zizi-al/muse-agent-example
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

过程清理: 删除已收口的整体收敛计划文档12份（结论已蒸馏进稳定文档，git历史可回取），验收记录引用修正，补登4项测试清单

Browse Source
This commit is contained in:
zizi 2026-08-23 22:23:50 +08:00
parent af54904da1
commit cc23bab482
14 changed files with 75 additions and 879 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/acceptance/2026-08-23-§11可见性对照验收-书12基线走查记录.md
View File

@ -2,7 +2,7 @@
日期：2026-08-23
走查对象：只读看板 `http://127.0.0.1:8765` + muse-example 数据库
走查依据：`docs/plans/2026-08-22-agent-example整体收敛总plan.md` §11 可见性对照矩阵
走查依据：整体收敛总 plan §11 可见性对照矩阵（该计划文档已于 2026-08-23 收口后删除，内容可从提交链 `eb83053`→`661695f` 回取）
## 矩阵逐项结论

237
docs/plans/2026-08-22-agent-example整体收敛总plan.md
View File

@ -1,237 +0,0 @@
# agent-example 整体收敛总 plan
日期：2026-08-22（2026-08-23 收口）
状态：**已收口**。阶段 A–G 全部完成并逐项提交（`eb83053`→`661695f`）；最终验收 §11 五类可见项全可见（记录见 `docs/acceptance/`）；对照实验裁决创作生成直调链退役、框架派发链为唯一创作生成链。各阶段台账见本目录阶段文件。
---
## 1. 意图
两条线，缺一不可：
**线一：主权生产链。** 把仓从"多条模型调用路径并存、约束散落各处、一次性脚本与设计文档堆积"收敛为一条主权清晰、链路唯一、边界机械强制的创作系统：
```text
人
-> 主代理（润色人的意图、协调授权；不写作、不约束创作）
-> 五个创作智能体（经授权工具自主探索、按提示词合同工作）
-> 静态校验与脚本编排（验证报告、推进状态、落库）
-> 人闸决策
-> 正式正文
```
**线二：作者参与链。** 这不是后台流水线，是作者要参与、要看见、要交互的工具。作者必须能在页面上：
- **阅读**：阅读正式正文。
- **待审**：看待审章节--候选正文、多版本对比、检查报告、逐维评分、本章实际用了哪些资料。
- **卡片**：查看知识卡、设定卡、范式卡及其确认状态。
- **链路透视**：查看每次运行的输入与输出--任务包、探索轨迹（读了什么、哪个版本）、生成结果、事件链、成本。
- **决策**：采纳、丢弃、授权继续补证或重写。
三条不变的主权规则：
1. 模型只产候选（Shadow），不产正式事实。
2. 系统只做机械验证，不做内容裁决。
3. 只有人通过决策通道决定候选是否进入正式正文（Canonical）。
## 2. 目标总链路
```text
人的意图
│ 主代理润色、确认歧义
▼
任务提示词 ──-> 智能体（框架派发）
│ 只读工具自主探索（评委为圈定授权）
▼
候选 / 报告 + 依赖清单
│ 静态校验（结构、引文真实性、哈希绑定）
▼
脚本编排（状态机、落库、CAS、授权终态）
│ 需继续时向人请求授权
▼
人闸决策 -> 正式正文 / 确认转正 / 丢弃
▲
│ 全程可透视
创作台（作者交互面）：阅读 / 待审 / 卡片 / 链路输入输出 / 决策
```
## 3. 作者交互面（创作台）
现有底座：只读看板（:8765）+ 决策通道（:8767）。目标形态统一为创作台，五个视图：
| 视图 | 内容 | 数据来源 |
|---|---|---|
| 阅读 | 正式正文、章节导航 | 正文表 |
| 待审 | 待审章节列表、候选对比、检查报告、评分、依赖清单 | 候选表、质量结果表、依赖清单 |
| 卡片 | 知识卡、设定卡、范式卡、确认状态 | 知识实体表、范式绑定 |
| 链路透视 | 每次运行的任务包、探索轨迹、事件链、模型调用、成本 | 运行表、事件账本、raw 指针 |
| 决策 | 采纳 / 丢弃 / 授权继续 | 决策通道（既有） |
边界：创作台只读库、不拼模型调用命令、不绕过决策通道写库。
## 4. 组件职责与边界
| 组件 | 职责 | 边界 | 结构 |
|---|---|---|---|
| 智能体（5 个） | 按角色合同生成候选或报告，自主探索后工作 | 不写库、不越工具白名单、不推进状态、不带来源不引用 | 角色身份提示 + 中央角色合同 + 任务提示词 |
| Skill | 业务功能合同：场景、输入输出 Schema、路由、失败路径 | 不持有模型策略、不绕过证据账本、依赖只向下 | SKILL.md（合同）+ scripts（机械实现）+ 元数据 |
| 工具 server | 给智能体提供只读取数能力，统一入口 | 只读、按任务包授权圈定、调用即留痕、不提供裸查询 | 每工具声明：读什么表、什么版本语义、返回什么结构 |
| 脚本编排 | 确定性流程：状态机、落库、CAS、终态 | 不做内容裁决、不拼提示词、不隐式循环 | 各 Skill scripts 层 |
| 静态校验 | Schema、引文真实性、哈希绑定、架构门禁 | 无模型参与、失败关闭 | 测试 + 校验脚本 |
| 主代理 | 润色人的意图、确认歧义、转述报告、请求授权 | 不写作、不约束创作、不承载合同 | 宿主会话 |
判定原则：模型能被说服的用提示词；模型不能碰的用工具白名单；不允许出错的用脚本与静态校验。主代理不承载任何创作约束，只传递人的意图。
## 5. 约束归属（所有改动的归位依据）
每类约束只有一个归属，禁止跨层承载：
| 约束类型 | 归属层 | 强制方式 |
|---|---|---|
| 创作意图、工作方法、写作纪律 | 提示词层（agent prompt） | 模型遵守 + 输出抽查 |
| 角色身份、模型策略、合同版本 | 中央角色合同 | 派发入口机械校验 |
| 数据可访问范围 | 工具层（tool server） | 白名单机械拒绝 |
| 输入输出格式 | 静态层（schema 校验） | 模型调用前后拒绝 |
| 状态推进、数据库写 | 脚本层 + 数据库约束 | CAS、触发器、事务 |
| 模块依赖、目录纪律 | 架构门禁（测试） | 失败关闭 |
## 6. 五智能体与五条链
| 智能体 | 所属链 | 目标形态职责 | 探索授权 |
|---|---|---|---|
| 规划智能体 | 规划链 | 产出设定、大纲、细纲的待审草稿 | 只读：作品事实、上层规划、已有设定 |
| 写作智能体 | 正文链 | 自主探索后生成一章正文候选 | 只读：细纲、前文、人物、世界规则、文风 |
| 检测智能体 | 质量链 | 对单个候选自主取证检查 | 只读：正典检索、细纲、事实证据 |
| 评委智能体 | 评测链 + 生产预检 | 独立盲评，逐维打分给引文 | 圈定授权只读：禁看候选身份、标准答案、其他评委结果；实验场景最窄，生产预检放宽 |
| 抽取智能体 | 知识链 | 从正文抽取实体、关系、事件草稿 | 只读：正文回读、既有知识卡 |
链定义：
- 规划链：人 -> 主代理 -> 规划智能体 -> 规划候选 -> 人确认转正。
- 正文链：人 -> 主代理 -> 写作智能体 -> 正文候选 -> 人闸。
- 质量链：检测智能体 -> 检查报告 -> 主代理向人请求是否补证/重写。
- 评测链：评委智能体 -> 盲评报告（评测候选永不进正式正文）。
- 知识链：抽取智能体 -> 知识草稿 -> 人确认转正。
补证与重写不设业务硬上限：检查发现问题后返回结构化缺口报告，由主代理转述给人，人授权后复用或新建智能体继续；技术保护（超时、预算、取消）保留。
写作智能体会话复用：一章默认复用同一实例；完全重写时新建实例并显式交接材料，不依赖隐藏记忆。
框架派发与直接模型调用共存：框架负责自主探索；直接调用保留为对照模式，使用智能体实际收集的依赖上下文生成对照正文，比较质量、成本与遗漏率。生产同一时刻只走一条链。
## 7. 全局边界（不做）
- 不动人闸与决策通道，正式正文主权不变。
- 不给任何智能体写库权限，探索工具全部只读。
- 不重造候选状态机、CAS、raw 三件套与事件账本表结构合同。
- 不在生产链混入对照实验。
- 创作台不成为第二个写库入口。
## 8. 阶段划分
```text
A 边界合同定义 -> B 链路盘点与清理 -> C 角色合同与领域文档对齐
-> D 能力建设（只读工具 server / 会话复用 / 依赖清单）
-> E 生产链切换（规划 / 写作 / 检测智能体）
-> F 评测链与知识链切换（评委 / 抽取智能体）+ 对照实验与旧路径终态裁决
-> G 创作台对齐（待审 / 卡片 / 链路透视 / 阅读）
```
A、B 可并行；C 依赖 A；E 依赖 D；F 依赖 E；G 依赖 D（链路透视数据）并随 E、F 逐步补全视图。真实模型调用只出现在 D、E、F，且每次需人工授权。
### 阶段 A：边界合同定义
- 意图：把第 4、5 节的组件边界与约束归属落为仓内唯一边界文档，后续所有改动按它归位。
- 边界：只写文档；对现有约束抽样登记"现在在哪层、应该在哪层"，形成错位清单，不修改代码。
- 验证：边界文档覆盖全部组件与约束类型；错位清单每项有具体文件位置；技能严格审计仍通过。
### 阶段 B：链路盘点与清理
- 意图：盘点全部模型调用路径、58 个技能、一次性脚本与散落设计文档，每项定终态归属，删除无消费者的遗留。
- 边界：4 条模型调用路径定终态--框架派发链为生产与评测主链；治理直调链为对照实验与内容模型任务；角色运行时链随直调链处置；批处理执行链定保留或退役。删除以零引用检索为依据。
- 验证：被删入口全仓零引用；全量离线清单无新增失败；单一提交可一次对比删除面。
### 阶段 C：角色合同与领域文档对齐目标形态
- 意图：按边界合同重写五个角色的角色合同、创作流程领域、智能体领域与主链图，明确主代理职责、智能体自主探索、授权管控。
- 边界：只改文档；只写目标合同与代码当前事实，不写待办措辞。
- 验证：文档交叉引用一致；与边界合同无矛盾；技能索引与严格审计通过。
### 阶段 D：能力建设
- 意图：给框架派发链补齐三块底座--只读工具 server、会话复用、依赖清单。
- 边界：工具 server 全部只读，复用现有取数端；会话复用使用框架原生会话机制，不自造；工具调用即依赖记录，不加新表。
- 验证：离线测试覆盖越权拒绝、会话续接、依赖清单完整性；一次真实派发查库可见每次读取的来源与版本。
### 阶段 E：生产链切换
- 意图：规划、写作、检测三个智能体接入框架派发；补证与重写删除写死上限，改为授权终态。
- 边界：只换执行节点，候选落库、CAS、人闸不动；防造假静态校验保留（引文必须真实存在于正文、哈希绑定、报告结构合法）。
- 验证：离线测试覆盖通过、缺口、冲突、造假引文拒绝；一次真实生产烟测停在人闸，查库核对候选、事件、依赖清单、模型调用无重复记账。
### 阶段 F：评测链与知识链切换 + 终态裁决
- 意图：评委与抽取智能体接入框架派发（评委保持圈定授权隔离）；用对照实验数据裁决直调链去留；处理写手探索冗余——生产链改为只给最小冻结输入（任务提示词 + 授权范围），由写作智能体真正自主探索取材，预组装完整上下文降为对照模式专用（2026-08-22 烟测实证：预组装下写手 0 次工具调用，探索无发生空间）。
- 第一部分（已完成，离线绿）：两阶段写手落地——探索阶段（只读工具，产出探索清单）与生成阶段（无工具，按回放资料单次成稿）分离；`--two-phase` 旗标；详见 `docs/plans/2026-08-22-阶段F-第一部分-两阶段写手-探索与生成分离.md`。
- 第二部分（已完成，真实派发通过）：抽取智能体接入框架派发（全量正文注入任务输入，工具白名单留给查重探索；机械校验失败一轮修复重派，仍不合法走保守收口）；候选 164 采纳后对第 3 章首次真实抽取产出 19 条草稿待人审；详见 `docs/plans/2026-08-22-阶段F-第二部分-知识链派发-抽取智能体.md`。
- 第三部分（已完成，真实盲评通过）：评委智能体经 `ModelRunner` 协议接入框架派发（圈定授权：实验无工具/生产预检只读检索；盲评合同与防泄漏校验全复用既有适配层）；候选 123 vs 164 真实盲评通过，164 四维领先与人采纳方向一致；详见 `docs/plans/2026-08-22-阶段F-第三部分-评测链派发-评委智能体.md`。
- 边界：对照只在显式对照模式运行；评测候选四层强制不可接受不变；知识草稿须经人确认转正。
- 第四部分（已完成，真实对照执行）：对照直调臂（同源探索输入 + 角色运行时直调）产出评测候选 167，机械门拒（复读细纲措辞）；框架臂候选 164 双门通过并经人采纳。裁决：创作生成的直调链退役，框架派发链为唯一创作生成链；直调链按阶段 B 终态仅留对照实验与内容模型任务；详见 `docs/plans/2026-08-22-阶段F-第四部分-对照实验与直调链终态裁决.md`。
- 验证：盲评隔离测试（禁看清单越权拒绝）；对照产出可比正文与成本数据；退役项零引用后删除。
### 阶段 G：创作台对齐（完成后按 §11 走最终验收）
- 意图：把现有看板与决策通道收敛为创作台五视图：阅读、待审、卡片、链路透视、决策。
- 第一部分（已完成，看板测试绿）：链路透视接线——运行详情页接事件账本（探索轨迹/模型回合/成本）与派发链父子导航；消解 §11 中"探索轨迹与事件链""依赖清单"两个接线缺口；详见 `docs/plans/2026-08-22-阶段G-第一部分-链路透视接线-事件账本与派发链.md`。
- 收尾（已完成）：任务包与运行工件在链路透视区块全量呈现（探索任务包/清单/摘要、生成任务包、上下文、管道结果）；§11 全矩阵走查完成并留验收记录 `docs/acceptance/2026-08-23-§11可见性对照验收-书12基线走查记录.md`：五类可见项全可见，授权终态行机制就绪待真实缺口运行。
- 边界：只读库；不拼模型调用命令；决策仍走唯一决策通道；artifacts 读侧迁到数据库与依赖清单投影。
- 验证：待审章节能看到候选、检查报告、依赖清单；链路透视能回放一次运行的任务包、探索轨迹与成本；既有看板测试与决策人闸测试通过。
## 9. 台账要求（每阶段强制）
每个阶段产出文件级处置台账，覆盖该阶段触碰的每一个文件与每一项遗留：
| 处置 | 必须写明 |
|---|---|
| 保留 | 保留原因：谁是它的现存消费者、它承担什么独有职责 |
| 修改 | 修改原因：依据哪条边界合同或阶段目标，改动前后职责差异 |
| 新增 | 新增原因：替代什么旧路径或填补什么合同空白，入口与使用路径 |
| 删除 | 删除原因：被什么替代、零引用证据、风险评估 |
| 遗留 | 遗留原因：为什么本阶段不处理、归属哪个后续阶段、当前风险 |
无消费者证据不得删除；无保留理由不得保留；兼容层（新旧并行）必须登记退出条件，不允许无限期双轨。
## 10. 总验证
每阶段过既有门禁：技能严格审计、架构边界测试、全量离线清单、零引用检索。涉及真实模型调用的阶段另做真实烟测，并以查库核对事件链、依赖清单与模型调用账为准。无自动化绿色证据不得声称完成。
## 11. 最终验收：新作品创作历程可见性对照（全部阶段完成后）
改造完成后，模拟一个新作品的完整创作历程，逐项对照书 12（深渊机神）当前在看板上的可见性。新作品走新智能体框架链路；书 12 可见的，新作品原则上必须可见；不可见的，必须在验收记录中说明原因（原因只能是：合同已被新形态替代、或属于某阶段的接线缺口）。
验收历程：
1. 新建作品，走完规划链：定盘 → 大纲 → 设定拆条 → 范式与文风 → 章细纲（规划智能体）。
2. 用新框架写作链写一章：写作智能体自主探索 → 机械门 → 检测智能体 → 候选落待审区。
3. 章后抽取知识卡草稿；经人确认后转正。
4. 人采纳候选 → 正式正文。
可见性对照矩阵（基线 = 书 12 当前在看板可见）：
| 内容 | 书 12 可见位置 | 新作品要求 | 已知差异原因 |
|---|---|---|---|
| 作品、章节、正式正文 | /works、/works/<id>/ch/<n> | 必须可见（正文表合同不变） | 无 |
| 候选与待审状态 | /candidates、/candidates/<id> | 必须可见（候选表合同不变） | 无 |
| 运行回执、质量结果、模型调用账 | /runs/<id> | 必须可见（三表继续写入） | 无 |
| 知识卡（草稿/转正） | /knowledge | 必须可见 | 无 |
| 探索轨迹与事件链（example_agent_event） | 书 12 无此数据 | 必须可见 | 看板尚未接事件账本（阶段 G 接线；书 12 时代没有事件账本，无基线可比，属新增可见项） |
| 依赖清单（本次运行实际读了什么） | 书 12 无此数据 | 必须可见 | 同上，阶段 G 接线 |
| 生产 artifacts（pipeline-result 等） | /runs/<id> 读 docs/write-chapter/artifacts/ | 新框架运行的审计件在运行目录与库内投影，不写旧 artifacts 目录 | 合同替代：旧文件快照 → 运行目录 + 依赖清单 + 事件账本（阶段 G 读侧迁移） |
| 授权终态与缺口报告 | 书 12 无此数据 | 必须可见（运行终态与报告在看板可读） | 新增可见项 |
验收规则：
- 对照矩阵逐项走查，截图或查询记录为证；每项标注「可见 / 不可见 + 原因」。
- 不可见且原因是「接线缺口」的，必须登记归属阶段并补齐后复验。
- 新作品的候选、待审、正文、卡片、链路记录五类全部可见，或每个缺口都有成立的原因，验收才算通过。
- 验收全程不得把测试数据伪装成书 12 的历史数据；新作品用独立作品行与独立运行记录。

