跳到主要内容

Review 综合与行动方案

本文档把 3 份 Claude Code sub-agent review report + Codex worker-dispatch 任务包（待用户分发） + 主会话自查发现合并为统一行动方案。

Review 矩阵​

Reviewer维度范围状态report
Sub-agent A跨章内部一致性主架构 27 节（深读 §4-13/15/17/18/20/21/23/27，浅读其余）✅ 完成2026-05-27-review-A-cross-chapter-consistency.md
Sub-agent B上位文档对齐战略白皮书 + 产品定义文档 vs 主架构✅ 完成2026-05-27-review-B-upper-doc-alignment.md
Sub-agent C工程可实施性M0 走通骨架 + 子系统接口完备度 + 测试/评估可执行度✅ 完成2026-05-27-review-C-engineering-feasibility.md
Codex战略保真度 + 业务建模自洽 + 写作纪律 + 综合独立验证全篇 5796 行 + 上位文档 cross-check🟡 任务包已准备codex-review-task-spec.md（待用户粘贴到 Codex 跑）
Claude Code 主会话整合 + 自查（禁词 grep / Mermaid 错误修复 / merge 完整性）同步进行✅ 完成（本文档）

三个 Reviewer 的 P0 清单（去重合并）​

P0-1：§8 vs §27 代码骨架冲突（Reviewer A）​

问题：§8 用 finbayes/cli/、finbayes/cognition/web_tasks.py 等旧路径；§27 用 src/finbayes/io/entries/{cli,tui,web,mcp,channels}/ 标准 src layout。两套互斥目录骨架，照 §8 实施会导致与 §27 / §17 / §18 / §20 / §21 / §25 全部不兼容。

根因：§8 是早期章节产出，§27 是最后产出，重写过程中 §27 升级了代码组织约定但 §8 未同步更新。

修复方案：以 §27 为事实源，重写 §8 "当前容器→代码包映射"段落，统一加 src/ 前缀与 io/entries/ 层级；或彻底删 §8 该段，仅写"详见 §27"。

P0-2：§11 状态机清单 vs §27 状态机映射 不一致（Reviewer A）​

问题：

  • §11 列 5 个 first-class 状态机：Session / Task / TaskGroup / Judgment Record / StateCandidate
  • §27 列 5 个状态机：Task / Fin Object / Judgment Record / State Candidate / Provider Readiness
  • §25 说"完整 5 个状态机"但不指明哪 5 个

Session、TaskGroup 在 §27 消失；Fin Object（§4 没说有状态机）、Provider Readiness（§9 没建状态机定义）凭空出现。

修复方案：在 §11 与 §27 之间统一一份权威清单。倾向保留 §11 的 5 个 + 加入 Provider Readiness = 6 个（Session/Task/TaskGroup/JR/Candidate/ProviderReadiness），把 Fin Object 移到"无独立状态机的对象"类。具体待 ADR 或 OpenSpec 提案裁决。

P0-3：M0 子系统切片边界不闭合（Reviewer C）​

问题：§25 M0 矩阵把 6 个子系统全标"✅"或"⚠️ 最小可用"，但每个子系统未定义"M0 切片到哪一行接口"。Codex 没法判断 State Management M0 是否要实现 confirm_candidate 等接口。

修复方案：新增"M0 接口子集表"，按 6 子系统列出 M0 implement / M0 stub / M0 skip 三栏。

P0-4：§9 关键接口签名缺类型（Reviewer C）​

问题：6 个子系统的"关键接口"表只给自然语言伪签名（"输入：归一化输入 / 输出：TaskGroup"），没给 Pydantic schema 或 Python type hint。M0 核心 dataclass（NormalizedInput / TaskGroup / EvidencePlan / EvidencePacket / StructuredCognitionResult / StateCandidate）只有名字没字段。

修复方案：新增附录"M0 核心 Pydantic 模型 v0 草案"，给 6 个核心 dataclass 的字段级 schema。

P0-5：M0 验收"题眼命中 / 反方 / 失效条件"无判定脚本（Reviewer C）​

问题：M0 验收要求"5 条样例输入，输出含反方 + 失效条件 + 题眼命中"。前两项可走 Pydantic 必填字段（schema 还要补），"题眼命中"在 §21 是 LLM-as-judge 维度但 M6 才上。M0 阶段如何判定？

修复方案：明示 M0 退化判定 = "schema 字段非空 + 长度下限 + 人工 5 条 checklist"。

