agent-host-e2e-tests

Agent 宿主端到端测试

这些测试会端到端运行整个 Agent 宿主（真实服务、真实的打包提供商 SDK/CLI、真实 AHP 协议），同时重放从已提交 YAML 夹具中记录的模型流量——结果确定且不消耗令牌。

开始任何操作前，请先阅读架构和故障排查参考： src/vs/platform/agentHost/test/node/e2e/README.md

其中介绍了整体思路、夹具格式、每个配置标志，以及症状→原因→解决方案故障排查表。本文档仅介绍工作流；关于工作原理，请以 README 为准。

验证上游提供商/运行时修复时，请使用 ci-artifact-testing，在本地构建前检查是否有兼容的 CI 工件。对打包的基线版本和候选版本运行相同的严格重放；保留测试断言和现有的跨平台验证要求。

核心原则

1. 默认严格重放。 不设置环境变量时，会使用已提交的夹具，不需要令牌或网络。遇到未记录的请求会直接缓存未命中。
2. 夹具名称取自测试标题。 重命名由模型支持的测试会导致 ${provider}-${slug}.yaml 失效；重命名后请重新录制。显式使用 hostOnlyTest(...) 注册的测试共用 captures/empty.yaml。
3. 录制须有意进行，并使用凭据。 AGENT_HOST_REPLAY_RECORD=1 会连接真实的 CAPI，并需要 GITHUB_TOKEN 或 gh auth token。提示词应保持简单，并且只在临时目录中执行只读操作。
4. 夹具由工具生成，不要手动编辑。 如果捕获内容中包含不稳定或敏感数据，请修复规范化或脱敏逻辑，然后重新录制。
5. 禁用的变体仍须留有记录。 在 e2e/KNOWN_ISSUES.md 中记录每个门控项的适用范围、预期和实际行为，以及用于聚焦复现的命令。
6. 必须通过 Azure 验证。 每个新增的 Agent Host E2E 测试或真实提供商集成测试，都必须在合并前通过 VS Code 流水线定义 111 执行的聚焦构建。

基本工作流：编写并评估 E2E 测试

1. 选择边界和层级。 将与提供商无关的 AHP 行为放入一致性测试，将提供商行为放入兼容性测试；只有当提供商特定行为不能越过模型边界时，才使用 providerHostOnlyTest(...)。
2. 将测试添加到最匹配的测试套件。 仅当行为确实不同，才创建并注册聚焦的测试套件模块。将提供商特定断言放在该提供商的 *.integrationTest.ts 中。
3. 实现最小化的确定性场景。 提示词应尽量精简，通过 AHP 驱动行为，等待准确的前置条件和完成状态，并确保每个由模型支持的轮次都已结束。
4. 断言契约最主要的可观察结果。 检查真实的协议结果或外部副作用；只有当顺序、路由或生命周期属于契约内容时，才快照额外流量。
5. 为每个启用的提供商录制夹具。 仅由宿主运行的测试使用共用的严格空夹具。对于由模型支持的测试，请遵循下文的录制工作流。
6. 检查生成的工件。 检查夹具和快照差异，确认其体现了预期行为、路径已规范化、不含凭据或用户名，也没有非预期的模型或请求变更。
7. 本地评估。 在严格重放模式下运行聚焦测试；如果辅助函数或共享状态有变更，也要运行相邻测试；对时间或生命周期敏感的场景重复运行；然后运行完整的确定性测试套件，以及 E2E README 中要求的覆盖率、类型检查、卫生检查和分层检查。
8. 在 CI 中评估。 创建或更新草稿 PR，并完成下文的跨平台 Azure 验证。时间、进程生命周期、文件系统监控、重新连接、重启和工作树测试，都必须在每个受支持的平台上成功执行两次。

通用最佳实践与应避免的错误

请精心维护本节。只有在根因分析发现某种模式可能有助于改进其他测试时，才添加或完善原则；特定故障的命令、日志和操作细节应放在 E2E README 或调查报告中。

• 等待契约状态，而不是代理信号。 存在、发现或发出中间操作，并不一定意味着依赖项已可用。例如，应等待目标聊天的 MCP 服务报告 Ready，而不只是等它的插件子项出现。
• 先断言主要结果，再检查次要影响。 钩子、通知、助手响应或持久化记录可能是被测行为的下游结果。应先确认实际工具结果或外部副作用成功。
• 不要把回放成功与执行成功混为一谈。 回放控制的是模型流量；实时工具、MCP 服务、钩子、命令和文件系统操作仍可能失败。记录的助手文本不能作为这些操作的判定依据。
• 依据可观测状态同步，绝不依据经过的时间。 使用协议通知或精确的状态轮询，而不是休眠、增加超时或仅检查是否存在。
• 遵守作用域和生命周期。 就绪状态可能属于特定聊天、会话、提供方进程或工作区。应在首次轮次前以及已有历史记录后测试重新配置：提供方进程正在运行，并不能证明存在可恢复的对话。应创建并观察操作实际使用的同一作用域，在拆除前排空任务，并清理所拥有的资源。临时工作区应放在不包含指令文件的祖先目录之外：更改其位置可能会将无关的仓库自定义配置注入提供方的模型请求。
• 区分存储语义与设备延迟。 基于 RAM 的文件仍可保留真实的 SQLite 事务、关闭/重新打开及主机重启行为；所需的磁盘存储生命周期覆盖应单独保留。在将超时归因于物理存储之前，应在同一工作进程上比较未更改的工作负载，并检查各阶段的耗时，而不只是通过次数。
• 集中管理重复的生命周期屏障。 如果多个测试需要相同的多步骤前置条件，应将其封装在共享辅助函数中，避免测试选择较弱的中间条件。
• 仅在必要范围内处理真正的非确定性。 仅对无法确定性回放或不受支持的行为使用仅录制或提供方/平台门控；绝不能用门控掩盖原因不明的失败。

