Yunxiao

云效 CLI

阿里云云效 DevOps 命令行工具。涵盖代码评审、发布管理和任务跟踪。

工具选择

创建 MR 完整流程（最常用）

一键执行，无需额外查询。 适用于：用户说"创建 MR"、"提交代码评审"、"推送分支并创建 MR"。

步骤 1：提取 ID（从 git remote 自动获取）

# 从 git remote 提取组织 ID
ORG_ID=$(git remote get-url origin | sed -E 's|.*codeup.aliyun.com[:/]([^/]+)/.*|\1|')
echo "组织 ID: $ORG_ID"

# 从 git remote 提取仓库名
REPO_NAME=$(git remote get-url origin | sed -E 's|.*/([^/]+?)(\.git)?$|\1|')
echo "仓库名: $REPO_NAME"

# 获取仓库 ID（⚠️ 注意：字段是大写 Id，不是 id）
REPO_ID=$(aliyun devops ListRepositories --organizationId $ORG_ID \
  | jq -r ".result[] | select(.name == \"$REPO_NAME\") | .Id")
echo "仓库 ID: $REPO_ID"

步骤 2：创建分支、提交、推送

# 创建并切换分支
git checkout -b feature/your-feature

# 添加改动并提交
git add .
git commit -m "feat: your commit message"

# 推送分支到远程
git push -u origin feature/your-feature

步骤 3：创建 MR

aliyun devops CreateMergeRequest \
  --organizationId $ORG_ID \
  --repositoryId $REPO_ID \
  --body '{
    "title": "feat: your MR title",
    "description": "## Summary\n\n- Change 1\n- Change 2",
    "sourceBranch": "feature/your-feature",
    "targetBranch": "main",
    "sourceProjectId": '$REPO_ID',
    "targetProjectId": '$REPO_ID',
    "createFrom": "WEB"
  }'

⚠️ 关键点：

• 仓库 ID 字段是 Id（大写 I），不是 id
• sourceProjectId、targetProjectId、createFrom: "WEB" 三个字段必须提供

更新 MR 描述

已创建的 MR 可以通过 UpdateMergeRequest 更新标题、描述等信息。

aliyun devops UpdateMergeRequest \
  --organizationId $ORG_ID \
  --repositoryId $REPO_ID \
  --localId <mr-local-id> \
  --body '{
    "title": "feat: updated title",
    "description": "## Summary\n\n- Updated description"
  }'

参数说明：

• --localId: MR 的本地编号（在 URL 中可见，如 /mergerequests/56 中的 56）
• --body: 要更新的字段，支持 title、description 等

获取 MR localId：

# 列出仓库的 MR
aliyun devops ListMergeRequests \
  --organizationId $ORG_ID \
  --repositoryId $REPO_ID \
  | jq -r '.result[] | "\(.localId): \(.title) [\(.state)]"'

已知 ID 速查表

首次使用前必须获取这些 ID，后续可直接复用：

# 获取组织 ID（必须加 --minAccessLevel 5）
aliyun devops ListOrganizations --minAccessLevel 5 \
  | jq -r '.result[] | "\(.organizationId): \(.organizationName)"'

# 获取项目 ID
aliyun devops ListProjects --organizationId <org-id> --category Project \
  | jq -r '.projects[] | "\(.identifier): \(.name)"'

# 获取任务类型 ID
aliyun devops ListProjectWorkitemTypes \
  --organizationId <org-id> --projectId <project-id> \
  --category Task --spaceType Project \
  | jq -r '.workitemTypes[] | "\(.identifier): \(.name)"'

# 获取状态 ID 列表
aliyun devops ListWorkItemWorkFlowStatus \
  --organizationId <org-id> \
  --spaceIdentifier <project-id> \
  --spaceType Project \
  --workitemTypeIdentifier <task-type-id> \
  --workitemCategoryIdentifier Task \
  | jq -r '.statuses[] | "\(.identifier): \(.name)"'

常见状态 ID（大多数项目通用）：

任务管理（一次成功模板）

查看任务列表

