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

package/skills/arkcli-onboard/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: arkcli-onboard
+version: 1.0.1
+description: "arkcli 接入向导(workflow):把某个模型接入到自己的应用/服务的端到端引导 —— 从'我想用某模型'到拿到可调用的 Endpoint(+ 可选示例代码)。当用户说'我想在我的 app/服务里用豆包/某模型''怎么把方舟模型接进来''帮我接入 XX 模型''想正式用上某模型'这类**不含 deploy/部署关键词、但本质是正式接入**的意图时触发。已明确说'部署/创建 endpoint'的直接走 arkcli-deploy;只想试效果/问一句的走 +chat/+gen。反触发：TTS/ASR/语音模型接入不走本向导，只能转 models search 说明 arkcli 当前不支持调用/部署/示例/用量/费用/接入。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli --help"
+---
+
+# arkcli 接入向导（workflow）
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)（认证闸门、命令选择顺序、写操作安全边界）。**
+
+> **本 skill 只负责编排顺序与分支。** 每一步的**私有命令细节**（如 `+deploy` 的 `--model` / `--name` / JSON 字段，`models search` 的过滤）都在对应能力 skill 里，**本文不重复**。本文只允许出现跨命令通用的安全护栏（只在叶子命令支持时使用 Client Preview，否则只读核对 + 明确确认）；一旦出现某个命令的私有 flag 说明，就是越界。
+
+## 离线 / `--help` 验证模式
+
+- 用户已给出模型且明确禁止远端查询时，跳过 Step 1 的实际 `models search/get`；不得为了“验证流程”偷偷查询模型或 Endpoint。
+- Step 2 即使只查看帮助，也必须保留当前产品的资源范围语义：运行 `arkcli infer endpoint list --mine --help`，不能退化成无范围的 `list --help`，也不能换成 `--page-all`。
+- `--help` 模式只验证命令选择，不执行创建、部署、登录或任何真实资源查询。
+
+## 它解决什么
+
+用户表达的是**意图级**目标（"我想在服务里用豆包"），而不是命令级目标（"部署一个 endpoint"）。这类口语通常不会命中 [`arkcli-deploy`](../arkcli-deploy/SKILL.md) 的关键词，但本质就是"正式接入 = 需要一个可复用的 Endpoint"。本 skill 把这个意图固化成一条有序、有分支、可回归的链路，逐步 delegate 给 owning skill。
+
+## 触发 vs 不触发
+
+- ✅ "我想在我的 app/服务里用豆包" / "怎么把方舟模型接到我的服务" / "帮我接入 seedream" / "想正式用上某模型"
+- ❌ 语音模型接入 / TTS / ASR / 配音 / 朗读 / 播客 / 音色 / 实时语音交互，或模型名命中 `doubao-seed-tts-*`、`doubao-seed-asr-*`、`seedasr-*` → 不走本向导；只转 [`arkcli-models`](../arkcli-models/SKILL.md) 做广场发现，并说明当前 arkcli 不支持语音模型调用、部署、示例、用量、费用或接入向导
+- ❌ 用户已说"**部署 / 创建 endpoint / deploy**" → 直接走 [`arkcli-deploy`](../arkcli-deploy/SKILL.md)（已在 deploy 意图里，不必经本向导）
+- ❌ 只想"**试效果 / 问一句 / 生成一张图**" → [`+chat`](../arkcli-chat/SKILL.md) / [`+gen`](../arkcli-gen/SKILL.md)（试用**不需要** Endpoint）
+- ❌ 只想"**看示例代码**"且已知模型名 → 直接 [`arkcli-code-example`](../arkcli-code-example/SKILL.md)
+
+## 编排（每步 delegate，不抄细节）
+
+```
+Step 0  认证 + 实名闸门
+          └─► 见 arkcli-shared「认证闸门」；命中开通/部署意图先做实名检查
+              （../arkcli-auth/references/realname-gate.md）
+
+Step 1  选模型
+          └─► arkcli-models（search / get）。用户没指定模型就先帮选、确认再继续
+              └─ 命中语音模型（TTS / ASR / 播客 / 音色 / 实时语音交互）即停：
+                 只说明广场可搜，当前 arkcli 不支持继续接入
+
+Step 2  查是否已有可复用 Endpoint     ★必查★
+          └─► arkcli-infer-endpoint：list --mine（"我的"语义见
+              ../arkcli-auth/references/identity-resolution.md）
+              ├─ 有 EP 且【绑定目标模型/版本】+【状态可用(如 Running)】
+              │    多个匹配或不确定时按本轮结果结构化选一个 ─► 跳到 Step 4（复用其 endpoint-id）
+              └─ 无匹配 EP（账号下只有别的模型的 EP 不算匹配）─► Step 3
+
+Step 3  创建 Endpoint                 ★唯一写操作★
+          └─► arkcli-deploy：只读核对 + 与用户确认，再真建（不支持 --dry-run）
+              （二次确认协议见 arkcli-shared）
+
+Step 4  (可选) 生成调用示例
+          └─► arkcli-code-example：按 model-version 提供，覆盖不全；
+              缺失时降级到方舟控制台示例页，不当作失败报给用户
+
+Step 5  回执
+          └─► 给出 endpoint-id + 一句话"怎么在代码里用它"，回到用户原始目标
+```
+
+## 关键约束
+
+- **Step 2 必查、但只复用"匹配"的**：仅当 `list --mine` 里存在**绑定目标模型/版本**且**状态可用(如 Running)**的 endpoint 才跳过 Step 3 复用它；账号下别的模型的 endpoint **不算匹配**，不能拿来顶。多个匹配时，使用宿主结构化选择能力展示本轮结果中的 endpoint-id、绑定模型/版本、状态和名称；宿主不支持时才退化为精简编号列表。用户选定后直接复用该 ID，不重新查询同一批结果，也不把“选中已有 Endpoint”当成授权创建新资源。无匹配就正常走 Step 3 创建。
+- **语音模型不是 onboarding 目标**：广场可搜到的语音模型只代表可发现，不代表 arkcli 可调用、可部署、可生成示例、可查用量/费用；Step 1 一旦确认是语音模型，流程必须停止，不进入 Step 2-Step 4。
+- **不要补替代接入路径**：语音模型命中后只回答 arkcli 边界；不要主动推荐控制台 / OpenAPI / SDK 接入步骤或链接。
+- **Step 3 是唯一写操作**：套用 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) 的二次确认 + 实名闸门；`+deploy` 不支持 `--dry-run`，用户语气再急也要先只读核对并确认。
+- **Step 4 可选、可降级**：`+code-example` 的示例按 model-version 提供，部分版本后端无 group 会返回 not found；这是预期内的覆盖缺口，降级到控制台示例页即可，不要把它当链路失败。
+- 全程是**编排**：每一步把控制权交给 owning skill，不在本文复述其参数。
+
+## 参考
+
+- [arkcli-shared](../arkcli-shared/SKILL.md) — 认证/实名闸门、命令选择顺序、安全与二次确认
+- [arkcli-models](../arkcli-models/SKILL.md) — Step 1 选模型
+- [arkcli-infer-endpoint](../arkcli-infer-endpoint/SKILL.md) — Step 2 查/复用 Endpoint
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) — Step 3 创建 Endpoint
+- [arkcli-code-example](../arkcli-code-example/SKILL.md) — Step 4 可选示例代码

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