49
docs/plans/2026-08-22-阶段A-边界合同定义.md
View File

@ -1,49 +0,0 @@
# 阶段 A：边界合同定义
日期：2026-08-22
总 plan：[2026-08-22-agent-example整体收敛总plan.md](2026-08-22-agent-example整体收敛总plan.md)
状态：已完成（本文件同时是阶段 A 台账与验证记录）。
## 1. 意图
把总 plan 第 4、5 节的组件边界与约束归属落为仓内唯一边界文档 [`.agent/docs/architecture/边界合同.md`](../../.agent/docs/architecture/边界合同.md)，后续所有改动按它归位。
## 2. 边界
- 只写文档，不修改任何代码。
- 对现有约束抽样登记"现在在哪层、应该在哪层"，形成错位清单；错位项本阶段不修。
- 用户已有的候选设计文档不碰。
## 3. 错位清单（抽样登记，非穷尽）
| # | 位置 | 现状 | 应属层（按边界合同） | 处置归属 |
|---|---|---|---|---|
| 1 | `run_writer_pipeline.py:33-34`（`MAX_EVIDENCE_REQUESTS=3`、`MAX_REWRITES=2`） | 补证/重写业务上限写死在脚本层，且被 05 领域文档记录为"已落地编排合同" | 业务继续/停止归主代理向人请求授权；脚本只保留技术保护 | 阶段 E |
| 2 | `produce_next_chapter.py:113`（`GATE_ANCHORS` 按章字典） | 章级机械门锚数据硬编码在脚本代码里，新章必须改代码才能登记 | 章级验收数据归数据层（库或 meta），机械门执行留脚本 | 阶段 E |
| 3 | `角色合同.md` writer 节（"唯一事实来源是冻结任务输入""不读写工作区"） | 写手的数据可访问范围以提示词层合同表达，等于剥夺探索能力 | 数据可访问范围归工具层白名单；提示词只保留写作纪律 | 阶段 C（改合同）+ 阶段 D（工具落地） |
| 4 | `角色合同.md` frontmatter `modelPolicy` 与 `muse_role.py:36-43`（`FIXED_OPUS_*` 常量） | 同一模型策略在合同文档与代码两处各自声明，存在漂移风险 | 策略事实源唯一（中央角色合同），代码只校验不自行声明 | 阶段 C 统一口径，随阶段 B/F 直调链终态一并收口 |
| 5 | `produce_next_chapter.py:107`（`ARTIFACTS = docs/write-chapter/artifacts`） | 运行时产物目录放在 `docs/` 下，看板从文件系统读运行展示 | 运行数据归数据库与运行目录投影；docs/ 只留文档 | 阶段 G |
| 6 | `dashboard/server.py:2482`（决策菜单生成「改」重产命令文本） | 视图层为人生成 shell 执行命令 | 创作台只读库、展示链路输入输出，不产执行命令 | 阶段 G |
| 7 | 评委角色（盲评链 `execute-role-task` 无会话进程，角色文件却声明 `tools: read, grep, find, ls`） | 实际执行无工具，角色文件工具提示与实际白名单长期不一致 | 角色文件可解释工具，但声明的工具应与该角色场景白名单相符 | 阶段 C（合同对齐时明确评委圈定授权两场景） |
抽样覆盖层：脚本层（#1、#2）、提示词层（#3）、双源（#4）、数据层（#5）、视图层（#6）、角色文件一致性（#7）。工具层当前整体缺失（无工具 server），是阶段 D 的建设对象，不属于错位项。
## 4. 文件台账（阶段 A 触碰的全部文件）
| 处置 | 文件 | 原因 |
|---|---|---|
| 新增 | `.agent/docs/architecture/边界合同.md` | 填补"组件边界与约束归属无唯一事实源"的合同空白；入口为架构索引、`.agent/_index.md` 与 AGENTS.md SoT 表；内容为六组件职责边界表、七类约束归属表、三层提示词结构、探索授权模式、证据责任，全部为目标合同表述，不含过程措辞 |
| 新增 | `docs/plans/2026-08-22-agent-example整体收敛总plan.md` | 总 plan 落盘（意图两线、目标链路、创作台五视图、组件边界、五智能体五链、阶段 A–G、台账要求、总验证） |
| 新增 | `docs/plans/2026-08-22-阶段A-边界合同定义.md` | 本文件：阶段 A 细节、错位清单、文件台账与验证记录 |
| 修改 | `.agent/docs/architecture/_index.md` | 登记边界合同入口（目录纪律：新增文档必须同步 _index.md） |
| 修改 | `.agent/_index.md` | 同上，长期知识索引补边界合同行 |
| 修改 | `AGENTS.md` | SoT 表补边界合同行，声明其"唯一事实源"地位 |
| 遗留 | 错位清单 #1–#7 | 本阶段只登记不修；各归属阶段处理时按总 plan 台账要求单独出处置理由 |
| 遗留 | 工作树中上一轮清理的未提交改动（05 领域文档、produce_next_chapter.py、已删 write-chapter 旧脚本） | 属上一轮链路清理产物，待用户决定提交；不属于阶段 A 范围 |
## 5. 验证
- 边界合同覆盖全部组件（主代理、五智能体、Skill、工具 server、脚本、静态校验、创作台）与约束类型（提示词、角色合同、工具、静态、脚本+数据库、架构门禁、授权管控）：见文档 §1、§2。
- 错位清单每项有具体文件位置与行号：见 §3。
- 技能严格审计：`skill_harness.py --strict` 通过，58 个 Skill，阻断 0，质量发现 0。
- Skill 索引一致性：`skills_index.py --check` 通过，索引与磁盘、skills.json 相符。

