@volcengine/ark-cli-darwin-arm64 0.0.0-stage → 1.0.46-prerelease.dc921200a42d

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

@@ -0,0 +1,54 @@
+# config profile (deprecated 兼容映射)
+
+> **0.1.16 起 profile 写操作迁移到 `arkcli profile` 子树**：`config list/show/switch/delete` 已 deprecated（仍可用，0.2.x 删除）。本文档保留旧命令与新命令的对照，方便 Agent 在排障老脚本时识别。
+
+## 常规准入与 Profile 管理的边界
+
+普通 CLI 只查当前身份/Profile 时，用 `arkcli auth status --format json`、`arkcli auth whoami --format json`；默认模型和路由看 `arkcli resources list --modality <text|image|video> --format json`。先遵守 shared 的宿主认证边界；禁止额外认证探测的宿主不能照搬这些认证命令。
+
+`profile show/list/keys list` 会尝试同步远端 Key，可能回写本地库存、清空失效 Key 或改选默认 Key。它们的脱敏输出不代表无配置副作用。用户只要求 Chat/Gen 准入、或明确“不改配置/Key”时，不执行它们，也不以旧 `config show/list` 代替；缺失信息如实报告未知。
+
+## 显式 Profile 管理用法
+
+以下 show/list 只用于用户明确要求的 Profile 详情、清单或管理任务，并先说明上述同步影响；切换、删除、重置仍需明确授权。
+
+```bash
+# 列出所有 profile（含 type/region/project/owner_trn 切面）
+arkcli profile list --format json
+
+# 查看当前 / 指定 profile
+arkcli profile show --format json
+arkcli profile show --profile default --format json
+
+# 切换默认 profile
+arkcli profile use default --format json
+
+# 删除单个 profile
+arkcli profile delete default --format json
+
+# 重置整个本地配置文件（保留，超出单 profile 范围）
+arkcli config reset --format json
+
+# 更新策略（只允许 update.mode）
+arkcli config set update.mode automatic
+arkcli config set update.mode disabled
+```
+
+公开模式只有 `automatic` 和 `disabled`。`disabled` 关闭静默安装，但保留隐式版本检查、更新提示以及显式 `arkcli update` / `arkcli update --check`。历史 YAML 中的 `notify` 仅作为兼容输入读取，不再是可设置选项。
+
+对应 production gate 开启后，真正全新且安装版本等于 registry `latest` 的 stable 全局 npm 安装会先进入与 exact install 绑定的惰性 enrollment；第一次成功的、符合安全条件的人工业务命令会完成 grace 与 consent，重新校验 active 后即可调度。重装为当前 latest 时不改 mode，已有 automatic 会换发 exact receipt；非 latest 则持久化 disabled。
+
+长期锁定版本仍建议先执行 `arkcli config set update.mode disabled`，再安装精确 npm 版本；非 latest 安装在成功确认 registry 后也会持久化 `disabled`。安装 `@latest` 本身不会将 `disabled` 改回 `automatic`；恢复时先安装 latest，再显式设置 automatic。配置位于 `$HOME/.arkcli/config.yaml`。
+
+## 旧命令兼容映射
+
+| 旧（deprecated） | 新 |
+|------|------|
+| `arkcli config list` | `arkcli profile list` |
+| `arkcli config show` | `arkcli profile show` |
+| `arkcli config switch <name>` | `arkcli profile use <name>` |
+| `arkcli config delete <name>` | `arkcli profile delete <name>` |
+| `arkcli config init ...` | `arkcli profile create --type=...`（行为更明确：必须指定 type） |
+| `arkcli config reset` | 仍可用（清整个本地配置文件，无替代） |
+
+> **为什么迁移**：profile 现在承载 `type / region / project / owner_trn / available_api_keys` 五个切面，命令路径 `arkcli profile <verb>` 比 `arkcli config <verb>` 更精确（config 还包括 reset、`update.mode` 和全局排障）。

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

