volcengine-cli

Volcengine CLI 技能

使用 ve 作为 Volcengine OpenAPI、TOS 对象操作、Ark 产品工作流和 TLS 日志服务工作流的统一入口。

Agent 调用方元数据（必需）

Agent 启动的每个 ve 进程都必须接收以下环境变量，包括 帮助／版本检查、身份验证、API 调用、重试、轮询，以及 ve tosutil / ve arkcli / ve volclog：

变量	必需值
VE_CALLER_TYPE	始终为 ai_agent。
VE_CALLER_NAME	从当前运行时环境中解析实际的 Agent 宿主标识符。此值标识 Agent 应用，而非模型、账户、用户或会话。
VE_SKILL_NAME	从执行此命令的工作流所使用的活动 Volcengine 技能 frontmatter 中解析 name。使用实际的 volcengine-* 名称。

请自行设置这些值；它们是运行时归属信息，并非凭据或用户设置步骤。 只有 VE_CALLER_TYPE=ai_agent 是固定值。每次执行前都要解析当前宿主和活动技能；两者都没有硬编码的默认值。例如，只有当前 Agent 是 Codex 时，codex 才有效；只有当 volcengine-cli 技能负责当前操作时，它才有效。当 Agent 环境或活动技能发生变化时，请重新解析这些值。共享辅助程序和上游产品 CLI 会继承实际调用的 Volcengine 技能身份；它们的可执行文件名称或安装目录不能决定该身份。

每次执行都要通过工具的进程环境或命令局部赋值提供全部三个变量。新的工具调用可能会启动全新的 shell，因此之前的 export 不足以满足要求。对于多命令 shell 代码块，请在代码块开头导出全部三个变量，并在切换工作流前更新技能名称。请将赋值放在可执行文件之前；这些不是 CLI 标志、API 参数，也不是要添加到请求正文的字段。 对于管道和 $(...)，请将变量设置在 ve 进程本身，或在运行管道或展开命令替换之前于同一 shell 中导出变量。

命令形式——执行前，Agent 必须将两个占位符替换为从实际运行时环境和活动技能中解析出的值：

VE_CALLER_TYPE=ai_agent \
VE_CALLER_NAME="<agent-id>" \
VE_SKILL_NAME="<current-volcengine-skill>" \
  ve ecs DescribeInstances --output json

对任何会启动 ve 的脚本，也要应用相同的环境，包括 install_ve.sh、ve_login_remote.sh、audit_extend_apis.py 和 call_extend_api.py。它们的子进程（包括分离运行的登录进程）会继承这些变量；后续再次调用辅助程序时，仍需重新提供这些变量。通过管道运行下载的安装程序时，应将环境附加到运行安装程序的 shell，而非仅附加到下载命令。保留必需的身份验证／配置设置和子 CLI 参数；调用方元数据请遵循下方的 Ark 委派规则。

本技能及其引用中的命令示例展示了命令语法；本环境要求同样适用于每次执行这些示例。

Ark 委派：一组调用方变量

对于 ve arkcli ...，请提供上述三个 VE_* 调用方变量。ve 会将它们转换为 Ark CLI 环境，因此 Agent 不得再添加 ARKCLI_CALLER_TYPE、ARKCLI_CALLER_NAME 或 ARKCLI_SKILL_NAME。也不要将独立 Ark 示例中的 ARKCLI_NO_UPDATE_NOTIFIER=1 复制到命令前缀中；让 ve 管理委派进程。此规则适用于 Ark 身份验证、模型操作、帮助和版本命令。

VE_CALLER_TYPE=ai_agent \
VE_CALLER_NAME="<agent-id>" \
VE_SKILL_NAME="<current-volcengine-skill>" \
  ve arkcli auth status

请根据实际 Agent 环境和活动 Volcengine 技能解析占位符。若要复用独立 Ark 调用的进程环境，请从本次调用中省略上述由包装器管理的四个变量。保留其他产品设置和凭据。 独立的 arkcli ... 调用仍须遵循上游 Ark 技能的环境规则。

产品 CLI 路由

版本要求：§0 最低版本（ve >= 1.1.11）也是委派给其他 CLI 的前提，包括 ve tosutil、ve arkcli 和 ve volclog。委派前请确认版本。仅凭 --help 中出现代理命令并不能满足此要求。

