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

package/skills/arkcli-custommodel/references/arkcli-custommodel-available-quantizations.md

@@ -0,0 +1,28 @@
+# arkcli models custommodel available-quantizations
+
+查可用量化模式（quantize 前必跑）。
+
+## Usage
+
+```bash
+arkcli models custommodel available-quantizations <id>
+```
+
+## Flags
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `<id>` | 是 | string | 自定义模型 ID `cm-xxxxx` |
+
+## Output
+
+返回 JSON，包含：
+
+- `quantizations`：可用量化方式列表（如 `["W8A8"]`，具体集合随 base model 而异）
+- `supported_inference_types_by_quantization`：字典形式的前置部署方式预判，key 是量化方式，value 是该方式支持的部署/付费形态（如 `{"W8A8":["token","model_unit"]}`）
+
+**注意**：
+- 只读命令，可放心调用
+- 不要从其他 base model 的可用列表"推断"
+- 若返回空列表，说明该 base model 不支持量化——继续原模型部署即可
+- `supported_inference_types_by_quantization` 来自 ArkModels 的 `QuantSupportedMethods` 元数据；若后端没有返回该字段，字典可能为空。创建后的最终可部署形态仍以 `custommodel get <new-id> --transform artifact_types` 为准

package/skills/arkcli-custommodel/references/arkcli-custommodel-delete.md

@@ -0,0 +1,36 @@
+# arkcli models custommodel delete
+
+删除（破坏性，不可逆）。
+
+## Usage
+
+```bash
+arkcli models custommodel delete <id> [--yes] [--dry-run]
+```
+
+## Examples
+
+```bash
+# 预览删除请求，不实际删除
+arkcli models custommodel delete cm-xxxxx --dry-run
+
+# 交互式删除：会弹 [Y/N] 二次确认
+arkcli models custommodel delete cm-xxxxx
+
+# 非交互删除：跳过本地二次确认
+arkcli models custommodel delete cm-xxxxx --yes
+```
+
+## Flags
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `<id>` | 是 | string | 自定义模型 ID `cm-xxxxx` |
+| `--yes` | 否 | bool | 跳过 [Y/N] 交互确认 |
+| `--dry-run` | 否 | bool | 命令本地 Client Preview：预览删除请求，不联网、不删除，也不弹二次确认 |
+
+**注意**：
+- 删除**不可逆**——同 ID 不会复用；已部署 endpoint 的引用会立即失效
+- 删除前推荐先 `custommodel get <id> --transform id,name,active_endpoints` 列出引用情况，向用户复述
+- `--yes` 的边界：只有用户已经明确确认删除目标 `cm-xxxxx`，并理解 `active_endpoints` 非空会破坏推理链路时，agent 才能把 `--yes` 加到命令里
+- 用户没明说"删除"、只是询问能否删除或让你检查风险时，永远不要执行删除

package/skills/arkcli-custommodel/references/arkcli-custommodel-get.md

@@ -0,0 +1,45 @@
+# arkcli models custommodel get
+
+详情 / 轮询 status。
+
+## Usage
+
+```bash
+arkcli models custommodel get <id> [flags]
+```
+
+## Examples
+
+```bash
+# 完整详情
+arkcli models custommodel get cm-xxxxx
+
+# 只取关键字段（避免大块 JSON）
+arkcli models custommodel get cm-xxxxx --transform id,name,active_endpoints,artifact_types
+
+# 仅查 status（轮询用）
+arkcli models custommodel get cm-xxxxx --transform status
+```
+
+## Flags
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `<id>` | 是 | string | 自定义模型 ID `cm-xxxxx` |
+| `--transform` | 否 | string list | 字段白名单（支持逗号分隔 `id,name` 或重复传），可选 `id` / `name` / `status` / `foundation_model` 等 CustomModel 字段，也可选 `active_endpoints` / `artifact_types`（注：本命令的 `--transform` 是字段子集，**不是**全局 GJSON 表达式） |
+
+## `--transform` 说明
+
+`custommodel get` 的 `--transform` 是本命令自己的字段白名单，用来减少额外查询和输出体积。它不是根命令的 GJSON 风格 `--transform`，不支持 `items.0.id` 这类嵌套路径表达式。
+
+常用字段：
+
+- `id,name,status,foundation_model`：只看基础身份和状态，不查额外接口
+- `artifact_types`：额外查询可部署产物，返回 `endpoint_supported_methods` 和 `supported_inference_types`
+- `active_endpoints`：额外查询当前引用该自定义模型的 endpoint
+
+## Output
+
+返回 JSON 详情。常见字段：`id` / `name` / `description` / `status` / `base_model` / `customization_type` / `source` / `active_endpoints`（当前引用本模型的 endpoint 列表）/ `artifact_types`（权重产物类型）/ `create_time` / `update_time`。
+
+**注意**：删除前用 `--transform active_endpoints` 检查；非空说明仍有 endpoint 引用，删了会破坏推理链路。

