# agent-example 整体收敛总 plan

日期：2026-08-22
状态：总 plan 已定；阶段细节在各阶段启动时另行制定。

---

## 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`。
- 边界：对照只在显式对照模式运行；评测候选四层强制不可接受不变；知识草稿须经人确认转正。
- 验证：盲评隔离测试（禁看清单越权拒绝）；对照产出可比正文与成本数据；退役项零引用后删除。

### 阶段 G：创作台对齐（完成后按 §11 走最终验收）

- 意图：把现有看板与决策通道收敛为创作台五视图：阅读、待审、卡片、链路透视、决策。
- 边界：只读库；不拼模型调用命令；决策仍走唯一决策通道；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 的历史数据；新作品用独立作品行与独立运行记录。