alibabacloud-lindorm-agent-skill：阿里云 Lindorm 数据库助手。支持实例查询管理、监控数据分析、性能诊断、存储分析、连接问题排查、代码编写（连接代码、建表语句、SQL 开发等）。覆盖包括 Lindorm SQL、宽表引擎、时序引擎、搜索引擎、HBase 兼容等多模场景。

Lindorm Agent Skill

阿里云 Lindorm 云原生多模数据库 Skill。覆盖三大领域：运维管理、开发指导和参考资料。开发指导包括经典 SQL / 搜索用法，以及向量检索、Lindorm AI 引擎调用、多模态图文搜索和私有知识库搜索。

核心能力矩阵

决策树

用户请求
├── 连接 / DDL / SQL / 代码示例 → 01-dev
│   ├── 连接地址 / 代码 → references/01-dev/connection-guide.md
│   ├── DDL / 写入 / 查询示例 → references/01-dev/quick-start-guide.md
│   ├── SQL 连接与基于 SQL 的应用开发 → references/01-dev/sql-client-guide.md
│   ├── SQL 语法参考 → references/01-dev/sql-operations.md
│   ├── MySQL 兼容性 → references/01-dev/sql-usage-notes.md
│   ├── 表设计指南 → references/01-dev/table-design.md
│   ├── 搜索引擎独立用法 → references/01-dev/search-guide.md
│   ├── 通过搜索 / 宽表使用向量引擎 → references/01-dev/vector-guide.md
│   ├── 图引擎用法（Gremlin / Schema / 查询）→ references/01-dev/graph-guide.md
│   ├── Lindorm AI 引擎模型调用 → references/01-dev/ai-guide.md
│   ├── 多模态图文搜索场景 → references/01-dev/multimodal-search-scene.md
│   └── 知识库搜索 / 私有问答场景 → references/01-dev/knowledge-search-scene.md
│
├── 实例 / 监控 / 错误 / 性能 / 存储 / 连接 / 扩缩容 / 备份 / 迁移 / 权限 / 慢查询 → 02-ops
│   ├── 实例查询（列表 / 详情 / 引擎 / 存储）→ references/02-ops/instance-management.md
│   ├── 实例写操作（创建 / 扩缩容 / 释放 / 付费类型）→ references/02-ops/instance-lifecycle.md
│   ├── IP 白名单 / ECS 安全组 → references/02-ops/network-access-control.md
│   ├── 监控 / 告警 → references/02-ops/monitoring-guide.md
│   ├── 错误码 → references/02-ops/error-troubleshoot.md
│   ├── 存储分析 → references/02-ops/storage-analysis.md
│   ├── 连接诊断 → references/02-ops/connection-troubleshoot.md
│   ├── 升配 / 降配 → references/02-ops/instance-lifecycle.md
│   ├── 备份与恢复 → references/02-ops/backup-restore.md
│   ├── 数据迁移 → references/02-ops/data-migration.md
│   ├── 账号与权限 → references/02-ops/user-permission.md
│   └── 慢查询分析 → references/02-ops/slow-query-analysis.md
│
└── 命令列表 / 权限参考 / CLI 工具 / SQL 执行 → 03-ref
    ├── Aliyun CLI 命令列表 + 地域规则 + 返回结构（`aliyun lindorm ...`）→ references/03-ref/related-commands.md
    ├── Lindorm CLI —— SQL 客户端，执行 SQL（`lindorm-cli`）→ references/03-ref/lindorm-cli-guide.md
    ├── HBase Shell（alihbase）→ references/03-ref/hbase-shell-guide.md
    ├── RAM 权限列表 → references/03-ref/ram-policies.md
    ├── Aliyun CLI 配置 → references/03-ref/cli-installation-guide.md
    ├── 验收标准 → references/03-ref/acceptance-criteria.md
    └── 验证方法 → references/03-ref/verification-method.md

