需要查 Cargo 余额/用量/账单或预估批处理成本时：用…

在已登录且有 admin 权限的 Cargo 工作区中，通过 cargo-ai billing 命令查询余额、用量、订阅、发票，估算并监控批处理成本，以及添加/更新付款卡。

适用场景

解决思路

1. 检查是否已登录：运行 `cargo-ai whoami`；若返回工作区则跳到后续步骤，否则执行引导。
2. 安装 CLI：`npm install -g @cargo-ai/cli`；若不使用全局安装，则在每条命令前加 `npx @cargo-ai/cli`。
3. 登录：运行 `cargo-ai login --email you@company.com`（邮件验证码，无浏览器；首次使用会创建账户）；替代方式为 `--oauth`（浏览器）或 `--token <api-token>`（CI）。
4. 在任何写入前确认活动工作区：运行 `cargo-ai whoami`。
5. 注意输出：所有命令向 stdout 打印 JSON；失败时以非零退出并返回 `{"errorMessage": "..."}`；任何创建 run 或 batch 的操作都是异步的，要传 `--wait-until-finished` 或轮询对应的 `get`。
6. 注意权限：本技能所有命令都要求工作区 admin 权限令牌；非 admin 令牌返回 `{"errorMessage":"forbidden"}`。
7. 先发现资源：因为用量指标可按资源 UUID 过滤和分组，查询前先发现资源。
8. 发现 play：`cargo-ai orchestration play list`（name、workflowUuid）。
9. 发现 tool：`cargo-ai orchestration tool list`（name、workflowUuid）。
10. 发现 agent：`cargo-ai ai agent list`（uuid、name）。
11. 发现 connector：`cargo-ai connection connector list`（uuid、name、integrationSlug）。
12. 发现 model：`cargo-ai storage model list`（uuid、name、slug）。
13. 快速查询用量：`cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD>`。
14. 按 workflow 分组查询用量：`cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD> --group-by workflow_uuid`。
15. 查询订阅：`cargo-ai billing subscription get`。
16. 查询发票：`cargo-ai billing subscription get-invoices`。
17. 更新付款方式：`cargo-ai billing subscription update-payment-method --card-number <number> --card-exp <MM/YYYY> --card-cvc <cvc>`。
18. 创建 Stripe 自助账单门户会话：`cargo-ai billing subscription create-portal-session`。
19. 估算大 batch 前成本 Step1 检查当前信用余额：运行 `cargo-ai billing subscription get`；剩余信用 = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`。
20. Step2 用样本 run 估算成本：先对单条记录运行工作流：`cargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'`；轮询至完成。
21. Step2 继续：查询该次 run 消耗的信用：`cargo-ai billing usage get-metrics --from <today> --to <today> --workflow-uuid <uuid>`；读取 `metrics[].items[]`（响应只有一个键 `metrics`，没有 `totalUsage`）。
22. Step3 投影 batch 成本：`estimated_cost = (credits_per_record × number_of_records) + (nodes_per_record × number_of_records / 100)`。
23. Step3 说明：第二项是每次执行 0.01 信用平台费；样本 run 可免费测量它——该记录的 execution 数是 `length(run.executions)`，或样本窗口 `--unit orchestration.executions` 的一行。忽略它会让每个步骤多的图报价偏低。
24. Step3 比较：在执行前与 `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` 比较。
25. Step4 在 batch 执行期间监控：`cargo-ai billing usage get-metrics --from <start-date> --to <today> --workflow-uuid <uuid>`。
26. 成本杠杆：使用更便宜模型（例如 `gpt-4o-mini` 对 `gpt-4o`），可显著降低 AI 节点成本。
27. 成本杠杆：在图早期添加 `filter` 节点，在昂贵连接器调用前跳过不合格记录。
28. 成本杠杆：设置 `fallbackOnFailure: false`，失败时尽早停止 run，而不是继续下游节点。
29. 成本杠杆：减少 agent 节点上的 `maxSteps`，限制每个记录允许的 tool 调用次数。
30. 成本杠杆：削减节点数——合并链式 `variables`、把分支对折成一个 `switch`；每次执行 0.01 × 记录数，是步骤主导而 provider 不主导的图的唯一杠杆。
31. 在选杠杆前，若要知道哪个节点或 provider 主导 play 花费，遵循 `../cargo-diagnostics/references/play-optimize-credits.md` 中的归因 runbook。
32. 按时间范围拉取信用和用量数据，可选过滤和分组。
33. 分组维度：`--group-by workflow_uuid`、`--group-by connector_uuid`、`--group-by integration_slug`、`--group-by model_uuid`、`--group-by agent_uuid`。
34. 按具体资源过滤：`--workflow-uuid <uuid>`、`--agent-uuid <uuid>`、`--connector-uuid <uuid>`、`--integration-slug <slug>`。
35. 一次只用一个 unit：`--unit billing.credits`、`--unit orchestration.executions`、`--unit storage.records` 是唯一接受的值。
36. `--group-by` 可用值：`workflow_uuid`、`connector_uuid`、`model_uuid`、`integration_slug`、`agent_uuid`。
37. 可用过滤器：`--workflow-uuid`、`--model-uuid`、`--connector-uuid`、`--integration-slug`、`--slug`、`--agent-uuid`；可与 `--group-by` 和 `--unit` 组合。
38. 处理三个用量单位：`--unit` 只接受 `billing.credits`、`orchestration.executions`、`storage.records`；其他值会返回 400 并列出它们。
39. 不带 `--unit` 时，三种单位会交错在同一个 `items[]` 数组中，且 `count` 字段不是同一量纲；要从 slug 读取单位。
40. `billing.credits`：slug 为 `integration.<slug>.action.<action>`、`native.<action>`、`integration.<slug>.chat`、`integration.<slug>.extractor.<name>`；`count` 是信用（小数）。
41. `orchestration.executions`：slug 为 `success`、`error`；`count` 是节点执行次数，一比一计数，不是信用。
42. `storage.records`：slug 为 `insert`；`count` 是写入记录数。
43. 当数字要用于估算时，总是传 `--unit`；不要用未限定 unit 的调用把执行次数和信用混在一起。
44. 理解执行费：每次节点执行计费 0.01 信用——每 100 次执行 1 信用；适用于每种节点和每个节点，包括结构性 native 节点 `branch`、`filter`、`switch`、`split`、`group`、`variables`、`start`、`end`；没有免费步骤。
45. 注意执行费不按节点归因：`run get` 的 `executions[].creditsUsedCount` 和 `spans.execution_credits_used_count` 只包含 provider 成本，在仍计费的 native 节点上会读为 `0`；逐节点归因会低估每个图，缺口随步骤数而非花费增长。
46. 查看执行费的唯一入口：`cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD> --unit orchestration.executions`；`items[] = [{"slug":"success","count":<executions>}, {"slug":"error","count":<executions>}]`；credits = `(success + error) / 100`。
47. 用运行时表交叉核对：`cargo-ai orchestration query execute "SELECT execution_status, count() AS executions, count() / 100 AS credits FROM spans WHERE execution_started_at >= '<YYYY-MM-DD>' GROUP BY execution_status"`。
48. 估算时使用两个成本项：`credits = (provider cost per record × records) + (nodes per record × records ÷ 100)`；第二项在 credits 成本表中不可见，因为该表给 actions 定价而不是 steps。
49. 识别执行费影响：它在 action 密集的 play 中相对小（例如每条记录 LinkedIn enrich 远超其 8 步），在步骤密集、action 少的图中占主导（12 节点路由 sweep 处理 20,000 条记录 = 2,400 信用且无 provider 调用）；出错的执行也计费，晚失败的图会为其整个前缀计费。
50. 处理 tool fan-out：tool 节点是一次执行，加上 tool 自身图内每个节点，各自单独计费；把子图提取成 tool 是可调试性收益，不是成本节省——每条记录额外增加一次执行，内部成本仍在。当图的执行数超过可见节点数，先查 tool 节点：在 `spans` 中按 `node_slug` 分组找到它们。
51. 查询订阅和信用：`cargo-ai billing subscription get` 返回当前计划、已用/可用信用、周期日期；`get-invoices` 返回发票历史（金额单位为 cents）；`get-credit-card` 返回存档卡；`update-payment-method` 添加或替换卡；`create-portal-session` 返回 Stripe 门户 URL 用于自助账单。
52. 从 `subscription get` 计算剩余信用 = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`。
53. 发票金额为 cents，除以 100 得美元值。
54. 免费层：新账户以 100 免费信用开始且没有存档卡。
55. 当 `subscription get` 显示新账户或接近新账户余额时，用该预算回答成本问题；例如回答“你已用掉 100 免费信用中的 12”才是对“我进度如何”的有用且诚实的答案，尤其当用户决定是否继续时。
56. 用 100 信用能买什么的锚点：`salesNavigator.searchLeads` 0.02/记录 ≈ 5,000 leads；`aiArk.enrichPerson` 0.1 ≈ 1,000 people；`waterfall.verifyEmail` 0.1 ≈ 1,000 checks；`waterfall.enrichContact` 2 ≈ 50 contacts；`FullEnrich.findPhone` 6 ≈ 16 numbers。
57. quickstart demo 花费约 0.5。
58. 电话查找是烧完免费层最快的方式，所以 phone 是受保护杠杆：escalation tier 为 3–7 credits/record，约 10× email，绝不该进入默认链；仅在用户明确要求且仅对合格 leads 时进入计划；完整 spend 规则见 `../cargo-gtm/references/cost-discipline.md`。
59. 添加卡：一个工作区只有一张卡；`update-payment-method` 设置它，无论是否已有卡，接受三种方式。
60. 方式 1 直接传卡详情（无浏览器、无需交接）：`cargo-ai billing subscription update-payment-method --card-number 4242424242424242 --card-exp 12/2030 --card-cvc 123`。
61. 方式 2 用 stdin 传 JSON（避免卡号进入 shell history 和进程列表）：`echo '{"number":"4242424242424242","expMonth":12,"expYear":2030,"cvc":"123"}' | cargo-ai billing subscription update-payment-method --card-stdin`。
62. 方式 3 不传卡详情：`cargo-ai billing subscription update-payment-method`；它会打印 Stripe 托管表单 URL 并等待卡提交。
63. 优先 `--card-stdin`；任何通过 flag 传的内容都会在 shell history 和可读进程列表的进程里可见；卡详情从本机直接到 Stripe 换 token，绝不经过 Cargo API，也不会被输出打印。
64. 绝不要编造卡详情，也不要复用对话中其他地方出现的卡号；向用户索要，或使用无参数形式并把 URL 交给用户。
65. 无参数形式是没有详情可提交时的回退：它打印一个直接打开卡表单的 URL，然后轮询直到卡变化（`--timeout`、`--poll-interval`、`--no-open`）；把该 URL 转给用户——它可通过 SSH 和沙箱工作。
66. 无论哪种方式，卡在成为默认前都会向发卡行验证，因此无法扣款的卡会在这里失败，而不是在下次续费时静默失败。
67. 处理失败 `cardDeclined` + `declineCode`：发卡行拒绝验证；读取 `declineCode`；在 spend-limited 虚拟卡上，`insufficient_funds` 或限额代码意味着预算/商户限制不允许，要求持卡人提高限额。
68. 处理失败 `authenticationRequired`：卡需要 3-D Secure，需要持卡人在场；用无参数重新运行并把托管表单 URL 交给用户。
69. 处理失败 `paymentMethodNotFound`：详情没有解析到可用卡；与用户重新核对卡号和有效期。
70. 卡更新每个工作区每小时限 10 次（与 setup intents 共享）；重试被拒绝的卡会消耗该预算——修复原因而不是循环重试。
71. 每个命令支持 `--help`：例如 `cargo-ai billing usage get-metrics --help`、`cargo-ai billing subscription get --help`、`cargo-ai billing subscription get-invoices --help`。

适用边界 · 注意事项

• 不适用于把花费归因到具体节点或削减 play 成本；这些应使用 cargo-diagnostics。
• 没有 admin 权限令牌时不要用；非 admin 令牌会返回 forbidden。
• 未安装 `@cargo-ai/cli` 或没有 Cargo 账户/工作区时不能直接使用，需先安装并登录。