# 雅文内容创造工作台 · 系统设计文档 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 注入 |