alibabacloud-cli-guidance：用户运行 skills 时如出现报错，cli-guidance 可提供调试指引，包括入参规则、插件管理、多版本支持以及错误调试方法。

Aliyun CLI 专家

引导用户使用 aliyun 命令行工具有效管理阿里云资源。

所需权限：见 ./references/ram-policies.md（## required_permissions）。对其他 CLI 命令按需扩展。

指令

Agent 执行：AI-mode 与 User-Agent（本 Skill）

Skill 标识符（无论走哪条路径，字符串相同）：AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance

使用恰好一种方式将本 Skill 附加到请求。不要为同一 skill token 组合 AI-mode（configure ai-mode + set-user-agent）与 ALIBABA_CLOUD_USER_AGENT 或逐命令环境前缀——CLI 会叠加这些来源，User-Agent / 归属会重复（对遥测不利）。

路径 A —— 开始（在第一次命中 API 的 aliyun 之前；如需要，可先运行不涉及云调用的本地 aliyun configure）：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance"

路径 A —— [必须] 每次退出都禁用（Skill 停止后 AI-mode 不得保持开启）：

aliyun configure ai-mode disable

路径 B —— 示例（每个工作流一种载体：export、内联 env 或根 --user-agent；绝不叠加同一 token 或与路径 A 混用）：

export ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance

… aliyun … 调用 … 然后：unset ALIBABA_CLOUD_USER_AGENT

ALIBABA_CLOUD_USER_AGENT=AlibabaCloud-Agent-Skills/alibabacloud-cli-guidance aliyun ecs DescribeRegions

根 **`--user-agent`** 也是路径 B 语义——不要为同一 token 与路径 A 组合。**非 Agent** 复制粘贴：路径 B 通常足够；**Agent** 会话：路径 A + 退出时禁用。下方示例只用路径 A 或 B，绝不同时用。

**前置检查：需要 Aliyun CLI >= 3.3.3** —— 运行 `aliyun version`。若过低：`curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` 或见 `references/installation-guide.md`。

**前置检查：需要更新 Aliyun CLI 插件** —— [必须] `aliyun configure set --auto-plugin-install true`；[必须] `aliyun plugin update`。

**CLI 版本里程碑（Agent 和用户）**

| 从版本 | 你能获得什么 |
| ------------- | -------------- |
| **>= 3.3.3** | 本 Skill 中产品插件和流程的基线（见上方前置检查）。 |
| **>= 3.3.5** | **`aliyun upgrade`** —— 当子命令存在时，从二进制自身更新 CLI。CLI 足够新时，日常升级优先用它而非重跑安装脚本。 |
| **>= 3.3.8** | **`aliyun plugin show --name <plugin>`** —— **已安装**插件的详情（版本、产品代码、描述、API 版本等）。旧版 CLI 上，只用 `aliyun plugin list` 和产品 `--help`。 |

### 1. 安装并配置 CLI

如果用户尚未安装或配置 CLI，引导其完成设置。
完整细节见 `./references/installation-guide.md`。快速路径：

安装或更新（macOS / Linux —— 一条命令）

/bin/bash -c "$(curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh)"

CLI 达到 **3.3.5 或更新**后，日常自更新可用 **`aliyun upgrade`** 而非 curl 安装器（首次安装或 `upgrade` 不可用时仍适合用安装器）：

aliyun version # 依赖 upgrade 前确认 >= 3.3.5

aliyun upgrade

#### OAuth（浏览器登录）

当同一台机器上**能打开浏览器**时（例如带 GUI 的本地桌面），**优先 OAuth** 而非存储 AccessKey 对：凭证不会以明文 AK/SecretKey 保存在配置中，且登录可使用 SSO。需要 Aliyun CLI **3.0.299** 或更高。**不**适合无头环境（例如无本地浏览器的纯 SSH 服务器）。

交互式运行：

aliyun configure --profile <your-profile-name> --mode OAuth