@@ -0,0 +1,87 @@
+# arkcli-config 最小评估用例
+
+目标：验证本 skill 在"该唤起/不该唤起/排错/写操作 guard"四个维度上行为稳定。
+
+## 1) 该唤起（Trigger）
+
+输入（用户说法）：
+
+- "为什么我的命令打到了错误环境/错误 base URL？"
+- "我想切换默认 profile"
+- "我怀疑 `--profile` / `ARK_PROFILE` 覆盖错了，帮我确认当前生效配置"
+- "我要初始化一个 profile（base-url/region/api-key）"
+
+期望行为：
+
+- 常规准入使用 `arkcli auth status --format json`、`arkcli auth whoami --format json` 和 Resources Skill；宿主禁止额外认证探测时沿宿主协议，不自行探测。
+- `profile show/list/keys list` 可能同步并回写 Key，不能当作无配置副作用的查询；用户明确要求 Profile 管理时先说明影响。
+- 解释实际命中的配置优先级，Profile 选择包括 first-platform fallback；区分持久切面与临时 override。评分看真实命令、状态与证据，不要求回答复述固定字面量。
+- 只有在用户确认后才执行写操作（`init/switch/delete/reset`）
+
+## 2) 不该唤起（Anti-trigger）
+
+输入（用户说法）：
+
+- "我 401 / 未登录 / 鉴权失败"
+- "我要列出模型/对话试用/生成图片/部署 endpoint/看用量"
+
+期望行为：
+
+- 认证问题优先 `arkcli auth status`，必要时转 [`../../arkcli-auth/SKILL.md`](../../arkcli-auth/SKILL.md)
+- 业务目标路由到对应产品命令与 skill（`models/+chat/+gen/+deploy/usage`），不要停在 config
+
+## 3) 写操作守卫（Guard）
+
+输入（用户说法）：
+
+- "帮我清理配置/删掉 profile/重置配置"
+
+期望行为：
+
+- 在执行 `delete/reset` 前复述影响范围并征得确认
+- 提醒：`arkcli config reset` 删除 `config.yaml/config.json`，不会清理 `$HOME/.arkcli/.env`（token/AKSK）或 identity store；需要清理凭证应走 `arkcli auth logout`
+
+## 4) 无业务副作用的命令面检查
+
+先检查帮助，不在真实登录目录中创建、切换、删除或刷新 Profile。集成用例由 Eval Kit
+提供独立夹具、明确的状态目录隔离与恢复，不能只替换一个 HOME 就声称真实凭证不会被触及。
+
+```bash
+arkcli auth whoami --help
+arkcli resources list --help
+arkcli profile show --help
+arkcli profile list --help
+arkcli profile use --help
+arkcli config reset --help
+```
+
+组合回归输入：“当前默认聊天模型是什么，现在能不能用？只查，不发送请求、不改任何配置或 Key。”
+要求 Agent 实际加载 Config/Resources/shared，查询当前上下文与默认资源，不执行可能回写 Key
+的 Profile 命令，也不发送 Chat/Gen。回答必须区分已查到的默认/兼容信息与尚未验证的实际调用、
+权限、额度；不能凭 exit=0、Key Active 或 invocable 就声称全部可用。
+
+## 5) 更新策略
+
+输入（用户说法）：
+
+- “以后自动更新 arkcli”
+- “关闭 arkcli 的静默自动更新”
+
+期望行为：
+
+- 明确这是持久化配置写操作，分别执行 `arkcli config set update.mode automatic` 或 `arkcli config set update.mode disabled`。
+- 说明公开模式只有 `automatic` 和 `disabled`；缺失配置及历史 `notify` 对外均按 `disabled` 处理。
+- 当前六个生产 gate 均已开启；用户显式执行 `automatic` 时应为当前 exact install 建立 consent 并持久化配置，不得把仅写配置冒充为授权成功。
+- `disabled` 关闭静默自动安装，但保留隐式版本检查、更新提示以及显式 `arkcli update` / `arkcli update --check`。
+- 不得再建议旧 `notify` setter；历史 YAML 中的 `notify` 只作为兼容输入读取。
+
+当前默认 enrollment 还必须满足：
+
+- 只有真正全新且安装版本等于 registry `latest` 的 stable 全局 npm 安装默认进入 `fresh_pending`。
+- 第一次成功的、符合安全条件的人工业务命令会在同一策略事务完成 grace 与 exact consent；重新校验 active 后该 invocation 即可调度。
+- AI Skill、CI、非 TTY、Preview、config/update 与内部维护命令不消耗宽限、不调度。
+- 重装后版本等于 registry `latest` 时不改 mode：已有 `automatic` 换发 exact receipt，已有 `disabled` / `notify` 保持关闭；不等时持久化 `disabled`。
+- registry 失败不改 mode、不发新 receipt；`--ignore-scripts` 不完成对齐。恢复时先安装 latest，再显式设置 `automatic`。
+- 长期锁定仍建议先执行 `arkcli config set update.mode disabled`，再安装精确版本；安装 `@latest` 不会自动重开 automatic。
+- automatic 成功结果只在下一次人工业务命令的 stderr 显示一次，不得污染 stdout 或改变业务退出码。
+- 不用通用 YAML 编辑或定时任务替代产品命令。

