跳到主要内容

Round-2 Review A — 实施团队可读性 + 跨层一致性

Sub-agent (researcher) 在主会话外的独立 review，于 2026-05-27 round-2 完成。原文未删改。

实施新人 mental model 建立速度评估​

按"白皮书 → 产品定义 → 架构"路径读下来，整体可在 4 小时内建起足以开工 M0 的 mental model，但其中分布严重不均：

  • 白皮书 v2 (447 行)：1 小时内完成，语言流畅、修辞克制，§7、§8、§14、§15 已经把"任务清单 / 生态分工 / 凭证边界 / 商业未决"四个工程关键锚点说清楚。新人能形成"FinBayes 是认知层，不下单，不收凭证，第一阶段做 Crypto+US Stocks，核心用户 L1-L3"的完整图像。
  • 产品定义 (540 行)：45 分钟可读完。§3 五对象 + §4 七任务 + §7 输出形态 + §9 多入口 是骨干，可读性最好。§10.3 / §10.4 把两类凭证拆开是亮点（战略层只有一句"凭证不收"被这里展开为可工程承接）。
  • 架构 (6483 行)：这里成为时间杀手。新人不可能在 2 小时内通读 28 章。但文档显式标注了"按需查阅"(§1)、§25 给出"M0 覆盖哪些章"清单、§28 把"M0 实施所需的字段级 schema / DDL / CLI / fixture / CI"集中在一个附录。遵循 §1 + §25 + §28 + §27 这条精读路径（约 1500 行），2 小时内可建起足以开工的局部 mental model。其他章节（§10-§24）留作查阅。

路径平滑度：从白皮书"为什么"到产品定义"是什么"到架构"怎么做"的过渡总体平滑，但有两个跳跃点：

  1. 白皮书 §7 说"七类任务"→ 产品定义 §4.2 把七类任务定义清楚 → 但首次出现 6 子系统这个概念是在产品定义 §1（一句话引述指向架构 §9），没有"为什么是 6 个"的过渡。新人会问"7 任务 vs 6 子系统"，需要架构 §9 才解释清楚（任务是用户视角，子系统是工程视角）。
  2. 产品定义 §3 描述 5 对象（Fin Object / Watchlist / Session / Judgment Record / Dynamic Profile），架构 §4 升级为 7 个 first-class 对象（加 Task / StructuredCognitionResult），§11 又只列 6 个独立状态机（再加 TaskGroup，但不含 Dynamic Profile / Watchlist / Fin Object 的状态机）。对象数量在三处变化（5 → 7 → 6），会让新人产生 schema 模糊感 —— 架构 §11 开篇注释做了说明，但容易被略读。

5 个抽查问题答复​

Q1: "我看到产品定义说 7 类任务，架构文档说 6 子系统——这俩有什么关系？"​

文档能直接答。架构 §9 开篇明确："任务类型本体在这里作为事后标签用于审计，不作前置路由" —— 意味着 7 类任务是业务/用户视角的输出语义，6 子系统是Core Runtime 的工程结构，正交关系。Task Orchestration 子系统通过 LLM Function Calling 识别任务，事后用 7 类本体打标签写审计 trail。但白皮书 / 产品定义没有显式说明这个正交关系，只靠架构 §9 + §4 + ADR-004 倾向才能拼出来。建议在产品定义 §1 那一句"6 子系统"旁加一句"7 任务是输出语义、6 子系统是 runtime 结构，两者正交"。

Q2: "凭证不变量在每层都说，是不是太啰嗦？"​

不啰嗦，反而是设计上的强项。三层做了职责分工而非重复：

  • 白皮书 §14：边界声明（不收/不存/不训练 + 本机 Provider 配置例外）
  • 产品定义 §10.3 / §10.4：产品级区分（金融执行凭证 vs 本机配置秘密的语义差异）
  • 架构 §2 / §17 / §28：工程级承接（输入 hook + 输出过滤 + State/Cache/审计 trail 全链路阻断 + 5 类 negative test fixture + CI grep）

新人读完会明白：这不是同一句话写三遍，而是 strategic claim → product contract → engineering implementation 的标准三层。

Q3: "Session 删除时 Judgment Record 会不会被删？"​

