ado-create-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADO Create Pull Request

ADO 创建拉取请求

Commit changes, push the branch, and open or update an Azure DevOps pull request with a conventional-commit-style title and a complete description: $ARGUMENTS

提交变更、推送分支，并以约定式提交（conventional-commit）风格的标题和完整描述创建或更新Azure DevOps拉取请求：$ARGUMENTS

Current state

当前状态

Git status: !
```
git status --porcelain
```
Current branch: !
```
git branch --show-current
```

Default branch: !

git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||' || echo main

Staged diff (stat): !
```
git diff --cached --stat
```
Unstaged diff (stat): !
```
git diff --stat
```
Recent commits on this branch: !
```
git log --oneline -10
```

Commits ahead of default: !

git log --oneline origin/$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||' || echo main)..HEAD 2>/dev/null | head -20

Remote URL (to confirm ADO host): !

git remote get-url origin 2>/dev/null || echo "no-remote"

Git状态: !
```
git status --porcelain
```
当前分支: !
```
git branch --show-current
```

默认分支: !

git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||' || echo main

暂存区差异（统计）: !
```
git diff --cached --stat
```
未暂存区差异（统计）: !
```
git diff --stat
```
该分支最近的提交: !
```
git log --oneline -10
```

领先于默认分支的提交: !

git log --oneline origin/$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||' || echo main)..HEAD 2>/dev/null | head -20

远程仓库URL（用于确认ADO主机）: !

git remote get-url origin 2>/dev/null || echo "no-remote"

Use the Azure DevOps MCP tools

使用Azure DevOps MCP工具

All ADO operations in this workflow go through the Azure DevOps MCP tools — never

az

az devops

. When you see tool names like

repo_create_pull_request

wit_link_work_item_to_pull_request

below, call the matching Azure DevOps tool from your tool list. If no Azure DevOps MCP tools are loaded in this session, stop and ask the user if they want to fallback to the

az

CLI.

此工作流中的所有ADO操作均通过Azure DevOps MCP工具执行——绝不使用

az

az devops

。当你看到如下方

repo_create_pull_request

或

wit_link_work_item_to_pull_request

之类的工具名称时，请从你的工具列表中调用对应的Azure DevOps工具。如果当前会话未加载Azure DevOps MCP工具，请停止操作并询问用户是否要回退到

az

CLI。

Workflow

工作流

1. Stage and commit

1. 暂存并提交

Follow the ado-commit skill for the commit step — same conventional-commit format, same AI-authorship trailer, same

AB#<id>

work-item trailer rules. Split into multiple commits if the staged diff covers unrelated concerns.

If the user is currently on the default branch (

main

master

), switch to a feature branch before committing. A reasonable default name is

user/<short-topic>

feature/<topic>

; if a work-item ID is known, prefix it:

feature/1234-<topic>

提交步骤请遵循ado-commit技能——使用相同的约定式提交格式、相同的AI作者尾注、相同的

AB#<id>

工作项尾注规则。如果暂存区的差异涉及不相关的内容，请拆分为多个提交。

如果用户当前处于默认分支（

main

master

），请在提交前切换到功能分支。合理的默认分支名称为

user/<简短主题>

或

feature/<主题>

；如果已知工作项ID，请添加前缀：

feature/1234-<主题>

。

2. Push

2. 推送

bash

git push -u origin "$(git branch --show-current)"

-u

sets upstream tracking so subsequent pushes don't need arguments.

bash

git push -u origin "$(git branch --show-current)"

-u

用于设置上游跟踪，后续推送无需再指定参数。

3. Gather context for the PR

3. 收集PR的上下文信息

Read the full diff against the base branch, not just the last commit — a PR title needs to summarize the whole branch, not one step of it.

bash

git diff origin/<default-branch>...HEAD

Open the files that changed significantly so you can describe the why accurately. If there's an existing PR for this branch, fetch it first (see step 5) and edit rather than replace — a human may already have curated the title or description.

读取与基准分支的完整差异，而非仅最后一次提交的差异——PR标题需要概括整个分支的内容，而非单一提交的内容。

bash

git diff origin/<default-branch>...HEAD

打开有重大变更的文件，以便准确描述变更的原因。如果该分支已有对应的PR，请先获取该PR（见步骤5）并进行编辑，而非直接替换——人工可能已经精心编辑过标题或描述。

4. Identify the repo, project, and work items

4. 识别仓库、项目和工作项

The MCP tools need identifiers:

