@volcengine/ark-cli-darwin-arm64 0.0.0-stage → 1.0.46-prerelease.dc921200a42d

package/skills/arkcli-usage/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: arkcli-usage
+version: 1.3.5
+description: "查询平台 Token/请求数、套餐额度快照、Agent Plan 按模型明细和团队席位用量。已发生调用的人民币金额、实际花费、用量折算费用优先转 arkcli-billing；目录询价转 pricing，明确要求按单价估算时才组合 usage 与 pricing。Coding Plan 只有额度快照，不提供按模型明细。席位列表/分配/轮换 Key 转 arkcli-plans；TTS/ASR 用量不支持查询。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli usage stats --help"
+---
+
+# arkcli usage
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md),其中包含认证闸门、配置排查与共享安全规则**
+**CRITICAL — `usage stats` 在执行之前,务必先用 Read 工具读取 [`references/arkcli-usage-stats.md`](references/arkcli-usage-stats.md),禁止直接盲目调用命令。**
+**CRITICAL — `usage plan` 在执行之前,务必先用 Read 工具读取 [`references/arkcli-usage-plan.md`](references/arkcli-usage-plan.md),禁止直接盲目调用命令。**
+**CRITICAL — `usage plan-details` 在执行之前,务必先用 Read 工具读取 [`references/arkcli-usage-plan-details.md`](references/arkcli-usage-plan-details.md),禁止直接盲目调用命令。**
+**CRITICAL — Coding Plan / Coding Plan Team 当前不提供按模型套餐明细。这类问题只能用 `usage plan --product coding-plan`（团队版用 `--product coding-plan-team`）给 quota 快照并明说能力边界；禁止改跑 `usage stats` 后把 platform / Endpoint Token 统计冒充 Coding Plan 套餐按模型明细。**
+**CRITICAL — 上述 Coding Plan 问题在本轮执行 `usage plan` 并说明边界后就停止。不主动追加 Endpoint / platform `usage stats`，因为它无法归因为 Coding Plan 套餐明细；只有用户在知道两者不同后另行明确要求「再看 platform / Endpoint 用量」，才开新查询。**
+**CRITICAL — `usage balance` 在执行之前,务必先用 Read 工具读取 [`references/arkcli-usage-balance.md`](references/arkcli-usage-balance.md),禁止直接盲目调用命令。**
+**CRITICAL — `usage seats` 在执行之前,务必先用 Read 工具读取 [`references/arkcli-usage-seats.md`](references/arkcli-usage-seats.md),禁止直接盲目调用命令。**
+
+> **数据时效(务必先看):`usage stats` 走的是上游 BFF 的聚合管道,数据有 5–30 分钟延迟,定位为「日级 / 聚合分析」。** 不要把它用于实时预算监控、限流、实时告警等需要秒级精度的控制场景——这类场景请直接读 `+chat` / `+gen` 等推理命令返回里的 `.usage` 字段(per-request、零延迟,详见 [arkcli-chat](../arkcli-chat/SKILL.md) 与 [arkcli-gen](../arkcli-gen/SKILL.md))。
+
+> **语音模型边界**：TTS / ASR / 配音 / 朗读 / 播客 / 音色 / 实时语音交互，或 `doubao-seed-tts-*` / `doubao-seed-asr-*` / `seedasr-*` 等广场语音模型，当前在 arkcli 只支持 `models search` 发现。不要用 `usage stats --model`、`usage plan-details` 或套餐/余额命令回答语音模型用量；直接说明 arkcli 不支持查询语音模型费用或用量。
+
+> **stats / plan / plan-details / balance 区分:**
+> - `stats` 出"按 token 计费的 inference 用量"(任何身份,5–30 分钟延迟)
+> - `plan` 出"订阅套餐的 quota 快照"(AgentPlan / CodingPlan 个人版 + 团队版的"我用了几成 / 几号刷新")
+> - `plan-details` 出"AgentPlan 按模型 / 套餐内外的时间序列调用明细"(AgentPlan 个人版 + 团队版,CodingPlan 没有按模型 endpoint)
+> - `balance` 出"还剩多少 X"(余额视角,`--type free-quota / media-asset / plan` 三选一)
+> - `seats` 出"团队席位**用量** admin 视角"(每个 seat 用了多少 / 套餐百分比;**只是用量视图**)。**席位的列表 / 绑定 / 分配 / API Key 轮换** 走 [`arkcli-plans`](../arkcli-plans/SKILL.md) 的 `plans team seat-list / seat-assign / rotate-apikey`。
+>
+> 用户问「我的套餐还剩多少额度」→ `plan` 或 `balance --type plan`(后者输出更精简);「我哪个模型用得最多」→ Agent Plan 用 `plan-details`，Coding Plan 只能用 `plan` 给 quota 快照并说明不支持按模型拆分;「我今天用了多少 token」→ `stats`;「我还剩多少免费额度 / 媒资库容量」→ `balance`;「**每个 seat 用了多少 / 团队席位用量分布**」→ `seats --with-usage`(纯管理类:谁绑了哪个 seat / 列出席位 / 分配席位 / 轮换 key → `arkcli-plans`)。
+
+## Step 0：先分金额、数量与额度，再确认身份
+
+先看用户要交付的单位；句子中出现“用量”不决定查询入口：
+
+- **已发生用量折算人民币 / 实际花费 / 应付账单**：先读取 [`arkcli-billing`](../arkcli-billing/SKILL.md)，按其日期、个人归属和 T+1 规则查实际应付。此分支在任何 `usage stats` 或价格查询之前执行。用户同时要调用量时再另查 Usage，分别交付。
+- **模型 / 套餐目录多少钱、每 Token 单价**：读取 Pricing 做询价，不查个人账单或用量。
+- **明确要求目录单价估算 / 预算预测**：才读取 Pricing，与用户指定范围的调用量组合；结果标“估算”，披露免费额度、折扣、缓存及结算差异。已有实际费用问题遇到 T+1 未出账时，报告未结算部分，不自动改成估算金额。
+
+用户已明确套餐名称时，直接用 `usage plan --product <plan>`；Agent Plan 按模型明细用 `usage plan-details --product <agent-plan|agent-plan-team> --start <日期>`。订阅属于账号/子用户，**不是由 active profile.type 决定**；platform profile 不等于没有套餐，也不需要为查询先切成 plan profile。
+
+- 平台 Token / 请求数 → `usage stats --start <日期>`；用户说“我的”时首条就带 `--mine`，追加 `--by model|endpoint|apikey` 不能删掉范围限制。
+- 套餐额度 → `usage plan` / `usage balance --type plan`；Agent Plan 明细 → `plan-details`；Coding Plan 只有 quota 快照，解释限制后停止，不补查平台桶冒充套餐明细。
+- “我的用量”未指明口径时，结合本轮上下文确认是平台 Token 还是套餐额度；仍有歧义就问这一项。只有用户明确要合并查看时才查多个桶，并分开报告，不能把百分比、AFP、Token 直接相加。
+- `subscribed:false` 只表示当前身份下该 SKU 没查到订阅，不证明其他身份无订阅，不触发自动切身份或平台查询。
+
+身份核对遵守当前宿主的共享协议；已有执行上下文可复用，缺少摘要且确需核实时用 `arkcli auth whoami --format json`。普通查询不调用可能同步/回写 Key 的 `profile show/list/keys list`。确需另一身份时先确认目标，不能静默切 Profile、Key、Project 或账号范围。
+
+**时间与交付：** `stats` / `plan-details` 必带 `--start`，没有 CLI 默认“近 7 天”；按用户时间词补齐 `--start/--end`，无日期时说明按今天查。长窗口按当前 reference 的限制分片，边界不重叠，保留用户原请求范围；无法覆盖的日期明确标注，不静默改成最近 30 天。回答同时标明口径、身份/范围、时间窗和数据延迟。
+
+### 数值与范围交付
+
+- `usage stats` 输出的顶层 `totals` 汇总本次所有返回记录；点名模型/品牌时按实际模型身份筛选并重新计算，不能把混合模型合计全归给目标模型。“我想查询”只是请求主语，不自动收窄为本人创建的资源；“我的用量/我创建的 Endpoint”才采用本人归属，且不改当前身份和 Project。
+- 套餐逐项以 `items[].product/edition/tier/seat_id` 标识身份，以同一项 `periods[].label/used/total/percent/reset_at` 生成正文和卡片；提交前比对二者数值、单位和周期。团队版和个人版不能因为档位名相同就复用额度；静态价格/套餐目录不能覆盖实时 `total`。
+- 排查套餐限额或交付额度快照时，按“套餐/版本/席位 → 周期 → 已用/总额/余量（原单位） → 已用百分比 → 重置时间（含时区）”逐项交付本轮返回值；卡片无法完整承载时用 Markdown 保留这些字段。只有同周期、同单位的真实 `used/total` 才计算余量；缺字段写未返回。不能只给百分比表而省略已有的绝对余量与重置时刻，也不能只摘一个健康窗口就宣称全部配额健康。
+- Coding Plan 仅有百分比、缺少 `used/total` 时只展示已有百分比与重置时间，不推算绝对额度、次数或 Token。缺字段、失败项和零消耗分开，不从另一个 SKU 填数。历史限额报错与当前快照分开标明，不能把当前未耗尽反推为历史报错不可能发生。
+
+### 限额报错：历史事实、当前快照与恢复条件
+
+用户贴出 `AccountQuotaExceeded` 或带重置时刻的套餐限额报错时，先保留原错误码、时间和已知套餐；需要错误目录解释时可转 [`arkcli-doctor`](../arkcli-doctor/SKILL.md)，近似错误码不能冒充原码。用 `usage plan` 查当前快照，按上方字段交付；查询失败或某桶失败时保留未知。
+
+- 原重置时刻已过去，只能说明那次窗口已经过去；当前快照未耗尽，只能证明本轮所查身份和套餐的额度状态。仍有新报错时需要它的时间、错误码、套餐/调用上下文；没有客户端日志，不把“自动重试旧请求”“客户端缓存”当成已知原因，也不由额度正常保证调用必然成功。
+- 恢复建议按实际 `product/edition` 区分。等待时引用对应窗口真实 `reset_at`；升配时转 [`arkcli-plans`](../arkcli-plans/SKILL.md) 并按该套餐文档说明生效条件，不把 Coding Plan 的时效规则推广到 Agent Plan。Agent Plan 文档中的“超额后付费”是有资格、服务开通和计费条件的恢复选项，不能笼统说所有套餐“只能等待”；Coding Plan 不自动继承该选项。
+- `usage plan` 的额度字段和 `plans get` 的订阅状态都不包含超额后付费开关，不能由这些返回值宣称已开启或已关闭。说明该选项会产生额外费用、需用户自行决定；本轮排障不启用开关、不升配、不切换收费路径，也不发送推理请求试探额度是否恢复。当前未超限时无需执行恢复操作。
+
+### 空结果与归属排查
+
+1. 区分命令失败、成功但空、存在 records 但合计为零；三者不能互相代替。
+2. 核对日期/时区、聚合延迟、所选口径、身份以及实际生效的 Project/过滤条件。近期记录未进入聚合不代表调用未发生；账号全范围不等于有所有资源权限，也不能先断言是 Project 隔离。
+3. Volc 个人平台统计仅在成功为空，或 CLI 明确报告本人没有 Endpoint 时，保留原日期/过滤条件改查 `--mine --mine-by=apikey`；已显式选 API Key 维度就不重复。鉴权、权限、网络错误不是空结果。CLI 提示 `omit --mine` 只列出另一种命令范围，不代表用户同意扩大查询。第二层为空或资源筛选失败时停在本人范围，分别报告空结果或未能取得结果；仅在用户另行明确要求后查询账号全量。无法获得新回复时保留范围和未知项，不用他人用量补齐。
+4. 平台 `records` 的 `ModelEndpoint` 可交给 `infer endpoint get <id>`；`AuthToken` 是 Key 掩码标识，可用 `apikey.list` 的元数据核对归属，后缀有冲突时报告歧义，不取明文、不轮换 Key。
+5. Agent Plan `plan-details` 不提供 Endpoint / API Key 级归属，查到模型/Harness 消耗即到边界；Coding Plan 无模型/Harness 明细。不能跨口径拼出不存在的调用归属，也不因 CLI 报错改用记忆/检索结果充当账号数据。
+
+## 适用场景
+
+- 查看当日或指定日期范围的推理用量(**接受 5–30 分钟延迟**)
+- 看订阅套餐(AgentPlan / CodingPlan)的配额消耗 / 重置时间
+- 看 AgentPlan 套餐内 vs 套餐外的按模型拆分明细
+- 按模型、接入点、API Key 维度分组统计(stats)
+- 分析 Token 消耗趋势、出对账报表
+- **不适用于语音模型用量**：用户问 TTS / ASR / 语音模型用了多少、剩余额度、调用次数时，不执行本 skill，转 `arkcli-models` 说明只支持广场发现
+
+## 业务定位
+
+- 本 skill 对应"看存量调用结果和消耗"的场景,是**离线 / 准实时**分析入口
+- 它通常发生在两类后置链路之后:
+  - Endpoint 已经存在,想按 endpoint 看使用情况
+  - 模型已经在被调用,想按 model / API Key 分析消耗
+  - 或:订阅了套餐,想看额度还剩多少
+- 它不是创建 Endpoint 的入口,也不是试用模型的入口
+- **它不是实时预算 / 限流 / 告警的数据源**——实时控制请走 per-request `.usage` 字段(见上方 banner)
+
+## 快速决策
+
+- 用户问"我的套餐还剩多少 / 用了几成 / 几号刷新 / 我有几个套餐":
+  - `arkcli usage plan`(默认探所有 4 个 SKU:personal × 2 + team × 2,subscribed 桶才下发 usage 请求)
+  - `arkcli usage plan --all`:不探订阅,4 桶全跑(诊断 / Excel)
+  - `arkcli usage plan --product=X`:跳过探测,单查
+  - **跟 `balance --type plan` 是同一份数据**;`usage plan` 输出完整(带 `subscribed` / `updated_at`),`balance --type plan` 精简(去掉元字段)。一般默认走 `usage plan`,只有用户明确把套餐余额跟"免费额度 / 媒资库容量"一起对账时,才走 `balance --type plan`(三 type 一起跑节省心智)
+- 用户问"我哪个模型用得最多 / 套餐内套餐外各占多少 / 团队某个子用户用得多":
+  - `arkcli usage plan-details --start <YYYY-MM-DD>`（Day 粒度，Agent Plan personal；显式补日期）
+  - `arkcli usage plan-details --product=agent-plan-team`(团队版,自动找 caller seat 或显式 `--seat <id>`)
+  - **Coding Plan 例外**：不执行 `plan-details` 或 `stats`；只执行 `arkcli usage plan --product coding-plan`(团队版用 `coding-plan-team`)，并明确该结果只是 quota 快照、不是本周按模型明细，然后停止。用户未另行要求 platform / Endpoint 用量时，不主动补跑 `usage stats`。
+- 用户问"我的用量 / 我今天用了多少 token / 我的 endpoint 消耗":
+  - 先按 Step 0 确定口径；明确的平台 Token / Endpoint 问题直接查下述平台桶，不因 profile.type 自动追加套餐查询。
+  - 如果用户点名的是语音模型或 TTS / ASR 场景 → **不要继续查 usage**；当前 arkcli 只承认语音模型广场发现，不支持语音模型用量查询
+  - **火山:** 先 `arkcli usage stats --start <YYYY-MM-DD> --mine`（默认 endpoint 维度）
+    - 返回 `data_count > 0` → 直接从 `totals` 取合计
+    - 返回 `data_count=0`（用户没有 Endpoint 或近期未通过 Endpoint 调用）→ 立即重试 `arkcli usage stats --start <YYYY-MM-DD> --mine --mine-by=apikey`
+    - 不自动退化为账号全量；第二层也成功为空时，可询问用户是否另查整个账号。明确同意后按 [stats 的第三层流程](references/arkcli-usage-stats.md#空结果的完整排查链) 保留其他参数、只移除 mine 限定，并标明“账号全量，可能包含其他用户”。这不是个人用量，也不授权切身份。
+- 用户问"我每个 APIKey 用了多少":
+  - **火山:** `arkcli usage stats --start <YYYY-MM-DD> --mine --mine-by=apikey`,从 `records[].AuthToken` 拆分
+- 用户问"我账上还有多少免费 token / 模型免费额度 / 媒资库还能存多少":
+  - `arkcli usage balance --type free-quota`(模型免费推理额度)
+  - `arkcli usage balance --type media-asset`(素材库容量)
+- 用户问"团队席位**用了多少** / 每个 seat 消耗 / 套餐百分比 by seat"(admin 用量视角):
+  - `arkcli usage seats --product agent-plan-team --with-usage`(列席位 + 每个 seat 的 AFP 用量)
+  - 不带 `--with-usage` 也行,但只有基础元数据,没有用量数字
+  - **路由分工**:本命令**只**回答"用量",不负责 seat 管理。"**列席位 / 谁绑了哪个 seat / 给员工分配席位 / 轮换席位 APIKey**" 全部走 [`arkcli-plans`](../arkcli-plans/SKILL.md) 的 `plans team seat-list / seat-assign / rotate-apikey`。Agent 路由这条问句先看动词:**"用了 / 消耗 / 多少"** 留这边,**"绑 / 列 / 分 / 轮换"** 跳过去 plans。
+- 数据看起来不对:先查认证和 profile,再怀疑数据本身
+
+## Agent 快速执行顺序
+
+1. 先按 Step 0 选定金额、数量或额度入口；需要核对缺失的身份摘要时遵循共享协议。
+2. 先做最小查询,再逐步加时间范围和分组条件
+3. 结果异常时,先检查 profile / region / API Key 来源是否正确,再怀疑数据本身
+4. 如果用户要按 endpoint 看 usage,最好先确认 endpoint-id 已知
+
+## 常见降级
+
+- 鉴权错误:转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md)
+- 查询范围或环境不对:转 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md)
+- 用户其实还没有 Endpoint,只是在准备正式接入:转 [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md)
+- 用户想看套餐**价格**(不是用量):转 [`../arkcli-pricing/SKILL.md`](../arkcli-pricing/SKILL.md)(`pricing plans` 出 catalog 询价,`usage plan` 出 quota 快照,两者是不同视角)
+- 用户想看**结算金额 / 账单 / 花了多少钱**(不是 token 用量):转 [`../arkcli-billing/SKILL.md`](../arkcli-billing/SKILL.md)(数据源是火山计费中心, T+1 出账; usage stats 是 BFF 推理聚合, 近实时)
+- 用户问语音模型 / TTS / ASR 的用量或额度:转 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) 只说明广场可搜与 arkcli 不支持用量查询，不转 pricing / billing
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| [`usage stats`](references/arkcli-usage-stats.md) | 查询推理用量(Token / 请求数,按日 / 小时聚合,按 token 计费的 inference 视角) |
+| [`usage plan`](references/arkcli-usage-plan.md) | 查询订阅套餐的额度快照(AgentPlan / CodingPlan,5h / weekly / monthly / session 周期的"用了多少 / 还剩多少 / 几号刷新")。默认探所有 4 个 SKU |
+| [`usage plan-details`](references/arkcli-usage-plan-details.md) | 查询 AgentPlan **个人版 + 团队版** 按模型 / Harness 的时间序列调用明细(套餐内 vs 套餐外拆分)。必传 `--start`，`--product=agent-plan-team` 切团队版 |
+| [`usage balance`](references/arkcli-usage-balance.md) | 余额视角统一入口 `--type free-quota / media-asset / plan`(模型免费推理额度 / 素材库容量 / 套餐余额) |
+| [`usage seats`](references/arkcli-usage-seats.md) | **Admin 视角** 列举企业版套餐下所有席位(SeatID / 绑定子用户 / billing 状态)。子用户调通常 AccessDenied |
+
+## 自然语言触发词表
+
+| 用户怎么说 | 对应命令 |
+|---|---|
+| "按模型明细 / 哪个模型用得最多 / 模型维度拆分 / 按模型时序 / 套餐内套餐外按模型" | `arkcli usage plan-details` |
+| "coding plan 按模型明细 / coding plan 套餐内套餐外" | `arkcli usage plan --product coding-plan`，并明说只支持 quota 快照、不支持按模型时序明细；禁止用 `usage stats` 冒充 |
+| "配额还剩多少 / 余额 / 还能用多少 / 用了几成 / 套餐额度" | `arkcli usage plan` 或 `arkcli usage balance --type plan` |
+| "免费额度还有多少 / 模型免费额度 / 免费 token" | `arkcli usage balance --type free-quota` |
+| "AFP 消耗 / 今日 AFP / 本周 AFP" | `arkcli usage plan`（AFP 就是套餐额度单位） |
+| "我的用量 / 我今天用了多少 token / 推理用量 / token 消耗" | `arkcli usage stats --start <YYYY-MM-DD> --mine` |
+
+## 参考
+
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) -- 先创建 Endpoint,再按 endpoint 看 usage
+- [arkcli-pricing](../arkcli-pricing/SKILL.md) -- catalog 询价(`pricing plans`),跟 `usage plan` quota 快照互补
+- [arkcli-shared](../arkcli-shared/SKILL.md) -- 认证和全局参数