如果可以使用 ve，即使已安装独立的 tosutil、arkcli 或 volclog，也优先使用 ve tosutil、ve arkcli 和 ve volclog。TOS 命令的拼写是 tosutil；toscli 是兼容性别名。现有的 TOS 技能名为 volcengine-tosutil（不是 volcengine-tosutils）。

任务	入口	使用前阅读
通用云资源 OpenAPI	ve <service> <Action>	§§1–5 中的原生 API 工作流
TOS 存储桶、对象和传输	ve tosutil <command>	使用 volcengine-find-skills 查找 volcengine-tosutil，如果未安装则安装，并阅读其说明
Ark 模型、推理、生成、Endpoints、微调、套餐和用量	ve arkcli <command>	按下文所述，下载并阅读相关的官方 Ark 技能
TLS（日志服务）日志搜索、分析、摄取、导出、Project/Topic 和 LogCollector 采集	ve volclog <command>	使用 volcengine-find-skills 查找 volcengine-tls（采集时使用 volcengine-tls-logcollector），如果未安装则安装，并阅读其说明

对于 TOS，请按查找器的 list → 选择确切的 volcengine-tosutil → 若未安装则安装 → 验证安装流程执行。执行前，加载已安装的技能及其选定的参考资料。使用其中原生的 tosutil 命令示例，将 tosutil ... 替换为 ve tosutil ...。

对于 TLS，请按照相同的查找器流程选择确切的 volcengine-tls；LogCollector 采集则选择 volcengine-tls-logcollector。这些技能会编写原生的 volclog ... 示例；运行时将其写作 ve volclog ...。ve 没有原生的 tls OpenAPI 命令：如果 ve volclog 报告未知服务或建议使用 --force，说明 ve 的版本早于上述要求，应升级 ve，而不是添加 --force。

对于 Ark，请从上面的官方仓库中选择任务技能，并与 arkcli-shared 及其说明要求的依赖一起安装。这些上游 arkcli-* 名称不属于本地 Volcengine 查找器目录中的条目；请直接从 Ark 仓库安装。例如，在 Codex 中发现模型：

npx --yes skills add https://github.com/volcengine/ark-cli \
  --skill arkcli-shared arkcli-auth arkcli-models --agent codex --yes --copy --full-depth
npx --yes skills list --agent codex --json

请使用实际宿主的 --agent 和任务技能名称。默认按项目范围安装；只有需要在用户级别安装时，才在两条命令中都添加 --global。执行前，请核对名称并阅读已安装的 arkcli-shared/SKILL.md、任务技能及其选定的参考资料。如果宿主无法加载新安装的技能，请按照查找器的说明，开启新对话并附上原始任务和已完成的上下文。产品说明请保留在这些技能中；此技能仅负责将请求路由到相应技能。

arkcli、tosutil 和 volclog 是透明委派的 CLI：仅替换其示例中的可执行文件前缀，后续所有参数保持不变。它们保留各自的身份验证、配置文件、参数、输出和退出代码。原生 API 规则（例如 --output、--query、--force、--detail、PascalCase 参数和 --DryRun）不适用。

• 将受支持的子命令标志放在子命令之后。ve --profile <name> arkcli ... 无效； ve arkcli ... --profile <name> 选择的是 Ark 配置，而不是 ve 配置。
• 遵循产品技能中的身份验证、标志和输出处理方式。将 tosutil ... / arkcli ... / volclog ... 改为 ve tosutil ... / ve arkcli ... / ve volclog ...，同时 保持所有子命令参数不变。 对于 ve arkcli，仅使用 Ark 委派 中所述的 VE_* 调用方元数据；不要复制独立 Ark 的调用方/通知器前缀。将任何必需的产品环境变量赋值放在 ve 之前。
• ve sts GetCallerIdentity 能正常运行，并不能证明任一子命令已完成身份验证。遵循所选产品技能。帮助、版本和本地预览任务不需要原生 API 登录。
• ve 在委派之前可能会刷新当前的 Console Login 会话；这并不意味着所有 ve 凭据或配置设置都会转换为子命令配置。仅有刷新警告，并不能证明子命令执行失败。

