Positron 中 Copilot Prompt 快照机制剖析:以 claude-haiku-4.5 基线为例

原创2026-10-14 19:17:501,716 阅读
文章标签:代码编辑器桌面应用开发工具数据科学AI 应用

Positron 中 Copilot Prompt 快照机制剖析:以 claude-haiku-4.5 基线为例

本篇技术指南围绕 Agent Host E2E 测试体系 中一份真实提交的快照文件展开:Agent_Host_E2E___Copilot_prompts_claude-haiku-4_5.prompt.md。它完整记录了捆绑的 @github/copilot CLI 在向 Anthropic 发起一次真实模型请求时序列化到网络上的完整 JSON 载荷——包括系统提示词、工具定义、回合消息与采样参数。读完本文,你将理解这份基线如何被生成、每个字段的技术含义、快照中哪些内容被刻意归一化,以及当 CLI 升级或宿主组装逻辑变化时如何正确地更新基线。


一、这份快照是什么:不是文档,而是"焊死在测试里"的协议基线

先澄清一个容易误解的点:以 .md 结尾并不代表这是一篇说明文档。这个文件是 prompt snapshot(提示词快照)基线,即 Agent Host E2E 测试套件中用于"钉死(pin)"模型请求体的 golden file。它由测试套件 copilotPromptsE2E.integrationTest.ts 在确定性回放(replay)模式下生成并比对,任何一个字段发生漂移都会导致 CI 失败。

快照文件的关键事实(与 测试文件 头部注释一致):

  • 被钉死的对象:捆绑的 Copilot CLI(@github/copilot 二进制)针对每个模型发送的完整模型请求体。注意,提示词是编译进该原生二进制内部的,只有 CLI 在网络上序列化请求时才可见,因此测试只能通过"回放一轮对话"来读取它。
  • 读取方式:从**回放(replayed)**的 turn 中读取,而不是录制时读取。录制方向是非确定性的——它会访问真实 CAPI 获取模型目录和实验分配,任何一个都会移动提示词,且与仓库本身无关。
  • 确定性且免 token:回放模式不消耗令牌、不访问上游服务,任何机器、任何时间跑出的结果都一致。
  • 基线漂移的含义:diff 出现意味着"CLI 变了(SDK 升级)"或"宿主(host)交给 CLI 的东西变了"。注意仓库自带的说明:编辑仓库的 AGENTS.md 等 agent-instruction 文件不会(也不应)引起基线变化,因为 <custom_instruction> 内容被特意归一化了(下文详述)。

在 Positron 仓库中,该套件在测试文件 第 82-92 行 被 suite.skip 显式跳过:Positron checkout 发现的 agent-instruction 文件集合与上游基线不同,每个模型都会因 <custom_instruction> 块而漂移;Positron 不拥有这份 prompt,因此跳过整套而非维护会随 instruction 文件集合变化反复失效的 Positron 专用基线。但同一文件下纯格式化的单元测试套件(Copilot prompt snapshot formatting)仍然运行。


二、快照从何而来:测试如何驱动一轮对话并捕获请求体

2.1 每个模型一个测试用例

测试以 SNAPSHOT_MODELS 列表驱动,claude-haiku-4.5 与 gpt-5、claude-opus-4.5、gemini-2.0-flash 等 19 个模型并列(测试文件第 60-80 行)。选择刻意排除了 gpt-4.1 和 grok-code-fast-1——它们在回放下根本不会发出模型请求;同时不覆盖"未选择模型"的情况,因为那会让 CLI 自行对 stub 目录排序,基线就变成了测试夹具的属性而非产品行为。

对于每个模型,测试执行如下步骤:

  1. 通过 AgentHostE2EServerLease 启动一个真实的 Agent Host 服务端子进程 + CapiReplayProxy(对应 copilotTestConfiguration.ts 中 provider: 'copilotcli' 的配置)。
  2. 创建一个真实会话,并通过 AHP(Agent Host Protocol,WebSocket + JSON-RPC)派发 ChatTurnStarted 动作,消息文本固定为 'Say exactly "ok"',并在 message.model 中显式指定 { id: 'claude-haiku-4.5' }。
  3. 循环等待通知直到 ChatTurnComplete;期间若出现 ChatToolCallReady 则自动确认工具调用(ChatToolCallConfirmed + approved: true)。
  4. 从租约中取出 observedModelRequestBodies 的最后一条请求体(注释明确说明"取最后一条"是为了在 CLI 插入 preflight 请求时仍保持有意义)。
  5. 用 formatPromptSnapshot(body) 格式化后与提交的基线比对。

