跳到主要内容

FinBayes 工程化文档

本目录是什么​

本目录承载 FinBayes 在 战略白皮书 基础上的工程化落地文档集。目的是让实施 Agent / 人类工程师知道 FinBayes 是什么、当前版本交付什么、每层怎么实现、如何验收成品是否符合预期。

文档的存在标准是能把战略和产品定义转为可执行契约：交付契约、实现约束、验收信号。每份文档负责一个工程决策层，帮助团队在代码落地、Review 和审计时使用同一套判断口径。

与父目录的关系​

父目录文档关系
FinBayes 战略白皮书唯一上位事实源。本目录所有文档都从战略白皮书派生
FinBayes 历史参考文档用于追溯早期讨论和旧工程上下文，不作为当前工程化事实源
FinBayes 项目入口当前 FinBayes 项目目录的 landing，指向战略白皮书、本目录和历史参考文档

文档清单（2026-05-29 Step 11 II-5 补全，共 16 份）​

主级文档（4 份）​

#文档角色
1FinBayes 产品定义L2 产品定义层：用户问 X 时 FinBayes 应该是什么样、输出哪些认知要素、交互对象和产品不变量
2FinBayes 工程架构L3 系统架构（9 部分 29 节 / 269K chars）：战略 / 产品定义到 runtime 的转译，业务对象 / 子系统 / 状态机 / 并发 / 降级 / 部署 / 存储 / 协议 / 安全 / 可观测 / 演化 / 测试 / 评估 / 缺口 / ADR 索引 / 风险 / 里程碑 / 审计 / 代码映射 + §29 认知体系工程承接 4 子系统索引
3主架构膨胀守门机制M0 期间 architecture.md 防膨胀守门：80 行阈值 + 拆分判断 + 收尾盘点
427 项待拍板归口 owner map（P0/P1/P2 三档分级）决策权三档分级（Step 11 整改包 III）：P0 5 项人类必签 / P1 8 项 AI 三方互审 / P2 14 项双签 + 真人 owner 暂代时间表

Engineering Packs（详见 engineering-packs README）​

#Pack状态
5M0 Walking Skeleton 工程包active（2052 行）
6Structured Cognition Result 1.1 契约源active
7数据 Provider 准入active
8数据分桶 70/20/10active
9评测公式 D1-D11active
10Milestone 字段演化矩阵 M0/M1/M2active

M1-M7 + horizontal-bundle 共 8 份占位/未起草工程包，详见 engineering-packs README。

Subsystems（4 子系统 + README）​

#文档
11Subsystem 入口
12KnowledgeGraphService 子系统
13ConsistencyMiddleware 子系统
14MCAClassifier 子系统
15EvalHarness 子系统

本 README​

#文档角色
16README.md（本文）目录引导

历史参考（不在阅读顺序中）​

  • FinBayes Harness Workflow 与 Goal 执行规范 — frontmatter status: deprecated-partial / maturity: superseded（2026-05-29 Step 11 II-5 移出阅读顺序）。原 v1 期间起草的 Harness 规范，与 ADR-001 / ADR-003 + 新架构 §25 / §26 大部分重合；保留作为历史追溯。
  • 已归档的 v1 工程化补充文档（2026-05-27 经新架构 v2 整体吸收后归档到 _archive/projects/finbayes/2026-05-27-engineering-supplements-archive/）：
    • local-runtime-and-entrypoints.md — Provider 配置 + 入口契约已被 §7 / §9 / §14 / §15 / §16 / §17 吸收
    • session-and-context-architecture.md — Session/Context 概念已被 §4 / §10 / §11 / §12 / §15 / §16 吸收
    • baseline-evaluation.md — v1 时期第三方仓评估，第三方参考改由 commons/references/finclaw/ 承接

工程化前置准入完成（2026-05-28 → 2026-05-29 Step 11 整改）​

  • 2026-05-28：完成 ADR-007 supplement formalize + L2 / L3 同步 + 4 子系统 + 1.1 契约派生 + harness 占位 + 主架构守门 + P1 三份 engineering-pack。M0 启动 11 维度准入全绿。汇总入口见 工程化前置准入产出汇总（2026-05-28）。
  • 2026-05-29：Step 11 整改包 III + IV 完成（决策权 P0/P1/P2 三档 + AI 三方互审 + cross-section 自动校验 + agent-pack budget 修复 + review 范式 playbook）。整改包 II + I 推进中。详见 Step 11 整改包详细方案。

