跳到主要内容

FinBayes 工程化文档全面排查报告（2026-05-28）

0. 执行摘要​

npm run verify:kb 通过。覆盖 35 份核心文档（5 engineering-packs + 5 子系统 + 4 主目录 + 4 ADR + 1 sync workstream + 4 phase drafts + 3 for-agents 派生 + 2 harness 工件 + 3 战略 cross-ref + 1 入口汇总）。整体健康度：结构层面（cross-reference 网络 / source-of-truth 分工 / snake_case 终态）已成型；但 .archon workflow yaml 1 处 P0 死链 + ADR-008 supplement §1/§3.1 中「5 字段」未同步为最终结论「6 字段」，加 2 处后会出现实施 Agent 立即失败 / schema 校验冲突。P0 修完即可启动 C-1；P1 7 条用词同步 / P2 12 条优化可并行 / 推迟 M0 收尾。

1. 排查范围与方法​

类数量位置
L2/L3 主目录4engineering/{README, product-definition, architecture, architecture-anti-bloat-guard}
engineering-packs5engineering-packs/{m0-walking-skeleton, cognition-1.1-contract, data-providers, eval-harness-formulas, data-splits}
subsystems5subsystems/{README, knowledge-graph-service, consistency-middleware, mca-classifier, eval-harness}
架构 ADR4ADR-008 Provider 接口 / ADR-008 supplement / ADR-009 / ADR-007 supplement
sync workstream1sync-plan-adr007-supplement.md
phase drafts（摘读关键节）4Phase 3 mechanisms-v1 / Phase 4 evaluation / Phase 5 iteration / Phase 7 SLA
for-agents 派生3topics/finbayes-m0-implementation/{agent-pack.yaml, manifest.json, llms.txt}
harness 工件2.archon/{README, workflows/milestone-M0.yaml}
战略 cross-ref3strategic-whitepaper §4/§10 + ecosystem/glossary
入口汇总12026-05-28-pre-engineering-readiness.md

方法：frontmatter + 关键节正文 + 五维度交叉对比（grep + 字段名一致性 + ID 闭环）。

2. 重复发现​

ID内容出现位置source of truth建议动作
DUP-11.1 顶层 6 字段定义ADR-008 sup §2 / cognition-1.1-contract §1-2 / m0-pack §3.5 / 4 子系统 §2 / eval-harness-formulas §8 / product-def §7.3ADR-008 sup（语义）+ cognition-1.1-contract（schema）4 子系统接口段去掉子模型字段列，保留接口签名 + 「事实源指针」
DUP-28 机制 M1-M8ADR-007 sup §2.1 + product-def §6.4 + Phase 3 mechs + strategic-WP §4 + arch §29ADR-007 sup §2.1现状 OK，5 处皆是引用 + 单句概括
DUP-3MCA 7 分轴三档枚举ADR-007 sup §2.2 / cognition-1.1-contract §2.7 + §5 / ADR-008 sup §2.7 / mca-classifier §1 / Phase 3 MCAADR-007 sup §2.2mca-classifier §1 重述三档语义，改为 1 行指针 + 接入要点表
DUP-4S1 4 失败模式 a/b/c/dADR-007 sup §2.3 / ADR-008 sup §2.6 / consistency-middleware §1 / Phase 3 S1 / cognition-1.1-contract §2.6ADR-007 sup §2.3 + ADR-008 sup §2.6consistency-middleware §1 改为「枚举 + 一行业务标签」+ 指针
DUP-511 维评测公式 D1-D11Phase 4 / ADR-007 sup §2.4 / eval-harness-formulas §1 / eval-harness §1 / mca-classifier §1eval-harness-formulas（工程公式）+ Phase 4eval-harness §1 D1-D11 文本展开与 ADR-007 §2.4 重复，改为 1 行表头 + 指针
DUP-6M0 1.1 最小子集字段m0-pack §3.5 / ADR-008 sup §5.2 / cognition-1.1-contract §0 + §7 / arch §29 末段m0-pack §3.5arch §29 末段重述了 M0 子集字段，违反 anti-bloat-guard 索引粒度；改为「详见 m0-pack §3.5」
DUP-7IAA kappa 三阶门槛 0.65/0.70/0.75Phase 4 / Phase 7 SLA §三 / eval-harness-formulas §5 / eval-harness §1+§5 / consistency-middleware §5 / mca-classifier §5Phase 7 SLA §三表保留 Phase 7 SLA + eval-harness-formulas 明文表；其它处仅指针