两处口径完全一致，且互为指针。产品定义 §3.3 显式说："删除或归档 Session 时，已确认长期认知资产默认保留（不级联删除）；用户若需同步删除必须二次确认并按资产逐项列出影响范围（工程承接详见架构文档 §11 Session 生命周期）。" 架构 §11.1 关键约束："删除 Session 不删除它引用的 Judgment Record / Watchlist 对象（这些是独立资产）"，§11 末尾"生命周期独立性"段重申一次。这是跨层一致性的标杆案例 —— 产品定义留指针，架构落实细节，无矛盾。

Q4: "战略白皮书说有 7 类任务，架构 §4 也说 7 类，§9 说有 clarify 工具 —— clarify 算第 8 类吗？"​

文档能答，但要绕一圈。架构 §9.2 把 clarify 定义为"工具（Tool）"，且"强制串行阻塞，澄清后回到 orchestrate 起点"，同时 Capability Registry §9.5 把工具池描述为"7 类任务工具 + clarify + 状态操作工具" —— clarify 是任务编排工具，不是用户认知任务类型。架构 §28 M0 接口子集表里 clarify 是 M0 stub（M2 才上线）。但白皮书 §7 末尾和产品定义 §4.3 都把"clarify"称作"澄清路径"而非"工具"，措辞不统一。新人可能要看完架构 §9.2 才彻底明白。建议产品定义 §4.3 显式标注"clarify 是任务编排工具，不是第 8 类用户认知任务"。

Q5: "M0 我具体要写哪些代码？文档能让我直接开工还是要追问很多问题？"​

能直接开工。架构 §28 是这次重写的亮点附录：

  • §28.1 列了 6 子系统 ×（implement / stub / skip）矩阵，18 个 implement + 11 个 stub = 29 个签名固定的接口
  • §28.2 给了 5 个 Pydantic 模型完整代码（types.py 全文）
  • §28.3 给了 4 张 SQLite DDL 完整代码（migrations/001_initial.sql）
  • §28.4 给了 5 个 CLI 命令规格 + 退出码表
  • §28.5 给了 Mock Provider fixture 目录结构 + hash 算法
  • §28.6 给了 5 条样例输入 yaml
  • §28.7 给了 5 类凭证 negative test yaml
  • §28.10 给了三检 CI 模板

新人能直接 git clone 工程仓 + 按 §27 路径建目录 + 复制 §28 代码片段开工。无重大模糊点。唯一需要补的是 OS Keychain 接入细节（§15 给了平台清单，未给具体调用），但这是 M1+ 范围。

跨层一致性 7 项核查​

任务类型清单​

完全一致。三层都用"解释 / 分析 / 比较 / 复盘 / 风险识别 / 交易准备 / 交易决策辅助"7 项，措辞统一。白皮书 §7 末尾 + 产品定义 §4.2 表头 + 架构 §2 / §4 / §9 多处呼应。架构 §2 明示"本文不增不减不改名"，§23 在拒绝概念表里列出已禁词"行动准备 / 行动判断 / 行动方案"作为反向锁定。这条核查通过。

业务对象​

结构上一致，数量上需要新人花心思 reconcile。

  • 产品定义 §3：5 类核心对象（Fin Object / Watchlist / Session / Judgment Record / Dynamic Profile）
  • 架构 §4：7 个 first-class 对象（上述 5 个 + Task + StructuredCognitionResult）
  • 架构 §11：6 个独立状态机对象（Session / Task / TaskGroup / Judgment Record / StateCandidate / Provider Readiness）
  • 架构 §15：8 张 SQLite 业务表（sessions / watchlist_objects / judgment_records / dynamic_profiles / state_candidates / fin_objects / audit_trail / context_snapshots）
  • 架构 §27：7 个 Pydantic 模型路径（对应 §4）
  • 架构 §28：M0 阶段 4 张表 + 5 个 Pydantic 模型（简化）

架构 §11 开篇做了"first-class 业务对象 vs 有独立状态机的对象"的明确说明，§11.5 / §15 mermaid 图都有注释。但新人读架构 §4 → §11 → §15 时数字变化频繁（5 / 7 / 6 / 8 / 7 / 4），需要架构 §11 开篇那段注释化解。如果略读容易迷惑。P1 改进：建议产品定义 §3 末尾加一行"工程层会派生出 Task / StructuredCognitionResult / StateCandidate / TaskGroup 等工程对象，详见架构 §4 / §11"。

凭证不变量​

