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

package/skills/arkcli-shared/references/global-flags.md

@@ -0,0 +1,45 @@
+# 常用全局 flags
+
+> 各命令自身的 flag 以 `arkcli <domain> <verb> --help` 为准。`--region` 与
+> `--project-name` 已从根命令删除；Region/Project 由所选 profile 决定。
+
+| Flag | 作用 |
+|------|------|
+| `--profile` | 选择本次调用的持久上下文；控制面和数据面都可使用 |
+| `--api-key` | 仅覆盖本次数据面调用的 ARK API Key |
+| `--base-url` | 仅覆盖本次数据面调用的 API Base URL |
+| `--env` | 选择控制面环境：`prod` 或 `stg` |
+| `--format` | 输出格式 |
+| `--transform` | 对输出做路径提取 |
+| `--page-all` | 自动翻页 |
+| `--page-limit` | 限制翻页次数 |
+| `--page-delay` | 翻页间隔（ms） |
+| `--debug` | 输出调试信息到 stderr |
+
+`--dry-run` 不是全局 flag。它只由支持 Client Preview 的叶子命令注册；以该
+叶子命令的 `--help` 为准。支持时只在客户端生成 `preview.v1`，不联网、不写文件、
+不启动子进程；不支持时传入该 flag 会明确报错，禁止静默忽略。
+
+## Volc 方舟体验入口
+
+`arkcli exp` 是给人类终端使用的 Volc 方舟体验入口，不是全局 flag。已安装时直接
+启动 `arkexp`；未安装时不再询问，直接从官方 CDN 安装，提示可用
+`arkcli exp uninstall` 卸载后立即启动。交互终端显示安装动画，CI、管道和重定向
+环境降级为静态进度提示。调用可能触发本地安装，AI Agent 只有在用户明确要求打开
+方舟体验时才能执行；卸载必须有用户明确意图。其他产品构建不提供该命令。
+
+## 解析与组合规则
+
+- Profile：`--profile` > `ARK_PROFILE` > `default_profile` > 第一个 platform profile > `"default"`。
+- API Key：`--api-key` > `ARK_API_KEY` > profile > 同 identity store > 产品 `.env` 兼容值。
+- Base URL：`--base-url` > `ARK_BASE_URL` > profile 自定义值 > 按 profile 的 Region/Type 派生 > 产品默认值。
+- `--profile` 选择持久上下文；它不覆盖显式的 `--api-key` / `--base-url`，也不会被临时调用写回。
+- API Key 与 Base URL **不是无条件双向成对**：显式 Base URL 必须有显式 API Key；但显式 API Key 可以和 Endpoint 组成安全调用，CLI 会读取 Endpoint 的权威 region 后派生 platform Base URL。
+- API Key + Base URL + Endpoint 构成 stateless 数据面模式，profile 对连接的影响为 `none`。
+- 只有 API Key + 模型名时，CLI 仅在该 Key 唯一匹配本地 profile 时推导 plan lane；无法唯一匹配就要求补 Base URL/Endpoint 或显式选择 profile，绝不根据 `ark-*` 文本猜 Key 类型。
+- Endpoint 只有在当前/兼容 profile 能提供 paygo Key 时才可直接调用；显式 `--profile` 不兼容时是硬错误，不静默借别的 profile。
+- 控制面或本地命令不消费这两个数据面 flag：显式传入会 fail-fast；环境变量在这些命令中被忽略。
+- `ARK_REGION` / `ARK_PROJECT_NAME` 不再是运行时覆盖入口。修改持久上下文应创建/切换 Profile；火山老状态中的产品 `.env` Project 只作旧 Profile 缺字段时的兼容兜底。
+
+完整的五类 Profile × 三模态矩阵、组合决策和 Client Preview 边界见
+[`execution-context.md`](execution-context.md)。

package/skills/arkcli-shared/references/profile-defaults.md