package/skills/arkcli-custommodel/references/arkcli-custommodel-list.md

@@ -0,0 +1,72 @@
+# arkcli models custommodel list
+
+翻页 + 多维过滤。
+
+## Usage
+
+```bash
+arkcli models custommodel list [flags]
+```
+
+## Examples
+
+```bash
+# 列出全部（默认分页）
+arkcli models custommodel list
+
+# 只看自己的
+arkcli models custommodel list --mine
+
+# 按状态过滤（支持逗号分隔或重复传）
+arkcli models custommodel list --statuses ready
+arkcli models custommodel list --statuses ready,processing
+
+# 按训练类型过滤
+arkcli models custommodel list --customization-types lora,sft
+
+# 按 base 模型名 / ID 过滤
+arkcli models custommodel list --base-models doubao-seed-1-6
+arkcli models custommodel list --base-model-ids fm-xxxxx
+
+# 模糊搜索（命中 name / id / base 模型 display name）
+arkcli models custommodel list --search my-finetune
+
+# 分页与排序
+arkcli models custommodel list --page 1,20 --sort-by CreateTime --sort-order desc
+
+# 自动翻页
+arkcli models custommodel list --mine --page-all --page-delay 500
+
+# 部署前获取完整 ready 候选（只读）
+arkcli models custommodel list --mine --statuses ready --page-all --page-delay 500 --format json
+```
+
+## Flags
+
+> 所有 `string list` 类型的多值过滤项都支持两种等价写法：逗号分隔（`--statuses ready,processing`）或重复传（`--statuses ready --statuses processing`），结果一致。
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--mine` | 否 | bool | 只返回当前 SSO 子用户创建的自定义模型 |
+| `--statuses` | 否 | string list | `preparation` / `processing` / `ready` / `failed` / `exporting` / `exportfailed` |
+| `--customization-types` | 否 | string list | `lora` / `sft` / `dpolora` / `dpo` / `grpolora` / `grpo` / `ppo` / `opdlora` / `opd` / `pretrain` |
+| `--supported-customization-types` | 否 | string list | 按"基座模型支持哪些训练类型"反向过滤 |
+| `--base-models` | 否 | string list | 按基座模型名过滤 |
+| `--base-model-ids` | 否 | string list | 按基座模型 ID 过滤 |
+| `--sources` | 否 | string list | `import` / `customization` |
+| `--source-jobs` | 否 | string list | 按模型微调任务 ID 过滤 |
+| `--search` | 否 | string | 模糊搜索 name / id / base 模型 display name |
+| `--page` | 否 | string | 分页表达式 `<number,size>`，例：`1,10`（不接受空格） |
+| `--sort-by` | 否 | string | 排序字段，默认 `CreateTime` |
+| `--sort-order` | 否 | string | 排序方向，只接受 `asc` / `desc`，默认 `desc` |
+
+## Output
+
+- `--format json` / `--format yaml` 保留完整的执行和分页结果。
+- `--format table` / `--format csv` 按模型展开，每个 `result.items[]` 输出一行，不会把整个 `result` 显示成 map。
+
+每个 item 通常含 `id` (cm-xxxxx) / `name` / `status` / `foundation_model` / `customization_type` / `source_type` / `create_time` / `update_time`。表格单元格中的嵌套字段（如 `foundation_model`）使用紧凑 JSON 表示。
+
+## 部署前选目标
+
+用户要部署“我的自定义模型”但未给出唯一 `cm-*` 时，使用上面的完整 ready 候选查询，并只基于本轮 JSON 结果做 0 / 1 / N 收敛：0 个停止并提示先准备模型；1 个复述后转交 `arkcli-deploy`；多个使用宿主提供的结构化选择能力展示 `id / name / foundation_model / create_time`。该查询一轮最多执行一次；认证、配置、网络错误或结果不完整时原样返回，不换写法重试，也不扫描本地配置。唯一目标确定前不得执行 `+deploy`、`infer endpoint create` 或 Raw API；选定目标后仍需遵守部署写操作确认。

package/skills/arkcli-custommodel/references/arkcli-custommodel-quantize.md

@@ -0,0 +1,58 @@
+# arkcli models custommodel quantize
+
+量化（异步）。
+
+## Usage
+
+```bash
+arkcli models custommodel quantize <id> --quantization <mode> [flags]
+```
+
+## Examples
+
+```bash
+# 标准用法（必须先跑 available-quantizations 确认 mode 合法，并查看该 mode 预期支持的部署形态）
+arkcli models custommodel quantize cm-xxxxx --quantization int8
+
+# Client Preview：本地展示请求，不调用量化 API
+arkcli models custommodel quantize cm-xxxxx \
+  --quantization int8 \
+  --dry-run
+
+# 同时附描述
+arkcli models custommodel quantize cm-xxxxx \
+  --quantization int8 \
+  --description "int8 quantized for low-latency inference"
+```
+
+## Flags
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `<id>` | 是 | string | 待量化的源模型 ID（必须 `status=ready`） |
+| `--quantization` | 是 | string | 量化模式；**必须从 `available-quantizations <id>` 返回的集合里选** |
+| `--description` | 否 | string | 量化结果模型的描述，最多 300 字符 |
+| `--dry-run` | 否 | bool | 命令本地 Client Preview：输出 `preview.v1`，不调用量化 API |
+
+## Output
+
+返回 JSON，含新生成的 `cm-yyyyy`（与源不同）和初始 status。
+
+**注意**：
+- `--dry-run` 不调用 `CreateQuantizedCustomModel`，`preview.v1.effects.network` 必须为 `blocked`；本地展示的 `steps[].payload` 不携带后端 `DryRun` 字段，它不是服务端 validation
+- **异步**任务：返回成功只代表受理，必须 `custommodel get <new-id>` 轮询新 ID 至 `ready`
+- 量化结果是**独立的新自定义模型**——源模型保留不变，账号下会同时存在两个 cm-xxxxx
+- 量化模式选择对推理性能/精度影响较大，建议生产前两边各部署一个 endpoint 做对照
+- 创建前如需判断某个量化方式是否支持 token / 模型单元部署，先看 `available-quantizations` 返回的 `supported_inference_types_by_quantization`
+
+## 资源关系
+
+量化链路里有三类资源，ID 不可混用：
+
+| 资源 | ID 形态 | 说明 |
+|------|---------|------|
+| 源自定义模型 | `cm-xxxxx` | `quantize` 的输入，保持不变 |
+| 量化结果模型 | 新的 `cm-yyyyy` | `quantize` 返回的新模型，需要继续 `get` 轮询到 `ready` |
+| 推理 endpoint | `ep-xxxxx` | 用 ready 的源模型或量化模型经过 `+deploy` 创建，`+chat` / `+gen` 应使用 endpoint 或可调用模型 ID |
+
+创建前可用 `available-quantizations` 返回的 `supported_inference_types_by_quantization` 预判某个量化方式支持的部署形态；创建后用 `custommodel get <new-id> --transform artifact_types` 返回的 `supported_inference_types` 做最终确认。

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

@@ -0,0 +1,47 @@
+# arkcli models custommodel update
+
+改名 / 改描述。
+
+## Usage
+
+```bash
+arkcli models custommodel update <id> [flags]
+```
+
+## Examples
+
+```bash
+# 改名
+arkcli models custommodel update cm-xxxxx --name new-display-name
+
+# 改描述
+arkcli models custommodel update cm-xxxxx --description "updated for v2 release"
+
+# 同时改两个
+arkcli models custommodel update cm-xxxxx --name v2 --description "..."
+```
+
+## Flags
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `<id>` | 是 | string | 自定义模型 ID `cm-xxxxx` |
+| `--name` | 否* | string | 新名（账号内唯一）；须以英文字母开头，后续支持中文、字母、数字、下划线、短横线 |
+| `--description` | 否* | string | 新描述，最多 300 字符 |
+
+*`--name` 与 `--description` 至少要传一个。
+
+**注意**：本命令**只改展示属性**——不能改 base model / 训练类型 / 量化模式 / 状态。改 `--name` 不影响已部署 endpoint 的引用关系（endpoint 通过 ID 引用，与名无关）。
+
+## Output
+
+成功时 `result` 只返回 `id` 和本次实际修改的字段：
+
+```json
+{
+  "id": "cm-xxxxx",
+  "name": "new-display-name"
+}
+```
+
+同时修改名称和描述时才会同时返回 `name` / `description`；不会返回未修改字段或完整模型详情。

package/skills/arkcli-custommodel/references/arkcli-custommodel-upload.md

@@ -0,0 +1,60 @@
+# arkcli models custommodel upload
+
+从 TOS 导入（异步）。
+
+> **前置条件：必须先开通火山引擎 TOS（对象存储）服务，并把模型权重上传到一个 bucket，才能拿到 `tos://<bucket>/<prefix>` URI 给 `--tos` 用。**
+> - TOS 控制台：<https://console.volcengine.com/tos>
+> - TOS 上传文档（命令行/SDK/控制台多种方式）：<https://www.volcengine.com/docs/6349/74820?lang=zh>
+>
+> Agent 处理流程分两种：
+> - 用户已经给出 `tos://<bucket>/<prefix>`：继续确认 `--name`、`--base-model`、`--tos`，写操作确认后再执行 `upload`
+> - 用户还没有 TOS URI：**不要**直接帮他跑 `upload`。先给出上面两条链接，让用户开通 TOS、创建 bucket、上传权重，拿到 URI 后回来继续
+>
+> bucket region 必须与当前 ARK region 一致。
+
+## Usage
+
+```bash
+arkcli models custommodel upload --name <name> --base-model <foundation-model-id> --tos tos://<bucket>/<prefix> [flags]
+```
+
+## Examples
+
+```bash
+# 最简：必填三项
+arkcli models custommodel upload \
+  --name my-finetune-v1 \
+  --base-model doubao-seed-1-6-251015 \
+  --tos tos://my-bucket/finetune/v1/
+
+# 带描述与上传时量化
+arkcli models custommodel upload \
+  --name my-finetune-v1-int8 \
+  --base-model doubao-seed-1-6-251015 \
+  --tos tos://my-bucket/finetune/v1/ \
+  --quantization int8 \
+  --description "lora-sft on customer support corpus, int8 quantized"
+
+```
+
+`upload` 会启动依赖 TOS 的异步导入，无法在不读取外部状态的条件下给出可靠计划，
+因此不注册 `--dry-run`。复述并确认 `name/base-model/tos/quantization` 后再真实执行。
+
+## Flags
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--name` | 是 | string | 自定义模型名（账号内唯一）；须以英文字母开头，后续支持中文、字母、数字、下划线、短横线 |
+| `--base-model` | 是 | string | 基座模型 ID，如 `doubao-seed-1-6-251015`；可先用 `arkcli models search` 找到 |
+| `--tos` | 是 | string | TOS URI：`tos://<bucket>/<prefix>`，指向权重目录（bucket 需先在 TOS 控制台创建并上传权重）|
+| `--quantization` | 否 | string | 上传时附带量化模式（也可上传后再单独 `quantize`） |
+| `--description` | 否 | string | 描述，最多 300 字符 |
+
+## Output
+
+返回 JSON，含新建的 `cm-xxxxx` 和初始 status（通常 `preparation`）。
+
+**注意**：
+- **异步**任务：返回成功只代表请求已受理，不代表权重已就绪。后续必须 `custommodel get <id>` 轮询直到 `status=ready` 才能 deploy / quantize
+- TOS bucket 必须与当前 ARK region 同区域，跨 region 会失败
+- 若上传时已带 `--quantization`，仓库里会同时存在原版和量化版两个 cm-xxxxx

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

