muse-agent-example/docs/2026-09-19-提示词问题修复方案.md

提示词问题修复方案（v2 修订版）

• 状态：已定稿，待按批次实施
• 日期：2026-09-19
• 前置：v1 方案经代码事实复核后修订；复核结论与本文档差异见「修订记录」
• 覆盖问题编号：A1-A3、B1-B3、C1-C4、D1-D3

修订记录（v1 → v2）

#	修订内容	依据
1	B1 正典名事实修正：角色合同 displayName: 规划师（角色合同.md:12、:119）与角色文件名/frontmatter 规划员 现状分裂；v1 所称"与角色合同一致"不成立。已决策统一为规划员，角色层改动范围显式豁免并收窄	复核 P1-1；用户决策 2026-09-19
2	C1 blocked 载荷改为仅 reason，不要求写手逐字引文举证；依据"写手纯写作负荷"原则（引文举证属检测/审阅职能）	用户决策 2026-09-19
3	C1 评测侧消费点补齐：逐例执行.py:935、语义检测.py:14 直读 paragraphs，blocked 需在读取前分流；补 blocked 统计口径与合同哈希/回放影响评估项	复核 P1-2、P1-3
4	A3（JF-03）引用面扩充：补 检查与维护拆书结果/SKILL.md:19、文件设计/后端-B03-资料研究.md:25,179-186；话术定位以 grep 为准，不按行号	复核 P2-1；用户决策=删除+话术改写
5	范围外声明修正：经开工前实测，报告所列其余孤儿模板已在早前批次删除，现存唯一孤儿为 核对实体歧义.md（批次 2 处置）；台账/报告的孤儿清单属过时信息	复核 P2-2 + 开工实测 2026-09-19
6	B3 身份句实为 4 处（补 创作质量审阅.md:3）	复核 P2-3
7	架构守卫正则须覆盖 系统提示=(...) 括号多行字面量形式	复核 P2-3
8	D2 判据下沉受写手纯度原则约束：判据优先落审阅/评委侧模板	决策 2 连带

范围与范围外

事实修正（2026-09-19 开工前实测）：专项检查报告所列其余孤儿模板（提取作品声音.md、诊断机器味.md、分析参考作品.md、交付/全书审阅.md、整理交付材料.md）已在早前批次删除，仓内不复存在；台账与报告中的孤儿清单属过时信息。现存唯一孤儿为 核对实体歧义.md（批次 2 处置）。批次 1 无需"底稿复用"动作，拆书分析.md 直接新建。

事实基线（已机械核实）

• 资源治理链：工具/资源登记.json（唯一登记输入）→ 工具/构建资源包.py（打 zip + sha256 清单）→ 运行时 打开资源() 哈希校验加载。
• 已登记任务模板 9 份，全部遵循"源文件随消费方模块归位、打包名按任务域命名空间"惯例（正文/ 审校/ 评测/ 规划/ 写作/）。
• 硬编码提示词 4 处：编排/生成正文.py 探索提示（"你是本作品的写手…受限探索"）、编排/章后处理.py（"你是本作品的抽取员…"）、资料研究/拆书分析.py:68（"你是参考作品分析员…"）、任务运行/配置探针.py:38。
• 模板身份句 4 处：生成正文.md:3、生成作品规划.md:3、细化章节计划.md:3、创作质量审阅.md:3。
• 写手输出合同 写作任务.py:142-167 为生产/评测共享外壳（逐例执行.py:266）；schema 用 jsonschema.Draft202012Validator 本地校验（模型调用.py:12,32），不透传 provider API，oneOf 无兼容性风险。
• 正典名现状分裂：角色合同 displayName: 规划师（角色合同.md:12、:119）vs 角色文件名与 frontmatter name: 规划员（.agent/角色/规划员.md）。
• 核对实体歧义.md 未登记、运行时不加载；台账 JF-03 已立案（标注需用户授权，本次已授权删除）。

已决决策（2026-09-19）

1. 正典名 = 规划员。与其余角色命名模式一致（写手/知识抽取员/检测员/评委）。角色层改动仅限角色合同两处文字（displayName、章节标题），.agent/角色/规划员.md 文件本身不动——此为对"角色层冻结"红线的显式收窄豁免。
2. A3 = 删除 + 话术改写（JF-03 授权）。
3. C1 blocked 载荷 = 仅 reason。原则：写手纯写作负荷——引文举证属检测/审阅职能，不压给写手；作者核查冲突依据的途径是冻结装配材料本身（任务详情可回看），无需写手复述。

---

批次 1 — 治理归一：硬编码提示词收归发布包（A1、A2、B2、D3）

新模板与归位

新文件	打包路径	消费方改动
src/muse/编排/提示词/受限探索.md（新建目录）	正文/受限探索.md	编排/生成正文.py 探索提示改 打开资源()
src/muse/编排/提示词/章后抽取.md	抽取/章后抽取.md	编排/章后处理.py 改 打开资源()
src/muse/资料研究/提示词/拆书分析.md	抽取/拆书分析.md	资料研究/拆书分析.py:68 改 打开资源()

