npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@qilin-agent/hmr

v3.1.12

Published

Coordinated module and profile configuration hot reload

Readme


description: "通过统一协调队列热重载插件代码和 profile 配置。" kind: "package-reference"

@qilin-agent/hmr

English | 中文

概述

在应用运行期间重载插件源码和配置。模块替换、Include 刷新与 profile 配置变更共用一个队列。包安装在该队列之外执行。ctx.hmr 保留现有 Cordis HMR 的配置和事件。

目录


使用本包

启动器提供 profileContext 时,base 组合包以 root: [] 启用 HMR;没有该 profile 上下文的宿主保留此条目为禁用状态。Headless、SDK 和 ACP 组合包在 YAML 中禁用此条目,后续 profile patch 可以重新启用。禁用或省略 HMR 时,更改在重启后生效。如需监听源码模块,在启动前通过 profile patch 配置 base 组合包提供的 hmr 条目:

- id: hmr
  disabled: false
  config:
    root: ["."]

已有配置将模块名 @qilin-agent/kylin-plugin-hmr 替换为 @qilin-agent/hmr。继续提供 hmr 服务键、baseDir、config、getLinked()、getOuterStack()、hmr/change 和 hmr/reload。工作区保留 vendored 包;QILIN profile 使用本包。

配置

| 字段 | 默认值 | 含义 | |---|---|---| | base | Context 的 base URL | 模块监听的基准目录。 | | root | ["."] | 模块监听目录;[] 仅保留显式注册的配置监听。 | | ignored | ["**/node_modules", "**/.*", "cache", "data"] | 排除的模块路径。 | | debounce | 100 | 合并模块变化的毫秒数。 |

Chokidar 选项(包括轮询)保持原有含义。精确配置监听同时观察新增、删除及初始不存在的父目录。它们默认使用 awaitWriteFinish: true:编辑后等待 Chokidar 的 2 秒写入稳定窗口,避免其变化事件节流丢失通知。可通过 awaitWriteFinish 调整窗口;禁用它可能漏掉快速连续编辑。直接通过 Plugin Manager 发起的操作无需等待文件事件即可应用。

由 HMR 的 profile 监听或插件管理器发起的一次 profile 重新组合,还会替换那些已加载文件在磁盘上发生变化、且文件位于 profile 目录或其 node_modules 链接目标之下的插件。因此,就地改变了文件的包——例如构建产物变化的链接包,或被另一处安装升级的依赖——会在下一次重新组合时生效,无需重启。reconcileProfile() 会报告它替换了什么、还有什么需要重启以及原因。替换加载失败时,前一版插件会停止,并带着加载错误被报告为 failed,而不是报告为需要重启(那会加载同一批文件);此后每次重新组合都会再次导入它,因此一旦其文件或依赖被修正,它就会启动。


理解实现

watchConfig() 注册会被等待的配置处理器。runExclusive() 将配置变更、Loader 更新与自动重载串行化,并拒绝嵌套事务。包安装和删除在该队列之外执行。HMR 不获取包操作写锁;manifest 通知仅在有序的 qilin.profile.bundles 列表变化时触发重载。profile 与 home patch 变化也会触发重新组合。配置事务期间收到的文件事件在事务结束后处理。Include 刷新与 profile 重载经由普通 Loader 条目更新到达插件;仅 volatile 的变化由 Loader 就地提交。

App-boot 负责 profile 解析和 patch 优先级规则。HMR 读取启动器提供的纯数据 profileContext,在初始化时注册 profile manifest 和两份用户 patch 的监听,并等待应用就绪后处理更改。销毁 HMR 时会关闭监听器并取消等待启动的重载。配置监听器在当前事务上下文之外启动,使后续通知可以进入队列。

node_modules 之外的 package.json 变化使该包的配置缓存失效。仅作为配置的 manifest 不触发模块重载;作为 JSON 模块导入的 manifest 保留依赖驱动重载,位于宿主依赖图中的 manifest 保留宿主重载。专属配置监听保留原有归属。新包入口在 Loader entry 重启时生效。

Loader entry 保留原始导入结果。HMR 为每个 entry 名称与配置树 base URL 保留所有不同的已导入命名空间;尚未初始化的 entry 不会覆盖其他 entry 的命名空间。HMR 将这些对象与缓存中 ModuleJob 的模块命名空间按对象身份匹配,不再重新解析 entry 名称。没有已导入命名空间的名称和 cordis: 内置入口仍按名称解析。因此 exports 或 main 改变后,源码重载仍使用已加载模块。

共享同一运行时的 entry 一起替换,每个 entry 使用其自身模块对应的实现。同一模块的重复 entry 仍保有各自的插件实例。替换失败时,HMR 清理已部分激活的替换实例,并恢复原来的模块和插件实现。重载成功后更新所有匹配的 entry 记录,包括已停用的 entry;替换失败时这些记录保持不变。从未加载过的 entry 仍保持未初始化状态。

package-manifest.ts 封装 package 读取、scope、type 和最近 manifest 查询所需的 Node internal 接口。每个 HMR 实例拥有自己的配置缓存,销毁时恢复它安装的 hook。manifest 失效会清空 ESM ResolveCache 和 CommonJS _pathCache:它们都不记录查询过的全部 manifest,入口也可能指向包目录之外。CommonJS 加载先用 Node 默认 resolver 解析请求,再进入原生 loader,绕过旧请求别名并保留已求值模块。同步 resolve hook 收到的是解析后的文件名。普通模块替换仍由 HMR 独立处理。

被监听模块的路径沿用 Node ESM 解析所用的 realpathSync() 表示,包括 Windows 短目录名,使文件事件与模块缓存匹配。

模块替换实现源自 @cordisjs/plugin-hmr 1.0.15,包含 Harness 的 Node loader 和惰性配置修改。保留其 MIT 许可证。

模型体验

被重载的插件

模型看到什么

ctx.hmr 不添加模型工具或消息。加载后的插件决定后续工具和提示词贡献。

Token 影响

没有直接的 token 贡献。

KV Cache 影响

重载提供上下文的插件可能改变后续请求前缀;HMR 不改写对话历史。

已知限制与延期工作

  • 模块替换需要 Node loader 内部接口。框架依赖变化调用宿主提供的 loader.exit() 钩子;HMR 本身不重启进程。
  • 仅 package.json 的改动不会被发现,node_modules 之下 manifest 的监听通知仍被忽略。浏览器 Client 模块图保留独立的浏览器侧加载机制。
  • TSX loader 和普通应用自行创建的 Worker 不在包缓存刷新支持范围内。
  • CommonJS 请求必须能由 Node 默认 resolver 解析。同步 hook 可以像 Desktop 的 Office resolver 一样处理解析后的文件名;依赖原始请求名或引入虚拟请求的 hook 不受支持。内置模块保留 Node 原有的加载行为。
  • 后续工作:跨 HMR 销毁和替换保留包配置失效状态。恢复原生 reader 后,其旧配置缓存可能重新可见。
  • 如果共享运行时的替换模块具有不同的插件回调,没有 Loader entry 的实例就无法确定应使用哪一个。HMR 会报告歧义错误并回滚此次重载。

开发备注

无。