vscode-dev-workbench

使用本地 VS Code 源码运行 vscode.dev

vscode-dev 仓库是 vscode.dev 服务。在本地运行并使用 ?vscode-quality=dev 时，它会从同级目录中的 microsoft/vscode 检出版本提供 VS Code Web 工作台（或 /agents 下的 Agents 窗口）。这是在不发布 Insiders 版本的情况下验证仅限 Web 的工作台改动的最快方式。

目录布局要求

vscode-dev 和 vscode 必须是同级文件夹：

<workRoot>/
  vscode/          # microsoft/vscode checkout
  vscode-dev/      # microsoft/vscode-dev checkout

如果路径不同，请检查 vscode-dev 中的 server/，了解源码根目录的解析方式——/vscode-sources/* 路由会映射到 ../vscode。

启动开发服务器

**重要：**请从 vscode-dev 文件夹运行 npm run dev，而不是从 vscode 运行。vscode 仓库没有 dev 脚本，因此会报错 npm error Missing script: "dev"。会将开头的 cd 简化或拆分为单独命令的终端工具，可能会悄悄沿用前一个终端的工作目录；请始终使用绝对路径执行 pushd，或在运行 npm run dev 前用 pwd 确认目录。

cd /path/to/vscode-dev     # NOT /path/to/vscode
npm run dev                # runs watch + nodemon; serves https://127.0.0.1:3000

如果你通过 Agent／终端工具操作，建议使用：

pushd /absolute/path/to/vscode-dev >/dev/null && pwd && npm run dev

首次启动时，你可能会遇到一次类似 Cannot find module './indexes' 的崩溃——这是监视程序与首次构建发生竞争导致的。out/ 编译完成后，nodemon 会自动重启。运行 curl -sk -o /dev/null -w "%{http_code}" https://127.0.0.1:3000/ 并返回 200 时，表示服务已就绪。

URL

• https://127.0.0.1:3000/?vscode-quality=dev — 主工作台，使用本地开发源码
• https://127.0.0.1:3000/agents?vscode-quality=dev — Agents 窗口，使用本地开发源码
• https://127.0.0.1:3000/?vscode-version=<commit> — 固定到指定的生产提交
• 添加 &vscode-log=trace 以启用详细的客户端日志

通过集成浏览器进行交互

使用 open_browser_page 和标准浏览器工具。

在聊天输入框中按 Enter 会插入换行

聊天输入框是一个 Monaco 编辑器——page.keyboard.press('Enter') 会插入换行。若要发送，请点击 Send 按钮（a[aria-label^="Send"]）或使用发送快捷键。

重新构建后强制刷新

Service Worker 会积极缓存客户端资源。普通刷新仍可能加载过时的模块：

await page.evaluate(async () => {
  const regs = await navigator.serviceWorker?.getRegistrations() ?? [];
  await Promise.all(regs.map(r => r.unregister()));
  const keys = await caches?.keys() ?? [];
  await Promise.all(keys.map(k => caches.delete(k)));
});
await page.reload({ waitUntil: 'domcontentloaded' });

模拟移动设备（仅在明确要求时）

集成浏览器面板会限制宽度，因此 page.setViewportSize() 和 CDP setDeviceMetricsOverride 只能将视口缩窄到面板所允许的范围。User-Agent 覆盖和触控模拟都可以正常使用：

const client = await page.context().newCDPSession(page);
await client.send('Emulation.setUserAgentOverride', {
  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
  platform: 'iPhone'
});
await client.send('Emulation.setTouchEmulationEnabled', { enabled: true, maxTouchPoints: 5 });
await client.send('Emulation.setDeviceMetricsOverride', {
  width: 393, height: 852, deviceScaleFactor: 3, mobile: true,
  screenOrientation: { type: 'portraitPrimary', angle: 0 }
});
await page.reload();

如需真正的移动设备视口，请使用 devices['iPhone 14 Pro'] 运行独立的 Playwright 脚本，而不要使用集成浏览器。如果自动化期间移动端自适应覆盖层拦截了指针事件，请在 click() 中使用 { force: true }。

已知的无关紧要的控制台消息（可忽略）

• clipboardService.js 中的 Canceled: Canceled — 鼠标悬停时取消的权限探测。
• NotAllowedError: Failed to execute 'write' on 'Clipboard' — Web 剪贴板需要用户手势。
• [WebTunnelAgentHost] Failed to list tunnels — 仅在未登录时出现。
• The web worker extension host is started in a same-origin iframe! — 开发环境中的预期情况。
• Unrecognized feature: 'local-network-access' — 开发清单警告。
• [LEAKED DISPOSABLE] 堆栈 — 基于 GC 的跟踪器；只有在多次重新加载后仍可复现时才是真正的问题。

故障排除

症状	原因	修复
首次运行时出现 Cannot find module './indexes'	nodemon 在 TS 编译完成前启动	请稍候；它会自动重启
发送聊天消息时出现 Session not found: <uuid>	重新打开了由云端／隧道支持的会话	在 Agents 窗口中启动一个新会话（⌘N）
工作区选择器打开原生对话框并导致自动化卡住	Select Folder… 需要真实的文件对话框	改选工作区 URL 方案，或在自动化中跳过
编辑 vscode/ 源码后界面仍显示旧内容	Service Worker 缓存	注销 SW 并清除缓存（见上方代码片段）

针对本地模拟 Agent 主机测试 Agents 窗口

如果场景涉及 Agents 窗口（/agents 路由），几乎总是需要运行模拟 Agent 主机。没有它，Agents 窗口会停留在登录／隧道发现页面，阻止任何实际交互。除了开发服务器之外，还要启动它——需要在第二个终端中运行，而不是用它替代开发服务器。

vscode-dev 支持 ?mock-agent-host=ws://… URL 参数，可跳过隧道发现，并将 Agents 窗口连接到原始 WebSocket。将其与 microsoft/vscode 中的模拟 Agent 主机二进制文件配合使用：

cd /path/to/vscode
node out/vs/platform/agentHost/node/agentHostServerMain.js \
  --enable-mock-agent --quiet --without-connection-token --port 8765
# Listens on ws://localhost:8765

前提条件：vscode 仓库中的 out/ 必须由 VS Code - Build 任务（或 npm run watch）生成。如果缺少 out/vs/platform/agentHost/node/agentHostServerMain.js，请先启动该任务。

--enable-mock-agent 会注册 src/vs/platform/agentHost/test/node/mockAgent.ts 中的 ScriptedMockAgent，并预置一个会话。通过 VSCODE_AGENT_HOST_MOCK_SEED_SESSIONS 环境变量添加其他会话，使用逗号分隔的会话 URI 列表（例如，VSCODE_AGENT_HOST_MOCK_SEED_SESSIONS=mock://pre-1,mock://pre-2）。脚本化提示词包括 hello、use-tool、error、permission、write-file、run-safe-command、slow、client-tool、subagent 等（完整列表请参见 mockAgent.ts）。

然后打开：

https://127.0.0.1:3000/agents?vscode-quality=dev&mock-agent-host=ws://localhost:8765&vscode-log=trace

请按顺序确认出现以下日志：

• [MockAgentHost] Using local mock agent host at ws://localhost:8765/
• [WebTunnelAgentHost] Found 1 tunnel(s) with agent host support
• [WebTunnelAgentHost] Connecting to tunnel 'mock-agent-host' (mock)
• [WebTunnelAgentHost] Protocol handshake completed with tunnel:mock
• [RemoteAgentHost] Registered agent mock from tunnel:mock as remote-tunnel__mock-mock

这种方式完全绕过 GitHub 身份验证和 /agents/api/hosts 端点，因此可离线使用。vscode-dev 一侧的模拟隧道必须在 src/vs/platform/agentHost/common/tunnelAgentHost.ts 中声明一个 protocolvN 标签，其值 ≥ TUNNEL_MIN_PROTOCOL_VERSION（当前为 5）；否则 WebTunnelAgentHostService 会将其过滤掉，并显示 Found 0 tunnel(s) with agent host support。