VS Code 本地 Harness 迁移前先查三处
VS Code 1.146 将 Local harness 标为弃用并安排于 2027 年 2 月移除,迁移重点是自定义配置、工具权限和会话生命周期。
正文
先说结论
VS Code 1.146 于 2026 年 11 月 11 日发布后,Local harness 已进入弃用状态,并计划在 2027 年 2 月移除。对开发者来说,这不是简单地把会话下拉框从 Local 改成 Copilot:Harness 决定的是哪套代理运行时负责协调模型、工具、权限和会话,而模型选择与代码执行位置仍是另外两层配置。迁移前最需要核对三处是自定义配置是否被转换、MCP 与扩展工具是否仍可用,以及关闭编辑器后任务是否还依赖原来的窗口进程。
如果你只使用默认提示词和普通终端工具,迁移步骤可能很短;如果工作流依赖 prompt 文件、hooks、MCP 身份验证、扩展提供的工具或企业权限策略,就应当把它当成一次运行时切换来验收。可以先从模型与平台目录确认自己的模型与工具入口,再对照把编码代理从编辑器窗口中拆出来理解 Agent Host 与编辑器窗口的进程边界。
1.146 具体改了什么
VS Code 官方 1.146 发布说明给出了三个需要区分的事实。第一,Copilot harness 从 1.143 起就是新会话的默认选择;1.146 进一步把 Local harness 标记为 deprecated,并说明它将在 2027 年 2 月被移除。第二,在移除之前的这段过渡期里,Local harness 仍然可以使用,但功能被冻结,新的能力和改进将集中在 Copilot harness 上,不能假定 Local 会同步获得相同支持。第三,曾经用于保留 Local 默认行为的 vscode.temporaryDefaultToLocalHarness 企业设置也会一起移除。
这次变化不等于模型被替换。官方迁移指南明确把三件事拆开:Harness 是协调代理工作的运行时;模型是被选中的模型;代码在哪台机器、容器或远程主机上执行,则由执行环境决定。选择 Claude 模型不会自动切换到 Claude harness,选择 Copilot harness 也不会自动把工作区搬到云端。迁移时如果只验证模型下拉框能否打开,就没有验证真正会影响工作流的部分。
Copilot harness 使用 Copilot SDK,并通过 Agent Host 运行会话。Agent Host 是独立于某个编辑器窗口的进程,负责持有会话和执行工作;编辑器 Chat 视图与 Agents window 只是连接它的客户端。这种进程边界带来一个直接变化:只要 Agent Host 和执行环境仍在运行,进行中的任务可以在关闭项目窗口后继续;而旧的 Local harness 依赖 VS Code 的 extension host,关闭拥有会话的编辑器窗口会停止正在进行的工作。
迁移前先检查三类依赖
自定义配置不会自动等价转换
官方迁移指南建议先选一个已经能在 Local harness 中稳定完成的小任务,记录预期结果、所需工具、自定义项和审批方式,再用同一任务验证 Copilot harness。这个顺序很重要,因为选择 Copilot 并不会把所有自定义配置自动转换。
在 VS Code 中可以打开 Chat: Open Customizations,进入 Migrations 查看检测到的项目。需要逐项复核的内容至少包括以下几类:
- prompt 文件。重复使用的提示词需要按 Copilot harness 的工作流迁移为 skills,并重新检查其中指定的 agent、model 和 tool;转换过程不保证保留这些选择。
- personal agents、instructions 和 skills。要检查配置文件的存放位置与搜索路径,尤其是那些必须脱离编辑器窗口运行的工作流。个人设置也不会因为切换 Harness 就自动在不同客户端之间同步。
- hooks。需要重新核对支持的事件、脚本输入输出以及失败处理方式。官方迁移说明明确指出 hooks 没有自动转换。
- MCP。要重新验证服务器配置、授权、工具列表和 sandbox 行为。保存在编辑器里的输入提示和 secrets 不会自动迁移,不能只看到服务器名称仍在就认为连接完整。
这一步应当记录“配置存在”和“配置被实际使用”两个结果。例如某个 MCP server 能在列表中出现,只能证明发现配置成功;还要让代理调用一个无副作用的测试工具,确认认证上下文、参数 schema 和权限边界都正确。需要检查中转或模型入口时,可以把请求路径和支持的工具能力与平台目录中的信息分开核对,不要把 Harness 的变化误判为模型 API 的变化。
扩展工具要区分 Host 工具与客户端工具
Agent Host 自己管理的工具可以在没有编辑器客户端连接时继续工作,但由编辑器扩展提供的工具仍然依赖那个扩展所在的客户端窗口。官方 Agent Host 架构文档把这一点列为会话生命周期的边界:客户端可以断开并重新连接同一会话,客户端贡献的浏览器工具或扩展工具却要求客户端保持连接。
因此,迁移验收不能只测试“代理能否修改文件”。至少应分开测试三种动作:由 Host 或执行环境直接完成的文件读写与命令、由 MCP server 提供的远程工具、由 VS Code 扩展临时贡献的工具。前一种动作适合测试关闭编辑器后是否能继续;后两种动作要在客户端断开、重连和扩展重启后分别测试。一个任务能够继续生成文本,不代表它依赖的浏览器、调试器或扩展命令仍然可达。
模型、权限和 sandbox 要单独验收
Copilot harness 的迁移也可能暴露权限差异。官方文档说明,Copilot harness 可以由组织策略统一管理 sandbox、文件系统和网络限制,也可以限制开发者可使用的审批级别;这些是运行时强制执行的控制,不是让模型“记住规则”这么简单。Local harness 无法执行 Copilot 运行时才有的权限和 sandbox 控制。
这意味着迁移验证需要覆盖成功和被拒绝两条路径。先用一个允许的工作区任务确认读写、终端和模型调用正常,再用一个明确应该被策略阻止的路径或网络动作确认限制确实生效。测试应使用临时目录或管理员指定的安全目标,不要用生产目录验证拒绝策略。若只看到审批提示而没有确认最终动作被阻止,不能算策略验证通过。
现有会话怎样处理
迁移现有会话前,先确认它的当前 Harness。改变模型或把会话从 Chat 视图打开到 Agents window,不会改变会话原本使用的 Harness。官方迁移指南说明,在组织策略要求 Copilot harness 时,打开未归档的 Local 会话可能触发自动迁移;如果当前 Host 支持会话导入,系统可以保留历史和未发送输入,并把原会话归档为只读。没有导入能力时,则不能假设历史、工具状态和上下文会完整保留。
更稳妥的做法是把长期会话和新任务分开处理。先在一个小任务上新建 Copilot 会话,记录输出、工具调用和审批结果;再选择一个不依赖高风险外部工具的旧 Local 会话尝试 handoff。迁移后的会话至少检查三项:历史是否还在、未发送输入是否仍在、旧会话是否已经变成只读归档。不要把“窗口里还能看见标题”当作上下文已被导入的证明。
还要重新理解“关闭窗口后继续运行”。Agent Host 会持有 Copilot 会话,但本机执行时仍要求 VS Code 应用进程、Agent Host 和执行环境继续运行;退出 VS Code 或关机都会终止本机条件。云会话由服务管理执行环境,生命周期规则不同。无论哪种目标,依赖编辑器扩展贡献的工具都需要对应客户端继续连接,所以长任务设计应明确哪些步骤可以脱离客户端,哪些步骤必须等待客户端回来。
团队如何分阶段切换
对个人项目,推荐顺序是“记录一个基线任务、切换一个新会话、验证配置和工具、再迁移旧会话”。基线任务应该短、可重复、没有破坏性副作用,并同时覆盖一个文件变更、一个终端命令和一个实际使用的自定义工具。这样出现差异时,容易判断是 Harness、模型、执行环境还是权限策略导致的。
对组织部署,官方指南建议先做试点,覆盖实际使用的项目、MCP、Remote SSH、WSL 和 Dev Containers,再扩大范围。确认试点通过后,管理员可以在 VS Code 1.143 或更高版本的企业托管设置中要求使用 Copilot harness:
{
"vscode": {
"temporaryAllowLocalHarness": false,
"temporaryDefaultToLocalHarness": false
}
}
这两个键必须放在企业托管设置中,而不是用户设置或工作区设置。temporaryAllowLocalHarness: false 会禁止 Local、Claude 和 Codex harness;temporaryDefaultToLocalHarness: false 会清除保留 Local 默认值的退出选项。如果团队还在鼓励迁移、但暂时不想禁止其他 Harness,可以使用设备策略 ChatEditorPreferCopilotHarness: true,让新编辑器 Chat 优先选择 Copilot,而不是立即封锁其他选择。
Harness 要求与模型默认值、权限默认值和 sandbox 配置是分开的。设置 Copilot harness 不会自动开启 sandbox,也不会自动添加权限规则;这些控制需要单独部署。部署后应分别打开新的编辑器 Chat 和新的 Agents window,确认 Harness、模型默认值、禁止的选择和策略诊断结果都符合预期。发现结果不一致时,先查看 Developer: Policy Diagnostics 和有效的临时 Local 控制,再修改配置。
一个可执行的验收顺序
可以把迁移验收压缩成下面六步:
- 在 Local harness 中保存一个小任务的输入、输出、工具调用和审批结果。
- 在相同工作区新建 Copilot harness 会话,确认模型选择没有被误认为 Harness 切换。
- 打开
Chat: Open Customizations的Migrations,逐项确认 prompt、skills、hooks、MCP 和扩展工具。 - 运行无副作用的 MCP 与扩展工具测试,再关闭项目窗口,确认只依赖 Agent Host 的任务是否继续。
- 用临时目录验证允许动作与拒绝动作,检查 sandbox、网络和审批策略的最终结果。
- 再处理旧会话,核对历史、未发送输入和归档状态;组织部署则追加
Developer: Policy Diagnostics检查。
这套顺序把“能选到 Copilot”与“工作流可用”分开,也把会话迁移与安全策略验证分开。若某项工具只能在 Local harness 工作,不要为了赶在移除前完成切换而静默放宽权限;应记录阻塞点,寻找 Copilot harness 的替代集成,并把临时 Local 例外限制在组织明确批准的范围内。官方迁移指南也提醒,Local fallback 不具备 Copilot 运行时的全部 sandbox 与权限保护,保留它本身就是一个需要审批的安全取舍。