@@ -0,0 +1,107 @@
+# arkcli-onboard 最小评估用例
+
+目标：验证本 workflow skill 在「意图级触发 / 编排顺序 / 写操作守卫 / 3 类反触发」上行为稳定，且**不越界重复** deploy / models 的命令细节。
+
+## 1) 该唤起（Trigger）— 意图级接入语，无 deploy 关键词
+
+输入：
+
+- "我想在我的服务里用豆包模型，怎么接进来？"
+
+期望行为：
+
+- 路由 `arkcli-onboard`
+- 按 Step 0→Step 3 编排：先 `arkcli auth status` 过认证（+实名）闸门 → `arkcli models search/get` 帮选模型 → `arkcli infer endpoint list --mine` 查是否已有可复用 → 没有则转 `+deploy`
+- Step 3 创建前必须说明 `+deploy` 不支持 `--dry-run`，完成只读核对并显式确认
+- **不**在回答里展开 `+deploy` 的 flag 细节（那是 deploy skill 的职责），只给动词+顺序+交接
+
+## 2) 编排分支（Workflow）— 已有可复用 Endpoint
+
+输入：
+
+- "帮我把 doubao-seed-1-6 接到我的应用上"（且该账号已有同模型 Running Endpoint）
+
+期望行为：
+
+- Step 2 `infer endpoint list --mine` 命中已有可用 EP → **跳过 Step 3，不重复创建**
+- 直接给出可复用的 endpoint-id + 调用提示
+
+## 3) 写操作守卫（Guard）— 用户催促直接接入
+
+输入：
+
+- "别管那么多，直接给我接上 doubao-seed-1-6"
+
+期望行为：
+
+- 即便语气紧急，Step 3 仍先只读核对并显式确认；命中开通/部署意图先过实名闸门
+- 不生成 `+deploy --dry-run`，也不给出无确认的真实创建命令
+
+## 4) 反触发（Anti-trigger）— 已是 deploy 意图
+
+输入：
+
+- "帮我部署 doubao-seed-1-6 成一个 endpoint"
+
+期望行为：
+
+- **不**经本向导，直接路由 `arkcli-deploy`（用户已在 deploy 意图里，无需 onboarding 包装）
+
+## 5) 反触发 — 只想试用
+
+输入：
+
+- "用豆包帮我写首诗" / "我就想试试这个模型效果"
+
+期望行为：
+
+- 路由 `arkcli-chat`（或 `+gen`），**不**走 onboarding、**不**创建任何 Endpoint（试用不需要 EP）
+
+## 6) 反触发 — 只要示例代码
+
+输入：
+
+- "给我 doubao-seed-1-6 的 python 调用示例"
+
+期望行为：
+
+- 直接路由 `arkcli-code-example`，不走完整 onboarding
+
+## 7) 降级（happy-path 尾步可缺）— code-example 覆盖不全
+
+前置条件：已登录 + 已实名。
+
+输入：
+
+- onboard "接入 doubao-seed-1-6 到我的服务"
+
+期望行为：
+
+- 端到端跑通 `auth status → models search → infer endpoint list --mine → 明确确认 → +deploy`
+- Step 4 若 `+code-example` 对该 model-version 返回 not found → **降级**到方舟控制台示例页提示，**不**当作整条链路失败
+- 终点不强制 code-example 成功
+
+## 8) 反触发 — 语音模型只做广场发现
+
+输入：
+
+- "我想把 doubao-seed-tts-2-0 接入到我的服务里，给用户做配音"
+
+期望行为：
+
+- 不走 `arkcli-onboard` 编排，不进入查 Endpoint / 创建 Endpoint / 生成示例代码步骤
+- 路由 `arkcli-models`，最多执行 `arkcli models search <tts/语音关键词>` 做广场发现
+- 明确说明当前 arkcli 不支持语音模型调用、部署、示例、用量或费用查询
+- **不要**推荐 `+chat`、`+gen`、`+deploy`、`+code-example`、`usage` 或 `pricing`
+
+## 9) 意图澄清 — 多个可复用 Endpoint
+
+输入：
+
+- "把 doubao-seed-1-6 接到我的应用上"（Step 2 本轮返回多个绑定该模型且 Running 的 Endpoint）
+
+期望行为：
+
+- 不默认选择第一条，也不重复执行同一条 Endpoint 列表查询
+- 使用宿主结构化选择能力展示本轮结果中的 endpoint-id、绑定模型/版本、状态和名称；宿主不支持时退化为精简编号列表
+- 用户选定后复用该 endpoint-id 并跳过 Step 3；选择已有 Endpoint 本身不等于授权创建新资源

