docs: add architecture, workflow and delivery documents

2026-09-16 19:06:19 +08:00
parent 99f6bd77b0
commit 72fc5b47c7
36 changed files with 8240 additions and 0 deletions
@@ -0,0 +1,559 @@
+# 雅文内容创造工作台 · 系统设计文档 v5
+
+> 文档日期：2026-08-26  
+> 文档状态：当前实现说明与运行设计  
+> 项目定位：企业级多 Agent 内容生产、知识检索、质量审查与成稿交付工作台  
+> 技术栈：FastAPI + SQLModel + SQLite + ChromaDB/本地向量兜底 + React + Vite + React Flow  
+> 云化扩展：[v6 用户端、管理端与云化设计](./设计文档v6-用户端管理端云化与计费设计.md)
+
+## 0. 文档范围
+
+本文件描述当前工作台的实际架构和已落地行为，包含：
+
+- Agent Runtime：会话、工具调用、审批、恢复、护栏和事件追踪。
+- Agent 画布：多节点、连线、拓扑调度、融合 Agent 和运行快照。
+- 内容生产链路：导图解析、内容段生成、四道质检、人工审查和组合成稿。
+- 知识库：文件导入、分类树、AI 分类建议、人工确认、RAG 检索、消费锁定和可回滚重建。
+- 模型管理：Provider、模型发现、连通性测试、Agent 独立模型和配置快照。
+- 认证与 RBAC：本地用户、PBKDF2 密码摘要、可撤销 Bearer Session 和角色权限。
+- LLM Trace：调用、Span、Agent 会话、工具事件、QC 报告和成稿产物的统一关联。
+- 前端信息架构、运维启动、备份恢复、测试和当前验收证据。
+
+文中“已实现”表示源码已经存在并通过本地验证；“后续增强”只表示可选演进方向，不作为当前功能承诺。
+
+## 1. 设计目标与边界
+
+### 1.1 设计目标
+
+1. 让内容生产从“手工复制粘贴”变成可追踪的 Agent 协作流程。
+2. 让每个 Agent 的规则、技能、知识库、记忆和模型选择可配置，同时在任务开始时冻结，保证任务可复现。
+3. 让知识引用可回溯，禁止生产 Agent 在没有知识材料时把推测写成事实。
+4. 让失败、人工审查、工具审批和服务重启都能恢复，不产生静默成功。
+5. 让管理员可以控制成员访问范围，并能从 Trace 还原一次任务的完整运行过程。
+
+### 1.2 系统边界
+
+- 当前部署是本地或内网单工作区服务，不依赖独立微服务集群。
+- API 服务监听 `127.0.0.1:8010`，React 开发服务器监听 `127.0.0.1:5173`。
+- SQLite 保存业务数据、账号和运行状态；源文件保存在知识库目录；向量保存于 ChromaDB 和本地兜底文件。
+- 模型调用使用已配置的 OpenAI 兼容 Provider；API Key 不写入运行快照，也不出现在前端日志中。
+
+## 2. 总体架构
+
+```mermaid
+flowchart LR
+    U[工作台用户] --> WEB[React + Vite 前端]
+    WEB --> API[FastAPI API]
+    API --> AUTH[认证与 RBAC]
+    API --> ORCH[任务编排器]
+    ORCH --> RUN[CampaignRun 检查点]
+    ORCH --> RT[Agent Runtime]
+    RT --> LLM[Provider / LLM]
+    RT --> EVT[RunEvent + LLMCall]
+    ORCH --> QC[QC 四道质检]
+    ORCH --> COMP[Composer 组合器]
+    API --> RAG[RAG 管道]
+    RAG --> FILES[知识库源文件]
+    RAG --> VEC[ChromaDB]
+    RAG --> FALLBACK[本地原子 JSON 向量兜底]
+    API --> DB[(SQLite / SQLModel)]
+    QC --> DB
+    COMP --> ART[Markdown / DOCX 产物]
+    RT --> DB
+```
+
+### 2.1 运行时分层
+
+| 层 | 主要职责 | 代码位置 |
+| --- | --- | --- |
+| Web UI | 页面、表单、画布、任务审查、Trace 浏览 | `web/src/App.tsx`、`web/src/CanvasPage.tsx` |
+| API | 鉴权、资源 CRUD、任务控制、文件上传、下载预览 | `server/app/main.py` |
+| 编排层 | 画布拓扑、内容段派发、质检、组合、跨段锚点 | `server/app/agents/runner.py`、`coordinator.py` |
+| Runtime | LLM 多轮、工具协议、审批、恢复、输入输出护栏 | `server/app/agents/runtime.py` |
+| 知识层 | 解析、分块、Embedding、向量检索、引用、消费记录 | `server/app/rag/` |
+| 持久化层 | SQLite 表、幂等迁移、索引和启动恢复 | `server/app/models.py`、`db.py` |
+
+## 3. 核心业务流程
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant UI as 前端
+    participant API as FastAPI
+    participant Run as CampaignRun
+    participant Runtime as Agent Runtime
+    participant KB as RAG 知识库
+    participant QC as QC
+    participant Composer as 组合 Agent
+
+    User->>UI: 创建内容任务并填写导图
+    UI->>API: POST /api/campaigns
+    API->>Run: 冻结画布、Agent、技能、模型和知识库配置
+    User->>UI: 执行导图解析
+    UI->>API: POST /api/campaigns/{id}/parse
+    API->>Runtime: 启动 coordinator 会话
+    Runtime->>KB: 读取任务所需资料和上游上下文
+    Runtime-->>API: 生成内容段任务单与锚点约束
+    User->>UI: 启动任务
+    UI->>API: POST /api/campaigns/{id}/run
+    API->>Run: 写入 queued/running 检查点
+    API->>Runtime: 按画布波次并行派发
+    Runtime->>KB: 只检索挂接库，预留并消费片段
+    Runtime-->>API: 返回正文和锚点卡
+    API->>QC: 执行结构、内容、风格、跨段质检
+    QC-->>API: PASS/FAIL 与检查项
+    User->>UI: 人工审查、通过或打回
+    UI->>API: POST /api/segments/{id}/review
+    User->>UI: 组合交付
+    UI->>API: POST /api/campaigns/{id}/compose
+    API->>Composer: 只读取已人工通过内容段
+    Composer-->>API: 组合报告和 Markdown/DOCX 产物
+```
+
+### 3.1 任务状态
+
+`Campaign.status`：
+
+| 状态 | 含义 |
+| --- | --- |
+| `draft` | 已创建，尚未解析 |
+| `parsing` | 正在将导图转为任务段 |
+| `parsed` | 已生成任务段，等待执行 |
+| `running` | Agent 正在生成 |
+| `qc` | 正在质检 |
+| `human_review` | 等待人工审查 |
+| `composing` | 正在组合最终稿 |
+| `done` | 组合完成并可预览/下载 |
+| `failed` | 存在未处理的失败 |
+
+`CampaignRun.status` 负责一次具体执行：`queued`、`running`、`awaiting_review`、`completed`、`failed`、`cancelled`。任务重跑会创建新的 Run，旧 Run 的 Trace 和检查点仍保留。
+
+## 4. Agent Runtime 设计
+
+### 4.1 RuntimeContext
+
+每个会话使用 `RuntimeContext`，包含数据库会话、Run/Campaign/Segment 标识、当前 Agent、Provider、模型、Trace ID 和取消检查器。模型、工具和事件都从该上下文取得，避免在业务代码中散落全局状态。
+
+### 4.2 会话与恢复
+
+`AgentSession` 持久化以下内容：
+
+- `run_id`、`campaign_id`、`segment_id`、`agent_id`、`agent_name`。
+- `phase`：`coordinator`、`production`、`qc`、`composer`、`handoff`。
+- `status`：`running`、`waiting_approval`、`interrupted`、`completed`、`failed`、`cancelled`。
+- 当前轮次、最大轮次、消息上下文、工具状态、最终输出和错误。
+- `trace_id`、父会话 ID、时间戳。
+
+服务启动时会把中断的运行标记为可恢复状态；`resume` 会复用未完成会话，而不会重复创建同一阶段的成功结果。消息会保留系统规则和最近上下文，超过上限时裁剪旧上下文。
+
+### 4.3 工具协议与审批
+
+工具通过 `RuntimeTool` 注册，包含名称、描述、JSON Schema、处理器和 `requires_approval` 标记。调用过程为：
+
+1. Runtime 记录 `tool_started`。
+2. 解析 JSON 参数并执行授权处理器。
+3. 记录 `tool_finished`，把结果以 `tool` 消息回传给模型。
+4. 需要人工审批时保存 `pending_tool`，会话进入 `waiting_approval`。
+5. 管理员或审查者通过 `/api/agent-sessions/{session_id}/tool-approval` 批准/拒绝，随后调用 `/api/runs/{run_id}/resume` 继续。
+
+Provider 不支持 tools 时，Runtime 自动退化为单轮最终输出；这只改变调用方式，不改变会话、Trace 和护栏记录。
+
+### 4.4 护栏
+
+- 输入护栏：拒绝空任务；用户输入超过 100,000 字时终止本会话。
+- 输出护栏：拒绝空输出；模型输出超过 120,000 字时标记失败。
+- 工具护栏：未注册工具直接返回“未授权工具”；参数必须是 JSON 对象。
+- 运行护栏：每个 Agent 默认最多 6 轮；收到取消请求后写入 `cancelled`。
+- 指令边界：知识库、工具和上游文本以数据注入，不得覆盖 Runtime 系统规则。
+
+## 5. Agent 画布与组合配置
+
+### 5.1 画布模型
+
+`Canvas.nodes` 保存节点 ID、Agent ID 和启用状态；`Canvas.edges` 保存 `from_node` 到 `to_node` 的依赖关系。连线表示下游 Agent 可以读取上游锚点卡，画布不连线的节点保持上下文隔离。
+
+支持：
+
+- 同一个 Agent 放置多个节点，用于同类内容并行或串行。
+- 节点启用/停用；停用节点不会被派发，下游收到跳过状态。
+- 通过拓扑排序生成波次；同一波次可并行执行。
+- 在任务创建时冻结画布和 Agent 配置，后续改画布不会影响已创建任务。
+- Agent 可配置 `fusion_agent_ids`，由融合生产逻辑把多种写法合并成一个自然段。
+
+### 5.2 组合约束
+
+组合 Agent 只读取已通过人工审查的段落，并检查：
+
+1. 结构是否完整。
+2. 时间线、概念和产品回指是否一致。
+3. 段间锚点是否兑现。
+4. 情绪曲线与语气是否连续。
+5. 成稿是否满足交付格式和文本样式规则。
+
+生产 Agent 的默认正文规则是大白话、自然口语、正文一段到底；表演提示可以使用括号内联。锚点卡以结构化 JSON 保存，不直接暴露内部推理。
+
+## 6. 配置快照与可复现运行
+
+### 6.1 快照内容
+
+`server/app/agents/snapshot.py` 负责冻结：
+
+- Agent ID、名称、角色、规则内容、规则版本和规则哈希。
+- 已挂接知识库 ID、技能版本与技能指令。
+- Agent 使用的 Provider、模型名称和 Provider 指纹。
+- 记忆、融合 Agent 和阶段角色配置。
+
+快照不包含 API Key。Provider 指纹包括名称、Base URL、模型和启用状态；运行期间指纹变化会被识别，防止“任务显示旧模型、实际调用新模型”。
+
+### 6.2 写入位置
+
+| 数据 | 快照字段 |
+| --- | --- |
+| 任务运行 | `CampaignRun.config_snapshot` |
+| 内容段 | `Segment.runtime_snapshot` |
+| 质检报告 | `QCReport.runtime_snapshot`、`run_id`、`trace_id` |
+| 最终产物 | `Artifact.runtime_snapshot`、`run_id`、`trace_id` |
+
+## 7. 知识库与 RAG
+
+### 7.1 数据结构
+
+- `KnowledgeBase`：库名称、源目录、文件数量、分块数量和索引状态。
+- `KnowledgeFile`：文件名、内容哈希、修订号、分类、AI 分类建议、置信度、分类状态。
+- `KnowledgeCategory`：支持无限层级的 `parent_id` 分类树。
+- `KnowledgeUsage`：记录某个 Agent 是否已经预留/消费某个 chunk。
+
+分类状态：`unclassified`、`ai_suggested`、`human_confirmed`。人工可以新建、修改、删除分类，也可以把文件移动到其他分类；向量元数据会写入完整分类路径。
+
+### 7.2 导入与重建
+
+```mermaid
+flowchart LR
+    A[docx/srt/md/txt/json/jsonl] --> B[复制到 KB 源目录]
+    B --> C[格式解析]
+    C --> D[清洗与语义分块]
+    D --> E[Embedding]
+    E --> F[写本地兜底向量文件]
+    F --> G[尝试写 Chroma collection]
+    G --> H[更新 chunk_count 与 ready]
+```
+
+- 支持格式：`.docx`、`.srt`、`.md`、`.txt`、`.json`、`.jsonl`。
+- SRT 使用约 2,200 字目标窗口，避免把连续字幕拆成过多碎片；其他格式使用通用分块目标。
+- Embedding 使用本地模型，批量大小为 64。
+- 每个知识库拥有独立 collection，文件更新前先删除该文件的旧向量。
+- 重建按文件写入，每个文件都是一个可观察进度点。
+
+### 7.3 只允许使用知识库内容
+
+生产 Agent 的检索范围由 `Agent.kb_ids` 决定，只查询已挂接知识库。检索结果会写入引用列表和消费记录；同一个 Agent 对同一个 chunk 处于 `reserved` 或 `consumed` 时，后续检索会排除它。其他 Agent 的消费记录互不影响。
+
+人工可以通过释放接口把某条使用记录恢复为可用状态。若进程在模型请求中断，启动恢复会把未完成的 `reserved` 记录归还为 `available`。
+
+### 7.4 KB3 当前基线
+
+截至 2026-08-26：
+
+- 文件数：73。
+- 分块数：2,717。
+- 数据库状态：`ready`。
+- 本地兜底索引：2,717 条，向量维度 512。
+- 独立 Python 进程读取和相似度检索均通过。
+
+ChromaDB 在 Windows 上可能出现只写入 HNSW 元数据的半成品索引，因此系统优先读取原子替换的 `server/data/vector_fallback/kb_3.json`。Chroma 写入失败不会阻断本地检索。
+
+### 7.5 重建回滚
+
+重建开始前导出当前向量快照；重建过程任一文件解析、Embedding 或写入失败时，恢复原向量和数据库计数。只有成功完成全部文件后才写 `ready`。KB3 重建使用的数据库备份为：
+
+`server/data/backups/workspace-before-kb3-rebuild-20260826-193733.db`
+
+SHA256：`D35F7F43B533E3DF0EC4F1EB6C659558CABEE36DDF6A3E48359329A31EAA0084`
+
+## 8. 模型管理
+
+### 8.1 Provider
+
+`ModelProvider` 保存名称、Base URL、模型列表、默认模型、启用状态和本地 API Key。API 支持：
+
+- 新增、修改、删除 Provider。
+- 调用 OpenAI 兼容的 `/models` 自动发现模型。
+- 测试 Provider 连通性。
+- 刷新 Provider 模型列表。
+- 设置全局默认模型。
+
+### 8.2 Agent 模型选择
+
+Agent 可以绑定独立的 `model_provider_id + model_name`；为空时跟随全局默认。任务创建时将实际 Provider 和模型写入快照，避免运行中途修改模型导致同一任务行为漂移。
+
+## 9. 认证与 RBAC
+
+### 9.1 首次启动
+
+没有账号时，`GET /api/auth/status` 返回 `bootstrap_required=true`。前端显示“初始化管理员账号”，由用户自己创建第一个管理员账号；系统不内置默认密码。
+
+### 9.2 安全实现
+
+- 用户名限制为 3–48 个字符，只允许字母、数字、点、下划线和连字符。
+- 密码长度 10–256 个字符。
+- PBKDF2-SHA256，240,000 轮，随机 16 字节盐。
+- Session 使用随机不透明 Token；数据库只保存 Token SHA-256 摘要。
+- Session 默认 12 小时有效，可撤销；账号停用后立即失效。
+- CORS 允许 `Authorization` 请求头。
+
+### 9.3 角色权限
+
+| 角色 | 权限 |
+| --- | --- |
+| `admin` | 全部权限；成员、Provider、Agent、标签、技能、知识库、任务和审查管理 |
+| `editor` | 读取资源、修改内容配置、运行任务、处理审查和失败 |
+| `reviewer` | 读取资源、人工审查、读取审计 Trace |
+| `viewer` | 只读工作台和资源 |
+
+未知写接口默认收敛到 `config:write`，防止新增 API 遗漏保护。系统始终保留至少一个启用中的管理员，当前登录管理员不能停用自己。
+
+## 10. LLM Trace 与可观测性
+
+### 10.1 Trace 关联
+
+一次任务运行拥有一个 `trace_id`，关联：
+
+- `CampaignRun`：运行状态、检查点和完整配置快照。
+- `LLMCall`：Provider、模型、尝试次数、Prompt/Output 哈希、Token、耗时、错误。
+- `AgentSession`：阶段、轮次、工具状态、会话结果。
+- `RunEvent`：模型、工具、护栏、审批、任务和段完成事件。
+- `QCReport`、`Artifact`：质检结果、组合产物和运行快照。
+
+每个模型或工具事件拥有 `span_id`；工具事件可通过 `parent_span_id` 关联到触发它的模型请求。
+
+### 10.2 API 与前端
+
+| API | 用途 |
+| --- | --- |
+| `GET /api/llm_calls` | 按 Campaign、Trace、状态筛选模型调用 |
+| `GET /api/traces` | Trace 汇总：调用数、错误数、Token、耗时、Agent 数 |
+| `GET /api/traces/{trace_id}` | 查看运行快照、调用、会话、事件、QC 和产物 |
+| `GET /api/notifications` | 查看失败、待审查和待确认提醒 |
+
+前端“日志与通知”页面提供 Trace 列表、状态筛选和详情回放。审查任务页面提供当前运行的会话、事件和工具审批状态。
+
+## 11. 数据模型总览
+
+| 表 | 作用 | 关键关联 |
+| --- | --- | --- |
+| `Agent` | Agent 规则、角色、标签、知识库、模型 | `AgentSkillBinding`、`Memory` |
+| `AgentSkill` | 可复用技能指令 | `AgentSkillBinding` |
+| `ContentTag` | 内容类型和分类 | Agent 与 Segment JSON 字段 |
+| `Canvas` | 画布节点和连线 | Agent |
+| `Campaign` | 内容任务和画布快照 | Segment、CampaignRun |
+| `Segment` | 单个内容段、锚点、引用、状态 | Campaign、Agent、QCReport |
+| `CampaignRun` | 一次可恢复运行 | Campaign、Trace |
+| `AgentSession` | Agent Runtime 会话 | Run、Segment、Agent |
+| `RunEvent` | Runtime、工具和任务事件 | Run、Trace |
+| `LLMCall` | 模型调用账本 | Run、Trace、Agent |
+| `KnowledgeBase` | 知识库索引状态 | KnowledgeFile、Category |
+| `KnowledgeFile` | 文件归属和分类审核 | KnowledgeBase、Category |
+| `KnowledgeUsage` | Agent 级 chunk 消费锁 | Agent、KnowledgeBase |
+| `PendingMemory` | 待人工确认记忆 | target Agent |
+| `Memory` | 已确认 Agent 记忆 | Agent |
+| `Artifact` | 组合报告和 DOCX 路径 | Campaign、Run、Trace |
+| `AppUser` | 本地账号和角色 | AuthSession |
+| `AuthSession` | 可撤销 Token 哈希 | AppUser |
+
+数据库启动初始化会执行幂等迁移和索引创建，包括 Trace 索引、AgentSession 查询索引、同 Agent 同 chunk 唯一索引和同一 Campaign 活跃 Run 唯一索引。
+
+## 12. API 资源分组
+
+### 12.1 认证
+
+```text
+GET  /api/auth/status
+POST /api/auth/bootstrap
+POST /api/auth/login
+POST /api/auth/logout
+GET  /api/auth/me
+GET  /api/auth/users
+POST /api/auth/users
+PUT  /api/auth/users/{user_id}
+POST /api/auth/users/{user_id}/reset-password
+```
+
+### 12.2 配置资源
+
+```text
+GET/POST/PUT/DELETE /api/tags
+GET/POST/PUT/DELETE /api/agents
+GET/POST/PUT/DELETE /api/skills
+GET/POST/PUT/DELETE /api/providers
+POST /api/providers/discover-models
+POST /api/providers/{id}/test
+POST /api/providers/{id}/refresh-models
+GET/PUT /api/settings/model-default
+GET/POST/PUT/DELETE /api/canvases
+```
+
+### 12.3 知识库
+
+```text
+GET/POST/PUT/DELETE /api/kbs
+POST /api/kbs/{id}/import
+POST /api/kbs/{id}/rebuild
+GET  /api/kbs/{id}/search
+POST /api/kbs/search
+GET  /api/kbs/{id}/files/{filename}
+POST/PUT/DELETE /api/kbs/{id}/categories
+PUT  /api/kbs/{id}/files/{filename}/category
+POST /api/kbs/{id}/files/{filename}/classification/confirm
+POST /api/kbs/{id}/classify
+GET  /api/kbs/{id}/usage
+POST /api/kb-usages/{usage_id}/release
+```
+
+### 12.4 任务与交付
+
+```text
+GET/POST /api/campaigns
+POST /api/campaigns/{id}/parse
+POST /api/campaigns/{id}/run
+GET  /api/campaigns/{id}/runs
+GET  /api/runs/{id}
+POST /api/runs/{id}/cancel
+POST /api/runs/{id}/resume
+GET  /api/agent-sessions/{id}
+POST /api/agent-sessions/{id}/tool-approval
+POST /api/segments/{id}/review
+POST /api/segments/{id}/fix
+POST /api/campaigns/{id}/compose
+GET  /api/artifacts/{id}/preview
+GET  /api/artifacts/{id}/download
+```
+
+### 12.5 常见错误
+
+| 状态码 | 场景 |
+| --- | --- |
+| `400` | 参数不合法、状态不允许或分类/画布引用无效 |
+| `401` | 缺少、过期、撤销或无效 Token |
+| `403` | 角色没有对应权限 |
+| `404` | 资源或 Trace 不存在 |
+| `409` | 同一任务已有活跃 Run、用户名重复或并发消费冲突 |
+| `500` | Provider、解析器、向量库或文件系统异常；错误会记录到 Run/Trace |
+
+## 13. 前端信息架构
+
+当前工作台导航分为：
+
+- 工作台：总览、任务看板。
+- 智能生产：Agent 画布、Agent 管理、技能库。
+- 资产中心：知识库、标签管理、模型管理。
+- 系统：日志与通知、记忆库、访问控制（仅管理员）。
+
+关键用户路径：
+
+1. 首次访问：初始化管理员或登录。
+2. Agent 管理：创建 Agent、填写规则、挂接技能、知识库和模型。
+3. Agent 画布：拖入多个 Agent 节点、连线、启停、保存模板。
+4. 知识库：上传文件、查看原文、分类、确认 AI 建议、检索测试、重建索引。
+5. 任务看板：创建任务、解析导图、观察运行状态、审查内容段、处理失败。
+6. 日志与通知：按状态筛选 Trace，查看模型调用和事件链。
+7. 组合交付：查看成稿预览、组合报告并下载产物。
+
+前端 API 封装统一从 `localStorage` 读取 `yawan-workbench-access-token`，JSON 请求和文件上传都会自动添加 Bearer Header；401 后由认证入口重新登录。
+
+## 14. 启动、部署与备份
+
+### 14.1 启动后端
+
+```powershell
+cd "C:\Users\xinmiclaw\Desktop\雅文内容创造工作台\server"
+.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8010
+```
+
+### 14.2 启动前端
+
+```powershell
+cd "C:\Users\xinmiclaw\Desktop\雅文内容创造工作台\web"
+npm.cmd run dev -- --host 127.0.0.1 --port 5173
+```
+
+也可以从项目根目录运行 `启动工作台.bat`。
+
+### 14.3 生产构建
+
+```powershell
+cd "C:\Users\xinmiclaw\Desktop\雅文内容创造工作台\web"
+npm.cmd run build
+```
+
+### 14.4 备份建议
+
+至少备份以下内容：
+
+- `server/data/workspace.db`：业务数据库。
+- `server/data/kb/`：知识库原始文件。
+- `server/data/vector_fallback/`：稳定向量兜底文件。
+- `server/data/chroma/`：Chroma 数据目录，可作为加速层备份。
+- `server/data/artifacts/`：Markdown/DOCX 交付产物。
+
+备份恢复后先启动 API，再检查 `/api/auth/status`、知识库 `index_status` 和 Trace 列表；不要只依据目录存在判断索引可用。
+
+## 15. 测试与验收证据
+
+当前已执行：
+
+```powershell
+cd "C:\Users\xinmiclaw\Desktop\雅文内容创造工作台\server"
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+.\.venv\Scripts\python.exe -m compileall -q app scripts
+
+cd ..\web
+npm.cmd run build
+```
+
+结果：
+
+- 后端测试 13 个全部通过。
+- Python 编译检查通过。
+- Vite 生产构建通过，生成 `web/dist/`。
+- `/api/auth/status` 返回 200。
+- 未登录访问受保护 Agent API 返回 401。
+- OpenAPI 文档包含 `/api/traces` 和 `/api/auth/users`。
+- 前端 5173 和后端 8010 均可访问。
+- KB3 独立进程读取为 `ready/2717`，相似度检索返回结果。
+
+## 16. 当前已知约束与后续增强
+
+### 16.1 已知约束
+
+- SQLite 适合当前本地/内网工作区；大规模多人并发时应迁移到 PostgreSQL。
+- 本地向量兜底使用 JSON，优先保证稳定性；数据量继续扩大后可替换为独立向量服务。
+- Provider 的 API Key 仍由本地数据库保存，生产多租户部署应接入系统密钥管理服务。
+- Agent Runtime 当前以线程/后台任务调度为主，跨机器扩展需要引入任务队列和分布式锁。
+
+### 16.2 后续增强方向
+
+1. 增加 Trace 导出 JSON、运行对比和成本统计。
+2. 为知识库分类增加分类规则版本和批量人工确认。
+3. 增加 Agent 规则版本差异对比和一键回滚。
+4. 将通知中心扩展为可配置的本地/企业 IM 通知。
+5. 为生产段加入更细粒度的引用覆盖率和事实一致性指标。
+
+## 17. 代码索引
+
+| 文件 | 说明 |
+| --- | --- |
+| `server/app/main.py` | FastAPI 路由、启动恢复、资源 CRUD、任务控制 |
+| `server/app/models.py` | SQLModel 数据表定义 |
+| `server/app/db.py` | 数据库初始化、幂等迁移和索引 |
+| `server/app/auth.py` | 密码哈希、Session、角色权限映射 |
+| `server/app/agents/runtime.py` | Agent Runtime 主循环和工具协议 |
+| `server/app/agents/snapshot.py` | Agent/阶段运行配置快照 |
+| `server/app/agents/runner.py` | 内容段生成、引用消费、状态机和锚点 |
+| `server/app/agents/qc.py` | 四道质检和 QC 报告 |
+| `server/app/agents/composer.py` | 组合成稿、总检和交付产物 |
+| `server/app/rag/pipeline.py` | 导入、分类、重建、回滚和检索编排 |
+| `server/app/rag/store.py` | Chroma 与本地向量兜底存储 |
+| `server/scripts/rebuild_kb3.py` | KB3 可观察重建脚本 |
+| `web/src/App.tsx` | 工作台页面、认证入口、资源管理和 Trace 页面 |
+| `web/src/CanvasPage.tsx` | Agent 画布交互 |
+| `web/src/api.ts` | 前端 API 和 Token 注入 |