跳到主要内容

Review D — Codex 独立 Review

Codex worker-dispatch（通过 codex exec CLI 调度），于 2026-05-27 完成。Codex 在主会话起完战略白皮书 5 处修订后运行，因此独立观察到"5 处 exact 旧术语已不成立"，反向验证主会话修订生效。原文从此处起未删改。

Codex 独立 Review Report — FinBayes 架构文档 v2

维度 1：战略保真度​

P0 阻断​

我没有在主架构文档中发现直接违反“凭证不变量 / 不直接下单 / 不替用户决策 / 用户画像主权”的 P0。projects/finbayes/engineering/architecture.md:140-157 明确继承“不直接下单、不持有账户凭证”和“金融执行凭证一律不收、不存、不训练”；projects/finbayes/engineering/architecture.md:161-165 明确画像只能服务沟通效率，不进入证据筛选；projects/finbayes/engineering/architecture.md:2971-2973 又在安全章节把三条战略边界映射到输入 hook、工具注册拒绝、输出契约。

真正的 P0 候选在上位战略白皮书，而不是主架构：用户给出的“白皮书 5 处旧术语”与当前文件不完全一致。当前 projects/finbayes/strategic-whitepaper.md 中，行动方案、行动判断、行动准备 exact grep 没有命中；但仍有多处“行动”残留，例如 projects/finbayes/strategic-whitepaper.md:109 “准备交易行动前检查”、:286 “接近交易行动”、:310 已是“交易准备支持”。如果禁入规则是 exact phrase，则当前 5 处已不成立；如果禁入规则扩展为避免“行动”作为任务语义中心，则 :109 和 :286 仍应修。

P1 重要​

第一，主架构对“凭证字段不进 schema”的设计方向正确，但 §26 的机械断言写的是 grep private_key / mnemonic / api_secret 0 命中，白名单为边界测试 fixture（projects/finbayes/engineering/architecture.md:5324-5327）。问题是主架构正文自己在工具 schema 拒绝示例中出现 private_key / mnemonic / api_secret（projects/finbayes/engineering/architecture.md:3093），这属于合法元引用，但会让未来自动审计必须有“文档元引用白名单 + 代码 schema 零命中”两套规则，否则会误报或被迫放宽。

第二，输出契约有反方和失效条件硬约束，但“风险”字段的命名不完全稳定。产品定义要求交易准备类含“反方证据、失效条件、不确定性、信息缺口、非指令标注”（projects/finbayes/engineering/product-definition.md:286-294）；架构测试要求综合层 schema 含“反方 / 风险 / 失效条件”（projects/finbayes/engineering/architecture.md:3817-3818、:5334）。建议统一为 schema 最小字段集：counter_evidence、risk_or_adverse_case、invalidation_conditions、uncertainty_or_evidence_gap、non_instruction_notice，避免“风险”在不同任务里被理解成可选描述项。

第三，Provider Credential Store 的边界需要在 ADR-010 或 ADR-008 中进一步锁死。架构已经区分金融执行凭证与本机 Provider secret（projects/finbayes/engineering/architecture.md:154-157、:2693-2696），但 M0 把 Credential / Config 简化（:5081），同时又要求 Provider 调用链审计完整（:5097）。这会给实现者留下“临时把 key 放 env/config”的空间，需要 M0 工程包明确 negative test：任何 Provider key 原文不得进日志、审计、State Store、fixture。

强项​

主架构的战略保真度总体强。它不是只声明边界，而是把边界落到输入边界 hook、输出过滤、Capability Registry、State Store、Audit Trail、测试、评估、代码路径映射。特别是 S6 凭证拒收时序（projects/finbayes/engineering/architecture.md:1661-1677）、工具注册拒绝（:3072-3093）、边界测试（:3960-3975）和 M0 审计点（:5416-5424）形成了闭环。

维度 2：业务建模一致性​

Watchlist 端到端​

