muse-agent-example/docs/2026-07-20-正文智能体正式优化设计与计划.md

正文智能体正式优化设计与计划

状态：评审修订版
日期：2026-07-20
定位：本文是实验台“正文智能体正式优化”的任务 SoT；稳定概念仍以父仓 design-docs/ 为准。评审通过后必须回填架构-04、专题-01/03/04/05/06/07、相关 API 契约、schema 和索引，本文完成蒸馏后删除。
历史：2026-07-16-批9c-收官与优化方案.md 的 run1-run3 只作实验记录。
可视化：正文智能体架构图

1. 意图与双流程

核心原则：卡是索引，根据卡去读原文。 卡负责定位实体、状态、规则和历史章节；原文负责人物声音、动作习惯、能力表现和叙事质感。卡不能替代原文，原文也不能替代正式设定与状态。

这里必须区分两个顺序：

• 能力验证顺序：正文智能体 -> 细纲智能体 -> 大纲+设定智能体，自底向上隔离变量。
• 正式创作数据流：大纲+设定 -> 细纲 -> 正文，自顶向下提供输入。

本任务只优化正文层。细纲与大纲+设定的真实能力验收，必须等正文层通过跨作品多样本门禁后再启动。

2. 目标与边界

2.1 目标

1. 卡检索必须带出历史来源指针，并触发原文回读。
2. 已有事实、人物声音和叙事质感分别有可追溯证据，不再靠 writer 自由猜测。
3. writer 保留真实创作空间，但不得改变细纲硬事件、结果方向和伏笔动作。
4. 生产链在交付候选前挡住可机械验证的硬错误；文学质量由独立 judge 评估，不由 detector 凭观感阻断。
5. 生成候选能进入“接受/修改后合并/丢弃”三决策，采纳后成为 Canonical 正文并触发章后抽取。
6. 多章节、多作品、多场景验证，报告假阴、假阳和无卡实体影响。

2.2 可信边界

• writer 运行在无工具、无会话持久化的隔离进程，只接收序列化 WriterContext，不能使用 Read/Grep/Glob、数据库或搜索工具。
• 检索节点是唯一取数入口，负责授权、冻结、排序、预算、哈希和来源回显。
• 回放时卡与原文都只能使用 chapter <= as_of 的事实；目标章、未来章和标准答案不得进入 writer 进程。
• 卡的终态摘要、未来弧线和无法证明章号的字段不进入回放 stateAsOf。
• 长原文片段只存在于本次临时上下文，不进入 git、长期报告、知识卡或评测摘要。

2.3 不做

• 不由正文智能体生成或修改大纲、细纲、设定和知识卡。
• 不把双盲 judge 设为每次续写的固定在线成本；它属于离线评测或可选质量详情。
• 不在正文层自动补齐关键新角色卡；只输出设定层缺口。
• 不允许诊断实验 A/B 臂的候选进入 Canonical 接受链路。

3. 两条独立链路

3.1 生产链

flowchart LR
    F[已确认细纲] --> RP[检索规划]
    RP --> CI[卡索引与 stateAsOf]
    CI --> PR[按来源指针回读原文]
    PR --> EG[证据包与覆盖门]
    EG --> W[无工具 writer]
    W -->|补证请求且预算可用| RP
    W --> D[detector 硬门]
    D -->|阻塞且返修未满2轮| W
    D -->|通过| S[Shadow 候选展示]
    D -->|满2轮仍阻塞| H[停止并交用户]
    S --> U{用户三决策}
    U -->|原样接受| AP[接受前置校验]
    U -->|修改后合并| M[编辑并生成 candidateVersion+1]
    M --> D
    AP --> C[confirm -> Canonical 正文]
    U -->|丢弃| X[关闭候选]
    C --> E[异步章后抽取]
    E --> K[知识草稿与冲突队列]

生产链不强制运行双盲 judge。用户可请求质量详情，或系统按抽样策略运行单次 judge，但 detector 硬门与用户三决策始终存在。

3.2 离线评测链

flowchart LR
    P[预注册样本/冻结点] --> A[原文线 A]
    P --> B[卡线 B]
    P --> C[双线 C]
    A --> D[统一 detector]
    B --> D
    C --> D
    D --> J1[盲评委 1]
    D --> J2[盲评委 2/反序]
    J1 --> ST[稳定性门]
    J2 --> ST
    ST -->|不稳定| J3[最多一次第三评委]
    ST --> R[去盲汇总与归因]
    J3 --> R

A/B 使用 diagnostic_only 策略：可以绕过“卡与原文必须同时存在”的生产充分性门，但仍必须通过授权、冻结、未来泄漏和候选结构门，且候选永不进入接受链路。C 使用生产策略。

4. 细纲、创作自由与硬约束

细纲不是分镜脚本，需拆为两类：

