跳到主要内容

Round-2 Review B — 工程化落地 Agent 100% 质量评估

视角：Codex/Claude Code 拿着 M0 task packet 入场，1-2 天内要让骨架代码"接近 100% 符合文档"。已读完 §4 / §9 / §11 / §13 / §15 / §17 / §18 / §20 / §25 / §26 / §27 / §28、ADR-001/003 全文，以及 §22 缺口章。§9 仅深读了 IO + Task Orchestration + Evidence/Synthesis（State / Capability / Provider Adapter 三子系统的"组件图 + 接口表"细节未逐字读完，本评估对这三块走"§28 接口表 + §27 映射"推断，明示存疑）。

维度 1：M0 实施可动工评估​

第 1-4 小时（项目骨架 + Pydantic + 接口）​

可执行度：约 90%。

  • §27 给出完整 src/finbayes/{io,orchestration,cognition,state,capabilities,providers}/ 目录树 + 1:1 测试镜像；§28 §2 已经给出 5 个 types.py 的完整 Pydantic 代码（NormalizedInput / BoundaryResult / Task / ToolCall / LLMCall / EvidencePacket / StructuredCognitionResult / Session / AuditEvent / ProviderReadiness / LLMResponse），Codex 可以直接 copy-paste。
  • §28 §1 接口子集表给出 18 implement + 11 stub = 29 个签名固定的接口，函数名 / 入参 / 出参类型基本确定。
  • ADR-003 明示 Python，§12 锁定 Python 3.11+ asyncio.TaskGroup / httpx / asyncio context vars。§8 提及 click / typer。

会卡壳的地方：

  1. 包管理器未定 —— pip / poetry / uv / hatch 哪个？没有 pyproject.toml 模板。Codex 必须自己挑（很可能默认 uv，但不是文档要求）。
  2. 入口框架 —— §8 写"click / typer 等"，二选一未定。CLI signature 在 §28 §4 是 shell 字符串而非 click 装饰器，Codex 必须自译。
  3. Pydantic schema 字段不全 —— §28 §2 是"M0 最小字段集"，但 LLMCall 的 provider_id / model 用什么字符串规范？Session.user_id 在单用户模式下塞什么常量？文档没说，Codex 要猜（很可能塞 "local"）。
  4. ClarifyResponse 类型未在 §28 §2 出现，但 §9 接口表里 orchestrate 出参含它 —— 维度 3 链路 1 会卡。

第 5-8 小时（migration + audit + mock LLM + 边界 hook）​

可执行度：约 75%。

  • §28 §3 给出完整 001_initial.sql（4 张表 + PRAGMA + 索引），可直接放进 migrations/。
  • §28 §7 给出 5 条凭证 negative fixture YAML，但正则 / BIP-39 词表 / Luhn 实现没给 —— §17 列了"凭证类型与识别策略"，但具体正则在工程实施仓维护。Codex 必须自己写 5 套 pattern，且无 ground truth。P0 隐患：自写正则的精度与文档"100% 拒收"目标之间没有自动桥接。
  • §28 §5 的 Mock Provider fixture 规范给出目录结构 + hash 字段白名单 + 单条 fixture JSON 格式，但 compute_request_hash 函数体留 ...（空实现），且 _index.json 的 schema 未定义。
  • audit_events.payload 是 JSON TEXT，但每种 event_type 对应的 payload 字段集没有 schema —— §28 §2 说 "具体由各 event_type 文档"，但文档里没找到这一表。Codex 写 boundary_rejected 时塞什么字段全凭想象。P0。
  • 边界 hook：§17 给"识别策略"是表格描述，但 hook 的返回结构 + reject_reason 取值 + 安全回应文案只在 §17 §"凭证拒收的用户感知" 给了一段示意 —— 还可以接受。

第 9-16 小时（5 样例 + 5 凭证 + CI gate）​

