跳到主要内容

Review C — 工程可实施性

Sub-agent (researcher) 在主会话外的独立 review，于 2026-05-27 完成。原文未删改。

我已读取了 review 所要求的所有重点章节（§ 8/9/10/11/12/13/15/16/17/18/19/20/21/25/26/27）。§ 8/10/11/14/16 的具体内容也都看到了核心结构。

P0 阻断（不补这些 Codex/人类没法开工）​

  • § 25 / § 9 M0 子系统"最小可用版本"边界不闭合：§ 25 M0 矩阵把 6 个子系统全标"✅"或"⚠️ 最小可用"，但每个子系统未定义"M0 切片到哪一行接口"。例如 § 9 State Management 列了 9 个接口（create_candidate/confirm_candidate/...），M0 只要 Fin Object 单一对象，到底实现哪几个？必须补"M0 接口子集表"（每个子系统列 M0 implement / M0 stub / M0 skip 三栏）。
  • § 9 关键接口签名缺类型：6 个子系统的"关键接口"表只给"输入：归一化输入 / 输出：TaskGroup"这类自然语言伪签名，没给 Pydantic 模型或 Python type hint。M0 实施需要的 NormalizedInput / TaskGroup / EvidencePlan / EvidencePacket / StructuredCognitionResult / StateCandidate 这 6 个核心 dataclass 的字段级 schema 在文档里只有名字没有 fields。Codex 没法 import 也没法 mock。必须补附录"M0 核心 Pydantic 模型 v0 草案"。
  • § 25 M0 验收"题眼命中 / 反方 / 失效条件"无判定脚本：M0 验收第 3 项"5 条样例输入，输出含反方 + 失效条件 + 题眼命中"——前两项可走 Pydantic schema 必填字段（schema 还要补），"题眼命中"在 § 21 是 LLM-as-judge 维度，但 M6 才上 judge。M0 阶段如何判定？要么降级为"含 main_answer 非空字段"机械断言，要么明示"M0 用人工 5 条 checklist"。现在两可。
  • § 26 "样本断言"对接评估运行器但 M6 才有运行器：§ 26 列出每个里程碑（含 M0/M1）都要"样本断言"走评估运行器，但 § 21 评估运行器在 M6 才上。M0-M5 期间的"样本断言"具体怎么落？必须明示"M0-M5 用简化判定 / 仅冒烟 5 条 fixture + Pydantic + grep 充当 样本断言"。
  • § 17 凭证识别正则未提供基线集：§ 17 列了 6 类凭证识别策略（私钥 / 助记词 / API key / 银行账户 / Luhn / "用户贴整段配置"）但正则放在工程实施仓——M0 验收第 4 项"5 类凭证样式输入全部拒收"要求 negative test set，但 negative test set 在哪？必须把"5 类凭证样式的 minimum negative test fixture"作为附录纳入本仓（或 § 17 内联），否则 M0 验收没基线。
  • § 27 工程实施仓的物理路径"不写入本仓"导致 Codex 无 cwd：§ 27 反复说工程实施仓物理路径"由维护者本地记录"。Codex / Claude Code 在 M0 接手时，task packet 必须包含工程实施仓绝对路径 + 该路径在哪条 memory（user memory: finbayes_repos.md 已存在，但本架构文档未引用）。建议 § 27 新增一段"工程实施仓的发现路径：通过 OpenSpec task packet 携带"。

P1 重要（M0/M1 阶段可能卡壳）​

  • § 12 asyncio 跨任务 trace ID 传递机制未指定：§ 18 trace ID 体系列了 5 类 ID，§ 12 用 asyncio.TaskGroup，但没说用 contextvars 还是显式参数透传。子任务 spawn 时 task_id 如何继承到 httpx 调用？M1 写并发就会卡。建议明示采用 contextvars.ContextVar + 在 TaskGroup 创建子任务时绑定。
  • § 19 Schema migration 单向 + 幂等：§ 19 说"migration 必须幂等"但未说幂等通过什么机制保证——是 CREATE TABLE IF NOT EXISTS 这类幂等 DDL？还是 migration runner 检测 schema_metadata.migration_history 跳过已跑脚本？两种做法约束完全不同。M7 演练时会撞到。
  • § 19 Prompt prompt_id 命名规范缺：列了 frontmatter 字段（prompt_id / prompt_version / delivery_mode / ...）但 prompt_id 的命名约定（按子系统 / 按任务类型 / 按 Provider）未定。多人协作时会冲突。
  • § 20 LLM Mock 录制重放的 fixture 文件结构 + hash 算法："请求 hash 基于关键参数（model / messages / tools）+ 忽略时间戳"——但 messages 含可变字段（如 user_id / session 时间戳 / 自动注入的上下文）。具体哪些字段进 hash、哪些规范化（如 strip 时间戳 / sort tools）没说。Codex 实现 Mock Provider 时这是最容易翻车的地方。
  • § 20 "Provider 端 API 变化检测"机制未具体化：说"fixture 失效时 CI 给明确报错"——但 Provider 端 API 变化检测靠真档每周跑 + diff fixture 还是fixture 含 Provider API 版本字段？前者要 nightly schedule，后者要 fixture schema。
  • § 18 日志脱敏的具体实现路径：列了"不写入 API key / 凭证 / 完整画像"但没说用什么机制（Python logging Filter？Pydantic SecretStr？structlog processor？）。Codex 单点决策风险。建议建 ADR 或附录指定 structlog + custom processor + Pydantic SecretStr 三件套。
  • § 21 评估运行器与 runtime "解耦"机制：说"通过 runtime 公开 API 调用（CLI / Web API），不直接 import"——但 M6 评估时 Web API（M3 才上）+ CLI（M0 上）的接口稳定度未保证。具体协议是 stdin/stdout JSON Lines？HTTP？需明示。
  • § 26 "战略原句存在"grep 模式过简：grep "FinBayes 不直接下单" 字面字符串，但同义改写（如"FinBayes 不替代下单系统"）就漏。§ 26 自己也说"语义断言"靠 Claude Code Review，但人工 review 没有 prompt 模板 / checklist。建议附录"语义 Review 提示词 v0"。
  • § 21 软/硬阈值的具体数值留白：表给了 "overall_score >= 3.5/5" 等"第一阶段建议"——这些数字是怎么来的？M6 上线前没有 baseline data 怎么校准？建议明示"M6 上线时跑 1 周收集 baseline，阈值按 baseline 5 分位数定"。

