跳到主要内容

FinBayes 工程化文档层重置

0. 提案历史​

本提案经历四次方向变更，每次由维护者澄清后修正：

  1. v1（已废）：把 product-cognition-output-contract.md 当下游契约权威，主张其他文档回写对齐 —— 方向错误（output-contract 是旧白皮书改名而来的 drift 源）
  2. v2（已废）：以 v2 战略白皮书矫正 output-contract，拆解可保留体验细节合并回 product-definition.md，对 product-definition.md 与 baseline-transformation-design.md 做术语替换 —— 方向正确但范围误判（product-definition / baseline-design 也是 pre-v2 遗留，合并/替换没意义）
  3. v3（已废）：把所有 pre-v2 工程化文档标 legacy 或归档，在 projects/finbayes/engineering/ 建立 v2 基础上的全新工程化文档层，遗留文档留在原位标 legacy —— 方向正确但维护者反馈遗留文档应集中到子目录，避免干扰 v2 工程化任务，并便于部分团队成员继续参考使用
  4. v4（本版）：在 v3 基础上，把 6 份 pre-v2 遗留文档统一迁入 projects/finbayes/legacy/ 子目录，并新写 projects/finbayes/README.md 作为 v2 landing 页

复用同一 proposal_id 保留迭代轨迹，本版生效。

1. 目标​

把 FinBayes 工程化文档层完全重置到 v2 战略白皮书基础上：

  • 6 份 pre-v2 遗留文档统一迁入 projects/finbayes/legacy/ 子目录（标 status: legacy，作为参考输入；与 v2 工程化任务隔离，但仍可被团队成员参考）
  • 两份完全过时的文档归档（product-cognition-output-contract.md + baseline-transformation-design.md）到 _archive/
  • 在 projects/finbayes/engineering/ 建立新工程化文档层
  • 新写 projects/finbayes/README.md 作为 v2 landing 页，指向 engineering/ 与 legacy/
  • 本轮交付：engineering/README.md + engineering/product-definition.md + legacy/ 子目录建立 + 新 landing
  • 其余三份 engineering 文档（architecture / baseline-evaluation / goal-execution）另开轮次

2. 影响范围​

路径动作
projects/finbayes/legacy/新建子目录
6 份 pre-v2 文档（README / product-definition / 3 份 goal-* / AGENT_INPUT_NARROWING）git mv 到 projects/finbayes/legacy/，frontmatter 加 status: legacy，文首加引导段，内部相对路径与明文路径修复
projects/finbayes/README.md重写为 v2 landing 页，指向 engineering/ 与 legacy/
projects/finbayes/product-cognition-output-contract.md归档到 _archive/projects/finbayes/2026-05-26-output-contract-rewrite/
projects/finbayes/baseline-transformation-design.md归档到 _archive/projects/finbayes/2026-05-26-pre-v2-baseline-design/
projects/finbayes/engineering/新建目录
projects/finbayes/engineering/README.md新建，目录引导 + 五份文档计划 + 与父目录关系图
projects/finbayes/engineering/product-definition.md新建，基于 v2 的产品定义（章节大纲见 §7）
各归档目录的 README.md新建，说明归档原因与可参考片段定位
sidebars.js更新 HIDDEN_SIDEBAR_DOC_IDS 中的 goal-execution-plan / goal-recovery-handoff 路径前缀

不动：strategic-whitepaper.md（v2 基线本身）。

3. 变更级别​

L1（项目级内容更新）。仅触及 projects/finbayes/ 与对应归档路径，未触及 ecosystem/、commons/、governance/。按 change-protocol §1，需 1 人 review + approval。