P0-6：§26 样本断言依赖 M6 才有的评估运行器（Reviewer C）​

问题：§26 列出每个里程碑（含 M0/M1）都要"样本断言"走评估运行器，但 §21 评估运行器在 M6 才上。M0-M5 期间样本断言怎么落？

修复方案：在 §26 明示"M0-M5 用简化判定：5 条 fixture + Pydantic + grep + 人工 checklist 充当样本断言；M6 起切换到评估运行器"。

P0-7：§17 凭证识别正则未提供基线集（Reviewer C）​

问题：§17 列 6 类凭证识别策略但正则放在工程实施仓。M0 验收第 4 项"5 类凭证样式输入全部拒收"没有 negative test set 基线。

修复方案：新增附录"5 类凭证样式的 minimum negative test fixture"作为本仓内联（M0 实施 Codex 直接复用）。

P0-8：§27 工程实施仓路径"不写入本仓"导致 Codex 无 cwd（Reviewer C）​

问题：§27 说工程实施仓物理路径"由维护者本地记录"。Codex 在 M0 接手时 task packet 缺少工程实施仓绝对路径。

修复方案：§27 新增段"工程实施仓的发现路径：通过 OpenSpec task packet 携带 working_directory 字段；维护者级 user memory finbayes_repos.md 是 fallback 引用"。

P0-9：战略白皮书 5 处旧术语命中（Reviewer B + 主会话自查）​

详见下方"上位文档修订方案"段。

P1 / P2 清单（精选高价值）​

来自 Reviewer A：

  • §15 表数量"8 vs 6"漂移（mermaid 与文字不一致）
  • 业务对象命名中英混用（建议 §4 加"工程英文名"列）
  • §10 S5 标题降级层级与图内容不符（写"L1→L2→L3"但内容 5 层）
  • §13 / §18 / §20 对 L1' 表示形式抖动（L1A / L1B / L1' / L1b 三套）

来自 Reviewer C：

  • §12 asyncio 跨任务 trace ID 传递机制未指定（建议 contextvars.ContextVar）
  • §19 Schema migration 幂等机制未指定
  • §19 Prompt prompt_id 命名规范缺
  • §20 LLM Mock fixture hash 字段白名单未具体化
  • §18 日志脱敏的具体实现路径（structlog vs Pydantic SecretStr vs logging Filter）
  • §21 软/硬阈值数值"3.5/5"的来源与校准方法

来自主会话自查：

  • CHAP-25 Mermaid 双引号 parse error（已修复）
  • 主文档合并完整性（已 verify ✅）

上位文档修订方案​

详见 Reviewer B 报告。这里给出可直接拿到 governance/change-protocol.md 流程的草案。

战略白皮书修订草案​

#行号现状改为理由
S1.1L109"形成条件化判断、准备行动方案和复盘历史判断""形成条件化判断、准备交易行动前检查与复盘历史判断"战略与工程层术语统一
S1.2L158"准备一次行动判断""准备一次交易决策"同上
S1.3L182"还是准备行动判断""还是准备交易决策"同上
S1.4L286"条件化、概率化的行动准备支持""条件化、概率化的交易准备支持"同上
S1.5L310"反方、条件化判断、历史复盘和行动准备支持""反方、条件化判断、历史复盘和交易准备支持"同上

辅助 P1 修订：在 §6.3 或 §7 末尾补一段：

"第一阶段识别七类金融认知任务：解释、分析、比较、复盘、风险识别、交易准备、交易决策辅助。具体定义由产品定义文档承接。"

辅助 P2 stub 指针（详见 Reviewer B 表）：

  • §14 末尾补"长期状态对象的写入遵循候选→用户确认两步契约（详见架构 §11）"
  • §14 第二段后补"用户在本地优先单机部署中配置 Provider 偏好是 first-class，工程层提供 4 层降级保障 LLM 不可用时仍可用（详见架构 §9 / §13）"

产品定义文档修订草案​

无 P0。

P1（L24 文档分工句细化）：

加入："架构文档（architecture.md）中关于状态对象生命周期、降级链、子系统职责、ADR 等工程细节是本文档的延伸定义，本文档不重复定义。"