产品 CLI 安装与升级

ve 先从 PATH 查找子命令，再查找其托管目录；如果子命令缺失，则首次使用时从官方 CDN 安装，并验证校验和。不需要单独安装产品。只检查任务所需的子命令：

ve tosutil version
ve tosutil help
ve arkcli --version
ve arkcli --help
ve volclog --version
ve volclog --help

使用 ve proxycli upgrade tosutil、ve proxycli upgrade arkcli 或 ve proxycli upgrade tls-cli 升级托管的子命令。管理命令使用产品 ID（TLS 的产品 ID 为 tls-cli）， 而调用时使用原生命令名称（ve volclog）。 这些命令不会更改 PATH 上的外部安装，这些安装仍由其原有的包管理器管理； 仅升级 ve 不会升级它们。如果 ve --help 中缺少子命令，请先升级 ve。产品标志和可用功能以已解析子命令的帮助信息为准。

---

0. 安装或升级 ve CLI

始终使用最新版本。本技能要求使用当前版本的 ve：支持设备码登录的 ve login、--output/--query、--force、--detail 和双连字符系统标志。不支持旧版本——请升级。

最低版本（强制）： 在任务中运行任何其他 ve 命令之前——包括原生 OpenAPI 调用、登录或产品 CLI 委派——先运行 ve version，并确认 ve >= 1.1.11（稳定版本为 1.1.11 或更高）。如果未安装 ve、版本低于 1.1.11，或无法确认版本，请使用以下任一选项安装或升级，然后再次运行 ve version 再继续。如果 npm 安装的仍是旧版本，则配置的 npm 镜像可能尚未同步；请改用 CDN 安装程序或 GitHub Releases。

选项 1：npm（首选）

npm i -g @volcengine/cli

选项 2：CDN 安装程序（没有 Node.js，或无法访问 npm）

curl -fsSL https://cloudcache.volccdn.com/ve/install.sh | sh
# or
wget -qO- https://cloudcache.volccdn.com/ve/install.sh | sh

同一脚本也以 scripts/install_ve.sh 的形式提供。它会从 CDN 获取最新版本，下载适用于主机操作系统/CPU 的归档文件，根据发布的 SHA256SUMS 验证文件，将其安装到可写入时的 /usr/local/bin（否则安装到 ~/.local/bin，绝不使用 sudo），移除 macOS 隔离标记，并运行 ve skills update。脚本头部列出了 --version <ver>、--install-dir <dir>、--dry-run 以及 VE_VERSION / VE_INSTALL_DIR / VOLCENGINE_CLI_DOWNLOAD_BASE_URL / VOLCENGINE_CLI_SKIP_SKILLS 变量的说明。Windows：请使用 npm 或发布页面。

选项 3：GitHub Releases — https://github.com/volcengine/volcengine-cli/releases

原生 OpenAPI 功能检查： ve login --help 必须列出 --no-browser，且 ve ecs DescribeInstances --help 必须在 System Flags 下列出 --output。如果缺少其中任一项，请使用 npm i -g @volcengine/cli@latest 升级，或重新运行 CDN 安装程序，然后继续。这些检查不能替代上述最低版本要求。

---

1. 原生 OpenAPI 初始化（用于 API 调用）

本节适用于 ve <service> <Action> 和扩展辅助工具。对于委托的产品命令，请先遵循产品 CLI 路由，再使用所选产品技能。

CLI 系统标志

每次 ve <service> <Action> 调用都可在 Action 后接受以下标志，且所有标志均使用两个连字符：

标志	用途
--profile <name>	仅对此次调用使用已配置的配置文件
--region <region>	仅对此次调用覆盖区域
--endpoint <host>	仅对此次调用覆盖端点
--lang EN|ZH	此次调用的显示语言
--version <YYYY-MM-DD>	API 版本；省略时使用元数据默认值（与 --force 一起使用时为必填项）
--method GET|POST	HTTP 方法；使用元数据默认值，否则为 GET
--force	跳过元数据验证（§3）；仅表示存在，绝不要写成 --force true
--output <fmt> / --query <jmespath>	响应格式化与投影（§4）
--header Name=Value、--body '{...}'	自定义标头 / 原始 JSON 请求体