录制或重新录制夹具

添加测试时，或捆绑的 SDK/CLI 升级改变其线路行为（新增端点、轮次数变化、工具架构变更）时，应重新录制。

1. 确保令牌可用：gh auth token（或导出 GITHUB_TOKEN）。
2. 按提供方录制：

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

   根据需要对 copilotAgentHostE2E / codexAgentHostE2E 重复操作。
3. 检查夹具上的 git diff：不得包含本地用户名/绝对路径、令牌或尚未发布的模型 ID。如果有信息泄露，应在 capiReplayProxy.ts（_normalize 和 *_RE 脱敏器）中扩展规范化/脱敏逻辑，然后重新录制，而不是编辑夹具。
4. 运行普通回放（不设置环境变量）确认通过，然后提交。

如果 SDK 现在会调用新的附带/引导端点（探测请求，而非真实模型轮次），应将其添加到 capiStubs.ts（由其提供服务，而不是录制），而不是录制下来——请参阅 /models/session 的处理方式。

为无法确定性重放的变体添加门控

实时流式传输、在轮次中途终止，以及特定于 POSIX 的本地执行（shell 工具、pwd、git worktree）都无法可靠重放。请精准添加门控，以便在可行的场景中保留测试覆盖：

• 仅录制（完全不进行确定性重放）：(RECORD ? test : test.skip)('…') — 请参阅 can abort a running turn。
• SDK 升级后子 Agent 测试夹具过时：重新录制（AGENT_HOST_REPLAY_RECORD=1 …）。子 Agent 流程对 SDK 版本最敏感（父级和子级共享一个 /v1/messages 序列），但重新录制后即可可靠重放，因此无需添加门控。
• 仅限 POSIX（在 Windows 上失败）：使用 !isWindows 添加门控；如果只有一个提供方存在差异，则使用针对该提供方的标志。请参阅 worktree 和 subagent-reopen 测试。
• 特定提供方／操作系统的重放：添加针对性配置门控，同时允许录制和不受影响的平台。请参阅 Codex shell 工具的 Linux 门控。

请务必添加注释，解释添加门控的原因。还要在 e2e/KNOWN_ISSUES.md 中添加或更新相应条目。重新启用该变体时，请在同一项更改中删除或更新该条目。

跨平台 Azure 验证

仅通过本地或 GitHub 拉取请求 CI 测试，尚不足以合并新的 Agent Host E2E 和真实提供方集成测试。请推送分支并打开或更新草稿 PR，然后使用 azure-pipelines skill 验证真实打包后的 Electron 集成测试流程。

1. 使用 VSCODE_BUILD_TYPE=CI 排队运行 VS Code 管道定义 111；启用 Windows、Linux 和 macOS x64，禁用发布、Release、Web、ARM、Alpine 和 Snap 构件。azure-pipelines skill 中包含标准命令。
2. 监控作业，待其完成。某个平台失败时，应立即检查其 Agent Host E2E Tests (Electron) 作业和 🧪 Run Agent Host E2E tests (Electron) 任务（测试 ID integration-agent-host-e2e），不要等无关阶段完成。
3. 只有当 Windows、Linux 和 macOS 上的 🧪 Run Agent Host E2E tests (Electron) 任务均成功时，才接受 Agent Host E2E 测试结果。
4. 对看似无关或既有的失败，应单独重新运行后再判断是否由 PR 导致。
5. 修复特定平台的问题后，至少重新运行该平台的测试。如果修复可能影响共享行为、提供方测试夹具、进程生命周期或跨平台路径，则应在三个平台上全部重新运行。
6. 推送替代提交后，取消过时的构建。

验证与故障排除

• 在重放模式下运行单个提供方：./scripts/test-integration.sh --run <path>（无需环境变量）。
• 筛选单项测试：添加 --grep "<test title fragment>"。
• 遇到挂起／超时时，请先读取运行时日志。 对于 Copilot 提供方，测试失败时会将最近的 Copilot 运行时（@github/copilot CLI）process-*.log 输出到测试结果中（[agent-host-e2e] # … 行）——其中包含 SDK／CLI 对启动、身份验证、模型请求和轮次生命周期的记录。日志级别为 --log trace。如果某轮次一直没有模型响应、发生 panic，或出现顺序错误／协议错误，则问题可能出在 SDK／CLI（如果升级后测试夹具过时，请重新录制；否则就是实际回归）。Claude／Codex 使用各自的运行时，不会记录在此处。请参阅 README 中的“A turn hangs or times out with no OS pattern”。
• 对于任何失败（缓存未命中、缺少测试夹具、特定操作系统的超时、PII 泄露、子 Agent 测试夹具过时、意外联系真实 CAPI），请查看 README 的故障排除部分——其中将每种症状对应到其原因和修复方法。