跳到主要内容

FinBayes Harness Workflow 与 Goal 执行规范（v1，部分已被吸收）

⚠️ 文档状态变更（2026-05-27）

本文档定义的”Harness Workflow + Milestone + Goal + Review Gate”四层执行模型，**已在 2026-05-27 经 28 章架构重写工作流（governance/workstreams/finbayes-arch-rewrite/）**整体规范化为下列事实源：

原段落替代位置
§1-2 执行模型 / Harness WorkflowADR-001 工程范式
§3 启动读取顺序architecture.md §1 文档角色与读者
§4 Milestone 切片architecture.md §25 与里程碑/任务的对应（M0-M7 八里程碑全景）
§5 Goal Task Packet 格式m0-walking-skeleton.md §12 + ADR-003 工程实施栈与协作
§6 第一阶段 Goal 清单（v1 编号 G0-G7）已废弃，由 architecture.md §25 的 M0-M7 里程碑清单替代；M0 实施清单由 OpenSpec task packet 起草时按新里程碑映射重写
§7-9 闭环 / 验收 / Review Gatearchitecture.md §26 审计点（三检 review gate 展开为机械/结构/样本/语义四类断言）
§10 中断续接规则governance/workstreams/finbayes-arch-rewrite/status.md 节点机制
§11 Definition of Donearchitecture.md §26 + m0-walking-skeleton.md §1 M0 验收

工程实施 Agent 应直接以 ADR + 新架构 + m0-walking-skeleton.md 为事实源，不依赖本文档的 v1 编号体系。本文档保留作历史参考。

0. 文档角色（v1，已废弃）​

本文定义 FinBayes 从知识治理文档进入代码仓 Coding 的实施方法。

当前工程化落地采用四层执行模型：

Harness workflow 作为外层执行框架，milestone 作为集成切片，Goal 作为可独立验证的交付单元，Review gate 作为成品一致性审计。

原因是 FinBayes 第一阶段是一组 runtime 重构和产品语义落地的组合工程。单个 Goal 可以确保某个功能完成；Harness workflow 把每个 Goal 放回同一条成品主线中验证，保证多个 Goal 拼起来后仍然是战略白皮书定义的”金融认知 runtime”。

1. 执行模型​

1.1 四层结构​

层级作用输出物
Harness workflow定义从文档到代码、从代码到评审、从评审到知识回写的完整闭环当前 milestone 的执行记录、验证结果、review 结论
Milestone把工程化落地切成可以集成验收的阶段可运行 runtime 能力、成品级演示路径、阶段门禁
Goal把 milestone 切成可由 Agent / 工程师独立执行的任务包代码、测试、fixtures、文档回写
Review gate检查结果是否仍然符合 FinBayes 产品预期成品一致性结论、缺口清单、下一步 Goal

Goal 是实施粒度，milestone 是集成管理粒度。Milestone 决定“这一波完成后系统应该像什么”，Goal 决定“这次具体改哪些文件、跑哪些测试”。

1.2 三类正向机制（active 事实源，承接 Build-Y 优先换轨）​

✅ 本节为 active 事实源（2026-05-29 复活）。 本文档其余 v1 内容已被 ADR + 新架构吸收，但本节定义的"三类正向机制"被 ADR-013 codify 哲学换轨 · Build-Y 优先 复活为有效口径，是里程碑工程包模板 §0.2「Build-Y 正向产出 / Delivery contract」引用的"正向交付契约"唯一定义点。

约束型 Goal 适合控制单点风险，例如凭证处理、内部 trace、样例硬编码。FinBayes 还需要管理组合质量：局部功能完成后，整体成品仍然要呈现为 FinBayes 的金融认知 runtime。

因此工程化落地以"正向产出优先"组织，需要三类正向机制：

机制解决的问题
交付契约说明这个切片完成后系统新增了什么可用能力（正向陈述"做成什么"，先于任何禁令）
实现约束说明为了让能力成立，代码必须遵守哪些结构和数据边界
验收信号说明如何证明局部实现已经进入正确的成品方向

