azure-devops

Azure DevOps 技能

全面集成 Azure DevOps，涵盖看板、存储库、流水线和制品。

自动激活条件： 用户提及 Azure DevOps、ADO、工作项、看板、存储库、流水线、制品或 Azure DevOps URL 时。

用途

此技能通过专用的 Python 命令行工具，提供全面的 Azure DevOps 自动化指南，涵盖：

工作项（看板）

• 创建带有 HTML 格式描述的工作项
• 更新工作项（状态、分配、字段）
• 确认后删除工作项
• 建立父子关系链接
• 执行 WIQL 查询
• 发现工作项类型和字段

存储库

• 列出存储库及其详细信息
• 创建包含审阅者和工作项的拉取请求
• 验证分支
• 获取克隆 URL

流水线

• 列出并运行流水线
• 监控构建并查看日志
• 管理部署

制品

• 管理包源
• 发布和下载包
• 管理版本

快速开始

1. 首先进行身份验证

始终先检查身份验证：

python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

此操作会验证 Azure CLI 是否已安装、你是否已登录、组织和项目是否已配置，以及你是否拥有访问权限。

参见：[​@authentication.md]

2. 常见操作

创建工作项

python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "Implement feature" \
  --description @story.md

查询工作项

python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

创建拉取请求

python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/branch \
  --target main \
  --title "Add feature"

渐进式加载参考资料

有关特定操作的详细指南，请参阅：

• [@authentication.md] - 身份验证方法（PAT、OAuth、环境变量）
• [@work-items.md] - 工作项 CRUD 操作、字段更新、状态转换
• [@queries.md] - WIQL 查询模式、筛选和排序
• [@html-formatting.md] - 工作项描述和评论中的 HTML 格式
• [@repos.md] - 存储库操作、拉取请求工作流
• [@pipelines.md] - 流水线触发、构建监控、部署
• [@artifacts.md] - 包管理、制品发布
• [@HOW_TO_CREATE_YOUR_OWN.md] - 创建类似集成工具的模板

可用工具

工具	用途	使用时机
auth_check.py	验证身份验证	执行任何操作之前
create_work_item.py	创建工作项	添加用户故事、任务、Bug 等
update_work_item.py	更新工作项	更改状态、受分配人或字段
delete_work_item.py	删除工作项	移除工作项（需确认）
get_work_item.py	获取工作项详细信息	查看完整的工作项信息
list_work_items.py	查询工作项	查找、筛选和列出工作项
link_parent.py	链接父子项	创建 Epic → Feature → Story 层级
query_wiql.py	执行 WIQL 查询	使用 WIQL 进行复杂筛选
format_html.py	转换为 HTML	设置富文本描述格式
list_types.py	发现类型和字段	探索可用选项
list_repos.py	列出存储库	查看项目中的所有存储库
create_pr.py	创建拉取请求	提交代码以供审阅

常见模式

模式 1：创建带父项的工作项

# Create parent work item
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Epic" \
  --title "Q1 Planning Initiative" \
  --description @epic_desc.md

# Output: Created work item #12345

# Create child and link to parent
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Feature" \
  --title "Authentication System" \
  --description @feature_desc.md \
  --parent-id 12345

# Output: Created work item #12346 and linked to parent #12345

模式 2：查询并更新工作项

# Find your active work items
python .claude/scenarios/az-devops-tools/list_work_items.py \
  --query mine \
  --format ids-only

# Update work item state
python .claude/scenarios/az-devops-tools/update_work_item.py \
  --id 12345 \
  --state "Active" \
  --comment "Starting work on this"

模式 3：从功能分支创建拉取请求

# List repositories
python .claude/scenarios/az-devops-tools/list_repos.py

# Create pull request
python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/auth \
  --target main \
  --title "Add authentication" \
  --description @pr_desc.md \
  --reviewers "[email protected],[email protected]" \
  --work-items "12345,12346"

模式 4：发现可用类型

# List all work item types in your project
python .claude/scenarios/az-devops-tools/list_types.py

# Show fields for specific type
python .claude/scenarios/az-devops-tools/list_types.py \
  --type "User Story" \
  --fields

关键经验

必须使用 HTML 格式

Azure DevOps 工作项描述使用 HTML，而非 Markdown 或纯文本。

这些工具会自动处理：

• create_work_item.py 默认会将 Markdown 转换为 HTML
• 使用 --no-html 可禁用转换
• 也可以直接使用 format_html.py 进行自定义格式处理

参见：[@html-formatting.md]

两步式父级关联

受 Azure 限制，无法通过 CLI 在创建工作项时指定父级。

这些工具提供了两种方式：

选项 A： 使用 --parent-id 标志（推荐）：

python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Task" \
  --title "My Task" \
  --parent-id 12345

选项 B： 单独关联：

# Step 1: Create
TASK_ID=$(python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Task" \
  --title "My Task" \
  --json | jq -r '.id')

# Step 2: Link
python .claude/scenarios/az-devops-tools/link_parent.py \
  --child $TASK_ID \
  --parent 12345

区域路径和工作项类型

• 区域路径格式：ProjectName\TeamName\SubArea
• 工作项类型因项目而异（标准类型 + 自定义类型）
• 使用 list_types.py 查找项目中可用的类型

错误恢复

错误	使用的工具	示例
身份验证失败	auth_check.py --auto-fix	自动登录并配置
无效的工作项类型	list_types.py	查看可用类型
字段验证错误	list_types.py --type "Type" --fields	查看有效字段
父级关联失败	检查 ID 是否存在，并验证层级规则	Epic → Feature → Story → Task
分支不存在	使用 git branch -a 验证	先推送分支

工具实现

所有工具都位于 ~/.amplihack/.claude/scenarios/az-devops-tools/：

• 独立的 Python 程序（可独立运行）
• 可导入的模块（可在其他脚本中使用）
• 全面的错误处理
• 测试位于 tests/ 目录中

参见：工具 README

理念

这些工具遵循 amplihack 原则：

• 极致简洁：每个工具都专注做好一件事
• 拒绝废话：每个函数都能正常工作，没有存根或 TODO
• 可复用：可导入、可组合
• 快速失败：提供清晰的错误信息和可执行的指导
• 自包含：仅依赖标准库和 azure CLI 封装器

快速参考

# Setup (first time)
python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

# Create work item
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "Title" \
  --description @desc.md

# Update work item
python .claude/scenarios/az-devops-tools/update_work_item.py \
  --id 12345 \
  --state "Active"

# Query work items
python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

# Create pull request
python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/branch \
  --target main \
  --title "Add feature"

# Discover types
python .claude/scenarios/az-devops-tools/list_types.py