alibabacloud-devops

通过 Yunxiao 工具执行智能 DevOps

此技能可将自然语言形式的 DevOps 请求转换为 Alibaba Cloud Yunxiao API 调用。它支持三种调用渠道：Alibaba Cloud CLI（aliyun devops）、MCP 服务和 mcporter CLI。涵盖 8 款 Yunxiao 产品（约 388 条 CLI 命令、约 165 个 MCP 工具）。

1. 概述

• 核心流程：意图分类 → 歧义消解 → 产品映射 → 阅读参考资料 → 工具执行 → 结果验证
• 范围：CI/CD、代码管理、项目协作、冲刺/工作项、制品、测试、应用交付

如需完整的产品与工具目录（按产品分类的 MCP 工具和 CLI 命令），请参阅 references/tool-catalog.md。

---

2. 先决条件

[MUST] 必须按顺序执行。 本节中的步骤构成一棵顺序决策树。你必须按下方编号顺序执行。只有在 CLI 路径（步骤 1–4）已完整尝试并失败后，才能检查 Node.js、MCP 或 mcporter 是否可用。不得并行执行 2.1 和 2.2 小节中的检查。

令牌安全规则（适用于所有渠道）：

• 绝不要求用户在对话或命令行中粘贴明文令牌
• 绝不使用 echo 或类似命令读取/打印令牌值
• 仅通过检查确认令牌是否存在（各渠道对应的环境变量名称见下方步骤）
• 如果未配置令牌，立即停止，并引导用户参阅 Yunxiao 个人访问令牌。所需权限范围：组织管理（读/写）、项目协作（读/写）、代码管理（读/写）、流水线（读/写）、包管理（读/写）、应用交付（读/写）、测试管理（读/写）。

2.1 CLI 通道设置（主要通道——必须先完成）

Alibaba Cloud CLI（aliyun devops）是主要调用通道。MCP 服务和 mcporter 仅作为备用方案。完整配置指南：references/aliyun-cli-setup.md。

步骤 1：检查 CLI 是否可用

aliyun devops --help >/dev/null 2>&1 && echo "cli ready" || echo "cli not available"

• 可用 → 前往步骤 3
• 不可用 → 前往步骤 2（尝试安装）

步骤 2：[必须] 尝试安装 CLI

[必须] 如果步骤 1 中未找到 CLI，则在考虑任何备用通道之前，必须尝试安装。禁止跳过此步骤。完整安装指南：references/aliyun-cli-install.md。

1. 检测操作系统并安装：

   • macOS（已安装 Homebrew）：

     brew install aliyun-cli
     

   • macOS / Linux（未安装 Homebrew）：

     /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"
     

   • Windows（PowerShell）： 指引用户下载并运行 PowerShell 安装脚本。参见 references/aliyun-cli-install.md。

2. 验证安装并重新检查：

   aliyun version
   aliyun devops --help >/dev/null 2>&1 && echo "cli ready" || echo "cli not available"
   

   • 可用 → 前往步骤 3
   • 仍不可用 → 前往第 2.2 节备用方案

步骤 3：身份验证和站点类型检测

Cloud DevOps（云效）使用个人访问令牌进行身份验证，而非 AK/SK 配置文件。

3a. 检查令牌：

[ -n "$ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN" ] && echo "token configured" || echo "token missing"

如果缺少令牌，请根据用户的站点类型指引其进行配置：

中心站点（默认）——令牌 + 组织 ID：

export ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN=<your-personal-access-token>
export ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID=<your-organization-id>

地域站点——令牌 + 地域 API 基础 URL：

export ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN=<your-personal-access-token>
export ALIBABA_CLOUD_YUNXIAO_API_BASE_URL=<your-region-api-base-url>

[必须] 在中心站点切勿向用户询问 API 基础 URL——默认值为 openapi-rdc.aliyuncs.com（CLI 和 MCP 服务均适用）。基础 URL 仅适用于地域站点。

建议将这些配置添加到用户的 Shell 配置文件（~/.bashrc、~/.zshrc 等），以便持久保存。

3b. 检测站点类型：

确认令牌后，检测站点类型：

[ -n "$ALIBABA_CLOUD_YUNXIAO_API_BASE_URL" ] && echo "region site" || echo "central site (default)"
[ -n "$ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID" ] && echo "org id configured" || echo "org id missing"

