跳到主要内容

Round-2 Review 综合 + 最终行动方案

本文档把 3 份 R2 review report（A 实施新人可读性 / B 落地 Agent 100% / C Codex 合并视角）合并为统一结论与行动方案。

Review 矩阵​

Reviewer视角关键指标性质
R2-A（Claude Code sub-agent，researcher）实施新人可读性 + 跨层一致性信心打分 4.75/5，4 小时 mental model偏"理解层"评估
R2-B（Claude Code sub-agent，researcher）工程化落地 Agent 100% 严格视角M0 完成度 80%，三检 gate 6/10 拦截能力偏"实施层"严格评估
R2-C（Codex worker-dispatch via codex exec）合并维度 + 独立验证mental model 80-85%，M0 完成度 65-75%（CLI+TUI 都做时降到 50-60%），gate 拦截 7.5/10跨 Agent 三角验证

评估对比是合理的：

  • R2-A 视角看的是"能不能读懂、能不能开工" —— 文档可读性确实优秀
  • R2-B/R2-C 视角看的是"100% 不跑偏" —— 颗粒度还不够（这是结构性的，因 LLM-as-judge 在 M6 才上线）

三份 review 共同的发现（高置信度行动项）​

P0 - 1：M0 范围二义性（R2-B + R2-C 共同发现）​

  • §25 M0 验收 描述 "⚠️ 仅 L1 → L2 降级"
  • §28.1 M0 接口子集表 描述 fallback_to_l2 是 stub
  • 两处直接矛盾

修订方案：以 §28 为准（M0 仅 L1 implement + readiness 探测 + 失败状态可观测；L2-L4 stub）。同步修订 §25 M0 验收的降级描述。

P0 - 2：CI 模板中 7 个未提供的脚本/测试文件（R2-B 独立发现）​

§28.10 CI 模板调用：

  • scripts/audit_capability_registry.py --strict
  • scripts/audit_contract_regression.py --baseline=m0-baseline
  • tests/unit/test_structured_cognition_result_schema.py
  • tests/contract/（整目录）
  • tests/m0/test_credential_isolation.py
  • tests/m0/test_synthesis_output_schema.py
  • 5 条样例 yaml 对应的 pytest runner

这 7 个文件内容文档没给，Codex 自己实现自己跑 = 守门员就是球员。

修订方案：§28 新增 §10.5 "M0 CI 脚本与测试文件的接口规范" —— 至少给 7 个文件的接口定义 + 期望断言摘要（不必给完整实现，但要让 Codex 实现时与文档预期 1:1 对齐）。

P0 - 3：M0 baseline 文件 / audit_contract_regression.py 在 M0 上跑什么（R2-B 独立发现）​

§26 说"M0 是基线 → 无前置对比"，但 §28.10 CI 调 audit_contract_regression.py --baseline=m0-baseline —— M0 阶段 gate-2 实际空转。

修订方案：§28.10 增加注释"M0 阶段 gate-2 仅生成 baseline 不做对比，从 M1 起进入对比模式；baseline 文件位于工程实施仓 .baseline/m0-contract.json，由 M0 完成时一次性生成"。

P0 - 4：audit_events.payload 按 event_type 的字段 schema 表（R2-B 独立发现）​

§28.2 AuditEvent.payload 是 dict，注释说"具体由各 event_type 文档"，但文档中没有这张表。

修订方案：§28.2 新增"§2.1 AuditEvent.payload 按 event_type 字段集"，至少列 10 种 event_type 各自的 required + optional 字段。

P0 - 5：5 类凭证正则参考实现 / BIP-39 词表 source（R2-B + R2-C 共同发现）​

§17 列识别策略表，§28.7 列 negative test fixture，但正则源码 + 词表来源未给 —— Codex 自写正则 vs "100% 拒收"目标之间无自动桥接。

修订方案：§28 新增 §11 "凭证识别正则基线 v0"，给 5 类 pattern 的 Python 代码 + BIP-39 词表的指定 source（Python mnemonic 库 vs 内嵌列表）+ Luhn 算法的引用。

P1 - 1：跨层对象映射表（R2-A + R2-C 共同发现）​

R2-A: "对象数量在三层间 5 → 7 → 6 → 8 变化" R2-C: "建议新增跨层映射表：产品五对象 / 架构七 first-class / 是否持久化 / 是否有状态机 / M0 是否实现"