aliyun devops ListWorkitems \
  --organizationId <org-id> \
  --spaceIdentifier <project-id> \
  --spaceType Project \
  --category Task \
  | jq -r '.workitems[] | "\(.identifier): \(.subject) [\(.status)]"'

更新任务状态为"已完成"

⚠️ 必须用 REST API 方式（aliyun devops POST /path），不能用命令行参数方式

aliyun devops POST /organization/<org-id>/workitems/updateWorkitemField \
  --body '{
    "workitemIdentifier": "<workitem-id>",
    "updateWorkitemPropertyRequest": [
      {"fieldIdentifier": "status", "fieldValue": "100014"}
    ]
  }'

关键点：

• updateWorkitemPropertyRequest 必须是数组 [{...}]
• 字段名是 fieldIdentifier 和 fieldValue（不是 propertyKey/propertyValue）

添加任务评论

aliyun devops POST /organization/<org-id>/workitems/comment \
  --body '{
    "workitemIdentifier": "<workitem-id>",
    "content": "## 评论标题\n\n评论内容，支持 Markdown",
    "formatType": "MARKDOWN"
  }'

关键点： formatType 必须指定（MARKDOWN 或 RICHTEXT）

完整示例：完成任务并添加评论

ORG_ID="<your-org-id>"
WORKITEM_ID="<your-workitem-id>"

# 1. 更新状态为已完成
aliyun devops POST /organization/${ORG_ID}/workitems/updateWorkitemField \
  --body "{
    \"workitemIdentifier\": \"${WORKITEM_ID}\",
    \"updateWorkitemPropertyRequest\": [
      {\"fieldIdentifier\": \"status\", \"fieldValue\": \"100014\"}
    ]
  }"

# 2. 添加完成评论
aliyun devops POST /organization/${ORG_ID}/workitems/comment \
  --body "{
    \"workitemIdentifier\": \"${WORKITEM_ID}\",
    \"content\": \"## 实现完成\\n\\n- 功能已实现\\n- 测试已通过\",
    \"formatType\": \"MARKDOWN\"
  }"

创建任务

步骤 1：获取必填字段配置

⚠️ 不同项目可能有不同的必填自定义字段，创建前必须先查询：

# 使用 MCP 工具查询字段配置
mcp__yunxiao__get_work_item_type_field_config(
  organizationId="<org-id>",
  projectId="<project-id>",
  workItemTypeId="<task-type-id>"
)

常见必填字段示例：

• assignedTo - 负责人（用户 accountId）
• priority - 优先级（如 c31cc0589797babd16889232e4 = 中）
• 自定义字段如「任务类别」「端」等

步骤 2：获取用户 accountId

# 列出组织成员
aliyun devops ListOrganizationMembers --organizationId <org-id> \
  | jq -r '.members[] | "\(.accountId): \(.organizationMemberName)"'

⚠️ 注意： 没有直接获取「当前用户」的 API，需要从成员列表中找到对应用户。

步骤 3：创建任务

aliyun devops CreateWorkitem \
  --organizationId <org-id> \
  --body '{
    "subject": "任务标题",
    "space": "<project-id>",
    "spaceIdentifier": "<project-id>",
    "spaceType": "Project",
    "category": "Task",
    "workitemType": "<task-type-id>",
    "workitemTypeIdentifier": "<task-type-id>",
    "assignedTo": "<user-accountId>",
    "description": "任务描述，支持 Markdown",
    "fieldValueList": [
      {"fieldIdentifier": "priority", "value": "<priority-id>"},
      {"fieldIdentifier": "<custom-field-id>", "value": "<value>"}
    ]
  }'

关键点：

• space 和 spaceIdentifier 必须同时提供，值相同
• workitemType 和 workitemTypeIdentifier 必须同时提供，值相同
• assignedTo 是必填的，值为用户的 accountId
• fieldValueList 中需包含项目定义的所有必填自定义字段

创建发布 Tag

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

常见错误速查

依赖工具

详细指南

• AI 助手必读: 见 references/cheatsheet.md - 所有必须遵守的规则
• OpenAPI 参考: 见 references/openapi.md - 完整 API 文档和 MR 操作指南