@@ -0,0 +1,57 @@
+# Profile Resources Default 偏好（含漂移检测与跨模态）
+
+> 本文从 `arkcli-shared` 正文拆出。仅在跑 `+chat` / `+gen` / `+deploy` 且涉及 `--model` / `--endpoint` / 默认资源选择时加载。常规读任务不需要读本文。
+
+profile.yaml 在 `resources.<modality>.default` 字段存用户对每个 modality (text / image / video) 默认资源 ID 的偏好。这是 +chat / +gen / +deploy 行为对齐的基础。
+
+- **platform profile**：默认值是用户已部署的 endpoint id (`ep-xxx`)
+- **agent-plan profile**：默认值是火山预置 model id（如 `doubao-seed-2-0-pro-260215` / `doubao-seedream-5.0-pro` / `doubao-seedance-2.5`）
+- **coding-plan profile**：text modality 用 `ark-code-latest` 这类套餐内文本模型；image / video 借道 platform 数据面 — 字段存的是用户在 platform 上 `+deploy` 出来的 endpoint id（`ep-xxx`），arkcli 会在 `+gen` 时自动把数据面切到 `/api/v3`。不再要求切 profile
+- **`agent-plan-team` profile**：text/image/video 都走 Agent Plan 数据面与套餐模型，凭证为团队席位 Key。
+- **`coding-plan-team` profile**：text 走 Coding Plan 数据面与套餐模型，凭证为团队席位 Key；image/video 切到 platform Endpoint，必须使用**后付费 API Key**，不能复用团队席位 Key。Endpoint default 可以保存在该 profile，但它不等于已经具备可调用凭证。
+
+每次帮用户跑 `+chat` / `+gen`：
+
+- 用户没传 `--model` → CLI 自动 fallback 到 `profile.resources.<modality>.default`
+- 用户传了 `--model <X>`、且 `X` ≠ 当前 default → 见下文"漂移检测"
+- 默认值为空时 CLI 已 fail-fast，错误体里会给 `arkcli resources list --modality <m>` 和 `arkcli profile set-default --modality <m> <id>` 两条引导，agent 直接照做
+
+## Default 漂移检测与 promote nudge
+
+在帮用户成功跑 `arkcli +chat` / `+gen` / `+deploy` 且用户**显式**传了 `--model X`（或 `--endpoint X`、platform 场景）时：
+
+1. 读 profile.yaml 的 `resources.<modality>.default`
+   - `+chat` → modality = text
+   - `+gen --modality image` → modality = image
+   - `+gen --modality video` → modality = video
+   - `+deploy` 由用户传的 `--set-default <modality>` 自带（用户已经显式说了）
+2. 比较 `X` 跟当前 default
+3. **命令成功之后**（数据面返回 200 / `+deploy` 返回 ep id），如果 `X` ≠ 当前 default：
+   > "你这次用了 `X`，但当前 `<modality>` default 是 `Y`。要把 `X` 设为新 default 吗？"
+4. 用户同意 → 跑 `arkcli profile set-default --modality <m> <X>`（已经包含 inline 校验，不需要 agent 二次校验）
+5. 用户拒绝 → 不动 profile
+
+**何时不 nudge**：
+- 命令失败 → 不 nudge（用户误调用不该被推 promote）
+- 用户没传 `--model` 走的就是 default → 不 nudge
+- 同一 session 已经 nudge 过同一个 `(modality, id)` → 不再问（避免 nag）
+- 用户明确说"别再问 X" → 写到 CLAUDE.md memory 持久化偏好
+
+## Cross-modality 处理 (S10 后)
+
+S10 改造后, arkcli 不再因为 active profile 是 `coding-plan` 就阻断 `+gen --modality image|video`. 行为如下:
+
+- **active=platform**: 直接走 platform 数据面 `/api/v3` + endpoint id, 跟原行为一致
+- **active=agent-plan**: 走 agent-plan 数据面 + 预置模型 (image=`doubao-seedream-5.0-pro`, video=`doubao-seedance-2.5`)
+- **active=coding-plan + modality=image|video**: arkcli 自动借道 platform 数据面 `/api/v3` + 用户在 platform 控制面 `+deploy` 出的 endpoint id (cfg 临时 clone, 不污染 factory cache). 用户体感不需要切 profile
+- **active=agent-plan-team**：走 Agent Plan 数据面 + 团队席位 Key + 预置 image/video 模型。
+- **active=coding-plan-team**：image/video 使用 platform Endpoint，但团队席位 Key 不兼容。提交前必须由用户显式授权兼容的后付费凭证：选择 Platform/Coding Plan 个人版 `--profile`，或提供 `--api-key`（需要时同时提供 `--base-url`）。CLI 不枚举、不借用 sibling profile；缺少显式授权时在真实请求前失败。
+
+资源发现 / default 设置链路也对齐:
+- `arkcli resources list --modality image` 在 coding-plan profile 下会列出同账号下 platform 已 deploy 的 endpoint
+- `arkcli profile set-default --modality image <ep-id>` 在 coding-plan profile 下也能 verify + 写入 (走同款 ListEndpoints)
+
+`+gen --modality image` 在 `agent-plan` profile 下默认会用 `doubao-seedream-5.0-pro`, `--modality video` 默认 `doubao-seedance-2.5`. Agent Plan 生图还可选 `doubao-seedream-5.0-flash`，生视频还可选 `doubao-seedance-2.0` 等旧版本（均非默认）。用户跑 `arkcli resources list --modality image` / `video` 可看完整可用清单.
+
+完整凭证/资源矩阵与临时覆盖组合见
+[`execution-context.md`](execution-context.md)。

package/skills/arkcli-shared/references/troubleshooting.md

