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、用途、临时片段
indexHints[]	array	否	仅诊断上下文可用的冻结卡提示；严格字段为 cardId/name/type/content/sourceId/sourceVersion/asOf
evidenceStrategy	enum	否	生产缺省视为 production_dual_evidence；正文 A/B/C 回放必须显式记录各臂证据策略
patternReferences[]	array	否	已授权范式卡，只作结构方法参考
evidenceCoverage[]	array	是	细纲要素到证据的覆盖状态
outputContract	object	是	篇幅、场景、frontmatter、申报规则
tokenBudget/omittedSources	object/array	是	预算与排除原因回显

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

evidenceStrategy 是兼容字段：生产上下文未填写时按 production_dual_evidence 校验；正文 A/B/C 回放不得使用缺省值，必须分别显式填写 historical_prose_only、card_index_only、card_index_plus_prose。indexHints 只能在 mode=diagnostic_only、purpose=evaluation/diagnostic 且 acceptanceEligible=false 时出现；生产上下文硬拒绝。其 asOf 不得超过上下文冻结点，claimLedger 不得引用 indexHints。只有显式填写 evidenceStrategy=card_index_only 的 B 臂允许在合同内跳过连续四章基线，并且必须保持 proseEvidence=[]；该例外不能用于生产。

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 派生并固定。
• judge 的可信输入边界是独立 writer-blind-input-v1 内容，包含 blind-1/2/3 候选正文/哈希，以及所有臂完全相同的 sharedEvaluationReference。共同参考只取目标章细纲硬约束、实体、必需角色、伏笔、章末钩子和冻结点前连续四章历史原文基准，用于评价细纲忠实、设定、文风和卡索引正确性；它可在真实运行时临时传递，但不进入安全摘要。共同参考严禁包含 indexHints、各臂补充原文、卡 manifest、evidenceStrategy、真实映射或臂名，不能用被测卡本身给被测候选背书。真实 A/B/C 映射仅在编排器内存中存在，judge 不得访问各臂 WriterContext、原始运行目录或含 candidate-A/B/C 的路径。
• 两个评委使用独立无会话实例，第二评委反转顺序；评分步长为 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 只形成“卡未证明增益”结论，不视为通过。

10.2 Task10 Gate A 预注册与当前可验证边界

唯一配置为 .claude/skills/replay-eval/configs/writer-gate-a-deep-space-v1.json。样本固定如下，不得根据生成结果替换章节或场景分类：

目标章	冻结点	场景	预注册目标	大纲/细纲来源	预期长度	主要实体	新角色比例	泄漏检查
489	488	战斗	圣蒂曼围攻/加特朗战	outline-window:deep-space:481-488 / fine-outline:deep-space:489	7500	圣蒂曼、加特朗	1.0	禁读 489 及以后；目标/未来读取数必须为 0
321	320	人物对话	莫妮卡道别与朋友确认	outline-window:deep-space:313-320 / fine-outline:deep-space:321	7600	莫妮卡、朋友关系	0	禁读 321 及以后；目标/未来读取数必须为 0
544	543	转折	迷途之地内应反水	outline-window:deep-space:536-543 / fine-outline:deep-space:544	6700	迷途之地、内应	未知	禁读 544 及以后；目标/未来读取数必须为 0
199	198	信息揭示	赛莉丝身份与联赛锁死真相	outline-window:deep-space:191-198 / fine-outline:deep-space:199	2000	赛莉丝、联赛	0	禁读 199 及以后；目标/未来读取数必须为 0
523	522	老角色回归	伊蕾莉雅与旧部重逢	outline-window:deep-space:515-522 / fine-outline:deep-space:523	6100	伊蕾莉雅、旧部	0	禁读 523 及以后；目标/未来读取数必须为 0

预期长度不是人工填写：配置记录目标章之前连续四章的 frozenRecentHanCounts，统一以 hardEventCount=1、foreshadowingActionCount=0、requiredSceneCount=0 调用 calculate_target_chars，且 usesTargetChapterLength=false。五章机械结果固定为 489=7500、321=7600、544=6700、199=2000、523=6100；上下限取正负 10% 后再受 2000-10000 限幅。

新角色比例只统计具名 requiredCharacters 在冻结点前无记录的比例。489 的加特朗在 488 前无记录，因此为 1.0；321/199/523 的具名角色已有记录，因此为 0；544 的“内应”是泛称、无法机械判定具体身份，必须为 null + unresolved_generic_role，不允许默认成 0。

仓内配置不含原文全文。writerContextInput.contentMode=sanitized_contract_fixture，连续四章只放脱敏合成短文本，用于 dry-run 机械证明 WriterContext 合同、冻结边界、三臂差异、manifest 可复现和候选不可接受；不能据此声称历史原文完整、生成质量通过或 real-run 完成。

dry-run 命令：

.venv/bin/python .claude/skills/replay-eval/scripts/run_writer_replay.py \
  --config .claude/skills/replay-eval/configs/writer-gate-a-deep-space-v1.json \
  --dry-run

dry-run 只生成计划、manifest 和上下文摘要，不调用模型。测试注入路径虽可验证 writer、detector 与盲评编排，但 judge 只接收独立盲化内容和共同评测参考，不能取得 raw 目录、真实臂映射或任一臂专属证据；评委顺序变化不得改变共同参考。当前真实 semantic detector 与 judge adapter 尚未实现，CLI --execute 必须明确失败关闭；在 adapter 接线、离线测试和预算确认完成前，不得声称真实回放或 Gate A 已完成。

Gate 判定只消费逐样本脱敏输入。writer_gate.py 在可信边界内自行计算 Gate A/B 的有效样本、作品/场景覆盖、C 臂硬门、C-A 五维增量、退化比例与五类混淆项；不信任上游聚合数字。五类混淆项为假阴、假阳、泄露、评委不稳定和新角色无卡，必须逐样本记录后汇总。

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 通过。