107
docs/plans/2026-08-22-阶段B-链路盘点与清理.md
View File

@ -1,107 +0,0 @@
# 阶段 B：链路盘点与清理
日期：2026-08-22
总 plan：[2026-08-22-agent-example整体收敛总plan.md](2026-08-22-agent-example整体收敛总plan.md)
状态：已完成（本文件同时是阶段 B 台账与验证记录）。
## 1. 意图
盘点全部模型调用路径、58 个 Skill、一次性脚本与散落设计文档，每项定终态归属，删除无消费者的遗留。
## 2. 四条模型调用路径终态判定
| 路径 | 当前消费者（取证于 2026-08-22） | 终态 | 依据 |
|---|---|---|---|
| 框架派发链（dispatch-agent-task） | 仅测试与自身；无生产消费者 | **生产与评测主链**（阶段 E/F 接入） | 总 plan 目标架构；pi 会话机制已验证可用 |
| 治理直调链（muse_llm.chat_governed） | 8 个 Skill 脚本：call-content-model、clean-book-text、deconstruct-book×3、extract-chapter-knowledge、repair-work-extraction、review-knowledge-cards | **保留：内容模型任务主链 + 对照实验生成** | 消费者全部是清洗/拆书/抽取/审卡等内容模型任务，无角色场景；对照模式归阶段 F |
| 角色运行时链（muse_role.run_role） | 6 个消费方：evaluate-frozen-replay、refresh-runtime-probe、replay-writer-gate×2、write-next-chapter×2 | **保留至阶段 E/F 切换，随后随直调链处置** | 全部是角色调用场景，属框架派发链的目标替换对象 |
| 批处理执行链（execute-role-task） | SKILL.md 文档引用（评测链角色调用入口）；无独立脚本消费者 | **保留：无工具直接批处理角色任务** | 与框架派发链职责不同（无 ReAct 循环、无会话）；边界合同已登记两者并列关系 |
判定含义：本阶段**无路径删除**。四条路径各有现存消费者，全部符合或终态符合边界合同；角色运行时链的生产替换发生在阶段 E，评测替换在阶段 F，替换后按零引用再删。
## 3. Skill 层盘点结论
58 个 Skill 全部有机械登记（skills.json、_index.md）之外的真实引用（meta/chains、领域文档、测试、其他 SKILL.md、dashboard）。**无删除候选**。工具层（工具 server）当前整体缺失，属阶段 D 建设对象，不是清理对象。
## 4. 文档清理
### 4.1 删除（24 份，全部零引用）
**样张快照（7 份）**--数据权威在库，文档是当时展示快照，Git 历史可回溯：
- `2026-07-13-B2放量-5书50章-216卡样张.md`（正式卡在库）
- `2026-07-13-S3新卡39张样张.md`（"库内活卡"）
- `2026-07-16-批9终态样张-升格机动.md`（559 张升格卡，数据在库）
- `2026-07-16-批9终态样张-升格深空.md`
- `2026-07-16-批9终态样张-范式五书.md`
- `试拆-门②样张.md`
- `试拆-opus基准-机动风暴.md`
**已执行完的一次性计划/记录（6 份）**--稳定结论已蒸馏进领域文档、DDL 或父仓 SoT：
- `2026-07-13-M3清洗拆书执行计划.md`（清洗已全部落库，见 4.3 库证据）
- `2026-07-13-S3窗级出卡验收报告.md`（验收完成，管线已投产）
- `2026-07-13-B4-fable独立审查报告.md`（自称"SoT"实为历史执行；后续批9 全量重审已取代）
- `2026-07-19-回放评测-细纲首跑设计与计划.md`（首跑完成，结论蒸馏进 08-01 评测 harness 设计与领域文档）
- `2026-07-24-Gate-A-正文智能体职责重构记录.md`（自称"历史执行记录，非 SoT"；引用的 `.claude/` 路径已不存在）
- `2026-07-24-work8-窗108-116续跑修复记录.md`（一次性修复记录）
**清洗审核材料（9 份）**--对应 8 个作品的清洗已全部落库（`example_clean_log` 有 work 2/3/4/6/7/8/10/11 的记录，共 1685 条），报告是历史人审材料：
- `清洗-2-希泊尼战纪.md` ~ `清洗-11-超神机械师.md`（8 份）
- `清洗质检-机破星河前50章.md`
**过程锚点与内部执行记录（2 份）**：
- `2026-07-16-批9c-收官与优化方案.md`（compact 恢复锚点；自带处置指令"任务完成后蒸馏进 README §九 并删本文档"；稳定产物已有独立落点：代码提交、升格卡改造设计、升格级联重跑设计）
- `2026-07-17-卡的第一性原理与知识效用闭环.md`（自称"内部执行记录，不是交付物"；交付物=父仓 design-docs 专题-07 等已落盘）
### 4.2 保留（9 份）
| 文档 | 保留原因 |
|---|---|
| `2026-07-14-参考书作品面数据入库方案.md` | 被 DDL 94、升格卡改造设计引用 |
| `2026-07-16-升格卡改造设计.md` | 被 meta/schemas（faction/item/power_system）引用 |
| `2026-07-21-升格级联重跑设计.md` | 执行状态未完成（备份/恢复演练/重建未执行），是未完成工作的依据 |
| `2026-07-30-落库与看板设计.md` | 被 DDL 99/101/102 引用，raw 与落库合同的设计拍板记录 |
| `2026-08-01-评测harness改造设计.md` | 被领域文档 05/06 引用 |
| `2026-08-19-craft-distillation-trace.md` | 被 skill 质量审查清单引用 |
| `2026-08-20-skill-质量审查与复利改造清单.md` | 被 harness/README 引用 |
| `2026-08-20-质量收敛环运行手册.md` | 被 optimize-content-quality SKILL 引用 |
| `2026-08-19-evaluate-frozen-replay-raw边界冲突.md` | **待所有者裁决**：文档自称"待裁决"，虽取证显示合同层已对齐 DB-first（评测链 SKILL.md 已写"完整 prompt/response 只经 record-run-evidence 写入受控 raw 表"，run_role 内部走 persist_call 落库，vault 降为仓外备份），但按仓规缺显式所有者批准不得代为关闭；裁决后删除或归档 |
### 4.3 库证据
清洗落库核对（`example_clean_log` 按 work 聚合）：work 2（49）、3（61）、4（163）、6（107）、7（566）、8（20）、10（596）、11（123）--删除的 9 份清洗材料对应作品全部有落库记录。
## 5. 上一轮清理的并入
工作树中上一轮"清理冗余链路"的未提交改动并入本阶段提交（同属链路清理语义）：
- 删除 `docs/write-chapter/step1_setup_work.py`、`step2_setup_chapter2.py`、`step2_setup_chapter3.py`、`step2a_retrofit_ch1_context.py`、`step2a_write_chapter1.py`（5 份无调用方的一次性建章脚本；其中 step2a_write_chapter1 含绕过人闸的直接 accept 路径）
- 修改 `produce_next_chapter.py`（删除对旧建章脚本的说明，改为数据库前置条件）
- 修改 `05-创作流程领域.md`（统一使用 produce_next_chapter.py 入口）
## 6. 文件台账（阶段 B 触碰的全部文件）
| 处置 | 文件 | 原因 |
|---|---|---|
| 删除 | docs/ 下 24 份（见 §4.1） | 零引用 + 已落库/已蒸馏/已被取代，逐份理由见 §4.1 |
| 删除 | docs/write-chapter/step*.py ×5 | 上一轮清理遗留：无调用方的一次性入口（并入提交） |
| 修改 | produce_next_chapter.py、05-创作流程领域.md | 上一轮清理遗留的引用修正（并入提交） |
| 保留 | docs/ 下 9 份（见 §4.2） | 逐份理由见 §4.2 |
| 保留 | 58 个 Skill、四条调用路径 | 见 §2、§3：全部有真实消费者 |
| 保留 | dashboard/fixtures/ | 离线回退数据，被 server.py 引用 |
| 新增 | 本文件 | 阶段 B 台账与验证记录 |
| 遗留 | raw 边界冲突裁决 | 待用户裁决（§4.2 末行）；裁决后处置 |
| 遗留 | `2026-07-21-升格级联重跑设计.md` 的未完成执行 | 属知识链工作，归阶段 F 或另行立项 |
| 遗留 | 用户候选文档 `docs/design/candidates/初步设定候选-统合.md` | 用户未提交改动，不属于本阶段范围，不触碰 |
## 7. 验证
- 被删文档全仓零引用：`rg` 检索被删文件名关键词，除本计划文档外无残留（含互引收敛后追加删除的批9c、第一性原理两份）。
- 技能严格审计：`skill_harness.py --strict` 通过，58 个 Skill，阻断 0，质量发现 0。
- Skill 索引一致性：`skills_index.py --check` 通过。
- 全量离线清单：101 通过、8 项外部依赖阻断、0 失败，与阶段 A 基准一致。
- 架构门禁：`test_import_boundaries` + `test_skills_index` 全部通过。
- `git diff --check`：通过。