P2 改进建议（后续里程碑可在实施中补全）​

  • § 9 Provider Adapter L3 "logistic regression on embedding 兜底分类"：突兀引入 logistic regression，与"无 ML 训练管道"的本地优先定位有张力。建议改为"BM25 + 关键词词典"或起 ADR 论证。
  • § 15 Audit Trail 写入异步化 "允许丢少量边界 case"：与战略保真度审计要求"边界拒收事件 100% 进审计"潜在冲突。建议拆分：边界事件同步写，常规审计异步写。
  • § 14 升级流程（未深读）建议补"Codex 手动跑 migration 的 dry-run 命令"。
  • § 8 单进程优先：M3 引入 Web API 后是否仍单进程？asyncio 单进程同时跑 CLI + Web API + Channel 的资源边界未谈。
  • § 19 工具 schema 变更分类："新增 optional 参数 minor / 改 required 参数 major"——但 LLM Function Calling 对工具描述字符串变化非常敏感（影响选工具准确率），描述变更也应该走 minor + 评估回归。
  • § 16 错误码语义 建议在 § 27 给一个错误码字典文件路径。

实施完整度强项（已经够具体）​

  • § 9 6 子系统的"组件图 + 职责 + 失败模式 + 验收信号"四件套结构完整：每个子系统都给了 mermaid 组件图 + 失败模式表 + 验收信号，框架填空式实施。
  • § 11 5 个状态机的转移矩阵清晰，Task / Fin Object / JR / Candidate / Provider Readiness 各自有独立 state enum。
  • § 12 asyncio.TaskGroup 选型 + 示意代码 + 超时分层表（5 级超时默认值齐备）已经够 Codex 直接落代码。
  • § 13 故障决策树的 mermaid + Provider 4 层降级的用户感知矩阵够具体到能写测试。
  • § 15 5 类存储 + 8 张表的 schema 总览够 M1 起 sqlite 表。
  • § 17 凭证类型与识别策略表 + 双向阻断图够 M0 落输入边界 hook 骨架（仍缺正则基线，见 P0）。
  • § 20 测试金字塔 + CI 三档（PR/nightly/release）+ Mock 三模式整体框架够支撑 M6。
  • § 27 子系统 / 业务对象 / 状态机 / 存储 / 测试 / 评估 / 部署的 7 张映射表够 Claude Code 起 OpenSpec 提案。

Codex 接手 M0 所需的"工程包"清单（建议补充到 § 25 或新增附录）​

建议在 § 25 M0 段下，或新增 § 28 "M0 task packet 规范"，包含：

  1. M0 接口子集表：按 6 子系统列出 M0 必须 implement / stub / skip 的接口名单（如 State Management M0 仅需 append_audit + read_session_context）。
  2. M0 核心 Pydantic 模型 v0：NormalizedInput / Task / EvidencePacket / StructuredCognitionResult 4 个 dataclass 的字段级 schema（含 schema_version=1）。
  3. M0 SQLite DDL v0：仅 2 张表（audit_trail + sessions），含 migrations/001_initial.sql 模板。
  4. M0 CLI 命令规格：finbayes ask <text> 流式输出格式 + 退出码约定。
  5. M0 Mock Provider fixture 规范：fixture 目录结构 + hash 字段白名单 + 一条样本 fixture（OpenAI Function Calling 格式）。
  6. M0 5 条样例输入 + 期望"能力清单"：作为验收 fixture（含 ETH 走势分析 / PE 概念解释 / etc）。
  7. M0 5 类凭证 negative test fixture：与 § 17 一致的 negative cases，每类 2-3 条。
  8. M0 "题眼 / 反方 / 失效条件"判定规则 v0：M0 阶段不上 LLM-as-judge 时的退化规则（schema 字段非空 + 长度下限 + 人工 5 条 checklist）。
  9. 工程实施仓发现路径协议：task packet 第一行必带工程实施仓绝对路径 + 提示读 user memory finbayes_repos.md。
  10. M0 三检 review gate 的 CI 模板：.ci/m0-gate.yml 草案（机械 grep / Pydantic schema 校验 / pytest -m m0 / verify-kb）。

Review 范围声明：完整读了 § 8/9/10（头）/12/13/15/16(头)/17/18/19/20/21/25/26/27。§ 10 8 个 sequence 详情、§ 11 状态机内部转移、§ 14 部署形态详情、§ 16 协议细节、§ 22-24 缺口 / ADR / 风险三章未细读——但这三章不在用户要求重点之列，已被略过。所有 P0/P1 论断都基于实际读到的章节文本。