完整设置（管理员同意、RAM 身份分配、`CN` vs `INTL` 站点）记录在 [Configure OAuth authentication for Alibaba Cloud CLI](https://www.alibabacloud.com/help/en/doc-detail/2995960.html) 和 `./references/installation-guide.md`。

通过环境变量提供凭证（自动化、CI/CD、无头，或 OAuth 不可用时）

export ALIBABA_CLOUD_ACCESS_KEY_ID=<key-id>

export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<key-secret>

export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

临时凭证（StsToken）—— 额外加：

export ALIBABA_CLOUD_SECURITY_TOKEN=<sts-token>

API 调用 + 本 Skill：用路径 A（ai-mode）或路径 B（ALIBABA_CLOUD_USER_AGENT）—— 不要同时用 —— 见「Agent 执行：AI-mode 与 User-Agent（本 Skill）」

验证

aliyun version # 应 >= 3.3.3

aliyun ecs describe-regions # 测试鉴权

Aliyun CLI 3.3.3+ 支持所有已发布的阿里云产品插件。较新命令（**3.3.5** 起的 `aliyun upgrade`、**3.3.8** 起的 `aliyun plugin show`）在本说明顶部的 **CLI 版本里程碑**中总结。

#### 鉴权模式（环境变量）

对于使用**显式密钥或 token**（非 OAuth）的模式，选择适合部署场景的。设置后，这些环境变量会覆盖 `~/.aliyun/config.json` 中的任何值。

| 模式 | 使用时机 | 环境变量 |
| ---- | ----------- | --------------------- |
| **AK** | 开发、长期凭证 | `ALIBABA_CLOUD_ACCESS_KEY_ID`、`ALIBABA_CLOUD_ACCESS_KEY_SECRET`、`ALIBABA_CLOUD_REGION_ID` |
| **StsToken** | CI/CD、临时凭证 | 同 AK，外加 `ALIBABA_CLOUD_SECURITY_TOKEN` |
| **RamRoleArn** | AssumeRole 后或跨账号会话 | 从角色会话导出临时对：与 **StsToken** 相同的变量（AK + secret + `ALIBABA_CLOUD_SECURITY_TOKEN`） |

#### 多账号或多环境

为每个 shell 会话、CI 作业或密钥存储使用独立的 `export` 块（不同的 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET` / `ALIBABA_CLOUD_REGION_ID` 值）。基于配置文件的 profile 工作流，见 `./references/installation-guide.md`。

### 2. 构造任何命令前先查阅 `--help`

内置命令在各 API 之间参数命名不一致——有些用 PascalCase，
另一些用 camelCase，确切名称不可预测。猜测参数名经常
导致需要多次重试的错误。先运行 `--help` 只需几秒：

aliyun <product> --help # 发现可用子命令

aliyun <product> <subcommand> --help # 获取确切参数名、类型、结构

帮助输出是权威来源。插件帮助尤其丰富——它包含每个参数的类型
信息、结构字段、格式提示和约束。

插件安装后，`aliyun <product> --help` 自动显示插件帮助。要查看
旧版内置（OpenAPI 风格）帮助：

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun ecs --help

### 3. 确保服务插件可用

每个阿里云产品都有 CLI 插件。插件提供一致的 kebab-case 命令
和全面的帮助，而旧版内置系统命名不一致且帮助极少。如果你知道要用哪个产品，直接安装插件——`plugin install` 是幂等的（即使已安装也安全）：

aliyun plugin install --names ecs # 安装（短名，不区分大小写）

aliyun plugin install --names ECS VPC RDS # 一次多个

发现或验证插件：

aliyun plugin list # 已安装插件

aliyun plugin list-remote # 所有可用插件

aliyun plugin search <keyword> # 按关键词搜索

aliyun plugin show --name ecs # Aliyun CLI >= 3.3.8 —— 单个已安装插件的详情

`plugin show` 需要 **Aliyun CLI >= 3.3.8**，且仅对**已安装**插件有效（用 `plugin list-remote` / `plugin search` 检查目录）。旧版本上，省略 `plugin show`，依赖 `plugin list` 加 `aliyun <product> --help`。

插件名同时接受短形式（`ecs`）和完整形式（`aliyun-cli-ecs`），不区分大小写。

插件生命周期：

aliyun plugin update --name ecs # 更新插件

aliyun plugin uninstall --name ecs # 移除插件

### 4. 优先使用插件命令而非内置命令

CLI 有两种命令风格，**子命令大小写**决定由哪个系统处理：

- **全小写子命令** → 路由到插件（CLI Native 风格）
- **含大写** → 路由到内置（OpenAPI 风格）

插件命令对子命令和参数都使用一致的 kebab-case 命名，使其可预测。内置命令使用 PascalCase 子命令，参数命名混合 / 不一致，因 API 而异——你必须为每条命令查 `--help` 才能知道确切名称。

插件（首选）：一致的 kebab-case

aliyun ecs describe-instances --biz-region-id cn-hangzhou

内置（兜底）：PascalCase 子命令，参数不一致

aliyun ecs DescribeInstances --RegionId cn-hangzhou

混用风格会导致静默失败——CLI 根据子命令大小写路由到不同后端。kebab-case 子命令配 PascalCase 参数会被送到插件系统，而插件系统不认识 PascalCase 参数名。

产品代码始终不区分大小写（`ecs`、`Ecs`、`ECS` 都可用）。

| 方面 | 插件（CLI Native） | 内置（OpenAPI） |
| ------ | ------------------- | ------------------ |
| 子命令 | `describe-instances` | `DescribeInstances` |
| 参数 | kebab-case（一致） | 混合（不一致） |
| ROA Body | 展开为单个参数 | 单个 `--body` JSON |
| Header 参数 | 帮助中可见，可直接使用 | 隐藏，仅手动 `--header` |
| 帮助 | 全面且带结构 | 基础 |

### 5. 理解全局参数与业务参数命名

CLI 插件系统为自身保留某些全局参数：

- `--region-id` / `--region` —— 控制请求发送到哪个 **API 端点**（例如
  `ecs.cn-hangzhou.aliyuncs.com`）。这是路由关注点，不是业务字段。
- 其他全局参数包括 `--profile`、`--api-version`、`--output` 等。

许多 API 也在 API spec 中定义自己的 `RegionId` 或 `Region` 参数——这些是
**业务参数**，有 API 特定含义（例如"在哪个地域创建此资源"）。
全局 `--region-id` 和 API 的 `RegionId` 用途不同，但在命令行上会冲突。

插件系统在代码生成时自动解决：

1. **`--biz-` 前缀（默认）**：API 参数 `RegionId` 变为 `--biz-region-id`
2. **`--<product>-` 前缀（兜底）**：如果 `--biz-region-id` 已被另一参数占用，
   插件回退到 `--<product>-region-id`（例如 `--ecs-region-id`）

这意味着在插件命令中，`--region-id` **始终**是全局端点选择器，
业务地域是 `--biz-region-id`（或 `--<product>-region-id`）。在本意是业务参数处
使用 `--region-id` 会静默改变端点而不设置预期字段。

始终查 `--help` 查看实际参数名——它是某命令使用 `--biz-region-id`、
`--<product>-region-id` 还是其他名称的权威来源。

### 6. 使用结构化参数语法

插件支持框架自动序列化的结构化输入。这避免了
易错的旧版 `--Tag.N.Key` / `--Param.N=value` 语法。

**原始类型和列表：**

--instance-id i-abc123 # 单值

--security-group-ids sg-001 sg-002 sg-003 # 空格分隔列表

--instance-id i-abc --instance-id i-def # 重复参数（也有效）

**键值对象和可重复结构：**

--tag Key=env Value=prod --tag Key=app Value=web # 可重复键值

--capacity-options OnDemandBaseCapacity=12 CompensateWithOnDemand=true # 对象

--data-disk '{"DiskName":"d1","Size":100}' # 复杂结构（JSON）

为每条命令查 `--help`——它显示确切类型、结构字段，以及参数是否可重复。

### 7. OSS 使用自定义命令

与其他产品不同，OSS 有手写实现和自定义命令语法。
API 风格命令如 `PutBucket` 或 `GetObject` 对 OSS 不存在——使用它们会静默失败
或产生令人困惑的错误。始终先查帮助：

aliyun oss --help # 基本操作（cp、ls、mb、rm 等）

aliyun ossutil --help # 高级工具（sync、stat 等）

以下各行**仅为语法示例**（`<your-*>` 占位符）。**不要逐字运行**——执行前替换为真实路径、bucket 名和文件名。

aliyun oss cp <your-file-name>.txt oss://<your-bucket-name>/ # 上传

aliyun oss mb oss://<your-bucket-name> # 创建 bucket

aliyun ossutil sync ./<your-folder-name>/ oss://<your-bucket-name>/ # 同步目录

### 8. 过滤和格式化输出

用 `--cli-query`（JMESPath）从 API 响应提取特定字段，用 `--output`
控制格式。这避免了将大 JSON blob 通过外部工具管道：

JMESPath 过滤：仅运行中实例，选定字段

aliyun ecs describe-instances \

--biz-region-id cn-hangzhou \

--cli-query "Instances.Instance[?Status=='Running'].{ID:InstanceId,Name:InstanceName}"

输出格式

aliyun ecs describe-instances --biz-region-id cn-hangzhou --output json # 默认

aliyun ecs describe-instances --biz-region-id cn-hangzhou --output table # 人类可读表格

aliyun ecs describe-instances --biz-region-id cn-hangzhou --output cols=InstanceId,InstanceName,Status rows="Instances.Instance[]" # 自定义列

### 9. 分页

许多 list 命令返回分页结果。用 `--page-number` 和 `--page-size` 控制：

aliyun ecs describe-instances \

--biz-region-id cn-hangzhou \

--page-number 1 \

--page-size 50

要无需手动循环自动获取所有页，用 `--pager`：

aliyun ecs describe-instances \

--biz-region-id cn-hangzhou \

--pager path='Instances.Instance[]' PageNumber=PageNumber PageSize=PageSize

`path` 参数指定哪个 JSON 字段包含要合并的页数据。

### 10. 等待资源状态

某些命令支持内置 waiter 用于自动化——轮询直到资源达到期望状态：

aliyun vpc describe-vpc-attribute \

--biz-region-id cn-shanghai \

--vpc-id <your-vpc-id> \

--waiter expr='Status' to='Available'

### 11. 调试

排查命令失败时，这些标志揭示底层发生了什么——完整 HTTP 请求 / 响应和参数校验详情：

- `--log-level debug` —— 详细请求 / 响应日志（显示端点、序列化参数、响应）
- `--cli-dry-run` —— 不执行即校验命令（检查参数解析）
- `ALIBABA_CLOUD_CLI_LOG_CONFIG=debug` —— 环境变量全局设置日志级别

对于 **403**、**Forbidden**、**NoPermission** 或其他 RAM 风格拒绝，凭证背后的身份缺少底层 API 动作的权限。见 `./references/ram-policies.md` 了解本 Skill 的 `required_permissions` 表、按需授权以及如何收窄权限。

### 12. 多版本 API 支持

某些产品（例如 ESS、SLB）提供多个 API 版本，命令集和能力不同。
使用错误版本可能导致参数缺失、行为废弃或命令可用性完全不同。
并非所有产品都有多版本——如果 `list-api-versions` 返回错误，产品是单版本，无需操作。

#### 发现版本

aliyun <product> list-api-versions

示例（ESS；`*` = 默认）：

• 2014-08-28 (default)

2022-02-22

每个版本可能暴露不同命令或参数名。

#### 逐命令指定版本

aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou

#### 通过环境变量设置默认版本

为避免每次调用都传 `--api-version`，为某产品设置默认值：

export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22

export ALIBABA_CLOUD_SLB_API_VERSION=2014-05-15

模式是 `ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION`（产品代码大写）。
这在脚本或 CI/CD 中尤其有用，可在多条命令间保持一致版本行为。

#### 查看特定版本的命令

不同 API 版本可能有不同命令集。查看可用内容：

aliyun ess --api-version 2022-02-22 # 列出此版本的命令

aliyun ess <cmd> --api-version 2022-02-22 --help # 此版本中特定命令的帮助

#### 何时指定版本

- **默认** —— 除非需要更新功能，否则足够。
- **`--help`** —— 缺失参数可能只存在于另一 API 版本。
- **脚本 / CI** —— 固定 `ALIBABA_CLOUD_<PRODUCT>_API_VERSION` 以保证可复现性。

全局标志参考

这些标志在所有插件命令上可用：

常见工作流

ECS 实例

aliyun plugin list | grep ecs

若缺失：aliyun plugin install --names ecs

aliyun ecs describe-instances --biz-region-id cn-hangzhou

下方 `create-instance` 示例**会创建计费资源**（固定镜像 ID、实例类型和磁盘仅作示意）。**不要逐字运行**——执行前按你的账号和策略调整地域、镜像、类型、磁盘、网络和标签。

aliyun ecs create-instance \

--biz-region-id cn-hangzhou \

--instance-type ecs.g7.large \

--image-id ubuntu_20_04_arm64_20G_alibase_20250625.vhd \

--data-disk Category=cloud_essd Size=100 \

--tag Key=env Value=prod --tag Key=app Value=web

### Function Compute（ROA Body 展开）

aliyun plugin list | grep fc

若缺失：aliyun plugin install --names fc

下方代码块是**语法示例**（`<your-function-name>` 和其他值仅作示意）。**不要逐字运行**——设置真实函数名、运行时、handler、内存、超时，并为你的环境添加任何必需的 VPC 或服务角色设置。插件命令将 ROA body 字段展开为单个参数（无需 `--body` JSON）。

aliyun fc create-function \

--function-name <your-function-name> \

--runtime python3.9 \

--handler index.handler \

--memory-size 512 \

--timeout 60 \

--description "Process uploaded images"

### 多版本 API（ESS）

检查可用版本

aliyun ess list-api-versions

使用最新版本以获取新功能

export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22

aliyun ess describe-scaling-groups --biz-region-id cn-hangzhou

或不设环境变量，逐命令指定

aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou

响应格式

提供 CLI 命令时：

1. 解释命令做什么以及为何使用特定参数
2. 展示带所有必需参数的完整命令
3. 点明不直观的值——尤其是 --biz- 前缀参数及其原因
4. 用户排查问题时建议 --log-level debug
5. 对于 API 归属，使用 AI-mode + set-user-agent 或 env/内联 ALIBABA_CLOUD_USER_AGENT，绝不为同一 skill token 同时用两者；Agent 应在每次退出时禁用 AI-mode，或在 export 后 unset（见 Agent 执行：AI-mode 与 User-Agent（本 Skill））

参考资料

• ./references/installation-guide.md —— 安装、配置模式、凭证设置
• ./references/command-syntax.md —— 完整命令语法指南
• ./references/global-flags.md —— 全局标志参考
• ./references/ram-policies.md —— 按需 RAM、最小权限、常见权限错误