zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

设计: 固化正文智能体卡索引原文回读契约

Browse Source
This commit is contained in:
zizi 2026-07-20 18:42:24 +08:00
parent 2124a79312
commit 36268bb118
8 changed files with 204 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.agents/workflows/ai-development-protocol.md
View File

@ -2,6 +2,7 @@
> **类型**:元流程(workflows) · **简版规约**:[`../../AGENTS.md`](../../AGENTS.md) §5 工作协议(本文件是其操作化展开)。
> **何时用**:承接**任何** oh-my-muse 任务时先走本流程分流。核心立场:**机械门禁优先、完成=验证、反假绿**。
> **版本**:v1 · **更新日期**:2026-07-20 · **变更记录**:从未编号版本升级为 v1，新增创作智能体反序验证门禁与正文卡索引/原文回读双线。
---
@ -32,6 +33,14 @@
- 全简体中文注释;外部交互/核心实现/错误路径留可追溯日志。
- 契约先行(见 [`../rules/contract-first.md`](../rules/contract-first.md));守 BC 边界(见 [`../rules/bc-boundaries.md`](../rules/bc-boundaries.md))。
### 创作智能体反序验证门禁
- **能力验证顺序固定**:清洗/抽卡/范式 → 正文 Gate B → 细纲 → 大纲+设定。正文 Gate B 未由唯一判定器输出 `passed` 前,不得启动细纲智能体真实能力验收;单章、单作品、Gate A 或人工观感都不能替代 Gate B。
- **正式创作数据流不倒置**:产品运行仍是大纲+设定 → 细纲 → 正文。反序只用于能力隔离与归因,不能让实验评测产物反写正式设定、Canonical 状态、细纲或正文。
- **正文双线固定**:抽取卡只作索引,命中后必须按来源引用回读冻结线内原文。卡线负责定位事实与历史场景,原文线负责人物声音、动作习惯、能力表现和叙事质感;无来源卡不得单独支撑正文硬事实。
- **独立权威事实**:作者确认的正式设定、冻结点可见的 Canonical 状态、已确认细纲声明的新事实直接引用各自不可变版本,不要求伪造抽取卡或历史原文来源。
- **阶段边界**:正文实验阶段不改产品 API、Flyway、业务数据库或 Canonical 主链。只有正文 Gate B=`passed` 后,才另立产品化计划和后续细纲验收计划。
## 五、验证(证据门 —— 不可跳过)
- **完成 = 机械验证**;无自动化绿证据**不得**声称“完成/修复/通过”(见 [`../rules/verification-and-anti-false-green.md`](../rules/verification-and-anti-false-green.md))。
- 用户可见功能按 [`../skills/golden-journey-vertical-slice.md`](../skills/golden-journey-vertical-slice.md) 的**三指标**报告(代码 / 自动化验证 / 端到端可用),不给单一百分比。

62
design-docs/专题-01-正文建议接受(Accept Suggestion)实现规范.md
View File

