# Investibook Cost Control Plan 主设计文档

**Date:** 2026-04-21
**Status:** Draft for discussion

---

## Summary

随着 Investibook 的使用场景从简单的人工对话扩展到自动诊断 (AutoChat)、日常回归评测 (Evaluation Daily Run) 以及更多的高级 Agent 任务，LLM Token 成本和相关基础设施成本的增长速度需要被有效管理。

这个 plan 的核心目标，是把“成本控制”升级成一个系统性的工程能力，并从单纯的“压低成本”转向“基于 ROI（投入产出比）的成本管理体系”。

一句话概括：

> 把“被动的账单查看”升级成“事前可控、事中可观测、事后可优化的全面成本与 ROI 治理体系”。

---

## 成本控制逻辑与指导原则 (Cost Control Logic & Principles)

在展开具体的任务规划前，我们需要明确本次成本控制设计的核心逻辑。这决定了为什么我们不采取一刀切的限额策略，而是按阶段推进。

**1. 为什么短期只做“托底”和“观察”，不急于全面限额？**

- **当前阶段特点**：系统目前处于早期上量测试阶段，使用场景、用户画像和 Token 消耗模型尚未稳定。
- **避免错杀价值**：如果在未摸清“费用去向”的情况下贸然对全线业务（包括人工排障）进行刚性限额，极易影响一线的核心诊断体验，甚至在 P0 故障中阻断 Agent 的救援。
- **核心逻辑**：因此，**5月前只设系统级的灾难托底（150 USD 预警 / 200 USD 熔断）**，保证不出现天价账单；主要精力必须放在**“把账本建清楚”（观察）**上。

**2. 为什么要把“成本控制”演进为“ROI 管理”？**

- **成本的反面是业务价值**：Agent 自动处理一个告警可能消耗 10 美金的 Token，但如果它将一个 P0 故障的处理时间缩短了 30 分钟，挽回了上千美金的隐形业务损失，那么这 10 美金不仅不是“成本”，反而是高额回报的“投资”。
- **核心逻辑**：从 5 月起，成本优化的目标不再是单纯地“把费用压得越低越好”，而是**“把低价值场景的消耗压下去（如空转的自动化评测或鸡肋轮询），把节省下来的额度倾斜给高回报场景（如故障排障和 P0 告警分析）”**。

**3. 从“成本中心”走向“价值中心”（分账逻辑）**

- **无法量化的价值无法变现**：如果我们不能清晰地证明 Agent 节省了多少工时、挽回了多少资损，项目就只能被定义为纯成本中心。
- **核心逻辑**：6月底必须落地 ROI 量化体系，为后续汇报及与业务线（如 Charles 团队）**实施跨部门费用分摊** 提供数据支撑。

---

## 任务跟踪矩阵 (Task Tracking Matrix)

为了确保核心目标按阶段落地，我们制定了以下 4×3 任务跟踪矩阵，明确了四个大模块（观察、控制、优化、ROI）和三个核心里程碑：


| 里程碑 (Milestones)                | 观察 (Observation)                                | 控制 (Control)                                                          | 优化 (Optimization)                                              | ROI (投入产出比)                                 |
| ------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------- |
| **1. 测试阶段** *(当前 - 5月初)*        | **🎯 场景打标与追踪** 1. 提供场景打标功能 2. 修复多步调用 Token 遗漏   | **🎯 托底限额与评估限流** 1. 落实全局 150 USD/日预算，200 USD 熔断 2. 测定 Evaluation 刚性上限 |                                                                |                                             |
| **2. 上量阶段** *(5月 - 6月)*         |                                                 |                                                                       | **🎯 生产系统核心降本** 1. Prompt Caching 优化 2. 智能模型降级 (Model Tiering) | **🎯 输出量化标杆案例** 1. 验证定价公式 2. 每周产出高 ROI 标杆对比 |
| **3. ROI 管控阶段** *(6月底 - 7月及以后)* | **🎯 上线 ROI 综合大盘** 搭建开放 Dashboard，打通底层投入与顶层挽回金额 |                                                                       |                                                                | **🎯 跨部门分账** 向 L3 汇报效率提升，讨论并正式推行跨部门分账       |


