FinBayes 架构总纲（canonical · 单一事实源）
历史资料；不再 canonical。 当前唯一目标架构、差异映射与整改主线见 FinBayes Atlas。本文的固定编号、判断对账校准和旧建成度不得作为当前任务或验收依据。
2026-06-20 阶段一收尾快照。本文是架构的单一文字入口，已改基为 14 组件骨架编号（原 9 块蓝图编号见 §6 对照），并对照
finbayes/源码核实建成度与代码落点（claude/baseline-rebuild分支）。 可视化事实源 = 架构可视化 HTML（团队 / AI Agent 阅读 + review 用，含三视图；源文件static/projects/finbayes/engineering/skeleton-architecture/finbayes-architecture-visual/index.html）；可编辑图源 =finbayes-architecture-2026-06-20.drawio（3 页）。三者与本文同步。 根因 / 建成度底料：handoff2026-06-20-phase1-closure-rca-and-eval-design.mdPart A。三份源 spec（ai-agent-skeleton-spec.md/-finance.md/skeleton-vs-hermes-cc-martin.md）保留作明细 + audit。
0. 怎么读 + 14 组件编号体系（整改导航）
后续「量 FinBayes → 矫正 / 整改 / 优化」全程用本文的稳定编号点名。编号体系：
- ① ~ ⑭ = 14 个骨架组件（与三张图、HTML 一致）。
- 建成度：✅ 已建（1·2·6·7·9·10·13）/ 🟡 部分（3·4·5·8·11·12·14）。
- [fin] = 金融特化组件（7·9·11·13·14）。
- 横切机制（预算收束 / 并发隔离 / 韧性）不单列编号，融在主回路①与持久化⑧ / 可观测⑫上。
- 旧「9 块蓝图 + 5 横切 X-A
E + 金融加法 F1F5」是领域无关的理想分解，仍有效，作 9↔14 对照见 §6。
离产品本质最近的一块 = ⑭ 判断对账校准：记录侧 + 统计机制现均已建（calibration.py，eb7c01d），剩真实数据积累 + 按桶分层 + 接线，属阶段二；阶段一收尾不被它卡。防漂移：INV-15 自主循环本体 ✅ 满足、INV-16 判断对账 🟡 部分（记录 + 统计机制建、数据积累待）。
1. 核心立场（不可动摇的四条地基）
- 只有一个思考循环。 复杂行为 = 领域内容插在这一个循环上涌现，不另起第二套认知/规划引擎（确定性流程作为「工具」被循环调用，不反过来把循环嵌进流程引擎）。已落实为
INV-15，死引擎已删。 - Harness 比模型更关键。 决定成败的是验收基线 / 执行边界 / 反馈信号 / 回退手段的质量，不是认知核多强——先建好骨架，再磨认知核。
- 一个循环 ≠ 零显式状态。 任务进度、判断台账要外化成数据对象（写文件 / 库），不塞进对话历史靠模型记。
- 机制 / 内容 / 策略点三分。 判据是「换业务要不要改」；约束要编码化（类型 / Linter / CI / Hook），不靠文档期望。
2. 三张架构图（drawio · 见 HTML 渲染版）
- 图 A · FinBayes 整体架构（理想完整形态） — 系统全貌：客户端 / 网关 / AI Agent 骨架核心 / 金融认知投影 / 数据真实接地 / 记忆存储 / 横切基础设施 / 生态上下游；建成度色标（✅ 已建 / 🟡 部分 / ⬜ 未建 / 🔴 缺口）。
- 图 B · FinBayes AI Agent 骨架（ReAct loop · 14 组件） — 以 ReAct loop（① 主回路）为核心的骨架，是整体架构的核心部分；建成度 + 真实代码落点（见 §3）。
- 图 C · FinBayes AI Agent Runtime · 运行时流程 — 对照
agent/loop.py的一次问答动态生命周期（见 §4）。 - 附 · 当前问题 → 组件/层映射（Part A A1 根因表，见 §5）。
→ 架构可视化 HTML（渲染版，推荐团队 / AI 阅读）/ finbayes-architecture-2026-06-20.drawio（可编辑源）。
3. 14 组件部件字典（逐一阐述 · 整改时按此点名）
格式：编号 名称 [fin] — 建成度 · 代码落点；含 是什么/做好的样子 · 金融特化 · 整改锚点 · 标杆。
① 主回路（发动机）— ✅ · agent/loop.py _run_agent_loop:658 · cap=40
- 单一 ReAct 循环：reason → 调工具 → 观察 → 收尾；模型是唯一决策者，系统是手脚不是大脑；新能力加在循环外不改循环内。含 provider 抽象、停止策略执行点。
- 整改锚点：死引擎（两段式取数/认知分离）已删 → 维持单循环，认知核在回路内产出结构化判断。
- 标杆：Hermes（≤90）、martin（≤40）、Claude Code 同范式。
② 工具系统 — ✅ · agent/tools/（38 工具）
- 注册 / schema 暴露 / 沙箱执行 / 超时与结果整形 / MCP 适配 / 副作用声明；ACI 阶梯（工具对应 Agent 目标不是底层 API）→ 结构化错误带修正建议；内部事件不进 LLM（AgentMessage vs Message 隔离）。
- 整改锚点：从仅报价×2 已扩至 38 工具 + 金融数据栈 → 维持 ACI 化、错误结构化。
- 标杆：Claude Code（ACI 标杆）；martin（~37 工具 + 金融栈）。
③ 上下文工程 — 🟡 · agent/context.py + tool_context.py
- 五层装配：常驻层（身份 / SOUL，短硬可执行）/ 按需层（Skills，见 ⑤）/ 运行时注入 / 记忆层 / 系统层（Hooks 不进上下文）；别把确定性逻辑塞进上下文；保护 prompt 缓存前缀。
- 金融特化：装配的内容是金融的（SOUL=金融顾问、Skills=金融方法论），机制不变。
- 整改锚点：身份已从硬编码外移；运行时注入读 USER.md 偏好仍部分（现写了不读）。
- 标杆：Claude Code（CLAUDE.md + 压缩 + plan）最佳。
④ 记忆 — 🟡 · agent/context.py + memory.py
- 四类：工作记忆=上下文窗口 / 程序性=Skills / 情景=JSONL 历史 / 语义=MEMORY.md；外化写盘，写并发契约（单 writer，子代理默认无写权）。
- 金融特化：第五类「判断台账」——每个标的的现行论点 / 失效条件 / 复盘记录（见 ⑭）。
- 整改锚点：后台记忆整理只整 base、未作用域化 → per-principal consolidate（阶段二）。
- 标杆：Hermes（可检索 MemoryProvider + FTS5）、Claude Code（TodoWrite 任务态）。
⑤ 规划拆解 — 🟡 · agent/skills.py（按需）+ 循环内隐式
- 任务分解 + 方法论 Skill 懒加载（系统提示只留索引，触发时才注入完整内容）+ 循环内隐式规划，无独立规划引擎。Skill 描述含 Use-when / Don't-use-when + 反例。
- 金融特化：金融方法论（风险四维 / DCF / 可比 / 事件 checklist / MCA / S1）= 懒加载 Skill，不是常驻字段矩阵。
- 整改锚点：讲座腔 bug 的架构根因曾在此——字段矩阵「常驻全量手册」反模式 → 已改按题眼懒加载。
- 标杆：Hermes（Procedural Memory）、Claude Code（Use-when 发源地）。
⑥ 子代理 — ✅ · agent/subagent.py + tools/spawn.py
- fork 有界子循环并行干活再聚合；接口是工具、机制是独立基础设施；独立上下文只回摘要；五件套（深度上限 / 并发上限 / 预算继承 / 取消传播 / 部分失败聚合）；ContextVar 作用域继承、gather 扇出。
- 金融特化：多标的并行分析（compare）是典型用例。
- 整改锚点：作用域（gather / 子任务 ContextVar 继承）已加并发作用域回归测试（
test_finbayes_principal_scope）。 - 标杆：Hermes（delegate + MoA 独有）、Claude Code（Task 隔离标杆）、martin（spawn fan-out）。
⑦ 真实数据接地 [fin] — ✅ · data/（18 源）+ fetch_result.py
- 金融数据栈（行情 / 财报 / 宏观 / 链上 / 期权）作为一等工具；统一出处信封（来源 + 时点）。
- 整改锚点：缺 FedWatch / 点阵图 / 利率期货等源（增量接）；宏观库 fredapi 已提为核心依赖（
6b75c25）。 - 标杆：martin（金融数据栈独有）。
⑧ 持久化 — 🟡 · session/manager.py
- 任务态写盘（TaskState）、断点续跑；长任务跨 session 恢复（横切 X-E）。
- 整改锚点：任务态外化 + 续跑路径需补全验收。
- 标杆：Claude Code（TodoWrite + plan 标杆）、Hermes（WAL）。
⑨ 主动性心跳 [fin] — ✅ · heartbeat/service.py · process_direct:1380
- 第二类入口：cron / heartbeat 自醒；只产生唤醒事件，触发负载=标准装配输入；旁路经
process_direct → _process_message → 同一 _run_agent_loop（不另起引擎 · INV-15）。 - 金融特化：失效条件命中 → heartbeat 主动复盘闭环（接判断台账）。
- 整改锚点：主动盯盘只盯 owner（心跳只接 base 一个工作区）→ 遍历 principals、各自复核、发回本人（阶段二）。
- 标杆：martin（cron + heartbeat LLM 判）、Claude Code（scheduled / loop）。
⑩ 多渠道 — ✅ · channels/（12 adapter）· manager._should_dispatch:234
- 消息怎么进来、答案怎么发出去；渠道差异收敛在 adapter 层，换渠道不改 Agent 核心；能力降级路由：瞬时输出（进度 / 流式预览）只发能原地刷新的渠道，canonical 末答永远下发。
- 整改锚点：含出站暴露（agent 自身作 MCP-server / ACP）作回填项。
- 标杆：Hermes（20+ 渠道最全）、martin（10 渠道 + MessageBus）。
⑪ 自检护栏 [fin] — 🟡 · security/redact.py scrub:95
- 工具调用前后的拦截点 + 授权 + 审批 / HITL：白名单授权 / 工作空间路径隔离 / 不可逆操作执行前确认 / 注入扫描 / 关键操作独立复核；安全先于功能。
- 金融特化：合规 / 审计——不越界投顾（牌照红线）、凭证绝不落盘（INV-11 双处脱敏，scrub 日志 / trace / 末答三出口兜底）、判断可追溯到源 + 时点。
- 整改锚点：access 白名单 / 认知-执行隔离软约束为主；旧仓 INV-01 只读标签在新基线丢失（40 工具 0 access 字段）→ 硬化（register 拒非只读），与「未决六」交易边界耦合（阶段二）。
- 标杆：Hermes（注入扫描 + 审批 + 路径最强）、Claude Code（权限 + hooks + HITL）。
⑫ 可观测 — 🟡 · observability.py
- 事件流（tool_start / tool_end / turn_end）一次发布多路消费；JSONL 可重放；trace 含 prompt / 工具入参出参 / token；跨子代理因果链。
- 整改锚点：request_id ↔ judgment 没完全 join → 打通 trace_id 全链（阶段二/三）。
- 标杆：完整 trace + 可重放为标杆形态。
⑬ 金融认知核（输出投影）[fin] — ✅ · judgment/ models·projections·renderers·runtime·taxonomy
- 模型末答 → 用户面输出（机制=骨架、格式契约=内容；注意契约会逆流进 prompt 污染上游）。
- 金融特化：用户面=顾问语气散文（结论先行）；内部面=结构化可证伪判断契约（方向 / 失效条件 / 反证 / 不确定性，事后抽取、不进 prompt）；用户主权两步（候选 → 用户确认才落地）。
- 整改锚点：判断契约曾逆流进 prompt（讲座腔）→ 已改内部事后抽取；保留用户主权两步。追问按钮触发率依赖模型格式；评估后决定不做生成兜底（召回已广、生成兜底是补丁反模式）。
- 标杆：结构化判断契约 + 用户主权是 FinBayes 独有强项（三标杆全无）。
⑭ 判断对账校准 [fin] — 🟡 记录 + 统计机制已建·阶段二（数据积累 + 分层） · judgmentlog.py + calibration.py + judgment/
- 判断台账留痕 → 跟进 → 校准（每个标的现行论点 / 失效条件 / 复盘记录 → 把握度准不准）。
- 现状：记录侧 + 统计侧均已建——记录侧（
judgmentlog.py判断台账 / record_outcome / 失效复盘到期回路）+ 统计侧（calibration.py：把握度→概率、verdict→结果、命中率 / Brier / 按把握度桶可靠性 / ECE +finbayes calibrationCLI，eb7c01d）。剩：真实数据积累（判断到期才出真校准、现 0 条已兑现）、按 MCA 桶 / 市场结构分层、心跳后推校准摘要、trace_id 全链 join。 - 整改锚点（阶段二）：校准模块已建（命中率 / Brier / 可靠性 / ECE）；待数据积累 + 分层 + 接心跳/trace。ADR-020「校准账本 = 唯一计分项」的工程落点，
INV-16即指此。 - 标杆：判断跟进 + 校准三标杆全无，是 FinBayes 护城河。
4. 主回路四环 · 真实运行（对照 agent/loop.py）
渠道 channels/ → 总线 bus/ → _run_agent_loop(cap=40)：
- ① 感知/规划
provider.chat(消息, 工具):725← 模型唯一决策者。 - ② 行动 有工具调用 →
asyncio.gather并发执行:788（工具层 ② / 数据层 ⑦）。 - ③ 观察/回灌
scrub脱敏:794→ 失败判定_looks_like_failed_fetch→add_tool_result:825→ 回灌入下一轮 ①。每轮停止记账：stall 同调用×3 停（stall_limit=3 :687/:838）、连续失败×5 停（fetch_failure_limit=5 :693/:846）。 - ④ 收敛 无工具调用 →
final_content:855｜ 预算/stall/no_data → 强制收束_force_closure:876。 - → ⑬ 输出投影
judgment/→ ⑩ 渠道能力降级路由manager._should_dispatch:234→ 发回用户。
心跳 ⑨ 走旁路 process_direct:1380 汇入同一主循环。横切贯穿每轮：预算/停滞→强制收束、事件流→可观测、错误回喂/provider fallback。
5. 当前问题 → 组件/层映射（2026-06-20 · Part A A1）
两类问题：表面/局部（孤立·便宜·不动架构）vs 架构缺口（离产品本质近）。⑭ 校准是离产品本质最近的一块（记录+统计机制已建、数据积累待，阶段二）；现无纯架构缺口。
| 问题 | 落点 · 阶段 | 类别 |
|---|---|---|
| 主动盯盘只盯 owner | ⑨ + ④ 作用域 · 二 | 部分硬化 |
| 缺 FedWatch/点阵图/利率期货 | ⑦ · 一/二 | 表面/局部 |
| ✅ 宏观库 fredapi 没打包 | ⑦ · 一（已清 6b75c25） | 表面 |
| 追问按钮触发率 | ⑬ 输出 · 决定不做（补丁反模式） | 半表面 |
| 后台记忆整理只整 base | ④ · 二 | 局部 |
| ✅ 子代理作用域没加测 | ⑥ + ④ · 一（已加测） | 局部 |
| ✅ 配置驼峰 footgun | 配置层 · 一（已清 extra=forbid） | 表面 |
| 护栏多为软约束 | ⑪ · 二(未决六) | 部分硬化 |
| 可观测 trace 没全串 | ⑫ · 二/三 | 部分 |
| 判断对账校准：统计机制已建、缺数据积累/分层 | ⑭ · 二 | 部分（机制建） |
A2 结论：阶段一收尾不被任何架构缺口卡。表面项已清（fredapi 提依赖 ✅ / 配置告警 ✅ / 子代理作用域测试 ✅ / 追问兜底=决定不做）；vs-martin 自动闸门管线已建（scripts/eval_*.py，待 owner 配判官 key + Stage 0 新灵魂重生跑）+ 重测延迟 → owner 签字。
6. 9↔14 编号对照 + 三方 scorecard
旧 9 块蓝图（理想分解）→ 新 14 组件（as-built）。两者不是 1:1（⑤ 规划拆解在 9 框无独立块；⑧ 持久化 / ⑫ 可观测原是横切；⑬/⑭ 同落 judgment/）：
| 旧 9 块 | → 新 # | 旧 9 块 | → 新 # |
|---|---|---|---|
| 块4 思考循环 | ① 主回路 | 横切E 持久化 | ⑧ 持久化 |
| 块3 工具 | ② 工具系统 | 块8 触发/调度 | ⑨ 主动性心跳 |
| 块2 上下文 | ③ 上下文工程 | 块1 渠道 | ⑩ 多渠道 |
| 块7 记忆 | ④ 记忆 | 块5 护栏 / F1 | ⑪ 自检护栏 |
| 块4内 / SK Skills | ⑤ 规划拆解 | 横切C 可观测 | ⑫ 可观测 |
| 块9 子代理 | ⑥ 子代理 | 块6 输出投影 / F2 | ⑬ 金融认知核 |
| 块3 金融数据栈 / F4 | ⑦ 真实数据接地 | 块7 判断台账 / F3 | ⑭ 判断对账校准 |
三方对照 scorecard（Hermes 通用 / Claude Code 编码 / martin 金融 · 按旧 9 块 · 底料 2026-06-05）：✅✅ 超出/标杆 · ✅ 达标 · 🟡 弱 · ➖ 无。
| 部件 | Hermes | Claude Code | martin |
|---|---|---|---|
| ① 渠道 | ✅✅ 20+多入口 | 🟡 多界面单入口 | ✅ 10 渠道 |
| ② 上下文装配 | ✅ 3层+预压缩 | ✅✅ CLAUDE.md+plan | ✅(身份焊死) |
| SK Skills | ✅✅ Procedural Memory | ✅✅ Use-when 发源地 | 🟡 |
| ③ 工具+ACI | ✅ | ✅✅ ACI标杆 | ✅ ~37+金融栈(独有) |
| ④ 思考循环 | ✅ ≤90 | ✅ | ✅ ≤40 |
| ⑤ 护栏 | ✅✅ 最强 | ✅✅ 权限+HITL | 🟡 软 |
| ⑦ 记忆 | ✅✅ 可检索+FTS5 | ✅ TodoWrite | 🟡 grep |
| ⑨ 子代理 | ✅✅ delegate+MoA(独有) | ✅✅ Task标杆 | ✅ spawn |
| X-B 并发 | ✅ worktree | ✅ 后台并行 | 🟡 全局锁 |
| X-E 持久化 | ✅ WAL | ✅✅ TodoWrite+plan标杆 | 🟡 JSONL |
| F2/F3 判断契约·台账·用户主权（=新 ⑬+⑭） | ➖ | ➖ | ➖ |
结论：三标杆是同一种单循环 ReAct 范式（平台最全 / 工程质量标杆 / 金融内容最全），骨架是其超集。新 ⑬+⑭（判断契约 + 台账 + 用户主权 + 校准）三标杆全无，是 FinBayes 真正独特价值——但要建在完整骨架上，不是建在偏离的两段式上。
7. 来源与版本
- 本快照：2026-06-20 阶段一收尾 · 改基 14 组件 · 代码落点对照
finbayes/源码（claude/baseline-rebuild）核实。 - 根因 / 建成度底料：handoff
2026-06-20-phase1-closure-rca-and-eval-design.mdPart A（INV-15/16、主回路四环、问题→组件映射）。 - 可视化：
finbayes-architecture-visual.html（团队 / AI 阅读）；可编辑图源：finbayes-architecture-2026-06-20.drawio（3 页），替代旧finbayes-target-architecture.drawio（9 组件，已退役）。 - 通用骨架推演：
ai-agent-skeleton-spec.md（v2.1）；金融特化：ai-agent-skeleton-spec-finance.md（v2.1-fin）；三方对照底料：skeleton-vs-hermes-cc-martin.md。 - 14 组件原始定义：
governance/workstreams/finbayes-arch-rewrite/drafts/2026-06-04-financial-agent-skeleton-blueprint.md。
Replaced-by: https://labs-fintecai-gov.topquant.org/projects/finbayes/atlas/