可执行度：约 70%。

  • §28 §6 / §7 / §10 CI 模板齐备，pytest 收敛点 tests/m0/ 明确。

  • 但 §28 §10 CI 模板里调了 3 个不存在的脚本：

    • 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

    这 7 个文件 / 脚本的具体内容文档没给。Codex 必须自己实现，且这些是 review gate 的"机械断言执行器" —— 自己实现的 gate 自己跑，等于守门员就是球员，gate 失效风险 P0。

  • "M0 baseline" 怎么生成、存哪、用什么格式？§26 说"M0 是基线 → 无前置对比"，那 audit_contract_regression.py 在 M0 上跑什么？没说。

  • §28 §6 expected_capabilities 是自然语言描述（"main_answer 含 ETH 与 时间窗口"），无对应可执行断言；Codex 必须把"含 ETH"翻译成 substring match 或正则，不一致风险高。

  • §28 §8 输出判定规则讲清楚"M0 不依赖 LLM-as-judge，用 Pydantic min_length + 人工 5 条 checklist"，但 checklist 是 markdown 模板，不进 CI。"100% 文档符合"在认知质量维度上结构性地依赖人工。

整体 M0 1-2 天能写到 80%？90%？100%？​

80% — 不到 90%。

范围完成度
项目骨架 + Pydantic + DDL + CLI 命令名~95%
6 子系统 implement 接口骨架~85%
Mock Provider + fixture 录制重放管线~70%
边界 hook（凭证拒收）正则实现~60%（正则是自写的）
审计 trail 写入 + 端到端贯通~80%
CI gate 三个 job 跑通~50%（依赖 7 个未提供的脚本/测试文件）

整体约 80% 文档符合。要把它推到 95%+ 必须补 P0 清单。

维度 2：100% 文档符合度的质量保证评估​

三检 review gate + 四类断言 拦截能力评分（满分 10）：6 / 10​

检查评分理由
战略保真度·机械（grep 禁词 / 凭证字段 / TLS）8禁词清单具体，可直接 grep；但 §28 §10 grep private_key/mnemonic/api_secret 仅在 src/**/*.py 范围，SQLite payload TEXT 内容、Prompt yaml、日志文件不在扫描面
战略保真度·结构（Pydantic schema 必填 + 工具 category 枚举）8StructuredCognitionResult 强约束清晰，但"工具 category 枚举无 execution"靠 §17 文本约束，没看到 ToolSpec 的 Pydantic 定义在 §28 中给出
契约回归4M0 是 baseline 自身，本里程碑无前置对比；audit_contract_regression.py 在 M0 是 no-op，整个 gate-2 在 M0 上空转，等 M1 才真正生效 —— 这意味着 M0 阶段加进的 schema 错误会被"冻"为 baseline
认知质量·样本（5 sample + 5 credential）6通过 / 不通过的具体断言文档只给"能力清单"自然语言，未给 pytest 断言代码
认知质量·语义（5 条人工 checklist）5完全人工 + 不进 CI + 不阻断 merge；只在"M0 验收"环节走一次

可能漏过去的偏离类型（举例）​

  1. 执行类工具偷偷注册：开发者新建 tools/place_order.py 但 category="analysis"（撒谎标签），grep 不命中"execution"字符串。audit_capability_registry.py --strict 没给实现，无法判断是否真的按工具实际行为校验。会漏。
  2. Output schema 字段悄悄改语义：invalidation_conditions 类型从 list[str] 改成 list[str] | None，contract_version 不升 —— M0 没 baseline 可比，gate-2 空转放行。会漏。
  3. 审计 payload 字段缺失：boundary_rejected 事件没写 reject_category。文档没规定 payload schema，无断言可挂。会漏。
  4. 凭证字符串入 SQLite payload：grep 只扫 .py，不扫运行时数据库。tests/m0/test_credential_isolation.py 是文档要求但内容未给 —— 实施者自己写时容易遗漏数据库扫描分支。会漏。
  5. Mock fixture 与真 Provider drift：provider_api_version 字段在 fixture 中，但比对脚本未提供，CI 强制重录的触发条件文档说"diff > 阈值" —— 阈值是多少？diff 算法是什么？会漏。
  6. 同义改写绕禁词：§26 列了"行动判断 → 行动倾向"，但禁词列表是固定 7 个词（§28 §10）。新同义词依赖人工 review —— 结构性会漏。
  7. 第一屏题眼命中 / 反方实质性：§28 §6 expected_capabilities 是 yaml 描述，没有断言代码，且 §28 §8 明确"靠人工 checklist" —— 结构性依赖人工。

