Qwen Code 扩展运行时刷新机制深度解析自动编排、增量 MCP 与/reload-plugins修复路径【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本篇技术指南聚焦 Qwen Code终端内开源 AI 编程代理的**扩展运行时刷新Extension Runtime Refresh**机制当用户在会话中安装、更新、启用、禁用或卸载扩展时运行时的 Skills、Commands、MCP、Agents、LSP 与 Hooks 如何被自动刷新以及当扩展文件被外部手工修改时如何通过/reload-plugins完成一次手动修复式重载。读完本文你将掌握该机制的完整设计蓝图、核心编排函数的源码级实现、分阶段落地路径以及各子系统的刷新契约与模型侧可见性通知的取舍。本文以仓库内设计文档 docs/plans/2026-07-01-extension-runtime-refresh-implementation.md 为主体骨架并结合 packages/core/src/extension/extension-runtime-refresh.ts 等实现代码与测试用例展开验证。一、设计目标保持自动生效的扩展 UXQwen Code 的核心体验原则是扩展 UI 层面的变更应当自动生效。用户安装、更新、启用、禁用或卸载扩展后不需要手工运行任何命令扩展在运行中的会话里就应当变得可用或不可用。这与 Claude Code 的插件流程形成对照——后者在插件变更后主要设置一个 stale 标记并提示用户运行/reload-plugins。因此剩余工作不是要不要自动刷新而是把自动刷新路径补完整Commands、Hooks、LSP 目前未被纳入编排把自动刷新做得更便宜MCP 全量重启过于昂贵应改为增量 reconcile让模型对能力变化的感知更准确skills/commands/MCP tools 只发新增通知、不发移除通知导致模型上下文里残留过期能力清单。对于 Qwen Code 未主动发起的外部文件变更例如手工编辑已安装扩展目录下的文件则另行设计/reload-plugins作为修复/重同步路径复用与自动变更相同的运行时刷新编排。二、当前行为与五个缺口2.1 现有的刷新链路设计文档给出了当前ExtensionManager在扩展变更后的刷新链路enable/disable/install/update/uninstall - ExtensionManager.refreshTools() - refreshMemory() - ToolRegistry.restartMcpServers() - SkillManager.refreshCache() - SubagentManager.refreshCache() - refreshHierarchicalMemory()这条链路有用但不完整具体缺口有五个子系统当前行为缺口MCPrestartMcpServers()重启并重新发现全部MCP 服务器刷新成本过高与变更无关的服务器也被波及Commands依赖 UI 层的命令重载行为间接重建没有 core 层命令管理器扩展变更缺少明确的命令刷新契约Hooks不在扩展运行时刷新编排内禁用/卸载扩展不会移除其 hooks启用/安装/更新也不会注册 hooksLSP原生 LSP 服务仅在启动时初始化一次运行期扩展变更不会重新初始化 LSP 服务器配置模型可见性skills/commands/MCP tools 只通知新增、不通知移除agents 更新 schema 但不发增减提醒模型可能依赖过期能力上下文认为已禁用扩展的能力仍然可用2.2 不对称通知的具体表现模型侧model-facing的可用性通知存在明显不对称Skills 与模型可调用的 commands启动后会广播新增可用提醒但禁用扩展后旧清单仍可能残留在对话历史里MCP tools新增时广播提醒移除时不广播AgentsAgentTool会更新 tool schema 与描述但不会发送显式的新增/移除 agent 类型提醒实践中模型在被提示前可能根本注意不到新扩展 agent。三、设计方向的三条主线3.1 保留自动变更刷新扩展 UI 变更的自动刷新是默认路径因为它保留了现有 UX用户切换扩展开关时扩展应当真正生效或失效而不是要求用户额外执行命令。3.2 仅对外部变更提供手动重载/reload-plugins专门面向 Qwen Code 变更 API 之外的文件变化用户手工编辑已安装扩展目录下的文件外部进程更新扩展内容marketplace 或本地扩展源在磁盘上发生变化watcher 检测到变化但在嘈杂的写入期间不应自动刷新。该命令必须复用与自动变更相同的运行时刷新编排保证两条路径行为一致。3.3 运行时刷新与模型通知分离刷新运行时会改变实际能执行什么模型通知则改变模型认为自己能调用什么——二者相关但属于两个独立关注点。运行时刷新覆盖所有应更新的组件模型通知则负责让对话上下文中的能力清单与运行期可用状态保持一致。四、子系统行为与刷新契约4.1 Skills扩展 skills 由SkillManager.refreshCache()从激活扩展加载SkillTool.refreshSkills()更新内存中的运行时集合。核心问题面向模型的available_skills路径在启动后是只增不减的。禁用扩展会从运行时状态移除 skill但旧清单仍可能残留在对话历史中。计划行为保留SkillManager.refreshCache()的运行时刷新扩展运行时刷新后提供发送当前完整可用 skills/commands 清单或等价明确增量delta的通道避免只依赖新 skills 已可用这类提醒来承载扩展变更通知。4.2 Commands扩展命令默认是对用户可见的斜杠命令当modelInvocable true时它们进入 Skill tool 的可用命令清单可被模型按名调用。核心问题core 层没有命令管理器命令重载是 CLI/UI 层操作扩展变更缺少明确的命令刷新契约。计划行为在 CLI/TUI 层可用时把命令重载显式纳入扩展运行时刷新确保模型可调用的扩展命令在发出模型侧 skill 提醒之前完成 Skill tool provider 更新保持最小改动不把整个命令系统迁入 core。4.3 MCP扩展 MCP 服务器配置通过Config.getMergedMcpServers()合并。当前restartMcpServers()会重启并重新发现所有 MCP 服务器。计划行为复用或扩展现有的增量 MCP reconcile 路径扩展缓存状态更新后对最新的合并 MCP 映射做 reconcile连接新增的、断开移除的、只重启变更的服务器保留既有新增 MCP tool提醒新增移除 MCP tool提醒避免禁用扩展后模型仍依赖过期工具上下文。4.4 Agents扩展 agents 由SubagentManager.refreshCache()加载。AgentTool监听 subagent 变化更新其描述与subagent_typeschema 枚举然后调用geminiClient.setTools()。核心问题这更新了运行时/tool schema但没有显式的新增/移除 agent 类型对话提醒。计划行为保留SubagentManager.refreshCache()与AgentToolschema 刷新新增模型侧新增/移除 agent 类型提醒意图上与 Claude Code 的agent_listing_delta类似不把每个 agent 做成独立 toolagents 仍通过Agenttool 的subagent_type参数选择。4.5 LSP扩展的lspServers可被 LSP 配置加载器读取但 LSP 服务只在启动时初始化一次。计划行为为扩展运行时刷新添加可选 LSP 重新初始化钩子当 LSP 已启用且 API 可用时调用首版不为 LSP 添加模型侧提醒——LSP 以固定的lsptool 暴露服务器状态更适合通过状态面板与工具结果呈现。4.6 Hooks扩展 hooks 应被视为运行时扩展组件。当前扩展变更刷新中没有明确的 hook 重载步骤。计划行为将 hook 重载加入扩展运行时刷新编排禁用/卸载扩展应移除其 hooks启用/安装/更新扩展应注册其当前 hooks。五、仓库落地实现refreshExtensionRuntime编排器设计文档的 PR 1 目标共享扩展运行时刷新编排器已在仓库中落地。核心实现在 packages/core/src/extension/extension-runtime-refresh.ts被 packages/core/src/extension/extensionManager.ts 引入并在 enable/disable 等变更路径refreshToolsAfterActivation中调用。refreshExtensionRuntime(config)接收一个从Config中 Pick 出的子集export type ExtensionRuntimeRefreshConfig Pick Config, | getSettingsMcpServers | reinitializeMcpServers | getSkillManager | getSubagentManager | getHookSystem | refreshHierarchicalMemory { reinitializeLsp?: Config[reinitializeLsp]; };5.1 严格的执行顺序编排函数按以下顺序执行顺序本身即是契约MCP 必须先settleawait config.reinitializeMcpServers(config.getSettingsMcpServers())。理由是 skills 与 subagents 的刷新可能依赖更新后的 MCP 工具列表例如SkillTool.refreshSkills()会重建模型侧工具描述并更新llmClient的工具列表。此处失败对用户可见扩展 MCP 工具将不可用因此直接向上抛出。LSP 可选重初始化调用config.reinitializeLsp?.()检查返回的reconcile.failed列表部分失败时构造LSP reload partially failed: ...错误。Skills / Subagents / Hooks 并行刷新使用Promise.allSettled而非Promise.all——某一路失败不能阻止其他路生效也不能跳过最后的内存刷新。hook 重载失败会单独捕获并在末尾汇总抛出。层次记忆刷新收尾await config.refreshHierarchicalMemory()包裹在 try/catch 中因为调用方enableExtension/installExtension此时已改写了isActive/installed标志内存刷新失败不应回滚整个扩展状态迁移只应留下暂时过期的记忆。错误聚合hook 与 LSP 的失败被收集单失败直接抛出多失败则抛AggregateError消息为Extension runtime refresh had multiple failures。5.2 测试用例印证packages/core/src/extension/extension-runtime-refresh.test.ts 用 vitest 的 mock 函数严格验证了上述行为顺序断言order[0] mcp、order[1] lsp、skills/subagents/hooks 三者以任意顺序并行、order[5] memoryMCP 失败传播reinitializeMcpServers抛错时后续 skills/subagents/hooks/memory 全部不执行LSP 部分失败reconcile.failed: [clangd]时抛出LSP reload partially failed: clangd但其余刷新腿仍全部执行refreshCache 腿失败不阻断skills 刷新 reject 时函数正常 resolve其余腿继续hook 失败汇总hook 与 LSP 同时失败时抛AggregateError内存失败容忍refreshHierarchicalMemory抛错时函数仍 resolve。六、/reload-plugins手动修复路径的落地设计文档的 PR 5/reload-plugins同样已在 CLI 层落地。6.1 CLI 命令实现packages/cli/src/ui/commands/reload-plugins-command.ts 定义了内建斜杠命令reload-plugins描述为 Reload extension changes from disksupportedModes限定为[interactive]说明它面向交互式会话。执行流程通过context.services.config获取配置调用extensionRefreshState.notifyExtensionsReloadStarted()标记重载开始执行reloadPluginsRuntime({ config, reloadCommands: context.ui.reloadCommands })成功后clearExtensionsChanged()并输出信息级消息失败时markExtensionsReloadFailed()并输出错误消息。6.2 运行时重载与摘要packages/cli/src/config/extension-runtime-reload.ts 中的reloadPluginsRuntime是核心执行体if (options.config.isSafeMode()) { throw new Error(Extension reload is disabled in safe mode.); } const manager options.config.getExtensionManager(); await manager.refreshCache(); await manager.refreshTools(); await options.reloadCommands?.(); return summarizeExtensions(options.config.getActiveExtensions());值得注意的是安全模式safe mode下扩展重载被禁止。刷新顺序为refreshCache() → refreshTools() → reloadCommands()最后通过summarizeExtensions生成ReloadPluginsSummary摘要。6.3 摘要的七类计数摘要ReloadPluginsSummary覆盖七类组件计数并由formatReloadPluginsSummary渲染为一条信息{{count}} extensions · {{count}} commands · {{count}} skills · {{count}} agents · {{count}} hooks · {{count}} extension MCP servers · {{count}} extension LSP servers对应的统计口径从源码可见commandsextension.commands?.lengthskillsextension.skills?.lengthagentsextension.agents?.lengthhooks按extension.hooks各事件名下definition.hooks数组长度累加mcpServerCountextension.mcpServers的键数量lspServerCountlspServers为字符串记 1为对象则记键数量。6.4 内容刷新辅助路径同一文件还提供了refreshExtensionContentRuntime不做 MCP/LSP 重初始化仅并行执行refreshCache()、skills/subagentsrefreshCache()与reloadCommands()任何失败腿的错误信息以;拼接后整体抛出——适用于更轻量的扩展内容刷新场景。七、分阶段落地路线PR 序列设计文档给出清晰的六步渐进式落地每一步都严格控制范围避免行为突变PR 1共享扩展运行时刷新编排器把现有刷新序列收敛到一个共享编排函数供所有扩展变更复用保持当前行为不变保留自动刷新、不加 watcher、不加/reload-plugins、不改模型提醒MCP 在本 PR 中仍可使用现有全量重启价值为后续 PR 提供统一的挂载点commands、hooks、LSP、MCP reconcile、模型通知让评审聚焦于结构而非行为。PR 2补全自动变更刷新CLI/TUI 命令服务可用时重载 commands重载 hooks可选 LSP 重初始化保留 skills、agents、memory 刷新MCP 行为除非有最小无风险集成否则不变。PR 3扩展变更的增量 MCP 刷新扩展缓存变化后对最新合并 MCP 配置做 reconcile避免重启无关 MCP 服务器保留既有事件/更新行为保证setTools()仍走 MCP 更新路径价值显著降低切换扩展时的副作用与延迟。PR 4模型侧可用性通知skills/模型可调用 commands 受影响时发送当前完整清单或等价明确增量新增移除 MCP tool提醒新增 agent 增减提醒首版不加 LSP 提醒。PR 5/reload-plugins复用共享编排器输出简洁刷新摘要不取代自动变更刷新负责清理后续 watcher PR 引入的过期状态。PR 6扩展文件 watcher 与过期通知保守地监控扩展相关文件白名单qwen-extension.json.qwen-extension-install.json扩展 enablement、preferences 与 source 元数据commands/**、skills/**、agents/**、hooks/**被引用的 LSP 配置文件扩展上下文文件如GEMINI.md检测到变化后标记扩展运行时为 stale弹出 UI 通知建议用户运行/reload-plugins不对每个文件事件自动重载避免刷新变得嘈杂或脆弱。八、非目标与开放问题8.1 明确的非目标不把 Qwen Code 的自动扩展变更行为替换为强制手动重载流程不在具体调用点需要之前引入宽泛的通用刷新框架不把每种 agent 类型做成独立的模型 tool不让 LSP 可用性提醒进入首版实现不自动重载每个扩展文件 watcher 事件。8.2 待定问题命令重载最小的稳定 API 是什么如何在避免 core 与 CLI 过度耦合的前提下被扩展运行时刷新调用skills/commands 刷新后应发完整清单还是增删增量完整清单更简单也更贴近现有available_skills模型移除的 MCP tool 提醒是列出全部被移除工具还是按扩展/服务器分组以降低噪音哪个既有 hook 重载函数应成为公开编排点/reload-plugins在非交互模式下应如何表现如果要有的话。九、总结Qwen Code 的扩展运行时刷新机制围绕三条主线展开保留自动变更刷新 UX、为外部文件变更提供/reload-plugins修复路径、把运行时刷新与模型通知彻底分离。仓库中的 extension-runtime-refresh.ts 已将设计蓝图落地为先 MCP/LSP、再并行刷新 skills/subagents/hooks、最后刷层次记忆的严格编排配套测试验证了顺序与容错语义CLI 层的 reload-plugins-command.ts 与 extension-runtime-reload.ts 提供了面向磁盘外部变更的手动重载与七类计数摘要。从源码结构看后续演进方向集中在增量 MCP reconcile 与模型侧增减通知的补齐上而这些能力最终服务于同一个目标让运行时会话中的扩展能力与模型认知始终保持一致。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考