---
name: voc-cost-controller
description: VOC 复杂采集任务的执行前成本估算、预算检查和执行后用量汇总。
---

# VOC 成本控制

对账号、商品或关键词规模较大的任务，先调用 `voc_cost_estimate`。Agent 根据返回的接口计划、当前生效价目和余额向用户说明经济版、标准版、完整版的预期成本区间，不把估算当作已消费。

执行过程中使用同一 `usageTraceId`，每批次前调用预算守卫：本地预算达到 80% 发出提示，超过硬上限停止新增采集并保存检查点。NewAPI 仍按每次实际调用实时扣费，不创建任务级支付或冻结余额。

VOC 数据余额不足时，保留已完成结果和检查点，返回差额、建议充值金额、Token 免登录 Balance 链接或现有二维码支付结果。到账后重新查询余额并从检查点继续；Agent 模型自身 402 由宿主运行时处理。

任务完成后调用 `voc_usage_report`，按追踪标识或日期范围展示调用次数、计费次数、quota、用户扣费和接口拆分。大模型费用与 VOC 数据费用分开；没有精确追踪时标记为 `reconstructed` 或 `mixed`。

价格唯一来源是服务端 billing query。目录中的 `billing` 字段不能被当作人民币单价。