49
docs/plans/2026-08-22-阶段C-角色合同与文档对齐.md
View File

@ -1,49 +0,0 @@
# 阶段 C：角色合同与领域文档对齐目标形态
日期：2026-08-22
总 plan：[2026-08-22-agent-example整体收敛总plan.md](2026-08-22-agent-example整体收敛总plan.md)
状态：已完成（本文件同时是阶段 C 台账与验证记录）。
## 1. 意图
按边界合同重写五个角色的角色合同、创作流程领域、智能体领域与主链导读，明确主代理职责（润色与授权协调）、智能体自主探索、补证/重写由人管控。
## 2. 边界
- 只改文档与角色提示，不改任何代码。
- 只写目标合同与代码当前事实，不写待办措辞（导读中"当前实现"标注沿用该文档既有惯例）。
- 不动错位清单中归属代码阶段的项目（#1、#2、#5、#6）。
## 3. 错位清单处置
| # | 项目 | 本阶段处置 |
|---|---|---|
| #3 | 写手探索限制以提示词层合同表达 | 已处置：角色合同 writer 节改为"经授权只读技能自主探索 + 依赖清单"；工具落地归阶段 D |
| #4 | 模型策略合同文档与代码双源 | 文档侧已处置：角色合同声明"本文件是模型策略事实源，执行侧常量是镜像，不一致即缺陷"，07 领域同步；代码侧合并归阶段 F |
| #7 | 评委角色文件声明工具与实际不符 | 已处置：角色合同与角色文件明确评委为圈定授权（实验场景最窄 / 生产预检放宽 + 禁看清单），与实际白名单机制一致 |
## 4. 文件台账
| 处置 | 文件 | 原因 |
|---|---|---|
| 修改 | `.agent/docs/architecture/角色合同.md` | 五个角色合同按目标形态重写：探索与取材/取证节、依赖清单要求、评委圈定授权与禁看清单；头部改为引用边界合同，声明模型策略事实源地位 |
| 修改 | `.agent/docs/architecture/domains/07-Agent与Skill领域.md` | §1 引边界合同；§2 四类执行单元改为五组件（主代理/创作智能体/工具 server/脚本与静态校验），派发合同六条（含会话复用与依赖清单）；§5 改为目标工作链与授权管控（无业务次数硬上限）；§7 运行底座改为三条链分工 |
| 修改 | `.agent/docs/architecture/domains/05-创作流程领域.md` | §5 改为目标工作链与编排合同（主代理职责、授权终态、防造假校验），保护步骤 6 条保留；当前实现事实单列；§6 补证口径改为"技术保护上限，业务授权归人" |
| 修改 | `.agent/docs/architecture/创作周期与Skill导读.md` | 角色定位改主代理职责；五角色说明补"都是创作智能体、圈定授权例外"；节点 W 主链图改目标形态并标注当前实现；合同索引加边界合同行 |
| 修改 | `.agent/agents/writer.md` | 加探索方法（细纲→人物→前文→世界规则→依赖清单）；工具提示改"探索只读" |
| 修改 | `.agent/agents/detector.md` | 加取证方法（对照细纲→检索正典→回读知情范围→查规则→引文回指） |
| 修改 | `.agent/agents/planner.md` | 加探索方法（上层规划→既有设定→承接点→依赖清单） |
| 修改 | `.agent/agents/extractor.md` | 加探索方法（回读正文→查既有卡→低置信标注） |
| 修改 | `.agent/agents/judge.md` | 加授权与取证节：圈定授权两场景 + 禁看清单（候选身份、oracle、他评结果） |
| 保留 | 派发装配合同与测试断言 | 系统提示词四段结构（身份+合同+Schema+冻结输入）不变，测试全绿 |
| 遗留 | 错位 #4 代码侧（muse_role 常量与合同统一） | 归阶段 F 直调链终态处置 |
| 遗留 | 生产链预组装上下文与目标探索形态的差异 | 归阶段 E 切换 |
## 5. 验证
- 派发装配测试（系统提示词四段结构、合同哈希、角色合同装载）：20 项通过。
- 细纲合同测试（planner.md 含 fine_outline）：6 项通过。
- 角色目录登记与合同装载测试：7 项通过。
- 角色目录校验：5 个角色、58 个 Skill 一致。
- 技能严格审计：58 个 Skill，阻断 0，质量发现 0。
- Skill 索引一致性：通过。