内容规则（同时解决 B2/B3 硬编码侧）

• 新模板不带"你是…"身份句——身份唯一来源是角色层（.agent/角色/*.md），消除装配后双自我介绍；"本作品的抽取员""参考作品分析员"两个私设身份名随之消失。
• 只保留行为指令（逐字引文、不补猜窗口外内容、不新增正文没有的设定等），原文语义不增不减；受限探索模板保留"探索完成后输出空 JSON 对象"等现有行为指令。
• 加载函数仿照 写作任务.生成正文模板() 返回 (文本, sha256)，供运行证据留痕；请求级冻结已由现有 请求字节哈希 + 批准保留 覆盖，不新增机制。

D3 配置探针

• 保留代码内提示：探针与 探针合同 代码同构、64 token、无迭代需求；加豁免注释说明理由。
• 新增架构守卫测试 tests/架构/test_提示词治理.py：扫描 src/muse/**/*.py 中 系统提示= 后接字符串字面量的赋值，正则须同时覆盖 系统提示="..." 与 系统提示=(...) 括号多行隐式拼接两种形式（章后处理、拆书分析的硬编码均为后者）；白名单仅 配置探针.py——从机制上杜绝 A1 类回归。

登记与重建

工具/资源登记.json 增 3 条 → 工具/构建资源包.py 重建 → 工具/维护索引.py --检查。

验收

• 扩展 tests/单元/test_规划审校发布模板.py 参数表覆盖 3 份新模板（源树/发布包同哈希、缺失不回退）。
• 新增单测断言探索/拆书/章后三条链路装配后系统提示 = 角色提示 + 资源模板 + 合同，且不含第二个"你是"。
• 守卫测试自验：对括号形式硬编码的检出（可临时植入样例断言检出后删除，或以正则单测覆盖）。

---

批次 2 — 身份与术语统一（B1、B3 存量侧、A3、C4、D2）

B3 + B1：身份句删除与正典名统一（已决=规划员）

1. 删除 4 处模板身份句：生成正文.md:3、生成作品规划.md:3、细化章节计划.md:3、创作质量审阅.md:3。
2. 角色层改动（红线收窄豁免，仅此两处文字）：角色合同.md:12 displayName: 规划师→规划员；:119 章节标题"## planner：规划师"→"## planner：规划员"。.agent/角色/规划员.md 不动。
3. 编排/生成规划.py:319 错误文案"规划师角色"→"规划员角色"。
4. 核对 配置/角色策略.yaml 及 docs 中显示名，统一为规划员。
5. 点名测试同步更新（v1 未列，删除身份句后必失败）：
   • tests/集成/test_受控规划方法消费.py:115 断言 "规划师" in instructions——改为按角色层实际身份词断言（以 .agent/角色/规划员.md 正文用词为准，不虚构断言）；
   • tests/集成/test_受控规划方法消费.py:193 match="规划师角色"→"规划员角色"。

A3（已决=删除+话术改写，JF-03 销项）

处置清单——话术定位以 grep 全仓为准，行号仅供定位：

• 删除 src/muse/资料研究/提示词/核对实体歧义.md（未登记、运行时不加载、承诺了不存在的任务）。
• 代码/CLI/SKILL 话术改"歧义只登记，由作者人工判定"：资料研究/实体归并.py:67、接入/cli/研究命令.py（台账记 :123、v1 记 :153，实测以 grep 结果为准）、.agent/skills/操作/检查与维护拆书结果/SKILL.md:19（v1 遗漏，补入）。
• docs 同步（v1 遗漏文件设计，补入）：模块设计/B03-资料研究.md:49、文件设计/后端-B03-资料研究.md:25、179-186（目录树+文件条目）、项目目录与文件职责.md:1057、目标文件清单.json:11362。
• 台账销项：docs/实现回顾/专项检查-台账.md 与对应报告的 JF-03 行。

C4 英文维度名中文对照

创作质量审阅.md 英文维度名首现处加中文对照——continuity（连续性）、craft（文学质感）、voice（声音指纹）、repair（修订）、retain（保留）、ask（追问）；核对 连续性审阅.md、评测两模板同名维度写法一致。

D2 判据下沉（受写手纯度原则约束）

• 角色层（冻结、稳定）不动；判据下沉到任务模板。
• 判据优先落审阅/评委侧模板；写手模板（生成正文.md）仅在判据属写作技艺本身（如"戏剧化=用动作、对白与细节呈现事件，不复述或概括事件"）且现文确有歧义时补，格式为并入现有句子而非新增条目，写手侧净增量 ≤2 行。

验收

• 全仓 grep"规划师"零残留（角色合同/历史回顾/总账留痕文档除外）；grep"核对实体歧义"仅剩台账留痕。
• 重建资源包；点名测试与模板内容断言更新后全绿。

---

批次 3 — 写手阻塞出口 + 模板重构（C1、D1）

合同变更（写作任务.py:_写作输出合同，生产/评测共享外壳）

oneOf: [{required: [paragraphs]}, {required: [blocked]}]
blocked: { reason: string(minLength 1), additionalProperties: false }

