FinBayes 工程架构文档重写 — 工作流状态
续接这个工作流
无论是同一会话续接、新会话续接、还是新 Agent 接手，标准动作：
- 读这份文件（status.md）一页就够 — 知道现在在哪、下一步做什么、哪些事已对齐
- 查决策：如果需要知道某个决策为什么这么定，去
decisions/看对应 ADR 文档 - 查章节草稿：如果需要看某章节当前状态，去
drafts/看对应章节文件 - 不要回看对话历史：所有对齐结论应该已经沉淀到本文件或 decisions/，对话只是加工现场
工作流是什么
把当前 projects/finbayes/engineering/architecture.md 重写为更可读、更可被实施 Agent 直接消费的新版本。原文档存在结构性问题：拓扑图把组件目录画成关系图、业务/技术/部署三层架构混在一张图、流程流转状态完全缺失、并发模型不交代、概念边界混乱。
重写采用"分层文档章节模板 + 静态视图分层画图标准 + 决策记录独立成档 + 业务建模思路"四套业界成熟方法的组合（具体方法选择见 ADR-002）。
最终产物
projects/finbayes/engineering/architecture-v2.md— 新主文档（9 部分 / 27 节）governance/workstreams/finbayes-arch-rewrite/decisions/ADR-NNN-*.md— 关键架构决策文档- 旧
architecture.md归档到_archive/projects/finbayes/2026-XX-XX-architecture-v1-rewrite/
当前状态
日期: 2026-05-27
所在阶段: ✅ 工作流主体全部完成（28 章草稿 + 主文档合并 + 上位/同位对齐 + 双轨拆分 + R1/R2 双轮 7 reviewer + Phase 1/2 修订 + 6 份 accepted ADR + 3 个 proposal 转 accepted + goal-execution v1 deprecation + CLAUDE.md 改名提示更新 + 516 行复盘+可复用方法论文档）。工作流状态从 active 转为 stable（保留作生态内复用模板）。下一阶段（不在本工作流范围）：M0 OpenSpec task packet 起草 + 工程实施仓 bootstrap（Codex 实施）+ DH/TM/RLE/FEFM 复用本工作流方法论启动各自架构重构。
已完成:
- 工作流初始化（status.md + 3 份 ADR）
- 第一部分（立架）3 章草稿
- 第二部分（业务架构）3 章草稿
- 第三部分（系统全景）3 章草稿
- 第四部分（系统运行）4 章草稿
- 第五部分（部署与基础设施）3 章草稿
- 第六部分（横向贯穿关注点）3 章草稿
- 第七部分（质量与验收）2 章草稿
- 第八部分（缺口与决策）3 章草稿
- 第九部分（落地映射）3 章草稿
- 总行数 ~5900 行；27 章草稿全部进入"待评审"状态
下一步候选（待用户选择推进顺序）:
- 评审与修订：用户对 27 章逐章 / 跨章评审，沉淀修订意见
- ADR 起草：把 7 条待写 ADR（ADR-004 至 ADR-010）按优先级（高 → 中）起草成独立决策文档
- 主文档合并：把 27 章合并为单一
projects/finbayes/engineering/architecture-v2.md（按 ADR-002 设计）+ 旧 architecture.md 归档 - proposal 移到 accepted：
governance/proposals/inbox/2026-05-26--finbayes-contract-alignment-after-whitepaper-v2.md走 accepted 流程 - 意图识别调研报告续写：8 章待续（agent-frameworks / function-calling / cache-rules / financial-llms / multi-tier-degradation / provider-config / multimodal-preprocessing / open-questions / references）
额外材料:
- 项目级调研资产：
projects/finbayes/research/intent-recognition-and-llm-strategy/（已起草 README + summary + recommendations，其余 8 章待评审反馈后继续） - Docusaurus dev server 在 http://localhost:3002/ 运行（PID 61245）
章节追踪表
状态说明：— 未开始 / D 已草稿 / R 评审中 / A 已定稿 / B 阻塞（依赖未解）
第一部分：把架构立起来
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-01 | 文档角色与读者 | D | drafts/CHAP-01-文档角色与读者.md | 待评审 |
| CHAP-02 | 上位继承与不变量 | D | drafts/CHAP-02-上位继承与不变量.md | 待评审。含战略不变量逐字复述、被拒绝概念清单、不抢答事项 |
| CHAP-03 | 架构目标与质量取舍 | D | drafts/CHAP-03-架构目标与质量取舍.md | 待评审。含 8 项质量属性 + 取舍规则表 |
第二部分：业务架构
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-04 | 业务对象与关系 | D | drafts/CHAP-04-业务对象与关系.md | 待评审。7 个 first-class 概念 + ER 关系图 + 各对象生命周期要点 |
| CHAP-05 | 用户价值与认知流转 | D | drafts/CHAP-05-用户价值与认知流转.md | 待评审。三层价值工程承接 + 端到端业务流转图 + 关键节点业务约束 |
| CHAP-06 | 关键业务场景 | D | drafts/CHAP-06-关键业务场景.md | 待评审。9 个典型场景（七类任务 + 复合 + 主动信号）+ 每场景业务约束 |
第三部分：系统全景
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-07 | 系统与外部世界的关系 | D | drafts/CHAP-07-系统与外部世界的关系.md | 待评审。1 张 Context 图 + 7 类外部角色接触契约 + 战略边界在 Context 层的体现 |
| CHAP-08 | 系统内部的进程与服务划分 | D | drafts/CHAP-08-系统内部的进程与服务划分.md | 待评审。1 张 Container 图 + 单进程优先决策 + 各容器职责 + 容器间通信方式 |
| CHAP-09 | 每个子系统的内部组件 | D | drafts/CHAP-09-每个子系统的内部组件.md | 待评审。6 个子系统（Input/Output Pipeline / Task Orchestration / Evidence + Synthesis / State Management / Capability Registry / Provider Adapter）+ 各 Component 图 + 数据流总览。融入意图识别调研结论（LLM Function Calling 主导 / 4 层降级 / 用户配置 Provider first-class） |
第四部分：系统运行
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-10 | 关键场景的流转图 | D | drafts/CHAP-10-关键场景流转图.md | 待评审。8 张 Sequence 图（同步问答 / TaskGroup / 主动信号 / 候选确认 / Provider 降级 / 凭证拒收 / clarify / 长会话压缩） |
| CHAP-11 | 状态对象的生命周期 | D | drafts/CHAP-11-状态对象生命周期.md | 待评审。5 张 State Machine（Session / Task / TaskGroup / JudgmentRecord / StateCandidate） |
| CHAP-12 | 并发与异步处理 | D | drafts/CHAP-12-并发与异步处理.md | 待评审。选定 asyncio.TaskGroup + 失败隔离 + 取消语义 + Semaphore backpressure |
| CHAP-13 | 故障与降级路径 | D | drafts/CHAP-13-故障与降级路径.md | 待评审。故障决策树 + 各模块失败矩阵 + 不降级硬故障清单 |
第五部分：部署与基础设施
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-14 | 部署形态 | D | drafts/CHAP-14-部署形态.md | 待评审。3 种形态 + 本地优先单机物理拓扑 + 首次安装流程 + OS 路径约定 + 升级/卸载 |
| CHAP-15 | 数据存储划分 | D | drafts/CHAP-15-数据存储划分.md | 待评审。5 类数据（State Store / Cache / Config / Credential / Audit Trail）+ SQLite 主存 + OS Keychain 凭证 + 数据完整性保护 |
| CHAP-16 | 通信协议 | D | drafts/CHAP-16-通信协议.md | 待评审。4 类通信范围 + Web API 端点表 + MCP / Channel + 跨协议错误码 + 协议演化策略 |
第六部分：横向贯穿的关注点
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-17 | 边界与安全 | D | drafts/CHAP-17-边界与安全.md | 待评审。三条战略边界工程承接 + 凭证类双向阻断图 + 输出端过滤位置（待 ADR-010）+ 执行类工具注册拒绝 + 用户主权 + Review Gate |
| CHAP-18 | 可观测性 | D | drafts/CHAP-18-可观测性.md | 待评审。认知过程 / 系统运行两类可观测 + 审计 trail 全景 + task_id trace 体系 + 4 类指标 + 工程日志脱敏 |
| CHAP-19 | 演化与版本管理 | D | drafts/CHAP-19-演化与版本管理.md | 待评审。5 类资产版本化 + semver + Schema migration 单向幂等 + Prompt 版本化（待 ADR-009）+ Provider / 工具池演化 + 演化中的不变量 |
第七部分：质量与验收
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-20 | 测试体系 | D | drafts/CHAP-20-测试体系.md | 待评审。LLM 应用测试金字塔 + 4 层测试 + LLM Mock 三模式录制重放 + 降级/边界/并发测试 + CI 集成 |
| CHAP-21 | 评估闭环 | D | drafts/CHAP-21-评估闭环.md | 待评审。评估测试 vs 普通测试 + 数据集分层 + Rubric 8 维度 + LLM-as-judge + 软/硬阈值 + 评估驱动改进 + Case Library 作为回归追踪非门禁 |
第八部分：已知缺口与决策
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-22 | 第一阶段缺口 | D | drafts/CHAP-22-第一阶段缺口.md | 待评审。三类缺口（战略待定 / 工程延后 / 场景外）+ 缺口演化触发流程 + 缺口与质量目标关系 |
| CHAP-23 | 架构决策索引 | D | drafts/CHAP-23-架构决策索引.md | 待评审。已 accepted 3 条 + 待写 7 条 ADR + 优先级 + ADR-004 编号变迁 + 拒绝概念无需独立 ADR + ADR 依赖关系图 |
| CHAP-24 | 风险登记 | D | drafts/CHAP-24-风险登记.md | 待评审。4 类共 18 条风险 + P1/P2/P3 评级 + 缓解 + 残余风险 + 触发处理动作 |
第九部分：落地映射
| ID | 节标题 | 状态 | 草稿文件 | 阻塞 / 备注 |
|---|---|---|---|---|
| CHAP-25 | 与里程碑 / 任务的对应 | D | drafts/CHAP-25-与里程碑任务的对应.md | 待评审。M0-M7 8 个里程碑全景 + M0 走通骨架范围 + 各里程碑覆盖章节增量 + 依赖与并行 + OpenSpec/Archon 协作落地 |
| CHAP-26 | 审计点 | D | drafts/CHAP-26-审计点.md | 待评审。三检展开为四类断言（机械/结构/样本/语义）+ 各类阻断条件 + M0-M1 具体审计点 + 审计 vs 测试 vs 评估关系 |
| CHAP-27 | 代码仓位置映射 | D | drafts/CHAP-27-代码仓位置映射.md | 待评审。工程实施仓与本仓边界 + src layout + 6 子系统/7 业务对象/5 状态机/数据/协议/边界/可观测/Prompt/测试/评估/CI/配置全映射 + 反向追溯机制 |
共识索引
已沉淀为独立决策记录的（见 decisions/）
| 编号 | 决策主题 | 文件 | 状态 |
|---|---|---|---|
| ADR-001 | 工程范式：Harness Workflow + 里程碑切片 + 走通骨架试点 | decisions/ADR-001-工程范式.md | 已确认 |
| ADR-002 | 架构文档结构：分层章节 + C4 画图 + 决策独立成档 | decisions/ADR-002-架构文档结构.md | 已确认 |
| ADR-003 | 工程实施栈与协作模式：OpenSpec + Archon + Agent 协作分工 | decisions/ADR-003-工程实施栈与协作.md | 已确认 |
| ADR-004 | 任务识别策略：LLM Function Calling 主导 + 4 层降级 | decisions/ADR-004-任务识别策略.md | 已确认（M0 最小 accepted 版） |
| ADR-008 | LLM Provider 接口抽象（与 whitepaper-rewrite 工作流 ADR-008 同号不同物） | decisions/ADR-008-LLM-Provider-接口抽象.md | 已确认（M0 最小 accepted 版） |
| ADR-010 | 输出端凭证过滤位置 | decisions/ADR-010-输出端凭证过滤位置.md | 已确认（M0 最小 accepted 版） |
待写入独立决策记录的候选（写作过程中沉淀）
| 候选编号 | 主题 | 触发章节 |
|---|---|---|
| ADR-004 | 多 Skill 命中同一任务时的优先级规则（市场范围 / 版本 / 优先级标记三维） | CHAP-09 写子系统时定 |
| ADR-005 | 内部并发原语选择（异步等待 / 多线程 / 多进程） | CHAP-12 写并发时定 |
| ADR-006 | 部署形态优先级（本地优先 / 远程优先 / 混合） | CHAP-14 写部署时定 |
| ADR-007 | 状态写入"待确认 → 已确认"两步设计 | CHAP-11 写状态生命周期时定 |
| ADR-008 | 大模型 Provider 接口抽象方式 | CHAP-09 写 Provider 子系统时定 |
| ADR-009 | Prompt 是代码还是数据 / 版本化策略 | CHAP-19 写演化策略时定 |
| ADR-010 | 输出端凭证类内容过滤的位置 | CHAP-17 写边界与安全时定 |
| ADR-011 | 明确拒绝的概念清单（不可引入 11 条契约 / 双模式 / 协作伙伴 / L3 四承诺 / 等） | CHAP-02 写上位继承时引用 |
共识但不必独立成 ADR 的小约定
- 稳定编号: 章节用 CHAP-NN / 决策用 ADR-NNN / 部分用 PART-N / 评审轮次用 REV-N。引用时必用编号，不说"上次那个 / 之前讨论的"
- 写作纪律:
- 内容 > 形式：每个章节 / 小节 / 段落 / 表格的存在必须服务于实施者的具体疑问。为了完整性 / 对称性 / 模板齐整而堆砌的内容应当删。章节长度按内容多寡定，不按模板定。如果某节内容无法回答任何实施者疑问，应当合并或删除而不是注水
- 建设型而非防御型：重点说"是什么 / 要做什么 / 怎么做"，不要变成"不是什么 / 不做什么 / 不许什么"的清单。战略边界（不直接下单 / 凭证不收）作为事实陈述承接一次就够，不要在每节都复述。"不做什么"列表只在确实能帮实施者避开错误时保留，且保持紧凑
- 不解释与工程化落地无关的方法论 / 理论：方法论选择类的内容（为什么选 arc42、为什么不用 Goal 范式等）放在对应 ADR 里，主架构文档不展开。即使是 ADR 本身，方法论对比也只列结论不展开评分
- 每节首段一句话回答"这节回答什么问题"
- 不在正文用"§N / vN"这类编号引用方式，用章节名 / 描述性引用
- 专有名词第一次出现给一句话解释（例如"Fin Object（用户关注的金融对象，含标的 / 板块 / 主题 / 事件 / 政策 / 组合 / 叙事 / 关键人物中的任意一种或组合）"）
- 图配三段说明：图表达什么 / 图特意不表达什么 / 怎么读这张图
- 不堆术语：能用普通中文表达的不用英文缩写；必须用英文术语时第一次出现给中文解释
- 抽象 vs 具体：优先用 FinBayes 实际场景说明，少用"系统应该 / 工程上应当"这类一般性论述
- 战略不变量（任何章节不得违反）:
- "FinBayes 不直接下单, 也不持有账户凭证"（战略白皮书边界原话）
- "金融执行凭证 — 私钥 / 助记词 / 钱包恢复短语 / 交易所登录凭证 / 交易所 API key / 经纪商 API key / 银行账户 / 信用卡等 — FinBayes 一律不收、不存、不训练"（战略白皮书凭证条款原话）
- 不引入战略白皮书构建期被否决的概念（11 条字段契约 / 默认 vs 行动准备双模式 / 升格为关系定义的"认知协作伙伴" / L3 长期状态四承诺 / 零状态前提 / 情绪桥 / 信任债承诺）
悬而未决的问题
（这里记录推进过程中遇到的需要决策但暂时不裁决的问题，等积累到一定时机批量讨论）
OQ-001 — Review gate 的 grep 检查不能作为合格判定，应配人工实质语义核查
工程化落地时，"被拒绝概念 0 命中" / "战略不变量原句存在" 这类 grep 检查存在两层风险：
- 同义改写绕过：被禁的"行动判断"可被改写为"行动倾向 / 行动指向 / 行动结论"等同义表达
- 结构隐藏：把被禁概念拆成不同字面散落在多处
- 英文替换：用 "action mode" 等英文绕过中文匹配
Goodhart's law：以 grep 命中数为指标必然导致 Agent 优化字面而非语义。
正确角色：
- grep 是必要的快速过滤工具，不是合格判定标准
- Review gate 应该是 "机械 grep + 人工实质语义核查" 双层
- 人工核查识别同义改写 / 结构隐藏 / 英文替换等规避方式
关于 CHAP-02 § 必须显式拒绝的概念 小节里 grep 命中的处理：
- 方案 A：用 HTML 注释包住禁止清单区段，grep 工具识别注释后跳过
- 方案 B：在 verify-kb 脚本里把"被禁概念命中"的判定改成"出现在非禁用清单区段的任何地方才算命中"
- 方案 C：保留人工判读，工具只列出位置不做判定
CHAP-03 § 质量属性一战略保真度 已明确表述为"机械 grep + 人工实质语义核查双层"，作为 Review gate 标准。
留待实施 review gate 实现时具体定。
OQ-003 — 自然语言到任务的识别策略
已经过多轮深度调研。研究材料独立于本工作流，作为 FinBayes 项目级资产存在于：
projects/finbayes/research/intent-recognition-and-llm-strategy/
研究覆盖：业界 Agent 项目意图识别实践 / LLM Function Calling 在金融场景实效 / L3 缓存与规则路径 / 金融专用 LLM 评估 / 多层劣化设计 / 用户自配置 Provider / 多模态预处理。
当前结论倾向（待 ADR-004 正式定）：
- 主架构采用业界标准（LLM Function Calling 主导 + 工具池 + 澄清作为工具），不预设意图分类管道
- L1 主力 Claude Sonnet，备选 GPT-4o / DeepSeek / Qwen 按场景路由
- L2 本地兜底 Qwen2.5-7B/14B（不用金融专用 LLM）
- L3 缓存 + 规则路径预期 18-22% 命中
- 用户自配置 Provider 作为 first-class 场景（两层路由：系统默认 + 用户覆盖）
- 多轮 / 复合任务在意图层显式拆解（不指望 LLM 原生处理）
详细推荐方案见 recommendations.md。ADR-004 起草以此为基础。
OQ-002 — 认知质量验收方法尚未定义
认知质量验收是工程上待解决的设计问题。当前 CHAP-03 仅明确：
- FinBayes Case Library 不作为二元门禁（其内容动态迭代）
- 每条认知输出必须可被重放、对比、追溯（含证据来源、综合路径、Provider 调用），作为后续质量评估的可被验证基础
待 CHAP-20 测试体系 + CHAP-21 评估闭环具体定义的事项：
- 评估维度清单（反方覆盖率、信息缺口标注率、来源时间戳完整率、失效条件具体性、多视角充分性 等候选）
- 各维度的具体 rubric（每个维度上从合格到优秀的可观测信号）
- 评估者机制（多评估者交叉验证、跨 Agent 模拟视角 vs 人工判读如何组合、inter-rater reliability 校准）
- Case Library 的回归报告如何驱动改进决策（哪些退化必须修、哪些可记技术债、退化的判定阈值）
- 量化指标的具体计算方法与可达性边界
工程层面目前不预设具体方法，避免在方法未确认时把"盲读"等不可重复的人工判读当成工程标准。
会话止 / 节点收尾协议
每次完成一个有意义的步骤（写完一章 / 通过一个决策 / 完成一轮评审），固定动作：
- 把新共识 / 决策追加到本文件「共识索引」 — 重要的提升为 ADR 独立文档
- 更新本文件「当前状态」「章节追踪表」
- 如果产生新 ADR，立独立文档到
decisions/ - 把
last-updated改为当天日期
多 Agent 接手时的交接 prompt 模板
如未来 Codex 或其他 Agent 接手某一章：
工作流上下文在: governance/workstreams/finbayes-arch-rewrite/
按以下顺序读取:
1. status.md（本文件，工作流状态）
2. 章节追踪表里你接手的章节对应的"阻塞 / 备注"列指向的 ADR
3. drafts/CHAP-XX-*.md（如果已有草稿）
战略上位事实源:
- projects/finbayes/strategic-whitepaper.md
- projects/finbayes/engineering/product-definition.md
接手任务: <具体任务，引用 CHAP-XX 编号>
完成后按"会话止 / 节点收尾协议"更新 status.md。