arkcli-billing

name	arkcli-billing
version	1.1.1
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 (认证 / 全局规则) 和 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;想看"花了多少钱"→ 本 skill。

Step 0(MUST):查"我的账单"先按 profile 路由

跟 arkcli-usage 的 Step 0(canonical 原则)同一套 —— 先查"自己这档 profile 的套餐账单",再查 endpoint 账单。查任何"我…花了多少"前必走:

1. 探 profile.type:arkcli profile show --format json,读 type
2. 定模态:用户点名模型/模态 → 只查该模态;没点名 → 全模态都覆盖
3. 按 (type × modality) 路由(①→② = 先套餐账单、再 endpoint 账单;单格 = 只查 endpoint 账单):

profile.type	text	image / video
agent-plan / agent-plan-team	① arkcli billing list --start <YYYY-MM> --product ark_subscription ② arkcli billing list --start <YYYY-MM> --mine	同 text(全模态都先套餐、再 endpoint)
coding-plan / coding-plan-team	① arkcli billing list --start <YYYY-MM> --product ark_subscription ② arkcli billing list --start <YYYY-MM> --mine	arkcli billing list --start <YYYY-MM> --mine(套餐不覆盖)
platform	arkcli billing list --start <YYYY-MM> --mine(无套餐)	arkcli billing list --start <YYYY-MM> --mine

依据同 usage:Agent Plan 套餐覆盖三模态、Coding Plan 套餐只覆盖文本、Platform 无套餐。套餐账单走订阅类必须显式 --product ark_subscription(默认 scope 不含订阅,见下方「Agent 关键纪律」);endpoint 账单 --mine 的撞空 fallback 见下。每条 billing list 必带 --start <YYYY-MM>(月单位,缺省即报 --start is required;查多月范围再加 --end <YYYY-MM>)。

快速决策

用户问	命令
我这个月 / 上个月花了多少 (含"我"语义)	先过 Step 0(本文档顶部):plan profile(agent / coding-text)先 arkcli billing list --start <YYYY-MM> --product ark_subscription 套餐账单、再 arkcli billing list --start <YYYY-MM> --mine endpoint 账单;platform 或非覆盖模态直接 arkcli billing list --start 2026-05 --mine — 撞空有 fallback 流程见下
整个账号花了多少 / 公司账号 / 整体 (无主语自指)	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 fallback 流程 (跟 usage stats 对齐)

用户问"我...花了多少"时:

• 火山: 先 arkcli billing list --start <YYYY-MM> --mine(默认 --mine-by=endpoint)
  • 有数据 → 用 partial_failures 检查截断后,告诉用户金额合计
  • 撞空 (no endpoints owned by current sub-user) → 立即重试 --mine --mine-by=apikey
  • 仍撞空 → 报告用户"该子用户在该账号下零资源,账单可能是主账号 / 其他子用户产生的",问是否切主账号或换 profile
  • ⛔ 禁止退化为不带 --mine 的全量查询 — 全账号金额 ≠ "我花的",一旦丢 --mine 范围语义就跑偏(对齐 arkcli-usage 的同条款)

dim 间 fallback (endpoint→apikey) agent 可以自动重试,因为同 mine 语义、不改查询范围;但不能丢 --mine 退到全量(那是改语义)。

Agent 关键纪律

• 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
• 想看推理量 (token / 请求数) → ../arkcli-usage/SKILL.md
• 想看模型 / 套餐价格目录 → ../arkcli-pricing/SKILL.md

命令一览

命令	说明
billing list	拆分账单明细查询(结算金额 × Token 用量)