Skip to content

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,而是这两段:

json
{
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": { "platform": "web" }
  },
  "exports": { "./client": "./src/client.js" }
}

cordis.patch.yml 则决定它插到宿主配置树的哪个位置:

yaml
- insert:
    - id: dsh-plugin-session-export
      name: dsh-plugin-session-export

就这四行。没有端口、没有进程、没有自己的配置文件。宿主启动时读 profile,把 bundle patch 应用到配置树,再调用插件的 apply(ctx, config)。从这一刻起,插件才拿到 ctx。

所以插件的能力边界完全由 ctx 决定:能注册工具、能订阅事件、能挂 Web 路由;但不能改 Agent 的循环,也不能假设自己独占某个服务。

为什么不直接 Fork 宿主

改宿主源码确实什么都能做,但升级要重新合并,插件之间也会互相踩。旁路的代价是只能使用公开契约,收益是 9 个插件可以独立安装、独立卸载、独立发版。这套插件全部选了后者。

二、加载链路:四道关 ​

一个插件从安装到生效,依次经过:

  1. profile 的 dsh.profile.bundles 决定装不装;
  2. package.json 的 dsh.bundle.patch 决定插到配置树哪里;
  3. apply(ctx, config) 执行注册逻辑;
  4. dsh.client + exports["./client"] 决定浏览器端加不加载。

前三步在 Node 侧,第四步在浏览器侧。两边共享同一个包名,但不共享运行时:Node 侧拿不到 DOM,浏览器侧拿不到 ctx。session-export 的面板之所以要再开一个 HTTP 路由,就是因为这个边界。

三、四个真实踩过的坑 ​

坑一:裸注册的工具参数必须是完整 JSON Schema ​

这是耗时最长的 bug。defineTool() 内部会把参数名映射编译成标准 JSON Schema,而裸 ctx.tools.register() 直接透传:

js
// ❌ 报错:参数名映射不是合法 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 里写不存在的服务,整个应用会崩 ​

js
// ❌ webServer 在某些 profile 里不存在,cordis 注入校验失败
export const inject = ["tools", "webServer", "sessions"];

// ✅ 只声明确定存在的,可选服务按需取
export const inject = ["tools", "sessions"];

症状不是“插件没加载”,而是 dsh web 启动后进程直接退出。更麻烦的是,webServer 可能比插件晚初始化,ctx.get("webServer") 第一次拿到的是 undefined。正确做法是在 ctx.effect() 里轮询等待,而不是判断一次就放弃:

js
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 只收一个参数 ​

js
// ❌ 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 ​

js
// ❌ 原生 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 一直等到超时,面板显示“服务不可用”,看起来像路由没注册。

四、怎么确认真的挂上了 ​

不用启动服务,先看配置树:

bash
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 上,决定别人的工具能不能执行。位置只有一处,但要处理的边界比写一个新工具多得多。

本文阅读--次|全站访问--次|访客--人