Watchlist 在 §4 被定义为用户主动维护的 Fin Object 集合，支持不同对象类型、分组、关注密度、复盘节奏，并与历史判断联动（projects/finbayes/engineering/architecture.md:331-337）。§9 State Management 把它列入长期状态，并要求 candidate → confirmed 两步写入（:1151-1198）。§15 映射到 SQLite watchlist_objects 表（:2613）。§27 映射到 src/finbayes/state/watchlist.py:Watchlist 与 watchlist_objects（:5587-5589）。一致性较好。

主要缺口：§11 的 5 个状态对象没有单独列 Watchlist 生命周期，只有 StateCandidate 映射到 Watchlist Object（:1943-1948）。这意味着 Watchlist 是 first-class 业务对象，但不是 first-class 状态机。可以接受，但应明示“Watchlist 的状态变化由 StateCandidate + Confirmed Store 管理，不独立建 WatchlistState”。

Judgment Record 端到端​

Judgment Record 在 §4 字段完整：时间戳、Session、Fin Object、判断方向、支持理由、反方、成立/失效条件、不确定性、复盘链（projects/finbayes/engineering/architecture.md:382-394）。§11 有完整生命周期：Candidate → Confirmed / ConfirmedEdited → Active → ReviewTriggered → Updated / Archived / Rejected（:1873-1908）。§15 有 judgment_records 表（:2614）。§27 映射 src/finbayes/state/judgment.py:JudgmentRecord 和 JudgmentState（:5588-5591、:5607-5610）。这是三者里最完整的对象。

风险点：产品定义说删除或归档 Session 时，长期资产“按用户选择保留或同步删除”（projects/finbayes/engineering/product-definition.md:127），但架构 §11 明确 Session 删除不级联 Judgment / Watchlist（projects/finbayes/engineering/architecture.md:1794-1799、:1964-1967）。这里存在产品定义与架构差异。建议修产品定义为“默认不级联，若提供同步删除必须二次确认并按资产逐项列出影响”。

State Candidate 端到端​

State Candidate 在 §4 被排除为工程实现细节（projects/finbayes/engineering/architecture.md:415-422），在 §9 成为 State Management 的关键接口：create_candidate、confirm_candidate、reject_candidate（:1200-1211）。§10 S4 给出用户确认、编辑、拒绝、清空当前 Session candidates 的时序（:1576-1611）。§11 定义 Pending、Confirmed、ConfirmedEdited、Rejected、Expired（:1914-1941）。§15 映射 state_candidates 表（:2616），§27 映射 src/finbayes/state/candidate.py:StateCandidate（:5591、:5610）。一致性强。

缺口是 payload schema 未落表。§11 只说“候选要转化的目标对象 schema”（:1960），但没有列 candidate_type、payload_json、target_schema_version、expires_at、source_task_id、user_edit_diff 这些实现必要字段。M1 前应补在工程包或 ADR-007。

Task Orchestration 子系统​

§9 将 Task Orchestration 定义为 LLM Function Calling 驱动的工具选择，不预设意图分类管道，任务类型作为事后标签进入审计（projects/finbayes/engineering/architecture.md:984-1063）。§10 S1/S2/S7 分别覆盖单任务、复合 TaskGroup、clarify 回路（:1469-1503、:1507-1539、:1683-1708）。§12 用 asyncio.TaskGroup 映射业务 TaskGroup（:1988-2026）。§27 映射 src/finbayes/orchestration/（:5574-5576）。一致。

但 ADR-004 尚未 accepted，而主文档已把 LLM Function Calling 主导写成事实（:1028-1030、:4580）。这不是 P0，但属于决策状态不一致：要么 ADR-004 先落 accepted，要么主文档措辞改成“当前草案倾向”。

Provider Adapter Pool 子系统​

§9 Provider Adapter 描述 L1 用户 Provider、L1' 系统默认、L2 本地、L3 缓存规则、L4 受限菜单（projects/finbayes/engineering/architecture.md:1315-1415）。§13 故障路径承接 4 层降级，§20 要求降级路径测试覆盖 L1→L4（:3940-3957）。§27 映射 src/finbayes/providers/adapter.py、llm/、data/、readiness.py、routing.py（:5579）。一致性较好。