63
docs/plans/2026-08-22-阶段D-能力建设.md
View File

@ -1,63 +0,0 @@
# 阶段 D：能力建设（只读工具 server / 会话复用 / 依赖清单）
日期：2026-08-22
总 plan：[2026-08-22-agent-example整体收敛总plan.md](2026-08-22-agent-example整体收敛总plan.md)
状态：完成（含真实派发验证，见 §4 末节）。
## 1. 意图
给框架派发链补齐三块底座：只读工具 server、会话复用、依赖清单。
## 2. 实现落点
### 2.1 只读工具 server（边界合同的工具层组件）
- `read_tools.py`：五个登记工具，单一事实源 `TOOL_REGISTRY`（名称、描述、读取表、参数说明、实现）：
- `read_fine_outline`（已确认细纲）、`read_style_constraints`（已确认文风投影）、`read_pattern_bindings`（已确认范式绑定）——查询语义与 assemble-context 三个一等取数端一致（工具 server 按边界合同自持实现，不跨 Skill 导入）。
- `read_chapter_text`（章节正式正文，30000 字截断标记）、`search_entities`（实体模糊检索，50 行上限）。
- 只读连接 `muse_db.connect(readonly=True)`；未知工具/非法参数合同拒绝（退出码 2）；`--list` 输出登记表。
- `muse_read_tools_extension.ts`：框架扩展，装载时从 `--list` 动态注册工具（不硬编码工具清单，防双源漂移）；每次执行转给只读实现；派发器未注入环境变量时不注册任何工具。
- 派发器经 `-e` 显式加载该扩展；`--no-extensions` 只禁自动发现（框架资源加载器合同已核实），隔离与工具加载共存。
- 派发门禁：任务白名单含登记表工具名但未 `--enable-read-tools` 时，运行前失败关闭（READ_TOOLS_NOT_ENABLED）。
### 2.2 会话复用
- `ExecutionPolicy` 增加 `session_id` / `session_dir`（同给或同缺，否则构造拒绝）；`build_pi_argv` 映射为框架原生 `--session-id` + `--session-dir`（不自造会话存储）。
- 派发语义：每次派发仍是一次独立运行记录；会话连续通过共享会话目录实现——同一章补证/修改传前次运行的会话 ID 与会话目录继续原会话；完全重写新建。
- CLI 新增 `--session-id` / `--session-dir` / `--enable-read-tools`。
### 2.3 依赖清单
- 框架工具事件携带参数（`tool_execution_start.args`）；适配器捕获进 `ToolCallRecord.args`，截断后随 `tool.started` 事件入账本。
- 成功运行把工具调用序列写为运行目录 `dependencies.json`（seq/tool/args/isError）；回执含 `dependencies` 摘要（count/file）。无工具调用不产文件。
- 不加新表：事件账本 + 运行目录审计件承载；创作台链路透视（阶段 G）读这两处。
## 3. 文件台账
| 处置 | 文件 | 原因 |
|---|---|---|
| 新增 | `scripts/read_tools.py` | 填补边界合同工具层空白：探索读取的唯一受控入口；登记表为单一事实源；入口为扩展装载与测试 |
| 新增 | `scripts/muse_read_tools_extension.ts` | 工具 server 的框架适配：只从登记表动态注册，无第二套工具清单；经派发器 `-e` 加载 |
| 修改 | `scripts/pi_runner.py` | 会话复用字段与 argv、扩展加载、工具参数捕获（依赖清单材料）；职责仍是薄适配，无业务决策 |
| 修改 | `scripts/dispatch_agent_task.py` | 三个 CLI 开关、工具门禁、环境变量注入、依赖清单写入、回执字段 |
| 修改 | `SKILL.md`（dispatch-agent-task） | 登记新模块、命令参数、事件与依赖清单合同、工具 server 红线 |
| 新增 | `tests/skills/dispatch-agent-task/test_read_tools.py` | 工具合同离线测试：五工具行为、拒绝路径、登记表 CLI、扩展动态装载对账 |
| 修改 | `tests/skills/dispatch-agent-task/test_dispatch_agent_task.py` | 新增 5 项：会话成对校验与 argv、扩展标志、工具参数捕获、工具门禁失败关闭、依赖清单产出 |
| 修改 | `harness/manifests/test-inventory.json` | 登记新测试条目，摘要同步重算（110 条） |
| 保留 | `execute-role-task`、直调链 | 阶段 F 裁决对象，本阶段不动 |
| 遗留 | 无 | 真实派发验证已完成（见 §4） |
## 4. 验证
- 工具离线测试：10 项通过（五工具行为、拒绝路径、登记表、扩展对账）。
- 派发测试：25 项通过（原 20 项 + 会话/工具/依赖清单 5 项）。
- 选择器定向：新增两条目通过。
- 全量离线清单：102 通过、8 项外部依赖阻断、0 失败（较阶段 C 基线 +1 条目）。
- 技能严格审计：58 个 Skill，阻断 0，质量发现 0；索引一致性通过。
- 架构门禁（导入边界 + 索引）：通过。`git diff --check`：通过。
- 真实派发验证（2026-08-22，人工授权冒烟）：显式 `catproxy-anthropic/claude-opus-5`、思考 low、planner 角色、工具白名单 `read_fine_outline` + `search_entities`，运行 `agent-smoke-explore-20260822T175440Z`：
- 扩展动态注册生效：智能体自主发起 5 次只读探索（读第 3 章确认细纲、检索林深/裴朔/生物机甲茧），5 回合模型调用全部实际模型匹配；
- 事件账本逐条可见：`tool.started`/`tool.completed` 携带参数（读了什么表、什么条件）；
- `dependencies.json` 完整（seq/tool/args/isError），运行目录权限 0700/0600；
- 结构化输出通过 Schema；实体检索零命中时智能体如实报告“未入库”，未编造事实；
- 模型调用账 5 条（`window_key=NULL` 按 run 归属）；raw 三件套落库，租约闭合；供应商未返回可计价成本，未伪造。

50
docs/plans/2026-08-22-阶段E-生产链切换-第一部分-授权终态.md
View File