package/skills/arkcli-connect/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: arkcli-connect
+version: 1.3.0
+description: "arkcli +connect：将 arkcli 内嵌的 AI skills 安装到本机检测到的所有 AI Agent 中，支持安装、列出已支持 agent、卸载。当用户需要将 arkcli 能力同步到 Claude Code 等本地 agent 时使用。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli +connect --help"
+---
+
+# arkcli +connect
+
+**前置：** 先用 Read 读 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) 获取共享安全规则。
+
+把 arkcli 内嵌的 skills 同步到本机 AI Agent（Claude Code、Cursor、Gemini CLI 等）的 skills 目录。**纯本地文件操作，不需要认证。**
+
+## 调用形态（子命令仍只有这三个）
+
+| 调用 | 说明 |
+|------|------|
+| `arkcli +connect` | 默认行为：安装到所有检测到的 agent |
+| `arkcli +connect --path <skills-dir>` | 安装到指定的本地 skills 目录（项目级 / 自定义路径），不扫描 agent、不改全局目录 |
+| `arkcli +connect list` | 只读：列出支持的 agent 与检测状态 |
+| `arkcli +connect uninstall` | 从所有 agent 删除 ownership manifest 记录且未被用户修改的 ArkCLI skills |
+| `arkcli +connect uninstall --path <skills-dir>` | 只从指定目录删除 ownership manifest 记录且未被用户修改的 ArkCLI skills |
+| `arkcli +connect uninstall --purge-prefix` | 显式破坏性清理：删除所有检测目录中的 `ark-` / `arkcli-` 前缀目录或软链 |
+| `arkcli +connect uninstall --path <skills-dir> --purge-prefix` | 只在指定目录执行显式全前缀清理 |
+
+> ⚠️ **没有** `+connect install` / `+connect setup` / `+connect sync` / `+connect remove` 等子命令；安装就是默认行为，不要凭直觉补 install。`--path` 是 flag，不是子命令。
+
+## 路由判断
+
+- 用户想把 arkcli skills 装进本地 agent → 跑 `arkcli +connect`，建议先 `arkcli +connect list` 预检
+- 用户想把 arkcli skills 装进某个 repo/project 的本地 skills 目录 → 跑 `arkcli +connect --path <skills-dir>`，例如 `arkcli +connect --path .claude/skills`；`--path` 接收具体 skills 目录，不是项目根目录
+- 用户只想知道支持哪些 agent → **只**跑 `arkcli +connect list`，**不要**顺手装
+- 用户想清理 ArkCLI 自己安装的 skills → `arkcli +connect uninstall`，仍需先确认 agent 范围；默认只删 manifest 记录且摘要未变化的 managed skills
+- 用户想清理 repo/project 本地 skills 目录里的 managed skills → `arkcli +connect uninstall --path <skills-dir>`
+- 用户明确要求连历史未知条目一起全清 → 解释风险并在确认后使用 `--purge-prefix`；它会删除用户手工维护的同前缀目录或软链
+
+## 反触发（应该路由到别处）
+
+- 401 / 鉴权失败 / "auth login 报错" → 走 `arkcli-auth`，**与 +connect 无关**（+connect 不需要认证）
+- profile / base-url / region 配置问题 → 走 `arkcli-config`
+- 想生成代码示例、调用模型 → 走 `arkcli-code-example` / `arkcli-chat`
+
+## 关键事实（写在 SKILL.md 内，避免 Agent 幻觉）
+
+- 安装走 **authoritative catalog update**：`.arkcli-managed-skills.json` 记录 ArkCLI 上次写入的精确名称、产品和目录摘要；每次安装都会用当前 CLI catalog 覆盖所有同名 Skill，并删除 manifest 中已退出当前 catalog 的旧 Skill
+- 当前 catalog 的精确官方名称具有最高优先级：无论现有同名目录是否被 manifest 记录、摘要是否变化、是否由用户手改，都会被当前版本覆盖；需要保留自定义内容时必须复制到不同名称
+- 不在当前 catalog、也未被旧 manifest 管理的其他目录或软链不会进入安装事务，即使名称带 `ark-` / `arkcli-` 前缀也默认保留
+- 目录摘要仍用于 provenance 和默认卸载保护，不再阻断安装升级；安装在 staging/backup 中完成并保持事务性，失败时回滚，不产生半套新旧 Skills
+- 历史 BytePlus candidate 的 `arkcli-managed-agent` 若存在于旧 manifest，会作为退出 catalog 的旧 Skill 删除；canonical `arkcli-agent` 作为当前官方名称安装。这是统一 catalog 规则的结果，不再需要产品特判
+- `--path <skills-dir>` 是隔离安装：相对路径按当前 `PWD` 解析，绝对路径原样使用；只在该目录收敛当前 catalog 和旧 manifest，并保留其他不同名条目。它**不**扫描 agent、不清 legacy 私有目录、不删除 `byted-ark-*` conflicting skills、不 patch Claude/opencode 等 harness 配置
+- **默认还会移除两个抢路由的第三方生成 skill**：`byted-ark-seedance-skill` / `byted-ark-seedream-skill`（按**精确名**匹配，不误伤其他 `byted-*`）。原因：它们的 description 带"推荐优先"+逐字触发词，会在"生图/生视频"意图上压过 `arkcli +gen`，且自身要独立 `ark-` API Key，赢了路由反而失败。移除后生成类意图统一落 `arkcli +gen`（用登录态 profile 凭证，跟视频一样能成）。日志显式打印 `removed N conflicting (...)`，非静默。要保留它们：`arkcli +connect --keep-conflicting`
+- `uninstall` 默认只删除 ownership manifest 中记录且摘要未变化的 managed skills；只有显式 `--purge-prefix` 才恢复旧式全前缀删除
+- 多个 agent 共享同一个 skills 目录时，按路径**自动去重**，只更新一次 ownership manifest
+- **多路径扫描特例**：Codex 同时扫 `~/.codex/skills`(CODEX_HOME) 和共享的 `~/.agents/skills`；Pi 同时扫 `~/.pi/agent/skills` 和共享的 `~/.agents/skills`。若两处都装 arkcli，会把每个 skill 列**两遍**或报同名冲突。因此 `+connect` 把 Codex / Pi 的 skill 都装进共享的 `~/.agents/skills`(与 cline/warp 去重成一份)，靠 `~/.codex` / `~/.pi/agent` 目录存在来检出对应 agent；legacy 私有目录只删除带旧 manifest 的 owned Skills，或与当前官方树逐字节一致的迁移副本，未知/修改过的同前缀条目保留
+- `list` 只扫描本地文件系统，不写入、不联网、不需要认证
+- 支持的 agent 列表硬编码在二进制里，新增 agent 需要重新编译
+- `npm install` arkcli 时 postinstall **会自动跑 `+connect`**：在能打开 `/dev/tty` 的交互式终端上按 authoritative catalog 规则更新检测到的所有 agent，无需用户确认；成功时只输出唯一安装目标数、对应 Agent 名称和安全卸载命令 `arkcli +connect uninstall`，不会逐目录展开进度明细。**下载完成后无论是否检测到 agent，都会输出当前编译产品的登录 SOP**；产品文案按 locale 输出。它不会执行 `--purge-prefix`。CI / 非交互终端 / 拿不到 `/dev/tty` 一律静默跳过；想完全静音可设 `ARKCLI_SKIP_POSTINSTALL=1`
+
+详细行为、错误码、输出示例见 [`references/arkcli-connect.md`](references/arkcli-connect.md)。

package/skills/arkcli-connect/references/arkcli-connect.md