修订方案：架构 §4 末尾新增一张跨层对象映射表（产品 §3 / 架构 §4 / §11 / §15 / §27 / §28），让新人一目了然。

P1 - 2：clarify 措辞跨层不一致（R2-A 独立发现）​

  • 白皮书 §7、产品定义 §4.3: "澄清路径"
  • 架构 §9.2: "工具(Tool) 且 M0 stub"
  • 架构 §28.1: clarify M0 skip（不是 stub）

修订方案：产品定义 §4.3 末尾加一句"clarify 是 Capability Registry 中的工具（非用户认知任务类型），M0 阶段 skip，M2 上线"。

P1 - 3：§22 未决问题分层（R2-C 独立发现）​

§22 缺口列了战略待定 / 工程延后 / 场景外三类，但没有显式标注哪些继承自白皮书 §15、哪些是工程层新增。

修订方案：§22 重排表头加列"来源（白皮书继承 / 产品新增 / 工程新增 / ADR 待定）"。

P1 - 4：ADR-004/008/010 措辞统一为"当前倾向"（Codex R1 + R2 共同发现）​

主架构正文有些段落把 ADR-004/008/010 的方向写得像 accepted。

修订方案：grep + sed 把全文 "倾向 LLM Function Calling 主导 / 统一 OpenAI-compatible / 两处都做" 等措辞前加"（待 ADR-N 正式 accepted）"修饰。

P1 - 5：ClarifyResponse / Chunk / ToolSpec 等"出现在接口签名但未在 §28.2 给出的 Pydantic 模型"（R2-B 独立发现）​

§9 接口表有 ClarifyResponse、§28.4 CLI streaming 有 Chunk、§9.5 Capability Registry 有 ToolSpec —— 这些 Pydantic 模型代码未给。

修订方案：§28.2 末尾加一节"M0 stub / skip 阶段需要的 placeholder 类型"，至少给 ClarifyResponse / Chunk / ToolSpec / ToolCategory 的最小字段定义。

各 reviewer 独立的次要发现（P2 级别）​

R2-A 独立​

  • 多入口契约在产品定义 §9 可补 M0/M1+ 入口优先级一列
  • 架构 §11 开篇"first-class vs 有独立状态机"注释提升为 callout
  • 产品定义 §3.5 vs 架构 §4 动态画像字段集差异（4 类 vs 5 类）

R2-B 独立​

  • 包管理器 / pyproject.toml 模板（uv/poetry/hatch 二选一）
  • CLI 框架 click vs typer
  • lint/format/type-check 工具链选定（ruff/mypy/...）
  • httpx 客户端配置 / asyncio.to_thread vs aiosqlite 最佳实践
  • trace_id 生成规范（uuid4 / ULID / Snowflake）
  • Pydantic ConfigDict 全局策略
  • migration runner 参考实现
  • CI reviewer prompt 模板（Claude Code 做 PR review 时用什么 checklist）
  • README + CONTRIBUTING 在工程实施仓的最小模板

R2-C 独立​

  • §28 DDL "M1+ 加 5 张表达成 §15 完整 8 张业务表 + schema_metadata"的数法容易混淆 → 统一为"8 张业务表 + 1 张元表"
  • 产品定义 §12 "用户接近交易行动时主动提供仓位、风险预算或时间窗口"易被理解成深一步交易建议 → 弱化措辞为"提示用户自行声明仓位/风险预算/时间窗口用于条件化检查"
  • M0 task packet 实体化样例（cwd 占位 + 验收命令 + Provider mock/real 边界）

工程化落地的"真实质量上限"​

综合三份 review 后的诚实结论：

类别自动化拦截率评估方法
机械偏离（禁词 / 凭证字段 / TLS）80-90%CI grep + Pydantic
结构偏离（schema / category / DDL）65-75%Pydantic + schema diff
跨章节一致性（状态机 vs 代码）20-30%需 contract tests 但内容未给
工具谎报 category30%需 audit_capability_registry.py 但未给
语义偏离（反方质量 / 题眼命中 / 信息缺口诚实度）10-15%M0 完全靠人工 checklist，无 CI

加权平均：约 50-55% 偏离能在 M0 阶段被 CI 拦下；剩下 45-50% 靠人工 review + 评估闭环（M6 才上）。

