VS Code Sessions 内置 create-pr 技能解析：技能文件格式、六步工作流与触发机制

2026-09-07 14:29:48作者：丁柯新Fawn

VS Code 的 Agents Window（vs/sessions）把"创建 Pull Request"封装成一个内置技能（skill）——create-pr。本篇以仓库中 src/vs/sessions/skills/create-pr/SKILL.md 为主体，完整拆解该技能的文件结构、六步执行工作流、依赖的 /commit 子技能，以及 Changes 工具栏"Create PR"按钮如何在源码层面触发这个技能，并说明如何自定义覆盖其内置行为。

一、create-pr 在 Sessions 中的定位

SKILL.md 是 Agents Window 内置技能之一。src/vs/sessions/README.md 对该目录下技能文件的定位给出了明确约定：

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

也就是说，这些 Markdown 文件不是普通文档，而是会被分发进每一个 agent-host 会话、由 Agent 按步骤执行的工作流脚本。src/vs/sessions/skills/ 目录下与 PR 生命周期相关的内置技能包括：

技能目录	技能名	职责
create-pr	`create-pr`	为当前会话的改动创建正式 PR
create-draft-pr	`create-draft-pr`	创建草稿 PR
update-pr	`update-pr`	同步/更新已有 PR
merge	`merge`	合并变更
commit	`commit`	生成符合仓库风格的提交
fix-ci、code-review、troubleshoot 等	—	CI 修复、代码评审、排障等配套工作流

二、技能文件的完整结构

SKILL.md 全文由 YAML frontmatter 与 Markdown 工作流正文两部分组成。

2.1 Frontmatter：name 与 description

---
name: create-pr
description: Create a pull request for the current session. Use when the user wants to open a PR with the session's changes.
---

name：技能标识，与目录名一致。Agent 通过 /<name> 斜杠命令引用技能（例如 /create-pr），工具栏按钮触发的也正是这个命令形式（见第四节）。
description：同时承担"能力说明"与"触发意图"两个作用——前半句说明技能做什么，"Use when …"部分描述何时该调用它。

2.2 工作流正文：六步完整继承

正文给出了工具选择策略与六个执行步骤（原文步骤逐条继承，未删减）：

工具选择策略：优先使用 GitHub MCP server 创建 PR；不可用时回退到 gh CLI。

六步工作流：

步骤	操作	要点
1	运行编译与卫生（hygiene）任务	如有错误必须先修复，保证 PR 基于可构建的代码
2	若存在未提交变更，调用 `/commit` 技能提交	复用内置 commit 技能的约定发现与消息生成逻辑（见第三节）
3	审阅当前会话的全部变更	确保 PR 内容与本次会话工作一致
4	撰写 PR 标题	简洁、带短小领域前缀，如 `sessions: …`、`editor: …`
5	撰写 PR 描述	覆盖改了什么（what）、为什么改（why）、评审者需要知道的事项
6	创建 Pull Request	传入 `show_ui=false`，使 PR 在无确认 UI 的情况下静默创建

其中第 6 步的 show_ui=false 是一个关键参数：它让创建动作绕过交互式确认界面，与工具栏按钮"一键触发、Agent 代跑"的产品形态相匹配——用户点击按钮后，Agent 独立完成从检查、提交到开 PR 的整条链路。

三、依赖的 `/commit` 技能：步骤 2 的完整行为

create-pr 的第 2 步委托给了 commit/SKILL.md。理解它，才能理解 create-pr 为什么敢在开 PR 前自动提交。commit 技能定义了一条五步工作流与一组安全红线：

安全红线（Guidelines）：

未经询问绝不 amend 已有提交；
未经用户明确批准绝不 force-push 或 push；
绝不跳过 pre-commit hooks（禁用 --no-verify）；
绝不跳过提交签名（禁用 --no-gpg-sign）；
除非用户明确要求，绝不 revert/reset/丢弃用户改动；
发现疑似密钥或生成产物时先询问用户。

五步工作流：

发现仓库提交约定——采样近期提交与用户自己的提交风格：
```
# 仓库整体风格
git log --oneline -20
# 用户个人风格
git log --oneline --author="$(git config user.name)" -10
```
据此判断仓库使用 Conventional Commits、Gitmoji、ticket 前缀还是自由格式，生成的消息必须遵循检测到的约定。
检查仓库状态（git status --short）：无变更则告知并停止；有暂存变更则只提交暂存区；仅有未暂存变更则 git add -A 后提交。
生成提交消息——基于 git diff --cached --stat 与完整 diff：主题行 ≤ 72 字符并遵循仓库约定；diff 非平凡时才写 body 解释"为什么"；分支名或上下文中出现 issue/ticket 编号时予以引用；聚焦变更意图而非逐文件清单。
执行提交：git commit -m "<subject>" -m "<body>"。
确认——git status --short 与 git log --oneline -1 验证结果；若 hooks 修改了文件或阻断提交，如实汇报且不自动 amend，由用户决定是否追加提交。

正是这套"先检测约定、再按约定生成"的机制，让 create-pr 步骤 4 中"标题带领域前缀"的要求与步骤 2 自动产生的提交在风格上保持一致。

四、从 UI 到技能：工具栏按钮的源码级触发链路