@@ -0,0 +1,129 @@
+# +connect 详细参考
+
+> **前置：** 先读 [`../SKILL.md`](../SKILL.md)。本文件只补充上面没写的细节。
+
+## Agent 必读要点（不要跳过）
+
+1. 子命令穷举：`(空)` / `list` / `uninstall`。**不存在** install / setup / sync / remove。`--path` 是 flag，不是子命令。
+2. 默认行为 = 安装；不要写 `arkcli +connect install`。
+3. 安装走 **authoritative catalog update**：当前 CLI catalog 的每个精确名称一律覆盖现有同名目录；旧 manifest 中已退出 catalog 的名称一律删除。
+4. 其他不同名且从未被 manifest 管理的目录默认保留。目录摘要不阻断安装，但 `uninstall` 默认仍只删除摘要未变化的 managed skills。
+5. `--path <skills-dir>` 表示"指定的 skills 目录"，不是项目根目录。相对路径按当前 `PWD` 解析，绝对路径原样使用。
+6. `--path` 模式是隔离操作：只在该目录收敛当前 catalog 与旧 manifest，并保留其他不同名条目；不扫描 agent、不清 legacy 私有目录、不删除 `byted-ark-*` conflicting skills、不 patch Claude/opencode 等 harness 配置。
+7. `list` 是只读，不需要认证；其他子命令也不需要认证。
+8. 多个 agent 共享同一 skills 目录时，按路径自动去重，只更新一次。Codex / Pi 统一安装到 `~/.agents/skills`；legacy 私有目录只删除带旧 manifest 的 owned Skills，或与当前官方树逐字节一致的迁移副本，未知/修改过的同前缀条目保留。
+9. `npm install` 触发的 postinstall 在交互式终端上**自动**跑 `+connect`，不再问 `[y/N]`；CI / 非交互终端静默跳过；详见下文「postinstall 行为」。
+
+## 行为细节
+
+1. 扫描 40+ 个已知 agent 的 skills 目录路径（如 `~/.claude/skills/`、`~/.cursor/skills/`）
+2. 父目录存在即判定为"已检测到"
+3. 对每个检测到的 agent：先把当前 catalog 写入隐藏 staging，再把当前 catalog 名称和旧 manifest 名称一起备份，原子收敛 Skills 和 manifest；任一步失败都回滚
+4. 按 `skillsDir` 去重
+
+共享安装目录只计为一个目标；同时存在 Codex / Pi 这类 agent 自己的检测目录时，
+展示名称优先使用该独立信号，避免仅因 `~/.agents` 已存在而把目标误标成 Cline。
+
+当前 catalog 是安装后的权威状态：同名目录无论来源和内容都由当前版本覆盖，旧
+manifest 记录但已退出 catalog 的名称会删除。其他既不在当前 catalog、也不在旧
+manifest 的不同名目录保持不变。旧 BytePlus `arkcli-managed-agent` 因此自然退休，
+canonical `arkcli-agent` 正常安装，不需要单独的产品或摘要特判。
+
+`--path` 模式跳过上面的 agent 扫描：
+
+1. 解析 `<skills-dir>`：相对路径基于当前 `PWD`，绝对路径保持原样
+2. 创建目标目录
+3. 覆盖当前 catalog 的全部精确同名目录，删除旧 manifest 中已退出 catalog 的名称；其他不同名条目保持不动
+4. 把当前 Skills 写入目标目录，并原子更新 `.arkcli-managed-skills.json`
+
+示例：
+
+```bash
+cd /path/to/repo
+arkcli +connect --path .claude/skills
+arkcli +connect uninstall --path .claude/skills
+```
+
+落盘结构：
+
+```text
+/path/to/repo/.claude/skills/arkcli-chat/SKILL.md
+/path/to/repo/.claude/skills/arkcli-gen/SKILL.md
+/path/to/repo/.claude/skills/.arkcli-managed-skills.json
+...
+```
+
+## 输出示例
+
+手动运行 `arkcli +connect`：
+```
+Detected N agent(s): claude-code cursor gemini-cli
+Installing M skill(s)...
+
+  updated 3 managed + installed M → claude-code (~/.claude/skills)
+  installed M → cursor (~/.cursor/skills)
+
+Done. Installed M skill(s) × N agent(s) = total.
+```
+
+npm postinstall 自动安装：
+```
+✓ 已将 ArkCLI Skills 安装到 N 个 AI Agent（claude-code/ codex/ opencode）。
+  如需移除 ArkCLI 安装的 Skills：arkcli +connect uninstall
+```
+
+安装到指定目录：
+```
+Installing M skill(s) to /path/to/repo/.claude/skills...
+
+  updated K managed + installed M → /path/to/repo/.claude/skills
+
+Done. Installed M skill(s).
+```
+
+卸载：
+```
+Uninstalling skills from N agent(s)...
+
+  removed K skill(s) from claude-code (~/.claude/skills)
+
+Done. Removed total skill(s) total.
+```
+
+从指定目录卸载：
+```
+  removed K skill(s) from /path/to/repo/.claude/skills
+
+Done. Removed K skill(s) total.
+```
+
+注意：默认卸载里的 K 只包含 manifest 记录且摘要未变化的 managed Skills。只有用户明确确认并追加 `--purge-prefix` 时，才删除目标中的所有 `ark-` / `arkcli-` 前缀目录或软链。
+
+## postinstall 行为
+
+`npm install` arkcli 时触发 `scripts/postinstall.js`，该脚本：
+
+1. 检查逃生阀：`ARKCLI_SKIP_POSTINSTALL=1` 或 `CI=true` 直接跳过
+2. 校验 platform/arch + binary 是否存在；不在支持名单或文件缺失（例如 `--ignore-scripts`）静默跳过
+3. 尝试打开 `/dev/tty` 双向 fd；拿不到（管道、Windows 等无 controlling tty 场景）静默跳过
+4. 直接以 `+connect` 启动平台对应的 binary，stdout/stderr 接到 tty；成功时只展示唯一安装目标数、对应 Agent 名称和安全卸载命令，不逐目录展开进度明细。自动路径使用同一 authoritative catalog 事务，绝不隐式启用 `--purge-prefix`
+5. 任何失败一律 `exit 0`，不阻断 npm 主链；想完全静音设 `ARKCLI_SKIP_POSTINSTALL=1`
+
+## 常见提示与错误
+
+| 消息 | 类型 | 原因 | 处理 |
+|------|------|------|------|
+| `No AI agents detected` | warning（正常退出） | 本机没有支持的 agent | 先装一个 agent（如 Claude Code）再跑 `+connect` |
+| `No skills embedded in this binary` | warning | 编译时未嵌入 skills | `make build` 重新编译 |
+| `embedded skills filesystem not initialised` | error | 内嵌文件系统未初始化 | 重新编译二进制 |
+| `mkdir ... permission denied` | error | skills 目录无写权限 | 检查目标目录权限 |
+| `copy ...: not a directory` | error | 指定目录中存在同名普通文件，无法覆盖成 skill 目录 | 手动移走该文件后重试 |
+| `managed Skill ... was modified` | uninstall error | 默认卸载发现目录摘要已变化 | 默认保留该目录；只有明确要求全前缀清理时才确认使用 `--purge-prefix` |
+
+`arkcli-managed-agent` 不是当前可安装 Skill 名。若它由旧 manifest 管理，下一次安装
+会按统一 catalog 收敛规则删除它，并在 manifest 和磁盘只保留 `arkcli-agent`。
+
+## 参考
+
+- [arkcli-connect](../SKILL.md) -- skill 入口
+- [arkcli-shared](../../arkcli-shared/SKILL.md) -- 共享认证与全局参数

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

