# docs/design · 设计文档 / Design Docs

本目录存放面向具体改动轮次的设计与实施计划。
Design and implementation plans for specific rounds of changes.

## 当前轮次 / Current round — LLM 接入与迁移地基 / LLM Integration & Migration Foundation

本轮三件事 / Three deliverables：① 引入 Alembic 迁移系统（含封装）② LLM 接入（配置页 + 落库 + 客户端）③ 基础 AI 搜索（查询词扩展）。
**本轮不含图片分析**（留作未来，架构已预留接口）。Image analysis is **not** in this round (reserved for the future).

**总体设计（High-level，"做什么/为什么"）/ High-level design ("what/why")：**

| 文件 / File | 内容 / Contents |
| --- | --- |
| [`llm-integration-design.md`](./llm-integration-design.md) | 原则、架构、迁移子系统、LLM 接入、AI 搜索、安全、测试、未来扩展、决策记录（D1–D10）。<br>Principles, architecture, migration subsystem, LLM, AI search, security, testing, future seams, decisions log. |

**实施计划（"怎么做"，每步一个自包含文件）/ Implementation plan ("how", one self-contained file per step)：**

| 文件 / File | 内容 / Contents |
| --- | --- |
| [`implementation-plan.md`](./implementation-plan.md) | 总览：步骤顺序、依赖、跨步骤约定。<br>Overview: sequence, dependencies, cross-cutting conventions. |
| [`step-1-alembic-foundation.md`](./step-1-alembic-foundation.md) | 步骤 1：Alembic 迁移地基（不改 schema）。<br>Step 1: migration foundation. |
| [`step-2-llm-integration.md`](./step-2-llm-integration.md) | 步骤 2：LLM 接入（`app_settings` + 客户端 + 配置页）。<br>Step 2: LLM integration. |
| [`step-3-ai-search.md`](./step-3-ai-search.md) | 步骤 3：基础 AI 搜索（查询词扩展）。<br>Step 3: basic AI search. |

> 每个 step 文件**自包含**：实现 Agent 每次只读对应的一个文件即可执行。
> Each step file is **self-contained** — an implementation agent only needs to read that one file.

> 实现与设计若有偏差，请回写本目录，并同步仓库简报 `../repository-brief.md`（尤其 §10 迁移、§15 约束）。
> If implementation diverges, update these docs and the brief (`../repository-brief.md`, esp. §10 & §15).