实施叙事约束​

工程文档应直接描述 FinBayes 要交付的完整产品能力、实现约束和验收信号，避免使用会诱导工程偏离完整交付预期的措辞。

本文档包中的 degraded / 降级 只表示 runtime 在 Provider、数据源或证据不足时的可观测运行状态：系统必须明确说明缺什么、还能判断什么、下一步看什么。它不是较低质量实现目标，也不是跳过产品契约的理由。

阅读顺序​

推荐阅读顺序：

  1. 父目录 strategic-whitepaper.md — 战略基线与不变量
  2. product-definition.md — L2 产品行为级契约
  3. architecture.md — L3 系统级跨模块决策（9 部分 29 节，核心契约文件 269K，强制完整通读，不允许抽查决议启动，详见 文档 review 范式 Playbook）
  4. engineering-packs/ + subsystems/ — L4 工程包 + 子系统契约
  5. .archon/workflows/milestone-M0.yaml（真 Archon schema 可执行 DAG）+ .archon/specs/milestone-M0.spec.yaml（工作流契约规约：gate 判定 / 阈值 / required_checks 单一事实源）— 运行态约定不进公开站点

每个 milestone 启动时先读架构文档 §25 与 Step 11 整改方案，确认该 milestone 的交付契约、实现约束、AI 三方互审协议。每个 Goal 启动时读取当前 Goal 的 task packet 与相关章节，其他章节作为 drill-down 按需读取。

Web UI 与工程化落地的关系​

本次工程化版本包含 Web UI 集成，但 Web UI 层由独立团队成员迭代。本目录的工程化落地口径是：先把 FinBayes 金融认知 runtime、本地 Provider readiness、CLI / TUI、Session / Context、TaskGroup event stream、Web task adapter、projection schema、状态候选和评估门禁做完整，再通过稳定 contract 与 Web UI 集成。

因此，runtime 能力验收以 CLI / TUI / API contract / fixtures 为准；Web UI 并行消费 contract，负责交互呈现、可视化编排和前端状态体验。任务识别、证据组织、综合判断、状态写入和认知/执行分工由 runtime 提供统一实现。

当前状态​

文档状态
README.md（本文）active，2026-05-29（Step 11 II-5 补全 16 份清单）
product-definition.mdactive draft，2026-05-27
architecture.mdactive draft v2 (Step 11 IV-5 + 完整 review 多处 stale 修复)，2026-05-29
architecture-anti-bloat-guard.mdstable，2026-05-28
pending-decisions-owner-map.mddraft (Step 11 III-1 P0/P1/P2 三档分级)，2026-05-29
engineering-packs/6 active + 8 占位/未起草（详见目录 README）
subsystems/4 active + README
goal-execution.mddeprecated-partial / superseded，2026-05-26（已移出阅读顺序，保留作为历史追溯）

重写工作流与 Review 资产​

新架构 v2 由重写工作流产出，工作流资产保留在 governance/workstreams/finbayes-arch-rewrite/：

  • status.md — 工作流状态与节点历史
  • decisions/ADR-NNN-*.md — 已 accepted 6 条（ADR-001/002/003/004/008/010）+ 待写 4 条（ADR-005/006/007/009，M1 启动前 accepted）
  • decisions/INDEX.md — ADR 索引 + namespace 消歧
  • drafts/CHAP-NN-*.md — 27 章原始草稿（合并源，修订需回到 drafts 后再次合并）
  • reviews/ + 2026-05-28-step1-step11-*.md — 多 Agent 11 步 Review 资产
  • Step 11 整改包详细方案 — 4 整改包可执行清单

维护约定​

  • 文档 frontmatter 必填 title / status / last-updated / scope / maturity，与 仓库根项目说明 一致
  • 战略白皮书是上位事实源；本目录文档在出现冲突时按战略白皮书修正，父目录变更另走治理提案
  • 涉及生态对象 / 跨项目接口的变更必须走 变更协议
  • 工程代码 / 运行日志 / Controller state / handoff / task-packet 留在 FinBayes 工程仓，本目录只维护知识治理文档
  • 触及 P0 / P1 决策的 PR 必须走 ADR-003 fresh-eyes 二阶 + AI 三方互审协议（自动校验 npm run audit:p0-touch）
  • 跨章节一致性自动校验：npm run audit:cross-section