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

package/skills/arkcli-plans/references/arkcli-plans-personal-rotate-apikey.md

@@ -0,0 +1,83 @@
+# plans personal rotate-apikey
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **⚠️ 写操作 / 毁坏性：** 调用成功后**原 APIKey 立即失效**，需要立即替换接入该 API Key 的模型 / Harness 配置以避免服务中断。默认走 [Y/N] 二次确认；脚本场景可加 `--yes` 跳过。
+
+轮换 Agent Plan **个人版** 的专属 APIKey。一次调用先查 `ListApiKeys` (Filter.Scene=`RealAgentPlanPersonal`)，仅提交一次 `UpdateApiKey {Id, Regen:true}`，再读 `GetRawApiKey` 并最多三次只读 `ListApiKeys` 核验同一 Id 为 Active；全部成功才返回新明文。
+
+## 排查错误时先区分发生阶段
+
+用户只要求解释或排查报错时，先保存原命令、时间、Profile/身份与错误；当前只读检查、后续写操作的拒绝、历史报错分开记录。不要为复现自动新建/切换 Profile、refresh 本地 Key 库存、导出明文或轮换 Key。按 [Key 查询契约](../../arkcli-auth/references/api-key-query.md)核对当前订阅与 `Filter.Scene=RealAgentPlanPersonal` 的完整元数据；查询失败保留未知。
+
+| 实际证据 | 可以得出的结论 | 不能据此推断 / 下一步 |
+| --- | --- | --- |
+| `no Agent Plan 个人版 API Key found` | 本次 Scene 查询响应、Result 或 Items 为空，尚未进入本命令的 Update | 不是“没买套餐”的充分证据；CLI 购买 hint 是通用提示。当前查到订阅或 Key 也不能解释历史为空，需核对当时身份、时间与请求范围 |
+| `plan_agreement_identity_required` / `plan_agreement_status_unavailable` | 本次受保护操作在身份/协议状态门禁被拒或未能核验 | 不能倒推原 NoKeyFound 的根因，不能断言未签协议或签后一定补配 Key；依宿主恢复身份，不换 Action 绕过 |
+| `UpdateApiKey` 超时或返回错误 | 轮换未拿到成功回执；具体是否落地须看服务端证据 | 不保证原 Key 有效，也不自动重放 Regen；先核对同一 Id 的实际结果 |
+| Update 已成功，但 `GetRawApiKey` 或后置 Active 校验失败 | 写入已经发生，后续读取或状态核验失败 | 整条命令非零不等于“没轮换”；不能承诺旧 Key 仍可用或无中断，只做获准的只读核查 |
+| 返回 `status=success`、同一 `key_id` 与新明文 | 本次轮换、读取及管理状态校验成功 | `Active` 不等于外部客户端已换 Key/业务不中断；凭证仅交给获准的安全落点，另核对客户端是否已加载 |
+
+交付时先给原错误的已知语义，再列当前核验结果、后续操作结果和仍待确认的根因。原问题不能由新报错替换；没有独立证据时不说“已定位根因”“旧 Key 仍可用”或“已恢复”。轮换内部只写一次 `UpdateApiKey(Regen=true)`，随后最多三次 `ListApiKeys` 是只读状态核验，不是允许 Agent 重跑轮换命令。
+
+## 命令
+
+```bash
+# 交互式：会先弹 [Y/N] 确认
+arkcli plans personal rotate-apikey
+
+# 非交互（脚本 / CI）：跳过确认
+arkcli plans personal rotate-apikey --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--yes` | 否 | bool | 跳过 [Y/N] 二次确认（脚本/CI 友好） |
+
+## 返回值
+
+成功：
+```json
+{
+  "status": "success",
+  "key_id": 114788,
+  "api_key": "sk-rotated-new-secret"
+}
+```
+
+`api_key` 是**新明文**，跟 frontend Modal 弹出的 "新 APIKey" 同一份。务必立即保存。
+
+## 失败语义
+
+| 场景 | exit code | 输出 |
+|---|---|---|
+| 用户 [N] / EOF / 空回车取消 | 1（ExitGeneral） | `{"ok":false,"error":{"type":"cancelled","message":"operation cancelled"}}` |
+| 本次个人 Agent Plan Scene 查询没有返回 Key（response / Result / Items 为空） | 2（ExitValidation） | `{"ok":false,"error":{"type":"validation","message":"no Agent Plan 个人版 API Key found","hint":"Subscribe Agent Plan 个人版 first via \`arkcli plans buy --plan agent-plan ...\`"}}` |
+| transport / 服务端错 | 1（ExitGeneral） | 普通 error 上抛 |
+
+## 二次确认文案
+
+CLI 输出（stderr）：
+```
+确认更新专属 APIKey?
+更新后原 APIKey 将立即失效，请及时替换接入该 API Key 的模型及 Harness 配置，以避免服务中断。
+继续? [y/N]:
+```
+
+输入 `y` / `Y` 才放行；其它（含空回车 / EOF / 任何字符）都按取消。
+
+## 注意事项
+
+- 这条命令仅影响 Agent Plan **个人版** scoped APIKey（`Filter.Scene=RealAgentPlanPersonal`），**不会影响**普通 Platform / Coding 池的 APIKey
+- CLI 使用本次 Scene 列表的第一项；源码没有据此保证服务端最多只有一把。排查时保留真实记录，不凭普通池或本地库存推断专属池。
+- 跟 `arkcli auth` 持久化的 SSO STS / IDToken 无关 —— 那是 CLI 自己的鉴权链路，APIKey 是给数据面 SDK 用的
+- `ErrNoAgentPlanPersonalKey` 只对应本次 Scene 查询没有 Key；查询 transport 错另行返回。订阅资格与 Key 是否存在分开核验，不能把购买 hint 当成未订阅的证据。
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans get`](arkcli-plans-get.md) -- 先确认是否有 Agent Plan 个人版订阅
+- [`plans team rotate-apikey`](arkcli-plans-team-rotate-apikey.md) -- 团队版席位 APIKey 轮换
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-renew.md

@@ -0,0 +1,134 @@
+# plans renew
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **⚠️ 写操作 + 计费：** 跟 `plans buy` 同样 `IsAutoPay=true`，加 `--yes` 后自动扣款。失败语义（payment_failed envelope）也跟 buy 一致。
+
+> **🔒 协议闸门 (强制流程,跟 `plans buy` 完全同套路)：** 不传 `--yes` 时,本命令**不续费**,只返协议清单。Agent **必须**先把 `agreements` 数组逐条展示给用户,等用户**明确同意**全部协议后才能加 `--yes` 重跑 `next_step`。详见 [`plans buy` 协议闸门说明](arkcli-plans-buy.md)。续费走的是跟新购完全一样的协议清单 (frontend BuyWindow 同时承载 buy + upgrade)。
+
+续费已有套餐。个人版自动从 `ListSubscribeTrade` 反查 InstanceID；团队版按 `--seat-ids` 拼 `Items` 一次走 `RenewAgentPlanEnterpriseTrade`。
+
+## 选择续费对象
+
+- 复用本轮持有列表；只有一个与用户目标相符的套餐时直接复述并沿用，不再要求用户选同一个对象。多个套餐/席位仍可能匹配时，让用户选目标，不默认第一条。
+- 选项应带套餐家族、个人/团队、当前档位、真实席位 ID（团队版）与已确认的到期时间；到期时间按 [get 的有效期规则](arkcli-plans-get.md#到期时间--还剩多少天) 转北京时间，未查到就标“到期时间未知”，不伪造。
+- 只补缺少的续费月数或目标席位，每轮一个决策。1 / 3 / 6 / 12 个月可作快捷选项，但 CLI 合法范围是 1–12，不能拒绝用户明确给出的 2、4 等合法月份。
+- 保持原档位；不询问新购档位，不传 `--type` / `--quantity`。参数完整也不能跳过下述本轮协议与价格披露。
+
+## 三种调用形态
+
+跟 `plans buy` 一致:
+
+| 形态 | 行为 |
+|---|---|
+| 不传 `--yes` 不传 `--estimate` | 协议闸门,返协议清单 + **价格** + `next_step`,内部走 EstimatePrice (IsRenew=true / Scene=RENEW),不下单 |
+| `--estimate` | 在线询价，不带协议清单 (脚本"只询价"出口) |
+| `--yes` | 真续费,自动扣款 |
+
+> 闸门返回值会**反查 tier**填回:个人版从 `ListSubscribeTrade.InfoList[0].BizInfo` 来,团队版从 `ListSeatInfos` 用 SeatIDs[0] 反查。`echo.tier` 字段供 agent 跟用户确认"还是续这个档位吗"。
+
+## 命令
+
+```bash
+# 第 1 步: 引导 — 拿到协议清单
+arkcli plans renew --plan agent-plan
+arkcli plans renew --plan agent-plan-team --duration 3 --seat-ids seat-001,seat-002
+
+# 第 2 步: 询价 (可选)
+arkcli plans renew --plan agent-plan --duration 6 --estimate
+
+# 第 3 步: 用户同意协议后, 真续费
+arkcli plans renew --plan agent-plan --yes
+arkcli plans renew --plan coding-plan --duration 6 --yes
+arkcli plans renew --plan agent-plan-team --duration 3 --seat-ids seat-001,seat-002 --yes
+arkcli plans renew --plan coding-plan-team --seat-ids seat-aaa --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--plan` | 是 | string | `agent-plan` / `coding-plan` / `agent-plan-team` / `coding-plan-team` |
+| `--duration` | 否 | int | 续费时长（月），1-12，默认 1 |
+| `--seat-ids` | 团队版 必填 | string | 逗号分隔，要续费的席位 ID（个人版**不允许**传） |
+| `--yes` | 否 | bool | 跳过协议闸门，真续费 (`IsAutoPay=true`) |
+
+> **关键差异**：跟 `plans buy` 不同，`renew` 不需要 `--type` —— 续费保持原档位。也不需要 `--quantity` —— 续费数量由 `--seat-ids` 个数决定。
+
+## 返回值 (协议闸门, 默认形态)
+
+不传 `--yes` 不传 `--estimate` 时:
+
+```json
+{
+  "status": "agreement_required",
+  "plan": "agent-plan",
+  "tier": "small",
+  "duration": 1,
+  "echo": {"plan": "agent-plan", "tier": "small", "duration": 1},
+  "agreements": [
+    {"title": "火山引擎数据授权协议", "url": "..."},
+    ...
+  ],
+  "total_amount_cny": 99.5,
+  "original_amount_cny": 100.0,
+  "confirm_text": "续费将立即扣款 (IsAutoPay=true)。请把上述协议链接展示给最终用户...",
+  "next_step": "arkcli plans renew --plan agent-plan --duration 1 --yes"
+}
+```
+
+`tier` / `echo.tier`:从已有订阅 / 席位反查的当前档位 — agent 拿这个跟用户确认续费档位。
+
+团队版 `next_step` 会带上 `--seat-ids seat-001,seat-002`,`echo.seat_ids` 也会列出 — 直接抄给用户即可。
+
+## 返回值 (真续费)
+
+加 `--yes` 后:
+
+```json
+{
+  "status": "success",
+  "plan": "agent-plan-team",
+  "tier": "",
+  "duration": 3,
+  "quantity": 2,
+  "order_number": "<本次真实订单号>",
+  "seat_ids": ["<已确认席位1>", "<已确认席位2>"]
+}
+```
+
+这是结构示例，不是成功回执。个人版可含 `instance_id` 与反查得到的 `tier`；团队版列出本次 `seat_ids`，`tier` 可能为空，不自行补值。订单相关可选字段以实际返回为准；不能把 `agreement_required`、询价结果或存在订单号当成支付成功。
+
+## 失败语义
+
+跟 [`plans buy`](arkcli-plans-buy.md#失败语义) 完全一致：
+- transport error → 普通 error；超时/断连后的订单与扣款状态可能未知，先核对，不自动重放续费
+- `payment_failed` envelope → 订单已落库但 auto-pay 没完成；hint 带 `Order ID: ORD-...`，**用户去 console 补单**，CLI 不要重试
+- `ProductStockNotEnough` → 库存不足；不重试、不重问已确认参数，按 buy 的控制台兜底规则处理，不改成新购
+
+这些失败均保留本轮已经确认的 `--plan` / `--duration` / `--seat-ids`，不重新启动参数 question。用户明确改变目标时才重新收集变化项并重新披露价格和协议。
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `--plan must be one of ...` | 拼错 plan key | 严格用 4 选 1 |
+| `--seat-ids is required for team plans` | 团队版漏传 | 列出要续费的席位 ID |
+| `--seat-ids only applies to team plans` | 个人版多传了 | 删掉 `--seat-ids`，个人版不需要 |
+| `--seat-ids must contain at least one non-empty seat ID` | 给了空串 / 全是逗号 | 检查输入 |
+| `--duration must be 1..12` | 越界 | 1-12 之间 |
+| `payment_failed` envelope | 余额不足 | console 手动补单 |
+
+## 注意事项
+
+- 团队版的 `--seat-ids` 不去重 —— 重复 ID 由服务端按最后一条覆盖
+- 个人版续费**不需要预先查 InstanceID** —— service 层会自动 `ListSubscribeTrade` 反查；用户只关心 `--plan`
+- 续费时长不会叠加到现有过期时间之外的限制；`--duration` 1-12 是单次调用上限
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans buy`](arkcli-plans-buy.md) -- 同套 payment_failed 语义
+- [`plans get`](arkcli-plans-get.md) -- 看续费后过期时间
+- [`plans team seat-list`](arkcli-plans-team-seat-list.md) -- 列出团队版可续费的席位
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-team-rotate-apikey.md

