VS Code Agents Window 内置技能解析：create-draft-pr 从 SKILL.md 工作流到“Create Draft PR”按钮的实现链路

2026-09-07 14:26:22作者：伍霜盼Ellen

本文以 create-draft-pr/SKILL.md 为核心，完整解读 VS Code Agents Window（vs/sessions 层）中“创建草稿 Pull Request”这一内置技能的定义结构、六步执行流程、与 /commit 技能的依赖关系，并结合源码说明该技能如何被聊天斜杠命令与 Changes 工具栏按钮触发、在 Agent Host 侧对应哪些 Changeset 操作。读完后可掌握：Skills 文件的前置元数据契约、技能被打包进 Agent 会话的机制，以及从 UI 按钮到 PR 创建操作的下行链路。

一、定位：Agents Window 中的“可执行产品工作流”

vs/sessions 目录实现了位于 vs/workbench 之上的 Agents Window 顶层。其 README 明确了不同 Markdown 文件的职责边界，其中与本文直接相关的定义是：

skills/*/SKILL.md files are executable product workflows;（skills 目录下的 SKILL.md 文件是“可执行的产品工作流”）

也就是说，src/vs/sessions/skills/ 下的每一个目录都是一个 Agent 会话可调用的完整工作流。该目录下当前内置的技能包括 commit、create-pr、create-draft-pr、merge、update-pr、sync、sync-upstream、fix-ci、troubleshoot、code-review、act-on-feedback、generate-run-commands、update-skills 等，构成一组覆盖“提交 → 建 PR → 合并 → 同步上游”的 Git/GitHub 协作闭环。本文聚焦其中的 create-draft-pr。

二、文件解剖：前置元数据与定制提示

完整的 SKILL.md 内容如下（原文逐行继承）：

---
name: create-draft-pr
description: Create a draft pull request for the current session. Use when the user wants to open a draft PR with the session's changes.
---
<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. -->

# Create Draft Pull Request

Use the GitHub MCP server to create a draft pull request if available, otherwise use `gh` CLI.

1. Run the compile and hygiene tasks (fixing any errors)
2. If there are any uncommitted changes, use the `/commit` skill to commit them
3. Review all changes in the current session
4. Write a clear, concise PR title with a short area prefix (e.g. "sessions: …", "editor: …")
5. Write a description covering what changed, why, and anything reviewers should know
6. Create the draft pull request

YAML 前置元数据

字段	值	作用
`name`	`create-draft-pr`	技能唯一标识，是斜杠命令 `/create-draft-pr` 与按钮 `skill` 字段匹配的名字
`description`	"Create a draft pull request for the current session. Use when the user wants to open a draft PR with the session's changes."	供 Agent/补全引擎判断“何时该调用该技能”的自然语言描述

前置元数据中的 name 并非展示名，而是路由键：源码 agentHostSkillButtons.ts 中“Create Draft PR”按钮的 skill 字段就是字符串 'create-draft-pr'，按钮点击时“发送与用户手动输入相同的 /<skill-name> 提示”。

定制覆盖机制

文件内的 HTML 注释给出了明确的定制契约：

Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior.（定制该技能并选择“保存”即可覆盖其行为；删除该副本即可恢复内置行为。）

即内置技能是可被用户派生覆盖的：在定制编辑器中修改并保存后，会话优先使用用户的副本；删除副本则回退到仓库内置版本。

三、六步工作流详解

技能正文先给出工具选择策略——优先使用 GitHub MCP server 创建草稿 PR，不可用时回退到 gh CLI——随后是六步流程。下面逐步拆解，并对照仓库中的关联实现。

步骤 1：先跑编译与卫生检查任务（并修复错误）

Run the compile and hygiene tasks (fixing any errors)。这一步保证进入 PR 的改动是可编译、可校验的基线，把“修错误”的职责前置到 PR 创建之前，避免把已知损坏提交到远端分支。

步骤 2：存在未提交改动时调用 `/commit` 技能

If there are any uncommitted changes, use the /commit skill to commit them。这里的 /commit 指向同目录下的 commit/SKILL.md，它是一个完整可执行工作流：先 git log --oneline -20 采样仓库与个人近期提交以探测提交规范，再用 git status --short 区分“无改动/已暂存/仅未暂存”三种状态决定暂存策略，然后基于 git diff --cached 生成符合仓库惯例的提交信息（主题行 ≤ 72 字符），最后以 git commit -m "<subject>" -m "<body>" 提交并复核。该技能同时内建了硬约束：未询问不得 amend、未获批准不得 push、禁用 --no-verify 与 --no-gpg-sign、不得回滚/重置用户改动。create-draft-pr 第 2 步把这套约束复用过来，保证草稿 PR 的提交信息质量与安全性由既有契约兜底。

步骤 3：回顾当前会话的全部改动

Review all changes in the current session。注意措辞是“session”而非“branch”：Agents Window 的会话自带隔离的改动集（changeset），这一步要求 Agent 以整个会话的变更面为对象做整体审视，为标题与描述提供事实依据。

步骤 4：写带“区域前缀”的 PR 标题

Write a clear, concise PR title with a short area prefix (e.g. "sessions: …", "editor: …")。区域前缀（area prefix）让 reviewer 一眼定位改动模块，例如 sessions: …、editor: …。这一约定与 VS Code 仓库自身的 PR 标题习惯一致。

步骤 5：写覆盖“改了什么、为什么、reviewer 须知”的描述

Write a description covering what changed, why, and anything reviewers should know。三段式要求对应了评审所需的完整上下文：变更内容（what）、动机（why）、评审注意点（reviewer notes）。

步骤 6：创建草稿 PR

结合文首的工具选择策略（GitHub MCP server 优先，gh CLI 兜底），执行最终的草稿 PR 创建动作。草稿状态意味着 PR 可先行挂载 CI 与评审上下文，但不会进入“可合并”流程。

四、技能如何被触发：斜杠命令与 Changes 工具栏按钮

斜杠命令

create-draft-pr 的 name 在 Copilot CLI 扩展侧注册为内置斜杠命令：见 builtinSlashCommands.ts 中的 createDraftPr: '/create-draft-pr'。在聊天输入框键入 /create-draft-pr 即触发该技能，这也是所有技能按钮的统一触发方式。

“Create Draft PR”工具栏按钮

agentHostSkillButtons.ts 为任意 agent-host-* 会话的 Changes 视图贡献四个技能按钮：merge、create-pr、create-draft-pr、update-pr。按钮规格（IAgentHostSkillButtonSpec）包含 id（形如 workbench.action.agentSessions.runSkill.createDraftPR）、本地化标题、skill 名、图标（草稿 PR 用 Codicon.gitPullRequestDraft）、分组与排序，以及上下文条件 extraWhen。其中 create-draft-pr 按钮的显示条件（L117-L131）为：

隔离模式为 Worktree（IsolationMode.Worktree）；
仓库具有 GitHub 远端（HasGitHubRemote）；
分支尚无 PR（HasPullRequest 取反）；
存在未提交改动或待推送提交（HasUncommittedChanges / HasOutgoingChanges 之一成立）。

条件不满足时按钮不渲染，避免在“无改动”或“已有 PR”的状态下误触发。文件注释同时说明了技能的装载机制：这些内置技能经 synced customization bundler 以 BUILTIN_STORAGE 的 PromptsType.skill 条目打包进每个 agent-host 会话，用户无需手动安装。

定制管理视图中的说明文案

在 AI 定制管理视图中，aiCustomizationWorkspaceService.ts 对 create-draft-pr 给出固定注解："Used by the Create Draft PR button in the Changes toolbar"（由 Changes 工具栏的 Create Draft PR 按钮使用）。当用户按前述机制定制覆盖该技能时，这条文案提示其影响面——修改将直接改变工具栏按钮的行为。

五、Agent Host 侧的 Changeset 操作映射

技能是“提示词层”的入口；真正执行 PR 创建的是 Agent Host 节点进程中的 Changeset 操作体系。agentHostPullRequestOperationProvider.ts 在“分支尚无 PR”的状态下暴露一组操作（create-pr、create-pr-auto-merge、create-pr-auto-squash、create-pr-auto-rebase，以及 create-draft-pr），其中草稿 PR 操作定义为：

{
  id: 'create-draft-pr',
  label: localize('agentHost.changeset.createDraftPR', "Create Draft PR"),
  icon: 'git-pull-request-draft',
  group: 'pull-request_draft',
  scopes: [ChangesetOperationScope.Changeset],
  status: ChangesetOperationStatus.Idle,
}

agentHostPullRequestOperationHandler.ts 进一步定义了处理侧的操作常量 OPERATION_CREATE_DRAFT_PR = 'create-draft-pr' 与 OPERATION_CREATE_DRAFT_PR_AGENT_MERGE = 'create-draft-pr-agent-merge'——后者在 Agent Merge 功能开启时追加为“Create Draft PR & Agent Merge”变体（由 Provider 中 _isAgentMergeEnabled() 读取根配置决定）。单元测试 agentHostPullRequestOperationProvider.test.ts 验证了草稿 PR 操作及其 Agent Merge 变体的 id/label 输出，E2E 套件 changesetSuite.ts 则将 create-draft-pr 归入 pull-request_draft 组做端到端覆盖。由此形成“按钮/斜杠命令 → 技能提示词 → Agent 执行 → Changeset 操作”的完整链路，且每一步都有测试兜底。

六、与 create-pr 的对照：草稿 PR 与正式 PR 的差异

同目录下的 create-pr/SKILL.md 与本文技能的前五步完全一致（同样的 MCP 优先策略、同样的六步骨架），唯一差异在最后一步：

Create the pull request, passing show_ui=false so the PR is created without opening a confirmation UI.（创建 PR 时传入 show_ui=false，使 PR 在不弹出确认 UI 的情况下直接创建。）

也就是说，正式 PR 路径要求静默创建、跳过确认界面；而 create-draft-pr 保持草稿状态，本身即作为“先行创建、暂缓合并”的确认手段。二者共用同一套触发按钮分组（pull_request vs pull-request_draft/pull_request_draft 组）与 Changeset 操作框架。

小结

create-draft-pr/SKILL.md 虽短，却是一个完整的可执行工作流契约：YAML 前置元数据提供 name（路由键）与 description（调用时机）；六步流程规定了“编译卫生 → 借助 /commit 规范化提交 → 会话级改动回顾 → 区域前缀标题 → 三段式描述 → MCP/gh 双通道创建草稿 PR”的标准动作；顶注则定义了“派生覆盖、删除即回退”的定制机制。仓库源码进一步印证了它的落地路径——/create-draft-pr 斜杠命令注册（builtinSlashCommands.ts）、Changes 工具栏按钮及其上下文显示条件（agentHostSkillButtons.ts）、定制管理视图的影响面提示（aiCustomizationWorkspaceService.ts），以及 Agent Host 侧 create-draft-pr/create-draft-pr-agent-merge Changeset 操作与测试覆盖（agentHostPullRequestOperationProvider.ts、agentHostPullRequestOperationHandler.ts）。理解这一技能即可作为模板，掌握 VS Code Agents Window 中“技能定义 → 触发入口 → 宿主操作”三层协作的通用模式。