@ -1,10 +1,11 @@
# 专题-01：正文建议接受（Accept Suggestion）实现规范
- 版本：v5
- 更新日期：2026-05-23
- 版本：v6
- 更新日期：2026-07-20
- 目标读者：产品 / 架构 / 前端 / 后端 / 测试
- 阅读时间：20–35 分钟
- 边界说明：本文档只收束“接受建议”这条跨文档主链路：用户怎么把 AI 候选写入正文、关联知识草稿怎么保留或失效、正文来源归因怎么落点、事务边界怎么切、前端怎么反馈。精确 Schema、状态机和统一错误模型由后续后端阶段承接；当前阶段以 `架构-02` 和 `架构-04` 为准。
- 变更记录：v6（2026-07-20）补齐编辑后新 candidateVersion、重新 detector、`accept_preflight` 与 CAS 接受边界；实验阶段不改 API/DB。v5（2026-05-23）收束接受建议、知识草稿、来源归因和事务边界。
## 1. 目标与范围
@ -42,14 +43,14 @@ Accept Suggestion 是 AI 候选从待审层(Shadow)进入正文规范数据(Cano
| 路径 | 正文结果 | 知识草稿结果 | 历史结果 |
|---|---|---|---|
| 原样接受 | Suggestion 内容进入目标 Block | 与当前 Suggestion 绑定的草稿保持待确认；不得自动入 Local KB | Suggestion 归档为 accepted |
| 修改后合并 | `contentOverride` 进入目标 Block | 旧草稿立即失效；AFTER_COMMIT 重新提取新的草稿 | Suggestion 归档为 accepted，并保留 `final_content` 快照（如需要） |
| 修改后合并 | 用户编辑先生成递增的 candidateVersion，重新通过 detector 和 `accept_preflight` 后，该版本正文进入目标 Block | 旧版本草稿在新版本被接受时失效；AFTER_COMMIT 重新提取新的草稿 | 最终 candidateVersion 归档为 accepted，旧版本保留审计链且不可接受 |
| 拒绝 | 正文不变 | 关联草稿一起丢弃 | Suggestion 归档为 rejected |
### 2.2 为什么“修改后合并”不是新状态
- 用户决策仍然是“接受这条建议，只是我改了最终入正文的文本”。
- 它不应该发明新的 Active 状态，也不应该生成第二套历史状态机。
- 归档层统一记为 `accepted`，但必须保留“这是 modified merge”的审计语义。
- 编辑动作只生成新的待审 candidateVersion，不直接写正文；归档层最终统一记为 `accepted`，但必须保留“这是 modified merge”的版本链与审计语义。
### 2.3 Stale Draft 规则
@ -90,7 +91,7 @@ Accept Suggestion 是 AI 候选从待审层(Shadow)进入正文规范数据(Cano
- Accept 主事务内不得发起外部 AI / 提取 / 校验调用。
- 原样接受时，正文写入、候选归档、正文来源归因、关联草稿状态保留、change log、outbox 写入必须放在同一事务里完成。
- 修改后合并时，正文写入、Suggestion 归档、旧草稿失效与审计仍在主事务；重新提取只能走 AFTER_COMMIT 异步链路。
- 修改后合并时，只有新 candidateVersion 重新通过 detector 和 `accept_preflight` 后，正文写入、Suggestion 归档、旧草稿失效与审计才进入主事务；重新提取只能走 AFTER_COMMIT 异步链路。
### 4.4 历史与投影
@ -112,8 +113,8 @@ Accept 命令必须携带以下语义：
| actor / work / targetBlock | 当前用户、作品和目标 Block |
| suggestion | 仍处于 Active / Shadow 的候选 |
| expectedRevision | 用户决策基于的目标 Block revision，必填 |
| acceptMode | `accept_as_is` 或 `merge_after_edit` |
| finalContent | 仅 `merge_after_edit` 需要，表示用户确认写入正文的最终内容 |
| acceptMode | `accept_as_is` 或 `merge_after_edit`；后者只能引用已经重新检测通过的编辑版本 |
| candidateVersion / candidateSha256 | 本次实际接受的不可变候选版本及正文哈希；编辑后必须递增版本并重新计算哈希 |
| decisionContext | UI 决策来源、候选版本、质量结果版本和必要审计摘要 |
| acceptPreconditionContext | 接受前置校验上下文，必须覆盖输出合规、静态检查、质量结果版本、来源状态、来源事件影响、Action Policy、授权快照、作品资产 feature gate、`expectedRevision` 和幂等结果；系统在接受时实时校验，不封装为独立对象 |
@ -121,8 +122,8 @@ Accept 命令必须携带以下语义：
| 语义 | 原样接受 | 修改后合并 |
|---|---|---|
| blockOutcome | 目标 Block 写入成功，revision 递增 | 目标 Block 写入用户最终内容，revision 递增 |
| suggestionOutcome | Suggestion 离开 Active，进入 Archive，disposition=accepted | Suggestion 离开 Active，进入 Archive，disposition=accepted，并记录 modified merge 摘要 |
| blockOutcome | 目标 Block 写入成功，revision 递增 | 目标 Block 写入已重新检测通过的编辑版本正文，revision 递增 |
| suggestionOutcome | Suggestion 离开 Active，进入 Archive，disposition=accepted | 最终 candidateVersion 离开 Active，进入 Archive，disposition=accepted；旧版本保留 modified merge 版本链且不可接受 |
| knowledgeDraftOutcome | 关联草稿保持待确认，仍需单独进入知识确认入口 | 基于旧候选文本的草稿失效，不允许继续确认 |
| followupTask | 可触发投影刷新，不要求即时返回草稿数量 | AFTER_COMMIT 启动重新提取或投影刷新任务 |
@ -152,11 +153,25 @@ Accept 在任何写正文动作前必须完成前置校验。前置校验失败
服务端必须在接受时实时校验候选来源版本和授权状态；如果校验缺失、过期、质量结果版本不匹配、`expectedRevision` 不匹配、授权快照变化、来源状态变化、作品资产 feature gate 变化或幂等结果不可复用，必须在写正文前重算。重算结果不是提示文案，而是写 Canonical 的硬闸门。
### 6.1 candidateVersion、detector 与 `accept_preflight`
用户编辑候选时不得把 `contentOverride` 直接送进 Accept 主事务。编辑动作必须：
1. 基于当前候选生成严格递增的新 candidateVersion 和 candidateSha256，旧版本立即失去接受资格但保留审计。
2. 重新运行 detector；报告必须绑定新 candidateVersion、candidateSha256、contextSnapshotSha256 和 qualityPolicyVersion，旧报告不得复用。
3. detector 绿证据成立后才进入 `accept_preflight`；编辑内容未重新检测、检测超时、报告版本不符或仍有高严重度问题时失败关闭。
4. `accept_preflight` 实时校验 `mode=production`、`acceptanceEligible=true`、候选未过期、上下文快照和来源未失效、授权仍有效、detector 报告精确绑定当前候选、`expectedRevision` 一致及幂等结果可复用。
5. 诊断、评测和回放候选固定 `acceptanceEligible=false`，即使正文相同或 detector 通过也不能进入 Canonical。
接受写入采用 compare-and-set（CAS）：只有服务端当前记录仍匹配 `runId + attempt + candidateVersion + candidateSha256 + currentState + expectedRevision` 时，才允许原子完成正文 revision 递增和候选终态迁移。旧 attempt、旧 candidateVersion、迟到 detector 结果、重复状态事件或 revision 已变化时返回冲突或既有幂等结果，不能覆盖新版本或 Canonical。具体生命周期只在 [架构-04 §5](架构-04-状态机与约束清单.md) 定义，本节拥有接受命令的前置与原子写边界。
| 校验 | 失败结果 |
|---|---|
| actor 对作品、Block、Suggestion 有操作权限 | `PERMISSION_DENIED`，不写正文 |
| Suggestion 仍处于 Active / Shadow，未过期、未失效 | `SUGGESTION_NOT_ACCEPTABLE`，不写正文 |
| expectedRevision 匹配目标 Block 当前 revision | `REVISION_CONFLICT`，进入显式冲突处理 |
| mode=production 且 acceptanceEligible=true | `CANDIDATE_NOT_ACCEPTANCE_ELIGIBLE`，不写正文 |
| detector 绿报告精确绑定 candidateVersion、candidateSha256、contextSnapshotSha256 和策略版本 | `QUALITY_EVIDENCE_STALE` 或 `DETECTOR_NOT_PASSED`，不写正文 |
| 接受前置校验通过（实时校验来源版本和授权状态），且覆盖输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、expectedRevision 和幂等结果 | 按校验结果阻断、需重验或要求显式确认 |
| 输出合规、语义安全围栏和静态检查通过 | `OUTPUT_COMPLIANCE_BLOCKED` 或 `STATIC_CHECK_FAILED`，不写正文 |
| 候选正文 lineage 中所有来源有有效 Authorization Snapshot | `SOURCE_AUTH_INVALID`，候选 invalidated / blocked |
@ -173,8 +188,8 @@ Accept 在任何写正文动作前必须完成前置校验。前置校验失败
1. 加载 Active Suggestion 并校验归属、状态与过期时间。
2. 加载目标 Block，并用 `expectedRevision` 做并发保护。
3. 实时校验候选来源版本和授权状态（校验清单：候选来源、授权快照、市场作品资产 feature gate、质量门控、输出合规、静态检查、质量结果版本、幂等结果和当前 Block revision）。
4. 更新 Block 内容与 revision。
3. 执行 `accept_preflight`，实时校验接受资格、candidateVersion/hash、detector 绿报告、上下文快照、候选来源版本和授权状态（校验清单：候选来源、授权快照、市场作品资产 feature gate、质量门控、输出合规、静态检查、质量结果版本、幂等结果和当前 Block revision）。
4. 以 candidateVersion、candidateSha256、当前候选状态和 `expectedRevision` 做 CAS，更新 Block 内容与 revision。
5. 如果候选包含 AI、市场、外部知识或授权知识来源，写 Block Source Attribution。
6. 将 Suggestion 迁入候选归档(disposition=accepted)。
7. 保持关联知识草稿为待确认；仅当问题来源没有参与正文 lineage 时，才允许把草稿标记为不可确认或需重验。
@ -185,14 +200,14 @@ Accept 在任何写正文动作前必须完成前置校验。前置校验失败
### 7.2 修改后合并事务
单个事务内完成：
编辑动作先在事务外形成新的待审 candidateVersion 并重新运行 detector；只有 detector 绿且 `accept_preflight` 通过后，单个接受事务才完成：
1. 加载 Active Suggestion 并校验归属、状态与过期时间。
1. 加载最终 Active candidateVersion，并校验归属、状态、候选哈希、版本链与过期时间。
2. 加载目标 Block，并用 `expectedRevision` 做并发保护。
3. 实时校验候选来源版本和授权状态（校验清单：候选来源、授权快照、市场作品资产 feature gate、质量门控、输出合规、静态检查、质量结果版本、幂等结果和最终正文内容）。
4. 用 `contentOverride` 更新 Block 内容与 revision。
3. 执行 `accept_preflight`，确认 detector 绿报告精确绑定最终 candidateVersion/candidateSha256/contextSnapshotSha256，并实时校验来源版本和授权状态。
4. 以 candidateVersion、candidateSha256、当前候选状态和 `expectedRevision` 做 CAS，把该候选正文写入 Block 并递增 revision；不得接受临时 `contentOverride`。
5. 默认继承上游候选的 lineage、授权快照、许可限制、召回状态和风险标记，并写 Block Source Attribution。
6. 将 Suggestion 迁入候选归档(disposition=accepted)，必要时记录 `final_content`。
6. 将最终 candidateVersion 迁入候选归档(disposition=accepted)，保留完整编辑版本链与最终正文哈希。
7. 将旧知识草稿标记为失效，不允许继续确认。
8. 写 change log / audit log，标记这是 modified merge。
9. AFTER_COMMIT 发布重新提取事件或创建异步任务记录。
@ -277,10 +292,11 @@ Reject 不得更新 Block，不得创建重新提取链路。
1. 用户点击“修改”。
2. 调整最终入正文的结构化内容。
3. 点击“修改后合并”。
4. 服务端完成正文主事务，并让旧草稿失效。
5. UI 显示“已合并，旧知识草稿已失效，正在重新提取”。
6. 前端进入等待新草稿状态。
3. 系统创建递增的 candidateVersion 并重新运行 detector；检测中不能点击接受。
4. detector 绿后，用户点击“修改后合并”，服务端执行 `accept_preflight` 与 CAS。
5. 服务端完成正文主事务，并让旧版本知识草稿失效。
6. UI 显示“已合并，旧知识草稿已失效，正在重新提取”。
7. 前端进入等待新草稿状态。
### 9.3 Reject
@ -306,6 +322,9 @@ Reject 不得更新 Block，不得创建重新提取链路。
11. 候选使用市场作品资产时，必须经过作品资产使用预检和 feature gate；否则不能接受。
12. 修改后合并默认继承上游 lineage 和许可限制，不能用 `contentOverride` 洗白来源。
13. Accept / Merge 写 Canonical 前必须实时校验来源版本和授权状态，校验清单必须覆盖输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、expectedRevision 和幂等结果。
14. 用户编辑必须生成递增 candidateVersion 并重新运行 detector；未重新检测或 detector 非绿不得进入 `accept_preflight`。
15. 只有 `mode=production`、`acceptanceEligible=true` 且候选/上下文/检测/策略版本一致时才能接受；诊断和评测候选永不可接受。
16. Accept / Merge 必须以 candidateVersion、candidateSha256、当前状态和 `expectedRevision` 做 CAS，旧版本和迟到结果不得覆盖 Canonical。
### Should-Have（P1）
@ -339,6 +358,9 @@ Reject 不得更新 Block，不得创建重新提取链路。
- 市场作品资产缺 feature gate / owner 预检 / `workAssetUsePrecheckId` 时阻断接受
- 修改后合并触发旧草稿失效
- 修改后合并不能清空上游 lineage、授权快照和许可限制
- 编辑后 candidateVersion 递增并重新 detector；旧检测报告和旧候选不可接受
- `acceptanceEligible=false`、detector 非绿、上下文哈希漂移或策略版本漂移时 `accept_preflight` 失败
- CAS 冲突、迟到 detector 和重复命令不能覆盖新 candidateVersion 或正文 revision
- Reject 零正文副作用
- 409 冲突返回必要信息
- 投影失败不阻塞主事务

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

@ -1,10 +1,10 @@
# 专题-03：AI 编排、上下文与质量评测实现规范
- 版本：v3
- 更新日期：2026-07-17
- 版本：v4
- 更新日期：2026-07-20
- 目标读者：产品 / 架构 / 后端 / 前端 / 测试
- 阅读时间：30-45 分钟
- 变更记录：v3（2026-07-17）§4.2 登记「分区内该选哪几条知识」的选择契约归属 [专题-07-知识消费契约与质量闭环](专题-07-知识消费契约与质量闭环.md)；关联阅读补专题-07。
- 变更记录：v4（2026-07-20）§4.5 固化正文实验的 `WriterContext v1`、`WriterOutput v1`、`RetrievalManifest`、双证据与冻结语义；明确实验阶段不改产品 API/DB。v3（2026-07-17）§4.2 登记「分区内该选哪几条知识」的选择契约归属 [专题-07-知识消费契约与质量闭环](专题-07-知识消费契约与质量闭环.md)；关联阅读补专题-07。
- 边界说明：本文件承接阶段 1~5，定义 AI 编排、上下文组装、检索、运行权限、来源追踪、风险路由和质量评测的产品架构合同。它不定义精确数据库表、后端 endpoint、前端组件和运维门禁；这些由后续前端/后端阶段承接。
## 1. 归属范围
@ -216,6 +216,51 @@ AI 结果必须能解释：
- 是否触发质量门控、重写、风险标记或输出阻断。
- 下一步用户可以接受、修改、丢弃、重生成或进入知识确认。
### 4.5 正文 WriterContext、输出与冻结合同
本节是正文生成上下文和输出结构的唯一 owner。知识侧为什么必须“卡是索引、按来源回读原文”由 [专题-07 §2.1](专题-07-知识消费契约与质量闭环.md) 定义；本节只定义检索结果如何冻结、组装和交给写手。
#### 4.5.1 `WriterContext v1`
`WriterContext v1` 是写手唯一可见输入，采用严格 schema：缺字段、未知字段、错误版本、无效引用或哈希不一致均失败关闭。最小合同如下。
| 字段组 | 必须包含 | 约束 |
|---|---|---|
| 身份与用途 | `schemaVersion=writer-context-v1`、runId、attempt、mode、qualityPolicyVersion | mode 仅为 `production` / `diagnostic_only`；运行标识不参与内容身份哈希 |
| 作品与冻结点 | workId、targetChapter、asOf、sourceVersion、authorizationSnapshot、sourceStatus | 回放必须 `asOf < targetChapter`；来源非允许状态即失败关闭 |
| 快照与检索 | contextSnapshot、retrievalPlan、`RetrievalManifest` | 引用、版本、过滤、排序、哈希和裁剪原因必须完整且互相一致 |
| 创作骨架 | 已确认大纲定位、fineOutline、narrativeState | 细纲明确区分硬事件、结果方向、伏笔动作、章末钩子、必须出场实体和可调整节拍 |
| 双证据 | `factEvidence[]`、`proseEvidence[]`、evidenceCoverage[] | 事实与写法证据不得混装；每项都必须回到不可变来源引用 |
| 输出控制 | outputContract、tokenBudget、omittedSources | 包含动态篇幅、结构要求、新设定申报规则和所有省略原因 |
| 接受隔离 | `acceptanceEligible` | `diagnostic_only`、evaluation 或回放上下文固定为 false；不得被写手输出覆盖 |
`factEvidence[]` 负责“写得对”，每项保存 factId、sourceType、不可变 sourceRef、内容哈希和 coverageState；来源准入、抽取卡回读要求及正式设定/Canonical 状态/细纲新事实的独立权威分类只以 [专题-07 §2.1](专题-07-知识消费契约与质量闭环.md) 为准。无可靠来源的提示不得进入该字段。
`proseEvidence[]` 负责“写得像”，只包含可回读的历史原文，记录 sourceVersion、章号、Block、Unicode code point 左闭右开区间、内容哈希和用途。连续前四章全文是正文实验 v1 的基础文风证据；抽取卡命中的来源原文只作补充，并按不可变来源去重、稳定排序。事实来源与原文证据不能互相冒充。
#### 4.5.2 `RetrievalManifest`
`RetrievalManifest` 是一次确定性检索结果的冻结清单，至少记录 `planId`、查询、授权和作品过滤、排序规则、卡索引版本、原文读取版本、sourceVersion/sourceRefs、stateAsOf、章号、Block 与字符区间、内容哈希、排除项和裁剪原因。抽取卡排序固定为 `score DESC, sourceVersion ASC, sourceId ASC, sourceOffset ASC`；同一检索计划、授权快照、冻结点和索引版本必须得到同一来源集合与 manifest identity。
manifest identity 对规范化后的来源集合计算，使用 UTF-8、Unicode NFC、LF、对象键排序和稳定数组合同；runId、时间戳、执行节点不参与身份。检索与原文读取必须在同一只读冻结快照内完成；任一来源越过冻结点、缺版本、缺授权、缺哈希或无法重现时，整次上下文组装失败关闭。
冻结边界按用途统一解释：
1. 回放只读取 `chapter <= asOf` 的 Canonical 正文、状态里程碑和抽取卡来源；目标章、未来章、全书终态摘要和无法证明绝对章号的演变事实一律拒绝。
2. 正向创作以当前最新 Canonical 章为 `asOf`；正式设定、Canonical 状态和已确认细纲分别读取各自不可变版本。
3. A/B/C 诊断臂可以改变证据策略，但共享作品、冻结点、大纲、细纲、篇幅算法、模型和检测规则，且全部 `acceptanceEligible=false`。
4. 评测产物只用于诊断和 Gate 裁决，不能反写 Canonical、知识卡、正式设定、Narrative State 或细纲。
#### 4.5.3 `WriterOutput v1`
`WriterOutput v1` 采用严格 schema，至少包含 `schemaVersion=writer-output-v1`、runId、attempt、mode、qualityPolicyVersion、contextSnapshotId/contextSnapshotSha256、candidateVersion、candidateBody/candidateSha256、`acceptanceEligible`、claimLedger[]、evidenceRequests[]、newSettingDeclarations[] 和 selfCheck。
候选正文先统一为 UTF-8、Unicode NFC 和 LF，再计算 SHA-256 与 Unicode code point 区间。claimLedger 每项必须绑定候选哈希、事实类型、正文区间和对应 factEvidence；证据请求和新设定申报不得静默改写上下文。`acceptanceEligible` 由可信组装层派生，写手无权把 false 改为 true；接受链的 candidateVersion、detector 与 CAS 前置条件只由 [专题-01 §6](专题-01-正文建议接受(Accept%20Suggestion)实现规范.md) 定义。
#### 4.5.4 实验落地边界
当前只在正文实验台验证以上合同，不修改产品 API 契约、Flyway、正式业务数据库或 Canonical 主链。只有正文 Gate B 由 [专题-04 §10.1](专题-04-生成质量门控与创作健康度设计方案.md) 的唯一判定顺序裁决为 `passed` 后，才另立产品化计划更新 `docs/api-contracts/*`、数据库迁移和正式实现；Gate B 通过前不得启动细纲智能体真实能力验收。
## 5. 检索和图查询
### 5.1 RAG 定位

41
design-docs/专题-04-生成质量门控与创作健康度设计方案.md
View File

@ -1,10 +1,10 @@
# 专题-04：生成质量门控与创作健康度设计方案
- 版本：v2
- 更新日期：2026-07-17
- 版本：v3
- 更新日期：2026-07-20
- 目标读者：产品 / 架构 / 前端 / 后端 / 测试
- 阅读时间：25-40 分钟
- 变更记录：v2（2026-07-17）§10 离线评估输入补「知识策略版本」、允许样本增补第 5 类参考作品回放样本（两道闸校验，机制归 [专题-07-知识消费契约与质量闭环](专题-07-知识消费契约与质量闭环.md)）；关联阅读补专题-07；物理文件名补 `.md` 扩展名。
- 变更记录：v3（2026-07-20）§10.1 新增正文五维量表、双盲稳定性与第三评委仲裁，并固化 Gate A/B 唯一判定顺序。v2（2026-07-17）§10 离线评估输入补「知识策略版本」、允许样本增补第 5 类参考作品回放样本（两道闸校验，机制归 [专题-07-知识消费契约与质量闭环](专题-07-知识消费契约与质量闭环.md)）；关联阅读补专题-07；物理文件名补 `.md` 扩展名。
- 边界说明：本文件承接阶段 1~5，定义质量门控(Quality Gate)、创作健康度(Writing Health)、质量策略、有限重写、质量结果展示和质量观测的产品架构合同。AI 编排、上下文组装和运行时权限见 `专题-03`；精确 Schema、API 和前端组件由后续阶段承接。
## 1. 定位
@ -299,6 +299,41 @@ active -> superseded / rolled_back
评估结果只能用于管理员判断策略、智能体或 Prompt 是否上线，不直接修改用户作品。
### 10.1 正文实验五维量表、盲评与 Gate A/B
正文回放使用独立的 `writer` 评测 profile，不覆盖细纲、知识或其他既有评测量表。每个维度按 0-10 分、0.5 分步长评分，并逐项标注证据来自已确认细纲、冻结历史原文、卡索引还是评委自行推断。
| 维度 | 评判问题 |
|---|---|
| 设定与实体保真 | 人物、关系、物品、地点、力量规则、知情范围和即时状态是否与冻结事实一致 |
| 细纲与情节忠实 | 细纲硬事件、结果方向、伏笔动作、必须出场实体和章末钩子是否全部兑现，且未被反转或提前回收 |
| 文风一致性 | 叙述声音、角色语言、动作习惯、段落节奏是否与冻结原文证据一致 |
| 叙事张力 | 场景推进、因果、冲突升级、情绪连续和章末牵引是否成立 |
| 文笔与可读性 | 文字是否准确、流畅、具体，是否存在空泛解释、机械重复或明显阅读阻力 |
每个样本先由两个独立、无会话的评委双盲评分；候选臂名随机化，第二评委反转展示顺序。任一维两次评分差异 `>0.5` 时，只增加一次第三评委。第三评委后，若三份评分中至少一对差值 `<=0.5`，该维最终分取三者中位数；若不存在稳定配对，整个样本标记为 `invalid_unstable`，不得强行给出输赢或方向结论。去盲、稳定性判断和聚合必须机械执行，人工只能复核证据归因，不能手改终态。
正文实验只允许下列 Gate 顺序，命中前项即停止，后项不得覆盖前项：
**Gate A（链路可运行）**
1. 有效样本 `<5`：`insufficient_evidence`。
2. 否则只要存在 schema 非法、未来泄漏、系统失败、C 臂 detector 高严重度残留，或细纲硬约束覆盖率 `<100%`：`failed`。
3. 其余：`passed`。
Gate A 只证明链路可运行，不代表正文层通过。
**Gate B（正文层正式裁决）**
1. Gate A=`insufficient_evidence`：`insufficient_evidence`。
2. Gate A=`failed`：`failed`。
3. 否则若作品 `<2`、任一作品有效样本 `<5`、总有效样本 `<10`、五类场景未覆盖，或 `invalid_unstable` 占比 `>20%`：`insufficient_evidence`。
4. 再判断 C 臂硬约束覆盖率 `<100%`、存在 detector 高严重度残留、C-A 的文风一致性或叙事张力平均增量 `<-0.25`，或任一维下降 `>0.5` 的样本占比 `>20%`；命中任一项：`failed`。
5. 再判断 C-A 的设定与实体保真平均增量 `>=0.25` 且正向样本比例 `>=60%`；同时满足：`passed`。
6. 其余：`no_gain`。
报告必须列出假阴、假阳、未来泄漏、评委不稳定、新角色无卡和场景选择偏差等混淆项。单章、单作品或只选卡友好场景不得得出普适结论。只有 Gate B=`passed` 才能声称正文层通过并启动细纲智能体真实能力验收；其他终态继续修正文层或补充预注册的合法样本。A/B/C 的冻结与接受隔离合同只引用 [专题-03 §4.5](专题-03-AI编排上下文与质量评测实现规范.md)，本节不重复定义。
## 11. 线上质量观测
线上质量观测用于发现策略、智能体、上下文组装和质量门控的真实效果，不用于监控单个作者的创作水平。

18
design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md
View File

@ -1,9 +1,10 @@
# 专题-05：AI 统一交互协议与外部 Agent Adapter 设计
- 版本：v0.1
- 更新日期：2026-06-29
- 版本：v0.2
- 更新日期：2026-07-20
- 目标读者：架构 / 后端 / 前端 / 运维 / 测试
- 边界说明：本文定义 Muse 后端到外部 Agent 运行时的统一交互协议与 adapter 层。它承接 `专题-03-AI编排上下文与质量评测实现规范.md`，不改变 Shadow -> Canonical、Runtime Permission Envelope、RAGFlow 检索和用户确认边界。
- 变更记录：v0.2（2026-07-20）§5.4 固化正文写手 adapter 的无工具、无会话持久化和超时失败关闭边界；v0.1（2026-06-29）建立外部 Agent 统一协议与 provider adapter 设计。
## 1. 背景与结论
@ -215,6 +216,19 @@ AgentScope adapter 以后按同一协议接入：
- 请求和响应仍走 `MuseAgentRuntimeRequest/Response`
- AgentScope 内部工具和知识权限即使受限，Muse 仍按外部 runtime 处理，不授予直接写入权。
### 5.4 正文写手 adapter 隔离边界
正文写手 adapter 是开放能力节点，但采用比通用 provider 更窄的执行边界：
1. **无工具**：写手进程的工具集合必须为空，不得读取文件、搜索、访问数据库、调用网络工具或自行扩大检索范围。检索、授权、冻结与组装全部在可信的 Muse 层完成。
2. **无会话持久化**：每次 attempt 使用独立无状态进程，禁止恢复、续接或保存 provider 会话；旧 attempt 的隐式记忆不得进入新候选。
3. **单一输入**：adapter 只接收 [专题-03 §4.5](专题-03-AI编排上下文与质量评测实现规范.md) 定义的冻结 `WriterContext v1`，不得旁路追加未登记正文、卡片、Prompt 记忆或未来信息。
4. **严格输出**：只接受 `WriterOutput v1`；非 JSON、未知字段、缺字段、候选哈希或上下文哈希不匹配均视为协议失败，不生成可接受候选。
5. **超时失败关闭**：adapter 必须设置单次 deadline。超时、取消、非零退出、provider bad response 或进程失联时，当前 attempt 进入失败终态，取消下游 detector/judge，丢弃迟到结果，且不得回退到有工具写手、旧会话或其他 provider 伪装成功。
6. **接受资格不可伪造**：`acceptanceEligible` 由可信上下文层派生；诊断/评测运行及任何 adapter 失败结果固定不可接受。provider 返回 true 不能覆盖可信层的 false。
该边界先在实验台验证，不新增或修改产品 API、数据库字段和正式 runtime 状态；产品化必须等待正文 Gate B 通过后另立计划。本节只拥有 adapter 隔离语义，Writer 合同和接受链分别由专题-03、专题-01 定义。
## 6. 系统 Agent 配置体验
管理端系统 Agent 配置页新增“外部运行时”区域：

20
design-docs/专题-06-元数据驱动的智能体架构.md
View File

@ -1,10 +1,10 @@
# 专题-06：元数据驱动的智能体架构
- 版本：v4
- 更新日期：2026-07-17
- 版本：v5
- 更新日期：2026-07-20
- 目标读者：架构 / 后端 / 前端 / 产品
- 边界说明：本册是「元数据驱动的智能体架构」这条横切主线的单一 owner，收束四件此前散落无主的事——元引擎与功能链如何共同驱动智能体、拆书作为通用抽取智能体的两处用场、target type 结构本体的全清单与分层判据、统一创作数据读取器与 base 内置机制。术语与双轨不变式的权威在 [架构-02-核心数据结构与双轨模型](架构-02-核心数据结构与双轨模型.md)（MetaSchema、Canonical/Shadow、domain/scope）；AI 链路合同与 Context Assembly 在 [专题-03-AI编排上下文与质量评测实现规范](专题-03-AI编排上下文与质量评测实现规范.md)；外部 Agent 协议在 [专题-05-AI统一交互协议与外部AgentAdapter设计](专题-05-AI统一交互协议与外部AgentAdapter设计.md)；表结构与字段合同在 [后端-04-统一数据库Schema-v1](后端-04-统一数据库Schema-v1.md)。上述对象本册只链接、不重复定义。
- 变更记录：v4（2026-07-17）拆书实验台证据回填——§4.5 拍板双层型开放问题（`craft` 公共面实测无损写入同一字段合同，单模具双库成立，不拆）并登记世界域实体型共享「演变历程」元素；§6 新增 6.4 参照作品面（参考书实体演变卡 = 系统侧证据资产，蒸馏为叙事域成长曲线范式后才入 Global KB）；知识消费选择契约与质量闭环整体归新册 [专题-07-知识消费契约与质量闭环](专题-07-知识消费契约与质量闭环.md)，本册补链接；§7 读取器 purpose 枚举 `parse` 统一为 `extraction`、字段级裁剪随 `aiContext` 值域升级（布尔或用途集，权威在 [架构-02 §9](架构-02-核心数据结构与双轨模型.md)）对齐表述。v3（2026-07-09）结构本体补全 scope 轴空格位——新增 `chapter`（章节容器）、`scene`（场景卡）、`narrative_state`（叙事状态模具）三型，清单 20→23、scope 七值全挂靠，种子四档同步 23 项；钉死读取器只依赖 owner api 模块具名端口（服务即 API）与 storage_binding 的权力边界（映射非数据通道）。v2（2026-07-09）新增 §2.1 检索基座的替换合同与演进方向（引擎缝 + 引擎中立合同，预期纯 Java 自研：PG 向量插件 + New-API 嵌入/重排，切块收回保护节点）。v1（2026-07-09）定稿自 2026-07-08 架构评审，将「agent = f(作品 + 元数据 + 知识库)」主线、三体关系、20 型结构本体、统一读取器与 base 机制蒸馏为 canonical。
- 变更记录：v5（2026-07-20）§7.1 登记 `generation_context` 的 generation purpose 严格 schema 投影、卡索引视图和事实/原文双证据字段，具体合同仍由专题-03/07 owner 定义。v4（2026-07-17）拆书实验台证据回填——§4.5 拍板双层型开放问题（`craft` 公共面实测无损写入同一字段合同，单模具双库成立，不拆）并登记世界域实体型共享「演变历程」元素；§6 新增 6.4 参照作品面（参考书实体演变卡 = 系统侧证据资产，蒸馏为叙事域成长曲线范式后才入 Global KB）；知识消费选择契约与质量闭环整体归新册 [专题-07-知识消费契约与质量闭环](专题-07-知识消费契约与质量闭环.md)，本册补链接；§7 读取器 purpose 枚举 `parse` 统一为 `extraction`、字段级裁剪随 `aiContext` 值域升级（布尔或用途集，权威在 [架构-02 §9](架构-02-核心数据结构与双轨模型.md)）对齐表述。v3（2026-07-09）结构本体补全 scope 轴空格位——新增 `chapter`（章节容器）、`scene`（场景卡）、`narrative_state`（叙事状态模具）三型，清单 20→23、scope 七值全挂靠，种子四档同步 23 项；钉死读取器只依赖 owner api 模块具名端口（服务即 API）与 storage_binding 的权力边界（映射非数据通道）。v2（2026-07-09）新增 §2.1 检索基座的替换合同与演进方向（引擎缝 + 引擎中立合同，预期纯 Java 自研：PG 向量插件 + New-API 嵌入/重排，切块收回保护节点）。v1（2026-07-09）定稿自 2026-07-08 架构评审，将「agent = f(作品 + 元数据 + 知识库)」主线、三体关系、20 型结构本体、统一读取器与 base 机制蒸馏为 canonical。
---
@ -291,6 +291,20 @@ scope 落座有两处最易被误判，须点明。`outline` 取 `work` 而非 c
裁剪分三级、同时生效：**字段级**（`aiContext` 不含本次 purpose 的字段剔除——`false` 即任何用途不入、`true` 即全用途可入，值域权威见 [架构-02 §9](架构-02-核心数据结构与双轨模型.md)）、**来源级**（状态受限的来源整块不进）、**用途级**（来源授权 `allowedPurpose` 不含本次 purpose 的剔除）。任一级判定剔除，数据即不进上下文。受限来源整块进 `omittedSources`，失败关闭并留痕可审计。
### 7.1 `generation_context` 的正文生成登记
`generation_context`（domain=`ai_context`、scope=`agent`）在正文实验中启用 generation purpose 的严格 schema 投影。这里仅登记 MetaSchema 结构入口，不复制邻册合同：
| 登记项 | MetaSchema 约束 | 唯一 owner |
|---|---|---|
| purpose | 固定枚举值 `generation`；不接受别名、空值或未知值 | purpose 值域与字段级 `aiContext` 语义仍见 [架构-02 §9](架构-02-核心数据结构与双轨模型.md) |
| schema / output 版本 | 必填、精确匹配；缺字段与未知字段失败关闭 | `WriterContext v1` / `WriterOutput v1` 见 [专题-03 §4.5](专题-03-AI编排上下文与质量评测实现规范.md) |
| cardIndexView | 只登记抽取卡的索引视图与来源引用，不承载原文正文 | “卡是索引、根据来源回读原文”见 [专题-07 §2.1](专题-07-知识消费契约与质量闭环.md) |
| factEvidence / proseEvidence | 两个独立字段组，禁止互相冒充或合并成通用 evidence | 双证据字段、哈希和冻结规则见 [专题-03 §4.5](专题-03-AI编排上下文与质量评测实现规范.md) |
| 正式事实来源 | 正式设定、Canonical 状态和细纲新事实保留各自不可变版本引用，不强造抽取卡或历史原文来源 | 权威来源分类见 [专题-07 §2.1](专题-07-知识消费契约与质量闭环.md) |
该登记先约束实验台 schema 和上下文投影，不代表产品 API、数据库结构或正式 MetaSchema 种子已经变更；产品化必须等正文 Gate B 通过后另立契约与迁移计划。
---
## 8. 关联阅读

19
design-docs/专题-07-知识消费契约与质量闭环.md
View File

@ -1,9 +1,10 @@
# 专题-07：知识消费契约与质量闭环
- 版本：v1
- 更新日期：2026-07-17
- 版本：v2
- 更新日期：2026-07-20
- 目标读者：产品 / 架构 / 后端 / 测试
- 边界说明：本册是「知识效用」这条横切主线的单一 owner——回答「该读什么知识、注入后有没有用、知识本身好不好」，收束四件此前无主的事：知识消费选择契约（含按用途默认合同与注入视图）、知识质量三性、回放评测、长线进度消费语义；文末附实验台实证附录。以下邻册对象本册只链接、不重复定义：Context Assembly 分层与 Token 预算见 [专题-03 §4](专题-03-AI编排上下文与质量评测实现规范.md)、检索结果合同见 [专题-03 §5.3](专题-03-AI编排上下文与质量评测实现规范.md)、统一创作数据读取器读合同见 [专题-06 §7](专题-06-元数据驱动的智能体架构.md)、输出侧质量维度见 [专题-04](专题-04-生成质量门控与创作健康度设计方案.md)、结构本体与字段合同见 [专题-06 §4](专题-06-元数据驱动的智能体架构.md) 与 [后端-04](后端-04-统一数据库Schema-v1.md)、Narrative State 与双轨见 [架构-02](架构-02-核心数据结构与双轨模型.md)。核心主张一句话：**知识的价值只在被选中并改善产出——写作、检测、规划三个效用时刻——的那一刻兑现；质量标准必须由消费端定义、由回放评测测量——以用定卡。**
- 变更记录：v2（2026-07-20）在 §2.1 固化正文消费的「卡是索引、按来源回读冻结原文」契约，并区分抽取卡证据与正式设定、Canonical 状态、细纲新事实三类独立权威来源。v1（2026-07-17）建立知识消费选择、质量三性、回放评测和长线进度消费语义。
---
@ -99,6 +100,20 @@ flowchart LR
**卡粒度预算**：进入上下文的是**注入视图，不是整条存储记录**。注入视图分两档——摘要视图（名称 + 一句话摘要 + 当前态要点）是默认档，焦点实体升全文视图（按 `aiContext` 裁剪后的字段全量）。排序信号 = 结构匹配度（在场 > 关系一跳 > 相似兜底；范式取型 × 场景意图 × 品类的精确匹配优先）+ 效用统计（被命中率 / 被接受率 / 跨书频次）；预算内截断落 omittedSources（截断规则归 [专题-03 §4.2](专题-03-AI编排上下文与质量评测实现规范.md)）。实验台实证两端病并存——p50 卡体仅 395 字符（薄到无肉可注）与单卡 104KB（角色卡流水累积，一张即撑爆预算）——这证明注入视图必须是一份独立合同，不能等于存储形态。
### 2.1 正文消费的卡索引与原文回读契约
正文生成再加一条不可绕过的消费规则：**卡是索引，根据抽取卡记录的来源回读原文；卡不能替代原文。** 卡负责缩小检索范围、指出相关实体与历史状态，冻结线内的历史原文负责证明人物声音、动作习惯、能力表现和叙事质感。读取器不得把卡片正文直接倾倒给写手，或把抽取摘要伪装成历史原文证据。
| 来源类型 | 进入正文上下文的条件 | 证据落点 |
|---|---|---|
| 由历史正文抽取的卡 | 必须携带 `sourceVersion`、`sourceRefs` 和按冻结点重建的 `stateAsOf`；系统沿 `sourceRefs` 回读 `chapter <= asOf` 的原文，并记录章节、Block、字符区间与内容哈希 | 卡只保留索引视图；事实约束与写法参考分别进入 [专题-03 §4.5](专题-03-AI编排上下文与质量评测实现规范.md) 的双证据字段 |
| 无可追踪原文来源的抽取卡 | 只能作为 `unverifiedIndexHint` 暴露缺口，不得单独支撑正文硬事实 | 进入省略/缺口清单，不进入可采信事实证据 |
| 作者确认的正式设定 | 直接引用其不可变正式版本，不要求伪造历史原文来源 | 独立权威事实证据 |
| Canonical 状态 | 直接引用当前冻结点可见的正式状态版本，不要求抽取卡二次背书 | 独立权威事实证据 |
| 细纲声明的本章新事实 | 以已确认细纲版本为权威，标记 `declared_new`；它不是历史事实，不得强造原文来源 | 独立权威事实证据与新设定申报 |
卡片与其来源是否落在冻结线内，只按 [专题-03 §4.5](专题-03-AI编排上下文与质量评测实现规范.md) 的 `RetrievalManifest` 和冻结规则判断；本册只拥有“选卡后必须回读什么”以及哪些正式事实不依赖抽取卡的消费规则。
---
## 3. 知识质量三性（输入侧质量维度）

19
design-docs/架构-04-状态机与约束清单.md
View File

@ -1,10 +1,11 @@
# 架构-04：状态机与约束清单
- 版本：v6
- 更新日期：2026-05-24
- 版本：v7
- 更新日期：2026-07-20
- 目标读者：架构 / 后端 / 前端 / 测试 / 产品
- 阅读时间：45-60 分钟
- 边界说明：本文件是 Muse 生命周期、状态流转和不可绕过约束的架构层单一来源；状态值是概念层合同，具体字段名、表结构和接口路径由后端阶段承接。系统边界见 `架构-01-系统全貌与边界上下文.md`，核心模型见 `架构-02-核心数据结构与双轨模型.md`。
- 变更记录：v7（2026-07-20）§5.2.1 登记正文实验候选与生产候选隔离、编辑版本重检、detector 绿证据、`accept_preflight` 和 CAS 状态约束；实验阶段不改 API/DB。v6（2026-05-24）收束 Muse 生命周期、来源传播和不可绕过约束。
## 1. 状态机总原则
@ -248,6 +249,20 @@ running -> failed / canceled
- 修改后合并必须让旧知识草稿失效，并基于最终正文重新提取。
- 候选来源撤权、下架、召回、owner 缺失、文本 revision 冲突或合规阻断时，接受和合并禁用。
### 5.2.1 正文候选的实验隔离与接受子状态
正文实验候选和生产候选共享检测规则，但不共享接受资格。
| 对象 | 允许流转 | 不可绕过约束 |
|---|---|---|
| 诊断/评测正文候选 | `draft -> checking -> passed / rejected / failed / invalid_unstable` | `acceptanceEligible=false` 为不变量；passed 只表示本次检测或评测完成，候选永远不能进入 `accept_preflight` 或 Canonical |
| 生产正文候选版本 | `draft -> checking -> shadow_ready -> accept_preflight -> accepted_as_is / merged_after_edit / revision_conflict / authorization_stale / source_stale / quality_stale` | 只有 detector 绿且报告绑定当前 candidateVersion、candidateSha256、contextSnapshotSha256 和 qualityPolicyVersion，才能进入 shadow_ready |
| 用户编辑版本 | `shadow_ready -> edited_candidate -> checking` | 编辑必须创建严格递增的新 candidateVersion；旧版本和旧 detector 报告立即失去接受资格，不允许“改完直接合并” |
`accept_preflight` 只允许 `mode=production`、`acceptanceEligible=true` 的当前版本进入，并实时校验候选未过期、detector 绿证据、上下文快照、授权、来源状态、策略版本和 `expectedRevision`。写入 Canonical 必须采用 compare-and-set（CAS）：服务端记录同时匹配 `runId + attempt + candidateVersion + candidateSha256 + currentState + expectedRevision` 才能原子递增 Block revision，并按用户决策迁入 `accepted_as_is` 或 `merged_after_edit` 后归档。旧 attempt、旧 candidateVersion、迟到结果和重复事件只能返回冲突或幂等旧结果，不能覆盖当前候选或正文。
实验台只验证上述状态合同，不写正式正文库，不修改产品 API、Flyway 或业务数据库结构。产品化必须在正文 Gate B 通过后另立计划；Gate B 通过前不得启动细纲智能体真实能力验收。接受命令的具体前置与事务边界只引用 [专题-01 §6](专题-01-正文建议接受(Accept%20Suggestion)实现规范.md)，本文件不重复定义。
### 5.3 规划候选生命周期
| 状态 | 含义 | 允许离开方式 |