# 实施计划 · 总览 / Implementation Plan · Overview

> 配合设计文档 [`llm-integration-design.md`](./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`](./step-1-alembic-foundation.md) | Alembic 迁移地基（V1 baseline + 独立幂等迁移命令 + 启动只校验/fail-close），**不改 schema** | 否 / No | — |
| **2** | [`step-2-llm-integration.md`](./step-2-llm-integration.md) | LLM 接入：`app_settings` 表 + 客户端 + 配置页 | 是 / Yes (V2) | 步骤 1 / Step 1 |
| **3** | [`step-3-ai-search.md`](./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`。不要引入 `openai` SDK。
  Reuse `httpx`; the only new dependency this round is `alembic`. Do not add the `openai` SDK.
- **保持形态 / 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).