跳到主要内容

Codex Round-2 Review — 跨层可读性 + 落地 100% 评估

说明：我没有改任何文件。架构文档 6483 行我完成了章节索引全量扫描，并深读/抽读了本轮指定交叉点：§2、§4、§7、§11、§14、§15、§16、§17、§22、§23、§25、§26、§27、§28，以及产品定义 §3/§4/§9/§10/§11、白皮书 §7/§8/§14/§15、ADR-001/002/003、Round-1 reviews。未逐字完整展开 6483 行每一行，因此下面结论按“重点维度 review”负责，不声称逐字法务式校对。

A. 跨层可读性​

A.1 4 小时 mental model 评估​

结论：工程新人按“白皮书 → 产品定义 → 架构”读，4 小时内可以建立 80%-85% 的完整 mental model。三层主线是清楚的：白皮书定义 FinBayes 是“感知 - 认知 - 执行”里的认知层；产品定义把它落成自然语言入口、金融对象、任务类型、多入口、画像与凭证边界；架构文档再拆成 6 子系统、状态对象、部署、协议、测试、评估、M0 工程包。

最大可读性优点是核心词表已经高度收敛：七类任务、Fin Object / Watchlist / Session / Task / StructuredCognitionResult / JudgmentRecord / DynamicProfile、凭证不变量、画像不裁剪事实空间、多入口共享 runtime，这些跨三层能对上。

主要阅读成本不在概念冲突，而在“入口太多、章节太长、决策状态混杂”。新人会在架构 §23 看到 ADR-004/008/010 仍待写，但正文和 §28 已经给出较强实现倾向。作为 mental model 还可以，作为 coding contract 会让新人不确定“这是已定方案，还是草案倾向”。

A.2 7 项一致性核查（逐项）​

  1. 任务类型清单：一致。白皮书 §7 明确第一阶段七类：解释、分析、比较、复盘、风险识别、交易准备、交易决策辅助；产品定义 §4.2 逐项定义；架构 §2/§4/§9.5 复用同一清单。可读性建议：产品定义 §4.1 的“问题族”多于七类任务，新人可能误以为两套分类竞争，应在 §4.1 开头再强调“问题族是入口识别层，任务类型是执行层”。

  2. 业务对象：基本一致。产品定义 §3 是五类产品对象，架构 §4 扩成七个 first-class 工程概念，§11 说明并非所有 first-class 概念都有独立状态机，§15/§27 分别落到表和模块。这个扩展合理，但“产品五类对象 vs 架构七类概念 vs §11 六个状态机”需要靠读者自己合并。建议新增一张跨层映射表：产品对象 / 架构 first-class / 是否持久化 / 是否有状态机 / M0 是否实现。

  3. 凭证不变量：强一致。白皮书 §14、产品定义 §10.3/§10.4、架构 §17/§28 都区分金融执行凭证和本机 Provider secret，并落实到输入拒收、状态/缓存/审计不落原文、输出过滤、negative fixture。这里已经接近可执行。

  4. 多入口契约：一致但落地优先级需再钉死。产品定义 §9 说 Web/TUI/CLI/MCP/Channel 是 runtime 入口适配；架构 §7/§14/§16 说入口共享 Core Runtime，M0 选 CLI，后续扩 TUI/Web/MCP/Channel。问题是 goal-execution 的 M0 写“CLI/TUI 调用同一 runtime”，而 architecture §25/§28 的 M0 更偏 CLI。这是 round-2 新发现：M0 范围在 architecture 与 goal-execution 之间仍有轻微不同步。

  5. 认知/执行分工：强一致。白皮书 §8、产品定义 §11.1、架构 §2/§17 都明确不直接下单、不持有账户凭证、不替用户决策。Trading Matrix 作为下游执行支持，FinBayes 与其无 runtime 直连，这个边界足够清楚。

  6. 画像主权：强一致。白皮书 §14、产品定义 §10.1/§10.2、架构 §13/§17 都强调用户可查看/修改/清空，画像只改表达密度和任务匹配，不裁剪事实空间。实现风险主要在 M1 以后：DynamicProfile 的字段、候选写入、用户编辑 diff、清空审计还没进入 M0 附录。

  7. 未决问题：部分一致但分类口径不完全重合。白皮书 §15 的未决是更多市场普适性、个人/机构分立、商业模式压力测试；架构 §22 增加了跨设备同步、Channel 优先级、任务类型最终形态、认知质量验收方法等工程/产品未决。不是冲突，但新人会问“白皮书未决是否等于架构未决全集”。建议 §22 明确分为“继承自白皮书”和“工程层新增未决”。