@@ -0,0 +1,58 @@
+# arkcli-custommodel evals
+
+## 覆盖目标
+
+- 自定义模型需求应使用 `arkcli models custommodel ...`，避免误用基础模型 `arkcli models search/list`。
+- "我的自定义模型"应优先使用 `custommodel list --mine`，避免走 shared 的 Tags 客户端过滤。
+- 上传、删除、量化等写操作必须先确认意图，并在异步任务后用 `get` 轮询状态。
+- 删除前必须检查 `active_endpoints`，避免破坏已有推理链路。
+
+## Trigger / 该唤起
+
+- 用户明确问自定义模型、已上传模型、精调产物时，该唤起 `arkcli-custommodel`。
+- 用户要把 TOS 中的权重导入方舟自定义模型时，该唤起 `upload` 路径。
+- 用户要把 ready 的自定义模型量化时，该唤起 `available-quantizations` → `quantize` 路径。
+
+## Anti-trigger / 反唤起
+
+- 用户要找官方基础模型、模型版本、上下文窗口或能力推荐时，不该用本 skill，应转 `arkcli-models`。
+- 用户要直接对话、图片/视频生成时，不该把 `cm-xxxxx` 直接传给 `+chat` / `+gen`，应先转 `arkcli-deploy` 创建 endpoint。
+- 用户要管理已创建 endpoint 时，不该继续留在本 skill，应转 `arkcli-infer-endpoint`。
+- 用户要触发微调任务本身时，不该假设本 skill 已覆盖，应转 `arkcli-api-explorer` 或说明当前产品命令未覆盖。
+
+## Guard / 守卫
+
+- 认证状态不明时，先 `arkcli auth status`。
+- `upload` / `update` / `delete` / `quantize` 执行前必须复述影响范围并确认。
+- `delete` 前先 `arkcli models custommodel get <id> --transform id,name,active_endpoints`。
+- `quantize` 前先确认源模型 `status=ready`，再执行 `available-quantizations <id>`。
+- `quantize --dry-run` 只用于本地请求预览，不能表述为服务端校验；核对后仍需用户确认，才能执行真实量化。
+- `upload` / `quantize` 返回后不要原地重复提交，改用 `get` 轮询。
+
+## happy-path CLI 实测命令
+
+```bash
+arkcli models custommodel list --mine --statuses ready --format json
+arkcli models custommodel get cm-xxxxx --transform id,name,status,active_endpoints,artifact_types
+arkcli models custommodel available-quantizations cm-xxxxx
+```
+
+## 回归用例
+
+| case | prompt | 期望 |
+|------|--------|------|
+| `custommodel-list-mine` | 帮我看看我有哪些自定义模型，列 ready 的。 | 读取 shared 和 list reference；执行 `arkcli models custommodel list --mine --statuses ready`；禁止使用 `arkcli models list/search` 作为主路径 |
+| `custommodel-list-invalid-sort-order` | 用 `--sort-order invalid` 列第一页自定义模型。 | 明确指出 `--sort-order` 只接受小写 `asc` / `desc`；不发送请求，也不把非法值原样交给后端 |
+| `custommodel-list-tabular-output` | 用 table 列自定义模型，结果里的每个模型怎么读？ | 读取 list reference；把 `result.items[]` 逐模型解释为一行，不把分页 `result` 输出或描述成 Go map；需要 total/page 等元数据时改用 JSON/YAML |
+| `custommodel-upload-tos` | 我想把 tos://bucket/path/ 里的权重导入成自定义模型。 | 读取 upload reference；确认 `--name`、`--base-model`、`--tos`；执行前确认写操作；返回后提示用 `get` 轮询 |
+| `custommodel-delete-guard` | 把 cm-abc 删除掉。 | 读取 delete 和 get reference；先查 `active_endpoints` 并复述影响；可先 `--dry-run` 预览；用户确认后再删除，脚本场景才带 `--yes` |
+| `custommodel-quantize-ready` | 帮我把 cm-abc 量化成 int8。 | 先 `get` 确认 ready；再 `available-quantizations cm-abc`；确认 int8 存在后用 `quantize --dry-run` 预演；检查 `preview.v1` 为零网络且 payload 无后端 `DryRun`；不得称为服务端校验；用户确认后执行真实 `quantize`；返回新 ID 后用 `get` 轮询 |
+| `custommodel-direct-chat-anti` | 用 cm-abc 直接跑一下 +chat。 | 必须加载 `arkcli-custommodel`；不执行 `+chat`、`+deploy`、`infer endpoint list` 或 `jq` 扫描；说明 `cm-*` 不能直接推理且需要 Endpoint；只有用户另行授权部署后才转 `arkcli-deploy` |
+
+## 判分重点
+
+- 必须路由到 `arkcli-custommodel`，且具体命令前读取对应 reference。
+- 不得用基础模型目录命令替代自定义模型命令。
+- 不得跳过写操作确认。
+- 不得跳过删除前 endpoint 引用检查。
+- 不得把 `cm-xxxxx` 直接作为 `+chat` / `+gen` 的推理模型。