估算拦截率：

  • 静态字段名 / Pydantic schema / DDL 偏离：~80% 拦截
  • 工具注册 / category 谎报：~30%（脚本未给）
  • 语义级"反方质量 / 题眼命中 / 信息缺口诚实"：~10%（人工 + checklist 不进 CI）
  • 跨章节一致性（如 §11 状态机转移 vs 实际代码）：~20%

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

自动化程度不够的 gate + 人工 prompt/checklist 是否在文档里​

Gate自动化人工 prompt/checklist 在文档？
战略保真度·语义（§26）"同义改写未绕过禁词 / 契约语义未弱化 / 战略不变量未削弱"0%没有 prompt 模板；只说"Claude Code Review + 工作流维护者裁决"
认知质量人工 5 条 checklist0%有 checklist 模板（§28 §8），但缺：评分人是谁？分歧仲裁？跨样例聚合阈值？
跨 Agent 模拟视角（ADR-001 / §25）0%完全无 prompt —— ADR-001 留作 OQ-002
Code Review PR 描述追溯 §N（§27）0%无 PR 模板给"如何引用 CHAP / ADR"的格式

关键缺口：M0 时 reviewer（Claude Code）的 review prompt 不存在。reviewer 自由心证 = 不可重复 = 100% 难保证。

维度 3：6 条 M0 关键链路完整度​

链路完整度缺口
1. CLI 输入 → 边界 → Task → LLM → 输出基本完整ClarifyResponse 类型未给；CLI streaming 协议（如何把 format_output_stream 的 AsyncIterator[Chunk] 拼成 §28 §4 的人类可读格式）只给示例输出，没给 Chunk 类型
2. 凭证拒收有缺口5 类凭证正则代码未给；BIP-39 词表未指定 source；LLM 辅助二次判断（§17）是否在 M0 实现？文档矛盾（§28 §1 没列，§17 说"对不确定 case 调小模型"）；输出端 hook 与输入端共享同一套 pattern —— src/finbayes/io/output_filter.py 在 §28 §1 表里完全没出现
3. 审计 trail 写入有缺口10 种 event_type 各自的 payload 字段集没有 schema 表；异步写入策略（§15 "审计 trail 写入异步化"）的实现细节缺失；trace ID 体系（§18）的生成函数未指定（uuid4？snowflake？）
4. Provider 调用 + 4 层降级严重缺口§28 §1 明确 M0 仅 call_llm implement，4 层 fallback 全部 stub。但 §25 M0 验收"⚠️ 仅 L1 → L2 降级"与 §28 §1 表"fallback_to_l2 是 stub"直接矛盾。L1 → L1' 切换路径在 M0 是否要走？文档自相矛盾
5. 状态对象基本完整Session 创建 + 默认 Session 兜底有 get_or_create_default_session（§28 §1）；但 default_session.user_id 在单用户模式下取值规则未指定；is_default flag 的迁移路径（已有 default 但 user 改名后）未定
6. 审计 + 测试 + 评估有缺口M0 不上评估（§28 §8 LLM-as-judge 在 M6），所以"评估闭环"在 M0 暂不闭合；CI gate 模板中 7 个 hook 脚本/测试文件内容未给（详见维度 1 第 9-16 小时）

维度 4：工程化落地需要的额外材料清单​