package/skills/arkcli-usage/references/arkcli-usage-balance.md

@@ -0,0 +1,217 @@
+# usage balance
+
+> **前置条件:** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **跟 `stats` / `plan` 的区别(务必先看):**
+> - `stats` / `plan-details` — **消耗视角**(已经发生的 token / 调用)
+> - `plan` — 订阅套餐的 quota **快照**(已用 / 总额 / 重置时间)
+> - `balance` — **余额视角**,统一三类"还剩多少 X"的查询入口
+>
+> 用户问「我账上还有多少 X」时走 `balance`,根据 `--type` 分流到三类数据源。
+>
+> **`balance --type plan` 跟 `usage plan` 是同一份数据的两个入口**(都调 `QueryPlanUsage`,默认探所有 4 个 SKU,flag 完全一致)。区别只在投影:
+> - `balance --type plan` 精简版(去掉 `subscribed` / `updated_at`,补 `"not subscribed"` hint)
+> - `usage plan` 完整版(带 `subscribed: true/false`、CodingPlan 的 `updated_at` 等元字段)
+>
+> 用余额视角(配 free-quota / media-asset 一起看)走 `balance --type plan`;直接看套餐 quota 快照(配 stats / plan-details 一起看)走 `usage plan`。
+
+`arkcli usage balance` 是一个 dispatcher,`--type` 决定数据源。三类目的差异显著,**`--type` 必传**。
+
+## 命令
+
+```bash
+# 各模型的免费推理额度 / 资源包余额(走 ListModelChargeItems)
+arkcli usage balance --type free-quota
+arkcli usage balance --type free-quota --model doubao-seed-1-6
+arkcli usage balance --type free-quota --modality LLM --page-size 20
+
+# 媒资库容量(走 /open/GetAssetQuota)
+arkcli usage balance --type media-asset
+arkcli usage balance --type media-asset --project my-project
+
+# 订阅套餐余额(走 QueryPlanUsage,精简版输出)
+arkcli usage balance --type plan
+arkcli usage balance --type plan --product agent-plan
+arkcli usage balance --type plan --all
+```
+
+## 参数白名单
+
+`--type` 是必填,其它 flag **按 type 分组**;跨 type 误传会报 `ErrValidation`(不静默忽略,避免用户以为过滤生效了但实际没生效)。
+
+| `--type` | 允许的额外 flag |
+|---|---|
+| `free-quota` | `--model` `--modality` `--page-number` `--page-size` |
+| `media-asset` | `--project` |
+| `plan` | `--product` `--all` `--seat` |
+
+### `--type free-quota`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `--model` | string | 单基础模型名;不传 = 列全量已开通模型 |
+| `--modality` | string | 后端 `FoundationModelDomain` 枚举:`LLM` / `ComputerVision` / `Audio` / `Embedding` / `Router`(**不接受别名**) |
+| `--page-number` | int | 页码,1-based |
+| `--page-size` | int | 每页条数,默认 50 |
+
+### `--type media-asset`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `--project` | string | 项目名;不传走当前 profile.ProjectName |
+
+### `--type plan`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `--product` | string | `agent-plan` / `coding-plan` / `agent-plan-team` / `coding-plan-team` |
+| `--all` | bool | 查所有个人版 plan 即使未订阅(跟 `--product` 互斥) |
+| `--seat` | string | 仅 team 版,过滤单席位 |
+
+## 返回值
+
+### `--type free-quota`
+
+```json
+{
+  "page_number": 1,
+  "page_size": 50,
+  "total_count": 7,
+  "items": [
+    {
+      "model": "doubao-seed-1-6",
+      "display_name": "Doubao Seed 1.6",
+      "vendor": "Doubao",
+      "state": "Available",
+      "is_overdue": false,
+      "free_usage": { "total": 500000, "consumed": 12345, "remaining": 487655 },
+      "resource_packs": [
+        {
+          "type": "FreeInference",
+          "total": 500000, "consumed": 12345, "remaining": 487655,
+          "reclaimed": 0, "sync_time": "2026-06-04T12:00:00Z"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**关键口径**:
+
+- `free_usage.remaining = total - consumed`,**已经算好**,不要让 agent 自己算
+- 没有任何余额信息(`free_usage` 和 `resource_packs` 都空)的模型行**不会输出**——`pricing models` 才出全表
+- `resource_packs[].type` 当前火山只有两个值:`FreeInference`(免费推理) / `DataPermission`(数据权限)。**没有 finetune 资源包**,`Finetune` / `LoraFinetune` 是定价单价(`pricing models` 的 `ChargeItems.Type`),不是余额维度
+- 资源包 `remaining` **可能为负**(过期降档时 `consumed > total`),不要 clamp
+
+### `--type media-asset`
+
+```json
+{
+  "tier": "advanced_monthly",
+  "assets":      { "total": 100000, "used": 23456, "remaining": 76544, "percent": 23.456 },
+  "asset_groups":{ "total": 100,    "used": 12,    "remaining": 88,    "percent": 12.0 },
+  "shared_pool": { "total": 1000000,"used": 0,     "remaining": 1000000,"percent": 0 },
+  "write_qpm": 600,
+  "capabilities": { "liveness_writable": true, "aigc_readable": true },
+  "projects": [
+    { "project_name": "default", "used": 23456, "allocated": false, "allocation": 0 }
+  ],
+  "updated_at_ms": 1717488000123
+}
+```
+
+**关键口径**:
+
+- `tier` 取值:`free` / `advanced` / `premium` / `advanced_monthly` / `premium_monthly`(月付与年付共用展示)。空值意味着账号没订阅媒资库 → 后端返 free tier 零容量
+- **`used > total` 是合法状态**(过期降档时 `tier` 降到 `free` 但 `used` 保留旧值),`percent` 可 > 100,`remaining` 可为负 — **不 clamp**
+- `shared_pool` 在没启用共享池的账号下被省略(全 0 不输出)
+- `capabilities` 只列**已开启**的能力,空 map 意味着所有能力都关
+- `projects[]` 只在**项目级配额分配生效**的企业账号下有数据,个人账号通常空数组
+
+### `--type plan`
+
+```json
+{
+  "viewer": {
+    "auth_method": "sso",
+    "user_id": "12345",
+    "user_name": "alice",
+    "is_root": false,
+    "profile": "my-profile",
+    "tenant": "volc",
+    "region": "cn-beijing"
+  },
+  "items": [
+    {
+      "product": "agent-plan",
+      "edition": "personal",
+      "tier": "small",
+      "periods": [
+        { "label": "5h",     "used": 10, "total": 100, "percent": 10, "reset_at": "2024-06-04T17:00:00+08:00" },
+        { "label": "weekly", "used": 50, "total": 1000, "percent": 5, "reset_at": "2024-06-11T08:00:00+08:00" }
+      ]
+    },
+    {
+      "product": "agent-plan-team",
+      "edition": "team",
+      "tier": "large",
+      "seat_id": "seat-001",
+      "periods": [
+        { "label": "5h",      "used": 50,    "total": 200,    "percent": 25, "reset_at": "2024-06-04T17:00:00+08:00" },
+        { "label": "weekly",  "used": 800,   "total": 5000,   "percent": 16, "reset_at": "2024-06-11T08:00:00+08:00" },
+        { "label": "monthly", "used": 4000,  "total": 20000,  "percent": 20, "reset_at": "2024-06-29T05:06:40+08:00" }
+      ]
+    },
+    {
+      "product": "coding-plan",
+      "edition": "personal",
+      "error": "not subscribed"
+    }
+  ]
+}
+```
+
+**关键口径**:
+
+- **顶层 `viewer`**:身份摘要(子用户 vs root,SSO/AKSK/APIKey)。让 agent 区分"我看的是自己的 vs 主账号的 vs 别人"。详见 [`usage plan` 文档的 viewer 章节](arkcli-usage-plan.md#viewer-字段身份摘要)
+- **默认探所有 4 个 SKU**(personal × 2 + team × 2)— 一次拉全你账号下的所有套餐余额。要单查传 `--product=X`
+- 比 `usage plan` **精简**:去掉 `subscribed` / `update_timestamp` 元字段;`error` 保留(用于区分"未订阅" / "AccessDenied" / "no seat bound")
+- `error: "not subscribed"` 是 balance 层补的 hint,后端原始是 `Subscribed=false` + 空 periods,直接展示对用户不可读
+- **Team 套餐自动找 caller seat**:不传 `--seat` 时 service 层自动调 `GetSeatInfo` 找你绑定的席位。订了套餐但没分到席位时返 `error: "no seat bound to caller for ..."`(区分于"未订阅")
+- `coding-plan` 后端只返 `percent`,`used` / `total` 字段缺(JSON `omitempty` 不出现)
+- `periods[].reset_at` 跟 `usage plan` 同 schema,输出 **RFC3339 北京时间(UTC+08:00)**;周期内无数据时不输出该字段
+
+## Agent 决策
+
+| 用户问法 | 命令 |
+|---|---|
+| 我哪些模型还有免费额度 | `arkcli usage balance --type free-quota` |
+| 模型 X 还能用多少 token | `arkcli usage balance --type free-quota --model X` |
+| 媒资库还能上传多少 / 容量满了吗 | `arkcli usage balance --type media-asset` |
+| 我的套餐还能用多少 / 几号刷新 | `arkcli usage balance --type plan`(自动探所有订阅) |
+| 我特定 product 的套餐余额 | `arkcli usage balance --type plan --product agent-plan-team` |
+| Admin 视角看其他席位用量 | `arkcli usage balance --type plan --product agent-plan-team --seat <id>` |
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|---|---|---|
+| `--type is required` | 没传 `--type` | 三选一:`free-quota` / `media-asset` / `plan` |
+| `--product is not valid for --type free-quota` | 跨 type flag | 检查 flag 跟 `--type` 是否匹配(见上表) |
+| `tier` 为空 + 全部 0 | 账号没订阅媒资库 | 后端返 free tier 零容量,没问题;要订阅请走火山方舟控制台 |
+| `foundation model "X" not found in pricing list` (exit=2) | `--model X` 名字打错或不在 pricing list | 检查拼写;或不传 `--model` 拉全量看支持的名字 |
+| `free-quota` 返回 `items: []` | `--modality` 传了别名(`text` / `video`)而不是后端枚举(没传 `--model` 时才会走到这条) | 翻译成 `LLM` / `ComputerVision` 再传 |
+| plan 行 `error: "no seat bound"` | 团队版订了但 caller 没分到席位 | 联系 admin 分配席位,或传 `--seat <id>` 显式指定 |
+
+## 跟其它命令的关系
+
+- 想看**单价**(每千 token 多少钱)→ [`arkcli pricing models`](../../arkcli-pricing/references/arkcli-pricing-models.md)
+- 想看**已经消耗**(token / 调用次数)→ [`stats`](arkcli-usage-stats.md) / [`plan-details`](arkcli-usage-plan-details.md)
+- 想看**订阅套餐 quota 快照(完整版,带 subscribed / 时间戳)**→ [`usage plan`](arkcli-usage-plan.md)
+
+## 参考
+
+- [arkcli-usage](../SKILL.md) — usage skill 概览
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — 认证和全局参数
+- [arkcli-pricing](../../arkcli-pricing/SKILL.md) — 定价目录视角

package/skills/arkcli-usage/references/arkcli-usage-plan-details.md

@@ -0,0 +1,136 @@
+# usage plan-details
+
+> **硬边界：本命令仅支持 `agent-plan` / `agent-plan-team`。Coding Plan 问题不得调本命令，也不得改跑 `usage stats` 后把 platform / Endpoint Token 统计表述成 Coding Plan 套餐明细；只能用 `arkcli usage plan --product coding-plan`（团队版用 `--product coding-plan-team`）返回 quota 快照，并向用户说明当前没有按模型时序明细能力。**
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **跟 `usage plan` / `usage stats` 的关系（务必先看）：**
+> - `usage plan` — AgentPlan / CodingPlan **额度快照**(5h / weekly / monthly 用了多少 / 还剩多少 / 几号刷新)
+> - `usage plan-details` — **AgentPlan 个人版**按模型 / Harness 的**时间序列调用明细**(每个 ObjectName 在每个时间桶的 token / 张数,以及套餐内 vs 套餐外计费)
+> - `usage stats` — 按 token 计费的 inference 用量(任意身份,跟订阅无关)
+>
+> 用户问「我哪个模型用得最多 / 套餐内用了多少 / 套餐外又用了多少」走 plan-details;问"还剩多少额度"走 plan。
+
+查询 AgentPlan 套餐的 Model / Harness 调用明细时间序列。**支持个人版 (默认) + 团队版**(`--product=agent-plan-team`)。CodingPlan 后端没暴露按模型的明细 API,传 `coding-plan` 类 product 直接 ErrValidation。
+
+## 命令
+
+```bash
+# 个人版,默认近 7 天 Day 粒度
+arkcli usage plan-details
+
+# 指定时间范围
+arkcli usage plan-details --start 2026-05-01 --end 2026-05-31
+
+# Hour 粒度 (单次范围 ≤ 31 天约束不变)
+arkcli usage plan-details --start 2026-06-01 --end 2026-06-04 --interval Hour
+
+# 过滤到特定模型 (--model 可重复)
+arkcli usage plan-details --model doubao-1-5-pro
+
+# === 团队版 ===
+# 自动找 caller 绑定的 seat,跟 usage plan team 一样
+arkcli usage plan-details --product agent-plan-team
+
+# 显式指定一个或多个 seat (admin 视角看其他 seat,可重复)
+arkcli usage plan-details --product agent-plan-team --seat seat-001
+arkcli usage plan-details --product agent-plan-team --seat seat-001 --seat seat-002
+
+# 全队聚合 (admin 全景视图,自动 ListSeatInfos 列全队后批量查)
+arkcli usage plan-details --product agent-plan-team --all-seats
+
+# Admin server-side 按子用户过滤 (后端 Filter,跟 --all-seats 配套用最方便)
+arkcli usage plan-details --product agent-plan-team --all-seats --seat-user-name alice
+arkcli usage plan-details --product agent-plan-team --all-seats --seat-user-id 12345
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--start` | **是** | string | 开始日期(`YYYY-MM-DD`)。后端约束: 单次范围 ≤ 31 天 / 历史 ≤ 6 个月 |
+| `--end` | 否 | string | 结束日期(`YYYY-MM-DD`,闭区间)。默认今天 |
+| `--interval` | 否 | string | 查询粒度: `Day`(默认) / `Hour`。大小写不敏感 |
+| `--model` | 否 | []string | 对客模型 / Harness 名称,可重复 |
+| `--product` | 否 | string | `agent-plan`(默认,个人版,OpenAPI)\| `agent-plan-team`(团队版,**OpenAPI**,AK/SK + SSO 都行) |
+| `--seat` | 否 | []string | **仅团队版**;SeatID 可重复(单次最多 1000)。不传时默认 `GetSeatInfo` 找 caller 单 seat |
+| `--all-seats` | 否 | bool | **仅团队版,admin 视角**;先 `ListSeatInfos` 列全队 SeatIDs 再批量查。`--seat` 显式给值时优先,`--all-seats` 被覆盖 |
+| `--seat-user-id` | 否 | []string | **仅团队版,admin 视角**;server-side 按子用户 ID 过滤(可重复) |
+| `--seat-user-name` | 否 | []string | **仅团队版,admin 视角**;server-side 按子用户名过滤(可重复) |
+
+### 后端约束(client-side 校验)
+
+- **单次范围 ≤ 31 天**(`end - start`):超出立即 ErrValidation 不发请求
+- **历史窗口 ≤ 6 个月**(`end` 离 now 不能超过 ~180 天):超出立即 ErrValidation
+- **end ≥ start**:反向时间范围立即 ErrValidation
+- 时间格式必须 `YYYY-MM-DD`,其它格式立即 ErrValidation
+
+## 返回值
+
+JSON 形态:
+
+```json
+{
+  "details": [
+    {
+      "time": 1717000000000,
+      "object_name": "doubao-1-5-pro",
+      "usage": 1024,
+      "unit": "Tokens",
+      "billing_type": "WithinPlan"
+    },
+    {
+      "time": 1717000000000,
+      "object_name": "doubao-1-5-pro",
+      "usage": 256,
+      "unit": "Tokens",
+      "billing_type": "OutsideOfPlan",
+      "seat_id": "seat-001"
+    }
+  ]
+}
+```
+
+### 字段说明
+
+| 字段 | 说明 |
+|---|---|
+| `time` | 时间桶起点,**epoch ms**(后端 IDL 标 ms,跟 `usage plan` 的 CodingPlan ResetTimestamp 不同,这里不需要换算) |
+| `object_name` | 对客展示的模型 / Harness 名称(如 `doubao-1-5-pro`) |
+| `usage` | 该 (time, object_name, billing_type) 三元组的用量。整数,单位看 `unit` |
+| `unit` | `Tokens` / `Images` / 其它(后端按模型类型决定) |
+| `billing_type` | `WithinPlan`(套餐内,免费配额消耗)/ `OutsideOfPlan`(套餐外,走基础按 token 计费) |
+| `seat_id` | **仅团队版**填充(`SeatUsageDetails[]` 展平时附带);个人版不出此字段 |
+
+> **聚合提示**: 同一时间点可能 `WithinPlan` + `OutsideOfPlan` 两行并列。对接时:
+> - 想看「这个模型今天总共调用了多少 token」→ 同 object_name 行 `usage` 累加
+> - 想看「套餐内 vs 套餐外的用量比」→ 按 `billing_type` 分组合计
+
+## V1 限制
+
+- **仅 AgentPlan 个人版**(`profile.Type=agent-plan` 或当前身份名下有 AgentPlan personal 订阅时数据非空)。AgentPlan 团队版(席位维度明细)对应后端 endpoint `GetSeatUsageDetails`,V1 未实装
+- **不依赖 `ListAgentPlanModelMappingMeta`**: 控制台用它做"模型下拉框 + 'all models' 时塞全量 ObjectName 列表",CLI V1 简化掉:不传 `--model` 就让后端返聚合行,要拆模型自己传 `--model`
+- **没有 PlanType filter**: 后端支持按套餐档位过滤(small/medium/large/max),CLI V1 没暴露;通常按身份当前生效订阅自动返,用户没有跨档位查询的必要
+- **CodingPlan 不支持**: CodingPlan 后端没有按模型的调用明细 API(其 `GetCodingPlanUsage` 只返周期 `Percent`),这条命令对 CodingPlan profile 也只能查 AgentPlan,**故不开 `--product` flag**
+
+## AI Agent 决策路径
+
+- 用户问「我哪个模型用得最多 / 套餐内套餐外各占多少」→ `arkcli usage plan-details`(默认近 7 天聚合)
+- 用户问「上周哪天 token 消耗最大」→ `--start 2026-05-26 --end 2026-06-01`,output 按 `time` 排序
+- 用户问「按小时看 5/15 当天的调用」→ `--start 2026-05-15 --end 2026-05-15 --interval Hour`
+- 用户问「`doubao-1-5-pro` 的趋势」→ `--model doubao-1-5-pro`(单模型时间序列,套餐内+套餐外两行/桶)
+- 用户问「我的套餐用了百分之几 / 几号刷新」→ 这条命令是**逐次累加视角**,看 quota 快照走 [`usage plan`](arkcli-usage-plan.md)
+- 用户问「按 token 计费的 inference 用量,不是套餐」→ 转 [`usage stats`](arkcli-usage-stats.md)
+
+## 错误降级
+
+- **未订阅 AgentPlan**: 后端返 Result=nil,CLI 输出 `{"details":[]}`(空数组而非 null)。要确认是不是订阅问题,先跑 `arkcli usage plan --product=agent-plan` 看 `subscribed` 字段
+- **AccessDenied**: 通常是 sub-user 没 AgentPlan 权限,转 [arkcli-auth](../../arkcli-auth/SKILL.md) 排查身份
+- **范围错误**: 看 ErrValidation 提示(31 天限 / 6 月历史窗口 / YYYY-MM-DD 格式)直接修 flag
+
+## 调用面对齐
+
+- 个人版调 OpenAPI **`/open/GetUsageDetails`**(AK/SK + SSO 都支持);arkcli 用公网 OpenTOP 不带 AgentPlan 前缀的入口
+- 团队版调 OpenAPI **`/open/GetSeatUsageDetails`** + **`/open/GetSeatInfo`**(找 caller seat),都是公网入口,AK/SK + SSO 都行
+- 默认窗口 `今天 - 6 天 ~ 今天`
+- 后端 31 天 / 6 月窗口约束 client-side 前置校验,不发请求,把错误暴露在 CLI 层