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，其中包含认证闸门、命令选择顺序与共享安全规则 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
• 用户目标是业务功能（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-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。长期锁定版本使用：

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-profile.md
• references/evals.md