Project and repository name — parse from the

origin

remote URL. ADO URLs follow

https://dev.azure.com/<org>/<project>/_git/<repo>

https://<org>.visualstudio.com/<project>/_git/<repo>

Repository ID — call

repo_get_repo_by_name_or_id

with

{ project, repositoryNameOrId: <repo-name> }

. Use the returned

id

for subsequent calls.

Work item IDs — scan the branch name and every commit subject/body on the branch (
```
git log origin/<default>..HEAD
```
) for
```
AB#<id>
```
,
```
#<id>
```
, or numeric prefixes like
```
feature/1234-...
```
. If the user mentioned a work item in the prompt, trust that.

If projects or repos aren't obvious,

core_list_projects

and

repo_list_repos_by_project

let you browse.

MCP工具需要以下标识符：

项目和仓库名称——从

origin

远程URL解析获取。ADO URL遵循格式

https://dev.azure.com/<组织>/<项目>/_git/<仓库>

或

https://<组织>.visualstudio.com/<项目>/_git/<仓库>

。

仓库ID——调用
```
repo_get_repo_by_name_or_id
```
工具，传入参数
```
{ project, repositoryNameOrId: <仓库名称> }
```
。后续调用请使用返回的
```
id
```
。
工作项ID——扫描分支名称以及该分支上所有提交的主题/正文（
```
git log origin/<默认分支>..HEAD
```
），查找
```
AB#<id>
```
、
```
#<id>
```
或类似
```
feature/1234-...
```
的数字前缀。如果用户在提示中提到了某个工作项，请以用户的说明为准。

如果无法明确项目或仓库，可以使用

core_list_projects

和

repo_list_repos_by_project

工具进行浏览。

5. Check for an existing PR

5. 检查是否存在现有PR

repo_list_pull_requests_by_repo_or_project {
  repositoryId: <id>,
  status: "active",
  sourceRefName: "refs/heads/<current-branch>"
}

If a result comes back, you're in update mode — keep the existing PR's ID and edit in place in step 7. Otherwise you're in create mode.

repo_list_pull_requests_by_repo_or_project {
  repositoryId: <id>,
  status: "active",
  sourceRefName: "refs/heads/<current-branch>"
}

如果返回结果，则处于更新模式——保留现有PR的ID，并在步骤7中进行编辑。否则处于创建模式。

6. Generate title and description

6. 生成标题和描述

Title — Conventional Commits, under 72 chars. For a single-commit PR the commit subject works; for a multi-commit PR synthesize a higher-level subject that captures the whole branch.

feat(auth): add JWT token refresh endpoint
fix(ui): resolve layout shift on mobile nav
refactor(db): migrate from raw SQL to query builder
feat(api)!: change pagination response shape

Description — use this template, omitting sections that don't apply:

markdown

undefined

标题——采用约定式提交（Conventional Commits）格式，长度不超过72字符。对于单提交PR，可以直接使用提交主题；对于多提交PR，需要提炼一个更具概括性的主题，覆盖整个分支的内容。

feat(auth): add JWT token refresh endpoint
fix(ui): resolve layout shift on mobile nav
refactor(db): migrate from raw SQL to query builder
feat(api)!: change pagination response shape

描述——使用以下模板，省略不适用的部分：

markdown

undefined

Summary

[1–2 sentences on what this PR does and why]

Changes

[Key change 1]
[Key change 2]

[Key change 1]
[Key change 2]

Breaking Changes

[What breaks and the migration step — delete this section if none]

Test Plan

[How this was verified — commands, manual checks, screenshots]

[How this was verified — commands, manual checks, screenshots]

Work Items

AB#1234


Keep the `AB#<id>` references in the description — ADO parses them and shows the linked work items alongside the PR. You'll *also* link them via MCP in step 8 so the links are first-class, not just string-matched.

AB#1234


请在描述中保留`AB#<id>`引用——ADO会解析这些引用，并在PR旁显示关联的工作项。你还需要在步骤8中通过MCP工具将它们关联起来，使这些链接成为一等关联，而非仅字符串匹配。

7. Create or update the PR

7. 创建或更新PR

Create (default to draft):

repo_create_pull_request {
  repositoryId: <id>,
  sourceRefName: "refs/heads/<current-branch>",
  targetRefName: "refs/heads/<default-branch>",
  title: "<conventional-commit title>",
  description: "<markdown from template>",
  isDraft: true
}

sourceRefName

