@volcengine/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.46bd0d6dcc58

package/skills/arkcli-agent/references/vision-agent.md

@@ -0,0 +1,92 @@
+# Vision / Ultra Agent（火山）
+
+## 先确定创建类型
+
+- 用户只说“创建一个会生图的 Agent”：这描述的是工具能力，不自动指定 Vision。可按 [普通 Agent 的工具模型绑定](agent.md#工具绑定模型仅部分工具支持)配置；普通 Agent 使用多模态工具同样可能受服务端开白约束。
+- 用户明确要求 Vision / Ultra / 视觉创作类型：使用 `BaseAgent: ultra_vision_agent_preview`。旧值 `multimodal_agent_preview` 仍可读取、复制，不主动迁移已有资源。普通类型是 `ark_agent_preview`，省略类型由后端按普通 Agent 处理。
+- 召回文档中的 Vision 示例不能覆盖用户意图。类型选择会影响结果且上下文无法确定时，先澄清一次。
+- 本页只针对火山；不据此宣称其他产品支持 Vision。
+
+## 主模型、工具模型与权限
+
+`Model.Id` 是 Agent 主模型；`Tools[].Configs[].Models[].ID` 是生图/视频工具模型，不能混用。
+
+Vision 主模型用 `arkcli agent model list --usage vision --format json` 查询，与火山前端读取同一份视觉创作配置；`--env stg` 读取 stg 配置，不回退线上。返回 `items[].model` 是完整模型 ID，`default` 是配置原始标记，`default_model` 是按前端规则选出的默认 ID（第一个标记项，否则第一项）。配置顺序和版本白名单保持不变，缺少名称或版本的项会被跳过，完整 ID 忽略大小写去重。
+
+可用 `--name` 按完整 ID 或展示名筛选；`default_model` 始终指向原目录的默认项，筛选后可能不在 items 中。Vision 查询每次读取当前配置，不使用 ArkModels 缓存；`--refresh-cache` 不改变这一行为。不支持 `--query`、`--primary-only`、`--include-all`，这些 ArkModels 选项不能用于扩大或缩小视觉版本白名单。查询失败不能当作无候选，也不回退普通模型列表；空目录应说明当前环境未配置候选。
+
+目录候选不等于账号已开白或模型已开通。用户提供明确主模型 ID 时保留并交由服务端校验，不增加创建前的强制白名单拦截；没有 ID 时从查询结果选择，不硬编码示例模型，不反复查源码寻找候选。BytePlus 不支持此查询。
+
+### 模型开白引导
+
+`--usage vision` 对筛选后每个候选额外查询当前账号可见的基础模型及精确版本，返回 `items[].model_access`，不隐藏候选、不改 `default_model`。判断与前端一致：`ListFoundationModels` 精确 Names 命中，再查 `ListFoundationModelVersions` 精确 ModelVersions 命中；不根据 `Owned`、计费项或 MA 功能权限判断模型开白。
+
+- `status=visible`：账号能看到模型和版本；仍不保证计费开通、Vision 功能授权或实际推理成功。
+- `status=requires_whitelist`：模型或版本未出现在当前账号查询结果中。展示该项 `application_url` 和模型 ID，引导用户申请，等待开白后重查；不要自动提交申请、换模型，或建议 `agent activate` / `models activate` 代替开白。
+- `status=unknown`：查询失败或响应缺失，不能当作未开白。按 `reason` 区分模型或版本查询阶段，检查登录、网络及接口状态后重查。
+
+申请入口使用当前查询返回的 `application_url`，与前端一致，不自行拼接地址。本能力只查询和提供引导，不新增创建前本地硬拦截，也不自动发起申请。开白查询不复用 ArkModels 的 5 分钟缓存，每次重查当前账号状态；可以用 `--name` 缩小查询范围。`--format json` 的退出码 0 表示目录查询完成，不能替代逐项检查 `model_access.status`。旧版没有此字段时，不能把字段缺失解释成已开白。
+
+仅需要自行选择工具模型时查询 `agent model list --usage tool --format json`，按生图/视频模态选择真实返回的 `items[].model`。已有明确 ID 时不增加资格前置拦截。工具模型对象支持 `ID`、`Name`、`Version`、`Default`；`ID` 是实际绑定，Name/Version 由后端解析回显。
+
+新建时优先为启用的生成工具显式绑定已确认模型。省略 Models 依赖服务端默认配置，不保证可用；若返回 `default model endpoint for tool "image_generate" is not configured`，说明缺少工具默认模型，不是主模型错误或 MA 未开通。查询工具候选、确认具体版本的输出模态后补齐该工具的 Models，保留其他工具配置；不要重复发送相同请求、替换主模型或开通服务来试错。创建后仍须回读绑定，配置成功不代表生成成功。
+
+MA 服务开通、Vision 账号/项目开白、模型可用性是不同检查。`agent activate` 不授予 Vision 开白。遇到 `FunctionNotAllowed` 应报告权限问题和服务端 RequestId，不自动换账号、改成普通类型或绕过确认调用 raw API。
+
+## 请求参数与模板
+
+当前服务端要求：
+
+- `Model.ReasoningEffort: high`；前端默认 `ServiceTier: default`。
+- 基础工具集 `agent_toolset_20260916`（服务端兼容 20260701）与多模态工具集 `agent_toolset_multimodal_20260825` 同时存在。
+- 多模态工具启用 `image_generate`、`visual_search`、`compose_video`、`general_search`、`todo_write`；`video_generate` 按用户需求启用。虽然前端只在启用视频时强制视频合成，CLI 模板按当前后端约束保留 compose_video/general_search。
+- 前端 Vision 关闭基础 `web_search`；不是关闭多模态 `general_search`。
+- `--tool` 是整个 Tools 数组替换；只传 image_generate 会丢掉必要工具集。CLI 不会因 `--base-agent` 自动补齐 Vision 工具或改模型参数。
+
+下面是请求结构模板，不是已验证可执行的模型配置。将占位 ID 换成本次确认的真实 ID 后保存为 `vision-agent.json`；不用视频时不附带视频模型绑定。
+
+```json
+{
+  "Name": "arkcli-vision-agent",
+  "BaseAgent": "ultra_vision_agent_preview",
+  "Model": {"Id": "<confirmed-vision-main-model-id>", "ReasoningEffort": "high", "ServiceTier": "default"},
+  "System": "根据用户需求生成创作成果，使用可用工具并说明输出文件。",
+  "Tools": [
+    {
+      "Type": "agent_toolset_20260916",
+      "DefaultConfig": {"Enabled": true, "PermissionPolicy": {"Type": "always_allow"}},
+      "Configs": [{"Name": "web_search", "Enabled": false}]
+    },
+    {
+      "Type": "agent_toolset_multimodal_20260825",
+      "DefaultConfig": {"Enabled": false, "PermissionPolicy": {"Type": "always_allow"}},
+      "Configs": [
+        {"Name": "image_generate", "Enabled": true, "Models": [{"ID": "<confirmed-image-model-id>", "Default": true}]},
+        {"Name": "visual_search", "Enabled": true},
+        {"Name": "compose_video", "Enabled": true},
+        {"Name": "general_search", "Enabled": true},
+        {"Name": "todo_write", "Enabled": true},
+        {"Name": "video_generate", "Enabled": false}
+      ]
+    }
+  ]
+}
+```
+
+权限策略应与用户要求一致；模板的 always_allow 不是额外授权。按实际需求设置 system、Skills、MCP，不因创建 Vision 自动添加无关资源。
+
+```bash
+arkcli agent agent create \
+  --file ./vision-agent.json \
+  --dry-run --format json
+```
+
+Preview 零网络，只检查输入与请求形态，不证明权限、模型和后端约束通过。复述配置、未决项和费用影响，按所属 Skill 的宿主授权契约取得本轮授权后，移除 `--dry-run` 执行一次，再 `agent agent get <returned-agent-id> --format json`。宿主使用 permission Widget 时，不在聊天中重复确认或自行补开通授权参数。
+
+## 回读、复制与失败处理
+
+- 核对 `BaseAgent`、`Model.Id/ReasoningEffort`、完整 Tools、`Configs[].Models[].ID`；table 只展示摘要，核对绑定用 JSON/YAML。
+- `+new-agent --fork <id>` 保留基座类型和工具模型。修改工具仍须提交完整数组；不自动升级工具集、不迁移旧类型。该命令不支持 `--dry-run`；先用 `agent agent get <id>` 核对源配置，复述复制与覆盖内容并取得本轮授权，再执行 fork。不能为了预览改用另一条创建流程，也不能将源配置读取当作复制已完成。
+- update / `+iterate` 可修改模型参数和工具，但不支持改变 BaseAgent。Session override 也不能切换基座类型，只继承源类型并按服务端约束校验覆盖后的配置。
+- 返回字段缺失时记录实际 CLI 版本、原始请求和输出，不声称已落库；检查版本兼容性，不用重复 create 试探。创建超时先只读核对是否已经创建，避免重复资源。
+- 工具模型透传、创建成功、实际生成图片是三个不同验收层次。仅完成预览/创建不得声称生图端到端成功；运行 Session 可能产生沙箱与模型费用。

package/skills/arkcli-api-explorer/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: arkcli-api-explorer
+version: 1.1.1
+description: Inspect or invoke locally registered ArkCLI actions when product commands cannot cover a task. Use for registry errors or exact raw payloads. Not for public API catalogs or OpenAPI schemas.
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli api --help"
+---
+
+# arkcli api（Raw API Explorer）
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证、配置覆盖排查与命令选择顺序**
+**CRITICAL — 只有在现有产品命令和业务 skill 确实不覆盖时，才允许进入本 skill；禁止把 `arkcli api` 当默认入口。**
+**CRITICAL — 任何 `arkcli api ...` 调用前，MUST 先用 Read 工具读取 [`references/arkcli-api.md`](references/arkcli-api.md)，禁止盲目猜参数与输出结构。**
+
+## 使用原则
+
+- `unknown action` 先查本地 `api --list`，使用完整注册名，不凭近似业务名猜 Action；`MissingParameter` 按当前契约里的字段名与大小写补齐，不轮流试 `Id/ID/KeyID`。
+- 查询 API Key 时，先读 [Auth 的 API Key 查询与交付](../arkcli-auth/references/api-key-query.md)：list 只定位元数据，授权导出才用真实 `Id` 调 `apikey.get_raw`，不默认回显明文或轮换。
+- 安装态未必有仓库源码：优先读同版本 Skill/reference 与已注册目录；能访问源码时再查 req/resp JSON tag。没有确定的契约来源就说明缺口并停止，不能虚构本地 `internal/apis` 文件已被检查。
+
+- 先产品命令：`arkcli <domain> <verb>` 或 `arkcli +<shortcut>`
+- 再 skill / reference：确认是否已有稳定入口与正确参数
+- 最后才 `arkcli api`：仅用于低频、专业或高风险的底层 Action 验证与兜底
+
+不要因为某个 Action 存在，就反推出新的顶层 skill 或 `cmd/` 命令；只有升级为稳定产品能力时，才考虑补 `shortcuts/`。
+
+## 适用场景
+
+- 现有产品命令确实无法覆盖需求（且该需求不值得做成标准命令或 `+shortcut`）
+- 需要验证某个已注册 Action 的输入输出契约（例如排障、回归验证、确认 transport 可达）
+- 需要确认 registry 中是否已存在某个 Action（用于开发或排查 “注册缺失”）
+
+## 唤起信号（When To Trigger）
+
+- 用户明确提到：`action` / `operation` / `registry` / “已注册 Action” / “契约验证”
+- 用户给出：`arkcli api ... --params ...` 并需要你补全/排错
+- 用户遇到：`unknown action` / 需要确认某个 Action 是否存在
+- 开发场景：在 `internal/apis/<domain>/` 新增 operation 后，要快速验证能否 `--list` 与可调用
+
+## 反唤起信号（When NOT To Trigger）
+
+- 用户要公开 API 契约目录、接口标识、OpenAPI schema 或必填请求字段：转 [`arkcli-docs`](../arkcli-docs/SKILL.md) 的 `docs apis list/spec`。`api --list` 只列二进制本地注册的 Action，不是公开 API 目录，也不提供完整 OpenAPI schema。
+- 用户目标是：对话（`+chat`）、生成（`+gen`）、部署（`+deploy`）、用量（`usage`）、查模型（`models`）等已有稳定产品路径
+- 用户只是鉴权失败/未登录/环境 profile 混乱（应先走 `auth/config`，不要把问题导向 `api`）
+- 用户只是想“找一个命令怎么用”（优先 `arkcli <domain> --help` + 对应 skill/reference）
+
+## Agent 快速执行顺序
+
+1. 先判断用户目标是否已有产品入口：`arkcli <domain> --help`，并优先转对应业务 skill
+2. 如果只是认证/配置问题，不要误判为需要 `api`：
+   - 认证失败先转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md)
+   - profile/base-url/region 覆盖混乱先转 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md)
+3. 枚举已注册 Action（无参等价于 list）：
+   - `arkcli api --list`
+   - `arkcli api`
+4. 定位契约与必填字段（禁止猜 JSON）：
+   - 查同版本 reference/官方契约；仓库可用时再查 `internal/apis/<domain>/` 对应 req/resp 结构体，安装态没有源码时不得声称已检查
+   - 同一 Action 因 `MissingParameter` / `InvalidParameter` 连续失败两次，且错误没有给出确定值时，停止更换相近字段名试错；回到注册 operation、req/resp tag 或官方契约确认。禁止循环枚举 `Scene` / `Type` / `BizType` 等猜测字段。
+5. 先用叶子命令的 Client Preview 核对最终 descriptor 和 payload：
+   - `arkcli api <registered-action> --params '{...}' --dry-run`
+   - Preview 是纯本地行为，不登录、不请求后端、不证明权限、配额或资源存在
+6. 只读优先；写操作在 Preview 后仍必须二次确认，然后去掉 `--dry-run` 执行：
+   - `arkcli api <registered-action> --params '{...}'`
+   - payload 自身的 `"DryRun":true` 是后端字段；未加 CLI `--dry-run` 时仍会发出真实网络请求
+7. 输出尽量稳定、减少噪声：
+   - 优先用全局 `--transform '<gjson path>'` 提取关键字段
+   - 只有排障需要时才开 `--debug`（会输出请求/响应调试信息到 stderr）
+
+## Guard Checklist（必须执行）
+
+| 检查点 | 目的 | 做法 |
+|--------|------|------|
+| 产品命令覆盖判断 | 防止误用 `api` | 先 `arkcli <domain> --help` 并对照对应 skill |
+| 认证闸门 | 防止把鉴权问题误判为缺能力 | 先 `arkcli auth status`；失败转 `arkcli-auth` |
+| 契约事实源 | 防止猜参数 | 从同版本 reference、官方契约或可访问的 req/resp JSON tag 生成 `--params`；缺确定契约就停止 |
+| Client Preview | 防止 raw Action 直接执行 | invoke 模式先加本地 `--dry-run`，核对 `steps[0].protocol/target/payload` |
+| 风险确认 | 防止写操作误触发 | 涉及创建/删除/修改/影响费用前，要求用户明确确认 |
+| 噪声控制 | 防止整坨输出污染上下游 | 默认引导 `--transform` 提取关键字段；`--debug` 仅排障打开 |
+
+## 示例
+
+```bash
+arkcli api --list
+arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}' --dry-run
+arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}'
+
+# 只提取 items 里的 name（示例 path，按实际输出结构调整）
+arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}' --transform 'Result.Items.#.Name'
+```
+
+## 常见错误与处理
+
+| 现象 | 常见原因 | 处理方式 |
+|------|----------|----------|
+| `unknown action "..."` | Action 未注册或拼写错误 | 先 `arkcli api --list`；再在 `internal/apis/` 中确认是否已注册 |
+| `invalid --params JSON: ...` | JSON 不合法（引号/转义/单引号包裹不当） | 确保 `--params` 是合法 JSON；必要时把 JSON 放到文件再用 shell 展开传入 |
+| `api list mode has no request to preview` | 对 `api --list` 使用了 `--dry-run` | list 本身已经是纯本地枚举；移除 `--dry-run` |
+| 输出字段和预期不一致 | 直接猜测了契约 | 先读 [`references/arkcli-api.md`](references/arkcli-api.md) 并查看 `internal/apis/<domain>/` 的 req/resp |
+
+## 开发约束
+
+- 如果 Action 未注册：补 `internal/apis/<domain>/` 的 operation 注册与 req/resp 契约
+- 不要直接因为 Action 缺失就新增 `cmd/<action>`；`api` 是兜底入口
+- 只有当它升级为稳定产品能力时，才在 `shortcuts/` 中补业务命令（并配套 skill/reference/test）
+
+## 参考
+
+- [arkcli-shared](../arkcli-shared/SKILL.md) -- 认证、配置覆盖排查与共享安全规则
+- [arkcli-auth](../arkcli-auth/SKILL.md) -- 认证失败时的回退入口
+- [arkcli-config](../arkcli-config/SKILL.md) -- profile / base-url / region 排障入口
+- [`references/arkcli-api.md`](references/arkcli-api.md) -- api explorer 的命令语义、参数与排错
+- [`references/evals.md`](references/evals.md) -- 最小评估用例（唤起/反唤起/排错）