风险在实现复杂度：M0 只做 L1→L2（:5079），但 M0 仍包含 6 个子系统最小可用（:5075）。如果没有 Provider interface subset，Codex 很容易过度实现 L3/L4 或反过来跳过 readiness/audit。

不一致清单​

  1. 产品定义允许 Session 删除时同步删除长期资产，架构默认不级联删除。
  2. Watchlist 是 first-class 业务对象，但 §11 没有 Watchlist 生命周期。
  3. ADR-004/008/010 仍 proposed，主文档局部写法已像 accepted。
  4. §15 说 State Store 包含 6 类业务对象表（projects/finbayes/engineering/architecture.md:2592），M1 又说完整 8 张表（:5112-5114），表数口径不一致。
  5. M0 选择 Fin Object 作为状态对象（:5042），但验收又要求审计 trail 完整 Provider 调用链（:5097），状态对象范围和审计状态范围需要拆开说明。

维度 3：写作纪律​

抽查结论​

整体写作纪律明显优于普通架构文档。大多数图后都有“这张图表达什么 / 不表达什么 / 怎么读”三段说明，例如 §4 关系图（projects/finbayes/engineering/architecture.md:292-312）、§25 里程碑图（:5007-5029）、§21 评估闭环图（:4084-4112）。文档以业务边界和工程承接为主，没有大量解释方法论。

违反纪律的位置​

§12 的 asyncio 选择里有较多方法论解释，但尚可接受，因为它直接约束实现（projects/finbayes/engineering/architecture.md:1988-2026）。§20/§21 对测试金字塔、评估测试与 LLM-as-judge 展开较多（:3777-3802、:4068-4080），有轻微“教学化”倾向，但内容仍服务工程验收。§23 ADR 编写规范段落可能偏流程文档化，放在主架构中略重；不过 ADR-002 要求主文档列摘要和链接，当前没有严重越界。

真正需要修的是“业界研究确认”多次出现但无引用，如 LLM 多轮 function calling 不稳定、verbalized confidence 不可信（:1030、:1116）。如果主文档不放研究引用，应改成“基于当前工程假设/调研结论，详见 ADR-004/调研产物”。

维度 4：上位文档对齐​

战略白皮书 5 处旧术语核查​

当前文件中，用户列出的 5 处 exact 旧术语不成立：

  • projects/finbayes/strategic-whitepaper.md:109 当前是“准备交易行动前检查”，不是“行动方案”。
  • :158 当前是“准备一次交易决策”，不是“行动判断”。
  • :182 当前是“准备交易决策”，不是“行动判断”。
  • :286 当前是“交易准备支持”，不是“行动准备”。
  • :310 当前是“交易准备支持”，不是“行动准备”。

所以如果 Claude Code 主会话仍看到 5 处旧术语，可能是基于旧版本或未刷新文件。当前 exact grep 结果不支持“5 处 P0”。

还有没有遗漏​

白皮书仍有“行动”语义残留，尤其 projects/finbayes/strategic-whitepaper.md:109、:286、:251、:263。其中大多数是“交易行动”作为执行域名词，不等同于禁入任务类型名；但 :109 的“准备交易行动前检查”可改为“交易前检查”，更干净。

主架构中的禁词 exact 命中均在合法元引用段：§2 术语约定（projects/finbayes/engineering/architecture.md:193-195）、§17 Review Gate（:3191-3199）、§23 拒绝概念表（:4604-4616）、§26 同义审计示例（:5340-5343）。未发现“行动倾向”等绕过命中。

产品定义文档对齐核查​

产品定义与新架构总体对齐：任务类型清单一致（projects/finbayes/engineering/product-definition.md:181-193 vs projects/finbayes/engineering/architecture.md:167-179）；凭证边界一致（product :439-458 vs architecture :144-157）；交易相关输出契约一致（product :214-220 vs architecture :562-573）。