约束服务于交付契约：约束仍然保留，但它们必须能回链到某条交付契约的可用能力，而不是成为文档叙事的中心。这与 ADR-013「Build-Y 应占 ≥ 60% / Prevent-X 仅 identity 级且 ≤ 10%」的换轨方向一致——里程碑工程包先回答"要做成什么"，再谈"不做什么"。

2. Harness Workflow​

每个 milestone 按以下 workflow 推进：

执行时遵守两条原则：

  1. 每个 Goal 都要能独立验证：即使 Web UI 尚未完成，也能通过 CLI、TUI、API contract、fixture 或 case runner 证明 runtime 行为。
  2. 每个 milestone 都要能组合验证：不能只看单测通过，还要看用户第一屏、状态沉淀、入口一致性和成品语义是否连起来。

3. 启动读取顺序​

每个 Goal 启动前按下列顺序读取：

  1. projects/finbayes/strategic-whitepaper.md
  2. projects/finbayes/engineering/product-definition.md
  3. 与 Goal 直接相关的 projects/finbayes/engineering/architecture.md 章节
  4. 如涉及第三方 baseline，则读取 projects/finbayes/engineering/baseline-evaluation.md
  5. 如涉及本地部署、TUI、CLI、MCP 或 Channel，则读取 projects/finbayes/engineering/local-runtime-and-entrypoints.md
  6. 如涉及 Session、上下文、Watchlist、Judgment Record 或长期状态，则读取 projects/finbayes/engineering/session-and-context-architecture.md
  7. 如涉及评估 case，则读取 commons/frameworks/evaluation/finbayes/case-library.md
  8. FinBayes 工程仓 AGENTS.md
  9. FinBayes 工程仓 README.md
  10. 当前 Goal 涉及的代码文件和测试

读取原则：知识治理库决定做什么，工程仓当前代码决定怎么改，Review gate 决定结果是否像 FinBayes。

4. Milestone 切片​

M0: Local Runtime Harness​

成品状态：用户在本地完成初始化、Provider readiness 检查，并通过 CLI / TUI 调用同一 FinBayes runtime。

主要 Goals：

  • G0-Local: Local Runtime and Provider Readiness
  • G0-Registry: Agent and Skill Registry Contract
  • G1-Web 的后端 contract 稳定骨架

Review gate：

  • finbayes doctor 能区分 ready、degraded、blocked、unsupported。
  • CLI / TUI 都走 runtime facade。
  • Provider secret 不进入用户输出、Session、Judgment Record 或 Profile。
  • Agent / Skill registry 能列出职责、权限、输入输出 schema、fallback 和 audit 字段。

M1: First-Screen Cognition Quality​

成品状态：用户输入真实金融问题后，runtime 能识别用户问题族，第一屏先回答题眼，并以“想清楚 / 看全面 / 看本质”的结构呈现判断材料。

主要 Goals：

  • G1: First-screen Answerability
  • G2: Case-family Templates Without Prompt Hardcoding

Review gate：

  • FinBayes Case Library 种子 case 的第一屏回答用户核心问题。
  • 结果包含反方、成立条件、失效条件、信息缺口和下一步观察点。
  • 每个高频 QuestionFamily 都能映射到主任务和辅助任务。
  • 回答能体现三层价值：想清楚问题、看全面证据、看透关键变量和条件。
  • paraphrase case 稳定通过，路由不依赖 exact prompt string map。

M2: Multi-Task Runtime and State Foundation​

成品状态：一个用户输入可以拆成 TaskGroup 并行执行；长期价值沉淀到 Session、Watchlist、Judgment Record 和 Profile，而不是留在普通聊天文本中。

主要 Goals：

  • G2-TaskGroup: Multi-task Orchestration and Streaming
  • G3: Judgment Record Domain Object
  • G3-Session: Session and Context Architecture
  • G4: Watchlist as Fin Object Registry

Review gate：

  • 主任务和辅助任务通过统一 projection 归并。
  • 某个辅助任务 degraded 时，主任务仍能输出有价值回答。
  • 用户可创建、切换、置顶、归档、删除 Session。
  • Judgment Record、Watchlist、Profile 通过 candidate confirmation 写入。

M3: Evidence Depth and Active Cognition​