文档未明示但需要决定的项：

  1. 包管理器：uv / poetry / hatch 选哪个 — 缺
  2. pyproject.toml 模板（依赖列表 + Python 版本约束）— 缺
  3. CLI 框架：click vs typer — 二选一未决
  4. lint / format / type-check 工具链：ruff / black / mypy / pyright — 完全没说
  5. httpx 客户端配置（timeout / retry / connection pool）— 缺
  6. 凭证正则源码 + BIP-39 词表 fixture — 缺（M0 的 P0）
  7. LLM Provider key 加载顺序：env var → keyring → config.yaml 的优先级链 — 文档说 Keychain 优先 + env 降级（§13），但未给加载顺序伪代码
  8. 错误处理规范：自定义 Exception 类层级 / 错误码到 Exception 的映射 — 缺（§28 §4 列了 6 个退出码，但没列对应 Exception class）
  9. logging 配置：日志格式 / 输出 sink / 旋转策略 — §18 提了日志分级但无配置模板
  10. 测试夹具规范：pytest fixture 命名 / conftest.py 结构 — 缺
  11. 异步上下文最佳实践：asyncio.to_thread 调 sqlite 还是直接 aiosqlite —— §15 提 aiosqlite，但 audit 异步写入的具体模式未给
  12. trace_id / task_id 生成：uuid4 / ULID / Snowflake — 未指定（影响审计可读性）
  13. Pydantic 配置：model_config = ConfigDict(...) 全局策略（extra='forbid' / strict）— 缺
  14. migration runner：§27 列了 migrations/runner.py 但 §28 没给实现 — 缺
  15. Mock 录制开关：RECORD=true env var 的语义（§20）— 大致清楚但无具体代码

P0 阻断（不补无法 100% 落地）​

  1. 5 类凭证正则的参考实现 / 测试基线（§17 + §28 §7）
  2. audit_events.payload 按 event_type 的字段 schema 表（§28 §2 / §18）
  3. CI 模板中 7 个未提供的脚本 / 测试文件：audit_capability_registry.py / audit_contract_regression.py / test_structured_cognition_result_schema.py / test_credential_isolation.py / test_synthesis_output_schema.py / tests/contract/* / tests/m0/sample_inputs.yaml 对应的 pytest runner
  4. M0 baseline 的契约文件位置 + 格式（§28 §10 --baseline=m0-baseline）
  5. M0 降级范围的二义性：§25 说"L1 → L2"，§28 §1 说 L2 是 stub。必须明确"L1 → L1' 在 M0 是否 implement"
  6. ClarifyResponse / Chunk 等出现在接口签名但未在 §28 §2 给出的 Pydantic 模型
  7. 包管理器 + pyproject.toml 模板（决定 Codex 第 1 小时能否跑起来）

P1 重要（落地质量打 7-8 折）​

  1. CLI 框架选定（click / typer）+ stream chunk 格式
  2. CI reviewer prompt 模板（Claude Code 做 PR review 时用什么 checklist）
  3. 错误处理规范（自定义 Exception 类层级 + 错误码映射）
  4. 5 条样例的 expected_capabilities 翻译成 pytest 可执行断言
  5. Mock fixture 的 compute_request_hash 实现 + _index.json schema
  6. logging / lint / type-check 工具链选定
  7. trace_id 生成规范（uuid4 / ULID）
  8. audit_events.payload 异步写入的实现模式

P2 改进（落地质量打 9 折但更稳）​

  1. pyproject.toml ruff / mypy 配置模板
  2. conftest.py 共享 fixture 约定（tmpdir SQLite / mock provider / time freeze）
  3. Pydantic ConfigDict 全局策略（extra='forbid' 等）
  4. migration runner 参考实现
  5. README + CONTRIBUTING 在工程实施仓的最小模板（哪段反向追溯文档？）
  6. "M0 完成"的可执行验收脚本（一个 make m0-ready 或类似）

一句话总结​

以本套文档落地 M0，Codex 可达到约 80% 文档符合度，缺口主要在"凭证正则代码 / audit payload schema / CI gate 实际可执行的脚本与断言 / M0 降级范围二义性"四处；要拉到 95%+ 必须补齐上述 7 项 P0 材料，且 reviewer 人工 review 流程必须出 prompt / checklist（目前完全靠 reviewer 心证 —— 100% 文档符合在"语义层"是不可达的，因为评估闭环 M0 不上线）。