快速映射表

Aliyun CLI

前置条件

需要 CLI 调用时，Agent 必须验证：

1. CLI 已安装：aliyun version >= 3.4.1 —— aliyun lindorm 子命令从 3.4.1 起才可用。在旧版 CLI 上，每次 aliyun lindorm ... 调用都会因未知命令失败，因此在假设命令损坏之前先检查版本。如果 CLI 缺失或过旧，见 references/03-ref/cli-installation-guide.md。lindorm 插件本身由下方 AI-Mode 步骤引入（aliyun configure set --auto-plugin-install true + aliyun plugin update）；用 aliyun lindorm --version 确认。
2. 凭证已配置：

> 安全规则：
> - 绝不读取、回显或打印 AK/SK 值
> - 绝不要求用户在对话或命令行中直接输入 AK/SK
> - 只使用 aliyun configure list 检查凭证状态
>
> 如果不存在有效 profile，停止。在本会话之外配置凭证。

1. 权限已授予：最低 AliyunLindormReadOnlyAccess + AliyunCloudMonitorReadOnlyAccess

> [必须] 权限失败处理： 当任何命令或 API 调用在执行过程中因权限错误失败时，遵循以下流程：
> 1. 阅读 references/03-ref/ram-policies.md 获取本 Skill 所需的完整权限列表
> 2. 如果 ram-permission-diagnose skill 可用，用它引导用户申请权限。否则，直接输出所需 RAM 策略 / 动作列表、错误码，以及用户通过 RAM 控制台 向管理员申请权限的分步说明
> 3. 暂停并等待用户确认所需权限已授予

可观测性（每条 aliyun 命令都必须遵守）

加载本 Skill 时，为整个会话生成一次新的随机 session ID（32 字符小写十六进制字符串），并在下方用作 {session-id}。session ID 必须每个会话新生成：不要复用下方示例值或任何上一会话的 session ID。
从 references/manifest.json 的 version 字段读取 Skill 版本，并在下方用作 {skill-version}。
规则：每条调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。
本地工具命令（如 configure、plugin、version）不支持该标志，应排除。
```
--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-lindorm-agent-skill/{session-id} skill-version/{skill-version}"
```
示例（假设 session-id 为 a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6，skill-version 为 0.0.3）：
```bash
aliyun lindorm v1 instance describe ld-xxx --lindorm-region cn-shanghai \
--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-lindorm-agent-skill/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 skill-version/0.0.3"
```
在任何 aliyun API 命令调用上，都不要跳过、改变格式或省略 --user-agent。

参数确认

执行任何命令前，所有用户可配置参数（地域、实例 ID、时间范围等）必须与用户确认。

版本检测

对于实例操作，Agent 必须先确定实例架构，因为 V1 和 V2 使用不同子命令。优先用 aliyun lindorm instance list：它返回该地域所有实例，带 arch（v1 / v2）和 service_type 列，因此一次调用即可解析架构而无需猜测：

aliyun lindorm instance list --lindorm-region cn-shanghai --output json

对于单个已知实例，aliyun lindorm v1 instance describe <id> 也会为两种架构返回 service_type —— 底层 GetLindormInstance 动作是共享的，尽管命令路径为 v1。

service_type 到架构的映射如下：

通用策略

地域策略

⚠️ [必须] 在 aliyun lindorm 下，以 --lindorm-region 传地域，绝不用 --region。 --region 是父 aliyun CLI 的全局标志，会在插件看到之前被消费。命令仍会成功，但查询的是 profile 的地域而非你要求的地域——这是错误答案陷阱，而非错误。插件确实会向 stderr 发出警告，Agent 不得忽略：
```
note: using region cn-shenzhen (from profile/environment). '--region' is consumed by the aliyun CLI
and never reaches this plugin — use '--lindorm-region <region>' to override.
```
同样适用于 --profile，其插件侧等价物是 --lindorm-profile。来自 aliyun lindorm --help：
```
--lindorm-region string Same as --region; use this under 'aliyun lindorm', where --region is consumed by the aliyun CLI
--lindorm-profile string Same as --profile; use this under 'aliyun lindorm', where --profile is consumed by the aliyun CLI
```
未给 --lindorm-region 时，地域来自当前 profile。始终显式传 --lindorm-region，并在告诉用户结果描述哪个地域之前验证输出中的 region_id。
例外：profile create --region <region> 是该子命令的命令本地标志，按原样工作。