API 参数采用 PascalCase（--Region、--InstanceIds.1），系统标志采用小写（--region），因此通常不会冲突。仅当 API 参数的拼写与某个小写系统标志完全相同时（例如 API 本身有 --query 或 --lang 字段），才将系统标志写成三个连字符（---query），API 参数仍使用两个连字符。其他任何地方都不要使用三个连字符的标志。

CLI 管理命令（ve configure ...、ve login、ve sso login）和辅助脚本使用各自的两个连字符标志，具体如 --help 所示。

配置文件选择（在整个对话中固定）

ve 可以通过不同的配置文件使用不同的凭证，但 Agent 不得自行选择配置文件。

• 如果用户未明确选择配置文件，请使用 CLI 的默认解析方式：直接运行 ve sts GetCallerIdentity。不要先列出所有配置文件再自行选择。
• 如果用户明确选择了配置文件，则在本次对话的所有后续命令中继续使用同一个配置文件：ve ecs DescribeInstances --profile prod、python3 scripts/call_extend_api.py --profile prod ...。
• 不要根据配置文件名称、区域、列表顺序、近期可用性、成功率或任务内容推断所需的配置文件。
• 如果默认身份与任务风险不匹配，或需要选择配置文件，请告知用户当前的默认身份，仅列出候选配置文件名称，并等待用户选择。
• 在本次对话中固定配置文件后，除非用户明确要求切换，否则不要切换到其他配置文件。

运行身份验证命令，确认凭证可用：

ve sts GetCallerIdentity

成功——告知用户当前账号身份和区域，然后继续执行任务。

稍后切换区域：服务 API 调用中的 --region 会覆盖该单次调用的区域（响应中的 Region 会相应变化），且当配置文件未设置区域时，VOLCENGINE_REGION 会设置默认区域。不会发生变化的是配置文件绑定的登录会话／账号——区域覆盖只会改变请求的目标位置，不会改变你的身份。不要主动切换区域或配置文件：只有用户明确要求时，才传入 --region 或切换配置文件（ve configure profile --profile <name>）。仅使用 ve configure list 显示候选配置文件名称；列出后不要自行选择配置文件。这与 ve login 本身的 --region 标志不同，后者是必需的（见下文）。

失败——没有可用的配置文件。默认方案：使用 ve login（控制台登录）。请事先告知用户，并说明他们可以说“使用 AK/SK”“使用 STS token”或“使用 SSO”来切换方式。

当之前可用的会话在任务进行中过期时，也适用同一方案：任何 ve 命令因 failed to refresh session token. Please run 've login' to re-authenticate（或类似的刷新令牌／会话过期提示）而失败，都是同一种情况，无论发出该命令的是哪个技能。错误文本会提示用户运行 ve login——不要将此指示转告用户，也不要让他们在自己的终端中运行 ve login；请自行执行下文的控制台登录流程，并且只向用户提供登录链接。重新登录必须针对正在使用的配置文件：如果在本次对话早些时候已固定配置文件，则将其传给 start，确保登录和验证都针对该配置文件——省略它会刷新 default，导致固定配置文件仍无法使用，并污染默认账号上下文。

默认方式：通过 scripts/ve_login_remote.sh 登录控制台

绝不要直接调用 ve login。务必使用 scripts/ve_login_remote.sh。 ve login 使用设备码流程：ve 会打印验证 URL 和用户代码，然后轮询，直到用户在任意设备上的浏览器中批准。设备代码只存在于该 ve 进程中，因此该辅助脚本会将其分离（setsid），使其跨工具调用边界存活，记录 URL 和代码，响应 ve 的提示，并验证结果。自行调用 ve login 会使进程失去管理，导致链接失效。

在对话中首次执行 start 之前，请完整阅读 references/console-login.md ——其中包含分步流程、所有退出代码、start-wait 变体、调优方法，以及所有会导致流程中断的情况。流程形式如下：

