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 参数，也不是要添加到请求正文中的字段。切勿将 VOLCENGINE_SAFETY_* 变量添加到此前缀中（§2）。 对于管道和 $(...)，请直接在 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）不适用。当地安全策略及其 --yes 重试（§2）也不适用；应遵循产品技能自身的确认规则。

• 将受支持的子命令标志放在子命令之后。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. 安全规则（强制）

这些规则适用于每次对话：

1. 默认只读——除非用户明确要求进行更改，否则以只读模式执行
2. 保护凭证——绝不读取 ~/.volcengine/config.json；绝不在输出中暴露 access-key、secret-key 或 session-token
3. 不要改动安全策略——除非用户明确要求更改策略本身，否则绝不运行 ve configure safety-policy enable|disable|add|remove，绝不读取或编辑 ~/.volcengine/safety-policy.json，也绝不在命令前缀、脚本或环境中设置、取消设置或覆盖 VOLCENGINE_SAFETY_POLICY_ENABLED、VOLCENGINE_SAFETY_POLICY_RULES 或 VOLCENGINE_SAFETY_SKIP_CONFIRM

获准执行或重试某项操作，并不代表获准更改安全策略。更改策略必须得到用户明确要求更改策略本身。

对于原生 OpenAPI 调用，只使用一个确认来源：安全策略已启用且规则列表非空时，使用 CLI；否则使用此技能的内置规则。对同一项操作绝不同时应用两者。

选择确认模式

在一次对话中首次调用原生 ve <service> <Action> 前（包括 ve sts GetCallerIdentity），使用与后续调用相同的调用者元数据和环境运行此命令：

ve configure safety-policy show

根据标准输出和消息文本判断，而非根据退出代码。没有安全策略支持的 ve 不提供 safety-policy 命令：它会向 stderr 输出 ve configure 用法说明，标准输出为空，但仍以 0 退出。

输出	模式
标准输出为 JSON，且 "enabled": true，rules 列表非空	安全策略——由 CLI 执行策略；不要应用技能的内置确认规则
标准输出为 JSON，且 "enabled": false 或 rules 列表为空	内置规则——仅遵循内置规则
输出包含 load effective safety policy:	两者都不适用。ve 将拒绝所有 API 调用，直到策略问题得到解决；向用户报告错误并停止。
其他任何情况：标准输出为空、ve configure 用法说明、未知命令错误或其他非 JSON 输出，无论退出代码是什么	内置规则——此 ve 不支持安全策略

只读取 enabled 和 rules 是否为空来选择模式。不要解读、匹配或缓存单条策略规则，以判断某项操作是否可以执行；该判断由 CLI 完成。

在本次对话中保持所选模式。仅当用户表示策略已更改，或以内置模式运行的调用被阻止或要求确认时，才再次运行 show；之后根据新输出选择的模式继续操作。

内置规则

仅在内置模式下将这些规则应用于原生调用。扩展助手调用也保留这些内置确认规则。

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

1. 先执行 DryRun——如果写入或破坏性操作支持 --DryRun true，先运行 DryRun 预览计划，然后再确认是否执行
2. 执行前先确认——显示写入操作的完整命令并等待批准

参考资料中的确认说明（“先向用户确认”、“需要明确确认”）均适用这些规则。

本地安全策略

对于安全策略模式下的原生调用，不要应用上述内置规则或参考资料中的确认说明。ve 会检查每次原生调用，包括使用 --force 的调用，因此请运行任务所需的命令，并根据 CLI 的结果采取行动：

ve 结果	策略判定	操作
API 响应或 API 错误	安全策略未拦截	按常规处理 API 结果或错误；不要再添加确认步骤。
operation blocked by safety policy: <service> <Action> (rule: <pattern>) / 操作被安全策略拒绝：...	deny；未发送请求	停止并告知用户该操作已被拒绝，在当前策略下无法继续。询问用户是否要调整策略，然后结束本轮并等待。不要自行重试或更改策略。
safety policy requires confirmation for: <service> <Action> / 安全策略要求确认以下操作：...	confirm；未发送请求	简要说明目标和影响，询问是否继续，然后结束本轮。用户再次明确批准后，使用添加了 --yes 的相同命令重试一次。无论调用是否成功，该批准都会被用掉。

• 每项操作开始时都不要使用 --yes（或 -y）；仅在唯一一次经批准的重试中添加它。本轮对话中此前的批准（包括对同一命令的批准）均不适用。
• 如果 ve 停在 Type 'yes' to proceed / 输入 'yes' 继续，绝不要回答它或向 ve 输送输入；其他消息请参阅 references/common-errors.md。
• 每次工具调用只运行一项写入或破坏性操作，并在进行下一项前检查结果；多命令 shell 代码块中被拦截的命令不会阻止后续命令运行。读取操作也可能需要确认：调用被拦截时，停止轮询循环。
• 多项操作需要确认时，先分别在不使用 --yes 的情况下各运行一次，并向用户列出所有被拦截的命令；仅对用户明确批准的命令各使用 --yes 重试一次。
• 不要通过其他方式执行被拒绝或暂缓的操作：不得使用该服务的其他拼写或版本、--force、Cloud Control、扩展辅助工具、产品 CLI、SDK 或原始 HTTP。ve 会对服务的所有拼写应用规则（rds_mysql、rdsmysql 和 rdsmysqlv2；cloudtrail 和 cloudtrail20180101）。
• 该策略不涵盖受委派的产品 CLI（ve tosutil、ve arkcli、ve volclog）；请遵循相应产品技能的说明。

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 部分会说明该操作接受的是扁平参数还是 JSON 请求体（§4）。

对于超出单个操作参数范围的 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（--version is required when using --force）；对于未知服务，除非配置文件或 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 同样适用；本地安全策略也会检查 --force 调用。
• 不要对 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）。

扩展辅助工具（仅用于在同一请求中同时发送查询参数和请求体）

ve --force 无法在同一个 POST 请求中同时发送 URL 查询参数和请求体。少数 API（VMP Prometheus 查询、Flink GWS）恰好需要这样做；仅对这些 API 使用辅助工具：

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 — 它会列出新元数据已原生覆盖的配方和辅助工具条目，以便移除这些条目。

它还提供自由模式（--service/--version/--query-keys），适用于形态相同但尚未注册的 API。凭据、选项和已注册列表见 references/extend-apis.md。除非用户已明确为本次对话选定配置文件，否则不要传入 --profile。

扩展辅助工具仍遵循内置确认规则（§2）。它们不在原生 CLI 安全策略集成范围内。

---

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": "..." } } }

错误处理

安全策略拦截或确认请求（§2）意味着未发送任何请求。按 §2 所述处理；这既不是权限错误，也不是 CLI 异常，因此无需启动权限诊断或邀请用户反馈。

每当原生 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 -> choose the confirmation mode (§2) -> 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, built-in rules -> show command -> DryRun (if supported) -> user confirmation -> execute
   Write operation, safety policy  -> execute -> if blocked or held for confirmation, follow §2
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