create-pr 技能并非只能手动输入斜杠命令。src/vs/sessions/contrib/providers/agentHost/browser/agentHostSkillButtons.ts 为所有 agent-host-* 会话（本地或远程）在 Changes 视图工具栏注册了四个内置技能按钮：merge / create-pr / create-draft-pr / update-pr。

4.1 按钮注册与显示条件（when 子句）

create-pr 按钮（源码 agentHostSkillButtons.ts#L102-L116）的菜单可见条件是各上下文的合取：

extraWhen: ContextKeyExpr.and(
  ContextKeyExpr.false(),
  ActiveSessionContextKeys.IsolationMode.isEqualTo(IsolationMode.Worktree), // 会话必须运行在 worktree 隔离模式
  ActiveSessionContextKeys.HasGitHubRemote,                                // 仓库必须有 GitHub 远端
  ActiveSessionContextKeys.HasPullRequest.negate(),                        // 会话尚无已存在的 PR
  ContextKeyExpr.or(ActiveSessionContextKeys.HasUncommittedChanges,
                   ActiveSessionContextKeys.HasOutgoingChanges),           // 有未提交或待推送变更
),

再叠加外层公共条件（同文件 #L177-L188）：必须处于 Sessions 窗口（IsSessionsWindowContext）、活动会话来自 agent-host provider（IsAgentHostSession，由同文件 #L49-L56 依据 provider 类型绑定）、且存在 Git 仓库（HasGitRepository）。

也就是说，"Create PR"按钮只在"worktree 会话 + GitHub 远端 + 尚无 PR + 有待交付变更"这一精确状态下出现，与 SKILL.md 第 6 步"直接创建、不弹确认 UI"的假设互为配套：出现按钮时，创建 PR 的前置条件已经由 UI 层判定完毕。

4.2 点击后的命令注入：发送 `/create-pr` 聊天请求

按钮的 run 实现（同文件 #L191-L221）核心只有三步：

const agentId = activeSession.resource.scheme;   // 会话贡献注册的 agent id（如 agent-host-copilotcli）
const prompt = `/${spec.skill}`;                 // 即 "/create-pr"
let result = await chatService.sendRequest(
  activeSession.resource, prompt, { agentIdSilent: agentId });

按钮等价于用户手动输入 /create-pr——技能内容随会话分发后，Agent 按 SKILL.md 正文执行六步工作流；
使用 agentIdSilent 静默路由到指定 agent，避免占用可见聊天入口；
若请求被排队（ChatSendResult.isQueued），会等待既有对话结束后自动补发，并在 responseCompletePromise 上等待技能执行完成；
源码注释还说明了技能的分发方式：这些内置技能由 synced customization bundler 以 BUILTIN_STORAGE 的 PromptsType.skill 条目打包进每个 agent-host 会话。

aiCustomizationWorkspaceService.ts#L287 中对该技能在定制管理视图中的描述与之呼应：create-pr 被标注为"Used by the Create PR button in the Changes toolbar"（由 Changes 工具栏的 Create PR 按钮使用）。

五、自定义与覆盖内置行为

SKILL.md 第 5 行留有一个 HTML 注释，它实际描述了技能的覆盖机制：

<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. -->

即：复制并自定义该技能后保存，即可用自定义副本覆盖内置行为；删除该副本则恢复内置工作流。结合 src/vs/sessions/AI_CUSTOMIZATIONS.md 的定制架构（workspace、user、extension、built-in 等多来源的 customization item 管道），可以看到 create-pr 属于 built-in 来源：内置技能通过 BUILTIN_STORAGE 进入每个 agent-host 会话，而用户/工作区副本在 item 管道中覆盖同名内置项。此外目录中还有一个元技能 update-skills，用于对技能本身进行更新维护。

六、关键路径汇总

内容	路径
本文主角：create-pr 技能定义	src/vs/sessions/skills/create-pr/SKILL.md
被依赖的 commit 技能	src/vs/sessions/skills/commit/SKILL.md
工具栏按钮注册与 `/create-pr` 注入逻辑	src/vs/sessions/contrib/providers/agentHost/browser/agentHostSkillButtons.ts
技能在定制视图中的角色描述	src/vs/sessions/contrib/chat/browser/aiCustomizationWorkspaceService.ts
技能文件定位说明	src/vs/sessions/README.md
定制来源与 item 管道架构	src/vs/sessions/AI_CUSTOMIZATIONS.md
按钮可见条件的行为测试	src/vs/sessions/contrib/changes/test/browser/changesViewActions.test.ts

小结：create-pr 技能用 16 行 Markdown 定义了一条完整的交付链路——先保证可构建（编译+hygiene）、再复用 /commit 技能按仓库风格提交、审阅会话全部变更、按"领域前缀 + what/why"规范生成标题与描述、最后以 show_ui=false 静默开 PR，工具优先选 GitHub MCP server 并回退 gh CLI。UI 层用一组上下文键（worktree、GitHub 远端、无既有 PR、有变更）把按钮的出现时机与技能假设对齐，点击按钮等价于向会话注入 /create-pr 请求；而文件头部的 HTML 注释则保留了"副本覆盖内置、删除副本还原"的自定义逃生通道。理解这套"Markdown 即工作流 + 上下文键门控 + 斜杠命令注入"的三件套，就掌握了 Agents Window 内置技能的设计范式。

vscode

Visual Studio Code

项目地址：https://gitcode.com/GitHub_Trending/vscode6/vscode

登录后查看全文