scripts/ve_login_remote.sh start <region> [profile]   # prints URL= CODE= LINK= EXPIRES_IN= NEXT=
scripts/ve_login_remote.sh url                        # same block, never blocks (11 = not yet, 3 = process gone)
# hand the user LINK (fallback: URL + CODE), end the turn, wait for "done"
scripts/ve_login_remote.sh verify [profile]           # 0 ok · 11 still pending · 13 logged in but API unreachable · 10 start over
scripts/ve_login_remote.sh abort                      # on user interrupt / expired code, then start again

区域：优先使用用户指定的区域，否则使用 VOLCENGINE_REGION，再否则使用 cn-beijing。只有当用户之前指定了 [profile] 时才传入它，并且传给 start 和 verify 的值必须相同。

即使不阅读参考文档，以下规则也必须遵守：

• 先说明计划和退出方式（“说‘use AK/SK’即可切换”），然后再开始——不要提供登录方式菜单。
• start 卡住或被终止不能证明任何事情：得出结论前先调用 url/status；绝不要因此重试 start、abort，或改用 nohup。
• 用户不会粘贴任何内容回来；不存在授权码。用户表示已批准后，运行 verify。
• verify 退出代码为 13，表示登录已成功，但主机无法访问 open.volcengineapi.com ——不要重新开始登录。
• 按原样使用 LINK；绝不要构造 signin.volcengine.com URL，也不要复用之前进程的 URL。
• start 退出代码为 4 = 未安装 ve，或其版本太旧，不支持设备码登录 → 安装/升级（§0），然后重试。

如果 ve login 失败（网络错误、start 退出代码为 4、所有设备上都没有浏览器），或者用户要求使用其他方式，请改用以下替代方案。

替代方式：AK/SK（长期凭证，适用于 CI/CD 或脚本）

向用户索取 AccessKey 和 SecretKey，然后：

ve configure set --profile default --region cn-beijing \
  --endpoint open.volcengineapi.com \
  --access-key <AK> --secret-key <SK>

对于 STS（临时）凭证，还需传入 --session-token <TOKEN>。

仅对当前 shell 生效的替代方式：导出 VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY、VOLCENGINE_REGION，并可选导出 VOLCENGINE_SESSION_TOKEN。

替代方式：SSO / Cloud Identity Center（适用于企业联合身份验证）

分三步设置；先向用户索取 SSO 起始 URL 和会话名称：

ve configure sso-session --name <session-name> \
  --start-url https://<sso-host>/userportal \
  --region cn-beijing \
  --registration-scopes cloudidentity:account:access,offline_access

ve configure sso --profile <profile-name> --sso-session <session-name>

ve configure profile --profile <profile-name>

然后运行 ve sso login --sso-session <session-name>（在无头机器上使用 --no-browser）。

凭证安全

• 绝不要读取 ~/.volcengine/config.json ——其中包含 AK/SK 和会话令牌。
• 运行带有 --secret-key 的 ve configure set 时，最好让用户在自己的 shell 中粘贴并运行命令，而不是通过 Claude 执行——作为命令行参数传入的密钥会留在 shell 历史记录和进程列表中。
• 绝不要以明文形式向用户回显 AK/SK、密钥或会话令牌。

---

2. 安全规则（强制）

读写分类

级别	操作类型	行为
只读	Describe* / List* / Get* / Query*	直接执行，无需确认
写入	Create* / Run* / Allocate* / Attach* / Associate* / Authorize*	显示完整命令并等待用户确认
破坏性	Delete* / Terminate* / Release* / Revoke* / Modify* / Stop* / Detach*	显示命令和影响摘要；必须获得用户确认

核心原则

1. 默认只读 — 除非用户明确要求更改，否则以只读模式执行
2. 先执行 DryRun — 如果写入/破坏性操作支持 --DryRun true，先执行 DryRun 预览计划，然后在执行前确认
3. 执行前确认 — 显示写入操作的完整命令，并等待批准
4. 保护凭据 — 切勿读取 ~/.volcengine/config.json；切勿在输出中暴露 access-key、secret-key 或 session-token

DryRun 说明

DryRun 验证成功时会返回 退出代码 1（非零），且 stderr 中包含 DryRunOperation。这是预期行为：

output=$(ve <svc> <action> --DryRun true ... 2>&1)
if echo "$output" | grep -q "DryRunOperation"; then
  echo "Parameter validation passed"