@@ -0,0 +1,108 @@
+# plans team rotate-apikey
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **⚠️ 写操作 / 毁坏性：** 调用成功后，所选席位的**原 APIKey 立即失效**，必须立即替换接入该 APIKey 的模型 / Harness 配置。默认走 [Y/N] 二次确认；`--yes` 跳过。
+
+轮换 Agent Plan / Coding Plan **企业版** 席位的 APIKey。一次调用 `RegenerateEnterpriseCodingPlanApikey`，可批量；服务端 per-item 状态。
+
+支持两种使用场景：
+
+- **self-rotate**：不传 `--seat-ids` 时，自动反查 "我的 agent-plan-team 席位"（`GetSeatInfo` Scene=`agent_plan_enterprise`），轮换该席位 APIKey
+- **admin batch**：显式传 `--seat-ids`，按 SeatID 批量轮换，服务端校验当前身份是否有管理权限
+
+> 用户 spec 注释里写的是 "Agent Plan 企业版"，self-rotate 路径只解析 agent-plan-team 自己的席位。Coding Plan 企业版用户自己轮换 APIKey 当前要走 admin 路径（显式传 `--seat-ids`）。
+
+## 命令
+
+```bash
+# 自己轮换 agent-plan-team 席位 APIKey（交互式）
+arkcli plans team rotate-apikey
+
+# 同上但跳过确认（脚本场景）
+arkcli plans team rotate-apikey --yes
+
+# 管理员批量轮换指定席位
+arkcli plans team rotate-apikey --seat-ids seat-001,seat-002
+
+# 管理员批量 + 跳过确认
+arkcli plans team rotate-apikey --seat-ids seat-001,seat-002,seat-003 --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--seat-ids` | 否 | string | 逗号分隔 SeatID。留空=self-rotate；非空=admin batch |
+| `--yes` | 否 | bool | 跳过 [Y/N] 确认 |
+
+## 返回值
+
+```json
+{
+  "scope": "self",
+  "success_count": 1,
+  "failed_count": 0,
+  "success": [
+    {
+      "seat_id": "seat-self-42",
+      "api_key": "sk-rotated-new-secret",
+      "api_key_sid": "apikey-..."
+    }
+  ],
+  "failed": []
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `scope` | `self` / `admin` —— 提示该次调用走的是反查路径还是显式批量路径 |
+| `success[].api_key` | 新明文，立即保存 |
+| `success[].api_key_sid` | APIKey 稳定 ID |
+| `failed[].reason` | 服务端透传 |
+
+## 二次确认文案
+
+self-rotate：
+```
+确认更新当前身份的 Agent Plan 企业版席位 APIKey?
+更新后原 APIKey 将立即失效，请及时替换接入该 API Key 的模型及 Harness 配置，以避免服务中断。
+继续? [y/N]:
+```
+
+admin batch（带 N 个席位）：
+```
+确认批量更新 N 个席位的 APIKey?
+更新后原 APIKey 将立即失效，请及时替换接入该 API Key 的模型及 Harness 配置，以避免服务中断。
+继续? [y/N]:
+```
+
+## 失败语义
+
+**部分失败**是合法终态（跟 `seat-assign` 同套路）：
+- stdout 始终是完整 result
+- `failed_count > 0` → stderr 追加 `rotate_apikey_partial` envelope + exit code 5
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `cancelled` envelope（exit 1） | 用户输 N / 空回车 / EOF | 重新跑加 `--yes` 或确认轮换 |
+| `no Agent Plan 企业版 seat bound to current identity` (validation) | self-rotate 但当前身份没企业版席位 | 让管理员买套餐 + 用 [`seat-assign`](arkcli-plans-team-seat-assign.md) 给你绑席位；或者你自己有管理权限就走 `--seat-ids` admin 路径 |
+| `--seat-ids must contain at least one non-empty seat ID` | `--seat-ids ""` 或全是逗号 | 检查输入 |
+| `--seat-ids exceeds single-call limit 1000` | 超上限 | 拆批调用 |
+| `RotateTeamSeatAPIKeys: duplicate SeatID %q` | 重复 ID | 客户端先拦 |
+| `failed_count > 0` + `AccessDenied` | 当前身份对该 SeatID 没管理权限 | 检查 SeatID 归属；普通成员只能 self-rotate |
+
+## 注意事项
+
+- self-rotate 当前**只解析 agent-plan-team 自己的席位**（Scene=agent_plan_enterprise）；如果你是 coding-plan-team 用户想自己轮换，先 `plans team seat-list --plan coding-plan-team --user-name <你>` 拿 SeatID，再用 admin 路径
+- 服务端按 SeatID 反推套餐线，所以管理员**可以同时混合 agent / coding plan 的 SeatID** 在一个 `--seat-ids` 里
+- 跟 `plans personal rotate-apikey` 区别：那个是**个人订阅**的 APIKey；这个是**企业版席位**的 APIKey，互不影响
+- 可能撞 `failed_count > 0` 但 `success_count > 0` 的部分成功 —— stdout 仍包含成功项的新 APIKey，**不要因为 exit code 非零就丢掉 success 那部分**
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans personal rotate-apikey`](arkcli-plans-personal-rotate-apikey.md) -- 个人版 APIKey 轮换
+- [`plans team seat-list`](arkcli-plans-team-seat-list.md) -- 列出可轮换的席位
+- [`plans team seat-assign`](arkcli-plans-team-seat-assign.md) -- 绑定席位
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-team-seat-assign.md

