<!-- 导航元信息: {"内容描述": "提示词问题 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`（批次 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:_写作输出合同`，生产/评测共享外壳）

```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。

---

## 附录：负向约束审计表（批次4 C2/C3 执行记录，2026-09-19）

处置判据：**删**=已被机械保证（无工具请求 / additionalProperties:false / 解析层拒绝）；**留**=行为性约束（schema 管不住）或预防性提示（降低小模型拒绝率，与 C3 同向）。

| 模板 | 约束 | 处置 | 依据 |
|---|---|---|---|
| 细化章节计划 | 不调用工具、不读取未授权正文 | 删 | 规划请求不带工具（机械不可为） |
| 生成作品规划 | 不执行工具、不读取其他作品、不输出正文 | 删 | 同上；输出合同无正文字段 |
| 生成作品规划 | 不添加…模型来源或用户确认字段 | 删 | additionalProperties:false 机械拒绝 |
| 创作质量审阅 | 不使用工具 | 删 | judge 请求无工具（机械保证） |
| 创作质量审阅 | 未登记字段 | 删 | additionalProperties:false |
| 全部模板 | 只返回约定 JSON 对象（含不添加解释/围栏变体） | 留 | 解析层机械拒绝，但提示预防拒绝成本更低 |
| 生成正文/修改选段/生成最小修订 | 不虚构冲突事实、不扩大圈选边界、retain不夹带改写等 | 留 | 行为性 |
| 连续性审阅/独立评审/文学评分 | 提示注入防护、盲化、引文保真、不提交位置哈希（带理由） | 留 | 行为性+预防性 |
| 受限探索 | 不要输出正文 | 留 | 探索合同 type:object 不限字段，非机械 |

统计：12 份任务模板逐条审计，删 5 处机械保证重复表述（写手模板零删除，其负向约束均为行为性）；C3 为拆书分析/章后抽取/连续性审阅各加 4 行引文正反例（逐字合法 vs 截断/转述/自造 id 非法），writer/judge 模板不加示例。

**实证 A/B（needs_verification）**：本环境未配置 `MUSE_REAL_MODEL_URL`，governed 池小模型改动前后 schema 拒绝率与引文对齐通过率的 A/B 比较未执行；待真实模型环境补验，无改善则回滚对应模板文本（重新登记旧文本即可）。