From df835887200f2b372d1346528b60d1736e3669dd Mon Sep 17 00:00:00 2001 From: chenchen Date: Wed, 10 Jun 2026 11:36:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(client-api):=20add=20budget=5Fremaining=20?= =?UTF-8?q?to=20agent=20usage=20=C2=A75.1=20(#9)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- docs/integration/heicode-desktop-client-api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/integration/heicode-desktop-client-api.md b/docs/integration/heicode-desktop-client-api.md index b7a676b..e655031 100644 --- a/docs/integration/heicode-desktop-client-api.md +++ b/docs/integration/heicode-desktop-client-api.md @@ -236,11 +236,13 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) ) "prompt_tokens": 8000, "completion_tokens": 4000, "call_count": 12, - "quota_per_unit": 500000 // 额度→货币换算分母(quota/quota_per_unit=美元额度) + "quota_per_unit": 500000, // 额度→货币换算分母(quota/quota_per_unit=美元额度) + "budget_remaining": 1234567 // ★ 用户钱包剩余额度(预算剩余;-1=读取失败,不阻断展示) }} ``` - **空数据语义**:无调用记录时各计数为 `0`(仍返回 `success:true`,不是 404)。 +- **`budget_remaining`(#9)**:用户剩余可用额度(同 `quota_per_unit` 口径换算)。Agent 模型调用经隐藏 token 计费到 `user.Quota`,故"本任务预算剩余"= 用户钱包剩余额度。 - **与 billing logs 的关系**:用量来自统一计费 logs(`SumAgentUsage`),按 token name `agent:` 过滤聚合 —— 即 agent 走 HM `/v1/*` 的真实消耗,与用户钱包/订阅扣费同源。 - **计费归集语义(#30)**:每个部署的 agent,HM 为其 mint 一个**隐藏、不展示在用户 token 列表**的模型 token(`UnlimitedQuota:true`)。`UnlimitedQuota` 的含义是「**不对该 token 自身设单独的剩余额度上限**」——它**不**绕过用户额度:agent 经此 token 调 `/v1/*` 时,HM 仍先校验 `user.Quota`,并在结算时从 `user.Quota`(钱包)或订阅项扣费、写计费 log,完全经过计费表达式。停止/删除 agent 后该 token 被撤销,旧 token 无法再调 `/v1/*`。该 token 对普通用户隐藏,但审计/管理员可追踪。