Files

T

Songhaoz666andClaude Opus 4.8 54cb327348 Agent Swarm v6：基准 v2.1、主控 Agent、实质性对等回复、客户端指南

- 基准标准 v2.1：SwarmMetrics（15 字段）、τ/η/P_decision/reward 公式、对称 G_E,c（修正 C_base=1.0 退化）、Σλ=1.0 校验；新增基线对比与运行记录 schema；指标覆盖缺口分析；参考系数暂留为元数据（待量化）。
- 主控 Agent 实体（分解 / 评审决策 / 汇总）；事件契约修正（timeline.title、budget.threshold_pct、handoff 角色、task.released）+ 契约校验脚本。
- 实质性 LLM 对等回复（含降级回退）；集成契约（runtime / event / usage / audit / frontend / capability / security）；CLIENT_GUIDE 客户端指南；CI 工作流；治理与交付文档。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-09 16:21:18 +08:00

5.2 KiB

Raw Blame History

用量与计费 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（budget.alert）；安全见 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 §五：

"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`，已实现）

"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 含）：

{
  "model_id": "...", "model_tokens": 0, "prompt_tokens": 0, "completion_tokens": 0,
  "model_cost_usd": 0.0, "runtime_seconds": 0.0, "billing_source": "...",
  "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 给出的运行时用量回传目标：

{
  "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 聚合得到运行级合计（观测用途）。
评审重做成本：每轮重做都会重新执行任务并累计 usage，因此已隐含计入运行级合计；但当前未单独打标「review_retry 成本」。

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` 成本单独打标	🟡 隐含累计，未单独标注
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 决定。

5.2 KiB Raw Blame History Unescape Escape