AgentLoop 应用接入

产品范围：本技能仅用于将应用接入 AgentLoop，并非通用的 CloudMonitor（CMS）管理技能。工作区（workspace）名称必须符合 agentloop-{32-char-code} 格式；严禁接入 default-cms-* 或其他 CMS 工作区。底层 CLI 为 aliyun cms2。

前置检查

1. 检查 aliyun 是否存在 — 运行 which aliyun（macOS/Linux）或 where aliyun（Windows）。

• 未找到 → 提示用户先安装 aliyun CLI：https://help.aliyun.com/document_detail/121541.html。暂停执行并等待。

2. 检查 CLI 版本 — 运行 aliyun version。最低要求版本为：3.3.15（参见 frontmatter 中的 compatibility 字段）。

警告：版本号各段须按 整数 比较（遵循语义化版本规则）：3.3.4 < 3.3.15，因为 4 < 15。 Shell 验证命令：printf '%sn' "3.3.15" "$(aliyun version)" | sort -V | head -1 若输出结果等于当前版本，则表示不满足要求。

• 版本符合要求 → 进入第 3 步。
• 版本过旧或无法识别 →

1. 运行 aliyun upgrade --help，测试 upgrade 子命令是否可用。

• 可用 → 运行 aliyun upgrade -y 自动升级至最新版本，随后重新运行 aliyun version 进行校验。

2. 若 upgrade 不可用 → 运行 curl -fsSL --connect-timeout 10 --max-time 300 https://aliyuncli.alicdn.com/setup.sh | bash，然后重新运行 aliyun version 校验。

3. 若升级成功 → 进入第 3 步。

4. 若升级失败 → 提示用户手动升级：https://help.aliyun.com/zh/cli/update-cli。暂停执行并退出。

5. 检查 cms2 插件 — 运行 aliyun cms2 --help。

• 帮助输出正常 → 继续至 凭证（Credentials） 环节。
• 返回 unknown command 或插件缺失 → 立即中止，输出下方错误报告（需附带 CLI 版本、操作系统及错误信息），且 不得再执行任何 CLI 命令。

凭证（Credentials）

aliyun cms2 复用 aliyun CLI 的凭证系统（即 aliyun configure）。 使用 --profile 切换配置文件。

所需 RAM 权限详见：references/ram-policies.md。

可观测性（Observability）

User-Agent 模板

本技能中所有 aliyun CLI 命令（如 aliyun cms2、aliyun sts、aliyun cs 等）必须包含 --user-agent 参数：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agentloop-management/{session-id}"

请将 {session-id} 替换为当前工作流的会话标识符。

示例：

aliyun cms2 apm configuration get 
 --workspace agentloop-2694ecf8****************1f84542d 
 --region cn-hangzhou 
 --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agentloop-management/3f2a8b1c4d5e6f709182a3b4c5d6e7f8"

session-id 规则

1. 一次性生成：每个由技能触发的接入工作流启动时生成一次。
2. 格式要求：严格为 32 位小写十六进制字符，不含连字符（hyphen），无前缀。
3. 全程复用：同一工作流内所有 CLI 命令均须使用相同的 session-id，以便后端日志在各步骤间关联追踪。
4. 禁止重复生成：同一接入请求的各步骤之间不得重新生成 session-id。
5. 生成方式（任选其一）：

# 推荐方式
openssl rand -hex 16

# 备选方式
uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]'

全局约定

硬性约束：严禁回退至 aliyun cms、其他 API 版本，或采用任何变通方案。

始终优先运行 aliyun cms2 [subcommand] --help，以获取完整参数列表与使用示例。

• 工作区由用户显式提供（必需）：AgentLoop 接入过程 不会 自动推导工作区名称（例如 default-cms-{AccountId}-{regionId}）。工作区名称 必须 符合 agentloop-{32-char-code} 格式（前缀 agentloop- + 恰好 32 个字符）。示例：agentloop-2694ecf8****************1f84542d。
  • 若用户未提供工作区：运行 aliyun cms2 workspace list -o json，选取首个匹配正则 agentloop-[0-9a-f]{32} 的名称，并在继续前明确告知所选工作区。若无匹配项，则中止并提示：请提供符合格式 agentloop-{32-char-code} 的有效 AgentLoop 工作区。
  • 严禁替换 为 default-cms-{AccountId}-{regionId} 或其他任意推导名称。
  • 配额降级处理：若创建工作区返回 403 或 400 类配额/限制错误，应立即运行 aliyun cms2 workspace list -o json（必要时可使用 entity query），复用一个已存在的 agentloop-{32-char-code} 工作区，明确注明 “因配额限制复用已有工作区”，并 继续 执行 apm configuration create / apm configuration get — 不得中断工作流，亦 不得切换至非 agentloop- 前缀的工作区。
• 优先使用 -o text（默认输出格式），以降低 list/get 类操作的 token 消耗；仅在需要缩进 JSON 格式时才使用 -o json。
• 在接入具体资源 ID 前，须通过 entity query --source CloudResource 验证其有效性；不可仅依赖 ID 的字符串特征做判断。
• entity query 默认时间范围：当用户未指定 --from/--to 时，应默认为最近 7 天（--from = 当前时间 - 7 天，--to = 当前时间，单位均为 Unix 秒）。

执行安全性

所有破坏性或高影响的变更操作 必须 遵循两阶段执行协议（详见 references/apm.md）：

1. A 阶段（规划）：输出待执行的精确命令、目标对象、影响范围及回滚方案 — 然后 暂停执行并等待用户确认。
2. B 阶段（执行）：仅在用户 下一条消息 明确表示同意（如输入 yes、confirm、proceed、go ahead）后，方可执行写入/删除类命令。

强制规则（违反即视为工作流错误）：

• 对于集群/应用变更（如 kubectl patch、install-cluster-addons、启动脚本修改等），禁止 在同一响应中合并 A 阶段与 B 阶段。
• apm service delete 必须首先执行 A 阶段，除非用户 初始提示 已明确要求删除在 同一 工作流中创建的服务（常见于自动化评测清理场景）—— 此情况下，可在当前轮次中以内联单行形式展示删除计划，并在创建/验证完成后立即执行删除。
• 严禁将用户沉默解读为批准。

以下操作 无需确认，可直接执行：只读类命令；幂等的 apm configuration create、apm service create、apm configuration get。

错误处理

错误码及其对应处理方式详见 aliyun cms2 --help。补充提示如下：

• InvalidJSON 通常表示 --body 参数格式异常；建议在传入 CLI 前使用 jq . <<<'' 进行校验。
• --body and stdin are mutually exclusive; specify only one 表示同时提供了 --body（或 --file）和标准输入数据。修复方法：仅保留一种输入源。在代理（agent）或 CI 环境中，若标准输入可能为管道（pipe），可在命令末尾添加 < /dev/null 以确保 stdin 为空。

强制显式调用的 API（为保障评测可追溯性与审计合规性所必需）：

模块路由

未列于上表中的命令，请参考 aliyun cms2 --help。