@@ -0,0 +1,36 @@
+# 故障分流与能力边界
+
+> 本文从 `arkcli-shared` 正文拆出。命令报错、不知道问题归类（认证 / 配置覆盖 / 参数 / 资源名 / 覆盖不足）时查阅。
+
+## 故障分流
+
+1. 先区分问题类型
+   - 认证问题
+   - 配置覆盖问题
+   - 参数问题
+   - 资源不存在或资源名不确定
+   - 产品命令覆盖不足
+2. 认证问题
+   - 先看 `arkcli auth status`
+   - 控制面鉴权错误（OpenTOP Action） → 转 `arkcli auth login`，并参考 [`../../arkcli-auth/references/auth-modes.md`](../../arkcli-auth/references/auth-modes.md) 的"控制面用 STS 还是长效 AK/SK"
+   - 数据面 API Key 鉴权 / 权限错误（Runtime 调用） → 参考 [`../../arkcli-auth/references/auth-modes.md`](../../arkcli-auth/references/auth-modes.md) 的"API Key 模式的错误恢复"。**命令失败且症状=key 失效 / `InvalidApiKey` / 突然 401 且没主动换过 key**（疑似后端轮换）→ 先 `arkcli profile apikey refresh` 同步后端 key 再重试一次（最轻的反应式自愈，agent 可自动跑）；**仅在失败时触发，不要每次命令前预防性 refresh**。refresh 救不了（权限不足 / env 覆盖 / SSO 过期）再 `arkcli auth apikey` 或重登
+3. profile / Base URL / Region / API Key / Project 覆盖混乱
+   - 普通诊断先用 `arkcli auth status --format json` 与 `arkcli auth whoami --format json` 查看当前身份/Profile 摘要；默认模型与路由转 `arkcli resources list --format json`。
+   - 只有用户显式要求核对持久 Profile 时才执行 `arkcli profile show [name]`，并先说明它可能同步远端 Key、回写本地 Key 库存或默认 Key。脱敏输出不代表无配置副作用。
+   - 根命令不再接受 `--region` / `--project-name`，`ARK_REGION` / `ARK_PROJECT_NAME` 也不覆盖运行时。
+   - 若数据面使用 `--base-url`，必须同时显式提供 `--api-key`；无 Profile 的 stateless 模式必须将两者成对提供。
+   - 两者仍对不上时，转 [`../../arkcli-config/SKILL.md`](../../arkcli-config/SKILL.md) 查看完整归因链路。
+   - 需要切 profile 时再用 `arkcli profile use <name>`
+4. 模型、接入点、任务 ID 等资源名不确定
+   - 优先走对应查询命令，例如 `arkcli models search`
+5. 产品命令确实不覆盖
+   - 先 `arkcli <domain> --help`
+   - 再看对应 skill
+   - 最后才转 [`../../arkcli-api-explorer/SKILL.md`](../../arkcli-api-explorer/SKILL.md)
+
+## 当前能力边界
+
+- 当前仓库已经覆盖：`models`、`+chat`、`+gen`、`+deploy`、`infer endpoint`、`usage stats`、`+connect`
+- Endpoint 管理型命令已有独立 skill [`../../arkcli-infer-endpoint/SKILL.md`](../../arkcli-infer-endpoint/SKILL.md)，支持 `create/list/get/start/stop/update`
+- 当用户说"先看看有没有现成 Endpoint"时，用 `arkcli infer endpoint list` 查询，不要假设必须先 `+deploy`
+- 如果用户目标是正式接入且列表为空，再转 `+deploy` 创建

package/skills/arkcli-shared/references/update.md