A.3 抽查 3 个实施新人会问的问题​

  1. “七类任务和十类问题族到底谁驱动代码？” 答案能从产品定义 §4.1/§4.2 与架构 §9.5 拼出来：问题族用于入口识别和第一屏结构，任务类型用于 Task/TaskGroup 执行与审计标签。但当前没有一张明确转换表。

  2. “M0 只做 CLI 还是也要 TUI？” architecture §25/§28 更像 CLI-only；goal-execution M0 要 CLI/TUI 都走 runtime facade。这会直接影响 1-2 天工作量。

  3. “ADR-004/008/010 未 accepted 时，Codex 能不能按 §28 开工？” 可以开 M0 骨架，但高风险接口不能视为最终稳定。尤其任务识别、Provider adapter、输出端过滤阈值，最好在 M0 task packet 中声明“按 §28 v0 实现，ADR 结论若变化允许重构”。

B. 工程化落地 100% 符合度​

B.1 M0 1-2 天完成度估算（百分比）​

按当前文档 + §28 工程包，熟悉 Python/pytest/CLI 的 Codex 或工程师可在 1-2 天完成 65%-75% 的 M0 skeleton。能完成：src layout、核心 Pydantic 模型、SQLite 初始表、CLI ask/status/init/session/audit、凭证 negative tests、mock LLM fixture、StructuredCognitionResult schema、审计事件写入、M0 CI 草案。

会卡住的部分：真实 Provider adapter 的最小选择、Provider secret 的读取生命周期、真实数据工具选型、Function Calling 的具体协议、TUI 是否进 M0、L1→L2 降级是否必须真跑本地 LLM。若 M0 严格只要求 mock + 一个 OpenAI-compatible L1，完成度可到 80%；若要求 CLI+TUI+真实 Provider+降级，1-2 天会掉到 50%-60%。

B.2 review gate 拦截能力评分（满分 10）​

评分：7.5/10。

强项：三检（战略保真度、契约回归、认知质量）加四类断言（机械、结构、样本、语义）是正确框架；§28 的 CI 模板能拦住禁词、凭证字段、执行类工具、schema 缺字段、M0 样例失败、凭证落盘。

拦截估算：对机械偏离可拦 80%-90%，例如禁词、缺 schema、凭证 fixture、执行类工具注册；对结构偏离可拦 65%-75%，取决于 schema diff 和 contract tests 是否真实实现；对语义偏离只能拦 40%-55%，例如“反方证据形式存在但没有实质反方”“第一屏没打中题眼”“画像暗中裁剪事实空间”。M0 阶段没有 LLM-as-judge，人工 checklist 是必要补位。

B.3 6 条 M0 链路完整度​

  1. CLI 输入：完整度 8/10。命令、流式输出、JSON 输出、退出码都有。缺少 argparse/typer 选型和配置路径细节，但不阻塞。

  2. 凭证拒收：完整度 8.5/10。白皮书、产品定义、架构、§28 negative fixture 对齐很好。缺口是 Provider secret 不落日志/审计/fixture 的专门测试还应加入 M0。

  3. 审计：完整度 7/10。AuditEvent 模型、audit_events DDL、task/provider/boundary 事件都有。缺口是“边界事件必须同步写，常规事件可异步”的优先级没有在 §28 明确，否则凭证拒收审计可能被异步丢失语义稀释。

  4. Provider + 降级：完整度 5.5/10。概念层完整，但 M0 子集仍不够硬。§28 写 L1 implement、fallback stubs，§25 写仅 L1→L2，白皮书/产品定义说四层降级。建议 M0 明确：真实实现只需 readiness + L1 mock/openai-compatible + 失败状态可观测；L2-L4 全部 stub 并有 contract tests。

  5. 状态对象：完整度 6.5/10。Session、FinObject、AuditEvent 在 M0 有模型/DDL；但 M0 选择“Fin Object”作为状态对象，而状态闭环更多靠 Session + Audit，FinObject 的 created/archived 生命周期没有在 M0 验收中体现。建议 M0 验收加一条：输入中识别 ETH/BTC 后能写/读 fin_objects 或至少审计中引用 canonical object。

  6. 测试评估：完整度 7/10。M0 样例、negative fixture、schema checks、人工 checklist 已经够启动。缺口是数据 Provider fixture 与真实金融源 freshness 的最小规范不足，M0 输出“sources 含价格 + 至少一类外部源”可能变成手写假源。

