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

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

@@ -0,0 +1,147 @@
+# pricing plans
+
+> **前置条件:** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+列出 AgentPlan / CodingPlan 套餐订阅价格(个人版 + 企业版,共 12 档)。`Price` 是后端按当前账号计算的**最终订阅单价(含折扣)**;`OriginalPrice` 是公示原价。
+
+`pricing plans` 与 `pricing models` 是**两类完全独立的命令**:
+- `pricing models` — 按 token 计费(模型按量调用)
+- `pricing plans` — 包月订阅(整体套餐)
+
+## 命令
+
+```bash
+# 列全 12 档套餐(personal 8 + enterprise 4 = 12)
+arkcli pricing plans
+
+# 单档查询
+arkcli pricing plans --plan agent-plan-personal-small
+arkcli pricing plans --plan coding-plan-personal-pro
+
+# 按产品过滤
+arkcli pricing plans --product agent-plan        # 只 AgentPlan,共 8 档
+arkcli pricing plans --product coding-plan       # 只 CodingPlan,共 4 档
+
+# 按版本过滤
+arkcli pricing plans --edition personal          # 只个人版,共 6 档
+arkcli pricing plans --edition enterprise        # 只企业版,共 6 档
+
+# 组合
+arkcli pricing plans --product agent-plan --edition personal   # AgentPlan 个人版 4 档
+```
+
+## Plan ID 全枚举
+
+| Plan ID | 产品 | 版本 | 档位 |
+|---|---|---|---|
+| `agent-plan-personal-small` | AgentPlan | personal | small |
+| `agent-plan-personal-medium` | AgentPlan | personal | medium |
+| `agent-plan-personal-large` | AgentPlan | personal | large |
+| `agent-plan-personal-max` | AgentPlan | personal | max |
+| `agent-plan-enterprise-small` | AgentPlan | enterprise | small |
+| `agent-plan-enterprise-medium` | AgentPlan | enterprise | medium |
+| `agent-plan-enterprise-large` | AgentPlan | enterprise | large |
+| `agent-plan-enterprise-max` | AgentPlan | enterprise | max |
+| `coding-plan-personal-lite` | CodingPlan | personal | lite |
+| `coding-plan-personal-pro` | CodingPlan | personal | pro |
+| `coding-plan-enterprise-lite` | CodingPlan | enterprise | lite |
+| `coding-plan-enterprise-pro` | CodingPlan | enterprise | pro |
+
+`--plan` 接受的就是上面这 12 个 ID(三段式 kebab-case)。错拼时命令会返回结构化错误 + 列出全部合法 ID。
+
+## 输出字段
+
+```json
+{
+  "items": [
+    {
+      "plan_id": "agent-plan-personal-small",
+      "product": "AgentPlan",
+      "edition": "personal",
+      "tier": "small",
+      "price": 40,
+      "original_price": 40,
+      "period": "monthly",
+      "currency": "CNY"
+    },
+    {
+      "plan_id": "agent-plan-enterprise-small",
+      "product": "AgentPlan",
+      "edition": "enterprise",
+      "tier": "small",
+      "price": 0,
+      "original_price": 0,
+      "period": "monthly",
+      "currency": "CNY",
+      "error": "AccessDenied: caller lacks permission"
+    }
+  ]
+}
+```
+
+| 字段 | 含义 |
+|---|---|
+| `plan_id` | 三段式 ID,可用作 `--plan` 入参 |
+| `product` | `AgentPlan` 或 `CodingPlan` |
+| `edition` | `personal` 或 `enterprise` |
+| `tier` | 档位标识,personal/enterprise 共用同套(small/medium/large/max 或 lite/pro) |
+| `price` | 当前账号最终订阅单价(后端结算后) |
+| `original_price` | 公示原价 |
+| `period` | 订阅周期,目前固定 `monthly` |
+| `currency` | 币种,目前固定 `CNY` |
+| `error` | 该行查询失败的原因。**只有该行**填,其它行不影响 |
+
+## 错误隔离机制
+
+后端把"个人版批量"和"企业版批量"分成两个 Action,所以**个人版和企业版的成功 / 失败彼此独立**:
+
+- 你账号没有企业版权限 → 后端返回 `AccessDenied`
+- 现象:6 行 enterprise 的 `error` 字段填错误信息,`price = 0`;6 行 personal 正常返价
+- 命令本身**不报错** —— `arkcli pricing plans` 退出码仍是 0,JSON 输出完整 12 行
+
+这跟火山方舟控制台的 UI 行为一致:UI 也是分 4 个 tab(AgentPlan / Agent 企业版 / Coding Plan / Coding 企业版),每个 tab 独立调询价、独立失败,不会因一个挂了影响另一个。
+
+**Agent 在响应处理时**:
+1. 先看用户问的是哪一档 → 直接读那一行的 `price`
+2. 如果该行 `error` 非空 → 告诉用户"账号没有 X 版权限,联系管理员"
+3. 不要因为某行有 `error` 就否定其他行的价格
+
+## 参数细节
+
+### `--plan <plan-id>`
+精确匹配 12 个 canonical ID 之一。命中 → 只查那一档(只调 1 个 API 即可)。错拼 → 错误信息 + 列出全部合法 ID。
+
+### `--product agent-plan | coding-plan`
+也接受 PascalCase(`AgentPlan` / `CodingPlan`)。其他值 → 返回空 items 数组(不报错,因为已知值集合是封闭的,但不阻塞 agent 链路)。
+
+### `--edition personal | enterprise`
+精确匹配。
+
+### 组合规则
+- 不传任何 flag → 全 12 档
+- `--plan X` 优先级最高(传 plan 时其它 flag 被忽略,因为 plan 本身已经唯一指定产品+版本+档位)
+- `--product` + `--edition` 可叠加(逻辑 AND)
+
+## 与其他命令的对照
+
+- 用户问"DeepSeek 多少钱"、"图生图多少钱"、"做精调多少钱" → [`pricing models`](arkcli-pricing-models.md)
+- 用户问"Agent Plan 多少钱"、"Coding Plan small 多少钱"、"个人版 / 企业版价格" → 本命令
+- 用户问"我**已经**用了多少 / 消耗多少" → [`../arkcli-usage/SKILL.md`](../../arkcli-usage/SKILL.md)
+
+## 调用涉及的后端 Action(供 raw API 排错时参考)
+
+| Action | 用于 |
+|---|---|
+| `EstimateSubscribeNewOrderPrice` | AgentPlan 个人版批量(4 档一次返回) |
+| `EstimateSubscribePrice` | CodingPlan 个人版单条(每档单独调一次) |
+| `EstimateAgentPlanEnterpriseNewOrderPrice` | AgentPlan + CodingPlan 企业版(按 Scene 区分,Agent=`agent_plan_enterprise`,Coding 不传) |
+
+如果 `pricing plans` 失败到完全无响应,可以用 raw API 自检:
+
+```bash
+arkcli api trade.estimate_subscribe_new_order_price --params '{
+  "Items": [
+    {"BizInfo":"small","ResourceType":"AgentPlan","ResourceName":"RealAgentPlanPersonal","Period":"monthly","Times":1}
+  ]
+}'
+```

