# 阶段 F 第一部分：两阶段写手（探索与生成分离）

日期：2026-08-22
状态：已完成（离线绿）
上游证据：两次生产烟测（`run-prod-work12-ch3-e7829416` / `run-prod-work12-ch3-59f43855`）

## 1. 问题（烟测实证）

单阶段派发下，多回合探索循环与长篇一次性产出合同冲突：

- 第一次烟测（medium，带元标签指令）：写手 0 次工具调用（预组装上下文让探索冗余），正文复读细纲原句「链接加深」，机械门 `OUTLINE_PHRASE_LEAKED` 拦截。
- 第二次烟测（high，指令留空）：写手真实探索（26 次工具调用、6 回合、依赖清单落盘），但正文碎片散落在中间回合，最终消息只剩 909 字残稿，机械门 `CANDIDATE_LENGTH_OUT_OF_RANGE` + `HARD_EVENT_MISSING` 拦截。

结论：探索与生成必须分离——探索走多回合框架循环，生成走单次成稿。

## 2. 设计

```text
阶段一（探索）：派发写作智能体（只读工具，独立探索会话）
  产出 = 探索清单（小结构化 JSON，writer-exploration-manifest-v1）
  独立派发运行记账（事件、raw、依赖清单）
        ↓
确定性回放：按清单逐条重放只读工具（无模型参与）
  产出 = 写手实际依赖的资料（含来源工具与参数）
        ↓
阶段二（生成）：派发写作智能体（无工具，写作会话）
  冻结生成输入 = 探索资料 + 篇幅/文风合同（来自冻结上下文投影）
  单条回复一次写完本章全部正文
        ↓
信封绑定：复用 dispatch_writer_bridge（身份、哈希、版本由桥绑定）
```

关键取舍：

- 生成输入不含预组装（细纲/基线/事实摘录/范式卡不进生成输入）；写手事实只来自它探索到的资料。合同部分（篇幅、文风约束）仍由生产编排冻结注入。
- 探索清单回放是确定性的：同一清单重放得到同一份资料；资料与清单一并构成链路透视数据。
- 探索失败、清单非法、回放失败、生成失败一律失败关闭，不产生半绑定候选。
- 探索会话（`writer-explore-work{W}-ch{T}`）与生成会话（`writer-work{W}-ch{T}`）分离：探索历史不混入生成上下文，写作连续性跨版本保留。
- 证据归属不变：探索运行与生成运行各自记模型事件/raw；生产运行只绑候选与质量证据；`writer_raw_ref` 指向生成运行。

## 3. 改动台账（逐项）

| 文件 | 动作 | 原因 |
|---|---|---|
| `.agent/skills/write-next-chapter/scripts/two_phase_writer.py` | 新增 | 两阶段编排：探索任务包装配、清单严格校验、确定性回放、生成输入装配、两阶段派发编排 |
| `.agent/skills/write-next-chapter/scripts/dispatch_writer_bridge.py` | 修改 | 增加覆盖位（任务提示词、冻结创作输入、工具开关、会话标签）；缺省行为完全不变 |
| `.agent/skills/write-next-chapter/scripts/produce_next_chapter.py` | 修改 | 新增 `--two-phase` 旗标（隐式派发模式）；探索摘要落工件与终端 |
| `tests/skills/write-next-chapter/test_two_phase_writer.py` | 新增 | 17 项离线测试：清单校验 7、回放 2、生成输入 2、编排 3、任务包 1、桥扩展 2 |

## 4. 验证

- 新增测试 17/17 通过。
- 全量离线门禁：82 个标准 `OK` + 19 个自定义输出通过（逐一核实无真失败），0 失败；桥扩展未破坏既有用例。
- 真实验证留待下一步：`produce_next_chapter.py 3 --two-phase --provider catproxy-anthropic --model claude-opus-5 --thinking high`。

## 5. 生产验证问题与修复（2026-08-22/23）

第三次真实烟测（`run-prod-work12-ch3-142d6cf0`）在生成阶段挂死，失败关闭收口。根因与修复：

| 问题 | 根因 | 修复 |
|---|---|---|
| 生成阶段模型发起探索工具调用，`--no-tools` 下无法解析导致挂死 | 写手角色合同写“动笔前按需使用授权工具自主取材”，与生成阶段“无工具”冲突；模型非确定性服从 | `writer.md` 改写为两阶段形态：探索阶段（白名单非空，只探索不写作）/ 生成阶段（白名单为空，禁止工具调用，单条成稿） |
| 生成会话被旧单阶段运行（带工具的探索+碎片写作）污染，诱导探索行为 | 生成复用旧会话 `writer-work{W}-ch{T}` | 生成会话独立标签 `writer-gen`（探索为 `writer-explore`） |
| 挂死不能无限阻塞 | 看门狗已存在（绝对超时 `maxDurationSeconds`，到点杀进程，`FRAMEWORK_TIMEOUT`） | 无需新增；本次人工提前清理仅为节省等待 |
| 令牌经命令行传入在进程表可见 | tmux 命令串内嵌环境变量赋值 | 运行结束后轮换 `MUSE_AI_NEW_API_TOKEN`；后续用环境文件或进程内注入，不进命令行 |

## 6. 未决（下一阶段）

- 两阶段真实烟测通过后：两阶段成为生产默认形态，单阶段派发降级为对照模式；角色合同与领域文档同步改写（写手 = 探索阶段 + 生成阶段）。
- 评委与抽取智能体的框架派发接入、直调链终态裁决仍按总 plan 阶段 F 推进。