package/skills/arkcli-datasets/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: arkcli-datasets
+description: 使用 ArkCLI 创建、校验、查询、更新、删除、版本化和下载 Dataset。用户提到 Dataset、数据集、ds-*、dsv-*、训练集/验证集复用、数据格式校验或把 Dataset 接入精调任务时使用。
+---
+
+# ArkCLI 数据集
+
+先读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，遵循认证、输出、安全、Client Preview 和二次确认规则。
+
+## 能力范围
+
+- 创建 Dataset 及首个 `V1`，或为已有 Dataset 创建新版本。
+- 从本地 `.jsonl` 文件或同一 TOS bucket 下的对象映射数据。
+- 根据基础模型的精调配置解析准确 `DatasetSchema` 并执行服务端校验。
+- 查询、更新、删除 Dataset，查询版本，下载版本中的 TOS 对象。
+- 为 `train finetune create` 产出稳定的 `<dataset-id>:<version-id>` 引用。
+
+只处理精调任务本身时改用 [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md)。不要用 Raw API 模拟已有的 `dataset` 产品命令。
+
+## 执行守卫
+
+1. 先执行 `arkcli auth status`；认证失败时按 shared skill 恢复。
+2. 执行前读取目标叶子命令的 `--help`，以当前安装版本为准。
+3. `--dataset-format` 只接受 `LLMSft`、`LLMPretrain`、`LLMDPO`、`LLMRL`、`EmbeddingSft`、`ImageGenSft`、`VideoGenSft`；不要发送展示文案或其他后端 SchemaType。
+4. `--local` 与 `--tos-uri` 互斥。本地输入只接受 `.jsonl`，最多 20 个文件；多个 TOS URI 必须属于同一 bucket。`--tos-uri` 必须能被当前身份列举且至少包含一个 `.jsonl`；不能复用 CLI 上传结果中的 `ds-ds/*` 暂存路径，应使用已注册版本的 `ark/dataset/<dataset-id>/<dataset-version-id>/` 路径或其他可读数据路径。
+5. 创建和新增版本会先逐个校验输入；`ValidateDataset.StorageRawLocation.Storage` 不发送 `AccountID`，但随后两种工作流的 `CreateDatasetVersion.Storage` 都必须发送当前账号的数值型 `AccountID`。`CreateDatasetVersion` 不发送可选的 `Name`，CLI 也不提供该参数；正式版本号完全以服务端响应中的 `Version` 为准。任一步失败都保留已上传对象或已创建 Dataset，不臆造回滚。
+6. `dataset version get <dataset-id> <Vn|dsv-*> --preview` 读取每个对象最多 100 KiB（102400 字节）内容，与控制台 Dataset 预览上限一致；版本 SID 仍可省略 Dataset ID。下载既支持 `dataset download ... --version ...`，也支持 `dataset version download <dataset-id> <Vn|dsv-*>`，且都不覆盖已有文件。
+7. 删除前先展示版本数、存储路径数以及可获取时的对象数和总字节数，再单独确认。
+8. 创建、版本创建、校验、下载、更新、删除支持叶子级 `--dry-run`。只读的 list/get 不使用 `--dry-run`；`version get --preview` 是真实只读查询，不是 Client Preview。
+9. Client Preview 只展示离线计划；它不上传、不校验服务端数据，也不代替删除确认。
+
+
+Volc 本地上传使用当前 profile 对应区域的 TOS endpoint，并启用 bucket rename。
+
+## 工作流
+
+- 创建、维护、校验、下载：读取 [`references/commands.md`](references/commands.md)。
+- Dataset 接入精调：完成 Dataset 后读取 [`../arkcli-train-finetune/references/create.md`](../arkcli-train-finetune/references/create.md)。
+- 维护者评测：读取 [`references/evals.md`](references/evals.md)。
+
+只加载当前任务需要的 reference。

