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,780 @@
+# 雅文内容创造工作台 · 核心逻辑设计文档 v6
+
+> 文档日期：2026-08-26  
+> 关联文档：[设计文档 v5](./设计文档v5-系统设计.md)、[设计文档 v6：用户端、管理端与云化设计](./设计文档v6-用户端管理端云化与计费设计.md)  
+> 从零落地：[核心逻辑设计文档 v6：从 0 到 1](./核心逻辑设计文档v6-从0到1.md)  
+> 文档用途：说明系统如何运行、数据如何流转、权限如何隔离，以及 v6 多用户云化能力如何接入现有 Runtime  
+> 说明：本文件是逻辑设计文档；其中“当前实现”对应现有源码，“v6 目标”对应 v6 设计，不能把规划功能当作已上线功能
+
+## 0. 一句话理解系统
+
+雅文内容创造工作台是一个以 **任务为中心、Agent 为执行单元、知识库为事实来源、记忆库为经验来源、模型目录为受控能力、Trace 为审计链路** 的内容生产系统。
+
+完整逻辑可以概括为：
+
+```text
+用户请求
+  → 权限和配额校验
+  → 冻结任务配置
+  → Agent 画布拓扑调度
+  → 只检索允许使用的知识与记忆
+  → Agent Runtime 生成内容
+  → QC 质检
+  → 人工审查
+  → 组合 Agent 统一成稿
+  → 云存储交付
+  → 用量计量、账单和 Trace 归档
+```
+
+## 1. 核心原则
+
+### 1.1 数据归属优先
+
+任何资源都先确定归属，再决定谁能看、谁能用、谁能改：
+
+```text
+organization_id
+  → owner_user_id
+    → resource_type + resource_id
+      → visibility / grant / permission
+```
+
+用户、Agent、任务、知识库、记忆、模型选择、Trace、产物和账单都必须绑定组织与用户。没有归属键的数据不能进入生产链路。
+
+### 1.2 配置先冻结，运行后复现
+
+任务开始前冻结：
+
+- 画布节点和连线。
+- Agent 规则、规则版本和规则哈希。
+- Agent 挂接的技能、知识库和记忆。
+- Provider、模型、模型能力标签和费率版本。
+- 内容段、上游锚点和任务参数。
+
+任务运行过程中修改管理端配置，只影响后续新任务；当前任务始终使用自己的快照。
+
+### 1.3 知识与记忆不能越权
+
+检索服务必须先计算用户可访问的资源集合，再执行向量检索：
+
+```text
+allowed_kb_ids
+  = owned_kb_ids
+  ∪ granted_kb_ids
+  ∪ global_kb_ids
+
+allowed_memory_ids
+  = owned_memory_ids
+  ∪ granted_memory_ids
+  ∪ global_memory_ids
+```
+
+不能先搜索全库再由前端过滤。Agent 只能使用任务快照中允许的知识库和记忆。
+
+### 1.4 事实必须可追溯
+
+每个知识片段、模型调用、工具调用、质检结果和最终产物，都要能回溯到：
+
+```text
+组织 → 用户 → 任务 → Run → Trace → Segment / Agent → 资源或模型
+```
+
+没有来源的事实不能标记为已验证内容；没有 Trace 的模型调用不能计入已完成任务。
+
+### 1.5 失败必须显式化
+
+失败不等于空结果，等待不等于成功，Provider 返回 200 也不等于内容有效。系统必须区分：
+
+- Provider 错误、网关拦截、模型拒绝、超时、限流。
+- RAG 无命中、索引损坏、文件解析失败。
+- Agent 输出为空、格式错误、护栏失败。
+- QC FAIL、人工打回、组合总检失败。
+- 云对象上传失败、导出失败、账单计量失败。
+
+## 2. 参与者和职责
+
+| 参与者 | 核心职责 | 不负责的事情 |
+| --- | --- | --- |
+| 用户端 | 创建任务、选择已开放模型、使用自己的资源和获授权资源 | 不能接 Provider、不能改费率、不能越权读私有资源 |
+| 管理端 | 管理用户、Provider、模型目录、知识库授权、记忆授权、配额、计费和导出 | 不绕过审计直接改历史账单 |
+| Coordinator Agent | 把导图拆成可执行内容段、分配标签和时间范围 | 不直接生成最终长稿 |
+| Production Agent | 根据任务段、规则、技能、知识和记忆生成内容 | 不使用未挂接资源，不补写无来源事实 |
+| QC Agent | 按固定检查项审查结构、内容、风格和跨段一致性 | 不替用户默默修改并伪装为通过 |
+| Composer Agent | 组合已人工通过的段落，执行全文一致性检查 | 不组合未通过或被跳过的段落 |
+| Agent Runtime | 维护会话、工具、审批、护栏、恢复和 Trace | 不替业务层决定资源权限 |
+| RAG 服务 | 解析、分块、向量化、检索、引用和消费锁定 | 不决定用户是否有权访问库 |
+| 计量服务 | 记录 LLM、Embedding、OCR、存储和导出用量 | 不修改原始调用事实 |
+
+## 3. 核心对象关系
+
+```mermaid
+erDiagram
+    ORGANIZATION ||--o{ USER_ACCOUNT : contains
+    USER_ACCOUNT ||--o{ AGENT : owns
+    USER_ACCOUNT ||--o{ KNOWLEDGE_BASE : owns
+    USER_ACCOUNT ||--o{ MEMORY : owns
+    KNOWLEDGE_BASE ||--o{ KNOWLEDGE_FILE : contains
+    KNOWLEDGE_BASE ||--o{ KNOWLEDGE_BASE_GRANT : shares
+    MEMORY ||--o{ MEMORY_GRANT : shares
+    MODEL_PROVIDER ||--o{ MODEL_CATALOG : exposes
+    MODEL_CATALOG ||--o{ MODEL_ORGANIZATION_GRANT : opens
+    AGENT ||--o{ AGENT_SKILL_BINDING : uses
+    AGENT ||--o{ AGENT_KB_BINDING : uses
+    CAMPAIGN ||--o{ CAMPAIGN_RUN : executes
+    CAMPAIGN ||--o{ SEGMENT : contains
+    CAMPAIGN_RUN ||--o{ AGENT_SESSION : starts
+    CAMPAIGN_RUN ||--o{ RUN_EVENT : emits
+    CAMPAIGN_RUN ||--o{ LLM_CALL : records
+    SEGMENT ||--o{ QC_REPORT : checks
+    CAMPAIGN ||--o{ ARTIFACT : produces
+    LLM_CALL ||--o{ USAGE_EVENT : meters
+```
+
+## 4. 任务核心逻辑
+
+### 4.1 任务创建
+
+任务创建只保存输入和初始选择，不立即调用模型：
+
+1. 用户填写任务名称、导图或主题。
+2. 服务端确认用户属于有效组织，且有创建任务权限。
+3. 用户选择画布；服务端读取画布节点、连线和启停状态。
+4. 服务端校验 Agent、技能、知识库和模型目录引用。
+5. 任务进入 `draft`。
+
+如果用户选择的模型被停用、Provider 已失效、知识库授权已撤销或 Agent 缺少必需知识库，任务创建应返回明确错误，而不是等到模型调用时才失败。
+
+### 4.2 导图解析
+
+解析由 Coordinator Agent 完成：
+
+```mermaid
+flowchart TD
+    A[导图/主题输入] --> B[输入护栏]
+    B --> C[Coordinator Runtime]
+    C --> D[识别内容节点]
+    D --> E[绑定内容标签]
+    E --> F[生成时间范围和任务目标]
+    F --> G[识别产品/下一段/钩子]
+    G --> H[标记不确定项]
+    H --> I[生成 Segment 任务单]
+```
+
+Coordinator 必须遵守：
+
+- 不补写导图没有提供的产品、日期、人物或事实。
+- 一个 Segment 只承担一个清楚的内容目标。
+- 每个 Segment 必须有标题、内容标签、时间范围、导图原文和目标 Agent。
+- 不确定信息写入 `pending_confirms`，不能猜测后直接进入生产。
+
+### 4.3 运行快照
+
+创建 Run 时冻结完整配置：
+
+```text
+CampaignRun.config_snapshot
+├── organization / user
+├── canvas
+├── segments[]
+│   └── primary Agent snapshot
+├── stages
+│   ├── coordinator
+│   ├── qc.structure
+│   ├── qc.content
+│   ├── qc.style
+│   ├── qc.cross
+│   └── composer
+├── model catalog/version/price
+└── memory and knowledge access snapshot
+```
+
+快照写入后，任务只引用快照，不重新读取用户当前编辑中的规则。这样可以保证审查结果和最终成稿对应同一组配置。
+
+### 4.4 Run 状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> queued
+    queued --> running
+    running --> awaiting_review
+    running --> failed
+    running --> cancelled
+    awaiting_review --> running: 人工继续/打回重跑
+    awaiting_review --> completed: 所有段已通过并完成组合
+    failed --> queued: 修复后重试
+    cancelled --> queued: 管理员重新排队
+    completed --> [*]
+```
+
+同一 Campaign 只能有一个 `queued` 或 `running` 的活跃 Run。Run 取消、失败和恢复都保留原 Trace，不覆盖历史记录。
+
+## 5. Agent 画布与调度逻辑
+
+### 5.1 图结构
+
+- 节点是画布上的执行实例，不是 Agent 定义本身。
+- `node_id` 标识画布节点，`agent_id` 指向 Agent 定义。
+- 同一个 Agent 可以放在多个节点上，形成并行或串行的多个实例。
+- 边 `from_node → to_node` 表示下游读取上游锚点卡。
+- 未连线的节点不共享上下文。
+
+### 5.2 波次调度
+
+服务端对画布执行拓扑排序：
+
+1. 找到入度为 0 的节点作为第一波。
+2. 第一波完成后，把其出边节点的入度减一。
+3. 入度归零的节点进入下一波。
+4. 同一波次节点并行执行。
+5. 检测到环时拒绝运行，并提示具体环路。
+
+节点停用时不会调用模型，下游收到 `skipped` 锚点。停用产品销售节点时，组合器必须知道“本场无产品”，不能自动补一个产品段。
+
+### 5.3 融合 Agent
+
+融合 Agent 用于把多个写法合成为一个自然段：
+
+```text
+主 Agent 任务
+  ├── 心法写法 Agent
+  ├── 钩子写法 Agent
+  └── 场景表达 Agent
+        ↓
+融合结果：一个自然口语段 + 一个结构化锚点卡
+```
+
+融合时只传递结构化任务、允许的知识引用和上游锚点，不把各 Agent 的内部推理互相暴露。最终文本遵守统一的“大白话、自然口语、默认一段到底”样式，避免拼贴感。
+
+## 6. Agent Runtime 核心逻辑
+
+### 6.1 会话循环
+
+```mermaid
+sequenceDiagram
+    participant O as 业务编排器
+    participant R as Agent Runtime
+    participant S as AgentSession
+    participant M as Model Provider
+    participant T as Tool
+    participant E as RunEvent/LLMCall
+
+    O->>R: run_agent(task, snapshot, tools)
+    R->>S: 创建或恢复会话
+    R->>E: runtime_started + input_guardrail
+    R->>M: 发送当前消息和工具定义
+    M-->>R: 文本或 tool_calls
+    R->>E: model_started/model_finished
+    alt 工具调用
+        R->>T: 校验参数并执行
+        T-->>R: 工具结果
+        R->>E: tool_started/tool_finished
+        R->>S: 写入 tool 消息
+        R->>M: 继续下一轮
+    else 最终文本
+        R->>E: output_guardrail
+        R->>S: 写入完成结果
+        R-->>O: completed/failed
+    end
+```
+
+### 6.2 会话恢复
+
+`AgentSession` 保存消息、轮次、工具状态、审批状态、结果和错误。恢复时：
+
+- 复用 `running`、`interrupted` 或 `waiting_approval` 会话。
+- 不重复执行已完成工具调用。
+- `pending_tool` 有审批决定后，先回放批准/拒绝结果，再继续模型循环。
+- 服务启动时把中断会话标记为可恢复，并归还未完成的知识片段预留。
+
+### 6.3 工具审批
+
+需要人工确认的工具调用进入 `waiting_approval`，不会因为接口返回成功就直接执行。审批动作必须记录：
+
+```text
+requester session → pending_tool → approver user → decision → tool result
+```
+
+工具批准接口只允许具有审查或管理权限的角色调用；工具本身还要在当前阶段的注册表中存在。
+
+### 6.4 护栏和输出契约
+
+Runtime 负责通用护栏，业务 Agent 负责领域契约：
+
+| 层级 | 检查内容 |
+| --- | --- |
+| Runtime 输入 | 非空、长度上限、系统规则优先 |
+| Runtime 工具 | 工具是否注册、参数是否为合法 JSON |
+| Runtime 输出 | 非空、长度上限、文本可保存 |
+| Coordinator | Segment 字段完整、未知信息待确认 |
+| Production | 正文、引用、锚点卡完整 |
+| QC | 检查项必须带状态和问题说明 |
+| Composer | 只组合人工通过内容段 |
+
+## 7. 知识库核心逻辑
+
+### 7.1 建库管道
+
+```text
+上传文件
+  → 计算内容哈希
+  → 写入云对象/本地源目录
+  → 解析格式
+  → 清洗文本
+  → 语义分块
+  → Embedding
+  → 写入向量索引
+  → 写入文件分类和版本
+  → 标记 ready
+```
+
+支持 `.docx`、`.srt`、`.md`、`.txt`、`.json`、`.jsonl`。文件更新时先删除同名文件旧向量，再写入新版本，避免重复命中。
+
+### 7.2 分类逻辑
+
+分类分为 AI 建议和人工确认：
+
+```text
+unclassified
+  → AI 分类任务
+  → ai_suggested
+  → 人工确认/修改
+  → human_confirmed
+```
+
+分类树使用 `parent_id` 支持无限层级。文件保存 `category_id`、AI 建议分类、置信度、原因、内容哈希和修订号。移动文件分类只修改归属元数据，并在下一次增量索引时更新向量元数据中的完整分类路径。
+
+### 7.3 检索与引用
+
+Agent 生成前构造检索请求：
+
+```text
+任务段目标
+  + 上游锚点卡
+  + Agent 规则里的检索意图
+  + 当前用户允许的知识库 ID
+  + 当前 Agent 已消费 chunk 排除集合
+```
+
+检索结果必须带：知识库、文件、分类路径、chunk ID、原文、相似度、文件哈希和修订号。引用写入 `Segment.references`，并进入 QC 对证。
+
+### 7.4 知识消费锁定
+
+消费锁是 Agent 级别，不是全局锁：
+
+```text
+Agent A 消费 chunk-001 → A 后续不可重复使用
+Agent B 未消费 chunk-001 → B 仍可使用
+```
+
+状态流转：
+
+```text
+available → reserved → consumed
+reserved  → available（任务中断/模型失败）
+consumed  → available（管理员人工释放）
+```
+
+数据库对 `(agent_id, kb_id, chunk_id)` 建唯一约束，防止同一个 Agent 并发重复认领同一片段。
+
+### 7.5 重建和回滚
+
+重建必须遵循：
+
+1. 读取当前索引快照。
+2. 标记 `indexing`。
+3. 按文件处理并记录进度。
+4. 所有文件成功后写入 `ready`。
+5. 任意文件失败时恢复旧快照和旧计数。
+
+Chroma 不稳定时使用本地原子 JSON 向量文件作为检索兜底。KB3 当前基线为 73 个文件、2,717 个分块、512 维向量，数据库和独立进程读取结果一致。
+
+## 8. 记忆库核心逻辑
+
+### 8.1 记忆来源
+
+记忆不是模型自动写入的隐式状态，而是可审查资源：
+
+```text
+任务失败/人工修改/QC意见
+  → PendingMemory
+  → 人工确认
+  → Memory
+  → 绑定来源 Agent 和版本
+```
+
+未确认记忆不能进入生产 Agent 的有效记忆上下文。
+
+### 8.2 记忆与知识库同构
+
+记忆库完全复用知识库的资源模型：
+
+| 范围 | 默认使用者 | 修改者 |
+| --- | --- | --- |
+| `private` | 所有者及其 Agent | 所有者 |
+| `shared` | 被授权用户 | 所有者和管理员 |
+| `global` | 当前组织全部用户 | 管理员 |
+
+管理员可以查看、导出、授权、撤销、发布全局和恢复私有。用户只能看到自己的私有记忆、获授权记忆和全局记忆。
+
+### 8.3 记忆注入
+
+Agent Runtime 注入记忆前执行：
+
+1. 校验任务用户和组织。
+2. 计算允许读取的记忆 ID。
+3. 按来源 Agent、版本和状态筛选。
+4. 将记忆作为“已授权数据”注入，不允许记忆内容覆盖 Runtime 系统规则。
+5. 将使用的记忆版本写入任务快照。
+
+撤销授权只影响新任务；已创建任务仍使用创建时的记忆快照。
+
+## 9. 模型核心逻辑
+
+### 9.1 管理端模型目录
+
+模型使用链路为：
+
+```text
+管理端接入 Provider
+  → 发现模型
+  → 规范化为 ModelCatalog
+  → 设置能力、可见性、费率和启用状态
+  → 按组织开放
+  → 用户端只读选择
+```
+
+用户端不能新增 Provider、查看 API Key、修改 Base URL、发现模型、修改费率或输入任意模型名称。
+
+### 9.2 模型选择和快照
+
+用户选择 `model_catalog_id`，服务端校验：
+
+- 模型目录存在且启用。
+- Provider 存在且启用。
+- 模型对当前组织可见。
+- 模型能力满足任务要求。
+- 当前用户和组织未超出配额。
+
+通过后把 Provider、真实模型名、能力标签和费率版本写入 Run 快照。模型目录停用不会改变历史任务。
+
+### 9.3 成人内容能力测试
+
+“破限”在系统中落地为管理端模型能力兼容性测试，而不是用户自行上传提示词：
+
+```text
+ModelCatalog
+  + adult-content-compat-v1
+  + 固定样例集
+  + Provider/网关路径
+  + 输出断言
+  + 通过率/拒绝率/超时率/费用
+  → 发布能力标签
+```
+
+结果必须区分 `provider_blocked`、`gateway_blocked`、`model_refused`、`timeout`、`format_failed`、`supported` 和 `partial`。模型更新、Provider 路由变化、系统提示词变化或审查配置变化时重新回归。
+
+## 10. 用户端与管理端逻辑
+
+### 10.1 用户端闭环
+
+```mermaid
+flowchart TD
+    L[登录] --> H[读取组织/角色/配额]
+    H --> R[读取可用资源]
+    R --> M[选择模型目录]
+    M --> C[创建任务]
+    C --> P[解析导图]
+    P --> G[运行 Agent]
+    G --> Q[查看 QC]
+    Q --> V[人工审查]
+    V --> O[组合和下载]
+    O --> U[查看用量/账单]
+```
+
+用户端所有写操作都带当前用户身份，所有资源查询都经过归属过滤。模型选择器只显示管理端开放的模型；知识库和记忆库按“我的/已授权/全局”分组。
+
+### 10.2 管理端闭环
+
+```text
+用户管理
+  → 组织/角色/配额
+  → Provider 和模型目录
+  → 成人内容能力测试
+  → 知识库/记忆授权
+  → 用量和账单
+  → 云存储和导出
+  → 审计复盘
+```
+
+管理端可以查看其他用户的私有知识库和记忆，但查看、下载、导出、授权、撤销和删除都必须写入审计。
+
+## 11. 认证、RBAC 与授权判断
+
+### 11.1 认证流程
+
+```text
+请求
+  → 读取 Bearer Token
+  → SHA-256 查找 AuthSession
+  → 检查撤销/过期
+  → 检查 AppUser 启用状态
+  → 写入 last_seen_at
+  → 得到 user_id / organization_id / role
+```
+
+密码使用 PBKDF2-SHA256 派生摘要；数据库不保存明文密码，也不保存明文 Session Token。
+
+### 11.2 权限判定
+
+权限不是前端隐藏按钮，而是后端每个请求的强制条件：
+
+```text
+身份认证
+  → 路由所需权限
+  → 组织范围
+  → 资源所有权/授权记录
+  → 操作级权限 read/use/manage
+  → 执行并记录审计
+```
+
+用户端和管理端 API 逻辑分开。新增未知写接口默认归入管理配置权限，避免新接口漏保护。
+
+### 11.3 资源权限矩阵
+
+| 操作 | 私有资源所有者 | 获授权用户 | 全局用户 | 管理员 |
+| --- | --- | --- | --- | --- |
+| `read` | 是 | 视授权 | 是 | 是，需审计 |
+| `use` | 是 | 视授权 | 是 | 是，需审计 |
+| `manage` | 视资源类型 | 否 | 否 | 是 |
+| `export` | 自己范围 | 允许范围 | 允许范围 | 全量或指定范围 |
+| `publish_global` | 否 | 否 | 否 | 是 |
+
+## 12. 多用户并发与隔离
+
+### 12.1 上下文隔离
+
+每次模型请求都绑定：
+
+```text
+organization_id
+user_id
+campaign_id
+run_id
+trace_id
+span_id
+session_id
+```
+
+消息历史保存在独立 `AgentSession`，不放在 Provider 全局状态、不放在前端共享变量、不通过模型名称作为上下文键。
+
+### 12.2 四层并发限制
+
+| 层级 | 限制 |
+| --- | --- |
+| 用户级 | 并发 Run、Token 日/月额度、存储和导出 |
+| 组织级 | 总并发、总预算、总 Token |
+| 模型级 | Provider QPS、并发连接、超时、重试 |
+| 任务级 | 同一 Campaign 一个活跃 Run |
+
+队列等待、限流、重试和取消都写入 Trace。一个 Provider 故障时，不影响其他 Provider 队列。
+
+## 13. 计费和用量核心逻辑
+
+### 13.1 计量原则
+
+计量记录必须追加写入，不按页面统计临时计算。每条 `UsageEvent` 绑定调用归属：
+
+```text
+user_id + organization_id + run_id + trace_id + provider + model + idempotency_key
+```
+
+计量对象包括 LLM 输入/输出 Token、Embedding、OCR、Rerank、云存储和导出。
+
+### 13.2 费用计算
+
+```text
+LLM 费用 = 输入 Token × 输入费率 + 输出 Token × 输出费率
+总费用 = LLM + Embedding + OCR + Rerank + 存储 + 导出
+```
+
+费用使用调用时冻结的费率版本。Provider 未返回 Token 时，估算值必须标记为 `estimated`，不能直接作为已结算值。
+
+### 13.3 配额检查时机
+
+```text
+创建任务前：检查用户/组织配额
+进入模型队列前：再次检查并发和预算
+调用返回后：写 UsageEvent
+任务结束后：结算本次实际用量
+```
+
+配额策略支持 `warn`、`soft_limit` 和 `hard_limit`。达到硬限制时禁止新调用，并把原因显示在任务和 Trace 中。
+
+## 14. 云存储和导出逻辑
+
+### 14.1 文件生命周期
+
+```mermaid
+stateDiagram-v2
+    [*] --> uploading
+    uploading --> stored
+    stored --> indexed
+    indexed --> active
+    active --> superseded: 文件更新
+    superseded --> recycle_bin
+    recycle_bin --> deleted
+    uploading --> orphaned: 数据库提交失败
+    orphaned --> deleted: 清理任务
+```
+
+对象键按组织、用户、知识库、哈希和安全文件名组成，不以原始文件名作为唯一键。数据库只把已经校验哈希的对象标记为当前版本。
+
+### 14.2 导出内容
+
+导出任务必须包含 `manifest.json`，记录：
+
+- 对象键、大小、哈希和版本。
+- 组织、用户、知识库/记忆归属。
+- 分类和授权状态。
+- Trace、账单和审计范围。
+- 导出发起人、时间、保留期和过期时间。
+
+下载使用短时效签名地址，浏览器不接触云存储长期密钥。
+
+## 15. 失败恢复和一致性
+
+### 15.1 模型调用失败
+
+| 失败 | 处理 |
+| --- | --- |
+| 超时/连接中断 | 按策略重试，写入每次尝试和耗时 |
+| 429/配额 | 进入限流或转人工，不伪造成功 |
+| Provider/模型不存在 | 直接失败，提示管理员修复目录 |
+| Provider 拦截 | 标记 `provider_blocked`，按能力路由规则处理 |
+| 网关拦截 | 标记 `gateway_blocked`，区分模型本体和网关 |
+| 空输出/截断 | 触发格式重试，仍失败则进入人工处理 |
+
+### 15.2 RAG 失败
+
+- 索引为 `indexing` 时禁止新任务使用该库，除非管理员明确允许旧版本。
+- 无命中是低置信结果，不得自动补写事实。
+- 重建失败恢复旧索引和旧计数。
+- 进程中断时归还 `reserved` 知识片段。
+- 向量库损坏时切换本地兜底索引，并记录降级事件。
+
+### 15.3 组合失败
+
+组合器不能把缺失段落静默填充为新内容：
+
+```text
+缺段 → compose_report 标记缺失
+      → Campaign 保持 human_review/failed
+      → 通知中心提醒
+      → 人工修复、跳过或重新运行
+```
+
+## 16. 核心不变量
+
+以下规则是系统必须长期保持的不变量：
+
+1. 没有有效身份和组织归属的请求不能访问业务 API。
+2. 用户端不能创建 Provider、查看 API Key 或输入任意模型名称。
+3. 模型调用必须使用启用且对当前组织可见的模型目录记录。
+4. 任务开始后，规则、技能、模型、知识和记忆必须从快照读取。
+5. Agent 只能检索被挂接且当前用户有权限使用的知识库。
+6. 同一个 Agent 不能重复消费同一个知识片段，其他 Agent 不受影响。
+7. 未确认记忆不能进入有效记忆上下文。
+8. Composer 只能组合已人工通过的段落。
+9. 每次模型调用必须有 `LLMCall`、Trace 和用量归属。
+10. 任何删除、授权、发布全局、导出和计费调整都必须有审计记录。
+11. 失败、等待审批、限流和降级不能标记为成功。
+12. 历史任务、账单和引用不能被当前配置修改覆盖。
+
+## 17. 关键 API 逻辑分组
+
+### 17.1 用户端
+
+```text
+认证：/api/auth/status、/api/auth/login、/api/auth/logout
+模型：/api/models/available
+知识：/api/kbs、/api/kbs/{id}/search、/api/kbs/{id}/files/{name}
+记忆：/api/memories
+任务：/api/campaigns、/api/campaigns/{id}/parse、/api/campaigns/{id}/run
+审查：/api/segments/{id}/review、/api/segments/{id}/fix
+Trace：/api/traces、/api/traces/{trace_id}
+用量：/api/me/usage、/api/me/billing
+```
+
+### 17.2 管理端
+
+```text
+用户：/api/admin/users、/api/admin/organizations
+模型：/api/admin/model-providers、/api/admin/models
+能力测试：/api/admin/models/{id}/capability-tests
+知识授权：/api/admin/knowledge-bases/{id}/grants
+记忆授权：/api/admin/memories/{id}/grants
+计费：/api/admin/usage、/api/admin/billing/settlements
+导出：/api/admin/knowledge-bases/{id}/export、/api/admin/memories/{id}/export
+审计：/api/admin/audit
+```
+
+## 18. 当前实现与 v6 目标对照
+
+| 领域 | 当前 v5 实现 | v6 目标 |
+| --- | --- | --- |
+| Runtime | 已实现会话、工具、审批、恢复、护栏和 Trace | 增加用户/组织归属和配额上下文 |
+| 画布 | 已实现节点、连线、波次和快照 | 按用户隔离画布和模板 |
+| 知识库 | 已实现 RAG、分类、消费锁和 KB3 回滚 | 增加云对象、全局/私有/共享和授权 |
+| 记忆库 | 已实现待确认池、Agent 记忆和筛选删除 | 增加与知识库同构的可见性和授权 |
+| 模型 | 已实现 Provider CRUD、发现、测试和 Agent 绑定 | 收敛为管理端 ModelCatalog，用户端只读选择 |
+| 成人内容能力 | 已设计管理端兼容性测试和能力标签 | 实现测试套件、回归、发布和路由 |
+| 认证 | 已实现本地用户、PBKDF2、Session、RBAC | 增加组织、多租户和管理端角色 |
+| Trace | 已实现 Run/Session/Event/LLMCall 聚合 | 增加用户、组织和账单关联 |
+| 计费 | 已有 Token/耗时调用字段 | 新增 UsageEvent、费率版本、配额和结算 |
+| 存储 | 当前以本地 SQLite、源文件和向量兜底为主 | 迁移云对象存储和异步导出 |
+
+## 19. 核心验收标准
+
+### 19.1 任务链路
+
+- 用户登录后可以创建任务、解析导图、运行 Agent、审查段落和组合成稿。
+- 每个 Run 都有唯一 `trace_id`，能看到模型调用、工具事件、QC 和产物。
+- 修改 Agent 规则或模型目录后，已运行任务的快照不变。
+
+### 19.2 资源隔离
+
+- 用户看不到其他用户未授权的知识库、记忆、任务、Trace 和账单。
+- 管理员可以查看和导出全量资源，所有动作有审计。
+- 全局知识库和全局记忆只允许管理员修改原文。
+- 用户端模型列表只包含管理端已启用且对当前组织开放的目录。
+
+### 19.3 稳定性
+
+- 同一用户不能并发消费同一知识片段。
+- 同一 Campaign 不能产生两个活跃 Run。
+- Provider、网关和模型版本变化能在 Trace 中区分。
+- KB3 重启后仍为 `ready/2717`，向量检索可返回结果。
+- 索引、模型、云存储和导出失败均有明确状态并可恢复。
+
+### 19.4 计费
+
+- 每次 LLM、Embedding、OCR 和存储行为都有用户/组织归属。
+- 费率版本变化不回写历史账单。
+- 预估、已计量和已结算状态可区分。
+- 用量明细可以回溯到 LLMCall、Run、Trace、Agent 和任务。
+
+## 20. 结论
+
+系统的核心不是“接入更多模型”或“堆更多 Agent”，而是把每一次生成变成一条可控、可复现、可审查、可计费的数据链：
+
+```text
+谁发起
+→ 用了哪个版本的 Agent/模型
+→ 读取了哪些被授权的知识和记忆
+→ 产生了哪些模型/工具调用
+→ 经过哪些质检和人工决定
+→ 最终交付了什么
+→ 消耗了多少 AI 和存储资源
+```
+
+v6 的用户端、管理端、云存储、模型能力测试、知识/记忆共享和计费，全部围绕这条链扩展，不改变 v5 已有的 Agent Runtime、QC、组合和 Trace 基础。