and

targetRefName

need the full

refs/heads/

prefix — a common mistake is passing the bare branch name and getting a cryptic 400.

Update (existing PR):

repo_update_pull_request {
  repositoryId: <id>,
  pullRequestId: <id-from-step-5>,
  title: "<updated title>",
  description: "<updated description>"
}

Respect the existing title/description if they're already meaningful — enhance rather than overwrite. If the existing title already follows conventional commits and is accurate, leave it alone.

创建（默认草拟模式）：

repo_create_pull_request {
  repositoryId: <id>,
  sourceRefName: "refs/heads/<current-branch>",
  targetRefName: "refs/heads/<default-branch>",
  title: "<conventional-commit title>",
  description: "<markdown from template>",
  isDraft: true
}

sourceRefName

和

targetRefName

需要完整的

refs/heads/

前缀——常见错误是仅传入分支名称，导致出现模糊的400错误。

更新（现有PR）：

repo_update_pull_request {
  repositoryId: <id>,
  pullRequestId: <id-from-step-5>,
  title: "<updated title>",
  description: "<updated description>"
}

如果现有标题/描述已经有意义，请予以尊重——进行补充而非覆盖。如果现有标题已经符合约定式提交格式且准确无误，请保持原样。

8. Link work items

8. 关联工作项

Even if the description contains

AB#<id>

, explicitly link each work item so it shows up as a structured PR-WorkItem relationship:

wit_link_work_item_to_pull_request {
  projectId: <project-id>,
  repositoryId: <repo-id>,
  pullRequestId: <pr-id>,
  workItemId: <work-item-id>
}

Call once per work item ID.

即使描述中包含

AB#<id>

，也要显式关联每个工作项，使其显示为结构化的PR-工作项关系：

wit_link_work_item_to_pull_request {
  projectId: <project-id>,
  repositoryId: <repo-id>,
  pullRequestId: <pr-id>,
  workItemId: <work-item-id>
}

每个工作项ID调用一次该工具。

9. Reviewers (optional)

9. 审核人（可选）

If the user named reviewers, resolve them to identity IDs and attach:

core_get_identity_ids { searchFilter: "<name or email>" }
repo_update_pull_request_reviewers {
  repositoryId: <id>,
  pullRequestId: <id>,
  reviewerIds: [<ids>],
  action: "add"
}

Don't auto-assign reviewers the user didn't mention — ADO default reviewer policies usually handle that, and guessing people's IDs is a good way to ping the wrong person.

如果用户指定了审核人，请解析他们的身份ID并添加：

core_get_identity_ids { searchFilter: "<name or email>" }
repo_update_pull_request_reviewers {
  repositoryId: <id>,
  pullRequestId: <id>,
  reviewerIds: [<ids>],
  action: "add"
}

不要自动分配用户未提及的审核人——ADO的默认审核人策略通常会处理此事，猜测用户ID很可能会通知错误的人。

10. Report back

10. 反馈结果

Print the PR's web URL (returned in the create/update response as

url

_links.web.href

) so the user can click through. Summarize: branch → target, draft status, work items linked, reviewers added.

打印PR的网页URL（在创建/更新响应中以

url

或

_links.web.href

返回），方便用户点击访问。总结内容包括：源分支→目标分支、草拟状态、关联的工作项、添加的审核人。

Guidelines

指导原则

Draft by default. Pass
```
isDraft: true
```
unless the user says otherwise. It's easier to mark ready than to walk back a premature review request.
Never skip pre-commit hooks. They run locally during commits created in step 1. A hook failure is the hook earning its keep.
Always attribute AI assistance via the
```
Assistant-model
```
trailer on every commit (see the ado-commit skill).
Respect existing content. If updating an existing PR, keep what's already curated; only replace sections that are stale or wrong.
Holistic title. The PR title is one line describing the whole branch. Don't concatenate commit subjects.

默认草拟模式。 除非用户另有说明，否则请传入
```
isDraft: true
```
。将PR标记为就绪比撤回过早发起的审核请求更容易。
绝不跳过提交前钩子（pre-commit hooks）。 这些钩子会在步骤1创建提交时在本地运行。钩子失败说明它正在发挥应有的作用。
始终标注AI协助——在每个提交中添加
```
Assistant-model
```
尾注（请参阅ado-commit技能）。
尊重现有内容。 如果更新现有PR，请保留已精心编辑的内容；仅替换过时或错误的部分。
整体化标题。 PR标题应为概括整个分支内容的单行文字。不要拼接多个提交的主题。

