# 用量与计费 Schema（Usage / Billing）

> 状态：**已对齐既有边界**（依据 `heicode-mananger/docs/heicode.md §八`、`docs/heicode-runtime-auth-newapi-secret-design.md §四/五`、`docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md §3/§5`）。
>
> 配套：事件载体见 [`event-schema.md`](./event-schema.md)（`budget.alert`）；安全见 [`security-boundary.md`](./security-boundary.md)。

## 1. 计费主线原则（不可破坏）

- **NewAPI 是计费账本**：模型调用费用在 HM 模型网关 `/v1/*` 处**按请求计量并扣费**（NewAPI 的 user / token / group / quota / usage）。**Swarm 不是账本**，也不重算扣费。
- **Swarm 的职责 = 用量上报与预算约束**，用于归因、观测与预算告警，不作为扣费依据。
- **归因主轴 = `user.id` / `channelId` / NewAPI user/token/group**，**不是** `tenant`/`project`。`heicode-runtime-auth §六` 明确：当前不引入 tenant/project 作为计费主轴。
- Agent 基础设施成本（CPU/内存/Pod）当前**未形成用户账本**（PayPal 说明 §5）。

> ⚠️ 与工单口径的差异：工单要求「tenant attribution」；按 Manager 标准应改为 **user/channelId 归因**。如未来确需租户账本，需作为独立产品决策，不在本仓暗自添加。

## 2. 计费归因上下文（HM 下发，Swarm 透传）

来自 `heicode-runtime-auth §五`：

```jsonc
"billing_context": {
  "provider": "newapi",
  "newapi_user_ref": "newapi_user_123",
  "newapi_group": "development",
  "quota_ref": "newapi_token_or_group_quota_ref"
}
```

- Agent 调模型走 HM `/v1`，用 **HM 为该用户现签的 `OPENAI_API_KEY`（sk-）**，扣费即记在该用户名下；删 agent 时吊销。
- Swarm 的 task_executor 随模型请求带 **`X-Agent-*` / `X-Agnet-*` 归因头**（`manager_deployment_id`、`swarm_id`、`task_id`、`agent_role`、`correlation_id`、`model_id`），供 HM/NewAPI 关联归因。

## 3. 预算约束（orchestration_plan.budget）

来自 PayPal 说明 §5：

| 字段 | 含义 |
|---|---|
| `budget.max_tokens` / `token_limit` | 本次部署 token 上限 |
| `budget.max_cost_usd` | 本次部署美元成本上限 |
| `budget.duration_seconds` / `max_duration_seconds` | 运行时长上限 |

Swarm 在运行中按时长/成本比例发 `budget.alert`（默认 80% 阈值），并在 `metrics` 返回预算占比。**这是约束与告警，不是扣费。**

## 4. 用量上报 Schema

### 4.1 Agent 单任务用量（task 结果 `usage`，已实现）
```jsonc
"usage": {
  "model_id": "gpt-4o-mini",
  "model_tokens": 0,
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "model_cost_usd": 0.0,
  "runtime_seconds": 0.0,
  "billing_source": "newapi | unknown"
}
```

### 4.2 运行级用量事件（orchestrator，已实现）
通过 `budget.alert` 事件上报（payload 含）：
```jsonc
{
  "model_id": "...", "model_tokens": 0, "prompt_tokens": 0, "completion_tokens": 0,
  "model_cost_usd": 0.0, "runtime_seconds": 0.0, "billing_source": "...",
  "cost_phase": "initial | review_retry",   // #16：返工再执行的用量标 review_retry，供成本归属
  "attempt": 0,                              // 该任务的重做次数（retry_count）
  "manager_deployment_id": "...", "swarm_id": "...", "task_id": "...",
  "agent_role": "...", "correlation_id": "...",
  "budget": { "max_tokens": null, "max_cost_usd": null, "consumed_usd": 0.0, "remaining_usd": null }
}
```

### 4.3 目标完整回传形态（对齐 AM，部分待实现）
PayPal 说明 §5 给出的运行时用量回传目标：
```jsonc
{
  "deployment_id": "dep_xxx", "agent_instance_id": "agi_backend_001",
  "usage": {
    "model_tokens": 32000, "model_cost_usd": 4.21, "runtime_seconds": 930,
    "cpu_core_seconds": 1200, "memory_mb_seconds": 2048000
  },
  "billing_source": "newapi", "correlation_id": "corr_xxx"
}
```

## 5. 多 Agent / 评审重做 成本聚合

- 一次 swarm 请求拆成多 task / 多 agent / 多评审轮；**每个 task 的 `usage` 可按 `swarm_id` 聚合**得到运行级合计（观测用途）。
- **评审重做成本（#16，已打标）**：每轮重做重新执行任务并累计 `usage`，且其用量事件带 `cost_phase="review_retry"`（cross-review 已把该任务记入 `rework_attributions` 之后的再执行）；初次执行为 `cost_phase="initial"`。计费/采集侧按 `swarm_id` 聚合时，可用 `cost_phase` 拆分 **initial vs review_retry 成本**——「review retry 成本可归属」由此满足，无需从 `retry_count` 反推。
- **详情聚合（#37）**：除逐条事件的 `cost_phase` 外，`GET …/{id}/metrics` 另返回 run 级滚动汇总 `cost_by_phase: { initial: {cost_usd, model_tokens}, review_retry: {cost_usd, model_tokens} }`，供 HM 详情用量聚合 / 客户端用量抽屉直接展示「初次 vs 返工」拆分，无需从事件流推导。

## 6. 字段覆盖与缺口

| 字段 | 状态 |
|---|---|
| `model_tokens` / `prompt_tokens` / `completion_tokens` | ✅ 已采集 |
| `model_cost_usd`、`runtime_seconds`、`billing_source` | ✅ 已采集 |
| 归因：`manager_deployment_id`/`swarm_id`/`task_id`/`agent_role`/`correlation_id` | ✅ 已采集 |
| `reasoning_tokens` / `cache_tokens` | 🔴 未采集（取决于 provider usage 返回） |
| `tool_cost`（工具调用成本） | 🔴 未采集（无 SK 工具计量） |
| `cpu_core_seconds` / `memory_mb_seconds`（基础设施） | 🔴 未采集（K8s 指标未接入账本） |
| `review_retry` 成本单独打标 | ✅ 已打标（usage 事件 `cost_phase=review_retry`，#16） |
| provider 成本拆分 | 🟡 由 NewAPI/账本侧负责，非本仓 |
| tenant 归因 | ❌ 按标准不使用（见 §1） |

## 7. 待对齐项

- [ ] 运行级用量是否需独立 `usage.report` 事件类型（当前借 `budget.alert` 载体）；与 HM/Billing Team 确认（HM 注册表暂无 usage 事件）。
- [ ] `budget.alert` 需补 `threshold_pct`（见 `event-schema.md §6`）。
- [ ] 若需基础设施计费，接入 K8s 用量（cpu/memory）并由 Billing Team 定义资源计价。
- [ ] `review_retry` 成本是否需单独打标，由 Billing Team 决定。