Qwen Code LSP 运行时热重载Hot Reload设计解析增量 Reconcile 与安全边界【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文围绕 Qwen Code终端内 AI 编码代理中LSPLanguage Server Protocol服务配置的运行时热重载展开讲解该设计如何在不重启当前会话的前提下让工作区.lsp.json的修改新增、删除、变更语言服务器立即生效同时不打断未变更服务器的连接与预热状态。文章基于docs/design/hot-reload/lsp-runtime-reinitialization.md设计文档并结合packages/core与packages/cli中的落地实现展开。读完本文你将掌握 LSP 配置的哈希识别、LspServerManager增量 reconcile 队列、NativeLspService.reinitialize()的文档重放机制、CLI 侧LspConfigWatcher的防抖监听以及围绕信任与命令注入的安全边界设计。背景为什么SettingsWatcher管不到 LSPQwen Code 的设计文档遵循与 MCP 热重载相同的分层原则CLI 决定何时触发重载Core 决定如何更新运行时状态见 mcp-runtime-reinitialization.md同时复用settings-change-detection.md中确立的监听器原则启动时不做文件系统副作用、变更防抖、语义化 diff、监听器串行执行、监听器失败不影响主会话。但 LSP 与 MCP 的关键差异在于LSP 服务器配置并不存放在settings.json中。当前原生 LSP 服务的启动链路是LspConfigLoader读取工作区.lsp.json与已启用扩展声明的lspServers将结果写入单会话的LspServerManager通过NativeLspService.discoverAndPrepare()通过start()启动全部配置的服务器。因此SettingsWatcher无法感知工作区.lsp.json的变化需要独立的监听与重载通道。现状代码评估设计文档原文要点LSP 启动只受--experimental-lsp控制packages/cli/src/config/config.ts目前没有--allowed-lsp-server-names之类的 LSP CLI 允许列表参数现有--allowed-mcp-server-names仅针对 MCP。NativeLspService在 CLI 配置加载阶段只构造一次启动路径依次是discoverAndPrepare()→start()→ 包装为NativeLspClient挂到Config。Config.setLspClient()与Config.setLspInitializationError()在初始化之后会抛错因此热重载不应替换 client 对象而是保留现有NativeLspClient仅对其背后的 service 做增量调和。LspServerManager.setServerConfigs()目前会清空全部 handle尚不支持增量调和下文会看到reconcileServerConfigs()已补上这一能力。仓库当前没有 LSP 共享池路径每个会话持有自己的NativeLspService与子进程/套接字连接。设计为未来共享池预留边界但 v1 只实现单会话模式。设计目标与非目标目标让 LSP 服务器配置变更无需重启当前 Qwen Code 会话即可生效——新增服务器 → 启动删除服务器 → 停止并从状态与工具路由中移除配置变更 → 只重启变更的服务器未变更服务器保持连接保留预热warm-up状态绝不启动不受信任或不被允许的服务器LSP 工具与/lsp状态通过既有 client 对象观察到新运行时状态。非目标本次变更不引入 LSP 共享进程池不支持在运行时切换--experimental-lsp启动时未启用就没有可重载的服务不完全监听影响lspServers的扩展安装/卸载变更扩展配置变更由手动/reload兜底。1. 用稳定哈希识别每个 LSP 服务器设计在 LSP 配置代码附近新增辅助函数export function lspServerConfigHash(config: LspServerConfig): string;该哈希必须稳定且基于LspConfigLoader产出的归一化运行时配置覆盖以下字段name、languages、transport、command、args、env、initializationOptions、settings、extensionToLanguage、workspaceFolder、rootUri、startupTimeout、shutdownTimeout、restartOnCrash、maxRestarts、trustRequired、socket。两条规则很关键对象键必须排序避免 JSON 属性顺序引发无谓重启数组顺序保持有意义因为命令参数顺序与语言优先级可能影响行为。运行时字段进程 id、状态、重启次数、诊断、预热状态等不得纳入哈希。落地实现见 packages/core/src/lsp/configHash.tslspServerConfigHash先通过sortJsonValue递归排序对象键并用Object.create(null)规避__proto__原型污染再对JSON.stringify结果做SHA-256摘要输出 hex 字符串。其类型约束使用satisfies Recordkeyof LspServerConfig, unknown保证未来新增配置字段时编译器强制要求纳入哈希。为兼容未来的共享池设计定义池身份pool identity为lsp:workspaceRoot:serverName:configHashv1 单会话管理器只需要维护serverName - configHash映射但同一个哈希未来可直接复用到池键中。2. 给LspServerManager增加增量 Reconcile热重载不能复用setServerConfigs()它会清空所有 handle因此设计新增async reconcileServerConfigs( configs: LspServerConfig[], ): PromiseLspReconcileResult执行流程构造期望态映射name - config与name - hash对已存在但已从期望态消失的 handle调用既有stopServer()随后删除 handle对哈希发生变化的 handle调用stopServer()替换为{ config, status: NOT_STARTED }再启动对新出现的服务器创建{ config, status: NOT_STARTED }并启动对哈希未变的服务器什么都不做保留原 handle。同时新增私有字段private serverConfigHashes new Mapstring, string();并在stopAll()与clearServerHandles()中清空。返回结果interface LspReconcileResult { added: string[]; removed: string[]; restarted: string[]; unchanged: string[]; failed: string[]; }注意skipped不属于LspServerManager结果——管理器只处理已通过准入的配置被准入拒绝的服务器由NativeLspService.reinitialize()聚合到服务级结果中。并发与失败语义设计文档的硬性要求串行队列在LspServerManager或NativeLspService中加 reconcile 队列stop/start 同一进程绝不能并发竞态新配置到达时若服务器仍在启动须等待handle.startingPromise再停止复用既有启动锁。stopServer()必须等待startingPromise设置stopRequested后先等待启动完成使stopAll()、删除、重启路径都能覆盖仍在分配连接/进程的崩溃重启。失败行为新增或变更的服务器启动失败时保留 handle 并标记FAILED让/lsp能解释失败原因失败不计入added/restarted而是进failed失败启动不缓存配置哈希后续相同配置的保存必须重试而不是被归类为unchanged启动在创建连接/进程之后失败时须释放该连接/进程绝不允许FAILEDhandle 背后残留语言服务器进程或套接字连接。清理资源stopServer()对自有服务器要同时释放两侧——先优雅关闭并结束 LSP 连接若进程仍存活再 kill 派生进程这对由command启动的tcp/socket传输尤为重要仅关闭套接字不够process.kill()需隔离错误处理清理期间进程退出不得中断其余 reconcile。有界优雅关闭若配置未指定shutdownTimeout使用默认关闭超时而非无限等待connection.shutdown()关闭完成或失败时必须清理超时定时器即便超时在竞速中胜出也要观察底层shutdown()promise避免迟到的服务端拒绝变成未处理的 rejection。stopAll()走同一队列仅等待当前队列再遍历 handle 不够因为可能在等待与清理之间插入新的 reconcileNativeLspService.stop()还要通过AbortController协作取消进行中/排队中的reinitialize()防止关闭被慢速重载无限阻塞也防止被取消的重载在stopAll()之后再启动新 LSP 进程。崩溃重启同样串行崩溃重启须经过 reconcile 队列或永久失败时清哈希不得与配置变更 reconcile 并行启动替换进程崩溃重启的 reset 须隔离connection.end()与process.kill()错误。停止后清缓存NativeLspService.stop()在serverManager.stopAll()之后清空openedDocuments与lastConnections已停止的服务不得残留旧文档集合或连接对象。落地实现中LspServerManager用private reconcileQueue: Promiseunknown串行化reconcileServerConfigs、stopAll与崩溃重启packages/core/src/lsp/LspServerManager.ts并刻意“吞掉”队列 promise 的错误防止一次失败污染后续热重载doReconcileServerConfigs按设计流程完成 add/remove/restart/unchanged/failed 分类releaseServerResources将连接关闭与进程 kill 分离执行shutdownConnection用Promise.race 定时器实现有界关闭并始终connection.end()。3.NativeLspService.reinitialize()加载、准入、调和、重放服务层新增async reinitialize(): PromiseLspServiceReinitializeResult流程若requireTrustedWorkspace为 true 且!config.isTrustedFolder()调用serverManager.stopAll()并返回——防止工作区变为不受信任后旧 LSP 进程继续运行用既有LspConfigLoader加载工作区.lsp.json与扩展配置按当前优先级合并配置在调和前应用 LSP 准入过滤器调用serverManager.reconcileServerConfigs(serverConfigs)只清空已移除与成功重启服务器的文档跟踪对removed与restarted清openedDocuments/lastConnectionsunchanged与failed保留文档状态failed 服务器保留文档跟踪以便后续成功重启时重放同一批已打开文档对成功重启的服务器重放textDocument/didOpen把重启前已打开的文档重新告知新服务器使其无需等待下一次 hover、补全或诊断请求去懒加载每个文件重放一个或多个文档后等待与懒加载ensureDocumentOpen()相同的文档打开延迟再报告重载完成。打开文档快照必须在reconcileServerConfigs()返回之后、按reconcile.restarted范围截取——这样 reconcile 挂起期间新打开的文档也能纳入重放快照。.lsp.json解析失败的专门处理不要把解析失败当成空配置watcher 应上报 invalid-config 事件供 CLI 展示用户可见错误但不得为该事件调用reinitialize()reinitialize()保留旧运行时状态、跳过 reconcile把错误写入状态/日志。只有删除文件、或解析出合法的空 JSON 配置才意味着期望配置为空。冷启动与热重载的解析严格度差异loadUserConfigs()保持宽松兼容冷启动跳过无效服务器条目返回可构建的合法条目loadUserConfigsStrict()供热重载使用若既有.lsp.json语法合法但顶层结构非法或某条目无法构建返回错误reinitialize()不做 reconcile——保留非法编辑下的当前 LSP 运行状态。严格路径不得引入冷启动未强制执行的字段级校验否则会出现“启动时合法、下次保存即非法”的不一致收紧已知字段校验应作为启动与热重载两侧同步的独立兼容性决策。严格加载期间文件缺失或被删除ENOENT按“合法空用户配置”处理因为删除.lsp.json就是显式移除全部工作区用户 LSP 服务器的方式。服务级返回与 Config 接线interface LspServiceReinitializeResult { reconcile: LspReconcileResult; skipped: Array{ name: string; reason: server_trust_required; }; }NativeLspClient增加可选reinitialize()并委托给 service为避免在Config.reinitializeLsp()里做不透明类型断言直接扩展LspClient接口reinitialize?: () PromiseLspServiceReinitializeResult;Config新增async reinitializeLsp(): PromiseLspServiceReinitializeResult | undefinedLSP 未启用或没有 client 时是 no-op该方法不得在Config.initialize()之后替换 client。由于setLspInitializationError()初始化后拒绝调用另加运行时安全的私有状态 settersetRuntimeLspInitializationError()重载部分失败failed非空时设置initializationError只有完全成功才清除。落地实现完全吻合packages/core/src/config/config.ts 中reinitializeLsp()先检查isLspEnabled()与lspClient?.reinitialize随后按result.reconcile.failed.length决定设置或清除lspInitializationErrorpackages/core/src/lsp/NativeLspService.ts 的doReinitialize用reinitializeQueue串行化、AbortController协作取消并通过snapshotOpenDocuments/clearDocumentTrackingForServers/replayOpenDocuments完成文档状态迁移。4. 准入与权限边界先审批、后启动现有 LSP 安全检查包括--experimental-lsp是唯一启用开关发现/启动前检查工作区信任每个服务器的trustRequired默认 truespawn 前检查命令存在性与命令路径安全性workspaceFolder被约束在工作区根目录内。热重载必须保留这些检查并在启动新服务器或重启变更服务器之前完成。核心规则是绝不先 spawn、后决定是否允许。工作区输入不可降级信任工作区.lsp.json是工作区控制的输入因此用户配置始终按trustRequired: true处理——即使文件显式声明trustRequired: false也不允许扩展提供的 LSP 配置仍可使用其声明的trustRequired值。这防止不受信任的工作区自行降低信任边界。环境变量注入防护.lsp.json中的环境变量同样由工作区控制。运行时 spawn 可以合并允许的 env 覆盖但NODE_OPTIONS、LD_PRELOAD、LD_LIBRARY_PATH、DYLD_INSERT_LIBRARIES、DYLD_LIBRARY_PATH等代码注入类变量不得被 LSP 配置覆盖PATH对实际服务器进程是允许的保留常见工具链配置。命令存在性探测可以保留探测所需的常规配置 env但解析裸命令名时不得使用配置提供的PATH——防止恶意工作区PATH把clangd --version之类的探测重定向到非预期可执行文件绕过真正的启动路径。敏感 env 键过滤包括仅限探测的PATH过滤必须大小写不敏感避免Path、node_options、Ld_PreLoad等 Windows 风格大小写变体绕过黑名单。落地实现中LspServerManager.buildProcessEnv用SECURITY_SENSITIVE_ENV_KEYS含DYLD_INSERT_LIBRARIES、DYLD_LIBRARY_PATH、LD_AUDIT、LD_LIBRARY_PATH、LD_PRELOAD、NODE_OPTIONS做key.toUpperCase()大小写无关过滤buildCommandProbeEnv在探测环境里额外剔除PATH避免探测阶段被重定向见 packages/core/src/lsp/LspServerManager.ts。允许列表上界当前仓库不支持 LSP 服务器名称的 CLI 允许列表LSP 只有--experimental-lsp允许列表参数仅存在于 MCP。若未来增加--allowed-lsp-server-names必须像 MCP 启动允许列表那样作为整个会话生命周期的上界运行时配置可以收窄该集合但绝不能超出 CLI 启动上界。启动上界存于ConfigParameters.lspcliAllowedLspServerNames?: string[];并暴露 getter不要从可变设置中读取上界。准入逻辑提取为纯函数filterLspServerConfigs(configs, { workspaceTrusted, requireTrustedWorkspace, cliAllowedServerNames, }): { admitted: LspServerConfig[]; skipped: Array{ name: string; reason: server_trust_required; }; }尽管当前没有 LSP 审批存储或 CLI 允许列表该 helper 让安全边界显式化为未来基于哈希的审批闸门留出空间若未来加入--allowed-lsp-server-names届时再增加not_allowed跳过原因v1 不携带未接线的允许列表路径。信任语义与当前启动路径保持一致requireTrustedWorkspace为 true 且工作区不受信任NativeLspService.reinitialize()在服务层停止全部服务器并返回不进入准入过滤器也不保留旧服务器requireTrustedWorkspace为 false服务不全局短路但准入过滤器仍会跳过单个trustRequired: true的服务器工作区受信任trustRequired不阻塞服务器。5. 触发机制自动监听 手动/reload自动监听工作区.lsp.jsonCLI 侧新增窄职责的LspConfigWatcher以SettingsWatcher为模板但职责更小只监听工作区根目录严格匹配 basename.lsp.json不创建任何目录或文件防抖 300 ms用“解析 规范化”比较变更前后的.lsp.json仅格式变化的保存不触发重载ENOENT视为删除区分 JSON 解析失败与其他读取失败两者都向监听器发用户可见的 invalid-config 事件并保留旧运行时状态但错误消息必须反映是 JSON 非法还是不可读文件删除是独立事件通知重载监听器产生空的工作区配置回调串行执行监听器超时与失败隔离对齐SettingsWatcher仅当监听器通知成功后推进语义快照监听器抛出或超时则保留上一快照使相同内容再次保存时重试重载。注册条件仅当config.isLspEnabled()且 client 支持reinitialize()。变更时调用await config.reinitializeLsp();随后发出显式运行时事件AppEvent.LspStatusChanged/lsp、/about、/status等 UI 可订阅刷新。若 reconcile 部分失败先发状态变更事件再向 watcher 抛错让 UI 先看到成功重启的部分同时 watcher 保留旧语义快照供重试失败时还须通过AppEvent.LogError展示用户可见错误尽量包含底层解析/启动错误消息不能只写 debug 日志。落地实现见 packages/cli/src/config/lsp-config-watcher.tsLspConfigWatcher使用 chokidar 监听工作区根depth: 0DEBOUNCE_MS 300、LISTENER_TIMEOUT_MS 30_000readSnapshot对 JSON 做sortJsonValue规范化与 configHash 相同的排序策略notifyListener用Promise.race实现监听器超时隔离并返回是否成功以决定快照推进。packages/cli/src/llm.tsx 的registerLspHotReload完成接线invalid 事件只发AppEvent.LogError不重载成功重载发AppEvent.LspStatusChanged部分失败先发状态事件、再发AppEvent.LogError并抛错保证 UI 反映成功部分、watcher 保留快照重试。手动/reload触发未来的/reload命令落地时应同时调用await config.reinitializeMcpServers(...); await config.reinitializeLsp();手动重载也为扩展lspServers变更提供兜底路径——这些变更未必映射为工作区.lsp.json文件事件。单会话模式与未来共享池当前状态只有单会话模式仓库没有 LSP 版 MCP transport 池。v1 在LspServerManager内部实现增量 reconcile每个会话拥有自己的进程与套接字。未来共享池保留NativeLspService作为消费方把LspServerManager内部替换为对以下池条目的 acquire/releaselsp:workspaceRoot:name:hash准入过滤必须在 acquire 之前发生对齐 MCP 共享池修复确保被拒绝或不受信任的服务器无法经池路径启动。单元测试计划与仓库中的落地验证设计明确优先单元测试针对真实 LSP 服务器的集成测试缓慢且依赖环境不作要求。Core 测试packages/core/src/lsp/configHash.test.ts哈希忽略对象键顺序command、args 顺序、env、settings、workspace folder、socket、信任要求的变更都会改变哈希哈希排除状态/进程/运行时字段。packages/core/src/lsp/LspServerManager.test.ts新增服务器只启动一次删除服务器关闭并移出 handles哈希变化停止旧 handle 启动新 handle未变哈希不启停并保持 handle 身份连接创建后的启动失败释放连接与自有进程tcp/socket由command启动的服务器停止时关闭连接并 kill 自有进程关闭超时定时器在关闭先完成时被清理缺失shutdownTimeout仍用默认超时且不阻塞 reconcilestopAll()等待进行中的启动再释放资源stopAll()经 reconcile 队列串行、不与后续 reconcile 并发process.kill()错误被记录且不中断清理单服务器启动失败不影响其他服务器 reconcile并发 reconcile 串行执行stopAll()与clearServerHandles()清空哈希表失败启动进failed、不计 added/restarted、不缓存哈希初始启动失败清缓存哈希使相同配置可重试崩溃重启与 reconcile 串行、永久失败清哈希崩溃重启 reset 忽略连接/进程清理错误并继续排队重启命令探测保留常规 env 但不用配置提供的PATH代码注入 env 覆盖在 spawn 前被过滤返回结果含 added/removed/restarted/unchanged/failed 而不含准入 skipped。测试须 mockcreateLspConnection、初始化与关闭不启动真实语言服务器。packages/core/src/lsp/NativeLspService.test.tsreinitialize()加载工作区与扩展配置并传合并配置给管理器调和.lsp.json解析失败保留旧运行时状态且不调用管理器调和严格热重载拒绝非法顶层结构与不可构建条目而不调和同一文件冷启动仍加载合法条目删除.lsp.json视为空工作区配置并触发调和严格加载把ENOENT当空用户配置含 watcher 通知与重载之间文件消失的删除竞态不受信任工作区停止全部服务器且不调和/不启动初始发现与热重载应用相同的逐服务器trustRequired准入过滤工作区.lsp.json不能免除trustRequired若实现 CLI 允许列表上界过滤 admitted 配置服务级返回值聚合准入跳过原因restarted/removed 服务器只清自己的文档跟踪failed 服务器不清文档跟踪、后续成功重启可重放重启服务器就绪后为先前打开的文档重放textDocument/didOpen并等待文档打开处理延迟reconcile 挂起期间打开的文档纳入重启服务器重放快照stop()取消进行中的重放延迟与排队的reinitialize()防止它们启动新服务器stop()停止全部服务器后清空文档跟踪缓存。packages/core/src/config/config.test.tsreinitializeLsp()在未启用或无 client 时是 no-op启用且 client 支持时委托调用reinitialize 抛错时状态快照暴露初始化/重载错误部分失败时状态快照暴露初始化/重载错误直到后续完全成功的重载清除。CLI 测试packages/cli/src/config/lspConfigWatcher.test.ts不创建.lsp.json检测 create/modify/delete忽略无关文件规范化解析后忽略纯格式变更解析失败发出 invalid-config 通知用户可见且不触发 LSP 重初始化非 ENOENT 读取失败发出用户可见的读取失败消息且不触发重初始化删除.lsp.json触发重载监听器重复文件事件被防抖慢监听器串行执行监听器失败不推进存储快照、相同内容可被后续通知重试。packages/cli/src/ui/AppContainer.test.tsx或对应事件测试AppEvent.LspStatusChanged触发 UI 刷新重载失败经AppEvent.LogError发用户可见错误部分调和失败仍在监听器 reject 前发AppEvent.LspStatusChanged使 UI 反映成功部分。packages/cli/src/config/config.test.ts保留--experimental-lsp构造并启动原生 LSP 的既有断言若增加--allowed-lsp-server-names解析器支持逗号分隔值与重复 flag并作为启动上界存储。packages/cli/src/ui/commands/lspCommand.test.ts若LspStatusSnapshot暴露 skipped 原因状态输出可展示 skipped/disallowed 服务器。覆盖率目标新纯函数接近 100%watcher 分支覆盖率对齐SettingsWatcher管理器 reconcile 覆盖 add/remove/change/unchanged/failure/concurrency。上述测试文件在当前仓库中均已落地configHash.test.ts、LspServerManager.test.ts、NativeLspService.test.ts、lsp-config-watcher.test.ts、llm.test.tsx设计文档描述的方案已从设计稿演进为可运行代码。严格评审结论与剩余风险结论v1 不应使用 stop-all/start-all该实现最简单但每次保存都会重启未变更的语言服务器并丢失预热状态现有管理器已有逐服务器生命周期方法增量 reconcile 是可控的额外代码量。不要把.lsp.json变更塞进SettingsWatcherSettingsWatcher负责 settings 作用域重载让它监听任意工作区文件会模糊契约、让 MCP/settings 行为更难推理独立窄职责的.lsp.jsonwatcher 更清晰。初始化后不替换NativeLspClientConfig.setLspClient()明确禁止 post-init 变更更新 adapter 背后的 service 可避免扩大生命周期 API。准入必须先于进程 spawn 或池 acquire这与 MCP 共享池设计指出的风险一致即使 LSP 当前没有池服务级重载结果也应返回启动前过滤的 skipped 原因防止未来池路径意外启动被拒服务器。新 LSP CLI 允许列表可选但若加入必须是上界当前代码没有 LSP 允许列表设计不允许设置项在运行时扩大命令行限制否则会比 MCP 热重载安全语义更弱。剩余风险扩展lspServers可能在.lsp.json不变的情况下变化自动 watcher 不覆盖全部扩展文件系统变更手动/reload兜底该路径部分语言服务器不耐受快速重启串行 reconcile 与防抖降低风险但测试应覆盖快速连续变更TCP/socket 服务器可能是外部管理的守护进程reconcile 应关闭连接但仅当本进程通过commandspawn 了该服务器时才对其进程主张所有权。参考与延伸阅读设计文档lsp-runtime-reinitialization.md姊妹设计mcp-runtime-reinitialization.md、settings-change-detection.md核心实现LspServerManager.ts、NativeLspService.ts、configHash.ts、LspConfigLoader.tsCLI 接线lsp-config-watcher.ts、llm.tsx、events.ts配置入口config.ts、config.ts【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考