要把 M0 拦截能力推到 80%+，必须补：

  1. P0 清单 5 项（M0 范围 / CI 脚本 / baseline / audit payload / 凭证正则）
  2. P1 清单 5 项（跨层对象映射 / clarify 措辞 / §22 分层 / ADR 措辞 / 缺失 Pydantic 模型）
  3. R2-B 独立 9 项 P2（包管理 / 工具链 / 错误处理 等）—— 可在工程实施仓 README 而非主架构补

要拉到 95%+ 需要 M6 评估闭环上线 + LLM-as-judge —— 这是结构性约束，不是 M0 阶段能解决的。

最终行动方案​

Phase 1：M0 启动前必补（P0，9 项）​

按 review 真实价值排序：

  1. §28 新增 §10.5 "CI 脚本与测试文件接口规范" —— 给 7 个文件的接口定义（不必完整实现）
  2. §28 新增 §11 "凭证识别正则基线 v0" —— 5 类 Python pattern + BIP-39 词表 source + Luhn 引用
  3. §28 新增 §2.1 "AuditEvent.payload 按 event_type 字段集" —— 10 种 event_type schema
  4. 修 §25 M0 验收降级描述 —— 与 §28.1 对齐（L1 implement + L2-L4 stub）
  5. §28.2 末尾加 placeholder 类型节 —— ClarifyResponse / Chunk / ToolSpec / ToolCategory
  6. 修 §28.10 CI 注释 —— gate-2 在 M0 仅生成 baseline 不对比
  7. §28 新增 §12 "工程实施仓 bootstrap 模板" —— pyproject.toml + 工具链选定（ruff + mypy + uv + click + httpx + aiosqlite + structlog）+ trace_id 用 uuid4 + Pydantic ConfigDict extra='forbid'
  8. 架构 §4 末尾新增跨层对象映射表 —— 产品 § / 架构 § / 状态机 / DDL / M0 实现度
  9. §9 / §28 / 主架构 ADR-004/008/010 措辞统一加"(待 ADR-N 正式 accepted)"修饰

Phase 2：可读性 P1 修订（5 项）​

  1. 产品定义 §4.3 加 clarify 是工具非任务类型的明示
  2. §22 缺口表加"来源"列（白皮书继承 / 产品新增 / 工程新增 / ADR 待定）
  3. 产品定义 §1 加 "7 任务是输出语义 / 6 子系统是 runtime 结构，两者正交"
  4. 产品定义 §3 末尾加 "工程层会派生 Task / StructuredCognitionResult / StateCandidate / TaskGroup 等工程对象，详见架构 §4 / §11"
  5. 产品定义 §12 "主动提供仓位" → "提示用户自行声明仓位"

Phase 3：工程实施仓侧补充（不在主架构）​

  1. M0 task packet 模板（OpenSpec 提案使用）
  2. CI reviewer prompt 模板（Claude Code 做 PR review 用的 checklist）
  3. README + CONTRIBUTING 在工程实施仓

Phase 4：M6 评估闭环上线时（远期）​

  1. ADR-004/008/010 正式 accepted（去掉"当前倾向"措辞）
  2. LLM-as-judge 上线 + 语义层拦截能力从 10% 拉到 60%+

关键决策点（请用户裁决）​

  1. 是否立刻执行 Phase 1 + Phase 2（共 14 项主架构修订），目标把 M0 落地完成度从 65-80% 拉到 90%+？
  2. 是否把 Phase 3 工程实施仓侧补充列入 M0 启动前的 task packet 一部分（OpenSpec 提案承接）？
  3. 是否对 ADR-004 / ADR-008 / ADR-010 起一个"M0 最小 accepted 版"（不必完整论证，但锁住 M0 阶段的接口）？

我的建议：Phase 1（9 项 P0）必做，Phase 2（5 项 P1）建议做，Phase 3 在 M0 启动时由 task packet 承接，Phase 4 留作 M6。

整体推进序：

  • Phase 1 → 重新合并主文档 → verify → 启动 M0 task packet 起草
  • Phase 2 → 同上
  • Phase 3 → 与 M0 OpenSpec 提案同步
  • Phase 4 → M6 里程碑

预估时间：Phase 1 + Phase 2 在本会话内可完成（小修订为主，§28 加 4 节为大头）；之后 M0 task packet 起草是下一轮工作。