FinClaw V1 Engineering Kickoff Decisions
状态：Accepted / V1 工程化启动前的硬性决策固化 日期：2026-05-16 项目：FinClaw 文档级别：项目级决策记录 上游文档：v1-execution-plan-and-milestones.md、v1-governance-engineering-alignment.md、mvp-product-definition.md
1. Purpose
本文件固化 V1 工程化启动之前必须确定的产品 / 治理 / 战略决策。它是 P-B 工程实施进入之前的 anchor：任何后续设计、task packet、工程 PR 与决策都应回引本文，避免「同一问题反复讨论」与「决策漂移」。
本文件不展开设计细节。落地到具体设计的部分会迁移到对应的 V1 设计文档（例如 model/provider 决策迁移到 v1-model-and-provider-policy.md，新仓库结构决策迁移到 v1-tech-stack-and-architecture-design.md）。
2. Decision Index
| ID | 决策项 | 决议 | 备注 |
|---|---|---|---|
| D-01 | Trial Cohort 范围 | Labs 内部内测，不对外招募 | trial 用户：项目发起人、Mark.T、Aven |
| D-02 | 试运营外部 channel | V1 trial 期间不引入 Telegram / Discord / Slack 等外部 channel | 渠道扩展推迟到 V2 |
| D-03 | 移动端承诺 | V1 是 Web + 响应式，不承诺原生 app | 与 mvp-product-definition.md §13 一致 |
| D-04 | 模型 provider 锁定 | GPT-5.5 + Kimi K2.6（替换原 Anthropic + Gemini） | 详细策略见 v1-model-and-provider-policy.md |
| D-05 | BYOM（用户自带模型） | 开放，但非默认 | 用户需显式配置；默认走 V1 锁定的 provider |
| D-06 | Kill Criteria 责任人 | 项目发起人（主），备份 1 名待定 | 任何 RB-2 / RB-3 触发时可立即停止 trial |
| D-07 | Skill / Advisor 停用决策权 | 项目发起人 | Phase 2 评审 grade = D 时拍板 |
| D-08 | 样本输出生成授权 | 授权 AI Agent 直接执行 evaluation runs 并归档（B-7） | 样本归档到工程仓库 + 治理库 evaluation 命名空间 |
| D-09 | aifinlab Root Skills 分析 | 同意建立独立执行计划，分配 Codex 异步并行；不阻塞 V1 工程化 | 见 aifinlab-root-skills-taxonomy-execution-plan.md |
| D-10 | 工程仓库重建 | 在 /Users/mlabs/Programs/CurvatureLabs/finclaw/ 启动全新工程仓库；旧 /Users/mlabs/Programs/fin-claw/ 保留作对照参考 | 见 §4 迁移策略 |
| D-11 | Skills 领域评审分两阶段 | Phase 1：基于 4 个参考项目分析做 baseline 自查（AI 自治）；Phase 2：trial 期间收集真实输出后再请外部金融专家 grade-based 评审 | 缓解 v1-skills-domain-knowledge-review-packet.md §8 的 Open Items |
| D-12 | 隐私 / 合规复核时机 | Labs 内测期间降紧迫，但必须在 trial 退出 / 公开扩展前完成 GDPR + 商业信号 instrumentation 复核 | 不豁免，仅延后 |
| D-13 | NDA 范围 | Labs 内测期间用内部同意书即可；外部专家 NDA 推迟到 Phase 2 评审之前签订 | — |
3. Decision Details
D-01 Trial Cohort 范围
- 内测人选：项目发起人、Mark.T、Aven（3 人）。
- 邀请发放：直接通过 Labs 协作渠道；不需要邀请码生成器（节省 v1-trial-operations-plan.md §3 描述的招募工程）。
- 用户同意书：以 Labs 内部知会函 + 简短同意条款形式记录；不签外部 NDA。
- 同意条款覆盖：反馈记录、行为信号采集、训练资产候选、撤回权。
D-02 V1 不引入外部 channel
- V1 工程仓库不实现 Telegram bot、Discord、Slack、Email、WhatsApp 等 channel adapter；
- Channel extension 设计保留在 v1-design-kickoff-packet.md §4.2 的
v1-channel-extension-design.md列表中，但推迟到 V2 产出； - 旧工程仓库已有的
server/api/telegram*.py不迁移。
D-03 移动端承诺
- V1 形态：Web + 响应式（移动端浏览器可正常使用）；
- 不承诺移动端原生 app；
- 不在 V1 工程仓库引入 React Native / Flutter / Capacitor 等原生壳。
D-04 模型 provider 锁定到 GPT-5.5 + Kimi K2.6
切换理由（相对原 Anthropic + Gemini）：
- 与 Labs 已有 FinRobot evaluation 验证过的 Kimi K2.6 endpoint 一致，复用 model telemetry 基线；
- 降低 cost，扩大 trial 期 token 预算空间；
- GPT-5.5 + Kimi K2.6 在中文金融场景的领域覆盖更广。
实现影响：
llm_client需要重写以支持 GPT-5.5 function calling + Kimi K2.6 tool-use；- system prompt（特别是 advisor profile）需要重新校准；
- 之前为 Claude 调试的 tool_use 结构化输出策略需要在两家 provider 上重新验证；
- 旧工程仓库的
anthropicSDK 依赖不迁移。
详细策略：见 v1-model-and-provider-policy.md。
D-05 BYOM（开放，但非默认）
- 默认 provider：V1 锁定为 GPT-5.5 + Kimi K2.6；
- 用户可在配置中显式启用 BYOM，自带 model API key + provider endpoint；
- BYOM 模式下：
- tool_use / function calling 兼容性由 LLMClient adapter 层抽象；
- V1 不保证 BYOM 在所有 Skill / Advisor 上达到与默认 provider 相同的领域质量；
- BYOM 输出在 evaluation runs 中独立标注，不混入主 provider 的 grade 统计。
D-06 Kill Criteria 责任人
- 主责：项目发起人；
- 备份：待定 1 名（建议从 Labs 团队选 1 人）；
- 触发条件参考 v1-human-experience-trial-script.md §5 Boundary Event Response Protocol RB-2（私钥/凭证输入）+ RB-3（订单字段输出）+ 任何 BoundaryGuard 异常触发；产品边界规则的母法见 mvp-product-definition.md；
- 触发后动作：立即停止 trial → 通知 Mark.T 与 Aven → 评估根因 → 决定是否恢复。
D-07 Skill / Advisor 停用决策权
- 主责：项目发起人；
- 触发条件：Phase 2 评审任一项 grade = D；
- 停用动作：在工程仓库
config/agents.yaml与skills/_disabled/标记，runtime 不加载； - 复用：触发停用的 Skill / Advisor 改造后需重启评审才能恢复。
D-08 样本输出生成授权
- AI Agent 可在工程仓库
evaluation/目录直接执行 evaluation runs； - 样本输出归档到：
- 工程仓库
evaluation/runs/<timestamp>/（结构化 jsonl + per-case markdown）； - 治理库
/Users/mlabs/Programs/Labs-FinTecAI/evaluation/finclaw/runs/<timestamp>/（同步副本，作为评测知识库证据）；
- 工程仓库
- 不写入任何真实交易、私钥、外部账户；
- 不发送给生产 channel（D-02 已禁用）。
D-09 aifinlab Root Skills 分析
- 状态：并行启动，不阻塞 V1 工程化；
- 执行方：Codex 异步执行（按 aifinlab-root-skills-taxonomy-execution-plan.md 节奏）；
- 产出回写位置：治理库
reference-experience/aifinlab-root-skills-taxonomy.md（按 batch 增量更新）。
D-10 工程仓库重建
新工程仓库路径：/Users/mlabs/Programs/CurvatureLabs/finclaw/
旧工程仓库 /Users/mlabs/Programs/fin-claw/：
- 保留只读对照参考（团队成员仍在持续修改更新）；
- 不做归档动作（保留主分支演进权）；
- 新仓库不与旧仓库共享 git history。
D-10.a 选择性迁移清单
| 旧仓库内容 | 迁移决策 |
|---|---|
| V1 数据模型（MarketCognitionSnapshot / PreExecutionCheckpoint / MarketCognitionThread / AdvisorOutput / EvidenceItem / DataQualityNote） | 迁移（已对齐 V1 设计） |
| 9 个 Skills 中的 7 个 V1 Skills（snapshot / pre_execution / risk_challenge / evidence_audit / thread_ops / narrative_mapper / event_impact_reader） | 迁移 |
旧 Skills：_default、market_audit | 不迁移 |
| ContextEngine、ObjectWriter、BoundaryGuard | 迁移（已对齐 V1） |
| AgentRuntime 核心调度 | 迁移骨架，llm_client 需要按 D-04 重写 |
| anthropic SDK 集成 | 不迁移 |
| 500 个测试 | 选择性迁移 ~70%（剔除与旧模型 / Anthropic SDK / Telegram 相关测试） |
Telegram bot 代码（server/api/telegram*.py） | 不迁移（D-02） |
旧设计文档（docs/design/01-09-*.md） | 不迁移（已过时） |
Web 前端（web/） | 迁移基础架构，UI 重写（按 UI 原型文档落地） |
| CoinGecko data tools | 迁移 |
Evaluation cases YAMLs（server/tests/evaluation_cases/ 7 份 edge-* + 6 份治理库 V1 cases） | 迁移到 evaluation/cases/，同步到治理库 evaluation/finclaw/cases/ |
D-10.b 迁移工序
- 在新路径下初始化新 git 仓库（不 clone 旧仓库）；
- 创建项目骨架（按 D-04 后的 provider 决策起步）；
- 逐组件 review-then-migrate：每个组件复制时同步重命名、重写 import、剔除旧依赖；
- 每组件迁移完成后立即跑测试；
- 不做一次性
cp -r。
D-11 Skills 领域评审分两阶段
| 阶段 | 时机 | 评审方式 |
|---|---|---|
| Phase 1 | V1 工程化期间 | AI 自治：基于 4 个参考项目（aifinlab / Chelae / martinpmm / FinRobot）的现成分析报告，对 7 个 Fin Skills + 6 个 Advisors 做领域 baseline 自查 |
| Phase 2 | trial 期跑出 ≥ 6 份真实样本输出后 | 邀请外部金融专家做 grade-based 评审（按 v1-skills-domain-knowledge-review-packet.md） |
这缓解了「不能等专家评审完才开始工程化」的死锁问题。
D-12 隐私 / 合规复核
- Labs 内测期间：降紧迫，可与工程并行准备草案；
- trial 退出 / 公开扩展前：必须完成 GDPR + 商业信号 instrumentation 隐私边界 + ProfileConsent + TrainingAssetCandidate 退出机制法务复核；
- 复核负责人：项目发起人协调外部法务（待定）。
D-13 NDA 范围
- Labs 内测：内部同意书（Labs 团队成员同意采集行为信号、提供反馈、训练资产候选授权 / 撤回权）；
- Phase 2 外部专家：轻量 NDA，由 AI 起草草案，项目发起人审定后签订。
4. Constraints and Non-Goals
4.1 本文件不做的事
- 不展开新工程仓库的项目骨架细节（迁移到
v1-tech-stack-and-architecture-design.md）； - 不展开 GPT-5.5 / Kimi K2.6 的 prompt / function-calling 适配细节（迁移到
v1-model-and-provider-policy.md）； - 不展开 aifinlab root skills 抽样节奏（迁移到
aifinlab-root-skills-taxonomy-execution-plan.md）； - 不替代 v1-execution-plan-and-milestones.md 的 milestone / risk register。
4.2 后续 V1 设计如不符合本决策应回退
任何后续 V1 设计 / task packet / 工程 PR 如与本文 §2 Decision Index 冲突：
- 不直接修改本文；
- 在对应 design / task-packet 中显式声明「需要修订决策 D-XX」并升级到项目发起人；
- 决策修订必须更新本文 §2 + §3，并在 v1-execution-plan-and-milestones.md 风险登记中追记。
5. Downstream Action Items
| ID | 动作 | 负责 | 落点 |
|---|---|---|---|
| AI-D-1 | 起草 v1-model-and-provider-policy.md（按 D-04 + D-05） | AI Agent | 本治理库 |
| AI-D-2 | 起草 aifinlab-root-skills-taxonomy-execution-plan.md（按 D-09） | AI Agent | 本治理库 |
| AI-D-3 | 起草 v1-tech-stack-and-architecture-design.md（按 D-10） | AI Agent（待用户最终启动指令） | 本治理库 |
| AI-D-4 | 起草 v1-data-and-persistence-design.md、v1-api-contract-design.md、v1-ui-prototype-and-design-system.md、v1-observability-and-telemetry-design.md、v1-memory-and-personalization-design.md、v1-cost-and-token-budget-design.md | AI Agent（待用户最终启动指令） | 本治理库 |
| AI-D-5 | 在新路径 /Users/mlabs/Programs/CurvatureLabs/finclaw/ 启动工程骨架（按 D-10.b 工序） | AI Agent（待用户最终启动指令） | 工程仓库 |
| AI-D-6 | Skills Phase 1 baseline 自查产出 | AI Agent（待用户最终启动指令） | 工程仓库 + 本治理库 evaluation 命名空间 |
| USR-D-1 | 指派 Kill Criteria 备份人 | 项目发起人 | 本文 §3 D-06 更新 |
| USR-D-2 | 隐私 / 合规复核外部法务对接 | 项目发起人 | 本文 §3 D-12 更新 |
6. Open Items
- D-06 Kill Criteria 备份人未定；
- D-12 隐私 / 合规复核外部法务未定；
- Phase 2 外部金融专家候选未定（推迟到 trial 跑过之后再确定）。
7. Outstanding User Decisions（review 5.3 升级）
本节为 review 5.3 升级登记位，不修改 §3 D-06 / D-12 正文决策（保留原 "项目发起人 = Kill Criteria 责任人" 锁定）。§5 已有 USR-D-1 / USR-D-2 行，本表补 Due 列并明确 AI Agent 行为约束。
| ID | Action | Owner | Due |
|---|---|---|---|
| USR-D-1 | 指定 Kill Criteria 备份责任人（D-06 单点风险消解） | 项目发起人 | trial 启动前 |
| USR-D-2 | 协调外部法务进行 privacy/compliance 复核（D-12） | 项目发起人 + Legal | trial 启动前 |
本节为 review 升级登记位，AI Agent 不可自治决定 Owner / Due / 备份责任人；只能登记问题、等待项目发起人答复。