1. 前提条件
[必须] CLI User-Agent——每次调用 aliyun CLI 命令时都必须包含：
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search[必须] 启用 AI-Mode——执行 Agent Skill 必须启用 AI-mode。
在调用任何其他 aliyun CLI 命令之前，运行以下命令：
```bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search"
```
预检查：必须使用阿里云 CLI >= 3.3.3
运行 aliyun version，验证版本是否 >= 3.3.3。如果未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装/更新，
或参见 references/cli-installation-guide.md 获取安装说明。
然后[必须]运行 aliyun configure set --auto-plugin-install true，启用插件自动安装功能。
然后[必须]运行 aliyun plugin update，确保本地计算机上的所有现有插件始终为最新版本。
预检查：必须配置阿里云凭证
安全规则：
- 严禁读取、回显或打印 AK/SK 的值（例如，严禁使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
- 严禁要求用户直接在对话或命令行中输入 AK/SK
- 严禁通过 aliyun configure set 设置明文凭证值
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效的配置文件（AK、STS 或 OAuth 身份）。
如果不存在有效的配置文件，请在此停止。
1. 从阿里云控制台获取凭证
2. 在此会话之外配置凭证（通过在终端中运行 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 待 aliyun configure list 显示有效的配置文件后，返回并重新运行
[必须] 在每个退出点禁用 AI-Mode——无论出于任何原因，在给出最终响应之前，始终必须先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何其他不会再执行 CLI 命令的场景。
AI-mode 仅用于调用 Agent Skill 的场景，skill 停止运行后不得保持启用状态。
```bash
aliyun configure ai-mode disable
```
---
2. 参数确认
重要：参数确认——在执行任何命令或调用 API 之前，
所有用户可自定义参数（例如 RegionId、实例名称、CIDR 网段，
密码、域名、资源规格等）都必须与
用户确认。未经用户明确批准，不得自行假设并使用默认值。
| 参数 | 必填/可选 | 描述 | 默认值 | | - | - | - | - | | Scope | 必填（跨账号） | 跨账号搜索范围：资源目录 ID、根文件夹 ID、文件夹 ID 或成员 ID | 无 | | ResourceType | 可选 | 资源类型（例如 ACS::ECS::Instance） | 无（所有类型） | | RegionId | 可选 | 资源地域 ID（例如 cn-hangzhou） | 无（所有地域） | | ResourceId | 可选 | 资源 ID | 无 | | ResourceName | 可选 | 资源名称 | 无 | | VpcId | 可选 | VPC ID（例如 vpc-xxx） | 无 | | VSwitchId | 可选 | VSwitch（例如 vsw-xxx） | 无 | | IpAddress | 可选 | IP 地址 | 无 | | GroupByKey | 可选 | 统计分组维度：ResourceType、RegionId、ResourceGroupId | 无 | | MaxResults | 可选 | 分页 APIs 的每页数量。 | 20 |
---
3. RAM 策略
完整权限列表请参见 [references/ram-policies.md](references/ram-policies.md)。
推荐的系统策略：
- 只读：
AliyunResourceCenterReadOnlyAccess - 完全访问权限：
AliyunResourceCenterFullAccess
开通资源中心时会自动创建服务关联角色 AliyunServiceRoleForResourceMetaCenter。
资源可见范围
RAM 策略（在 ram-policies.md 中定义）控制用户是否可以调用资源中心 API。但是，对于搜索 APIs（SearchResources、GetResourceCounts、GetResourceConfiguration、SearchMultiAccountResources、GetMultiAccountResourceCounts、GetMultiAccountResourceConfiguration），结果中的资源可见范围由各云产品自身的权限决定：
单账号
- 云资源读取权限：RAM 用户在资源中心中只能看到其对相应云产品拥有只读权限的资源。例如，授予
ReadOnlyAccess后，用户可以看到其有权访问的所有资源；仅授予AliyunVPCReadOnlyAccess时，可见范围将仅限于 VPC 资源。 - 资源组范围权限：如果资源按资源组组织，可以授予 RAM 用户针对特定资源组的读取权限。该用户将只能看到该组中的资源，从而实现资源隔离。
跨账号
- 向资源目录管理账号的 RAM 用户授予系统策略
AliyunResourceCenterFullAccess，以启用跨账号资源搜索。
---
4. 核心工作流
步骤 1：根据用户需求确定所需的 APIs
根据用户的具体场景确定需要哪些 APIs。请参阅下方的场景卡片。
步骤 2：[必须] 每次调用 CLI 前阅读 API 文档
严重警告：在阅读references/related-apis.md中准确的参数格式之前，不得执行任何aliyun resourcecenter命令。
失败模式：猜测 --filter 等参数的格式会导致错误。必须从文档中复制正确的 JSON 结构。
强制操作：构造任何 CLI 命令之前，必须打开并阅读 [references/related-apis.md](references/related-apis.md) 中相应的 API 章节。
---
场景卡片
场景 1：服务开通
| 需求 | 账号类型 | API | 描述 | | - | - | - | - | | 检查是否已开通 | 单账号 | get-resource-center-service-status | 返回服务状态 | | 开通服务 | 单账号 | enable-resource-center | 首次使用时必须开通 | | 检查跨账号状态 | 资源目录 | get-multi-account-resource-center-service-status | 多账号场景 | | 开通跨账号服务 | 资源目录 | enable-multi-account-resource-center | 需要管理账号或委派管理员 |
---
场景 2：发现 ResourceType
| 需求 | 账号类型 | 脚本 | 描述 | | - | - | - | - | | 按关键字查找资源类型代码 | 单账号 | scripts/query-resource-types.py | 在 ResourceType、ProductName 和 ResourceTypeName 字段中搜索 |
决策逻辑：
- 当需要按资源类型筛选但不知道确切代码时 -> 先使用此脚本
- 发现正确的
ResourceType代码后 -> 在搜索或计数 API 中通过--filter参数使用该代码
---
场景 3：资源搜索
| 需求 | 账号范围 | API | 关键参数 | | - | - | - | - | | 按条件搜索资源 | 当前账号 | search-resources | --filter | | 跨账号资源搜索 | 资源目录 | search-multi-account-resources | --scope + --filter | | 搜索时包含已删除资源 | 当前账号 | search-resources | --include-deleted-resources=true |
---
场景 4：查看资源详情
| 需求 | 账号范围 | API | 使用场景 | | - | - | - | - | | 获取单个资源的配置 | 当前账号 | get-resource-configuration | 获取完整配置详情 | | 批量获取多个资源的配置 | 当前账号 | batch-get-resource-configurations | 一次获取多个资源 | | 获取其他账号中的资源配置 | 资源目录 | get-multi-account-resource-configuration | 跨账号查看 |
---
场景 5：统计与分析
| 需求 | 账号范围 | API | 分组维度 | | - | - | - | - | | 统计资源数量 | 当前账号 | get-resource-counts | ResourceType, RegionId, ResourceGroupId | | 跨账号统计 | 资源目录 | get-multi-account-resource-counts | ResourceType, RegionId, ResourceGroupId |
---
场景 6：标签发现
| 需求 | 账号范围 | API | 描述 | | - | - | - | - | | 列出所有标签键 | 当前账号 | list-tag-keys | 浏览标签目录 | | 列出指定标签键的所有值 | 当前账号 | list-tag-values | 例如，列出 env 的所有值 | | 跨账号标签键 | 资源目录 | list-multi-account-tag-keys | 多账号场景 | | 跨账号标签值 | 资源目录 | list-multi-account-tag-values | 多账号场景 |
---
5. 成功验证
有关每个工作流步骤的详细验证步骤和命令，请参见 [references/verification-method.md](references/verification-method.md)。
---
6. 注意事项
[必须] 高风险操作确认——执行disable-resource-center或disable-multi-account-resource-center前：
1. 必须明确告知用户以下影响：
- 关闭影响
- 关闭资源中心后，将无法再在资源中心查看资源数据。具体而言：
- 对于单个阿里云账号，关闭资源中心后，将无法再查看当前账号中的资源数据。
- 对于资源目录的管理账号和资源中心的委派管理员账号，关闭资源中心也会关闭跨账号资源搜索功能。届时，将无法再查看当前账号以及资源目录成员的资源数据。此外，成员也无法查看各自账号中的资源数据。
- 关闭资源中心后，控制台首页的资源管理模块、配置审计服务及其他相关场景也将无法查看资源数据。
- 关闭限制
- 如果资源目录的管理账号或资源中心的委派管理员账号已由其他账号启用跨账号资源功能，则无法关闭资源中心。
- 如果存在强依赖资源中心的云产品或功能，例如配置审计和关联资源转移，则必须先关闭这些云产品或功能，才能关闭资源中心。
2. 必须获得用户的明确确认（例如，用户输入“确认关闭”或类似的明确肯定答复）
3. 未经用户明确确认，不得继续
关闭资源中心
警告：关闭操作将删除所有资源数据并影响依赖服务（例如配置审计）。如果已启用跨账号功能，必须先将其关闭。
aliyun resourcecenter disable-resource-center \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search关闭跨账号资源中心
必须在关闭单账号资源中心前完成此操作（如果已启用跨账号功能）。需要使用管理账号或委派管理员账号。
aliyun resourcecenter disable-multi-account-resource-center \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search---
7. 最佳实践
- 每次调用资源中心 CLI 时都使用
--user-agent——此 skill 中的所有aliyun resourcecenter示例均包含--user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search。执行此 skill 的命令时，始终传入同一标志，确保用法与验证要求、维护人员的预期和任何自动检查保持一致。 - 使用筛选条件进行定向搜索——组合使用
ResourceType、RegionId和Tag筛选条件可提高搜索效率 - 使用
GroupByKey快速统计——无需迭代即可按类型、地域或资源组获取资源分布 - 跨账号范围选择——使用最具体的范围（成员 ID > 文件夹 ID > 根文件夹 ID > 目录 ID）以缩小搜索结果范围
- 启用后等待——资源中心激活后需要几分钟构建数据；大型账号可能需要更长时间
- 优先使用只读策略——出于安全考虑，请在日常搜索和统计操作中使用
AliyunResourceCenterReadOnlyAccess - ResourceType 发现——如果不知道确切的资源类型代码，请使用第 8 节中说明的辅助脚本（从 skill 根目录运行）。
- 标签发现与按标签筛选的搜索——如需了解“存在哪些标签键/值”，请使用
list-tag-keys/list-tag-values（以及带--scope的多账号变体）。仅使用search-resources查找符合标签条件的资源。
---
8. 可用脚本
| 脚本 | 用途 | 用法 | | - | - | - | | scripts/query-resource-types.py | 按关键字从阿里云资源中心查询资源类型；stdout 输出为 JSON（resourceTypes、count、keyword、language；失败时使用 success: false 和 error） | python3 scripts/query-resource-types.py <keyword> [--language LANGUAGE] |
---
9. 故障排除
当资源中心 API 调用或 aliyun resourcecenter 命令失败时，请读取响应中的 HTTP 状态码、Code（错误码）和 Message，然后在目录中查找匹配项。
完整错误列表：[references/error-codes.md](references/error-codes.md)
---
10. 参考链接
| 参考资料 | 说明 | | - | - | | [references/related-apis.md](references/related-apis.md) | 所有 CLI 命令列表 | | [references/ram-policies.md](references/ram-policies.md) | RAM 权限策略 | | [references/verification-method.md](references/verification-method.md) | 每个工作流的验证步骤 | | [references/error-codes.md](references/error-codes.md) | 去重后的资源中心 API 错误码目录（HTTP、Code、Message）及查询提示 | | [references/cli-installation-guide.md](references/cli-installation-guide.md) | 阿里云 CLI 安装指南 | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | 仅供维护人员/CI 使用：Skill 测试验收标准、正确的 CLI 命令格式、参数验证规则。注意：本文档面向人工维护人员和自动化测试，最终用户无需阅读。 |