3. 冗余发现​

ID内容当前位置建议动作
RED-1m0-pack §3 1.0 schema 主体（已被 §3.5 升级到 1.1）m0-pack §3 §3 末加 1 行 status：「M0 双 schema 并存，M1+ 合并到契约源 §5 后本节降为 superseded」
RED-2Phase 3 mechanisms / MCA / S1 draftsdrafts/frontmatter 加 source-of-truth-for: adr-007-supplement 明示仍是 active 事实源（不是过时 draft）
RED-3Phase 4 / Phase 5 / Phase 7 draftsdrafts/同 RED-2
RED-4Phase 5 iteration-governance §3.3 + 多处写「MCA 6 轴」drafts/2026-05-28-phase5-...md L60+L101+L150ADR-007 sup R-A P0-2 已加轴 7；draft 文本应「6 → 7」
RED-5Phase 4 evaluation-system §3 写「M3.t1-M3.t7 七类时钟」drafts/2026-05-28-phase4-...md L75+L81ADR-007 sup §2.1 已立 9 类（+M3.t8 Koo / M3.t9 Minsky）；draft 「7 → 9」或加 superseded 标签
RED-6arch §29 末段「v1 实现路径建议」列 M0 子集字段细节arch §29 末段anti-bloat-guard 80 行约束允许索引段；细节列字段超粒度。改为「M0 子集详见 m0-pack §3.5」+ 4 个里程碑路径标签

4. 不完整发现​

ID缺失项应补到优先级
INC-14 子系统「实现里程碑映射」段各子系统加 §9「子机制 → M0/M1/M2/M3 落地」表P1 — ✅ 已修 (2026-05-28)，4 子系统（knowledge-graph-service / consistency-middleware / mca-classifier / eval-harness）各加 §9 M0/M1/M2/M3 落地范围 + 不落地清单表
INC-2cognition-1.1-contract §5 mca_bucket.worst_axis 类型 + tag_version pattern 约束cognition-1.1-contract §1 + §4P2
INC-3data-providers / eval-harness-formulas / data-splits 三 pack 互相 cross-reference 不完整三 pack 头部加双向指针P2
INC-4m0-pack §15 关联资产未引用 data-splits（M0 case 库分集前提）+ architecture-anti-bloat-guardm0-pack §15 补两条指针P2
INC-5cognition-1.1-contract §8 worst_axis pending 未引 mca-classifier §7 v1 排序§8 加 1 行「v1 起步排序见 mca-classifier §7」P2
INC-6M0 yaml ai-cognition-schema.related_pack 缺 cognition-1.1-contractyaml 加为第二项 related_packP1 — ✅ 已修 (2026-05-28)，related_pack 改为列表含 m0-walking-skeleton + cognition-1.1-contract 两项
INC-7topic agent-pack.yaml sources 缺 architecture-anti-bloat-guard + Phase 4/5 draftssources 加 3 项P1 — ✅ 已修 (2026-05-28)，sources 补 architecture-anti-bloat-guard + phase4-evaluation-system + phase5-iteration-governance 3 项，notes 同步更新
INC-84 子系统无「§0 范围与定位」段（engineering-packs 5 份都有）4 子系统补 §0「事实源 / 派生关系 / status 语义」P2
INC-9ADR-008 sup / ADR-007 sup §6 缺反向指针到 cognition-1.1-contract两 ADR §6 各加「工程契约派生源: engineering-packs/cognition-1.1-contract.md」P2
INC-10M0 yaml ai-eval-harness-m0.related_pack 缺 eval-harness-formulas（公式事实源）yaml 加为 related_packP1 — ✅ 已修 (2026-05-28)，ai-eval-harness-m0 inputs 新增 related_pack 列表含 eval-harness-formulas

5. 冲突发现​