成品状态：Crypto、US Stocks、Cross Market 不只是路由标签，而是有证据面、source 候选清单、降级口径和主动复盘信号的市场能力包。

主要 Goals：

  • G5: Market Pack Evidence Depth
  • G6: Active Cognition Signal
  • Web adapter 与 UI 团队集成验收

Review gate：

  • Market Pack 能产出 evidence plan，并记录 freshness、confidence、degraded reason。
  • 每个 Pack 的数据 source 候选清单进入 Data Source Registry，并能解释 source 选择和降级原因。
  • 主动信号说明触发了哪条历史判断、哪个条件、当前变化是什么、用户可如何复盘。
  • Web UI 通过 Web task adapter 消费 runtime contract，不复制任务识别、综合判断和状态写入逻辑。

5. Goal Task Packet 格式​

每个 Goal 都应写成一个独立 task packet，至少包含：

Goal: 一句话说明要交付的用户/工程价值
Milestone: 所属 milestone
Why now: 为什么这个 Goal 排在当前阶段
Product source: 对应产品定义章节
Architecture source: 对应架构章节
Delivery contract: 完成后系统新增什么可用能力
Implementation constraints: 为保证能力成立，代码必须遵守哪些结构约束
Code scope: 允许触碰的目录和文件
Acceptance signals: 可运行验收命令 + 人类可读验收标准
Regression: 必跑回归
State handoff: 中断续接时必须留下哪些证据

Implementation constraints 可以包含“排除项”，但必须服务于 Delivery contract。例如，“Web UI 不写 confirmed state”应写成“confirmed state 统一由 State API 在用户确认后写入，Web UI 提交 StateAction”。

6. 第一阶段 Goal 清单​

G0-Local: Local Runtime and Provider Readiness​

交付契约：FinBayes 能在本地完成初始化、Provider 配置检查、运行模式识别和基础 CLI / TUI smoke。

实现约束：

  • 本地配置加载、Provider registry、readiness check 和 CLI command surface 归入 runtime 入口体系。
  • Provider secret 只作为本机运行秘密处理。
  • CLI / TUI 通过 FinBayes runtime facade 调用认知能力。

验收信号：

  • readiness 能区分 ready、degraded、blocked、unsupported。
  • no-secret-output tests 覆盖模型 / 数据 Provider secret。
  • CLI / TUI smoke 证明没有走 legacy chat shortcut。

G0-Registry: Agent and Skill Registry Contract​

交付契约：FinBayes runtime 有自己的 Agent / Skill registry，能声明内部职责、可调用能力、权限、输入输出 schema、fallback 和 audit 字段。

实现约束：

  • Agent 类型至少覆盖 Router、Planner、Evidence、Synthesis、State、Projection。
  • Skill 类型至少覆盖 Market Skill、Data Adapter Skill、Extraction Skill、Synthesis Aid Skill、State Action Skill。
  • 所有 registry entry 必须声明 id、version、capability、market_scope、supported_question_families、supported_tasks、permission、fallback。
  • 用户可见输出不暴露内部 Agent / Skill 名称；debug / audit 层可以展示。

验收信号：

  • registry contract tests 能列出所有 entry 并验证 schema。
  • EvidencePlan 引用 Skill 时记录选择理由、source、freshness、confidence 和 degraded reason。
  • 新增 Skill 没有 permission、fallback 或 audit 字段时测试失败。

G1: First-screen Answerability​

交付契约：用户第一屏回答命中题眼，并以 FinBayes 的金融认知结构呈现判断材料，覆盖“想清楚 / 看全面 / 看本质”的最低要求。

实现约束：

  • 修改范围优先集中在 finclaw/cognition/projections.py、finclaw/cognition/renderers.py、finclaw/cognition/execution.py 和相关 tests。
  • 第一屏必须消费 QuestionFamilyMatch、主任务、证据缺口和 Synthesis 输出。
  • 内部 dispatch、prompt、provider raw error 进入 audit 或 debug 层，不进入用户第一屏。
  • provider unavailable 时生成受限状态认知快照。