4. 证据​

  • v2 战略白皮书（projects/finbayes/strategic-whitepaper.md）日期 2026-05-25 v2-implementation-polish
  • 旧工程化文档批次：2026-05-24 那批（README / product-definition / baseline-transformation-design / goal-execution-plan / goal-recovery-handoff）+ 2026-05-25 的 AGENT_INPUT_NARROWING + goal-compact-context，维护者明确确认为 pre-v2 旧工程化版本产物
  • product-cognition-output-contract.md 自标 v1-renamed-from-strategic-whitepaper，内含被 v2 否决的概念（11 条契约 / 双模式 / 协作伙伴 / L3 四承诺 等）

5. 架构动作​

5.1 pre-v2 遗留文档迁入 legacy/ 子目录（6 份）​

对下列文件做以下编辑：

  1. git mv 从 projects/finbayes/ 迁入 projects/finbayes/legacy/
  2. frontmatter 加 status: legacy
  3. 文首加 legacy 引导段
  4. 修复因深度变化造成的相对路径（./engineering/ → ../engineering/、../../_archive/ → ../../../_archive/ 等）
  5. 修复明文路径引用（projects/finbayes/X.md → projects/finbayes/legacy/X.md）
文件源路径目标路径
README.mdprojects/finbayes/README.mdprojects/finbayes/legacy/README.md
product-definition.mdprojects/finbayes/product-definition.mdprojects/finbayes/legacy/product-definition.md
goal-execution-plan.mdprojects/finbayes/goal-execution-plan.mdprojects/finbayes/legacy/goal-execution-plan.md
goal-recovery-handoff.mdprojects/finbayes/goal-recovery-handoff.mdprojects/finbayes/legacy/goal-recovery-handoff.md
goal-compact-context.mdprojects/finbayes/goal-compact-context.mdprojects/finbayes/legacy/goal-compact-context.md
AGENT_INPUT_NARROWING.mdprojects/finbayes/AGENT_INPUT_NARROWING.mdprojects/finbayes/legacy/AGENT_INPUT_NARROWING.md

legacy 引导段统一模板：

> **【pre-v2 遗留】** 本文是 v2 战略白皮书前的旧工程化版本产物，不作为 v2 工程化落地的事实源。v2 基础上的工程化文档在 `projects/finbayes/engineering/` 子目录。本文保留作为参考输入，不再维护。

5.2 归档动作（2 份）​

源目标
projects/finbayes/product-cognition-output-contract.md_archive/projects/finbayes/2026-05-26-output-contract-rewrite/product-cognition-output-contract.md
projects/finbayes/baseline-transformation-design.md_archive/projects/finbayes/2026-05-26-pre-v2-baseline-design/baseline-transformation-design.md

各归档目录配套 README.md 说明归档原因 + 可参考片段定位（如 output-contract §6.1 黄金路径 / §12 用户画像 等可作为 engineering/product-definition.md 写作时的体验细节参考）。

5.3 跨文档链接清理​

执行 5.1 与 5.2 后扫描 projects/finbayes/ 下所有 markdown 链接：

  • 指向被归档文件的链接：改为指向 _archive/... 或删除
  • 指向被标 legacy 文件的链接：保留但确认链接显示文本不要暗示其为权威源

5.4 新建 engineering/ 目录 + README​

创建 projects/finbayes/engineering/README.md，内容大纲见 §6。

6. engineering/README.md 内容大纲​

---
title: FinBayes 工程化文档
status: active
last-updated: 2026-05-26
scope: project/finbayes/engineering
maturity: draft
---