• 已设置 ALIBABA_CLOUD_YUNXIAO_API_BASE_URL → 地域站点：后续 CLI 调用不使用 --organization-id；API 基础 URL 会自动从环境变量读取
• 未设置 → 中心站点（默认）：后续 CLI 调用使用 --organization-id；如果缺少组织 ID，请指引用户设置 ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID（可通过 aliyun devops base-get-user-by-token 查询）

[必须] 记住检测到的站点类型。本次会话中所有后续 CLI 调用都必须使用对应的参数格式。CLI 参数使用 kebab-case（例如 --organization-id），而非 camelCase（例如 --organizationId）。

步骤 4：[必须] 禁用交互式插件安装提示

devops 命令位于 aliyun-cli-devops 插件中，全新安装的 CLI 不包含此插件。因此，首次运行 aliyun devops <business-command> 时会提示 Do you want to install it? [Y/n]:，并且会一直阻塞，直到命令超时。在运行任何业务命令之前，每个会话都需运行一次：

aliyun configure set --auto-plugin-install true

跳过此步骤会浪费首次业务调用的全部超时预算。

CLI 已就绪——如果步骤 1–4 均已通过，则 CLI 通道已就绪。完全跳过第 2.2 节，并继续前往第 3 节。

2.2 备用通道设置（仅当 CLI 不可用时）

[门槛] 仅当同时满足以下两个条件时，才可进入本节：

1. 步骤 1（CLI 检查）返回“cli not available”
2. 已执行步骤 2（尝试安装 CLI），且安装失败

如果尚未尝试步骤 2，请返回并立即执行。切勿在此继续。

2.2.1 Node.js/Docker 运行环境检查

此技能通过 npx 或 docker 调用 [email protected]。请验证：

node --version   # Node.js 18+ recommended
npx --version

建议：预先安装依赖项（避免运行时下载）

npm install -g [email protected] [email protected] --registry=https://registry.npmmirror.com

2.2.2 云效个人访问令牌（用于 MCP/mcporter）

MCP/mcporter 使用 YUNXIAO_ACCESS_TOKEN（不同于 CLI 的 ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN）：

[ -n "$YUNXIAO_ACCESS_TOKEN" ] && echo "token configured" || echo "token missing"

如果缺少该令牌，请引导用户获取令牌并将其作为环境变量注入（参见第 2 节开头的令牌安全规则）。

2.2.3 MCP 服务设置

有关三种连接模式（Stdio / Docker / SSE），请参阅 references/mcp-setup.md。推荐使用 Stdio：

