docs(提示词): 修复方案v2定稿——复核修订八项与三项已决决策并入

- 正典名统一规划员（角色合同两处文字收窄豁免） - C1 blocked 载荷按写手纯写作负荷原则改为仅 reason，补齐评测侧消费点与回放影响评估 - A3 授权删除，JF-03 引用面扩充（SKILL.md/文件设计） - 孤儿模板范围外声明；索引与用例清单同步（顺带修复 NC-ui-preference-infer 存量漂移）
2026-09-19 20:24:29 +08:00 · 2026-09-19 20:24:29 +08:00 · 10f08b342a
commit 10f08b342a
parent 2276f8cb00
3 changed files with 197 additions and 0 deletions
--- a/docs/2026-09-19-提示词问题修复方案.md
+++ b/docs/2026-09-19-提示词问题修复方案.md
@ -0,0 +1,184 @@
+<!-- 导航元信息: {"内容描述": "提示词问题 A1-D3 的四批次修复方案（含复核修订与已决决策）", "使用场景": "实施提示词修复批次、验收批次结果时", "使用要求": "批次实施与验收以本方案为准；完成后稳定结论回填 SoT"} -->
+# 提示词问题修复方案（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` 例外随批次 1 处置 | 复核 P2-2 |
+| 6 | B3 身份句实为 **4 处**（补 `创作质量审阅.md:3`） | 复核 P2-3 |
+| 7 | 架构守卫正则须覆盖 `系统提示=(...)` 括号多行字面量形式 | 复核 P2-3 |
+| 8 | D2 判据下沉受写手纯度原则约束：判据优先落审阅/评委侧模板 | 决策 2 连带 |
+
+## 范围与范围外
+
+**范围外（显式声明，避免误认提示词问题已全处置）**：以下孤儿模板归属各自专项批次/台账组，本方案不动——
+
+- `审校修订/提示词/提取作品声音.md`、`诊断机器味.md`（审校修订+效果评测组台账）
+- `交付/全书审阅.md`、`整理交付材料.md`（交付连载组台账，已登记但无代码消费者）
+
+**例外**：`资料研究/提示词/分析参考作品.md` 与批次 1 新建的 `拆书分析.md` 同域同类，随批次 1 一并处置（见批次 1），避免同类双份残留。
+
+## 事实基线（已机械核实）
+
+- 资源治理链：`工具/资源登记.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)`，供运行证据留痕；请求级冻结已由现有 `请求字节哈希 + 批准保留` 覆盖，不新增机制。
+
+### 分析参考作品.md 处置（范围外声明的例外）
+
+- 新建 `拆书分析.md` 时以 `分析参考作品.md` 为底稿改写（内容可对齐则复用其表达），改写完成后**删除原孤儿文件**；内容不可对齐则直接删除并在台账注明。
+- 对应台账项（资料研究组孤儿模板）随本批次销项。
+
+### 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:_写作输出合同`，生产/评测共享外壳）
+
+```text
+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。
--- a/docs/目录.md
+++ b/docs/目录.md
@ -7,6 +7,7 @@
 | 实现回顾 | [目录.md](实现回顾/目录.md) | 功能落地对照、R2 历史留痕及验证边界 | 后续改同一功能、交接、对照设计时 | 功能合并后留回顾 |
 | 缺陷回顾 | 暂无 | bug 根因、修法、如何防再发 | 同类故障、改相关代码前 | 非平凡 bug 修完留根因时 |
 | 2026-09-01 创作链路合同校准提交前四维审查报告 | [2026-09-01-创作链路合同校准提交前四维审查报告.md](2026-09-01-创作链路合同校准提交前四维审查报告.md) | 本次提交前对创作链 SoT/Skill/实现校准差异的四维审查结论与验证证据 | 提交前确认本轮变更是否可交付时 | 只对应本次合同校准提交，不替代长期 SoT |
+| 提示词问题修复方案（v2 修订版） | [2026-09-19-提示词问题修复方案.md](2026-09-19-提示词问题修复方案.md) | 提示词问题 A1-D3 的四批次修复方案（含复核修订与已决决策） | 实施提示词修复批次、验收批次结果时 | 批次实施与验收以本方案为准；完成后稳定结论回填 SoT |
 | acceptance | [acceptance/](acceptance/) | 旧实现阶段的验收记录 | 追溯原任务的输入、决定与证据时 | 仅代表记录时点；当前行为须查现行设计与实现 |
 | design | [design/](design/) | 旧实现阶段的设计记录 | 追溯原任务的输入、决定与证据时 | 仅代表记录时点；当前行为须查现行设计与实现 |
 | plans | [plans/](plans/) | 旧实现阶段的计划记录 | 追溯原任务的输入、决定与证据时 | 仅代表记录时点；当前行为须查现行设计与实现 |
--- a/tests/用例清单.json
+++ b/tests/用例清单.json
@ -11687,6 +11687,18 @@
      "file": "web/tests/交互/作者偏好.test.tsx",
      "symbol": "NC-ui-preference-conflict：点名冲突并审阅后才能确认"
    },
+    {
+      "case_id": "NC-ui-preference-infer",
+      "environment": "离线界面和传输替身",
+      "given": "确定性聚合产出的推断偏好建议",
+      "when": "作者点击采纳",
+      "then": [
+        "以建议原话与真实反馈保存为待确认偏好，不自动生效"
+      ],
+      "contract": "docs/系统架构/新版设计/模块设计/B07-作者经验.md#偏好双轨关系",
+      "file": "web/tests/交互/作者偏好.test.tsx",
+      "symbol": "NC-ui-preference-infer：推断建议采纳为待确认偏好"
+    },
    {
      "case_id": "NC-ui-preference-scope",
      "environment": "离线界面和传输替身",