@ -1,50 +0,0 @@
# 阶段 E：生产链切换（第一部分：授权终态合同）
日期：2026-08-22
总 plan：[2026-08-22-agent-example整体收敛总plan.md](2026-08-22-agent-example整体收敛总plan.md)
状态：第一部分完成并提交；第二部分（写作/检测智能体接入框架派发、授权后继续的接线、真实生产烟测）另行启动，真实模型调用需人工授权。
## 1. 意图
删除补证/重写的业务硬上限（补证≤3 / 重写≤2），改为授权终态：检查发现缺口后系统停在结构化报告，由主代理转述给人，人授权后以新运行继续。技术保护（超时、预算、取消）保留在执行策略层。
## 2. 合同设计（本部分核心决策）
授权门只挡昂贵的模型重调用，不挡廉价的确定性检索：
```text
语义检查发现证据缺口
→ 确定性检索（evidence_provider，只读、无模型开销）
├─ 零命中 = 新设定提案 → 升格 passed 进人闸（原行为保留）
└─ 命中 = 需要模型重写 → AUTHORIZATION_REQUIRED 授权终态
携带：缺口清单、机械/语义检查快照、下一 attempt、重组上下文哈希
人授权后：编排方以新运行继续（新候选版本，会话可复用）
```
依据：CAS 链按运行唯一（`ON CONFLICT (run_id) DO NOTHING`），同运行不能开新轮；授权后的继续天然是新运行，与"一章复用同一写作智能体会话"通过框架会话续接（阶段 D 能力）组合。
## 3. 文件台账
| 处置 | 文件 | 原因 |
|---|---|---|
| 修改 | `run_writer_pipeline.py` | 删除 `MAX_EVIDENCE_REQUESTS/MAX_REWRITES` 常量、自动补证/重写循环与两个上限错误码；缺口分支改为"检索→零命中升格/命中授权终态"；单次收敛文档化。CAS 基元（含 `start_next`）保留，状态机闭集不动 |
| 修改 | `produce_next_chapter.py` | AUTHORIZATION_REQUIRED 显式分支：输出结构化缺口报告与授权指引；模块头口径同步 |
| 修改 | `test_run_writer_pipeline.py` | 两个自动补证测试改写为授权终态合同（缺口停终态、授权报告落结果文件）；provider 改为真实检索推进 |
| 修改 | `test_production_evidence_reassemble.py` | 命中重写测试改为授权终态（写手单次调用、details 带 nextAttempt 与重组上下文哈希）；零命中升格测试不变 |
| 修改 | `test_candidate_cas.py` | CAS 上的补证环测试改为授权终态链断言（create→CHECKING→REJECTED，revision=3） |
| 修改 | `test_writer_acceptance.py` | 失败码 fixture 对齐（REWRITE_LIMIT_REACHED → AUTHORIZATION_REQUIRED） |
| 修改 | `05-创作流程领域`、`write-next-chapter/SKILL.md`、`dashboard/server.py` 注释 | 补证口径全仓同步（检索语义不变、命中停授权终态） |
| 保留 | `production_evidence_reassemble.py` | 确定性检索是新合同的组成部分（授权前置检索），职责不变 |
| 保留 | `start_next` 等 CAS 基元 | 总 plan 不重造状态机；续跑走新运行的 `create` 链 |
| 遗留 | 授权后继续的编排接线（新运行 + 重组上下文 + 会话续接） | 阶段 E 第二部分 |
| 遗留 | 写作/检测智能体框架派发接入 | 阶段 E 第二部分；真实烟测需人工授权 |
## 4. 验证
- 管线测试：10 项通过（含授权终态 2 项新合同测试）。
- 补证重组装测试：5 项通过（命中授权终态 + 零命中升格）。
- CAS 测试：离线全通过；真实库集成测试（PostgresCasStateStore）全部通过。
- 候选接受测试：通过（失败码对齐后）。
- 全量离线清单：102 通过、8 项外部依赖阻断、0 失败。
- 技能严格审计：58 个 Skill，阻断 0；索引一致性、架构门禁、`git diff --check` 通过。
- 旧口径零残留：`补证≤3 / 重写≤2 / EVIDENCE_REQUEST_LIMIT / REWRITE_LIMIT` 全仓检索无生产代码引用（写手篇幅适配器的"≤3 遍重抽"是独立技术重试合同，不属于补证/重写，保留）。

44
docs/plans/2026-08-22-阶段E-生产链切换-第二部分-派发接线与授权继续.md
View File

@ -1,44 +0,0 @@
# 阶段 E：生产链切换（第二部分：派发接线与授权继续）
日期：2026-08-22
总 plan：[2026-08-22-agent-example整体收敛总plan.md](2026-08-22-agent-example整体收敛总plan.md)
状态：离线接线完成并提交；真实生产烟测（一章正文经派发链生成、停在人闸）待人工授权。
## 1. 意图
把写作节点接入框架派发链（可选显式模式），把授权终态接成可继续的流程：授权请求留痕、人授权后以新运行继续补证。证据归属按边界合同分界：智能体框架负责模型事件、raw、逐回合调用（记派发运行）；生产编排负责候选、CAS、质量结果与业务回执（记生产运行）；两者以显式证据引用关联，禁止同一模型回合两套记账。
## 2. 实现落点
- `dispatch_writer_bridge.py`（新增）：写作智能体派发桥。任务包装配（角色=writer、冻结创作输入、输出 Schema=candidateBody、探索白名单=工具 server 登记表全部只读工具）；会话按作品/章稳定（`writer-work{W}-ch{T}`，跨运行复用同一写作智能体）；产出经可信信封绑定（身份、哈希、版本由桥绑定，模型只产正文）；证据引用从派发运行调用账读取，缺则失败关闭。
- `produce_next_chapter.py`：
- `--dispatch-writer --provider --model [--thinking]`：写作节点走派发链，失败关闭（不做篇幅自动重抽，篇幅合同由机械门把关）。
- `AUTHORIZATION_REQUIRED` 时留痕 `artifacts/<run_id>-authorization-request.json`（缺口、下一 attempt、重组上下文哈希、候选哈希、人指令）。
- `--continue-from <前序 run_id>`：校验授权请求的作品/章匹配后，按缺口补证重组上下文，以新运行继续；运行登记记录 `continueFrom` 与 `writerMode`。
- 两处候选落库透传 `writer_raw_ref`（直调链为 None，走原有本运行查账）。
- `persist_writer_run.py`：`persist_writer_execution` 增加可选 `writer_raw_ref`；给则用显式引用（缺项失败关闭），不给则维持原有本运行查账的严格合同。
## 3. 文件台账
| 处置 | 文件 | 原因 |
|---|---|---|
| 新增 | `scripts/dispatch_writer_bridge.py` | 生产链接入框架派发链的唯一桥；入口为 `produce_next_chapter --dispatch-writer` |
| 修改 | `scripts/produce_next_chapter.py` | 派发模式、授权请求留痕、授权继续、证据引用透传；诊断逻辑提取为助手函数复用 |
| 修改 | `scripts/persist_writer_run.py` | 显式证据引用路径；直调链合同不变 |
| 新增 | `tests/.../test_dispatch_writer_bridge.py` | 桥合同离线测试：任务包冻结、会话稳定、信封绑定、派发失败与缺证失败关闭（5 项） |
| 修改 | `tests/.../test_persist_writer_run.py` | 显式引用绕过本运行查账、引用缺项失败关闭（2 项） |
| 修改 | `SKILL.md`（write-next-chapter） | 登记派发模式、授权继续与证据分界合同 |
| 修改 | `harness/manifests/test-inventory.json` | 登记新测试条目（111 条） |
| 保留 | 直调链（默认模式） | 对照与回退路径；终态裁决归阶段 F |
| 遗留 | 真实生产烟测 | 需人工授权（一章正文，派发链，停在人闸） |
| 遗留 | 检测智能体派发化 | 语义检测仍走直调链；接入框架派发归阶段 F（含评委） |
## 4. 验证
- 桥离线测试：5 项通过（任务包装配、会话按章稳定、成功绑定信封+证据引用、派发失败关闭、缺证失败关闭）。
- 落库显式引用测试：2 项通过；原有 2 项不回归。
- write-next-chapter 全部测试：10 个文件全过（含真实库 CAS 集成）。
- 架构门禁：导入边界与索引测试通过（跨 Skill 引用遵循既有先例方式）。
- 全量离线清单：103 通过、8 项外部依赖阻断、0 失败（较第一部分基线 +1）。
- 技能严格审计：58 个 Skill，阻断 0；索引一致性通过。
- 真实生产烟测：待授权。建议参数：作品 12、目标章按库内进度、显式 `catproxy-anthropic/claude-opus-5`、思考等级待人定；验收按总 plan §11 的可见性矩阵走查。

79
docs/plans/2026-08-22-阶段F-第一部分-两阶段写手-探索与生成分离.md
View File