P2 stub 指针（详见 Reviewer B 表）：

  • §1 / §11 末尾补"工程实现按 6 子系统组织，详见架构文档 §9"
  • §3.4 / §3.5 末尾补"候选→已确认两步写入工程承接详见架构 §11"
  • §9 多入口契约补"Provider 选择走 4 层降级，详见架构 §9 / §13"
  • §10.3 末尾补"凭证不变量端到端阻断工程细节见架构 §17"
  • §4.3 末尾补"自然语言到任务的识别策略由 ADR-004 决议"

上位文档修订的执行流程​

  1. 起 OpenSpec 提案 governance/proposals/inbox/2026-05-27--upper-doc-alignment-after-arch-v2.md
  2. 内容含：S1.1-S1.5（5 处术语替换，P0）+ 战略白皮书 §6.3 / §7 / §14 段落补充（P1/P2）+ 产品定义文档 L24 / §1 / §3.4 / §3.5 / §4.3 / §9 / §10.3 stub 补充（P1/P2）
  3. 走 governance/change-protocol.md 流程
  4. 评审通过后再编辑两份上位文档

给 Codex 的 worker-dispatch 任务包​

路径：governance/workstreams/finbayes-arch-rewrite/reviews/codex-review-task-spec.md

用户操作：复制该文档全部内容到 ChatGPT Pro / Codex，让 Codex 独立完成深度 review；Codex 完成后把 review report 粘贴回 Claude Code，主会话整合到本文档"Codex 独立发现"段。

Codex review 的独特价值：与 3 个 sub-agent 不同维度的覆盖（战略保真度深度 + 业务建模逻辑自洽 + 写作纪律），跨 Agent 三角验证。

行动方案（按优先级排序）​

立即可执行（无需评审）​

  • ✅ Mermaid parse error 修复（CHAP-25 已修）
  • ✅ 3 份 sub-agent review 持久化
  • ✅ Codex worker-dispatch 任务包准备好

待用户决策​

  1. 派发 Codex review（用户复制任务包到 ChatGPT Pro 跑）
  2. 上位文档对齐 OpenSpec 提案（用户授权后由 Claude Code 起草，走 governance/change-protocol.md）

待评审通过后执行（不可绕过流程）​

  1. 修订战略白皮书 5 处旧术语 + P1/P2 补充
  2. 修订产品定义文档 L24 + P2 stub 指针补充

主架构修订（高优先级，需用户决策修订路径）​

  1. §8 / §27 代码骨架统一：选 §27 为事实源，回到 drafts/CHAP-08-*.md 修订后重新合并
  2. §11 / §27 状态机清单统一：在 §11 与 §27 之间裁决，回到 drafts/CHAP-11-.md 与 CHAP-27-.md 修订后重新合并
  3. 新增附录"M0 工程包"（10 项 deliverable，详见 Reviewer C 末段）—— 这是 Codex 接手 M0 的前置条件
  4. §9 接口签名补 Pydantic schema（M0 核心 6 个 dataclass）
  5. §17 凭证 negative test fixture 内联
  6. L1' 表示形式统一（选定 L1' 为标准形式，全篇统一）

其他 P1（在 ADR / 工程实施仓 落点）​

  • ADR-005 写并发原语时含 contextvars.ContextVar 决定
  • ADR-008 写 Provider 接口时含 LLM Mock fixture hash 规范
  • ADR-009 写 Prompt 版本化时含 prompt_id 命名规范
  • ADR-010 写输出端过滤时含正则集合
  • §18 日志脱敏机制 ADR / 工程实施仓决定（不一定独立 ADR）

给用户的关键决策点​

请用户在下列 3 类决策中选择推进方向（可多选）：

A. 主架构修订（高优先级）

  • A1：是否立刻修订 §8 / §27 代码骨架冲突？（回 drafts/ 修后重新合并主文档）
  • A2：是否立刻修订 §11 / §27 状态机清单不一致？

B. 上位文档对齐

  • B1：是否立刻起草上位文档对齐 OpenSpec 提案？（5 处术语 P0 + P1/P2 stub）

C. 工程包补全

  • C1：是否立刻起草 §28 "M0 工程包" 附录？（含 10 项 deliverable，是 Codex 接手 M0 的前置）

D. Codex review

  • D1：是否立刻派发 Codex 独立 review？（用户复制任务包到 ChatGPT Pro）

建议优先级：D1（成本最低，跨 Agent 三角验证最大价值） → A1 + A2（阻断 M0 启动的核心修订） → B1（上位文档对齐，与 A 并行不冲突） → C1（M0 工程包，在 A 与 B 完成后）。