@@ -0,0 +1,117 @@
+# arkcli-connect 最小评估用例
+
+目标：验证本 skill 在「该唤起 / 项目级安装 / 不该唤起 / 子命令分流 / 破坏性守卫 / catalog 收敛」六个维度上行为稳定，并且不让 Agent 幻觉出不存在的 `+connect install / setup / sync / remove` 子命令。
+
+## 1) 该唤起（Trigger）— 安装
+
+输入（用户说法）：
+
+- "刚装完 arkcli，想把 skills 同步到本机的 Claude Code"
+- "把 arkcli 内嵌的 skills 装到我电脑上的所有 AI agent"
+
+期望行为：
+
+- 路由到 `arkcli-connect`
+- 推荐 `arkcli +connect`（默认行为就是安装；**没有** `+connect install` 子命令）
+- 建议先 `arkcli +connect list` 做预检
+- 说明当前 CLI catalog 的精确官方名称会覆盖所有现有同名目录，不受 owner 或摘要影响
+- 说明不在当前 catalog、也未被旧 manifest 管理的其他不同名目录会保留
+- **不要**给出 `arkcli +connect uninstall`
+
+## 2) 该唤起（Trigger）— 项目级 / 自定义 skills 目录安装
+
+输入：
+
+- "把 arkcli skills 安装到当前 repo 的 `.claude/skills`，不要污染全局 agent 目录"
+- "我有一个项目级 skills 目录，想让 arkcli 只写那里"
+
+期望行为：
+
+- 路由到 `arkcli-connect`
+- 推荐 `arkcli +connect --path .claude/skills`
+- 说明 `--path` 接收的是具体 skills 目录，不是项目根目录
+- 说明相对路径基于当前 `PWD`，绝对路径也支持
+- 说明不会扫描 / 修改全局 agent 目录，也不会自动 patch Claude / opencode 等 harness 配置
+- **不要**给出 `arkcli +connect install`
+
+## 3) 该唤起（Trigger）— 仅查看支持范围
+
+输入：
+
+- "我这台机器上 arkcli 能识别出哪些 agent？我不想现在就装东西"
+
+期望行为：
+
+- 路由到 `arkcli-connect`
+- 只给出 `arkcli +connect list`
+- 解释 list 是只读、不需要认证、不写入文件系统
+- **不要**顺手 install 或 uninstall
+
+## 4) 破坏性守卫（Guard）— 卸载
+
+输入：
+
+- "把之前用 +connect 装过的 skills 从所有 agent 里清理掉"
+
+期望行为：
+
+- 路由到 `arkcli-connect`
+- 推荐 `arkcli +connect uninstall`，但先确认作用于哪些 agent
+- 说明默认只删除 ownership manifest 记录且摘要未变化的 managed Skills，用户自管同前缀条目保持不动
+- 只有用户明确要求清理全部历史同前缀条目时，才在二次确认后给出 `arkcli +connect uninstall --purge-prefix`
+- 建议先 `arkcli +connect list` 看清范围
+- 不要直接执行（破坏性）
+
+## 5) 不该唤起（Anti-trigger）— 401/鉴权失败
+
+输入：
+
+- "我跑 arkcli 业务命令报 401，是不是 +connect 没装好？"
+- "auth login 失败"
+
+期望行为：
+
+- 路由到 `arkcli-auth`，**不要**走 `+connect`
+- 明确说明：`+connect` 是本地文件系统操作，不需要认证；与 401 无关
+- 先 `arkcli auth status`，必要时 `arkcli auth login`
+
+## 6) Agent 行为反幻觉清单（重点）
+
+下列子命令**不存在**，任何评测里 Agent 给出都视为失分：
+
+- `arkcli +connect install`
+- `arkcli +connect install --agent <name>`
+- `arkcli +connect setup`
+- `arkcli +connect sync`
+- `arkcli +connect remove`
+
+允许的子命令穷举：`(空)` / `list` / `uninstall`，仅此三种。
+
+`--path` 是允许的 flag：
+
+- `arkcli +connect --path .claude/skills`
+- `arkcli +connect uninstall --path .claude/skills`
+- `arkcli +connect uninstall --purge-prefix`
+- `arkcli +connect uninstall --path .claude/skills --purge-prefix`
+
+## 7) 配套机器评测
+
+收敛评测：
+
+- 当前 catalog 中的官方 Skill 即使未被 manifest 管理或已被用户修改，也必须被当前版本覆盖
+- 旧 manifest 管理、但已退出当前 catalog 的 Skill 即使被用户修改，也必须事务性删除
+- 历史 `arkcli-managed-agent` 应按上一条自然退休，当前 `arkcli-agent` 被安装并认领，不使用 BytePlus 产品特判
+- 不在当前 catalog、也未被旧 manifest 管理的其他 `ark-` / `arkcli-` 目录必须保持不变
+- 覆盖、退休和 manifest 更新必须同事务提交；故障注入后不得留下半套新旧目录
+
+机器评测资产位于 `tests/skills/arkcli-connect/`，复跑：
+
+```bash
+cd skill-creator
+python3 -m scripts.run_arkcli_skill_benchmark \
+  --skill-path ../skills/arkcli-connect \
+  --workspace /tmp/arkcli-connect-bench \
+  --iteration 1 \
+  --runs-per-config 2 \
+  --runtime claude
+```