主要不一致是前面提到的 Session 删除级联语义，以及 product-definition 中仍多处使用“默认任务组合”“默认必含认知要素”（projects/finbayes/engineering/product-definition.md:161、:286）。这不是“默认 vs 行动准备双模式”的禁入结构，但建议换成“常规任务组合 / 通常必含认知要素”，减少误伤。

修订意见​

  1. 白皮书 :109 改“交易前检查与复盘历史判断”，删除“行动前”。
  2. 白皮书保留“交易行动”作为执行域可以，但避免“准备 + 行动”连用。
  3. 产品定义把“默认任务组合 / 默认必含认知要素”改为“常规 / 基线”。
  4. 产品定义 :127 调整为不级联删除长期资产，或明确这是可选二次确认动作。
  5. ADR-004/008/010 未 accepted 前，主架构相关段落统一标“当前倾向”。

维度 5：M0 工程包齐全度​

工程包评分（10 分制）​

7/10。§25 对 M0 范围、链路、章节覆盖、验收口径描述清楚（projects/finbayes/engineering/architecture.md:5033-5098），足够让 Codex 知道目标是 CLI + Crypto + 即时认知请求 + Fin Object + 审计 + 边界 hook。但它还不是自包含 task packet，不能直接等同于“1-2 天可执行工程包”。

缺什么​

缺接口子集表：M0 需要列 NormalizedInput、Task、EvidencePacket、StructuredCognitionResult、AuditEvent 的最小字段。缺 Pydantic 模型草案：尤其输出契约必须含反方、失效条件、信息缺口、非指令标注。缺 DDL：fin_objects、sessions、audit_events、schema_metadata 至少需要初版。缺 Mock fixture：Crypto 价格/新闻/链上最小样本、Mock LLM function calling 响应。缺凭证 negative tests：5 类凭证样式输入、Provider key 不落审计、输出端 mock 凭证样式过滤。缺 Provider subset：M0 到底支持一个 OpenAI-compatible mock + 一个真实低成本 Provider，还是只支持 mock，应明确。

独立发现（与 3 个 Claude Code sub-agent 不重叠的）​

  1. 当前白皮书不支持“5 处 exact 旧术语 P0”的说法，需防止 review 线程基于旧文件误判。
  2. 产品定义的“默认任务组合”不是禁入双模式，但容易被 grep 策略误伤，应主动改词。
  3. Session 删除长期资产的语义，产品定义与架构相冲突。
  4. §26 的 schema 禁字段 grep 与主文档合法元引用会冲突，自动审计需要分层：代码 schema 零命中、文档元引用白名单。
  5. M0 把 Credential / Config 简化，但又涉及 Provider 调用审计，必须提前加 secret 原文不落盘测试。

给 ADR-004 至 ADR-010 起草的建议要点​

ADR-004：明确 LLM Function Calling 主导、clarify 工具、事后任务标签，以及低 confidence / 多意图冲突处理。

ADR-005：修正 TaskGroup 失败隔离细节，避免 Python asyncio.TaskGroup 默认“任一失败取消全部”与业务 partial success 目标冲突。

ADR-006：确认本地优先单机下 State Store / Credential Store / Config Store 的职责边界。

ADR-007：补 StateCandidate 字段、过期、编辑 diff、确认事务、拒绝审计。

ADR-008：锁定 Provider Adapter 最小接口、readiness、credential 读取生命周期、M0 Provider subset。

ADR-009：区分关键 Prompt、任务模板、输出 schema prompt、judge prompt 的版本和审计方式。

ADR-010：把输出端凭证过滤定为综合层语义级 + IO 格式级，并定义误报处理和测试白名单。

npm run verify:kb 已跑通：manifest、链接、content hygiene 均通过；但它没有捕捉上述白皮书“行动”语义残留，所以人工 review 仍必要。