正文章节：

  1. 本目录是什么：基于 v2 战略白皮书的工程化落地文档集；服务于实施 Agent / 人类工程师能正确完整实现 FinBayes
  2. 与父目录的关系：父目录 strategic-whitepaper.md 是唯一上位事实源；其他父目录文件是 pre-v2 遗留参考
  3. 文档清单（五份）：
    • product-definition.md —— 产品定义（行为级契约：用户问→系统应输出什么）
    • architecture.md —— 系统架构（跨模块决策：拓扑 / 接口契约 / 数据模型）
    • baseline-evaluation.md —— martinpmm/Finclaw 对 v2 的契合度评估（替代旧 baseline-transformation-design.md）
    • goal-execution.md —— Goal 执行规范（替代旧三份 goal-*.md；是否合并为一份或保留多份在该提案决定）
    • README.md —— 本文
  4. 阅读顺序：strategic-whitepaper（父目录）→ product-definition → architecture → baseline-evaluation → goal-execution
  5. 文档关系图（mermaid）：strategic → product-definition + architecture；product-definition + architecture → baseline-evaluation；以上四份 → goal-execution
  6. 当前状态：仅 README + product-definition 已起草；其余三份后续轮次

7. engineering/product-definition.md 起草大纲​

7.1 文档角色​

回答"FinBayes 在用户行为级面前应该是什么样"。不回答"为什么是这样"（那是 strategic-whitepaper 的事）、"代码怎么拆"（那是 architecture 的事）、"什么时候做完"（那是 goal-execution 的事）。

7.2 frontmatter​

---
title: FinBayes 产品定义
status: active
last-updated: 2026-05-26
scope: project/finbayes/engineering
maturity: draft
upstream: ../strategic-whitepaper.md (v2)
---

7.3 章节大纲​

§章节内容要点
1文档角色与上位继承上游 v2；下游 architecture；不重复战略论证
2第一阶段范围Crypto + US Stocks，ETF/宏观支撑层；L1-L3 核心用户；不做 L0 商业押注、不做 L4
3核心对象Fin Object（用户关注的金融对象：标的/板块/事件/主题/政策/Actor/组合）/ Watchlist（组织 Fin Object 的机制）/ Session / Judgment Record / 动态用户画像
4用户认知任务体系任务类型：解释 / 分析 / 比较 / 复盘 / 风险识别 / 交易准备 / 交易决策；自然语言入口如何映射到任务类型
5输出形态按任务类型动态组织的认知要素（多视角 / 反方 / 成立条件 / 失效条件 / 不确定性 / 可复盘 / 依据）；不固化字段表；不同任务类型对应不同输出形态
6体验主线黄金路径（用户问题 → 任务识别 → 信息组织 → 条件化判断 → 复盘记录 → 后续触发）；主动信号机制
7多入口契约Web / TUI / CLI / MCP / Channel 共享同一 runtime 与同一输出质量；表达密度可调，判断质量不调
8用户画像与敏感信息静默构建 / 透明可调 / 不裁剪事实空间 / 凭证类信息一律不收 —— 直接承接 v2 §14，不引入 L3 四承诺
9边界与不变量不下单 / 不调仓 / 不持账户凭证 / 不触发自动交易；用户决策权与执行权恒定
10第一阶段成功口径行为级可观测信号（不是商业指标 —— 商业指标按 v2 §15 在战略层未决）

7.4 输入源（按优先级）​

  1. 唯一权威：projects/finbayes/strategic-whitepaper.md (v2)
  2. 可选参考（在 v2 未覆盖到的产品体验细节上）：
    • _archive/projects/finbayes/2026-05-26-output-contract-rewrite/product-cognition-output-contract.md §4.2 / §5.1 / §5.4 / §6.1-6.6 / §12 等体验层片段
    • projects/finbayes/product-definition.md（pre-v2 遗留）的可继承产品判断
  3. 禁止引入：已被 v2 否决的概念
    • "11 条字段级强约束" / "字段级输出契约"
    • "默认 / 行动准备双模式"
    • "认知协作伙伴"作为关系定义（v2 用"AI 金融助手 + 认知层"）
    • "L3 四承诺"
    • "零状态前提"
    • "情绪桥" / "信任债承诺"作为升格术语（v2 §13 仅用"温和承接情绪化时刻"）
  4. 术语规范：
    • "交易准备" / "交易决策" / "交易行动"（不用"行动准备" / "行动判断"）
    • "Fin Object" + "Watchlist"（已在维护者内部对齐，不冲突）
    • "认知任务" / "结构化认知结果"（保留）

