@volcengine/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.2e2d76ea86c4

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

@@ -0,0 +1,166 @@
+# usage plan
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **跟 `stats` / `billing` 的区别（务必先看）：**
+> - `usage stats` — 按 token 计费的 **inference 用量**（按时间序列,有 5–30 分钟延迟）
+> - `billing list` — 按月**结算金额**(火山计费中心拆账,T+1 出账)
+> - `usage plan` — **订阅类套餐(AgentPlan / CodingPlan)的 quota 快照**(后端"我的套餐"实时数据,跟火山方舟控制台 1:1)
+>
+> 用户问「我用了多少 token / 多少次请求」走 stats;问「花了多少钱」走 billing;问「我的套餐还剩多少额度 / 用了百分之几 / 几号刷新」走 **plan**。
+
+查询订阅套餐的额度用量快照。Plan 不是按时间序列查,而是**按时间窗口(5h / weekly / monthly / session)给当前生效订阅的"已用 / 总额 / 重置时间"**。
+
+当前 `periods[].total` 与历史档位 AFP 表不同，只能报告当前快照的产品、档位、时间窗口、数值及查询时间；它不证明按剩余天数折算、权益缩水、赠送或升降档。没有当前订单周期或官方权益规则证据时，差异原因明确标为未知。`reset_at` 是额度窗口刷新时间，不是订阅到期时间；到期查询转 Plans。
+
+## 命令
+
+```bash
+# 默认:并发 ListSubscribeTrade × 4 探所有 SKU (personal × 2 + team × 2),
+# 探到的桶才下发 usage 请求 — 一次拉全你账号下所有生效订阅的余额
+arkcli usage plan
+
+# 纯人读额度卡片 (不输出 JSON；管道下也去 ANSI)
+arkcli usage plan --render
+
+# 显式指定 product (跳过订阅探测,直接单桶查)
+arkcli usage plan --product agent-plan
+arkcli usage plan --product coding-plan
+arkcli usage plan --product agent-plan-team
+arkcli usage plan --product coding-plan-team
+
+# 强制查所有 4 个桶 (personal + team), 不管订阅与否 (诊断 / Excel 视角)
+arkcli usage plan --all
+
+# Team 版查指定席位 (绕过 GetSeatInfo 的自动 caller seat 解析)
+arkcli usage plan --product agent-plan-team --seat seat-001
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--product` | 否 | string | 显式 product id: `agent-plan` / `coding-plan` / `agent-plan-team` / `coding-plan-team`。不传则默认走自动探订阅 |
+| `--all` | 否 | bool | 强制查所有 4 个 product,没订阅的桶 endpoint 自己返 subscribed=false 行。**跟 `--product` 互斥** |
+| `--seat` | 否 | string | 仅 team product 有意义。不传时 service 层自动调 `GetSeatInfo` 找 caller 绑定的 seat;传了则跳过该 RPC,直接用提供的 SeatID(管理员视角查别人的 seat) |
+| `--render` | 否 | bool | 只输出人读额度卡片，不输出 JSON。TTY 下彩色，管道/重定向下保留 Unicode 进度条但去 ANSI；不能与显式 `--format` / `--transform` 混用 |
+
+## 默认行为(无 `--product` / `--all`)
+
+不传任何 product 时,**默认行为统一**(profile.Type 不再参与派生 — 历史版本曾按 profile 单桶查,V2 起改为统一探所有订阅,因为同一身份常常同时订了多个 product):
+
+1. 4 桶并发探订阅状态:
+   - **Personal × 2** 走 `ListSubscribeTrade`(`ResourceNames=[RealAgentPlanPersonal]` / `[""]`)
+   - **Team × 2** 走 `GetSeatInfo(Scene="agent_plan_enterprise" / "")`(企业版不在 ListSubscribeTrade 暴露,实测返 null;改通过 caller seat 绑定状态探)
+2. 探到的桶下发对应 usage RPC:
+   - `agent-plan` (personal) → `GetAFPUsage`
+   - `coding-plan` (personal) → `GetCodingPlanUsage`
+   - `agent-plan-team` → 已经拿到 SeatID → `GetSeatAFPUsage(SeatIDs=[id])`
+   - `coding-plan-team` → 已经拿到 SeatID → `GetSeatInfoUsage(SeatID=id, Scene="")`
+3. 一桶失败不挡其它桶 (per-bucket error isolation)
+
+> **多 1 次 RPC 换零 flag 体验**:`ListSubscribeTrade × 2 + GetSeatInfo × 2` 并发约 ~50ms,远低于循环逐 product 查的成本。要跳过这个探测就传具体 `--product`。
+>
+> **Team 桶静默规则**:caller 没绑 seat 时,team 桶在默认探测里**不出现**(避免 admin 没买企业版还看到 "no seat bound" 误导)。要看完整 4 桶(包括 "no seat bound" error 行)用 `--all` 强制。
+
+## 返回值
+
+JSON 形态(顶层 `viewer` + `items` 数组):
+
+```json
+{
+  "viewer": {
+    "auth_method": "sso",
+    "is_root": false,
+    "user_id": "12345",
+    "user_name": "alice",
+    "account_id": "210000",
+    "profile": "my-profile",
+    "tenant": "volc",
+    "region": "cn-beijing",
+    "project_name": "default"
+  },
+  "items": [
+    {
+      "product": "agent-plan",
+      "edition": "personal",
+      "tier": "medium",
+      "subscribed": true,
+      "periods": [
+        { "label": "5h",      "used": 250,    "total": 1000,   "percent": 25,   "reset_at": "2024-05-30T05:26:40+08:00" },
+        { "label": "weekly",  "used": 12500,  "total": 50000,  "percent": 25,   "reset_at": "2024-06-06T00:26:40+08:00" },
+        { "label": "monthly", "used": 50000,  "total": 200000, "percent": 25,   "reset_at": "2024-06-29T05:06:40+08:00" }
+      ]
+    },
+    {
+      "product": "agent-plan-team",
+      "edition": "team",
+      "tier": "large",
+      "seat_id": "seat-001",
+      "subscribed": true,
+      "periods": [...]
+    }
+  ]
+}
+```
+
+### `viewer` 字段(身份摘要)
+
+```
+viewer.auth_method  = sso | aksk | apikey | none
+viewer.is_root      = SSO 主账号(JWT trn 带 :root)
+viewer.user_id      = SSO 子用户 ID(AK/SK / APIKey 通常空)
+viewer.user_name    = SSO 子用户名
+viewer.account_id   = JWT sub claim
+viewer.profile      = 当前激活 profile 名
+viewer.tenant       = volc
+viewer.region       = active region
+viewer.project_name = active project
+```
+
+**用途**:子用户跟主账号视图易混淆 — `viewer` 字段告诉用户/agent"这条数据是给谁看的"。具体匹配规则:
+- 子用户 SSO 登录 → `is_root=false`,`user_id` / `user_name` 是子用户身份,看到的是这个子用户绑定的 seat
+- 主账号 SSO 登录 → `is_root=true`,看到的是主账号视图(整个 account 下的订阅)
+- AK/SK 登录 → `auth_method=aksk`,`user_id` 通常空,后端按 AK/SK 解析的 IAM 身份找数据
+- APIKey 登录 → `auth_method=apikey`,数据范围跟 API Key 绑定的身份对齐
+
+### 字段说明
+
+| 字段 | 说明 |
+|---|---|
+| `product` | `agent-plan` / `coding-plan` / `agent-plan-team` / `coding-plan-team`(跟 `profile.Type` 一致) |
+| `edition` | `personal` / `team` |
+| `tier` | 实际订阅档位(`small/medium/large/max` 或 `lite/pro`),由后端返;AgentPlan 才有,CodingPlan 通常缺 |
+| `subscribed` | 当前身份是否有有效订阅。AgentPlan: `Result != nil`; CodingPlan: `QuotaUsage` 数组非空 |
+| `periods[].label` | AgentPlan: `5h` / `weekly` / `monthly`(后端返的 `daily` 不展示)。CodingPlan: `session` / `weekly` / `monthly`,按 canonical order 稳定排序 |
+| `periods[].used` / `total` | AgentPlan 给的是绝对值,CodingPlan 后端只返 `Percent`,`used`/`total` 字段缺(JSON 通过 `omitempty` 不出现) |
+| `periods[].percent` | 已用百分比(0-100). AgentPlan 由 `used/total*100` 算; CodingPlan 直接透传后端 `Percent` |
+| `periods[].reset_at` | 下次刷新时间,**RFC3339 北京时间(UTC+08:00)**。service 内部仍把 AgentPlan 后端 ms / CodingPlan 后端秒统一成 epoch ms,输出层再格式化;周期内无数据的 sentinel 不输出该字段 |
+| `updated_at` | 仅 CodingPlan,后端 `UpdateTimestamp` 透传(epoch ms) |
+| `error` | 该桶失败原因(per-bucket error isolation,一桶失败不挡其它桶)。team product NotImpl 也走这个字段 |
+
+## 错误处理
+
+- **AccessDenied / 网络错误**: 写到对应 `items[].error`,其它桶不受影响,整体不阻塞
+- **未订阅**: AgentPlan `Result=nil` → `subscribed: false, periods: []`; CodingPlan `QuotaUsage` 空 → 同样 `subscribed: false`
+- **Team 订了但 caller 没绑 seat**: `subscribed: true` + `error: "no seat bound to caller for ..."`(区分于"未订阅"),传 `--seat <id>` 显式指定可绕过
+- **typo product**: 不在 `agent-plan` / `coding-plan` / `*-team` 集合内 → ErrValidation 立即返,不发请求
+- **`--all` + `--product` 同传**: ErrValidation 互斥
+- **自动探全失败**: 上抛 `auto-discover subscriptions: <err>`(如 `MissingParameter.ResourceNames` 之类的后端拒绝),提示用户改用显式 `--product`
+
+## AI Agent 决策路径
+
+- 用户问「我的套餐用了多少 / 还剩多少」→ `arkcli usage plan`(默认探所有订阅,一把拉全)
+- 用户问「我有几个套餐」→ `arkcli usage plan --all`(展开所有 4 个桶,subscribed=true 的就是有的)
+- 用户问「team 套餐 admin 视角看其他 seat 用量」→ `arkcli usage plan --product agent-plan-team --seat <id>`
+- 用户问「为啥 plan 出了空 items」→ 大概率当前身份名下所有 product 都没订阅,转 [arkcli-pricing](../../arkcli-pricing/SKILL.md) 查 catalog 价格
+- 用户问「按模型看我哪个模型用得多」→ 这条命令只给 quota 快照,**没有按模型的拆分**,转 [`usage plan-details`](arkcli-usage-plan-details.md)(仅 AgentPlan)
+
+## 调用面对齐
+
+- AgentPlan personal: `/open/GetAFPUsage`(OpenAPI,AK/SK + SSO 都支持)。arkcli 用公网 OpenTOP 入口,不带 AgentPlan 前缀
+- CodingPlan personal: `/open/GetCodingPlanUsage`(OpenAPI)
+- AgentPlan team: `/open/GetSeatAFPUsage`(**公网 OpenAPI**,AK/SK + SSO 都可调)。arkcli 用公网 OpenTOP 不带 AgentPlan 前缀的入口
+- CodingPlan team: `/open/GetSeatInfoUsage`(OpenAPI)
+- 自动探的 `ListSubscribeTrade` payload(personal × 2);**企业版**不在 `ListSubscribeTrade` 暴露,改通过 `GetSeatInfo(Scene)` 探 caller seat 绑定状态
+- Team SeatID 解析: `/open/GetSeatInfo` 不传 SeatID,后端按 caller 身份 + Scene 返绑定的 seat。**Scene 必须用 `agent_plan_enterprise`**(AgentPlan 企业版)或**空字符串**(CodingPlan 企业版,后端默认即 enterprise)— 早期错用 `agent_plan` / `coding_plan` 会返空 SeatID 不报错

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