ID不同说法正确版本修复动作
CONF-1（P0）.archon/workflows/milestone-M0.yaml:94 ai-semi-manual-sla 节点 anchor_doc: projects/finbayes/engineering/phase7-semi-manual-annotation-sla.md 该文件不存在实际在 governance/workstreams/finbayes-cognition-system-research/drafts/2026-05-28-phase7-semi-manual-annotation-sla.md修 yaml anchor_doc 路径 — ✅ 已修 (2026-05-28)，milestone-M0.yaml L94 anchor_doc 指向 drafts 路径
CONF-2（P0）ADR-008 sup §1 引用段 + §3.1 第 1+2 项写「5 新字段」；§4.1 末段 audit trail 显式纠正为「6 字段 + 1 元数据」；product-def L163 + L186 也写「5 字段」；cognition-1.1-contract / m0-pack / 4 子系统全部以 6 字段为准；eval-harness §6 已有注释指出此漂移6 字段（applicability_flags + phase_evidence + causal_graph + regulation_status + posterior + s1）修 ADR-008 sup §1 / §3.1 + product-def 「5 → 6」（保留 §4.1 audit trail 段说明）— ✅ 已修 (2026-05-28)，ADR-008 sup §1 + §3.1 + product-def L163 + m0-pack L609 + eval-harness §6 L140 全部统一为「6 顶层字段 + 1 元数据」并显式列字段名
CONF-3（P1）「7 MCA 桶」vs「8 MCA 桶」措辞漂移ADR-007 sup §2.4 / eval-harness §1 / mca-classifier §1 / Phase 4 §五 写「7 桶」；eval-harness-formulas §3 写「7 MCA 桶（B5 拆实际 8 桶）」；入口汇总 L78 写「8 MCA 桶」7 桶概念层 / 8 label 实施层并存
CONF-4（P1）Phase 4 §3 写「M3.t1-M3.t7 七类时钟」ADR-007 sup §2.1 9 类（M3.t1-M3.t9）Phase 4 draft 文本「7 → 9」或加 superseded 标签 — ✅ 已修 (2026-05-28)，phase4 L75 / L85 改为「M3.t1–M3.t9 9 类时钟」并附 R1 修订指向 ADR-007 sup §2.1
CONF-5（P1）Phase 5 §3.3 + 多处「MCA 6 轴」ADR-007 sup §2.2 7 轴Phase 5 draft「6 → 7」 — ✅ 已修 (2026-05-28)，phase5 L60 / L101 + phase4 L205 active 治理表述改为「7 轴」并附 R1 修订指向；L296 / L305 / L307 / L331 桶位表设计耦合，保留 R1 前 6 轴 + L/D/F/N/C/I 列名（重表设计超 P1 范围）
CONF-6（P2）M0 yaml ai-semi-manual-sla.description 写「IAA kappa ≥ 0.7」Phase 7 SLA §三表是任务级分级 0.65-0.75yaml description 改「IAA kappa 0.65-0.75 任务级分级（见 Phase 7 SLA §三）」
CONF-7（P1）M0 yaml ai-cognition-schema 输出 cognition/types.py vs cognition-1.1-contract §5 Pydantic 草案文件名 src/finbayes/cognition/contract_v1_1.py vs m0-pack §3.5 用 contract_v1_1_m0.py工程落盘约定 src/finbayes/cognition/types.py（与 m0-pack §3 主体一致）cognition-1.1-contract §5 注释文件名改为 src/finbayes/cognition/types.py — ✅ 已修 (2026-05-28)，L146 文件名注释改为 src/finbayes/cognition/types.py
CONF-8（无需修）worst_axis 多桶裁决：mca-classifier §3+§7 vs cognition-1.1-contract §8「本契约不锁定」mca-classifier §7（v1 working）已诚实标 working，无需修
CONF-9（无需修）data-splits §6 18 case 桶位映射「v1 起步建议」已标 v1 起步，Phase 5 治理首季评估无需修
CONF-10（P2）regulation_status ADR-008 sup §2.3「轴 3 = F2/F3 必选」vs m0-pack §3.5 整体 stubM0 全 Mock fixture 控制 axis_3 = F1 → stub 合规m0-pack §3.5 加 1 行注释「M0 Mock 默认 axis_3 = F1 故 stub」

6. 链接 / cross-reference 健康度​

