跳到主内容

events 使用指南

create-dsh-plugin 脚手架内的事件/生命周期模板示例：零运行时依赖，演示监听 session/event、tools/change、tools/pre-execute 与 ctx.effect 资源清理。

本文为派生内容（基于 wiki / faq / compatibility_json 自动组装），非 AI 即时创作。

本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-suite (create-dsh-plugin/events 模板)

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add github:whyihaveyou/dsh-suite#path:packages/create-dsh-plugin/templates/events

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

这个 events 模板具体监听了哪些事件？

订阅三个：session/event（会话日志变化，按 type/计数打印）、tools/change（工具注册表增删，每事件打印）、tools/pre-execute（工具调用拦截水线，打印后必须调 next() 放行，否则会短路阻断工具调用）（templates/events/src/index.ts:21-43）。

为什么说它"零运行时依赖"？

因为 src/index.ts 里所有 dsh 相关导入都加了 import type 前缀（templates/events/src/index.ts:7-9），编译后 dist/ 里没有任何 dsh 包的实际 require；package.json#dependencies 为空，dsh-tools / dsh-session 全部下沉到 devDependencies 仅取类型（templates/events/package.json:24-34）。

它跟 create-dsh-plugin 工具本身是什么关系？

它是 create-dsh-plugin 脚手架的子模板目录之一（templates/events/）。create-dsh-plugin 在生成项目时会递归读这个目录、用占位符替换 {{PKG_NAME}} / {{PLUGIN_ID}} / {{CORDIS_VERSION}} 等 token，输出一个完整的、可独立安装的事件插件项目（packages/create-dsh-plugin/src/generate.js:67-74 / packages/create-dsh-plugin/src/templates.js:3）。

直接 dsh plugin add github:.../templates/events 安装会成功吗？

会。模板根目录就是合法的 cordis bundle：package.json 里声明了 dsh.bundle.patch: ./cordis.patch.yml，宿主 loader 会按这个 patch 把 {{PKG_NAME}} 替换为包名后注入到加载列表，前提是先跑 pnpm install && pnpm run build 产出 dist/index.js（templates/events/package.json:15-19 / templates/events/cordis.patch.yml:7-9）。

为什么我的定时器在卸载时不会自动停？

因为 ctx.on() 是宿主管理的 effect，卸载会自动清理；但你自己 setInterval 起的定时器宿主不管，必须像模板里那样包进 ctx.effect(() => { const timer = setInterval(...); return () => clearInterval(timer) })，返回的 disposer 才是卸载钩子（templates/events/src/index.ts:45-59）。

修改完模板代码后，怎么验证没把脚手架搞坏？

在 packages/create-dsh-plugin 目录下跑 node --test，里面有三个 generate 模板的快照测试，会断言 events 模板没有遗留 {{token}}、运行时依赖仍为空、并包含 ctx.on( 与 ctx.effect(；想跑完整链路（pnpm install → tsc → dsh plugin add）需加 DSH_SMOKE_VERIFY=1（packages/create-dsh-plugin/test/smoke.test.mjs:66-79 / 109-119）。

用它生成的插件和官方 DSH 版本对不上怎么办？

脚手架在生成时通过 npm view @deepseek-ai/dsh-tools dist-tags.next 拉取当前 next-tag 的精确版本写进 devDependencies，离线时回退到 0.1.0-rc.6。DSH 升大版本时，重新跑一次生成即可拿到新版本号，无需手改（packages/create-dsh-plugin/src/util.js:54-80）。

模板里的 cordis.patch.yml 为什么写包名而不是相对路径？

因为 patch 的 name 走 node_modules / $DSH_HOME/profiles/node_modules 解析，模板已用 {{PKG_NAME}} token 注入包名；写相对路径会让宿主找不到入口。模板顶部注释专门把这个坑写出来防呆（templates/events/cordis.patch.yml:1-9）。

— 源: plugin_wiki.faq_json

兼容性

  • DSH: 0.1.0-rc.6（模板本身的 host peerDependency 由 @deepseek-ai/cordis@^{{CORDIS_VERSION}} 解析，默认 cordis=4.0.1；运行时 dsh 版本由用户在生成时通过 next-tag 锁定，默认 0.1.0-rc.6，见 packages/create-dsh-plugin/src/util.js:54-80）
  • Node: ^22.19.0 || >=24.0.0（脚手架根 package.json 的 engines 字段；模板自身未声明 engines）

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则

events 使用指南