package/skills/arkcli-profile/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: arkcli-profile
+version: 1.1.4
+description: "arkcli profile 切面管理：列出、查看、新建、切换、删除、重命名 profile；管理 profile 内 API Key 列表；管理五类 profile 的默认资源与持久身份切面。也负责判断 Token 额度包/资源包应继续使用 platform profile 与 `/api/v3`，不能因「套餐」或价格字样误判为 Agent Plan/Coding Plan。临时 API Key/Base URL/Endpoint 调用不写回 profile，按 arkcli-shared 的 execution-context 契约执行。旧 config 子命令已 deprecated。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli profile --help"
+---
+
+# arkcli profile
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证闸门、配置排查与命令选择顺序**
+
+**CRITICAL — 一旦确定走 `profile create`、`profile delete` 或 `profile project`（重选 project 会重命名/重派生 platform profile），必须先复述对 `config.yaml` 的影响并征得用户确认；其他写操作（`use` / `set-default` / `keys use` / `keys refresh` / `models refresh` / `rename`）执行前也要复述目标 profile 名。**
+**CRITICAL — `profile` 是本地身份切面管理，全域不注册 `--dry-run`。`profile show/list/keys list` 会做 best-effort 在线 Key 同步，可能回写本地 Key 库存或默认 Key；只在用户显式要求 Profile 管理时使用，并先说明该影响。其他写操作仍通过明确确认保护。**
+
+## 先区分核对与管理
+
+- 只读核对当前身份、默认资源是否可见或凭证是否兼容，不是 Profile 管理；即使用户提供了 Profile 名称或 type，也先读取 Auth 与 Resources Skill 并交由它们处理。信息缺失不授权进入 `profile show/list/keys list`。
+- 用户明确要管理 Profile、准备运行 `show/list/keys list` 时，先在**调用工具之前的用户可见文本**中说明两项具体影响：尝试在线同步远端 API Key；可能回写本地 Key 库存或默认 Key。例如：“该管理查询会尝试在线同步 API Key，可能回写本地 Key 库存或默认 Key。”
+- “我会先解释”只是计划，不是披露；工具描述、内部思考和执行后的最终答复也不能替代这条前置说明。执行后不得把这些管理查询称为“纯只读”或据此保证“本地 Key 未变化”。
+
+## 使用原则
+
+- profile 是 0.1.16 引入的 **统一身份切面**，把 `(type × region × project × owner_trn × api_keys)` 五个属性绑成一组
+- profile 写操作（create / use / set-default / keys / models / delete / rename）一律走 `arkcli profile <verb>`；旧的 `arkcli config init/list/show/switch/delete` 已 deprecated，不要再引导用户用
+- 普通身份准入使用 `arkcli auth status` / `arkcli auth whoami`，默认资源与路由检查使用 `arkcli resources list`；不要为业务准入自动进入 Profile 管理
+- 用户明确要查看或管理 Profile 时才运行 `profile show/list/keys list`，执行前先说明它们可能在线同步并回写 Key；脱敏 stdout 不代表本地配置无副作用
+- ProfileType 五种：`platform` / `agent-plan` / `agent-plan-team` / `coding-plan` / `coding-plan-team`；其 text/image/video 所需的数据面、凭证与资源不同
+- 用户只想临时传 API Key / Base URL / Endpoint 时，不要创建、切换或修改 profile；先读 [`../arkcli-shared/references/execution-context.md`](../arkcli-shared/references/execution-context.md)
+
+## 适用场景
+
+- 用户问"我有哪些 profile / 当前 profile 是哪个 / 切换 profile"
+- 用户要创建新 profile（platform，或 Agent/Coding Plan 的个人版/团队版）
+- 用户问 default 模型 / 资源是什么、想换 default
+- 用户的 API Key 列表过期、新 key 还没被拉进来，需要 refresh
+- 业务命令 `+chat / +gen / resources list` 报错"profile xxx 缺 ..."，转回这里排查
+
+## 反唤起信号
+
+- 用户问鉴权 / 401 / SSO 失败 → 转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md)
+- 用户问 base URL / region / API Key 优先级被覆盖 → 转 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md)（config 现在专门讲解析归因 + reset）
+- 用户问"有哪些 endpoint / 模型可用" → 转 [`../arkcli-resources/SKILL.md`](../arkcli-resources/SKILL.md)
+- 用户问"我要找一个模型" / "哪个模型最强" → 转 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md)
+
+## 切换 profile 的硬状态机
+
+1. 执行 `profile use` 前必须先跑一次 `arkcli profile list --format json`；只有本轮已有完整、未截断的同源列表时可复用，不凭记忆认定目标存在。
+2. `profile list` 的结构化 stdout 是本地 profile 的唯一事实源；列表为空就报告未配置并停止，不再搜索文件系统、读取状态目录或猜测配置文件。用户给了精确名称时只做精确匹配；名称不存在就如实说明，并只从列表真实结果提供可用 profile。不得把该名称重解释为 project / region，也不得自动 `project` / `create` / `rename`。
+3. 用户只给了 type、用途或模糊描述时，只用列表里的 `name / type / region / project` 等权威字段筛选，然后严格按 [`arkcli-shared`](../arkcli-shared/SKILL.md) 的 0 / 1 / N 候选规则消歧；用户选定前不执行写操作。
+4. 目标唯一且用户意图明确后才执行 `arkcli profile use <name>`，随后必须跑 `arkcli profile show --format json` 验证实际 active profile。
+5. 只有核验结果与目标一致才声称切换成功；报告 `name / type / region / project / base_url` 这些生效切面，不把 `profile use` 的 exit=0 当成最终证据。
+
+## 切换默认资源的硬状态机
+
+1. 用户没给具体资源 ID 时，先确定 modality，再只跑一次 `arkcli resources list --modality <m> --format json` 取得当前或 `--profile` 指定切面的完整候选。
+2. 候选只能来自这次真实结果，按 [`arkcli-shared`](../arkcli-shared/SKILL.md) 的 0 / 1 / N 规则处理：多候选优先调用宿主的结构化选择能力，通用 Skill 不写死工具名。
+3. 执行前复述目标 profile、modality 和精确 ID；使用 `arkcli profile set-default --modality <m> <id>` 的默认 inline verify。除非用户明确要求并接受跳过校验的风险，不得自行添加 `--skip-verify`。
+4. 写入后必须跑 `arkcli profile show --format json` 或 `arkcli resources list --modality <m> --format json` 核验新 default；只有结构化结果与目标 ID 一致才声称切换成功。
+
+## --profile flag 的精确语义（0.1.16 修正）
+
+```
+优先级:  --profile flag > ARK_PROFILE env > config.yaml default_profile
+         > 第一个 type=platform 的 profile > "default" sentinel
+```
+
+**关键修正（codex P0-A）**：在 `resources list / profile apikey refresh / profile set-default / profile models refresh` 这些命令上，`--profile` 不再只是改 target 对象名，而是真的切换执行身份 —— 内部用 `Factory.RebuildForProfile(name)` 重建 invoker，所以 `arkcli profile apikey refresh --profile B` 会用 B 的 token / UserID 打控制面，而不是 active=A 的身份打完再写到 B。
+
+Agent 行为约定：
+- 用户跑 `--profile B` 之类的子命令时，**不要假设它跟 active profile 等价**；告诉用户"将以 B 的身份操作"
+- 0.1.16 final clean-slate 模型: 整 arkcli 同一时间只 active 一个 identity. 新 SSO 完成时 `sso.ActivateIdentity` 检测 newKey vs `cfg.DefaultProfile.IdentityKey`: 一致 (alice 重登 alice) → 不动 yaml profile / `--profile B` 用于同 identity 内跨 type 的临时切换; 不一致 (跨 sub / 跨 tenant) → 全清 yaml/.env/identities 三层重建 (BuildFirstProfileSet 火山多 type 派生)
+
+## Agent 快速执行顺序
+
+1. 普通业务只需当前身份/Profile 摘要 → `arkcli auth whoami --format json`；不要调用 Profile 管理命令补齐普通准入
+2. 用户明确要查看 active profile 或本地 Profile 清单 → 先说明 Key 同步/回写影响，再用 `arkcli profile show --format json` 或 `arkcli profile list --format json`
+3. 用户要切默认 profile → 按上面的硬状态机先 `profile list`，精确定位后 `profile use <name>`，再 `profile show`
+4. 用户要新建 profile：先按下面决策树确认五类 type，读 [create reference](references/arkcli-profile-create.md) 后执行；只有用户明确要求同时切默认时才带 `--set-default`
+5. 用户问 default 模型是什么 → plan 类用 `arkcli profile models list`，platform 用 `arkcli profile show` 看 `resources` 字段
+6. 用户要换 default 资源 → 按上面的硬状态机取真实候选、消歧、`profile set-default`，再只读核验
+7. 用户的 default API Key 报错 / key 列表过期 → `arkcli profile apikey refresh`，然后 `arkcli profile apikey list --format json` 看新清单。refresh 按 profile 类型取对应池：普通池、Agent Plan 个人版专属池或团队席位 Key；空结果会报错并保留本地 Key，不会成功清空。
+8. 用户要选别的 key 作 default → `arkcli profile apikey use <api-key>`（必须 ∈ `profile.available_api_keys`）
+9. 用户要换 active project（不重登）→ `arkcli profile project`（无参拉真实 ListProjects 交互选；先复述「会把 platform profile 重命名/重派生到新 project，个人版 plan profile 保留」并确认）
+
+## Token 额度包 / 资源包的 profile 归属
+
+「19 元 Token 额度包」、「Token 资源包」、「预付费 Token 抵扣包」等产品仍属于标准 platform 按量调用的计费产品，不是 Agent Plan 或 Coding Plan 订阅身份：
+
+- 应沿用 `type=platform` 的 profile，数据面使用 platform `/api/v3`。
+- 价格、「额度包 / 套餐」市场名称、Token 数量都不是 ProfileType 判据；只有明确的 Agent Plan / Coding Plan 订阅或团队席位才使用对应 plan profile。
+- 用户只问「它属于哪类 profile」时直接解释分类，禁止自动执行 `profile create` / `profile use` / `profile set-default`。
+- 用户要实际使用时，先用 `arkcli auth whoami --format json` 核对当前持久 Profile 摘要；需要查看 Profile 详情或修改时，再按本 skill 的同步披露与写操作确认契约执行。
+
+## 命令一览
+
+| 命令 | 说明 | 改动来源 |
+|------|------|---------|
+| `arkcli profile list` | 列出所有 profile（含 type/region/project 切面） | 替代 `config list` |
+| `arkcli profile show [name]` | 显示当前/指定 profile 详细信息 | 替代 `config show` |
+| `arkcli profile use [name]` | 切换默认 profile（无参时交互选择） | 替代 `config switch` |
+| `arkcli profile create --type ...` | 新建 profile（interactive 或 inline） | 替代 `config init`（type 改为必选） |
+| `arkcli profile delete <name>` | 删除 profile（必须 `--yes` 才能跳确认） | 替代 `config delete` |
+| `arkcli profile rename <old> --to <new>` | 重命名 profile（校验格式 + 唯一性） | 0.1.16 新增 |
+| `arkcli profile project [<name>]` | 重选 active project（无参拉真实 ListProjects 交互选，列表置顶「账号全部资源」=不传 ProjectName/account-wide）；把 platform profile 重派生到新 project，个人版 plan profile 原样保留；不重登 | 0.1.17 新增 |
+| `arkcli profile apikey list` | 列 default + available API Keys（masked） | 0.1.16 新增 |
+| `arkcli profile apikey use <key>` | 切 default API Key（key 必须 ∈ available list） | 0.1.16 新增 |
+| `arkcli profile apikey refresh` | 按 profile 类型重拉普通池 / Agent Plan 专属池 / 团队席位 Key，非空时更新 available list | 0.1.16 新增 |
+| `arkcli profile models list` | plan 类 profile 的 PlanTier + Resources defaults | 0.1.16 新增 |
+| `arkcli profile models refresh` | 按目标 Plan 类型及 profile 的 Edition + PlanTier 重拉 VirtualModelID 直接模型清单，更新 Text.Default；会写配置 | 0.1.16 新增 |
+| `arkcli profile set-default --modality <m> <id>` | 设某 modality 的 default 资源 ID | 0.1.16 新增 |
+
+## ProfileType 选型速查
+
+### 命令适用范围与空值
+
+- `profile models list/refresh` 支持四类 Plan（Agent/Coding，个人/团队），不支持 platform；它不是公共模型目录或账号自定义模型列表。本表仅描述当前产品，不推导其他产品的身份契约。
+- `resources list` / `set-default` 依各 type × modality 的实际资源类型工作：platform 使用 Endpoint；Agent Plan 使用套餐模型；Coding Plan 图像/视频进入 platform lane。不要把一次文本配置推广到全部模态。
+- `current_default` 或某 modality 的 default 为空表示“未设置”，不是第一条候选、目录 primary version 或推荐项；不得把展示/排序顺序当成默认值。
+- 本地 Key 清单的掩码不是真实可调用 Key；查询元数据、导出凭证、刷新库存、轮转和切默认是不同动作。未要求更改时不能自动 use/refresh/rotate。
+- 图像理解失败先核对输入模态、API 支持和客户端输入能力；`output_modalities=text` 不代表不支持读图，Plan 别名也不能只凭无版本后缀判无效。
+- 批量推理权限与 Profile 切换不是同一个问题；先保留实际错误并核对模型/能力开通及权限，不把 account-wide 下的拒绝先归因为 Project，也不自动扩权或切身份。
+
+| type | 适用 | 数据面 base URL | 控制面 | 视觉模型 (image/video) |
+|------|------|----------------|--------|----------------------|
+| `platform` | 火山方舟 console 的标准用法 | `/api/v3` | OpenTOP | ✓ 默认 endpoint |
+| `agent-plan` | 火山方舟 Agent Plan 订阅（个人版） | `/api/plan/v3` | OpenTOP + Plan API | ✓ tier 目录按 `OutputModalities` 动态过滤 |
+| `coding-plan` | 火山方舟 Coding Plan 订阅（个人版） | `/api/coding/v3` | OpenTOP + CodingPlan API | text: 套餐内文本模型；image/video: 借道 platform 数据面 + 用户 +deploy 的 endpoint id (S10, commit f69be53) |
+| `agent-plan-team` | Agent Plan 团队席位 | `/api/plan/v3` | OpenTOP + Plan API | text/image/video 都用套餐模型 + 团队席位 Key |
+| `coding-plan-team` | Coding Plan 团队席位 | `/api/coding/v3` | OpenTOP + CodingPlan API | text 用套餐模型 + 团队席位 Key；image/video 用 platform Endpoint + 后付费 API Key |
+
+> Coding Plan 个人版的 text lane 使用后付费 API Key；Coding Plan Team 只有 text
+> lane 使用团队席位 Key。完整矩阵见
+> [`../arkcli-shared/references/execution-context.md`](../arkcli-shared/references/execution-context.md)。
+
+`--plan-tier` 手动声明仅适用于个人版；团队版档位与 Key 来自真实 Running 席位，不能用此 flag 绕过席位校验：
+- agent-plan：`small` / `medium` / `large` / `max`
+- coding-plan：`lite` / `pro`
+
+## profile create 决策树
+
+```
+用户明确要求创建 Profile
+  |
+  +-- 标准按量 / Token 资源包 -----------------> platform
+  |
+  +-- 明确 Agent Plan
+  |     +-- 个人订阅 -------------------------> agent-plan
+  |     `-- 团队席位 -------------------------> agent-plan-team
+  |
+  +-- 明确 Coding Plan
+  |     +-- 个人订阅 -------------------------> coding-plan
+  |     `-- 团队席位 -------------------------> coding-plan-team
+  |
+  `-- 只说 "买了 plan" / 家族或个人团队不明 ---> 只澄清缺少的决策，不默认个人版
+```
+
+个人版由订阅 Detect 得到档位；用户明确确认实际个人档位且遇到可见性问题时才考虑 `--plan-tier`，它不证明订阅有效或有调用权限。团队版必须由当前绑定身份查到 Running 席位；失败时说明缺少的席位/权限，不改成个人版或拿普通 API Key 顶替。Vaka 的身份和授权由 shared 约束，不用创建/切换 Profile 修复宿主凭证错误。
+
+## 常见错误
+
+- `set-default: <id> 不在当前 profile (... ) 可用列表` → 用 `arkcli resources list --modality <m>` 核对可用 ID；不得自行用 `--skip-verify` 强写
+- `models list/refresh` 的类型不支持错误 → 核对目标是否属于当前产品支持的 Plan type；Volc 支持四类 Plan，不支持 platform。不要为消除报错擅自切 profile
+- S10 之后, coding-plan profile 下 `profile set-default --modality image|video <ep>` 不再 fail-fast: verify 会借道 platform 控制面 ListEndpoints 校验 ep-id 是否存在
+- `keys refresh: fetch api keys: NotLogin` → 控制面鉴权失败 (如登录态/STS 过期)；fetcher 会用 `.env` 缓存单 key 兜底，profile.available_api_keys 仅含 1 项，恢复后再 refresh
+- `keys refresh` 报没有可用 Key → 先按 profile type 判断：`platform` / `coding-plan` 个人版去普通 API Key 管理页；`agent-plan` 个人版去 Agent Plan 使用配置页检查专属 Key；团队版检查 Running 席位。不得把所有类型都引向普通 API Key 页面。
+- `arkcli auth apikey` 只操作普通 API Key 池；它返回 `saved=true` 也不表示 Agent Plan 专属 Key 或团队席位 Key 已恢复。
+- 切账号后 keys / models refresh 行为奇怪 → 检查 `arkcli auth whoami`，可能 active profile 仍绑旧 identity；P0-D 之后 STS / token 都在 per-identity store，但 active profile.identity_key 是 yaml 字段，跨账号要么 `profile use <new>`，要么走 SSO Gate 2 自动新建
+
+## deprecated 命令自然语言重定向表
+
+| 用户提到 | 实际执行 |
+|---|---|
+| "config init / 新建配置 / 初始化配置 / 新建 profile" | `arkcli profile create --type ...` |
+| "config list / 看看有几个 profile / 列出 profile" | `arkcli profile list` |
+| "config show / 看下我的配置 / 显示 profile" | `arkcli profile show` |
+| "config switch / 切配置 / 切换 profile / 换 profile" | `arkcli profile use [name]` |
+| "config reset / 全清掉 / 恢复出厂设置 / 配置乱了从头来 / 清空所有配置" | **转 `arkcli-config`**：`arkcli config reset`（破坏性操作，必须先确认） |
+| "我 agent-plan 下面有哪些可用模型 / 有哪些模型 / 模型列表" | `arkcli profile models list`（plan 类 profile）或 `arkcli resources list` |
+
+## 参考
+
+- [`references/arkcli-profile-create.md`](references/arkcli-profile-create.md)
+- [`references/arkcli-profile-keys.md`](references/arkcli-profile-keys.md)
+- [`references/arkcli-profile-set-default.md`](references/arkcli-profile-set-default.md)
+- [`../arkcli-shared/references/execution-context.md`](../arkcli-shared/references/execution-context.md) — 五类 Profile 的调用矩阵与临时覆盖

package/skills/arkcli-profile/references/arkcli-profile-create.md

@@ -0,0 +1,101 @@
+# profile create 详细参考
+
+> **前置**：先读 [`../SKILL.md`](../SKILL.md)。本文件只补 flag 细节、输出形态、错误码。
+
+## 命令模板
+
+```bash
+# Platform 类（最常用，默认 region=cn-beijing / project=default）
+arkcli profile create --type platform --set-default
+
+# 显式 region + project
+arkcli profile create --type platform --region cn-beijing --project myproject --set-default
+
+# Agent Plan：自动 Detect 订阅状态
+arkcli profile create --type agent-plan --set-default
+
+# Agent Plan：强制 plan-tier（绕过 OpenTOP 后端可见性 bug）
+arkcli profile create --type agent-plan --plan-tier medium --set-default
+
+# Coding Plan
+arkcli profile create --type coding-plan --plan-tier lite --set-default
+
+# 团队版：当前身份必须已绑定对应的 Running 席位；不手填档位或普通池 Key
+arkcli profile create --type agent-plan-team --no-interactive
+arkcli profile create --type coding-plan-team --no-interactive
+
+# 完全 inline（CI 友好，所有必填字段都给）
+arkcli profile create \
+  --type platform \
+  --region cn-beijing \
+  --project default \
+  --owner-trn "trn:iam::21xxxxxxx:user/myname" \
+  --no-interactive \
+  --set-default
+```
+
+## Flag 一览
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--type` | 是（除非 interactive） | `platform` / `agent-plan` / `coding-plan` / `agent-plan-team` / `coding-plan-team` |
+| `--region` | 否 | 默认 `cn-beijing` |
+| `--project` | 否 | 默认 `default`；0.1.16 起 Project 进 profile 切面 |
+| `--name` | 否 | 默认 `{type}_{region}_{project}` 派生；显式传跳过派生 |
+| `--default-api-key` | 否 | 显式指定绑定的 default API Key；默认按 type 取普通池、Agent Plan 专属池或团队席位 Key，不可跨池替代 |
+| `--owner-trn` | 否 | 火山 IAM trn；通常留空（SSO 登录场景下由 `sso.Switch` 从 IDToken `claims.Trn` 直接写入；0.1.16 起不再走 self-heal 回填） |
+| `--plan-tier` | 否 | **仅个人版手动声明**：agent-plan 取 `small`/`medium`/`large`/`max`，coding-plan 取 `lite`/`pro`；跳过个人订阅 Detect，不绕过权限/协议/余额。团队版仍查询真实席位，并以其档位为准 |
+| `--set-default` | 否 | 创建后立即设为 default profile |
+| `--no-interactive` | 否 | 缺必填字段直接报错，不进入交互；不是跳过远端资格校验 |
+
+这些是创建配置的写命令，不是查订阅的探针。先确认创建目标和影响；`--set-default` 仅在用户要求创建后同时切换时使用，不能因为示例带了就自动添加。
+
+## 输出形态
+
+```json
+{
+  "created": "platform_cn-beijing_default",
+  "type": "platform",
+  "region": "cn-beijing",
+  "project": "default",
+  "is_default": true,
+  "api_key_count": 3
+}
+```
+
+`api_key_count` 是 fetcher 拉到的 active 全 list 长度；写到 `profile.available_api_keys`。0 表示控制面没拉到 key（NotLogin / 权限不足），fetcher 会用 `.env` 缓存单 key 兜底，并打 stderr warn。
+
+## 个人版 Detect 与团队版席位校验
+
+Agent Plan / Coding Plan **个人版**创建时会先调 `ListSubscribeTrade` 确认订阅状态：
+
+```
+Agent Plan 订阅已回收, 请前往 console 续费:
+  https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement
+  如已购买但 Detect 看不到, 加 --plan-tier=<small|medium|large|max> 绕过 (后端可见性问题)
+```
+
+控制台可见但 Detect 返回空可能是可见性问题，也可能是身份/范围不同，不能仅凭空列表断言后端 bug。只有用户明确确认实际个人档位和手动声明意图时才用 `--plan-tier=<tier>`；创建成功仍不证明数据面可调用。
+
+团队版独立处理：
+
+| type | 检测与凭证 | 文本模型清单 |
+| --- | --- | --- |
+| `agent-plan-team` | `GetSeatInfo` 的 Agent Plan 企业 Scene；真实 `SeatID`、Running 状态、`BizInfo` 与席位 Key | Agent Plan 清单 |
+| `coding-plan-team` | `GetSeatInfo` 的 Coding Plan Scene；同样要求当前身份的 Running 席位 | Coding Plan 清单，需要当前 AccountID |
+
+- 缺席位、非 Running、身份不符或接口错误时停止；“团队已购买”不等于“当前子用户已绑定席位”。需要分配席位时转 Plans，并另行确认具体目标。
+- `--plan-tier` 不能制造席位、绕过 `GetSeatInfo` 或恢复已过期席位；不要改成个人版、普通池 Key 或另一个账号重试。
+- 团队 Key 来自该席位，不能把 `auth apikey` 成功或普通池非空当团队凭证已就绪；反馈只报脱敏信息。
+
+## 跟旧 `config init` 的差异
+
+| 维度 | 旧 `config init` | 新 `profile create` |
+|------|------------------|---------------------|
+| `--type` | 没有此 flag，profile = (region × project) | 明确区分 platform 与四类 Plan（个人/团队） |
+| `--plan-tier` | 不存在 | 个人 Plan 可手动声明；团队版仍以真实 Running 席位为准 |
+| `--owner-trn` | 不存在；trn 不绑 profile | 新增，profile schema v1 切面字段 |
+| API Key 拉取 | 单 key（用户传的 `--api-key`） | 全 list fetch + masking + 选 default |
+| Project 字段 | 仅 `.env` `VOLCENGINE_ARK_PROJECT_NAME` | 进 profile 切面，`.env` 仅兜底 |
+
+老脚本里 `arkcli config init ...` 仍然能跑（标 deprecated，0.2.x 删除），但 Agent 不应再引导用户用。