@ -1,79 +0,0 @@
# 阶段 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`） | 无需新增；本次人工提前清理仅为节省等待 |
| 候选过双门后接受前置检查报 `CONTEXT_NOT_FROZEN`，人闸被阻 | 冻结幂等键为 `manifest_sha256` 单键；检索清单跨运行不变而上下文每次不同，新冻结永远 `ON CONFLICT DO NOTHING` 回读旧行 | 迁移 `db/ddl/114-example冻结幂等键-清单加上下文对.sql`：唯一键改 `(manifest, context)` 对；`persist_freeze` 同步改冲突键与回读条件；补落候选 164 冻结行后复验 `ACCEPTANCE_INTENT_READY`；新增零污染真实库测试 |
| 令牌经命令行传入在进程表可见 | tmux 命令串内嵌环境变量赋值 | 改用 600 权限环境文件注入；运行结束后轮换 `MUSE_AI_NEW_API_TOKEN` |
## 6. 真实验证结果（2026-08-23）
`run-prod-work12-ch3-42beb650`（opus-5 high，指令留空）：
- 探索阶段：约 2 分钟，5 份材料；生成阶段：无工具单条成稿，无碎片化；AI 味诊断 13 条。
- 机械门通过、语义检测通过；候选 164（candidate_version=9）落库 `state=passed, semantic_status=passed`。
- 冻结缺陷修复后接受前置检查复验：`ACCEPTANCE_INTENT_READY`——候选停在人闸，等人在决策通道接受/拒绝。
## 7. 未决（下一阶段）
- 两阶段真实烟测通过后：两阶段成为生产默认形态，单阶段派发降级为对照模式；角色合同与领域文档同步改写（写手 = 探索阶段 + 生成阶段）。
- 评委与抽取智能体的框架派发接入、直调链终态裁决仍按总 plan 阶段 F 推进。

51
docs/plans/2026-08-22-阶段F-第三部分-评测链派发-评委智能体.md
View File

@ -1,51 +0,0 @@
# 阶段 F 第三部分：评测链派发——评委智能体
日期：2026-08-23
状态：已完成（离线绿 + 真实盲评通过）
上游事实：第 3 章候选 164 已采纳入正典；候选 123（v7，被机械门拒）与 164（v9，采纳）构成真实对比盲评样本。
## 1. 意图
评委智能体接入框架派发，保持圈定授权隔离；盲评编排（输入防泄漏校验、草稿逐字引文校验、有界纠错、报告哈希绑定）全部复用既有可信适配层，派发桥只实现 `ModelRunner` 协议。
## 2. 设计
```text
编排侧：取两个候选 → 匿名化（盲 ID 洗牌，映射只留编排侧工件）
→ 组装盲评输入（blind-judge v4：哈希全绑定，组装即过官方校验器）
↓
派发评委（每位评委独立新会话；任务输入 = 盲评模型输入本体，桥不附加身份）
圈定授权：实验场景无工具；生产预检开放 read_chapter_text/search_entities
↓
编排侧：草稿逐字引文校验（防编造）→ 有界纠错一轮 → 报告绑定回执哈希
↓
落库：example_quality_result（judge_kind=scoring）
```
关键取舍：
- 接入点是 `ModelRunner` 协议（`run_writer_blind_judge(blind_input, model_runner=...)`）：派发不触碰盲评合同本身。
- 隔离三层机械强制：输入侧防泄漏走查（官方校验器）、任务包与模型输入全等（桥不附加身份）、评委会话互相独立。
- 引文纪律是提示词层问题（模型可被说服）：任务提示词给出 evidenceRefs 的四种 sourceType 与精确 ID 空间（逐字选用，禁拼接描述词）。
- 报告落库枚举以库级 CHECK 约束为准（`scoring`），不自造未登记枚举。
## 3. 改动台账
| 文件 | 动作 | 原因 |
|---|---|---|
| `.agent/skills/score-content-quality/scripts/dispatch_judge_bridge.py` | 新增 | 圈定授权白名单 + `DispatchJudgeRunner`（ModelRunner 协议） |
| `.agent/skills/score-content-quality/scripts/judge_via_dispatch.py` | 新增 | 生产预检盲评入口：候选匿名化、盲评输入组装、报告落库 |
| `tests/skills/score-content-quality/test_dispatch_judge_bridge.py` | 新增 | 离线测试（10 项）：圈定白名单、任务包零身份、会话独立、失败关闭、盲评输入官方校验器回环 |
## 4. 验证结果
- 离线测试 10/10 通过。
- 真实盲评（候选 123 vs 164，battle 场景，opus-5）：
- 前两轮草稿因引文格式被机械校验拒绝（evidenceRefs 的 sourceId 拼接描述词）——失败关闭与有界纠错按合同工作；任务提示词补全引用合同（四种 sourceType 与精确 ID 空间）后第三轮通过。
- 第三轮报告（`run-blind-judge-w12-c3-20260823T155855`，judge_kind=scoring）：候选 164 在 5 维中 4 维领先（设定保真/细纲保真/文风一致/叙事张力），候选 123 仅正文可读性领先 0.5 分——与人采纳 164 的决定方向一致（独立证据）。
- 落库枚举错误（误用 `blind_judge`，库级 CHECK 只许 detection/scoring/review/experiment）当场被约束拦下——按 `scoring` 补落库并如实收口运行。
## 5. 未决
- 评委圈定授权的"禁看清单越权拒绝"专项测试（总 plan 验证项）留待对照实验阶段一起做。
- 直调链终态裁决（对照实验数据）与退役项删除按总 plan 阶段 F 收尾。

48
docs/plans/2026-08-22-阶段F-第二部分-知识链派发-抽取智能体.md
View File

@ -1,48 +0,0 @@
# 阶段 F 第二部分：知识链派发——抽取智能体
日期：2026-08-23
状态：已完成（离线绿 + 真实派发通过）
上游事实：候选 164 经决策通道采纳（署名 qingse），第 3 章正典落库（5131 字）；接受意图 `queue_chapter_extraction`。
## 1. 意图
抽取智能体接入框架派发（边界合同：智能体框架记模型事件/raw，生产编排记知识草稿与业务回执），替代抽取直调链的生产使用；直调链保留为对照/回退，终态裁决按总 plan 用数据说话。
## 2. 设计
```text
生产编排：注册抽取运行 → 读正典章全量正文 + 既有实体名
↓
派发抽取智能体（单次派发，探索与产出同一循环）：
输入 = 全量正文（注入，不经工具——工具读取会截断）+ 既有实体名 + 抽取合同
工具白名单 = read_chapter_text、search_entities（查重与回读核验用）
产出 = 结构化抽取 JSON（entities/relations/state）
↓
机械校验：normalize_extraction（证据必须正文逐字片段）
失败 → 一次修复重派（只纠证据绑定，不新增条目）→ 仍失败 → salvage 保守收口
↓
落库：persist_extraction（muse_knowledge_draft，草稿态）→ 人确认转正（:8766）
```
关键取舍：
- 正文注入而非工具读取：`read_chapter_text` 超长截断，证据逐字绑定要求全量正文，注入是唯一可靠路径；工具留给查重探索。
- 单次派发（非两阶段）：抽取产出是结构化 JSON，无长篇碎片化风险；探索与产出同循环。
- 机械校验与落库全部复用既有可信适配层（`normalize_extraction`/`salvage_extraction`/`persist_extraction`），不新造合同。
- 修复重派一轮（证据绑定是机械问题，对齐直调链既有语义）；仍不合法走 salvage；salvage 失败失败关闭。
- 证据归属：派发运行 `{run_id}-extractor-v{N}` 记事件/raw（trigger_detail 带 productionRunId），草稿落生产抽取运行。
## 3. 改动台账
| 文件 | 动作 | 原因 |
|---|---|---|
| `.agent/skills/extract-chapter-knowledge/scripts/dispatch_extraction_bridge.py` | 新增 | 抽取任务包装配 + 派发编排（校验/修复/落库/收口） |
| `.agent/skills/extract-chapter-knowledge/scripts/extract_via_dispatch.py` | 新增 | 派发入口（显式 provider/model，真实调用需授权） |
| `tests/skills/extract-chapter-knowledge/test_dispatch_extraction_bridge.py` | 新增 | 离线测试（7 项） |
## 4. 验证结果
- 离线测试 7/7 通过。
- 真实派发（作品 12 第 3 章，`extract-knowledge-w12-c3-20260823T150511`，catproxy-anthropic/claude-opus-5，medium）：
- v1 派发完成但证据绑定未过 `normalize_extraction` → 桥自动触发 v2 修复重派 → 通过（修复路径首次真实验证）。
- 18 条实体草稿 + 1 条叙事状态草稿落库（status=pending），看板与经验确认通道 :8766 可见，待人审转正。

56
docs/plans/2026-08-22-阶段F-第四部分-对照实验与直调链终态裁决.md
View File

