FinClaw V1 Model and Provider Policy (Outline)
状态：Outline Draft / 待工程化启动后补全细节
日期：2026-05-16
项目：FinClaw
文档级别：项目级技术策略 outline
上游文档：v1-engineering-kickoff-decisions.md D-04 / D-05、v1-prd.md §8、v1-agent-orchestration-design.md
配套任务包：将在 V1 工程化启动时一同产出 v1-model-and-provider-task-packet.md（暂未创建）
1. Purpose and Scope
本文件定义 FinClaw V1 在模型与 provider 选择上的策略框架，包括默认 provider、BYOM 边界、failover 路径、cost / budget、Skill / Advisor 级别的模型映射规则。
它是 outline，列出需要回答的关键问题 + 当前已确定的决策；不展开具体的 prompt 适配代码、provider SDK 抽象层接口、token 计费表。这些细节会在工程实施期间分别由 llm_client 模块、provider_router 模块和 cost_telemetry 模块的代码落地补全。
2. Locked Decisions (来自 v1-engineering-kickoff-decisions.md)
| ID | 决策 |
|---|---|
| D-04 | 默认 provider 锁定为 GPT-5.5 + Kimi K2.6 |
| D-05 | BYOM 开放，但非默认；用户需显式配置 |
| D-02 | 不引入外部 channel → provider 不需要支持 channel 适配相关能力 |
| D-08 | 样本输出生成可直接使用默认 provider，无需 BYOM |
3. Provider Roles
V1 不采用「单一主 provider」模式，而是双 provider 并存 + 任务分流：
| Role | Default Provider | 用途 | 备注 |
|---|---|---|---|
| Primary Cognition Provider | GPT-5.5 | Snapshot / Checkpoint / Advisor 主分析；结构化 tool_use 输出 | 选用理由：function calling 稳定、英文金融领域强、tool schema 兼容性最高 |
| Secondary Cognition Provider | Kimi K2.6 | 中文加密市场叙事 / 长上下文证据合并；非主分析的 advisor 辅助视角 | 选用理由：中文领域覆盖强、上下文窗口大、cost 低；Labs 已有 FinRobot evaluation 验证过 Moonshot-compatible endpoint |
| BYOM Provider Slot | 用户自定义 | 用户自带 model（可选） | 不参与默认路由；用户显式启用 |
3.1 任务分流原则（v0 草案，工程化期间精化）
- 主 Snapshot 路径（核心结构化对象生成）：默认走 GPT-5.5，保证 tool_use 结构化输出最强；
- 次要 Advisor 视角（counter-thesis、market_macro、event_interpretation 等附加视角）：可由 Kimi K2.6 提供，节省 cost 同时引入语言 / 风格多样性；
- Skill 内部子调用（例如 evidence_audit 子提取）：由 Skill metadata 显式声明使用哪个 provider；
- 降级路径：主 provider 失败时按 §6 failover 处理；
- 任何分流策略必须在
config/provider_routing.yaml中可配置，不硬编码到 runtime。
4. BYOM Boundary
| 维度 | 策略 |
|---|---|
| 启用方式 | 用户在 ~/.finclaw/config.yaml 显式配置 byom.enabled: true + byom.provider + byom.endpoint + 凭证（macOS Keychain 引用） |
| 凭证存储 | 必须走 Keychain：禁止明文 key 写入任何配置文件 |
| 兼容性要求 | BYOM provider 必须支持以下能力之一：OpenAI function calling / Anthropic tool_use / native JSON mode |
| 质量保证 | BYOM 输出不保证与默认 provider 同等领域质量；evaluation runs 中独立标注（D-05） |
| Fallback 行为 | BYOM 调用失败时不自动回退到默认 provider（避免用户成本意外产生）；返回明确错误并提示用户检查配置 |
| 商业信号 instrumentation | BYOM 调用同样要遵守 v1-commercial-signal-instrumentation-design.md 的事件采集；但 model_name 字段标注为 byom:<user-supplied-name> |
| 数据隔离 | BYOM endpoint 不访问 FinClaw 用户的认知历史 / Profile 之外的数据；training-asset-candidate 路径禁用 BYOM（避免用户私有数据流向不可控第三方） |
5. Skill / Advisor → Provider 映射
工程实施时按下表初始化 config/agent_routing.yaml：
| Skill / Advisor | Default Provider | 备选 | 备注 |
|---|---|---|---|
snapshot (核心 Skill) | GPT-5.5 | Kimi K2.6 | 结构化输出敏感，优先 GPT-5.5 |
pre_execution (核心 Skill) | GPT-5.5 | Kimi K2.6 | 行动邻近边界判断需要稳定 tool_use |
risk_challenge (核心 Skill) | Kimi K2.6 | GPT-5.5 | 风险挑战可适当用 Kimi 增加视角差异 |
evidence_audit (核心 Skill) | GPT-5.5 | Kimi K2.6 | source provenance 判断需要严格 |
thread_ops (核心 Skill) | GPT-5.5 | Kimi K2.6 | thread refresh diff 结构化敏感 |
narrative_mapper (核心 Skill) | Kimi K2.6 | GPT-5.5 | 加密叙事识别中文优势 |
event_impact_reader (核心 Skill) | Kimi K2.6 | GPT-5.5 | 加密事件解读中文 / 链上信息覆盖广 |
| Event Interpretation Advisor | Kimi K2.6 | GPT-5.5 | — |
| Asset Research Advisor | GPT-5.5 | Kimi K2.6 | — |
| Market / Macro Advisor | Kimi K2.6 | GPT-5.5 | — |
| Risk Advisor | GPT-5.5 | Kimi K2.6 | — |
| Counter-Thesis Advisor | Kimi K2.6 | GPT-5.5 | 提供视角差异 |
| Pre-Execution Advisor | GPT-5.5 | Kimi K2.6 | 行动邻近边界判断 |
上表是 v0 默认值；trial 期间根据 evaluation grade 调整。
6. Failover and Resilience
6.1 失败分类
| 类型 | 例 | 处理 |
|---|---|---|
| Transient（网络 / 限流 / 5xx） | 429、503、connection reset | 指数退避重试 ≤ 3 次 |
| Provider-specific（schema 校验失败 / tool_use 不兼容） | tool_call 缺少必填字段 | 切到备选 provider |
| Persistent（鉴权失败 / 服务下线） | 401 / 403 / 永久 5xx | 立即切到备选 provider + 告警 |
| Quota / Budget 超限 | 超出 daily / monthly budget | 拒绝请求，返回明确错误（不切换） |
6.2 Failover 路径
Skill / Advisor 请求
↓
Primary provider (per §5 mapping)
↓ failure → 6.1 分类
├─ Transient: 退避重试
├─ Provider-specific: 切到备选 provider
├─ Persistent: 切到备选 provider + 告警
└─ Quota: 拒绝 + 错误
6.3 Failover 不能掩盖的语义差异
- Primary 与备选 provider 切换时，advisor output 的
model_name字段必须如实标注实际使用的 provider； - 切换不计入「同一 advisor 视角」（即不可两次切换试图刷出同一视角的多份输出）；
- Evaluation runs 必须记录每个 case 的 provider chain（primary → fallback）。
7. Cost and Budget Policy
⚠️ SUPERSEDED — 本节 V0 草案已被 v1-cost-and-token-budget-design.md (B-7) 工程化校准并替换。
工程实施时必须以 B-7 为单一权威：
- Provider unit cost → B-7 §3.2（与本节 §3 任务分流的 cost-aware 维度一并 down-pour 到 B-7 §4 Provider Routing Economics）；
- Budget cap 矩阵（per-route / per-user / global）→ B-7 §5.1（本节 §7.1 占位数字 $0.10/$0.05/$0.02 已被 B-7 校准为 $0.20/$0.15/$0.10/$0.05 soft + per-user daily $3 / monthly $50 + global daily $10 / monthly $200）；
- Budget 触达行为 → B-7 §8 Overrun Handling and Degradation Path（V1 改为 4-Tier graded degradation 而非本节 §7.2 的「直接拒绝 + 只读模式」一刀切）；
- Token telemetry schema → B-7 §10.2 cost_telemetry event schema（canonical schema；本节 §7.3 字段清单已被 B-7 嵌套 schema 替代）；
- Telemetry hook 落地 → v1-observability-and-telemetry-design.md §10（B-5 metrics / trace / SQLite 索引）。
本节以下内容保留仅作历史 outline 参考，trial 启动后所有 cost / budget 决策禁止回引本节作为权威。
7.1 Budget Scope（已被 B-7 §5.1 替代）
| Scope | Budget Type | V0 草案上限（已 superseded） |
|---|---|---|
| Per Snapshot | hard cap | |
| Per Checkpoint | hard cap | |
| Per Advisor 视角 | soft cap | |
| Trial 期 daily budget | hard cap | 待 trial 启动前确定 → B-7 §5.1 占位 $3 / user, $10 global |
| Trial 期 monthly budget | hard cap | 待 trial 启动前确定 → B-7 §5.1 占位 $50 / user, $200 global |
| BYOM | 用户自承担 | 不计入 FinClaw budget（与 B-7 §7 一致） |
7.2 Budget 触达后的行为（已被 B-7 §8 4-Tier Degradation 替代）
Soft cap 触达 → 写入 evaluation runs 警告字段；不阻断；Hard cap 触达 → BoundaryGuard 拒绝继续；返回明确错误 + 建议用户简化任务；Daily / monthly budget 触达 → 整个工程仓库降级到「只读模式」任何 budget 触达事件都进入商业信号 instrumentation；
→ 全部行为以 B-7 §8 Degradation Ladder 为准（Tier-1 ~ Tier-4 graded 降级，仅 Tier-3/4 才拒绝，且 cs-event forward 走 B-7 §10.4）。
7.3 Token Telemetry（已被 B-7 §10.2 替代）
每次 LLM 调用必须记录 provider / model / endpoint / prompt_tokens / completion_tokens / total_tokens / estimated_cost_usd / skill_or_advisor_id / failover_chain。落盘位置：工程仓库 evaluation/runs/<timestamp>/llm_telemetry.jsonl。
→ Canonical schema 见 B-7 §10.2 cost_telemetry event schema；落盘双写（JSONL + SQLite 旁路索引）由 v1-observability-and-telemetry-design.md §10.3 实现。
8. Open Items
待 V1 工程化期间决定：
- GPT-5.5 + Kimi K2.6 在 V1 测试场景下的 token cost benchmark（决定 §7 budget 上限）；
- Kimi K2.6 的 tool-use schema 与 GPT-5.5 function-calling 的适配层抽象（决定
llm_client接口形状）； - BYOM 兼容性测试矩阵（至少覆盖 OpenAI-compatible / Anthropic-compatible / 本地 vLLM 三类）；
- Trial 期 daily / monthly budget 具体数值（与项目发起人对齐）；
- Skill / Advisor → Provider 映射在 trial evaluation 后的调整建议；
- 是否在 V1 trial 中保留 Anthropic 作为应急降级 provider（当前 D-04 决议不保留；可在 trial 中观察后决定）。
9. Downstream Tasks
| ID | 任务 | 触发时机 |
|---|---|---|
| M-1 | 实现 llm_client 抽象层 + GPT-5.5 / Kimi K2.6 adapter | V1 工程化启动后 |
| M-2 | 实现 provider_router 模块（按 §3 任务分流 + §5 映射） | V1 工程化启动后 |
| M-3 | 实现 cost_telemetry 模块（按 §7） | V1 工程化启动后 |
| M-4 | BYOM 配置 schema + Keychain 集成（按 §4） | V1 工程化启动后 |
| M-5 | 评测 GPT-5.5 + Kimi K2.6 在 V1 6 个 cases 上的 baseline grade | 工程骨架就绪后 |
| M-6 | 决策是否保留 Anthropic 作为应急降级 | trial 期间评估后 |
10. References
- v1-engineering-kickoff-decisions.md D-04 / D-05；
- v1-agent-orchestration-design.md Advisor 编排骨架；
- v1-commercial-signal-instrumentation-design.md 信号采集；
- evaluation/finclaw/ 评测命名空间；
- Labs-FinTecAI/projects/finclaw/reference-experience/finrobot-evaluation.md Kimi K2.6 endpoint 验证基线。