类型	writer 权限
硬事件、结果方向、伏笔动作、章末钩子、必须出场实体	不得删除、反转或提前回收
场景切分、局部顺序、过渡方式、环境质感、动作和对白细节	可合并、拆分或局部调序

writer 可以创造非 Canonical 的环境细节、动作、过渡、无名配角和对白表达。新增地名、能力、组织、人物身份、代际、战绩或关系等 Canonical 事实，必须进入“新设定申报”，不得直接写成已确认事实。

补证请求不是固定一次，而是受总预算控制：最多 3 次请求、累计新增上下文不超过本次检索预算的 30%；任一上限达到后停止补证并报告缺口。

5. 两阶段检索

5.1 检索规划

查询来自细纲硬约束与可调整节拍，包括人物、关系、地点、物品、能力、力量规则、历史回调、伏笔、语言指纹和同类历史场景。

RetrievalPlan 必须固定。runId 是运行元数据，不参与计划身份；planId 使用下表除 runId 外字段的规范 JSON 计算 SHA-256：UTF-8、NFC、LF 换行、对象键排序、数组保持合同顺序、无额外空白。

字段	含义
planVersion/runId/asOf	合同版本、运行 ID、冻结点；runId 不进入 planId
queries[]	queryId、查询文本、实体类型、检索目的、topK
cardIndexVersion	卡索引和嵌入模型版本
proseIndexVersion	原文索引/读取器版本
filters	作品、授权、章号上限、来源状态
tieBreak	score DESC, sourceVersion ASC, sourceId ASC, offset ASC
tokenBudget	卡、连续原文、历史证据、范式各自预算

5.2 卡索引与冻结

每个卡命中返回：cardId/name/type/retrievalReason/sourceRefs/stateAsOf。

stateAsOf 只能由绝对章号 <= as_of 的里程碑重建。以下字段直接排除或阻断：

• 全书终态摘要；
• 未来成长弧线与结局方向；
• 无法证明绝对章号的演变事实；
• 内容描述明显属于目标章或未来章的错位里程碑。

正向创作没有回放冻结点时，asOf 等于当前 Canonical 最新章。

5.3 根据卡回读原文

首版必须保留 run3 已验证条件：目标章之前连续 4 章全文。选择性裁剪只能作为后续 A/B 实验变量；未证明不降质前，不得替代四章全文基线。

在连续四章之外，按卡来源指针补充：

1. 最近一次状态变化场景；
2. 人物代表性语言场景；
3. 能力、物品或关系的代表性表现；
4. 与本章细纲同类的历史场景。

RetrievalManifest 保存 planId、查询、过滤、排序、来源版本、章号、片段 offset、内容哈希和裁剪原因。manifestId 对规范化来源集合计算 SHA-256，排除 runId、时间戳和执行节点；同一 planId 与索引版本必须产生相同 manifestId。

6. 双证据模型

6.1 事实证据 factEvidence

负责“写得对”。可信来源包括：

• 已确认设定；
• Canonical 卡与状态台账；
• 已确认历史正文；
• 细纲明确声明的本章新 Canonical 事实。

正式设定无需历史正文即可成为硬事实。抽取卡若没有可靠来源或与 Canonical 冲突，则不能单独支撑事实。

6.2 表现证据 proseEvidence

负责“写得像”。来源是历史原文场景，用于人物声音、动作习惯、战斗表现、段落节奏和章末钩子。新角色没有历史原文时不构成事实阻断，但必须使用设定/细纲约束，并降低“文风复现”置信度。

6.3 覆盖状态

状态	含义	生产处理
supported	事实证据充分；需要表现复现时也有原文证据	允许
declared_new	细纲/设定明确声明的新 Canonical 事实	允许并申报
card_gap	原文或正式设定可证，但缺卡	允许，输出卡质量问题
style_gap	事实可证，但没有历史表现样本	允许，降低风格置信度
unsupported	没有可信事实证据	阻断硬事实
conflict	卡、设定、状态或原文互相冲突	阻断并交用户

7. 可执行数据合同

7.1 WriterContext v1

字段	类型	必填	约束
schemaVersion	string	是	固定 writer-context-v1
runId/attempt	string/int	是	runId 格式受限；attempt 单调递增
mode	enum	是	production / diagnostic_only
qualityPolicyVersion	string	是	绑定生产或离线状态机
workId/targetChapter/asOf	int	是	asOf < targetChapter（回放）
contextSnapshot	object	是	manifest ID、SHA-256、生成时间不进入哈希
sourceVersion	string	是	原始来源版本
authorizationSnapshot	object	是	不可变授权 ID、用途、重验时间
sourceStatus	enum	是	非允许状态失败关闭
retrievalPlan/manifest	object	是	版本、查询、过滤、排序、来源哈希
fineOutline	object	是	硬约束、可调整节拍、新设定声明
narrativeState	object	是	时间、地点、角色位置、即时局面
factEvidence[]	array	是	事实 ID、来源类型、sourceRef、hash
proseEvidence[]	array	是	章号、offset、hash、用途、临时片段
patternReferences[]	array	否	已授权范式卡，只作结构方法参考
evidenceCoverage[]	array	是	细纲要素到证据的覆盖状态
outputContract	object	是	篇幅、场景、frontmatter、申报规则
tokenBudget/omittedSources	object/array	是	预算与排除原因回显

