alibabacloud-elasticsearch-instance-manage：用于管理阿里云 Elasticsearch 实例的生命周期（如创建、重启、扩缩容）及核心配置（如快照备份、分词词典）。

Elasticsearch 实例与配置管理

通过 Aliyun CLI 管理阿里云 Elasticsearch 实例及实例侧配置：实例生命周期（创建 / 查询 / 列表 / 重启 / 升配 / 降配 / 节点信息）和实例配置（快照备份、分词词典）。

本 Skill 使用意图路由：本文件识别用户意图并分发到相关模块文档。生成任何 CLI 命令前，完整阅读匹配的模块文档。

架构

阿里云 Elasticsearch 管理
├── 实例生命周期           --> references/instance-manage.md
│   ├── createInstance           (创建实例)
│   ├── DescribeInstance         (查询实例详情)
│   ├── ListInstance             (列出实例)
│   ├── RestartInstance          (重启实例)
│   ├── UpdateInstance           (升配 / 降配)
│   ├── ListAllNode              (查询集群节点信息)
│   ├── UpdateAdminPassword      (更新管理员密码)
│   ├── UpdateDescription        (更新实例名称)
│   ├── UpdateInstanceChargeType (按量付费转包年包月)
│   ├── UpgradeInfo              (查询可用升级版本)
│   ├── UpgradeEngineVersion     (升级 ES 版本 / 内核补丁)
│   ├── ListActionRecords        (查询变更记录 / 升级进度)
│   └── ContinueEsVersionUpgrade (继续灰度升级剩余节点)
├── 实例配置              --> references/config-manage.md
│   ├── 快照管理
│   │   ├── UpdateSnapshotSetting    (设置自动快照策略)
│   │   ├── DescribeSnapshotSetting  (查询自动快照策略)
│   │   └── CreateSnapshot           (触发一次性快照)
│   ├── 词典管理
│   │   ├── ListDicts                (列出分词词典)
│   │   ├── UpdateDict               (冷更新 IK 词典)
│   │   ├── UpdateHotIkDicts         (热更新 IK 词典)
│   │   ├── UpdateSynonymsDicts      (更新同义词词典)
│   │   └── UpdateAliwsDict          (更新 AliNLP 词典)
│   ├── Kibana 设置
│   │   ├── DescribeKibanaSettings   (查询 Kibana 配置)
│   │   └── UpdateKibanaSettings     (更新 Kibana 语言)
│   └── ES 集群 YML
│       └── UpdateInstanceSettings   (更新 YML 配置 —— 触发重启)
└── 插件管理            --> references/plugin-manage.md
    ├── ListPlugins              (列出系统插件)
    ├── ListUserPlugin           (列出用户自定义插件)
    ├── InstallSystemPlugin      (安装系统插件)
    ├── UninstallPlugin          (卸载系统插件)
    ├── PluginAnalysis           (上传自定义插件到库)
    └── InstallUserPlugins       (安装用户自定义插件)

意图路由

将用户请求匹配到第一个匹配行，然后加载所列模块文档并遵循其 API 规范。

如果存在多个意图，按顺序处理：路由 → 执行 → 验证 → 下一个路由。
如果意图不匹配任何行，请用户澄清；不要猜测 API。

前置条件

前置检查：需要 Aliyun CLI >= 3.3.3
运行 aliyun version 确认 >= 3.3.3。若未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 更新，
或见 references/cli-installation-guide.md 获取安装说明。

