Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
35 changes: 27 additions & 8 deletions .env.example
Original file line number Diff line number Diff line change
@@ -1,10 +1,29 @@
# LLM API (OpenAI-compatible endpoint)
LLM_API_KEY=your-api-key-here
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL=qwen-plus
# 复制为 .env(make setup 会复制并生成 BACKEND_JWT_SECRET)。后端和 docker compose 都读这个文件。

# CORS
CORS_ORIGINS=http://localhost:5173,http://localhost:3000
# 模型:任何 OpenAI 兼容的聊天补全接口都行
# OpenAI: LLM_BASE_URL=https://api.openai.com/v1 LLM_MODEL=gpt-4.1-mini
# DeepSeek: LLM_BASE_URL=https://api.deepseek.com/v1 LLM_MODEL=deepseek-chat
# 通义千问: LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODEL=qwen-plus
# Ollama: LLM_BASE_URL=http://localhost:11434/v1 LLM_MODEL=qwen3(LLM_API_KEY 随便填)
LLM_API_KEY=
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=
# 知识地图、知识坐标、划线翻译用的小模型;留空和 LLM_MODEL 一样
LLM_FAST_MODEL=
# PDF 阅读版逐页看图转文字用的模型,必须能看图;留空和 LLM_MODEL 一样
PDF_READING_MODEL=
# 原样带进每次模型调用的 extra_body(JSON 对象),例如给 DeepSeek 关掉推理:{"thinking":{"type":"disabled"}}
LLM_EXTRA_BODY=
# 输出上限的参数名:留空按模型名自动判断(gpt- / o 系列用 max_completion_tokens,其它用 max_tokens)
LLM_MAX_TOKENS_PARAM=

# Database
DATABASE_URL=sqlite:///./bloom.db
# 前端服务端给后端签访问令牌用的密钥,至少 32 个字符;前后端用同一个值
BACKEND_JWT_SECRET=

# 数据库:默认是 backend/storage/bloom.sqlite3;也可以用 Postgres,例如
# DATABASE_URL=postgresql://bloom:bloom@localhost:5432/bloom

# 可选:把模型调用记到 Langfuse(https://langfuse.com)
# LANGFUSE_PUBLIC_KEY=
# LANGFUSE_SECRET_KEY=
# LANGFUSE_BASE_URL=https://cloud.langfuse.com
83 changes: 83 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
name: tests

on:
pull_request:
push:
branches: [main]

concurrency:
group: tests-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
secret-scan:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v4
- name: No key-like strings in the repository (same script as the local pre-push hook)
run: ./scripts/secret-scan.sh

backend:
runs-on: ubuntu-latest
timeout-minutes: 20
services:
postgres:
image: postgres:18
env:
POSTGRES_USER: bloom
POSTGRES_PASSWORD: bloom
POSTGRES_DB: bloom
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U bloom"
--health-interval 5s
--health-timeout 5s
--health-retries 10
env:
# A throwaway database that only exists for this job
DATABASE_URL: postgresql+psycopg://bloom:bloom@localhost:5432/bloom
TEST_DATABASE_URL: postgresql+psycopg://bloom:bloom@localhost:5432/bloom
BACKEND_JWT_SECRET: ci-only-secret-0123456789abcdef0123456789abcdef
LLM_MODEL: ci-model
defaults:
run:
working-directory: backend
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v6
with:
python-version: "3.12"
enable-cache: true
cache-dependency-glob: backend/uv.lock
- run: uv sync --frozen
- name: Run every migration on a fresh Postgres
run: uv run --frozen alembic upgrade head
- name: Migrations match the models
run: uv run --frozen alembic check
- name: Backend tests (the Postgres-only ones run too because TEST_DATABASE_URL is set)
run: uv run --frozen pytest -q

frontend:
runs-on: ubuntu-latest
timeout-minutes: 15
defaults:
run:
working-directory: frontend
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 10.33.0
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
cache-dependency-path: frontend/pnpm-lock.yaml
- run: pnpm install --frozen-lockfile
- run: pnpm exec tsc --noEmit
- run: pnpm test
6 changes: 3 additions & 3 deletions GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,9 @@ The tutor will:
3. Generate the next document

The next document's opening will include:
- **Thought question review** (evaluates each of your answers, provides correct answers)
- **??? responses** (addresses every confusion you annotated)
- **New content** (tailored to your understanding level)
- **Thought question review** (kept short: if you answered, one or two sentences per answer; if you did not, a single sentence, and the reference answers sit at the end of that lesson)
- **Annotation responses** (only if you annotated; two or three sentences each, and a one-sentence callback for anything already answered in the highlight Q&A)
- **New content** (tailored to your understanding level, starting right after the review)

### 5. Repeat Until Course Completion

Expand Down
6 changes: 3 additions & 3 deletions GUIDE.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,9 @@ Claude 会立即为你生成:
3. 生成下一篇文档

下一篇文档的开头会包含:
- **思考题复盘**(逐题评估你的回答,给出正确答案)
- **??? 解答**(逐条解答你标注的所有困惑)
- **新内容**(根据你的理解程度定制)
- **思考题复盘**(很短:你作答了就逐题一两句点评;没作答就只有一句话,参考答案放在这一篇的末尾)
- **批注解答**(有批注才有;每条两三句,已在划线问答里回答过的只回扣一句)
- **新内容**(根据你的理解程度定制,复盘之后马上开始)

### 5. 重复,直到课程完结

Expand Down
32 changes: 24 additions & 8 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,27 +1,43 @@
.PHONY: dev dev-backend dev-frontend build up down logs test
.PHONY: setup dev dev-backend dev-frontend migrate build up down logs test test-backend test-frontend

dev-backend:
cd backend && uv run uvicorn app.main:app --reload --port 8000
# 第一次用:复制 .env 并生成 BACKEND_JWT_SECRET,再装好前后端依赖
setup:
@test -f .env || (umask 077 && sed "s|^BACKEND_JWT_SECRET=.*|BACKEND_JWT_SECRET=$$(openssl rand -hex 32)|" .env.example > .env && echo "已生成 .env,记得填上 LLM_API_KEY 和 LLM_MODEL")
cd backend && uv sync
cd frontend && pnpm install

migrate:
cd backend && uv run alembic upgrade head

# 后端只监听本机:它不对外开放,浏览器经前端的同源代理访问
dev-backend: migrate
cd backend && uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

dev-frontend:
cd frontend && npm run dev
set -a && . ./.env && set +a && cd frontend && BACKEND_URL=http://127.0.0.1:8000 pnpm dev

dev:
@echo "请在两个终端分别运行:"
@echo " make dev-backend"
@echo " make dev-frontend"
@echo "然后打开 http://localhost:3000"

build:
docker compose build
DOCKER_BUILDKIT=1 docker compose build

up:
docker compose up -d
DOCKER_BUILDKIT=1 docker compose up -d --build

down:
docker compose down

logs:
docker compose logs -f

test:
cd backend && uv run pytest tests/ -v
test: test-backend test-frontend

test-backend:
cd backend && uv run pytest -q

test-frontend:
cd frontend && pnpm test
Loading
Loading