fi

---

3. 定位 API 并检索参数

定位 API（查找服务名称 + Action 名称）

Step 1: Service name + Action known? -> Use them directly; skip to "Retrieve parameters"
Step 2: Service name known, Action unknown?
  -> ve <service> 2>&1 | grep -i <keyword>
Step 3: Service name also unknown?
  -> ve 2>&1 | grep -i <service keyword>
Step 4: None of the above work?
  -> python3 scripts/find_api.py <keyword>   (returns Service, Action, Version)

检索参数（已知 Action 后）

--help 输出简洁（名称、类型、必填/可选）。--help --detail 会为每个参数补充完整描述、枚举值、约束和示例——它是 CLI 自带的 API 文档副本，无需外部获取。

情况	命令
只读（Describe/List/Get）	ve <svc> <Action> --help — 通常只需查看名称
写入/破坏性操作（Create/Run/Delete…）	ve <svc> <Action> --help --detail — 查看必填字段、嵌套结构和示例
查看 --help 后仍不清楚	--help --detail；添加 --lang ZH 查看中文文本
出现 Invalid* / Missing* 等错误	使用 --help --detail 重新检查名称、必填字段和取值范围

ve ecs DescribeInstances --help
ve ecs RunInstances --help --detail
ve ecs RunInstances -h --detail --lang ZH

同一输出中的 Parameter Form / --body 部分会说明该 Action 接受的是平铺参数还是 JSON 请求体（§4）。

对于超出单个 Action 参数范围的 API 问题（比较、错误代码语义、分页行为、是否存在批量版本），请加载 volcengine-api 技能，该技能会直接查询 API Explorer。

ve 命令名称与 API 版本的关系

• 默认版本 -> ve 命令 = 基础服务名称（例如 iam）
• 非默认版本 -> ve 命令 = 服务名称 + 去掉连字符的版本号（例如，iam v2021-08-01 -> iam20210801）
• 不确定时：运行 ve 2>&1 | grep <service> 进行确认

调用 CLI 元数据中未列出的 API：--force

当 ve 返回 unknown service "<svc>" 或 unknown action，但 API 确实存在（用户提供了 API、find_api.py 找到了其 Service/Action/Version，或文档中有说明）时，请使用 --force 调用。--force 会跳过本地元数据检查，因此你必须提供元数据中本应包含的信息：版本，以及——对于 CLI 不认识的服务——端点。

ve newservice DescribeNewResource \
  --version 2024-01-01 \
  --endpoint open.volcengineapi.com \
  --SomeParam value \
  --force

• --version 为必填项（使用 --force 时必须提供 --version）；对于未知服务，除非 profile 或 VOLCENGINE_ENDPOINT 已设置端点，否则必须提供 --endpoint。
• 对于 POST API，使用 --method POST（默认值为 GET）；对于 JSON 请求体，使用 --body '{...}'（不能与 --Param 值混用）；如果服务固定在某个区域签名，则使用 --region。
• --force 是一个存在性标志：使用 --force，而不是 --force true。
• 参数未经验证：只能从用户提供的材料、volcengine-api 技能或 references/extend-apis.md 获取参数，切勿猜测。find_api.py 只定位 Service/Action/Version；不会返回参数、方法或端点。
• §2 中的只读/写入/破坏性操作规则同样适用于已列出的 Action。
• 不要对 TLS（日志服务）使用 --force；ve 没有 tls OpenAPI 命令，因此应通过产品 CLI 路由表，将 TLS 任务路由到 ve volclog。

references/extend-apis.md 包含扩展服务的服务代码/版本/端点/签名区域配置方案；这些服务此前由辅助脚本封装，包括 CDN、DCDN、domain、Flink、GA、IoT、Live、MCDN、Metrics、sec_agent、trademark、VEEN、VKE。

Extension helper（单个请求中同时包含 query 和 body）

ve --force 不能在单个 POST 请求中同时发送 URL 查询参数和请求 body。少数 API（VMP Prometheus 查询、Flink GWS）恰好需要这样做；仅对这些 API 使用此 helper，不要用于其他情况：