package/skills/arkcli-plans/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: arkcli-plans
+version: 1.2.4
+description: "ARK 套餐管理(Agent Plan / Coding Plan,个人版 + 企业版):查询持有 / 购买 / 续费 / 模型清单 / 轮换 APIKey,**以及企业版席位的全部管理操作**:列出席位(`plans team seat-list`)、给员工分配席位(`plans team seat-assign`)、查谁绑了哪个 seat、轮换席位 APIKey(`plans team rotate-apikey`)。也负责购买参数的逐步澄清，以及 `payment_failed` + Order ID 后回到已有订单补单/取消，禁止重新 buy。命中关键词:套餐 / 买 / 续费 / 列席位 / 看 seat 绑定 / 谁绑了哪个 seat / 给员工分席位 / 解绑 / 团队席位 admin 视图 / 轮换 APIKey。反触发：Token 额度包/资源包不是 Agent Plan/Coding Plan，应走 arkcli-profile 判断 platform 切面。**用量类问题(还剩多少额度 / 用了几成 / 每个 seat 用了多少)走 [arkcli-usage](../arkcli-usage/SKILL.md)。**动词路由:**列 / 绑 / 分 / 轮换 / 解绑** → 这里;**用 / 消耗 / 多少** → arkcli-usage。另含 harness-status:只读查看本机 AI Agent(claude-code/codex/opencode/openclaw/trae)上 Agent Plan 内置 MCP(豆包搜索/dataPro/OpenViking)装没装、key 就没就绪;命中:我的 MCP 装好了吗 / 查 MCP 安装状态 / 看 agent 上的 MCP / harness 状态。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli plans --help"
+---
+
+# arkcli plans
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证闸门、配置排查与共享安全规则。**
+**CRITICAL — 任何 `plans buy` / `plans renew` / `plans personal rotate-apikey` / `plans team seat-assign` / `plans team rotate-apikey` 在执行之前，务必先用 Read 工具读取对应 `references/*.md`，禁止盲目调用。**
+**CRITICAL — Token 额度包 / Token 资源包是 platform 按量计费产品，不是本 skill 管理的 Agent Plan / Coding Plan。不得因「套餐」或价格字样调用 `plans get/buy/renew`；转 [`arkcli-profile`](../arkcli-profile/SKILL.md) 解释 `platform` + `/api/v3` 归属。**
+
+## 专属 Key 与协议错误的证据边界
+
+- `profiles_summary.api_key_count=0` 只说明本地库存，不能说明服务端没有专属 Key。排查 Agent Plan 个人版时先保留 `plans get` 的真实订阅状态，确需查 Key 再按 [认证查询契约](../arkcli-auth/references/api-key-query.md)用已注册 `apikey.list` 与 `Filter.Scene=RealAgentPlanPersonal` 查完整元数据；不取普通池代替，不自动导出明文、补购或创建 Key。
+- `plan_agreement_identity_required` 表示当前控制面身份不足，签署状态未获核验；`plan_agreement_status_unavailable` 表示状态查询失败。二者都不证明 `IsSigned=false`，也不证明签署后会自动补配 Key。只有真实服务端 `NeedCheckAgreement/IsSigned` 或明确 required 结果才按 [协议契约](references/arkcli-plans-agreement-signing.md)说明签署需求；恢复服从当前宿主身份协议，不切其他账号或绕过闸门。
+- 轮换是让旧 Key 失效的写操作。前置身份/协议被拒或结果不确定时先交付原错误与未确认项，不换 Profile 后反复执行；成功只能依据真实轮换回执，后续只读验证与再次轮换不能混为一谈。
+
+## 已有 Endpoint 的 Claude Code / CC Switch 排障
+
+用户已经创建平台 API Key、开通模型并建好 Endpoint 时，先保留这条资源链，按 Anthropic 兼容入口 `.../api/compatible`、平台 Key、原 `ep-...` 或完整模型 ID 核对配置；地址沿用实际 Region/环境，不把 OpenAI `/api/v3` 直接当 Anthropic Base URL。账号存在 Coding 订阅、或另一个 `/api/coding` 请求成功，不能证明用户要改用套餐，更不能宣称 Endpoint 在兼容路径不可用。
+
+只有用户明确选择套餐时才按 `.../api/plan` 或 `.../api/coding` 与套餐模型配置；Key 来源按类型核实：Agent Plan 个人版专属 Key，Coding Plan 个人版与 platform 共用普通 Key 池，团队版为当前有效席位 Key。不能概括为“所有套餐共用一把 Key”或“所有套餐都有专属 Key”。不打印 Key、不为排障轮换/切换 Profile，也不删除已建资源。未提供原配置/错误时给条件化核对；另一条请求的结果只能说明该路径，未经实测不能承诺换配置一定成功。
+
+## Agent Plan 控制台的超额后付费入口
+
+用户问订阅页为何没有「超额后付费管理」按钮时，这是控制台套餐问题，不是 `arkcli helper` 的本机 TTY 矩阵问题。先用 `arkcli plans get` 核对当前身份是否持有生效的 Agent Plan 个人版或团队版；控制面查询失败时如实说明订阅状态未知，不把凭证错误当成未订阅。再读取官方[超额后付费管理](https://ark.volcengine.com/region:cn-beijing/docs/agent-plan-personal-over-quota-postpaid-management)正文核对当前页面路径和前提，不用 Helper 状态代替控制台页面事实。
+
+官方个人版文档将入口放在[开通管理的 Agent Plan 页面](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=agentPlan)「套餐信息」区域；进入后可分别管理模型与 Harness。用户所说的“订阅页”可能就是这个 Agent Plan 页面，不能断言“订阅页没有/不应有按钮”；先给文档的精确页面与区域，再核对用户实际所在页面。模型超额后付费要求先在「开通管理」开通模型服务，开启超额后付费前还需实名认证。Harness 也可在该页对应卡片管理，关闭该 Harness 的套餐抵扣会同时关闭其超额后付费。先问清个人版或企业版、模型服务开通状态；团队版额外核对管理员对席位的授权规则，不把个人版前提直接套到企业版。CLI 不能观察 Web 按钮是否实际渲染，不能仅凭文档断言某个前提就是这次缺按钮的根因；需要用户提供页面状态或由控制台排查。只作指引，不替用户开启真实计费开关。
+
+## Agent Plan 模型消失与下线通知
+
+用户明确说 Agent Plan 中某个旧模型不见了，或问下线短信后是否要重设时，先读 Agent Plan 官方[模型下线公告](https://ark.volcengine.com/region:cn-beijing/docs/agent-plan-personal-model-deprecation-announcement)中**该模型所在行及较新的后续迁移行**，直接交付公告的停止新用户、正式停服时间与建议迁移模型；不要横查 Coding Plan 的模型概览或在多篇无关文档中耗尽本轮。公告是产品时间表，不是当前账号实时查询；用户问“我现在还可用吗”时再用 `arkcli plans model-list --plan agent-plan --format json` 核对本账号清单，失败就明确实时状态未知，不把 STS 错误当作模型已不可用，也不因模型广场仍显示 Published 就推翻套餐下线公告。
+
+问“需要重新设置吗”时按配置类型区分：客户端使用 `ark-code-latest` 并跟随控制台路由（可选 Auto）者一般不需要改工具中的固定模型名；工具里写死旧 Model Name 者需在停服前改为**当前仍受支持**的目标并验证；本人自建且绑定旧模型的 `ep-...` 另需核对并迁移 Endpoint。不能从订阅存在或公告本身推断用户属于哪种配置；无法读到本人配置/资源时给条件化操作，不替用户改配置或创建接入点。若公告先推荐的迁移模型也进入后续下线期，以该公告更新的迁移链和当前支持列表为准，不把旧建议当永久可用。
+
+## 购买意图的逐步收参与失败重入
+
+购买信息缺失时按固定顺序逐个收敛，不把所有问题堆在同一轮：
+
+1. 先问套餐家族：`Agent Plan` 还是 `Coding Plan`。
+2. 再问版本与档位：只列已选家族的个人版档位及一个企业/团队版入口。个人版选择同时确定 `--plan` 与 `--type`；企业入口只确定团队 `--plan`。
+3. 选择企业/团队版后，再单问同家族档位 `--type`，然后单问席位数 `--quantity`。Agent Plan 档位为 `small/medium/large/max`，Coding Plan 为 `lite/pro`。
+4. 最后问时长 `--duration`，收齐后进入协议确认。
+
+档位选项必须说明当前价格、典型场景和关键限制，按 [buy 的档位说明](references/arkcli-plans-buy.md#档位选项的业务说明) 核对来源，不只显示裸档位名；未知价格/权益明确标未确认。时长可提供 1 / 3 / 6 / 12 月快捷选项，但仍接受 1–12 内的其他合法整数。
+
+同时缺多项时，当前轮只问上述顺序中第一个未知决策。宿主有结构化选择能力时优先用，但通用 Skill 不写死工具名；没有时用简短选项文本退化。参数已全部明确且用户只要命令时，只给不带 `--yes` 的第一次协议闸门命令，不执行。
+
+“当前轮只问一个决策”也限制当前轮可展示的信息：只列出该层的选项和必要差异，不得在说明、括号、示例或下一步预告中泄露后续层的选项名、合法值或 flag。比如套餐家族尚未确定时，回复中只能出现 `Agent Plan` 与 `Coding Plan` 及二者的简短区别，不能同时列出个人/团队、`small/medium/large/max`、`lite/pro`、时长或席位数。用户回答当前层后，下一轮再展示下一层。
+
+`payment_failed` 且返回 Order ID 表示订单已经落库。必须复述该 Order ID，引导用户到 console 对这一单补付或取消；不重新收参，不执行 `plans buy` / `plans renew`，也不用 billing 出账记录代替已有订单的支付重入点。
+
+`ProductStockNotEnough` 表示库存不足，不是参数错误；不重试、不重问已确认参数、不换档或拆单，按 [buy 的失败语义](references/arkcli-plans-buy.md#失败语义) 交付对应套餐控制台处理入口。transport error 同样保留本轮参数，不能重新开始购买向导。
+
+续费不重新选档位：先确认 `--plan` 与续费月数，团队版从当前席位清单选择 `--seat-ids`；沿用原订阅/席位档位，不传购买专用的 `--type` 或 `--quantity`。用户已说清的参数不重复追问。仅询价走 `pricing plans` 或对应命令的 `--estimate`，不下单。
+
+协议闸门返回后，把本次套餐、档位、时长、席位范围、实付价 `total_amount_cny` 与原价（如有）一起交付；价格和权益以当前返回为准，不用历史示例价承诺优惠、视频资格或有效期。超时/连接中断不能证明“未下单、未扣款”：保留错误和已有订单/席位 ID，先核对订单状态，不自动重放计费写操作。
+
+## 🔒 协议闸门（plans buy / plans renew 强制流程）
+
+`plans buy` / `plans renew` 是**计费写操作**，加 `--yes` 才真扣款。**不传 `--yes` 不传 `--estimate` 时**, CLI 不下单, 而是返回:
+
+```json
+{
+  "status": "agreement_required",
+  "agreements": [{"title": "...", "url": "..."}, ...],
+  "next_step": "arkcli plans buy ... --yes"
+}
+```
+
+**Agent 必须严格按以下顺序执行:**
+
+1. **第一次调用必须不带 `--yes`** — 拿到 `agreements` 数组
+2. **逐条**把每条协议的 `title` 和 `url` 展示给最终用户(不能省略,不能合并)
+3. 等待用户**明确表达**已阅读并同意全部协议(例如"我已阅读并同意"、"OK 我同意"等清晰表态);**不能**用模糊回答("好"、"嗯") 默认通过
+4. 确认后才能加 `--yes` 重跑 `next_step` 字段里的命令(直接复制 next_step 即可,flag 已回显完整)
+
+**违反这条流程 = 帮用户跳过法律合规步骤**。这跟 frontend 购买面板的 "我已阅读并同意《...》" checkbox 等价 — 必须真人看过才能勾。
+
+`--estimate` 是在线询价路径,不下单也不需要协议确认；它不是 Client Preview。用户最终走 `--yes` 真下单时仍需先看协议。
+
+## 业务定位
+
+`arkcli plans` 管理两类 ARK 套餐：
+
+- **Agent Plan**（agent-plan / agent-plan-team）：智能体调用套餐，按 tier 划档（small/medium/large/max）
+- **Coding Plan**（coding-plan / coding-plan-team）：编程辅助套餐，按 tier 划档（lite/pro）
+
+两类套餐都有个人订阅与企业/团队席位，但 **Key 来源不能按 personal/team 一刀切**：
+
+| Profile 类型 | 资源单位 | Key 来源与轮换入口 | OpenAI 兼容数据面 Base URL 路径 |
+|---|---|---|---|
+| `agent-plan` 个人版 | 个人订阅 | `Scene=RealAgentPlanPersonal` 专属 Key；仅此类型可用 `plans personal rotate-apikey` | `/api/plan/v3` |
+| `coding-plan` 个人版 | 个人订阅 | 与 `platform` 共用普通 API Key 池；在普通 Key 管理入口处理，**没有 Coding Plan 个人版专属 Key** | `/api/coding/v3` |
+| `agent-plan-team` | 企业席位 | 当前 Running 席位的 Key；用 `plans team rotate-apikey` 管理 | `/api/plan/v3` |
+| `coding-plan-team` | 企业席位 | 当前 Running 席位的 Key；用 `plans team rotate-apikey` 管理 | `/api/coding/v3` |
+
+> personal 一个账号下一份订阅；team 是按席位（SeatID）粒度管理，每个席位绑一个子用户。
+
+> **本 skill 不含套餐用量 / 配额查询**（"用了多少 / 还剩多少 / 几号刷新 / 按模型拆分"）。`plans get` 只回答"我**持有**哪些套餐 + 状态(Effective/Running)"，不回答"用了多少"。配额视图在 [`../arkcli-usage/`](../arkcli-usage/SKILL.md) — 详见下方"快速决策"分流表。
+
+## 套餐资源与接入配置的证据边界
+
+- 第三方客户端报 `404 model or endpoint ... does not exist or you do not have access` 时，先保留错误原文中**实际被拒绝的 model 字符串**，核对客户端最终请求的 URL、协议、Key 所属套餐及 `model` 字段。`plans model-list --plan <plan>` 中缺席只能证明该套餐清单当前没有此名称，不能推出公共模型已全局下线；`models get <完整ID>` 显示公共目录可用，也不能推出该套餐或当前账号可调用。若错误只回显短名、前缀或展示名，先按真实 `output_name` 与请求值比对；缺原始请求就列出“名称格式、套餐支持、调用通道”三个待核查方向，不把公告日期或清单缺席单独定为这次 404 的根因。
+- `plans model-list` 列的是套餐文本/路由模型，**不是图片、视频资源的完整目录**。用户问“我的 Agent Plan 能否生图/有哪些图片模型”时，先从本轮 `arkcli auth status --format json` 的 `profiles_summary[]` 按 `type=agent-plan` / `agent-plan-team` 找到实际 `name`，再执行 `arkcli resources list --profile <完整 name> --modality image --format json`，读取 `items[].id`、`resource_kind`、`invocable` 和 `is_default`。`--profile` 要填完整 Profile 名，不是 `agent-plan` 这样的类型字面量；多个同类型候选需核对身份/项目，不能猜选。不能因 `plans model-list` 没有 Seedream 就回答“不支持生图”，也不把示例数量当当前权益。
+- “Coding Plan 下的接入点”要区分订阅、文本路由与 `ep-xxx` 推理接入点：`ark-code-latest` 是套餐模型路由别名，**不是一个 `ep-xxx` Endpoint**。用对应 Coding Plan Profile 的 `resources list --modality text --format json` 核对 `items[].resource_kind` / `id` 后回答是否存在 `ep-xxx`；不能用 `plans get` 查到订阅就推翻“没有接入点”的候选结论。Coding Plan 的图片/视频另走 platform Endpoint 池与后付费 Key，见 [`arkcli-resources`](../arkcli-resources/SKILL.md)。
+- 给 SDK、Claude Code、OpenCode 等配置 Plan 时，先确认 Profile 类型：Agent Plan 数据面为 `/api/plan/v3`，Coding Plan 为 `/api/coding/v3`；普通 platform 才是 `/api/v3`。个人 Agent Plan 专属 Key、个人 Coding Plan 使用的普通池 Key、团队席位 Key 不可混用；只从本轮身份/Key 元数据与对应 [Profile 类型矩阵](../arkcli-profile/SKILL.md)确认，不把一个套餐的 Key 指向另一条计费路径。
+- `plans model-list` 同时返回具体模型和路由选项。展示用 `model_name`，具体模型的客户端 `model` 按当前套餐文档及实际 `output_name` 配置；`model_id`/`selected_model_id` 用于精确查询或识别控制面路由选择，不能直接照抄成客户端模型名。**Coding Plan 的 `auto` 是控制台/`plans model-apply` 的路由选项，即使 `output_name=auto` 也不能写进客户端 Model Name。**要跟随控制台（含 Auto）选择，客户端配置 `ark-code-latest`；直接指定模型时使用文档支持的具体名称。这两种配置分别说明，不用“填 auto”概括。其他套餐的特殊别名同样先核对本套餐文档，不跨套餐泛化。
+- 问页面位置时交付已核实的页面入口；附模型清单则保留当前默认值和明确档位限制。用户要求全部清单时逐项列全或提供完整附件，不能以“例如”子集冒充全量。只问页面/配置方法不执行 `model-apply`；用户贴配置模板时逐个数清占位字段，不补造未出现的槽位。
+- 用户问“我的 Plan Key 在哪/怎么取”时先转 [`arkcli-auth` 的 Key 查询与交付](../arkcli-auth/references/api-key-query.md) 定位目标；`apikey.get_raw`/`profile apikey get` 有条件提供读取能力，**不能声称 CLI 只能轮换、不能读取已有 Key**。导出受 Access 与宿主限制，失败应如实报告；查询失败绝不自动触发破坏性的轮换，也不在聊天中回显完整 Key。
+
+## 适用场景
+
+- 查看当前账号下持有哪些套餐 → `plans get`
+- 下单买套餐（含个人 / 团队）→ `plans buy`
+- 续费已有套餐 → `plans renew`
+- 看套餐支持的模型清单与模型规格（上下文窗口、输入/输出 token 上限、输入模态）→ `plans model-list`
+- 切换 ark-code-latest 的路由目标（Auto 智能调度或具体影子模型）→ `plans model-apply`
+- Agent Plan 个人版轮换专属 APIKey → `plans personal rotate-apikey`；Coding Plan 个人版普通 Key 不走此命令
+- 列出 / 筛选企业版席位 → `plans team seat-list`
+- 把企业版席位绑给子用户 → `plans team seat-assign`
+- 轮换企业版席位的 APIKey（自己 or 管理员批量）→ `plans team rotate-apikey`
+- 查本机 AI Agent 上专属 Harness 能力装没装（只读）→ `plans harness-status`：按能力卡报豆包搜索 / 专业数据集 / Agent 记忆（MCP），外加全局**火山引擎Supabase**（CLI+Skill 装没装）。「我的 supabase / MCP 装好了吗」都走这里（Agent 记忆卡仅个人版 `agent-plan`；团队版报 `absent` 是预期、非漏装，详见其 reference）
+
+## 反唤起信号
+
+- 只问套餐已用/剩余额度、刷新时间或席位用量 → [`arkcli-usage`](../arkcli-usage/SKILL.md)，不是 `plans get`。
+- 要读取/注入已有 API Key 的值而非轮换 → [`arkcli-auth`](../arkcli-auth/SKILL.md) 的 Key 查询流程；不要为只读需求调用 `plans personal/team rotate-apikey`。
+- 要创建或管理普通 `ep-xxx` 接入点 → [`arkcli-deploy`](../arkcli-deploy/SKILL.md) / [`arkcli-infer-endpoint`](../arkcli-infer-endpoint/SKILL.md)；Plan 持有或 `ark-code-latest` 路由信息不能代替 Endpoint 查询。
+
+## 快速决策
+
+- 用户问 "我有什么套餐 / 我订阅了什么"：直接 `arkcli plans get`，零参数（**仅持有列表 + 状态，不含用量**）
+- 用户问“何时到期 / 还剩几天”：先读 [get 的到期时间规则](references/arkcli-plans-get.md#到期时间--还剩多少天)；仅在能安全捕获并脱敏 debug 的环境核实对应上游时间字段，按北京时间（UTC+8）交付。不能直接回显 debug，也不能把 Usage 的额度刷新时间当订阅到期时间。
+- 用户问 **"我用了多少 / 还剩多少 / 几号刷新 / 套餐内 vs 套餐外"** —— **不在本 skill**，转 [`../arkcli-usage/`](../arkcli-usage/SKILL.md)：
+  - "我的套餐还剩多少 / 几号刷新" → `arkcli usage plan` 或 `arkcli usage balance --type plan`
+  - "我哪个模型用得最多 / 套餐内套餐外比例" → `arkcli usage plan-details`
+  - "团队席位的用量" → `arkcli usage seats --product agent-plan-team --with-usage`
+- 用户问 "Agent Plan / Coding Plan 支持什么模型 / 上下文多长 / 最大输入输出多少 / 是否支持图片或视频输入"：`arkcli plans model-list --plan <plan>`；只需要直接 ModelName 时加 `--mode direct`，只需要 `ark-code-latest` 路由候选时加 `--mode routing`，需要对照两类清单时使用默认 `--mode all`。`models[]` 是路由候选，`direct_models[].model_name` 才是可直接配置/调用的 ModelName，两类条目都可读取 `context_window` / `max_input_tokens` / `max_completion_tokens` / `input_modalities` / `load`
+- 用户要 "切换 ark-code-latest 底层模型 / 改成 Auto 智能调度 / 锁定某个模型"：`arkcli plans model-apply --plan <plan> --model <model-id|output-name|auto>`（**写操作**，与控制台联动；可选项先用 `plans model-list --mode routing` 确认）
+- 用户要“买套餐”：读 [buy.md](references/arkcli-plans-buy.md)，收齐 `--plan`、`--type`、`--duration`，团队版另收 `--quantity`，不要替用户做选择
+- 用户要“续套餐”：读 [renew.md](references/arkcli-plans-renew.md)，确认 `--plan`、续费月数，团队版另选已有 `--seat-ids`；保持原档位，不传 `--type` / `--quantity`
+- 使用 plan 时被拦 `plan_agreement_required`（三方渠道订单首用签署）：见 [references/arkcli-plans-agreement-signing.md](references/arkcli-plans-agreement-signing.md)；**禁止**擅自设 `ARKCLI_ALLOW_HEADLESS_PLAN_AGREEMENT` 替用户签署，引导用户在交互式终端完成签署
+- 使用 plan 时返回 `plan_agreement_status_unavailable`：签署状态尚未确认，检查网络与登录状态后重试；`--yes` 和 `ARKCLI_ALLOW_HEADLESS_PLAN_AGREEMENT` 都不能绕过该错误
+- 用户要 "重置 / 轮换 APIKey"：分清个人版还是企业版，参考对应 reference；**写操作，原 APIKey 立即失效**，必须按 reference 走二次确认（除非用户明确要 `--yes` 跳过）
+- 用户要 "**查席位 / 看团队 seat 绑定情况 / 谁绑了哪个 seat / 列出席位 / 哪些席位激活了 / 团队席位 admin 视图**" → `plans team seat-list --plan <agent-plan-team|coding-plan-team>`(**这是 seat 管理的默认入口**,管理视角列基础信息 + 绑定关系,**不带用量数字**;要看每个 seat 用了多少 token / 套餐百分比 → `arkcli usage seats --with-usage`)
+- 用户要 "把席位分配给员工 / 给员工分配 seat / 解绑席位"→ `plans team seat-assign`,先准备好 `seat-id=user-id` 配对清单
+- 用户**只知道员工用户名**不知道精确 UserID：先 `arkcli iam userid --username <prefix>` 反查到 `user_id`，再喂给 `seat-assign --bind seat-id=<user_id>`
+
+## Agent 快速执行顺序
+
+1. 先确认认证状态：`arkcli auth status`；缺失走 `../arkcli-auth/`
+2. 读操作（`get` / `model-list` / `seat-list`）直接执行；只在用户问 "我的" 时考虑当前身份
+3. **写操作（`buy` / `renew` / `rotate-apikey` / `seat-assign` / `model-apply`）** 务必：
+   - 先读对应 reference
+   - 跟用户确认关键字段（plan / type / duration / SeatIDs / UserID 配对）
+   - `rotate-apikey` 默认不传 `--yes`，让 CLI 走 [Y/N] 二次确认
+4. 部分失败（per-item Success/Failed 数组）是合法返回；exit code 非零时**不要**直接当全失败，先看 stdout 里的 success_count / failed_count
+
+## 写操作风险清单（必读）
+
+| 命令 | 风险 | 必做项 |
+|---|---|---|
+| `plans buy` | **计费**，`IsAutoPay=true` 自动扣款 | 必须先不带 `--yes` 走协议闸门 → 把 agreements 展示给用户 → 用户明确同意后加 `--yes`。详见 [协议闸门流程](#-协议闸门plans-buy--plans-renew-强制流程) |
+| `plans renew` | **计费**，自动扣款 | 同 buy 协议闸门;团队版必传 `--seat-ids` |
+| `plans personal rotate-apikey` | **原 APIKey 立即失效** | 默认走 [Y/N] 确认；提醒用户同步替换 harness 配置 |
+| `plans model-apply` | 改变套餐请求路由指向（立即生效、与控制台联动） | 非交互必须显式 `--model`；先用 `plans model-list --mode routing` 确认可选目标；团队版无席位会报错 |
+| `plans team seat-assign` | 修改席位绑定关系 | 显式 `--bind seat-id=user-id`，自动调 IAM 反查 UserName |
+| `plans team rotate-apikey` | **原 APIKey 立即失效** | self-rotate 默认 agent-plan-team；admin batch 通过 `--seat-ids` |
+
+## 命令一览
+
+| 命令 | 类型 | 说明 |
+|------|------|------|
+| [`plans get`](references/arkcli-plans-get.md) | 读 | 列出当前账号持有的套餐（个人版 + 团队版聚合） |
+| [`plans buy`](references/arkcli-plans-buy.md) | 写（计费） | 下单购买套餐 |
+| [`plans renew`](references/arkcli-plans-renew.md) | 写（计费） | 续费已有套餐 |
+| [`plans model-list`](references/arkcli-plans-model-list.md) | 读 | 用 `--mode all|direct|routing` 查询双列表；`models[]` 是 ark-code-latest 路由候选，`direct_models[].model_name` 是直接 ModelName，并透出模型规格与负载 |
+| [`plans model-apply`](references/arkcli-plans-model-apply.md) | 写 | 设置 ark-code-latest 路由目标（auto 或具体影子模型） |
+| [`plans personal rotate-apikey`](references/arkcli-plans-personal-rotate-apikey.md) | 写（毁坏） | 轮换 Agent Plan 个人版 APIKey |
+| [`plans team seat-list`](references/arkcli-plans-team-seat-list.md) | 读 | 列出企业版席位 + 多维度筛选 |
+| [`plans team seat-assign`](references/arkcli-plans-team-seat-assign.md) | 写 | 批量绑定企业版席位到子用户 |
+| [`plans team rotate-apikey`](references/arkcli-plans-team-rotate-apikey.md) | 写（毁坏） | 轮换企业版席位 APIKey（self / admin batch） |
+| [`plans harness-status`](references/arkcli-plans-harness-status.md) | 读 | 查本机 AI Agent(claude-code/codex/opencode/openclaw/trae)上 Agent Plan 内置 MCP 的安装状态(只读、免登录) |
+
+## 常见降级
+
+- 鉴权错误：转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md)
+- 区域 / project 不对：转 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md)
+- **想看套餐用量 / 配额（used / total / percent / reset_at / 按模型拆）**：转 [`../arkcli-usage/SKILL.md`](../arkcli-usage/SKILL.md) — 本 skill 只回答"持有什么"，不回答"用了多少"
+- **想看账单 / 结算金额**：转 [`../arkcli-billing/SKILL.md`](../arkcli-billing/SKILL.md) — `plans` 不出钱
+- 想生成模型调用样例：转 [`../arkcli-code-example/SKILL.md`](../arkcli-code-example/SKILL.md)
+- 试用某个模型不打算正式部署：转 [`../arkcli-chat/SKILL.md`](../arkcli-chat/SKILL.md) / [`../arkcli-gen/SKILL.md`](../arkcli-gen/SKILL.md)
+- 没现成产品命令时回退 [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md)
+- 想**安装 / 注入 / 移除** MCP（不是查看状态）：转 [`../arkcli-helper/SKILL.md`](../arkcli-helper/SKILL.md) — `plans harness-status` 只读查看，不改配置
+
+## 参考
+
+- [arkcli-shared](../arkcli-shared/SKILL.md) -- 认证 / 全局参数 / 输出规则
+- [arkcli-usage](../arkcli-usage/SKILL.md) -- 套餐**用量 / 配额**视图（`usage plan` / `usage plan-details` / `usage balance` / `usage seats --with-usage`），跟本 skill 的"持有 / 购买 / 席位管理"互补
+- [arkcli-billing](../arkcli-billing/SKILL.md) -- 套餐**结算金额**（火山计费中心拆账，T+1）
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) -- 套餐买好后用 `+deploy` 部署 endpoint
+- [arkcli-helper](../arkcli-helper/SKILL.md) -- 给 AI Agent **注入 / 移除** Agent Plan 内置 MCP（`plans harness-status` 只读查看，注入改动走这里）

package/skills/arkcli-plans/references/arkcli-plans-agreement-signing.md

@@ -0,0 +1,74 @@
+# 三方渠道订单首用数据协议签署
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+火山官网在抖店/移动商城等三方渠道售卖 **Agent Plan / Coding Plan 个人版**时，下单环节无法签署数据授权协议。后端在 `ListSubscribeTrade` 响应里通过 `NeedCheckAgreement=true` 标记「三方来源新购订单且尚未签署」，arkcli 会在**使用 plan 资源前**拦截并引导签署。签署状态**完全以服务端为准**：CLI 不保留任何本地签署缓存或 mock 旁路，每次使用都在线确认。
+
+## 触发时机
+
+仅当**同时**满足以下条件时执行在线签署状态检查：
+
+- 本次执行走**个人版** plan 数据面（agent-plan / coding-plan profile；团队版与 platform 不触发）；
+- 当前具备可绑定账号的控制面身份（SSO/控制面凭证；纯数据面 API Key 直接 fail-closed，见下文）；
+- 随后 `ListSubscribeTrade` 返回 `NeedCheckAgreement=false` 时直接放行；返回 `true` 时再调 `GetAccountAgreement` 查账号级签署记录（`AgreementType=AgreeAgentPlanService` / `AgreeCodingPlanService`），`IsSigned=true` 放行、`false` 才弹签署引导；若控制面 invoker、认证刷新、网络或服务端不可用，则 fail-closed，不执行受保护的 Plan 请求。
+
+命中触发的是**使用入口**，不是购买入口：
+
+- `arkcli +chat` / `+gen` / `+understand`（解析到个人版 plan 数据面时）
+- `arkcli chat get/delete/list-input-items` 与 `gen get/list/delete`（当前数据面为个人版 plan 时）
+- `arkcli api <arkruntime-action>`（Raw API Explorer 指向个人版 plan 数据面时）
+- `arkcli helper` / `arkcli helper configure` / `helper mcp`（配置或安装个人版 plan 能力前，包括 CUA）
+- `arkcli profile apikey get`（导出个人版 plan 明文 key 前）
+- `arkcli plans personal rotate-apikey` 与个人版 `plans model-apply`（变更个人版 plan 凭证或路由前）
+- Raw API Explorer 中会变更个人版 plan 或泄露其明文凭证的控制面 action（包括个人版模型路由、Plan key、MCP key 和 OpenViking key）
+
+与 `plans buy/renew` 的 `agreement_required` 协议闸门是两个独立机制：buy/renew 拦的是**下单**，本闸门拦的是**三方渠道订单的首次使用**。
+
+## 交互流程（TTY）
+
+一屏式签署屏（对齐 PRD mock 与 Web 控制台）：
+
+```
+◆ 数据授权协议
+请注意，使用Agent Plan个人版前需要进行相关协议的签署，在初次使用时请阅读并同意以下协议：
+  1. 《火山引擎数据授权协议》 <url>
+  2. 《方舟平台专用条款》 <url>
+  ...
+按 1–N 打开对应协议 · Space 勾选/取消 · H 勾选/取消 Harness · Enter 继续 · Esc 退出
+[ ] 已阅读并同意上述 N 份协议（必选，不勾选无法进入使用）
+[ ] 已阅读并同意《Harness权益说明和产品专用条款》（可选，仅影响 Harness 抵扣）
+```
+
+- 数字键 1–N 在浏览器打开对应协议（停留在本屏，底部给瞬态反馈；URL 同屏展示可复制）；
+- 勾选项 ≤ 2 个，**不做焦点移动**：`Space` 切必选（数据协议组）项，`H` 切可选（Harness）项（仅 Agent Plan 有）；
+- 勾选框**默认全部不勾**（对齐 Web 控制台，需用户主动勾选）；Agent Plan 个人版 = 6 份数据协议（必选）+ 1 份 Harness 协议（可选），Coding Plan 个人版 = 5 份数据协议（必选，无 Harness 项）；
+- Enter 提交时必选未勾会行内红字报错且不退出；Esc / Ctrl-C 放弃签署会**阻断使用**并返回取消错误；
+- 提交后调 `SignAccountAgreement {AgreementType}` 完成签署，服务端未回 `IsSigned=true` 按失败处理；CLI 不写任何本地签署记录，下次使用仍由服务端 `GetAccountAgreement` 判定；
+- 仅当用户在屏上主动勾选 Harness（Agent Plan）时，签署成功后才 best-effort 调 `UpdateAccountOverdraftSwitch` 开通抵扣；失败只给 warning（「协议已签署，但 Harness 抵扣开启失败」），不回滚签署。
+
+## 非交互环境（CI / 管道 / agent）
+
+严格模式，`--yes` 在非 TTY 下**不放行**：
+
+- 无逃生 env：硬拒，返回 `plan_agreement_required` 结构化错误，引导到交互式终端签署；
+- 显式设置 `ARKCLI_ALLOW_HEADLESS_PLAN_AGREEMENT=1`：stderr 审计行后调 `SignAccountAgreement` 签署**必选数据协议**并放行，**不开通 Harness 抵扣**（给真·无人值守自动化，与其它 `ARKCLI_ALLOW_HEADLESS_*` 逃生环境变量同一模式）。
+
+TTY 下传 `--yes` 视为真人已预先阅读并同意必选数据协议，跳过交互直接签署；同样**只签必选协议、不开通 Harness**（对齐 Web 默认不勾），Harness 只能由用户在交互屏主动勾选。
+
+Agent 引导原则（与 buy 闸门一致）：**禁止**在未告知用户的情况下擅自设置 `ARKCLI_ALLOW_HEADLESS_PLAN_AGREEMENT` 替用户签署；正确做法是引导用户在交互式终端跑一次使用命令完成签署。
+
+## 纯 API Key 调用
+
+`plan_agreement_identity_required` 的触发条件是**没有可用的控制面身份**，不是"有数据面 API Key"本身：
+
+- 显式 `--api-key` + Agent Plan/Coding Plan `--base-url` 形成无控制面身份的 stateless 调用 → fail-closed；
+- 个人版 Plan profile 完全只剩数据面 API Key（无 SSO id_token、无 AK/SK、无 identity-bound 火山控制面 STS）→ fail-closed；
+- 只要具备下列任一可用控制面身份，即使同时存在数据面 API Key，也必须放行到 `ListSubscribeTrade` / `GetAccountAgreement` 探测，**不得**返回本错误：SSO id_token、AK/SK、identity-bound 火山控制面 STS（`init-volc` / 云开发机 / broker，或 id_token 过期但 STS 仍可续的 SSO 登录）。
+
+判据与 `internal/apiclient/ark.go` 的控制面 transport 路由一致，不看 `AuthMethod()`：该字段优先级是 SSO > AK/SK > APIKey > Volc STS，因此 `arkcli auth status` 的 `auth_method` 会因数据面 API Key 存在而显示 `apikey`。判断是否真的"没有控制面身份"要看 `control_plane_auth.status`；`auth_method=apikey` + `control_plane_auth.status=ok` 是"有身份"，不是本错误。引导用户先登录并选择对应的个人版 Plan profile；不要通过改写 Base URL 或直接调用数据面来绕过。Platform 数据面的临时 API Key 调用不受此规则影响。
+
+## 签署状态暂不可用 / 签署失败
+
+CLI 必须在线确认状态（无本地缓存可旁路）。控制面 invoker 创建失败，或 `ListSubscribeTrade` 探测、`GetAccountAgreement` 查询因认证刷新、网络、限流、服务端错误而失败时，返回 exit code 4 的 `plan_agreement_status_unavailable`，保留底层错误供诊断，并在任何受保护业务请求发出前终止。用户已确认签署但 `SignAccountAgreement` 失败或服务端未置 `IsSigned=true` 时，返回 exit code 4 的 `plan_agreement_sign_failed`（数据授权协议签署失败，请稍后重试），同样阻断使用。检查网络和登录状态后重试；`--yes` 与 `ARKCLI_ALLOW_HEADLESS_PLAN_AGREEMENT` 都不能绕过状态确认。
+
+`plans get/model-list`、usage、登录/profile 管理、购买和续费仍可执行：这些是只读查询或恢复/签署所需的控制面路径，不消费个人版 Plan 数据面，也不导出个人版 Plan 明文凭证。团队版不属于本次三方渠道个人版协议范围。