package/skills/arkcli-api-explorer/references/arkcli-api.md

@@ -0,0 +1,185 @@
+# arkcli api（Raw API Explorer）
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证闸门、全局 flags、配置覆盖排查与安全规则。
+
+`arkcli api` 用于调用仓库中已注册的 Action（operation），作为产品命令的兜底入口。它面向低频、专业或高风险场景，不应替代 `arkcli <domain> <verb>` 或 `arkcli +<shortcut>`。
+
+## 唤起信号 / 反唤起信号
+
+适合进入 `arkcli api` 的信号：
+
+- 用户明确说要“验证某个 Action/operation/registry”
+- 用户目标是“排障/回归验证/契约核对”，且产品命令确实没有覆盖
+- 用户遇到 `unknown action`，需要确认是否已注册
+
+不适合进入 `arkcli api` 的信号：
+
+- 用户目标是 `models/+chat/+gen/+deploy/usage` 等已覆盖场景
+- 用户只是未登录/鉴权失败/环境配置混乱（优先回到认证与配置排障）
+
+## 没有产品命令封装的数据面能力（直接走 raw API）
+
+下面这些数据面能力当前**没有专属产品命令**，需要直接通过 `arkcli api` 调用对应的 `arkruntime.*` Action：
+
+| 能力 | Action | Endpoint |
+|------|--------|----------|
+| Embedding（文本向量） | `arkruntime.create_embeddings` | `/embeddings`，`input` 为字符串（或字符串数组） |
+| Embedding（多模态：文本 + 图片 + 视频） | `arkruntime.create_multimodal_embeddings` | `/embeddings/multimodal`，`input` 为内容片段数组，返回单个文档向量 |
+
+**调用前先确认 `model` 是当前账号真实可调用的 ID**（embedding 类失败绝大多数是模型名问题，不是接口问题）：
+
+1. 查 embedding 模型的完整版本 ID（不要用展示名或裸族名，如 `doubao-embedding`）：`arkcli models list --modality embed`
+2. 或查当前 profile 已经可调用的推理接入点：`arkcli resources list`（用 `ep-...` ID）
+3. 模型需已在控制台开通；子账号还需主账号授权，否则返回 404 `InvalidEndpointOrModel.NotFound`
+
+```bash
+# 文本向量：<text-embedding-model-id> 用上一步 search 到的实际版本 ID 替换
+arkcli api arkruntime.create_embeddings --params '{"model":"<text-embedding-model-id>","input":"火山方舟"}'
+
+# 多模态向量：vision embedding 模型（*-embedding-vision-*）只能走这个 action；
+# 误走到 create_embeddings 会收到 400 "<model> does not support this api"
+arkcli api arkruntime.create_multimodal_embeddings --params '{"model":"<vision-embedding-model-id>","input":[{"type":"text","text":"火山方舟"}]}'
+```
+
+常见报错对照（CLI 已会把这些翻译成带排查步骤的 hint）：
+
+| 报错 | 含义 / 处理 |
+|------|-------------|
+| 404 `InvalidEndpointOrModel.NotFound` | 模型/endpoint 名写错、用了裸族名、未开通或无权访问；按上面 1–3 步核对 |
+| 400 `<model> does not support this api` | vision/多模态 embedding 模型误走了文本 `/embeddings`；改用 `create_multimodal_embeddings` |
+| 400 `does not support the agent plan feature` | 当前 Agent Plan / Coding Plan 数据面不支持该模型；`arkcli resources list` 查套餐内可调用对象，或切 platform profile |
+| 本地 `connection refused` / 缺少 API Key | 检查代理环境变量 / `arkcli auth status`，必要时 `arkcli auth login` |
+
+需要新增其它能力的产品命令时，从这里降级到 raw API 是合法兜底，不要把 raw API 当默认入口。
+
+## 命令
+
+```bash
+# 列出所有已注册 Action（无参等价于 --list）
+arkcli api --list
+arkcli api
+
+# 调用某个已注册 Action
+arkcli api <registered-action> --params '{...}'
+
+# 只在客户端预览 descriptor 和最终 payload，不请求后端
+arkcli api <registered-action> --params '{...}' --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `<registered-action>` | 否 | string | Action 名（例如 `model.list_foundation_models`）。不提供时默认进入 list 模式 |
+| `--list` | 否 | bool | 列出全部已注册 Action |
+| `--params` | 否 | string | JSON 请求体（字符串形式）。省略时默认 `{}` |
+| `--dry-run` | 否 | bool | 仅 invoke 模式可用；输出 `preview.v1` Client Preview，不请求后端 |
+
+## 返回值
+
+- list 模式：返回已注册 Action 列表（按名称排序）。
+- invoke 模式：返回该 Action 的原始响应对象（按契约定义）。
+- invoke + `--dry-run`：返回 `mode=client_preview` 和 `steps[0]` 中的
+  `protocol`、`target`、脱敏后的 `payload`；不创建 transport，不验证服务端。
+- 输出遵循当前二进制帮助中的全局 `--format` 与 `--transform`（GJSON path 表达式）；机器处理优先用完整 JSON，不把历史“仅 json”当成输出能力限制。
+
+`arkcli api --list --dry-run` 会报错，因为 list 本身已经是纯本地枚举，
+没有远端请求可供 Preview。
+
+## 如何确定 `--params` 的结构
+
+禁止猜参数。推荐按下面顺序定位契约：
+
+1. `arkcli api --list` 找到 action 名（例如 `model.list_foundation_models`）
+2. 使用当前版本的 reference/契约；有匹配版本的源码时，可在 `internal/apis/<domain>/...` 搜索 operation 定义与 req/resp。已安装 CLI 的宿主不一定有源码，不要求用户下载整个仓库才能调用。
+3. 以已核实的请求字段（源码中为 `json:"..."` tag）构造 `--params` JSON；拿不到 schema 时先补证据，不靠字段大小写轮番试错。registry 枚举只证明 Action 已注册，不证明猜测的 payload 有效。
+
+例如 `model.list_foundation_models` 的请求体来自 `ListFoundationModelsRequest`，包含 `PageSize`、`PageNumber`、`SortBy`、`SortOrder`、`Filter` 等字段。
+
+## 风险与守卫
+
+### JSON 与 shell 变量
+
+静态 JSON 用外层单引号、内部双引号：`--params '{"PageSize":100}'`。动态值用 JSON 编码器构造，不把用户文本拼进转义字符串；字符串用 `--arg`，已校验的数字/布尔/数组才用 `--argjson`：
+
+```bash
+# 只构造参数，不执行远端请求；字段仍必须按目标 Action 的真实 schema 选择
+page_size=100
+params=$(jq -cn --argjson size "$page_size" '{PageSize:$size}')
+# 字符串示例：引号、反斜杠和换行由 jq 编码，不使用 eval
+name_params=$(jq -cn --arg name "$resource_name" '{Name:$name}')
+# 调用时整体引用变量：arkcli api <已核实Action> --params "$params"
+```
+
+`jq` 失败就停止，不发送空串或部分 JSON。构造成功只证明 JSON 语法正确，不证明请求字段或资源权限正确。响应先完整捕获，再按实际 envelope 与字段大小写解析；不得用 `head` 截断后拼回“合法 JSON”。
+
+- 默认只读优先：能用查询验证就先查询验证。
+- 写/删/可能产生费用的 Action：执行前必须让用户明确确认意图。
+- 写/删/可能产生费用的 Action：先运行同一条命令的 `--dry-run` Client
+  Preview 核对 payload；Preview 后仍必须让用户明确确认，不能自动去掉 flag。
+- `--params '{"DryRun":true}'` 中的 `DryRun` 是后端请求字段，不等于 CLI
+  `--dry-run`。未加 CLI flag 时命令仍会创建 transport 并发出真实请求。
+- `--debug` 仅用于排障：会输出请求/响应调试信息到 stderr，容易产生噪声。
+- 输出降噪：优先用 `--transform` 抽取稳定字段（便于脚本与后续步骤消费）。
+
+## 常见用法模式
+
+```bash
+# 1) 最小调用（先跑通再逐步加字段）
+arkcli api model.list_foundation_models --params '{}'
+
+# 2) 先做本地 Client Preview
+arkcli api model.list_foundation_models \
+  --params '{"PageSize":10,"PageNumber":1}' \
+  --dry-run \
+  --transform 'steps.0.payload'
+
+# 3) 加分页
+arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}'
+
+# 4) 只提取关键字段（示例 path，按实际输出结构调整）
+arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}' --transform 'Result.Items.#.Name'
+```
+
+## 显式核对 GetModelChargeItem 原始契约
+
+仅当用户明确要求核对该 Action 的原始计费项或开通状态时，使用已注册的只读 operation：
+
+```bash
+arkcli api model.get_model_charge_item \
+  --params '{"FoundationModelName":"<actual-foundation-model-name>"}'
+```
+
+先从同一身份下的权威模型结果取得真实 `Name`，不要把 DisplayName、Endpoint ID 或
+自行拼接的版本名放进 `FoundationModelName`。保留实际返回的结构与字段：原始计费项和
+`pricing` 的产品价格投影不是同一契约；字段缺失或查询失败标未知，不编造价格/开通状态。
+此查询不执行开通或购买。普通模型询价仍使用 pricing/models，不因这个例子自动转 raw。
+
+## 常见错误
+
+| 错误/现象 | 原因 | 处理方式 |
+|----------|------|----------|
+| `unknown action "..."` | Action 未注册/拼写错误 | 先 `arkcli api --list`；再检查 `internal/apis/` 是否已注册该 operation |
+| `invalid --params JSON: ...` | JSON 不合法 | 确保 `--params` 是合法 JSON（双引号、无多余逗号）；必要时先用工具校验 JSON |
+
+## 注意事项
+
+- `--params` 是字符串 JSON：命令行引号和转义容易出错，优先从最小 `{}` 开始逐步加字段。
+- `--transform` 建议用于提取稳定字段，减少 stdout 噪声，便于脚本集成。
+- 写操作/删除操作：必须在执行前让用户确认意图；能只读验证就先只读验证。
+
+## 最小评估（建议每次改动后跑）
+
+```bash
+# 1) list 能工作（无参/--list 都行）
+arkcli api --list --transform '0.name'
+
+# 2) 正常调用能工作（以已知 action 为例）
+arkcli api model.list_foundation_models --params '{"PageSize":1,"PageNumber":1}' --transform 'Result.Items.#.Name'
+
+# 3) Client Preview 不请求后端，输出统一 plan
+arkcli api model.list_foundation_models \
+  --params '{"PageSize":1,"PageNumber":1}' \
+  --dry-run \
+  --transform 'steps.0.payload'
+```

package/skills/arkcli-api-explorer/references/evals.md

@@ -0,0 +1,92 @@
+# arkcli-api-explorer 最小评估用例
+
+目标：验证本 skill 在“该唤起/不该唤起/排错”三个维度上行为稳定。
+
+## 原始计费项契约（遗漏 #71）
+
+- 用户明确要求核对 `GetModelChargeItem` 的原始计费项/开通状态时，确认已注册的
+  `model.get_model_charge_item` 与 `FoundationModelName`，使用真实基础模型 Name 做只读调用。
+- 保留原始返回结构；字段缺失或接口失败标未知，不用 pricing 的投影字段冒充原始计费项。
+- 用户只是询问模型价格时，继续走 pricing/models；原始查询不自动开通模型或购买套餐。
+
+## 1) 该唤起（Trigger）
+
+输入（用户说法）：
+
+- “产品命令没有覆盖，我要验证某个 Action 的入参/出参契约”
+- “我怀疑 registry 里没有这个 operation，帮我确认一下”
+- “`arkcli api ...` 报 `unknown action`，怎么定位？”
+
+期望行为：
+
+- 先引导 `arkcli api --list`（或 `arkcli api`）枚举
+- 再引导到 `internal/apis/<domain>/` 作为契约事实源
+- 最后才执行 `arkcli api <action> --params '{...}'`
+
+## 2) 不该唤起（Anti-trigger）
+
+输入（用户说法）：
+
+- “帮我找一个模型/列出模型/看模型详情”
+- "我要试用对话/生成图片/生成视频"
+- “我想部署一个 endpoint”
+- “我想看用量统计”
+- “列出公开 API 契约目录和接口标识” / “读取某接口的 OpenAPI schema”
+
+期望行为：
+
+- 明确拒绝把 `api` 当默认入口
+- 将用户路由到对应产品命令与 skill（`models/+chat/+gen/+deploy/usage`）
+- 公开目录与 schema 请求转 `arkcli-docs` 的 `docs apis list/spec`；不执行本机 `api --list` 替代。
+
+## 3) 认证/配置分流（Guard）
+
+输入（用户说法）：
+
+- “我调用报错了/401/鉴权失败/没有权限”
+- “profile/base-url/region 看起来不对”
+
+期望行为：
+
+- 先 `arkcli auth status`，必要时转 `arkcli-auth`
+- 配置覆盖问题转 `arkcli-config`
+- 不要直接用 `api` 反复重试
+
+## 4) CLI 实测命令（可重复）
+
+```bash
+# list 模式可用
+arkcli api --list --transform '0.name'
+
+# invoke 模式可用（需要已登录且联网）
+arkcli api model.list_foundation_models --params '{"PageSize":1,"PageNumber":1}' --transform 'Result.Items.#.Name'
+```
+
+## 5) Client Preview 与后端 DryRun 分流
+
+输入（用户说法）：
+
+- “只看这个 raw Action 最终会发什么参数，不要请求后端”
+
+期望行为：
+
+```bash
+arkcli api model.list_foundation_models \
+  --params '{"PageSize":1,"PageNumber":1}' \
+  --dry-run \
+  --format json
+```
+
+- 使用 Action 叶子命令的本地 `--dry-run`。
+- 检查 `mode=client_preview` 和 `steps[0].payload`。
+- 不要求登录，不把 Preview 成功解释为后端验证成功。
+
+输入（用户说法）：
+
+- “payload 里加 `DryRun:true` 就不会请求后端了，对吗？”
+
+期望行为：
+
+- 明确否定。payload 中的 `DryRun` 是后端字段。
+- 未传 CLI `--dry-run` 时，Raw API 仍会建立 transport 并发送请求。
+- 写操作仍需目标、影响和用户确认。

package/skills/arkcli-auth/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: arkcli-auth
+version: 1.3.0
+description: "arkcli 认证管理：交互式登录、Volc SSO 登录、查看状态、退出登录、生成 ARK API Key (apikey)、以及云开发机/CI 用 `arkcli init-volc` 从 VOLC_INIT_* 环境变量无交互引导 platform profile。0.1.16 起 SSO 登录走 Gate 1+2 自动绑定 Profile 切面 (type/region/project/owner_trn)；AK/SK login 通道暂关。当用户需要初始化凭证、排查鉴权问题、切换认证方式、生成或重选 ARK API Key、或在已注入凭证的环境无交互引导时使用。反触发：用户问 TTS/ASR/语音模型能力、接入或调用时，不要引导 `auth apikey`，转 models search 做发现；火山 Agent Plan 个人版/企业版 TTS 使用 arkcli-gen 的 +gen --modality audio，原生 ASR 使用 arkcli-understand 的 WS 入口。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli auth --help"
+---
+
+# arkcli auth
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证闸门、配置排查与共享安全规则**
+**CRITICAL — 用户目标是其他业务命令时，必须先判断是不是被认证阻塞，再决定是否进入本 skill。**
+**CRITICAL — `auth` 是身份/TTY 工作流，全域不注册 `--dry-run`；不要生成该 flag。**
+**CRITICAL — Key 列表、当前 Profile 选中 Key、最近有调用的 Key 是三个不同事实。声称“最近使用”前，须完整分页并按真实 `LastAccessTime` 解析时区后取最大值；列表第一条、名称中的日期、`CreateTime` 或 `Active` 状态都不能代替最近调用证据。查询/聚合与披露边界见 [API Key 查询与交付](references/api-key-query.md)。**
+
+**⚠️ 0.1.16 变化总览（必读）**：
+1. SSO 登录引入 **Gate 1+2**：浏览器流后比对 SSO trn 与 `is_default profile.OwnerTrn`，4-case 分别走 `BuildFirstProfile` (新建) / `GUIDE_SKIP` (复用) / 提示切 default / 提示新建。详见 `docs/runtime/volc-sso.md`。
+2. **AK/SK 登录通道暂关**：`auth login --access-key / --secret-key` 已注释,promptui 也移除"AK/SK"选项；SSO（火山）+ `arkcli auth login --no-browser`（**注册在 auth login，由 volc-sso 继承**）是唯一登录入口。
+3. **auth status / auth whoami 输出新增 profile 切面字段**：`active_profile.{name,type,region,project,owner_trn}` 和 `profiles_summary[...]`；顶层 `auth_method/logged_in/volc_sso/ark_api_key` 等老字段全部保留（向后兼容）。
+4. **Profile 管理迁移到 `arkcli profile`**：`config init/list/show/switch/delete` 已 deprecated，详见 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md)。
+5. **0.1.17 首登动态选 project**：`BuildFirstProfile` 的 project 步骤改为经 IAM `ListProjects` 拉当前身份名下真实 active project 列表交互选（拉取失败/无权限回退兜底 `default`，不阻断登录）。登录后想换 project 不必重登：`arkcli profile project [<name>]`（拉同一列表重选，把 platform profile 重派生到新 project，个人版 plan profile 保留），详见 [`../arkcli-profile/SKILL.md`](../arkcli-profile/SKILL.md)。
+6. **1.0.4 起 `arkcli auth login` 交互式浏览器 SSO 分支支持借用本机 volcengine-cli 登录态**：检测到 `ve >= 1.0.45` 且已 `ve login` 时,直接接管 STS 落一份 arkcli identity (`identity_store/<key>/metadata.json.source="ve"`, 不写 IDToken/refresh_token/ClientID; STS 由 volcengine-go-sdk 内部持 refresh_token 自动 refresh)。用户视角: 少一次浏览器授权; agent 视角: `auth_method` 变成 `"sts"` 而非 `"sso"`, 但 `logged_in=true`。检测失败 / ve 未登录 → 自动降级 arkcli 原生 SSO OAuth 流。详见 [`references/arkcli-auth-login.md`](references/arkcli-auth-login.md) 的"volcengine-cli 登录态借用"节。
+
+## 适用场景
+
+- 第一次登录 `arkcli`
+- 切换到 Volc SSO
+<!-- AK/SK 通道在 0.1.16 暂关 (见上方说明); 恢复后取消下条注释 -->
+<!-- - 使用 AK/SK 做非交互登录 -->
+- 登录后重新获取或切换 ARK API Key
+- 查看当前凭证状态
+- **回答"我是谁 / 我的 IAM ID 是多少 / 我属于哪个账号"——用 `arkcli auth whoami`**
+- 清理本地登录状态
+- 其他业务 skill 因未登录、凭证过期、身份不匹配而被阻塞
+- **云开发机 / CI 已注入 `VOLC_INIT_*` 凭证，无交互引导** —— 用 `arkcli init-volc`（不是 SSO）
+
+## 无交互引导（init-volc）
+
+云开发机 / CI 等**已经把火山凭证注入成 `VOLC_INIT_*` 环境变量**的场景，用 `arkcli init-volc` 一条命令、零交互地落一个火山 platform profile 并设为 default，让后续 arkcli / OpenCode 调用开箱即用（数据面用 API Key，控制面用 STS）。
+
+- 触发词："云开发机引导 / 无交互初始化 / 已注入 VOLC_INIT 怎么让 arkcli ready / CI 里跳过 SSO"
+- 跟 `auth login` 的区别：`init-volc` **不登录、不交互、不联网**，纯消费环境变量；本地终端用户首次引导仍走 `auth login`（SSO）
+- 详细环境变量契约、落地行为、输出见 [`references/arkcli-auth-init-volc.md`](references/arkcli-auth-init-volc.md)
+
+## Agent 快速执行顺序
+
+**待授权优先于重新登录。** 本轮或用户提供的上一轮状态为 `stage=authorize_pending`、用户尚未完成授权且没有 code 时，等待用户；不要重新执行任何 `auth login`、`config init` 或原业务命令。可只读检查一次 `auth status`：若已有所需的有效凭据则恢复原任务；`logged_in=false` 只说明尚未登录，不表示 pending 过期或丢失，仍须等待。仅收到 CLI 明确的会话过期/不存在错误或用户明确要求重启登录，才重开 Phase 1。
+
+1. 业务命令开始前如果不确定认证状态，先执行 `arkcli auth status`
+2. 需要识别当前用户身份（"我创建的 / 我的 xxx" 语义）时，用 `arkcli auth whoami`，不要去 `~/.arkcli/.env` 里手动解 JWT
+3. **未登录或凭证失效时，火山方舟场景直接通过 Bash 执行 `arkcli auth login volc-sso`**（不要只是"提示用户去跑"）。SSO 是 0.1.16 唯一可用登录通道，覆盖控制面 BFF + 数据面绝大多数能力
+   - 执行前用一句话告知用户："检测到未登录，我现在为你启动 SSO 登录，请在弹出的浏览器中完成授权"
+   - Bash 调用必须设 `timeout=600000`（10 分钟）
+   - 启动失败（浏览器没装、`open` 失败、端口被占用、超时等）→ 不原地重试，把 stderr 贴回给用户，请用户手动在终端跑对应租户的登录命令（火山：`arkcli auth login volc-sso`）
+   - 命令成功后立即回到用户原始任务，不要停在 auth 结果
+4. **agent / 沙箱 / CI 无浏览器登录走两段式 `--no-browser`**（AK/SK 通道 0.1.16 暂关，提到 AK/SK 时告知并引导走这里）：agent 终端通常非 TTY，`--no-browser` 现为**两段式**，不再阻塞读 stdin（旧版在沙箱必报 `读取授权码失败: EOF` —— 进程在拿到授权码前就被 EOF 打断）：
+   - **Phase 1**：跑 `arkcli auth login --no-browser`。它打印授权 URL 并以 JSON 输出 `{"stage":"authorize_pending","authorize_url":"...","next_command":"..."}` 后**立即退出**（不傻等）。把 `authorize_url` 原样转发给用户，请他在**任意设备**浏览器完成 SSO，复制页面显示的 **base64 授权码**回来。
+   - **Phase 2**：拿到授权码后跑 `arkcli auth login --no-browser --code <授权码>` 完成登录（读 Phase 1 落盘的 PKCE/state 换 token）。`--code` **必须连 `--no-browser`**（单独写会报 `--code 仅在 --no-browser 模式下有效`）。
+   - **两段必须同一运行环境**：Phase 1 落盘 `~/.arkcli/.sso-pending.json`、Phase 2 读它接力，**两条命令须共享同一 `HOME` / 同一持久化卷**（同一容器 / 开发机）；跨容器或跨 HOME 派发会让 Phase 2 报「没有待完成的…会话」。期间不要动 `~/.arkcli/`。
+   - **flag 位置**：`--no-browser` / `--code` 注册在 `auth login`，并由 `volc-sso` 继承；两种入口都支持。Agent 示例统一用 `arkcli auth login --no-browser`，Phase 2 同时带 `--no-browser --code`。
+   - **出错恢复**：`会话过期(TTL 10min)` / `没有待完成的会话` → **重跑 Phase 1**（确保同一 HOME）；`base64 解码失败` / `state 不匹配(CSRF)` / token 交换瞬时失败 → pending 仍在盘，**TTL 内纠正后直接重试 Phase 2**（贴对当前 authorize_url 的码，必要时从同一 URL 重新授权拿新码），**不必**重跑 Phase 1。
+   - 真人终端（TTY）下 `arkcli auth login --no-browser` 仍是一条命令交互式（打印 URL 后当场粘贴），行为不变。
+5. 用户明确要求挑选登录方式时，因 stdin 交互 agent 无法替用户选，让用户自己跑 `arkcli auth login`
+6. 只有在用户明确要求清理本地凭证时，才执行 `arkcli auth logout`
+
+## 核心规则
+
+- `auth status` 是默认入口；不要上来就 `login`
+- 登录成功后，应回到用户原始目标继续执行，而不是停在 auth 结果本身
+- `auth logout` 是破坏性操作，必须由用户明确提出
+- `auth status` 会对敏感字段做掩码，可直接用于排障，并会展示当前生效的 `project_name`
+- `auth login` 成功后会输出 `auth_method`；凭证存储位置是实现细节，不再回显路径
+- SSO 登录（`arkcli auth login volc-sso`）与 `auth apikey` 都会在选中 API Key 之后写入凭证存储；0.1.16 final clean-slate 模型: 整 arkcli 同一时间只 active 一个 identity, 新 SSO 跟旧 sub 不一致时清空所有 profile (含跨 tenant) 重建
+- **API Key 必须按 profile 类型分池理解**：`platform` / `coding-plan` 个人版使用普通 API Key；`agent-plan` 个人版使用 `Scene=RealAgentPlanPersonal` 的专属 Key；`agent-plan-team` / `coding-plan-team` 使用 `GetSeatInfo` 返回的席位 Key。普通池里“有 Key”不能证明 Agent Plan/团队版 Key 可用。
+- TTY 首登发现普通池为空时会先询问是否创建；确认后只调用一次 `CreateApiKey`，再最多读 3 次状态。Agent Plan 专属记录存在但非 Active 时会询问是否轮转；确认后也只轮转一次、最多读 3 次状态。非 TTY、用户拒绝或无专属记录时绝不写。
+- TTY 首登中，如果用户选择的 profile 类型在 API Key 获取阶段报错（例如 Agent Plan 轮转后检查 3 次仍为 `Restricted`），CLI 会保留已选 region/project、从本轮候选中移除该失败类型，并重新让用户选择其他消费场景。失败类型不会再次 silent backfill，避免重复获取或二次轮转；这属于 profile 级重选，绝不会拿普通/Coding Plan Key 冒充 Agent Plan 专属 Key。
+- **v3 ve handoff 分支** (1.0.4 起, 仅火山 SSO 交互式登录): 检测到本机装有 `volcengine-cli >= 1.0.45` 且已 `ve login` 时, `arkcli auth login` 会先尝试借用其登录态直接落 arkcli identity (省一次浏览器授权)。落盘差异见 [`references/arkcli-auth-login.md`](references/arkcli-auth-login.md): 不落 `token.json` (IDToken/refresh_token/ClientID 由 ve SDK 管), 但落 `sts.json` + `metadata.json.source="ve"`; `auth whoami` 显示 `auth_method="sts"` 而非 `"sso"`, 是合法登录态。检测失败 / ve 未登录 → 自动降级 arkcli 原生 SSO OAuth。
+- `arkcli auth apikey` 只列举并选择**普通 API Key 池**，写入 identity/.env 兼容凭证；它不读取或修复 Agent Plan 专属 Key、也不读取团队席位 Key。当前是 Plan profile 时优先使用 `profile apikey refresh` 或对应 Plan 的轮转/席位流程，不能把 `auth apikey` 的 `saved=true` 解读为 Plan Key 已恢复。它也不能让广场语音模型获得 `+chat` / `+gen` / `+deploy` / `+code-example` / `usage` / `pricing` 能力。
+- `arkcli auth apikey create` 创建、验证并保存一把**普通 API Key**到当前 identity/.env 兼容凭证；TTY 必须确认，非交互环境收到 `requires_confirmation` 后必须走共享 Skill 的宿主确认流程；只发一次 `CreateApiKey`，随后最多做 3 次只读状态检查，成功输出不包含明文 Key。它同样不能创建或修复 Agent Plan 专属 Key、团队席位 Key；已有 Profile 要切换默认 Key 时仍用 `profile apikey refresh/use`。
+- 火山 Agent Plan 个人版/企业版 TTS 使用 `arkcli-gen` 的 `+gen --modality audio`；个人版使用专属 Key，企业版使用席位 Key，不能用 `auth apikey` 的普通 Key 替代。原生 ASR 同样使用已绑定的 Agent Plan Key，走 `+understand asr/asr-align --audio-protocol ws-bidirectional|ws-unidirectional`。其他未实现语音能力只说明边界。
+- **只查不切的 list API Key**(只想看 account 下有哪些 key,不想切换当前 key): 跑 `arkcli api apikey.list --params '{"PageSize":100}' --page-all --format json`,**不要**跑 `auth apikey` — 后者是交互式选择并写入凭证存储,会改变当前生效 key
+- **当前已选 key 的元信息**(name / suffix / project / 状态): 看 `auth status` 输出里的 `ark_api_key` 字段,不需要再调远端
+
+## 与其他 skill 的串联
+
+查询 Key 列表、辨别掩码与明文、向下游注入凭证前，先读 [API Key 查询与交付](references/api-key-query.md)。保留“查元数据 → 定位真实 ID → 必要时授权导出”的业务流程；不要默认回显全部明文。
+
+- `arkcli-models`、`arkcli-chat`、`arkcli-gen`、`arkcli-deploy`、`arkcli-usage` 被鉴权错误阻塞时，先回到这里
+- 如果用户其实是在排查 profile / base-url / region 覆盖问题，应转 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md)
+
+## 自然语言触发词 + 跨技能指引表
+
+| 用户怎么说 | 走哪个命令/skill |
+|---|---|
+| "我是谁/我的身份/当前用户/哪个账号/我自己的 IAM 用户 ID" | `arkcli auth whoami` |
+| "查同事 zhangsan 的 IAM 用户 ID/查别人的 IAM 用户 ID" | **转 `arkcli-profile`**（查看当前 profile 并列出可用 API Key）+ 提示用户使用 `arkcli iam` 命令（如有） |
+| "API Key 泄露/废弃旧 Key/换新 Key/rotate/轮换 API Key" | **转 `arkcli-plans`**：`plans personal rotate-apikey` 或 `plans team rotate-apikey` |
+| "命令突然报 key 失效/401/InvalidApiKey 但我没换过 key"（疑似后端轮换） | **转 `arkcli-profile`**：先 `arkcli profile apikey refresh` 同步后端 key 再重试（**遇失败才触发的反应式自愈，非预防性**）；refresh 救不了再看 [`references/auth-modes.md`](references/auth-modes.md) |
+| "看账号有哪些 Key/Key 列表/只查不切" | `arkcli api apikey.list`，按上述 reference 分页查看元数据，不改变当前 Key |
+| "看当前 Profile 的 Key 库存" | **转 `arkcli-profile`**：说明同步影响后用 `profile apikey list` |
+| "切换默认 Key/用另一个 Key" | **转 `arkcli-profile`**：`arkcli profile apikey use <key>` |
+| "创建一把普通 API Key" | `arkcli auth apikey create`；非交互环境按 `requires_confirmation` 走宿主确认流程 |
+| "AK/SK 登录/access key/secret key" | **告知通道暂关**：当前版本 AK/SK 登录通道暂时关闭，请使用 SSO 登录，运行 `arkcli auth login`
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `arkcli auth status` | 查看当前认证状态（凭证健康度） |
+| `arkcli auth whoami` | 查看当前认证身份（用户名 / IAM 用户 ID / 账号 ID 等），脚本与 Skill 用 |
+| `arkcli auth login` | 交互式选择登录方式（火山 SSO 浏览器 / 火山 SSO 无浏览器） |
+| `arkcli auth login volc-sso` | 浏览器 SSO 登录 |
+| `arkcli auth login --no-browser` | 无浏览器 SSO（cross-device）。TTY：一条命令交互式粘贴；非 TTY（agent/沙箱）：Phase 1，打印 URL + `authorize_pending` JSON 后退出 |
+| `arkcli auth login --no-browser --code <授权码>` | 无浏览器 SSO **Phase 2**：把 base64 授权码喂回完成登录（agent/沙箱两段式的第二步） |
+<!-- AK/SK 通道 0.1.16 暂关; 恢复后取消下行注释 -->
+<!-- \| `arkcli auth login --access-key <ak> --secret-key <sk>` \| 非交互 AK/SK 登录 \| -->
+| `arkcli auth apikey` | 选择普通 API Key 并写入对应 identity store；不代表 Agent Plan 专属/团队席位 Key 可用 |
+| `arkcli auth apikey create` | 创建、验证并保存一把普通 API Key 到当前身份；不输出明文 Key，不处理 Plan 专属/席位 Key |
+| `arkcli auth logout` | 删除本地凭证 |
+
+## 参考
+
+- [`references/arkcli-auth-login.md`](references/arkcli-auth-login.md)
+- [`references/arkcli-auth-status.md`](references/arkcli-auth-status.md)
+- [`references/arkcli-auth-whoami.md`](references/arkcli-auth-whoami.md)