验收信号：

  • FinBayes Case Library 当前种子集中每个 case 的第一屏回答用户核心问题。
  • 第一屏包含必要的反方、成立条件、失效条件、信息缺口或下一步观察点。
  • 至少覆盖概念理解、行情解释、追高 / 减仓困惑、资产比较、历史复盘、风险扫描六类问题族。
  • renderer / runtime tests 覆盖正常路径和 degraded path。

G1-Web: Web Adapter Contract Baseline​

交付契约：Web UI 在完成前即可基于稳定 runtime contract 开发和集成。

实现约束：

  • Web task adapter 提供创建任务、查询状态、接收事件流、取消任务的后端契约。
  • 最终结果包含 answer_projection、widgets、audit_summary、state_candidates。
  • Web UI 通过 StateAction 提交用户确认、编辑、拒绝、清空等动作。
  • tests/fixtures/agent_json_projection.v1.json 包含完整 schema 和 example payload，UI 团队按此并行实现。

验收信号：

  • API contract tests 覆盖 task request、task event、task result、state action。
  • UI 可仅凭 runtime projection 展示完整结果。
  • schema snapshot 能支持 Web UI 团队并行迭代。

G2: Case-family Templates Without Prompt Hardcoding​

交付契约：高频用户问题族有稳定输出形态，并能覆盖真实用户的改写表达。

问题族：

  • 概念理解
  • 行情解释
  • 追高 / 减仓困惑
  • 具体价位决策
  • 资产比较
  • 历史复盘
  • 风险扫描
  • 事件冲击
  • 组合视角
  • 持续跟踪

实现约束：

  • 问题族由 taxonomy、task features 和 output contract 支撑。
  • paraphrase case 与种子 case 使用同一任务语义。
  • deterministic contract path 与 analysis-mode path 都要有可测试入口。
  • 问题族输出结构承接产品定义的三层价值交付契约。

验收信号：

  • paraphrase case 通过。
  • 每个问题族至少有一个 deterministic contract path 和一个 analysis-mode path。
  • 每个问题族能说明默认主任务、辅助任务、必需认知要素和必需证据面。
  • routing tests 能证明实现基于特征，而不是基于样例字符串。

G2-TaskGroup: Multi-task Orchestration and Streaming​

交付契约：当一个用户输入命中多个金融认知任务时，runtime 能生成 TaskGroup，并支持并行执行、partial projection、失败隔离和最终归并。

实现约束：

  • TaskGroup 区分主任务、辅助任务、依赖关系、并发策略和取消策略。
  • partial projection 只输出用户可读进展、阶段性判断或降级说明。
  • 最终结果由统一 projection 合并。

验收信号：

  • 一个输入可以产生主任务和辅助任务。
  • independent tasks 可并行执行。
  • 某个辅助任务 degraded 时，主任务输出继续推进。
  • task event / projection tests 覆盖顺序、失败隔离和最终归并。

G3: Judgment Record Domain Object​

交付契约：历史判断成为可复盘、可引用、可更新的长期认知资产。

实现约束：

  • Judgment Record 从回答中以 candidate 形式生成。
  • 用户确认后持久化。
  • 后续市场变化、新问题和主动信号可引用历史 judgment。

验收信号：

  • creation candidate、confirmation、retrieval、update chain 都有测试。
  • 用户可删除或清空已确认 judgment。
  • 复盘类任务能引用历史判断的成立条件、失效条件和反方。

G3-Session: Session and Context Architecture​

交付契约：FinBayes 支持默认 Session、命名 Session、当前专注 Fin Object、ContextSnapshot 和长期认知资产引用。

实现约束：

  • Session 管理交互和上下文预算。
  • Watchlist、Judgment Record 和 Profile 作为长期资产通过 StateLink 被 Session 引用。
  • ContextSnapshot 保留金融语义锚点。

验收信号：

  • 用户可创建、切换、置顶、归档、删除 Session。
  • 用户可设置当前专注 Fin Object。
  • 达到上下文预算时生成 ContextSnapshot。
  • ContextSnapshot 保留成立条件、失效条件、反方证据、信息缺口和来源时间点。

G4: Watchlist as Fin Object Registry​

交付契约：Watchlist 从 ticker list 升级为 Fin Object registry。

对象类型：

  • asset
  • sector
  • theme
  • event
  • policy_or_macro_variable
  • actor
  • narrative
  • portfolio_or_compare_set