@ -1,56 +0,0 @@
# 阶段 F 第四部分：对照实验与直调链终态裁决
日期：2026-08-23
状态：已完成（对照实验真实执行，裁决落定）
上游事实：阶段 F 一/二/三部分完成；总 plan §6"直接调用保留为对照模式，使用智能体实际收集的依赖上下文生成对照正文，比较质量、成本与遗漏率"。
## 1. 实验设计
同一份探索依赖上下文（候选 164 生成阶段的任务包：5 份回放资料 + 篇幅合同 + 35 条文风约束），两条生成链各写一次第 3 章：
| 臂 | 链 | 模型 | 运行 |
|---|---|---|---|
| A（框架） | 两阶段写手·框架派发生成 | catproxy-anthropic/claude-opus-5 high | `run-prod-work12-ch3-42beb650-writer-v9`（候选 164） |
| B（直调） | 角色运行时直调（固定 Opus 策略） | claude-opus-4-8[1M] | `run-contrast-work12-ch3-302a293a`（候选 167，run_type=eval） |
已知混杂：模型不同（opus-5 vs opus-4-8）；直调臂的角色提示词为直调链自带旧版（未含两阶段形态）。对照臂候选 `run_type=eval` + `acceptance_eligible=FALSE` + 语义空，四层机械不可接受。
## 2. 数据
| 指标 | 框架臂（164） | 直调臂（167） |
|---|---|---|
| 机械门 | ✅ 通过 | ❌ `OUTLINE_PHRASE_LEAKED`（复读细纲原句） |
| 语义检测 | ✅ 通过 | 未执行（对照候选无接受路径） |
| 人决定 | ✅ 采纳入正典 | — |
| 正文汉字 | 3764 | 3339 |
| 输入令牌 | 12,922（另探索 122,088） | 14,059 |
| 输出令牌 | 17,860 | 20,423 |
| 模型回合 | 探索 4 + 生成 1 | 1 |
## 3. 裁决
**创作生成（写手）的直调链退役出生产与对照之外的用途；框架派发链（两阶段写手）是唯一创作生成链。**
依据：
1. 质量：同一输入下，直调臂未过机械门（复读细纲措辞），框架臂通过双门并经人采纳。直调臂的失败模式与框架链改造前的单阶段形态一致——两阶段化 + 角色合同改写带来的纪律收益无法在直调链上复现。
2. 成本：直调臂单次调用（约 3.4 万令牌）确实省去了探索开销（框架臂探索约 12.2 万输入令牌），但探索是质量与链路透视的来源；省成本不抵质量缺口。
3. 与阶段 B 终态一致：治理直调链保留为**对照实验与内容模型任务**专用（本次实验即其对照用途的实证），不再承担创作生成。
保留与退役清单：
- 保留：`run_writer_with_receipt`/角色运行时直调（对照实验与内容模型任务的取数通道）、语义检测直调（生产检测组件，另案评估）。
- 退役：直调链作为创作生成生产路径的资格；`produce_next_chapter.py` 的默认直调写作分支保留代码（对照入口），生产一律显式 `--two-phase`。
## 4. 局限性（如实登记）
- 单样本（一次对照）；严格结论需多章重复。
- 模型混杂：两臂模型不同（链的冻结配置使然），质量差异含模型因素。
- 未做盲评：直调臂未过机械门，盲评比较无意义（盲评前提是过门候选）。
## 5. 改动台账
| 文件 | 动作 | 原因 |
|---|---|---|
| `.agent/skills/write-next-chapter/scripts/run_contrast_writer.py` | 新增 | 对照直调臂入口：同源探索输入、直调生成、机械门留证、`eval` 候选落库（失败关闭） |
| 本文档 | 新增 | 实验设计与裁决记录 |

37
docs/plans/2026-08-22-阶段G-第一部分-链路透视接线-事件账本与派发链.md
View File

@ -1,37 +0,0 @@
# 阶段 G 第一部分：链路透视接线——事件账本与派发链上看板
日期：2026-08-23
状态：已完成（看板测试绿 + 真实运行页走查通过）
上游事实：两阶段写手、抽取、盲评派发运行已在 `example_agent_event` 与 `example_run` 留下真实数据；§11 矩阵中"探索轨迹与事件链""依赖清单"此前为接线缺口。
## 1. 意图
把框架派发链的运行时证据接上看板：运行详情页新增"链路透视"区块，回放一次运行的探索轨迹（读了什么）、模型回合（成本）与派发链父子关系。只读库，不拼命令，不写库。
## 2. 改动台账
| 文件 | 动作 | 原因 |
|---|---|---|
| `dashboard/server.py` | 修改 | `view_run_detail` 主查询补 `trigger_detail`；新增 `_agent_events_html`（探索轨迹 + 模型回合，读 `example_agent_event`）与 `_dispatch_chain_html`（经 `trigger_detail.productionRunId/evaluationRunId` 关联父子运行）；页面加"链路透视"区块 |
## 3. 验证
- `dashboard/test_server_display.py` 全绿（展示层中文语义与编码合同）。
- 真实页走查（只读看板）：
- `…-writer-v9`：探索轨迹含 `read_chapter_text`×8、`read_fine_outline`×4 等，模型回合带令牌/成本，"派发链"回链父运行。
- 生产父运行 `…-42beb650`：列出子运行 explore-v9 / writer-v9。
- 盲评运行 `…-30f33c50c7`：列出 judge-v1 / judge-v2。
## 4. §11 对照（本部分消解的缺口）
| 内容 | 之前 | 现在 |
|---|---|---|
| 探索轨迹与事件链（example_agent_event） | 看板未接（缺口） | 运行详情页"链路透视"可见 |
| 依赖清单（本次运行实际读了什么） | 看板未接（缺口） | 以工具事件（工具名+参数明细）呈现 |
| 派发链父子关系 | 无视图 | "派发链"区块双向可导航 |
## 5. 未决（阶段 G 后续）
- 任务包（spec）与生产 artifacts 读侧迁到运行目录/库投影的看板呈现（§11"生产 artifacts"行的读侧迁移）。
- 待审视图增强：候选详情页直达其生产运行与检查报告（现经 /runs 手工跳转）。
- 五视图整体走查与 §11 全矩阵验收。

80
harness/manifests/test-inventory.json
View File

@ -1817,13 +1817,79 @@
"skill_behavior_eval": false,
"classification_confidence": "high",
"classification_basis": "Fixes agent event ledger writer shapes and atomic framework evidence persistence with fake connections; no DB, no network."
},
{
"path": "tests/skills/assemble-context/test_persist_freeze_db.py",
"scope": "runtime_skill",
"owner_skill_or_domain": "assemble-context",
"kind": "integration",
"evidence_level": "real_dependency_integration",
"requires": [
"postgresql"
],
"side_effects": [
"postgresql"
],
"skill_behavior_eval": false,
"classification_confidence": "high",
"classification_basis": "真实库验证冻结幂等键 (manifest_sha256, context_sha256) 对：按既有一行原值重放不新增行；append-only 触发器禁止清理，故零污染设计。"
},
{
"path": "tests/skills/write-next-chapter/test_two_phase_writer.py",
"scope": "runtime_skill",
"owner_skill_or_domain": "write-next-chapter",
"kind": "runtime_contract",
"evidence_level": "deterministic_offline",
"requires": [
"offline",
"filesystem"
],
"side_effects": [
"filesystem"
],
"skill_behavior_eval": false,
"classification_confidence": "high",
"classification_basis": "两阶段写手离线契约：探索清单严格校验、确定性回放失败关闭、生成输入只含回放材料与合同、两阶段编排与探索摘要落盘；假派发器与假工具，不连库不真调。"
},
{
"path": "tests/skills/extract-chapter-knowledge/test_dispatch_extraction_bridge.py",
"scope": "runtime_skill",
"owner_skill_or_domain": "extract-chapter-knowledge",
"kind": "runtime_contract",
"evidence_level": "deterministic_offline",
"requires": [
"offline",
"filesystem"
],
"side_effects": [
"filesystem"
],
"skill_behavior_eval": false,
"classification_confidence": "high",
"classification_basis": "抽取派发桥离线契约：全量正文注入任务输入、证据逐字绑定机械校验、修复重派语义、缺证失败关闭；假派发器，不连库不真调。"
},
{
"path": "tests/skills/score-content-quality/test_dispatch_judge_bridge.py",
"scope": "runtime_skill",
"owner_skill_or_domain": "score-content-quality",
"kind": "runtime_contract",
"evidence_level": "deterministic_offline",
"requires": [
"offline"
],
"side_effects": [
"none"
],
"skill_behavior_eval": false,
"classification_confidence": "high",
"classification_basis": "评委派发桥离线契约：圈定授权工具白名单、盲评输入防泄漏哈希绑定、任务包与盲评输入全等（桥零附加身份）、ModelRunner 协议形状；不连库不真调。"
}
],
"summary": {
"entry_count": 111,
"entry_count": 115,
"by_scope": {
"other": 1,
"runtime_skill": 99,
"runtime_skill": 103,
"harness": 3,
"domain": 8
},
@ -1832,17 +1898,17 @@
"skill_behavior_eval": 1,
"harness_self_test": 3,
"domain_eval": 4,
"integration": 9,
"integration": 10,
"tool_unit": 32,
"fake_pipeline": 22,
"runtime_probe": 1,
"runtime_contract": 4
"runtime_contract": 7
},
"by_evidence_level": {
"deterministic_offline": 95,
"real_dependency_integration": 10,
"deterministic_offline": 98,
"real_dependency_integration": 11,
"static_structure": 6
},
"total": 111
"total": 115
}
}