python3 scripts/call_extend_api.py --list
python3 scripts/call_extend_api.py --api QueryMetrics --params '{"workspace":"<id>","query":"up"}'

升级 ve 后，运行 python3 scripts/audit_extend_apis.py——它会列出新元数据现已原生支持的配方/helper 条目，因此可以将其移除。

它还提供自由模式（--service/--version/--query-keys），用于形态相同但未注册的 API。凭证、选项和已注册列表请参阅 references/extend-apis.md。除非用户已在本次对话中明确选择了某个配置文件，否则不要传入 --profile。

---

4. 执行 API 调用

基本格式

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME=<agent-id> VE_SKILL_NAME=<current-volcengine-skill> \
  ve <ServiceCode> <ActionName> --ParamName "value" [system flags]

系统标志（--profile、--region、--endpoint、--output、--query 等）放在 Action 之后，其顺序相对于参数可以任意调整。

参数传递规则

根据 --help 输出确定格式：

• 扁平参数格式：--help 列出单独的 --Key type 条目（例如 ECS、VPC、IAM）-> 使用 --Key "value" 传递
• 数组参数：优先使用 --help 所示的编号 CLI 格式，例如 --InstanceIds.1 "$instance_id" 或 --SubnetIds.1 "$subnet_id"。不要假设每个 Action 都接受 JSON 数组字符串。
• JSON 格式：--help 只显示 --body '{...}'（例如 Redis、CR 和其他 POST API）-> 使用 --body '{...}' 传递

# Flat parameters — nested fields use dot notation; arrays use .N index (starting from 1)
ve ecs RunInstances --ZoneId "cn-beijing-a"
ve ecs RunInstances --NetworkInterfaces.1.SubnetId "subnet-xxxx"
ve ecs RunInstances --Tags.1.Key "publish-by" --Tags.1.Value "deploy-skill"

# JSON format (when --help only shows --body)
ve redis CreateDBInstance --body '{"InstanceName":"demo","RegionId":"cn-beijing","ConfigureNodes":[{"AZ":"cn-beijing-a"}],"ShardedCluster":0,"NodeNumber":2,"ShardCapacity":1024,"ShardNumber":1,"EngineVersion":"6.0","SubnetId":"subnet-xxxx","VpcId":"vpc-xxxx","Password":"<secret>","Tags":[{"Key":"publish-by","Value":"deploy-skill"}]}'

输出格式和查询

每个 API 调用都接受 --output 和 --query；它们可以替代对 JSON 使用临时的 grep/jq。

--output	用途
json（默认）	完整响应；以此格式进行程序化解析
table / table-num	易读列表；table-num 会添加行号列——适合向用户展示资源列表
text	纯文本值，每行一个——适合在 shell 变量中捕获单个字段或 ID 列表
yaml	易读的嵌套详情
off	执行调用但不打印任何内容（跳过依赖响应的 --query 求值）。仅用于确实不需要响应的调用——绝不要用于 Create*/Run*/Allocate*，因为响应是新资源 ID 的唯一来源

--query 接受一个 JMESPath 表达式，在格式化之前对完整响应进行求值，因此路径从 Result.（或 ResponseMetadata.）开始：

# Single field
ve sts GetCallerIdentity --query 'Result.AccountId' --output text

# Project a list for the user
ve ecs DescribeInstances --query 'Result.Instances[].{Id:InstanceId,Name:InstanceName,Status:Status,Zone:ZoneId}' --output table

# Filter, then pick IDs into a shell variable
ids=$(ve ecs DescribeInstances --query "Result.Instances[?Status=='RUNNING'].InstanceId" --output text)

# Length / existence checks
ve vpc DescribeVpcs --query 'length(Result.Vpcs)' --output text

经验法则：

• 当你（Agent）需要读取响应时，保留 json；仅在向用户展示时切换为 table/yaml。
• 在查看 ResponseMetadata.Error 之前，不要将写入/破坏性调用的 --query 结果筛选为空；失败时仍会打印错误对象。
• --query 筛选的是打印内容，而不是请求内容——分页（NextToken、PageNumber）不变。

响应格式

// Success
{ "ResponseMetadata": { "RequestId": "..." }, "Result": { ... } }

