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 请求合同

```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`。