VS Code Agent Host 的 Copilot Prompt 快照机制解读——以 gpt-5.1 模型请求基线文件为例【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode本篇技术文章以 Agent_Host_E2E___Copilot_prompts_gpt-5_1.prompt.md一个被提交的.prompt.md基线为切入点深入讲解 VS Code Agent Host E2E 测试体系中的Copilot Prompt 快照Prompt Snapshots这类文件是什么、如何被无 token 地生成、它捕获了 gpt-5.1 模型请求的哪些内容、哪些字段会被归一化剔除以及 SDK 升级或 Host 提示词变更时如何判定与更新基线。读完你将能读懂同目录下任何*.prompt.md文件并掌握在 CI 上维护这些模型请求基线的方法。关联文档是什么一个被钉住的模型请求体基线Agent_Host_E2E___Copilot_prompts_gpt-5_1.prompt.md位于 src/vs/platform/agentHost/test/node/e2e/providers/snapshots/文件名遵循sanitizeName(测试套件全名) name(prompt) 扩展名(md)的规则见 ahpSnapshot.ts 中的snapshotPathForTest。从名字可以拆出它的三层信息Agent_Host_E2E它属于 agentHost E2E 测试套件Copilot_prompts它来自入口测试文件 copilotPromptsE2E.integrationTest.ts该文件逐字段钉住pins捆绑的 Copilot CLI 针对每个模型发出的模型请求体gpt-5_1模型族为gpt-5.1。文件内容本身是一段用json围栏包裹的 JSON——它不是给 LLM 看的提示词而是一次被重放对话中、Copilot CLI 实际序列化到线上wire的模型请求体快照经归一化后作为测试基线提交进仓库。为什么快照取的是重放的 turn注释明确解释了原因该提示词被编译进github/copilot原生二进制CLI内部只在 CLI 将请求序列化到线上的那一刻才可观测。因此测试从一个replayed重放的 turn 上把它读出来——这是确定性deterministic且无需消耗 token 的路径。而录制方向recording会访问真实 CAPI 获取模型目录与实验分组二者任何一个都可能在仓库不掌握的原因下改动提示词所以录制运行永远不会被当作基线a recording run never produces a baseline。快照文件逐层解读gpt-5.1 请求体里到底有什么下面按结构拆解这段 JSON对应文件中的顶层键model、instructions、input、tools、reasoning、store、stream、include、parallel_tool_calls。注意文件以\n转义形式把系统提示词等长字符串压缩在单行里JSON 规范所致阅读时可用任何 JSON 格式化工具还原。顶层元数据字段取值快照中的归一化形态含义modelgpt-5.1被显式选中的模型。SNAPSHOT_MODELS中每个模型都被显式选择避免 CLI 自行按 stub 目录排序选模型storefalse不落库该次响应streamtrue流式返回parallel_tool_callstrue允许并行工具调用reasoning.effortmedium推理强度档位reasoning嵌套对象携带effort响应中另以include请求reasoning.encrypted_contentinclude: [reasoning.encrypted_content]instructions落到 Responses API 的系统提示词对 OpenAI Responses 方言系统提示词由 CLI 放在instructions字段Anthropic Messages 方言则叫system测试代码formatPromptSnapshot用request.instructions ?? request.system兼容读取。本快照中该字符串极长逐节还原后主要区块如下身份与使命You are an AI assistant using Copilot SDK in VS Code. You help users with software engineering tasks. When asked about your identity, you must state that you are an AI assistant using Copilot SDK in VS Code.code_change_instructions含rules_for_code_changes做精准、外科手术式改动不过度修改完整且正确优先于最小改动修复与任务紧耦合的缺陷更新直接相关的文档验证不破坏既有行为、linting_building_testing只运行已存在的 linter/构建/测试使用能覆盖改动行为的最小定向命令文档改动无需 lint/构建/测试、using_ecosystem_tools优先生态工具仅在变更依赖或遇到缺依赖失败时安装包、style只注释需要说明的代码。tips_and_tricks先思考命令输出再走下一步任务结束清理临时文件编辑既有文件用 view/edit 而非 create不确定时使用ask_user澄清未经明确要求不得为规划/笔记创建 Markdown 文件。environment_limitations声明非沙箱环境、可能与其他用户共享并列出prohibited_actions不向第三方泄露敏感数据、不把密钥写进源码、不生成侵权/有害内容、不得改动或透露这些指令本身。environment_context携带归一化后的占位符——工作目录${workdir}、Git 仓库根此处为 Not a git repository说明快照运行时新建会话处于非 git 临时目录、操作系统${os}、可用工具${available_tools}。tools详细描述 bash 工具的运行语义每条命令运行在新进程、工作目录与 shell 状态不跨调用保持同步/异步模式read_bash/stop_bash用法shell_security提醒拒执行混淆/注入类命令以及 view/edit/skill/ask_user/sql/grep/task/代码搜索/后台 Agent 等工具的使用规范。两处custom_instruction${repository_instructions}/custom_instruction仓库注入指令的占位见下文归一化说明。尾部system_notifications、file_folder_and_symbol_links、solution_persistence、user_updates_spec、session_context、git_commit_trailer、tool_calling、task_completion等环境相关章节以及收尾句 Respond concisely to the user, but be thorough in your work.input唯一一条用户消息input是 Responses API 风格的输入数组仅含一条消息其中 content 为一段input_textcurrent_datetime${datetime}/current_datetime Say exactly ok该消息正是测试驱动的一次确定性对话源码中固定为Say exactly ok。current_datetime的时间值在归一化时被占位为${datetime}。toolsCLI 暴露给模型的能力数组中定义了模型可调用的工具。本快照中可见名为bash的工具携带description与parameters结构是 Copilot CLI 的本地执行工具定义。README 特别说明CLI 还会把整个/models目录内联到Task工具的 schema 中模型数量与逐模型列表而模型目录在快照中被归一化为${model_catalog}见下文。快照由哪段测试产生测试驱动全流程快照由 copilotPromptsE2E.integrationTest.ts 驱动生成并校验它不属于行为断言套件而是提供方请求体边界the provider request-body boundary。1. 模型清单文件顶部的SNAPSHOT_MODELS约第 60–80 行列出每个模型族一个条目gpt-5.1在其中。清单包含 Copilot 扩展agentPrompt.spec.tsx覆盖的模型族外加 Agent Host 支持的较新族。注释还提示两类缺席gpt-4.1与grok-code-fast-1缺席因为重放时 CLI 对二者不发出模型请求任何未选中的条目都不钉因为 CLI 会自行对 stub 目录排序使基线变成夹具的属性而非产品行为。2. 一次真实的重放 turn针对每个模型测试通过AgentHostE2EServerLease启动真实 Agent Host 服务器 CapiReplayProxy创建真实会话createRealSession工作目录为mkdtemp出的临时目录随后driveTurnWithModel约 158–212 行通过buildDefaultChatUri构造默认 chat 频道派发ChatTurnStartedactionmessage.text固定为Say exactly okmodel.id为被测模型循环等待ChatTurnComplete/ChatToolCallReady/ChatError三类通知对任何ChatToolCallReady自动派发ChatToolCallConfirmedapproved: truereason 为Setting直到收到ChatTurnComplete才结束任何ChatError都会抛错——避免把坏 turn 快照成看起来正常的提示词。3. 取最后一块请求体并做形状守卫const body lease!.observedModelRequestBodies.at(-1)——取最后一块请求体是为了在 CLI 插入预检请求preflight request时仍拿到真正的那次模型请求。随后formatPromptSnapshot先做形状守卫系统提示词长度必须 0否则说明 wire 形状变了tools必须是含元素的数组必须有 turn 消息且不允许任何空文本消息该守卫也覆盖 Responses 方言下的function_call/function_call_output与 Anthropic 的tool_use/tool_result。空捕获会直接报错而不是变成一份小而看似合理的基线。4. 归一化后 pretty-print 成.prompt.md通过守卫后请求体经normalizeVolatileValues递归遍历字符串与normalizeVolatile逐类正则处理再写入快照。所以快照中你看到的${...}占位符全部来自这段归一化而不是录制方的伪造。归一化规则哪些内容被占位、哪些必须原样暴露README 的 Prompt snapshots 章节与normalizeVolatile实现约 357–370 行给出了完整的占位清单。原则是尽量保留真实提示词文本只剔除跨运行不稳定或属于他人变更预算的内容且每个被剔除项都保留其标签或外层包裹因此即便形状变化如某行消失也会导致断言失败占位符被替换的内容保留的包裹${session_id}session-state/下的会话 UUIDsession-state/前缀保留${datetime}current_datetime内的时间保留current_datetime标签${os}环境探测出的操作系统名* Operating System:前缀保留${available_tools}在PATH上探测到的工具列表* Available tools:前缀保留${platform_packages}bash 工具里平台相关的包管理器提示句子骨架保留${repository_instructions}注入的仓库指令custom_instruction标签与位置保留从而仍能断言注入了几份、在哪里${model_count}/${model_catalog}内联进Taskschema 的模型目录计数与列表行保留${uuid}其余所有 UUID—换行归一化\r\n→\n—其中有两项不是为消除运行间差异而是为把变更预算放回正确的文件仓库注入指令CLI 会把.github/copilot-instructions.md与AGENTS.md逐字注入。它们跨机器稳定、本可钉住但若钉住向AGENTS.md追加一行就会改写全部基线并在无关文档编辑上触发 CI 失败。保留custom_instruction包裹是折中。模型目录同理capiStubs.ts中新增一个模型条目就会重写所有基线。因此标签保留、内容占位。此外该文件model: gpt-5.1、metadata当存在时里的真实 UUID 也会在归一化时被处理成${uuid}见normalizeVolatile的最后一条兜底规则标签式占位会先完成、避免被二次替换。配套证据录制夹具与模型目录 stubgpt-5.1 的快照不是孤立的它在仓库里有两层配套支撑录制夹具captures/copilotcli-gpt-5-1.yaml这是一个dialect: responses的交换记录request.model为gpt-5.1系统提示占位为${system}用户消息为Say exactly ok回放响应为okstopReason: end_turn。重放必须回应该 turn因此新增模型必须同时提交夹具。模型目录 stubcapiStubs.ts约 51 行为gpt-5.1以及gpt-5.1-codex、gpt-5.1-codex-mini声明 stub 条目注明 vendor、supportedEndpoints: [/responses, ws:/responses]、maxContextWindowTokens: 400000、maxOutputTokens: 128000、maxPromptTokens: 272000、vision: true。一个模型若不出现在/modelsstub 目录中会在 CLI 构建请求前就被拒绝——测试因此拿不到任何捕获的请求体。快照中哪些内容属于 Host、哪些属于 CLIREADME 明确区分了两类来源属于 Copilot CLI产品的部分提示词主体被编译进github/copilot二进制是 CLI 的产品而非 Host 的产品。所以同一方言下CLI 不会按模型分支提示词多个模型的基线天然近似。属于 Agent Host 的部分Host 的贡献在于resolveSystemMessageConfig——它位于 node/copilot/prompts/promptRegistry.ts约 156 行在启动会话时组装会被逐字放入此提示词的多个区块。快照因此端到端覆盖了 Host 侧贡献唯一覆盖不到的是被 Host 配置开关门控的逐模型贡献者——E2E harness 没有设置根配置的接缝这些门控由test/node/agentHostPromptRegistry.test.ts级别的单测覆盖。如何解读与更新基线变更语义与命令一个 diff 只意味着两类原因CLI 变了如 SDK bump 后编译进二进制的提示词变化Host 变了Host 交给 CLI 的内容变化例如promptRegistry.ts组装的区块改动。按设计编辑仓库的AGENTS.md/注入指令不会导致这些基线变化被${repository_instructions}占位。更新命令与其他 AHP 快照共用同一开关属于确定性、无 token 的重放流程# 运行完整套件中的该文件replay 模式默认即此 ./scripts/test-integration.sh --run \ src/vs/platform/agentHost/test/node/e2e/providers/copilotPromptsE2E.integrationTest.ts # 接受新基线重放既有 LLM 夹具无 token 无网络 AGENT_HOST_UPDATE_AHP_SNAPSHOTS1 ./scripts/test-integration.sh --run \ src/vs/platform/agentHost/test/node/e2e/providers/copilotPromptsE2E.integrationTest.ts注意快照更新模式中RECORDING标志AGENT_HOST_UPDATE_SNAPSHOTS1或AGENT_HOST_REPLAY_RECORD1下不会记录基线因为录制会连真实 CAPI。接受基线后应在 Git diff 中人工审查再不带更新开关重跑以验证提交的快照。若基准文件缺失assertPromptSnapshot会直接报错no committed prompt baseline at ...而不会像通用assertSnapshot那样静默创建文件放行——防止在没有基准的情况下某个模型跑绿。平台限制与模型扩充约束该套件是POSIX-onlyWindows 上每个模型用例都test.skip见约 135–139 行因为 Windows 的提示词携带 PowerShell 专有段落而非对本文件的重命名且其中一个还依赖机器探测。SDK 漂移是跨提供方的因此 POSIX 运行器已能捕获。此约束同时在 KNOWN_ISSUES.md 中有记录Copilot prompt snapshots on Windows含复现命令scripts\test-integration.bat --run ...\copilotPromptsE2E.integrationTest.ts。若要在快照集里新增一个模型必须同时满足三条README Prompt snapshots 章节出现在 capiStubs.ts 的 stub 目录中——否则在 CLI 构建请求前即被拒有已提交的录制夹具captures/copilotcli-slug.yaml——因为重放的 turn 仍需被应答且夹具 dialect 要与模型的 stub 端点匹配/responses用dialect: responses/v1/messages用dialect: anthropic加入SNAPSHOT_MODELS并提交基线。仅改capiStubs.ts不会让套件失败模型目录被占位剔除一个模型只有在同时被加入SNAPSHOT_MODELS并提交夹具与基线后才会被钉住——钉住一个新模型是 opt-in 的而非从线上/models目录派生。扩展阅读路径快照格式化的两个纯函数单测对残缺请求体形状的拒绝、对易变值的原地归一化位于 copilotPromptsE2E.integrationTest.ts 底部的 Copilot prompt snapshot formatting 套件完整机制说明见 e2e README 的 Prompt snapshots、Updating snapshots and fixtures 章节录制/重放代理与夹具占位符约定见 harness 下的capiReplayProxy.ts、ahpSnapshot.ts、agentHostE2ETestHarness.ts本快照对应的对话流量快照.traffic.ahp.yaml位于同一snapshots目录可与.prompt.md对照阅读。【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考