arkcli-config

# arkcli config **⚠️ 0.1.16 起命令树迁移**：`arkcli config init/list/show/switch/delete` 已标记 deprecated，请改用 `arkcli profile create/list/show/use/delete`（行为一致 + 新增 profile 切面字段 type/project/owner_trn/available_api_keys）。`arkcli config reset` 保留（清整个本地状态，超出单 profile）。0.2.x 删除全部已 deprecated 子命令。 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证闸门、命令选择顺序与共享安全规则** **CRITICAL — 配置类写操作前必须确认用户意图。`profile show/list/keys list` 可能同步远端 Key 并回写本地库存或默认 Key，不能当作无配置副作用的准入探测。** ## 唤起信号（When To Trigger） - 用户提到：`profile`、`base-url`、`api-key` 覆盖混乱，或仍在使用已删除的全局 `--region/--project-name` - 用户现象：同一条业务命令“打到了错误环境/错误 base URL/错误账号”，怀疑是配置来源不一致 - 用户目标：初始化/更新 profile、切换默认 profile、重置本地配置文件 - 用户目标：启用、关闭或恢复 arkcli 的自动更新/更新提示策略 ## 反唤起信号（When NOT To Trigger） - 用户要解决的是“未登录/401/鉴权失败/没有权限”：先走 `arkcli auth status`，必要时转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md) - 用户目标是业务功能（models/+chat/+gen/+deploy/usage 等）：不要停留在 config，排除配置后回到原任务 ## 适用场景 - 初始化或更新 profile - 查看当前解析后的配置 - 切换默认 profile - 删除单个 profile 或重置整个本地配置 - 排查为什么业务命令连到了错误环境、错误账号或错误 base URL ## Agent 快速执行顺序 1. 先遵守 shared 的认证及宿主边界。普通 CLI 的当前身份/Profile 诊断用 `arkcli auth status --format json`、`arkcli auth whoami --format json`；宿主禁止额外认证探测时，使用宿主已给的上下文，不自行探测。 2. Chat/Gen 的默认模型和路由用 `arkcli resources list --modality <text|image|video> --format json`，按 Resources Skill 区分发现、兼容性和真实调用验证。仅查看默认模型不等于授权发送收费请求。 3. 切换默认 profile：`arkcli profile use <name>` 4. 创建 profile：`arkcli profile create --type=...`（详见 arkcli-profile 子树，本 skill 不重复） 5. `arkcli config reset` 是破坏性操作（清整个本地配置文件），必须确认用户意图 6. 更新策略只使用 allowlist 命令：`arkcli config set update.mode automatic|disabled` 7. 用户明确需要 Profile 详情、清单或 Key 管理时才考虑 `arkcli profile show` / `arkcli profile list`；执行前说明可能同步并回写 Key。用户要求“不改配置/Key”时不执行它们，也不改用旧 `config show/list` 绕过限制。 ## 配置归因（优先级） `arkcli` 的解析优先级（从高到低）： - Profile 选择: `--profile` flag > `ARK_PROFILE` 环境变量 > `config.yaml` 的 `default_profile` > 第一个 `type=platform` 的 profile > `"default"` sentinel - API Key: `--api-key` > `ARK_API_KEY` > profile > 同 identity store > 产品 `.env` 兼容值 - Base URL: `--base-url` > `ARK_BASE_URL` > profile 自定义值 > 按 Profile 的 Region/Type 派生 > 默认值 - Region/Project: 由所选 Profile 持有；`ARK_REGION` / `ARK_PROJECT_NAME` 不再覆盖运行时 `--api-key/--base-url` 仅供数据面命令使用。无 Profile 时必须成对提供；覆盖 Base URL 时也必须显式提供 API Key。控制面/本地命令显式收到这两个 flag 会 fail-fast。 排障时要明确”是谁覆盖了谁”，不要直接猜测。 > **0.1.16 修正**：`--profile` 现在优先于 `ARK_PROFILE`（对齐 CLI 行业惯例 flag > env > config）。0.1.15 及更早版本是 env > flag，与本规则相反。 ### 证据与结论 说明本轮实际检查了什么、哪些来源覆盖仍未验证，不要求复述固定评测词句。`auth whoami` 的 Profile 字段是持久切面摘要，不能据此声称临时 API Key/Base URL override 已验证或数据面调用一定成功。缺少证据时明确保留未知，不为补字段执行可能回写配置的命令。路径展示使用 `$HOME/...`，不读取凭证文件。 ## 核心规则 - 本 skill 负责解释“为什么命令打到了错误环境/错误账号/错误 base URL”，并兼容历史 `config init/list/show/switch/delete` 命令排障语义 - 常规准入沿 `auth status/whoami` → `resources`，不把 Profile 管理命令当无副作用查询 - profile 写操作（create / use / set-default / delete）走 `arkcli profile` 子树 - `arkcli config reset` 负责全量清理；`arkcli config set update.mode <mode>` 只写更新策略。不要用它写任意 YAML 路径。 ## Guard Checklist（必做） - 只读意图：不执行可能回写 Key 的 `profile show/list/keys list`；脱敏不等于无副作用，命令名为 show/list 也不等于只读 - 写操作确认：`profile use/delete` 与 `config reset` 执行前必须复述影响范围并征得确认 - 全量清理提醒：`arkcli config reset` 删除 `config.yaml/config.json`，不会清理 `$HOME/.arkcli/.env`（token）或 identity store；要清理凭证请用 `arkcli auth logout` ## 与其他 skill 的串联 - profile 创建 / 切换 / 资源 default 设置 / API Key 管理 → 转 `arkcli-profile`（推荐）或继续看本 skill 的兼容映射 - 业务命令失败且怀疑是 `--profile`、`--base-url`、API Key 来源或 Profile 的 Region/Project 不一致时，先转到这里 - 配置问题排除后，再回到原始业务 skill 继续 - 配置仍无法解释问题时，再考虑转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md) 或 [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md) ## 命令一览 | 命令 | 说明 | 状态 | |------|------|------| | `arkcli config reset` | 删除整个本地配置文件（保留） | ✅ 活跃 | | `arkcli config set update.mode automatic` | 显式为当前 exact install 启用 automatic；从非 latest 版本恢复时先安装 latest 再执行 | ✅ 活跃 | | `arkcli config set update.mode disabled` | 关闭静默自动安装，保留隐式版本检查、更新提示和手工 update | ✅ 活跃 | | `arkcli profile show [--profile <name>]` | 查看 Profile；可能同步并回写 Key | ✅ Profile 管理，替代 `config show` | | `arkcli profile list` | 列出 Profile；可能同步并回写各 Profile 的 Key | ✅ Profile 管理，替代 `config list` | | `arkcli profile use <name>` | 切换默认 profile | ✅ 替代 `config switch` | | `arkcli profile delete <name>` | 删除单个 profile | ✅ 替代 `config delete` | | `arkcli profile create --type=...` | 创建 profile（替代旧 `config init`） | ✅ 替代 `config init` | | `arkcli config init/list/show/switch/delete` | 旧子命令，0.2.x 移除 | ⚠️ deprecated | 公开模式只有 `automatic` 和 `disabled`。`disabled` 保留隐式版本检查和更新提示，但绝不静默安装；显式 `arkcli update` 和 `arkcli update --check` 也始终可用。缺失 `update.mode` 和历史配置中的 `notify` 对外都按 `disabled` 处理，历史配置中的 `notify` 继续按 `disabled` 兼容读取，但不得再建议用户设置 `notify`。 Windows、macOS、Linux 的 fail-closed transaction 与六个产品/平台生产 gate 均已开启。stable 全局 npm postinstall 会将安装后版本与 registry 当前 `latest` 比较：非 latest 持久化 `disabled`；当前 latest 不改 mode，已有 `automatic` 时为新 exact install 换发授权。postinstall 不立即执行版本替换。 ### 新安装 enrollment 只有能证明“此前没有产品状态目录”且安装版本等于 registry `latest` 的 stable 全局 npm 新安装，才默认写入 `automatic` 并创建绑定当前 exact install 的惰性 pending evidence： 1. 第一次成功的、符合安全条件的人工业务命令在一个策略事务中完成 pending → grace → active。 2. 重新检查确认 exact-install consent 已 active 后，该 invocation 即可调度 automatic patch 更新。 由 npm `postinstall` 启动的全部 CLI 进程（包括其中的 `+connect`）以及用户手工执行的 `+connect` 都不消耗 enrollment、不做隐式版本检查，也不调度 automatic。AI Skill、CI、非 TTY、Client Preview、`config`、`update` 和内部维护命令同样不消耗 enrollment，也不调度 automatic。更新成功后，下一次成功的人工业务命令只在 stderr 显示一次 `旧版本 -> 新版本` 结果，不修改 stdout 或业务退出码。 当前生产 automatic 按明确产品策略关闭 24/48/72 小时与 10%/50%/100% cohort admission；原 rollout 实现与回归测试仍保留，在线 Probe 仍要求两次独立观测。普通 automatic 仍须满足 exact consent、实时 registry target/SRI/tarball 校验、reservation、退避和全部 staged-apply 安全边界。 每次 npm 重装都不得沿用旧 exact-install receipt。若安装版本等于当前 `latest`，不改既有 mode：`automatic` 换发新 receipt，`disabled` / 历史 `notify` 仍保持关闭。若安装版本不等于 `latest`，持久化 `disabled`。registry 失败时不改 mode、不发新 receipt；`--ignore-scripts` 也不会完成对齐。从非 latest 版本恢复时，先安装 latest，再明确执行 `arkcli config set update.mode automatic`。长期锁定版本使用： ```bash arkcli config set update.mode disabled npm i @volcengine/ark-cli@<exact-version> -g --registry https://registry.npmjs.org ``` 为避免 registry 不可用时的不确定，需要确定锁版时仍建议先执行 `arkcli config set update.mode disabled` 再安装精确版本。`disabled` 位于 `$HOME/.arkcli/config.yaml`，安装 `@latest` 也不会自动改回 `automatic`。`arkcli config reset` 会尽力撤销 exact consent 后再清配置。npm 解析 `@latest` 与 postinstall 查询之间恰好发新版时，存在极小概率误判为非 latest 的竞态。 ## 参考 - [`references/arkcli-config-init.md`](references/arkcli-config-init.md) - [`references/arkcli-config-profile.md`](references/arkcli-config-profile.md) - [`references/evals.md`](references/evals.md)