azure-devops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure DevOps Skill

Azure DevOps 技能

Complete Azure DevOps integration covering boards, repositories, pipelines, and artifacts.

Auto-activates when: User mentions Azure DevOps, ADO, work items, boards, repos, pipelines, artifacts, or Azure DevOps URLs.

完整的Azure DevOps集成，涵盖工作项看板（Boards）、代码仓库（Repositories）、流水线（Pipelines）和制品（Artifacts）。

自动激活场景： 用户提及Azure DevOps、ADO、工作项、看板、仓库、流水线、制品或Azure DevOps相关URL时。

Purpose

用途

This skill provides comprehensive guidance for Azure DevOps automation through purpose-built Python CLI tools that handle:

本技能通过专门构建的Python CLI工具，为Azure DevOps自动化提供全面指导，可处理以下内容：

Work Items (Boards)

工作项（Boards）

Work item creation with HTML-formatted descriptions
Work item updates (state, assignments, fields)
Work item deletion with confirmation
Parent-child relationship linking
WIQL query execution
Work item type and field discovery

支持带HTML格式描述的工作项创建
工作项更新（状态、分配、字段修改）
带确认步骤的工作项删除
父子关联关系链接
WIQL查询执行
工作项类型与字段信息查询

Repositories

代码仓库（Repositories）

Repository listing with details
Pull request creation with reviewers and work items
Branch validation
Clone URL access

带详情的仓库列表展示
可指定评审人和关联工作项的拉取请求创建
分支有效性验证
克隆URL获取

Pipelines

流水线（Pipelines）

Pipeline listing and execution
Build monitoring and logs
Deployment management

流水线列表展示与执行
构建监控与日志查看
部署管理

Artifacts

制品（Artifacts）

Package feed management
Package publishing and downloading
Version management

包源管理
包发布与下载
版本管理

Quick Start

快速开始

1. Authentication First

1. 先完成身份认证

ALWAYS start by checking authentication:

bash

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

This verifies Azure CLI is installed, you're logged in, org/project are configured, and you have access.

See: [@authentication.md]

执行任何操作前，请务必先检查身份认证：

bash

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

该命令会验证Azure CLI是否已安装、是否已登录、组织/项目是否配置完成，以及您是否具备访问权限。

参考：[@authentication.md]

2. Common Operations

2. 常见操作示例

Create Work Item

创建工作项

bash

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

bash

python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "实现功能需求" \
  --description @story.md

Query Work Items

查询工作项

bash

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

bash

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

Create Pull Request

创建拉取请求

bash

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

bash

python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/branch \
  --target main \
  --title "新增功能"

Progressive Loading References

进阶参考文档

For detailed guidance on specific operations, see:

[@authentication.md] - Authentication methods (PAT, OAuth, environment variables)
[@work-items.md] - Work item CRUD operations, field updates, state transitions
[@queries.md] - WIQL query patterns, filtering, sorting
[@html-formatting.md] - HTML formatting in work item descriptions/comments
[@repos.md] - Repository operations, pull request workflows
[@pipelines.md] - Pipeline triggers, build monitoring, deployment
[@artifacts.md] - Package management, artifact publishing
[@HOW_TO_CREATE_YOUR_OWN.md] - Template for creating similar integration tools

如需特定操作的详细指导，请查看：

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

Available Tools

可用工具列表

Tool	Purpose	When to Use
`auth_check.py`	Verify authentication	Before any operations
`create_work_item.py`	Create work items	Add User Stories, Tasks, Bugs, etc.
`update_work_item.py`	Update work items	Change state, assignee, fields
`delete_work_item.py`	Delete work items	Remove work items (with confirmation)
`get_work_item.py`	Get work item details	View complete work item info
`list_work_items.py`	Query work items	Find, filter, and list work items
`link_parent.py`	Link parent-child	Create Epic → Feature → Story hierarchies
`query_wiql.py`	Execute WIQL queries	Complex filtering with WIQL
`format_html.py`	Convert to HTML	Format rich descriptions
`list_types.py`	Discover types/fields	Explore available options
`list_repos.py`	List repositories	View all repositories in project
`create_pr.py`	Create pull request	Submit code for review

工具名称	用途	适用场景
`auth_check.py`	验证身份认证	执行任何操作前
`create_work_item.py`	创建工作项	添加用户故事、任务、缺陷等
`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`	创建拉取请求	提交代码进行评审

Common Patterns

常见操作模式

Pattern 1: Create Work Item with Parent

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

bash

undefined

bash

undefined

Create parent work item

创建父工作项

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "Epic"
--title "Q1 Planning Initiative"
--description @epic_desc.md

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "Epic"
--title "Q1规划倡议"
--description @epic_desc.md

Output: Created work item #12345

输出：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

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "Feature"
--title "认证系统"
--description @feature_desc.md
--parent-id 12345

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

输出：Created work item #12346 and linked to parent #12345

undefined

undefined

Pattern 2: Query and Update Work Items

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

bash

undefined

bash

undefined

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"

undefined

python .claude/scenarios/az-devops-tools/update_work_item.py
--id 12345
--state "Active"
--comment "开始处理此项工作"

undefined

