# AI 套件
# ArkCLI 快速入门
Source: https://ark.volcengine.com/region:cn-beijing/docs/ark-cli
Ark CLI 是火山方舟平台官方命令行工具，支持在本地终端快速完成认证与资源管理，并可将能力安装到常用 AI Agent 中，通过自然语言触发模型调用、推理接入点管理、内容生成与用量账单查询等操作。
# 快速开始
**环境要求：** Node.js >= 16
## 1. 安装并登录 Ark CLI
**选项：手动安装并登录**
### 安装 Ark CLI
在终端执行以下命令：
```Bash
# 1. 通过 NPM 安装
npm install -g @volcengine/ark-cli
# 2. 验证安装
arkcli --version
```
### 登录 Ark CLI
```Bash
# 登录方式 1：火山 SSO 浏览器登录 (推荐)
arkcli auth login volc-sso
# 登录方式 2：火山 SSO 无浏览器登录 / 远程终端登录
arkcli auth login --no-browser
# 查看登录状态
arkcli auth status
# 装 skill 到你常用的 AI Agent (Claude Code / Cursor / TRAE / Gemini CLI 等)
arkcli +connect
```
**选项：通过 AI Agent 安装并登录**
将下方提示词复制给 AI Agent（Claude Code、Codex、Cursor、TRAE 等），它会自动完成安装。
````Plaintext
根据下面命令帮我安装 Ark CLI：https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/intro/volc.md
````
> **注意**
>
> 如果需要卸载 Skill, 在终端执行命令：`arkcli +connect uninstall`
## 2. 使用 Ark CLI
配置完成后，重启 AI Agent 即可开始使用。可以直接在 AI Agent 用自然语言说出你的需求，可参考以下示例。
| 你想做什么 | 在 AI Agent 发送 |
|-|-|
| 查询模型 | 帮我看下 doubao / seedream 相关模型 |
| 查询用量 | 看下这个账号今天 / 这周用了多少 token |
| 查询账单 | 帮我查一下最近账单和费用明细 |
| 查询套餐 | 看下当前 Agent Plan / Coding Plan 套餐和 seat 情况 |
| 换 API key | 帮我给测试 profile 换一个可用 key |
| 文本对话 | 用 doubao 模型回答一句：北京今天适合带伞吗 |
| 图片理解 | 帮我描述这张图片里有什么 |
| 文档理解 | 帮我抽取这个 PDF 的重点信息 |
| 生成图片 | 生成一张柴犬在樱花树下奔跑的图片 |
| 生成视频 | 生成一段 5 秒猫跳跃的视频 |
| 验证图片或视频来源 | 帮我验证这张图片是否是 Seedream 生成的: https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/ark-gen.jpeg |
| 部署 Endpoint | 帮我部署一个测试 Endpoint，并告诉我怎么调用 |
| 生成代码 | 给我一段 Python 调 seed 2.0 的代码 |
| 清理资源 | 把刚才创建的测试 Endpoint / gen task / chat response 清理掉 |
在 Claude Code 中使用 Ark CLI 的示例如下：
[视频](https://arkdocs.tos-cn-beijing.volces.com/videos/CodingPlan/arkcli.mov)
# 核心能力
| 领域 | 能力说明 | 命令入口 |
|-|-|-|
| 认证与身份 | 支持登录方舟平台、查看认证状态、查看当前身份、生成与切换 API Key、多 Profile 切换与管理等。 | `arkcli auth`、`arkcli profile` |
| 对话与推理 | 多模态对话、多轮对话、流式输出、思考相关参数调节等。 | `arkcli +chat` |
| 图片/视频生成 | 文生图、图生图、文生视频、图生视频、参考素材生成等。 | `arkcli +gen` |
| 多模态理解 | 支持对图片、文档、视频、音频等输入进行理解。 | `arkcli +understand` |
| 模型发现 | 支持基础模型查询、模型搜索、模型详情、可用参数、可用资源查看等。 | `arkcli models` |
| 推理资源与部署 | 支持创建推理接入点、查询、更新、启动、停止等能力，提供基于指定模型快速部署推理接入点。 | `arkcli infer`、`arkcli +deploy` |
| 模型精调 | 支持创建与管理精调任务，覆盖 SFT、LoRA、DPO 及 RL 训练流程；提供数据校验、超参与费用预览，支持产物导出部署等。 | `arkcli train` |
| Managed Agents | 管理 ARK Managed Agents，包括 Agent / Skill / Env / Session / File / Memory Store / Vault / MCP OAuth。 | `arkcli agent`|
| 文档检索 | 支持检索方舟文档、按 URL 获取方舟文档内容、分页列出文档页面等。 | `arkcli docs` |
| 用量统计 | 支持查询推理用量、免费额度或资源包余额、订阅套餐用量、分模型用量明细和团队席位用量。 | `arkcli usage` |
| 账单与定价 | 支持查询Ark分账账单明细，并按账期、接入点、API Key 或产品维度拆账；支持查询模型价格与套餐价格。 | `arkcli billing`、`arkcli pricing` |
| 套餐与席位 | 支持查询、购买和续费 Agent Plan / Coding Plan，查看套餐支持的模型，并管理个人或团队套餐。 | `arkcli plans` |
| Agent 集成与接入 | 支持自动检测本机 AI Agent，并安装、查看或卸载 Ark CLI skills；提供多语言代码示例等。 | `arkcli +connect`、`arkcli +code-example` |
| 诊断 | 统一诊断入口，覆盖业务侧诊断(账号、模型、接入点)，验证图片与视频产物的来源特征。 | `arkcli doctor` |
# 命令语法参考
Ark CLI 遵循以下命令结构：
```Bash
# 快捷命令
arkcli + [flags]
# 领域命令
arkcli [flags]
# 领域快捷命令
arkcli + [flags]
# 原始 API 调用
arkcli api --params '{...}'
```
使用 `--help` 查看任意命令的详细用法：
```Bash
arkcli --help
arkcli +chat --help
arkcli models search --help
arkcli train finetune create --help
```
## 全局标志
| Flag | 说明 |
|-|-|
| `--api-key ` | 覆盖默认的 API Key |
| `--base-url ` | 自定义数据面 API Base URL |
| `--debug` | 输出请求/响应调试信息 |
| `--dry-run` | 预览模式，仅展示请求元信息，不实际执行 |
| `--page-all` | 自动拉取所有分页数据 |
| `--page-delay` | 翻页时的延迟，默认 200 毫秒。 |
| `--page-limit ` | 配合 `--page-all` 使用，限制最大拉取页数（默认 10） |
| `--profile ` | 指定使用的 Profile |
| `--project-name ` | 覆盖当前 Project |
| `--format json` | 输出格式指定为 JSON（默认） |
| `--region ` | 覆盖当前 Region |
| `--transform ` | 使用 GJSON 表达式对输出做数据处理 |
---
# 身份与配置
Source: https://ark.volcengine.com/region:cn-beijing/docs/auth-and-configuration
身份与配置：登录认证、本地配置、无交互引导，以及贯穿所有命令的 Profile 身份切面。
- `auth` 管 SSO 登录/登出与 ARK API Key；`config` 管本地 profile 配置与 `update.mode` 策略；
- `profile` 是 `type × region × project × owner_trn × api_keys` 五元组身份切面，是所有命令的配置中心来源；
- `resources` 只读，把 Endpoint 解析为权威模型与模态，是 Skills 与 API Explorer 的校准基线。
## auth
认证与凭证管理：SSO 登录、查看登录状态、退出登录、生成/重选 ARK API Key。
- `auth login` 是交互式入口；无浏览器环境用 `--no-browser` 两段式（先取 URL，再回贴 base64 code）；
- `auth login volc-sso` 是火山引擎 SSO 通道（0.1.16 起 SSO 登录自动绑定 profile 切面）；
- 凭证存储位置是实现细节，业务代码一律通过 profile 的 `cfg.APIKey` 读取，不要直接访问存储。
### auth apikey
获取并配置 ARK API Key
```Bash
arkcli auth apikey
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--key-id` | int64 | 指定要选择的 API Key ID（非交互模式用） |
### auth apikey create
创建并保存一把普通 ARK API Key
```Bash
arkcli auth apikey create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过确认提示（非交互模式） |
### auth login
登录火山方舟平台（火山引擎）
```Bash
arkcli auth login
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--code` | string | 无浏览器 Phase 2：把浏览器显示的 base64 授权码喂回以完成登录（agent/沙箱用） |
| `--credential-store` | string | Broker verifier 存储后端：encrypted-file（默认，不访问 keyring）或 keyring（不可用时直接失败） |
| `--login-mode` | string | 登录模式：auto（新链路失败时按错误类型降级）、legacy（仅旧链路）、broker（仅新链路） |
| `--no-browser` | bool | 无浏览器模式：在任意设备完成 SSO 登录后手动粘贴授权码 |
### auth login volc-sso
通过火山引擎 SSO 登录
```Bash
arkcli auth login volc-sso
```
### auth logout
清除已保存的登录凭证
```Bash
arkcli auth logout
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--reset-service-account` | bool | （保留） |
### auth status
查看当前登录状态
```Bash
arkcli auth status
```
### auth whoami
查看当前已认证的身份
```Bash
arkcli auth whoami
```
## config
本地配置管理入口。profile 创建、查看、切换与删除已迁移到 `profile` 域。
- 保留能力：`config reset`（清整个本地状态，破坏性）、`config set update.mode automatic|disabled`（更新策略）、`config lang`；
- profile 归因、历史 yaml 排障等场景见 `profile` 域。
### config lang get
打印当前生效的持久化 UI 语言
```Bash
arkcli config lang get
```
### config lang set
持久化全局 UI 语言
```Bash
arkcli config lang set
```
### config lang unset
清除持久化的 UI 语言，改用构建默认值
```Bash
arkcli config lang unset
```
### config reset
删除所有本地配置文件
```Bash
arkcli config reset
```
### config set
设置允许修改的全局配置项
```Bash
arkcli config set
```
## profile
Profile 是 arkcli 在控制面与数据面之间的**统一身份切面**：`type × region × project × owner_trn × api_keys` 五元组绑成一组，作为所有命令执行的配置中心来源。
- 常用操作：列出/查看/新建/切换/删除/重命名，管理 profile 内 API Key 列表与各类默认资源；
- `profile project` 登录后重选 active project：project 相关 profile 重新派生，个人版 plan profile 原样保留，全程不换身份、不重登；
- 首登 project 选择器含「账号全部资源」合成项（默认），表示不设定 ProjectName、按账号全量。
### profile apikey get
打印某个 profile 的默认 API Key 明文（机器可读）
```Bash
arkcli profile apikey get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
| `--plain` | bool | 只打印 key 本身，不带 JSON 外层结构 |
### profile create
新建 profile（交互式或行内参数）
```Bash
arkcli profile create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | Profile 名称（默认：{type}_{region}_{project}） |
| `--type` | string | Profile 类型：platform \| agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team |
| `--region` | string | 地域（默认：cn-beijing） |
| `--project` | string | 项目名称（默认：default） |
| `--default-api-key` | string | 要绑定的默认 API Key（可选） |
| `--owner-trn` | string | Owner TRN（可选；自愈场景通常留空） |
| `--plan-tier` | string | [仅套餐类型] 强制指定 PlanTier（agent-plan：small\|medium\|large\|max；coding-plan：lite\|pro）；跳过 ListSubscribeTrade 的自动探测 |
| `--set-default` | bool | 创建后把该 profile 设为默认 |
| `--no-interactive` | bool | 跳过交互提示；缺少必填字段时立即失败 |
### profile delete
删除 profile（非交互场景需用 --yes 确认）
```Bash
arkcli profile delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互确认（适合内联执行） |
### profile apikey list
列出当前或指定 profile 中的 API Key（脱敏）
```Bash
arkcli profile apikey list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
### profile apikey refresh
从控制面重新拉取 API Key 列表并更新 profile
```Bash
arkcli profile apikey refresh
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
### profile apikey use
按 1 起始的序号（来自 `apikey list`）或完整 Key 设置默认 API Key
```Bash
arkcli profile apikey use
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
### profile list
列出全部 profile（标记出当前生效的）
```Bash
arkcli profile list
```
### profile models list
查看各模态的 PlanTier 与默认 Resources
```Bash
arkcli profile models list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
### profile models refresh
重新拉取文本模型列表，并更新 Resources.Text.Default（取第一个）
```Bash
arkcli profile models refresh
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
### profile project
重新选择生效 project；会删除旧的 platform profile，并为新 project 新建一个
```Bash
arkcli profile project []
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互确认（适合内联执行） |
### profile rename
设置 profile 的显示名（可含中文与空格）
```Bash
arkcli profile rename --to
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--to` | string（必填） | 展示名称（可含中文/空格；空字符串表示清除标签） |
### profile set-default
为当前生效 profile 的某个模态设置默认资源 ID
```Bash
arkcli profile set-default
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
| `--modality` | string | 模态：text \| image \| video |
| `--skip-verify` | bool | 跳过内联校验（绕过控制面可用性检查） |
### profile show
查看 profile 详情（密钥脱敏，含推导出的 base_url）
```Bash
arkcli profile show [profile]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（位置参数的替代写法） |
### profile use
切换后续所有命令使用的生效 profile
```Bash
arkcli profile use [profile]
```
## resources
实时控制面资源查询：列出当前/指定 profile 可见资源及其调用兼容性，并把 Endpoint 解析为权威模型、模态与候选工作流。
- 只读，不写 profile.yaml；拿到临时 `ep-...` 不确定该走 chat/understand/gen 时，先在本域 resolve；
- 是 Skills 与 API Explorer 的校准基线：返回的模型绑定与模态信息即真实可调用的契约。
### resources list
列出当前生效 profile 可用的资源（实时查询，不走缓存）
```Bash
arkcli resources list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
| `--modality` | string | 模态：text \| image \| video |
### resources resolve
把 Endpoint 解析为它绑定的模型、模态、API 与候选工作流
```Bash
arkcli resources resolve
```
---
# 模型与套餐
Source: https://ark.volcengine.com/region:cn-beijing/docs/models-and-plans
模型与套餐：公共基础模型查询与激活、套餐购买与席位管理、单价查询，以及 IAM 辅助与平台文档检索。
- `models` 只负责公共基础模型（doubao 等）；账号下的自定义模型（`cm-*`）走 `models custommodel`；
- `plans` 管 Agent Plan / Coding Plan（个人版 + 企业版，含席位分配与 API Key 轮换）；`pricing` 出折后单价与套餐订阅价；
- `iam` 查询身份标识与项目列表，主要供诊断与首登 project 选择使用；
- `docs` 在终端内检索方舟文档、API 契约与平台公告。
## docs
火山方舟平台文档检索与阅读：搜索（`search`）、列表（`list`）、按 URL 获取正文（`get`）、API 文档枚举与 OpenAPI spec 拉取（`apis list/spec`）。
- 适合在终端内直接查模型接入文档、API 契约与平台公告，不用切到浏览器。
### docs apis list
列出已发布的方舟 API
```Bash
arkcli docs apis list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--api-mcp-url` | string | 仅用于 apis list/spec 的 MCP 地址；也可配置 ARK_DOCS_API_MCP_URL，不改变 search/list/get 后端 |
### docs apis spec
按单一选择器读取一条已发布的方舟 OpenAPI 契约
```Bash
arkcli docs apis spec
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--api-mcp-url` | string | 仅用于 apis list/spec 的 MCP 地址；也可配置 ARK_DOCS_API_MCP_URL，不改变 search/list/get 后端 |
| `--id` | string | 按目录中的唯一 id 过滤，例如 chat-ChatCompletions_create；与 --service / --api-path 互斥；公开目录推荐优先用它 |
| `--service` | string | 按目录中的文件名分组过滤，例如 chat 或 endpoints；不是粗粒度服务标签。多数分组不唯一，命中多条时请改用 --id 或 --api-path。与 --id / --api-path 互斥 |
| `--api-path` | string | 按目录中的真实路径过滤，例如 /api/v3/chat/completions 或 /?Action=ListEndpoints&Version=2024-01-01；与 --id / --service 互斥 |
### docs get
读取方舟文档正文
```Bash
arkcli docs get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--outline` | bool | 只返回该文档已发布的标题大纲（id/level/title），不返回正文；用返回的 id 再配合 --section 精确取章节 |
| `--section` | string | 仅读取指定章节（含子章节）：精确标题或 #锚点ID；仅支持公共文档后端 |
| `--compact` | bool | 正文只输出一份，保留引用和续读信息；不输出 chunks 和 raw_text |
| `--snapshot` | string | 复用 get/list 返回的 snapshot，固定分页与续读版本 |
| `--chunk-start` | int | 从第几个正文块开始读取（默认 0） |
| `--chunk-count` | int | 返回正文块数量（默认 5）；取值范围 1-50 |
### docs list
浏览方舟文档目录
```Bash
arkcli docs list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--query` | string | 在已发布目录里按标题、描述、面包屑或路径本地过滤；搜索不可用时用它代替换词重试 |
| `--snapshot` | string | 复用 get/list 返回的 snapshot，固定分页与续读版本 |
| `--limit` | int | 每页文档数量（默认 10）；取值范围 1-100 |
| `--offset` | int | 目录起始位置（默认 0）；公共文档翻页需携带 snapshot |
### docs search
搜索方舟文档
```Bash
arkcli docs search
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--top-k` | int | 返回结果数量（默认 5）；取值范围 1-50 |
| `--snapshot` | string | 复用 search 返回的 snapshot，固定候选集与排序后再翻页（有效期约 5 分钟） |
| `--offset` | int | 搜索结果起始位置（默认 0）；大于 0 时必须携带 --snapshot |
## iam
身份与访问管理辅助命令：查询当前身份标识（`userid`）、项目列表等 IAM 信息。
- 主要供诊断与首登 project 选择使用；日常业务命令的 project 归属由 profile 切面自动处理，不需要手工指定。
### iam userid
按用户名前缀解析 IAM UserID（省略 --username 时返回当前身份的 UserID）
```Bash
arkcli iam userid
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--username` | string | 逗号分隔的待查用户名前缀（例如 ivan,bob）；省略则返回当前身份的 UserID |
## models
火山公共基础模型（如 doubao 系列）查询与激活：列表、搜索、详情，以及显式要求的开通/激活计费项（`activate`）。
- 只负责**公共基础模型**；账号下的自定义模型（cm-*）走 `models custommodel` 子域；
- 激活 ≠ 部署：`activate` 只是开通计费项，创建可调用的 Endpoint 请走 `+deploy` 或 `infer` 域；
- 性能敏感选型可参考 TTFT/TPOT 排名与输入长度对比。
### models activate
开通基础模型计费项——封装 OpenModelChargeItem
```Bash
arkcli models activate
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--sub-services` | string_slice | 要开通的子服务: base \| context-cache \| fast-infer（逗号分隔；默认仅开通 base） |
| `--yes` | bool | 跳过 [Y/N] 确认提示（非交互） |
### models custommodel available-quantizations
列出某个自定义模型可用的量化模式
```Bash
arkcli models custommodel available-quantizations
```
### models custommodel delete
从模型仓库中删除自定义模型（不可逆；需确认，或用 --yes 跳过）
```Bash
arkcli models custommodel delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 确认删除 |
### models custommodel get
查看自定义模型详情（底座模型、量化、状态、生效中的接入点）
```Bash
arkcli models custommodel get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--transform` | string_slice | 要包含的字段：id,name,active_endpoints,artifact_types |
### models custommodel list
列出账号模型仓库中的自定义模型，支持按底座模型、训练类型、状态与来源过滤
```Bash
arkcli models custommodel list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--search` | string | 按名称、id 或基础模型展示名模糊搜索自定义模型 |
| `--page` | string | 分页参数，格式 ，例如 1,10 |
| `--base-models` | string_slice | 按基础模型名称过滤，逗号分隔或重复传入 |
| `--base-model-ids` | string_slice | 按基础模型 ID 过滤，逗号分隔或重复传入 |
| `--customization-types` | string_slice | 按训练类型过滤：lora,sft,dpolora,dpo,grpolora,grpo,ppo,opdlora,opd,pretrain |
| `--supported-customization-types` | string_slice | 按支持这些训练类型的基础模型过滤 |
| `--source-jobs` | string_slice | 按模型定制任务 id 过滤 |
| `--statuses` | string_slice | 按状态过滤：preparation,processing,ready,failed,exporting,exportfailed |
| `--sources` | string_slice | 按来源过滤：import,customization |
| `--mine` | bool | 只包含当前 SSO 子用户创建的自定义模型 |
| `--sort-by` | string | 排序字段，默认 CreateTime |
| `--sort-order` | string | 排序方向：asc \| desc（默认：desc） |
### models custommodel quantize
按指定量化模式为自定义模型创建量化变体
```Bash
arkcli models custommodel quantize
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--quantization` | string（必填） | 量化模式 |
| `--description` | string | 量化后自定义模型的描述，最长 300 字符 |
### models custommodel update
重命名自定义模型或更新其描述
```Bash
arkcli models custommodel update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | 新的自定义模型名称 |
| `--description` | string | 新描述，最长 300 字符 |
### models custommodel upload
从 veTOS 产物导入自定义模型到模型仓库（需要底座模型、量化模式与名称）
```Bash
arkcli models custommodel upload
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--tos` | string（必填） | veTOS URI：tos:/// |
| `--base-model` | string（必填） | 底座模型 ID，例如 doubao-xxx-260515 |
| `--name` | string（必填） | 自定义模型名称 |
| `--quantization` | string（必填） | 量化模式 |
| `--description` | string | 描述，最长 300 字符 |
### models finetune-config
获取某个模型版本权威的精调超参数 schema。按训练类型返回 Parameters[]，每项含 Name/DefaultValue/Min/Max/Description。请在 `train finetune create` 之前用它确认正确的字段名（GRPO 用 lr+num_steps，SFT 用 learning_rate+epoch 等）。
```Bash
arkcli models finetune-config [version]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称，如 doubao-seed-1-6（也可作为第一个位置参数传入） |
| `--version` | string | 模型版本，如 250615（也可作为第二个位置参数传入）。留空 = 取 API 返回的第一个版本 |
| `--type` | string | 只查一种定制类型：sft \| lora \| dpo \| dpo-lora \| grpo \| grpo-lora \| ppo \| opd \| opd-lora \| pt。留空 = 所有有数据的类型 |
### models get
获取可见模型详情、价格与限流信息
```Bash
arkcli models get [version]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--id` | string | 模型标识，例如 doubao-seed-2-0-pro-260215（也可用位置参数传入） |
| `--version` | string | 可选的模型版本覆盖，如 260215（也可用位置参数传入） |
| `--no-cache` | bool | 绕过本地 CardView 与 ArkModels 元数据缓存 |
### models list
列出基础模型（支持过滤与分页）
```Bash
arkcli models list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--modality` | string | 按模态过滤：text \| image \| video \| audio \| embed |
| `--name` | string | 按模型名称过滤（不区分大小写的子串匹配；更丰富的过滤请用 `models search`） |
| `--page-number` | int | 页码（>=1） |
| `--page-size` | int | 每页条数 |
| `--sort-by` | string | 排序字段：CreateTime \| UpdateTime \| Name（也接受 create_time / update_time / name） |
| `--sort-order` | string | 排序方向：Asc \| Desc（也接受 asc / desc） |
| `--no-cache` | bool | 绕过本地 CardView 缓存，实时拉取可见模型 |
### models performance input-length
比较指定模型在不同输入长度下的 TTFT 或 TPOT
```Bash
arkcli models performance input-length
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--metric` | string | 性能指标：ttft、tpot 或 all |
| `--thinking` | bool | 包含思考与思考摘要生成耗时（默认 false） |
| `--time-window` | string | 统计窗口：1h、6h、24h、3d、7d 或 30d |
| `--model` | string_slice | 必填精确模型选择器 name@version:deployment；可重复 |
| `--input-lengths` | string_slice | 输入长度桶：1k、10k、50k、100k；可重复或逗号分隔 |
### models performance rank
按 TTFT 或 TPOT 对基础模型进行性能排名
```Bash
arkcli models performance rank
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--metric` | string | 性能指标：ttft、tpot 或 all |
| `--thinking` | bool | 包含思考与思考摘要生成耗时（默认 false） |
| `--time-window` | string | 统计窗口：1h、6h、24h、3d、7d 或 30d |
| `--input-length` | string | 输入长度桶：1k、10k、50k 或 100k |
| `--keyword` | string | 按模型名或展示名筛选 |
| `--deployment` | string_slice | 部署方式：default 或 fast；可重复或逗号分隔 |
| `--top` | int | 每个指标返回的模型数量（1-50）（默认 10） |
| `--order` | string | 排序方向：asc 或 desc |
| `--compare` | string | 对比方式：default-deployment 或 none |
### models performance trend
查看指定模型的 TTFT 或 TPOT 延迟趋势
```Bash
arkcli models performance trend
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--metric` | string | 性能指标：ttft、tpot 或 all |
| `--thinking` | bool | 包含思考与思考摘要生成耗时（默认 false） |
| `--time-window` | string | 统计窗口：1h、6h、24h、3d、7d 或 30d |
| `--input-length` | string | 输入长度桶：1k、10k、50k 或 100k |
| `--model` | string_slice | 必填精确模型选择器 name@version:deployment；可重复 |
| `--max-points` | int | 向服务端请求的最大数据点数（默认 12） |
### models search
按关键词 + 结构化条件检索模型（模态、上下文长度、能力）
```Bash
arkcli models search [keyword]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--keyword` | string | 检索关键词（也可用位置参数传入） |
| `--size` | int | 最多返回的结果数；0 = 不截断（默认） |
| `--modality` | string | 粗粒度模态过滤：text\|image\|video\|audio（output-modality 的别名） |
| `--input-modality` | string | 按输入模态过滤（逗号分隔，例如 text,image,video） |
| `--output-modality` | string | 按输出模态过滤（逗号分隔） |
| `--multimodal` | bool | 仅返回支持多种输入模态的模型 |
| `--min-context-window` | int | context_window 下限（Token，例如 200000） |
| `--max-context-window` | int | context_window 上限（Token） |
| `--min-input-tokens` | int | max_input_tokens 下限 |
| `--min-output-tokens` | int | max_completion_tokens 下限 |
| `--capability` | string_slice | 要求具备的能力（重复传入为 AND 关系）：thinking\|mcp\|functioncall\|web_browsing\|knowledge_base\|response_format\|reasoning_effort；caching 已废弃，请改用 --cache-type explicit_cache |
| `--cache-type` | string_slice | 要求命中的缓存类别（重复传入为 AND 关系）：explicit_cache\|implicit_cache\|session_cache\|prefix_cache |
| `--strict-filter` | bool | 丢弃缺少补充数据的模型，而不是保留（默认：保留） |
| `--include-deprecated` | bool | Include shutdown/已下线 (lifecycle_status=Shutdown 或 display_name 含'废弃/下线') 模型，默认过滤 |
| `--refresh-cache` | bool | 搜索前强制同步刷新 ArkModels 元数据缓存 |
### models versions
列出基础模型对用户可见的版本及各版本 ActiveConfigurationId（作为 `models finetune-config` 的输入）
```Bash
arkcli models versions
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称，如 doubao-seed-1-6（也可用位置参数传入） |
## plans
ARK 套餐（Agent Plan / Coding Plan，个人版 + 企业版）管理：查询持有、购买、续费、模型清单、API Key 轮换；企业版含完整席位管理（seat-list / seat-assign / rotate-apikey）。
- 购买参数会逐步澄清，避免误购；`payment_failed` 提供 Order ID 后回到已有订单补单/取消，不会重新下单；
- 注意与 platform profile 区分：Token 额度包/资源包仍走 platform profile + `/api/v3`，不因“套餐”字样误入本域。
### plans buy
购买 Agent Plan / Coding Plan 套餐（个人版 + 企业版），默认开启自动续费
```Bash
arkcli plans buy
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string（必填） | 套餐名称：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team |
| `--type` | string（必填） | 档位：small / medium / large / max（agent-plan*）\| lite / pro（coding-plan*） |
| `--duration` | int | 订阅时长（月，1-12，默认 1） |
| `--quantity` | int | 席位数量（*-team 套餐必填） |
| `--estimate` | bool | 只做在线价格试算，不下单 |
| `--yes` | bool | 确认协议并真正下单；不带该参数时只返回协议 URL 供用户查看 |
### plans get
查看当前账号持有的 Agent Plan / Coding Plan 套餐（个人版 + 企业版）——名称与档位状态
```Bash
arkcli plans get
```
### plans harness-status
查看本机各 AI Agent（claude-code / codex / opencode / openclaw / trae）上内置 Agent Plan MCP 的安装状态
```Bash
arkcli plans harness-status [agent]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--scope` | string | (仅 Trae)读取范围:global(默认)\| project(当前目录 ./.trae/mcp.json) |
| `--codex-config-scope` | string | (仅 Codex)读取范围:profile(默认,~/.codex/arkcli.config.toml)\|global(~/.codex/config.toml) |
| `--codex-profile` | string | (仅 Codex profile 模式)Codex profile 名,默认 arkcli |
### plans model-apply
设置套餐 ark-code-latest 的路由目标（auto 或指定某个影子模型）
```Bash
arkcli plans model-apply
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string | 套餐名称：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team（默认：agent-plan-team） |
| `--model` | string | 路由目标：模型 id、输出名或 "auto"；非交互模式必填 |
### plans model-list
列出某套餐支持的模型，以及当前 ark-latest-model（默认 agent-plan-team）
```Bash
arkcli plans model-list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string | 套餐名称：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team（默认：agent-plan-team） |
### plans personal rotate-apikey
轮换（重新生成）Agent Plan 个人版 API Key——旧 Key 立即失效
```Bash
arkcli plans personal rotate-apikey
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过 [Y/N] 确认提示（非交互） |
### plans renew
续费已有的 Agent Plan / Coding Plan 套餐（个人版 + 企业版），默认开启自动续费
```Bash
arkcli plans renew
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string（必填） | 套餐名称：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team |
| `--duration` | int | 续费时长（月，1-12，默认 1） |
| `--seat-ids` | string | 逗号分隔的待续费席位 ID（*-team 套餐必填，例如 seat-001,seat-002） |
| `--estimate` | bool | 只做在线续费价格试算，不下单 |
| `--yes` | bool | 确认协议并真正续费下单；不带该参数时只返回协议 URL 供用户查看 |
### plans team rotate-apikey
轮换（重新生成）Agent Plan / Coding Plan 企业版席位 API Key——旧 Key 立即失效
```Bash
arkcli plans team rotate-apikey
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--seat-ids` | string | 管理员批量轮换用逗号分隔的席位 ID；省略则轮换自己的 agent-plan-team 席位 |
| `--yes` | bool | 跳过 [Y/N] 确认提示（非交互） |
### plans team seat-assign
把企业版套餐席位分配（绑定）给子用户；重复传 --bind 可批量分配
```Bash
arkcli plans team seat-assign
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string（必填） | 套餐名称：agent-plan-team \| coding-plan-team |
| `--bind` | string_slice（必填） | 席位与用户的绑定关系（可重复）。格式：--bind seat-001=user-123，或 --bind seat-001=user-123:user-name（跳过 IAM 查询） |
| `--project-name` | string | 项目名称（默认：default） |
### plans team seat-list
按条件列出企业版套餐席位（Agent Plan Team / Coding Plan Team）
```Bash
arkcli plans team seat-list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string（必填） | 套餐名称：agent-plan-team \| coding-plan-team |
| `--type` | string | 档位过滤：small/medium/large/max（agent-plan-team）\| lite/pro（coding-plan-team） |
| `--seat-ids` | string | 逗号分隔的席位 ID（最多 1000 个），例如 seat-001,seat-002 |
| `--user-name` | string | 按绑定的子用户名称过滤 |
| `--seat-status` | int | 席位绑定状态：1=Idle，2=Active |
| `--billing-status` | int | 计费状态：1=待生效，2=生效中，3=已过期，4=已回收 |
| `--project-name` | string | 项目名称（默认：default） |
| `--page-number` | int | 页码（>=1） |
| `--page-size` | int | 每页条数 |
## pricing
查询基础模型结算单价（含当前账号折扣）与 AgentPlan/CodingPlan 套餐订阅价格。
- `Price` 是后端按账号合同/活动/套餐折后的最终单价，`OriginalPrice` 是公示原价；
- 适用场景：模型选型前的成本估算、套餐价值评估、不同模态价格对比。
### pricing models
列出基础模型计费价目（Price 为当前账号折后的实际单价）
```Bash
arkcli pricing models
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 只查单个基础模型名称（如 doubao-seed-1-6）或自定义模型 id（cm-*）；cm-* 会自动解析到其基础模型，响应中带 resolved_custom_model 字段 |
| `--modality` | string | 按 FoundationModelDomain 过滤（后端枚举）：LLM \| ComputerVision \| Audio \| Embedding \| Router |
| `--region` | string | 价格地域（如 cn-beijing）；默认取当前 profile 的地域 |
| `--page-number` | int | 页码（从 1 开始，默认 1） |
| `--page-size` | int | 每页条数（默认 50） |
### pricing plans
列出 AgentPlan 与 CodingPlan 的订阅价格（个人版与企业版）
```Bash
arkcli pricing plans
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--plan` | string | 只查单个套餐 id，例如 agent-plan-personal-small |
| `--product` | string | 按产品过滤：agent-plan \| coding-plan |
| `--edition` | string | 按版本过滤：personal \| enterprise |
---
# 对话与生成
Source: https://ark.volcengine.com/region:cn-beijing/docs/chat-and-generation
数据面工作流与它们的记录管理：对话、生成、多模态理解三条 `+` 工作流，以及对应会话/任务记录的事后查询。
- 开放式对话走 `+chat`，明确产出形态的理解任务走 `+understand`，生成任务走 `+gen`；
- `chat` / `gen` 是数据面产物的事后管理域（`get` / `list` / `delete`），本身不发起新的调用；
- 三条工作流都支持临时 API Key / Base URL / Endpoint 免配置执行，脚本与 CI 场景可复现。
## +chat
通过 Responses API 实现多模态对话、多轮对话、流式输出，支持临时 API Key、Base Url、Endpoint 免配置执行。
```Bash
arkcli +chat
```
示例：
```Bash
arkcli +chat "用三句话介绍你自己"
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 模型名称或 Endpoint ID。不传时，默认使用当前 Profile 中的文本模型默认资源。 |
| `--input` | string_slice | 输入素材引用，例如 `@photo.jpg`。传入多个文件时，可重复使用该参数。 |
| `--stream` | bool | 开启流式输出。 |
| `--previous-response-id` | string | 基于上一轮响应 ID 继续对话。 |
| `--instructions` | string | 在提示词前追加系统级指令。 |
| `--temperature` | string | 设置采样温度，例如 `0.7`。 |
| `--top-p` | string | 设置核采样参数 `top_p`，例如 `0.9`。 |
| `--max-output-tokens` | int | 设置模型回复的最大输出 token 数。 |
| `--store` | bool | 保存本次响应，以便后续通过 `--previous-response-id` 继续对话。 |
| `--reasoning-effort` | string | 推理深度：minimal \| low \| medium \| high |
| `--tools` | string_slice | 按类型快速指定工具，例如 --tools web_search；多个可重复。function 工具请用 --tools-file。 |
| `--tools-file` | string | 存放 tools 数组的 JSON 文件路径（完整 SDK 结构）。在 --tools 条目之后合并。 |
| `--tool-choice` | string | 工具调用策略：auto \| required \| none |
| `--max-tool-calls` | int | 每轮最多允许的工具调用次数 |
| `--caching` | string | 服务端提示词缓存：enabled \| disabled |
| `--cache-prefix` | bool | 开启 prefix-cache 模式（仅在 --caching 开启时有意义） |
| `--thinking` | string | 内部推理：auto \| enabled \| disabled |
| `--expire-at` | int | 已保存响应的回收时间戳（epoch 秒；仅在 --store 时有意义） |
| `--include-events` | bool | 仅流式模式：把每个 SDK 事件以一行 NDJSON 输出到 stdout，替代人类可读文本 |
| `--text-format` | string | 输出格式：text \| json_object \| json_schema |
| `--text-schema` | string | JSON Schema 文件路径（--text-format=json_schema 时必填） |
| `--text-schema-name` | string | 附加到 JSON schema 的名称（默认：arkcli_response） |
| `--text-strict` | bool | 强制严格遵循 schema（仅在 --text-format=json_schema 时有效） |
| `--no-progress` | bool | 关闭非流式调用期间周期性打印到 stderr 的心跳 |
## +gen
根据提示词生成素材（图片直接内联返回；视频立即返回任务 ID，加 --wait 可阻塞到视频生成完成）
```Bash
arkcli +gen
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 生成模型名称或 Endpoint ID（省略时取当前 profile 的 Resources..Default） |
| `--modality` | string | 显式指定生成模态：image \| video（--model 传 Endpoint ID 时必填；--model 也省略时默认 image） |
| `--input` | string_slice | 引用素材；多个可重复传入。可用 @ 前缀的本地路径，或 http(s)/file/tos URL。可选角色前缀 first:/last:/ref:/none: |
| `--name` | string | 可选的任务名覆盖 |
| `--version` | string | 模型版本覆盖 |
| `--size` | string | 图片输出尺寸 |
| `--image-count` | int | 生成图片数量（图片任务；大于 1 会启用顺序自动生成） |
| `--n` | int | --image-count 的别名（图片任务）；两者同时设置时以本参数为准 |
| `--resolution` | string | 素材分辨率 |
| `--duration` | int | 视频时长（秒） |
| `--frames` | int | 视频帧数（在支持的模型上会覆盖 duration） |
| `--seed` | int | 确定性生成的随机种子 |
| `--watermark` | bool | 是否添加水印 |
| `--generate-audio` | bool | 是否生成同步音频 |
| `--guidance-scale` | string | 无分类器引导系数（图片任务；浮点数，例如 7.5） |
| `--optimize-prompt` | bool | 是否启用服务端提示词优化（图片任务） |
| `--output-format` | string | 图片输出格式：jpeg \| png |
| `--response-format` | string | 图片响应格式：url \| b64_json（图片任务；服务端默认 url） |
| `--prompt-thinking` | string | 提示词优化思考模式：auto \| enabled \| disabled（图片任务；仅在设置 --optimize-prompt 时生效） |
| `--prompt-mode` | string | 提示词优化模式：standard \| fast（图片任务） |
| `--sequential` | string | 顺序生成图片：auto \| disabled。留空则保持 arkcli 的自动 auto 模式（--image-count > 1 时）；传 disabled 可强制单图生成，即使 --image-count > 1 |
| `--ratio` | string | 覆盖输出宽高比，如 16:9 / 9:16 / 1:1（视频任务） |
| `--camera-fixed` | bool | 锁定虚拟相机（视频任务） |
| `--return-last-frame` | bool | 在返回最终视频的同时返回最后一帧 URL（视频任务） |
| `--draft` | bool | 草稿模式：更快更便宜，质量更低（视频任务） |
| `--service-tier` | string | 服务等级覆盖（视频任务） |
| `--safety-id` | string | 调用方提供的安全标识（视频任务） |
| `--execution-expires-after` | int | 服务端任务存活时间（秒，视频任务） |
| `--priority` | int | 调度优先级 0-9，越大越早（视频任务；受各模型 supported_params 限制） |
| `--callback-url` | string | 接收任务生命周期事件 POST 的 URL（视频任务；created/running/succeeded/failed） |
| `--wait` | bool | 阻塞直到视频任务结束再返回（视频任务；默认 false——立即提交并返回 task id，之后用 'arkcli gen get ' 异步轮询） |
| `--extra-body` | string | 前向兼容的 JSON 对象，其键会合并进顶层请求体，例如 --extra-body '{"new_field":"value"}'（视频任务） |
| `--tools` | string_slice | 启用工具；目前支持 web_search。可重复。 |
| `--stream` | bool | 以 NDJSON 流式输出图片生成帧（仅图片任务）；每行是一个 image_generation.* 事件 JSON |
| `--save-to` | string | 本地保存生成素材的目录（默认：当前目录；传 --save-to="" 关闭）（默认 .） |
| `--force` | bool | 跳过逐模型的 supported_params 校验，按原样提交（模型目录过期时的逃生口） |
| `--open` | bool | 下载完成后用系统默认应用打开生成的素材。默认 auto：仅当 stdout 是交互终端（人手动执行）时打开，agent/管道/CI 下保持安静。传 --open 强制开启，--no-open 强制关闭。 |
| `--no-open` | bool | 即使在交互终端下也不自动打开生成的素材（覆盖 auto/--open 默认行为）。 |
## +understand
多模态理解（图片 / 文档 / 视频）：由 Responses API 上的子技能实现；省略子技能时按 --input 的模态自动路由
```Bash
arkcli +understand [prompt]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--input` | string_slice | 输入素材，例如 @photo.jpg；可重复传入。本地图片 / 视频 / 文档会自动上传。 |
| `--model` | string | 覆盖子技能默认模型（名称或 Endpoint ID） |
| `--stream` | bool | 增量流式输出响应 |
| `--system-prompt-override` | string | 完全替换子技能内置的 system 提示词 |
| `--system-prompt-append` | string | 在子技能内置 system 提示词之后追加额外指令 |
| `--temperature` | string | 采样温度（浮点数，如 0.7） |
| `--top-p` | string | 核采样 top_p（浮点数，如 0.9） |
| `--max-output-tokens` | int | 回复的最大输出 Token 数 |
| `--reasoning-effort` | string | 推理深度：minimal \| low \| medium \| high |
| `--thinking` | string | 内部推理：auto \| enabled \| disabled |
| `--store` | bool | 持久化该响应，便于之后取回 |
| `--no-progress` | bool | 关闭非流式调用期间周期性打印到 stderr 的心跳 |
| `--timeout` | string | 本地文件准备与推理的最长耗时（例如 2m 或 10m） |
## chat
对话会话记录管理：`chat get` 查看历史会话、`chat delete` 删除、`chat list-input-items` 列出会话输入项。
- 数据面产物：记录由 `+chat` 等 Responses API 调用产生，本域负责事后查询与清理；
- 只读为主，删除操作有确认闸门。
### chat delete
按 ID 删除已保存的响应
```Bash
arkcli chat delete
```
### chat get
按 ID 获取已保存的响应
```Bash
arkcli chat get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--include` | string_slice | include 提示（image_url\|audio_url\|encrypted_content）；多个可重复传入。注意：SDK 与后端版本可能不一致——当前线上在某些账号下不接受任何文档中的取值；若遇到 `Invalid value for 'include'`，直接去掉该参数即可 |
### chat list-input-items
分页列出某个已保存响应的输入项
```Bash
arkcli chat list-input-items
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--after` | string | 游标：列出该条目 ID 之后的数据 |
| `--before` | string | 游标：列出该条目 ID 之前的数据 |
| `--limit` | int | 分页大小（1-100，服务端默认 20） |
| `--order` | string | 排序方向：asc \| desc（服务端默认 desc） |
| `--include` | string_slice | include 提示（image_url\|audio_url\|encrypted_content）；多个可重复传入。注意：SDK 与后端版本可能不一致——当前线上在某些账号下不接受任何文档中的取值；若遇到 `Invalid value for 'include'`，直接去掉该参数即可 |
## gen
生成任务记录管理：`gen get` 查询任务详情与结果、`gen list` 列出历史任务、`gen delete` 删除记录。
- 任务由 `+gen` 工作流产生，本域负责事后查询、取回与清理；
- 视频任务异步执行，轮询状态直到出图/出片完成。
### gen delete
按 ID 删除异步内容生成任务（非交互场景必须用 --yes 确认）
```Bash
arkcli gen delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互确认（适合内联执行） |
### gen get
按 ID 获取异步内容生成任务（任务成功后自动下载素材）
```Bash
arkcli gen get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--save-to` | string | 任务成功后本地保存素材的目录（默认：当前目录；传 --save-to="" 关闭）（默认 .） |
| `--open` | bool | 用系统默认应用打开下载的素材。默认 auto：仅在交互终端下打开，agent/管道/CI 下保持安静。传 --open 强制开启，--no-open 强制关闭。 |
| `--no-open` | bool | 即使在交互终端下也不自动打开下载的素材（覆盖 auto/--open 默认行为）。 |
### gen list
分页列出异步内容生成任务（视频 / 3D / 后续模态）
```Bash
arkcli gen list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--page-num` | int | 页码，从 1 开始；省略时使用服务端默认值 |
| `--page-size` | int | 每页条数；省略时使用服务端默认值 |
| `--status` | string | 按任务状态过滤：succeeded \| failed \| running \| queued \| cancelled |
| `--model` | string | 按模型名称或 Endpoint ID 过滤 |
| `--service-tier` | string | 按服务等级覆盖项过滤 |
| `--task-id` | string_slice | 按任务 ID 过滤；多个可重复传 |
---
# 用量与诊断
Source: https://ark.volcengine.com/region:cn-beijing/docs/usage-and-diagnostics
用量、账单与诊断：推理量、结算金额，以及健康检查与错误码归因。
- `usage` 出推理量（近实时，5-30 分钟延迟），`billing` 出结算金额（T+1 财务口径），两者不可混用；
- 遇到报错先用 `doctor error` 做错误码归因，再按建议分流到对应域；
- `doctor` 还覆盖接入点 / 模型 / 指标专项诊断与 Ark 媒体来源特征验证。
## billing
查询火山引擎 ARK **拆分账单明细**（结算金额、Token 用量计费），按账期月、月范围、Endpoint、API Key、产品编码等维度过滤。
- 账单是财务口径：T+1 出账、按结算金额聚合，和 `usage` 域的近实时推理量是两个数据源；
- 适用场景：对账、按 EP / API Key 拆账、按产品拆账、月度成本复核。
### billing list
列出 ARK 拆分账单明细（结算金额 × Token 用量），支持按账期月或月范围查询。默认按账号维度统计 ARK 账单（Product 自动锁定为 ARK 系列，排除 ark_subscription）；传 --endpoint/--apikey/--apikey-sid 可下钻，传 --split-dim 可按维度拆分账号级汇总，传 --product 可覆盖或扩展产品集合。
```Bash
arkcli billing list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--start` | string（必填） | 单个账期月，格式 YYYY-MM（最早 24 个月前）。单独使用即单月；与 --end 搭配表示区间。必填。 |
| `--end` | string | 区间结束月份，格式 YYYY-MM（含当月）。省略则只查单月。区间最长 24 个月。 |
| `--day` | string | 在 --start 内定位到某个 YYYY-MM-DD（上游的性能提示）。需要 --interval=day 或 --interval=detail；与 --end 区间不兼容 |
| `--interval` | string | 聚合粒度：month（默认）\| day \| detail |
| `--endpoint` | string | 只统计指定 Endpoint ID（ep-...）。与 --apikey/--apikey-sid 互斥。 |
| `--apikey` | string | 按 API Key 值过滤（ark-...）；shortcut 会通过 arkbff 自动解析为 apikey SID。与 --endpoint/--apikey-sid 互斥。 |
| `--apikey-sid` | string | 按 API Key SID 过滤（apikey-{ts}-{xxx}，来自 `arkcli api apikey.list`）。跳过 arkbff 解析。与 --endpoint/--apikey 互斥。 |
| `--split-dim` | string | 按维度拆分账号级账单：apikey \| endpoint。留空 = 账号级汇总（默认）。设置 --endpoint/--apikey/--apikey-sid 时必须与隐含维度一致。 |
| `--product` | string_slice | 按火山引擎产品编码过滤（可重复）。省略则查看全部产品；返回行的 Product 字段会告诉你该账号实际可用的编码。 |
| `--project` | string_slice | 按项目 ID 过滤（可重复）。未设置时默认使用 profile 选定的项目（仅当 profile 无项目 / 为 'account-wide' 时跳过）；传 --project= 清空，或 --project 覆盖。 |
| `--instance-no` | string | 只统计指定计费实例 ID |
| `--bill-category` | string_slice | 按账单类型过滤（可重复）：consume-use、consume-new、consume-renew、consume-formalize、consume-modify、consume-trial、refund-terminate、refund-modify、transfer-manual、transfer-system |
| `--billing-mode` | string_slice | 按计费模式过滤（可重复）：1（订阅）\| 2（按量）\| 3（合同）\| 4（履约） |
| `--ignore-zero` | bool | 跳过折后单价为 0 的计费项 |
| `--mine` | bool | 只统计归属于当前 SSO 子用户所有资源的账单。配合 --mine-by 选择归集维度。订阅 / 账号级账单因没有 IAM 归属会被排除。与 --endpoint/--apikey/--apikey-sid/--split-dim 互斥。 |
| `--mine-by` | string | --mine 的口径：endpoint（默认，即“基础设施归属”——我部署的 Endpoint 上的全部花费，不论调用方是谁）\| apikey（费用因果——由我的 API Key 产生的账单）。两种口径互不重叠、不能相加：endpoint 按使用了哪套基础设施归集，apikey 按谁付费归集。默认与 usage stats 的 --mine-by 对齐。 |
| `--limit` | int | 分页模式：每次请求最多返回 N 行（1-300）。在多路扇出（--end / --mine）时按每路生效；总返回量 ≤ limit × 扇出路数。求和前请务必检查 is_truncated 与 partial_failures 摘要。 |
| `--offset` | int | 分页模式：每次请求跳过 N 行。循环 offset += limit 直到 offset >= total_records（单路扇出），多路扇出请用 shell 循环。 |
| `--output` | string | 将完整 Output（items + summary + partial_failures）以 JSON 写入 FILE；stdout 只显示元信息（不含 items）。会自动把内部分页上限提到 1000（30 万行），便于大账号一次性导出完整明细；用户传的 --page-limit=N 仍然优先。 |
## doctor
运行 CLI 健康检查（安装 / 连通性 / 配置）
```Bash
arkcli doctor
```
### doctor +verify-origin
验证 1-20 个图片或视频是否包含 Ark 生成来源特征
```Bash
arkcli doctor +verify-origin [media-url...]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--query-id` | string_slice | 恢复已有验证 QueryID，不创建新任务；可重复传入，最多 20 个 |
| `--timeout` | string | 整批执行最长等待时间，例如 2m 或 10m（默认 2m0s） |
| `--yes` | bool | 在已阅读价格后，对本批全部媒体仅确认一次并创建所有验证任务 |
### doctor account
诊断当前账号（身份 / 实名 / 余额 / IAM / VMP / TOS）
```Bash
arkcli doctor account
```
### doctor error
诊断 Ark 错误码并跳转到对应的修复指引
```Bash
arkcli doctor error
```
### doctor infer-endpoint
诊断推理接入点（状态、模型、用量、配额压力）
```Bash
arkcli doctor infer-endpoint
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--auto-bind` | bool | VMP 订阅 + SLR 都已开通但 telemetry 未绑定 VMP workspace 时, 自动建 ark_default + 绑 ark telemetry (订阅 / SLR 缺失时仍只给云产品开通页跳转链接, 不会替用户开通) |
| `--window` | string | 回溯窗口，Go duration 语法（如 1h、24h；time.ParseDuration 不支持 '7d'） |
### doctor metrics
查询 VMP 中具名的 PromQL 指标（由 catalog 驱动）
```Bash
arkcli doctor metrics
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--auto-bind` | bool | VMP 未绑定 workspace 时自动建 ark_default + 绑 ark telemetry (订阅 / 跨服务授权缺失时仍给 LinkOpenMgmtCloudProduct 链接, 不会替用户开通) |
| `--filter` | stringArray | 注入额外的标签匹配器（可重复，label=value）；模板必须声明 ${@filters} 指令（默认 []） |
| `--format` | string | 输出形态（仅限裸写法 'metrics '——list/describe 始终输出 json）：json \| scalar \| table |
| `--param` | stringArray | 绑定目录参数（可重复，key=value）（默认 []） |
| `--step` | string | 采样步长（Go duration；默认 = window/60，限制在 [10s,60s]） |
| `--window` | string | 回溯窗口（Go duration；不支持 '7d'）（默认 1h） |
| `--workspace-id` | string | VMP workspace UUID（默认：通过 ark telemetry 配置自动解析） |
### doctor metrics describe
查看某个 catalog 条目的完整元数据（仅支持 json 输出）
```Bash
arkcli doctor metrics describe
```
### doctor metrics list
列出 catalog 中全部具名 PromQL 查询（仅支持 json 输出）
```Bash
arkcli doctor metrics list
```
### doctor metrics raw
执行任意 PromQL 查询（必须引用 ark_* 指标）
```Bash
arkcli doctor metrics raw
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--auto-bind` | bool | VMP 未绑定 workspace 时自动建 ark_default + 绑 ark telemetry |
| `--format` | string | 输出形态：json \| scalar \| table |
| `--promql` | string | PromQL 表达式（必填） |
| `--step` | string | 采样步长（Go duration；默认自动） |
| `--window` | string | 回溯窗口（Go duration；不支持 '7d'）（默认 1h） |
| `--workspace-id` | string | VMP workspace UUID（默认：自动解析） |
### doctor model
诊断基础模型（是否存在、接入点、用量、错误率、配额）
```Bash
arkcli doctor model
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--auto-bind` | bool | VMP 订阅 + SLR 都已开通但 telemetry 未绑定 VMP workspace 时, 自动建 ark_default + 绑 ark telemetry (订阅 / SLR 缺失时仍只给云产品开通页跳转链接, 不会替用户开通) |
| `--window` | string | 回溯窗口（Go duration 语法，如 1h、24h） |
### doctor report
向 Ark case-platform 上报 Seedance 2.x 效果问题
```Bash
arkcli doctor report
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--account-id` | string | task 所属账号 id; 未传时按 APIKey 反查 |
| `--badcase-type` | string | 问题类别 (可选枚举, 见 --help Long 段) |
| `--contact-info` | string | 联系方式 (邮箱/电话), ≤255 字符 |
| `--dry-run` | bool | 预览客户端执行计划，不发网络请求、无副作用 |
| `--feedback` | string | 问题描述, 1-2000 字符, 拒绝纯空白 |
| `--source` | string | 来源枚举: huosu \| huoshan \| qianzhi \| case_import (默认) |
| `--task-id` | stringArray | seedance 2.x 的 task_id（可重复或用逗号/空白分隔；1-50 个）（默认 []） |
| `--yes` | bool | TTY 下跳过 Y/N 确认; headless 环境本 flag 无效, 需 ARKCLI_ALLOW_HEADLESS_REPORT=1 |
## usage
ARK 用量查询：`usage stats`（Token/请求数，5-30 分钟延迟）、`usage plan`（套餐额度快照）、`usage plan-details`（Agent Plan 按模型时间序列，套餐内外拆分）、`usage balance`（余额：免费额度/媒资库/套餐）、`usage seats --with-usage`（团队席位用量）。
- stats 出推理量（近实时），billing 出结算金额（T+1 财务口径），两者不可混用；
- Coding Plan 只有 quota 快照，没有按模型的套餐明细，不能用 stats 冒充。
### usage balance
Query account balance from one of three angles: free-quota (per-model 免费推理额度 / 资源包余额), media-asset (素材库 / 媒资库容量), plan (订阅套餐余额)
```Bash
arkcli usage balance
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--type` | string（必填） | 余额类型（必填）：free-quota \| media-asset \| plan |
| `--model` | string | [free-quota] 只查单个基础模型（如 doubao-seed-1-6） |
| `--modality` | string | [free-quota] FoundationModelDomain 枚举：LLM \| ComputerVision \| Audio \| Embedding \| Router（不支持别名） |
| `--page-number` | int | [free-quota] 页码（从 1 开始） |
| `--page-size` | int | [free-quota] 每页条数（默认 20；从 50 下调以保证 ListModelChargeItems 落在 10s 超时预算内） |
| `--project` | string | [media-asset] 项目范围；默认取当前 profile 的项目 |
| `--product` | string | [plan] 套餐 id：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team |
| `--all` | bool | [plan] 查询全部支持的个人版套餐，即使未订阅也查 |
| `--seat` | string | [plan] 只查指定 SeatID（仅企业版） |
### usage plan
查询套餐用量（Agent Plan / Coding Plan 的额度与周期用量）。默认自动发现全部 4 个 SKU（个人 × 2 + 企业 × 2）；可用 --product 或 --all 覆盖。
```Bash
arkcli usage plan
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--product` | string | 套餐产品 id：agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team。默认自动发现全部订阅。 |
| `--all` | bool | 查询全部 4 个产品（个人 × 2 + 企业 × 2），即使未订阅也查。与 --product 互斥。 |
| `--seat` | string | [team] 指定 SeatID；默认通过 GetSeatInfo 取调用方绑定的席位 |
### usage plan-details
查询 Agent Plan 的用量明细（按模型的时间序列），支持个人版或企业版。必须传 --start；--end 默认今天；--interval 默认 Day。
```Bash
arkcli usage plan-details
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--start` | string（必填） | 开始日期（YYYY-MM-DD）。必填。后端限制区间 ≤ 31 天，历史 ≤ 6 个月。 |
| `--end` | string | 结束日期（YYYY-MM-DD，含当天）。默认今天。 |
| `--interval` | string | 查询粒度：Day \| Hour |
| `--model` | string_slice | 按对外展示的 model/harness ObjectName 过滤（可重复）。省略则不按模型分组。 |
| `--product` | string | agent-plan（默认，个人版）\| agent-plan-team |
| `--seat` | string_slice | [team] SeatID（可重复，单次调用 ≤ 1000）；默认通过 GetSeatInfo 取调用方绑定的席位 |
| `--all-seats` | bool | [team, admin] 先调用 ListSeatInfos 取出团队内全部席位 ID 再批量查询（与 --seat 同时给出时以 --seat 为准） |
| `--seat-user-id` | string_slice | [team] 服务端按子用户 ID 过滤（可重复，管理员范围） |
| `--seat-user-name` | string_slice | [team] 服务端按子用户名称过滤（可重复，管理员范围） |
### usage seats
列出企业版套餐订阅下的全部席位（管理员视图）。需要管理员权限；子用户调用会返回 AccessDenied。project 解析顺序：--project 参数 > 字面量 `default`（企业席位始终创建在 `default`，刻意绕过 profile 的 project，以与 internal/service/agentplan/buy.go::buyTeam 的创建路径保持 1:1）。
```Bash
arkcli usage seats
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--product` | string（必填） | 团队套餐 id（必填）：agent-plan-team \| coding-plan-team |
| `--biz-info` | string | 按档位过滤：small/medium/large/max（AgentPlan）\| lite/pro（CodingPlan） |
| `--billing-status` | string_slice | 按计费状态过滤（可重复）：Running / Expired / Reclaimed / Inactive |
| `--seat-status` | string | 按席位状态过滤：Active / Inactive |
| `--user-id` | string_slice | 按子用户 ID 过滤（可重复；超过 1 个会按用户做客户端扇出，结果按 SeatID 合并去重） |
| `--user-name` | string_slice | 按子用户名称过滤（可重复；超过 1 个会做客户端扇出） |
| `--seat-id` | string_slice | 只查指定 SeatID（可重复；会绕过项目过滤） |
| `--project` | string | 项目范围。解析顺序：本参数 > 字面量 `default`。`plans buy --plan *-team` 一律在 `default` 下创建席位，因此这里刻意忽略当前 profile 的项目——若回退到 profile 项目，当 profile 项目 != `default` 时会静默返回空列表。 |
| `--page-size` | int | 每页条数（默认 100） |
| `--page-number` | int | 页码，从 1 开始；传入后关闭自动翻页，只取一页 |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：ASC \| DESC |
| `--with-usage` | bool | [仅团队产品] 关联按席位用量：AgentPlan→ListSeatAFPUsage（已用/总量/百分比），CodingPlan→ListSeatInfoUsages（仅百分比）。每行会附加 afp_usage / coding_usage。 |
### usage stats
按日期范围查询推理用量（Token / 请求数），可按模型、Endpoint 或 API Key 过滤
```Bash
arkcli usage stats
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--start` | string（必填） | 开始日期，格式 YYYY-MM-DD（必填） |
| `--end` | string | 结束日期，格式 YYYY-MM-DD，默认今天 |
| `--interval` | string | 查询粒度：Day \| Hour |
| `--endpoint` | string | 按 Endpoint ID 过滤 |
| `--model` | string | 按模型名称过滤 |
| `--apikey` | string | 按 API Key 过滤（Values 精确匹配，旧写法） |
| `--apikey-suffix` | string | 按 API Key 后缀过滤（ValueLike 匹配，例如 Key 末 12 位） |
| `--mine` | bool | 只统计当前 SSO 子用户拥有的资源；配合 --mine-by 使用 |
| `--mine-by` | string | --mine 的口径：endpoint（默认）\| apikey |
| `--by` | string | 分组维度：model、endpoint、apikey |
| `--show-window-detail` | bool | 在响应中拆解每次调用的计费窗口 |
---
# 推理与训练
Source: https://ark.volcengine.com/region:cn-beijing/docs/inference-and-training
推理部署与模型训练：接入点（Endpoint）生命周期、精调训练任务，以及训练数据管理。
- 普通交互式创建接入点走 `+deploy`（含模型澄清与复用检查）；脚本化 / CI / 无护栏场景走 `infer` 的 raw CRUD；
- `train` 管精调任务（`mcj-*`），训练数据来自 `dataset`（`ds-*` / `dsv-*`），导出产物是 `cm-*` 自定义模型；
- 导出后衔接 `models custommodel` 与 `infer`：先入模型仓库，再按接入点工作流上线。
## +deploy
引导式创建推理接入点：模型澄清、复用检查、Profile 默认资源同步（`infer endpoint create` 的带护栏版本）
```Bash
arkcli +deploy
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string（必填） | Endpoint 名称 |
| `--description` | string | 接入点描述 |
| `--model` | string（必填） | 模型 ID（基础模型或自定义模型） |
| `--model-unit-id` | string | 模型单元 ID |
| `--rate-limit` | string | 限流配置（JSON 字符串） |
| `--batch-only` | bool | 仅批量模式 |
| `--moderation` | string | 内容审核配置（JSON 字符串） |
| `--data-delivery` | bool | 数据投递模式 |
| `--dedicated-to-ptu` | bool | 专用于 PTU |
| `--dedicated-to-dynamic-ptu` | bool | 专用于动态 PTU |
| `--content-generation` | string | 内容生成配置（JSON 字符串） |
| `--inference-foundry` | string | 推理底座（Inference foundry）配置（JSON 字符串） |
| `--tags` | string | Tags（JSON 字符串） |
| `--yes` | bool | In an interactive terminal, skip the [y/N] model-activation (开通) prompt. NOTE: in non-interactive (agent/CI/pipe) this flag does NOT authorize 开通 — activation is hard-refused there; set ARKCLI_ALLOW_HEADLESS_ACTIVATION=1 only for genuine unattended automation. |
| `--allow-data-collected` | bool | 允许采集数据 |
| `--service-info` | string | 服务信息（JSON 字符串） |
| `--need-watermark` | bool | 是否需要水印 |
| `--watermark-info` | string | 水印信息（JSON 字符串） |
| `--intelligent-router` | string | 智能路由配置（JSON 字符串） |
| `--is-intelligent` | bool | 是否为智能版 |
| `--fallback` | string | 降级配置（JSON 字符串） |
| `--limit-coefficient` | string | 限流系数配置（JSON 字符串） |
| `--deployment-type` | string | 部署类型 |
| `--is-agentic` | bool | 是否为 agentic |
| `--agentic-strategy` | string | Agentic 策略配置（JSON 字符串） |
| `--is-aicc` | bool | 是否为 AICC |
| `--specify-region` | string | 指定地域 |
| `--set-default` | string | 把创建成功的 Endpoint 提升为当前 profile 在该模态下的默认（text\|image\|video）。 |
| `--domain` | string | 域 |
## dataset
Dataset（数据集）全生命周期管理：创建、查询、更新、删除、版本化（`ds-*` / `dsv-*`）、下载与格式校验。
- 面向精调场景设计：训练集/验证集的复用、版本冻结、格式校验都在本域完成；
- 精调任务通过 `--dataset` 引用本域产物，衔接 `train` 域的精调工作流。
### dataset create
创建数据集并提交首个 V1 版本
```Bash
arkcli dataset create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string（必填） | 数据集名称 |
| `--description` | string | 描述 |
| `--dataset-format` | string（必填） | 后端 SchemaType：LLMSft、LLMPretrain、LLMDPO、LLMRL、EmbeddingSft、ImageGenSft 或 VideoGenSft |
| `--local` | string_slice | 本地 .jsonl 文件路径，可重复 |
| `--tos-uri` | string_slice | 可列举且包含 .jsonl 的 TOS URI（tos://bucket/path），可重复且必须属于同一 bucket；不支持 ds-ds/* 上传暂存路径 |
### dataset delete
删除数据集
```Bash
arkcli dataset delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互式确认 |
### dataset download
下载数据集版本中的 TOS 对象
```Bash
arkcli dataset download
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--version` | string（必填） | 版本 SID（dsv-...）或友好版本号（V1、V2 等） |
| `--output-dir` | string | 下载目录；默认 ./-/ |
### dataset get
获取数据集详情
```Bash
arkcli dataset get
```
### dataset list
列出数据集
```Bash
arkcli dataset list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--page-number` | int | 页码（默认 1） |
| `--page-size` | int | 每页条数（1-100，默认 100） |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：Asc 或 Desc |
| `--id` | string_slice | 按数据集 ID 过滤，可重复 |
| `--name` | string | 按数据集名称过滤 |
| `--schema-type` | string_slice | 按 SchemaType 过滤，可重复 |
| `--resource-origin` | string_slice | 按 ResourceOrigin 过滤，可重复 |
### dataset update
更新数据集名称或描述
```Bash
arkcli dataset update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | 数据集名称 |
| `--description` | string | 描述 |
### dataset validate
按照模型微调配置校验本地文件或 TOS 数据
```Bash
arkcli dataset validate
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--local` | string_slice | 本地 .jsonl 文件路径，可重复 |
| `--tos-uri` | string_slice | 可列举且包含 .jsonl 的 TOS URI（tos://bucket/path），可重复且必须属于同一 bucket；不支持 ds-ds/* 上传暂存路径 |
| `--model` | string（必填） | 基础模型名称 |
| `--model-version` | string（必填） | 基础模型版本 |
| `--type` | string（必填） | 微调类型，例如 sft、lora、dpo、grpo、pt |
### dataset version create
为现有数据集创建下一个 Vn 版本
```Bash
arkcli dataset version create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--description` | string | 描述 |
| `--local` | string_slice | 本地 .jsonl 文件路径，可重复 |
| `--tos-uri` | string_slice | 可列举且包含 .jsonl 的 TOS URI（tos://bucket/path），可重复且必须属于同一 bucket；不支持 ds-ds/* 上传暂存路径 |
### dataset version download
下载指定数据集版本中的 TOS 对象
```Bash
arkcli dataset version download
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--output-dir` | string | 下载目录；默认 ./-/ |
### dataset version get
获取数据集版本详情
```Bash
arkcli dataset version get |
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--preview` | bool | 读取并展示版本中每个对象的前 100 KiB（102400 字节） |
### dataset version list
列出数据集版本
```Bash
arkcli dataset version list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--page-number` | int | 页码（默认 1） |
| `--page-size` | int | 每页条数（1-100，默认 100） |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：Asc 或 Desc |
| `--id` | string_slice | 按版本 SID 过滤，可重复 |
| `--version` | string_slice | 按友好版本号 Vn 过滤，可重复 |
| `--status` | string_slice | 按版本状态过滤，可重复 |
## infer
推理接入点（Endpoint，ep-*）全生命周期管理：获取、列表、创建、启动、停止、删除、更新，以及模型部署形态能力查询（capability）。
- `infer endpoint create` 是**显式 raw CRUD 通道**：面向脚本化 / CI / 无护栏场景；普通交互式创建请优先使用 `+deploy` 工作流（含模型复用检查与 profile 同步）；
- 创建前可用 `capability` 确认模型支持的部署形态；启停与删除均有确认闸门。
### infer endpoint capability get
查看某个模型支持的推理部署形态（在线接入点 / 共享服务 / 批量 / PTU / 规格档位 / 降级）。为 maas-fe 的 `EndpointSupportedMethods` 接口提供支撑。请在 `infer endpoint create` 之前调用，以确认模型是否可部署、以及哪些 `--type` 类参数对它有效。精调自定义模型传 --custom-model-id；基础模型传 --model + --version。
```Bash
arkcli infer endpoint capability get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称（如 doubao-seed-1-6-flash）；与 --custom-model-id 互斥 |
| `--version` | string | 模型版本（配合 --model 使用） |
| `--custom-model-id` | string | 自定义模型 ID（cm-xxx）；与 --model 互斥 |
### infer endpoint create
创建推理接入点（原始 CRUD，无流程护栏；需要带模型复用检查与 Profile 同步的引导式部署请用 +deploy）
```Bash
arkcli infer endpoint create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string（必填） | 模型 ID（基础模型或自定义模型） |
| `--name` | string（必填） | Endpoint 名称 |
| `--billing-method` | string | 计费方式：token |
| `--rpm` | int | 限流 RPM |
| `--tpm` | int | 限流 TPM |
| `--yes` | bool | In an interactive terminal, skip the [y/N] model-activation (开通) prompt. NOTE: in non-interactive (agent/CI/pipe) this flag does NOT authorize 开通 — activation is hard-refused there; set ARKCLI_ALLOW_HEADLESS_ACTIVATION=1 only for genuine unattended automation. |
### infer endpoint delete
删除推理接入点（不可逆）。需要确认：交互式 TTY 会提示 Y/N；非交互场景（Agent / CI / 管道）需要设置 ARKCLI_ALLOW_HEADLESS_DELETE=1，此时 --yes 不生效。
```Bash
arkcli infer endpoint delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互式 Y/N 提示（仅 TTY）。注意：非交互模式下本参数不构成删除授权——请改用 ARKCLI_ALLOW_HEADLESS_DELETE=1。 |
### infer endpoint get
获取推理接入点详情（同时支持普通接入点与预置推理接入点）
```Bash
arkcli infer endpoint get
```
### infer endpoint list
按条件分页列出推理接入点
```Bash
arkcli infer endpoint list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--format` | string | 输出格式：table \| json |
| `--model` | string | 按模型 ID 过滤（自定义模型） |
| `--status` | string | 按 Endpoint 状态过滤 |
| `--mine` | bool | 只列出当前 SSO 子用户创建的 Endpoint |
| `--page-number` | int | 页码（>=1） |
| `--page-size` | int | 每页条数 |
### infer endpoint start
启动推理接入点。启动请求被接受后返回的是接入点当前状态（通常是 Scheduling）——到 Running 的转换是异步的；请轮询 `infer endpoint get ` 直到 Status='Running' 确认。
```Bash
arkcli infer endpoint start
```
### infer endpoint stop
停止推理接入点。停止请求被接受后返回的是接入点当前状态——到 Stopped 的转换是异步的；请轮询 `infer endpoint get ` 直到 Status='Stopped' 确认。
```Bash
arkcli infer endpoint stop
```
### infer endpoint update
更新推理接入点（名称 / 描述 / 限流）
```Bash
arkcli infer endpoint update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | 新的 Endpoint 名称 |
| `--description` | string | 新的接入点描述（传空字符串可清空） |
| `--rpm` | int | 限流：每分钟请求数（必须与 --tpm 配对） |
| `--tpm` | int | 限流：每分钟 token 数（必须与 --rpm 配对） |
| `--cg-concurrent-requests` | int | ContentGeneration：最大并发请求数（图片生成接入点） |
| `--cg-create-task-rpm` | int | ContentGeneration：CreateTask 的 RPM（图片生成接入点） |
## train
模型精调（Fine-tune）训练任务全生命周期：创建、查询、日志/trajectory、指标分析、最佳 step 选择、导出为 custom model（mcj-*）。
- 训练数据来自 `dataset` 域的 Dataset/版本；本域负责超参、资源组匹配、价格查询与训练方法选择；
- 导出部署衔接 `models custommodel` 与 `infer`：导出产物是 cm-* 自定义模型，再按推理接入点工作流上线。
### train finetune artifacts export
把一个或多个 mcj 产物（例如 global_step_2）导出为可部署的 cm-* 实体。输出 `{job_id, items[]}`，每项含 custom_model_name / custom_model_id / export_status。命名规则：设置 --custom-model-name-prefix 时为 `_`，否则保留后端默认名。建议先用 `arkcli train finetune artifacts list ` 查出 artifact_name。
```Bash
arkcli train finetune artifacts export
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--artifact-name` | string_slice | 要导出的产物（output）名，例如 global_step_2。可重复。 |
| `--custom-model-name-prefix` | string | 导出后 cm-* 名称的前缀。最终名称为 `_`。留空表示沿用后端默认名。 |
### train finetune artifacts list
列出精调任务的训练产物（Outputs[] 投影：artifact_name / export_status / custom_model_name / custom_model_id / create_time）。用 `--format table` 便于人工挑选。默认会并发调用 GetCustomModel 回填 custom_model_name；传 --lite 可跳过该查询。
```Bash
arkcli train finetune artifacts list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--format` | string | 输出格式：json（默认）\| table |
| `--lite` | bool | 跳过逐个 cm 的 GetCustomModel 名称查询。更快，但 custom_model_name 会为空。 |
### train finetune capability get
查看某个基础模型（或自定义模型的来源模型）支持哪些精调训练方法。基础模型传 --model + 可选 --version；自定义模型传 --model-id（cm-xxx）——后者会在底层解析到其来源 FoundationModel，与 maas-fe 的 CustomBoard 一致（自定义模型本身不携带能力列表，续训支持由底座的 FinetuneTypes 推导）。返回 supported_types（arkcli 参数写法：sft / lora / dpo / dpo-lora / grpo / grpo-lora / ppo / opd / opd-lora / pt，与 `train finetune create --type` 一致）与 supported_types_wire（后端 CustomizationType 字面量）。--version 语义：与 --model 同用时，--version 为空只返回主版本；--version 与 --model-id 互斥（cm 绑定的来源版本会自动解析——二者传其一，不要同时传）。配合 `models finetune-config` 可获取所选 --type 的超参数 schema。
```Bash
arkcli train finetune capability get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称，如 doubao-seed-1-6-flash。与 --model-id 互斥 |
| `--version` | string | 模型版本，如 250828；留空 = 仅主版本。与 --model-id 互斥（cm 自带绑定的来源版本） |
| `--model-id` | string | 自定义模型 ID（cm-xxx）。与 --model/--version 互斥。会解析到其来源基础模型，并报告该基础模型的能力 |
### train finetune create
创建精调任务。除兼容旧参数（--dataset、--epochs、--lr、--lora-rank、--beta）外，还支持对齐 PRD 的新增项：本地文件、RL 流程、数据容错、超参数 JSON、模型保存上限、轨迹记录。
```Bash
arkcli train finetune create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string（必填） | 任务名称 |
| `--type` | string（必填） | 定制类型：sft \| lora \| dpo \| dpo-lora \| grpo \| grpo-lora \| ppo \| opd \| opd-lora \| pt |
| `--description` | string | 任务描述 |
| `--model` | string | 基础模型名称（如 doubao-seed-1-6-flash），与 --model-id 互斥 |
| `--model-version` | string | 基础模型版本（如 250615），配合 --model 使用 |
| `--model-id` | string | 自定义模型 ID，与 --model/--model-version 互斥 |
| `--dataset` | string | 训练数据集：tos://bucket/path 或数据集 ID（ds-xxx）。旧版合并参数——建议改用 --train-tos-uri / --train-dataset |
| `--dataset-version` | string | 数据集版本 ID（dsv-xxx），当 --dataset 传数据集 ID 时必填。旧写法——建议改用 --train-dataset-version |
| `--train-tos-uri` | string | 训练数据 TOS URI（tos://bucket/prefix）。输入为 TOS 路径时，与 PRD 对齐的 --dataset 别名 |
| `--train-dataset` | string | 训练数据集及版本，格式 :；旧的 --train-dataset-version 分开写法仍支持 |
| `--train-dataset-version` | string | 训练数据集版本 id（dsv-yyy）。与 PRD 对齐的 --dataset-version 别名 |
| `--train-file` | string_slice | 本地训练文件路径（可重复；映射到 data.training_set.local_files[]） |
| `--train-path` | string_slice | 托管数据集路径 JSON（可重复）：{"dataset_id":"ds-...","dataset_version_id":"dsv-...","multiplier":1}，或把 multiplier 换成 sample_count |
| `--preset-dataset` | string_slice | 预设数据集 JSON（可重复）：{"dataset_version_id":"dsv-...","inject_multiplier":1}；inject_multiplier 与 inject_sample_count 二选一 |
| `--validation-dataset` | string | 验证数据集及版本，格式 :；旧的 tos:// 与分开写版本的形式仍支持 |
| `--validation-dataset-version` | string | 验证数据集版本 id（dsv-xxx） |
| `--validation-tos-uri` | string | 验证数据 TOS URI（tos://bucket/prefix）。与 PRD 对齐的别名 |
| `--validation-dataset-id` | string | 验证数据集 id（ds-xxx）。与 PRD 对齐的别名 |
| `--validation-file` | string_slice | 本地验证文件路径（可重复；映射到 data.validation_set.local_files[]） |
| `--validation-percentage` | int | 用作验证集的训练集比例（例如 10）；与 --validation-dataset/--validation-file 互斥 |
| `--max-invalid-records-ratio` | string | 允许的坏样本比例，取值 [0,1)（例如 0.01） |
| `--max-invalid-records-number` | int | 允许的坏样本绝对条数（正整数） |
| `--shuffle-random-seed` | string | -1 = 每次运行随机，0 = 不洗牌，正数 = 固定种子以便复现（字符串类型，使 0 与未设置区分开） |
| `--hyperparameters` | string | JSON 字典或 @file（例如 '{"epoch":"3","batch_size":"8"}' 或 @hyperparameters.json）。会与标量参数 --epochs/--lr/--lora-rank/--beta 合并（冲突时以标量参数为准） |
| `--epochs` | int | 训练轮数（--hyperparameters epoch 的旧写法） |
| `--lr` | string | 学习率（--hyperparameters learning_rate 的旧写法） |
| `--lora-rank` | int | LoRA 秩（--hyperparameters lora_rank 的旧写法） |
| `--beta` | string | DPO 的 beta 参数（--hyperparameters beta 的旧写法） |
| `--save-model-limit` | int | 保留的训练产物数量上限（1-10；后端默认 1） |
| `--enable-trajectory` | bool | 开启 RL rollout 轨迹记录（调试 GRPO/PPO 时推荐） |
| `--pipeline` | string | @file 形式的 JSON RL pipeline 配置路径（custom_rl_pipeline；自定义 rollout/grader 的 GRPO/PPO 必填） |
| `--resource-group` | string | 资源组 ID；请按查询结果原样传入，提交前会检查当前账号/项目权限、任务资源模板和资源组可用性 |
| `--yes` | bool | Skip the interactive confirmation prompts: the upload-to-TOS gate (--train-file) and the final submit prompt. NOTE: model activation (开通) is hard-refused in non-interactive (agent/CI/pipe) regardless of --yes — set ARKCLI_ALLOW_HEADLESS_ACTIVATION=1 for unattended activation, otherwise the base model must already be activated. |
| `--estimate` | bool | 只做在线 Token 与价格试算，不创建精调任务 |
### train finetune delete
删除精调任务记录（不可逆）。用 --yes 跳过确认提示，脚本场景推荐。仅处于终态（Completed / Failed / Terminated）的任务可删除；非终态任务会在 shortcut 层被拒绝，并提示先执行 `train finetune stop`（省去一次注定失败调用上的确认往返——否则后端会以 `OperationDenied.UnsupportedPhase` 拒绝）。对 Agent 的要求：先用 `train finetune get` 查看目标，复述任务 ID 与影响，取得明确确认后再删除。
```Bash
arkcli train finetune delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互确认提示 |
### train finetune get
获取精调任务的完整详情（状态 / 配置 / 产物）。数据与当前的 `train finetune status` 相同，这是 PRD 规定的读取入口。要看训练步进度用 `train finetune metrics`；要实时轮询用 `train finetune watch`。不含费用——接口 schema 没有按任务的计费字段；提交前在线估算请用 `train finetune create --estimate`。
```Bash
arkcli train finetune get
```
### train finetune list
列出模型精调任务
```Bash
arkcli train finetune list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--page-number` | int | 页码（必须大于等于 1，默认 1） |
| `--page-size` | int | 每页条数（1-100，默认 100） |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：Asc \| Desc |
| `--phase` | string_slice | 按阶段过滤（可重复）：Preprocessing \| Queued \| Deploying \| Running \| Pausing \| Paused \| Terminating \| Terminated \| Completing \| Completed \| Failed |
| `--name` | string | 按任务名称过滤（模糊匹配） |
| `--customization-type` | string_slice | 按定制类型过滤（可重复）：FinetuneSft \| FinetuneLoRA \| DPO \| DPOLoRA \| GRPO \| GRPOLoRA \| PPO \| OPD \| OPDLoRA \| Pretrain |
| `--create-time-after` | string | 过滤该时间之后创建的任务（RFC3339，例如 2026-01-01T00:00:00Z） |
| `--create-time-before` | string | 过滤该时间之前创建的任务（RFC3339） |
### train finetune logs
跟踪精调任务的训练日志。默认数据源是公网 ARK Action `GetTaskLogs`（与 maas 控制台「训练日志」页一致）——即 system / 训练框架的 stdout，任意鉴权 profile 均可访问。支持 --follow / --tail / --search / --since；任务进入终态且没有新行后 --follow 会自动退出；--tail >1000 时自动分批。加 --custom 后数据源切换为该任务专属的 CustomTLSConfig topic——RL 插件（rollout / grader）函数的 stdout，与 maas 控制台「自定义日志（TLS）」子页一致。--custom 需要火山 SSO STS（直连 TLS，与轨迹相同），且只对开启了 --enable-trajectory 并启用了 project 级 TLS 的 RL 任务有效（见 `arkcli train finetune tls config get`）；--custom 不支持 --follow。--all 会导出超过 --tail 上限的全部日志（一直翻页到后端 ListOver），并且必须配合 --output FILE，避免 10MB+ 日志撑爆 Agent 上下文。
```Bash
arkcli train finetune logs
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--tail` | int | Tail 大小：每次请求拉取的行数。默认 200；maas-fe 控制台默认 2000。设置 --all 时忽略。 |
| `--follow` | bool | 任务运行期间持续轮询新日志行；进入终态且无新行后自动停止。用 --interval 调整轮询节奏。不支持与 --custom 或 --all 同用。 |
| `--interval` | string | --follow 的轮询间隔，支持时长写法（5s、30s）或纯整数秒。默认 5s。 |
| `--search` | string | 服务端筛选；GetTaskLogs 来源使用 FilterExpression；TLS 自定义日志使用 content 过滤。 |
| `--since` | string | 起始时间，相对于当前时间的时长（如 30m、2h）；TLS 自定义日志默认 30 天，GetTaskLogs 来源默认不限制起始时间。 |
| `--json` | bool | 输出结构化 JSON，替代纯文本行。 |
| `--custom` | bool | 读取 RL 插件函数的 stdout（CustomTLSConfig TLS topic），而不是 system / 训练框架日志。需要火山 SSO + RL 任务 + --enable-trajectory。 |
| `--function-name` | string | 仅 TLS --custom：按插件函数名筛选（如 SingleRollout-xxx），对应 function_name 查询。 |
| `--all` | bool | 分页读取全部日志，忽略 --tail；必须提供 --output FILE。GetTaskLogs 使用 Ctx 游标，TLS 使用 Context 游标。 |
| `--output` | string | 写入日志文件：GetTaskLogs 为纯文本，TLS 自定义日志为 JSON；stdout 仅返回元数据。--all 时必填。 |
### train finetune metrics
获取精调任务的训练指标。底层分两步：先用 GetModelCustomizationJobMetrics 返回可用指标名（如 train/loss、eval/loss、train/lr、train/grad_norm；DPO/GRPO 任务前缀不同），再用 GetModelCustomizationJobMetricData 拉取逐步时间序列。用 --metric（可重复）过滤；默认返回全部可用指标。用 --output 把 JSON 落盘（便于 Agent 渲染图表）。
```Bash
arkcli train finetune metrics
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--metric` | string_slice | 只取一个或多个指标名（可重复）。留空表示全部可用指标 |
| `--min-sample-step` | int | 最小采样 step（服务端降采样） |
| `--max-metric-point` | int | 每个指标最多返回的采样点数（服务端会均匀降采样） |
| `--from-step` | int | 范围过滤：只返回 step >= 该值的样本 |
| `--to-step` | int | 范围过滤：只返回 step <= 该值的样本 |
| `--output` | string | 将响应 JSON 写入该文件路径；便于 Agent 渲染图表 |
### train finetune pause
暂停运行中的精调任务（可通过 `train finetune resume` 恢复）。与不可逆终止的 `stop` 不同。
```Bash
arkcli train finetune pause
```
### train finetune pricing
查询基础模型的精调价格。--billing-method=token 时，按 --type 过滤基础模型计费项：lora / lora-sft / dpo-lora / grpo-lora / opd-lora → LoRA 精调；sft / dpo / grpo / ppo / opd / pt → 全参精调。--type 为空则返回全部精调相关计费项。--billing-method=instance 时，解析出精确的模型版本/类型超参数 schema，列出可用的训练资源模板，并关联其 FlavorSum 小时价。指定 --type 时，arkcli 会与 `train finetune capability get` 交叉校验，模型不支持该训练方法时直接拒绝（对不支持的方法返回通用计费项价格会误导调用方）。
```Bash
arkcli train finetune pricing
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string（必填） | 基础模型名称，如 doubao-seed-1-6-flash |
| `--type` | string | 定制类型：sft \| lora \| lora-sft \| dpo \| dpo-lora \| grpo \| grpo-lora \| ppo \| opd \| opd-lora \| pt；留空 = 全部 |
| `--billing-method` | string | 计费方式：token \| instance |
| `--model-version` | string | 基础模型版本；--billing-method=instance 时必填 |
| `--hyperparameters` | string | 仅实例计费时：JSON 字典或 @file；会与模型默认值以及 --epochs/--lr/--lora-rank/--beta 等标量覆盖项合并 |
| `--epochs` | int | 仅实例计费时：覆盖 epoch |
| `--lr` | string | 仅实例计费时：覆盖 learning_rate |
| `--lora-rank` | int | 仅实例计费时：覆盖 lora_rank |
| `--beta` | string | 仅实例计费时：覆盖 beta |
| `--region` | string | 仅 Token 计价：价格地域，默认取当前 profile 的地域 |
### train finetune resource-group list
检查资源组权限，并按当前精调模型、训练类型和超参数列出任务资源需求与可用资源组
```Bash
arkcli train finetune resource-group list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 基础模型名称；与 --model-id 互斥 |
| `--model-version` | string | 基础模型版本；使用 --model 时必填 |
| `--model-id` | string | 已有自定义模型 ID；会解析其基础模型，与 --model/--model-version 互斥 |
| `--type` | string（必填） | 训练类型：sft \| lora \| dpo \| dpo-lora \| grpo \| grpo-lora \| ppo \| opd \| opd-lora \| pt |
| `--hyperparameters` | string | 超参数 JSON 或 @file；与创建任务保持一致 |
| `--epochs` | int | epoch 快捷覆盖值 |
| `--lr` | string | learning_rate 快捷覆盖值 |
| `--lora-rank` | int | lora_rank 快捷覆盖值 |
| `--beta` | string | beta 快捷覆盖值 |
| `--only-matched` | bool | 只返回当前任务可以使用的资源组 |
### train finetune resume
恢复已暂停（Paused）的精调任务；后端允许时也可重试 Failed / Terminated 任务
```Bash
arkcli train finetune resume
```
### train finetune sdk login
用 arkcli 的 STS 写入 ark_sdk 的 `~/.ark/authorization.json`——替代 `ark login`。仅当用户自己跑 `python3 submit_job.py` 时才需要：ark_sdk 0.6.0 Python 库的提交热路径只读该文件（不读环境变量），属上游 SDK 限制。用 YAML 规格提交请改用 `train finetune sdk submit `——它不会写 authorization.json（使用 0600 的临时凭证文件，作用域限定在 ark 进程内）。STS 过期会自动刷新。若已存在属于其他账号的文件，除非传 --force，否则拒绝覆盖。
```Bash
arkcli train finetune sdk login
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--refresh` | bool | 写入前强制刷新产品原生 SSO STS。 |
| `--force` | bool | 即使已存在的 authorization.json 的 account_id 与 arkcli 当前 profile 不同，也强制覆盖。 |
| `--path` | string | 覆盖输出路径。默认：~/.ark/authorization.json（与 ARK_SDK_AUTHORIZATION_FILE 环境变量一致）。 |
### train finetune status
获取精调任务详情（`get` 的别名；若后端拆分 API，预留给未来的精简阶段 / 进度投影）
```Bash
arkcli train finetune status
```
### train finetune stop
停止运行中的精调任务（不可逆——会终止任务；若想之后恢复请改用 `train finetune pause`）。默认 [y/N] 确认；`--yes` 跳过提示。
```Bash
arkcli train finetune stop
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过 [y/N] 确认提示。非交互执行（CI / 管道 / agent）时必填。 |
### train finetune tls config delete
永久删除该 project 的精调 TLS 资源——会销毁已存储的轨迹 / 自定义日志 / trace / 可解释性数据。不可逆。传 --yes 跳过 [y/N] 确认。删除后可随时通过 `arkcli train finetune tls config enable` 重新开启（会创建全新的空 topic）。
```Bash
arkcli train finetune tls config delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--project-name` | string | 覆盖项目名称（默认：当前 profile 的项目） |
| `--yes` | bool | 跳过 [y/N] 确认提示 |
### train finetune tls config disable
关闭 project 级精调 TLS（停止新数据写入；已有数据按 TLS 保留策略保留）。传 --yes 跳过 [y/N] 确认。若要永久删除 TLS 资源（数据一并销毁），请改用 `arkcli train finetune tls config delete`。
```Bash
arkcli train finetune tls config disable
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--project-name` | string | 覆盖项目名称（默认：当前 profile 的项目） |
| `--yes` | bool | 跳过 [y/N] 确认提示 |
### train finetune tls config enable
开启 project 级精调 TLS 资源（会创建四个后付费火山 TLS topic——产生费用）。本项目内任何任务要记录轨迹 / 自定义插件 stdout / trace / token 级数据，都必须先开启。默认 [y/N] 确认，因为会开通计费资源；传 --yes 跳过（非交互调用方 / Agent 必须传）。该在线开通流程不支持 --dry-run，请先确认当前 project 再显式确认。注意：子账号 IAM 用户可能没有权限，需请主账号管理员在 maas 控制台开启。
```Bash
arkcli train finetune tls config enable
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--project-name` | string | 覆盖项目名称（默认：当前 profile 的项目） |
| `--yes` | bool | 跳过 [y/N] 确认提示（非交互执行时必填） |
### train finetune tls config get
查看 project 级精调 TLS 状态：是否已开启，以及支撑 `--enable-trajectory` / RL 插件日志 / trace / 可解释性数据的四个 topic id（trajectory / custom / trace / explainability）。project 默认取当前生效 profile 的 project，可用 --project-name 覆盖。
```Bash
arkcli train finetune tls config get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--project-name` | string | 覆盖项目名称（默认：当前 profile 的项目） |
### train finetune trajectory get
获取单条 rollout 轨迹记录（始终返回完整内容；单条约 3KB）。用 --sample-id（精确匹配）或 --step + --index（该 step 下第 i 条 rollout）指定。SSO 要求与 `trajectory list` 相同。
```Bash
arkcli train finetune trajectory get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--sample-id` | string | Sample id（smpl-...）。与 --step/--index 互斥。 |
| `--step` | int | Step 序号（配合 --index 选取指定 rollout） |
| `--index` | int | 该 step 内从 0 开始的 rollout 序号（默认 0） |
| `--since` | string | 相对当前时间的时间窗口。默认 30d。 |
| `--output` | string | 将 JSON 写入该文件路径 |
### train finetune trajectory list
列出某精调任务的 RL rollout 轨迹。直接从该任务对应的火山 TLS topic（TrajectoryTLSConfig.TopicID）读取——绕过 ARK 控制面。默认输出为摘要（step / sample_id / phase / reward / advantage / tokens / duration），对 Agent 友好，约 150 字节/条。传 --full 得到完整形态（展开 sample / trajectory / metrics / reward_details / plugin_details，约 3KB/条）。传 --output FILE 可把完整 JSON 落盘，stdout 只留一小段元信息。需要 SSO 认证的 profile（与 logs 的限制相同）。
```Bash
arkcli train finetune trajectory list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--step` | int | 按 step 序号过滤（例如 --step 20） |
| `--phase` | string | 按阶段过滤：train \| eval |
| `--sample-id` | string | 按 sample id 过滤（smpl-...） |
| `--query` | string | 原始 TLS 查询表达式；覆盖 --step/--phase/--sample-id |
| `--limit` | int | 最多返回的条目数（默认 200；因 TLS API 单次上限 100，超过 100 会自动分页）。--all 时忽略。 |
| `--since` | string | 相对当前时间的时间窗口（30m / 2h / 24h）。默认 30d（覆盖 TLS 完整保留期）。 |
| `--full` | bool | 返回完整内容：sample / trajectory / metrics / reward_details / plugin_details（约 3KB/条，较重） |
| `--all` | bool | 一直分页直到后端把该 topic 读完。必须配合 --output FILE——拒绝把无界数据直接打到 stdout。 |
| `--output` | string | 将完整 JSON 写入该文件路径；stdout 只显示元信息（推荐 Agent 场景使用）。设置 --all 时必填。 |
### train finetune update
更新精调任务的可变字段（name / description）。--name 与 --description 至少要传一个；空字段不会被提交。
```Bash
arkcli train finetune update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | 新的任务名称 |
| `--description` | string | 新的任务描述 |
### train finetune watch
轮询精调任务直到进入终态（Completed / Failed / Terminated）。默认模式：按阶段逐行把进度输出到 stderr；--rich 模式额外给出步进度条 / ETA / 各指标迷你走势（最近 30 步）。免去 Agent/CI 自己写轮询循环。
```Bash
arkcli train finetune watch
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--interval` | string | 轮询间隔，支持时长写法（如 15s、1m、1h30m）或纯整数秒。默认 30s；--rich 模式默认 5s，与 maas-fe 的进度图一致 |
| `--timeout` | string | 总等待上限，可用时长（如 30m、2h）或纯整数秒；0 = 不超时（默认 0） |
| `--quiet` | bool | 关闭每次 tick 打印到 stderr 的进度 |
| `--rich` | bool | 渲染 PRD 风格 TUI：step / 进度条 / ETA / 迷你趋势图指标。stderr 不是 TTY 时自动关闭。 |
| `--metric` | string_slice | （--rich）要渲染成迷你走势的指标（以 / 分隔的键，例如 train/loss、train/lr、train/grad_norm）。默认：train/loss、train/lr、train/grad_norm、train/global_step。可重复。 |
---
# 工具与平台
Source: https://ark.volcengine.com/region:cn-beijing/docs/tools-and-platform
接入与工具：把方舟能力配置进第三方 Agent、安装内嵌 Skills、生成调用示例、原始 API 兜底，以及 CLI 自升级与体验入口。
- `helper` 配置 model/provider 与 Harness 工具能力；`+connect` 安装二进制内嵌 Skills；`+code-example` 生成多语言调用示例；
- `api` 是已注册 Action 的兜底通道，先用产品命令、覆盖不到再用；
- `update` 只响应显式调用，无静默升级；`exp` 是 Volc 专属的交互式 TUI 体验入口。
## +code-example
为指定基础模型生成多语言（Python / Go / Java / Node / curl）调用示例代码并写入本地文件。
```Bash
arkcli +code-example
```
示例：
```Bash
arkcli +code-example \
--model doubao-seedream-5-0 \
--language python \
--format json
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string（必填） | 基础模型名称或捆绑 id（如 doubao-seedream-5-0 或 doubao-seedream-5-0-260128） |
| `--version` | string | 基础模型版本（如 260128）；若 --model 已带版本则省略 |
| `--language` | string | 按语言过滤：python、go、java、node、curl（默认全部） |
| `--lang` | string | --language 的已废弃别名；在本命令上选择 UI 语言请用根命令的 --ui-lang |
| `--output-dir` | string | 示例文件输出目录（默认：./ark-examples/） |
## +connect
把 arkcli 内置 AI skills 安装到本机检测到的所有 AI Agent
```Bash
arkcli +connect
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--path` | string | 把 arkcli skills 安装到指定的本地 skills 目录，而不是自动探测的全局 agent 目录；相对路径基于当前工作目录解析 |
| `--refresh` | bool | 对外版:先从 CDN(首选)/ GitHub(兜底)重新下载最新 skill 再安装(内场版 skill 已内嵌,此标志为空操作) |
| `--keep-conflicting` | bool | 保留会劫持 +gen 路由的第三方生成技能（byted-ark-seedance/seedream）；默认 +connect 会把它们从各 Agent 目录中移除 |
### +connect list
列出支持的 AI Agent 及检测状态
```Bash
arkcli +connect list
```
### +connect uninstall
从检测到的 AI Agent 中卸载 arkcli AI skills
```Bash
arkcli +connect uninstall
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--path` | string | 只从指定的本地 skills 目录卸载 arkcli skills，而不是自动探测的全局 agent 目录；相对路径基于当前工作目录解析 |
| `--purge-prefix` | bool | 破坏性删除所有以 ark-/arkcli- 为前缀的目录或软链接，包括非 ArkCLI 管理的条目 |
## api
已注册 Action 的原始 API 浏览器
```Bash
arkcli api [registered-action]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--dry-run` | bool | 预览客户端执行计划，不发网络请求、无副作用 |
| `--list` | bool | 列出全部已注册的 API Action |
| `--params` | string | JSON 请求体 |
## exp
启动方舟体验 TUI
```Bash
arkcli exp
```
### exp uninstall
卸载方舟体验 TUI
```Bash
arkcli exp uninstall
```
## helper
交互向导：把本机 AI Agent 配置到 Platform Endpoint 或受支持的 Plan
```Bash
arkcli helper
```
### helper configure
非交互配置单个 harness 到 Platform Endpoint 或受支持的 Plan
```Bash
arkcli helper configure
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | 目标 Platform / Plan profile（默认当前 active） |
| `--model` | string | Plan model ID（默认取该 plan 选中/首个模型；Platform 不可用） |
| `--endpoint` | string | 已验证的 Platform 文本 Endpoint ID（仅 Platform profile 必填） |
| `--codex-config-scope` | string | (仅 Codex)配置范围:profile(默认,写 ~/.codex/arkcli.config.toml)\|global(写 ~/.codex/config.toml) |
| `--codex-profile` | string | (仅 Codex profile 模式)Codex profile 名,默认 arkcli |
| `--dsh-config-scope` | string | (仅 DSH)配置范围:home(默认,写 $DSH_HOME/cordis.patch.yml)\|profile(写 $DSH_HOME/profiles//cordis.patch.yml,需 --dsh-profile) |
| `--dsh-profile` | string | (仅 DSH)profile scope 的 DSH profile 名 |
| `--with-mcp` | bool | 同时注入 Agent Plan 内置 MCP(豆包搜索 + dataPro + OpenViking;仅 Agent Plan 含团队版、且支持 MCP 的 harness 生效) |
| `--keep-native-websearch` | bool | 保持原生 WebSearch 开启 |
| `--with-cua` | bool | 同时安装云电脑(CUA)skill(仅 Agent Plan 个人版 Medium/Large/Max;一次性装给所有已安装的 AI Agent;失败只 warn) |
| `--with-routing` | bool | 启用 Agent Plan 强制搜索路由（同时配置所选业务 MCP） |
| `--with-supabase` | bool | 同时装 byted-supabase CLI+Skill 并注入火山登录态(仅 Agent Plan 家族;个人版全档 + 团队版全档;与 harness 无关、失败只 warn) |
### helper list
列出支持的 AI Agent 及其安装状态、配置路径
```Bash
arkcli helper list
```
### helper mcp
为目标 agent 配置 Agent Plan Harness 工具;默认配置整组 MCP(豆包搜索 + DataPro + OpenViking),可用 --capability 只配单项。不传 target 自动检测;不改模型
```Bash
arkcli helper mcp [target]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--capability` | string | 只配置一项 Harness 能力:datapro \| web-search \| agent-memory(不传则保持整组 MCP 旧行为) |
| `--profile` | string | 指定 Agent Plan profile(默认自动定位账号下的 agent-plan / agent-plan-team profile,与当前 active profile 无关) |
| `--ov-resource` | string | 指定 OpenViking 库(按库名;账号有多个库时必填,不填会报错列出可选库名) |
| `--scope` | string | MCP 写入范围:global(默认,用户级 ~/.trae/mcp.json 等)\| project(仅 Trae,写当前目录 ./.trae/mcp.json) |
| `--codex-config-scope` | string | (仅 Codex)配置范围:profile(默认,写 ~/.codex/arkcli.config.toml)\|global(写 ~/.codex/config.toml) |
| `--codex-profile` | string | (仅 Codex profile 模式)Codex profile 名,默认 arkcli |
| `--dsh-config-scope` | string | (仅 DSH)配置范围:home(默认,写 $DSH_HOME/cordis.patch.yml)\|profile(写 $DSH_HOME/profiles//cordis.patch.yml,需 --dsh-profile) |
| `--dsh-profile` | string | (仅 DSH)profile scope 的 DSH profile 名 |
| `--keep-native-websearch` | bool | 保持原生 WebSearch 开启 |
### helper reset
移除 arkcli 为某 harness 注入的配置(含 MCP),保留用户其它设置
```Bash
arkcli helper reset
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--scope` | string | (仅 Trae)移除范围:global(默认,~/.trae/mcp.json)\| project(./.trae/mcp.json) |
| `--codex-config-scope` | string | (仅 Codex)移除范围:profile(默认,~/.codex/arkcli.config.toml)\|global(~/.codex/config.toml) |
| `--codex-profile` | string | (仅 Codex profile 模式)Codex profile 名,默认 arkcli |
| `--dsh-config-scope` | string | (仅 DSH)配置范围:home(默认,写 $DSH_HOME/cordis.patch.yml)\|profile(写 $DSH_HOME/profiles//cordis.patch.yml,需 --dsh-profile) |
| `--dsh-profile` | string | (仅 DSH)profile scope 的 DSH profile 名 |
### helper supabase
装 byted-supabase-cli + skill 并注入火山 Agent Plan 登录态(打通 byted-supabase 数据库能力);仅 Agent Plan(个人版全档 + 团队版全档)
```Bash
arkcli helper supabase
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | 指定 Agent Plan profile(默认自动定位账号下的 agent-plan / agent-plan-team profile,与当前 active 无关) |
## update
升级 arkcli 到最新稳定版本
```Bash
arkcli update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--check` | bool | 只检查是否有新版本, 不执行升级 |
| `--refresh` | bool | 配合 --check: 强制联网查询最新版本 (默认只读本地缓存) |
| `--yes` | bool | 跳过交互确认, 直接升级 |
---
# Managed Agents
Source: https://ark.volcengine.com/region:cn-beijing/docs/managed-agents
ARK Managed Agents：Agent / Skill / Env / Session / File / Memory Store / Vault 的完整生命周期，以及围绕会话的高频快捷工作流。
- `agent` 域管八大资源类型：控制面（Agent/Skill/Env 定义）走 ForTop/OpenTOP，数据面（Session 运行时、文件）直联；
- 快捷工作流按生命周期分工：`+new-agent` / `+iterate` 建与改，`+new` 起会话，`+tail` / `+debug` / `+export` 观察与导出；
- 典型链路：`agent create` → `env create` → `session create` → `session events send/stream`。
## +debug
诊断某个托管智能体会话（事件、错误与执行状态，按 session-id）
```Bash
arkcli +debug
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--limit` | int | 最多检查的最近事件数 |
| `--session-thread-id` | string | 按会话 thread id 过滤事件 |
## +export
把托管智能体会话诊断信息导出为本地归档
```Bash
arkcli +export
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--output` | string | 输出 .tar.gz 路径 |
| `--limit` | int | 最多导出的事件数 |
| `--session-thread-id` | string | 按会话 thread id 过滤事件 |
## +iterate
更新托管智能体、新建一个会话，然后可选进入对话
```Bash
arkcli +iterate
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--env-id` | string | 新会话使用的环境 ID；默认取最新环境（--environment-id 的别名） |
| `--environment-id` | string | 新会话使用的环境 ID；默认取最新环境 |
| `--title` | string | 新会话标题 |
| `--resource` | string | 新会话的 Resources 数组 |
| `--tos-path` | string | 要挂载的 TOS 目录，例如 tos://bucket/prefix/ |
| `--vault-id` | string_slice | 新会话的 Vault id；逗号分隔或重复传入 |
| `--vault-ids` | string_slice | 新会话的 Vault id；逗号分隔或重复传入 |
| `--tags` | string | 会话 tags 映射或 tag 数组 |
| `--agent-overrides` | string | AgentWithOverrides 对象；行内 JSON/YAML 或 @file |
| `--environment-overrides` | string | EnvironmentWithOverrides 对象；行内 JSON/YAML 或 @file |
| `--message` | string | 创建会话后发送一条消息，空闲后退出 |
| `--session-thread-id` | string | 首条消息 / REPL 的目标会话 thread id |
| `--no-event-deltas` | bool | 不请求 PRD 的 event_start/event_delta 帧，只使用完整事件 |
| `--raw` | bool | 对话时打印原始 NDJSON 流事件 |
| `--no-chat` | bool | 只更新 Agent 并创建 Session，不进入 chat/REPL |
| `--diff` | bool | 预览 update/session/chat 的请求内容，不改变远端状态 |
| `--file` | string | JSON/YAML 格式 UpdateAgentRequest 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--version` | int | 可选的 Agent 当前版本；省略或为 0 时从 GetAgent 自动读取，正数用于显式并发版本检查 |
| `--name` | string | Agent 名称 |
| `--display-name` | string | Agent 展示名 |
| `--model` | string | 模型 ID 或包含 id/provider/speed/thinking/reasoning_effort/service_tier 的对象 |
| `--speed` | string | 兼容保留的模型 speed 参数 |
| `--thinking` | string | 模型思考模式 |
| `--reasoning-effort` | string | 模型推理强度 |
| `--service-tier` | string | 模型服务等级 |
| `--description` | string | 智能体描述 |
| `--system` | string | System 提示词，或用 @file 从磁盘读取 |
| `--tool` | string_slice | 替换工具列表；可重复或直接传数组，用 [] 清空 |
| `--mcp-server` | string_slice | 替换 MCP server 列表；可重复传入或直接传数组，传 [] 表示清空 |
| `--skill` | string_slice | 替换技能列表；可重复或直接传数组，用 [] 清空 |
| `--multiagent` | string | 多 Agent 配置对象 |
| `--metadata` | string | 元数据补丁 map 对象；值为 null 表示删除该键 |
## +new
ARK Managed Agent 运行时命令：新建 Agent 会话（`+new session`）、创建新 Agent 定义（`+new-agent`）、迭代已有 Agent（`+iterate`）。
- 面向“让 Agent 跑起来”的任务入口：定义、会话、迭代一条链路；
- 底层资源仍归 `agent` 域管理，本域提供的是面向任务的快捷工作流。
### +new session
新建一个托管智能体会话，然后进入对话
```Bash
arkcli +new session [agent-id]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--agent-id` | string | 用于新建对话会话的智能体 ID |
| `--agent-version` | int | 新建对话会话使用的智能体版本 |
| `--env-id` | string | 新建对话会话使用的环境 ID（--environment-id 的别名） |
| `--environment-id` | string | 新建对话会话使用的环境 ID |
| `--title` | string | 新会话标题 |
| `--resource` | string | 新会话的 Resources 数组 |
| `--tos-path` | string | 要挂载的 TOS 目录，例如 tos://bucket/prefix/ |
| `--vault-id` | string_slice | 新会话的 Vault id；逗号分隔或重复传入 |
| `--vault-ids` | string_slice | 新会话的 Vault id；逗号分隔或重复传入 |
| `--tags` | string | 新会话的 tags 映射或 tag 数组 |
| `--agent-overrides` | string | AgentWithOverrides 对象；行内 JSON/YAML 或 @file |
| `--environment-overrides` | string | EnvironmentWithOverrides 对象；行内 JSON/YAML 或 @file |
| `--message` | string | 发送一条消息，会话回到空闲后退出 |
| `--session-thread-id` | string | 目标会话 thread id |
| `--no-event-deltas` | bool | 不请求 PRD 的 event_start/event_delta 帧，只使用完整事件 |
| `--max-event-chars` | int | 美化后事件文本最多显示的字符数；默认 2000，0 表示不限制 |
| `--raw` | bool | 打印原始 NDJSON 流事件 |
## +new-agent
用结构化字段创建托管智能体，可选择 fork 已有的智能体
```Bash
arkcli +new-agent
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--fork` | string | 在应用覆盖项之前要复制的已有智能体 ID |
| `--from` | string | --fork 的别名 |
| `--no-echo` | bool | 跳过最后的 GetAgent 回显，只打印 CreateAgent 响应 |
| `--file` | string | JSON/YAML 格式 CreateAgentRequest 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--name` | string | Agent 名称 |
| `--display-name` | string | Agent 展示名 |
| `--base-agent` | string | 基础智能体 ID |
| `--model` | string | 模型 ID 或包含 id/provider/speed/thinking/reasoning_effort/service_tier 的对象 |
| `--speed` | string | 兼容保留的模型 speed 参数 |
| `--thinking` | string | 模型思考模式 |
| `--reasoning-effort` | string | 模型推理强度 |
| `--service-tier` | string | 模型服务等级 |
| `--description` | string | 智能体描述 |
| `--system` | string | System 提示词，或用 @file 从磁盘读取 |
| `--tool` | string_slice | 完整替换 Tools 数组。省略时 arkcli 发送默认的 agent_toolset_20260701；传 [] 可关闭默认值 |
| `--mcp-server` | string_slice | MCP server 对象；可重复传入或直接传数组 |
| `--skill` | string_slice | Skill 对象；可重复传入或传数组。裸 skill-xxx ID 作为 custom TOP skill 且省略 Version 表示使用最新版；s-xxx SkillHub ID 必须传显式对象 |
| `--skill-zip` | string_slice | 通过 CreateSkill 上传并作为自定义技能挂载的本地技能 zip 包；可重复 |
| `--multiagent` | string | 多 Agent 配置对象 |
| `--metadata` | string | 元数据 map 对象 |
| `--tags` | string | Tags 映射或 tag 数组 |
| `--show-system` | bool | 在表格输出中展示完整 System 提示词 |
| `--yes` | bool | 在交互终端下跳过 [y/N] 模型开通确认。非交互模式除非设置 ARKCLI_ALLOW_HEADLESS_ACTIVATION=1，否则拒绝开通。 |
## +tail
持续跟踪托管智能体会话事件
```Bash
arkcli +tail
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--after` | string | 游标：取该事件 ID 之后的数据 |
| `--before` | string | 游标：取该事件 ID 之前的数据 |
| `--since` | string | 游标/时间下界 |
| `--created-after` | string | 事件 created_at 下界（RFC3339） |
| `--created-before` | string | 事件 created_at 上界（RFC3339） |
| `--type` | string_slice | 事件类型过滤；可重复或用逗号分隔 |
| `--session-thread-id` | string | 按会话 thread id 过滤 |
| `--no-event-deltas` | bool | 不请求 PRD 的 event_start/event_delta 帧，只使用完整事件 |
| `--max-event-chars` | int | 美化后事件文本最多显示的字符数；默认 2000，0 表示不限制 |
| `--order` | string | 排序方向：asc \| desc |
| `--raw` | bool | 打印原始 NDJSON 事件，而不是人类可读的 tail 视图 |
## agent
ARK Managed Agents 全生命周期管理：Agent、Skill、环境（Env）、会话（Session）、文件（File）、记忆库（Memory Store）、凭证保险库（Vault / MCP OAuth）八大资源类型。
- **控制面**（Agent/Skill/Env 定义）优先走 ForTop/OpenTOP，**数据面**（Session 运行时、文件上传下载）直联对应服务，CLI 自动分流；
- 典型链路：`agent create` 建定义 → `env create` 准备运行环境 → `session create` 起会话 → `session events send/stream` 驱动执行；
- `session compact/upgrade`、`env work stats` 等命令负责长会话压缩、热升级与算力用量审计；
- `vault credentials` 与 `vault oauth-flow` 管理敏感凭证，避免明文出现在命令行历史里。
### agent +mcp-login
创建 Vault MCP OAuth 流程：打开授权链接并等待回调
```Bash
arkcli agent +mcp-login
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--vault-id` | string（必填） | Vault id |
| `--display-name` | string | 凭证显示名 |
| `--name` | string | --display-name 的别名 |
| `--mcp-server-url` | string（必填） | MCP server URL |
| `--callback-host` | string | 本地回调监听地址（默认 127.0.0.1） |
| `--callback-port` | int | 本地回调监听端口；0 表示自动选择 |
| `--callback-path` | string | 本地回调 HTTP 路径（默认 /callback） |
| `--timeout` | string | 等待回调的最长时间，例如 5m 或 300s（默认 5m0s） |
| `--source` | string | 流程来源标记（默认 arkcli-mcp-login） |
| `--client-id` | string | 自定义 MCP/provider 覆盖模式下的 OAuth client id |
| `--client-secret` | string | OAuth client secret，或用 @file 从磁盘读取 |
| `--no-open` | bool | 不自动打开浏览器，改为打印授权 URL |
### agent activate
开通 Managed Agent 服务（账号级计费能力操作，仅火山版；已开通时直接返回状态，不重复开通）
```Bash
arkcli agent activate
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 在交互终端下跳过 [y/N] 开通确认。非交互模式除非设置 ARKCLI_ALLOW_HEADLESS_ACTIVATION=1，否则拒绝开通 |
### agent agent create
创建托管智能体定义（名称、模型、系统提示词、技能、工具）
```Bash
arkcli agent agent create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 格式 CreateAgentRequest 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--name` | string | Agent 名称 |
| `--display-name` | string | Agent 展示名 |
| `--base-agent` | string | 基础智能体 ID |
| `--model` | string | 模型 ID 或包含 id/provider/speed/thinking/reasoning_effort/service_tier 的对象 |
| `--speed` | string | 兼容保留的模型 speed 参数 |
| `--thinking` | string | 模型思考模式 |
| `--reasoning-effort` | string | 模型推理强度 |
| `--service-tier` | string | 模型服务等级 |
| `--description` | string | 智能体描述 |
| `--system` | string | System 提示词，或用 @file 从磁盘读取 |
| `--tool` | string_slice | 完整替换 Tools 数组。省略时 arkcli 发送默认的 agent_toolset_20260701；传 [] 可关闭默认值 |
| `--mcp-server` | string_slice | MCP server 对象；可重复传入或直接传数组 |
| `--skill` | string_slice | Skill 对象；可重复传入或传数组。裸 skill-xxx ID 作为 custom TOP skill 且省略 Version 表示使用最新版；s-xxx SkillHub ID 必须传显式对象 |
| `--skill-zip` | string_slice | 通过 CreateSkill 上传并作为自定义技能挂载的本地技能 zip 包；可重复 |
| `--multiagent` | string | 多 Agent 配置对象 |
| `--metadata` | string | 元数据 map 对象 |
| `--tags` | string | Tags 映射或 tag 数组 |
| `--show-system` | bool | 在表格输出中展示完整 System 提示词 |
| `--yes` | bool | 在交互终端下跳过 [y/N] 模型开通确认。非交互模式除非设置 ARKCLI_ALLOW_HEADLESS_ACTIVATION=1，否则拒绝开通。 |
### agent agent delete
删除托管智能体并级联删除其会话（需确认，或用 --yes 跳过）
```Bash
arkcli agent agent delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 硬删除及级联删除会话时跳过交互确认 |
### agent agent get
查看托管智能体定义（配置、版本、已绑定技能；--show-system 展示完整系统提示词）
```Bash
arkcli agent agent get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--version` | int | Agent 版本 |
| `--show-system` | bool | 在表格输出中展示完整 System 提示词 |
### agent agent list
按条件（名称、ID、时间范围）分页列出托管智能体
```Bash
arkcli agent agent list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--created-at-gte` | string | 按创建时间下界过滤（RFC3339） |
| `--created-at-lte` | string | 按创建时间上界过滤（RFC3339） |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
| `--id` | string | 按智能体 ID 过滤 |
| `--ids` | string_slice | 按智能体 ID 过滤，逗号分隔或重复传入 |
| `--name` | string | 按 Agent 名称过滤 |
| `--display-name` | string | 按 Agent 展示名过滤 |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：Asc \| Desc |
| `--show-system` | bool | 在表格输出中展示完整 System 提示词 |
### agent agent update
更新托管智能体定义（名称、模型、技能；--file 接受 JSON/YAML 载荷）
```Bash
arkcli agent agent update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 格式 UpdateAgentRequest 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--version` | int | 可选的 Agent 当前版本；省略或为 0 时从 GetAgent 自动读取，正数用于显式并发版本检查 |
| `--name` | string | Agent 名称 |
| `--display-name` | string | Agent 展示名 |
| `--model` | string | 模型 ID 或包含 id/provider/speed/thinking/reasoning_effort/service_tier 的对象 |
| `--speed` | string | 兼容保留的模型 speed 参数 |
| `--thinking` | string | 模型思考模式 |
| `--reasoning-effort` | string | 模型推理强度 |
| `--service-tier` | string | 模型服务等级 |
| `--description` | string | 智能体描述 |
| `--system` | string | System 提示词，或用 @file 从磁盘读取 |
| `--tool` | string_slice | 替换工具列表；可重复或直接传数组，用 [] 清空 |
| `--mcp-server` | string_slice | 替换 MCP server 列表；可重复传入或直接传数组，传 [] 表示清空 |
| `--skill` | string_slice | 替换技能列表；可重复或直接传数组，用 [] 清空 |
| `--multiagent` | string | 多 Agent 配置对象 |
| `--metadata` | string | 元数据补丁 map 对象；值为 null 表示删除该键 |
### agent agent versions
列出托管智能体的版本历史
```Bash
arkcli agent agent versions
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
### agent env create
创建托管智能体环境
```Bash
arkcli agent env create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--name` | string | 环境名称 |
| `--description` | string | 环境描述 |
| `--config` | string | 环境配置对象 |
| `--setup-script` | string | 环境初始化脚本，或 @file；写入 Config.SetupScript |
| `--metadata` | string | 元数据 map 对象 |
| `--scope` | string | 环境范围 |
| `--runtime-type` | string | 环境运行方式：cloud \| self_hosted（Config.Type） |
### agent env delete
删除托管智能体环境
```Bash
arkcli agent env delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--yes` | bool | 跳过删除的交互确认 |
### agent env get
获取托管智能体环境
```Bash
arkcli agent env get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
### agent env list
列出托管智能体环境
```Bash
arkcli agent env list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
| `--id` | string | 按环境 ID 过滤 |
| `--name` | string | 按环境名称过滤 |
| `--sort-by` | string | 排序字段 |
| `--sort-order` | string | 排序方向：Asc \| Desc |
### agent env update
更新托管智能体环境
```Bash
arkcli agent env update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--name` | string | 环境名称 |
| `--description` | string | 环境描述 |
| `--config` | string | 环境配置对象 |
| `--setup-script` | string | 环境初始化脚本，或 @file；写入 Config.SetupScript |
| `--metadata` | string | 元数据 map 对象 |
| `--scope` | string | 环境范围 |
### agent env work get
查询自托管 Work Item
```Bash
arkcli agent env work get
```
### agent env work list
列出自托管环境的 Work Items
```Bash
arkcli agent env work list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
### agent env work stats
查询自托管环境的队列统计
```Bash
arkcli agent env work stats
```
### agent env work stop
请求停止 Work Item
```Bash
arkcli agent env work stop
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--force` | bool | 立即将 Work 标记为 stopped；不代表远端 Sandbox 已退出 |
| `--yes` | bool | 确认停止此 Work Item |
### agent file delete
从 ARK Files 存储中删除文件
```Bash
arkcli agent file delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 确认删除 |
### agent file get
获取 ARK Files 存储中文件的元数据
```Bash
arkcli agent file get
```
### agent file list
列出已上传到 ARK Files 存储的文件
```Bash
arkcli agent file list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--limit` | int | 分页大小 |
| `--after` | string | 游标：取该文件 ID 之后的数据 |
| `--order` | string | 排序方向：asc \| desc |
| `--purpose` | string | 文件用途（默认 user_data） |
| `--session-id` | string | 按 managed-agent 会话范围过滤文件 |
### agent file upload
把本地文件或 URL 上传到 ARK Files 存储并返回 file_id
```Bash
arkcli agent file upload
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--path` | string | 以 multipart 字段 file 上传的本地文件路径 |
| `--url` | string | 要注册的 HTTP/HTTPS URL 或 tos:// URI；与 --path 互斥 |
| `--purpose` | string | 文件用途（默认 user_data） |
| `--session-id` | string | 附加 Ark-Agent-Session-Id 头，用于 managed-agent 会话范围的文件 |
| `--tos` | string | TOS 存储对象，例如 '{bucket: b, prefix: arkfiles/}' |
| `--preprocess-configs` | string | 预处理配置对象 |
| `--expire-at` | int | UTC Unix 时间戳（秒） |
| `--wait-active` | bool | 返回前轮询 file get 直到状态变为 active |
| `--wait-timeout` | int | 配合 --wait-active 的最长等待秒数；默认 120 |
| `--wait-interval` | int | 配合 --wait-active 的轮询间隔秒数；默认 2 |
### agent file wait
等待文件进入 active 状态
```Bash
arkcli agent file wait
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--wait-timeout` | int | 最长等待秒数；默认 120 |
| `--wait-interval` | int | 轮询间隔秒数；默认 2 |
### agent memory-store create
创建记忆库
```Bash
arkcli agent memory-store create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--name` | string | Memory Store 名称 |
| `--description` | string | 记忆库描述 |
### agent memory-store creators
列出记忆库创建者
```Bash
arkcli agent memory-store creators
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
### agent memory-store delete
删除记忆库
```Bash
arkcli agent memory-store delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--yes` | bool | 跳过删除的交互确认 |
### agent memory-store get
获取记忆库
```Bash
arkcli agent memory-store get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
### agent memory-store list
列出记忆库
```Bash
arkcli agent memory-store list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
| `--name` | string | 按 Memory Store 名称过滤 |
| `--created-by` | string_slice | 创建者用户 ID，逗号分隔或重复传入 |
### agent memory-store memories batch-create
批量创建记忆
```Bash
arkcli agent memory-store memories batch-create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--items` | string | 记忆条目数组 |
### agent memory-store memories create
创建记忆
```Bash
arkcli agent memory-store memories create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--path` | string | Memory 路径 |
| `--content` | string | 记忆内容，或用 @file 从磁盘读取 |
### agent memory-store memories delete
删除记忆
```Bash
arkcli agent memory-store memories delete [memory-id]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--yes` | bool | 跳过删除的交互确认 |
| `--memory-id` | string | 记忆 ID |
### agent memory-store memories get
获取记忆
```Bash
arkcli agent memory-store memories get [memory-id]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--memory-id` | string | 记忆 ID |
| `--view` | string | Memory 视图：basic \| full |
### agent memory-store memories list
列出记忆库中的记忆
```Bash
arkcli agent memory-store memories list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
| `--path-prefix` | string | Memory 路径前缀（默认 /） |
| `--updated-after` | string | 过滤在该时间之后更新的 Memory（RFC3339） |
| `--depth` | int | 列表深度 |
### agent memory-store memories update
更新记忆
```Bash
arkcli agent memory-store memories update [memory-id]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--memory-id` | string | 记忆 ID |
| `--path` | string | Memory 路径 |
| `--content` | string | 记忆内容，或用 @file 从磁盘读取 |
| `--content-sha256` | string | 用于乐观锁的当前内容 sha256 期望值 |
### agent memory-store update
更新记忆库
```Bash
arkcli agent memory-store update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--name` | string | Memory Store 名称 |
| `--description` | string | 记忆库描述 |
### agent model config
查询基础模型运行参数的支持值与默认值
```Bash
arkcli agent model config
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--provider` | string | 查询模型 metadata 使用的 provider（不切换账号或产品）（默认 ark） |
| `--key` | string_slice | Metadata key，可重复或逗号分隔；省略时查询全部配置 |
### agent model list
列出可作为托管智能体底座的基础模型
```Bash
arkcli agent model list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--usage` | string | 模型用途：agent（主模型，默认）或 tool（工具模型） |
| `--query` | string | 用于补充/排序 ArkModels managed-agent 白名单的用户意图或关键词 |
| `--name` | string | 按模型名称子串过滤 |
| `--refresh-cache` | bool | 同步刷新全版本 ArkModels 缓存；失败冷却期内不重试；query 模式同时刷新搜索缓存 |
| `--include-all` | bool | 不按所选用途过滤支持性，返回所有模型并标注能力 |
| `--primary-only` | bool | 从完整模型列表中只保留主版本 |
### agent session compact
压缩空闲 Managed Agent Session 的当前上下文
```Bash
arkcli agent session compact
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--instructions` | string | 可选压缩指令，或 @file |
| `--session-thread-id` | string | 目标 Session Thread ID |
| `--timeout` | int | 完成超时秒数；默认 120 |
| `--poll` | bool | 轮询事件列表，不建立 SSE 流 |
| `--raw` | bool | 输出原始 NDJSON 事件 |
### agent session create
创建托管智能体会话
```Bash
arkcli agent session create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--agent-id` | string | 智能体 ID |
| `--agent-version` | int | 智能体版本 |
| `--agent` | string | 已解析的智能体对象；设置后覆盖 --agent-id/--agent-version |
| `--env-id` | string | 环境 ID（--environment-id 的别名） |
| `--environment-id` | string | 环境 ID |
| `--title` | string | 会话标题 |
| `--resource` | string | Resources 数组 |
| `--tos-path` | string | 要挂载的 TOS 目录，例如 tos://bucket/prefix/；会追加一个 type=tos 资源 |
| `--vault-id` | string_slice | Vault id；逗号分隔或重复传入 |
| `--vault-ids` | string_slice | Vault id，逗号分隔或重复传入 |
| `--tags` | string | Tags 映射或 tag 数组 |
| `--agent-overrides` | string | AgentWithOverrides 对象；行内 JSON/YAML 或 @file |
| `--environment-overrides` | string | EnvironmentWithOverrides 对象；行内 JSON/YAML 或 @file |
### agent session delete
删除托管智能体会话
```Bash
arkcli agent session delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--yes` | bool | 跳过删除的交互确认 |
### agent session events list
列出托管智能体会话事件
```Bash
arkcli agent session events list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 请求体的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
| `--after` | string | 游标：取该事件 ID 之后的数据 |
| `--before` | string | 游标：取该事件 ID 之前的数据 |
| `--since` | string | 游标/时间下界 |
| `--created-after` | string | 事件 created_at 下界（RFC3339） |
| `--created-before` | string | 事件 created_at 上界（RFC3339） |
| `--type` | string_slice | 事件类型过滤；可重复或用逗号分隔 |
| `--session-thread-id` | string | 按会话 thread id 过滤 |
| `--order` | string | 排序方向：asc \| desc |
### agent session events send
发送托管智能体会话事件
```Bash
arkcli agent session events send
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 请求体的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--events` | string | 事件数组；多个事件按顺序串行发送（非原子） |
| `--event` | string | 单个事件对象 |
| `--type` | string | 单个事件类型，例如 user.message |
| `--text` | string | user.message 的文本 |
| `--content` | string | 内容字符串，或用 @file 从磁盘读取 |
| `--image` | string_slice | 图片文件 ID 或 @本地路径；可重复或逗号分隔 |
| `--document` | string_slice | 文档 / PDF 文件 ID 或 @本地路径；可重复或逗号分隔 |
| `--purpose` | string | 本地 --image/--document 上传的文件用途（默认 user_data） |
| `--wait-timeout` | int | 本地上传、--stream/--wait 初始阶段或 --poll 的秒数；默认 120 |
| `--wait-interval` | int | 本地多模态上传的轮询间隔秒数；默认 2 |
| `--session-thread-id` | string | 目标会话 thread id |
| `--no-event-deltas` | bool | 不请求 PRD 的 event_start/event_delta 帧，只使用完整事件 |
| `--max-event-chars` | int | 美化后事件文本最多显示的字符数；默认 2000，0 表示不限制 |
| `--stream` | bool | 发送后打开 SSE 事件流并等待到终态；超时则回退到事件列表轮询 |
| `--wait` | bool | --stream 的兼容别名；除非显式指定 --stream，大请求体可能立即返回 |
| `--wait-fallback-timeout` | int | 流超时后继续轮询的秒数；默认 120 |
| `--poll` | bool | 发送后改为轮询事件列表直到终态，而不是开流；适合大请求或长耗时请求 |
| `--poll-interval` | int | 配合 --poll 的轮询间隔秒数；默认 2 |
| `--raw` | bool | 配合 --stream、--wait 或 --poll 时，打印原始 NDJSON 事件而不是人类可读行 |
| `--tool-use-id` | string | user.tool_confirmation 的 tool use id |
| `--custom-tool-use-id` | string | user.custom_tool_result 的自定义工具调用 ID |
| `--result` | string | 结果值，例如 allow \| deny |
### agent session events stream
流式订阅托管智能体会话事件
```Bash
arkcli agent session events stream
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--after` | string | 游标：取该事件 ID 之后的数据 |
| `--before` | string | 游标：取该事件 ID 之前的数据 |
| `--since` | string | 游标/时间下界 |
| `--created-after` | string | 事件 created_at 下界（RFC3339） |
| `--created-before` | string | 事件 created_at 上界（RFC3339） |
| `--type` | string_slice | 事件类型过滤；可重复或用逗号分隔 |
| `--session-thread-id` | string | 按会话 thread id 过滤 |
| `--no-event-deltas` | bool | 不请求 PRD 的 event_start/event_delta 帧，只使用完整事件 |
| `--max-event-chars` | int | 美化后事件文本最多显示的字符数；默认 2000，0 表示不限制 |
| `--order` | string | 排序方向：asc \| desc |
### agent session get
获取托管智能体会话
```Bash
arkcli agent session get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
### agent session list
列出托管智能体会话
```Bash
arkcli agent session list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page` | int | 页码 |
| `--agent-id` | string | 按智能体 ID 过滤 |
| `--agent-version` | int | 按智能体版本过滤 |
| `--environment-id` | string | 按环境 ID 过滤 |
| `--memory-store-id` | string | 按记忆库 ID 过滤 |
| `--start` | string | 按会话开始时间下界过滤（RFC3339） |
| `--end` | string | 按会话开始 / 更新时间上界过滤（RFC3339） |
| `--order` | string | 排序方向：asc \| desc |
| `--status` | string_slice | 按会话状态过滤；可重复或用逗号分隔 |
| `--tags` | string | Tags 映射或 tag 数组过滤条件 |
### agent session resources add
为托管智能体会话添加资源
```Bash
arkcli agent session resources add
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 请求体的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--path` | string | 本地文件路径：上传后等待其变为 active，再挂载为文件资源 |
| `--file-id` | string | Files API 文件 ID。可用 `arkcli agent file upload` 或 `arkcli agent file list` 获取。 |
| `--type` | string | 资源类型：file |
| `--mount-path` | string | 追加到后端托管的 /mnt/session/uploads/ 前缀之后的路径 |
| `--purpose` | string | 使用 --path 时的文件上传用途（默认 user_data） |
| `--tos` | string | 使用 --path 上传文件时的 TOS 存储对象 |
| `--preprocess-configs` | string | 使用 --path 上传文件时的预处理配置对象 |
| `--expire-at` | int | 使用 --path 上传文件时的 UTC Unix 时间戳（秒） |
| `--wait-timeout` | int | 本地文件激活的最长秒数；配合 --wait 时也限制 Agent 响应等待（默认 120） |
| `--wait-interval` | int | 轮询间隔秒数；默认 2 |
### agent session resources delete
删除托管智能体会话资源
```Bash
arkcli agent session resources delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过删除的交互确认 |
| `--resource-id` | string | Session 资源 id |
### agent session resources get
查看挂载到托管智能体会话的单个资源
```Bash
arkcli agent session resources get [resource-id]
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--resource-id` | string | Session 资源 id |
| `--file-id` | string | 按 file_id 匹配文件资源 |
| `--mount-path` | string | 按 mount_path 匹配文件资源 |
### agent session resources list
列出挂载到托管智能体会话的资源
```Bash
arkcli agent session resources list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 请求体的路径。传 - 或省略 --file 表示从 stdin 读取 |
### agent session resources update
更新托管智能体会话资源
```Bash
arkcli agent session resources update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--resource-id` | string | Session 资源 id |
| `--authorization-token` | string | github_repository 资源的新授权 token |
### agent session threads get
获取托管智能体会话线程
```Bash
arkcli agent session threads get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 请求体的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--session-thread-id` | string | 会话 thread id |
### agent session threads list
列出托管智能体会话线程
```Bash
arkcli agent session threads list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 请求体的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
### agent session update
更新托管智能体会话
```Bash
arkcli agent session update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--title` | string | 会话标题 |
| `--tag` | string | Tags 补丁映射对象（服务端按合并语义处理） |
| `--tags` | string | Tags 映射或 tag 数组 |
| `--agent` | string | 智能体补丁对象；仅用于 tools/mcp_servers |
### agent session upgrade
升级已有 Session 的运行配置（返回受理结果，不代表升级完成）
```Bash
arkcli agent session upgrade
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | 升级请求 JSON/YAML 文件（snake_case）；显式 flags 覆盖对应字段 |
| `--agent` | string | Agent 升级对象（snake_case）；inline JSON/YAML 或 @file |
| `--environment` | string | Environment 升级对象（snake_case）；inline JSON/YAML 或 @file |
| `--agent-version` | int | 加载指定 Agent 版本；不传或 0 表示保留当前快照 |
| `--model` | string | 模型 ID 或模型升级对象（snake_case JSON/YAML 或 @file） |
| `--speed` | string | 兼容保留的模型 speed 参数 |
| `--thinking` | string | 模型思考模式 |
| `--reasoning-effort` | string | 模型推理强度 |
| `--service-tier` | string | 模型服务等级 |
| `--vault-ids` | string | 已绑定 Vault ID 的 JSON/YAML 数组或 @file；仅刷新，不改变绑定集合 |
| `--initial-events` | string | 初始事件数组（JSON/YAML 或 @file）；可选，[] 表示不追加事件 |
| `--compact` | bool | 附带升级用 /compact 事件；false 显式设置 initial_events 为 [] |
### agent skill create
上传本地技能 zip 包并创建自定义托管智能体技能
```Bash
arkcli agent skill create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--zip` | string（必填） | 本地技能 zip 包路径 |
| `--display-title` | string | 所上传技能的显示标题 |
| `--protection-enabled` | bool | 为新建 Skill 启用内容保护 |
### agent skill delete
删除自定义托管智能体技能（需先删除该技能的全部版本）
```Bash
arkcli agent skill delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 确认永久删除 |
| `--version` | string | 只删除该技能版本；省略则删除整个技能（要求无剩余版本） |
### agent skill download
下载自定义托管智能体技能的某个版本归档
```Bash
arkcli agent skill download
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--version` | string | 技能语义版本；默认取最新版本 |
| `--output` | string | 本地输出 zip 路径；默认 -v.zip |
### agent skill get
通过 TOP GetSkill 获取自定义或 Ark 托管智能体技能
```Bash
arkcli agent skill get
```
### agent skill github import
扫描并导入 GitHub 公共仓库中的 Skills
```Bash
arkcli agent skill github import
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--path` | string_slice | 仓库内 Skill 相对路径；可重复传入 |
| `--all` | bool | 导入全部有效候选 |
| `--selected` | string | 通过 @file 传入 Path 和可选 ProtectionEnabled 选择数组 |
| `--protection-enabled` | bool | 为新建 Skill 启用内容保护 |
### agent skill github scan
扫描 GitHub 公共仓库中的 Skills
```Bash
arkcli agent skill github scan
```
### agent skill list
列出 SkillHub market 或 TOP custom/ark Managed Agent skills
```Bash
arkcli agent skill list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--source` | string | Skill 来源：market \| custom \| ark \| all；all 返回 custom 与 ark 联合视图 |
| `--limit` | int | 分页大小（--page-size 的别名） |
| `--page` | string | 页码（--page-number 的别名） |
| `--page-number` | int | 页码 |
| `--page-size` | int | 每页条数 |
| `--query` | string | 搜索关键词 |
| `--id` | string | 按技能 ID 过滤 |
| `--ids` | string_slice | 按 ID 过滤自定义技能；可重复或逗号分隔 |
| `--name` | string | 按技能名称过滤 |
| `--display-title` | string | 按 Skill 展示标题过滤 |
| `--skill-space-id` | string | 按技能空间 id 过滤 |
| `--keywords` | string | 按关键词过滤 |
| `--source-type` | string | 按来源类型过滤 |
| `--status` | string_slice | 按状态过滤；可重复或用逗号分隔 |
| `--sharing` | bool | 按可见性过滤市场技能；true=社区，false=自定义 |
| `--sort-by` | string | TOP ListSkills 的自定义技能排序字段 |
| `--sort-order` | string | TOP ListSkills 的自定义技能排序方向 |
| `--create-time-gte` | string | TOP ListSkills 的自定义技能创建时间下界 |
| `--create-time-lte` | string | TOP ListSkills 的自定义技能创建时间上界 |
### agent skill search
按用户查询搜索 skills，并输出 Agent skill refs
```Bash
arkcli agent skill search
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
| `--source` | string | Skill 来源：market \| custom \| ark \| all；all 返回 custom 与 ark 联合视图 |
| `--private` | bool | 只搜索私有技能 |
| `--type` | string | 输出 refs 使用的 Agent skill 类型：custom \| skill_hub |
### agent skill set-protection
开启或关闭自定义 Managed Agent Skill 的内容保护
```Bash
arkcli agent skill set-protection
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--enabled` | bool（必填） | 内容保护状态 |
### agent skill update
为已有的自定义托管智能体技能上传新版本
```Bash
arkcli agent skill update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--zip` | string（必填） | 新的本地技能 zip 包路径 |
| `--display-title` | string | 技能新版本的显示标题 |
### agent skill versions
列出自定义或 Ark 托管智能体技能的版本
```Bash
arkcli agent skill versions
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 |
### agent vault create
创建凭证库（Vault）
```Bash
arkcli agent vault create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--display-name` | string | 凭证库显示名 |
| `--metadata` | string | 元数据 map 对象 |
### agent vault credentials create
在凭证库中创建凭证
```Bash
arkcli agent vault credentials create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--display-name` | string | 凭证显示名 |
| `--auth` | string | 凭证认证对象 |
| `--auth-type` | string | 认证类型：environment_variable \| static_bearer \| mcp_oauth |
| `--mcp-server-url` | string | bearer/OAuth 凭证使用的 MCP server URL |
| `--token` | string | Bearer token 或环境变量值；可用 @file 读取本地文件 |
| `--access-token` | string | 当前 OAuth access token；用 @file 从本地文件读取 |
| `--secret-name` | string | environment_variable 认证用的环境变量名 |
| `--secret-value` | string | 环境变量值；可用 @file 读取本地文件 |
| `--networking-type` | string | 环境网络类型：limited \| unrestricted |
| `--allowed-host` | string_slice | 受限环境下允许访问的主机；可重复或逗号分隔 |
| `--client-id` | string | OAuth 刷新的 client id |
| `--client-secret` | string | OAuth 刷新的 client secret；建议用 @file |
| `--refresh-token` | string | OAuth refresh token；可用 @file |
| `--token-endpoint` | string | OAuth token endpoint |
| `--resource` | string | OAuth resource |
| `--scope` | string | OAuth scope |
| `--metadata` | string | 元数据 map 对象 |
### agent vault credentials delete
删除凭证
```Bash
arkcli agent vault credentials delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--yes` | bool | 跳过删除的交互确认 |
### agent vault credentials get
获取凭证
```Bash
arkcli agent vault credentials get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
### agent vault credentials list
列出凭证库中的凭证
```Bash
arkcli agent vault credentials list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
| `--id` | string | 按凭证 ID 过滤 |
| `--name` | string | 按凭证名称过滤 |
### agent vault credentials update
更新凭证
```Bash
arkcli agent vault credentials update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--display-name` | string | 凭证显示名 |
| `--auth` | string | 凭证认证对象 |
| `--auth-type` | string | 认证类型：environment_variable \| static_bearer \| mcp_oauth |
| `--mcp-server-url` | string | bearer/OAuth 凭证使用的 MCP server URL |
| `--token` | string | Bearer token 或环境变量值；可用 @file 读取本地文件 |
| `--access-token` | string | 当前 OAuth access token；用 @file 从本地文件读取 |
| `--secret-name` | string | environment_variable 认证用的环境变量名 |
| `--secret-value` | string | 环境变量值；可用 @file 读取本地文件 |
| `--networking-type` | string | 环境网络类型：limited \| unrestricted |
| `--allowed-host` | string_slice | 受限环境下允许访问的主机；可重复或逗号分隔 |
| `--client-id` | string | OAuth 刷新的 client id |
| `--client-secret` | string | OAuth 刷新的 client secret；建议用 @file |
| `--refresh-token` | string | OAuth refresh token；可用 @file |
| `--token-endpoint` | string | OAuth token endpoint |
| `--resource` | string | OAuth resource |
| `--scope` | string | OAuth scope |
| `--metadata` | string | 元数据 map 对象 |
### agent vault delete
删除凭证库（Vault）
```Bash
arkcli agent vault delete
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--yes` | bool | 跳过删除的交互确认 |
### agent vault get
获取凭证库（Vault）
```Bash
arkcli agent vault get
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
### agent vault list
列出凭证库（Vault）
```Bash
arkcli agent vault list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page` | string | 分页游标 / 页码 |
| `--id` | string | 按凭证库 ID 过滤 |
| `--name` | string | 按 Vault 名称过滤 |
### agent vault oauth-flow create
创建 Vault MCP OAuth 流程并返回授权链接
```Bash
arkcli agent vault oauth-flow create
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--vault-id` | string | Vault id |
| `--display-name` | string | 凭证显示名 |
| `--mcp-server-url` | string | MCP server URL |
| `--redirect-url` | string | OAuth 回调的业务成功跳转 URL |
| `--source` | string | 流程来源标记，例如 arkcli-mcp-login |
| `--client-id` | string | 自定义 MCP/provider 覆盖模式下的 OAuth client id |
| `--client-secret` | string | OAuth client secret，或用 @file 从磁盘读取 |
### agent vault oauth-provider list
列出可用于 Agent MCP server 与凭证库的已注册 MCP provider
```Bash
arkcli agent vault oauth-provider list
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--limit` | int | 分页大小 |
| `--page-token` | string | 下一页 token |
### agent vault update
更新凭证库（Vault）
```Bash
arkcli agent vault update
```
| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--file` | string | JSON/YAML 载荷的路径。传 - 或省略 --file 表示从 stdin 读取 |
| `--display-name` | string | 凭证库显示名 |
| `--metadata` | string | 元数据 map 对象 |
---
# ArkExp 快速入门
Source: https://ark.volcengine.com/region:cn-beijing/docs/agent-plan-personal-arkexp-quickstart
ArkExp 将**火山方舟模型能力**带到用户的本地终端，让你在当前工作目录中用自然语言完成知识问答、内容处理、命令执行和任务管理。ArkExp 适合希望保留终端工作流，同时获得方舟模型与 Agent 完整体验的用户使用。
## 什么是 ArkExp
ArkExp 不是一个单纯的聊天窗口，而是面向本地工作环境的 AI-native CLI。你提出目标后，它会结合当前目录和会话上下文规划任务，通过受控工具读取和修改文件、执行命令、调用扩展能力，并将过程与结果持续展示在 TUI 中。
## 为什么使用 ArkExp
ArkExp 的价值不只是把模型放进终端，而是把方舟能力、本地交互和持续任务体验整合成一个完整的 CLI。
- **深度集成方舟体系，而不只是接入一个模型。**
与 Claude Code、Codex、OpenCode 等通用 CLI 相比，ArkExp 面向方舟体系原生设计：从火山引擎账号登录、套餐与用量管理、模型和 Endpoint 选择，到豆包 Web Search、OpenViking 知识与资源能力以及 ArkCLI 能力，都可以在同一条体验链路中使用，无需自行拼装多个 Provider、插件和配置。
- **从一次问答升级为可持续的本地任务体验。**
交互式 TUI 集中呈现流式响应、工具执行和任务状态；会话恢复、历史记录、Goal、Memory、Context 与上下文压缩共同承载长期任务。运行期间还可以补充指令、排队后续问题或取消操作，让任务始终可见、可控、可继续。
- **开箱即用，同时保持开放、安全和可恢复。**
Skills、MCP、Workflow、Cron 与自定义斜杠命令让能力可以按需扩展；权限闸门、高风险操作确认、自动检查点、结果验证和失败记忆则为本地执行提供安全边界与恢复能力。
## 快速开始
### 一、安装 ArkExp
**前提条件**：
- 请确保本机可以使用 `npm`，并能访问 npm 官方 Registry。
- ArkExp 运行时需要 Bun 1.3 或更高版本。全局安装脚本会在缺少 Bun 时自动调用官方安装器完成安装。如需自行管理 Bun，可设置 `ARKTUI_AUTO_INSTALL_BUN=0` 关闭自动安装，但启动 ArkExp 前仍需保证 Bun 可用。
**安装 ArkExp**：在命令行界面，执行以下命令安装 ArkExp。
```Bash
curl -fsSL https://lf3-static.bytednsdoc.com/obj/eden-cn/welryh/ljhwZthlaukjlkulzlp/prod/install.sh | sh
arkexp --version
```
**更新版本**：可以先检查可用更新，再执行受校验的事务式升级；已经启动的进程继续使用原版本，下次启动切换到新版本。
```bash
arkexp update --check --refresh
arkexp update
```
### 二、启动并配置 ArkExp
在任务对应的工作目录中启动 ArkExp。工作目录决定本次会话加载的项目配置、指令与 Skills。
```bash
cd /path/to/project
arkexp
```
**首次使用步骤如下**：
1. 运行 `arkexp` 进入 TUI。
2. 如果首页已经显示可用的模型连接，可直接进入下一步；否则输入 `/login`，按界面提示完成方舟登录。
3. 输入 `/plans`，选择账号已有的 Agent Plan、Coding Plan 或 Platform 按量后付费来源。
4. 输入 `/models`（也可使用 `/model`），从当前来源选择实际可用的模型或 Endpoint。
5. 回到输入框，用自然语言描述任务。首页显示连接可用后即可开始。
**非首次使用步骤如下**：
再次在项目目录运行 `arkexp` 即可，可以关注以下信息：
- ArkExp 会复用已经保存且仍有效的连接。
- 需要切换账号、套餐或模型时，再使用 `/login`、`/plans` 或 `/models`。
- 通过 `/usage` 可以查看受支持 Plan 的额度，通过 `/sessions` 恢复历史会话。
### 三、使用 ArkExp
直接告诉 ArkExp 你希望达到的结果，并补充范围、约束与验收方式。对于会修改文件或执行命令的任务，建议同时说明允许的范围和期望的结果。
| 经典场景 | 示例 Prompt |
|---|---|
| 知识问答 | 结合当前目录中的资料，解释这个项目的目标、主要模块和使用方式。 |
| 内容处理 | 汇总 `@docs/` 下的产品说明，生成一份面向新用户的快速入门。 |
| 日志与数据分析 | 分析 `@logs/app.log`，按错误类型归类并给出排查顺序。 |
| 命令执行 | 运行当前项目的检查命令，解释失败原因；需要修改文件时先说明影响范围。 |
| 多步骤任务 | 把这个任务拆成可执行计划，持续推进，并在关键节点汇报结果。 |
| 代码开发 | 检查当前分支相对基线的改动，重点关注兼容性、权限边界和缺失测试。 |
**常用交互**：
- `Ctrl+K`：打开命令面板。
- `Ctrl+O`：切换模型。
- `Shift+Tab`：切换 Normal、Plan 与 Full Access 权限姿态。
- `Enter`：任务运行时追加当前轮指令。
- `Alt+Enter`：将内容排队为当前任务后的独立追问。
- `Ctrl+C`：运行中中断；空闲时退出。
**非交互模式使用**：在脚本或一次性任务中，可以直接使用以下命令。
```bash
arkexp run "解释这个仓库的核心模块，并列出建议的阅读顺序"
```
完整命令、快捷键和当前版本支持的能力以 TUI 内的 `/help` 为准。
## 相关文档
* [Ark CLI：Agent Plan 个人版使用指南](/docs/agent-plan-personal-ark-cli)
* [ArkExp 命令参考](/docs/agent-plan-personal-arkexp-command-reference)
---
# ArkExp 命令参考
Source: https://ark.volcengine.com/region:cn-beijing/docs/agent-plan-personal-arkexp-command-reference
ArkExp 是一款面向通用模型体验、任务处理与本地工作流的 CLI。在终端中连接方舟模型与 ArkCLI 能力，通过清晰、可交互、可扩展的 TUI 完成日常任务。
> **说明**
>
> ArkExp 的安装、启动、配置及使用参见 [ArkExp 快速入门](/docs/agent-plan-personal-arkexp-quickstart)。
## 核心特性
**本地终端体验**
在熟悉的终端里使用方舟模型，流式查看响应、工具执行和任务状态。
**账号与模型开箱可用**
内置登录、套餐、用量、模型与 API 传输方式管理，减少环境切换。
**持续任务承载**
会话、目标、记忆、上下文与历史记录共同承载持续任务。
**可扩展**
通过 Skills、MCP、工作流、自定义斜杠命令和定时任务扩展能力。
**权限可控**
工具执行经过权限闸门；高风险操作需要明确确认。
**可恢复**
检查点、验证与失败记忆帮助任务在本地端更稳定地推进。
## 斜杠命令
> **注意**
>
> 斜杠命令、别名和参数是兼容性标识，必须按下表原样输入。
### 账号、模型与 API
| 命令 | 作用 | 用法 |
|-|-|-|
| `/login` | 登录火山引擎并建立方舟连接。 | `/login` |
| `/logout` | 退出登录并移除本地凭证。 | `/logout` |
| `/plans` | 发现、查看并选择可用套餐或连接。 | `/plans` |
| `/usage` | 查看当前方舟套餐的额度使用情况。 | `/usage` |
| `/models` | 打开模型选择器。 | `/models` |
| `/api` | 查看或切换 API 传输方式。 | `/api [status\\|auto\\|responses\\|chat] [--save]` |
| `/apm` | 查看遥测门禁，或启用 / 停用遥测。 | `/apm [status\\|on\\|off]` |
| `/language` | 查看或固定响应语言。 | `/language [status\\|auto\\|Chinese\\|English\\|Japanese]` |
### 会话与历史
| 命令 | 作用 | 用法 |
|-|-|-|
| `/new` | 开始新会话。 | `/new` |
| `/sessions` | 浏览并恢复历史会话。 | `/sessions` |
| `/resume` | 按 ID 或标题恢复会话；无参数时打开选择。 | `/resume [session-id-or-title]` |
| `/clear` | 清空当前聊天视图。 | `/clear` |
| `/timeline` | 打开时间线并跳转到指定消息。 | `/timeline` |
| `/fork` | 从时间线中的位置派生新会话。 | `/fork` |
| `/copy` | 复制完整会话记录。 | `/copy` |
| `/copy-last` | 复制最近一条用户消息。 | `/copy-last` |
| `/export` | 将会话导出为 Markdown。 | `/export` |
| `/compact` | 把较早历史压缩为摘要，释放上下文空间。 | `/compact` |
| `/summarize` | `/compact` 的兼容别名。 | `/summarize` |
| `/undo` | 撤销上一次会话回退。 | `/undo` |
| `/redo` | 重做被撤销的会话变更。 | `/redo` |
| `/stash` | 打开已暂存的输入草稿。 | `/stash` |
| `/stash-save` | 暂存当前输入，或直接暂存给定文本。 | `/stash-save [draft]` |
| `/stash-pop` | 恢复最近暂存的草稿。 | `/stash-pop` |
### 任务模式与目标
| 命令 | 作用 | 用法 |
|-|-|-|
| `/agents` | 切换可用任务 Agent / 模式。 | `/agents` |
| `/plan` | 进入规划模式。 | `/plan` |
| `/implement` | 退出规划模式并回到执行模式。 | `/implement` |
| `/goal` | 设置、查看、暂停、恢复、完成或清除持久目标。 | `/goal [--criteria "a;b"]`
`/goal [status\\|pause\\|resume\\|complete\\|clear]` |
| `/btw` | 基于当前上下文提一个旁路问题，不写入持久会话历史。 | `/btw ` |
### 工作流与扩展
| 命令 | 作用 | 用法 |
|-|-|-|
| `/workflow` | 打开工作流面板，运行或停止已保存工作流。 | `/workflow [list\\|run [json]\\|stop ]` |
| `/workflows` | `/workflow` 的兼容别名。 | `/workflows [list\\|run [json]\\|stop ]` |
| `/cron` | 创建和管理持久化的一次性或周期任务。 | `/cron` |
| `/mcp` | 查看、连接、认证、启停和刷新 MCP 服务。 | `/mcp` |
| `/tools` | 检查工具可见性、可用性、Schema 成本和权限风险。 | `/tools` |
| `/skills` | 查看、启停、安装或移除 Skills。 | `/skills`
`/skills install\\|remove ` |
### 工作区与内容
| 命令 | 作用 | 用法 |
|-|-|-|
| `/memory` | 浏览和配置用户、项目、会话与系统摘要记忆。 | `/memory`
`/memory show user\\|project\\|session\\|system-summary` |
| `/context` | 查看上下文 token、预算与使用率。 | `/context` |
| `/init` | 为当前项目生成 `AGENTS.md` 指令。 | `/init` |
### 界面与诊断
| 命令 | 作用 | 用法 |
|-|-|-|
| `/help` | 打开快捷键与内置命令帮助。 | `/help` |
| `/theme` | 选择并预览界面主题。 | `/theme` |
| `/timestamps` | 显示或隐藏消息时间戳。 | `/timestamps` |
| `/thinking` | 显示或隐藏推理摘要。 | `/thinking` |
| `/status` | 查看 MCP、Skills 与 Commands 状态。 | `/status` |
| `/feedback` | 提交产品反馈。 | `/feedback ` |
| `/exit` | 退出 CLI。 | `/exit` |
| `/quit` | `/exit` 的兼容别名。 | `/quit` |
### 随包 Skill 命令
以下命令来自随包 Skills；是否可执行取决于当前连接、权限与 Skill 启用状态。
| 命令 | 作用 | 用法 |
|-|-|-|
| `/add-resources` | 把本地路径或远程 URL 导入 OpenViking Resources。 | `/add-resources [--to ]` |
| `/arkexp-docs` | 查询产品用法、配置与排障信息。 | `/arkexp-docs ` | \
| | > `/arkexp-docs` 是随包 Skill 提供的技术命令名。| |
| `/byted-web-search` | 在当前连接为 Agent Plan 时使用随包豆包搜索能力。 | `/byted-web-search ` |
### 别名速查
| 推荐命令 | 可用别名 | 说明 |
|-|-|-|
| `/models` | `/model` | 模型选择器。 |
| `/theme` | `/themes` | 主题选择器。 |
| `/sessions` | `/session` | 历史会话。 |
| `/skills` | `/skill` | Skill 管理。 |
| `/agents` | `/agent` | 任务模式选择。 |
| `/timestamps` | `/toggle-timestamps` | 时间戳显示开关。 |
| `/thinking` | `/toggle-thinking` | 推理摘要显示开关。 |
| `/stash-pop` | `/unstash` | 恢复最近草稿。 |
| `/compact` | `/summarize` | 会话压缩。 |
| `/workflow` | `/workflows` | 工作流管理。 |
| `/exit` | `/quit` | 退出。 |
## /api 详解
`/api` 用于查看或切换当前模型连接的 API 传输方式。它不会更换模型、Endpoint 或套餐。
| 命令 | 行为 |
|-|-|
| `/api` | 显示当前传输方式；等价于 `/api status`。 |
| `/api status` | 显示当前传输方式与生效状态。 |
| `/api auto` | 优先使用 Responses API，并在兼容条件下安全回退到 Chat Completions。 |
| `/api responses` | 仅使用 Responses API。 |
| `/api chat` | 仅使用 Chat Completions API。 |
| `--save` | 追加到切换命令后，将选择持久化到后续会话。 |
```Bash
/api status
/api auto
/api responses --save
/api chat --save
```
> **说明**
>
> 不确定时使用 `/api auto`。只有在排障、兼容性验证或明确依赖某一协议时，才固定为 `responses` 或 `chat`。
## 快捷键
| 快捷键 | 操作 |
|-|-|
| `Ctrl+C` | 运行中中断；空闲时退出。 |
| `Ctrl+H` | 打开帮助。 |
| `Ctrl+K` | 打开命令面板。 |
| `Ctrl+O` | 切换模型。 |
| `Ctrl+T` | 切换主题。 |
| `Ctrl+B` | 显示或隐藏侧边栏。 |
| `Ctrl+G` | 展开或折叠工具执行详情。 |
| `Enter` | 发送；运行中在安全边界调整当前任务。 |
| `Alt+Enter` | 将内容排队为当前任务后的独立追问。 |
| `Shift+Enter` / `Ctrl+Enter` | 输入换行。 |
| `Shift+Tab` | 循环切换权限姿态。 |
| `Esc` | 关闭对话框；运行中立即中断。 |
| `Fn+↑ / Fn+↓` | macOS 内置键盘：跳到上一 / 下一条用户 Prompt。 |
| `Page Up / Page Down` | Windows、Linux 或全尺寸键盘：跳到上一 / 下一条用户 Prompt。 |
| `Home / End` | 跳到记录开头 / 返回实时底部。 |
| `↑`（空输入框） | 打开当前目录的 Prompt 历史。 |
## 扩展斜杠命令
### 项目命令
把可复用 Prompt 保存为 Markdown 文件，文件名就是命令名。例如 `.arkexp/commands/brief.md` 会生成 `/brief`。
- 项目范围会扫描 `.arkexp/command(s)`、`.agents/command(s)`、`.claude/command(s)`、`.codex/command(s)`、`.cursor/command(s)` 与根目录 `command(s)`。
- 个人范围使用 `~/.arkexp/command(s)`。
```markdown
---
description: 生成任务简报
argument-hint: "[topic]"
---
围绕 $ARGUMENTS 生成一份简洁、可执行的任务简报。
```
### Skills
```text
/skills
/skills install
/skills remove
```
### MCP
使用 `/mcp` 管理 MCP 服务；使用 `/tools` 检查工具可见性、可用性、Schema 成本与权限风险。
> **说明**
>
> 命令优先级：内置命令 > 已启用 Skills > 项目 / 个人自定义命令。不要用自定义文件覆盖内置命令名。
## CLI 模式与更新
### 交互式 TUI
```bash
arkexp
```
### 单次 CLI 调用
```bash
arkexp run "总结当前目录中的资料，并给出下一步建议"
```
### 更新
```bash
arkexp update --check --refresh
arkexp update
```
全局安装建议始终使用 npm 的 `@latest` 标签；升级前可先执行检查命令。
## 相关资源
* [ArkExp 快速入门](/docs/agent-plan-personal-arkexp-quickstart)
* [Ark CLI：Agent Plan 个人版使用指南](/docs/agent-plan-personal-ark-cli)
* [npm 安装包](https://www.npmjs.com/package/@volcengine/ark-tui)
---
# 选择读取方式
Source: https://ark.volcengine.com/region:cn-beijing/docs/read-docs-with-ai-agents
AI Agent 读取文档时，应优先使用能够结构化检索并按需返回内容的入口。目标页面已知时，直接读取 Markdown 镜像；其他方式不可用时，再读取 HTML 页面。
## 选择读取方式
| 优先级 | 方式 | 适用场景 | 说明 |
| --- | --- | --- | --- |
| 1 | [文档 MCP](/docs/tutorials-mcp) | Agent 支持 MCP，需要检索文档、API、代码示例或模型信息 | 文档 MCP 提供结构化工具和按需读取能力，减少 Agent 自行维护 URL 和解析页面的成本。 |
| 2 | [llms.txt 系列文件](/docs/read-ark-docs-with-llms-txt) | Agent 可以访问公网，但未接入 MCP；需要发现页面或获取批量语料 | `llms.txt` 用于发现文档；`llms-full.txt` 和章节全文文件用于构建知识库或离线检索。 |
| 3 | [Markdown 镜像](/docs/read-docs-from-urls#read-markdown) | 已知目标页面地址，只需要页面正文 | 在文档页面 URL 后追加 `.md`，获取 `text/markdown` 内容，避免 HTML 页面中的导航和样式代码。 |
| 4 | [HTML 页面](/docs/read-docs-from-urls#read-html) | Agent 只能使用网页读取工具，或目标页面没有可用的 Markdown 镜像 | 网页解析工具通常能够提取正文，但原始 HTML 同时包含导航、脚本、样式和页面元数据，会增加无关上下文。 |
## 配置 Agent 读取规则
将以下规则加入 Agent 的系统提示词。规则包含文档 MCP、`llms.txt` 和页面 URL 的完整入口：
```text
回答产品相关问题前，按以下顺序读取最新官方文档：
1. 如果客户端支持 MCP，连接 https://mcp.ark-doc-resources.cn/mcp/，
使用文档 MCP 检索并读取目标内容。
2. MCP 不可用时，读取 https://ark.volcengine.com/llms.txt，
根据标题和简介定位相关页面，再读取命中文档的 Markdown 链接。
3. 构建知识库或执行离线检索时，读取 https://ark.volcengine.com/llms-full.txt，
或读取 llms.txt 中对应章节的“章节全文”链接。不要把全站全文直接注入单次对话。
4. 已知文档页面 URL 时，读取 .md，优先使用 Markdown 镜像。
5. .md 不可用时，读取 ，并且只保留文章标题、正文、
代码块、表格和链接；忽略导航、脚本、样式、页脚和交互控件。
6. 回答时引用读取到的最新官方文档，不要只依赖已有知识。
```
## 使用推荐流程
1. Agent 已接入文档 MCP 时，使用 MCP 检索并读取目标内容。
2. MCP 不可用时，读取 [llms.txt](https://ark.volcengine.com/llms.txt)，根据标题和简介定位相关页面。
3. 构建知识库或执行离线检索时，读取 [llms-full.txt](https://ark.volcengine.com/llms-full.txt) 或章节全文文件。
4. 已知目标页面时，读取 `.md`。
5. `.md` 不可用时，读取 HTML 页面，并且只保留正文内容。
## 相关文档
- 配置结构化检索工具，详情请参见[文档 MCP](/docs/tutorials-mcp)。
- 使用索引、章节全文或全站全文读取文档，详情请参见[llms.txt](/docs/read-ark-docs-with-llms-txt)。
- 直接读取 Markdown 镜像或 HTML 页面，详情请参见[通过 URL](/docs/read-docs-from-urls)。
- 安装文档配套能力，详情请参见[文档 Skill](/docs/ark-document-skills)。
---
# 文档 MCP
Source: https://ark.volcengine.com/region:cn-beijing/docs/tutorials-mcp
Ark Docs MCP 是方舟官方提供的远程 [Model Context Protocol](https://modelcontextprotocol.io/) Server。在支持 MCP 的 AI 编程助手（TRAE、Cursor、Claude Code、VS Code、Windsurf、OpenClaw 等）中完成配置后，AI 助手即可在编码上下文中直接检索方舟平台的**文档、API 参考、代码示例、模型信息**，降低幻觉、避免使用过时参数与已下线接口。
> **注意**
>
> **域名迁移通知**：Ark Docs MCP 已使用 [当前服务地址](https://mcp.ark-doc-resources.cn/mcp/)。原公测域名已于 2026 年 8 月 17 日下线，请将存量配置更新为当前地址。
## 接入方式
### 一键安装（推荐）
主流客户端支持通过 URL 协议直接唤起安装：
[安装到 TRAE CN（中国版）](trae-cn://trae.ai-ide/mcp-import?type=http&name=ark-docs-mcp&config=eyJ1cmwiOiJodHRwczovL21jcC5hcmstZG9jLXJlc291cmNlcy5jbi9tY3AvIn0=)
[安装到 TRAE（国际版）](trae://trae.ai-ide/mcp-import?type=http&name=ark-docs-mcp&config=eyJ1cmwiOiJodHRwczovL21jcC5hcmstZG9jLXJlc291cmNlcy5jbi9tY3AvIn0=)
[安装到 VS Code](vscode:mcp/install?%7B%22name%22%3A%22Ark%20Docs%20MCP%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.ark-doc-resources.cn%2Fmcp%2F%22%7D)
[安装到 Cursor](cursor:mcp/install?%7B%22name%22%3A%22Ark%20Docs%20MCP%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.ark-doc-resources.cn%2Fmcp%2F%22%7D)
[安装到 Windsurf](windsurf:mcp/install?%7B%22name%22%3A%22Ark%20Docs%20MCP%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.ark-doc-resources.cn%2Fmcp%2F%22%7D)
OpenClaw 等 AI Agent 安装
将以下内容发送给 AI Agent，由其完成安装。
```Plain Text
帮我安装方舟文档MCP
{
"mcpServers": {
"ark-docs-mcp": {
"url": "https://mcp.ark-doc-resources.cn/mcp/"
}
}
}
```
### 手动配置
在客户端的 MCP 配置文件中新增一条 server 条目：
```JSON
{
"mcpServers": {
"ark-docs-mcp": {
"url": "https://mcp.ark-doc-resources.cn/mcp/"
}
}
}
```
- Cursor / Windsurf：写入 `~/.cursor/mcp.json` / `~/.codeium/windsurf/mcp_config.json`
- Claude Code：写入 `~/.claude.json` 或项目 `.mcp.json`
- VS Code（GitHub Copilot MCP）：写入 workspace `.vscode/mcp.json`
- TRAE：设置面板 > MCP > 新增
保存后重启客户端，AI 助手的工具列表中即会出现 `ark-docs-mcp` 提供的 `ark_*` 工具。
## 工具列表
Ark Docs MCP 目前提供以下只读工具，按用途分为**文档 / API / 代码 / 模型** 四类。用户无需关心具体工具的调用参数，AI 助手会自主拉取工具列表并按需调用。
|分类 |工具 |描述 |
|---|---|---|
|文档 |`ark_search_docs` |检索方舟平台文档 |
|文档 |`ark_list_docs` |列出全部方舟平台文档 |
|文档 |`ark_fetch_doc` |拉取指定文档的完整正文 |
|API |`ark_list_apis` |列出方舟平台全部 API 端点 |
|API |`ark_get_spec` |获取指定 API 的参数定义与结构 |
|代码 |`ark_search_examples` |检索方舟官方多语言代码示例 |
|模型 |`ark_list_models` |按能力、状态、价格、限速等维度筛选模型 |
|模型 |`ark_get_model` |获取指定模型的完整元数据 |
## 典型示例
完成接入后，可在 AI 助手中直接使用自然语言触发以下能力。以下场景均由 AI 助手自主编排 `ark_*` 工具，无需手工指定具体工具调用序列。
### 报错排障
用户提问示例："调用 `chat/completions` 接口返回 401，请查询方舟文档定位可能原因。"
AI 助手行为：检索方舟文档中相关的错误码说明 > 深读命中文档 > 给出可能原因与修复步骤。
### 生成 API 调用代码
用户提问示例："使用 Python 编写调用 Ark `chat/completions` 的代码，要求启用流式返回，并参考官方最新示例。"
AI 助手行为：获取 API 参考 > 检索官方 Python 示例 > 依据规范与示例结构组装代码，避免虚构参数。
### 模型选型
用户提问示例："请检索支持 vision、低延迟、成本敏感的方舟模型，并输出对比表。"
AI 助手行为：按能力 / 状态 / 价格维度筛选候选模型 > 逐个拉取完整元数据 > 输出对比表，标注成本、限速、能力差异。
### 模型升级 / 迁移
用户提问示例："项目内使用的 `<待下线模型 ID>` 已在下线名单，请先给出迁移清单，不要直接修改代码。"
AI 助手行为：定位下线模型对应的推荐替换 > 确认新模型能力兼容 > 拉取新模型的调用示例 > 输出迁移清单。
## 使用限制
- **只读**：不提供任何写入或状态修改能力，读取失败不会产生副作用
- **无鉴权**：当前所有工具公开可用，无需 API Key
- **上下文预算**：`ark_get_spec` 强制按 `service` 或 `api_path` 过滤、`ark_fetch_doc` 支持分块拉取，避免单次调用返回超大 payload 占用 LLM 上下文
- **数据时效**：文档与模型元数据随方舟平台发布同步；若客户端缓存陈旧，重启 MCP session 即可刷新
## 附录：System Prompt 与服务元数据
面向 Agent Skill / System Prompt 开发者
### 服务元数据
- **接入点**：[Ark Docs MCP](https://mcp.ark-doc-resources.cn/mcp/)
- **协议**：MCP 2024-11-05；传输方式 Streamable HTTP
- **鉴权**：无需 API Key
- **数据时效**：实时，与方舟平台发布同步
### System Prompt 模板
以下段落可直接嵌入 AI 助手的 System Prompt 或 Skill 定义的 `instructions` 字段，用于约束工具调用时机与调用规范，减少凭训练知识作答与虚构参数：
```text
你已接入 ark-docs-mcp 工具集。请遵循以下调用约束：
1. 当用户提问涉及方舟平台的概念、API、报错排障、模型选型、
模型迁移时，必须先调用 ark-docs-mcp 检索方舟官方文档，
不得仅凭训练知识作答。
2. 生成方舟 API 调用代码前，必须先调用 ark_get_spec 获取
对应 API 参考；若未获取到 spec，拒绝生成代码。
3. 检索代码示例时，将目标语言（Python / Go / Java / cURL 等）
写入 query，避免返回非期望语言的示例。
4. 使用 ark_fetch_doc 拉取长文档时，若返回 has_more=true，
持续按 chunk_start += chunk_count 拉取直至完整。
```
参照上述模板落地时，可依据业务的规范化程度自行删改条款。
---
# llms.txt
Source: https://ark.volcengine.com/region:cn-beijing/docs/read-ark-docs-with-llms-txt
`llms.txt` 系列文件适合未接入文档 MCP、但能够访问公网 URL 的 AI Agent。Agent 先通过索引发现目标文档，再按需读取命中的 Markdown 内容，可以减少无关上下文。
## 获取文件地址
文档站提供以下文件：
| 文件 | 地址 | 说明 |
| --- | --- | --- |
| 文档索引 | [llms.txt](https://ark.volcengine.com/llms.txt) | 按目录列出公开文档的标题、简介和 Markdown 链接。 |
| 文档全文 | [llms-full.txt](https://ark.volcengine.com/llms-full.txt) | 汇总当前发布版本的全部公开文档正文。 |
| 章节全文 | 以 [llms.txt](https://ark.volcengine.com/llms.txt) 中的“章节全文”链接为准 | 汇总一个目录章节下的公开文档正文，例如 [AI 套件章节全文](https://ark.volcengine.com/llms-full/ai-suite.txt)。 |
这些文件无需注册或 API Key，由文档系统随发布自动更新。
## 了解文件内容
`llms.txt` 是 Markdown 格式的文档索引：
- 每个二级标题对应一个目录章节。
- 每个章节的“章节全文”链接指向该章节的 Markdown 合集。
- 每篇文档按 `- [文档标题](文档地址): 简介` 的格式列出，链接直接指向该页面的 Markdown 镜像。
索引内容示例：
```Markdown
## AI 套件
- [章节全文](https://ark.volcengine.com/llms-full/ai-suite.txt)
- [ArkCLI 快速入门](https://ark.volcengine.com/region:cn-beijing/docs/ark-cli.md): ArkCLI 快速入门说明……
```
`llms-full.txt` 和章节全文文件是纯 Markdown 文本。全站文件内容较多，适合持久化后建立检索索引；单次问答优先读取 `llms.txt` 和命中的单篇文档。
## 选择使用方式
### 按需读取单篇文档
该方式适合问答、排障和生成代码等任务：
1. 读取 [llms.txt](https://ark.volcengine.com/llms.txt)。
2. 根据标题和简介定位相关文档。
3. 读取命中文档的 Markdown 链接。
4. 基于文档内容回答，并在需要时继续读取关联页面。
### 读取一个章节
该方式适合需要同一主题下多篇文档的任务。读取 [llms.txt](https://ark.volcengine.com/llms.txt) 中对应章节的“章节全文”链接，避免加载无关章节。
### 建立文档知识库
该方式适合离线检索或知识库构建。定期获取 [llms-full.txt](https://ark.volcengine.com/llms-full.txt) 或章节全文文件，保存版本并建立检索索引。不要把全站全文直接注入单次对话。
## 配置 Agent 读取规则
将以下规则加入 Agent 的系统提示词，或在对话中直接发送：
```text
当问题涉及当前产品时，先读取 https://ark.volcengine.com/llms.txt，
根据标题和简介定位相关文档，再读取命中文档的 Markdown 链接。
回答时以最新官方文档为准，不要只依赖已有知识。
```
## 相关文档
- 比较全部读取方式，详情请参见[选择读取方式](/docs/read-docs-with-ai-agents)。
- 直接读取 Markdown 镜像或 HTML 页面，详情请参见[通过 URL](/docs/read-docs-from-urls)。
- 配置结构化检索工具，详情请参见[文档 MCP](/docs/tutorials-mcp)。
---
# 通过 URL
Source: https://ark.volcengine.com/region:cn-beijing/docs/read-docs-from-urls
AI Agent 可以通过文档页面 URL 读取 HTML 数据，也可以读取 `.md` 获取 Markdown 镜像。Markdown 镜像主要包含页面正文，应优先读取；HTML 数据包含导航、脚本和样式，仅作为兜底方式。
## 比较两种 URL
| URL 类型 | 响应内容 | 优点 | 局限 |
| --- | --- | --- | --- |
| Markdown 镜像 | `text/markdown` | 主要包含标题和正文，适合直接加入 Agent 上下文。 | 需要已知目标文档页面，并读取 `.md`。 |
| HTML 页面 | `text/html` | 支持网页读取的 Agent 可以直接访问，无需改写地址。 | 原始 HTML 同时包含导航、脚本、样式和页面元数据，会占用额外上下文并影响正文提取。 |
## 读取 Markdown 镜像
在文档页面 URL 后追加 `.md`。例如：
- 页面 URL：[快速入门](https://ark.volcengine.com/region:cn-beijing/docs/quick-start)
- Markdown 地址：[快速入门 Markdown](https://ark.volcengine.com/region:cn-beijing/docs/quick-start.md)
Markdown 镜像适合以下场景：
- Agent 已从 `llms.txt`、搜索结果或用户输入中获得目标页面地址。
- 任务只需要页面正文，不需要导航和交互组件。
- 需要把文档内容加入对话上下文或保存为文本语料。
## 读取 HTML 页面
支持网页访问和正文提取的 Agent 可以直接读取页面 URL。文档页面的 HTML 响应包含完整正文，也包含站点导航、交互脚本、样式和页面元数据。
读取 HTML 页面时，Agent 应执行以下处理：
1. 提取文章标题和正文区域。
2. 忽略页面导航、页脚、登录入口和交互控件。
3. 忽略脚本、样式及其配置数据。
4. 保留正文中的代码块、表格和链接语义。
不同网页读取工具的正文提取能力不同。工具直接返回原始 HTML 时，不要把完整响应注入模型上下文。
## 配置直接读取规则
将以下规则加入 Agent 的系统提示词：
```text
已知文档页面地址时，先读取 .md 获取 Markdown 镜像。
如果 .md 不可用，再读取 获取 HTML 页面。
读取 HTML 页面时，只保留文章标题和正文，忽略导航、脚本、样式、页脚和交互控件。
```
## 相关文档
- 比较全部读取方式，详情请参见[选择读取方式](/docs/read-docs-with-ai-agents)。
- 通过索引定位文档，详情请参见[llms.txt](/docs/read-ark-docs-with-llms-txt)。
---
# 文档 Skill
Source: https://ark.volcengine.com/region:cn-beijing/docs/ark-document-skills
本文列出当前方舟文档提供的 Skill。
## Skill 列表
| Skill | 功能 |
| --- | --- |
| `ark-model-benchmark` | 评测方舟模型的 TTFT、TPOT、E2E 和缓存命中率，并生成评测报告 |
| `ark-docs-assistant` | 分析模型升级或迁移方案，扫描项目中的模型引用并评估替换风险 |
| `sd25-pe` | 优化 Seedance 2.5 视频生成提示词 |
| `sd2-pe` | 优化 Seedance 2.0 视频生成提示词 |
## 安装 Skill
安装前需准备 Node.js 22.20.0 或更高版本，以及 npm。安装完成后，重新打开 AI Agent 会话再使用 Skill。
### ark-model-benchmark
`ark-model-benchmark` 支持连通性检查、Prefix 前缀复用、多轮长上下文和完整测试，并在 `reports/` 目录中生成 Markdown 报告和 PNG 图表。
使用前需安装 Ark CLI 并完成 SSO 登录：
```bash
npm install -g @volcengine/ark-cli@latest
arkcli auth login volc-sso
```
执行以下命令安装 Skill：
```bash
npx --yes skills@latest add "https://arkdocs.tos-cn-beijing.volces.com/skills/" \
--skill ark-model-benchmark \
--yes
```
安装完成后，使用自然语言触发。例如：
```text
帮我压测一下方舟上豆包 Seed 2.0 Mini 模型的性能。
```
有关评测模式、参数和报告说明，详情请参见[模型接入指南（LLM） - 性能评测](/docs/go-live-benchmark-guide)。
### ark-docs-assistant
`ark-docs-assistant` 用于分析模型升级或迁移方案，也可以扫描代码项目中的模型引用，生成模型替换清单并评估迁移风险。
该 Skill 优先使用文档 MCP 获取信息；MCP 不可用时，会尝试使用 Ark CLI。文档 MCP 的配置方法，详情请参见[文档 MCP](/docs/tutorials-mcp)。
执行以下命令安装 Skill：
```bash
npx --yes skills@latest add "https://arkdocs.tos-cn-beijing.volces.com/skills/" \
--skill ark-docs-assistant \
--yes
```
安装完成后，使用自然语言触发。例如：
```text
扫描当前项目，将目标模型升级为最新模型，先给出迁移清单，不要直接修改。
```
有关模型迁移场景，详情请参见[Seed-Evolving](/docs/latest-model)。
### sd25-pe
`sd25-pe` 可以处理文本、故事片段和多模态参考素材，并根据视频生成、关键帧、分镜、视频编辑、声音编辑或视频延长等任务组织提示词。
执行以下命令安装 Skill：
```bash
npx --yes skills@latest add "https://arkdocs.tos-cn-beijing.volces.com/skills/" \
--skill sd25-pe \
--yes
```
安装完成后，在 AI Agent 对话框中输入：
```text
/sd25-pe + 你的提示词内容
```
该 Skill 只负责生成或优化提示词，不会自行提交视频生成任务。有关 Seedance 2.5 提示词写法，详情请参见[Doubao Seedance 2.5 提示词指南](/docs/seedance-2-5-prompt-guide)。
### sd2-pe
`sd2-pe` 可以根据任务类型整理 Seedance 2.0 视频生成提示词中的主体、动作、场景、镜头、风格和素材引用关系。
执行以下命令安装 Skill：
```bash
npx --yes skills@latest add "https://arkdocs.tos-cn-beijing.volces.com/skills/" \
--skill sd2-pe \
--yes
```
安装完成后，在 AI Agent 对话框中输入：
```text
/sd2-pe + 你的提示词内容
```
有关 Seedance 2.0 的模型能力和提示词规则，详情请参见[Doubao Seedance 2.0 系列教程](/docs/seedance-2-0)。