@volcengine/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.46bd0d6dcc58

package/skills/arkcli-auth/references/realname-gate.md

@@ -0,0 +1,23 @@
+# 实名认证闸门（开通 / 写资源类命令）
+
+> 本文从 `arkcli-shared` 拆出。仅在命中"开通模型 / 部署 / 精调 / 激活模型"这类会触发 `OpenModelChargeItem` 的写资源意图时加载。常规读任务不需要读本文。
+
+部分命令会触发**开通模型**（`OpenModelChargeItem`），而开通模型要求账号**已完成实名认证**——未实名时后端必拒（`OperationDenied` / cause `NotVerifiedAccount`）。对这类命令，在「认证闸门」通过之后、执行命令之前，**再追加一道实名检查**：
+
+适用命令（凡会触发开通模型的）：
+
+- `arkcli +deploy`
+- `arkcli infer endpoint create`
+- `arkcli train finetune create`
+- `arkcli models activate`
+
+**执行顺序是硬约束**：命中上述任一意图（开通 / 部署 / 精调）时，**第一步**就做实名检查——在跑 `models get/search`、`+deploy`、`activate`、`infer endpoint create` 等**任何业务命令之前**，先 `auth status` 读 `verified`。**不要**先去试 deploy/activate、撞到"模型未开通"或"model ID invalid"之类报错再回头查实名——那些报错会把你带偏，让你忘了真正的前置是实名。
+
+检查步骤：
+
+1. 读 `arkcli auth status` 输出里的 `volc_sso.identity.verified`（0.1.17+ 字段）：
+   - `verified == true` → 已实名，放行，继续目标命令。
+   - `verified == false` → 账号未实名。**立即停**：用一句话告诉用户"检测到账号未实名，开通模型 / 部署 / 精调需要先完成实名认证"，并给出实名认证页：`https://console.volcengine.com/user/authentication/detail/`。**在此暂停等待**用户完成实名后回来告知，再继续目标命令；**不要原地轮询、不要改用别的模型 ID 重试、不要继续跑 deploy/activate 去碰运气**（与 SSO 登录失败的"贴回链接 + 等用户"处理一致）。
+   - **`verified` 字段缺失**（探测失败 / AK-SK 模式无此字段）→ **不要硬卡**，正常继续执行；实名是火山账号概念，字段缺失视为"未知 / 不适用"，交由命令失败时的 error-hint 兜底，**不要假报**已实名或未实名。
+2. 实名是**账号级**前置，与 profile / project / 登录方式无关；它是"开通模型 / 开通云产品 / 创建推理接入点"的共同必要条件。
+3. **代码兜底（0.1.17+）**：即便漏了上面的前置检查、直接跑 `+deploy` / `infer endpoint create` / `train finetune create`，`EnsureModelAvailable` 也会在开通前做一次实名预检，未实名时直接返回结构化 `account_not_verified` hint（不再是误导的"操作已取消：模型未开通"）。这是最后一道网，不是免去主动检查的理由——主动在第一步检查能给用户更早、更清晰的引导。

package/skills/arkcli-auth/scripts/key-metadata.jq

