| name | arkcli-shared |
| version | 2.0.1 |
| description | arkcli 共享执行协议：首次配置入口、业务命令执行前的认证闸门、命令路由与选择顺序、输出/安全/二次确认规则。深度细节（身份解析、AK-SK 边界、API Key 恢复、实名闸门、profile 默认与漂移、全局 flags、故障分流）按需在 references/ 加载。当用户第一次使用 arkcli、遇到未登录/鉴权失败、需要判断该走产品命令还是 raw api、或任何 arkcli-* skill 需要公共上下文时触发。 |
| metadata | {"requires":{"bins":["arkcli"]},"cliHelp":"arkcli --help"} |
arkcli 共享规则
本 skill 是 arkcli 的统一执行协议入口。所有 arkcli-* skill 在执行前都应先读取本文件。
分层约定：本文正文只放"几乎每个任务都命中"的规则。稀有路径 / 查表类细节下沉到 reference，命中对应场景时再读：
配置与首次使用
统一 CLI 与 Profile
arkcli 是唯一的二进制：
arkcli profile create --type platform --set-default
arkcli profile use <name>
切换 profile 会联动切换登录身份、API Key、控制面路由等全部上下文。详细命令树看 ../arkcli-profile/SKILL.md。判断当前租户：arkcli profile show 看 tenant 字段。
命令路由与执行顺序
优先按用户目标判断，而不是按命令名思考：
| 用户目标 | 路径 | 关键点 |
|---|
| 试用模型 / 快速验证效果 | auth → models（可选）→ +chat / +gen | 不需要 Endpoint |
| 专项多模态理解（转写/抽取/字幕/框目标…） | auth → +understand | 有明确产出形态时走 understand，不是 chat |
| 语音模型发现 / 选型（TTS / ASR / 播客 / 音色 / 实时语音交互） | auth → models search | 仅支持广场检索；不支持 +chat / +gen / +deploy / +code-example / usage / pricing / onboard |
| 正式接入 / 稳定调用 | auth → models → infer endpoint list → 没有就 +deploy | 核心资源是 Endpoint，不是 +chat/+gen |
| 排查存量调用 / 看消耗 | auth → usage | — |
| 本地 AI Agent 集成 | +connect | — |
易混动词路由（避免选错 skill）：
- 列 / 绑 / 分 / 轮换席位 APIKey →
arkcli-plans；用 / 消耗 / 还剩多少额度 → arkcli-usage
- profile 写操作（create/use/set-default/keys）→
arkcli-profile；配置排障 / 老 yaml → arkcli-config
- 开放式带图对话 →
+chat；生成图/视频 → +gen；有产出形态的理解 → +understand
- 语音合成 / TTS / 配音 / 朗读、或用户点名
doubao-seed-tts-* 等广场语音模型 → 只允许 models search 做发现与选型说明；不要转 +chat / +gen / +deploy / +code-example / usage / pricing。不要主动补充控制台 / OpenAPI / SDK 等非 arkcli 接入路径或链接，除非用户另问"官方文档在哪里"。如果用户只是要"把一个音频文件转文字"且未要求使用广场语音模型，可另走 +understand asr；不要把 +understand 解释成支持广场 ASR 模型。
命令选择顺序（始终按此）：
- 先用产品命令
arkcli <domain> <verb> 或 arkcli +<workflow>
- 有对应 reference 文档先读 reference 再执行
- 产品命令确实不覆盖，最后才走
arkcli api（不要把 Raw API Explorer 当默认入口）
- 读操作优先直接执行；写 / 删除 / 切换默认配置前必须确认用户意图
认证闸门
除 arkcli auth ...、arkcli profile list/show、arkcli +connect list 外，默认认为业务命令需要先过认证检查。不要跳过认证检查就连续重试一串业务命令。
- 先运行
arkcli auth status；已登录就继续目标命令
- 未登录 / 凭证失效：按当前 profile 的
tenant 选登录命令
- 火山（
tenant=volc 或未设置）：直接 Bash 执行 arkcli auth login volc-sso
- 执行前一句话告知用户"检测到未登录，正在启动 SSO 登录，请在浏览器完成授权"；Bash 调用设
timeout=600000（10 分钟）；成功后立即回到原始任务，不要停在 auth 结果
- SSO 同时覆盖控制面 BFF 和数据面，所以默认走 SSO；AK/SK 登录通道 0.1.16 暂关。CI / agent / 沙箱（非 TTY）走
arkcli auth login --no-browser 两段式：Phase 1 跑它拿 authorize_pending JSON 里的 authorize_url 转发给用户，待其浏览器授权后回粘 base64 授权码，再跑 arkcli auth login --no-browser --code <授权码> 完成（细节见 ../arkcli-auth/SKILL.md）。不要在非 TTY 直接指望它阻塞等粘贴（旧版会 EOF 崩）
- 启动 SSO 失败（无浏览器 /
open 失败 / 端口占用 / 超时）→ 不原地重试，把 stderr 原样贴回用户、请其手动在终端登录后回来
- 登录流程细节、whoami、apikey 选择见
../arkcli-auth/SKILL.md
追加闸门 / 错误恢复（命中才读，避免常驻）：
输出规则
- 当前全局
--format 只支持 json
stdout 只放结构化结果；解释 / 调试 / 错误都走 stderr
安全规则
- 禁止输出完整 AK/SK、token、secret
- 写入、删除、切换配置前需要确认用户意图
- 只有已注册 Action 才能通过
arkcli api 调用
- 涉及创建 Endpoint、修改 profile、清理凭证等操作时，优先建议先用只读命令或
--dry-run 验证
二次确认错误处理（human-in-the-loop）
高危操作（删除资源、变更凭证、产生费用等）需要二次确认。CLI 自动检测环境：交互式终端显示 Y/N 提示；非交互式（Agent 调用）返回 ExitValidation 错误、type="requires_confirmation"。
当 arkcli 返回 ExitValidation 且 type="requires_confirmation" 时：
- 不要直接报错给用户 —— 这是正常的二次确认流程
- 调用 AskUser —— 提示内容可从 CLI 错误的
hint 字段提取，或通用提示"即将执行高危操作，确认继续吗？"
- 用户确认 → 给原命令加
--yes flag 重试
- 用户取消 → 返回"操作已取消"
当前会触发二次确认的命令：plans personal rotate-apikey、plans team rotate-apikey、models activate <model-name>、profile delete <profile-name>、profile project [<project-name>]、config delete <profile-name>。后续新增高危命令遵循同一约定。
Agent 禁止行为
- 不要把
arkcli api 当默认入口
- 不要在未检查认证状态前连续重试业务命令
- 不要把中间步骤当最终结果；登录、查模型、切 profile 完成后应回到用户原始任务
- 不要在业务 skill 里重复共享规则；共享规则统一以本 skill（及其 references）为准
- 不要把"试用模型"误写成"需要先创建 Endpoint"（试用走
+chat/+gen）；也不要把"正式接入"误导到一次性试用命令（正式接入走 +deploy）
- 不要把广场可搜到的语音模型误写成 arkcli 已支持调用、部署、示例、用量或费用查询；语音模型在 arkcli 当前只承认
models search 发现能力。
- 不要把语音模型边界回答扩展成"去控制台开通 / 用 OpenAPI / 用 SDK 接入"的替代方案；当前 skill 只负责说明 arkcli 支持边界。
- 不要为单个业务命令加
--project / --project-name；Project Name 只有全局 --project-name 一个入口，持久化优先走 arkcli profile create --project <name>，不要写进 .env / 老 config.json
参考
