607 lines
26 KiB
Markdown
607 lines
26 KiB
Markdown
# 专题-03：AI 编排、上下文与质量评测实现规范
|
||
|
||
- 版本：v1
|
||
- 更新日期：2026-05-19
|
||
- 目标读者：架构 / 后端 / 前端 / 测试 / 文档维护者
|
||
- 阅读时间：35-55 分钟
|
||
- 边界说明：本文件补齐 AI 编排、检索、上下文、风险路由和质量评测的跨文档设计合同。它描述目标设计，不代表当前代码都已实现。精确表结构仍以 `后端-04-统一数据库Schema-v1.md` 为准，精确 API 路径和错误码仍以 `后端-05-统一API契约-v1.md` 为准，阶段门禁和证据包仍归 `doc/dev/*`。
|
||
|
||
## 1. 归属范围
|
||
|
||
本文件只承载第一类设计缺口：系统运行合同、接口语义、字段合同、失败路径和质量算法。以下内容不放在本文件：
|
||
|
||
- 阶段是否退出、证据包字段、review 记录和命令输出。
|
||
- 当前代码是否已经实现。
|
||
- 具体服务类名、JPA 泛型、前端 hook 或测试文件路径。
|
||
|
||
| 设计主题 | 本文件负责 | 其它主文档 |
|
||
|---|---|---|
|
||
| RAGFlow 运行合同 | 客户端调用语义、错误分类、阻塞边界、来源标记 | Schema 看 `后端-04`，API 看 `后端-05` |
|
||
| Graph Query Provider | 查询能力矩阵、返回元信息、降级边界 | ADR 决策看 `架构-03` |
|
||
| Falsification Benchmark | query set、阈值、记录字段、失败原因分类 | 评测 API 和表结构看 `后端-04` / `后端-05` |
|
||
| 上下文组装(Context Assembly) | 请求/响应合同、Layer 0-3、权限二次过滤、Token Budget | 系统流程看 `流程-02A/02B` |
|
||
| Agent / Prompt | 能力矩阵、fallback、模板族、审计字段白名单 | 管理 API 看 `后端-05` |
|
||
| Pipeline / Risk Routing | 风险等级行为、重试与自动确认边界 | 状态机看 `架构-04` |
|
||
| Planning Candidate / Knowledge Draft | 待审对象字段合同和版本校验 | 表结构看 `后端-04` |
|
||
| 全书解析批量返回 / 一致性检查结果 | 用户可解释返回结构 | 普通用户操作流程看 `流程-01B` |
|
||
| 质量评测 | 多模型聚合、分歧惩罚、配置快照绑定 | 评测集 API 看 `后端-05` |
|
||
| S0-AUTH 默认超级管理员 | 初始化与凭据交付安全合同 | 认证 API 和 RBAC 表看 `后端-04` / `后端-05` |
|
||
|
||
## 2. RAGFlow 运行合同
|
||
|
||
### 2.1 定位
|
||
|
||
RAGFlow 是外部语义检索基座，不是 Muse 的事实源。它只能消费 PostgreSQL 中的规范数据(Canonical)和授权资料投影，不能反向决定作品事实。
|
||
|
||
允许进入正式检索的来源类型：
|
||
|
||
| sourceType | 含义 | 是否可进正式检索 |
|
||
|---|---|---:|
|
||
| `work_content` | 当前作品已确认正文、章节和文本块摘要 | 是 |
|
||
| `local_knowledge_base` | 当前作品已确认局域知识 | 是 |
|
||
| `global_knowledge_base` | 当前用户/作品被授权的全局知识库资料 | 是 |
|
||
| `shadow_draft` | Suggestion / Knowledge Draft / Planning Candidate 等待审内容 | 否。只能用于明确标记的预览或审计，不得进入正式生成上下文 |
|
||
|
||
### 2.2 调用输入
|
||
|
||
Muse 后端调用 RAGFlow 时，必须传入或等价计算以下上下文：
|
||
|
||
| 字段 | 要求 |
|
||
|---|---|
|
||
| `workId` | 当前作品 ID |
|
||
| `userId` | 当前用户 ID 或系统任务服务身份 |
|
||
| `scenario` | `generation` / `extraction` / `validation` / `planning` / `consistency_check` / `search` |
|
||
| `allowedGlobalKbIds` | 当前请求允许使用的全局知识库 ID 列表 |
|
||
| `sourceTypes` | 本次允许检索的来源类型，默认不包含 `shadow_draft` |
|
||
| `queryText` / `queryVectorInput` | 检索查询文本或等价输入 |
|
||
| `maxResults` | 最大返回数量 |
|
||
| `traceId` | 链路追踪 ID |
|
||
|
||
RAGFlow 请求不得只依赖物理 dataset 隔离做权限边界。即使多个全局知识库共用物理索引，请求或后处理也必须按 `global_kb_id IN allowedGlobalKbIds` 或等价规则过滤。
|
||
|
||
### 2.3 错误分类与阻塞边界
|
||
|
||
| 错误 | 系统行为 |
|
||
|---|---|
|
||
| RAGFlow 不可用 / 超时 / 认证失败 | 阻塞依赖检索上下文的生成、提取、校验、规划和一致性检查，返回可恢复失败 |
|
||
| RAGFlow 限流 | 任务进入可重试失败；不静默降级为低质量生成 |
|
||
| 投影落后 | 使用 watermark + overlay 补齐；补不齐时返回投影未追平错误 |
|
||
| 单条资料缺权限 | 丢弃该条结果，记录审计摘要，不进入上下文 |
|
||
| 单条资料缺来源元信息 | 丢弃该条结果，不作为事实上下文 |
|
||
|
||
RAGFlow 不可用不得阻塞：
|
||
|
||
- 正文保存。
|
||
- 手工编辑章节或文本块。
|
||
- 查看已确认正文和已确认作品知识。
|
||
- 处理不依赖检索上下文的本地 UI 状态。
|
||
|
||
### 2.4 投影失败与重建
|
||
|
||
正式写入 Canonical 后，投影事件通过 `projection_outbox` 或等价机制发送给 RAGFlow。投影消费者必须满足：
|
||
|
||
- 幂等：同一 PG 业务 ID 重放不会生成重复事实。
|
||
- 可重试：超时、限流、临时不可用要保留失败原因和重试次数。
|
||
- 可观测：管理员能看到投影目标、失败原因、最后尝试时间和待处理数量。
|
||
- 可重建：重建索引时以 PostgreSQL 事实源为准，旧 RAGFlow 文档 ID 只能作为映射参考，不作为事实。
|
||
|
||
## 3. Graph Query Provider
|
||
|
||
### 3.1 能力矩阵
|
||
|
||
Graph Query Provider 是图查询抽象，不直接等同 Neo4j。它的实现可以是 RAGFlow GraphRAG、Neo4j 或其它 provider，但对 Muse 的合同必须稳定。
|
||
|
||
| queryType | 必须支持的语义 | 典型用途 |
|
||
|---|---|---|
|
||
| `entity_adjacency` | 实体邻接关系、关系类型、方向、证据来源 | 角色关系、组织关系、地点关联 |
|
||
| `relationship_evolution` | 同一实体关系随章节或时间变化 | 角色关系演变、阵营变化 |
|
||
| `event_timeline` | 事件时间线、章节范围、先后顺序 | 时间线一致性 |
|
||
| `causal_chain` | 因果链、触发事件、后果事件 | 因果检查、伏笔回收 |
|
||
| `foreshadowing_trace` | 伏笔、铺垫、回收节点 | 长篇结构检查 |
|
||
| `consistency_evidence` | 支撑一致性检查的问题证据集合 | 风险解释和定位 |
|
||
|
||
### 3.2 请求合同
|
||
|
||
```json
|
||
{
|
||
"workId": "string-id",
|
||
"queryType": "entity_adjacency",
|
||
"entityIds": ["string-id"],
|
||
"chapterRange": {
|
||
"fromChapterId": "string-id",
|
||
"toChapterId": "string-id"
|
||
},
|
||
"allowedGlobalKbIds": ["string-id"],
|
||
"maxResults": 20,
|
||
"traceId": "request-trace-id"
|
||
}
|
||
```
|
||
|
||
### 3.3 返回合同
|
||
|
||
每条结果必须带可追溯来源。缺少来源对象、授权状态或置信度的结果不得进入上下文。
|
||
|
||
```json
|
||
{
|
||
"provider": "ragflow_graphrag",
|
||
"queryType": "entity_adjacency",
|
||
"degraded": false,
|
||
"watermark": {
|
||
"projectionTarget": "graph_provider",
|
||
"lastSyncedRevision": 123
|
||
},
|
||
"results": [
|
||
{
|
||
"sourceObjectType": "knowledge_relation",
|
||
"sourceObjectId": "string-id",
|
||
"sourceChapterId": "string-id",
|
||
"globalKnowledgeBaseId": null,
|
||
"authorization": "allowed",
|
||
"confidence": 0.87,
|
||
"evidence": "引用摘要或证据片段",
|
||
"metadata": {
|
||
"relationType": "ally",
|
||
"direction": "outgoing"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.4 降级边界
|
||
|
||
- Graph Query Provider 不可用时，可以让非因果、非时间线类生成继续使用 RAGFlow 语义检索，但响应必须标记 `degraded=true`。
|
||
- 因果链、事件时间线、伏笔回收和一致性检查不能静默降级为普通语义检索后假装完整。
|
||
- Provider 返回投影落后时，必须先尝试 PG overlay；仍无法补齐时返回可恢复失败。
|
||
|
||
## 4. Falsification Benchmark
|
||
|
||
### 4.1 Query set
|
||
|
||
S1-B 起，GraphRAG / Graph Query Provider 的决策不能靠主观感受。首批 benchmark query set 至少包含：
|
||
|
||
| 类别 | 目标 | 最低通过阈值 |
|
||
|---|---|---:|
|
||
| `local` | 当前作品局域知识、正文和规划项检索 | 90% |
|
||
| `global` | 授权全局知识库检索和过滤 | 90% |
|
||
| `temporal` | 时间线、章节顺序、事件先后关系 | 80% |
|
||
| `causal` | 因果链、伏笔铺垫和回收关系 | 80% |
|
||
|
||
低于阈值不自动等于必须引入 Neo4j，但必须触发 ADR-006 决策复审，并记录失败原因。mock provider 或手写假结果不得计入正式 benchmark 结论。
|
||
|
||
### 4.2 记录字段
|
||
|
||
每次 benchmark run 必须记录：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `datasetVersion` | 固定 query set 版本 |
|
||
| `provider` | `ragflow_graphrag` / `neo4j` / `mock` 等 |
|
||
| `queryType` | local / global / temporal / causal |
|
||
| `queryText` | 查询输入 |
|
||
| `expectedEvidence` | 期望命中的事实、章节或关系 |
|
||
| `actualResults` | 实际返回摘要和来源 |
|
||
| `score` | 单条得分 |
|
||
| `failureReason` | 失败分类 |
|
||
| `testedConfigSnapshot` | RAGFlow、Graph Provider、Prompt、Agent、上下文策略和 New-API 摘要 |
|
||
| `traceId` | 可追踪请求 ID |
|
||
|
||
失败原因至少包含：`missing_fact`、`wrong_source`、`unauthorized_source`、`stale_projection`、`temporal_order_wrong`、`causal_link_missing`、`low_confidence`、`provider_error`。
|
||
|
||
## 5. 上下文组装(Context Assembly)
|
||
|
||
### 5.1 请求合同
|
||
|
||
上下文组装是后端内部合同，可以有内部 API 或服务接口。无论实现形态如何，输入语义必须稳定：
|
||
|
||
```json
|
||
{
|
||
"workId": "string-id",
|
||
"userId": "string-id",
|
||
"scenario": "continuation",
|
||
"targetChapterId": "string-id",
|
||
"targetBlockId": "string-id",
|
||
"userIntent": "继续写下一段",
|
||
"currentText": "用户当前输入或选中文本",
|
||
"allowedGlobalKbIds": ["string-id"],
|
||
"tokenBudget": {
|
||
"maxInputTokens": 12000,
|
||
"reservedOutputTokens": 2000
|
||
},
|
||
"includeDebugSnapshot": false
|
||
}
|
||
```
|
||
|
||
`scenario` 至少包含：`continuation`、`rewrite`、`description`、`planning`、`extraction`、`validation`、`consistency_check`、`ner_preview`、`full_parse`。
|
||
|
||
### 5.2 四层上下文
|
||
|
||
| Layer | 内容 | 缓存策略 | 可省略性 |
|
||
|---|---|---|---|
|
||
| Layer 0 当前输入 | 用户当前意图、目标文本、目标章节、目标 Block revision | 不跨请求缓存 | 不可省略 |
|
||
| Layer 1 近邻正文 | 当前章节、相邻 Block、章节目标、已确认规划项 | 可按章节和 revision 缓存 | 续写、改写、描写不可省略 |
|
||
| Layer 2 作品事实 | 正式局域知识、Narrative State、角色关系、事件时间线 | 可按 work watermark 缓存 | 一致性检查和规划不可省略 |
|
||
| Layer 3 授权全局资料 | 被授权全局知识库摘要、体裁规则、平台规范 | 可按授权策略版本缓存 | 可按场景省略，但不能越权 |
|
||
|
||
Token Budget 处理顺序：
|
||
|
||
1. 先保留输出预算。
|
||
2. Layer 0 必须完整保留。
|
||
3. Layer 1 优先于 Layer 2，Layer 2 优先于 Layer 3。
|
||
4. 超限时先摘要化低优先级资料，再截断；不得丢失来源引用。
|
||
5. 被省略资料必须进入 `omittedSources`，写明原因：`token_budget`、`not_authorized`、`stale_projection`、`low_confidence`、`not_relevant`。
|
||
|
||
### 5.3 场景注入矩阵
|
||
|
||
| 场景 | 必须注入 | 可以省略 |
|
||
|---|---|---|
|
||
| 续写 | Layer 0、Layer 1、核心 Layer 2、已授权且相关的 Layer 3 | 低相关全局资料、远距离章节摘要 |
|
||
| 改写 | Layer 0、目标 Block revision、局部上下文、风格约束 | 远距离时间线 |
|
||
| 描写 | Layer 0、目标实体/地点、风格约束、相关局域知识 | 与描写无关的事件链 |
|
||
| 规划生成 | 作品方向、章节规划、Narrative State、相关实体关系 | 当前正文全文 |
|
||
| 提取 | 来源文本、来源快照、MetaSchema | 全局资料，除非提取规则依赖它 |
|
||
| 校验 | 待审草稿、当前 Canonical、相关关系和事件 | 与冲突无关的风格规则 |
|
||
| 一致性检查 | 正式正文、正式知识、规划项、时间线/因果图 | 未确认草稿 |
|
||
| NER Preview | 当前文本和局部 MetaSchema | 正式检索上下文 |
|
||
| Full Parse | 章节文本、章节边界、MetaSchema、parse job 信息 | 其它章节全文，除非用于跨章冲突检查 |
|
||
|
||
### 5.4 响应合同
|
||
|
||
```json
|
||
{
|
||
"contextId": "string-id",
|
||
"scenario": "continuation",
|
||
"layers": [
|
||
{
|
||
"layer": "L1",
|
||
"tokenCount": 3200,
|
||
"sourceRefs": [
|
||
{
|
||
"sourceType": "block",
|
||
"sourceId": "string-id",
|
||
"revision": 12
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"omittedSources": [
|
||
{
|
||
"sourceType": "global_knowledge_base",
|
||
"sourceId": "string-id",
|
||
"reason": "not_authorized"
|
||
}
|
||
],
|
||
"permissionFilters": {
|
||
"allowedGlobalKbIds": ["string-id"],
|
||
"droppedResultCount": 2
|
||
},
|
||
"projectionState": {
|
||
"usedOverlay": true,
|
||
"laggingTargets": ["ragflow"]
|
||
},
|
||
"userExplanation": "参考了当前章节、角色关系和已授权资料；部分资料因未授权未使用。",
|
||
"auditSnapshotRef": "string-id"
|
||
}
|
||
```
|
||
|
||
普通用户只能看到 `userExplanation` 和可理解来源摘要。完整 Prompt、配置快照、Layer 明细、Graph Query Provider 结果和 Token Budget 调试信息只允许管理员、审计或调试接口查看。
|
||
|
||
### 5.5 二次权限校验
|
||
|
||
上下文组装必须做两次权限控制：
|
||
|
||
1. 检索前：根据当前用户、作品、套餐、访问策略计算 `allowedGlobalKbIds`。
|
||
2. 检索后：对每条外部返回再次校验来源、授权状态和元数据完整性。
|
||
|
||
检索后发现未授权、已撤销、缺 `global_kb_id` 或缺来源对象的结果时，必须丢弃并记录摘要。不得因为结果来自外部检索系统就直接进入 Prompt。
|
||
|
||
## 6. Planning Task 与规划候选
|
||
|
||
### 6.1 建模口径
|
||
|
||
Planning Task 是任务类型(`task_type`)，不是 S3 阶段必需的独立 Planning Agent。
|
||
|
||
- S3 阶段：通过现有 Agent 能力执行 `task_type=planning`，输出规划候选。
|
||
- S5 后：如果 benchmark、可观测性和产品需求证明规划能力需要独立生命周期，再新增独立 Planning Agent ADR。
|
||
- 任何规划候选仍然进入 Shadow，由普通用户确认后才成为正式规划数据或生成上下文。
|
||
|
||
### 6.2 Planning Candidate 合同
|
||
|
||
规划候选至少需要以下语义字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `candidateId` | 规划候选 ID |
|
||
| `workId` | 所属作品 |
|
||
| `sectionKey` | 作品设定、章节大纲、世界设定、角色关系、文风检查等分区 |
|
||
| `taskType` | 固定为 `planning` 或规划子类型 |
|
||
| `baseItemId` | 被修改的规划项；新建时为空 |
|
||
| `baseItemVersion` | 生成时读取的规划项版本 |
|
||
| `sourceSnapshot` | 输入文本、上下文、配置和来源摘要 |
|
||
| `proposedData` | 候选规划数据 |
|
||
| `evidence` | 支撑该候选的正文、知识或全局资料来源 |
|
||
| `riskLevel` | low / medium / high / critical |
|
||
| `expiresAt` | 过期时间 |
|
||
|
||
确认规划候选前必须校验 `baseItemVersion`。版本不匹配时返回 stale，不得把旧候选强行写入 Canonical；用户可以重新生成或手动修改后保存。
|
||
|
||
## 7. Agent 能力矩阵与 fallback
|
||
|
||
| 能力 | 输入 | 输出 | 可接受 fallback | 不允许 |
|
||
|---|---|---|---|---|
|
||
| Generation | 上下文、Prompt、当前文本、New-API 绑定 | Suggestion、可选 Knowledge Draft、Risk Markers | Agent 服务不可用时，可走直连 New-API fallback，但必须标记 degraded 并保留任务记录 | 缺检索硬依赖时静默生成低质量候选 |
|
||
| Extraction | 来源快照、MetaSchema、正文或候选文本 | Knowledge Draft / Proposal | 旧 NER 只能作为预览或低置信草稿来源，不得自动确认 | 提取失败静默跳过 |
|
||
| Validation | Draft、当前 Canonical、关系和时间线 | 风险标记、冲突摘要、去重建议 | 可以返回 `needs_review` | 无校验时标记 safe |
|
||
| Planning | task_type、作品规划上下文、目标 section | Planning Candidate | 可使用通用生成能力执行规划任务 | S3 阶段强制引入独立 Planning Agent |
|
||
| Retrieval / Context | 查询、授权、场景和 Token Budget | 可解释上下文 | 非图强依赖场景可降级为语义检索 | 越权资料进入上下文 |
|
||
| Evaluation | 固定数据集、候选输出、评审模型集合 | 评测报告和风险结论 | 单模型临时评审只能做调试，不计正式结论 | 用评测结论替代用户确认 |
|
||
|
||
fallback 对用户的基本反馈：
|
||
|
||
- 生成不可用：提示“AI 助手暂时不可用，可以稍后重试”。
|
||
- 检索资料未授权：提示“部分资料当前无权使用，已从本次参考中排除”。
|
||
- 来源已变更：提示“源文本已变更，需要重新生成或重新提取”。
|
||
- Token Budget 超限：提示“参考资料过多，系统已优先保留当前章节和关键设定”。
|
||
|
||
普通用户界面不得直接暴露 `Agent`、`Prompt`、`Token Budget`、`Graph Query Provider`、`Layer` 等系统词。
|
||
|
||
## 8. Prompt 工程合同
|
||
|
||
### 8.1 模板族
|
||
|
||
Prompt 至少按以下模板族管理：
|
||
|
||
| 模板族 | 用途 | 必含变量 |
|
||
|---|---|---|
|
||
| `generation` | 续写、改写、描写、插入 | 作品方向、当前章节目标、目标文本、上下文摘要、文风约束、输出格式 |
|
||
| `planning` | 作品设定、章节规划、世界设定、角色关系、文风检查 | 规划分区、当前规划项、约束条件、候选数量、输出 schema |
|
||
| `extraction` | 从正文、候选或导入内容提取知识草稿 | MetaSchema、来源快照、目标 domain/scope/targetType、输出 schema |
|
||
| `validation` | 校验来源、冲突、重复和风险 | 当前 Canonical、待审数据、风险等级规则、输出 schema |
|
||
| `evaluation` | 多模型评审和回归对比 | 评测场景、评分标准、候选输出、参考答案或参考证据 |
|
||
|
||
### 8.2 激活前要求
|
||
|
||
Prompt 新版本激活前必须满足：
|
||
|
||
- 变量结构完整，不能依赖运行时拼接隐式变量。
|
||
- 输出格式明确，能被后端解析或人工审阅。
|
||
- 禁止直接要求 AI 写 Canonical。
|
||
- 关联至少一个可回归评测场景，或者标记为临时实验版本。
|
||
- 激活、停用、回滚都有审计记录。
|
||
|
||
Prompt 工程的质量闭环是：模板版本 -> 固定评测集 -> 多模型评审 -> 聚合结论 -> 人工复核 -> 激活或回滚。不能只靠一次手工试跑决定上线。
|
||
|
||
## 9. New-API 审计字段白名单
|
||
|
||
Muse 不复制 New-API 的成本账本，也不持久化 New-API token 明文。Muse 可以保存的任务级摘要字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `newApiBindingId` | Muse 侧 New-API 绑定引用 |
|
||
| `newApiRequestId` | New-API 返回的请求引用或 trace |
|
||
| `modelAlias` | 模型别名或逻辑模型名，不作为供应商路由权威 |
|
||
| `inputTokenCount` / `outputTokenCount` | 任务级 usage summary |
|
||
| `latencyMs` | 调用耗时 |
|
||
| `finishReason` | 正常结束、长度截断、内容过滤、错误等 |
|
||
| `errorCode` / `errorMessage` | 脱敏错误摘要 |
|
||
| `promptVersionRef` | Prompt 版本引用 |
|
||
| `agentConfigRef` | Agent 配置引用 |
|
||
| `contextSnapshotRef` | 上下文摘要引用 |
|
||
|
||
禁止保存：
|
||
|
||
- New-API token 明文。
|
||
- Prompt secret。
|
||
- 模型供应商成本明细作为 Muse 权威账本。
|
||
- 未脱敏的完整请求头。
|
||
- 普通用户不可见的系统配置全文，除非走管理员审计视图并受权限控制。
|
||
|
||
## 10. Risk Routing
|
||
|
||
### 10.1 风险等级行为表
|
||
|
||
| riskLevel | 系统行为 | 是否允许自动确认 |
|
||
|---|---|---:|
|
||
| `low` | 展示轻量提示，允许用户正常确认 | 可允许 |
|
||
| `medium` | 明确展示风险和来源，要求用户显式确认 | 不建议自动确认 |
|
||
| `high` | 阻止批量自动确认，要求用户逐项处理或重新生成 | 否 |
|
||
| `critical` | 阻止确认进入 Canonical；要求重新生成、人工修改或管理员排查 | 否 |
|
||
|
||
生成链路最多自动重试 2 次。两次后仍为 high / critical 时，不继续循环重试，必须给出失败状态、替代候选或人工处理入口。
|
||
|
||
用户手工编辑正文时，Risk Routing 只能标记风险、生成待审草稿或提示重新提取，不得自动改写用户正文。
|
||
|
||
### 10.2 与待审层的关系
|
||
|
||
- 风险标记属于 Shadow 解释的一部分，不是 Canonical 事实。
|
||
- high / critical 不得通过“一键确认全部可确认章节”绕过。
|
||
- 风险状态、来源证据和用户决策必须进入 Archive 或审计摘要，便于后续追溯。
|
||
|
||
## 11. Knowledge Draft 字段合同
|
||
|
||
Knowledge Draft / Proposal 至少需要以下语义字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `id` | Draft / Proposal ID |
|
||
| `workId` | 所属作品 |
|
||
| `proposalType` | create_entity / update_attribute / add_relation / update_narrative_state / planning_update |
|
||
| `sourceKind` | block / suggestion / parse_job / planning_candidate |
|
||
| `sourceRefId` | 来源对象 ID |
|
||
| `sourceBlockRevision` | 来源 Block revision，适用时必填 |
|
||
| `sourceContentHash` | 来源内容 hash |
|
||
| `evidence` | 支撑该草稿的证据数组 |
|
||
| `proposedData` | 拟写入数据 |
|
||
| `currentData` | 当前 Canonical 快照 |
|
||
| `riskLevel` | low / medium / high / critical |
|
||
| `suggestionId` | 生成链路中关联 Suggestion |
|
||
| `parseJobId` + `chapterId` | Full Parse 章节确认边界 |
|
||
| `expiresAt` | 过期时间 |
|
||
|
||
`evidence` 至少包含：
|
||
|
||
```json
|
||
{
|
||
"sourceType": "block",
|
||
"sourceId": "string-id",
|
||
"revision": 5,
|
||
"quoteOrSummary": "证据摘要",
|
||
"confidence": 0.82
|
||
}
|
||
```
|
||
|
||
缺少来源快照、来源 hash 或章节边界的旧草稿不得 best-effort 硬确认，应作废并重新提取。
|
||
|
||
## 12. 全书解析批量返回合同
|
||
|
||
批量选择和“一键确认全部可确认章节”只是用户操作效率优化。后端仍按章节逐个事务执行，并返回可解释摘要。
|
||
|
||
建议返回结构：
|
||
|
||
```json
|
||
{
|
||
"parseJobId": "string-id",
|
||
"summary": {
|
||
"requestedChapterCount": 12,
|
||
"succeededChapterCount": 10,
|
||
"failedChapterCount": 2
|
||
},
|
||
"chapters": [
|
||
{
|
||
"chapterId": "string-id",
|
||
"status": "succeeded",
|
||
"acceptedProposalCount": 18,
|
||
"archivedProposalCount": 18,
|
||
"outboxEventCount": 6,
|
||
"retryable": false
|
||
},
|
||
{
|
||
"chapterId": "string-id",
|
||
"status": "failed",
|
||
"failureCode": "CHAPTER_BATCH_CONFLICT",
|
||
"failureReason": "本章存在冲突草稿，需要逐项处理",
|
||
"retryable": true
|
||
}
|
||
],
|
||
"retryableChapterIds": ["string-id"]
|
||
}
|
||
```
|
||
|
||
失败章节不得回滚已成功章节；也不得只返回一个全局错误让用户无法定位。
|
||
|
||
## 13. 一致性检查结果结构
|
||
|
||
一致性检查是主动质量工具，不是强制审批。返回结果至少包含：
|
||
|
||
```json
|
||
{
|
||
"checkId": "string-id",
|
||
"workId": "string-id",
|
||
"issues": [
|
||
{
|
||
"issueId": "string-id",
|
||
"issueType": "timeline_conflict",
|
||
"severity": "high",
|
||
"title": "角色到达地点的时间冲突",
|
||
"description": "第 12 章和第 14 章对同一事件时间顺序描述不一致",
|
||
"locations": [
|
||
{
|
||
"chapterId": "string-id",
|
||
"blockId": "string-id",
|
||
"revision": 8
|
||
}
|
||
],
|
||
"relatedObjects": [
|
||
{
|
||
"type": "knowledge_entity",
|
||
"id": "string-id"
|
||
}
|
||
],
|
||
"evidence": [
|
||
{
|
||
"sourceType": "graph_provider",
|
||
"sourceId": "string-id",
|
||
"summary": "证据摘要"
|
||
}
|
||
],
|
||
"suggestedActions": [
|
||
"修改第 14 章事件描述",
|
||
"更新角色时间线"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
严重程度使用 `low` / `medium` / `high` / `critical`。检查结果只提示、定位和解释风险，不自动写正文、规划项或知识。
|
||
|
||
## 14. 质量评测聚合算法
|
||
|
||
### 14.1 多模型评审输入
|
||
|
||
正式 Evaluation Run 至少绑定：
|
||
|
||
- 评测集版本。
|
||
- Prompt 版本。
|
||
- Agent 配置版本。
|
||
- 上下文策略版本。
|
||
- 全局知识库和访问策略版本。
|
||
- New-API 绑定摘要。
|
||
- judge model set。
|
||
|
||
### 14.2 加权中位数 + 分歧惩罚
|
||
|
||
每个评审模型返回 `score`、`confidence`、`rationale` 和结构化问题列表。聚合时：
|
||
|
||
1. 按模型可信度、场景适配度和历史稳定性计算权重。
|
||
2. 用加权中位数作为基础分，降低极端模型输出影响。
|
||
3. 计算分歧度，例如四分位距、最大最小差或高低分阵营差。
|
||
4. 根据分歧度扣减置信度或最终分。
|
||
5. 输出三态结论：`pass`、`needs_human_review`、`fail`。
|
||
|
||
聚合结果必须保留：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `baseScore` | 加权中位数基础分 |
|
||
| `disagreementPenalty` | 分歧惩罚 |
|
||
| `finalScore` | 最终分 |
|
||
| `confidence` | 聚合置信度 |
|
||
| `verdict` | pass / needs_human_review / fail |
|
||
| `judgeBreakdown` | 各模型得分摘要 |
|
||
| `failureReasons` | 失败或需复核原因 |
|
||
|
||
评测结论只能用于改进 Prompt、Agent、上下文策略和回归风险判断，不替代普通用户对正文、规划和作品知识的确认。
|
||
|
||
## 15. 默认超级管理员初始化
|
||
|
||
Sa-Token 引入后，系统需要可审计的默认超级管理员初始化，但不能交付明文默认密码。
|
||
|
||
目标合同：
|
||
|
||
- 初始化只允许在安装、首启或明确的系统管理命令中执行。
|
||
- 初始化必须幂等：已存在超级管理员时不得重复创建或覆盖密码。
|
||
- 凭据交付只能使用一次性 bootstrap token、临时密码哈希、控制台一次性输出或等价安全机制。
|
||
- 首次登录必须强制改密或完成凭据轮换。
|
||
- 初始化行为必须写审计日志，记录时间、来源、操作者或系统服务身份。
|
||
- 日志、接口响应和文档不得包含明文默认密码。
|
||
|
||
错误处理：
|
||
|
||
| 场景 | 行为 |
|
||
|---|---|
|
||
| 超级管理员已存在 | 返回已初始化状态，不改写凭据 |
|
||
| bootstrap token 过期 | 拒绝初始化，要求重新生成 |
|
||
| 初始化部分失败 | 回滚用户/角色绑定或进入可重试失败状态 |
|
||
| 无安全凭据来源 | 拒绝创建默认账号 |
|
||
|
||
## 16. 与 doc/dev 的关系
|
||
|
||
`doc/dev/00-09` 仍负责研发管理基线、阶段依赖、验收门禁和证据包。本文件只把其中已经属于“目标设计合同”的内容沉入 `doc/design-docs`。后续如果 `doc/dev` 再出现新的设计合同，应先判断：
|
||
|
||
1. 是否属于产品/架构/API/Schema/流程目标设计。
|
||
2. 是否已有正式设计 owner。
|
||
3. 是否只是阶段门禁或证据要求。
|
||
|
||
只有第 1 类和第 2 类才需要进入 `doc/design-docs`；阶段门禁和证据要求继续留在 `doc/dev`。
|