实现约束：

  • Watchlist candidate 与 confirmed state 分离。
  • WatchlistObject 可关联 Judgment Record、Session 和主动复盘节奏。
  • Fin Object 支持资产、主题、事件、叙事和组合。

验收信号：

  • AI 算力长期需求、稳定币监管、NVDA、BTC vs ETH 都能进入 watchlist candidate。
  • 主动信号可引用 Fin Object 和 Judgment Record 条件。

G5: Market Pack Evidence Depth​

交付契约：Crypto、US Stocks、Cross Market 能声明并执行市场语义证据要求。

实现约束：

  • Market Pack 产出 evidence plan。
  • Data Source Registry 负责选择本地数据、第三方 API 或 Data Horizon 输入。
  • 每个 Pack 声明第一阶段数据 source 候选清单和 source 优先级。
  • EvidencePacket 标注 source、freshness、confidence、status 和 degraded reason。

验收信号：

  • Crypto 覆盖价格、链上、协议 / 监管、叙事、流动性缺口。
  • US Stocks 覆盖财报、估值、行业、ETF / 宏观、价格技术缺口。
  • Cross Market 覆盖利率、美元、风险偏好、跨资产联动。
  • source candidate tests 验证每个 Pack 的数据源选择、fallback 和 freshness。
  • 缺失数据被标注为 degraded。

G6: Active Cognition Signal​

交付契约：主动提醒从价格 / 新闻提醒升级为“触发历史判断条件的复盘信号”。

实现约束：

  • 信号引用 Judgment Record、Fin Object、触发条件和当前变化。
  • Channel 输出是低噪音认知摘要和复盘入口。
  • 可审计调度存在时再声明已创建提醒。

验收信号：

  • 信号说明触发了哪条判断、哪个条件、当前变化是什么、建议怎么复盘。
  • Channel summary 可回链到 Session 或 Fin Object。
  • 主动信号 tests 覆盖真实调度和未创建调度两种路径。

7. Goal 工程闭环​

每个 Goal 的工程闭环：

  1. 读取产品定义和架构对应章节。
  2. 读取当前代码和现有 tests。
  3. 写失败测试、contract fixture 或补充评估 case。
  4. 实现满足交付契约的目标代码。
  5. 运行目标测试。
  6. 运行相关 FinBayes Case Library 子集。
  7. 涉及 Web 的 Goal 同步更新 contract fixture 或 projection snapshot。
  8. 记录结果到 docs/design/ 或 Goal handoff。
  9. 更新知识治理文档中被实现或被修正的假设。

8. 验收命令分层​

下表中的命令是目标验证面，不代表所有测试都已存在。每个 Goal task packet 必须明确三列：existing tests、tests to create、expected initially failing tests。

截至 2026-05-26 对当前 FinBayes 实现仓本地 checkout 的观察，测试现状如下。开工前以工程仓当前 git status 和 ls tests/ 重新核验。