@@ -0,0 +1,34 @@
+# Input: complete apikey.list JSON, --arg id <observed numeric Id as text>.
+# Fail closed on incomplete pages, duplicate IDs or integers jq cannot represent safely.
+def safe_id: type == "number" and . > 0 and . <= 9007199254740991 and floor == .;
+.Result as $r
+| if ($r | type) != "object" or ($r.Items | type) != "array" then
+    error("expected complete Result.Items")
+  elif ($r.TotalCount | type) != "number" then
+    error("expected numeric TotalCount")
+  elif $r.TotalCount != ($r.Items | length) then
+    error("incomplete inventory: item count differs from TotalCount")
+  elif any($r.Items[]; (.Id | safe_id | not)) then
+    error("invalid or unsafe Id: use an exact-integer parser")
+  elif ([$r.Items[].Id] | unique | length) != $r.TotalCount then
+    error("duplicate Id in inventory")
+  else $r end
+| . as $inventory
+| [.Items[] | select((.Id | tostring) == $id)] as $matches
+| if ($matches | length) != 1 then error("expected one exact numeric Id match") else
+    ($matches[0] | {
+      Id, SID: (.SID // null), Name: (.Name // null),
+      ProjectName: (.ProjectName // null), Status: (.Status // null),
+      LastAccessTime: (.LastAccessTime // null), AccessControlInfo: (.AccessControlInfo // null)
+    }) as $selected
+    | {
+        total_count: $inventory.TotalCount,
+        status_counts: ($inventory.Items
+          | map(if (.Status | type) == "string" and (.Status | length) > 0
+                then .Status else "__unknown__" end)
+          | group_by(.) | map({status: .[0], count: length})),
+        selected: $selected,
+        missing_fields: ($selected | to_entries
+          | map(select(.value == null or .value == "") | .key))
+      }
+  end

package/skills/arkcli-billing/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: arkcli-billing
+version: 1.1.3
+description: "查询火山引擎 ARK 拆分账单明细（结算金额、Token 用量计费），支持按账期月、月范围、Endpoint、API Key、产品编码等维度过滤。当用户问账单、花了多少钱、对账、账期、按 EP / API Key 拆账、按产品拆账、月度账单、出账明细时使用。注意 billing 跟 usage stats 不同：stats 出推理量（近实时），billing 出结算金额（T+1 出账，财务口径）。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli billing list --help"
+---
+
+# arkcli billing
+
+**执行前 MUST 读取** [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) (认证 / 全局规则) 和 [`references/arkcli-billing-list.md`](references/arkcli-billing-list.md) (参数详解)。
+
+## 适用场景
+
+- 查询某账期月或月范围内的拆分账单明细(结算金额 / Token 用量)
+- 按 Endpoint、API Key、产品编码、账单类型过滤拆账行
+- 月度 / 季度 / 年度对账
+- 排查"这个 EP / 这把 key 花了多少钱"
+
+## 业务定位 — billing vs usage stats
+
+| 维度 | `usage stats` | `billing list` |
+|---|---|---|
+| 数据源 | ARK BFF 推理聚合 | 火山计费中心拆账 |
+| 时效 | 5–30 分钟延迟 | T+1 出账 |
+| 单位 | Token / 请求数 | CNY 金额 |
+
+想看"用了多少 token"→ [`arkcli-usage`](../arkcli-usage/SKILL.md);想看"花了多少钱"→ 本 skill。
+
+## Step 0：确认账单口径与范围
+
+先分清“已结算金额”与“Token / 套餐额度消耗”，后者交给 Usage，不用单价乘估算 Token 冒充账单。用户只查某个 Endpoint、Key 或订阅时，仅查其明确范围；`profile.type=platform` 不能证明没有套餐。
+
+身份上下文已知则复用，确需核实时按共享宿主协议使用 `arkcli auth whoami --format json`；托管宿主的注入协议优先。普通账单查询不调用可能同步/回写 Key 的 `profile show/list/keys list`，不为了补全账单切换身份。
+
+- “我的调用用了多少钱 / 我的用量折合多少人民币”按本人 Key 归属查询，显式使用 `--mine --mine-by=apikey`；“我部署的接入点花了多少”才选 `--mine --mine-by=endpoint`。只说“我花了多少”而未点名资源时，可按本人 Key 归属解释并在输出开头说明这一口径，不把 CLI 默认 Endpoint 视图直接称作本人的全部消费；“我想查询豆包调用次数及费用”中的“我想查询”只是请求主语，不等于本人资源归属限定。先按用户点名的模型/产品、已生效的身份与 Project 查询并说明范围；不能擅自追加 `--mine` 把问题缩成本人创建的 Endpoint。用户要求订阅类账单时显式 `--product ark_subscription`，并解释其账号/订阅范围，不称为个人 Endpoint 用量。
+- “整个账号花了多少”才使用账号查询；Project 筛选按本次实际上下文说明，不能为补数擅自清空 Project、换 Profile 或换身份。
+- 每条 `billing list` 必带 `--start <YYYY-MM>`，跨月加 `--end <YYYY-MM>`。账期是月份，不是 Usage 的日级参数；T+1 及当期未出账部分必须披露。
+- “本周”与“最近 N 天”先读取真实运行日期，按用户明确的时区与周起点计算；未指定时说明采用的时区、本周按周一至当天，近 N 天按当天向前 N−1 天。用日历工具计算闭区间和星期，不心算、不抄历史日期。冻结起止、归属和产品范围；跨月覆盖全部账期。T+1尚未出账不能把本周扩大为上一周或近7天来凑金额。
+- `BillingDate` 在 `--interval day` 结果中也可能缺失。先检查真实行结构；有有效日期才过滤原区间，缺失时按参数详解的逐日查询流程补查并保留请求日期来源，不能把缺日期行过滤成零。部分日期失败或无法证实覆盖时如实说明缺口，不把整月金额说成本周金额。
+- 返回数组是 `items`，不是 `Items`；使用 `--output FILE` 后从文件读取完整记录，stdout 的 `items:null` 只是摘要形式。先校验退出状态、`returned`、`total_records`、`partial_failures` 和 `is_truncated`。日期、金额字段都须按实际输出判断，缺失不等于零；完整成功的空结果与解析失败、请求失败、截断分开报告。
+
+### 用量与费用同时回答时
+
+- `usage stats` 的 `totals` 是本次全部返回记录的合计。用户点名模型/品牌时按实际模型身份筛选记录后重新合计；有明确版本可用 `--model`，不能把包含其他模型的总请求数直接叫作“豆包次数”。原始数值先计算，再统一展示单位和舍入。
+- 账单 `Count` 与同一行的 `Unit`、`ChargeItemCode`、`ConfigurationCode` 绑定；例如“326.7 千 Token”才换算为 326,700 Token。金额、视频计量、Token 和请求次数分别呈现，不能把某一计费项的 Count 从全模型 usage Token 中减去，再把差额归给剩余请求。
+- 只有日期、模型/产品、资源归属、单位和已出账覆盖都相同，才逐项对账；否则分列推理统计与已结算金额，披露延迟/范围差异。未出账部分可以给有来源的估算，但清楚标成估算，不能把估算当实际账单或从一次空列表宣称费用为零。
+
+### 汇总交付：一份记录，一次本地计算
+
+1. 将本轮完整返回落盘，记录查询范围与时间。筛选后的同一份记录同时用于总量、Top N、其余项、比例和卡片；只为排序、求和或排版不要再次请求服务。需要刷新时整组更新，不把新总量与旧明细拼接。
+2. 用本地程序一次产出所有展示数值：请求数用精确整数，金额用Decimal等十进制运算，最后统一舍入。“其余”从未展示的记录直接求和，不能心算补数，也不能用来自另一查询的总量减Top N。缺少完整明细时说明无法核对，不凑差额。
+3. 输出前断言同范围的总量等于已展示分组与其余项之和，分组个数也相符；舍入后的金额有尾差时单独说明。文字、表格和卡片直接复用计算结果。出现矛盾时先修本地计算或说明快照差异，不用“约”掩盖一个未经计算的精确数字。
+
+## 快速决策
+
+| 用户问 | 命令 |
+|---|---|
+| 我的调用 / 用量这个月花了多少 | `arkcli billing list --start <YYYY-MM> --mine --mine-by=apikey`；按本人当前 Active Key 归属，并披露历史覆盖限制 |
+| 我部署的接入点这个月花了多少 | `arkcli billing list --start <YYYY-MM> --mine --mine-by=endpoint`；可能包含他人调用这些接入点的费用 |
+| 整个账号花了多少 / 公司账号 / 整体 (无主语自指) | `arkcli billing list --start 2026-05` (账号维度全量) |
+| 这个 EP 花了多少 | `arkcli billing list --start 2026-05 --endpoint ep-...` |
+| 这把 key 花了多少 | `arkcli billing list --start 2026-05 --apikey ark-...` |
+| 账号下每个 EP / key 各花了多少 | `--split-dim endpoint` 或 `--split-dim apikey` |
+| 按天 / 按每条结算明细 | `--interval day` 配 `--day YYYY-MM-DD`,或 `--interval detail` |
+| 过去 N 个月对账 | `--start ... --end ...` (闭区间, 最多 24 个月) |
+| 看 Agent Plan / Coding Plan 订阅类账单 | 显式 `--product ark_subscription` (默认查询不含) |
+
+### 按用户意图选择本人账单归属
+
+`--mine` 只表示按当前身份拥有的资源归集；`--mine-by` 决定是哪种资源。CLI 默认仍是 `endpoint`，这不是“本人调用消费”的同义词，也不能仅因 Usage 默认相同就沿用到费用问题。
+
+1. 先确定用户明确的资源与费用意图，再显式选择维度。Endpoint 视图查询本人创建的接入点账单；API Key 视图查询当前可列出的本人 Active Key 的账单。两组资源和金额可以不同，同一消费也可能同时体现在两个视图，不能相加或互相替代。
+2. 输出开头说明维度、身份/Project、日期与已出账覆盖。按 Key 归属不等于识别了实际发起请求的人；共享 Key 的调用也按 Key 归集。源码仅筛选当前 Active Key，不能据此保证覆盖历史已停用、删除或不再归属本人的 Key。
+3. 返回有数据也先检查 `partial_failures`、`is_truncated` 和实际日期范围，再用同一份完整记录汇总。不能因某一维度先查到数据，就认为它一定回答了用户要的口径。
+4. 成功但 `items` 为空，或明确报告本人无该类资源时，报告该口径未查到匹配账单，并核对日期、出账延迟和覆盖限制。请求/鉴权失败与空数据分开。如果原意是本人调用费用、先前误用了 Endpoint 维度，可以纠正为 Key 维度，并明确说明这是归属口径纠正；不能把它叫作相同范围的重试。
+5. 用户已指定某个 Endpoint、Key、订阅或明确归属维度时，保留其范围；空结果不自动替换为另一组资源。用户要求对照两种归属时分别标注查询与合计。始终保留已授权的账期、日期、产品和 Project，不删 `--mine` 扩成全账号，也不切 Profile 或身份补数。
+
+## Agent 关键纪律
+
+- **保留 stderr**：首次查询和用于得出结论的查询不得加 `2>/dev/null`。账号全量 scope 提示、软截断 WARN 与部分失败原因都可能只写 stderr；需要解析 JSON 时只接管 stdout，或优先使用 `--output FILE`。
+- **`is_truncated=true` 时停下问用户,不要自动决策** — 撞 cap (preflight 模式下 items 不返,只有 metadata + partial_failures + stderr 警告) 是规模信号不是错误。先把 `total_records` 和 `partial_failures[*].total` 报给用户,列出 4 条出路,**等用户明确选一个再继续**。选哪条要看用户当前任务意图(对账 / 排查 / 导出),agent 不要替用户拍。**永远不要 sum items 当总额**(items 可能为空或部分):
+  - 想要全量明细 → `--output FILE` (落盘 stdout 不爆;自动放宽 cap 到 300k 行)
+  - 只要总金额 → `--split-dim apikey|endpoint` (服务端聚合到几十行)
+  - 缩到一个资源 → `--endpoint <ep-...>` / `--apikey <ark-...>`
+  - 强行流进 stdout → `--page-limit=N` (N 见 partial_failures.reason 建议;mind context size)
+- **`--limit/--offset` 在 fan-out 时是 per-fan-out 各 N 行** (`--end` 跨月或 `--mine` 多资源时), `partial_failures` 标 `reason="windowed sample"`, agent 据此知 returned ≤ limit × fanout_count
+- **金额是 CNY 字符串** — JSON 数字精度有损,加和 / 比较用 decimal 库,不要 `parseFloat`
+- **月初对完整账期时查前一个月** — T+1出账，当月当日数据可能不全；用户明确问本周或当期时保留其日期范围，不能改成上月。
+- **`--mine` ≠ `PayerID`** — `--mine` 按 IAM 子用户过滤资源,`PayerID` 是财务托管 owner 账号 ID,单账户场景手撸 `PayerID` 是 no-op (= 全账号查询)。默认 `--mine-by=endpoint`(infra ownership,对齐 usage stats),要看 cost causation (我的 key 在花钱) 显式 `--mine-by=apikey`
+- 默认 scope = ARK 推理 / Agent 9 个支持 API Key 分账的产品(**不含 `ark_subscription`**,要看订阅类显式 `--product ark_subscription`) + profile.project 自动注入(若 profile.project 是具体 id 如 `auto-test`,自动按 project 过滤;`default`/账号全部资源哨兵/空跳过 = 真账号全量;stderr 出软提示)。要强制账号全量传 `--project=` (空值清空默认)
+
+## 常见降级
+
+- 鉴权错误 / SSO 失效 → [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md)
+- 想看推理量 (token / 请求数) → [`../arkcli-usage/SKILL.md`](../arkcli-usage/SKILL.md)
+- 想看模型 / 套餐价格目录 → [`../arkcli-pricing/SKILL.md`](../arkcli-pricing/SKILL.md)
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| [`billing list`](references/arkcli-billing-list.md) | 拆分账单明细查询(结算金额 × Token 用量) |

package/skills/arkcli-billing/references/arkcli-billing-list.md

@@ -0,0 +1,247 @@
+# billing list
+
+> **前置**: 先读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) (认证 / 全局参数)。
+
+> **`billing list` vs `usage stats`**: stats 出"用了多少 token"(近实时,ARK BFF 聚合);billing 出"花了多少钱"(T+1 出账,火山计费中心)。
+
+查询指定账期(YYYY-MM)或月范围内的拆分账单明细。**默认全量分页**,撞 service 内部 cap (~3000 行 / 1 MB JSON) **软截断**(不 hard fail): 已抓数据正常返 + `is_truncated=true` + `partial_failures` 标注哪些 fan-out 截断 + stderr 强警告。`--limit/--offset` 切显式分页模式 (跨 fan-out 时 per-fan-out 各 N 行)。
+
+**核心纪律**: agent 必须先看 `is_truncated` 和 `partial_failures` 头判断截断状况, **`is_truncated=true` 时不要 sum items 当总额** — 看 `partial_failures[*].total` 知真实规模, 然后决定下一步: 想全量明细 → `--output FILE` 落盘 / 只要总金额 → `--split-dim apikey|endpoint` 聚合 / sample 够就用现状 / 缩到单资源 → `--endpoint`/`--apikey`。
+
+> **`--start` 单独用 = 单月查询**(不是开放区间到今天)。`billing list` 是月单位,wire 单 `BillPeriod` 字段 — 要查多月范围必须 `--end`(例: `--start 2026-03 --end 2026-05`,客户端 fan-out 模拟)。跟 `usage stats` 的日级 `--start --end` 不同。
+
+## 命令
+
+```bash
+# 单月汇总(最常用) — 默认: 9 个支持 API Key 分账的 ARK / Agent 产品 + profile.project
+# 自动注入(若 profile.project 是具体 id, 如 "auto-test");profile.project="default" /
+# 账号全部资源哨兵 / 空 时跳过注入 = 真账号全量。stderr 出软提示告知。
+arkcli billing list --start 2026-05
+
+# 多月范围(闭区间, 最多 24 个月)
+arkcli billing list --start 2026-03 --end 2026-05
+
+# 按天 / 按每条结算明细
+arkcli billing list --start 2026-05 --interval day --day 2026-05-15
+arkcli billing list --start 2026-05 --interval detail
+
+# 单值 scope (三选一互斥)
+arkcli billing list --start 2026-05 --endpoint ep-...
+arkcli billing list --start 2026-05 --apikey ark-...        # 自动经服务端反查 SID
+arkcli billing list --start 2026-05 --apikey-sid apikey-... # advanced, 跳过反查
+
+# 账号维度切片
+arkcli billing list --start 2026-05 --split-dim endpoint    # 每个 EP 各花了多少
+arkcli billing list --start 2026-05 --split-dim apikey      # 每把 key 各花了多少
+
+# 我的调用费用：本人当前 Active API Key 归属 (SSO 子用户视角)
+arkcli billing list --start 2026-05 --mine --mine-by=apikey
+
+# 我部署的接入点上的费用，可能包含他人调用；CLI 默认也是此维度
+arkcli billing list --start 2026-05 --mine --mine-by=endpoint
+
+# 其他过滤
+arkcli billing list --start 2026-05 --product ark_subscription  # 看订阅类账单
+arkcli billing list --start 2026-05 --bill-category consume-use --billing-mode 2
+arkcli billing list --start 2026-05 --ignore-zero
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|---|------|
+| `--start` | **是** | 单个账期 `YYYY-MM` (距今 24 个月内) |
+| `--end` | 否 | 范围终点 `YYYY-MM` (闭区间,省略 = 单月,最多 24 个月) |
+| `--day` | 否 | 账单日 `YYYY-MM-DD`，必须属于 `--start` 的月份，**仅 `--interval=day\|detail` 生效**，不能与跨月 `--end` 范围组合 |
+| `--interval` | 否 | `month` (默认) / `day` / `detail` |
+| `--endpoint` / `--apikey` / `--apikey-sid` | 否 | 单值 scope,三方互斥 (SplitItemID 单值)。`--apikey ark-*` 自动经服务端反查成 SID;`--apikey-sid` 跳过反查 |
+| `--split-dim` | 否 | 账号维度切片: `apikey` / `endpoint`。**显式 scope 已隐含维度,split-dim 必须一致或不传** |
+| `--product` | 否 | 火山产品编码 (可重复)。**ARK 大模型推理 = `ark_bd`**;订阅类 = `ark_subscription` |
+| `--project` | 否 | 项目 ID (可重复)。**不传时自动用 profile 的 ProjectName 当默认值**;`--project=` (空)= 账号全量 |
+| `--instance-no` | 否 | 计费实例 ID |
+| `--bill-category` | 否 | `consume-use` / `consume-new` / `consume-renew` / `consume-formalize` / `consume-modify` / `consume-trial` / `refund-terminate` / `refund-modify` / `transfer-manual` / `transfer-system` |
+| `--billing-mode` | 否 | `1` 包年包月 / `2` 按量 / `3` 合同 / `4` 履约 |
+| `--ignore-zero` | 否 | 跳过折后价 = 0 的行 |
+| `--mine` | 否 | 仅看当前 SSO 子用户名下资源的账单。维度由 `--mine-by` 决定。**跟 `--endpoint` / `--apikey` / `--apikey-sid` / `--split-dim` 互斥**。订阅类不含 (没 IAM 归属) |
+| `--mine-by` | 否 | `endpoint` (默认,**infra ownership** — 我部署的 EP 上的账单,含他人调;跟 usage stats 默认对齐) / `apikey` (**Key 归属** — 当前列出的本人 Active Key 产生的账单)。两视图选择的资源不同，不能相加或互相替代；后者不是 wire PayerID，也不证明每次调用都由本人发起 |
+| `--limit` / `--offset` | 否 | 分页模式 (Limit 1-300,wire 硬上限),单页直返。在 fan-out 时是 **per-fan-out 各 N 行** (跨月 `--end` / `--mine` 多资源),`partial_failures[]` 标 `windowed sample` |
+| `--output` | 否 | 写完整 JSON (items + summary + partial_failures) 到 FILE,stdout 只剩 metadata 不爆 context。自动放宽内部 cap 到 300k 行 |
+
+## Scope 视图能力
+
+不同 scope 覆盖的账单子集不一样。**`ark_subscription` (Agent Plan / Coding Plan) 只能在账号维度看,任何 IAM/EP/apikey 维度都看不到**(账号级归属,没 IAM owner)。
+
+Volc 默认使用二进制内置的 9 个 API Key 可分账产品白名单，已覆盖
+大模型推理、图像、开源模型及 Managed Agent 账单。用户显式传
+`--product` 时仍尊重用户指定的产品范围。
+
+| 视图 | ARK 推理 / Agent (9 product) | 订阅类 (`ark_subscription`) |
+|---|---|---|
+| 裸跑 (默认) | ✅ | ❌ (默认 Product 锁过滤) |
+| `--product ark_subscription` | ❌ | ✅ |
+| `--product ark_bd --product ark_subscription` | ✅ | ✅ |
+| `--endpoint` / `--apikey` / `--apikey-sid` / `--split-dim` / `--mine` | 各自 scope | ❌ |
+
+**`--mine-by=endpoint` 跨产品覆盖**: SplitItemID `ep-...` 是跨产品 unique 主键,`+deploy` 出来的 endpoint 账单会落在不同 Product 字段下 (LLM → `ark_bd`,图片 → `Doubao-image-generation`,视频 → `ark_bd` 等);service 层不锁 Product 让 wire 按 SplitItemID 自然跨产品命中。所以 `--mine --mine-by=endpoint` 会把图片 / 视频 EP 的账单也包含。两个 mine 视图同一笔消费各出现一次,**不可加和**。
+
+当前 Volc 的 `resolveMyAPIKeySIDs` 从本人 Key 列表中只保留 `Active=true` 且 SID 非空的条目。查历史账期时须披露这一资源集合限制；未查询到已停用/删除 Key 的历史费用不等于这些费用不存在。空结果不改变用户指定的归属，补查另一维度时必须明确它是另一种范围。
+
+**`--mine` ≠ `PayerID`**:
+- `--mine` 按 **IAM 子用户** UserID 过滤 (客户端先列我的资源 ID,service 层 per-resource fan-out)
+- wire 的 `PayerID` / `OwnerID` 是 **账号 owner ID** (10 位整数),用于财务托管场景
+- 单账户场景手撸 `--params '{"PayerID":[<我账号 ID>]}'` 是 no-op (= 全账号查询);要看自己用 `--mine`
+
+## 返回值
+
+以下是字段齐全的形状示例，不保证每次返回都包含所有字段。固定Volc契约中的日期、币种和金额字段允许省略；先检查实际记录，再选择统计字段，不能把示例当作必填schema。
+
+```json
+{
+  "items": [
+    {
+      "BillPeriod":         "2026-05",
+      "BillingDate":        "2026-05-15",
+      "Product":            "ark_bd",
+      "ProductZh":          "字节跳动大模型服务（豆包大模型）",
+      "SplitItemID":        "ep-...",
+      "SplitItemName":      "doubao-pro-4k-prod",
+      "Currency":           "CNY",
+      "OriginalBillAmount": "123.4500",
+      "PreferentialAmount": "10.0000",
+      "PayableAmount":      "113.4500",
+      "Count":              "1234567",
+      "Unit":               "千tokens"
+    }
+  ],
+  "total_records": 87881,
+  "returned": 3000,
+  "is_truncated": true,
+  "partial_failures": [
+    {
+      "period": "2026-05",
+      "total": 87881,
+      "returned": 3000,
+      "reason": "exceeds 10 pages cap (3000 rows scanned, total 87881 rows). Options: --limit/--offset to sample / page through; --split-dim apikey|endpoint to aggregate server-side; --endpoint/--apikey to narrow scope; --page-limit=N to raise the cap"
+    }
+  ]
+}
+```
+
+| 字段 | 含义 |
+|------|------|
+| `BillPeriod` / `BillingDate` | 账期 / 账单日；`BillingDate`即使在day/detail查询中也可能为空或缺失，不能据此过滤成零账单 |
+| `Product` / `ProductZh` | 产品编码 / 中文名 |
+| `SplitItemID` / `SplitItemName` | 拆分项 ID / 名字 (endpoint 或 apikey,取决于 scope) |
+| `Currency` | 通常`CNY`；缺失时须有真实接口/账单币种证据才能称人民币，多币种分开汇总 |
+| `OriginalBillAmount` | 优惠前金额 |
+| `PreferentialAmount` | 可选的优惠/资源包抵扣金额，缺失不等于零，也不妨碍汇总已有应付金额 |
+| `PayableAmount` | **应付金额**，对账主字段；缺失行不按零补齐。不可仅因字段名就假定各金额项满足某个等式 |
+| `Count` / `Unit` | 计量值 / 单位 |
+| `total_records` / `returned` / `is_truncated` | summary 头: 服务端真实总数 / 本次返回行数 / 是否截断 |
+| `partial_failures` | 软截断 / sample 标记数组 (撞 cap 或 windowed); 每项含 `period` / `resource` / `total` / `returned` / `reason`,**`is_truncated=true` 时必查** |
+
+> 金额字段是字符串,加和 / 比较用 decimal 库,不要 `parseFloat` (JSON 数字精度有损)。
+
+### 本周、近N天与缺日期字段
+
+1. 先从真实运行时取得当前日期和时区；用户指定历史日期、时区或周起点时优先采用。默认周一开始的本周截至当天：用日历库取`today - timedelta(days=today.weekday())`至`today`；近N天则是`today - timedelta(days=N-1)`至`today`。这两个区间不等同。星期同样由工具计算，不按记忆填。保存本次日级起止、时区、资源归属与产品过滤，后续所有分片复用。
+2. 按覆盖月份查询`--interval day`后先看真实记录。只有逐行日期可用且符合实际日期格式时，才能按原闭区间筛选；日期缺失的非空记录不能当作“本周无账单”，也不能拿整个账期的合计代替原区间。
+3. 缺少逐行日期时，在原区间内串行补查`arkcli billing list --start <该日YYYY-MM> --interval day --day <YYYY-MM-DD> --output <该日文件>`，并保留原归属/产品/Project过滤。每个日期只收集一份成功完整结果，`--day`不与跨月范围混用。汇总记录查询日期及原始文件来源；这是请求范围证据，不给原行伪造`BillingDate`。若返回明确与日期约束矛盾，保留错误并说明无法确认，不能继续作精确日归属。
+4. 每片先校验退出状态、业务错误、截断、partial_failures以及文件摘要与行数。完整成功且`total_records=returned=0`、`items`为空数组或null，只表示该范围本次无已出账行；当日T+1或历史Key覆盖缺口仍须说明。请求失败、缺字段、部分返回与截断不能直接`items or []`后按零并入总额；保留失败日期并把合计标为已获取部分。
+5. 用Decimal汇总实际`PayableAmount`，同一份合格记录生成所有展示值。缺少优惠字段不阻断已有应付金额统计，也不臆造优惠；金额无法解析或应付字段缺失时报告缺口。确需用优惠前与应付之差时，只对同范围、同币种、两字段齐全的记录计算，并标为“计算差额”，不冒充接口返回的优惠/资源包抵扣细目。T+1未结算不擅自向前扩日期或按旧金额补齐。
+
+## 软截断 (cap / windowed) 决策
+
+撞 cap 或显式 `--limit/--offset` 时 service **不 hard fail**,返已抓数据 + summary 头 + stderr 强警告。agent 看 `partial_failures` 选下一步:
+
+| `partial_failures[].reason` | 含义 | 推荐处理 |
+|---|---|---|
+| `exceeds N pages cap (...)` | 默认全量模式撞 service 兜底 cap | 想全量明细 → `--output FILE` (自动放宽 cap 到 300k 行,落盘);只要总金额 → `--split-dim apikey\|endpoint` 服务端聚合;sample 够 → 用现状;缩到单资源 → `--endpoint`/`--apikey` |
+| `windowed sample (limit=L, offset=M); returned X of Y rows` | 用户主动开 `--limit/--offset` 拿 sample | 用户已知是 sample;循环 `offset += limit` 客户端拼全量,或换 `--output FILE` 全量落盘 |
+
+跨 fan-out (`--end` 跨月 / `--mine` 多资源) 的 `--limit/--offset` 是 **per-fan-out** 各 N 行 (returned ≤ limit × fanout_count); 每个 fan-out 在 `partial_failures` 各占一项,标 `period` / `resource` 字段。
+
+### 深分页与限流恢复
+
+- 多天明细或跨月深分页遇到服务端 offset 上限、429 或部分截断时，保留原始错误、已完成范围和剩余范围；不要继续无限增加 offset 或并发扫页。
+- 按原用户时间范围拆成 `--interval detail --day YYYY-MM-DD` 的逐日查询，保留原 Endpoint/API Key/产品过滤和身份，不擅自缩成最近几天或扩大账号范围。每片先检查退出码、业务错误、`is_truncated` 和 `partial_failures`，再汇总；失败片不按零计费。
+- 默认串行；429 按服务端等待提示退避，反复失败则交付已完成部分和缺口，不不断重放。若单日仍超过上限，按真实资源分片或说明当前导出边界，不能声称全量。
+- Vaka 1.0.32 曾记录 `offset=1800` 的上限，但当前客户端没有这一固定阈值，上游适用范围也尚未确认。不得把它承诺为所有账期/维度的统一上限；实际遇到该错误仍按上面的分片流程恢复。
+
+## --output FILE 模式
+
+落盘大数据避免 stdout 灌爆 agent context。跟 `train finetune logs/metrics/trajectory` 的 `--output` 一致:
+
+```bash
+arkcli billing list --start 2026-05 --output bills.json
+#   ↳ stdout: {total_records: 87881, returned: 87881, is_truncated: false, output_file: "bills.json"}
+#   ↳ bills.json: 完整 JSON (含 87881 行 items + summary + partial_failures)
+```
+
+- service 自动把内部 cap 抬高到 1000 pages (300k 行 / ~100 MB 内存),覆盖绝大多数大账户全量
+- stdout 只剩 metadata (items=null + output_file 路径) — agent context 安全
+- 统计读取`output_file`中的完整JSON，核对其summary和实际行数；不能用stdout的null判断没有消费。原始明细保留，只展示必要的结构样本与本地计算结果。
+- 用户显式 `--page-limit=N` 仍尊重 (用户传的优先)
+- 仍超时 partial_failures 会标,再放宽 `--page-limit`
+
+## 客户端循环翻页范式
+
+需要拼全量数据时 (撞 cap 或 windowed sample 都适用):
+
+以下示例故意保留 stderr。不要加 `2>/dev/null`：scope 提示、软截断 WARN 和部分失败原因可能只写在 stderr，吞掉后会把不完整结果误当成全量。
+
+**单月分页拉全量**:
+```bash
+total=$(arkcli billing list --start 2026-05 --limit 1 | jq '.total_records')
+offset=0; all="[]"
+while [ "$offset" -lt "$total" ]; do
+  page=$(arkcli billing list --start 2026-05 --limit 300 --offset "$offset" | jq '.items')
+  all=$(jq -n --argjson a "$all" --argjson b "$page" '$a + $b')
+  offset=$((offset + 300))
+done
+echo "$all" | jq 'length'   # 应等于 total_records
+```
+
+**跨月嵌套翻页拉每月全量** (外层 fan-out + 内层 +offset):
+```bash
+for m in 2026-03 2026-04 2026-05; do
+  total=$(arkcli billing list --start "$m" --limit 1 | jq '.total_records')
+  offset=0; items="[]"
+  while [ "$offset" -lt "$total" ]; do
+    page=$(arkcli billing list --start "$m" --limit 300 --offset "$offset" | jq '.items')
+    items=$(jq -n --argjson a "$items" --argjson b "$page" '$a + $b')
+    offset=$((offset + 300))
+  done
+  jq -n --arg m "$m" --argjson t "$total" --argjson it "$items" '{month:$m, total:$t, items:$it}'
+done | jq -s '.'
+```
+
+客户端翻页**不受** `--page-limit` cap 限制 (cap 只在默认全量模式触发)。
+
+## 常见错误
+
+| 错误 | 处理 |
+|------|------|
+| `--start is required` / `must be YYYY-MM` | 加或修正 `--start 2026-05` (距今 24 个月内) |
+| `--end ... must be >= --start` / `range exceeds 24 months` | 调整范围 |
+| `--day ... incompatible with --start/--end range` / `requires --interval=day or detail` | 单月 + 同月 day,或去掉 `--day` |
+| `--endpoint, --apikey, --apikey-sid are mutually exclusive` | 三选一 (SplitItemID 单值) |
+| `--split-dim ... incompatible with --endpoint/--apikey` | 让 split-dim 跟显式 scope 一致或不传 |
+| `--apikey value too short` (<16) | 改完整 ark-*,或如果只有 SID 改 `--apikey-sid` |
+| `couldn't resolve API key` | 切到正确 profile,或直接传 `--apikey-sid` |
+| `not logged in` / SSO 失效 | `arkcli auth login volc-sso` |
+
+> **撞 cap 不在错误码表** — 软截断走正常返回路径 (ok=true + is_truncated=true + partial_failures + stderr WARN)。详见上面"软截断决策"段。
+
+## 注意事项
+
+- **T+1 出账**: 当月当日数据可能不全,月度对账建议月初拉**前一个完整账期**
+- **数据量大**: 单账期 ARK 账单常上万行,默认 cap ~3000 条 (~1 MB JSON);首选 `--split-dim` 服务端聚合,sample 用 `--limit`,要全量明细放宽 `--page-limit`
+- **金额是 CNY 字符串**: 用 decimal 库,不要 `parseFloat`
+- **默认锁 9 个支持 API Key 分账的 ARK / Agent 产品**: 防 EIP / TOS / VDB 等非 ARK 产品脏返回,**不含 `ark_subscription`** — 看订阅类显式 `--product ark_subscription`
+
+## 参考
+
+- [arkcli-billing](../SKILL.md) — billing skill 概览
+- [usage stats](../../arkcli-usage/references/arkcli-usage-stats.md) — 推理用量 (Token / 请求数)
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,50 @@
+# 统计与账单交付回归
+
+以真实命令输出验收，不能把本页数值注入线上实验题，也不能用关键词存在代替正确结果。
+
+| 场景 | 输入与证据 | 验收 | 失败样例 |
+| --- | --- | --- | --- |
+| 按品牌查询次数与费用 | 用户说“我想查询豆包调用次数及费用”；14 条 usage 记录合计 34 次，其中 DeepSeek 3 次、豆包 31 次 | 按真实模型过滤为 31 次；披露实际身份、Project 和查询日期；“我想查询”不自动触发本人资源限定 | 把 34 次全归豆包；无本人限定却追加 mine |
+| 跨口径单位 | usage 总 Token=1,083,817，其中 Seedance=980,786；某账单计费项 Count=326.7，Unit=千 Token | usage 剩余=103,031；账单该项=326,700 Token，分开报告，不跨范围相减 | 用 1,083,817−326,700=757,117 归到其他模型/请求 |
+| 跨月周账单 | 本周起止日期跨两个账期；用户要本人调用费用，API Key 维度有结算记录 | 显式选择 Key 归属，用日历工具固定本周区间；覆盖两个账期，有日期按 BillingDate 过滤、缺日期按原区间逐日补查；此前误用 Endpoint 时说明口径纠正；已出账金额与估算分别标注 | 只查一个月、把整月或 Token×单价说成实际周账单、把另一个归属视图叫作同范围重试 |
+| 部分失败与截断 | API 失败、鉴权失败或 is_truncated=true | 保留错误，不能报告零费用或将部分 rows 合计称全量 | 隐藏 stderr，空数组一律当零费用 |
+
+真实回归 Case：Viking 300/V10 的 163601、163678；修复前证据见累计实验文档及冻结 4297 结果。单位依据 `internal/apis/billing/list_split_bill_detail.go`；月范围依据 `internal/service/billing/service.go`；usage 合计依据 `internal/service/usage/usage.go`。
+
+## 同一快照的总量、Top N 与其余项（4341/163601）
+
+失败已复现：实际已加载账单范围修复后的完整 Skill。一次返回的33个模型请求数合计43609，Top10合计37530，其余23项合计6079；随后再次查询得到总数43610。最终回复混用后一总数与前一Top10，另报“其余约6084次”，既不等于6079，也不等于两份快照混算的6080。官方效果0.50（答案1.00、计算错误扣0.50），不能靠加“约”或重跑查询抹去错误。
+
+通过条件：一次完整查询落盘，按同一身份/日期/模型过滤得到一份记录集合；总量、Top N、其余项的数目和合计全部由该集合在一次本地计算中生成，表格、文字与卡片复用这些结果。断言“总数=Top N合计+其余合计”与“模型数=N+其余模型数”（不足N按实际项数），整数保持精确，金额使用Decimal后统一舍入。再次查新数据时整组替换，不能只更新总数；无完整明细时披露缺口，不凑差额。
+
+对照：空记录但查询成功、不足N项、同分项、计数超出浮点精确整数范围、金额舍入、部分失败/截断、前后查询增加1次。已知非空明细应能还原43609/37530/6079，并拒绝6084；这只是本地算术校准，不代表云端Agent已遵循新规则。
+## 本人消费的归属口径
+
+失败依据：实际加载候选 Billing Skill 的4348/163678按Endpoint归属返回了正确合计，但Skill同时把Endpoint到Key切换写成“不改查询范围”。固定Volc源码的两个分支分别向`EndpointIDs`和`APIKeySIDs`注入不同资源集合，Key分支还只保留当前Active条目。历史GT的日期与资源状态不同，不能把分差当作金额算错的证据。
+
+| 场景 | 对照证据 | 通过条件 |
+| --- | --- | --- |
+| 本人调用费用 | 本人Key调用他人EP；他人Key也调用本人EP，两组消费不同 | 显式Key归属并说明覆盖，不因默认EP有数据就替代；不把两个视图金额相加 |
+| 本人部署的EP | 用户明确按自己部署的接入点统计 | 显式Endpoint归属，说明可能包含他人调用；不擅自改查Key |
+| 已指定资源但为空 | 指定EP无账单、另一Key有账单 | 保持原资源与日期，报告原范围未查到；不拿Key金额冒充EP金额 |
+| 历史停用Key | 历史账期有费用，但当前Key列表只含Active集合 | 披露资源覆盖限制，不宣称本人历史费用为零或已完整覆盖 |
+| 已知原查询误选维度 | 用户要调用费用，先查Endpoint却为空 | 可以纠正到Key并说明归属变化，保留账期/日期/Project；不是相同查询的环境重试 |
+| 非自指与订阅 | “我想看整个账号账单”或明确订阅费用 | 不因“我想”缩成个人Key；订阅保持账号/订阅范围，不混入mine视图 |
+
+原题回归不得改写用户query或注入固定金额/日期；根据当次真实命令及输出判定归属、完整性和计算。上述源码复核与静态检查不能替代云端Agent执行验收。
+
+## 日历区间与可选账单字段
+
+失败依据：4356/163678运行日期为上海时区2026-10-05（周一），却查询09-29至10-05并称为本周；该区间实际是近7天。首次对缺失`BillingDate`的2636条记录做字符串过滤，得到伪空结果；随后逐日查询，又因假设`PreferentialAmount`必有、空`items`必为数组而两次解析失败。最终金额计算正确不代表日期范围正确。旧“按BillingDate筛本周”规则未处理该字段可选；不能据此把日期错误归因于新的Key归属规则。
+
+| 场景 | 已知证据 | 通过条件 |
+| --- | --- | --- |
+| 周一与近7天 | 2026-10-05，Asia/Shanghai | 本周截至当天仅10-05；近7天才是09-29至10-05。用日历工具验证，不靠心算星期；T+1未出账不扩大到上一周补数 |
+| 周日、跨年、闰日 | 2026-10-04、2027-01-01、2028-02-29 | 本周起点分别为09-28、12-28、02-28；跨月覆盖所有涉及账期，日期计算不抄历史GT |
+| 日期已指定 | 用户明确另一时区、周日起算或历史绝对区间 | 遵从用户日历口径，不被运行机器时区或默认周一覆盖；仍披露起止闭区间 |
+| 缺少BillingDate | 日汇总返回非空记录但无逐行日期 | 不过滤成零；在原区间内按日查询，`--start`匹配该日账月，保留请求日期来源，不给原记录伪造BillingDate |
+| 可选金额缺失 | PayableAmount存在，PreferentialAmount缺失 | 应付金额仍能用Decimal汇总；不抛KeyError、不把缺失优惠写为零；核心金额或币种证据缺失时披露覆盖缺口 |
+| stdout与落盘结果 | stdout items=null且returned>0，输出文件含完整明细 | 读取落盘文件；校验退出状态、summary、截断及partial_failures，不能将stdout的null说成零费用 |
+| 真空与部分失败 | 完整成功且total_records=returned=0、items=null；另一个日期请求失败 | 前者仅说明本次未查到已出账行；后者保持缺失，不能一律`items or []`后当作完整零账单 |
+
+本地日历与解析fixture只校准工具，不代表云端Agent通过。原题回归必须核对实际查询参数、原始输出、覆盖范围和最终答复；保持固定CLI、测试身份与原query。