From eb830532b8c82ef1bdbdd3f85c3e884f539faf59 Mon Sep 17 00:00:00 2001 From: zizi Date: Sun, 23 Aug 2026 00:26:53 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3:=20=E8=90=BD=E8=BE=B9?= =?UTF-8?q?=E7=95=8C=E5=90=88=E5=90=8C=E4=B8=8E=E6=95=B4=E4=BD=93=E6=94=B6?= =?UTF-8?q?=E6=95=9B=E6=80=BBplan=EF=BC=88=E9=98=B6=E6=AE=B5A=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agent/_index.md | 1 + .agent/docs/architecture/_index.md | 1 + .agent/docs/architecture/边界合同.md | 62 ++ AGENTS.md | 1 + .../2026-08-22-agent-example整体收敛总plan.md | 200 ++++++ docs/plans/2026-08-22-阶段A-边界合同定义.md | 49 ++ .../plans/2026-07-20-writer-agent-v1.md | 573 ------------------ 7 files changed, 314 insertions(+), 573 deletions(-) create mode 100644 .agent/docs/architecture/边界合同.md create mode 100644 docs/plans/2026-08-22-agent-example整体收敛总plan.md create mode 100644 docs/plans/2026-08-22-阶段A-边界合同定义.md delete mode 100644 docs/superpowers/plans/2026-07-20-writer-agent-v1.md diff --git a/.agent/_index.md b/.agent/_index.md index d57b3aa..ea4a58d 100644 --- a/.agent/_index.md +++ b/.agent/_index.md @@ -4,5 +4,6 @@ - [Skill 发现总索引](skills/_index.md) - [角色身份提示](agents/)（writer / planner / extractor / detector / judge） - [角色合同](docs/architecture/角色合同.md)（稳定角色边界、模型策略与派发合同唯一事实源） +- [边界合同](docs/architecture/边界合同.md)（组件职责边界与约束归属唯一事实源） 项目入口与协作规则仍由根目录 [`AGENTS.md`](../AGENTS.md) 拥有；本目录只保存跨任务稳定知识。 diff --git a/.agent/docs/architecture/_index.md b/.agent/docs/architecture/_index.md index e6478dd..c8f7b9e 100644 --- a/.agent/docs/architecture/_index.md +++ b/.agent/docs/architecture/_index.md @@ -1,5 +1,6 @@ # 架构文档索引 - [单用户本地优先领域设计](domains/_index.md) +- [边界合同](边界合同.md)（组件职责边界与约束归属唯一事实源） - [角色合同](角色合同.md)（五个角色的唯一稳定合同事实源） - [创作周期与 Skill 导读](创作周期与Skill导读.md)（教学地图，不是合同权威） diff --git a/.agent/docs/architecture/边界合同.md b/.agent/docs/architecture/边界合同.md new file mode 100644 index 0000000..85515cf --- /dev/null +++ b/.agent/docs/architecture/边界合同.md @@ -0,0 +1,62 @@ +# 边界合同 + +> 本文件是组件职责边界与约束归属的唯一事实源。角色合同、Skill 合同、可视化模块合同和各领域 SoT 从属本文件的边界划分；与各组件相关的字段、流程细节归各自合同，本文件不复制。系统目标链路与作者交互面（创作台五视图）见 [创作周期与 Skill 导读](创作周期与Skill导读.md) 与 [可视化模块合同](可视化模块合同.md)。 + +## 1. 组件职责与边界 + +| 组件 | 职责 | 边界（不做） | 结构 | +|---|---|---|---| +| 主代理 | 理解并润色人的创作意图、确认歧义、把确认后的意图交给智能体；转述智能体报告、向人请求授权（补证/重写/继续） | 不写作、不替智能体设计情节、不承载创作约束、不直接读写库 | 宿主会话（由根 AGENTS.md 约束） | +| 创作智能体（5 个） | 按角色合同生成候选或检查报告；经授权工具自主探索、形成自己的上下文依赖 | 不写库、不推进状态机、不越工具白名单、不裁决自己产出、引用不带来源不落正文 | 角色身份提示 + 中央角色合同 + 任务提示词（三层提示词） | +| Skill | 业务功能合同：适用场景、输入输出 Schema、路由、失败路径与落库要求 | 不持有模型策略、不绕过证据账本、不承载跨业务编排、依赖只向下 | SKILL.md（合同）+ scripts（确定性实现）+ 元数据 | +| 工具 server | 给智能体提供只读取数能力的统一入口 | 只读、不提供裸查询（每工具只暴露声明过的数据范围）、按任务包授权圈定、调用即留痕进事件账本 | 每工具声明：读什么表、什么版本语义、返回什么结构 | +| 脚本编排 | 确定性流程：上下文绑定校验、状态机、落库、CAS、终态收敛 | 不做内容裁决、不拼创作提示词、不隐式无限循环（需要继续时停在授权终态） | 各 Skill 的 scripts 层 | +| 静态校验 | Schema 校验、引文真实性核验、哈希绑定、架构门禁 | 无模型参与；失败即关闭，不重试放宽 | 测试 + 校验脚本 + 数据库约束（触发器、CHECK、CAS） | +| 创作台（看板+决策通道） | 只读渲染库内状态；决策写走唯一决策通道 | 只读看板不拼执行命令、不写库；决策通道不绕过候选状态机 | 独立只读进程 + 独立决策进程 | + +## 2. 约束归属 + +每类约束只有一个归属，禁止跨层承载；跨层即视为缺陷，须按本表归位。 + +| 约束类型 | 归属层 | 强制方式 | +|---|---|---| +| 创作意图、工作方法、写作纪律 | 提示词层（agent prompt） | 模型遵守 + 输出抽查（评测） | +| 角色身份、模型策略、合同版本 | 中央角色合同（角色合同.md） | 派发入口机械校验 | +| 数据可访问范围（能读什么） | 工具层（工具 server 白名单） | 框架按任务包机械拒绝 | +| 输入输出格式 | 静态层（schema 校验） | 模型调用前后拒绝 | +| 状态推进、数据库写 | 脚本层 + 数据库约束 | CAS、触发器、事务 | +| 模块依赖、目录纪律 | 架构门禁（测试） | 失败关闭 | +| 业务继续/停止（补证、重写次数） | 主代理向人请求授权 | 授权终态；脚本只保留技术保护（超时、预算、取消） | + +判定原则：**模型能被说服的用提示词；模型不能碰的用工具白名单；不允许出错的用脚本与静态校验。** 主代理不承载任何创作约束，只传递人的意图。 + +## 3. 三层提示词结构 + +智能体收到的提示词由三层组成，来源各不相同： + +| 层 | 内容 | 来源 | 维护者 | +|---|---|---|---| +| 系统提示词 | 角色身份、职责、工作方法、探索方法、基本禁区 | `.agent/agents/*.md` 身份提示 + 角色合同对应章节 | 角色合同 | +| 技能提示词 | 当前任务的工作步骤、取数方法、输出要求 | 对应 Skill 合同 | Skill | +| 任务提示词 | 人确认后的创作意图（主代理润色产物） | 主代理 | 会话 | + +角色身份文件可以**解释**工具和 Skill 路由（Agent 需要知道能力边界才能正确行动），但实际权限由任务包白名单和工具 server 机械强制；两者冲突时以机械强制为准。 + +## 4. 探索授权模式 + +智能体按角色合同获得差异化的探索授权： + +- **只读集**（规划、写作、检测、抽取）：授权范围内自由探索，每次读取留依赖记录。 +- **圈定授权**（评委）：盲评合同要求匿名隔离--禁看候选身份、标准答案（oracle）、目标章全文、其他评委结果；实验场景授权最窄（仅冻结快照），生产预检可放宽到正典检索。 +- **无工具**（部分批处理角色任务）：任务包白名单为空。 + +同一角色可在不同场景获得不同授权范围；授权由任务包声明，工具 server 执行，不靠提示词自觉。 + +## 5. 数据权威与证据 + +数据库是正式事实唯一权威（见 [08-数据权威与可视化领域](domains/08-数据权威与可视化领域.md)）。各组件对证据的责任： + +- 智能体的每次工具读取、每次模型调用都进事件账本，形成**依赖清单**（这章/这次检查实际用了哪些资料、什么版本）。 +- 脚本编排负责把候选、报告、依赖清单与运行回执绑定落库。 +- 创作台的"链路透视"视图直接读库与事件账本，不依赖仓外文件。 +- raw 三件套（prompt/response/supplier）与事件账本表结构是既有合同，本合同不重定义。 diff --git a/AGENTS.md b/AGENTS.md index ef9daaf..09c2a33 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面 | [`CLAUDE.md`](CLAUDE.md) | Claude Code 兼容入口，只引用本文件，不定义独立规则或 SoT。 | | [`../design-docs/`](../design-docs/) | Muse 的概念、产品、业务和总体架构 SoT。 | | [`.agent/docs/architecture/domains/`](.agent/docs/architecture/domains/_index.md) | 本仓领域边界、数据权威、落库合同和领域协作的 SoT。 | +| [`.agent/docs/architecture/边界合同.md`](.agent/docs/architecture/边界合同.md) | 组件职责边界与约束归属的唯一事实源：什么约束放提示词、工具、脚本、静态层；智能体/Skill/工具 server/主代理各自不做什么。 | | [`meta/schemas/`](meta/schemas/) | 23 型结构本体的字段合同；库内 payload 结构以该合同为准。 | | [`meta/chains/`](meta/chains/) | scenario、purpose、功能 skill、角色槽位和保护节点的链路登记。 | | [`.agent/skills/`](.agent/skills/) | 每个 `SKILL.md` 定义项目运行时能力的输入、输出、红线、数据库读写合同和输入产出落库；同目录 `scripts/` 是运行时确定性实现与机械门，开发验证和行为评测入口由 `harness/manifests/` 登记。全量 skill 的发现总索引是 [`.agent/skills/_index.md`](.agent/skills/_index.md)：只登记 `skill_name` / `skill_file` / `skill_description` 三字段，由 `harness/skills_index.py` 生成，与磁盘、frontmatter、skills.json 机械对账。 | diff --git a/docs/plans/2026-08-22-agent-example整体收敛总plan.md b/docs/plans/2026-08-22-agent-example整体收敛总plan.md new file mode 100644 index 0000000..e39fdb5 --- /dev/null +++ b/docs/plans/2026-08-22-agent-example整体收敛总plan.md @@ -0,0 +1,200 @@ +# 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：链路盘点与清理 + +- 意图：盘点全部模型调用路径、59 个技能、一次性脚本与散落设计文档，每项定终态归属，删除无消费者的遗留。 +- 边界：4 条模型调用路径定终态--框架派发链为生产与评测主链；治理直调链为对照实验与内容模型任务；角色运行时链随直调链处置；批处理执行链定保留或退役。删除以零引用检索为依据。 +- 验证：被删入口全仓零引用；全量离线清单无新增失败；单一提交可一次对比删除面。 + +### 阶段 C：角色合同与领域文档对齐目标形态 + +- 意图：按边界合同重写五个角色的角色合同、创作流程领域、智能体领域与主链图，明确主代理职责、智能体自主探索、授权管控。 +- 边界：只改文档；只写目标合同与代码当前事实，不写待办措辞。 +- 验证：文档交叉引用一致；与边界合同无矛盾；技能索引与严格审计通过。 + +### 阶段 D：能力建设 + +- 意图：给框架派发链补齐三块底座--只读工具 server、会话复用、依赖清单。 +- 边界：工具 server 全部只读，复用现有取数端；会话复用使用框架原生会话机制，不自造；工具调用即依赖记录，不加新表。 +- 验证：离线测试覆盖越权拒绝、会话续接、依赖清单完整性；一次真实派发查库可见每次读取的来源与版本。 + +### 阶段 E：生产链切换 + +- 意图：规划、写作、检测三个智能体接入框架派发；补证与重写删除写死上限，改为授权终态。 +- 边界：只换执行节点，候选落库、CAS、人闸不动；防造假静态校验保留（引文必须真实存在于正文、哈希绑定、报告结构合法）。 +- 验证：离线测试覆盖通过、缺口、冲突、造假引文拒绝；一次真实生产烟测停在人闸，查库核对候选、事件、依赖清单、模型调用无重复记账。 + +### 阶段 F：评测链与知识链切换 + 终态裁决 + +- 意图：评委与抽取智能体接入框架派发（评委保持圈定授权隔离）；用对照实验数据裁决直调链去留。 +- 边界：对照只在显式对照模式运行；评测候选四层强制不可接受不变；知识草稿须经人确认转正。 +- 验证：盲评隔离测试（禁看清单越权拒绝）；对照产出可比正文与成本数据；退役项零引用后删除。 + +### 阶段 G：创作台对齐 + +- 意图：把现有看板与决策通道收敛为创作台五视图：阅读、待审、卡片、链路透视、决策。 +- 边界：只读库；不拼模型调用命令；决策仍走唯一决策通道；artifacts 读侧迁到数据库与依赖清单投影。 +- 验证：待审章节能看到候选、检查报告、依赖清单；链路透视能回放一次运行的任务包、探索轨迹与成本；既有看板测试与决策人闸测试通过。 + +## 9. 台账要求（每阶段强制） + +每个阶段产出文件级处置台账，覆盖该阶段触碰的每一个文件与每一项遗留： + +| 处置 | 必须写明 | +|---|---| +| 保留 | 保留原因：谁是它的现存消费者、它承担什么独有职责 | +| 修改 | 修改原因：依据哪条边界合同或阶段目标，改动前后职责差异 | +| 新增 | 新增原因：替代什么旧路径或填补什么合同空白，入口与使用路径 | +| 删除 | 删除原因：被什么替代、零引用证据、风险评估 | +| 遗留 | 遗留原因：为什么本阶段不处理、归属哪个后续阶段、当前风险 | + +无消费者证据不得删除；无保留理由不得保留；兼容层（新旧并行）必须登记退出条件，不允许无限期双轨。 + +## 10. 总验证 + +每阶段过既有门禁：技能严格审计、架构边界测试、全量离线清单、零引用检索。涉及真实模型调用的阶段另做真实烟测，并以查库核对事件链、依赖清单与模型调用账为准。无自动化绿色证据不得声称完成。 diff --git a/docs/plans/2026-08-22-阶段A-边界合同定义.md b/docs/plans/2026-08-22-阶段A-边界合同定义.md new file mode 100644 index 0000000..85a0d9e --- /dev/null +++ b/docs/plans/2026-08-22-阶段A-边界合同定义.md @@ -0,0 +1,49 @@ +# 阶段 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 相符。 diff --git a/docs/superpowers/plans/2026-07-20-writer-agent-v1.md b/docs/superpowers/plans/2026-07-20-writer-agent-v1.md deleted file mode 100644 index 8ce1238..0000000 --- a/docs/superpowers/plans/2026-07-20-writer-agent-v1.md +++ /dev/null @@ -1,573 +0,0 @@ -# 正文智能体实验台 v1 Implementation Plan - -> **类型：历史实施计划，非 SoT，禁止继续执行。** 文中的 v1 合同、文件路径、任务状态和命令只记录 2026-07-20 的实施基线；正文稳定合同以父仓 `design-docs/专题-03/04/05` 为准，后续执行只认当前 skill、配置和代码事实。 -> -> **已迁移（2026-07-26 skill 重组）：** 文中 `replay-eval/scripts/writer_rubric.py`、`writer_gate.py` 等评分/裁决模块已迁入 `quality-gate/scripts/`；`claude_runtime.py`/`file_cas.py`/`raw_vault.py` 运行时底座已迁入新建 `runtime/scripts/`。下文路径仅为历史基线，不代表当前位置。 - -> **执行约束（创始人 2026-07-20 确认）：** 不使用 worktree，不使用 superpower。执行类任务由子代理直接在当前 `main` 工作树实现，主代理负责文件边界、代码审查与机械验证；不得暂存或覆盖用户已有改动。 - -**Goal:** 在参考作品回放环境中实现一套可机械验证的正文智能体：知识卡只承担索引职责，智能体必须顺着卡片证据回读冻结线内的历史原文，再依据大纲、细纲和事实证据生成正文，并经过审查、盲评及 Gate A/B 验收。 - -**Architecture:** 实验链路分为确定性上下文层、无工具写作层、审查收敛层和离线评测层。检索层在只读快照内生成 `RetrievalPlan` 与 `RetrievalManifest`；上下文层区分事实证据和文风证据；写手只接收冻结后的 `WriterContext v1`，不能自行调用工具；候选正文必须通过 detector 和接受前置检查。A/B/C 回放仅用于诊断，任何评测产物都不得进入 Canonical 正文。 - -**Tech Stack:** Python 3.12、标准库 `unittest`、PostgreSQL/psycopg、现有 `.claude/skills` 流程规范、Claude CLI adapter、YAML/JSON 元数据契约。 - ---- - -## 边界与完成定义 - -- 本计划只实现 `agent-example` 的正文实验台，不修改 `muse-cloud`、产品 API、正式状态机或业务数据库结构。 -- v1 只验收“依据细纲生成下一章”的 `continuation` 场景；改写、扩写、润色、纠错、去 AI 味和角色声音仍复用 writer 身份，但不纳入本轮 Gate，不得宣称这些场景已优化完成。 -- 生产化接口、数据库迁移和 UI 入口必须等 Gate B 通过后另立设计与实施计划。 -- 所有冻结规则在可信的检索/组装层执行，不能依赖写手提示词自觉。 -- `抽取卡 -> 原文` 是强制链路：抽取卡若没有可追踪的历史原文来源，不得单独作为正文硬事实。作者已确认的正式设定、Canonical 状态与细纲声明的新事实可以直接成为事实证据，并标为 `declared_new` 或相应来源类型。 -- “完成”至少包含：测试通过、dry-run 通过、真实回放所需配置齐全；没有真实模型回放结果时只能称“实现完成”，不能称 Gate A/B 通过。 - -## 环境准备：当前主工作树本地依赖 - -- [ ] 在 `agent-example` 当前 `main` 工作树复用已安装依赖的 `.venv`，先确认解释器版本与依赖可用： - -```bash -cd /Users/qingse/Sync/local-git/oh-my-muse/agent-example -.venv/bin/python --version -``` - -- [ ] 后续所有 Python 命令都在当前 `agent-example` 主工作树执行并使用 `.venv/bin/python`；若 `requirements.txt` 变化，先重装依赖再验证。 - -## 任务 0：回写稳定设计 SoT，标明实验边界 - -> 本任务直接在外层仓库 `/Users/qingse/Sync/local-git/oh-my-muse` 的当前 `main` 工作树执行。只提交下列精确路径，保留外层和内层工作树中的用户已有改动。 - -**Files:** -- Modify: `/Users/qingse/Sync/local-git/oh-my-muse/design-docs/专题-01-正文建议接受(Accept Suggestion)实现规范.md` -- Modify: `/Users/qingse/Sync/local-git/oh-my-muse/design-docs/专题-03-AI编排上下文与质量评测实现规范.md` -- Modify: `/Users/qingse/Sync/local-git/oh-my-muse/design-docs/专题-04-生成质量门控与创作健康度设计方案.md` -- Modify: `/Users/qingse/Sync/local-git/oh-my-muse/design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md` -- Modify: `/Users/qingse/Sync/local-git/oh-my-muse/design-docs/专题-06-元数据驱动的智能体架构.md` -- Modify: `/Users/qingse/Sync/local-git/oh-my-muse/design-docs/专题-07-知识消费契约与质量闭环.md` -- Modify: `/Users/qingse/Sync/local-git/oh-my-muse/design-docs/架构-04-状态机与约束清单.md` -- Modify: `/Users/qingse/Sync/local-git/oh-my-muse/.agents/workflows/ai-development-protocol.md` - -- [ ] 在专题-07 中把“卡是索引，根据卡回读原文”设为正文消费契约，明确卡不能替代原文。 -- [ ] 在专题-03 中补齐 `WriterContext v1`、`WriterOutput v1`、`RetrievalManifest` 和冻结语义。 -- [ ] 在专题-04 中补齐正文五维评分、双盲评、第三评委仲裁、Gate A/B 唯一判定顺序。 -- [ ] 在专题-05 中明确写手 adapter 的无工具、无会话持久化、超时失败关闭边界。 -- [ ] 在专题-06 中登记 generation purpose 的严格 schema、卡索引视图和双证据字段；只引用各 owner 文档，不复制完整定义。 -- [ ] 在专题-01 中补齐编辑后生成新 candidateVersion、重新 detector、`accept_preflight` 与 CAS 接受边界。 -- [ ] 在架构-04 中标注实验态候选不能进入 Canonical，正式接受仍需 CAS 和 detector 绿证据。 -- [ ] 在既有 `.agents/workflows/ai-development-protocol.md` 中沉淀反序验证门禁：清洗/抽卡/范式 -> 正文 Gate B -> 细纲 -> 大纲+设定；正文层固定采用卡索引与原文回读双线。 -- [ ] 按外层 `CLAUDE.md` 检查概念 owner，只在 owner 文档定义，在其他文档放链接和一句话摘要；所有实质修改同步递增版本号和更新日期。 -- [ ] 在文档中明确“本阶段不改 API 契约/DB”；只有 Gate B 通过后的产品化计划才更新 `docs/api-contracts/*` 和 Flyway。 -- [ ] 运行文档一致性检查： - -```bash -cd /Users/qingse/Sync/local-git/oh-my-muse -rg -n "卡是索引|WriterContext v1|acceptanceEligible|Gate A|Gate B|Canonical" \ - 'design-docs/专题-01-正文建议接受(Accept Suggestion)实现规范.md' \ - design-docs/专题-03-AI编排上下文与质量评测实现规范.md \ - design-docs/专题-04-生成质量门控与创作健康度设计方案.md \ - design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md \ - design-docs/专题-06-元数据驱动的智能体架构.md \ - design-docs/专题-07-知识消费契约与质量闭环.md \ - design-docs/架构-04-状态机与约束清单.md \ - .agents/workflows/ai-development-protocol.md -``` - -- [ ] Commit： - -```bash -git -C /Users/qingse/Sync/local-git/oh-my-muse add \ - 'design-docs/专题-01-正文建议接受(Accept Suggestion)实现规范.md' \ - design-docs/专题-03-AI编排上下文与质量评测实现规范.md \ - design-docs/专题-04-生成质量门控与创作健康度设计方案.md \ - design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md \ - design-docs/专题-06-元数据驱动的智能体架构.md \ - design-docs/专题-07-知识消费契约与质量闭环.md \ - design-docs/架构-04-状态机与约束清单.md \ - .agents/workflows/ai-development-protocol.md -git -C /Users/qingse/Sync/local-git/oh-my-muse commit \ - -m "设计: 固化正文智能体卡索引原文回读契约" -``` - -## 任务 1：建立 WriterContext/WriterOutput 严格契约 - -**Files:** -- Modify: `meta/schemas/generation_context.yaml` -- Modify: `meta/schemas/outline.yaml` -- Modify: `meta/schemas/README.md` -- Create: `.claude/skills/assemble-context/scripts/writer_contract.py` -- Create: `.claude/skills/assemble-context/scripts/test_writer_contract.py` - -- [ ] 先写失败测试，覆盖： - - `runId` 不参与 manifest identity；相同输入得到相同 hash。 - - Unicode NFC 归一化后计算偏移和 hash。 - - 汉字数只计算 CJK Unified Ideographs，不以 Markdown 字符数冒充正文长度。 - - 目标长度采用 half-up 取整，且受 min/max 硬边界约束。 - - `evaluation`/`diagnostic` 上下文始终 `acceptanceEligible=false`。 - - 未知字段、缺字段、错误版本号均 fail closed。 - -```bash -.venv/bin/python \ - .claude/skills/assemble-context/scripts/test_writer_contract.py -v -``` - -- [ ] 实现 `normalize_text()`、`canonical_json()`、`retrieval_identity()`、`han_count()`、`calculate_target_chars()`。 -- [ ] 定义并校验 `WriterContext v1`：大纲定位、细纲硬约束、冻结点、事实证据、文风证据、检索清单、目标长度、用途与接受资格。 -- [ ] 定义并校验 `WriterOutput v1`：正文、claim ledger、evidence requests、新设定声明、候选版本和上下文 hash。 -- [ ] 更新 YAML schema，使字段名、枚举和 Python 校验器一致；将 `generation_context` 从待启用改为实验台启用，并同步 `meta/schemas/README.md` 的状态和实例落点说明。 -- [ ] 测试转绿并检查 schema 可读性。 -- [ ] Commit： - -```bash -git add meta/schemas/generation_context.yaml meta/schemas/outline.yaml meta/schemas/README.md \ - .claude/skills/assemble-context/scripts/writer_contract.py \ - .claude/skills/assemble-context/scripts/test_writer_contract.py -git commit -m "实现: 建立正文上下文与输出严格契约" -``` - -## 任务 2：实现确定性的卡检索和冻结原文读取 - -**Files:** -- Modify: `.claude/skills/search-knowledge/scripts/search.py` -- Modify: `.claude/skills/evaluate-frozen-replay/scripts/load_reference_work.py` -- Create: `.claude/skills/assemble-context/scripts/retrieve_writer_sources.py` -- Create: `.claude/skills/assemble-context/scripts/test_retrieve_writer_sources.py` - -- [ ] 先写失败测试，使用 fake repository 覆盖： - - 卡片按 `score DESC, source_version ASC, source_id ASC, source_offset ASC` 稳定排序。 - - 同分检索多次结果一致。 - - `stateAsOf` 只由 `chapter <= asOfChapter` 的里程碑派生。 - - 终态摘要、未来章号、目标章正文和未来来源引用全部被拒绝。 - - 每条抽取卡索引保留 `sourceVersion/sourceRefs/stateAsOf`；正式设定和细纲新事实使用各自的 Canonical 来源引用。 - - 原文读取事务为 `REPEATABLE READ READ ONLY`。 - - 作品生产检索只读 active Canonical entity 和有效 binding，拒绝 draft/eval 卡。 - - 参考作品回放只读预注册的 `upgrade_book` 卡，并固定 `productionRetrievalEligible=false`，不能流入生产仓储适配器。 - -```bash -.venv/bin/python \ - .claude/skills/assemble-context/scripts/test_retrieve_writer_sources.py -v -.venv/bin/python \ - .claude/skills/evaluate-frozen-replay/scripts/test_load_reference_work.py -v -``` - -- [ ] 从 `search.py` 提取可复用的 `search_cards()`，CLI 继续调用同一实现，避免两套检索语义。 -- [ ] 实现 `CardIndexRepository` 和 `ProseRepository` 协议：作品适配器复用 `search.py` 的授权过滤；回放适配器复用 `load_reference_work.py` 的授权快照、冻结投影和泄露审计；测试使用内存 fake。禁止复制一套旁路 SQL。 -- [ ] 生成 `RetrievalPlan`：从大纲、细纲实体和状态需求确定卡片查询，不允许写手临场改变检索范围。 -- [ ] 抽取卡命中后必须展开 `sourceRefs` 并读取冻结线内原文；没有来源的抽取卡事实标为 `unverifiedIndexHint`，不能单独进入事实证据。正式设定、Canonical 状态和细纲声明的新事实走独立可信来源，不强造历史原文。 -- [ ] 测试转绿。 -- [ ] Commit： - -```bash -git add .claude/skills/search-knowledge/scripts/search.py \ - .claude/skills/evaluate-frozen-replay/scripts/load_reference_work.py \ - .claude/skills/assemble-context/scripts/retrieve_writer_sources.py \ - .claude/skills/assemble-context/scripts/test_retrieve_writer_sources.py -git commit -m "实现: 卡索引驱动冻结原文检索" -``` - -## 任务 3：组装双证据 WriterContext - -**Files:** -- Create: `.claude/skills/assemble-context/scripts/assemble_writer_context.py` -- Create: `.claude/skills/assemble-context/scripts/test_assemble_writer_context.py` -- Modify: `.claude/skills/assemble-context/SKILL.md` - -- [ ] 先写失败测试，覆盖： - - 连续前 4 章全文作为基础 prose evidence；不足 4 章时从第一章开始，不重复。 - - 卡片来源原文作为补充 prose evidence，按来源去重并稳定排序。 - - `factEvidence` 只含冻结后的历史事实、正式设定、Canonical 状态或细纲声明的新事实；`proseEvidence` 只含可引用原文。 - - `evidenceCoverage` 显示细纲实体、关系、物品、地点、力量体系的覆盖和缺口。 - - 同一快照、同一输入生成相同 manifest/context hash。 - - 超出上下文预算时优先保留细纲硬约束、最近原文和高风险事实，裁剪结果可追踪。 - -```bash -.venv/bin/python \ - .claude/skills/assemble-context/scripts/test_assemble_writer_context.py -v -``` - -- [ ] 实现确定性的 `assemble_context()`，输出 JSON 和可供人审阅的 Markdown manifest。 -- [ ] 将每个事实绑定到证据引用：历史抽取事实必须回到章节、块和字符区间；正式设定、Canonical 状态和细纲新事实必须回到各自不可变版本引用。 -- [ ] 更新 read-context 流程：先计划、再卡索引、再原文回读、最后组装，禁止直接把卡片全文倾倒给写手。 -- [ ] 测试转绿。 -- [ ] Commit： - -```bash -git add .claude/skills/assemble-context/SKILL.md \ - .claude/skills/assemble-context/scripts/assemble_writer_context.py \ - .claude/skills/assemble-context/scripts/test_assemble_writer_context.py -git commit -m "实现: 组装正文事实与文风双证据上下文" -``` - -## 任务 4：收紧无工具写手并实现动态篇幅 - -**Files:** -- Modify: `.claude/agents/writer.md` -- Modify: `.claude/skills/write-next-chapter/SKILL.md` -- Modify: `README.md` -- Create: `.claude/skills/write-next-chapter/scripts/run_writer.py` -- Create: `.claude/skills/write-next-chapter/scripts/test_run_writer.py` - -- [ ] 先写失败测试，fake subprocess 断言： - - adapter 使用 `--tools ""` 和 `--no-session-persistence`。 - - adapter 同时使用 `--print --output-format json --agent writer --model opus`，CLI 参数与当前安装版本一致。 - - 只把 `WriterContext v1` 通过 stdin 交给写手。 - - 超时、非零退出、非 JSON、schema 不符均失败关闭，不产生可接受候选。 - - 输出正文汉字数落在动态目标区间；越界返回结构化失败。 - - claim ledger 的每项包含事实类型、正文偏移、候选文本 hash 和证据引用。 - -```bash -.venv/bin/python \ - .claude/skills/write-next-chapter/scripts/test_run_writer.py -v -``` - -- [ ] 从 `writer.md` 移除 `Read/Write/Grep/Glob` 工具声明，明确禁止自行检索和写文件；adapter 以参数列表调用 CLI，禁止 shell 字符串拼接。 -- [ ] 写手提示词把细纲定义为硬骨架，把大纲定义为方向，把 fact evidence 定义为设定约束，把 prose evidence 定义为叙事和文风参考。 -- [ ] 实现动态目标长度：依据细纲场景数、动作/对话/转折权重和前文中位章长计算，不再写死 4000-5000 字。 -- [ ] 要求输出 `claimLedger/evidenceRequests/newSettingDeclarations`，不得静默补设定。 -- [ ] 更新 README 的 writer 能力说明和篇幅口径，删除固定“2500-3500 字”的旧描述，并明确 v1 仅验收 continuation。 -- [ ] 测试转绿。 -- [ ] Commit： - -```bash -git add .claude/agents/writer.md .claude/skills/write-next-chapter/SKILL.md README.md \ - .claude/skills/write-next-chapter/scripts/run_writer.py \ - .claude/skills/write-next-chapter/scripts/test_run_writer.py -git commit -m "实现: 无工具正文写手与动态篇幅控制" -``` - -## 任务 5：实现 detector 硬门和有限收敛循环 - -**Files:** -- Modify: `.claude/agents/detector.md` -- Modify: `.claude/skills/check-content-consistency/SKILL.md` -- Create: `.claude/skills/check-content-consistency/scripts/check_writer_candidate.py` -- Create: `.claude/skills/check-content-consistency/scripts/test_check_writer_candidate.py` -- Create: `.claude/skills/write-next-chapter/scripts/run_writer_pipeline.py` -- Create: `.claude/skills/write-next-chapter/scripts/test_run_writer_pipeline.py` - -- [ ] 先写失败测试，覆盖： - - 细纲关键事件、角色、伏笔、章末钩子是硬约束，缺一项即不通过。 - - claim ledger 的 Unicode 偏移、候选 hash 和证据引用不匹配即不通过。 - - 新设定未声明或与冻结事实冲突即不通过。 - - evidence request 最多 3 次；重写最多 2 次；达到上限返回稳定失败码。 - - 状态只能通过 CAS 从 `DRAFT -> CHECKING -> PASSED/REJECTED`，并发旧版本不能覆盖新版本。 - - 运行结果临时文件写完并 fsync 后原子替换正式结果。 - -```bash -.venv/bin/python \ - .claude/skills/check-content-consistency/scripts/test_check_writer_candidate.py -v -.venv/bin/python \ - .claude/skills/write-next-chapter/scripts/test_run_writer_pipeline.py -v -``` - -- [ ] 实现机械校验器，模型 detector 只负责无法机械判定的语义项。 -- [ ] 实现“请求证据 -> 重新组装上下文 -> 重写 -> 重审”的有限状态机。 -- [ ] 更新 detector 和 detect 规范，输出结构化 failure codes，保留全部审查轨迹。 -- [ ] 测试转绿。 -- [ ] Commit： - -```bash -git add .claude/agents/detector.md .claude/skills/check-content-consistency/SKILL.md \ - .claude/skills/check-content-consistency/scripts/check_writer_candidate.py \ - .claude/skills/check-content-consistency/scripts/test_check_writer_candidate.py \ - .claude/skills/write-next-chapter/scripts/run_writer_pipeline.py \ - .claude/skills/write-next-chapter/scripts/test_run_writer_pipeline.py -git commit -m "实现: 正文细纲硬审查与有限收敛循环" -``` - -## 任务 6：实现接受前置检查，隔离评测产物 - -**Files:** -- Modify: `.claude/skills/decide-candidate/SKILL.md` -- Modify: `meta/chains/README.md` -- Create: `.claude/skills/decide-candidate/scripts/check_writer_acceptance.py` -- Create: `.claude/skills/decide-candidate/scripts/test_writer_acceptance.py` - -- [ ] 先写失败测试，覆盖： - - `acceptanceEligible=false` 的诊断/评测候选不可接受。 - - 用户编辑后必须产生新 candidateVersion，并重新跑 detector。 - - `expectedRevision` 不匹配时返回冲突，不覆盖 Canonical。 - - 只有 detector 绿、上下文 hash 一致、候选未过期才能进入 Shadow 待接受态。 - - `accept/merge/discard` 都要求明确确认；接受成功后才允许异步触发抽卡。 - -```bash -.venv/bin/python \ - .claude/skills/decide-candidate/scripts/test_writer_acceptance.py -v -``` - -- [ ] 实现纯函数 preflight，实验台仅验证状态转换，不写正式正文库。 -- [ ] 更新 confirm 和 chain 文档，删除“修改后直接合并”的模糊路径。 -- [ ] 测试转绿。 -- [ ] Commit： - -```bash -git add .claude/skills/decide-candidate/SKILL.md meta/chains/README.md \ - .claude/skills/decide-candidate/scripts/check_writer_acceptance.py \ - .claude/skills/decide-candidate/scripts/test_writer_acceptance.py -git commit -m "实现: 正文候选接受前置检查" -``` - -## 任务 7：建立正文五维量表和盲评仲裁 - -**Files:** -- Modify: `.claude/agents/judge.md` -- Modify: `.claude/skills/optimize-content-quality/SKILL.md` -- Modify: `.claude/skills/score-content-quality/SKILL.md` -- Create: `.claude/skills/evaluate-frozen-replay/scripts/writer_rubric.py` -- Create: `.claude/skills/evaluate-frozen-replay/scripts/test_writer_rubric.py` - -- [ ] 先写失败测试，覆盖五维各 0-10 分、0.5 步长： - - 设定与实体保真。 - - 细纲与情节忠实。 - - 文风一致性。 - - 叙事张力。 - - 文笔与可读性。 -- [ ] 测试双评委去盲；同一维两次评分差异 `>0.5` 时启动一次第三评委。 -- [ ] 第三评委后，若三评分中至少一对差值 `<=0.5`，该维取三者中位数；不存在稳定配对则样本标为 `invalid_unstable`，不强行给输赢。 -- [ ] 评委必须逐项标注证据来自细纲、历史原文、卡片还是自行推断，便于识别假阴/假阳。 -- [ ] writer rubric 必须作为独立 profile 接入，不覆盖现有 `fine_outline_replay` profile；运行既有细纲 rubric 回归测试。 - -```bash -.venv/bin/python \ - .claude/skills/evaluate-frozen-replay/scripts/test_writer_rubric.py -v -.venv/bin/python \ - .claude/skills/evaluate-frozen-replay/scripts/test_rubric.py -v -``` - -- [ ] 同步 judge/eval/quality-gate 的维度、阈值和无效样本语义。 -- [ ] 测试转绿。 -- [ ] Commit： - -```bash -git add .claude/agents/judge.md .claude/skills/optimize-content-quality/SKILL.md \ - .claude/skills/score-content-quality/SKILL.md \ - .claude/skills/evaluate-frozen-replay/scripts/writer_rubric.py \ - .claude/skills/evaluate-frozen-replay/scripts/test_writer_rubric.py -git commit -m "实现: 正文五维盲评与稳定性仲裁" -``` - -## 任务 8：实现 A/B/C 同条件回放编排 - -**Files:** -- Create: `.claude/skills/evaluate-frozen-replay/scripts/run_writer_replay.py` -- Create: `.claude/skills/evaluate-frozen-replay/scripts/test_run_writer_replay.py` - -- [ ] 先写失败测试，验证三臂唯一变量： - - A：仅历史原文，无卡索引，诊断候选。 - - B：仅冻结卡片索引，不回读原文；卡内容放入 `indexHints` 而非生产 `factEvidence`，用于测“把卡当原文替代品”的诊断候选。 - - C：卡索引 + 原文回读，诊断候选。 - - 三臂共享同一作品、冻结点、大纲、细纲、目标长度、模型版本、采样参数和 detector。 - - 三臂 manifest 清楚记录差异，候选全部 `acceptanceEligible=false`。 - - 任一臂泄露目标章/未来章时整组样本作废。 - - real-run 输出目录不在 `/private/tmp` 时失败关闭，防止原书或候选误入仓库。 - -```bash -.venv/bin/python \ - .claude/skills/evaluate-frozen-replay/scripts/test_run_writer_replay.py -v -.venv/bin/python \ - .claude/skills/evaluate-frozen-replay/scripts/test_run_replay.py -v -``` - -- [ ] 实现 dry-run：只生成计划、manifest 和上下文摘要，不调用模型。 -- [ ] 复用现有 replay-eval 的 `build_snapshot.py`、`check_snapshot.py`、`audit_leakage.py`、`load_reference_work.py` 和授权预检；`run_writer_replay.py` 只增加正文 profile、三臂上下文和 writer/detector/judge 编排，不另造冻结、授权或数据库旁路。 -- [ ] 固定 CLI：`--config`、`--run-id`、`--output-dir`；默认 dry-run，只有显式 `--execute` 才调用模型。real-run 强制 `output-dir` 位于 `/private/tmp`。 -- [ ] 实现 real-run：调用三臂、detector、双盲评和必要的第三评委；原书、候选、完整 prompt/response 只写入显式传入的 `/private/tmp` 运行目录，结构化结果中不得嵌入原文全文。 -- [ ] 测试转绿。 -- [ ] Commit： - -```bash -git add .claude/skills/evaluate-frozen-replay/scripts/run_writer_replay.py \ - .claude/skills/evaluate-frozen-replay/scripts/test_run_writer_replay.py -git commit -m "实现: 正文三臂冻结回放编排" -``` - -## 任务 9：实现 Gate A/B 唯一判定器 - -**Files:** -- Create: `.claude/skills/evaluate-frozen-replay/scripts/writer_gate.py` -- Create: `.claude/skills/evaluate-frozen-replay/scripts/test_writer_gate.py` - -- [ ] 先写表驱动失败测试，固定终态优先级。 -- [ ] Gate A 判定顺序：有效样本 `<5` -> `insufficient_evidence`；否则只要存在 schema 非法、未来泄漏、系统失败、C 臂 detector 高严重度残留或细纲硬约束覆盖率 `<100%` -> `failed`；其余 -> `passed`。 -- [ ] Gate B 判定顺序：Gate A=`insufficient_evidence` -> `insufficient_evidence`；Gate A=`failed` -> `failed`；否则若作品 `<2`、任一作品样本 `<5`、总样本 `<10`、五类场景未覆盖或不稳定样本占比 `>20%` -> `insufficient_evidence`；再判断 C 臂硬约束覆盖率 `<100%`、高严重度残留、文风/叙事张力平均增量 `<-0.25`，或任一维下降 `>0.5` 的样本占比 `>20%`，命中 -> `failed`；再判断 C-A“设定与实体保真”平均增量 `>=0.25` 且正向样本比例 `>=0.60`，达标 -> `passed`；其余 -> `no_gain`。 -- [ ] Gate B 不允许用单章、单作品或只选卡友好场景得出普适结论。 -- [ ] 报告必须列出假阴、假阳、泄露、评委不稳定和新角色无卡等混淆项。 - -```bash -.venv/bin/python \ - .claude/skills/evaluate-frozen-replay/scripts/test_writer_gate.py -v -``` - -- [ ] 实现判定器并测试转绿。 -- [ ] Commit： - -```bash -git add .claude/skills/evaluate-frozen-replay/scripts/writer_gate.py \ - .claude/skills/evaluate-frozen-replay/scripts/test_writer_gate.py -git commit -m "实现: 正文 Gate A B 唯一判定器" -``` - -## 任务 10：预注册 Gate A 样本并完成全量机械验证 - -**Files:** -- Create: `.claude/skills/evaluate-frozen-replay/configs/writer-gate-a-deep-space-v1.json` -- Modify: `.claude/skills/evaluate-frozen-replay/SKILL.md` -- Modify: `docs/2026-07-20-正文智能体正式优化设计与计划.md` - -- [ ] 预注册深空之影 5 个目标章，固定为：第 489 章“圣蒂曼围攻/加特朗战”=战斗；第 321 章“莫妮卡道别与朋友确认”=人物对话；第 544 章“迷途之地内应反水”=转折；第 199 章“赛莉丝身份与联赛锁死真相”=信息揭示；第 523 章“伊蕾莉雅与旧部重逢”=老角色回归。不得根据生成结果换章或改分类。 -- [ ] 每章记录冻结点、目标章、原始大纲/细纲来源、预期长度、主要实体、新角色比例和泄露检查方式。 -- [ ] 更新 replay-eval 流程和正文设计文档，使实际命令、输出路径、Gate 状态与实现一致。 -- [ ] 运行全部新增测试： - -```bash -.venv/bin/python -m unittest discover \ - -s .claude/skills/assemble-context/scripts -p 'test_*.py' -v -.venv/bin/python -m unittest discover \ - -s .claude/skills/write-next-chapter/scripts -p 'test_*.py' -v -.venv/bin/python -m unittest discover \ - -s .claude/skills/check-content-consistency/scripts -p 'test_*.py' -v -.venv/bin/python -m unittest discover \ - -s .claude/skills/decide-candidate/scripts -p 'test_*.py' -v -.venv/bin/python -m unittest discover \ - -s .claude/skills/evaluate-frozen-replay/scripts -p 'test_*.py' -v -``` - -- [ ] 运行静态检查： - -```bash -git diff --check -if rg -n "TODO|TBD|implement later" \ - .claude/skills/assemble-context .claude/skills/write-next-chapter .claude/skills/check-content-consistency \ - .claude/skills/decide-candidate .claude/skills/evaluate-frozen-replay meta/schemas; then - echo "发现未完成占位文本" >&2 - exit 1 -fi -``` - -- [ ] 运行不烧模型额度的 dry-run： - -```bash -.venv/bin/python \ - .claude/skills/evaluate-frozen-replay/scripts/run_writer_replay.py \ - --config .claude/skills/evaluate-frozen-replay/configs/writer-gate-a-deep-space-v1.json \ - --dry-run -``` - -- [ ] 检查 dry-run：五个样本均冻结正确、三臂差异仅为证据策略、目标章和未来章读取数为 0、所有候选不可接受。 -- [ ] Commit： - -```bash -git add .claude/skills/evaluate-frozen-replay/SKILL.md \ - .claude/skills/evaluate-frozen-replay/configs/writer-gate-a-deep-space-v1.json \ - docs/2026-07-20-正文智能体正式优化设计与计划.md -git commit -m "验证: 预注册正文 Gate A 回放样本" -``` - -## 任务 11：真实 Gate A 回放和人工复核门 - -**Files:** -- Generated outside repo: `/private/tmp/muse-writer-replay//manifest.json` -- Generated outside repo: `/private/tmp/muse-writer-replay//gate-report.json` -- Generated outside repo: `/private/tmp/muse-writer-replay//raw/` -- Create after sanitization: `docs/replay/-writer-summary.md` - -- [ ] 执行前记录模型版本、价格窗口、随机参数、代码 commit、数据 snapshot identity；任一项缺失则不启动。 -- [ ] 运行真实回放。该步骤会消耗 Claude/MiniMax 调用，执行者在运行前向用户报预算和样本规模。 -- [ ] 获得预算确认后，使用同一 shell 中的固定 `RUN_ID` 执行： - -```bash -RUN_ID="writer-gate-a-$(date -u +%Y%m%dT%H%M%SZ)" -RUN_DIR="/private/tmp/muse-writer-replay/$RUN_ID" -.venv/bin/python .claude/skills/evaluate-frozen-replay/scripts/run_writer_replay.py \ - --config .claude/skills/evaluate-frozen-replay/configs/writer-gate-a-deep-space-v1.json \ - --run-id "$RUN_ID" --output-dir "$RUN_DIR" --execute -.venv/bin/python .claude/skills/evaluate-frozen-replay/scripts/writer_gate.py \ - --run-dir "$RUN_DIR" --summary-output "docs/replay/$RUN_ID-writer-summary.md" -``` - -- [ ] 人工抽查每章三臂的冻结边界、证据引用、细纲执行和评委归因；发现目标章泄露则整批作废并修复后重跑。 -- [ ] 运行 `writer_gate.py` 生成唯一 Gate A 结果；不得手工改状态。 -- [ ] 若 Gate A 为 `passed`，进入任务 12 的 Gate B 多作品预注册；若 `failed/insufficient_evidence`，按 failure code 修正文层，不提前启动细纲智能体。 -- [ ] 最终提交只包含配置、代码和不含原书全文/完整细纲/完整 prompt-response 的评分摘要；原书正文、生成正文和评委原始响应只留在 `/private/tmp/muse-writer-replay//raw/`，不得复制进仓库。 -- [ ] Commit： - -```bash -git add "docs/replay/$RUN_ID-writer-summary.md" -git commit -m "验证: 裁决正文智能体 Gate A" -``` - -## 任务 12：预注册 Gate B 多作品评估集 - -**Files:** -- Create: `.claude/skills/evaluate-frozen-replay/configs/writer-gate-b-v1.json` -- Modify: `.claude/skills/evaluate-frozen-replay/scripts/test_run_writer_replay.py` -- Modify: `.claude/skills/evaluate-frozen-replay/scripts/test_writer_gate.py` - -- [ ] 只有 Gate A=`passed` 才执行本任务；否则保持配置未启用并修正文层。 -- [ ] 固定 2 本书、每书 5 章、总计 10 章，且两书都覆盖五类场景： - - 深空之影 work=8：489 战斗、321 人物对话、544 转折、199 信息揭示、523 老角色回归。 - - 机动风暴 work=4：489 战斗、95 人物对话、450 转折、210 信息揭示、414 老角色回归。 -- [ ] 配置固定每章的 `asOf=targetChapter-1`、作品/source 版本、授权快照、模型、采样参数、篇幅算法、最大预算、臂定义和随机化种子；不得根据 Gate A 或生成结果替换章节。 -- [ ] 增加配置校验测试：作品数、每书样本数、总样本数、场景覆盖、重复章、冻结点和授权任一不符即拒绝。 -- [ ] 增加判定测试：不稳定样本占比、平均退化、单样本大幅退化、保真平均增量和正向比例均按任务 9 的唯一顺序裁决。 - -```bash -.venv/bin/python .claude/skills/evaluate-frozen-replay/scripts/test_run_writer_replay.py -v -.venv/bin/python .claude/skills/evaluate-frozen-replay/scripts/test_writer_gate.py -v -.venv/bin/python .claude/skills/evaluate-frozen-replay/scripts/run_writer_replay.py \ - --config .claude/skills/evaluate-frozen-replay/configs/writer-gate-b-v1.json \ - --dry-run -``` - -- [ ] dry-run 必须证明：10/10 样本冻结正确、两书各 5 章、五类场景全覆盖、目标章/未来章读取数为 0、三臂除证据策略外无差异、所有候选不可接受。 -- [ ] Commit： - -```bash -git add .claude/skills/evaluate-frozen-replay/configs/writer-gate-b-v1.json \ - .claude/skills/evaluate-frozen-replay/scripts/test_run_writer_replay.py \ - .claude/skills/evaluate-frozen-replay/scripts/test_writer_gate.py -git commit -m "验证: 预注册正文 Gate B 多作品评估集" -``` - -## 任务 13：真实 Gate B 回放与正文层最终裁决 - -**Files:** -- Generated outside repo: `/private/tmp/muse-writer-replay//gate-report.json` -- Create after sanitization: `docs/replay/-writer-gate-b-summary.md` -- Modify after result: `docs/2026-07-20-正文智能体正式优化设计与计划.md` - -- [ ] 执行前向用户报告 10 章 x 3 臂 x detector/judge/仲裁的调用上限、模型和预算；没有明确预算记录不启动。 -- [ ] 获得预算确认后运行 Gate B，全量原始输入输出只落 `/private/tmp`： - -```bash -RUN_ID="writer-gate-b-$(date -u +%Y%m%dT%H%M%SZ)" -RUN_DIR="/private/tmp/muse-writer-replay/$RUN_ID" -.venv/bin/python .claude/skills/evaluate-frozen-replay/scripts/run_writer_replay.py \ - --config .claude/skills/evaluate-frozen-replay/configs/writer-gate-b-v1.json \ - --run-id "$RUN_ID" --output-dir "$RUN_DIR" --execute -.venv/bin/python .claude/skills/evaluate-frozen-replay/scripts/writer_gate.py \ - --run-dir "$RUN_DIR" --summary-output "docs/replay/$RUN_ID-writer-gate-b-summary.md" -``` -- [ ] 人工抽查两书各至少 2 章的 manifest、冻结边界、卡到原文指针、claim ledger 和评委归因；发现泄露或控制变量漂移则整批作废。 -- [ ] 由 `writer_gate.py` 生成唯一终态：`passed` / `failed` / `insufficient_evidence` / `no_gain`，不得手工覆盖。 -- [ ] 只有 Gate B=`passed` 才把正文层标为通过并启动“细纲智能体”设计与回放；其余终态继续修正文层或补合法样本。 -- [ ] 将脱敏摘要和终态回写任务 SoT；不提交原书、候选正文、完整细纲、完整 prompt/response 或供应商原始响应。 -- [ ] Commit： - -```bash -git add "docs/replay/$RUN_ID-writer-gate-b-summary.md" \ - docs/2026-07-20-正文智能体正式优化设计与计划.md -git commit -m "验证: 裁决正文智能体 Gate B" -``` - -## 完成检查单 - -- [ ] 设计 SoT、schema、Python 校验器和技能规范字段一致。 -- [ ] 写手无工具、无会话、不能自行绕过冻结检索。 -- [ ] 抽取卡只作为索引；抽取卡承载的既有事实能回到冻结原文，正式设定/Canonical 状态/细纲新事实能回到各自权威版本。 -- [ ] 细纲执行由 detector 硬门保证，不依赖评委事后打分。 -- [ ] 诊断候选与生产候选在契约和状态机上隔离。 -- [ ] A/B/C 回放控制变量完整，包含假阴/假阳分析。 -- [ ] Gate A/B 由唯一判定器输出，单章结果不能宣称正文层完成。 -- [ ] 本计划的正文层最终完成条件是 Gate B=`passed`；Gate A 通过只代表链路可运行。 -- [ ] Gate B 通过前不启动细纲智能体，不修改产品 API/DB/Canonical 主链。