Related Azure DevOps tools

相关Azure DevOps工具

The 10-step workflow above names the tools you need on the happy path. Reach for the ones below when the situation calls for it — don't run them by default. Grouped by the sub-task they unlock.

Sub-task	Tool	When to reach for it
Locate the repo	`core_list_projects`	Project name isn't obvious from the remote URL
	`repo_list_repos_by_project`	Multiple repos in the project and you need to pick
Inspect branches	`repo_list_branches_by_repo`	Confirm the default / target branch exists before creating the PR
	`repo_get_branch_by_name`	Pull the latest commit or branch policies on the source branch
	`repo_create_branch`	Branch off server-side when the user isn't working locally
Pick a work item	`wit_my_work_items`	User didn't name one — surface their active items so they can confirm
	`search_workitem`	Keyword search when the work item ID is uncertain
	`wit_get_work_item` / `wit_get_work_items_batch_by_ids`	Fetch title/state to enrich the PR description (e.g. "Closes AB#1234 — add JWT refresh")
Inspect the change	`repo_get_pull_request_changes`	Programmatic diff on an existing PR when local `git diff` isn't enough
	`repo_search_commits`	Verify specific commits landed on the source branch
	`repo_get_file_content`	Re-read a file at a specific commit to describe it accurately
Fetch the PR	`repo_get_pull_request_by_id`	Reload the PR after create/update (web URL, status, policy state)
Extra linking	`wit_add_artifact_link`	Link a commit or build to a work item (non-PR relationship)
	`wit_add_work_item_comment`	Post "PR #N opened" on the work item so watchers see it async
Comments & votes	`repo_list_pull_request_threads` / `repo_list_pull_request_thread_comments`	Read existing review threads before editing the PR
	`repo_create_pull_request_thread`	Seed a context comment on the new PR (e.g. testing notes)
	`repo_reply_to_comment`	Respond to a reviewer inline
	`repo_vote_pull_request`	Approve / wait-for-author / reject on the user's behalf — only when explicitly asked
CI signal	`pipelines_get_build_status`	Check whether the branch's CI is green before un-drafting
	`pipelines_get_build_log`	Pull logs when CI is red and you're helping diagnose

上述10步工作流列出了正常流程所需的工具。仅在需要时使用以下工具——不要默认运行它们。按工具支持的子任务分组。

Sub-task	Tool	When to reach for it
定位仓库	`core_list_projects`	无法从远程URL明确项目名称时
	`repo_list_repos_by_project`	项目中有多个仓库，需要选择时
检查分支	`repo_list_branches_by_repo`	创建PR前确认默认/目标分支存在时
	`repo_get_branch_by_name`	获取源分支的最新提交或分支策略时
	`repo_create_branch`	用户未在本地工作，需要从服务器端创建分支时
选择工作项	`wit_my_work_items`	用户未指定工作项——展示其活跃工作项供确认时
	`search_workitem`	不确定工作项ID，需要关键词搜索时
	`wit_get_work_item` / `wit_get_work_items_batch_by_ids`	获取工作项标题/状态以丰富PR描述时（例如："Closes AB#1234 — 添加JWT刷新功能"）
检查变更	`repo_get_pull_request_changes`	本地 `git diff` 无法满足需求，需要以编程方式获取现有PR的差异时
	`repo_search_commits`	验证特定提交是否已合并到源分支时
	`repo_get_file_content`	需要重新读取特定提交版本的文件以准确描述变更时
获取PR	`repo_get_pull_request_by_id`	创建/更新后重新加载PR（获取网页URL、状态、策略状态）时
额外关联	`wit_add_artifact_link`	将提交或构建关联到工作项（非PR关联）时
	`wit_add_work_item_comment`	在工作项上发布"已创建PR #N"，以便关注者异步查看时
评论与投票	`repo_list_pull_request_threads` / `repo_list_pull_request_thread_comments`	编辑PR前查看现有审核线程时
	`repo_create_pull_request_thread`	在新PR上添加上下文评论时（例如测试说明）
	`repo_reply_to_comment`	在线回复审核人时
	`repo_vote_pull_request`	代表用户批准/等待作者/拒绝PR时——仅在明确要求时执行
CI信号	`pipelines_get_build_status`	将PR移出草拟模式前检查分支CI是否通过时
	`pipelines_get_build_log`	CI失败时获取日志以协助诊断时