---

## 现状分析 (Current Implementation Analysis)

目前代码库中已经具备了基础的成本控制和观测能力，但需要进一步整合到上述的矩阵规划中：

### 1. Workspace 级别的成本熔断 (`session_cost.py`)

- **机制**：通过 `WORKSPACE_COST_LIMIT_USD` 配置全局的 Workspace 成本上限。
- **现状**：缺乏用户级别、租户级别或全局单日级别的硬性熔断。

### 2. 自动化任务的防逃逸 (`auto_chat.py`)

- **机制**：AutoChat 设置了超时控制并使用 LLM 判断是否需要人工介入。
- **现状**：LLM 评估自身也会产生额外成本；缺乏对 AutoChat 整体并发数和单日总消耗的限制。

### 3. 成本与 Token 追踪 (`metrics.py`)

- **机制**：通过 Prometheus 暴露了详尽的 Token 和成本指标（如 `acp_token_input_total`, `acp_session_cost` 等）。
- **现状**：目前已在 `runbooks/rules/resilience/investibook/cost.yaml` 中配置了最近 1 天总成本超过 100 USD 告警及 Workspace/User 成本告警。

### 4. ⚠️ 已知问题：上游 Token 统计不准确

- **现象**：目前系统中的 Token 统计存在严重的低估问题（前置步骤的 Output、Reasoning 和 Cache.write 会被最后一步覆盖而丢失）。
- **原因**：上游依赖库 Bug（参考 [anomalyco/opencode#21913](https://github.com/anomalyco/opencode/issues/21913)）。
- **应对**：在当前第一阶段（测试阶段）必须跟进修复该问题，以消除统计盲区。

---

## 详细执行方案 (Execution Plan by Milestones)

以下内容**严格对应**上方任务跟踪矩阵中的格子，不在矩阵中的事项不列入本阶段交付；避免把历史讨论过又删掉的条目写回来。

### Milestone 1：测试阶段 (当前 - 5月初)

- **观察：场景打标与追踪**
  - 提供场景打标能力，使成本可按场景归因（与 `usage_scenario` 等指标对齐）。
  - 跟进上游修复多步工具调用场景下 Token 被覆盖、未累加的问题（见上文「已知问题」与 [opencode#21913](https://github.com/anomalyco/opencode/issues/21913)），恢复可观测性后再做精细对账。
- **控制：托底限额与评估限流**
  - 落实 **150 USD/日** 与 **200 USD 熔断** 的托底策略（与现有告警/运营目标一致；具体实现可结合 `runbooks/.../cost.yaml` 等已有规则与后续阈值调整）。
  - 为每日 **Evaluation** 测定并落实刚性消耗上限（与业务方对齐预算后执行）。

### Milestone 2：上量阶段 (5月 - 6月)

- **优化：生产系统核心降本**
  - **Prompt Caching**：提升命中率与上下文组织方式，降低线上重复调用的单位成本。
  - **Model Tiering**：非核心路径路由到更低成本模型，核心路径保持质量。
- **ROI：输出量化标杆案例**
  - 验证定价公式（含「节省时间 × 时薪」等已约定的框架），用可复现的样本固化算法。
  - 按矩阵要求持续产出**高 ROI 标杆对比**（例如 Token/美元成本 vs 业务侧可解释的止损或提效），供对内复盘与对外沟通。

### Milestone 3：ROI 管控阶段 (6月底 - 7月及以后)

- **观察：上线 ROI 综合大盘**
  - 搭建并开放 **ROI Dashboard**，在同一视图内呈现底层 Token/成本投入与可论证的业务侧挽回或提效，便于对账与复盘。
- **ROI：跨部门分账**
  - 向 L3 级汇报效率与价值，与受益业务方**讨论并落地跨部门分账**（具体分摊规则与节奏与财务/业务共同敲定）。