@@ -0,0 +1,72 @@
+# 版本检查与显式升级
+
+本 reference 只负责回答“当前版本是否最新”和执行用户明确要求的升级。它不访问业务账号，不需要先跑 `auth status`。
+
+`update.mode` 的读取、写入、默认值和 automatic production gate 属于 [`../../arkcli-config/SKILL.md`](../../arkcli-config/SKILL.md)。不要因发现新版本或仅看到 postinstall enrollment 就推断 active automatic consent；新安装 pending、registry latest reconciliation、exact receipt 换发与版本锁定流程以 config Skill 为准。
+
+本 reference 的所有 Agent 命令都必须携带下方 `ARKCLI_CALLER_TYPE=ai_agent` 等 caller metadata。它不仅用于归因，也保证 AI Skill 不消耗人工首次宽限、不激活 exact consent、不调度 automatic。不要删除这些变量后用 Agent 模拟人工命令。
+
+## 只检查
+
+默认先读零网络的本地缓存：
+
+```bash
+ARKCLI_NO_UPDATE_NOTIFIER=1 \
+ARKCLI_CALLER_TYPE=ai_agent \
+ARKCLI_CALLER_NAME=<agent-id> \
+ARKCLI_SKILL_NAME=arkcli-shared \
+arkcli --format json update --check
+```
+
+按 `status` 判断，不要只看兼容字段 `update_available`：
+
+| `status` | 含义 | Agent 行为 |
+|---|---|---|
+| `unknown` | 没有当前发行渠道的有效缓存 | 明确说“未知”；需要实时结果时再用 `--refresh` |
+| `up_to_date` | 缓存或 registry 已确认当前版本不旧于 latest | 报告已是最新，并说明 `source` |
+| `update_available` | `latest` 严格新于 `current` | 报告版本差异；不要自动升级 |
+
+`source` 是 `none`、`cache` 或 `registry`，`checked_at` 是缓存或查询时间。用户要求实时结果时再刷新：
+
+```bash
+ARKCLI_NO_UPDATE_NOTIFIER=1 \
+ARKCLI_CALLER_TYPE=ai_agent \
+ARKCLI_CALLER_NAME=<agent-id> \
+ARKCLI_SKILL_NAME=arkcli-shared \
+arkcli --format json update --check --refresh
+```
+
+`--refresh` 会访问当前二进制内置的 npm registry。查询失败时原样报告错误；不要把旧缓存包装成实时结果，也不要把 `status=unknown` 解读成“无更新”或“已是最新”。
+
+## 显式升级
+
+只有用户在本轮明确要求升级时才进入写流程。先检查并展示 `current -> latest` 和发行渠道，再取得本轮确认；确认后才可在非交互命令中添加 `--yes`：
+
+```bash
+ARKCLI_NO_UPDATE_NOTIFIER=1 \
+ARKCLI_CALLER_TYPE=ai_agent \
+ARKCLI_CALLER_NAME=<agent-id> \
+ARKCLI_SKILL_NAME=arkcli-shared \
+arkcli update --yes
+```
+
+显式 `arkcli update` 和 `arkcli update --check` 在所有更新模式下都可用；`disabled` 只关闭静默安装。`disabled` 仍允许隐式检查和版本提示。
+
+后台 automatic patch 更新成功提交并释放更新锁后，会用新版二进制静默执行一次裸 `+connect`。Volc 的新版 Skills 已随同一版本的 CDN 产物进入安装目录；这里读取该版本的本地快照，不加 `--refresh`。同步输出写入 `update-apply.log`；若 Agent Skill 同步失败，CLI 更新仍保持成功，可查看日志后手工重试 `arkcli +connect`。
+
+用户要求长期锁定版本时，不要只执行 npm 降级。先引导用户持久设置 `arkcli config set update.mode disabled`，再安装精确版本。重装不得沿用旧 exact receipt：安装版本等于 registry 当前 `latest` 时不改 mode，已有 automatic 会换发 receipt；非 latest 持久化 disabled。安装 `@latest` 不会把 disabled 改回 automatic，恢复时先安装 latest，再显式设置 automatic。
+
+`update` 会启动外部 npm，属于 `opaque_external_execution`，不支持 `--dry-run`。不要伪造 Client Preview，也不要用 raw API 代替；用版本差异说明和明确确认完成安全闭环。
+
+只有 npm 成功、同一 npm global root 下的 package 版本等于 `latest`，且 npm 管理的目标 executable 的 `--version` 也等于 `latest`，才能报告升级成功。命令失败时不得声称升级完成。
+
+## 失败与平台分流
+
+- `npm` 缺失：转述 CLI 给出的手动命令，不自行安装 Node/npm。
+- npm prefix、Node 或 NVM 不一致：停止，提示用户切回安装当前 arkcli 的 Node 环境；不要用 PATH 中另一个 npm 强行继续。
+- 当前 binary 不在 npm global package 内：说明该副本不受影响。即使 npm package 验证成功，也不要声称当前副本已经变更。
+- Windows 的显式更新只表示“已安排”；只有新一次 `arkcli --version` 显示目标版本，或 `update-apply.log` 记录 `installed and verified`，才能报告完成。
+- Windows 更新失败时保留旧安装、日志和 `.arkcli-update-*` 恢复目录，不把失败解释成“部分成功”。
+- macOS/Linux 的显式更新仍是手工 npm 升级语义；不要把 automatic 原子 cutover 描述成显式命令已采用的路径。
+
+不要用 cron、系统服务或 Agent 定时任务模拟自动更新，也不要因普通更新提示中断当前业务命令或改变其退出码。

