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

agent-example 整体收敛总 plan

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

---

1. 意图

两条线，缺一不可：

线一：主权生产链。 把仓从"多条模型调用路径并存、约束散落各处、一次性脚本与设计文档堆积"收敛为一条主权清晰、链路唯一、边界机械强制的创作系统：

人
-> 主代理（润色人的意图、协调授权；不写作、不约束创作）
-> 五个创作智能体（经授权工具自主探索、按提示词合同工作）
-> 静态校验与脚本编排（验证报告、推进状态、落库）
-> 人闸决策
-> 正式正文

线二：作者参与链。 这不是后台流水线，是作者要参与、要看见、要交互的工具。作者必须能在页面上：

• 阅读：阅读正式正文。
• 待审：看待审章节--候选正文、多版本对比、检查报告、逐维评分、本章实际用了哪些资料。
• 卡片：查看知识卡、设定卡、范式卡及其确认状态。
• 链路透视：查看每次运行的输入与输出--任务包、探索轨迹（读了什么、哪个版本）、生成结果、事件链、成本。
• 决策：采纳、丢弃、授权继续补证或重写。

三条不变的主权规则：

1. 模型只产候选（Shadow），不产正式事实。
2. 系统只做机械验证，不做内容裁决。
3. 只有人通过决策通道决定候选是否进入正式正文（Canonical）。

2. 目标总链路

人的意图
  │ 主代理润色、确认歧义
  ▼
任务提示词 ──-> 智能体（框架派发）
                  │ 只读工具自主探索（评委为圈定授权）
                  ▼
              候选 / 报告 + 依赖清单
                  │ 静态校验（结构、引文真实性、哈希绑定）
                  ▼
              脚本编排（状态机、落库、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. 阶段划分

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

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

• 意图：把现有看板与决策通道收敛为创作台五视图：阅读、待审、卡片、链路透视、决策。
• 边界：只读库；不拼模型调用命令；决策仍走唯一决策通道；artifacts 读侧迁到数据库与依赖清单投影。
• 验证：待审章节能看到候选、检查报告、依赖清单；链路透视能回放一次运行的任务包、探索轨迹与成本；既有看板测试与决策人闸测试通过。

9. 台账要求（每阶段强制）

每个阶段产出文件级处置台账，覆盖该阶段触碰的每一个文件与每一项遗留：

处置	必须写明
保留	保留原因：谁是它的现存消费者、它承担什么独有职责
修改	修改原因：依据哪条边界合同或阶段目标，改动前后职责差异
新增	新增原因：替代什么旧路径或填补什么合同空白，入口与使用路径
删除	删除原因：被什么替代、零引用证据、风险评估
遗留	遗留原因：为什么本阶段不处理、归属哪个后续阶段、当前风险

无消费者证据不得删除；无保留理由不得保留；兼容层（新旧并行）必须登记退出条件，不允许无限期双轨。

10. 总验证

每阶段过既有门禁：技能严格审计、架构边界测试、全量离线清单、零引用检索。涉及真实模型调用的阶段另做真实烟测，并以查库核对事件链、依赖清单与模型调用账为准。无自动化绿色证据不得声称完成。

11. 最终验收：新作品创作历程可见性对照（全部阶段完成后）

改造完成后，模拟一个新作品的完整创作历程，逐项对照书 12（深渊机神）当前在看板上的可见性。新作品走新智能体框架链路；书 12 可见的，新作品原则上必须可见；不可见的，必须在验收记录中说明原因（原因只能是：合同已被新形态替代、或属于某阶段的接线缺口）。

验收历程：

1. 新建作品，走完规划链：定盘 → 大纲 → 设定拆条 → 范式与文风 → 章细纲（规划智能体）。
2. 用新框架写作链写一章：写作智能体自主探索 → 机械门 → 检测智能体 → 候选落待审区。
3. 章后抽取知识卡草稿；经人确认后转正。
4. 人采纳候选 → 正式正文。

可见性对照矩阵（基线 = 书 12 当前在看板可见）：

内容	书 12 可见位置	新作品要求	已知差异原因
作品、章节、正式正文	/works、/works//ch/	必须可见（正文表合同不变）	无
候选与待审状态	/candidates、/candidates/	必须可见（候选表合同不变）	无
运行回执、质量结果、模型调用账	/runs/	必须可见（三表继续写入）	无
知识卡（草稿/转正）	/knowledge	必须可见	无
探索轨迹与事件链（example_agent_event）	书 12 无此数据	必须可见	看板尚未接事件账本（阶段 G 接线；书 12 时代没有事件账本，无基线可比，属新增可见项）
依赖清单（本次运行实际读了什么）	书 12 无此数据	必须可见	同上，阶段 G 接线
生产 artifacts（pipeline-result 等）	/runs/ 读 docs/write-chapter/artifacts/	新框架运行的审计件在运行目录与库内投影，不写旧 artifacts 目录	合同替代：旧文件快照 → 运行目录 + 依赖清单 + 事件账本（阶段 G 读侧迁移）
授权终态与缺口报告	书 12 无此数据	必须可见（运行终态与报告在看板可读）	新增可见项

验收规则：

• 对照矩阵逐项走查，截图或查询记录为证；每项标注「可见 / 不可见 + 原因」。
• 不可见且原因是「接线缺口」的，必须登记归属阶段并补齐后复验。
• 新作品的候选、待审、正文、卡片、链路记录五类全部可见，或每个缺口都有成立的原因，验收才算通过。
• 验收全程不得把测试数据伪装成书 12 的历史数据；新作品用独立作品行与独立运行记录。