@@ -0,0 +1,142 @@
+# plans team seat-assign
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **写操作：** 修改企业版席位与子用户的绑定关系。一次调用 `GrantSeats`，可批量；服务端 per-item 状态（成功 / 失败可同时存在）。
+
+把 Agent Plan / Coding Plan 企业版席位绑定到 IAM 子用户。同一 Action 同时支持两种企业版（agent-plan-team / coding-plan-team），服务端按 SeatID 反推套餐线，**不需要 Scene**。
+
+## 不知道员工的精确 UserID 怎么办
+
+如果你只知道员工用户名（或前缀），先用 `arkcli iam userid` 反查：
+
+```bash
+# 单个前缀
+arkcli iam userid --username ivan
+
+# 多个员工一次性查
+arkcli iam userid --username ivan,bob,carol
+```
+
+输出形态：
+```json
+{
+  "queries": [
+    {
+      "query": "ivan",
+      "matches": [
+        {"user_id": "12345", "user_name": "ivan"},
+        {"user_id": "67890", "user_name": "ivanka"}
+      ]
+    }
+  ]
+}
+```
+
+- 严格**前缀匹配**：`iv` 不会命中 `kevin`，只命中 `ivan` / `ivanka`
+- 一个前缀命中多个时全部返回，让你挑
+- 0 命中也保留该 query 记录，方便脚本判定
+- 不传 `--username` → 返回当前身份的 UserID（即 "我是谁"）
+
+把拿到的 `user_id` 喂给 `seat-assign --bind`，跳过下面 IAM 反查也省一次 round-trip。
+
+## 命令
+
+```bash
+# 单条绑定（自动调 IAM ListUsers 反查 UserName）
+arkcli plans team seat-assign --plan agent-plan-team \
+    --bind seat-001=83144215
+
+# 批量绑定（重复 --bind）
+arkcli plans team seat-assign --plan agent-plan-team \
+    --bind seat-001=83144215 \
+    --bind seat-002=83143634
+
+# 显式指定 UserName，跳过 IAM 反查（escape hatch — 没 IAM 权限或要省调用时用）
+arkcli plans team seat-assign --plan coding-plan-team \
+    --bind seat-001=83144215:ivan \
+    --bind seat-002=83143634:bob
+
+# 自定义 project
+arkcli plans team seat-assign --plan agent-plan-team \
+    --bind seat-001=83144215 \
+    --project-name my-project
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--plan` | 是 | string | `agent-plan-team` / `coding-plan-team` |
+| `--bind` | 是 | stringArray | 重复多次实现批量。格式 `seat-id=user-id` 或 `seat-id=user-id:user-name` |
+| `--project-name` | 否 | string | 项目名，默认 `default` |
+
+> **`--bind` 而不是 `--seat-id=...`：** 用户原始 spec 写的 `--<seat-id>=<user-id>` 是动态 flag 名，cobra/pflag 不支持。改成可重复的固定 flag `--bind` 加值。
+
+### 三段语法 / IAM 反查
+
+`--bind` 的值有两种形态：
+
+| 形态 | 解析 | 行为 |
+|---|---|---|
+| `seat-001=83144215` | UserName 留空 | service 层自动调 **Volc IAM `ListUsers`**（直连 `iam.volcengineapi.com`），分页扫账号下全部子用户，按 ID 匹配 UserName |
+| `seat-001=83144215:ivan` | UserName 显式 | 跳过 IAM 反查，直接喂给 `GrantSeats` |
+
+服务端 `GrantSeats` 对 `{SeatID, UserID, UserName}` 三字段强校验（**UserName 必须非空**），所以 CLI 必须先拿到 UserName。IAM 反查是默认路径；如果 STS 凭据缺 `iam:ListUsers` 权限或想避开 IAM round-trip，用 `:user-name` escape hatch。
+
+IAM 反查是**一次 list-all + 内存 map 缓存**，同一次 seat-assign 调用里多个 binding 复用同一份缓存（不会每个 binding 都 N 次往返）。
+
+## 返回值
+
+```json
+{
+  "plan": "agent-plan-team",
+  "project_name": "default",
+  "success_count": 2,
+  "failed_count": 0,
+  "success": [
+    {
+      "seat_id": "seat-001",
+      "user_id": "83144215",
+      "api_key_sid": "apikey-...",
+      "api_key": "sk-..."
+    }
+  ],
+  "failed": []
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `success[].api_key` | 该席位绑定后的 APIKey 明文，立即给用户保存 / 同步给 harness |
+| `success[].api_key_sid` | APIKey 稳定 ID，后续做轮换 / 删除时定位资源 |
+| `failed[].reason` | 服务端 `FailedReason` 透传，典型：`BindCountLimitExceeded` |
+
+## 失败语义
+
+**部分失败**是合法终态：
+- stdout 始终是完整 result（含 success + failed 两个数组）
+- `failed_count > 0` 时 stderr 追加 `grant_seats_partial` envelope，exit code = 5（`ExitAPI`）
+- `failed_count == 0` 时 exit 0
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `--plan must be one of ...` | 拼错 / 用了个人版 plan | 用 `agent-plan-team` / `coding-plan-team` |
+| `--bind ... must be in the form seat-id=user-id` | 格式错 | 严格 `seat-id=user-id` 或 `seat-id=user-id:user-name` |
+| `--bind specifies SeatID %q more than once` | 同一 SeatID 在多个 `--bind` 里出现 | 服务端会拒，客户端先拦 |
+| `resolve UserName for UserID=...: IAM ListUsers ...: AccessDenied` | STS 凭据缺 IAM 权限 | 走 escape hatch：`--bind seat-id=user-id:user-name` 显式指定 |
+| `failed_count > 0` + `BindCountLimitExceeded` | 该子用户已经绑了 N 个席位（受限） | 先解绑（暂未实现 unbind 子命令）；frontend 走的是 `RevokeSeats` |
+
+## 注意事项
+
+- IAM 反查是**全 listing**（分页拉账号下所有 IAM 用户），只在第一个 binding 触发；同一调用里之后 lookup 走内存
+- IAM 反查防御性兜底：超过 10000 条还没找到目标 ID 时报错（防止后端循环游标无限分页）
+- 同一席位**不能同时**绑多个子用户（服务端约束）；要换人需先 unbind 再 assign（unbind = `RevokeSeats`，CLI 暂未暴露）
+- `success[].api_key` 是**新生成的 APIKey 明文**，绑定即生效；第一次返回后 console / CLI 都拿不到原始明文（mask 形态），务必立即保存
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans team seat-list`](arkcli-plans-team-seat-list.md) -- 先列出空闲席位
+- [`plans team rotate-apikey`](arkcli-plans-team-rotate-apikey.md) -- 已绑定后轮换 APIKey
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-team-seat-list.md