// Failure
{ "ResponseMetadata": { "Error": { "Code": "...", "Message": "..." } } }

错误处理

每当原生 ve <service> <Action> 命令或扩展辅助程序失败，或响应中包含 ResponseMetadata.Error 时，请先完整阅读 references/common-errors.md，再诊断错误或回复用户。部分搜索结果、匹配行或摘录不符合此要求。对于 ve tosutil / ve arkcli / ve volclog 失败，请遵循所选产品技能和原生命令的子错误格式。

首先将错误归类为请求格式、缺少依赖项、账户状态、服务激活、实名认证、购买资格或权限相关错误。对于产品专属错误，还需阅读下面对应的服务说明。对于权限错误（AccessDenied、NoPermission、RoleNotExist、Forbidden 或 STS 相关故障），请启用 volcengine-troubleshooting 技能，并使用其账户权限诊断能力定位根因，指导用户完成修复。

对于 CLI 异常或未完全解决的任务，请遵循 volcengine-troubleshooting 中的非阻塞反馈指导：继续主要任务，并将任何可选邀请留到自然的总结中。用户主动请求反馈时，应使用 volcengine-feedback；若该技能不可用，请在当前对话中使用反馈表单，不要为了收集反馈而安装技能或重新开始任务。

异步资源创建需要轮询

某些资源（如 VKE 集群、RDS 实例、ECS 实例等）需要几分钟才能创建完成。创建后，请轮询 Describe 端点，直到资源达到所需状态再继续。

在创建 VPC 后立即创建子资源（例如安全组）可能会失败，并返回 InvalidVpc.InvalidStatus。请按顺序创建子资源（先创建子网，再创建安全组），或等待几秒后重试。

# General polling pattern: check every 30 s, give up after a deadline, stop on API failure
max_attempts=40   # 40 x 30 s = 20 min; size it to the resource type
for attempt in $(seq 1 "$max_attempts"); do
  if ! cur_status=$(ve <svc> Describe<Resource> --<IdParam> "xxx" --query 'Result.<Path>.Status' --output text 2>&1); then
    echo "describe failed: $cur_status"; break        # classify with common-errors.md, do not keep looping
  fi
  echo "$(date +%H:%M:%S) $cur_status"
  case "$cur_status" in
    Running) break ;;
    Error|Failed|Deleted) echo "resource entered $cur_status"; break ;;
  esac
  [ "$attempt" -eq "$max_attempts" ] && echo "timed out waiting for Running"
  sleep 30
done

Result.<Path> 和终态名称因产品而异——请从 --help --detail 和服务说明中获取，不要假定状态为 Running。

---

5. 原生 OpenAPI 执行流程（摘要）

1. Set caller metadata for this execution -> verify credentials -> GetCallerIdentity -> confirm region
2. Understand the task: is the user querying or making changes?
3. Locate the API: ve --help first -> find_api.py as fallback -> --force if the metadata lacks it
4. Retrieve parameters: --help, then --help --detail for write/destructive actions
5. Query dependent resources: use Describe*/List* (with --query to pick IDs) to obtain required IDs
6. Read operation -> execute directly and display results (--output table for lists)
   Write operation -> show command -> DryRun (if supported) -> user confirmation -> execute
7. Parse the response and report results to the user

---

6. 服务专属说明

遇到服务专属问题时，请查阅或更新对应的说明文件：

• 常见错误：references/common-errors.md
• 控制台登录流程（ve_login_remote.sh、退出代码、规则）：references/console-login.md
• Cloud Control API（cloudcontrol）：references/cloudcontrol.md
• ECS：references/ecs.md
• VPC：references/vpc.md
• CR：references/cr.md
• ALB：references/alb.md
• CLB：references/clb.md
• VKE：references/vke.md
• veFaaS：references/vefaas.md
• RDS：references/rds.md
• 消息队列：references/mq.md
• 存储 API：references/storage.md
• 可观测性：references/observability.md
• DNS/边缘：references/dns-edge.md
• IAM：references/iam.md
• KMS：references/kms.md
• Redis：references/redis.md
• NAT 网关：references/natgateway.md
• EBS：references/ebs.md
• 扩展 API（--force 用法及查询/请求体辅助程序）：references/extend-apis.md