@@ -0,0 +1,194 @@
+# usage seats
+
+> **前置条件:** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **跟其它命令的区别:**
+> - `usage plan` / `balance --type plan` — **caller 自己**的订阅余额(子用户视角看自己的 seat)
+> - `usage seats` — **admin 视角** 列举团队下**所有 seat**(管理员看团队席位)
+>
+> 子用户调 `usage seats` 通常 `AccessDenied`(后端权限校验)。需要 admin / root SSO 身份。
+
+## 命令
+
+```bash
+# 列出 AgentPlan 团队版下所有 seat (默认自动翻页直到末页)
+arkcli usage seats --product agent-plan-team
+
+# 列出 CodingPlan 团队版的所有 seat
+arkcli usage seats --product coding-plan-team
+
+# 按 BizInfo 档位过滤
+arkcli usage seats --product agent-plan-team --biz-info large
+
+# 按 BillingStatus 过滤(回收态准备清理)
+arkcli usage seats --product agent-plan-team --billing-status Reclaimed
+
+# 查特定子用户绑定的 seat
+arkcli usage seats --product agent-plan-team --user-id 12345
+arkcli usage seats --product agent-plan-team --user-name alice
+
+# 多个用户(client-side fan-out 并行查 N 次再合并)
+arkcli usage seats --product agent-plan-team --user-name alice --user-name bob --user-name charlie
+
+# 跨字段组合 = AND (alice 名下的 + 状态是 Running 的)
+arkcli usage seats --product agent-plan-team --user-name alice --billing-status Running
+
+# 单页查询(关闭 auto-paginate)
+arkcli usage seats --product agent-plan-team --page-number 1 --page-size 50
+
+# === --with-usage:同时拉每个 seat 的用量 ===
+arkcli usage seats --product agent-plan-team --with-usage   # AFP 用量(used/total/percent)
+arkcli usage seats --product coding-plan-team --with-usage  # 仅 percent(CodingPlan 后端只暴露百分比)
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|---|---|---|---|
+| `--product` | 是 | string | 团队版 plan id:`agent-plan-team` / `coding-plan-team`。**personal 不支持**(没 seat 概念) |
+| `--biz-info` | 否 | string | 档位过滤:`small/medium/large/max`(AgentPlan)\|`lite/pro`(CodingPlan) |
+| `--billing-status` | 否 | string slice | 计费状态(可重复):`Pending` / `Running` / `Expired` / `Reclaimed` |
+| `--seat-status` | 否 | string | 席位状态:`Idle` / `Active`;`Idle` 表示未绑定,`Active` 表示已绑定 |
+| `--user-id` | 否 | string slice | 按子用户 ID 过滤(可重复;>1 触发 client-side fan-out 并行查) |
+| `--user-name` | 否 | string slice | 按子用户名字过滤(可重复;>1 触发 client-side fan-out 并行查) |
+| `--seat-id` | 否 | string slice | 指定具体 SeatID(可重复;wire 原生 array,单次调用) |
+| `--project` | 否 | string | 项目过滤;不传走 active profile project |
+| `--page-size` | 否 | int | 单页大小,默认 100 |
+| `--page-number` | 否 | int | 1-based 页码;**显式传则关闭 auto-paginate**,只拉单页 |
+| `--sort-by` / `--sort-order` | 否 | string | 排序字段 / 升降序 |
+| `--with-usage` | 否 | bool | **Team product only**:join 每个 seat 的用量。AgentPlan team 走 `ListSeatAFPUsage` 出 `afp_usage{plan_type, periods[5h/weekly/monthly with used/total/percent/reset_at]}`;CodingPlan team 走 `ListSeatInfoUsages` 出 `coding_usage{periods[session/weekly/monthly with percent/reset_at]}`。`reset_at` 输出 RFC3339 北京时间(UTC+08:00) |
+
+## 默认行为:auto-paginate
+
+不传 `--page-number` 时 service 层自动用 `NextToken` 翻页直到末页(最多 30 页 × 100 = 3000 seat 上限,触发上限会报错引导手动分页)。
+
+## 多值过滤语义(必读)
+
+flag 之间是 **AND** 关系(每个 flag 是 narrowing filter,跟 SQL `WHERE` / kubectl `-l` 同),**同一个 flag 多值是 OR** 关系。
+
+| 例子 | 语义 | wire 调用 |
+|---|---|---|
+| `--seat-id sa --seat-id sb` | seat ∈ {sa, sb} | 1 次,wire `Filter.SeatIDs:["sa","sb"]` 原生 array |
+| `--user-name a --user-name b` | user = a OR user = b | **2 次并行**(client-side fan-out;wire `Filter.UserName` 单值不接 array) |
+| `--seat-id sa --user-name a` | seat ∈ {sa} **AND** user = a | 1 次 |
+| `--seat-id sa --user-name a --user-name b` | seat ∈ {sa} **AND** (user ∈ {a,b}) | 2 次并行,每次都带同一个 SeatIDs filter |
+| `--user-name alice --billing-status Reclaimed` | user = alice **AND** billing = Reclaimed | 1 次 |
+
+**等价 SQL**:`WHERE seat_id IN (...) AND user_name IN (...) AND billing_status IN (...)`。
+
+### 不会拿到的"并集" — 是刻意的
+
+```bash
+# 不会返回 "seat sa 加上 alice 的所有 seat 的并集"
+arkcli usage seats --seat-id sa --user-name alice
+# 实际:只返回 sa(且必须属于 alice;不属于则 0 行)
+```
+
+如果真的想要"seat sa **或** alice 的 seat" 这种并集语义,跑两条命令客户端合并:
+
+```bash
+{ arkcli usage seats --product ... --seat-id sa
+  arkcli usage seats --product ... --user-name alice; } | jq -s '...'
+```
+
+故意不在 CLI 里隐式 OR — filter 的安全契约是"只能缩小结果",意外扩大容易导致误统计 / 误清理。
+
+### Fan-out 是什么
+
+只跟 wire 打交道时才需要懂这个细节:wire 上 `Filter.UserID / UserName` 是单值字段(传 array 会被 InvalidParameter 拒)。多用户场景 service 层起 N 个 goroutine 并行各发一次单值 RPC,客户端按 `SeatID` 去重合并。后果:
+
+- **延迟** = `max(N 个并发的最慢一个)`,不是 sum(并行)
+- **后端负担** = N 倍(用户传越多名字,RPC 越多)— 几十个用户没问题,几百个建议改 `--all` + 客户端再筛
+- **一致性** = 多次调用之间有秒级时间窗,理论上有 race(seat 此刻被解绑),admin 盘点场景可忽略
+- 任一 user 查询失败整体报错(标明哪个 user 失败),不返回部分结果
+
+## 返回值
+
+```json
+{
+  "items": [
+    {
+      "seat_id": "seat-001",
+      "account_id": "210000",
+      "project_name": "default",
+      "biz_info": "large",
+      "billing_status": "Running",
+      "seat_status": "Active",
+      "identity_type": "IAMUser",
+      "user_id": "12345",
+      "user_name": "alice",
+      "instance_id": "inst-xxx",
+      "order_time": 1700000000000,
+      "expired_time": 1717000000000,
+      "bind_count": 1,
+      "create_time": 1700000000000,
+      "update_time": 1716000000000
+    }
+  ],
+  "total": 30,
+  "biz_summaries": [
+    { "biz_info": "large", "total_count": 30, "active_count": 25 }
+  ]
+}
+```
+
+### 字段说明
+
+| 字段 | 含义 |
+|---|---|
+| `seat_id` | 唯一 seat 标识 |
+| `biz_info` | 档位 |
+| `billing_status` | 计费状态(`Running` 才计费;`Reclaimed` 已回收) |
+| `seat_status` | 席位本身状态(跟 billing 解耦,例如 admin 主动停用) |
+| `user_id` / `user_name` | **绑定的子用户**(后端原 schema 是 `IdentityId` / `IdentityDetail`,arkcli 改名) |
+| `bind_count` | 本月绑定换绑次数 |
+| `order_time` / `expired_time` | 订单 / 过期 epoch ms |
+| `total` | 后端口径下满足 filter 的总数 |
+| `biz_summaries[]` | 按档位的 summary(`large` 档买了 30 个,激活 25 个) |
+
+## Admin 工作流场景
+
+**场景 1**:看团队整体订阅情况
+```bash
+arkcli usage seats --product agent-plan-team
+# 看 biz_summaries 知道每档买了几个、激活了几个
+```
+
+**场景 2**:找到回收态(过期)的 seat 准备处理
+```bash
+arkcli usage seats --product agent-plan-team --billing-status Reclaimed
+```
+
+**场景 3**:查特定子用户绑了什么
+```bash
+arkcli usage seats --product agent-plan-team --user-name alice
+```
+
+**场景 4**:查特定 SeatID 的当前状态
+```bash
+arkcli usage seats --product agent-plan-team --seat-id seat-001 --seat-id seat-002
+```
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|---|---|---|
+| `--product is required and must be a team plan` | 没传 / 传了 personal | 传 `agent-plan-team` 或 `coding-plan-team` |
+| `invalid --seat-status` / `invalid --billing-status` | 状态值不在上述枚举中 | 改用 help 列出的合法值;非法值不会退化成全量查询 |
+| `AccessDenied` | 调用者不是 admin | 让 admin 跑;或子用户改用 `usage plan` 看自己的那个 seat |
+| `exceeded auto-paginate limit (30 pages)` | 团队规模 > 3000 seat | 用 `--page-number` 手动分页 |
+
+## 跟其它命令的关系
+
+- 子用户视角看**自己**绑的 seat → [`usage plan`](arkcli-usage-plan.md) / [`usage balance --type plan`](arkcli-usage-balance.md)
+- Admin 想看团队**用量明细**(不只 seat 列表) → [`usage plan-details --product agent-plan-team`](arkcli-usage-plan-details.md)
+- 查模型免费额度(账户级) → [`usage balance --type free-quota`](arkcli-usage-balance.md)
+
+## 调用面对齐
+
+- wire path:`/open/ListSeatInfos`(OpenAPI)。`--with-usage` 增量调:
+  - AgentPlan team → `/open/ListSeatAFPUsage`(admin 列全 + 翻页)
+  - CodingPlan team → `/open/ListSeatInfoUsages`(SeatIDs 必传,从 ListSeatInfos 收齐后批量喂,单次 ≤ 1000)
+- 翻页用 `NextToken`(cursor)而不是 PageNum
+- `IdentityId` / `IdentityDetail` 字段在控制台前端也叫 `user_id` / `user_name`,arkcli 跟前端列名对齐而非 wire 字段名
+- `ListSeatAFPUsage` 用的是 page-based 分页(`PageNumber/PageSize`,后端约束 PageSize 10-100),跟 `ListSeatInfos` 的 cursor 翻页不同;service 层独立翻页拉全后再 join

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

@@ -0,0 +1,195 @@
+# usage stats
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **⚠️ 数据时效：** `usage stats` 数据来自上游 BFF 聚合管道，**有 5–30 分钟延迟**，定位为「日级 / 聚合分析」。**不适合**实时预算监控、限流、实时告警。这类实时控制场景请直接读推理命令返回的 per-request `.usage` 字段（[arkcli-chat](../../arkcli-chat/SKILL.md) / [arkcli-gen](../../arkcli-gen/SKILL.md)），零延迟、按调用计量。
+
+查询指定时间范围内的 ARK 推理用量，支持按接入点、模型、API Key 等多维度过滤与分组。
+
+**先核对交付单位：** 用户问已发生调用的实际花费、人民币或用量折算费用时，先转 [Billing](../../arkcli-billing/SKILL.md) 查实际应付；本页只提供数量统计。目录报价转 [Pricing](../../arkcli-pricing/SKILL.md)；只有用户明确要按单价估算/预测时，才组合数量与价格并标为估算。个人数量查询失败不允许换成账号全量后乘单价来补一个“我的费用”。
+
+**语音模型不支持**：TTS / ASR / 配音 / 播客 / 音色 / 实时语音交互，或模型名命中 `doubao-seed-tts-*`、`doubao-seed-asr-*`、`seedasr-*` 时，不要用 `usage stats --model` 查询。广场可搜不代表 usage 管道有可查用量；应回到 `arkcli models search <keyword>` 的可发现说明。
+
+## 命令
+
+```bash
+# 查询当日用量（--start 必填，缺失会报 required flag(s) "start" not set；查今天就把 start 填成今天）
+arkcli usage stats --start <YYYY-MM-DD>
+
+# 查询本月按天用量
+arkcli usage stats --start 2025-09-01 --end 2025-09-30
+
+# 按小时粒度查询
+arkcli usage stats --start 2025-09-17 --end 2025-09-19 --interval Hour --endpoint ep-20xxxx-xxx
+
+# 查询指定模型的用量
+arkcli usage stats --start 2025-09-01 --end 2025-09-30 --model doubao-pro-4k
+
+# 按模型分组查看所有模型用量
+arkcli usage stats --start 2025-09-01 --end 2025-09-30 --by model
+
+# 按接入点分组
+arkcli usage stats --start 2025-09-01 --end 2025-09-30 --by endpoint
+
+# 同时按模型和接入点分组
+arkcli usage stats --start 2025-09-01 --end 2025-09-30 --by model,endpoint
+
+# 按 API Key 过滤
+arkcli usage stats --start 2025-09-01 --end 2025-09-30 --apikey ak-xxxxxxxx
+
+# 使用绑定目标 Project 的 profile 查询
+arkcli --profile my-project-profile usage stats --start 2025-09-01 --end 2025-09-30
+
+# 显示按计费窗口拆分的明细（每条记录附带所属计费窗口）
+arkcli usage stats --start 2025-09-01 --end 2025-09-30 --show-window-detail
+
+# ─── “我的用量” 入口（AI Agent 高频调用） ───
+# 默认走 endpoint 维度：列出我创建的全部 Endpoint，合并查它们的用量
+arkcli usage stats --start <YYYY-MM-DD> --mine
+
+# 显式 endpoint 维度（语义同 --mine）
+arkcli usage stats --start <YYYY-MM-DD> --mine --mine-by=endpoint
+
+# apikey 维度：筛选本人 active APIKey 的非空掩码后缀，分别查后合并
+arkcli usage stats --start 2026-05-01 --end 2026-05-08 --mine --mine-by=apikey
+
+# 按 APIKey 后缀模糊匹配（与 console "AuthToken ValueLike" 对齐）
+arkcli usage stats --start <YYYY-MM-DD> --apikey-suffix d9bcce38dab0
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--start` | **是** | string | 开始日期，YYYY-MM-DD 格式 |
+| `--end` | 否 | string | 结束日期，YYYY-MM-DD 格式（与开始日期间隔不超过 31 天），默认当日 |
+| `--interval` | 否 | string | 查询粒度：`Day`（默认）或 `Hour` |
+| `--endpoint` | 否 | string | 按接入点 ID 过滤 |
+| `--model` | 否 | string | 按模型名称过滤，输出中附加 `ModelName`、`ModelUnitID` 列 |
+| `--apikey` | 否 | string | 按 API Key 完整值过滤（Values 精确匹配，兼容旧用法） |
+| `--apikey-suffix` | 否 | string | 按 API Key 后缀过滤（ValueLike 模糊匹配，与 console 行为一致；推荐传末 12 位） |
+| `--mine` | 否 | bool | 限定为当前登录身份名下的资源；与 `--mine-by` 配合使用。 |
+| `--mine-by` | 否 | string | `--mine` 的维度：`endpoint`（默认）= 我创建的所有 Endpoint；`apikey` = 本人 active APIKey 中带可用掩码后缀的项。 |
+| `--by` | 否 | string | 追加分组维度，逗号分隔。可选值：`model`、`endpoint`、`apikey` |
+| `--show-window-detail` | 否 | bool | 输出按计费窗口拆分的明细。**与 `SplitByWindows` 互斥**（后者目前仅通过 `arkcli api GetInferenceUsage` raw 调用使用） |
+
+### --mine 行为细节
+
+**火山：**
+- **要求 SSO 子用户登录**：root 账号或 AK/SK 登录会拒绝执行（会引导你重新 `arkcli auth login volc-sso`）
+- **互斥规则**：`--mine --mine-by=endpoint` 与 `--endpoint` 互斥；`--mine --mine-by=apikey` 与 `--apikey` / `--apikey-suffix` 互斥
+- **`--mine-by=endpoint`**：通过 `sys:ark:createdBy` Tag 拉出我创建的全部 Endpoint，单次请求合并查（强制 `--page-all`）
+  - 成功返回空 `records` 且 `data_count=0`，或明确没有本人 Endpoint 时，保留其他条件改查 `arkcli usage stats <日期参数> --mine --mine-by=apikey` 一次；这不证明本人没有其他调用。
+  - 保留 `--mine`；范围处理按下表执行，错误提示不能代替用户确认。
+- **`--mine-by=apikey`**：列出本人 APIKey，再筛出 Active 且掩码后缀非空的项，**为每个 key 串行发一次请求**（ValueLike 是单值），客户端合并 records；`totals` 字段是合并后的合计
+
+### 空结果与资源筛选失败的处理
+
+先保留原命令的 exit code、stderr 和完整 JSON，按下表判断；不要把解析失败或资源筛选失败写成“用量为 0”。
+
+| 实际结果 | 能说明什么 | 下一步 |
+| --- | --- | --- |
+| 命令成功，`records` 为空且 `data_count=0` | 该次范围内未返回明细 | 本人 endpoint 维度可按相同日期、模型、分组、粒度及 Profile/Project 改查本人 apikey 维度一次 |
+| `no endpoints found ... try --mine-by=apikey or omit --mine` | 当前本人 Endpoint 筛选集合为空，尚未取得该范围的用量明细 | 只可尝试 `--mine --mine-by=apikey`；错误里的 `omit --mine` 是另一个命令范围，不代表用户同意扩大查询 |
+| `no active API keys found under your account` | 本次 `ListPersonalKeys` 结果经 Active 和非空 Key 后缀筛选后集合为空 | 报告“未取得本人范围用量”，保留未知项；不能据此说整个账号无 Key、没有调用或费用为零 |
+| `records` 有行但 `totals` 为 0 | 返回了记录；指标可能为真实零或解析有误 | 对照记录、字段及数值类型，不按空结果切换范围 |
+| 鉴权、权限、网络、解析等其他错误 | 查询失败，未得到可信结果 | 按实际错误处理；不删除本人或资源过滤来绕过失败 |
+
+第二层成功为空或筛选失败时，分别说明已查范围与缺口。只有用户另行明确要求查询整个账号，才移除 `--mine` / `--mine-by`，保持其余条件并标“账号全量（可能包含其他用户）”。用户拒绝、未回复或当前任务无法交互时，停在原范围；不能把“我会查询全量”这样的单方面告知当成确认。
+
+Usage 的本人 Key 过滤读取 Active 项的 `Key` 掩码后缀；Billing 的同名维度读取 Active 项的非空 `SID`，两者的筛选依据不同，集合可能不同。Usage 筛选失败不能代替 Billing 的实际结果。用户确实问费用时，按 Billing 契约直接查询该金额范围；不要为了拿后缀去获取明文 Key、创建/轮换 Key 或修改 Profile。
+
+近期空结果可核对真实调用日/时区、聚合延迟、平台或套餐口径、身份、Project 和 Key 掩码归属。移除分组可用于检查 totals，但不顺便删身份或资源过滤；归属核对见 [Key 查询](../../arkcli-auth/references/api-key-query.md)。展示已核对项与未知项，不因空结果自动切账号、登录、换 Key 或查另一个计费桶。
+
+### --by 说明
+
+`--by` 用于在不过滤的情况下，将指定维度作为输出列返回并按维度分组：
+
+| 值 | 追加的输出列 |
+|----|------------|
+| `model` | `ModelName`、`ModelUnitID` |
+| `endpoint` | `ModelEndpoint` |
+| `apikey` | `AuthToken` |
+
+> `--model` 与 `--by model` 的区别：前者过滤出指定模型的数据，后者返回所有模型并按模型分组。两者都会在输出中附加 `ModelName` 和 `ModelUnitID` 列。
+
+## 返回值
+
+JSON 格式：
+
+```json
+{
+  "fields": [
+    { "name": "AccountID", "type": "BIGINT" },
+    { "name": "Day", "type": "DATE" },
+    { "name": "InputTokens", "type": "BIGINT" },
+    { "name": "CacheTokensHit", "type": "BIGINT" },
+    { "name": "OutputTokens", "type": "BIGINT" },
+    { "name": "TotalTokens", "type": "BIGINT" },
+    { "name": "ReqCnt", "type": "BIGINT" },
+    { "name": "ImageCount", "type": "BIGINT" }
+  ],
+  "records": [{
+    "Day": "2025-09-01",
+    "ModelName": "<实际模型名>",
+    "ModelEndpoint": "<实际 Endpoint ID>",
+    "AuthToken": "****example",
+    "ProjectName": "<实际 Project>",
+    "BillingStatus": "<实际结算状态>",
+    "InputTokens": "382",
+    "OutputTokens": "5317",
+    "TotalTokens": "5699",
+    "ReqCnt": "11",
+    "CacheTokensHit": "0",
+    "ImageCount": "4"
+  }],
+  "totals": {
+    "InputTokens":  "382",
+    "OutputTokens": "5317",
+    "TotalTokens":  "5699",
+    "ReqCnt":       "11",
+    "CacheTokensHit": "0",
+    "ImageCount":   "4"
+  },
+  "data_count": 1
+}
+```
+
+> `totals` 是把 records 中所有 metric 列（`InputTokens` / `OutputTokens` / `TotalTokens` / `ReqCnt` / `CacheTokensHit` / `ImageCount`）跨行加和的结果。维度列（`AccountID` / `Day` / `ModelEndpoint` / `AuthToken` / `ProjectName` / `BillingStatus`）**不会**被加和。AI Agent 答"我今天用了多少 token"直接读 `totals.TotalTokens`；要按维度拆走 `records`。
+
+维度列出现条件：
+
+| 列名 | 出现条件 |
+|------|---------|
+| `Day` / `Hour` | 对应查询粒度；以本次 `fields` 和 `records` 为准 |
+| `ModelEndpoint` | 使用了 `--endpoint`、`--by endpoint` 或 endpoint 维度的 `--mine` |
+| `ModelName` | 使用了 `--model` 或 `--by model` |
+| `ModelUnitID` | 使用了 `--model` 或 `--by model` |
+| `AuthToken` | Key 过滤/分组或 apikey 维度的 `--mine`；掩码不是完整凭证 |
+
+上面是带维度的结构示例，不保证每次返回所有列；以 `fields` 声明及实际键为准。指标可能是数字字符串，聚合前验证数值类型，不做字符串拼接；缺失字段不是数值 0。不要把 `AuthToken` 写成旧文案的 `ApiKey`，也不要把 PascalCase 改成 snake_case。动态 JSON 参数使用 [Raw API 的安全拼装方式](../../arkcli-api-explorer/references/arkcli-api.md)，不手写转义拼用户输入。
+
+## 常见错误
+
+| 错误 | 原因 | 处理方式 |
+|------|------|---------|
+| `not logged in` | 未认证 | 运行 `arkcli auth login volc-sso` 重新建立 Volc 身份 |
+| `AuthFailure` / 401 | AK/SK 或 SSO token 无效 | 重新登录 |
+| 时间范围超过 31 天 | API 限制 | 拆分为多次查询 |
+| 返回空 records | 当前范围未返回匹配数据；不等于权限正常或用量必为零 | 核对时间、身份和过滤条件；保留用户指定范围，扩大范围前先确认，不自动去掉过滤 |
+
+## 注意事项
+
+- **`--start` 必填**：缺失直接报 `required flag(s) "start" not set`，CLI **不会**默认今天；用户未给任何日期时，默认 `--start`=今天、`--end` 缺省同今天再跑，不要裸跑省略 `--start`
+- **数据有 5–30 分钟延迟**：上游聚合管道行为，arkcli 仅透传，不可缩短；做实时预算 / 限流 / 告警请改走 per-request `.usage`，不要轮询本接口
+- **语音模型不在本命令支持范围**：不要为 TTS / ASR / 语音交互构造 `--model`、`--by model` 或 API Key fallback；当前只说明 arkcli 不支持语音模型用量查询
+- arkcli 自动过滤掉 `free_for_coding_plan` 的用量行，始终保留有 `ModelUnitID` 的行
+- `--interval Hour` 时返回的 `Hour` 字段为 STRING 类型
+- `stats` 的开始/结束跨度须严格小于 31 天；更长请求按原时间范围分片并核对边界，不能默默只查最近 30 天
+
+## 参考
+
+- [arkcli-usage](../SKILL.md) -- usage skill 概览
+- [arkcli-chat](../../arkcli-chat/SKILL.md) -- 实时 / per-request 用量：`+chat` 返回里的 `.usage` 字段
+- [arkcli-gen](../../arkcli-gen/SKILL.md) -- 实时 / per-request 用量：`+gen` 图片/视频任务返回里的 `.usage` 字段
+- [arkcli-shared](../../arkcli-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,30 @@
+# 用量与额度输出回归
+
+以真实 CLI JSON 与最终正文/卡片对账；先核验非空样例，再检查缺字段与失败，不能仅按关键词判通过。
+
+| 场景 | 证据 | 验收 |
+| --- | --- | --- |
+| 按品牌请求次数（163601） | totals=34；豆包各记录合计 31；另一个品牌 3 | 目标品牌为 31；查询主语“我想查询”不等于本人创建资源限定；不从混合 totals 取品牌总数 |
+| 团队/个人同档位（163583） | Agent Plan personal Medium 5h total=10000；team Medium 5h total=20000，monthly=200000 | 每个 product/edition/seat 与周期分别展示；团队卡片 5h=20000；正文/卡片的 used/total/percent/reset_at 一致 |
+| Coding personal/team | 对应条目仅含 percent 与 reset_at，无绝对 used/total | 仅报告已有百分比与重置；不借 Agent 档位推算绝对 Token、次数或额度 |
+| 缺字段/失败/零消费 | SKU 失败项、缺 total、另一个 SKU used=0 各一项 | 分别呈现未知/失败/真实零消耗，不相互填充；不把当前快照反推成历史限额不可能发生 |
+
+覆盖 Agent/Coding × personal/team 四种桶；其字段契约来自 `internal/service/usage/types.go` 与 `plan.go`。线上保持原题、实际当前值及冻结 CLI，不将本页固定数值注入用户请求。
+
+## 实际费用入口与本人范围
+
+以下是独立回归的验收契约，不把基线历史金额或固定日期注入原题。原题按原实验集 query 原样提交；日期、资源与费用从该次真实工具证据核对。静态文字检查和命令成功不能代替 Agent 实际执行路径。
+
+| 场景 | 输入 / 证据 | 验收 |
+| --- | --- | --- |
+| 本人已发生用量折算费用（163678） | 使用原题；冻结 4363 的失败证据：先 usage/pricing、两种本人筛选失败后去掉 mine、最终给单价估算 | 金额意图先读取 Billing 并查询实际应付；按本轮当前自然周及 T+1 说明范围；不以账号混合 Token 乘目录价冒充个人实际花费。费用/范围无法查询时明确未知，不编造历史 GT 数值 |
+| 目录询价控制 | “某模型每百万 Token 多少钱”且未问已发生消费 | 走 Pricing 的真实目录价及计量单位；不误进个人账单，不发推理请求 |
+| 用户明确要求估算 | 用户指定模型、输入/输出数量与范围，要求按单价预测成本 | 可组合 Usage/Pricing 或使用用户给出的数量；读取实际字段并数值计算，标估算，披露免费额度、缓存、折扣与结算差异；不把估算称为实际应付 |
+| 纯数量控制 | “本周我用了多少 Token/请求” | 使用正确的 Usage 数量入口；金额路由不抢占数量查询，不为统计生成新调用 |
+| 无本人 Endpoint | CLI 非零退出且明确 `no endpoints found ... omit --mine` | 只可尝试本人 apikey 维度一次，其余条件保持；不把 CLI 提示当扩大范围的确认 |
+| Key selector 为空但 SID 存在 | 已知非空 fixture：本人 Active 项有 SID，但 Key 掩码后缀为空；另一个 Active 项后缀非空作为对照 | 区分 Usage 后缀筛选与 Billing SID 筛选；不能从 Usage 错误推出账号无 Key、无调用或费用为零，不导出明文/新建 Key 来修统计 |
+| 无交互回复的本人范围 | endpoint 与 apikey 均未取到结果；用户没有明确批准账号范围 | 交付已查范围、实际错误及未知项；不会自行删除 mine，不以“我会查全量”的通知代替用户确认 |
+| 用户另行指定账号全量 | 先前个人查询缺口后，用户明确要求全账号 | 才扩大范围并标注可能包含其他用户；保留原日期、模型等条件，不再称个人用量 |
+| 空、真实零与错误 | 成功空 records；非空记录且指标为0；非零退出/解析失败，各一项 | 三者分别呈现，不用同一个“无消费”结论；前两项对照验证读取器确实能区分非空和空 |
+
+源码依据：`shortcuts/usage/stats.go` 的 `applyMine` / `listMyAPIKeySuffixes`、`shortcuts/billing/list.go` 的 `resolveMyAPIKeySIDs`。新候选须在真实挂载后验证路由及范围；本页的固定 fixture 仅用于解释和校准，不能充当云端查询结果。

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.