Merge pull request #37 from xmindlab-heicode/feat/usage-cost-phase

用量按 review-retry 成本归属：usage 事件标 cost_phase（Refs #16）

docs/integration/usage-billing-schema.md

@@ -62,6 +62,8 @@ Swarm 在运行中按时长/成本比例发 `budget.alert`（默认 80% 阈值
 {
   "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 }
@@ -84,7 +86,8 @@ PayPal 说明 §5 给出的运行时用量回传目标：
 ## 5. 多 Agent / 评审重做 成本聚合
 
 - 一次 swarm 请求拆成多 task / 多 agent / 多评审轮；**每个 task 的 `usage` 可按 `swarm_id` 聚合**得到运行级合计（观测用途）。
-- **评审重做成本**：每轮重做都会重新执行任务并累计 `usage`，因此**已隐含计入**运行级合计；但当前**未单独打标**「review_retry 成本」。
+- **评审重做成本（#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. 字段覆盖与缺口
 
@@ -96,7 +99,7 @@ PayPal 说明 §5 给出的运行时用量回传目标：
 | `reasoning_tokens` / `cache_tokens` | 🔴 未采集（取决于 provider usage 返回） |
 | `tool_cost`（工具调用成本） | 🔴 未采集（无 SK 工具计量） |
 | `cpu_core_seconds` / `memory_mb_seconds`（基础设施） | 🔴 未采集（K8s 指标未接入账本） |
-| `review_retry` 成本单独打标 | 🟡 隐含累计，未单独标注 |
+| `review_retry` 成本单独打标 | ✅ 已打标（usage 事件 `cost_phase=review_retry`，#16） |
 | provider 成本拆分 | 🟡 由 NewAPI/账本侧负责，非本仓 |
 | tenant 归因 | ❌ 按标准不使用（见 §1） |