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

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

@@ -0,0 +1,209 @@
+# plans buy
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **⚠️ 写操作 + 计费：** `plans buy` 强制 `IsAutoPay=true`，加 `--yes` 调用成功即真实扣款。**不要替用户做选择**：`--plan`、`--type`、`--duration`、团队版 `--quantity` 必须由用户明确给出。
+
+> **🔒 协议闸门 (强制流程，agent 必须遵守)：** 不传 `--yes` 时,本命令**不下单**，只返协议清单。Agent **必须**:
+> 1. 拿到 `agreements` 数组后,把每条协议的 `title` 和 `url` **逐条**展示给最终用户
+> 2. 等待用户**明确表达**"已阅读并同意全部协议"(不能用模糊措辞默认同意)
+> 3. 用户同意后才能加 `--yes` 重跑 `next_step` 字段里的命令
+>
+> **禁止**在用户没看过协议的情况下直接补 `--yes`。这是合规要求,跟 frontend 购买面板的 "我已阅读并同意《...》" checkbox 等价。
+
+## 三种调用形态
+
+| 形态 | 行为 | 何时用 |
+|---|---|---|
+| 不传 `--yes` 不传 `--estimate` | **协议闸门**:返协议清单 + **价格** + `next_step`,内部走 EstimatePrice,**不下单** | 默认引导步骤;agent 走这个一次拿"协议 + 价格" |
+| `--estimate` (无论是否带 `--yes`) | **在线询价**:调 EstimatePrice,返价格,**不下单** | 跟闸门重叠,留作脚本"只询价不看协议"的快捷出口 |
+| `--yes` 不带 `--estimate` | **真下单**:`IsAutoPay=true` 自动扣款 | 用户已确认协议 + 价格,真下单 |
+
+> **闸门里已经包含价格** — 不需要先 `--estimate` 再看协议。一次调用同时拿到 `agreements` + `total_amount_cny` + `original_amount_cny`；展示后等待明确同意，再走 `next_step`。
+
+## 收参与协议披露模板
+
+先读本 reference，再构造第一条命令。家族与个人/团队共同映射为 `--plan`，档位映射为 `--type`，团队席位数映射为 `--quantity`；不能发明 `--product`、`--edition` 或 `--tier`。
+
+一次只问一个尚未确定的决策；已提供的值不重复问。按以下顺序展开，不能在家族未定时混列两家的档位：
+
+1. 家族：Agent Plan（智能体任务）／Coding Plan（AI 编程工具）。
+2. 版本与档位：已选家族的个人版合法档位，或一个团队版入口。个人版一次选择确定版本和档位；选团队版后，再单问同家族档位，然后单问席位数，不同时把后续层选项堆进当前问题。
+3. 时长：提供 1／3／6／12 个月快捷选项；用户明确给出其他 1–12 的整数仍合法，不能强改为快捷值。
+4. 收齐参数后进入协议闸门。续费使用 [renew](arkcli-plans-renew.md) 的短决策链，不重新询问档位或购买数量。
+
+每个档位选项的说明必须包含当前价格、典型场景及关键限制，按下文权益说明填充；团队数量是席位数，不是月份。没有可靠当前权益数据就明确标注未知，不捏造价格或资格。
+
+协议披露使用以下结构，**所有占位符都取本次返回值**，不要复用历史询价或把协议缩写为“相关条款”：
+
+```text
+协议确认
+购买/续费：<plan> / <tier>，<duration> 个月
+数量/目标席位：<quantity 或 seat_ids；个人版注明不适用>
+本次实付：¥<total_amount_cny>（有原价时同时列原价）
+请阅读以下全部协议：
+- [<agreements[0].title>](<agreements[0].url>)
+- ... 按返回顺序逐条列出，不截断
+明确同意全部协议后，继续执行将按上述实付价格自动扣款。
+继续：已阅读并同意全部协议；停止：取消购买/续费。
+```
+
+必须实际等待用户回应。拒绝、取消、空答案、未回答、工具拒绝或模糊回应均不放行；不得代答或自行加 `--yes`。宿主支持结构化交互时在其正文中完整展示这些信息；具体 question、授权 Pane / Web Widget 的分工以共享宿主协议为准。工具执行 permission 不等于同意业务协议，协议同意也不等于已取得工具执行授权。价格、套餐或席位变化后须重新披露并确认。
+
+## 命令
+
+```bash
+# 第 1 步: 引导 (不传 --yes) — 拿到协议清单
+arkcli plans buy --plan agent-plan --type small --duration 1
+
+# 第 2 步 (可选): 询价
+arkcli plans buy --plan agent-plan --type small --duration 1 --estimate
+
+# 第 3 步: 用户阅读并同意全部协议后, 真下单
+arkcli plans buy --plan agent-plan --type small --duration 1 --yes
+
+# 团队版各档位示例
+arkcli plans buy --plan agent-plan-team --type medium --duration 2 --quantity 5 --yes
+arkcli plans buy --plan coding-plan-team --type pro --quantity 10 --yes
+```
+
+## 参数
+
+### 档位选项的业务说明
+
+不能只让用户在裸 `small/pro` 等名称中盲选。每个档位选项应说明**价格、典型场景、关键限制**；已明确的参数不再问，Agent 与 Coding 的档位不能混在同一组。
+
+价格先复用本轮 `pricing plans` 的对应产品/版本/档位记录，没有时按 [pricing plans](../../arkcli-pricing/references/arkcli-pricing-plans.md) 查询；带 `error` 的记录不是零元档。团队价不能套个人价，多月和多席位最终以本次协议闸门的 `total_amount_cny` 为准。
+
+以下保留 Vaka 1.0.32 业务说明的场景和权益对照，**数值及视频资格是历史核对基线，不是当前权益承诺**：
+
+| 家族 / 个人档位 | 典型场景 | 原业务说明的权益基线（使用前核对） |
+| --- | --- | --- |
+| Coding / `lite` | 中等强度开发、一般开发任务 | AI 编程工具场景；价格以当前查询为准 |
+| Coding / `pro` | 复杂项目、高强度开发 | AI 编程工具场景；价格以当前查询为准 |
+| Agent / `small` | 轻量体验 | ¥40/月、20,000 AFP、不支持视频生成 |
+| Agent / `medium` | 1–2 个项目并行的参考档位 | ¥200/月、100,000 AFP、支持视频生成 |
+| Agent / `large` | 2 个以上项目并行的参考档位 | ¥500/月、250,000 AFP |
+| Agent / `max` | 2 个以上项目并行、较高额度需求 | ¥1,000/月、500,000 AFP |
+
+- 场景是选择参考，不是并发数或任务成功保证。团队版沿用同家族档位集合，但计价与权益按当前团队商品核对，不直接套个人 AFP。
+- 当前价格用查询返回；AFP、视频资格和使用限制用当前明确返回或官方权益条款核对，`pricing plans` 只有价格时不能声称已核实全部权益。未取得当前证据的项在选项说明中标“待核实”，不把历史值写成当前可用额度。
+- 当前 AFP 快照与上述历史基线不同，只能报告两者数值、查询时间和范围；没有订单周期或官方折算规则的证据，不得推断是按剩余天数折算、赠送、升降档或权益缩水。
+- Coding 的适用场景不能简化成“技术上完全没有 API”：客户端接入方式、套餐允许用途和实际 API 支持分别核对，不能用一把 Key 能调通推导任意用途都合规。
+- 宿主使用结构化选项时将这些信息放进 `option.description`；普通终端用等价简短文字。参数已完整时跳过收参，但不跳过协议和价格披露。
+
+### 参数表
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--plan` | 是 | string | `agent-plan` / `coding-plan` / `agent-plan-team` / `coding-plan-team` |
+| `--type` | 是 | string | tier 档位：agent-plan* 取 `small/medium/large/max`；coding-plan* 取 `lite/pro` |
+| `--duration` | 否 | int | 订阅时长（月），1-12，默认 1 |
+| `--quantity` | 团队版 必填 | int | 席位数量（≥1）；个人版传了会被忽略 |
+| `--yes` | 否 | bool | 跳过协议闸门，真下单 (`IsAutoPay=true`) |
+
+`--plan` 与 `--type` 兼容性：
+
+| Plan 系 | 合法 tier |
+|---|---|
+| agent-plan / agent-plan-team | small, medium, large, max |
+| coding-plan / coding-plan-team | lite, pro |
+
+## 返回值 (协议闸门, 默认形态)
+
+不传 `--yes` 不传 `--estimate` 时:
+
+```json
+{
+  "status": "agreement_required",
+  "plan": "agent-plan",
+  "tier": "small",
+  "duration": 1,
+  "echo": {"plan": "agent-plan", "tier": "small", "duration": 1},
+  "agreements": [
+    {"title": "火山引擎数据授权协议", "url": "https://www.volcengine.com/docs/82379/1928265"},
+    {"title": "方舟平台专用条款", "url": "https://www.volcengine.com/docs/82379/1104498"},
+    {"title": "免责声明", "url": "https://www.volcengine.com/docs/82379/1108564"},
+    {"title": "豆包模型服务协议", "url": "https://www.volcengine.com/docs/82379/1142195"},
+    {"title": "开源模型许可证", "url": "https://www.volcengine.com/docs/82379/1454060"},
+    {"title": "语音模型服务协议", "url": "https://www.volcengine.com/docs/6561/1866421?lang=zh"},
+    {"title": "Harness权益说明和产品专用条款", "url": "https://www.volcengine.com/docs/82379/2516291?lang=zh"}
+  ],
+  "total_amount_cny": 99.5,
+  "original_amount_cny": 100.0,
+  "confirm_text": "下单将立即扣款 (IsAutoPay=true)。请把上述协议链接展示给最终用户...",
+  "next_step": "arkcli plans buy --plan agent-plan --type small --duration 1 --yes"
+}
+```
+
+**闸门同时返回价格**:`total_amount_cny`(实付)+ `original_amount_cny`(原价,有折扣时低于原价)。Agent 应该把价格 + 协议一起展示给用户。
+
+**`agreements` 数组按 plan 类型不同**(agent-plan 系含 Harness 协议;团队版多一条对应套餐专用条款,不带《数据授权协议》)。**直接用返回值里的清单**,不要替换或省略。
+
+## 返回值 (真下单)
+
+加 `--yes` 后:
+
+```json
+{
+  "status": "success",
+  "plan": "agent-plan-team",
+  "tier": "medium",
+  "duration": 2,
+  "quantity": 5,
+  "order_number": "ORD-...",
+  "instance_id": "ins-...",
+  "seat_ids": ["seat-...", "seat-..."]
+}
+```
+
+`seat_ids` 仅团队版填充。
+
+## 失败语义
+
+**失败类型要分清；已确认的参数不得重新收集：**
+
+1. **transport error**：返回普通 error，但超时、断连或未解析出订单字段不能证明订单没落库/没扣钱。先核对订单状态；不得仅因失败退出就自动重新下单。
+2. **payment_failed**（订单**已**落库但支付未完成）：典型如余额不足。返回 `output.ErrWithHint` envelope：
+   ```json
+   {
+     "ok": false,
+     "error": {
+       "type": "payment_failed",
+       "message": "INSUFFICIENT_BALANCE_ERROR",
+       "hint": "Order ID: ORD-...; please complete the payment manually in console"
+     }
+   }
+   ```
+   exit code = 5（`ExitAPI`）。**用户必须去 console 手动补单或取消订单**，不要在 CLI 重试 `plans buy`（会重复下单）。
+
+   团队版 dangling：第一步 `CreateSeatInfo` 成功 + 第二步 trade 失败 → hint 里会带 `(Created seats: seat-001,seat-002; bound to the unpaid order above.)`，**席位资源已生成**，不会自动清理。
+
+3. **`ProductStockNotEnough`（商品库存不足）**：不是用户参数填错。不自动重试，不重新问 plan / tier / 时长 / 席位数，不擅自换档或拆单；说明库存不足，保留已返回的 Order ID / SeatID，引导到对应 Agent Plan / Coding Plan 控制台页面处理。没有返回订单号只表示本次响应未提供订单号，不能据此宣称订单未落库、没有扣款或无需补付/取消；是否已有订单须核对控制台记录。GUI 只是后续处理入口，不表示购买已成功或页面一定有库存；Vaka 的卡片格式见主 Skill 宿主说明。
+
+transport error、库存不足、支付失败都保留本轮已确认参数。只有用户主动改变购买目标时才重新收集变更项；不得为了“恢复流程”再次创建收费订单。
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `--plan must be one of ...` | 拼错 plan key | 严格用 4 选 1 |
+| `--type %q not allowed for --plan %q` | tier 跟 plan 不兼容 | 见上方表格 |
+| `--quantity is required for team plans` | 团队版漏传 | 加 `--quantity N` |
+| `--duration must be 1..12` | 越界 | 1-12 之间 |
+| `payment_failed` envelope | 余额不足 / auto-pay 失败 | 去 console 补单，不要 CLI 重试 |
+| `ProductStockNotEnough` | 商品库存不足 | 不重试、不重问参数；转对应套餐控制台处理，保留已有订单/席位信息 |
+
+## 注意事项
+
+- **真实扣款**：CLI 没有 "下单不支付" 模式；要询价用 `--estimate`，不得为了验证流程擅自换轻档位真实试买
+- 团队版下单后席位会以 `BillingStatus=Running` 状态出现，但**没绑定子用户**；后续走 [`plans team seat-assign`](arkcli-plans-team-seat-assign.md) 分配
+- 重试要谨慎：`payment_failed` 的订单**已经在服务端**，重跑会再开一单
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans renew`](arkcli-plans-renew.md) -- 续费已有套餐
+- [`plans get`](arkcli-plans-get.md) -- 下单后查持有状态
+- [`plans team seat-assign`](arkcli-plans-team-seat-assign.md) -- 团队版下单后绑定子用户
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

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