所有对象使用严格 schema，额外字段失败；引用的 ID、版本和 hash 必须存在且一致。

7.2 WriterOutput v1

schemaVersion
runId / attempt / mode / qualityPolicyVersion
contextSnapshotId / contextSnapshotSha256
candidateVersion
candidateSha256
acceptanceEligible
candidateBody
claimLedger[]
evidenceRequests[]
newSettingDeclarations[]
selfCheck

diagnostic_only 输出必须固定 acceptanceEligible=false；confirm 对此状态硬拒绝。

candidateBody 在计算 hash 和 offset 前统一为 UTF-8、Unicode NFC、LF 换行。candidateSha256 对该规范化字节计算。claimLedger[] 至少包含：claimId、candidateSha256、startCodePoint、endCodePoint、事实类型、factEvidenceId、可选 proseEvidenceId、coverageState；范围采用 Unicode code point 的左闭右开区间 [start,end)。规则门机械校验范围、hash 和引用完整性；detector 判断语义是否真的匹配。

8. 篇幅与叙事基线

8.1 确定性算法

1. 正文先统一为 Unicode NFC 和 LF；“汉字数”= Unicode Script=Han 的 code point 数，不计标点、空白、拉丁字母和数字。
2. “有效章节”= Canonical、汉字数 >= 500、非空章、章号 < targetChapter。
3. 有细纲显式 targetChars 时使用该值，但仍执行 2000-10000 限幅；该字段需加入 outline schema。
4. 否则取最近 min(20, 有效章节数) 章的汉字数中位数；偶数样本取中间两值算术平均，使用十进制 ROUND_HALF_UP 取整数；不足 3 章时使用作品初始化默认值。
5. density = hardEventCount + 0.5 * foreshadowingActionCount + 0.5 * requiredSceneCount。
6. 调整系数 factor = clamp(0.85 + 0.05 * (density - 3), 0.85, 1.15)。
7. target = round_to_100(medianChars * factor)；round_to_100 使用十进制 ROUND_HALF_UP；范围端点同样半入取整，最后限制在 2000-10000 字。

回放评测只使用目标章之前的数据，不读取目标章字数。叙事基线同时记录连续四章的场景数、对话占比、段落长度和钩子类型。

9. 生产质量状态机

qualityPolicyVersion = writer-production-v1

validating_context -> retrieving -> writing -> detecting
detecting -> shadow_ready
detecting -> rewriting(attempt <= 2) -> detecting
detecting -> blocked_user_action(attempt > 2)
shadow_ready -> accept_preflight / edited_candidate / discarded
edited_candidate -> detecting
accept_preflight -> accepted / revision_conflict / authorization_stale / source_stale / quality_stale
accepted -> canonical_committed -> extraction_queued

detector 只阻断可定位、可验证的问题：细纲硬约束漏项、事实冲突、证据引用缺失、时间地点/知情范围/能力代价矛盾、未来泄漏、输出合同错误。文风、张力和文笔只给建议或交 judge，不作为 detector 硬阻断。

每个节点都有 deadline；超时先把当前 attempt 标为 *_timeout，取消下游，丢弃迟到结果。所有状态写入使用 compare-and-set：仅当数据库中的 runId + attempt + candidateVersion + currentState 与事件预期一致时转移；任何较小 attempt 或旧 candidateVersion 的成功、失败和迟到输出都忽略。终态不得回退，重试必须幂等。

accept_preflight 必须实时校验：mode=production、acceptanceEligible=true、qualityPolicyVersion、detector 报告绑定的 candidateSha256/candidateVersion、授权快照仍有效、sourceStatus 未变化、contextSnapshot 未失效、expectedRevision 一致。用户修改后合并必须生成新 candidateVersion、重新跑 detector，再回到 Shadow 展示与接受前置校验。

生产自动返修最多 2 轮。用户可在阻塞后手动发起新运行，不复用旧 candidateVersion。

10. 离线优化与双盲评测

qualityPolicyVersion = writer-eval-v1