当用户报告某地域范围查询静默返回了另一地域的数据（无错误，region_id 错误）时，诊断为这个标志陷阱——绝不要诊断为 RAM / 权限（Forbidden）问题。说明根因（--region 被父 CLI 消费）和修复方式（--lindorm-region）。

⚠️ summary 会少报——不要将其用作清单。 观察到它返回自洽的 total，而个别地域被少计或完全缺失（例如某地域报告为 9 个实例，而该地域的 instance list --lindorm-region 返回 11 个）。仅将其视为快速总览；要获得准确计数，用 regions list 然后逐地域 instance list --lindorm-region <region>。

时间格式

云监控时间参数时区说明：

• ✅ 2026-04-14 08:00:00（本地时间，按 CST 北京时间解析）
• ✅ 1773897600000（Unix 毫秒时间戳，无时区歧义）
• ✅ 2026-04-14T08:00:00Z（ISO 8601 UTC 完整格式，按 UTC 解析，即 CST+8 = 16:00）
• ❌ 2026-04-14T08:00Z（ISO 8601 短格式，无秒——不支持，返回 parse param time error）
• ❌ 绝不要对用户意图的本地时间使用 UTC Z 格式（例如用户说"14:00"，写 2026-04-14 14:00:00，而非 2026-04-14T14:00:00Z）
• ⚠️ 注意：本地时间和 ISO 8601 Z 格式查询不同的时间窗口——时区相关问题的常见来源

命令参考

#### 查询（只读，无计费影响）

#### 变更（计费 / 破坏性——除非 --yes 否则请求确认）

aliyun lindorm instance ... 是 aliyun lindorm v2 instance ... 的别名。
⚠️ **在 aliyun lindorm 下，使用 --lindorm-region / --lindorm-profile，绝不用 --region /
--profile** —— 后者是 aliyun CLI 的全局标志，CLI 自行解析且不转发给插件，因此被静默忽略（退出码 0，使用了错误地域）。
这些别名在独立二进制上也有效，因此一种拼写覆盖两种模式。
需要插件 v0.2.20+。
每个子命令上可用的其他标志：--aliyun-profile / --output table|json|yaml（-o）/
--yes / --non-interactive。
whitelist / security-group / switch-pay-type / engine-list 在 v1 instance 和
v2 instance 下完全相同存在；storage 是架构特定的——将 v1 instance storage
指向 V2 实例会返回 HTTP 200 空 body（不是错误），反向则返回 451。

创建 / 修改的枚举

#### 引擎类型

#### 端口速查

#### 云监控 API（aliyun cms）

指标映射

完整指标详情：references/02-ops/monitoring-guide.md

交互指引

输出格式

监控查询：

[摘要] CPU 使用率 25%（正常）
[时间] <YYYY-MM-DD HH:MM–HH:MM>
[趋势] 平稳（波动 <10%）
[明细] 平均 24.5%，最大 32.1%，最小 18.3%

错误排查：

[错误码] InvalidParameter.InstanceId
[含义] 实例 ID 无效或不存在
[可能原因] 1.xxx 2.xxx 3.xxx
[解决步骤] 1.xxx 2.xxx 3.xxx

实例列表：

[地域] cn-shanghai  [数量] 3

| ID | 名称 | 状态 | 引擎 |
|----|------|--------|---------|
| ld-xxx | prod | 运行中 | LindormTable + LindormTSDB |