@@ -0,0 +1,96 @@
+# plans get
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **范围限制：** `plans get` 只回答"我**持有**哪些套餐 + 状态(Effective/Running/...)"，**不回答"用了多少 / 还剩多少 / 几号刷新 / 按模型拆分"**。配额查询走：
+> - `arkcli usage plan` —— 完整版，含 used / total / percent / reset_at + 多周期(5h/daily/weekly/monthly)
+> - `arkcli usage balance --type plan` —— 精简版（同数据源）
+> - `arkcli usage plan-details` —— AgentPlan 按模型 × 套餐内/外的时间序列
+>
+> 详见 [`../../arkcli-usage/SKILL.md`](../../arkcli-usage/SKILL.md)。
+
+一次性返回当前账号下**实际持有**的套餐：Agent Plan / Coding Plan 的个人版 + 团队版聚合。读操作，无副作用。
+
+## 命令
+
+```bash
+arkcli plans get
+```
+
+## 参数
+
+零参数。所有 4 路 plan（agent-plan / agent-plan-team / coding-plan / coding-plan-team）一次并发拉取。
+
+## 返回值
+
+```json
+{
+  "plans": [
+    {
+      "key": "agent-plan",
+      "name": "Agent Plan",
+      "scope": "personal",
+      "tier": "small",
+      "status": "Effective"
+    },
+    {
+      "key": "agent-plan-team",
+      "name": "Agent Plan Team",
+      "scope": "team",
+      "tier": "medium",
+      "status": "Running",
+      "seat_id": "seat-..."
+    }
+  ]
+}
+```
+
+| 字段 | 出现条件 | 含义 |
+|------|---------|------|
+| `key` | always | 稳定标识：agent-plan / agent-plan-team / coding-plan / coding-plan-team |
+| `scope` | always | personal / team |
+| `tier` | 持有时 | 个人版：small/medium/large/max（agent）或 lite/pro（coding）；团队版：当前用户席位的 tier |
+| `status` | 持有时 | 个人版：Effective / Pending / Expired 等；团队版：Running |
+| `seat_id` | 团队版独有 | 当前用户在该 Scene 下的席位 ID（团队版才有） |
+| `error` | 调用失败时 | API 透出诊断信息；跟 tier/status 互斥 |
+
+**没持有的套餐 / Reclaimed 历史订阅 / 团队版无席位** 会被过滤掉，不出现在数组里。
+
+## 行为细节
+
+- 内部并发拉 `ListSubscribeTrade`（个人版）+ `GetSeatInfo`（团队版）
+- 任一 plan 失败不阻塞其它 plan：失败项保留在数组里，带 `error` 字段
+- 团队版仅识别 `BillingStatus=Running` 的有效席位，历史席位（Pending/Expired/Reclaimed）会被过滤
+
+## 到期时间 / 还剩多少天
+
+这是订阅有效期问题，不是 Usage 的额度刷新时间。标准 `plans get` JSON **没有到期字段**，不能从 `status`、`tier`、购买月份或 `reset_at` 推算。
+
+1. 用户问到期时间时，可用 `arkcli --debug plans get --format json` 取证；但 debug 的团队响应可能含席位 Key，**必须先把 stdout/stderr 分别捕获到权限受限的临时文件，只向工具返回/对话输出目标时间和必要标识**，不能直接打印原始 debug。`--debug` 的上游响应在 stderr，不是给 stdout 增加字段，不要用 `2>&1` 混成 JSON。当前环境无法安全捕获并脱敏时不打开 debug，转 API Explorer 核对已注册的订阅读接口及字段投影，或说明缺少安全取证条件。
+2. 个人版从对应 `ListSubscribeTrade` 响应的 `Result.InfoList` 定位订阅，读取 `EndTime`；团队版从对应 `GetSeatInfo` 的 `Result` 读取 `SeatID` 与 `ExpiredTime`。区分 Agent/Coding、个人/团队、订阅/席位，不能把四路响应里的首个时间当作目标套餐到期时间。已有团队管理清单时可复用目标席位的 `expired_time`，不为查个人到期时间扩大到全团队。
+3. 上述字段是 Unix **秒**，可能以数字或数字字符串返回。转成北京时间 `Asia/Shanghai`（UTC+8）后交付完整日期和时间，并标明时区；不要把 UTC 原值直接标成北京时间，也不要误按毫秒转换。若上游已给带时区的 ISO 时间，按其原始时区解析后转换，不重复加 8 小时。
+4. “还剩几天”按本次查询时间与到期时间计算，注明查询时间及取整口径；已经到期明确说已到期。缺失、0、解析失败、目标记录不唯一或该路 API 失败时，只能说到期时间未确认，不能报 1970 年、永久有效或用别的套餐时间补齐。
+
+最终只给套餐/席位标识、到期时间、时区及必要状态；不回显 debug 原文、API Key 或其他身份信息。诊断只读失败时保留脱敏错误，遵循当前宿主的鉴权恢复规则，不自动购买、续费或切换身份。
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `plans get: ark: API error: AuthFailure` | 未认证 / token 过期 | `arkcli auth login volc-sso` |
+| 输出 `{"plans":[]}` | 当前账号没有任何套餐 | 用 `plans buy` 下单或检查账号是否切换 |
+
+## 注意事项
+
+- 这是**唯一一个无需任何参数**的 plans 子命令；用户问 "我有什么套餐 / 我订阅了什么" 直接调用即可
+- **想看用量 / 配额（used / total / percent / 几号刷新）**：本命令**不出**这些字段，转 `arkcli usage plan` / `arkcli usage balance --type plan` / `arkcli usage plan-details`（详见顶部范围限制说明）
+- 不会列出别人的套餐 — 永远是当前 SSO 身份名下的视图
+- 团队版只展示当前用户**自己持有的席位**；要看团队全部席位走 [`plans team seat-list`](arkcli-plans-team-seat-list.md)（基础信息）或 `arkcli usage seats --with-usage`（含席位用量）
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans model-list`](arkcli-plans-model-list.md) -- 看持有套餐能调哪些模型
+- [`plans buy`](arkcli-plans-buy.md) / [`plans renew`](arkcli-plans-renew.md) -- 下单 / 续费
+- [arkcli-usage](../../arkcli-usage/SKILL.md) -- 套餐用量 / 配额（本命令不含的字段都在这里）
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-harness-status.md

@@ -0,0 +1,149 @@
+# plans harness-status
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+> **范围限制：** `plans harness-status` 是**只读视图** —— 只回答"本机某个 AI Agent 上，Agent Plan 内置 MCP 装没装、key 就没就绪"，**不安装、不修改、不移除任何配置**。要**注入 / 配置 / 移除** MCP，走 [`../../arkcli-helper/SKILL.md`](../../arkcli-helper/SKILL.md)（`helper mcp` / `helper reset`）。
+
+只读本机 AI Agent（harness）的配置，镜像火山方舟控制台「配置 Harness」页：按**能力卡**报告专属 Harness 能力各自装没装、key 就没就绪。纯本地文件读取，**免登录**（不需要 `auth status` 通过）。
+
+输出分两段：
+
+- **`agents[]`** —— per-agent 的 MCP 能力卡：**豆包搜索** / **专业数据集** / **Agent 记忆**。每张卡带 `forms` 交付形态标签 + 卡级 `installed`/`key_state` + 卡内底层 `mcp_servers` 明细。
+- **`supabase`** —— 全局的**火山引擎Supabase** 集成态，**与能力卡同形**：`installed` 是「装好没」统一 headline（CLI 与 Skill 都就绪），`cli_installed` / `skill_installed` 是次要细分。它不是 per-agent 的 MCP，而是一次性的 CLI + Skill + 登录态注入，故置顶单列、**与查哪个 agent 无关**。
+
+> **plan 维度提醒：** 命令免登录、不区分 plan 类型，只如实镜像磁盘节点。但「Agent 记忆」卡(OpenViking 两台)仅**个人版 `agent-plan`** 适用；**团队版 `agent-plan-team` 与 OpenViking 无关** —— 团队版机器上该卡 `installed:false` 是预期正确状态，**不是漏装**（详见文末注意事项）。`supabase` 块只报本机有没有装，**不判当前 plan 能不能用**（资格要登录读 profile，与本命令免登录冲突；想确认资格走 `arkcli helper supabase`）。
+
+## 命令
+
+```bash
+arkcli plans harness-status [agent] [--scope project] [--codex-config-scope profile|global] [--codex-profile <name>]
+```
+
+## 目标 agent 的选择（三种模式）
+
+| 调用 | 行为 |
+|---|---|
+| `plans harness-status`（在某 agent 里跑） | 自动识别当前宿主（claude-code / opencode / openclaw），只报它 |
+| `plans harness-status`（裸终端 / 脚本，识别不出宿主） | **全量兜底**：列出全部支持 MCP 的 agent，不报错 |
+| `plans harness-status <agent>` | 只报指定 agent；随处可用，被查 agent 此刻没在跑也能查（读磁盘配置） |
+
+> 宿主识别靠宿主注入的环境变量（`CLAUDECODE` / `OPENCODE` / `OPENCLAW_*`）。脱离宿主就没有这些信号 —— 此时**不报错**，改列全部（只读、零风险）。Codex / Trae 不被自动识别（无环境信号），始终在"列全部"兜底里出现，或显式 `harness-status codex` / `harness-status trae`。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `[agent]` | 否 | `claude-code` / `codex` / `opencode` / `openclaw` / `trae` 之一。不传 = 按上表自动决定。传非法名或 `hermes`（不支持 MCP）→ `validation` 报错并列出合法值 |
+| `--scope` | 否 | **仅 Trae**:`global`(默认)读 `~/.trae/mcp.json`;`project` 读当前目录 `./.trae/mcp.json`。对非 Trae agent 传 `project` 会报错 |
+| `--codex-config-scope` | 否 | **仅 Codex**:`profile`(默认)读 `~/.codex/<profile>.config.toml`;`global` 读 `~/.codex/config.toml` |
+| `--codex-profile` | 否 | **仅 Codex profile 模式**:Codex profile 名,默认 `arkcli` |
+
+## 返回值
+
+```json
+{
+  "agents": [
+    {
+      "agent": "claude-code",
+      "mcp_config_path": "/Users/me/.claude.json",
+      "capabilities": [
+        {
+          "key": "web-search", "name": "豆包搜索", "forms": ["skill", "mcp"],
+          "installed": true, "key_state": "real",
+          "mcp_servers": [
+            { "name": "mcp-server-askecho-search-infinity", "transport": "stdio", "installed": true, "key_state": "real" }
+          ]
+        },
+        {
+          "key": "datapro", "name": "专业数据集", "forms": ["mcp"],
+          "installed": true, "key_state": "real",
+          "mcp_servers": [
+            { "name": "dataPro-search", "transport": "http", "installed": true, "key_state": "real" }
+          ]
+        },
+        {
+          "key": "agent-memory", "name": "Agent 记忆", "forms": ["mcp"],
+          "installed": true, "key_state": "real",
+          "mcp_servers": [
+            { "name": "openviking-dataplane",    "transport": "http",  "installed": false, "key_state": "absent" },
+            { "name": "openviking-controlplane", "transport": "stdio", "installed": true,  "key_state": "real" }
+          ]
+        }
+      ]
+    }
+  ],
+  "supabase": {
+    "name": "火山引擎Supabase", "forms": ["cli", "skill"],
+    "installed": true, "cli_installed": true, "skill_installed": true
+  }
+}
+```
+
+| 字段 | 含义 |
+|---|---|
+| `agent` | harness 稳定标识：claude-code / codex / opencode / openclaw / trae |
+| `mcp_config_path` | 实际读取的配置文件路径（诊断"为什么说没装"时看这里） |
+| `capabilities[].key` | 能力稳定标识：`web-search` / `datapro` / `agent-memory` |
+| `capabilities[].name` | 能力展示名（对齐控制台卡）：豆包搜索 / 专业数据集 / Agent 记忆 |
+| `capabilities[].forms` | 交付形态标签（描述性）：`mcp` / `skill` / `cli`。豆包搜索同时交付 Skill+MCP |
+| `capabilities[].installed` | **卡级**：代表性 server 是否注入（Agent 记忆取 `openviking-controlplane`） |
+| `capabilities[].key_state` | **卡级**：`real` / `placeholder` / `absent`（见下表） |
+| `capabilities[].mcp_servers[]` | 卡内底层 MCP server 明细（诊断用；Agent 记忆含 dataplane+controlplane 两台） |
+| `mcp_servers[].name/transport/installed/key_state` | 单个底层 server 的名/传输/是否注入/key 三态 |
+| `supabase.name` / `supabase.forms` | 与能力卡同形：展示名「火山引擎Supabase」+ 交付形态 `["cli","skill"]` |
+| `supabase.installed` | **统一 headline**：CLI 与 Skill 都就绪才 `true`（= `cli_installed && skill_installed`）。用户/agent 看这一个就知「装好没」，不必自己 AND 两个细分字段 |
+| `supabase.cli_installed` | 细分：`byted-supabase-cli` 是否在 PATH |
+| `supabase.skill_installed` | 细分：byted-supabase 配套 skill 是否已装（靠 CLI 自带 `skills status`） |
+
+### key_state 三态
+
+| key_state | installed | 含义 | 怎么处理 |
+|---|---|---|---|
+| `real` | true | 已注入且 key 就绪 ✅ | 可用，无需动作 |
+| `placeholder` | true | 已注入但 key 还是占位符 / 空 | 带 key 重新注入：`arkcli helper mcp` |
+| `absent` | false | 没注入这一个 | 需要的话注入：`arkcli helper mcp` |
+
+> **安全**：本命令**从不输出真实 key**，只输出上面三种状态之一。
+
+## 能力卡 → 底层 MCP server 对照（个人版 agent-plan / 团队版 agent-plan-team）
+
+| 能力卡 `key`（name） | `forms` | 卡内底层 MCP server | key 来源 |
+|---|---|---|---|
+| `web-search`（豆包搜索） | skill·mcp | `mcp-server-askecho-search-infinity` | Agent Plan API Key（与 dataPro 同一把） |
+| `datapro`（专业数据集） | mcp | `dataPro-search` | Agent Plan API Key |
+| `agent-memory`（Agent 记忆，**仅个人版 agent-plan**） | mcp | `openviking-dataplane` + `openviking-controlplane` | dataplane：绑定库访问 key（vikingdb 下发；0 库时跳过 → 可能 `absent`）；controlplane：Agent Plan API Key（有 Agent Plan 即注入，不依赖 OV 库列表）。**团队版两台都从不注入** |
+
+> 卡级 `installed`/`key_state` 取**代表性 server**：豆包搜索取 askecho、专业数据集取 dataPro-search、Agent 记忆取 **controlplane**（最稳的"能力配没配"信号）。逐台细节看 `capabilities[].mcp_servers[]`。
+
+## 全局 Supabase 集成（`supabase` 块）
+
+| 字段 | 含义 | 怎么探测 |
+|---|---|---|
+| `cli_installed` | `byted-supabase-cli` 在不在 PATH | `exec.LookPath` |
+| `skill_installed` | byted-supabase 配套 skill 装没装 | CLI 自带 `byted-supabase-cli skills status`（CLI 未装时直接 `false`，不误报） |
+
+> Supabase 是 `arkcli helper supabase` 配的**全局**能力（CLI + Skill + 火山登录态注入），不是 per-agent 的 MCP，所以不进 `agents[]`、只在顶层 `supabase` 出现一次。本块**只报装没装、不判 plan 资格**（agent-plan 全档均支持，但资格判定要登录读 profile 类型/租户才知道，超出本免登录命令范围）。
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|---|---|---|
+| `{"type":"validation","message":"未知 agent ..."}` exit 2 | `[agent]` 传了不认识的名字 | 用 claude-code / codex / opencode / openclaw / trae |
+| `{"type":"validation","message":"agent \"hermes\" 不支持 MCP ..."}` exit 2 | 指定了不支持 MCP 注入的 agent | hermes 不支持 MCP |
+| `parse ... 非法 JSON` | agent 配置文件被手改坏了 | 修复该 agent 的 JSON 配置 |
+
+## 注意事项
+
+- 只读、免登录、零副作用 —— 跟 `helper mcp` / `helper reset`（写操作）相反方向
+- Codex:默认查 profile `~/.codex/arkcli.config.toml`;查全局配置用 `harness-status codex --codex-config-scope global`;查其它 profile 用 `--codex-profile <name>`
+- Trae:默认查全局 `~/.trae/mcp.json`;查项目级用 `harness-status trae --scope project`（读当前目录 `./.trae/mcp.json`）
+- **先分 plan 类型再解读「Agent 记忆」卡**：它仅对**个人版 `agent-plan`** 有意义。**团队版 `agent-plan-team` 与 OpenViking 无关** —— 团队版下该卡 `installed:false`、卡内两台 `absent` 是**预期正确状态**，别据此提示用户去注入 OpenViking（团队版本就不该有这两台）
+- 解读「Agent 记忆」卡时**展开卡内 `mcp_servers` 看两台**：（**个人版**）`openviking-dataplane` 报 `absent` 不一定是"漏装"——账号下没有 OpenViking 库时，注入本就会跳过它；`openviking-controlplane` 报 `absent` 才是真漏装（它始终随个人版 Agent Plan 注入、不依赖 OV 库），说明该 agent 从未跑过 `helper mcp`。**卡级 `installed` 取的就是 controlplane**，所以卡级 `installed:false` ≈ controlplane 漏装
+- Supabase 块只反映本机 `cli_installed`/`skill_installed`；要**配置/重装**它走 [`../../arkcli-helper/SKILL.md`](../../arkcli-helper/SKILL.md) 的 `helper supabase`
+- 这是 plan 视角下"我的能力落地了没"的快速自检；想看 agent 自身装没装（install）+ 模型 / provider 配没配 → [`../../arkcli-helper/SKILL.md`](../../arkcli-helper/SKILL.md) 的 `helper list`
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [arkcli-helper](../../arkcli-helper/SKILL.md) -- **注入 / 配置 / 移除** MCP（本命令只读查看，改动走这里）
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-model-apply.md

@@ -0,0 +1,56 @@
+# plans model-apply
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+设置指定套餐的 **ark-code-latest 路由目标**：`auto`（智能调度，平台自动挑底层模型）或清单中某个具体影子模型。与控制台「选择 ark-code-latest 路由模型」确认按钮调同一批后端接口，改动立即生效、两端同步。写操作。
+
+## 命令
+
+```bash
+# 交互终端：省略 --model 会弹出路由目标选择器（当前生效项带 [当前生效] 标注并默认高亮）
+arkcli plans model-apply --plan agent-plan
+
+# 非交互 / agent：必须显式 --model（model id / output name / auto 均可）
+arkcli plans model-apply --plan agent-plan --model auto
+arkcli plans model-apply --plan coding-plan --model doubao-seed-code
+arkcli plans model-apply --plan coding-plan-team --model doubao-seed-code-251028
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--plan` | 否 | string | `agent-plan` / `coding-plan` / `agent-plan-team` / `coding-plan-team`，默认 `agent-plan-team` |
+| `--model` | 非交互必填 | string | 路由目标：模型 `model_id`、`output_name` 或 `auto`；交互终端可省略进入选择器 |
+
+## 返回值
+
+```json
+{
+  "plan": "agent-plan",
+  "previous_selected_model_id": "doubao-seed-code-251028",
+  "applied": {
+    "model_id": "auto",
+    "output_name": "auto"
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `plan` | 入参回显 |
+| `previous_selected_model_id` | 写入前 ark-code-latest 命中的影子模型 id（未设置时为空） |
+| `applied.model_id` / `applied.output_name` | 本次写入的路由目标；`auto` 时两字段均为 `auto` |
+
+## 注意事项
+
+- **可选项以 [`plans model-list --mode routing`](arkcli-plans-model-list.md) 返回的 `models[]` 为准**；`--model` 传清单外的值会报 `不支持路由目标` 并列出可选项
+- 团队版（`*-team`）作用域是**当前身份的席位**：账号在该套餐下没有有效席位时会报错，需先在控制台开通席位
+- 写入后 CLI 会重读一次清单校验；控制面异步生效期间不一致只打 stderr `warn`、不影响退出码，可用 `plans model-list --mode routing` 复核
+- 该命令只改"路由指向"，不改本机 Agent 配置；本机 Agent 要切模型走 [`../../arkcli-helper/SKILL.md`](../../arkcli-helper/SKILL.md) 的 `helper configure --model`
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans model-list --mode routing`](arkcli-plans-model-list.md) -- 只查询可选路由目标与当前生效项
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-model-list.md

@@ -0,0 +1,119 @@
+# plans model-list
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+列出指定套餐的两类模型：`models` 是 `ark-code-latest` 的路由候选，
+`direct_models` 是可直接写入推理请求或 Agent 配置 `model` 字段的 ModelName。
+两类条目都可包含负载和模型规格。读操作。
+
+清单包含具体模型及控制面的 Auto 路由选项，不能把所有 `output_name` 原样当客户端 Model Name。Coding Plan 的 `auto` 即使同时出现在 `model_id` 和 `output_name`，也只证明它是控制台/`plans model-apply` 的可选目标。客户端要跟随控制台选择（含 Auto），配置 `ark-code-latest`；要直接指定具体模型，则核对当前套餐官方文档并使用支持的具体名称。不能建议客户端填写 `model=auto`，也不因用户只问页面/配置方法而执行 `model-apply`。
+
+以本次 `selected_model_id`/`selected` 标记当前默认模型，不能照抄示例默认值。交付全部清单时保留每项名称与明确的档位限制；只列举部分时说明是示例。
+
+## 命令
+
+```bash
+# 当前身份只持有一个有效套餐时，自动识别该套餐
+arkcli plans model-list
+
+# 看 Agent Plan 个人版模型
+arkcli plans model-list --plan agent-plan
+
+# 看 Coding Plan 团队版模型
+arkcli plans model-list --plan coding-plan-team
+
+# 只查可以直接配置/调用的 ModelName（只请求 VirtualModelID）
+arkcli plans model-list --plan coding-plan --mode direct
+
+# 只查 ark-code-latest 智能路由候选（只请求 LatestModel）
+arkcli plans model-list --plan coding-plan --mode routing
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--plan` | 否 | string | `agent-plan` / `coding-plan` / `agent-plan-team` / `coding-plan-team`；省略时自动识别当前身份唯一持有的有效套餐，持有多个时要求显式指定 |
+| `--mode` | 否 | string | `all` / `direct` / `routing`，默认 `all`；`direct` 只请求直接 ModelName，`routing` 只请求智能路由候选 |
+
+只有 `--plan` 一个业务筛选参数，不接受 `--type` / `--tier` / `--product` / `--edition`。套餐模型目录按 plan 查询，不按购买档位查询；同一家族的档位共享模型目录，价格、配额与其他权益另查 [buy](arkcli-plans-buy.md) 和 [pricing](../../arkcli-pricing/SKILL.md)，不能把“模型列出来了”推导为某个档位已获全部权益。
+
+例如 `arkcli plans model-list --plan coding-plan --type pro` 会报未知 flag；应使用 `arkcli plans model-list --plan coding-plan`。需要 vendor、模态或基础模型版本元信息时，把返回的 `model_id`（不是友好展示名 `model_name`）交给 [models get](../../arkcli-models/references/arkcli-models-get.md)，不要从名字推断。
+
+未传 `--plan` 时，CLI 会查询当前身份实际持有的四类套餐。只有一个有效个人订阅或 Running 团队席位时自动使用其 `Edition + BizInfo`；存在多个有效套餐时不按顺序猜选，而是报出候选并要求重新传 `--plan`。任一套餐状态查询失败时也不会根据不完整结果自动选择。
+
+## 返回值
+
+```json
+{
+  "plan": "agent-plan-team",
+  "edition": "enterprise",
+  "tier": "large",
+  "selected_model_id": "doubao-seed-2-0-pro-260215",
+  "models": [
+    {
+      "model_id": "doubao-seed-2-0-pro-260215",
+      "model_name": "Doubao Seed 2.0 Pro",
+      "output_name": "doubao-seed-2-0-pro",
+      "context_window": 262144,
+      "max_input_tokens": 229376,
+      "max_completion_tokens": 65536,
+      "input_modalities": ["text", "image", "video"],
+      "load": {"status": 1, "level": 2, "score": 0.46, "coverage": 0.92, "updated_at": 1789999999},
+      "selected": true
+    },
+    {
+      "model_id": "doubao-pro-32k-260215",
+      "model_name": "Doubao Pro 32K",
+      "output_name": "doubao-pro-32k"
+    }
+  ],
+  "direct_models": [
+    {
+      "model_name": "doubao-seed-code",
+      "context_window": 262144,
+      "max_input_tokens": 229376,
+      "max_completion_tokens": 65536,
+      "input_modalities": ["text", "image", "video"],
+      "load": {"status": 1, "level": 1}
+    }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `plan` | 入参回显 |
+| `edition` | 请求套餐模型接口使用的版本：个人版 `personal`，团队版 `enterprise` |
+| `tier` | 当前套餐档位，即请求中的 `BizInfo` |
+| `selected_model_id` | 当前路由选择的后端模型 ID；个人版按订阅服务端 `Enabled` 字段判断，团队版从用户席位映射读取；未选择时省略 |
+| `models[]` | `ark-code-latest` 的路由候选；用于 `plans model-apply`，不是直接 ModelName 清单 |
+| `models[].model_id` | 后端路由目标 ID，适合控制面写入 |
+| `models[].model_name` | 面向用户的展示名；不要把它误当成调用 ID |
+| `models[].output_name` | 路由写接口配套的输出名；不要据此推断可直接调用的 ModelName |
+| `models[].selected` | 为 `true` 时表示当前路由选中该项；未选中时因 `omitempty` 可能不出现 |
+| `direct_models[]` | 当前套餐可直接调用的模型清单，来源为 VirtualModelID 接口 |
+| `direct_models[].model_name` | 可直接写入推理请求或 Agent 配置 `model` 字段的准确 ModelName |
+| `*.context_window` | 上下文窗口大小，单位为 token；接口未提供时省略 |
+| `*.max_input_tokens` | 最大输入 token 长度；接口未提供时省略 |
+| `*.max_completion_tokens` | 最大输出 token 长度；接口未提供时省略 |
+| `*.input_modalities` | 支持的输入模态，例如 `text` / `image` / `video`；只有 `text` 时表示纯文本输入 |
+| `*.load` | 服务端负载快照；仅 `status=1` 且 `level=1/2/3` 分别表示低/中/高负载，其余状态不能解释为当前可用负载 |
+
+## 注意事项
+
+- CLI 会先解析目标套餐的当前档位，实际发出的每个模型列表请求都会携带 `Edition` + `BizInfo`；没有有效订阅/Running 席位或档位为空时直接报错，不发送无范围查询。
+- `--mode all` 请求两类模型接口；`--mode direct` 只请求 VirtualModelID，返回空的 `models`；`--mode routing` 只请求 LatestModel，返回空的 `direct_models`。团队版 routing 为标识当前选中项仍可能读取席位信息。
+- 个人版与团队版的 ark-code-latest 当前选择来源不同：
+  - 个人版：服务端按订阅维度返回模型清单 + Enabled flag
+  - 团队版：从用户席位 `ExtraConfig.ArkCodeLatestMappingModelID` 字段读
+- 不要把路由候选与直接 ModelName 混用：切换 `ark-code-latest` 只看 `models[]`；直接配置/调用只看 `direct_models[].model_name`。
+- 模型规格直接来自套餐模型接口的 `ModelCapability`；缺失字段会省略，不能按模型名猜测或用其它目录数据覆盖
+- 数据是订阅期内允许调用的模型，不等同于全局可调用模型；试用模型用 [`../arkcli-models/`](../../arkcli-models/SKILL.md)
+
+## 参考
+
+- [arkcli-plans](../SKILL.md) -- skill 概览
+- [`plans get`](arkcli-plans-get.md) -- 先看自己持有哪些套餐
+- [arkcli-models](../../arkcli-models/SKILL.md) -- 不限于套餐的模型查询
+- [arkcli-shared](../../arkcli-shared/SKILL.md)