package/skills/arkcli-train-finetune/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: arkcli-train-finetune
+description: 使用 ArkCLI 创建、查询和管理模型精调训练任务，并从训练指标选择最佳 step、导出训练产物为 custom model、衔接模型仓库与推理部署。任何包含精调任务 ID（`mcj-*`）的查询、查不到原因诊断、日志、trajectory、状态或生命周期操作都应使用本 skill；也适用于选择训练方法、查询精调价格和超参数、校验精调训练/验证数据、匹配精调资源组、创建任务及导出部署。本 skill 不负责独立 Dataset 生命周期管理；精调工作流中的数据校验和 Dataset 引用仍由本 skill 编排。
+---
+
+# ArkCLI 精调训练
+
+先读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，遵循认证、输出、安全和二次确认规则。
+
+## 执行面与凭证（先看）
+
+- 本 skill 的 `arkcli train finetune *`、`arkcli dataset *`、`arkcli models finetune-config *` 都属于**控制面**：
+  使用 SSO 派生的 STS，先执行 `arkcli auth status`；未登录按 shared 的认证闸门登录。
+- 控制面命令不消费数据面 `--api-key` / `--base-url`。显式传入会 fail-fast
+  （`--api-key only applies to data-plane commands; ... is control-plane or local`）；`.env` / `ARK_API_KEY`
+  只能用于推理数据面，**不能用于训练创建或 TOS 上传**。
+- SFT / LoRA / DPO / RL 是训练任务，不是 Agent Plan 模型调用；不要转 `+chat` / `+gen`，也不要按 Agent Plan
+  模型或套餐额度选型。训练费用与能力以 `train finetune pricing` / `capability get` 的实时结果为准。
+- 本地 `--train-file` / `--validation-file` 会由 ArkCLI 自动上传到 Ark 托管 TOS，最终请求使用
+  `TosBucket` / `TosPaths`；不需要用户先手工上传，也不要把本地路径直接当后端数据地址。
+
+## 适用场景与能力边界
+
+- 校验训练/验证数据、创建精调任务：读取 [`references/create.md`](references/create.md)
+- 列出或筛选任务：读取 [`references/list.md`](references/list.md)
+- 下载某任务实际使用的训练集/验证集：读取 [`references/download.md`](references/download.md)
+- 查询、观察或操作一个指定任务：读取 [`references/manage.md`](references/manage.md)
+- 根据指标选择 step、导出产物并部署：读取 [`references/export-deploy.md`](references/export-deploy.md)
+- 精调任务创建或预检所需的本地/TOS 训练、验证数据校验留在本 skill，直接调用 `arkcli dataset validate`；不要因为命令路径属于 `dataset` 就切换 skill。
+- 独立 Dataset 的创建、查询、更新、删除、版本、下载，或不涉及精调任务的独立数据校验，转 [`../arkcli-datasets/SKILL.md`](../arkcli-datasets/SKILL.md)。创建精调任务时可以直接消费本地文件、TOS URL、`ds-*/dsv-*` 引用和模型支持的 preset。
+- 普通训练 Dataset 默认使用 `--train-dataset`（`Multiplier=1`）；需要重复引用、倍率或采样数时改用可重复的 `--train-path`。每项最多设置 `multiplier` 或 `sample_count` 之一，均不设置时仍默认 `Multiplier=1`。preset 必须在 `inject_multiplier` 与 `inject_sample_count` 中二选一。
+- 训练产物的指标分析和 artifact export 由本 skill 编排；custom model 详情、可部署版本准备和 Endpoint 创建必须按模型仓库及部署 skill 执行。
+- 不把 Raw API 或精调 SDK 当默认入口。
+
+只加载当前任务需要的 reference。不要为了熟悉全部命令一次性读取所有文件。
+
+## 反唤起信号
+
+- 只查询公共基础模型目录 → 使用 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md)。
+- 只管理已有推理 Endpoint → 使用 [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md)。
+- 纯登录或 profile/config 排障 → 分别使用 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md) 或 [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md)。
+- 不要把 Raw API 或精调 SDK 当作默认入口；只有产品命令无法表达任务且用户确认 fallback 后才进入扩展流程。
+
+## 指定任务的精确范围诊断
+
+- 用户给出 `mcj-*` 并询问任务状态、查不到原因、日志或 trajectory 时，必须加载本 skill 并读取 [`references/manage.md`](references/manage.md)。
+- “这个任务怎么查不到”首先在当前 active profile / project / region 对原始 ID 执行 `arkcli train finetune get <mcj-id>`，再按该权威 API 的原始结果解释。
+- `mcj-*` 是不透明资源 ID。不得根据日期片段、后缀单词或臆测的哈希格式断言 ID 无效，也不得改写用户给出的 ID。
+- 用户要求不切环境或只查指定任务时，禁止执行 `train finetune list`、扫描其他任务、切换 profile/project/region，或查询其他账号。目标 `get` 失败时保留错误 code、message 和 request ID；只有用户另行授权后才能扩大范围。
+- 用户要求把指定 MCJ 的日志保存到本地路径时，第一条业务命令就是 `arkcli train finetune logs <mcj-id> --output <path>`。不得先 list 全部任务或用脚本遍历；目标命令失败时原样报告，不建议切环境。
+- 用户要求指定 MCJ 的完整 rollout trajectory 时，直接执行 `arkcli train finetune trajectory list <mcj-id> --full`。不存在 `arkcli train trajectory` 路径；无轨迹或未开启记录时保留原错误，不探索 profile、MCP 或其他任务。
+- `logs --follow` 仅在任务活跃且可能继续产生日志时持续轮询；任务已终态时输出当前快照后自动退出，轮询中发现终态且无新日志也会退出。不要再用外部 timeout 作为正常终止机制。
+- `pause` 与 `resume` 是明确的可逆关系：`pause` 将运行任务置为 `Paused`，`resume` 用于恢复 `Paused`；后端允许时也可用 `resume` 重试 `Failed` / `Terminated`，以当前 API 结果为准。
+
+## 实时信息原则
+
+以下信息会变化，不在 skill 中硬编码：
+
+- 可训练模型、模型版本和训练方法
+- 训练价格
+- 超参数字段、默认值、范围和枚举
+- CLI flags、任务阶段和操作限制
+- 基础模型或自定义模型支持的推理部署方式
+
+关键命令执行前或执行报错，使用当前安装版本的 `--help` 和 ArkCLI 查询命令获取实时结果。若 CLI 输出与本文命令骨架不一致，以当前 CLI 为准。
+
+训练和验证数据优先通过 `arkcli dataset validate` 按目标模型、精确版本和训练类型完成服务端校验，具体流程见 [`references/create.md`](references/create.md#3-获取并校验训练数据)。不默认由 Agent 对照文档逐行检查或自写校验器。火山方舟[模型精调数据集格式说明](https://www.volcengine.com/docs/82379/1099461?lang=zh)仅用于解释校验错误、辅助修复或说明命令未覆盖的格式；文档比对不能替代命令的校验结果。不在 reference 中维护容易过期的格式说明及样例。
+
+## 默认训练类型、训练方法与部署限制
+
+- 用户未指定训练类型（`--type`）时，默认按 SFT 处理。
+- 用户未指定 LoRA 还是全量训练等训练方法时，默认选择 LoRA。
+- 用户明确选择全量训练时，创建前提示：当前 ArkCLI 还不支持对全量训练产物进行部署，训练完成后的部署需要到控制台完成。
+
+## SDK Fallback Gate
+
+精调 SDK 是 fallback，不是默认入口。
+
+仅当 ArkCLI 无法完成，而精调 SDK 能完成时进入 fallback，例如：
+
+- 自定义 grader 或 rollout plugin
+- 复杂 RL 流程
+- 自定义 job YAML
+- 自定义训练代码
+- 当前 ArkCLI 版本没有对应能力
+
+需要 fallback 时，先检查当前 ArkCLI 的 `train finetune`、`models finetune-config` 和相关 `--help` 是否能够完整表达用户配置。若 ArkCLI 已提供对应参数或 pipeline 配置并能完整完成任务，继续走标准创建流程。
+
+命中 fallback 时暂停执行，询问用户：
+
+> 当前任务需要精调 SDK，ArkCLI 标准创建流程无法表达该配置。是否现在自动安装精调 SDK 并继续？
+
+只有用户明确确认后，才读取并执行 [`references/ark-finetune-sdk.md`](references/ark-finetune-sdk.md)；由该 reference 负责安装 SDK、准备配置或代码并提交任务。用户拒绝时不要安装、不要提交。
+
+## 关键客户端校验
+
+- 提交前以精确模型/版本查询 `train finetune capability get --model <name> --version <version>`，或复用同版本 `models finetune-config ... --type <type>` 的权威校验。支持类型为空/未知时停下核对模型与版本，不暴力枚举 SFT/LoRA/DPO 直到碰巧成功。
+- 价格查询的 `--model` 使用权威基础模型名，不把带版本的拼接 ID 当名称；需要精确版本时用当前 help 支持的独立版本参数。能力、超参、价格与 create 必须对应同一训练方法。
+- DPO / DPO-LoRA 不机械继承 SFT 的数据容错与 shuffle 参数；只有该模型/类型的当前配置明确支持时才传。超参名和值按实时 schema，不能照抄历史 `dpo_beta`，也不能把当前已注册的 `--beta` 误说成不存在。
+- 数据必须是用户提供或明确授权的真实文件、TOS URI、Dataset/preset 引用；占位 bucket/path 只用于说明，不发真实提交。缺数据就请求补充。
+- `create` 不支持本地 `--dry-run`。在线 `--estimate` 会上传本地训练集和验证集，须遵守上传确认规则；训练 token 估算不包含验证集。在线校验、费用估算和真实提交分别报告，不把估算成功当成训练已创建。
+
+- 用户给出模型名和训练类型询问“精调/SFT/LoRA 价格”时，首选且必须执行 `arkcli train finetune pricing --model <model> --type <type>`。不要改走通用 `arkcli pricing models`：通用账单目录不会按目标模型交叉校验训练方法能力。
+- 显式选择训练方法时，必须用精确的模型版本调用 `models finetune-config <model> <version> --type <type>`。该命令会先按同版本 `FinetuneTypes` 校验能力；不支持时停止，不继续询价、estimate 或创建任务。
+- 手动分页时，`train finetune list --page-number` 必须 `>=1`，`--page-size` 必须在 `1-100`；第 2 页及以后超出当前过滤条件对应的 `total_count` 时是参数错误，不要把空页当成有效结果。
+- 同时传入 `train finetune metrics --from-step` 和 `--to-step` 时，`to-step` 必须严格大于 `from-step`；非法区间应在查询指标名称或曲线前停止。
+- `train finetune pricing --billing-method token` 按 Token 计费项查询；`instance` 必须提供精确的 `--model-version` 和 `--type`，并保持超参与后续创建一致。实例结果只有 `price_complete=true` 才能作为完整小时价范围；否则必须报告 `missing_flavor_ids`。
+- 使用稳定资源组前，必须用与 create 完全相同的模型、版本、训练类型和超参数执行 `train finetune resource-group list`。只有 `allowed=true` 且 `matched=true` 的资源组 ID 才能传给 `create --resource-group`；ID 是不透明字符串，必须按查询结果原样传入；有多个匹配项时让用户选择。
+- 用户说“我的 / 我创建的 / 本人提交的”精调任务时，`train finetune list` 必须加 `--mine`（服务端 `sys:ark:createdBy` 过滤）；不要先拉全账号再本地猜创建人。
+
+## 守卫与通用执行规则
+
+维护者回归用例见 [`references/evals.md`](references/evals.md)。
+
+1. 运行 `arkcli auth status`，认证失败时按 shared skill 恢复。
+2. 读操作可直接执行；上传文件、创建任务、产生费用和破坏性操作必须遵守确认规则。
+3. 用户已经明确指定参数时不要重复询问；缺失且无法从实时查询推导时再询问。
+4. 输出区分事实来源：CLI/API 返回值、服务端校验结果、以及本地粗略估算。
+5. 不打印凭证、完整训练日志或大型轨迹内容；大结果写入文件后只提取必要字段。
+
+## 参考与相关文档
+
+<https://www.volcengine.com/docs/82379/1099350>

package/skills/arkcli-train-finetune/references/ark-finetune-sdk.md

@@ -0,0 +1,133 @@
+---
+name: ark-finetune-sdk
+description: 用于创建、配置、测试、调试、提交、监控或排查模型精调 SDK 项目，尤其是包含 rollout 和 grader 插件的强化学习任务。当请求涉及 `ark` SDK 命令入口、`ark_sdk` Python 包、`job.py`、`job.yaml`、`arkworkspace.toml`、`custom_rl_pipeline`、`ModelCustomizationJob`、rollout/grader 函数、插件测试、RL debug 任务、轨迹分析或精调产物时使用。
+---
+
+# Ark Finetune SDK
+
+这是通过精调 SDK 执行模型定制任务的操作指南。优先相信当前 SDK 行为和最新生成的模板，而不是记忆中的旧示例。
+
+## 信息优先级
+
+1. 当前已安装 SDK 和命令输出。
+2. 使用 `ark init workspace` 新生成的 SDK 模板。
+3. 需要用户可见引用时，使用官方公开产品文档。
+4. 本 skill 附带的 reference。
+
+不要把访问标签、环境专属说明、准入清单、变化较快的模型支持列表或敏感来源链接写进用户可见输出或生成文件。
+
+
+## 起步检查
+
+处理任何实质性任务前：
+
+1. **准备 venv 并安装 SDK**（用户自管 venv，arkcli 不代管）
+   ```bash
+   python3.11 -m venv /tmp/ark-rl     # 必须 ≥ 3.10
+   source /tmp/ark-rl/bin/activate
+   ```
+   火山方舟 SDK 使用以下安装源：
+   ```bash
+   python -m pip install https://ark-public-example-cn-beijing.tos-cn-beijing.volces.com/ark-sdk/ark_sdk-latest.tar.gz
+   ```
+   后续 `ark` / `python` 命令必须在同一 shell 里执行,或显式用 `/tmp/ark-rl/bin/ark`。
+
+2. **完成 SDK 鉴权**
+   火山方舟鉴权走 ArkCLI 桥，不要单独执行 `ark login`：
+   ```bash
+   arkcli auth login                            # 已登录时跳过
+   arkcli train finetune sdk login              # 把 ArkCLI STS 写入 ~/.ark/authorization.json
+   ```
+   说明：
+   - `sdk login` 会**临时覆盖** `~/.ark/authorization.json`；如果用户机器上已有 `ark login` 的长期 SSO 状态，该状态会被 STS 替换。
+   - STS 默认约 30 分钟过期。鉴权报错时重跑 `arkcli train finetune sdk login --refresh`；该命令使用 ArkCLI 缓存的 refresh token，不会再次打开浏览器。
+   - 多账号防误操作：既有文件的 `account_id` 与 ArkCLI 当前 active profile 不同时会拒绝覆盖；仅在确认目标账号后使用 `--force`。
+
+3. 确认 SDK 版本和命令面。
+   ```bash
+   python -m pip show ark-sdk
+   ark upgrade --help
+   ark --help
+   ark init workspace --help
+   ark create mcj --help
+   ark test pipeline_plugin --help
+   ```
+   需要升级且用户明确同意后再执行 `ark upgrade`；该命令会实际更新 SDK，不把它当只读版本检查。
+4. 如果要创建或改造项目，先在临时目录用当前 SDK 初始化模板，并阅读生成文件后再改用户项目。
+   ```bash
+   ark init workspace <workspace-dir> --template <template-name>
+   ```
+5. 判断任务类型：SFT/DPO/CPT 类监督精调、带自定义 rollout/grader 的 RL、Agent RL，或产物管理。
+6. 涉及写入或可能产生费用的操作时，如果用户没有明确要求提交，先总结最终配置并等待明确意图。`ark create mcj` 无 dry-run，提交即真实创建任务并上传插件 zip。
+
+## Reference 路由
+
+只加载需要的文件：
+
+- 任务与数据配置：[job-configuration.md](job-configuration.md)
+- RL rollout/grader 实现：[rl-plugins.md](rl-plugins.md)
+- 测试、调试、监控与排障：[testing-debug-monitoring.md](testing-debug-monitoring.md)
+
+## 核心流程
+
+执行 SDK 精调任务时：
+
+1. 完成当前环境要求的 SDK 鉴权。
+   - 火山方舟按“起步检查”步骤 2 准备 ArkCLI STS，**不要**单独执行 `ark login`；否则会覆盖 ArkCLI 写入的 STS，导致鉴权状态分裂。
+
+
+2. 初始化或检查 SDK workspace。
+3. 配置 `job.py` 或 `job.yaml`：模型引用、训练方式、数据、超参、可选验证集、可选产物配置。
+4. 对 RL 任务，先实现或改造 rollout，再实现 grader，最后接入 `custom_rl_pipeline`。
+5. 在正式测试前补齐可观测性：轨迹、函数日志、指标，以及可用的 tracing。
+6. 用一条预期通过样本和一条预期失败样本做本地测试。
+7. 用小批量数据测试，并发接近计划 batch size。
+8. 模板支持时，执行在线插件或类 FaaS 测试。
+9. RL 正式训练前提交 debug 任务，除非用户明确接受跳过风险。
+10. 提交正式任务后,**用 arkcli native 监控**(下一节"长任务监控")—— 不要在 python 里循环 `mcj.get`。
+
+## 稳定规则
+
+- 不硬编码超参表。针对所选模型和版本实时查询。
+  ```bash
+  ark get foundation-model --model <model-name> --version <model-version> --fields hyperparameters
+  ```
+- 除非当前 SDK 文档或模板明确允许，否则 `foundation_model` 和 `custom_model_id` 互斥。
+- 本地数据路径尽量保持为项目内相对路径；生成模板通常按相对路径工作。
+- RL 任务中，SDK 支持且有排障价值时设置 `enable_trajectory=True`。
+- 不在代码、日志或最终答复中暴露 API key、AK/SK、token、endpoint JWT 或 Authorization header。优先使用环境变量或本地鉴权。
+- 不凭记忆编造 SDK 类名或装饰器。名称不一致时，检查生成模板 import 和已安装的 `ark_sdk`。
+- 不依赖本 skill 获取变化较快的支持矩阵。使用当前 SDK 输出、生成模板和官方公开产品文档确认。
+
+## 常用命令
+
+```bash
+ark upgrade  # 会实际更新 SDK，先取得用户确认
+ark login
+arkcli auth login
+arkcli train finetune sdk login
+ark init workspace <workspace-dir> --template rl_demo
+ark init workspace <workspace-dir> --template rl_search_mcp_demo
+ark get foundation-model --model <model-name> --version <model-version> --fields hyperparameters
+python job.py
+ark create mcj -f job.yaml
+ark create mcj --file job.yaml --debug
+ark get mcj <mcj-id>
+ark list mcj
+ark pull mcj <mcj-id> --include-plugin
+```
+
+命令参数不确定时，优先执行 `ark <command> --help`。
+
+## 长任务监控:回到 arkcli native
+
+火山方舟的 SDK 鉴权使用短期 STS，默认约 30 分钟过期。提交完任务后不要在 Python 里实现无边界的 `while True: mcj.get(...)` 轮询，否则长任务会遇到鉴权过期。改用 ArkCLI native，由产品命令管理鉴权，并统一使用产品侧的状态、日志和指标查询：
+
+```bash
+arkcli train finetune watch <mcj-id>           # 阻塞到终态
+arkcli train finetune get <mcj-id>             # 一次性查详情
+arkcli train finetune metrics <mcj-id>         # 指标
+arkcli train finetune logs <mcj-id>            # 日志
+arkcli train finetune trajectory list <mcj-id> # RL 轨迹
+arkcli train finetune artifacts list <mcj-id>  # 产物
+```