ID问题修复动作
LINK-1（P0）.archon yaml:94 死链见 CONF-1
LINK-24 子系统 §8 跨子系统 + 与 EvalHarness 联动段已有✓
LINK-3三 engineering-pack 互引不完整见 INC-3
LINK-4（P2）architecture-anti-bloat-guard 未被 m0-pack / arch §29 / 4 子系统反向引用m0-pack §15 + arch §29 末段补指针（防实施 Agent 跳过守门）
LINK-5Phase 3 drafts 未声明 source-of-truth-for见 RED-2
LINK-6ADR-008 sup → ADR-008 主体路径✓
LINK-7（P2）sync-plan-adr007-supplement.md 未反向指向 4 子系统作为已执行 P0 任务清单sync-plan 补 cross-reference
LINK-8eval-harness-formulas §9 关联资产链接闭环✓
LINK-9for-agents/manifest.json + machine-context.json 引用 Phase 7 SLA 路径✓（verify:kb 通过）

7. 修复优先级总表​

P0（阻塞 C-1 启动 / 2 条）

  1. CONF-1：修 .archon/workflows/milestone-M0.yaml:94 anchor_doc 死链 → 改指向 governance/workstreams/finbayes-cognition-system-research/drafts/2026-05-28-phase7-semi-manual-annotation-sla.md
  2. CONF-2：ADR-008 sup §1 + §3.1「5 新字段」→「6 新字段」+ product-def L163+L186 同步

P1（强烈建议修，不阻塞 / 7 条）

  • CONF-3 / CONF-4 / CONF-5 / CONF-7：「7 桶」「7 时钟」「6 轴」措辞统一 + cognition-1.1-contract §5 文件名同步
  • INC-1：4 子系统补「实现里程碑映射」段
  • INC-6 / INC-10：M0 yaml 两节点补 related_pack
  • INC-7：topic agent-pack.yaml sources 补 3 项

P2（优化 / 12 条）

  • DUP-1/3/4/5：4 子系统接口段去字段细节重列
  • RED-1/2/3：drafts frontmatter 加标签 + m0-pack §3 加 status 注释
  • RED-6：arch §29 末段改为指针
  • INC-2/3/4/5/8/9：互补 cross-reference
  • CONF-6/10：yaml description + m0-pack §3.5 注释微调
  • LINK-4/7：anti-bloat-guard + sync-plan 反向指针

8. 决策建议​

可以启动 C-1（EvalHarness M0 schema 实施），但 P0 两条必须先关掉：

  1. CONF-1：实施 Agent 一旦尝试加载 ai-semi-manual-sla.inputs.anchor_doc 立即 404，会卡 ai-semi-manual-sla 节点不能开工
  2. CONF-2：实施 Agent 读 ADR-008 sup §1 / §3.1 看到「5 新字段」会与 cognition-1.1-contract / m0-pack §3.5 / product-def §7.3 表「6 字段」不一致，造成 Pydantic schema 字段数校验不通过 / 实施者疑惑

P0 预计 30 分钟工程量（2 文件 3 处 edit），直接落手，不起新 ADR；修完跑 npm run verify:kb 即可启动 C-1。P1 7 条建议 C-1 期间并行修；P2 12 条推迟 M0 收尾盘点（参见 anti-bloat-guard §4）。

9. 排查方法论自检 / 不足​

  • Phase 7 SLA §四 sla-breached fallback 路径未深读 — ai-semi-manual-sla 节点遇边界问题可能需要回 Phase 7 SLA §四追读
  • Phase 6 R-A / R-B / R-C reviews 资产 11 份未逐一比对（通过 ADR-007 sup / Phase 4-5 / 4 子系统的 R 收口标签交叉验证，未发现新冲突，但未做穷尽 review）
  • legacy projects/finclaw/ 未排查（与 FinBayes 工程化范围不相关）
  • 18 case Phase 2 个案报告未逐一与 data-splits §6 表交叉验证（通过 Phase 3 case-calibration-summary + data-splits §3 间接验证）
  • ADR-008 主体（1.0）vs ADR-008 sup（1.1）差异表 §3「10 要素契约全部保留」未逐字段验证（通过 cognition-1.1-contract / m0-pack §3 主体字段清单间接验证）
  • .archon runtime state 不在排查范围（runtime / state 不进本仓约定）