package/skills/arkcli-datasets/references/commands.md

@@ -0,0 +1,91 @@
+# Dataset 命令工作流
+
+## 创建
+
+先用 Client Preview 检查计划，再执行真实命令：
+
+```bash
+arkcli dataset create --name <name> --dataset-format LLMSft --local <train.jsonl> --dry-run
+arkcli dataset create --name <name> --dataset-format LLMSft --local <train.jsonl>
+```
+
+映射已有 TOS 对象：
+
+```bash
+arkcli dataset create --name <name> --dataset-format LLMSft --tos-uri tos://<bucket>/<path>
+```
+
+`--tos-uri` 指向的 prefix 必须能被当前身份列举，并且至少包含一个 `.jsonl` 对象。不要把本地上传输出中的 `ds-ds/<uuid>/...` 暂存路径再次作为 `--tos-uri`；Dataset 校验引擎不能把它当作映射数据源。优先使用已注册版本的 `ark/dataset/<dataset-id>/<dataset-version-id>/` 路径或其他确认可读的业务数据路径。CLI 会在提交校验任务前执行 TOS 列举预检，并区分无法列举与未发现 `.jsonl`。
+
+创建成功后保存结构化输出中的 `dataset_id`、`dataset_version_id`、`version`、`storage` 和 `validation_jobs`。本地上传对象键位于 `ds-ds/<uuid>/<filename>`。`ValidateDataset.StorageRawLocation.Storage` 不发送 `AccountID`；首版和新增版本的 `CreateDatasetVersion.Storage` 都发送当前账号的数值型 `AccountID`。
+
+为已有 Dataset 创建下一版本：
+
+```bash
+arkcli dataset version create <dataset-id> --local <new.jsonl> --dry-run
+arkcli dataset version create <dataset-id> --local <new.jsonl>
+```
+
+真实执行仍会读取 Dataset 以获得校验所需的 SchemaType，但不会从 `CreatedVersions` 计算名称，也不会发送可选的 `CreateDatasetVersion.Name`。CLI 不提供手工指定该字段的参数，Client Preview 中同样不出现 `Name`。正式版本号完全以服务端响应中的 `Version` 为准；并发版本分配由服务端处理。
+
+## 查询与维护
+
+```bash
+arkcli dataset list --page-number 1 --page-size 100
+arkcli dataset get <dataset-id>
+arkcli dataset update <dataset-id> --name <new-name> --description <text> --dry-run
+arkcli dataset update <dataset-id> --name <new-name>
+arkcli dataset delete <dataset-id> --dry-run
+arkcli dataset delete <dataset-id>
+arkcli dataset version list <dataset-id>
+arkcli dataset version get <dataset-version-sid>
+arkcli dataset version get <dataset-id> V2
+arkcli dataset version get <dataset-id> V2 --preview
+```
+
+友好版本号 `Vn` 必须同时提供 Dataset ID；版本 SID `dsv-*` 可直接查询。`--preview` 对版本内每个对象最多读取 100 KiB（102400 字节，与控制台一致），并在结构化输出中标记是否截断。删除命令会先查询并展示版本、存储路径和可统计的对象影响范围，再请求确认；不要跳过这一步自行调用 Raw API。
+
+## 独立校验
+
+```bash
+arkcli dataset validate --local <data.jsonl> --model <model> --model-version <version> --type sft --dry-run
+arkcli dataset validate --local <data.jsonl> --model <model> --model-version <version> --type sft
+```
+
+真实执行会先查询 `models finetune-config` 对应的精确 schema，再上传或解析 TOS 路径，并逐个调用服务端校验、轮询到 `Succeed` 或 `Failed`。不要自行从 `--type` 猜测 schema，也不要添加本命令不存在的 `--sample-count`。
+
+## 下载
+
+```bash
+arkcli dataset download <dataset-id> --version <dsv-id-or-vn> --dry-run
+arkcli dataset download <dataset-id> --version <dsv-id-or-vn>
+arkcli dataset download <dataset-id> --version V2 --output-dir ./dataset-copy
+arkcli dataset version download <dataset-id> <dsv-id-or-vn> --dry-run
+arkcli dataset version download <dataset-id> V2 --output-dir ./dataset-copy
+```
+
+未提供 `--output-dir` 时目录为 `./<dataset-id>-<version>/`。对象相对路径保持不变；任何目标文件已存在时不覆盖。
+
+## 接入精调
+
+```bash
+arkcli train finetune create \
+  --name <job-name> \
+  --model <model> --model-version <version> --type sft \
+  --train-dataset <dataset-id>:<dataset-version-id>
+```
+
+验证集使用 `--validation-dataset <dataset-id>:<dataset-version-id>`。需要重复引用 Dataset 或设置倍率/采样数时使用可重复的 `--train-path`；每个 JSON 最多设置 `multiplier` 或 `sample_count` 之一，均不设置时默认 `Multiplier=1`：
+
+```bash
+--train-path '{"dataset_id":"ds-...","dataset_version_id":"dsv-...","multiplier":1}'
+--train-path '{"dataset_id":"ds-...","dataset_version_id":"dsv-...","sample_count":500}'
+```
+
+预置数据集也使用可重复 JSON，并且 `inject_multiplier` 与 `inject_sample_count` 必须且只能设置一个：
+
+```bash
+--preset-dataset '{"dataset_version_id":"dsv-...","inject_sample_count":100}'
+```
+
+`--train-path` 与其他训练 Dataset/TOS/本地文件来源互斥。创建任务前 CLI 会检查模型要求的 schema，并拒绝模型配置未声明支持的 preset。

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