Pattern 3: Feature Branch to Pull Request

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

bash

undefined

bash

undefined

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 "user1@domain.com,user2@domain.com"
--work-items "12345,12346"

undefined

python .claude/scenarios/az-devops-tools/create_pr.py
--source feature/auth
--target main
--title "新增认证功能"
--description @pr_desc.md
--reviewers "user1@domain.com,user2@domain.com"
--work-items "12345,12346"

undefined

Pattern 4: Discover Available Types

模式4：查询可用的工作项类型

bash

undefined

bash

undefined

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

undefined

python .claude/scenarios/az-devops-tools/list_types.py
--type "User Story"
--fields

undefined

Critical Learnings

关键注意事项

HTML Formatting Required

需使用HTML格式

Azure DevOps work item descriptions use HTML, not Markdown or plain text.

The tools handle this automatically:

```
create_work_item.py
```
converts markdown to HTML by default
Use
```
--no-html
```
to disable conversion
Or use
```
format_html.py
```
directly for custom formatting

See: [@html-formatting.md]

Azure DevOps工作项描述仅支持HTML格式，不支持Markdown或纯文本。

本工具已自动处理此问题：

```
create_work_item.py
```
默认将Markdown转换为HTML格式
使用
```
--no-html
```
参数可禁用转换
或直接使用
```
format_html.py
```
进行自定义格式转换

参考：[@html-formatting.md]

Two-Step Parent Linking

父子关联需分两步完成

You cannot specify a parent during work item creation via CLI (Azure limitation).

The tools provide two approaches:

Option A: Use

--parent-id

flag (recommended):

bash

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

Option B: Link separately:

bash

undefined

通过CLI创建工作项时，无法直接指定父项（Azure平台限制）。

本工具提供两种解决方案：

方案A：使用
--parent-id
参数（推荐）：

bash

python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Task" \
  --title "我的任务" \
  --parent-id 12345

方案B：分开创建与关联：

bash

undefined

Step 1: Create

步骤1：创建子工作项

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

TASK_ID=$(python .claude/scenarios/az-devops-tools/create_work_item.py
--type "Task"
--title "我的任务"
--json | jq -r '.id')

Step 2: Link

步骤2：关联父项

python .claude/scenarios/az-devops-tools/link_parent.py
--child $TASK_ID
--parent 12345

undefined

python .claude/scenarios/az-devops-tools/link_parent.py
--child $TASK_ID
--parent 12345

undefined

Area Path and Work Item Types

区域路径与工作项类型

Area path format:
```
ProjectName\TeamName\SubArea
```
Work item types vary by project (standard + custom types)
Use
```
list_types.py
```
to discover what's available in your project

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

Error Recovery

错误排查

Error	Tool to Use	Example
Authentication failed	`auth_check.py --auto-fix`	Auto-login and configure
Invalid work item type	`list_types.py`	See available types
Field validation error	`list_types.py --type "Type" --fields`	See valid fields
Parent link failed	Check IDs exist, verify hierarchy rules	Epic → Feature → Story → Task
Branch does not exist	Verify with `git branch -a`	Push branch first

错误类型	解决工具	示例说明
身份认证失败	`auth_check.py --auto-fix`	自动登录并完成配置
无效的工作项类型	`list_types.py`	查看项目中可用的工作项类型
字段验证错误	`list_types.py --type "Type" --fields`	查看该类型支持的有效字段
父子关联失败	检查ID是否存在，验证层级规则（Epic→Feature→Story→Task）	确保符合层级关系要求
分支不存在	使用 `git branch -a` 验证	先推送分支到远程仓库

Tool Implementation

工具实现说明

All tools are in

~/.amplihack/.claude/scenarios/az-devops-tools/

Standalone Python programs (can run independently)
Importable modules (can use in other scripts)
Comprehensive error handling
Tests in
```
tests/
```
directory

See: Tool README

所有工具均位于

~/.amplihack/.claude/scenarios/az-devops-tools/

目录下：

独立的Python程序（可单独运行）
可作为模块导入（可在其他脚本中使用）
完善的错误处理机制
测试用例位于
```
tests/
```
目录

参考：工具README

Philosophy

设计理念

These tools follow amplihack principles:

Ruthless Simplicity: Each tool does one thing well
Zero-BS: Every function works, no stubs or TODOs
Reusable: Importable and composable
Fail-Fast: Clear errors with actionable guidance
Self-Contained: Standard library + azure CLI wrapper only

这些工具遵循amplihack的设计原则：

极致简洁：每个工具专注完成一件事
实用至上：所有功能均可正常使用，无占位符或待办项
可复用：可导入并与其他工具组合使用
快速失败：提供清晰的错误信息与可操作的解决指导
独立封装：仅依赖标准库与Azure CLI封装

Quick Reference

快速参考命令

bash

undefined

bash

undefined

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

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "User Story"
--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"

python .claude/scenarios/az-devops-tools/create_pr.py
--source feature/branch
--target main
--title "新增功能"

Discover types

查询可用工作项类型

python .claude/scenarios/az-devops-tools/list_types.py

undefined

python .claude/scenarios/az-devops-tools/list_types.py

undefined