• paragraphs 保持 minItems: 1、结构不变；blocked 仅 reason（决策 3：写手纯写作负荷，引文举证不压给写手）。
• 顶层 additionalProperties: false，paragraphs 与 blocked 均入 properties；两者同现或全缺由 oneOf 机械拒绝（tests/契约/test_正文与模型输出.py 扩展四态组合：仅 paragraphs / 仅 blocked / 双现 / 全缺）。
• oneOf 安全性依据：schema 为本地 Draft202012Validator 校验，不透传 provider。

模板变更（生成正文.md，同时完成 D1）

• 拆"写作要求 / 输出与阻塞"两块；阻塞段 ≤2 行："仅当细纲与前置事实材料存在不可化解的死结（任何写法都必然虚构冲突事实）时，不写正文，输出 blocked 与一句话 reason。"——不要求写手引文举证。
• LF/CR 换行语义移入合同 description 字段（json.dumps(schema) 随装配进系统提示，信息不丢失，模板正文减负）。

生产消费路径

• 编排/生成正文.py:399 读 paragraphs 前分流：交付含 blocked → 不产出候选，按该文件 82 行"编排内明确失败"（WRITING_FLOW_INVALID）模式向作者呈现 reason；blocked 载荷写入运行证据/事件记录（审计留痕：为何未写）。作者核查冲突依据 = 冻结装配材料（任务详情可回看）。

评测消费路径（v2 补齐）

• writers 交付记录处分流 blocked；以下两处直读 paragraphs 的消费点必须在读取前判 blocked，杜绝 KeyError：
  • 逐例执行.py:935（成对比较材料组装）；
  • 语义检测.py:14（读取检测材料）。
• 统计口径：依赖 blocked writer 的下游 spec（成对比较、语义检测）标记无结果（写手阻塞），不进成对比较、不静默跳过；评测报告单列 blocked 计数。
• 机械测试覆盖两处消费点的 blocked 分支（防 KeyError 回归）。

合同哈希与回放影响（v2 新增实施验证项）

output_schema_hash 入运行证据（运行证据.py:39,249）、冻结配置与步骤合同强比对（模型调用.py:239）、回放校验（接口.py:429）。实施时验证：合同变更后存量冻结任务的回放/重验是否失效；若失效，按评测侧版本串惯例（quote-only-v2、writer-rubric-v1、detection_contract）决定写作输出合同是否需版本化，或确认冻结配置内嵌合同已足够隔离。以重放相关测试为机械判据。

边界

修改选段.md 路径有独立 replace/retain 合同，不扩散。接口契约登记处与 docs/接口契约 相应文档同步；无 DB 迁移。

---

批次 4 — 小模型鲁棒性（C2、C3）

前置：批次 1-3 后模板已定稿，只动一次哈希。

1. C2 负向约束瘦身：逐条审计全部模板（含批次 1 新增 3 份）的"不得/不要/禁止"，处置判据：
   • 删：已被机械保证的（additionalProperties:false 保证的"不输出多余字段"、schema not pattern 保证的换行禁则、后端引文对齐门禁保证的"引文必须存在"提示重复表述）；写手模板的机械保证类负向约束优先删（直接减负，与决策 3 同向）。
   • 留：行为性负向约束（不虚构事实、不越圈选边界、不替作者批准——schema 管不住）。
   • 产出"模板 × 约束 × 处置 × 依据"审计表，随提交附上。
2. C3 few-shot 补样：仅 governed 池角色（extractor/detector）的任务模板各加 1 个 ≤8 行微型示例：正例（合法 JSON + 逐字引文 + 码点区间）+ 反例（引文截断，标注为何非法）。落点：拆书分析.md、章后抽取.md、连续性审阅.md 引文段。writer/judge 走 fixed 顶级模型不加示例（风格污染、双盲泄漏、写手纯度三重依据）。
3. 实证验证（与风险相称）：改动前后各跑一轮 governed 池小模型（qwen3.8-flash、MiniMax-M2.7、glm-5.2）抽取/检测任务 A/B（每模型 N≈20，走现有真实调用或评测通道），比较 schema 拒绝率与引文对齐通过率；无改善则回滚对应模板文本（重新登记旧文本即可，哈希机制天然支持回滚）。

收尾：全量门禁（架构 + 单元 + 契约 + 集成 + 端到端抽测）集中跑一次。

---

横切事项

• 每批次末尾固定动作：构建资源包.py 重建 → 维护索引.py --检查 → 受影响快速测试（make 快检 范围=<受影响路径>）；发布身份/资源哈希变更在提交信息中注明。
• 角色层冻结红线豁免范围（仅批次 2）：角色合同.md 两处文字（displayName、章节标题）；其余角色文件一律不动。
• 执行顺序刚性：1 → 2 → 3 → 4（批次 2/3 依赖批次 1 的资源化落点；批次 4 依赖模板定稿）。
• 提交纪律：每批次至少一次本地 commit 检查点；中文提交 {类型}({模块}): {描述}；合并回 main 前统一 Review。