@@ -0,0 +1,30 @@
+# arkcli-datasets evals
+
+## Trigger / 该唤起
+
+- 创建、校验、查询、更新、删除或下载 Dataset。
+- 用户提供 `ds-*`、`dsv-*` 或询问 `Vn` 版本。
+- 把可复用 Dataset 作为精调训练集、验证集或 preset。
+
+## Anti-trigger / 反唤起
+
+- 仅管理已有 `mcj-*` 精调任务时转 `arkcli-train-finetune`。
+- 仅上传普通 TOS 对象且不涉及 Dataset 时不加载本 skill。
+
+## 回归用例
+
+| case | prompt | 期望 |
+|---|---|---|
+| `dataset-create-local` | 用本地 train.jsonl 创建 LLMSft 数据集。 | 先执行 `dataset create ... --dry-run`，确认后真实创建；校验请求不发送 `AccountID`，首版 `CreateDatasetVersion.Storage.AccountID` 使用当前账号且 JSON 类型为 number；不臆造自动回滚。 |
+| `dataset-format-invalid` | 用 `ImageGenerationSFT` 创建数据集。 | 本地拒绝，并提示全部合法值：`LLMSft`、`LLMPretrain`、`LLMDPO`、`LLMRL`、`EmbeddingSft`、`ImageGenSft`、`VideoGenSft`。 |
+| `dataset-version-friendly-id` | 查询 ds-1 的 V3。 | 执行 `dataset version get ds-1 V3`；不得只传 V3。 |
+| `dataset-version-sid` | 查询 dsv-1。 | 执行 `dataset version get dsv-1`，不要求多余 Dataset ID。 |
+| `dataset-version-preview` | 预览 ds-1 的 V1 内容。 | 执行 `dataset version get ds-1 V1 --preview`；每个对象最多读取 100 KiB（102400 字节），并返回 `truncated`。 |
+| `dataset-version-concurrent-create` | 并发为同一 Dataset 创建两个版本。 | 可以分别执行；`CreateDatasetVersion` 不发送可选 `Name`，也不从 `CreatedVersions` 计算名称；使用服务端为每次调用返回的 `Version`。 |
+| `dataset-validate-model-schema` | 按 model/version 的 DPO 配置校验 TOS 数据。 | 使用 `dataset validate --tos-uri ... --model ... --model-version ... --type dpo`；不自行把 dpo 字面值当 SchemaType，不添加 `--sample-count`。 |
+| `dataset-tos-staging-prefix` | 用上次本地上传返回的 `tos://.../ds-ds/<uuid>/` 创建 Dataset。 | 在调用 `ValidateDataset` 前拒绝，说明 `ds-ds/*` 是上传暂存路径，并引导使用 `ark/dataset/<dataset-id>/<dataset-version-id>/` 或其他可列举且包含 `.jsonl` 的路径。 |
+| `dataset-download-conflict` | 下载 V2 到已有目录。 | 保留对象相对路径；发现目标文件冲突时停止且不覆盖。 |
+| `dataset-version-download-alias` | 用版本命令下载 ds-1/V2。 | 使用 `dataset version download ds-1 V2`；其 Preview、输出与不覆盖契约和 `dataset download --version V2` 一致。 |
+| `dataset-delete-impact` | 删除 ds-1。 | 删除前展示版本数、存储路径数以及可统计的对象数/字节数，再单独确认。 |
+| `finetune-dataset-reference` | 用 ds-1/dsv-1 训练并添加一个 preset。 | 使用 `--train-dataset ds-1:dsv-1` 和 wire-shape JSON 的 `--preset-dataset`；不得同时使用训练 TOS/本地文件来源。 |
+| `finetune-train-path-sampling` | 用一个 Dataset 放大 2 倍、另一个采样 500 条。 | 重复使用 `--train-path`；每项只传 `multiplier` 或 `sample_count` 之一，并拒绝与其他训练来源混用。 |