DSH 插件(一):一个插件从 package.json 到运行时
工具写完了,dsh --profile web --dump-config 里也能看到插件,可模型一调用就报:
Invalid schema for function 'export_session':
{"type":"string","description":"..."} is not of type "string"参数明明写了 session 和 format,看起来没问题。真正的原因是:我用的是裸 ctx.tools.register(),它不会帮我把“参数名映射”编译成 JSON Schema。这个 bug 花的时间比写整个插件还长。
这篇不讲某个插件的功能,只讲一个包从安装到生效要经过哪些关,以及每一关最容易错在哪。素材来自 session-export 的开发笔记,里面记的都是实际报过错、排查过的问题。
一、插件不是独立应用
先看一个最小插件的全部“身份文件”。
package.json 里真正决定它是不是 DSH 插件的,不是 main,而是这两段:
{
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"client": { "platform": "web" }
},
"exports": { "./client": "./src/client.js" }
}cordis.patch.yml 则决定它插到宿主配置树的哪个位置:
- insert:
- id: dsh-plugin-session-export
name: dsh-plugin-session-export就这四行。没有端口、没有进程、没有自己的配置文件。宿主启动时读 profile,把 bundle patch 应用到配置树,再调用插件的 apply(ctx, config)。从这一刻起,插件才拿到 ctx。
所以插件的能力边界完全由 ctx 决定:能注册工具、能订阅事件、能挂 Web 路由;但不能改 Agent 的循环,也不能假设自己独占某个服务。
为什么不直接 Fork 宿主
改宿主源码确实什么都能做,但升级要重新合并,插件之间也会互相踩。旁路的代价是只能使用公开契约,收益是 9 个插件可以独立安装、独立卸载、独立发版。这套插件全部选了后者。
二、加载链路:四道关
一个插件从安装到生效,依次经过:
- profile 的
dsh.profile.bundles决定装不装; package.json的dsh.bundle.patch决定插到配置树哪里;apply(ctx, config)执行注册逻辑;dsh.client+exports["./client"]决定浏览器端加不加载。
前三步在 Node 侧,第四步在浏览器侧。两边共享同一个包名,但不共享运行时:Node 侧拿不到 DOM,浏览器侧拿不到 ctx。session-export 的面板之所以要再开一个 HTTP 路由,就是因为这个边界。
三、四个真实踩过的坑
坑一:裸注册的工具参数必须是完整 JSON Schema
这是耗时最长的 bug。defineTool() 内部会把参数名映射编译成标准 JSON Schema,而裸 ctx.tools.register() 直接透传:
// ❌ 报错:参数名映射不是合法 JSON Schema
parameters: {
session: { type: "string", description: "会话 ID" },
format: { type: "string", description: "md 或 html" },
}
// ✅ 根必须是 object,参数放进 properties
parameters: {
type: "object",
properties: {
session: { type: "string", description: "会话 ID" },
format: { type: "string", description: "md 或 html" },
},
}还有一个连带规则:属性里不能写 required: false。可选参数直接省略 required,写了就会抛 required must be true when present,因为模型 API 不接受这种写法。
坑二:inject 里写不存在的服务,整个应用会崩
// ❌ webServer 在某些 profile 里不存在,cordis 注入校验失败
export const inject = ["tools", "webServer", "sessions"];
// ✅ 只声明确定存在的,可选服务按需取
export const inject = ["tools", "sessions"];症状不是“插件没加载”,而是 dsh web 启动后进程直接退出。更麻烦的是,webServer 可能比插件晚初始化,ctx.get("webServer") 第一次拿到的是 undefined。正确做法是在 ctx.effect() 里轮询等待,而不是判断一次就放弃:
ctx.effect(() => {
let disposed = false;
const tryRegister = () => {
if (disposed) return;
const ws = ctx.get("webServer");
if (ws?.register) registerRoutes(ws);
else setTimeout(tryRegister, 500);
};
tryRegister();
return () => { disposed = true; };
});坑三:浏览器端 factory 只收一个参数
// ❌ exports 是 undefined
factory: function (require, exports) { exports.name = "x"; }
// ✅ 自己构造 module.exports
factory: (require) => {
const module = { exports: {} };
module.exports = { name: "x", apply };
return module.exports;
}宿主调用 factory 时只传 require。这个契约没有类型提示,写错了只在浏览器控制台报 Cannot set properties of undefined,Node 侧完全正常。
另外,生产模式下 client bundle 没有 HMR:改完 client.js 必须重启 dsh web,因为 bundle 在启动时就组合好了。
坑四:Web 路由是 Node 原生 res
// ❌ 原生 res 没有 statusCode()/send(),连接会一直挂着
res.statusCode(200);
res.send(JSON.stringify(body));
// ✅ 原生 http.ServerResponse
res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
res.end(JSON.stringify(body));这个错误最隐蔽的地方是“不报错”:handler 执行完了,但 res.end() 从未调用,前端 fetch 一直等到超时,面板显示“服务不可用”,看起来像路由没注册。
四、怎么确认真的挂上了
不用启动服务,先看配置树:
dsh --profile web --dump-config | Select-String "session-export"能搜到 # == dsh-plugin-session-export 和对应的 id,说明 bundle patch 生效了。再启动 dsh web,看启动日志里的端口和 token。如果所有插件路由都 404,先对比一个已知可用的路由(比如 /vault-memory/health)——都 404 通常是认证或路径前缀问题,不是新插件写错了。
| 检查项 | 命令或位置 | 通过标准 |
|---|---|---|
| 包声明 | package.json 的 dsh.bundle | 指向存在的 patch 文件 |
| 挂载 | dsh --profile web --dump-config | 输出里出现插件 id |
| 工具 schema | 模型实际调用 | 不再报 Invalid schema |
| 浏览器端 | DevTools Console | 无 Failed to load plugins |
| 清理 | 卸载插件后 | 定时器、路由、DOM 都不残留 |
踩坑:link 安装后改源码要不要重装
link: 协议在 Windows 上是目录联接,改源码直接生效,但必须重启 dsh web。只有改 package.json 里的依赖或 bundles 才需要重新 pnpm install。我一开始每次改代码都重装,白白多花了很多时间。
五、这套契约换来了什么
代价是每个插件都要自己处理生命周期、自己声明 schema、自己等 service 就绪;收益是 9 个插件可以共享同一套加载方式,卸载时不需要改宿主一行代码。
理解了这一层,下一篇就能看第一个真正“卡在中间”的插件:它不注册新工具,而是挂在 tools/pre-execute 上,决定别人的工具能不能执行。位置只有一处,但要处理的边界比写一个新工具多得多。