预算治理：AI Agent 成本控制与自动熔断

预算治理：AI Agent 成本控制与自动熔断

1. 问题定义

AI Agent 系统的一个核心风险是成本失控：

• Agent 可能陷入无限循环，持续消耗 token
• 多个 Agent 并行执行时，总成本可能远超预期
• 模型定价复杂（input token、output token、cached token 价格不同）
• 无人值守时，预算消耗可能在几分钟内达到数千美元

预算治理通过在 Agent 执行前检查预算、执行中追踪成本、执行后记录事件，建立完整的成本控制闭环。

2. 核心架构

3. 预算策略（Budget Policy）

3.1 策略定义

每个 budget policy 包含：

字段	说明
scope_type	范围类型：company / agent / project
scope_id	对应的实体 ID
amount	预算金额（USD）
warn_percent	警告阈值百分比（如 80%）
hard_stop_percent	硬上限百分比（如 100%）
window_kind	窗口类型：monthly（月度日历）/ lifetime（累计）

3.2 多粒度 Scope

预算可以在不同粒度设置：

• 公司级：全局预算，所有 Agent 和项目的总和
• Agent 级：单个 Agent 的月度预算（类似”工资”）
• 项目级：特定项目的预算上限

4. 预算窗口

4.1 月度日历窗口

默认使用 UTC 月度窗口：

// 伪代码：计算当前月度窗口
function currentUtcMonthWindow() {
  const now = new Date();
  const start = new Date(Date.UTC(now.getFullYear(), now.getMonth(), 1));
  const end = new Date(Date.UTC(now.getFullYear(), now.getMonth() + 1, 1));
  return { start, end };
}

4.2 累计窗口（Lifetime）

统计从系统上线以来的总消耗，用于长期预算规划。

5. 预算执行流程

5.1 预检（Pre-check）

在 Agent 执行前：

伪代码：
observed = sum(cost_events where scope = agent.scope AND time = window)
if observed >= policy.amount × hard_stop_percent / 100:
    return "hard_stop" → 跳过执行，记录事件
elif observed >= policy.amount × warn_percent / 100:
    return "warning" → 继续执行，记录告警
else:
    return "ok" → 继续执行

5.2 硬上限熔断

当预算达到硬上限：

1. 取消队列中的任务：调用 cancelWorkForScope 取消该 scope 下所有 pending 任务
2. 暂停 Agent：将 Agent 状态标记为 paused，阻止新的唤醒
3. 记录 Budget Incident：创建事件记录，包含触发原因、时间、影响范围
4. 通知董事会：通过 activity log 和实时事件推送

5.3 警告阈值

当预算达到警告阈值：

• 继续执行，但记录 warning 事件
• 在 Dashboard 上显示预算告警
• 不自动暂停 Agent（留给人类决策）

6. 成本事件追踪

6.1 事件维度

每次心跳执行产生成本事件：

维度	说明
company_id	所属公司
agent_id	消耗 Agent
issue_id	关联任务
provider	模型提供商（OpenAI、Anthropic 等）
model	使用的模型
input_tokens	输入 token 数
output_tokens	输出 token 数
cost_usd	美元成本

6.2 成本聚合

成本事件按多个维度聚合：

公司总成本 = SUM(cost_events WHERE company_id = X AND time = window)
Agent 成本 = SUM(cost_events WHERE agent_id = X)
项目成本 = SUM(cost_events WHERE issue_id IN (issues WHERE project_id = X))

7. Budget Incident 管理

7.1 Incident 生命周期

阶段	说明
Created	预算超限事件创建，记录触发原因
Acknowledged	董事会确认收到通知
Resolved	人工处理（增加预算、永久暂停 Agent 等）
Dismissed	忽略事件（不增加预算）

7.2 解决策略

董事会对 Budget Incident 的处理：

• 增加预算：调高 budget policy 的 amount
• 暂停 Agent：永久暂停该 Agent
• 恢复执行：确认是误报，恢复正常执行
• 调整策略：修改 warn_percent 或 hard_stop_percent

8. 陷阱与对策

陷阱	后果	对策
并发预算竞态（多个 Agent 同时通过预检）	总消耗超出预算上限	预算检查使用乐观锁或余额扣减，确保串行化
单次执行成本远超预算余量	即使通过预检，执行后仍超限	设置单次执行最大成本上限（per-run cap）
模型定价变更导致成本计算错误	预算计算偏差	使用 Provider API 实时获取定价，或定期更新本地定价表
月度边界跨越时的竞态	月末最后几分钟的执行计入下月	使用 UTC 时间严格切割，边界上的事件明确归属
Budget incident 风暴	同一原因触发大量 incident	Coalescing：相同 root cause 的 incident 合并

9. 参考来源

• Paperclip Budget Service — server/src/services/budgets.ts
• Paperclip Budget Policies Schema — packages/db/src/schema/budget_policies.ts
• Paperclip Cost Events Schema — packages/db/src/schema/cost_events.ts
• Paperclip Budget Incidents Schema — packages/db/src/schema/budget_incidents.ts
• Paperclip SPEC-implementation.md — “Budget enforcement: Soft alerts + hard limit auto-pause”