验证面Existing tests / runnerTests to create or confirmExpected initially failing tests
快速静态.venv/bin/python -m compileall finclaw无，保持可运行即可不应失败；失败说明语法或导入层退化
local runtime readinesstests/test_finbayes_runtime_integration.py, tests/test_finbayes_phase1_product_contract.pytests/test_finbayes_local_runtime.py, tests/test_finbayes_provider_readiness.pyprovider readiness、config path、masked secret 的新契约测试
单元 / contracttests/test_finbayes_g1_contract.py, tests/test_finbayes_g2_contract.py, tests/test_finbayes_boundary_context.pycontract versioning、required/optional、错误码 fixture新增 schema version / source freshness 断言先失败
task orchestrationtests/test_finbayes_orchestrator.py, tests/test_finbayes_execution_dag.pytests/test_finbayes_taskgroup_streaming.py并行 TaskGroup、partial projection、失败任务静默降级的 contract 测试
session / context相关行为可能分散在 runtime / product contract 测试tests/test_finbayes_session_context.pyStateLink create/unlink/delete/orphan/merge conflict 生命周期测试
runtime / renderertests/test_finbayes_analysis_runtime.py, tests/test_finbayes_renderers.py, tests/test_finbayes_widget_projection.py, tests/test_finbayes_web_widget_events.pyprojection schema snapshotsource summary、freshness、gaps 在 projection 中的必含测试
evaluation casestests/test_finbayes_evaluation_cases.py, tests/test_finbayes_synthesis_budget.py新增或修订 case-library 覆盖缺口问题族、三层价值、first-screen 题眼质量相关 case 可先失败
FinBayes Case Library seed runnerscripts/run_finbayes_package_c_30case.py每个 Goal 的子集 runner 命令与 artifact 路径质量类 goal 可以先产生未达标报告，但 deterministic smoke 不应被误作 live quality
层级命令
快速静态.venv/bin/python -m compileall finclaw
local runtime.venv/bin/python -m pytest tests/test_finbayes_local_runtime.py tests/test_finbayes_provider_readiness.py
单元 / contract.venv/bin/python -m pytest tests/test_finbayes_g1_contract.py tests/test_finbayes_g2_contract.py
task orchestration.venv/bin/python -m pytest tests/test_finbayes_taskgroup_streaming.py
session / context.venv/bin/python -m pytest tests/test_finbayes_session_context.py
runtime / renderer.venv/bin/python -m pytest tests/test_finbayes_analysis_runtime.py tests/test_finbayes_renderers.py
evaluation cases.venv/bin/python -m pytest tests/test_finbayes_evaluation_cases.py
FinBayes Case Library seed runner.venv/bin/python scripts/run_finbayes_package_c_30case.py --mode deterministic-smoke
live qualityonly after preflight/provider readiness passes

如果 .venv 不存在，按工程仓 README.md 初始化。Live provider 失败应标注为 BLOCKED / degraded，并与 deterministic smoke 分开记录。

9. Review Gate​

每个 Goal 结束时必须回答三类问题。

成品语义：

  • 用户第一屏是否命中题眼？
  • 回答是否保留反方、成立条件、失效条件和信息缺口？
  • 回答是否体现“想清楚 / 看全面 / 看本质”的三层价值？
  • 输出是否体现“懂金融 / 懂用户 / 懂判断”，而不是通用金融泛答？
  • 结构化结果是否能沉淀为 Watchlist、Judgment Record、Profile 或 ContextSnapshot？

工程一致性：

  • CLI / TUI / Web / MCP 是否共享同一 runtime 和 projection contract？
  • Web UI 是否通过 runtime contract 与 StateAction 接入？
  • 一个输入命中多个任务时，是否通过 TaskGroup 编排和归并？
  • 问题族、任务类型和 TaskGroup 是否基于特征识别，而不是样例字符串？
  • Agent / Skill registry 是否声明 schema、权限、fallback 和 audit 字段？
  • Market Pack 是否声明 source 候选清单，并把 source 选择和降级原因写入 EvidencePacket？
  • Session 是否支持多会话、上下文预算和长期资产引用？

治理与可续接性：

  • 交易、账户、凭证和自动执行请求是否进入认知与执行分工处理链？
  • 模型 / 数据 Provider secret 是否留在本地运行配置中？
  • 是否有中断续接所需的 artifact？
  • 相关知识治理文档是否已回写。

10. 中断续接规则​

如果 Goal 中断，必须留下：

  • 已改文件列表
  • 已运行命令和结果
  • 未通过测试 / BLOCKED 原因
  • 下一步交付动作
  • 是否涉及用户未提交改动

恢复时从当前 git status、当前 docs、当前 tests 重新读，不从旧记忆直接继续。

11. Definition of Done​

一个 Goal 完成必须同时满足：

  1. 代码实现或文档交付存在于正确仓库。
  2. 目标测试已运行并记录结果。
  3. Delivery contract 中的能力可以通过 CLI、TUI、API contract、fixture 或 case runner 观察到。
  4. Review gate 没有发现成品语义偏离。
  5. 用户第一屏质量有可读样例或评估证据。
  6. 相关知识治理文档已同步。
  7. 只读第三方仓保持只读。

如果只有局部测试通过，但第一屏仍像内部流程或多个 Goal 组合后不像 FinBayes 金融认知 runtime，当前 milestone 不算完成。