B.4 额外材料清单​

仍建议补这些，不一定全进主架构：

  • M0 task packet 实例：明确工程仓 cwd、M0 是否含 TUI、是否允许真实 Provider、必跑命令。
  • Provider adapter v0 选择：OpenAI-compatible 客户端、自实现还是 LiteLLM；真实调用与 mock 调用边界。
  • 错误码字典文件：§16/§28 有退出码，但缺 Python 常量位置和错误 payload schema。
  • Secret-handling 测试模板：Provider key 原文不得进入日志、审计、fixture、stdout/stderr。
  • 数据工具最小集：Crypto price/news/on-chain M0 到底选哪些 mock source。
  • 人工 checklist 模板归档位置：谁签、签在哪、如何进入 review gate 证据。
  • ADR-004/008/010 最小 accepted 版，至少覆盖 M0 不可逆接口。

C. 与 Round-1 review 不重叠的新发现​

  1. architecture M0 与 goal-execution M0 范围不完全一致：前者 CLI-first，后者 CLI/TUI 都要 smoke。这个会影响 1-2 天估算和 task packet。

  2. §22 未决问题比白皮书 §15 多，且没有显式标注哪些是战略继承、哪些是工程新增。读者可能误以为战略未决被工程层重写。

  3. §28 M0 DDL 说“M1+ 加 5 张表，达成 §15 完整 8 张业务表（+ schema_metadata）”。这里数法容易混淆：M0 4 张含 schema_metadata，M1+ 再加 5 张后总物理表 9 张；§15 的 8 张是业务/状态表口径。建议统一“业务表 8 + 元表 1”。

  4. 产品定义 §12 仍有“用户接近交易行动时主动提供仓位、风险预算或时间窗口”的表述。不是 Round-1 指定旧术语 exact phrase，但“主动提供仓位”容易被理解成交易建议深一步，应改成“提示用户自行声明仓位/风险预算/时间窗口用于条件化检查”。

D. 综合行动建议​

  1. P0/P1：统一 M0 范围。明确“architecture §28 为准：M0 是否 CLI-only；TUI 是 M0 smoke 还是 M3/M1 后续”。这是最直接影响落地 Agent 的点。

  2. P1：补一张跨层对象映射表。覆盖产品五对象、架构七概念、六状态机、八业务表、M0/M1 实现阶段。

  3. P1：把 §22 未决问题分层：白皮书继承项 / 产品新增项 / 工程新增项 / ADR 待定项。

  4. P1：为 ADR-004/008/010 起草最小 accepted 版，至少锁住 M0 的任务识别、Provider adapter、输出过滤接口。

  5. P1：把 §28 的 M0 task packet 样例实体化，含工程仓 cwd 占位、验收命令、人工 checklist 归档方式、Provider mock/real 边界。

  6. P2：统一表数量口径为“8 张业务表 + 1 张 schema_metadata 元表”。

  7. P2：产品定义中弱化“主动提供仓位”等容易越过认知/执行边界的表达。

一句话总结​

这套文档已经能让工程团队“看懂大方向”并让 Codex 开始 M0 骨架，但距离“落地接近 100% 不跑偏”还差最后一层实施锁定：M0 范围、跨层对象表、ADR-004/008/010 最小决策、Provider/secret/testing 的 task packet 级细化。

hook: Stop hook: Stop Completed