package/skills/arkcli-profile/references/arkcli-profile-keys.md

@@ -0,0 +1,100 @@
+# profile apikey 详细参考
+
+> **前置**：先读 [`../SKILL.md`](../SKILL.md)。
+
+`profile apikey` 是 0.1.16 引入的 API Key 管理子树，跟 `arkcli auth apikey`（只交互选择普通池 Key）**不是同一个东西**：
+
+- `profile apikey list/use/refresh` 操作的是 **profile.yaml 里的 available_api_keys 列表 + default_api_key 选择**
+- `arkcli auth apikey` 操作的是 **普通 API Key 池**，并写入 `.env` 的 `VOLCENGINE_ARK_API_KEY`（identity-level 兼容凭证）；它不读取或修复 Agent Plan 专属 Key，也不读取团队席位 Key
+
+## 命令模板
+
+```bash
+# 列当前 profile 的 default + available_api_keys（masked）
+arkcli profile apikey list --format json
+arkcli profile apikey list --profile platform_cn-beijing_default --format json
+
+# 切 default key（必须 ∈ available list）
+arkcli profile apikey use 392xxxxdab0
+
+# 按 profile 类型重拉对应 Key 来源 → 更新 available list（写 profile.yaml）
+arkcli profile apikey refresh
+arkcli profile apikey refresh --profile platform_cn-beijing_default
+```
+
+## `keys refresh` 关键行为
+
+1. **用 target profile 的身份打控制面**（codex P0-A 修正）
+   - `--profile X` 时内部 `Factory.RebuildForProfile(X)` 重建 invoker
+   - 不会再用 active=A 的 token 打控制面后写到 B
+2. **按 profile 类型选择 Key 来源，禁止串池**
+   - `platform` / `coding-plan` 个人版：普通 `ListApiKeys` → `GetRawApiKey`
+   - `agent-plan` 个人版：`ListApiKeys(Filter.Scene="RealAgentPlanPersonal")` → `GetRawApiKey`
+   - `agent-plan-team` / `coding-plan-team`：`GetSeatInfo.Result.ApiKey`，要求 Running 席位
+3. **List 返回 mask，profile 必须落 full plaintext**（codex P1-B 修正）
+   - `ListApiKeys` 返回的 `Items[].Key` 是 mask 字符串（`392****dab0`）
+   - 直接写到 `available_api_keys` 会让数据面 SDK 拿 mask 当 Bearer → server 报 `API key format is incorrect`
+   - 普通池和 Agent Plan 个人版池都要对 Active item 调 `GetRawApiKey` 拿真实 Key
+4. **空结果 fail closed**
+   - 对应来源返回零把可用 Key 时，refresh 报类型专属错误，并保留已有 `available_api_keys` / `default_api_key`
+   - 不得把空结果当成功同步，更不能清空本地 Key
+5. **graceful fallback**：控制面拉 key 失败 (登录态/STS 过期、上游临时不可用) → 用 `.env` 缓存单 key 兜底
+   - stderr 打 warn：`控制面拉 API Key 列表失败 (NotLogin), 用 .env 缓存单 key 兜底`
+   - `profile.available_api_keys` 仅含 1 项，恢复后再 refresh
+
+## `keys refresh` 的防御用途（后端 key 变更 → 自愈）
+
+refresh 本质是「**以后端为 SSOT、单向把当前 profile 的 key 同步下来**」，所以它是「**后端 key 被改 / 轮换 → 本地 profile.yaml 变旧 → 业务命令报鉴权错**」这类故障的**第一线自愈动作**：比 `auth login` 重登、`auth apikey` 交互重选都轻，一条非交互命令即可，适合 agent 自动自愈（agent 完整恢复流程见 [`../../arkcli-auth/references/auth-modes.md`](../../arkcli-auth/references/auth-modes.md) 的「API Key 错误恢复」playbook）。
+
+**但 refresh 不是万能 —— 它能/不能自愈什么：**
+
+| 症状 | refresh 能否自愈 | 正确动作 |
+|---|---|---|
+| `InvalidApiKey` / `Unauthorized` / `AuthenticationError`（key 旧 / 被轮换，且没主动换过 key） | ✅ 能（后端有有效 key 可拉） | `keys refresh` → 重试原命令 |
+| key 来自 `ARK_API_KEY` env / `--api-key` flag | ❌ 不能（覆盖优先级高于 profile.yaml，refresh 写盘不生效） | 先去掉覆盖，再 refresh |
+| `AccessDenied` 针对某资源（key 缺权限） | ❌ 不能（同账号同权限，refresh 后还是同样被拒） | console 给 key 加权限 / 建带权限新 key |
+| SSO / 身份过期（refresh 自己的控制面调用也 401） | ❌ 不能 | `arkcli auth login volc-sso` 重登 |
+| Agent Plan 个人版专属记录非 Active（如 `Restricted`） | ❌ refresh 只读，不主动轮转 | TTY 登录/Helper 可在确认后轮转一次并最多读 3 次；或去 Agent Plan 使用配置页手动更新 |
+| 对应来源返回零把可用 Key | ❌ 不能；命令报错且保留本地 Key | 按 profile 类型去普通 Key 页面、Agent Plan 使用配置页或团队席位页处理 |
+| team 档无 Running 席位 | ❌ 不能（refresh 直接报错） | 查席位 / 套餐（`arkcli-plans`） |
+
+**refresh ≠ rotate**：refresh 同步「已被改的」key，本身不会触发轮转；主动「换一把 / 废弃泄露的 key」走 `arkcli plans personal|team rotate-apikey`。Agent Plan 个人版的交互式登录/Helper 只在专属记录存在但非 Active 时提供一次经确认的恢复轮转，并最多读 3 次状态。**单 profile 范围**：只治当前 / `--profile` 那条，不影响其它 profile。
+
+## 输出形态
+
+### `keys list`
+
+```json
+{
+  "profile": "platform_cn-beijing_default",
+  "default_api_key": "392****dab0",
+  "available_api_keys": ["392****dab0", "abc****1234", "..."]
+}
+```
+
+### `keys use`
+
+```json
+{
+  "profile": "platform_cn-beijing_default",
+  "new_default": "abc****1234"
+}
+```
+
+### `keys refresh`
+
+```json
+{
+  "profile": "platform_cn-beijing_default",
+  "default_api_key": "392****dab0",
+  "available_api_keys": ["...", "..."],
+  "added_count": 2,
+  "removed_count": 0,
+  "refresh_status": "ok"
+}
+```
+
+stderr 同步打：
+```
+[arkcli] profile "platform_cn-beijing_default" keys refreshed: +2 -0 (total 5)
+```