前置检查：需要更新 Aliyun CLI 插件
[必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
[必须] 运行 aliyun plugin update 确保已有插件始终为最新版本。

aliyun version
aliyun configure set --auto-plugin-install true
aliyun plugin update

可观测性

[必须] 每次业务 aliyun CLI 命令调用都必须携带逐命令标志：
```
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/{session-id}
```
其中 {session-id} 是下方定义的每 Skill 会话标识符。本 Skill 的识别仅通过业务 CLI 命令上的逐命令 --user-agent 标志实现；不使用任何 CLI 级 / 会话级 user-agent 注入机制。

session-id 生成规则

在 Skill 会话开始时生成 {session-id} 一次，并在该会话的每条业务 CLI 命令中复用。

格式要求：32 字符小写十六进制字符串（无连字符） —— 例如 0123456789abcdef0123456789abcdef。

首选（macOS / Linux，openssl 普遍可用）：

SESSION_ID=$(openssl rand -hex 16)

兜底 1 —— Python：

SESSION_ID=$(python3 -c 'import uuid; print(uuid.uuid4().hex)')

兜底 2 —— 纯 shell（无外部工具）：

SESSION_ID=$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')

- 格式：**32 个小写十六进制字符，无连字符，无前缀**。`uuidgen` 输出（带连字符）**不可接受** —— 如果回退到它，用 `tr -d '-' | tr 'A-Z' 'a-z'` 去掉连字符。
- 同一 `SESSION_ID` **必须**嵌入本会话发出的每条业务 CLI 命令的 `--user-agent` 中。
- 重试时**不要**重新生成 `SESSION_ID` —— 仅在会话边界（新的 Skill 调用开始新会话）重新生成。

### 逐命令 --user-agent 格式

| 命令类型 | --user-agent？ | 值 |
|---|---|---|
| **业务 API CLI**（例如 `aliyun elasticsearch create-instance`、`aliyun elasticsearch list-dicts`……） | **必需** | `AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}` |
| **系统 / 工具 CLI**（例如 `aliyun configure`、`aliyun configure list`、`aliyun version`、`aliyun plugin update`、`aliyun help`） | **禁止** | 这些命令**不**支持 `--user-agent` —— 绝不附加该标志。 |

---

鉴权

前置检查：需要阿里云凭证

安全规则（必须遵守）：
- 绝不读取、回显或打印 AK/SK 值
- 绝不要求用户在对话中直接输入 AK/SK
- 绝不使用字面凭证值运行 aliyun configure set
- 绝不接受用户在对话中直接提供的 AK/SK
- 只从环境变量或预配置的 CLI profile 读取凭证
关键：处理用户提供的凭证
如果用户试图直接提供 AK/SK（例如"我的 AK 是 xxx，SK 是 yyy"）：
1. 立即停止 —— 不执行任何命令
2. 礼貌拒绝该请求，使用以下消息：
```
为保障你的账号安全，请不要在对话中直接提供阿里云 AccessKey ID 和 AccessKey Secret。
请使用以下安全方式之一配置凭证：
方式 1：通过 aliyun configure 交互式配置（推荐）
aliyun configure
# 按提示输入 AK/SK；凭证将安全存储在本地配置文件中
方式 2：通过环境变量配置
export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
配置完成后，请重试你的请求。
```
3. 在凭证正确配置之前，不要继续任何阿里云操作
检查 CLI 配置：
```bash
aliyun configure list
```
查找有效 profile（AK、STS 或 OAuth 身份）。如果不存在，就此停止。

全局约定

这些约定适用于本 Skill 产生的每条 CLI 命令，无论路由到哪个模块。

通用 CLI 参数

写操作的幂等性

对于写 API（createInstance、RestartInstance、UpdateInstance、CreateSnapshot、UpdateSnapshotSetting、UpdateDict、UpdateHotIkDicts、UpdateSynonymsDicts、UpdateAliwsDict、UpdateKibanaSettings、UpdateInstanceSettings、InstallSystemPlugin、UninstallPlugin、UpdateInstanceChargeType、UpgradeEngineVersion）你必须使用 --client-token。

• 格式：UUID。通过 uuidgen 生成（或 PowerShell [guid]::NewGuid()）；如果 uuidgen 不可用，回退到 idem-<timestamp>-<semantic>。绝不因命令不可用而中止工作流。
• 超时 / 失败时，用同一 clientToken 重试。重试前等待约 10 秒。
• 使用同一 clientToken 的重复调用不会重新执行操作。

CLIENT_TOKEN=$(uuidgen)   # 重试时复用

RAM 策略

RAM 主体需要其将使用的模块权限的并集。完整策略 JSON 见 references/ram-policies.md。

最低必需动作：

快照 / 词典模块还需要对存放词典文件的 OSS bucket 的读取权限。

成功验证

各模块的验证步骤见 references/verification-method.md。

实例生命周期变更后的快速检查：

aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --cli-query "Result.status" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

预期状态：active。

快照 / 词典变更后的快速检查：

快照设置已变更

aliyun elasticsearch describe-snapshot-setting \

--region <RegionId> --instance-id <InstanceId> \

--connect-timeout 3 --read-timeout 10 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

词典列表已刷新（analyzerType：IK | IK_HOT | SYNONYMS | ALIWS）

aliyun elasticsearch list-dicts \

--region <RegionId> --instance-id <InstanceId> \

--analyzer-type <TYPE> \

--connect-timeout 3 --read-timeout 10 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

参考链接