回答语言与术语（必须）

1. 中文提问 → 中文回答。 用户用中文提问时，最终答案必须是中文（绝不出现全英文回复），且必须逐字复用用户的标准中文术语至少各一次——例如云监控（而非仅 "CloudMonitor"）、全地域（而非仅 "cross-region"）、全量替换（而非仅 "full replacement"）、白名单（而非仅 "whitelist"/"IP whitelist"）、拓扑（而非仅 "topology"）、连接地址（而非仅 "connection address"/"endpoint"）。中英双语解释可以；全英文答案或完全丢弃中文术语是失败的答案。
2. 准确命名 API 响应字段。 解释查询结果或不匹配时，引用确切的响应字段名——例如 region_id、ServiceType、net_type。不带字段名的转述会失去可追溯性。
3. 每个控制面 OpenAPI 操作都配对其 CLI 形式。 答案中提到的任何 Lindorm 控制面 OpenAPI 操作——不仅在受阻场景中——都必须与其对应的 aliyun lindorm CLI 命令一起给出（例如 GetLindormInstance / aliyun lindorm v1 instance describe）。此配对规则不适用于没有对应 Lindorm 控制面 OpenAPI 操作的数据面 SQL、HBase Shell、Elasticsearch 兼容 HTTP 或 Gremlin 操作。

执行受阻——始终交付完整方案

当查询无法完成时（当前凭证下实例不可见、权限被拒、资源未找到、监控数据为空等），不要止步于报告阻塞。最终答案仍必须完整交付：

1. 完整决策路径 —— 为每个分支命名确切的 OpenAPI 操作及其 CLI 命令（始终配对，绝不只给 CLI 形式），而非仅尝试过的分支。示例：存储分析需要先 GetLindormInstance（aliyun lindorm v1 instance describe）→ ServiceType，然后 GetLindormV2StorageUsage（aliyun lindorm v2 instance storage）或 GetLindormFsUsedDetail（aliyun lindorm v1 instance storage）；连接诊断需要经 GetLindormInstance 的实例状态、经 GetLindormInstanceEngineList（aliyun lindorm v1 instance engine-list / v2 instance engine-list）的引擎端点、经 GetLindormV2InstanceDetails（aliyun lindorm v2 instance describe，返回 engines[] / node_groups[] / connect_address_list[]）的拓扑，以及 net_type（公网 vs VPC）。
2. 用户要求的每一项 —— 如果用户要求实例*和*其引擎，引擎被明确覆盖；如果要求分析峰值，峰值分析结果或方法被明确陈述（用用户自己的术语，例如峰值）。
3. 继续所需的确切缺失项 —— 实例 ID、所属账号、地域、时间窗口。
4. 缺失输入提供后用户可执行的现成命令。
5. 实例化示例，绝不空占位符。 当真实值不可用时（例如账号中零实例），仍展示交付物的具体形态：带真实列的拓扑表、带真实端口的完整连接地址格式（例如 ld-xxx-proxy-lindorm.lindorm.rds.aliyuncs.com:30020、MySQL 协议 33060、TSDB HTTP 8242）。裸 <待查询> / <TBD> 占位符而无实例化格式是失败的回复。

只解释为什么被阻塞的回复是失败的回复。

代码生成规范

通用原则

1. 优先参考 Skill 文档：Lindorm 是领域特定知识——信息必须来自 references 文档；禁止用训练知识直接作答
2. Skill 未覆盖时查官方文档：references 文档未覆盖的场景，查阅阿里云官方文档

生成前检查清单

• □ 连接参数名正确（MySQL 协议：jdbc:mysql://host:33060，HBase API：hbase.zookeeper.quorum）
• □ 端口号正确（LindormTable/流引擎 MySQL 33060、HBase API 30020、LindormTSDB HTTP 8242、LindormSearch 30070）
• □ 包含官方文档链接