tliu93
c42cc2ddb6
Add docs/: a bilingual repository brief, plus docs/design/ with the high-level design (Alembic migration foundation, LLM integration, basic AI search) and a self-contained per-step implementation plan (step 1-3).
2.5 KiB
2.5 KiB
实施计划 · 总览 / Implementation Plan · Overview
配合设计文档
llm-integration-design.md阅读。 Read alongside the high-level design doc.三步走，每步一个独立文件、一个可独立合入的 PR / branch。实现 Agent 每次只需读对应的 step 文件即可执行。 Three steps, one self-contained file and one mergeable PR per step. An implementation agent only needs to read the relevant step file.
步骤与文件 / Steps & Files
| 步骤 / Step | 文件 / File | 目标 / Goal | 改 schema? | 依赖 / Depends on |
|---|---|---|---|---|
| 1 | step-1-alembic-foundation.md |
Alembic 迁移地基（封装 + V1 baseline + 自动认领），不改 schema | 否 / No | — |
| 2 | step-2-llm-integration.md |
LLM 接入：app_settings 表 + 客户端 + 配置页 |
是 / Yes (V2) | 步骤 1 / Step 1 |
| 3 | step-3-ai-search.md |
基础 AI 搜索：常驻按钮 + 查询词扩展 | 否 / No | 步骤 2 / Step 2 |
顺序 / Sequence： 严格按 1 → 2 → 3，前一步绿了再进下一步。 Strictly 1 → 2 → 3; advance only when the previous step is green.
跨步骤约定 / Cross-cutting Conventions（每步都适用 / apply to every step）
- 提交 / Commits： 每步独立 branch + PR；遵循仓库约定——不主动 push/commit，除非业主明确要求。 One branch/PR per step; do not push/commit unless explicitly asked.
- CI 不联网 / Network-free CI： 任何 LLM 调用在测试中必须 mock。 All LLM calls must be mocked in tests.
- 降级优先 / Degradation first： 每个 AI 接入点先想清楚"未配置 / 调用失败"时的表现；AI 是加分项，不是依赖。 Always design the "unconfigured / failed" path first; AI is additive, never required.
- 依赖最小 / Minimal deps： 复用已有
httpx；本轮唯一新增依赖是alembic。不要引入openaiSDK。 Reusehttpx; the only new dependency this round isalembic. Do not add theopenaiSDK. - 保持形态 / Keep the shape： FastAPI + Jinja2 SSR + SQLite，无前端构建链；新页面沿用现有模板/样式。
- 文档同步 / Keep docs in sync： 实现与设计若有偏差，回写本目录对应文件与仓库简报
../repository-brief.md（§10 迁移、§15 约束）。 If implementation diverges, update the step file, the design doc, and the brief (§10/§15).