提PR工具實(shí)現(xiàn))
1. 為什么我要自己造一個(gè)自動(dòng)提 PR 的輪子團(tuán)隊(duì)里用 Azure DevOps 做代碼托管已經(jīng)兩年多了日常開(kāi)發(fā)流程里最煩的其實(shí)不是寫(xiě)代碼而是每次改完一堆文件之后那套機(jī)械動(dòng)作切分支、寫(xiě) commit message、push、打開(kāi)瀏覽器、找到目標(biāo)倉(cāng)庫(kù)、點(diǎn) New Pull Request、填標(biāo)題、填描述、選 reviewer、關(guān)聯(lián)工作項(xiàng)。一套下來(lái)少說(shuō)五分鐘多的時(shí)候十分鐘就沒(méi)了而且這十分鐘里你腦子是空轉(zhuǎn)的純純的體力活。一開(kāi)始我也試過(guò)用現(xiàn)成的腳本糊一個(gè)比如寫(xiě)個(gè) bash 把 git 命令串起來(lái)再調(diào) Azure DevOps 的 REST API 創(chuàng)建 PR。能用但問(wèn)題很明顯腳本是死的參數(shù)全靠命令行傳稍微復(fù)雜一點(diǎn)的需求比如根據(jù)改動(dòng)文件自動(dòng)推斷 reviewer、根據(jù)分支名自動(dòng)關(guān)聯(lián)工作項(xiàng)就得改腳本。后來(lái) MCPModel Context Protocol這個(gè)概念火起來(lái)我意識(shí)到這東西天生適合干這種把多個(gè)工具串起來(lái)、由模型決定調(diào)用順序的活。MCP 本質(zhì)上是一個(gè)標(biāo)準(zhǔn)化的協(xié)議讓模型能夠以統(tǒng)一的方式調(diào)用外部工具而 Skill 則是把這些工具能力封裝成模型可以理解和編排的單元。所以這個(gè)項(xiàng)目的目標(biāo)就很明確了做一個(gè) MCP 工具把 Git 的本地操作和 Azure DevOps 的遠(yuǎn)端 API 串起來(lái)讓模型通過(guò) Skill 編排實(shí)現(xiàn)我說(shuō)一句把這個(gè)改動(dòng)提個(gè) PR它自己把剩下的事全干完。關(guān)鍵詞里的 MCP、Git、Azure DevOps、PR、Skill 這五個(gè)詞基本就是這個(gè)項(xiàng)目的全部骨架。這篇文章我會(huì)把整個(gè)實(shí)現(xiàn)過(guò)程拆開(kāi)講包括我踩過(guò)的坑、為什么這么設(shè)計(jì)、以及一些文檔里不會(huì)寫(xiě)的細(xì)節(jié)。先說(shuō)清楚適合誰(shuí)看如果你已經(jīng)在用 Azure DevOps 或者類似的代碼平臺(tái)日常有大量重復(fù)的提交 PR 操作并且對(duì) MCP 有基本了解哪怕只是聽(tīng)說(shuō)過(guò)那這篇能直接抄作業(yè)。如果你完全沒(méi)接觸過(guò) MCP也沒(méi)關(guān)系我會(huì)在講實(shí)現(xiàn)的時(shí)候把必要的背景補(bǔ)上但你需要對(duì) Git 的基本操作和 REST API 的調(diào)用方式有概念。2. 拆解需求這個(gè) MCP 工具到底要解決哪幾件事2.1 把提 PR這個(gè)動(dòng)作拆成原子能力很多人一上來(lái)就想做一個(gè)一鍵提 PR的大工具我覺(jué)得這是錯(cuò)的。MCP 的設(shè)計(jì)哲學(xué)是提供細(xì)粒度的工具讓模型去編排而不是做一個(gè)黑盒。所以我先把整個(gè)流程拆成了幾個(gè)原子操作檢查工作區(qū)狀態(tài)當(dāng)前在哪個(gè)分支、有沒(méi)有未提交的改動(dòng)、有沒(méi)有未跟蹤的文件。創(chuàng)建并切換分支根據(jù)命名規(guī)范生成分支名比如feature/xxx或fix/xxx。暫存與提交把改動(dòng) add 進(jìn)來(lái)生成符合規(guī)范的 commit message。推送到遠(yuǎn)端push 到 origin并設(shè)置 upstream。創(chuàng)建 PR調(diào)用 Azure DevOps REST API填標(biāo)題、描述、源分支、目標(biāo)分支、reviewer。關(guān)聯(lián)工作項(xiàng)如果分支名或 commit message 里有工作項(xiàng) ID自動(dòng)關(guān)聯(lián)。這六個(gè)操作每一個(gè)都做成獨(dú)立的 MCP tool模型可以根據(jù)實(shí)際情況決定調(diào)用哪些、跳過(guò)哪些。比如工作區(qū)是干凈的那就不需要 commit直接 push 就行比如分支已經(jīng)存在那就不需要?jiǎng)?chuàng)建。2.2 為什么不讓模型直接調(diào) git 命令有人會(huì)問(wèn)既然模型能執(zhí)行 shell 命令為什么不直接讓它跑git commit -m xxx我試過(guò)問(wèn)題在于不可控。模型生成的命令你沒(méi)法保證它每次都正確尤其是涉及路徑、分支名、特殊字符的時(shí)候一個(gè)引號(hào)沒(méi)處理好就出問(wèn)題。而且直接執(zhí)行 shell 命令沒(méi)有結(jié)構(gòu)化輸出模型拿到一堆文本還得自己解析容易出錯(cuò)。做成 MCP tool 的好處是輸入輸出都是結(jié)構(gòu)化的 JSON模型知道每個(gè)字段是什么含義調(diào)用之前可以先校驗(yàn)參數(shù)調(diào)用之后能拿到明確的結(jié)果。比如create_branch這個(gè) tool輸入是{branch_name, base_branch}輸出是{success, branch_name, message}模型一看就知道成沒(méi)成。2.3 Skill 在這里扮演什么角色Skill 我的理解是給模型看的使用說(shuō)明書(shū) 編排模板。MCP tool 是能力Skill 是告訴模型在什么場(chǎng)景下、按什么順序、用哪些能力。比如我寫(xiě)了一個(gè)叫auto-pr的 Skill里面描述了標(biāo)準(zhǔn)流程先檢查狀態(tài)再?zèng)Q定是否創(chuàng)建分支再提交再推送最后創(chuàng)建 PR。模型讀到這個(gè) Skill 之后就知道遇到提 PR的請(qǐng)求該按什么套路走。這樣做的好處是流程邏輯不寫(xiě)在代碼里而是寫(xiě)在 Skill 的描述里。以后流程要改改 Skill 就行不用重新編譯 MCP server。這也是我覺(jué)得 MCP Skill 這套組合最有價(jià)值的地方能力與編排分離。3. 環(huán)境搭建Git 與 Azure DevOps 的對(duì)接準(zhǔn)備3.1 Git 側(cè)的配置細(xì)節(jié)Git 的安裝和配置網(wǎng)上教程一大堆我就不重復(fù)了只說(shuō)幾個(gè)容易忽略但很關(guān)鍵的點(diǎn)。第一個(gè)是用戶身份。MCP server 執(zhí)行 git commit 的時(shí)候用的是當(dāng)前系統(tǒng)用戶的 git config。如果你在 CI 環(huán)境或者容器里跑很可能沒(méi)配 user.name 和 user.emailcommit 會(huì)直接失敗。我的做法是在 MCP server 啟動(dòng)時(shí)先檢查這兩個(gè)配置沒(méi)有的話就用環(huán)境變量兜底git config --global user.name ${GIT_USER_NAME:-mcp-bot} git config --global user.email ${GIT_USER_EMAIL:-mcp-botexample.com}第二個(gè)是憑證管理。push 到遠(yuǎn)端需要認(rèn)證Azure DevOps 支持 PATPersonal Access Token或者 SSH key。我推薦用 PAT因?yàn)樗?HTTP 層面工作配置簡(jiǎn)單而且可以精細(xì)控制權(quán)限范圍。PAT 的權(quán)限只需要勾選Code (read write)就夠了不要給多余的權(quán)限。第三個(gè)是換行符?？缙脚_(tái)協(xié)作的時(shí)候 CRLF 和 LF 混用會(huì)導(dǎo)致整個(gè)文件顯示為改動(dòng)非常煩。建議在倉(cāng)庫(kù)根目錄放一個(gè).gitattributes強(qiáng)制統(tǒng)一* textauto eollf *.bat text eolcrlf3.2 Azure DevOps 的 PAT 與 API 端點(diǎn)Azure DevOps 的 REST API 基地址格式是https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version7.0創(chuàng)建 PR 用 POST請(qǐng)求體大概長(zhǎng)這樣{ sourceRefName: refs/heads/feature/xxx, targetRefName: refs/heads/main, title: PR 標(biāo)題, description: PR 描述, reviewers: [ { id: reviewer-uuid } ], workItemRefs: [ { id: 12345 } ] }注意幾個(gè)坑sourceRefName和targetRefName必須帶refs/heads/前綴少了會(huì)報(bào)錯(cuò)。reviewers里的id是用戶的 UUID不是郵箱也不是顯示名這個(gè) UUID 需要通過(guò) Graph API 查。workItemRefs關(guān)聯(lián)工作項(xiàng)的時(shí)候工作項(xiàng) ID 是字符串不是數(shù)字。PAT 的認(rèn)證方式是 HTTP Basic Auth用戶名隨便填通常填個(gè)pat或者空字符串密碼填 PATcurl -u :$PAT https://dev.azure.com/...3.3 MCP Server 的技術(shù)選型MCP server 我選了 Node.js TypeScript原因是官方 SDK 對(duì) TypeScript 支持最好而且 JSON 處理方便。核心依賴就兩個(gè)modelcontextprotocol/sdk和simple-git封裝 git 命令。HTTP 請(qǐng)求用 Node 18 自帶的 fetch不需要額外裝 axios。目錄結(jié)構(gòu)大概是這樣mcp-auto-pr/ ├── src/ │ ├── index.ts # MCP server 入口 │ ├── tools/ │ │ ├── git-status.ts │ │ ├── create-branch.ts │ │ ├── commit.ts │ │ ├── push.ts │ │ └── create-pr.ts │ ├── azure/ │ │ └── client.ts # Azure DevOps API 封裝 │ └── config.ts # 配置讀取 ├── skills/ │ └── auto-pr.md # Skill 描述文件 └── package.json4. 逐個(gè)實(shí)現(xiàn) MCP Tool從 git status 到 create PR4.1 git_status一切判斷的起點(diǎn)這個(gè) tool 的作用是讓模型知道當(dāng)前倉(cāng)庫(kù)的狀態(tài)。返回的信息包括當(dāng)前分支、是否有未提交改動(dòng)、未跟蹤文件列表、與遠(yuǎn)端的差異。import { simpleGit } from simple-git; export async function gitStatus(repoPath: string) { const git simpleGit(repoPath); const status await git.status(); const branch await git.revparse([--abbrev-ref, HEAD]); return { currentBranch: branch.trim(), isClean: status.isClean(), modified: status.modified, notAdded: status.not_added, created: status.created, deleted: status.deleted, ahead: status.ahead, behind: status.behind, }; }這里有個(gè)細(xì)節(jié)status.isClean()只判斷已跟蹤文件的改動(dòng)未跟蹤文件不算。所以我在返回里單獨(dú)列了not_added讓模型自己決定要不要處理。實(shí)際用下來(lái)模型看到有未跟蹤文件時(shí)會(huì)主動(dòng)問(wèn)用戶這些新文件要不要一起提交這個(gè)交互體驗(yàn)挺好的。4.2 create_branch命名規(guī)范要在這里落地分支命名我定了一套規(guī)范{type}/{workitem-id}-{short-desc}比如feature/12345-add-login。type 可以是 feature、fix、hotfix、chore。export async function createBranch( repoPath: string, branchName: string, baseBranch: string main ) { const git simpleGit(repoPath); // 先切到 base 分支并拉最新 await git.checkout(baseBranch); await git.pull(origin, baseBranch); // 創(chuàng)建并切換到新分支 await git.checkoutLocalBranch(branchName); return { success: true, branchName, baseBranch }; }為什么要先切到 base 再 pull因?yàn)槿绻苯釉诋?dāng)前分支創(chuàng)建新分支新分支會(huì)繼承當(dāng)前分支的狀態(tài)可能包含未推送的提交。先切到 base 并拉最新能保證新分支是從最新的主干切出來(lái)的減少后續(xù)合并沖突。注意如果工作區(qū)有未提交的改動(dòng)checkout會(huì)失敗或者把改動(dòng)帶過(guò)去。所以這個(gè) tool 應(yīng)該在git_status確認(rèn)工作區(qū)干凈之后再調(diào)用或者在內(nèi)部先做 stash。4.3 commitmessage 生成與暫存策略commit 這個(gè) tool 我設(shè)計(jì)成接收一個(gè) message 參數(shù)而不是讓模型自己拼 git 命令。暫存策略默認(rèn)是git add -A但支持傳入文件列表做精細(xì)控制。export async function commit( repoPath: string, message: string, files?: string[] ) { const git simpleGit(repoPath); if (files files.length 0) { await git.add(files); } else { await git.add(.); } const result await git.commit(message); return { success: true, commitHash: result.commit, summary: result.summary, }; }commit message 的規(guī)范我建議用 Conventional Commits格式是type(scope): subject。這個(gè)規(guī)范的好處是機(jī)器可讀后續(xù)可以自動(dòng)生成 changelog。我在 Skill 里明確告訴模型要按這個(gè)格式生成 message實(shí)測(cè)下來(lái)模型生成的質(zhì)量還不錯(cuò)比如feat(auth): add JWT token refresh logic。4.4 push處理 upstream 和沖突push 看起來(lái)簡(jiǎn)單其實(shí)坑不少。最常見(jiàn)的是新分支沒(méi)有 upstream直接git push會(huì)報(bào)錯(cuò)。所以要用git push -u origin branchName。export async function push( repoPath: string, branchName: string, setUpstream: boolean true ) { const git simpleGit(repoPath); const options setUpstream ? [-u, origin, branchName] : [origin, branchName]; const result await git.push(options); return { success: true, pushed: result.pushed, branch: branchName, }; }另一個(gè)坑是遠(yuǎn)端已經(jīng)有同名分支且歷史不一致。這種情況 push 會(huì)被拒絕需要 force push。但 force push 很危險(xiǎn)我堅(jiān)決不在 tool 里提供這個(gè)選項(xiàng)。如果遇到這種情況讓模型告訴用戶手動(dòng)處理這是安全底線。4.5 create_prAzure DevOps API 的封裝這是整個(gè)項(xiàng)目最核心的 tool。前面幾個(gè)都是本地操作這個(gè)才是真正跟 Azure DevOps 打交道的地方。export async function createPullRequest(params: { organization: string; project: string; repositoryId: string; sourceBranch: string; targetBranch: string; title: string; description: string; reviewerIds?: string[]; workItemIds?: string[]; pat: string; }) { const url https://dev.azure.com/${params.organization}/${params.project}/_apis/git/repositories/${params.repositoryId}/pullrequests?api-version7.0; const body { sourceRefName: refs/heads/${params.sourceBranch}, targetRefName: refs/heads/${params.targetBranch}, title: params.title, description: params.description, reviewers: (params.reviewerIds || []).map(id ({ id })), workItemRefs: (params.workItemIds || []).map(id ({ id })), }; const response await fetch(url, { method: POST, headers: { Content-Type: application/json, Authorization: Basic ${Buffer.from(:${params.pat}).toString(base64)}, }, body: JSON.stringify(body), }); if (!response.ok) { const errorText await response.text(); throw new Error(創(chuàng)建 PR 失敗: ${response.status} ${errorText}); } const data await response.json(); return { success: true, pullRequestId: data.pullRequestId, url: https://dev.azure.com/${params.organization}/${params.project}/_git/${params.repositoryId}/pullrequest/${data.pullRequestId}, }; }這里有個(gè)細(xì)節(jié)值得說(shuō)reviewer 的 UUID 怎么來(lái)。Azure DevOps 的 Graph API 可以按郵箱或顯示名查用戶GET https://vssps.dev.azure.com/{organization}/_apis/graph/users?api-version7.0返回的是所有用戶列表需要自己過(guò)濾。我建議在配置里維護(hù)一個(gè)郵箱 → UUID的映射表避免每次調(diào)用都查一遍。這個(gè)映射表可以定期更新或者第一次查完之后緩存起來(lái)。5. Skill 編排讓模型知道按什么順序干活5.1 Skill 描述文件的結(jié)構(gòu)Skill 文件我用 Markdown 寫(xiě)因?yàn)槟Ｐ妥x Markdown 最自然。內(nèi)容分三部分適用場(chǎng)景、可用工具、標(biāo)準(zhǔn)流程。# Skill: auto-pr ## 適用場(chǎng)景 當(dāng)用戶要求提交 PR、創(chuàng)建合并請(qǐng)求、把這個(gè)改動(dòng)提上去時(shí)使用。 ## 可用工具 - git_status: 檢查工作區(qū)狀態(tài) - create_branch: 創(chuàng)建并切換分支 - commit: 暫存并提交 - push: 推送到遠(yuǎn)端 - create_pr: 在 Azure DevOps 創(chuàng)建 PR ## 標(biāo)準(zhǔn)流程 1. 調(diào)用 git_status確認(rèn)當(dāng)前分支和工作區(qū)狀態(tài)。 2. 如果工作區(qū)不干凈根據(jù)改動(dòng)內(nèi)容生成 commit message調(diào)用 commit。 3. 如果當(dāng)前在 main 或 develop 等保護(hù)分支調(diào)用 create_branch 創(chuàng)建新分支。 4. 調(diào)用 push 推送當(dāng)前分支。 5. 調(diào)用 create_pr標(biāo)題和描述根據(jù) commit 內(nèi)容生成。 6. 如果分支名或 commit message 里有工作項(xiàng) ID在 create_pr 時(shí)關(guān)聯(lián)。5.2 為什么流程要寫(xiě)在 Skill 里而不是代碼里這是我在實(shí)際使用中體會(huì)最深的一點(diǎn)。一開(kāi)始我把流程硬編碼在 MCP server 里做一個(gè)auto_pr的大 tool內(nèi)部按順序調(diào)所有子操作。結(jié)果發(fā)現(xiàn)兩個(gè)問(wèn)題第一靈活性差。有時(shí)候用戶只想提交不想提 PR有時(shí)候分支已經(jīng)存在不需要?jiǎng)?chuàng)建硬編碼的流程沒(méi)法處理這些變體。第二調(diào)試?yán)щy。流程出問(wèn)題的時(shí)候你不知道是哪一步錯(cuò)了因?yàn)樗胁襟E都包在一個(gè) tool 里。改成 Skill 編排之后模型會(huì)根據(jù)實(shí)際情況決定調(diào)用哪些 tool。比如它看到工作區(qū)干凈、分支已存在、只是沒(méi)推送就會(huì)跳過(guò) commit 和 create_branch直接 push 然后 create_pr。這種靈活性是硬編碼給不了的。5.3 處理模型不聽(tīng)話的情況Skill 畢竟是自然語(yǔ)言描述模型不一定每次都嚴(yán)格照做。我遇到過(guò)幾種情況模型跳過(guò)了 git_status 直接 commit結(jié)果在有沖突的文件上操作失敗。模型生成的 commit message 不符合 Conventional Commits 格式。模型在保護(hù)分支上直接 commit 而沒(méi)有創(chuàng)建新分支。針對(duì)這些我的做法是在 tool 層面加校驗(yàn)。比如committool 內(nèi)部先檢查當(dāng)前分支是不是保護(hù)分支如果是就返回錯(cuò)誤提示模型先創(chuàng)建分支。create_prtool 校驗(yàn) sourceBranch 和 targetBranch 不能相同。這樣即使模型編排出錯(cuò)tool 層面也能兜住。提示Skill 是軟約束tool 的參數(shù)校驗(yàn)是硬約束。兩者結(jié)合才能保證流程可靠。6. 實(shí)測(cè)中踩過(guò)的坑與排查過(guò)程6.1 push 報(bào) ssh認(rèn)證失敗 的排查第一次跑通流程的時(shí)候push 一直失敗報(bào)的是 SSH 認(rèn)證錯(cuò)誤。我一開(kāi)始以為是 key 沒(méi)配好折騰了半天。后來(lái)發(fā)現(xiàn)根本原因是倉(cāng)庫(kù)的 remote URL 是 SSH 格式但我的 PAT 是給 HTTP 用的。排查過(guò)程是這樣的先git remote -v看 remote URL發(fā)現(xiàn)是gitssh.dev.azure.com:...這種格式。SSH 格式走的是 SSH key 認(rèn)證跟 PAT 沒(méi)關(guān)系。解決辦法有兩個(gè)要么配 SSH key要么把 remote URL 改成 HTTPS 格式。我選了后者因?yàn)?PAT 管理起來(lái)更方便git remote set-url origin https://dev.azure.com/{org}/{project}/_git/{repo}改完之后 push 就正常了。這個(gè)坑的教訓(xùn)是PAT 和 SSH key 是兩套認(rèn)證體系不能混用。用 PAT 就必須走 HTTPS。6.2 PR 創(chuàng)建成功但 reviewer 沒(méi)加上有幾次 PR 創(chuàng)建成功了但 reviewer 列表是空的。查了 API 返回發(fā)現(xiàn) reviewers 字段被忽略了。原因是傳的 UUID 格式不對(duì)。Azure DevOps 的 reviewer id 必須是完整的 UUID 格式比如a1b2c3d4-e5f6-7890-abcd-ef1234567890少一段或者格式不對(duì)都會(huì)被靜默忽略。排查方法是在創(chuàng)建 PR 之后再調(diào)一次 GET 接口查 PR 詳情看 reviewers 字段是不是空的。如果是空的就說(shuō)明 id 有問(wèn)題。我后來(lái)在代碼里加了一個(gè)校驗(yàn)UUID 必須匹配正則^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$不匹配的直接報(bào)錯(cuò)不靜默忽略。6.3 工作項(xiàng)關(guān)聯(lián)失敗的幾種情況關(guān)聯(lián)工作項(xiàng)也踩過(guò)坑。有一次傳了工作項(xiàng) ID但 PR 創(chuàng)建后工作項(xiàng)沒(méi)關(guān)聯(lián)上。查下來(lái)發(fā)現(xiàn)是工作項(xiàng) ID 傳成了數(shù)字類型而 API 要求字符串。改成字符串之后就好了。還有一種情況是工作項(xiàng)不存在或者沒(méi)權(quán)限訪問(wèn)。這種 API 會(huì)返回 400但錯(cuò)誤信息很模糊只說(shuō) Invalid work item reference。我的處理方式是在關(guān)聯(lián)之前先調(diào)工作項(xiàng)的查詢接口確認(rèn)存在不存在就跳過(guò)關(guān)聯(lián)并在返回里提示。6.4 大文件導(dǎo)致的 push 超時(shí)有一次提交了一個(gè)幾十 MB 的二進(jìn)制文件push 卡了很久最后超時(shí)。這個(gè)問(wèn)題的根源是倉(cāng)庫(kù)里不應(yīng)該有大文件。我的處理方式是在committool 里加一個(gè)文件大小檢查超過(guò) 10MB 的文件給出警告超過(guò) 50MB 直接拒絕提交。const MAX_FILE_SIZE 50 * 1024 * 1024; // 50MB // 在 add 之前遍歷文件檢查大小這個(gè)閾值可以根據(jù)團(tuán)隊(duì)實(shí)際情況調(diào)整。如果確實(shí)需要管理大文件應(yīng)該用 Git LFS而不是直接提交到倉(cāng)庫(kù)。7. 一些讓工具更好用的經(jīng)驗(yàn)補(bǔ)充7.1 配置文件的設(shè)計(jì)我把所有環(huán)境相關(guān)的配置抽到一個(gè)config.json里包括 organization、project、repositoryId、PAT、reviewer 映射表、保護(hù)分支列表。這樣換一個(gè)項(xiàng)目只需要改配置不用動(dòng)代碼。{ organization: my-org, project: my-project, repositoryId: my-repo, pat: ${AZURE_DEVOPS_PAT}, protectedBranches: [main, develop, release/*], reviewerMap: { aliceexample.com: uuid-1, bobexample.com: uuid-2 } }PAT 用環(huán)境變量占位符避免明文寫(xiě)在配置文件里。啟動(dòng)時(shí)做一次替換。7.2 日志與可觀測(cè)性MCP server 跑在后臺(tái)出問(wèn)題的時(shí)候如果沒(méi)日志會(huì)很難查。我在每個(gè) tool 的入口和出口都加了日志記錄輸入?yún)?shù)、執(zhí)行結(jié)果、耗時(shí)。日志寫(xiě)到文件里按天切割。logger.info(create_pr called, { sourceBranch, targetBranch, title }); const start Date.now(); // ... 執(zhí)行 logger.info(create_pr completed, { pullRequestId, duration: Date.now() - start });有了這些日志排查問(wèn)題的時(shí)候直接看日志就行不用復(fù)現(xiàn)。實(shí)測(cè)下來(lái)90% 的問(wèn)題看日志就能定位。7.3 冪等性處理網(wǎng)絡(luò)抖動(dòng)或者超時(shí)的時(shí)候模型可能會(huì)重試。如果 create_pr 被調(diào)用了兩次會(huì)創(chuàng)建兩個(gè)重復(fù)的 PR。所以我在 create_pr 里加了冪等檢查先查一下源分支有沒(méi)有已經(jīng)打開(kāi)的 PR有的話直接返回那個(gè) PR 的信息不重復(fù)創(chuàng)建。GET .../pullrequests?searchCriteria.sourceRefNamerefs/heads/{branch}searchCriteria.statusactive這個(gè)查詢返回當(dāng)前分支所有活躍的 PR如果有就直接復(fù)用。這樣即使重試也不會(huì)產(chǎn)生重復(fù) PR。7.4 關(guān)于 Skill 的版本管理Skill 文件我放在 git 倉(cāng)庫(kù)里跟代碼一起管理每次改 Skill 都走正常的 PR 流程。這樣做的好處是 Skill 的變更可追溯出問(wèn)題可以回滾。另外我在 Skill 文件頭部加了一個(gè)版本號(hào)方便排查模型用的是哪個(gè)版本的 Skill。!-- skill-version: 1.2.0 --模型讀到這個(gè)版本號(hào)在日志里也會(huì)帶上排查問(wèn)題的時(shí)候能對(duì)應(yīng)上。8. 關(guān)于這套方案的一些個(gè)人體會(huì)這套東西跑了大半年團(tuán)隊(duì)里現(xiàn)在提 PR 基本都是一句話的事。我最大的體會(huì)是MCP Skill 這套組合的價(jià)值不在于自動(dòng)化而在于可編排。傳統(tǒng)的腳本自動(dòng)化是線性的、固定的而 MCP 讓模型根據(jù)上下文動(dòng)態(tài)決定調(diào)用哪些能力這才是它真正區(qū)別于腳本的地方。另一個(gè)體會(huì)是安全邊界一定要在 tool 層面守住。Skill 是給模型看的模型可能理解偏差但 tool 的參數(shù)校驗(yàn)是代碼是確定性的。force push、刪除分支、修改保護(hù)分支這些危險(xiǎn)操作我堅(jiān)決不在 tool 里提供從源頭上杜絕誤操作。最后說(shuō)一個(gè)我覺(jué)得后續(xù)可以擴(kuò)展的方向現(xiàn)在 reviewer 是根據(jù)配置文件靜態(tài)映射的其實(shí)可以根據(jù)改動(dòng)的文件路徑動(dòng)態(tài)推斷。比如改了src/auth/下的文件就自動(dòng)找 auth 模塊的負(fù)責(zé)人。這個(gè)邏輯可以做成一個(gè)獨(dú)立的 tool讓 Skill 在創(chuàng)建 PR 之前調(diào)用。不過(guò)這個(gè)需要維護(hù)一份路徑 → 負(fù)責(zé)人的映射團(tuán)隊(duì)規(guī)模小的時(shí)候可能不劃算規(guī)模大了就很有價(jià)值。 基于MCP與Skill的Azure DevOps自動(dòng)提PR工具實(shí)現(xiàn)
1. 為什么我要自己造一個(gè)自動(dòng)提 PR 的輪子團(tuán)隊(duì)里用 Azure DevOps 做代碼托管已經(jīng)兩年多了日常開(kāi)發(fā)流程里最煩的其實(shí)不是寫(xiě)代碼而是每次改完一堆文件之后那套機(jī)械動(dòng)作切分支、寫(xiě) commit message、push、打開(kāi)瀏覽器、找到目標(biāo)倉(cāng)庫(kù)、點(diǎn) New Pull Request、填標(biāo)題、填描述、選 reviewer、關(guān)聯(lián)工作項(xiàng)。一套下來(lái)少說(shuō)五分鐘多的時(shí)候十分鐘就沒(méi)了而且這十分鐘里你腦子是空轉(zhuǎn)的純純的體力活。一開(kāi)始我也試過(guò)用現(xiàn)成的腳本糊一個(gè)比如寫(xiě)個(gè) bash 把 git 命令串起來(lái)再調(diào) Azure DevOps 的 REST API 創(chuàng)建 PR。能用但問(wèn)題很明顯腳本是死的參數(shù)全靠命令行傳稍微復(fù)雜一點(diǎn)的需求比如根據(jù)改動(dòng)文件自動(dòng)推斷 reviewer、根據(jù)分支名自動(dòng)關(guān)聯(lián)工作項(xiàng)就得改腳本。后來(lái) MCPModel Context Protocol這個(gè)概念火起來(lái)我意識(shí)到這東西天生適合干這種把多個(gè)工具串起來(lái)、由模型決定調(diào)用順序的活。MCP 本質(zhì)上是一個(gè)標(biāo)準(zhǔn)化的協(xié)議讓模型能夠以統(tǒng)一的方式調(diào)用外部工具而 Skill 則是把這些工具能力封裝成模型可以理解和編排的單元。所以這個(gè)項(xiàng)目的目標(biāo)就很明確了做一個(gè) MCP 工具把 Git 的本地操作和 Azure DevOps 的遠(yuǎn)端 API 串起來(lái)讓模型通過(guò) Skill 編排實(shí)現(xiàn)我說(shuō)一句把這個(gè)改動(dòng)提個(gè) PR它自己把剩下的事全干完。關(guān)鍵詞里的 MCP、Git、Azure DevOps、PR、Skill 這五個(gè)詞基本就是這個(gè)項(xiàng)目的全部骨架。這篇文章我會(huì)把整個(gè)實(shí)現(xiàn)過(guò)程拆開(kāi)講包括我踩過(guò)的坑、為什么這么設(shè)計(jì)、以及一些文檔里不會(huì)寫(xiě)的細(xì)節(jié)。先說(shuō)清楚適合誰(shuí)看如果你已經(jīng)在用 Azure DevOps 或者類似的代碼平臺(tái)日常有大量重復(fù)的提交 PR 操作并且對(duì) MCP 有基本了解哪怕只是聽(tīng)說(shuō)過(guò)那這篇能直接抄作業(yè)。如果你完全沒(méi)接觸過(guò) MCP也沒(méi)關(guān)系我會(huì)在講實(shí)現(xiàn)的時(shí)候把必要的背景補(bǔ)上但你需要對(duì) Git 的基本操作和 REST API 的調(diào)用方式有概念。2. 拆解需求這個(gè) MCP 工具到底要解決哪幾件事2.1 把提 PR這個(gè)動(dòng)作拆成原子能力很多人一上來(lái)就想做一個(gè)一鍵提 PR的大工具我覺(jué)得這是錯(cuò)的。MCP 的設(shè)計(jì)哲學(xué)是提供細(xì)粒度的工具讓模型去編排而不是做一個(gè)黑盒。所以我先把整個(gè)流程拆成了幾個(gè)原子操作檢查工作區(qū)狀態(tài)當(dāng)前在哪個(gè)分支、有沒(méi)有未提交的改動(dòng)、有沒(méi)有未跟蹤的文件。創(chuàng)建并切換分支根據(jù)命名規(guī)范生成分支名比如feature/xxx或fix/xxx。暫存與提交把改動(dòng) add 進(jìn)來(lái)生成符合規(guī)范的 commit message。推送到遠(yuǎn)端push 到 origin并設(shè)置 upstream。創(chuàng)建 PR調(diào)用 Azure DevOps REST API填標(biāo)題、描述、源分支、目標(biāo)分支、reviewer。關(guān)聯(lián)工作項(xiàng)如果分支名或 commit message 里有工作項(xiàng) ID自動(dòng)關(guān)聯(lián)。這六個(gè)操作每一個(gè)都做成獨(dú)立的 MCP tool模型可以根據(jù)實(shí)際情況決定調(diào)用哪些、跳過(guò)哪些。比如工作區(qū)是干凈的那就不需要 commit直接 push 就行比如分支已經(jīng)存在那就不需要?jiǎng)?chuàng)建。2.2 為什么不讓模型直接調(diào) git 命令有人會(huì)問(wèn)既然模型能執(zhí)行 shell 命令為什么不直接讓它跑git commit -m xxx我試過(guò)問(wèn)題在于不可控。模型生成的命令你沒(méi)法保證它每次都正確尤其是涉及路徑、分支名、特殊字符的時(shí)候一個(gè)引號(hào)沒(méi)處理好就出問(wèn)題。而且直接執(zhí)行 shell 命令沒(méi)有結(jié)構(gòu)化輸出模型拿到一堆文本還得自己解析容易出錯(cuò)。做成 MCP tool 的好處是輸入輸出都是結(jié)構(gòu)化的 JSON模型知道每個(gè)字段是什么含義調(diào)用之前可以先校驗(yàn)參數(shù)調(diào)用之后能拿到明確的結(jié)果。比如create_branch這個(gè) tool輸入是{branch_name, base_branch}輸出是{success, branch_name, message}模型一看就知道成沒(méi)成。2.3 Skill 在這里扮演什么角色Skill 我的理解是給模型看的使用說(shuō)明書(shū) 編排模板。MCP tool 是能力Skill 是告訴模型在什么場(chǎng)景下、按什么順序、用哪些能力。比如我寫(xiě)了一個(gè)叫auto-pr的 Skill里面描述了標(biāo)準(zhǔn)流程先檢查狀態(tài)再?zèng)Q定是否創(chuàng)建分支再提交再推送最后創(chuàng)建 PR。模型讀到這個(gè) Skill 之后就知道遇到提 PR的請(qǐng)求該按什么套路走。這樣做的好處是流程邏輯不寫(xiě)在代碼里而是寫(xiě)在 Skill 的描述里。以后流程要改改 Skill 就行不用重新編譯 MCP server。這也是我覺(jué)得 MCP Skill 這套組合最有價(jià)值的地方能力與編排分離。3. 環(huán)境搭建Git 與 Azure DevOps 的對(duì)接準(zhǔn)備3.1 Git 側(cè)的配置細(xì)節(jié)Git 的安裝和配置網(wǎng)上教程一大堆我就不重復(fù)了只說(shuō)幾個(gè)容易忽略但很關(guān)鍵的點(diǎn)。第一個(gè)是用戶身份。MCP server 執(zhí)行 git commit 的時(shí)候用的是當(dāng)前系統(tǒng)用戶的 git config。如果你在 CI 環(huán)境或者容器里跑很可能沒(méi)配 user.name 和 user.emailcommit 會(huì)直接失敗。我的做法是在 MCP server 啟動(dòng)時(shí)先檢查這兩個(gè)配置沒(méi)有的話就用環(huán)境變量兜底git config --global user.name ${GIT_USER_NAME:-mcp-bot} git config --global user.email ${GIT_USER_EMAIL:-mcp-botexample.com}第二個(gè)是憑證管理。push 到遠(yuǎn)端需要認(rèn)證Azure DevOps 支持 PATPersonal Access Token或者 SSH key。我推薦用 PAT因?yàn)樗?HTTP 層面工作配置簡(jiǎn)單而且可以精細(xì)控制權(quán)限范圍。PAT 的權(quán)限只需要勾選Code (read write)就夠了不要給多余的權(quán)限。第三個(gè)是換行符?？缙脚_(tái)協(xié)作的時(shí)候 CRLF 和 LF 混用會(huì)導(dǎo)致整個(gè)文件顯示為改動(dòng)非常煩。建議在倉(cāng)庫(kù)根目錄放一個(gè).gitattributes強(qiáng)制統(tǒng)一* textauto eollf *.bat text eolcrlf3.2 Azure DevOps 的 PAT 與 API 端點(diǎn)Azure DevOps 的 REST API 基地址格式是https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version7.0創(chuàng)建 PR 用 POST請(qǐng)求體大概長(zhǎng)這樣{ sourceRefName: refs/heads/feature/xxx, targetRefName: refs/heads/main, title: PR 標(biāo)題, description: PR 描述, reviewers: [ { id: reviewer-uuid } ], workItemRefs: [ { id: 12345 } ] }注意幾個(gè)坑sourceRefName和targetRefName必須帶refs/heads/前綴少了會(huì)報(bào)錯(cuò)。reviewers里的id是用戶的 UUID不是郵箱也不是顯示名這個(gè) UUID 需要通過(guò) Graph API 查。workItemRefs關(guān)聯(lián)工作項(xiàng)的時(shí)候工作項(xiàng) ID 是字符串不是數(shù)字。PAT 的認(rèn)證方式是 HTTP Basic Auth用戶名隨便填通常填個(gè)pat或者空字符串密碼填 PATcurl -u :$PAT https://dev.azure.com/...3.3 MCP Server 的技術(shù)選型MCP server 我選了 Node.js TypeScript原因是官方 SDK 對(duì) TypeScript 支持最好而且 JSON 處理方便。核心依賴就兩個(gè)modelcontextprotocol/sdk和simple-git封裝 git 命令。HTTP 請(qǐng)求用 Node 18 自帶的 fetch不需要額外裝 axios。目錄結(jié)構(gòu)大概是這樣mcp-auto-pr/ ├── src/ │ ├── index.ts # MCP server 入口 │ ├── tools/ │ │ ├── git-status.ts │ │ ├── create-branch.ts │ │ ├── commit.ts │ │ ├── push.ts │ │ └── create-pr.ts │ ├── azure/ │ │ └── client.ts # Azure DevOps API 封裝 │ └── config.ts # 配置讀取 ├── skills/ │ └── auto-pr.md # Skill 描述文件 └── package.json4. 逐個(gè)實(shí)現(xiàn) MCP Tool從 git status 到 create PR4.1 git_status一切判斷的起點(diǎn)這個(gè) tool 的作用是讓模型知道當(dāng)前倉(cāng)庫(kù)的狀態(tài)。返回的信息包括當(dāng)前分支、是否有未提交改動(dòng)、未跟蹤文件列表、與遠(yuǎn)端的差異。import { simpleGit } from simple-git; export async function gitStatus(repoPath: string) { const git simpleGit(repoPath); const status await git.status(); const branch await git.revparse([--abbrev-ref, HEAD]); return { currentBranch: branch.trim(), isClean: status.isClean(), modified: status.modified, notAdded: status.not_added, created: status.created, deleted: status.deleted, ahead: status.ahead, behind: status.behind, }; }這里有個(gè)細(xì)節(jié)status.isClean()只判斷已跟蹤文件的改動(dòng)未跟蹤文件不算。所以我在返回里單獨(dú)列了not_added讓模型自己決定要不要處理。實(shí)際用下來(lái)模型看到有未跟蹤文件時(shí)會(huì)主動(dòng)問(wèn)用戶這些新文件要不要一起提交這個(gè)交互體驗(yàn)挺好的。4.2 create_branch命名規(guī)范要在這里落地分支命名我定了一套規(guī)范{type}/{workitem-id}-{short-desc}比如feature/12345-add-login。type 可以是 feature、fix、hotfix、chore。export async function createBranch( repoPath: string, branchName: string, baseBranch: string main ) { const git simpleGit(repoPath); // 先切到 base 分支并拉最新 await git.checkout(baseBranch); await git.pull(origin, baseBranch); // 創(chuàng)建并切換到新分支 await git.checkoutLocalBranch(branchName); return { success: true, branchName, baseBranch }; }為什么要先切到 base 再 pull因?yàn)槿绻苯釉诋?dāng)前分支創(chuàng)建新分支新分支會(huì)繼承當(dāng)前分支的狀態(tài)可能包含未推送的提交。先切到 base 并拉最新能保證新分支是從最新的主干切出來(lái)的減少后續(xù)合并沖突。注意如果工作區(qū)有未提交的改動(dòng)checkout會(huì)失敗或者把改動(dòng)帶過(guò)去。所以這個(gè) tool 應(yīng)該在git_status確認(rèn)工作區(qū)干凈之后再調(diào)用或者在內(nèi)部先做 stash。4.3 commitmessage 生成與暫存策略commit 這個(gè) tool 我設(shè)計(jì)成接收一個(gè) message 參數(shù)而不是讓模型自己拼 git 命令。暫存策略默認(rèn)是git add -A但支持傳入文件列表做精細(xì)控制。export async function commit( repoPath: string, message: string, files?: string[] ) { const git simpleGit(repoPath); if (files files.length 0) { await git.add(files); } else { await git.add(.); } const result await git.commit(message); return { success: true, commitHash: result.commit, summary: result.summary, }; }commit message 的規(guī)范我建議用 Conventional Commits格式是type(scope): subject。這個(gè)規(guī)范的好處是機(jī)器可讀后續(xù)可以自動(dòng)生成 changelog。我在 Skill 里明確告訴模型要按這個(gè)格式生成 message實(shí)測(cè)下來(lái)模型生成的質(zhì)量還不錯(cuò)比如feat(auth): add JWT token refresh logic。4.4 push處理 upstream 和沖突push 看起來(lái)簡(jiǎn)單其實(shí)坑不少。最常見(jiàn)的是新分支沒(méi)有 upstream直接git push會(huì)報(bào)錯(cuò)。所以要用git push -u origin branchName。export async function push( repoPath: string, branchName: string, setUpstream: boolean true ) { const git simpleGit(repoPath); const options setUpstream ? [-u, origin, branchName] : [origin, branchName]; const result await git.push(options); return { success: true, pushed: result.pushed, branch: branchName, }; }另一個(gè)坑是遠(yuǎn)端已經(jīng)有同名分支且歷史不一致。這種情況 push 會(huì)被拒絕需要 force push。但 force push 很危險(xiǎn)我堅(jiān)決不在 tool 里提供這個(gè)選項(xiàng)。如果遇到這種情況讓模型告訴用戶手動(dòng)處理這是安全底線。4.5 create_prAzure DevOps API 的封裝這是整個(gè)項(xiàng)目最核心的 tool。前面幾個(gè)都是本地操作這個(gè)才是真正跟 Azure DevOps 打交道的地方。export async function createPullRequest(params: { organization: string; project: string; repositoryId: string; sourceBranch: string; targetBranch: string; title: string; description: string; reviewerIds?: string[]; workItemIds?: string[]; pat: string; }) { const url https://dev.azure.com/${params.organization}/${params.project}/_apis/git/repositories/${params.repositoryId}/pullrequests?api-version7.0; const body { sourceRefName: refs/heads/${params.sourceBranch}, targetRefName: refs/heads/${params.targetBranch}, title: params.title, description: params.description, reviewers: (params.reviewerIds || []).map(id ({ id })), workItemRefs: (params.workItemIds || []).map(id ({ id })), }; const response await fetch(url, { method: POST, headers: { Content-Type: application/json, Authorization: Basic ${Buffer.from(:${params.pat}).toString(base64)}, }, body: JSON.stringify(body), }); if (!response.ok) { const errorText await response.text(); throw new Error(創(chuàng)建 PR 失敗: ${response.status} ${errorText}); } const data await response.json(); return { success: true, pullRequestId: data.pullRequestId, url: https://dev.azure.com/${params.organization}/${params.project}/_git/${params.repositoryId}/pullrequest/${data.pullRequestId}, }; }這里有個(gè)細(xì)節(jié)值得說(shuō)reviewer 的 UUID 怎么來(lái)。Azure DevOps 的 Graph API 可以按郵箱或顯示名查用戶GET https://vssps.dev.azure.com/{organization}/_apis/graph/users?api-version7.0返回的是所有用戶列表需要自己過(guò)濾。我建議在配置里維護(hù)一個(gè)郵箱 → UUID的映射表避免每次調(diào)用都查一遍。這個(gè)映射表可以定期更新或者第一次查完之后緩存起來(lái)。5. Skill 編排讓模型知道按什么順序干活5.1 Skill 描述文件的結(jié)構(gòu)Skill 文件我用 Markdown 寫(xiě)因?yàn)槟Ｐ妥x Markdown 最自然。內(nèi)容分三部分適用場(chǎng)景、可用工具、標(biāo)準(zhǔn)流程。# Skill: auto-pr ## 適用場(chǎng)景 當(dāng)用戶要求提交 PR、創(chuàng)建合并請(qǐng)求、把這個(gè)改動(dòng)提上去時(shí)使用。 ## 可用工具 - git_status: 檢查工作區(qū)狀態(tài) - create_branch: 創(chuàng)建并切換分支 - commit: 暫存并提交 - push: 推送到遠(yuǎn)端 - create_pr: 在 Azure DevOps 創(chuàng)建 PR ## 標(biāo)準(zhǔn)流程 1. 調(diào)用 git_status確認(rèn)當(dāng)前分支和工作區(qū)狀態(tài)。 2. 如果工作區(qū)不干凈根據(jù)改動(dòng)內(nèi)容生成 commit message調(diào)用 commit。 3. 如果當(dāng)前在 main 或 develop 等保護(hù)分支調(diào)用 create_branch 創(chuàng)建新分支。 4. 調(diào)用 push 推送當(dāng)前分支。 5. 調(diào)用 create_pr標(biāo)題和描述根據(jù) commit 內(nèi)容生成。 6. 如果分支名或 commit message 里有工作項(xiàng) ID在 create_pr 時(shí)關(guān)聯(lián)。5.2 為什么流程要寫(xiě)在 Skill 里而不是代碼里這是我在實(shí)際使用中體會(huì)最深的一點(diǎn)。一開(kāi)始我把流程硬編碼在 MCP server 里做一個(gè)auto_pr的大 tool內(nèi)部按順序調(diào)所有子操作。結(jié)果發(fā)現(xiàn)兩個(gè)問(wèn)題第一靈活性差。有時(shí)候用戶只想提交不想提 PR有時(shí)候分支已經(jīng)存在不需要?jiǎng)?chuàng)建硬編碼的流程沒(méi)法處理這些變體。第二調(diào)試?yán)щy。流程出問(wèn)題的時(shí)候你不知道是哪一步錯(cuò)了因?yàn)樗胁襟E都包在一個(gè) tool 里。改成 Skill 編排之后模型會(huì)根據(jù)實(shí)際情況決定調(diào)用哪些 tool。比如它看到工作區(qū)干凈、分支已存在、只是沒(méi)推送就會(huì)跳過(guò) commit 和 create_branch直接 push 然后 create_pr。這種靈活性是硬編碼給不了的。5.3 處理模型不聽(tīng)話的情況Skill 畢竟是自然語(yǔ)言描述模型不一定每次都嚴(yán)格照做。我遇到過(guò)幾種情況模型跳過(guò)了 git_status 直接 commit結(jié)果在有沖突的文件上操作失敗。模型生成的 commit message 不符合 Conventional Commits 格式。模型在保護(hù)分支上直接 commit 而沒(méi)有創(chuàng)建新分支。針對(duì)這些我的做法是在 tool 層面加校驗(yàn)。比如committool 內(nèi)部先檢查當(dāng)前分支是不是保護(hù)分支如果是就返回錯(cuò)誤提示模型先創(chuàng)建分支。create_prtool 校驗(yàn) sourceBranch 和 targetBranch 不能相同。這樣即使模型編排出錯(cuò)tool 層面也能兜住。提示Skill 是軟約束tool 的參數(shù)校驗(yàn)是硬約束。兩者結(jié)合才能保證流程可靠。6. 實(shí)測(cè)中踩過(guò)的坑與排查過(guò)程6.1 push 報(bào) ssh認(rèn)證失敗 的排查第一次跑通流程的時(shí)候push 一直失敗報(bào)的是 SSH 認(rèn)證錯(cuò)誤。我一開(kāi)始以為是 key 沒(méi)配好折騰了半天。后來(lái)發(fā)現(xiàn)根本原因是倉(cāng)庫(kù)的 remote URL 是 SSH 格式但我的 PAT 是給 HTTP 用的。排查過(guò)程是這樣的先git remote -v看 remote URL發(fā)現(xiàn)是gitssh.dev.azure.com:...這種格式。SSH 格式走的是 SSH key 認(rèn)證跟 PAT 沒(méi)關(guān)系。解決辦法有兩個(gè)要么配 SSH key要么把 remote URL 改成 HTTPS 格式。我選了后者因?yàn)?PAT 管理起來(lái)更方便git remote set-url origin https://dev.azure.com/{org}/{project}/_git/{repo}改完之后 push 就正常了。這個(gè)坑的教訓(xùn)是PAT 和 SSH key 是兩套認(rèn)證體系不能混用。用 PAT 就必須走 HTTPS。6.2 PR 創(chuàng)建成功但 reviewer 沒(méi)加上有幾次 PR 創(chuàng)建成功了但 reviewer 列表是空的。查了 API 返回發(fā)現(xiàn) reviewers 字段被忽略了。原因是傳的 UUID 格式不對(duì)。Azure DevOps 的 reviewer id 必須是完整的 UUID 格式比如a1b2c3d4-e5f6-7890-abcd-ef1234567890少一段或者格式不對(duì)都會(huì)被靜默忽略。排查方法是在創(chuàng)建 PR 之后再調(diào)一次 GET 接口查 PR 詳情看 reviewers 字段是不是空的。如果是空的就說(shuō)明 id 有問(wèn)題。我后來(lái)在代碼里加了一個(gè)校驗(yàn)UUID 必須匹配正則^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$不匹配的直接報(bào)錯(cuò)不靜默忽略。6.3 工作項(xiàng)關(guān)聯(lián)失敗的幾種情況關(guān)聯(lián)工作項(xiàng)也踩過(guò)坑。有一次傳了工作項(xiàng) ID但 PR 創(chuàng)建后工作項(xiàng)沒(méi)關(guān)聯(lián)上。查下來(lái)發(fā)現(xiàn)是工作項(xiàng) ID 傳成了數(shù)字類型而 API 要求字符串。改成字符串之后就好了。還有一種情況是工作項(xiàng)不存在或者沒(méi)權(quán)限訪問(wèn)。這種 API 會(huì)返回 400但錯(cuò)誤信息很模糊只說(shuō) Invalid work item reference。我的處理方式是在關(guān)聯(lián)之前先調(diào)工作項(xiàng)的查詢接口確認(rèn)存在不存在就跳過(guò)關(guān)聯(lián)并在返回里提示。6.4 大文件導(dǎo)致的 push 超時(shí)有一次提交了一個(gè)幾十 MB 的二進(jìn)制文件push 卡了很久最后超時(shí)。這個(gè)問(wèn)題的根源是倉(cāng)庫(kù)里不應(yīng)該有大文件。我的處理方式是在committool 里加一個(gè)文件大小檢查超過(guò) 10MB 的文件給出警告超過(guò) 50MB 直接拒絕提交。const MAX_FILE_SIZE 50 * 1024 * 1024; // 50MB // 在 add 之前遍歷文件檢查大小這個(gè)閾值可以根據(jù)團(tuán)隊(duì)實(shí)際情況調(diào)整。如果確實(shí)需要管理大文件應(yīng)該用 Git LFS而不是直接提交到倉(cāng)庫(kù)。7. 一些讓工具更好用的經(jīng)驗(yàn)補(bǔ)充7.1 配置文件的設(shè)計(jì)我把所有環(huán)境相關(guān)的配置抽到一個(gè)config.json里包括 organization、project、repositoryId、PAT、reviewer 映射表、保護(hù)分支列表。這樣換一個(gè)項(xiàng)目只需要改配置不用動(dòng)代碼。{ organization: my-org, project: my-project, repositoryId: my-repo, pat: ${AZURE_DEVOPS_PAT}, protectedBranches: [main, develop, release/*], reviewerMap: { aliceexample.com: uuid-1, bobexample.com: uuid-2 } }PAT 用環(huán)境變量占位符避免明文寫(xiě)在配置文件里。啟動(dòng)時(shí)做一次替換。7.2 日志與可觀測(cè)性MCP server 跑在后臺(tái)出問(wèn)題的時(shí)候如果沒(méi)日志會(huì)很難查。我在每個(gè) tool 的入口和出口都加了日志記錄輸入?yún)?shù)、執(zhí)行結(jié)果、耗時(shí)。日志寫(xiě)到文件里按天切割。logger.info(create_pr called, { sourceBranch, targetBranch, title }); const start Date.now(); // ... 執(zhí)行 logger.info(create_pr completed, { pullRequestId, duration: Date.now() - start });有了這些日志排查問(wèn)題的時(shí)候直接看日志就行不用復(fù)現(xiàn)。實(shí)測(cè)下來(lái)90% 的問(wèn)題看日志就能定位。7.3 冪等性處理網(wǎng)絡(luò)抖動(dòng)或者超時(shí)的時(shí)候模型可能會(huì)重試。如果 create_pr 被調(diào)用了兩次會(huì)創(chuàng)建兩個(gè)重復(fù)的 PR。所以我在 create_pr 里加了冪等檢查先查一下源分支有沒(méi)有已經(jīng)打開(kāi)的 PR有的話直接返回那個(gè) PR 的信息不重復(fù)創(chuàng)建。GET .../pullrequests?searchCriteria.sourceRefNamerefs/heads/{branch}searchCriteria.statusactive這個(gè)查詢返回當(dāng)前分支所有活躍的 PR如果有就直接復(fù)用。這樣即使重試也不會(huì)產(chǎn)生重復(fù) PR。7.4 關(guān)于 Skill 的版本管理Skill 文件我放在 git 倉(cāng)庫(kù)里跟代碼一起管理每次改 Skill 都走正常的 PR 流程。這樣做的好處是 Skill 的變更可追溯出問(wèn)題可以回滾。另外我在 Skill 文件頭部加了一個(gè)版本號(hào)方便排查模型用的是哪個(gè)版本的 Skill。!-- skill-version: 1.2.0 --模型讀到這個(gè)版本號(hào)在日志里也會(huì)帶上排查問(wèn)題的時(shí)候能對(duì)應(yīng)上。8. 關(guān)于這套方案的一些個(gè)人體會(huì)這套東西跑了大半年團(tuán)隊(duì)里現(xiàn)在提 PR 基本都是一句話的事。我最大的體會(huì)是MCP Skill 這套組合的價(jià)值不在于自動(dòng)化而在于可編排。傳統(tǒng)的腳本自動(dòng)化是線性的、固定的而 MCP 讓模型根據(jù)上下文動(dòng)態(tài)決定調(diào)用哪些能力這才是它真正區(qū)別于腳本的地方。另一個(gè)體會(huì)是安全邊界一定要在 tool 層面守住。Skill 是給模型看的模型可能理解偏差但 tool 的參數(shù)校驗(yàn)是代碼是確定性的。force push、刪除分支、修改保護(hù)分支這些危險(xiǎn)操作我堅(jiān)決不在 tool 里提供從源頭上杜絕誤操作。最后說(shuō)一個(gè)我覺(jué)得后續(xù)可以擴(kuò)展的方向現(xiàn)在 reviewer 是根據(jù)配置文件靜態(tài)映射的其實(shí)可以根據(jù)改動(dòng)的文件路徑動(dòng)態(tài)推斷。比如改了src/auth/下的文件就自動(dòng)找 auth 模塊的負(fù)責(zé)人。這個(gè)邏輯可以做成一個(gè)獨(dú)立的 tool讓 Skill 在創(chuàng)建 PR 之前調(diào)用。不過(guò)這個(gè)需要維護(hù)一份路徑 → 負(fù)責(zé)人的映射團(tuán)隊(duì)規(guī)模小的時(shí)候可能不劃算規(guī)模大了就很有價(jià)值。