@@ -0,0 +1,115 @@
+# plans team seat-list
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+列出 Agent Plan / Coding Plan **企业版** 席位，支持 7 种过滤维度 + 分页。读操作。
+
+## 命令
+
+```bash
+# 列 Agent Plan 团队版全部席位（默认页大小）
+arkcli plans team seat-list --plan agent-plan-team
+
+# Coding Plan 团队版
+arkcli plans team seat-list --plan coding-plan-team
+
+# 按席位档位过滤
+arkcli plans team seat-list --plan agent-plan-team --type medium
+
+# 精准查指定席位（最多 1000 个 SeatID）
+arkcli plans team seat-list --plan agent-plan-team --seat-ids seat-001,seat-002
+
+# 按绑定子用户名过滤
+arkcli plans team seat-list --plan agent-plan-team --user-name yinfan.ivan
+
+# 仅看空闲席位（Idle=1）
+arkcli plans team seat-list --plan agent-plan-team --seat-status 1
+
+# 仅看 Running 计费状态
+arkcli plans team seat-list --plan agent-plan-team --billing-status 2
+
+# 翻页
+arkcli plans team seat-list --plan agent-plan-team --page-number 2 --page-size 50
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--plan` | 是 | string | `agent-plan-team` / `coding-plan-team`（个人版 plan 会被拒绝） |
+| `--type` | 否 | string | tier 过滤：agent-plan-team 取 `small/medium/large/max`；coding-plan-team 取 `lite/pro` |
+| `--seat-ids` | 否 | string | 逗号分隔精准过滤；**单次上限 1000**（客户端先拦截） |
+| `--user-name` | 否 | string | 按绑定的子用户名过滤 |
+| `--seat-status` | 否 | int | 1=Idle（空闲未绑定）/ 2=Active（已绑定）。其它值会被拒 |
+| `--billing-status` | 否 | int | 1=Pending（待付费） / 2=Running（生效中）/ 3=Expired（已过期）/ 4=Reclaimed（已回收） |
+| `--project-name` | 否 | string | 项目名，默认 `default` |
+| `--page-number` | 否 | int | 页码（≥1） |
+| `--page-size` | 否 | int | 页大小（≥1） |
+
+`--plan` 与 `--type` 兼容性跟 `plans buy` 一致。
+
+## 返回值
+
+```json
+{
+  "plan": "agent-plan-team",
+  "scene": "agent_plan_enterprise",
+  "total": 42,
+  "seats": [
+    {
+      "seat_id": "seat-20260608110804-gjrwr",
+      "tier": "medium",
+      "seat_status": "Active",
+      "billing_status": "Running",
+      "user_id": "83144215",
+      "user_name": "yinfan.ivan",
+      "project_name": "default",
+      "instance_id": "ins-...",
+      "order_time": 1700000000000,
+      "expired_time": 1790351999,
+      "create_time": 1690000000000,
+      "update_time": 1700000000000
+    }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `scene` | agent-plan-team 是 `agent_plan_enterprise`；coding-plan-team **空字符串**（服务端默认 coding_plan） |
+| `total` | 服务端匹配过滤后的总数（不一定等于当前页大小） |
+| `seat_status` | "Idle" / "Active" / "Unknown"（已经把数字枚举翻译成可读字符串） |
+| `billing_status` | "Pending" / "Running" / "Expired" / "Reclaimed" / "Unknown" |
+| `user_id` / `user_name` | 绑定的子用户标识（IAM `IdentityId` / `IdentityDetail`） |
+| `expired_time` | Unix 秒；`0`、缺失或不可解析时表示没有可靠到期时间，不能判定永不过期 |
+| `order_time` / `create_time` / `update_time` | 上游原始时间值；按各字段契约确认单位，不能由其中一项推导所有 `*_time` 都是毫秒 |
+
+交付到期时间必须程序化换算为北京时间（UTC+8），保留原始秒值作为核对依据，不能心算日期或用额度刷新时间代替。比如 `1790351999` 对应 `2026-09-25 23:59:59 +08:00`。JavaScript 的 `Date` 接收毫秒，必须先乘 1000：
+
+```javascript
+const expiredSeconds = 1790351999; // 替换为当前席位真实 expired_time
+const beijing = new Intl.DateTimeFormat('sv-SE', {
+  timeZone: 'Asia/Shanghai', year: 'numeric', month: '2-digit', day: '2-digit',
+  hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23'
+}).format(new Date(expiredSeconds * 1000));
+console.log(`${beijing} +08:00`);
+```
+
+`coding-plan-team` 时输出里 `scene` 是空字符串 —— 这是预期行为，服务端按空 Scene 默认到 coding_plan。
+
+## 注意事项
+
+- 如果用户问 "我有多少个席位" 不区分 plan：先 `arkcli plans get` 看持有哪种团队版，再分别 `seat-list` 一次
+- **本命令只列基础信息**（SeatID / 绑定身份 / billing 状态等）。**想看每个席位的用量**（5h/weekly/monthly percent + reset_at）走 `arkcli usage seats --product <agent-plan-team|coding-plan-team> --with-usage` —— 数据源同 `ListSeatInfos`，多 join 一层 `ListSeatAFPUsage` / `ListSeatInfoUsages`
+- 数字枚举 (`--seat-status` / `--billing-status`) 已经在 reference 里说明数字含义，**不要让用户去查文档**；提示时直接给意义
+- `--seat-ids` 不去重，重复 ID 由服务端按最后一条覆盖
+- 默认 `BillingStatus` 不过滤（返回所有状态）；frontend 上 BindSeatDrawer 默认只看 `[Running, Expired]`，CLI 更"raw"，要按需自己加 `--billing-status`
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans team seat-assign`](arkcli-plans-team-seat-assign.md) -- 给空闲席位绑定子用户
+- [`plans team rotate-apikey`](arkcli-plans-team-rotate-apikey.md) -- 轮换席位 APIKey
+- [`plans get`](arkcli-plans-get.md) -- 先看持有哪种团队版套餐
+- [arkcli-usage](../../arkcli-usage/SKILL.md) -- 席位**用量**视图（`usage seats --with-usage`），跟本命令的"基础列表"互补
+- [arkcli-shared](../../arkcli-shared/SKILL.md)