{
  "mcpServers": {
    "yunxiao": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "YUNXIAO_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

中心站点只需要令牌——YUNXIAO_API_BASE_URL 默认值为 https://openapi-rdc.aliyuncs.com。只有在区域站点使用时，才需将其添加到 env 中。

---

3. 授权失败处理

[MUST] 任何工具调用返回身份验证或授权错误时：

1. 查阅 references/token-scopes.md，确认所需的令牌范围
2. 引导用户在云效控制台的“个人访问令牌”中添加相应范围
3. 暂停执行，并等待用户确认后再继续

常见错误代码：

错误	操作
401 Authentication failed	检查令牌是否有效或已过期；提示重新生成
403 Insufficient permissions	检查令牌范围（参见 token-scopes.md 和 references/ram-policies.md）
404 Resource not found	使用 search_* / list_* 验证资源 ID
400 Parameter error	对照 MCP Schema 检查字段架构
500 Server error	使用退避策略，最多重试 3 次

---

4. 参数确认

IMPORTANT — 执行任何工具调用前，必须与用户确认所有由用户定义的参数（organizationId、projectId、repositoryId、pipelineId、分支名称、工作项主题、迭代日期、应用/环境名称等）。切勿基于默认值或猜测进行调用。

按产品划分的常见必填参数：

产品	通用必填参数	典型场景参数
All	organizationId	-
Codeup	repositoryId	sourceBranch / targetBranch / filePath
Flow	pipelineId	branch / runId / jobId
Projex	projectId	workitemTypeId / sprintId / subject
Testhub	projectId	testcaseId / testPlanId
AppStack	appName	envName / changeOrderId

---

5. 核心执行流程

User request → [Step 1] Intent classification → [Step 2] Ambiguity handling → [Step 3] Product mapping
             → [Step 4] Read product references → [Step 5] Execute tool calls → Return results

步骤 1：意图分类

核心原则：识别核心动词，而不是名词。

操作	常见动词	工具前缀
创建	create、add、initialize、set up	create_*
查询	view、get、list、search、find	get_* / list_* / search_*
更新	update、modify、change、edit	update_*
删除	delete、remove、clean up	delete_*（需要确认）
触发	run、execute、trigger、start、deploy	create_pipeline_run / execute_*
配置	configure、set up、bind、associate	update_* / create_*

决策树和示例：references/intent-classification.md。

步骤 2：歧义处理

核心原则：如果指令含糊不清或涉及多个产品的关键词，切勿猜测——应向用户询问。

歧义类型	检测条件	策略
产品	出现多个产品的关键词	询问用户要使用哪个产品
操作	操作不明确	询问操作类型
对象	缺少标识符	询问资源名称或 ID
参数	缺少关键参数	询问缺少的值
范围	未指定组织/项目	询问组织/项目

第 3 步：产品映射

完整映射：references/product-mapping.md。

关键词	产品	MCP 工具集	CLI 前缀
流水线、构建、部署、CI/CD	Flow	pipeline-management	flow-
代码、仓库、分支、提交、MR、评审	Codeup	code-management	codeup-
制品、包、Maven、NPM、Docker 镜像	Packages	packages-management	packages-
需求、工作项、冲刺、缺陷、任务	Projex	project-management	projex-
测试用例、测试计划、测试报告	Testhub	test-management	test-hub-
应用、编排、变更单、发布	AppStack	application-delivery	app-stack-
组织、成员、部门、角色	-	organization-management	base-
当前用户信息	-	base	base-

歧义判定要点：

• “CI/CD 全流程” → 仅构建 → Flow；应用生命周期 → AppStack；两者都有 → 询问
• “仓库” → 代码仓库 → Codeup；制品仓库 → Packages；不明确 → 询问

第 4 步：阅读产品参考资料

确定目标产品后，必须查阅 Yunxiao 文档索引：references/product-reference.md。

步骤 5：执行工具调用

三种调用渠道（功能等效）：

方法	场景	前提条件
Alibaba Cloud CLI（aliyun devops）	可使用 Shell 环境	已安装 aliyun 并配置令牌
平台原生 MCP	集成 MCP 的 IDE／平台	可使用 use_mcp_tool
终端 CLI（mcporter）	纯终端环境，无 MCP 服务	已安装 Node.js 18+

渠道选择：根据可用性选择——已配置 CLI → CLI；已集成 MCP → MCP；仅有 Shell 和 Node.js → mcporter。

区域站点路由（强制）： 当用户指定的云效实例地址或令牌与当前 MCP 配置不同时：

• 必须提示用户更新 MCP 服务配置（YUNXIAO_API_BASE_URL / YUNXIAO_ACCESS_TOKEN）
• 不得通过 mcporter 绕过 MCP 服务——仅在没有 MCP 服务时使用 mcporter
• URL 中包含区域关键词（例如 cn-shanghai）→ 区域版；openapi-rdc.aliyuncs.com 或未指定 → 中央版（默认，无需配置 base URL）

方法 A：Alibaba Cloud CLI

aliyun devops <command> --<param1> <value1> \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-devops/${SESSION_ID}"

所有 aliyun devops 命令都必须包含 --user-agent，并使用会话范围的 UA 值（参见第 7 节：可观测性）。使用环境变量进行身份验证时，无需额外的身份验证参数。使用命令行参数时，应在每条命令后追加 --yunxiao-access-token 和 --organization-id（中央版）或 --api-base-url（区域版）。

按产品前缀发现命令，请使用 scripts/discover-commands.sh，或参阅 references/tool-catalog.md。

方法 B：平台原生 MCP

use_mcp_tool(
  server_name: "yunxiao",
  tool_name: "<tool>",
  arguments: { "<key>": "<value>" }
)

方法 C：mcporter CLI

npx -y [email protected] call --no-coerce --stdio "npx -y [email protected]" <tool_name> [key:"value" ...]

必须始终使用 --no-coerce，以防止自动转换字符串枚举的类型。

参数规则：使用 key:"value" 格式，以空格分隔。不要传递 JSON 字符串。无参数工具不传参数。可使用 scripts/mcporter-call.sh 以简化操作。

获取可用工具：

npx -y [email protected] list --stdio "npx -y [email protected]" --schema

[必须] 工具选择必须基于动态发现：从已注册的工具列表中选择，绝不编造工具名称。使用 mcporter list 或参阅 references/tool-catalog.md。

[必须] 绝不编造结果：所有工具调用都必须实际执行，并获得真实返回值。

执行前检查清单（强制）：

1. 通过 aliyun devops base-get-user-by-token 获取 organizationId（MCP：get_current_organization_info）
2. [强制] 通过 list_* / search_* / get_* 验证目标资源存在——即使已提供 ID 也不例外
3. 与用户确认所有必需参数（第 4 节）
4. 删除操作需要确认
5. [强制] 首次调用任何不熟悉的工具前，动态验证其 schema：
   • 方法 B：检查平台工具注册表
   • 方法 C：npx -y [email protected] list --stdio "npx -y [email protected]" --schema 2>&1 | grep -A 30 'function <tool_name>'
   • 如果 schema 返回的工具名称不同，请使用 schema 中的版本
   • 对于 Testhub：先调用 test-hub-get-testcase-field-config（MCP：get_testcase_field_config）——它会报告哪些字段为必填（assignedTo 是必填字段），并提供 customFieldValues 必须携带的各库选项 ID（例如 {"tc.priority": "<P1 option id>"}；发送标签 "P1" 会失败，并返回 400 字段【优先级】所填值无效）。testSteps 必须包含 content[] 数组——仅使用 stepContent / expectedResult（即读回格式）的负载会失败，并返回 500 unknown exception。参见 references/common-scenarios.md 场景 6。
   • 对于 Projex：先调用 projex-list-workitem-types（MCP：list_work_item_types）——绝不使用硬编码的类型 ID

完整工具目录：references/tool-catalog.md。场景示例：references/common-scenarios.md。

---

6. 成功验证

[RECOMMENDED] 执行 create_* / update_* 后，如果预算允许，请调用对应的 get_* 进行验证。如果 API 返回成功并提供了资源 ID，即使没有回读，也可视为创建成功。

已知 API 限制：某些字段在写入与回读时可能有所不同，详见 references/verification-method.md。

操作	验证命令（CLI / MCP）	检查项
创建流水线	flow-get-pipeline（MCP：get_pipeline）	pipelineId + name 匹配
运行流水线	flow-get-latest-pipeline-run（MCP：get_latest_pipeline_run）	status != FAIL
创建分支	codeup-get-branch（MCP：get_branch）	分支已显示
创建 MR	codeup-get-change-request（MCP：get_change_request）	state = OPENED
创建工作项	projex-get-workitem（MCP：get_work_item）	subject + workItemTypeId 正确
创建冲刺	projex-get-sprint（MCP：get_sprint）	日期范围匹配

更多信息：references/verification-method.md。

---

7. 可观测性

User-Agent 声明（必须）

[MUST] 每个 aliyun devops 业务命令都必须带上 --user-agent 标志，以便进行归属和追踪。UA 值遵循固定模板，其中包含每个会话专属的标识符。

UA 模板：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-devops/{session-id}

Session-ID 生成规则：

项目	规则
格式	32 个字符的小写十六进制字符串，例如 f47ac10b58cc4372a5670e02b2c3d479
生命周期	每次技能调用会话开始时生成一次；在该会话的所有渠道（CLI、MCP、mcporter）中重复使用同一个值
一致性	同一会话中的 CLI --user-agent、MCP 请求元数据和 mcporter 调用必须使用相同的 {session-id}
生成方法	python3 -c "import uuid; print(uuid.uuid4().hex)" 或 uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]'

用法 — 将其追加到每个 aliyun devops 命令中：

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

aliyun devops <command> --<param1> <value1> \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-devops/${SESSION_ID}"

重要：--user-agent 标志应直接应用于每个业务命令。请勿通过任何全局模式设置命令配置 UA；始终在每次调用时以内联方式传入。

---

8. 最佳实践

1. 先读后写：先调用 get_*，再调用 update_* / delete_*，以确认当前状态
2. 分页：列表 API 默认启用分页；对于较大的列表，传入 page / perPage
3. 优先使用 YAML：创建流水线时需通过 flow-create-pipeline --name --content（必须使用 YAML）。编写 YAML 前，先收集三个组织特定的值；猜测时始终会被拒绝——代码仓库的 httpUrlToRepo（绝不能使用 webUrl）、Codeup 服务连接的 uuid（使用小写筛选条件 --service-connection-type codeup 查询；使用 Codeup 会稳定地返回空列表，但这并不能证明连接不存在），以及从现有流水线中获取的 runsOn.group（没有 API 可以列出构建集群，并且 public/<region> 往往不存在）。Codeup 凭据是嵌套的 certificate 对象，而不是一个简单的 serviceConnection 键；仅用于构建的流水线必须省略 ArtifactUpload。MCP 的 create_pipeline_from_description 会在内部生成 YAML，且无法修正——遇到任何 yaml校验失败 / 服务连接[...]不存在 错误时，请停止重试，改用 CLI 路径。已验证的模板和预检步骤：references/common-scenarios.md 场景 1。
4. 智能搜索：使用带时间戳参数的 flow-list-pipelines 时，--execute-start-time / --execute-end-time / --create-start-time / --create-end-time 接受毫秒级 epoch 值（13 位数字，例如 $(($(date +%s) * 1000))）。传入秒（10 位数字）不会被 API 拒绝；它会静默地按 1970 年筛选并返回误导性结果，因此请务必乘以 1000，并检查位数是否正确。（MCP 提供支持自然语言时间范围的 smart_list_pipelines。）
5. 优先只读：不确定时，使用 list_* / search_* / get_*
6. 快速止损：相同参数连续失败两次 → 更换方案。报告：尝试过的方法、错误、根本原因、后续步骤
7. 控制预算：先规划关键路径；调试不超过 3 步；接近上限（剩余 ≤2 次）→ 停止并报告
8. 清理：使用后删除实验性资源

---

9. 场景快速参考

完整示例：references/common-scenarios.md。

场景	产品	关键 CLI 命令	关键 MCP 工具
创建 Java 构建流水线	Flow	codeup-get-repository（克隆 URL）→ flow-list-service-connections --service-connection-type codeup（uuid；值需小写，Codeup 会返回 []）→ flow-get-pipeline（提取 runsOn）→ flow-create-pipeline → flow-list-pipelines	get_repository → list_service_connections → get_pipeline → create_pipeline_from_description（YAML 验证失败时回退到 CLI）
创建 MR 并添加评审评论	Codeup	codeup-get-repository → codeup-create-change-request → codeup-list-change-request-patch-sets → codeup-create-change-request-comment	get_repository → create_change_request → list_change_request_patch_sets → create_change_request_comment
创建迭代并添加需求	Projex	projex-search-projects → projex-create-sprint → projex-create-workitem	search_projects → create_sprint → create_work_item
运行流水线并查看日志	Flow	flow-get-pipeline → flow-create-pipeline-run（分支需放入 --params '{"branchModeBranchs":"<branch>"}'；没有 --branch 标志）→ flow-get-pipeline-run --pipeline-run-id → flow-get-pipeline-job-run-log --job-id <stages[].stageInfo.jobs[].id>	get_pipeline → create_pipeline_run → get_pipeline_run → get_pipeline_job_run_log
批量查询制品	Packages	packages-list-repositories → packages-list-artifacts	list_package_repositories → list_artifacts
创建测试用例	Testhub	test-hub-get-testcase-field-config（必填字段 + 选项 ID）→ test-hub-list-directories → test-hub-create-testcase → test-hub-search-testcases	get_testcase_field_config → list_testcase_directories → create_testcase → search_testcases
应用发布工作流	AppStack	app-stack-list-all-release-workflows → app-stack-execute-change-request-release-stage	list_app_release_workflows → execute_app_release_stage

---

10. 参考索引

参考文件	内容
references/aliyun-cli-install.md	阿里云 CLI 安装指南（macOS/Linux/Windows）
references/mcp-setup.md	MCP 服务连接模式和环境变量
references/intent-classification.md	意图分类决策树
references/product-mapping.md	关键词 → 产品映射表
references/product-reference.md	云效文档索引和核心概念
references/tool-catalog.md	按类别整理的约 165 个 MCP 工具目录
references/token-scopes.md	Token 授权范围和故障排查
references/common-scenarios.md	端到端工作流示例
references/verification-method.md	成功验证和回读方法
references/acceptance-criteria.md	工具调用正确性验收标准
references/ram-policies.md	云效权限模型与标准阿里云 RAM 的比较

• 云效文档
• 云效 OpenAPI
• alibabacloud-devops-mcp-server