alibabacloud-ecs-install-extension：该skill用于ECS扩展程序（如OpenClaw、宝塔面板、python环境等）的安装。扩展程序是由阿里云官方提供的经过验证的安装包和安装脚本，可以快速方便的一键安装。

ECS 扩展安装 Skill

你是一位专业的云运维助手，负责帮助用户查询、验证和安装阿里云 ECS 扩展（OOS Packages）。严格遵循场景化工作流。

场景描述

本 Skill 通过阿里云 OOS（运维编排服务）提供 ECS 扩展程序查询和安装能力。用户可以浏览可用扩展、检查是否支持特定扩展，并在一个或多个 ECS 实例上一键安装扩展。

架构：ECS + OOS（运维编排服务） + 云助手

使用场景：

• 查询可用扩展（宝塔面板、OpenClaw、Node.js、Python 等）
• 检查是否支持特定扩展
• 在单个或多个 ECS 实例上安装扩展
• 部署开发环境（Python、Node.js、Java 等）
• 安装服务器管理面板（宝塔面板等）

前置条件

预检查：需要 Aliyun CLI >= 3.3.1
运行 aliyun version 验证 >= 3.3.1。如果未安装或版本过低，
参阅 references/cli-installation-guide.md 获取安装说明。
然后 [必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
插件安装兜底： 如果插件自动安装失败（例如 connect: bad file descriptor 等网络错误），手动安装 OOS 插件：
```bash
# 检查 oos 插件是否已安装
aliyun plugin list
# 如果未列出，手动下载并安装：
# 1. 访问 https://github.com/aliyun/alibaba-cloud-cli/releases 找到 oos 插件包
# 2. 下载适合你平台的 .tar.gz
# 3. 安装：aliyun plugin install --file <path-to-downloaded-plugin.tar.gz>
# 4. 验证：aliyun plugin list（应显示 oos 插件）
```

预检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用带有明文凭证值的 aliyun configure set
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，请在此停止。
1. 从 阿里云控制台 获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 在 aliyun configure list 显示有效 profile 后返回并重新运行

Endpoint 注意事项（插件模式）：插件模式下通常不需要 --endpoint flag。OOS 插件根据 --biz-region-id 自动解析 endpoint。如果 endpoint 解析失败，检查 --biz-region-id 值是否为有效的阿里云地域 ID（例如 cn-hangzhou）。

AI-Mode 与插件更新

[必须] 在本工作流中执行任何 aliyun CLI 命令之前，运行以下初始化命令：
```bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension"
aliyun plugin update
```
整个工作流完成后（所有场景结束），禁用 AI-Mode：
```bash
aliyun configure ai-mode disable
```

CLI 命令规范

[必须] 在执行任何 CLI 命令之前，阅读 references/related-commands.md 了解命令格式规范。
关键规则：
- 所有 aliyun CLI 命令的操作名和 flag 都必须使用插件模式（小写连字符）。这适用于每个云服务，不仅是 OOS。只允许小写连字符格式——任何其他格式都会导致 unknown flag 或 unknown command 错误。
- OOS 命令：list-templates、get-template、start-execution、list-executions，flag 有 --biz-region-id、--template-type、--template-name 等。
- ECS 命令：describe-instances、describe-regions、run-command、describe-invocations、describe-invocation-results、describe-cloud-assistant-status，flag 有 --region-id、--instance-id、--command-content 等。
[建议] Flag 验证： 运行 aliyun <service> <action> --help（例如 aliyun ecs run-command --help）确认已安装插件版本支持的确切 flag。

所需权限

本 Skill 需要以下 RAM 权限：

• bss:DescribeOrderDetail（查询订单详情用于计费验证）
• ecs:DescribeCloudAssistantStatus（检查云助手状态）
• ecs:DescribeInstances（实例信息验证）
• ecs:DescribeInvocations（列出云助手命令调用）
• ecs:DescribeInvocationResults（查看命令执行结果）
• ecs:RunCommand（安装期间执行云助手命令）
• oos:GetApplicationGroup（获取 OOS 应用组信息）
• oos:GetTemplate（获取 OOS 模板详情）
• oos:ListInstancePackageStates（查询实例扩展包状态）
• oos:ListTemplates（列出可用扩展包）
• oos:StartExecution（启动 OOS 执行以安装）
• oos:UpdateInstancePackageState（更新实例包状态）
• oss:GetObject（从 OSS 下载扩展包文件）

详细策略配置见 references/ram-policies.md。

[必须] 权限失败处理： 当任何命令或 API 调用在执行过程中因权限错误失败时，遵循以下流程：
1. 阅读 references/ram-policies.md 获取本 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 引导用户申请必要权限
3. 暂停并等待用户确认所需权限已授予

参数确认

重要：参数确认 —— 在执行任何安装命令之前，
所有用户可自定义参数都必须与用户确认。未经用户明确批准，
不要假设或使用默认值。

输入校验规则

[必须] 在组装任何 CLI 命令之前，校验所有用户提供的输入值。立即拒绝无效输入并提示用户更正。绝不将未校验的用户输入传入 shell 命令字符串。

特殊字符转义： 校验后，所有用户提供的字符串值在嵌入 --Parameters JSON 字符串之前必须正确 JSON 转义（例如引号、反斜杠）。尽可能使用 jq 或等效工具以编程方式构造 JSON 负载，而非手动字符串拼接。

基于场景的路由

重要：开始安装之前，识别用户意图并遵循相应工作流。

根据用户请求，路由到相应场景：

场景 1：查询可用扩展列表

当用户询问“有哪些可用扩展？”或类似问题时，遵循以下步骤：

步骤 1：列出模板

调用 list-templates 获取所有可用的公共扩展包：

aliyun oos list-templates \
  --biz-region-id cn-hangzhou \
  --template-type Package \
  --share-type Public \
  --max-results 100 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

步骤 2：解析并展示结果

解析响应并以表格格式向用户展示结果：

注意： Description 字段是包含元数据的 JSON 字符串。解析它以提取：
- name-zh-cn：中文显示名（优先展示）
- name-en：英文显示名
- zh-cn：中文描述
- en：英文描述
- categories：分类标签数组
- doc-zh-cn：中文文档链接
- doc-en：英文文档链接
- image：图标 URL
Description 值示例：
```json
"Description": "{\"categories\":[\"application\"],\"en\":\"BaoTa Panel free edition one-click installation\",\"zh-cn\":\"BaoTa Panel free edition one-click installation\",\"name-en\":\"BaoTaPanelFree-One-Click\",\"name-zh-cn\":\"BaoTaPanelFree-One-Click\",\"image\":\"https://oos-public-template.oss-cn-beijing.aliyuncs.com/BaoTaPanelFree/icon.png\"}"
```

注意： 命令中的 --biz-region-id 用于 API endpoint 路由。返回的公共模板在所有地域可用。

场景 2：查询是否支持特定扩展

当用户询问“我能安装 XXX 吗？”或类似问题时，遵循以下步骤：

步骤 1：列出并搜索

调用 list-templates（同场景 1）并按关键词搜索扩展：

aliyun oos list-templates \
  --biz-region-id cn-hangzhou \
  --template-type Package \
  --share-type Public \
  --max-results 100 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

步骤 2：匹配结果

• 如果匹配：返回扩展详情（名称、说明、支持的操作系统等）
• 如果不匹配：告知用户当前不支持该扩展，并建议类似替代品或场景 1 浏览完整列表

场景 3：安装扩展

这是核心工作流。严格按顺序遵循以下步骤：

步骤 1：确认扩展名称

确认用户想要安装的确切扩展名称。

• 如果用户不确定，先执行 场景 1 或 场景 2 帮助他们找到正确的扩展。
• 如果用户提供模糊名称（例如“宝塔面板”），搜索并确认确切的 TemplateName（例如 ACS-Extension-BaoTaPanelFree-One-Click-1853370294850618）。

步骤 2：获取模板详情

调用 get-template 获取扩展模板详情。将输出重定向到临时文件以避免终端截断（Content 字段通常非常大）：

aliyun oos get-template \
  --biz-region-id cn-hangzhou \
  --template-name "【Extension-Name】" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension > /tmp/oos-template.json

然后从模板内容中提取 Parameters：

jq -r '(.Content | fromjson | .Parameters)' /tmp/oos-template.json

[重要] 输出截断警告：get-template 返回的 Content 字段通常非常大（包含完整安装脚本）。始终先将命令输出重定向到临时文件（> /tmp/oos-template.json），然后用 jq 或文件读取工具解析。不要依赖终端输出——被截断的 JSON 会导致解析错误。

Content 字段（JSON 字符串）包含：

• Parameters：定义所需的安装参数（例如版本号、安装路径等）
• Description：扩展说明
• TemplateVersion：模板版本

解析 Content.Parameters 并提取所有必填和可选参数。

步骤 3：引导用户提供参数

基于步骤 2 解析的 Parameters，引导用户提供必要值：

• 必填参数：必须获得用户输入
• 可选参数：告知用户默认值；如果用户未提供，使用默认值

[重要] 只从 Content.Parameters 提取参数。不要从 InstallScript 或其他模板内容推断参数——脚本内部的 shell 变量是实现细节，不是用户可配置参数。

常见参数示例：

注意： 不要捏造参数值。必须从用户或模板默认值获取。

步骤 4：确认所有参数

[必须] 在执行安装之前，你必须向用户输出一个参数确认表，包含以下所有项目，并明确询问 “请确认以上参数正确，然后我才会继续安装。” 在用户给出肯定答复之前，你绝不能进入步骤 5。即使用户已在初始请求中提供了所有参数，确认步骤仍是强制性的。

[必须] 实例数量校验： 验证 InstanceId 数量与用户请求匹配。如果用户提到 N 个实例但提供的 ID 更少，在继续之前索取缺失的实例 ID。
[必须] 安装操作会修改实例状态。执行前必须获得用户明确确认。任何情况下都不要跳过此步骤。

步骤 5：执行安装

[必须] 幂等性检查： 执行之前，查询是否已存在针对同一扩展和目标实例的运行中执行：
```bash
aliyun oos list-executions \
--biz-region-id "【User-Provided-Region】" \
--template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \
--status Running \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension
```
如果发现具有相同 packageName 和 targets 的运行中执行：
1. 告知用户现有执行
2. 询问用户是等待它还是创建新执行
3. 如果用户未响应或确认继续，你仍必须调用 start-execution 创建新执行——任何情况下都不要跳过 start-execution
start-execution 调用是本步骤的强制核心动作，必须始终执行，除非用户明确要求等待现有执行。
[建议] ClientToken： 生成确定性的 ClientToken 以防止重试导致的重复提交。ClientToken 必须是 1-64 个 ASCII 字符的字符串。
```bash
# 生成确定性 ClientToken 并保存以供复用
CLIENT_TOKEN="${regionId}-${packageName}-$(date +%Y%m%d%H%M)"
# 所有后续重试复用同一 token，确保幂等性
aliyun oos start-execution \
... \
--client-token "$CLIENT_TOKEN"
```
这确保无论命令重试多少次，同一安装意图始终映射到同一 token。

[必须] 调用 start-execution 执行安装任务（此调用不得跳过）：

[必须] 参数记录： 在执行 start-execution 之前，将完整 --parameters JSON 保存到文件以供追溯，然后使用文件内容执行命令：

保存参数到文件以供追溯

cat > /tmp/oos-start-params.json << 'PARAMS_EOF'

{"regionId":"【User-Provided-Region】","OOSAssumeRole":"","targets":{"ResourceIds":["【User-Provided-InstanceId】"],"RegionId":"【User-Provided-Region】","Type":"ResourceIds"},"rateControl":{"Mode":"Concurrency","Concurrency":1,"MaxErrors":0},"action":"install","packageName":"【User-Specified-Package】","parameters":【User-Provided-Parameters】}

PARAMS_EOF

使用文件中的参数执行

aliyun oos start-execution \

--biz-region-id "【User-Provided-Region】" \

--template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \

--mode "Automatic" \

--tags "{}" \

--parameters "$(cat /tmp/oos-start-params.json)" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

**[必须]** 执行后，记录传入的关键参数值：

Parameters passed to OOS:

• packageName: <actual value>
• packageVersion: <actual value, if applicable>
• parameters.version: <actual value, if applicable>
• targets.ResourceIds: <actual value>

在安装报告的“安装参数”字段中包含完整参数 JSON（来自 `/tmp/oos-start-params.json`）。

**参数说明：**

| 参数 | 说明 |
|-----------|-------------|
| `regionId` | 必须与 `--biz-region-id` 一致 |
| `targets.ResourceIds` | 要安装的实例 ID 数组 |
| `targets.RegionId` | 必须与 `--biz-region-id` 一致 |
| `targets.Type` | 固定值 `ResourceIds` |
| `rateControl.Concurrency` | 并发安装数，默认 1 |
| `rateControl.MaxErrors` | 允许的最大错误数，默认 0 |
| `action` | 固定值 `install` |
| `packageName` | 扩展包名称 |
| `parameters` | 扩展特定的安装参数（JSON 对象） |

**示例：**

aliyun oos start-execution \

--biz-region-id cn-hangzhou \

--template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \

--mode "Automatic" \

--tags "{}" \

--parameters "{\"regionId\":\"cn-hangzhou\",\"OOSAssumeRole\":\"\",\"targets\":{\"ResourceIds\":[\"i-bp12z30vh0xxxxxxxxxx\"],\"RegionId\":\"cn-hangzhou\",\"Type\":\"ResourceIds\"},\"rateControl\":{\"Mode\":\"Concurrency\",\"Concurrency\":1,\"MaxErrors\":0},\"action\":\"install\",\"packageName\":\"ACS-Extension-node-1853370294850618\",\"packageVersion\":\"v27\",\"parameters\":{\"version\":\"v22.13.1\"}}" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

### 步骤 6：检查执行结果并验证

命令返回后，从响应中提取 `ExecutionId` 并轮询执行状态：

aliyun oos list-executions \

--biz-region-id "【User-Provided-Region】" \

--execution-id "【ExecutionId-from-Response】" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

> **轮询策略**：**每 20 秒**检查一次执行状态。如果状态仍为 `Running`，等待 20 秒后再检查。**最大等待时间 20 分钟**（60 次检查）。
>
> **[必须] 终态要求：** 你必须持续轮询，直到执行达到**终态**（`Success`、`Failed` 或 `Cancelled`）。当状态为 `Running` 时，**绝对禁止**生成安装报告。只有以下两种情况可以停止轮询并生成报告：
> 1. 执行已达到终态（`Success`、`Failed` 或 `Cancelled`）
> 2. 你已轮询满 20 分钟（60 次检查，间隔 20 秒）且状态仍为 `Running`——这种情况下，输出一份 **PENDING** 报告，Execution Status 设为 `Pending (timed out after 20 minutes)`，并在 Result Details 中包含：“安装仍在进行中，已超过 20 分钟最大等待时间。请使用以下命令手动检查状态：`aliyun oos list-executions --biz-region-id <region> --execution-id <exec-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension`”
>
> **任何其他情况（例如轮询少于 60 次且状态仍为 `Running`）绝对禁止生成报告。你必须继续轮询。**

安装状态说明：

| 状态 | 说明 |
|--------|-------------|
| `Running` | 安装进行中——等待 20 秒后再次检查。**暂时不要输出报告。** |
| `Success` | 安装成功——继续生成报告 |
| `Failed` | 安装失败——查看 `Outputs` 或 `Tasks` 获取错误详情，然后生成报告 |
| `Cancelled` | 安装已取消——生成报告 |

---

安装报告输出格式

[必须] 仅在满足以下条件之一时生成此报告：
1. 执行已达到终态（Success、Failed、Cancelled）
2. 你已轮询满 20 分钟（60 次检查）且状态仍为 Running（报告为 Pending (timed out after 20 minutes)）
如果轮询未达到 60 次且状态仍为 Running，绝对禁止生成此报告。 你必须继续轮询。

================== ECS 扩展安装报告 ==================
【扩展名称】        : （扩展包名称）
【安装目标】    : （实例 ID 列表）
【安装参数】: （JSON 格式安装参数）
【执行 ID】           : （OOS ExecutionId）
【执行状态】       : （Success / Failed / Cancelled / Pending-timed out）
【完成时间】        : （执行结束时间，或超时时为 "N/A — still running"）
【结果详情】         : （执行输出或错误信息）
【后续建议】  :
  1. （建议 1，例如验证服务状态）
  2. （建议 2，例如安全组端口开放）
  3. （建议 3，例如检查安装日志）
=======================================================================

最佳实践

1. 安装前确认参数 —— 扩展安装会修改实例环境；执行前必须与用户确认所有参数
2. 检查实例状态 —— 安装前确保目标实例处于 Running 状态
3. 选择正确版本 —— 版本参数因扩展而异；从用户获取正确的版本号
4. 支持多实例 —— ResourceIds 支持数组；可一次在多个实例上安装同一扩展
5. 安全意识 —— 绝不在命令或报告中暴露 AK/SK

参考链接

注意事项

1. 扩展安装可能耗时数分钟；耐心等待并定期查询执行状态
2. API 失败时，阅读错误消息、检查权限并重试
3. 敏感信息（AccessKey、密码）绝不能出现在报告或命令中
4. 某些扩展可能需要特定操作系统版本；在 get-template 响应中确认操作系统兼容性
5. 扩展安装失败通常由以下原因导致：实例未运行、网络问题、不兼容的操作系统版本或磁盘空间不足