完全一致且分层承接清晰。三层职责分工：

  • 白皮书 §14：边界声明 + 区分本机 Provider 配置
  • 产品定义 §10.3 / §10.4：产品级区分（金融执行 vs 本机配置）、提示工程层端到端阻断
  • 架构 §2：工程承接（不收/不存/不训练机械三承接）
  • 架构 §17：端到端阻断图 + 凭证类型识别策略表
  • 架构 §28.7：5 类凭证 negative test fixture

逐字检查：白皮书 §14 原句"金融执行凭证——私钥、助记词、钱包恢复短语、交易所登录凭证、交易所 API key、经纪商 API key、银行账户、信用卡等——FinBayes 一律不收、不存、不训练"在产品定义 §10.3 完整引用、架构 §2 完整引用，未发生措辞漂移。架构 §2 末尾还设置了 grep 级核查作为变更评审必要条件。这条核查为标杆通过。

多入口契约​

一致。CLI / TUI / Web / MCP / Channel 5 个入口在产品定义 §9、架构 §7 / §8 / §14 / §16 / §27 都按相同顺序列出。

  • 产品定义 §9：产品行为契约（各入口范围、共享 runtime contract、Provider 配置）
  • 架构 §8：容器图 + 5 个 Adapter 同进程
  • 架构 §14：部署形态对各入口的影响
  • 架构 §16：每个入口的通信协议
  • 架构 §27：src/finbayes/io/entries/ 下 5 个子目录

唯一小不一致：产品定义 §9 把 MCP 描述为"后续兼容入口"，架构 §28 M0 接口子集表里 Web / TUI / MCP / Channel 都是 M0 stub / skip，但白皮书没有提及多入口具体顺序。P2 优化：可以在产品定义 §9 表格加一列"M0 / M1+ 的入口优先级"指向架构 §25 里程碑表。

认知/执行分工​

一致。

  • 白皮书 §8：生态分工"FinBayes 不直接下单，也不持有账户凭证"
  • 产品定义 §11.1：同句引用 + 强调用户决策权 + 指向 AI Trading Matrix
  • 架构 §2：同句引用 + 工程承接"工具注册表对执行类工具的注册请求一律拒收"
  • 架构 §17：执行类工具的注册拒绝清单 + 拒绝机制图

逐字一致，工程承接到位。架构 §17 / §9.5 把"不下单"具体落到 Capability Registry 的注册时拒收（注册期而非运行期拦截），逻辑清晰。这条核查通过。

画像主权​

一致。

  • 白皮书 §14：用户始终保有"查看、修改、清空"完整控制权
  • 产品定义 §10.1：同三动作 + 清空时显式提示"协作上下文已重置"
  • 架构 §2：用户主权简短承接
  • 架构 §9.4：State Management 子系统接口 view_profile / modify_profile / clear_profile
  • 架构 §13：用户主权不变量
  • 架构 §15：finbayes profile view / modify / clear 用户命令
  • 架构 §17：用户主权 5 维度（知情 / 修改 / 清空 / 卸载 / 可移植）

架构 §17 把白皮书的"3 个动作"扩展到"5 维度"（加卸载权 + 可移植）是一个工程层增量，符合工程比产品定义更细的预期。无矛盾。

未决问题​

一致且层次清晰。

  • 白皮书 §15：战略未决 4 项（更多市场普适性 / 个人 vs 机构分立 / 商业模式压力测试 / L1-L3 商业强度）
  • 白皮书 §15 末尾：工程承接原则 + 5 类工程观测字段
  • 架构 §22 第一阶段缺口：三类缺口（战略待定 / 工程延后 / 场景外），"战略待定"段直接呼应白皮书 §15
  • 架构 §22 + §23：待写 ADR 7 个（ADR-004 至 ADR-010）
  • 架构 §23：已 accepted 3 个 ADR (001/002/003)

架构 §22 明示**"工程层不替战略层做决策"**，触发条件成立时回到 governance/change-protocol.md。这条核查通过。

实施新人信心打分（1-5）​