• 状态机：preregistered -> generating -> detecting -> judging_pair -> stable_report；双评不稳定时进入 adjudicating -> adjudicated_report，第三评委后仍无稳定配对则进入 invalid_unstable；授权、冻结、合同或模型失败进入对应 failed_* 终态。
• 离线优化允许最多 5 轮，且每轮只改一个变量；与生产两轮返修是两套状态机。
• 三臂使用相同细纲、冻结点、模型、篇幅算法和最大生成预算。
• 候选臂名映射为随机化 ID；顺序种子由预注册 evaluationSetVersion + sampleId 派生并固定。
• 两个评委使用独立无会话实例，第二评委反转顺序；评分步长为 0.5。
• 同维分差 > 0.5 时判不稳定，最多增加一次第三评委。三评分中若至少一对差值 <=0.5，则该维最终分取三者中位数；若不存在稳定配对，则样本进入 invalid_unstable，不参与方向结论。
• 五维：设定与实体保真、情节与细纲忠实、叙事完整与张力、文风一致、文笔质量。
• 离线达标不改变 detector 红线，也不允许评委看到 writer 未见的底牌。

10.1 两级验收门

门	有效样本	机械通过条件	其他终态
Gate A 链路可运行	深空 5 章，五类场景各 1；授权/冻结通过且评委稳定	5/5 schema 合法；未来泄漏 0；系统失败 0；C 臂 detector 最终高严重度 0；细纲硬约束覆盖率 100%	有效样本 <5=insufficient_evidence；任一泄漏/系统失败/高严重度残留=failed
Gate B 正文层正式通过	至少 2 本书、每书 >=5 章、总计 >=10 章；五类场景均覆盖	Gate A 已 passed；C-A 的“设定与实体保真”平均增量 >=0.25 且至少 60% 样本增量 >0；“文风一致/叙事张力”平均增量均 >=-0.25，且任一维下降 >0.5 的样本占比 <=20%；C 臂硬约束覆盖率 100%、高严重度 0	样本不足或不稳定样本 >20%=insufficient_evidence；无明显保真增益但无退化=no_gain；发生质量退化或硬错误=failed

裁决按以下顺序执行，命中即停止，保证每次只有一个终态：

1. Gate A：有效样本不足 5 -> insufficient_evidence；否则只要存在 schema 非法、未来泄漏、系统失败、C 臂高严重度残留或硬约束覆盖率 <100% -> failed；其余 -> passed。
2. Gate B：Gate A=insufficient_evidence -> insufficient_evidence；Gate A=failed -> failed；否则若作品/样本/场景覆盖不足或不稳定样本占比 >20% -> insufficient_evidence；再判断硬错误或质量退化，命中 -> failed；再判断保真平均增量与正增益样本占比，达标 -> passed；其余 -> no_gain。

只有 Gate B=passed 才解锁细纲智能体真实能力验收；no_gain 只形成“卡未证明增益”结论，不视为通过。

11. 用户闭环与下游交接

Shadow 候选展示后提供三决策：

1. 原样接受；
2. 修改后合并，带 expectedRevision；
3. 丢弃。

原样接受和修改后合并都必须经过 accept_preflight。修改后合并先生成新 candidateVersion 并重新 detector；原样接受也必须重新校验授权、来源、质量策略、candidate hash 和 expectedRevision。通过后才调用 confirm；版本冲突返回 revision_conflict，不得静默覆盖。Canonical 提交后异步触发章后抽取，产出知识草稿和冲突队列；正文层只定义交接合同，不直接审批知识入库。

12. 实施计划与 SoT 回填

1. 启用并完善 meta/schemas/generation_context.yaml，新增 WriterOutput、RetrievalPlan/Manifest、claimLedger 合同。
2. 新增受控历史原文读取入口；扩展 search 为卡索引检索，不让 search 直接返回无版本原文。
3. 调整 read-context：四章全文基线、卡 stateAsOf、双证据和确定性 manifest。
4. 调整 writer：无工具隔离执行、受预算补证、硬约束/可调节拍、新设定申报。
5. 调整 continuation：确定性动态篇幅与输出合同。
6. 调整 detect：硬门清单、claimLedger 语义验证、结构化返修单。
7. 调整 quality-gate/eval/judge：生产与离线两套策略、双盲稳定性和第三评委上限。
8. 接通 Shadow 三决策、confirm、Canonical 和异步抽取交接。
9. 为无工具边界、未来章读取失败、卡冻结、manifest 复现、schema、超时、幂等、三臂隔离和用户决策增加机械测试。
10. 通过 Gate A 后执行 Gate B；Gate B 通过才恢复细纲智能体。
11. 评审通过后回填父仓 架构-04、专题-01/03/04/05/06/07、相关 API 契约、schema 和索引，删除重复定义；任务完成后蒸馏并删除本文。

13. 实施前门禁

• 本修订版通过产品流程与技术合同两类独立评审。
• 用户确认本文为正文智能体实验台任务 SoT。
• 独立范式抽取继续运行，但不得与正文实现共享改动文件或进程。
• 细纲真实回放保持暂停，直到正文 Gate B 通过。