package/skills/arkcli-profile/references/arkcli-profile-set-default.md

@@ -0,0 +1,81 @@
+# profile set-default 详细参考
+
+> **前置**：先读 [`../SKILL.md`](../SKILL.md)。
+
+`profile set-default` 显式表达"在某 modality 下用什么资源作 default"的偏好，写到 `profile.yaml` 的 `Resources.<modality>.Default`。`+chat` / `+gen` 命令在 `--model` 缺省时按这里 fallback。
+
+## 命令模板
+
+```bash
+# 设 text default（chat 用）
+arkcli profile set-default --modality text doubao-seed-2-0-pro-260215
+
+# 设 image default（gen --modality image 用）
+arkcli profile set-default --modality image doubao-seedream-5.0-flash
+
+# 设 video default（gen --modality video 用）
+arkcli profile set-default --modality video doubao-seedance-2.0
+
+# 显式指定 profile（多账号场景）
+arkcli profile set-default --profile platform_cn-beijing_default ep-xxx
+
+# 跳过 inline verify（控制面暂不可达但 id 已知有效）
+arkcli profile set-default --modality text --skip-verify doubao-seed-2-0-pro-260215
+```
+
+## 关键 inline verify 行为
+
+默认情况下 set-default 会先调控制面校验 `<id>` 在当前 profile 的可用列表里：
+
+| profile.Type | 校验来源 |
+|--------------|---------|
+| `platform` | `ListEndpoints` (PageAll) + modality filter — endpoint 自带 modality 必须跟 `--modality` 匹配, text endpoint 不能写到 image/video default. unknown modality (custom endpoint) 放行避免错杀 |
+| `agent-plan` / `agent-plan-team` | 统一调用 `ListAgentPlanVirtualModelID`（携带对应 `Edition` + `BizInfo=PlanTier`），再按 `ModelCapability.OutputModalities` 过滤 text/image/video；个人/团队使用各自匹配的凭证，不混用 |
+| `coding-plan` / `coding-plan-team` | text: `ListCodingPlanVirtualModelID`（携带对应 `Edition` + `BizInfo=PlanTier`）<br>image/video: 借道 platform `ListEndpoints` + modality filter；团队席位 Key 不能据此当作视觉后付费 Key |
+
+**校验用 target profile 的身份**（codex P0-A 修正）：`--profile X` 时通过 `rt.RebuildFactoryForProfile(X)` 重建 invoker，避免 active=A 的 ListEndpoints 结果被当成 B 的可选范围。
+
+校验通过只证明目标 ID 在该 Profile/模态的候选中，不证明实际 Key、权益或余额可用；`--skip-verify` 仅跳过候选校验，不是权限兜底，不能自动添加。Plan 的合法调用别名保持原样，不把能力查询得到的基础模型 Name/Version 强制覆盖为默认调用 ID。
+
+## 跟 `+chat / +gen` 的衔接
+
+```
++chat / +gen --model 未传:
+  ↓
+  resolveModelDefault(active profile name)  ← P0-B: 按 active profile 解析, 不是 DefaultProfile
+  ↓
+  读 profile.Resources.<modality>.Default
+  ↓
+  S9 runtime alias: plan 类 + text + default=="auto" → 替换为 "ark-code-latest"
+  ↓
+  发数据面请求
+```
+
+如果 `Resources.<modality>.Default` 为空，会报：
+```
+--model 未传, profile "platform_cn-beijing_default" text default 也未设.
+  请显式 --model <id>, 或先跑
+    arkcli resources list --modality text              # 看可用 ID
+    arkcli profile set-default --modality text <id>    # 设默认
+```
+
+Agent 看到此 hint 时，先只读列候选；用户明确要持久设置并选定目标后才运行写命令，不因 hint 自动把第一条设为默认。用户仅要本次调用时，使用明确的 `--model`，不修改 default。
+
+## 输出形态
+
+stdout：
+```json
+{
+  "profile": "platform_cn-beijing_default",
+  "modality": "text",
+  "new_default": "doubao-seed-2-0-pro-260215",
+  "verified": true
+}
+```
+
+stderr：
+```
+[arkcli] profile "platform_cn-beijing_default" text default 已设为 "doubao-seed-2-0-pro-260215"
+```
+
+`verified=false` 表示加了 `--skip-verify`。

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

@@ -0,0 +1,5 @@
+# Profile 读取与管理回归
+
+- 用户给定 Profile type，只读核对身份/默认资源兼容性：转 Auth 与 Resources；资源为空时说明缺口，不调用可能回写 Key 的 profile show/list/keys list。
+- 用户明确管理 Profile 并要求先说明同步影响再列举：首个管理命令前的可见文本必须实际说明在线 Key 同步和本地库存/default 回写风险；只说“稍后解释”或最终答复补写均失败。
+- 管理查询完成：不得称为纯只读，或在未核对实际副作用时保证本地 Key 未变化。