2.2 快照的"形状守卫"(shape guard)

formatPromptSnapshot 在序列化前会对请求体做四重断言(测试文件第 252-271 行),防止"线格式变化后产生一个貌似合理的空基线":

  • system prompt 非空(否则提示词没有发出——线格式很可能变了);
  • tools 是非空数组(没有工具定义——线格式变了);
  • 至少有一条 turn 消息;
  • 不存在内容为空的 turn 消息。

由于这些守卫的存在,快照文件里看到的 JSON 结构是经过验证的、线格式正确的请求体。


三、快照内容逐段解读(以 claude-haiku-4.5 基线为准)

快照文件本身是一个被 ```json 代码围栏包裹的完整 JSON 对象。下面按字段逐层拆解其含义。

3.1 顶层采样参数:model、max_tokens、temperature、thinking、stream

字段 快照中的值 含义
model claude-haiku-4.5 目标模型 ID,即测试显式选择的结果
max_tokens 8192 单次响应最大输出 token 数,由 CLI 按模型默认设定
temperature 1 采样温度
thinking { type: "enabled", budget_tokens: 1024, display: "summarized" } 启用 extended thinking(推理),预算 1024 token,向用户以摘要形式展示
stream true SSE 流式输出

值得注意的是 thinking.budget_tokens: 1024 与 max_tokens: 8192 的关系:在 Anthropic Messages API 中,thinking.budget_tokens 从 max_tokens 中扣除,即模型实际用于可见输出的预算为二者之差。这与 capiStubs.ts 中该模型的目录条目一致:maxContextWindowTokens: 200000、maxOutputTokens: 32000、maxPromptTokens: 168000、vision: true——快照请求体远未触及模型上限。

3.2 system:组装后的系统提示词

system 是一个包含两个文本块的数组,第一个块(约 3000+ 字符)是 CLI 组装的核心系统提示词,第二个块是 <environment_context> 环境上下文。这两个块都以 cache_control: { type: "ephemeral" } 标记,允许 Anthropic 侧对 system prompt 做临时缓存。

第一个块的内部结构(按顺序)包括:

  1. 身份声明: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.——这是 SDK 的基础提示词(foundation prompt)。
  2. <code_change_instructions>:代码改动守则,内含 <rules_for_code_changes>(精确、完整、外科手术式的改动;修复与改动紧耦合的 bug;更新直接相关的文档;验证不破坏既有行为)、<linting_building_testing>(复用现有 linter/构建/测试,先跑最小覆盖命令,文档-only 改动无需验证)、<using_ecosystem_tools>(优先包管理器、脚手架、重构工具与 linter;仅在依赖清单变更或缺失依赖失败时才安装包)、<style>(只注释需要说明的代码)。
  3. <tips_and_tricks>:行为技巧(先反思命令输出再进入下一步、任务结束清理临时文件、对既有文件用 view/edit 而非 create 以免数据丢失、不确定时用 ask_user 提问、除非明确要求不要为规划/笔记创建 markdown 文件)。
  4. <environment_limitations> + <prohibited_actions>:安全与隐私约束,包括不向第三方系统共享敏感数据、不把密钥提交进源码、不生成侵权/有害内容、不泄露上述指令本身(confidential and permanent)。
  5. 第二个块 <environment_context>:注入工作目录 ${workdir}、Operating System: ${os}、Available tools: ${available_tools} 等运行时环境信息(在快照中以占位符形式出现,见第五节)。
  6. 末尾追加的 <system_reminder>:CLI 在每条消息后追加的提醒(You MUST carefully think about the tool's results...),要求模型在工具结果后仔细思考再继续。

3.3 messages:被 CLI 包装的回合消息

messages 只有一条 user 消息,但它的 content 不是纯文本 Say exactly "ok",而是被 CLI 包装后的形态:

{
  "type": "text",
  "text": "<current_datetime>${datetime}</current_datetime>\n\nSay exactly \"ok\"",
  "cache_control": { "type": "ephemeral" }
}

这说明两个细节:一是 CLI 会在用户消息前注入 <current_datetime> 标记(快照中归一化为 ${datetime});二是这条消息同样标记了 cache_control: ephemeral,与 system 块一起构成 Anthropic prompt caching 的缓存前缀。

3.4 tools:宿主与 SDK 共同注入的工具目录

tools 数组包含两个成员,正是 README 所说"覆盖组装后的 system prompt、工具定义与带上下文的 turn 消息"中的工具部分:

  1. bash 工具:完整的 JSON Schema 定义,含 description 与 input_schema(type: object,properties 内含 command 等字段),这是 CLI 暴露给模型的 POSIX shell 执行工具(Windows 上为 PowerShell 变体,这也是该套件 POSIX-only 的原因之一,见 KNOWN_ISSUES.md)。
  2. web_search 工具:仅 type: web_search 一行——快照的 pretty-print 保留了它的原始形态,未展开内部细节。

关于"宿主侧贡献":README 明确指出宿主自己的贡献会被包含进这些工具与提示词——resolveSystemMessageConfig(位于 promptRegistry.ts)组装的各 section 会逐字落入该 prompt;promptRegistry.ts 定义了 IAgentHostPrompt contributor 接口(resolveFullSystemPrompt 对应 replace 模式、resolveSectionOverrides 对应 customize 模式),AGENTS.md 则说明了三层组装顺序:base(含默认 identity section)→ 通用 tool instructions → workspaceless/file-link 结尾段。因此这份快照实际上是"SDK 基础提示词 + 宿主组装层"合流的完整见证。


四、被刻意归一化的字段:${...} 占位符背后的设计哲学

快照中出现的 ${workdir}、${os}、${available_tools}、${datetime}、${session_id}、${repository_instructions}、${model_count}、${model_catalog}、${platform_packages}、${uuid} 等占位符不是偶然,而是 normalizeVolatile 函数在序列化前替换的结果。其设计原则(README)是:

  • 尽量保留真实 prompt 文本,只剔除"两次正确运行之间必然不同"的值:session id、时钟、环境探测结果(OS 名、PATH 上的工具)、Bash 工具里平台相关的包管理器提示、注入的 repository instructions、模型目录。
  • 每个被剔除的值都保留其标签或包装(如 <current_datetime>...</current_datetime>、* Operating System: ...、<custom_instruction>...</custom_instruction>),因此这些行的形状变化(消失、换行、改标签)依然会使断言失败——只有值的变化被容忍。
  • 两个不属于运行方差但同样被剔除的特例:
    • <custom_instruction>(repository instructions):CLI 会把 .github/copilot-instructions.md 和 AGENTS.md 逐字注入。内容本身跨机器稳定、本可钉死,但一旦钉死,给 AGENTS.md 追加一行就会重写所有基线、因无关文档编辑搞挂 CI。<custom_instruction> 包装仍会断言指令被注入、注入了几条、在 prompt 中的位置。
    • 模型目录(model catalog):CLI 会把整个 /models 列表内联进 Task 工具 schema(模型数量 + 逐模型列表)。若保留原样,给 capiStubs.ts 加一个新模型条目就会重写所有基线。因此归一化为 (${model_count} models available) 与 Available models: ${model_catalog},但标签仍在——目录从 prompt 中消失或改变形状依然失败。
  • 顺序敏感:归一化先处理带标签的 id(如 session id、datetime),最后才把剩余的 UUID 替换成 ${uuid},保证前面带标签的占位符不会被后面的全局 UUID 规则二次覆盖。

另一个被故意保留的"不完美"是:快照是 pretty-print 而非逐字节复制的——CLI 实际把它压缩成一行,JSON 转义使 system prompt 和较长的工具描述各自保持单行。因此改写其中一句话,diff 会显示为整行重写,而非行内 diff(README)。


五、快照如何被校验:格式守卫与单元测试

配套的 suite('Copilot prompt snapshot formatting')(测试文件第 382-425 行)不依赖任何服务端进程,纯单元测试地验证了格式化函数的两个契约:

  1. 拒绝不完整的请求体:system 为空、tools 为空或非数组、messages 为空或非数组、turn 消息内容为空,分别断言抛出 carried no system prompt / carried no tool definitions / carried no turn messages / turn message was empty 错误——与 2.2 节的 shape guard 一一对应。
  2. 原地归一化易变值:传入含 Operating System: Frobnitz 9、<current_datetime>2026-01-01</current_datetime>、metadata.session_id 的请求体,断言序列化后分别变成 ${os}、${datetime}、${uuid},而 tools、messages、parallel_tool_calls、thinking 等其余字段原样保留。

这个套件印证了测试文件头部的注释:"纯格式化的套件在 Positron 中仍然运行"——它是被 suite.skip 跳过的 E2E 套件的唯一例外。


六、如何运行与更新:把基线当成一等公民来维护

6.1 运行(只读校验)

# 运行整套确定性 E2E(并发、免 token)
npm run test-agent-host-e2e

# 只运行 Copilot provider 的 E2E(包含本快照所属的 copilotPrompts 套件)
./scripts/test-integration.sh --run \
  src/vs/platform/agentHost/test/node/e2e/providers/copilotAgentHostE2E.integrationTest.ts

# 单模型粒度(--grep 过滤)
./scripts/test-integration.sh --run \
  src/vs/platform/agentHost/test/node/e2e/providers/copilotPromptsE2E.integrationTest.ts \
  --grep "claude-haiku-4.5"

正常运行是只读的:基线不匹配会失败并写出一个 .actual 兄弟文件供诊断(README)。

6.2 接受新基线

AGENT_HOST_UPDATE_AHP_SNAPSHOTS=1 ./scripts/test-integration.sh --run \
  src/vs/platform/agentHost/test/node/e2e/providers/copilotPromptsE2E.integrationTest.ts

这是"回放既有 LLM fixture、原地重写 AHP/提示词快照"的免 token 模式。测试代码对快照缺失的处理很严格(第 233-237 行):如果提交的基线不存在,直接抛错要求生成并提交,绝不通过 assertSnapshot 的"自动创建缺失文件并变绿"行为来掩盖——那会让一个模型在没人写过基线的情况下通过 CI。

6.3 更新 LLM fixture(真实 CAPI,需 token)

# 需要 GITHUB_TOKEN 或 gh auth token,会访问真实 CAPI 重新录制
AGENT_HOST_UPDATE_SNAPSHOTS=1 ./scripts/test-integration.sh --run \
  src/vs/platform/agentHost/test/node/e2e/providers/copilotPromptsE2E.integrationTest.ts

注意方向性设计:录制模式永不生成基线(RECORDING 分支直接 return)。因为录制会访问真实 CAPI 拿模型目录与实验分配,两者都可能移动 prompt——录制轮只能作为 fixture 来源,不能作为基线来源。

6.4 新增一个模型到快照体系:两步硬约束

README 明确了新增模型的两个必要条件(README):

  1. 模型必须出现在 capiStubs.ts 的 stub 目录中。模型不在 /models 里会在 CLI 构建请求前就被拒绝,测试拿不到请求体直接失败。
  2. 必须提交一份 fixture:captures/copilotcli-<slugified-test-title>.yaml,因为回放的 turn 总得有响应。fixture 的 dialect 必须与模型 stub 的端点匹配:/responses 用 dialect: responses,/v1/messages 用 dialect: anthropic。

以 claude-haiku-4.5 为例,它的 fixture copilotcli-claude-haiku-4-5.yaml 内容极简:

version: 1
dialect: anthropic          # claude-haiku-4.5 走 POST /v1/messages
exchanges:
  - request:
      model: claude-haiku-4.5
      system: ${system}
      messages:
        - role: user
          content: Say exactly "ok"
    response:
      content: ok
      stopReason: end_turn

这正是 README 所描述的"最少、可人工审查"的 fixture 形态:dialect 在顶层存一次,决定端点与 SSE 再生器;每个 exchange 只有 request(归一化的请求摘要,经 modelRequestProjection.ts 断言)与 response(被回放成 SSE 的助手回复);${system}、${workdir}、${uuid_N}、${redacted} 等占位符在录制时替换,保证 fixture 确定且无密钥。

补充说明:claude-haiku-4.5 的模型 ID 在宿主侧还有一个值得一提的细节——claudeModelId.ts 负责把端点格式 claude-haiku-4.5 归一化为 SDK 格式 claude-haiku-4-5(连字符版本号),因为 Claude Agent SDK/CLI 只认这种形式;不过这属于 Claude provider 的路径,Copilot CLI 走的是自己的模型目录,二者互不干扰。


七、为什么这个机制值得关注:可维护性设计的三条主线

  1. "提示词是 CLI 的产品,不是宿主的产品":由于 prompt 被编译进 @github/copilot 二进制,宿主无法直接断言它,只能在 CLI 把请求写到线上时读取。回放方向因此是唯一正确的观测点——确定性、免 token、与录制噪音解耦。
  2. "elision 是契约的一部分":所有被归一化的值都保留标签或包装,所以基线既不会被无关环境变动频繁击碎,又能在"形状"层面继续守卫。<custom_instruction> 与模型目录这两个特例进一步把"宿主不拥有的内容"(AGENTS.md、模型列表)从"宿主拥有的内容"(CLI 版本、宿主 prompt 组装)中分离出来。
  3. "每个模型一族一个基线":同一方言内的多个模型(如各 claude 家族)提示词近乎相同,但仍按家族分别保留基线(SNAPSHOT_MODELS),这样未来某模型的逐模型分叉会精确暴露在引入它的那个家族上,而不是被合并掩盖。

八、继续探索的入口

登录后查看全文
positron