oh-my-muse/design-docs/专题-03-AI编排上下文与质量评测实现规范.md

专题-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	系统流程看 流程-02
Agent / Prompt	能力矩阵、fallback、模板族、审计字段白名单	管理 API 看 后端-05
Pipeline / Risk Routing	风险等级行为、重试与自动确认边界	状态机看 架构-04
Planning Candidate / Knowledge Draft	待审对象字段合同和版本校验	表结构看 后端-04
全书解析批量返回 / 一致性检查结果	用户可解释返回结构	用户流程看 流程-01
质量评测	多模型聚合、分歧惩罚、配置快照绑定	评测集 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 请求合同

{
  "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 返回合同

每条结果必须带可追溯来源。缺少来源对象、授权状态或置信度的结果不得进入上下文。

{
  "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 或服务接口。无论实现形态如何，输入语义必须稳定：

{
  "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 响应合同

{
  "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 至少包含：

{
  "sourceType": "block",
  "sourceId": "string-id",
  "revision": 5,
  "quoteOrSummary": "证据摘要",
  "confidence": 0.82
}

缺少来源快照、来源 hash 或章节边界的旧草稿不得 best-effort 硬确认，应作废并重新提取。

12. 全书解析批量返回合同

批量选择和“一键确认全部可确认章节”只是用户操作效率优化。后端仍按章节逐个事务执行，并返回可解释摘要。

建议返回结构：

{
  "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. 一致性检查结果结构

一致性检查是主动质量工具，不是强制审批。返回结果至少包含：

{
  "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。