package/skills/arkcli-custommodel/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: arkcli-custommodel
+version: 1.0.1
+description: "arkcli 自定义模型仓库管理：从 TOS 导入自定义模型、查询/筛选自定义模型、查看详情、改名、删除、查询可用量化模式、量化已就绪的模型。任何提到自定义模型 ID（`cm-*`）的管理、部署准备，或要求用 `cm-*` 直接对话/推理/试效果的边界判断，都必须使用本 skill。注意：查询火山**公共基础模型**（doubao 等 foundation models）走 arkcli-models；本 skill 只管账号下的自定义模型仓库。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli models custommodel --help"
+---
+
+# arkcli models custommodel
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证闸门、配置排查与共享安全规则**
+**CRITICAL — 所有 `models custommodel` 命令在执行之前，务必先用 Read 工具读取其对应的 reference 文档，禁止直接盲目调用命令。**
+**CRITICAL — 写操作（upload / update / delete / quantize）必须先确认用户意图。删除前必须确认是否还有 endpoint 引用。**
+
+## 守卫与使用原则
+
+- 自定义模型相关需求优先使用 `arkcli models custommodel ...`
+- 这些命令虽然是标准 CLI 类型，但实现入口仍然来自 `shortcuts/models/`
+- 只有产品命令无法覆盖时，才回退到 [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md)
+- 本 skill 不是基础模型查询入口；基础模型目录查询转 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md)
+- 写操作和异步任务必须把影响范围、轮询方式和后续动作串起来，不要停在单条命令
+
+## 适用场景
+
+- 把训练好/微调好的权重从 veTOS 导入到 ARK 自定义模型
+- 查询账号下已有的自定义模型（"我的自定义模型有哪些 / 状态如何"）
+- 查看自定义模型详情、产物形态、活跃 endpoint 引用
+- 修改自定义模型展示名或描述
+- 删除不再使用的自定义模型
+- 把已 `ready` 的自定义模型量化，准备给 `+deploy` 当目标
+
+## 反唤起信号
+
+- 找官方基础模型 → 用 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) 的 `search/list/get`
+- 直接调用自定义模型推理 → 必须先 `+deploy`，再走 `+chat` / `+gen`
+- 触发模型微调任务（customization job 本身）→ 转 [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md)
+- **从精调任务的 step（`global_step_N`）注册成 `cm-`**(=「导出训练产物」)→ 转 [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md) 的 `arkcli train finetune artifacts list / export`，**不要**用本 skill 的 `upload`(那是给"用户自己的 TOS 文件"用的,后端 Action `UploadModel`;mcj 输出走 `CreateCustomModel`,完全不同的 API)
+- 已经拿到 endpoint-id 后想管理 endpoint → 转 [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md)
+
+## `cm-*` 直接推理边界
+
+- 用户要求“用 `cm-*` 直接对话/推理/试效果”时也必须加载本 skill。明确说明 `cm-*` 是自定义模型资源 ID，不能直接传给 `+chat` / `+gen`；推理前需要单独获得或部署 Endpoint。
+- 该请求本身不授权部署、查询账号下 Endpoint 或发起推理。未经用户继续授权，不执行 `arkcli +deploy`、`arkcli +chat`、`arkcli infer endpoint list`，也不拼接 `jq` 等扫描方案。
+- 只说明边界和下一步选择；用户明确要求继续部署后，才转 [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md) 并遵守其确认流程。
+
+## 核心概念
+
+- 本 skill 统一把 `arkcli models custommodel ...` 管理的资源称为**自定义模型**（CustomModel，ID 形如 `cm-xxxxx`）；它与 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) 中 `search/list/get` 操作的官方基础模型（FoundationModel）是**两套独立资源**
+- 自定义模型来源有两类：
+  - `import` —— 用户从 TOS 上传权重导入(本 skill `upload` 命令,走 `UploadModel` API)
+  - `customization` —— 通过模型微调任务产出(走 [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md) 的 `train finetune artifacts export`,**底层是另一个 OpenAPI Action `CreateCustomModel`**,跟 `upload` 不互通)
+- 生命周期状态机：`preparation → processing → ready`（成功）或 `failed`；导出场景另有 `exporting` / `exportfailed`
+- 量化是单独流程：先 `available-quantizations <id>` 查可用模式，并查看 `supported_inference_types_by_quantization` 预判每种量化方式支持的部署/付费形态；再 `quantize <id> --quantization <mode>` 提交量化任务，结果是一个**独立的新 cm-xxxxx**。源模型、量化结果模型、最终部署出来的 endpoint 是三类不同资源，不能混用 ID
+- 自定义模型 ID（`cm-xxxxx`）**不是** `<name>-<primary_version>` 形式，**不能直接作为 `+chat` / `+gen` 的 `--model`**；必须先通过 `arkcli +deploy` 获得 endpoint，拿 `ep-xxx` 才能调用推理。若该自定义模型已有 Running Endpoint，`+deploy` 会直接复用已有 endpoint
+
+## 快速决策
+
+- 用户问"我的自定义模型"：读 [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md)，用 `arkcli models custommodel list --mine`
+- 用户要按名称 / ID / base 模型 display name 模糊查找：读 [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md)，用 `list --search <kw>`
+- 用户已有 `cm-xxxxx` 并要状态 / 详情 / endpoint 引用 / artifact types：读 [`references/arkcli-custommodel-get.md`](references/arkcli-custommodel-get.md)，用 `get`
+- 用户要从 TOS 导入权重：读 [`references/arkcli-custommodel-upload.md`](references/arkcli-custommodel-upload.md)。用户已有 `tos://...` 时确认 TOS URI、base model 和名称；用户还没有 TOS URI 时先引导开通/上传 TOS，不要直接跑 `upload`
+- 用户要改名 / 改描述：读 [`references/arkcli-custommodel-update.md`](references/arkcli-custommodel-update.md)，确认意图后用 `update`
+- 用户要删除：读 [`references/arkcli-custommodel-delete.md`](references/arkcli-custommodel-delete.md)，先查 `active_endpoints`，确认后再执行
+- 用户要量化：先读 [`references/arkcli-custommodel-available-quantizations.md`](references/arkcli-custommodel-available-quantizations.md)，再读 [`references/arkcli-custommodel-quantize.md`](references/arkcli-custommodel-quantize.md)
+
+## 列表参数与输出契约
+
+- `custommodel list --sort-order` 只接受小写 `asc` / `desc`。收到其他值时应把它视为本地参数错误，不要尝试调用接口或改成其他大小写后盲目重试。
+- 使用 `--format table` 或 `--format csv` 时，每个 `result.items[]` 模型是一行；不要把分页响应根对象或 `result` map 当成模型记录。需要保留完整分页元数据时使用 JSON/YAML。
+
+## 部署前的自定义模型目标澄清
+
+仅当用户的最终目标是“把我的自定义模型部署成 Endpoint”、但没有给出唯一 `cm-*` 时执行本节；用户已明确给出 `cm-*` 时跳过。
+
+1. 先执行同范围只读查询：`arkcli models custommodel list --mine --statuses ready --page-all --page-delay 500 --format json`。保留退出码与 stderr，不能把认证、权限或网络失败当作空清单；认证/权限错误按 shared 处理，不扫描凭证或自动切身份。
+2. 候选只能来自本轮完整结构化结果。输出被宿主截断时，先读取工具保存的完整文件；确实没有完整捕获时，允许把同一只读查询的 stdout 重新落盘，stderr 单独保留，再用 `jq` / `sed` 检查 `result.items` 与分页信息。该同范围补查一轮最多执行一次，不循环重试。`jq` 空结果或字段缺失时先核对当前 reference 与原始 JSON，不盲猜字段、不凭记忆补 `cm-*`。分页未取全、补查仍失败或关键字段仍缺失时，说明具体边界并停止；拿全候选前不出选择题，更不执行部署。
+3. 按 0 / 1 / N 收敛：
+   - 0 个：停止，提示用户先 upload、量化或完成精调产物导出。
+   - 1 个：复述该模型的 `id / name / foundation_model / create_time`，将它作为唯一目标转交 `arkcli-deploy`。
+   - N 个：使用宿主提供的结构化选择能力，把每个候选的 `id / name / foundation_model / create_time` 直接列给用户选择；不要在通用 Skill 中写死某个宿主的工具名，也不要额外写死 `Other` 选项。
+4. 唯一目标确定前，不执行 `arkcli +deploy`、`arkcli infer endpoint create` 或 Raw API。目标选择完成后转 `arkcli-deploy`，并继续遵守其写操作确认；选择模型本身不等于授权部署。
+
+## Agent 快速执行顺序
+
+1. 不确定认证状态时，先 `arkcli auth status`
+2. "我的自定义模型"语义：直接 `custommodel list --mine`，**不要套 shared 的 Tags 默认过滤**（custommodel 服务端原生支持 `--mine`）
+3. 上传前必填三项：`--name` / `--base-model <foundation-model-id>` / `--tos tos://<bucket>/<prefix>`；缺任一会被服务端拒
+4. `upload` / `quantize` 是异步任务：返回后用 `custommodel get <id>` 轮询 status，**不要原地循环 upload/quantize**
+5. `quantize` 前必跑 `available-quantizations <id>`：不同 base model 支持的量化模式不同，盲传服务端会拒；若用户关心 token / 模型单元等部署形态，优先看返回里的 `supported_inference_types_by_quantization`
+6. `quantize --dry-run` 只输出本地 `preview.v1`，不会调用 `CreateQuantizedCustomModel`；`steps[].payload` 只描述真实请求字段，不应出现后端 `DryRun`。它不是服务端校验，核对后仍需确认再执行真实量化
+7. `delete` / `update` / `quantize` 是写操作，执行前向用户复述影响范围
+8. `delete` 默认会走 [Y/N] 二次确认；`--yes` 表示跳过本地二确，`--dry-run` 表示只预览不删除。只有用户已经明确确认删除目标和影响范围后，agent 才能把 `--yes` 加到命令里
+9. `get --transform` 是 `custommodel get` 自己的字段白名单，不是全局 GJSON 表达式；要查嵌套路径时不要把它当作全局 `--transform`
+
+## 典型业务链路
+
+### 1. 从 TOS 上传新自定义模型
+
+```
+auth status → custommodel upload --name X --base-model <fm-id> --tos tos://b/p
+            → custommodel get <id>  （轮询直到 status=ready）
+            → custommodel get <id> --transform 'artifact_types'  （看产物形态）
+```
+
+### 2. 量化已就绪的自定义模型
+
+```
+custommodel get <id>  （确认 status=ready）
+        → custommodel available-quantizations <id>  （看支持哪些 mode）
+        → custommodel quantize <id> --quantization <mode> --dry-run
+        → 用户确认量化目标和影响范围
+        → custommodel quantize <id> --quantization <mode>
+        → custommodel get <new-id>  （量化结果是新 cm-xxxxx，再次轮询）
+```
+
+### 3. 准备给 `+deploy` 当目标
+
+```
+custommodel list --mine --statuses ready --page-all --page-delay 500 --format json
+        → 按 0 / 1 / N 澄清唯一 cm-xxxxx
+        → +deploy --model cm-xxxxx ...   （若已有 Running Endpoint 会复用；详见 ../arkcli-deploy/SKILL.md）
+```
+
+### 4. 清理不再使用的自定义模型
+
+```
+custommodel get <id> --transform 'active_endpoints'  （确认无 endpoint 引用）
+        → custommodel delete <id> --dry-run
+        → custommodel delete <id>  （交互二确）或 custommodel delete <id> --yes
+```
+
+## 反模式（agent 必读）
+
+- 不要用 `arkcli models search` / `list` 找自定义模型 —— 那两条只走 FoundationModel 目录，自传模型一律不在里面。要找自传模型用 `custommodel list --search <kw>` 或 `--mine`
+- 不要在 `upload` 之后立刻 `quantize` —— upload 是异步任务，status 经历 `preparation → processing → ready`；先 `custommodel get <id>` 确认 ready，再走 `available-quantizations` → `quantize`
+- 不要给 `quantize` 传一个 `available-quantizations` 没列的 mode —— 不同 base model 支持的量化集合不同，盲传必失败。先 `available-quantizations <id>`，从返回里挑
+- 不要把 `cm-xxxxx` 直接传给 `+chat` / `+gen` 的 `--model` —— 自定义模型必须先通过 `+deploy` 获得 endpoint（`ep-xxx`）才能推理调用；`+deploy` 可能复用已有 Running Endpoint
+- 不要在多个 ready 自定义模型中自行挑一个部署 —— 先按“部署前的自定义模型目标澄清”让用户从本轮实时结果中选择
+- 不要为了自动化主动补 `--yes` —— 没 `--yes` 时 CLI 会走 [Y/N] 二确；只有用户已经确认删除 `cm-xxxxx` 且知道 endpoint 引用风险时才带
+- 不要在 "我的" 语义下走 shared 的 Tags 客户端过滤 —— `custommodel list --mine` 是服务端原生过滤，更准也更省请求
+- 不要密集刷 `get` 来轮询 status —— 推荐间隔 ≥ 10s，否则会被限流
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `arkcli models custommodel list` | 翻页 + 多维过滤 |
+| `arkcli models custommodel get <id>` | 详情 / 轮询 status |
+| `arkcli models custommodel upload` | 从 TOS 导入（异步） |
+| `arkcli models custommodel update <id>` | 改名 / 改描述 |
+| `arkcli models custommodel delete <id> [--yes] [--dry-run]` | 删除（破坏性，不可逆）；默认二确，`--yes` 跳过，`--dry-run` 预览 |
+| `arkcli models custommodel available-quantizations <id>` | 查可用量化模式（quantize 前必跑） |
+| `arkcli models custommodel quantize <id> --quantization <mode> [--dry-run]` | 量化（异步）；`--dry-run` 仅本地预览，不调用后端 |
+
+## 常见降级
+
+- 认证失败：转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md)
+- profile / region 看起来不对：转 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md)
+- 找的是基础模型不是自定义模型：转 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md)
+- 拿到自定义模型后要部署：转 [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md)
+- 产品命令未覆盖（例如想直接触发 customization job）：转 [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md)
+
+## 参考
+
+- [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md)
+- [`references/arkcli-custommodel-get.md`](references/arkcli-custommodel-get.md)
+- [`references/arkcli-custommodel-upload.md`](references/arkcli-custommodel-upload.md)
+- [`references/arkcli-custommodel-update.md`](references/arkcli-custommodel-update.md)
+- [`references/arkcli-custommodel-delete.md`](references/arkcli-custommodel-delete.md)
+- [`references/arkcli-custommodel-available-quantizations.md`](references/arkcli-custommodel-available-quantizations.md)
+- [`references/arkcli-custommodel-quantize.md`](references/arkcli-custommodel-quantize.md)
+- [`references/evals.md`](references/evals.md)
+- [arkcli-models](../arkcli-models/SKILL.md) — 基础模型查询（与本 skill 是两套资源）
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) — 拿到 ready 的自定义模型后部署成 endpoint
+- [arkcli-shared](../arkcli-shared/SKILL.md) — 认证、全局 flag、安全规则