7.5 验收口径​

文档草稿完成后，按以下问题验收（每问应能直接从文中找到答案）：

  • 用户问"BTC 现在还能追吗"，FinBayes 应识别为什么任务类型？默认输出含哪些认知要素？什么条件下才进入交易准备形态？
  • 同一用户问题在 Web / TUI / CLI 三个入口的输出在哪一层一致、在哪一层允许不同？
  • Fin Object 与 Watchlist 各自承担什么？用户加 Watchlist 时数据上发生了什么？
  • 第一阶段什么场景不做？文档边界与不变量是否覆盖了 v2 §8 的所有边界？
  • 用户画像在什么时刻被读取 / 修改 / 清空？凭证类信息在什么场景下系统会拒绝接收？

不能从文中直接回答的问题，要么是文档遗漏，要么应明确标"由 architecture.md 承接"或"由 goal-execution 承接"。

7.6 长度上限​

不超过 600 行。超出说明在引入产品定义之外的内容（架构 / 工程 / 战略论证）。

8. 不在本轮范围​

动作何时做
engineering/architecture.md 起草本提案 approve 后另开轮
engineering/baseline-evaluation.md 起草（重新评估 martinpmm/Finclaw 对 v2 的契合度，不参考旧 baseline-transformation-design.md）本提案 approve 后另开轮，建议依赖 architecture.md 完成度
engineering/goal-execution.md 起草（是否合并为一份或保留三份分文件，提案中决定）本提案 approve 后另开轮
ecosystem/glossary.md 是否新增 Fin Object / Watchlist 条目另开 L3 提案
FinClaw → FinBayes 改名收尾CLAUDE.md 已记录在进行中，与本提案独立推进
FinBayes 工程仓的代码改造本知识库内文档完成后启动；本提案不涉及代码

9. 执行顺序​

approve 后按以下顺序执行：

  1. 第一步：归档与遗留标记

    • 创建 _archive/projects/finbayes/2026-05-26-output-contract-rewrite/ + 归档 product-cognition-output-contract.md + 写归档 README
    • 创建 _archive/projects/finbayes/2026-05-26-pre-v2-baseline-design/ + 归档 baseline-transformation-design.md + 写归档 README
    • 对 6 份遗留文件加 status: legacy frontmatter + 文首引导段
    • 清理父目录跨文档链接（指向被归档/被标 legacy 文件的链接）

  2. 第二步：建立 engineering/ 目录

    • 创建 projects/finbayes/engineering/
    • 写 engineering/README.md（按 §6 大纲）

  3. 第三步：起草 engineering/product-definition.md

    • 按 §7 大纲与验收口径起草
    • 完成后跑 npm run verify:kb 确认无破坏

  4. 第四步：提案归档

    • 本提案移入 governance/proposals/accepted/2026/
    • 在 accepted 副本 frontmatter 加 status: accepted + 接受日期

10. 评审请求​

请 FinBayes Controller 审议六项：

  • §5.1 遗留标记清单：6 份 pre-v2 文档加 status: legacy
  • §5.2 归档清单：output-contract.md + baseline-transformation-design.md 双归档
  • §5.3 链接清理：跨文档引用更新
  • §6 engineering/README.md 大纲：是否符合预期
  • §7 engineering/product-definition.md 章节大纲与禁止引入清单：是否完整覆盖 v2 应该承接到产品层的内容
  • §8 不在本轮范围声明：是否同意其余三份 engineering/ 文档另开轮，本轮先稳住产品定义

评审反馈方式：在同目录追加 2026-05-26--finbayes-contract-alignment-after-whitepaper-v2.review.md（按 change-protocol §6.2），或在本会话直接回复 approve / 改动建议。

approve 后由提案作者按 §9 顺序执行，并将本提案移入 governance/proposals/accepted/2026/。