问题打分理由
我知道 FinBayes 是什么5白皮书 §1 + §4 + §8 三处呼应，定义稳定
我知道 M0 要做什么5架构 §25 范围表 + §28 工程包附录覆盖完整，无模糊
我知道每个子系统在哪里实现5架构 §27 7 张映射表精确，每个子系统都有路径
我知道如何写第一个 Pydantic 模型 + 第一行 SQL5§28.2 给了 5 个 Pydantic 模型完整代码，§28.3 给了 DDL 完整代码，直接复制即可
我知道怎么验收 M04§28.8 自动判定规则完整，人工 5 条 checklist 也给出，但"实质反方 / 形式反方"的判定标准还有些主观，需要 reviewer 校准
我知道怎么调用 LLM Provider4§9.6 Provider Adapter 描述 4 层降级，§28.1 表说 M0 只实现 L1 用户 Provider，LLMResponse 模型也给出。但统一 OpenAI-compatible 抽象还在 ADR-008（待写），具体 LLM 调用代码模板未给出
我知道边界拒收凭证应该怎么实现5§17 端到端阻断图 + §28.7 5 类 negative fixture + §28.10 CI grep + 凭证识别策略表，实现路径清楚
我知道审计 trail 怎么落5§15 audit_trail 表 + §28.2 AuditEvent Pydantic + §28.3 audit_events DDL + §17 边界事件字段表，全部齐备

平均 4.75 / 5 —— 新人确实可以开工 M0，且对验收标准有信心。

P0 阻断（新人无法理解 / 三层口径冲突）​

无 P0。在三层关键不变量（凭证 / 不下单 / 画像主权 / 任务类型清单）上均保持原句一致；架构 §28 把 M0 工程包具体化到可复制代码的颗粒度，实施新人不会因为"读不懂"而停滞。

P1 改进（新人会感到模糊 / 三层口径勉强一致）​

  1. 对象数量在三层间从 5 到 7 到 6 到 8 变化，产品定义未显式预告这种工程层 derive。建议在产品定义 §3 末尾或 §1 增加一句"工程层会派生 Task / StructuredCognitionResult / StateCandidate / TaskGroup 等工程对象，详见架构 §4 / §11"，降低新人迷惑。
  2. 6 子系统 vs 7 任务的正交关系未在产品定义级别澄清。产品定义 §1 那一句"6 子系统"过短，新人容易混淆"7 任务 = 7 子系统"。建议在产品定义 §1 加一句"7 任务是用户视角的输出语义，6 子系统是 runtime 工程结构，两者正交"。
  3. clarify 在白皮书 / 产品定义被称作"澄清路径"，在架构被称作"工具(Tool)且 M0 stub"。产品定义 §4.3 应显式说明"clarify 是任务编排工具不是第 8 类用户认知任务"以避免歧义。
  4. 架构 §28.5 "Provider API 变化检测" 提到 nightly 真档跑 5 条样例对比 fixture diff 阈值，但具体阈值在哪个文件配置 / 谁监控未明示。M0 实施时这块需要工作流维护者补充。

P2 优化（可读性已 OK 但有更好表达）​

  1. 多入口契约在产品定义 §9 可补充 M0 / M1+ 入口优先级一列指向架构 §25，让新人不读 §25 也能看到入口的实施节奏（CLI in M0，TUI/Web in M3，Channel in M5）。
  2. 架构 §22 缺口表与白皮书 §15 表共用工程观测字段（market_pack / provider_type / 等）未在两处显式对照。可考虑在架构 §22 加一行 "对应白皮书 §15 表的工程观测字段已落在 §28 AuditEvent.payload 等结构里"。
  3. 架构 §11 开篇"first-class 业务对象 vs 有独立状态机的对象"的注释非常重要但容易被略读。可考虑把这段提升为带 callout 框的显眼说明，或在 §4 末尾就预告"§11 只挑出有独立状态机的对象做生命周期"。
  4. 产品定义 §3.5 动态画像段把 4 种字段集合（认知偏好 / 风险偏好 / 表达偏好 / 关注密度）简单列出，但架构 §4 动态画像段列出 5 类字段（风险偏好 / 关注模式 / 市场标的范围 / 任务类型偏好 / 表达密度偏好）。两边不一致但都是开放列表（"but not limited to"），P2 级别。

一句话总结：FinBayes 三层文档对实施新人友好度​

FinBayes 三层文档对实施新人整体友好：战略层稳定、产品层提供清晰行为契约、架构层提供 §28 M0 工程包附录这种"开箱即开工"级别的工程材料，跨层口径在七项关键不变量上保持一致，实施新人在 4 小时内可建立足以启动 M0 的 mental model，信心打分平均 4.75/5；主要可改进点集中在"对象数量在三层间 5→7→6→8 的变化未在产品定义层预告"、"7 任务 vs 6 子系统的正交关系未在产品定义级别澄清"和"clarify 在三层措辞不统一"三个 P1 级表达问题，无 P0 阻断。