DSH 插件开发实战:从零写一个「定时提醒」插件

前言

DSH 插件是什么

• 同一个插件可以发布多个版本，运行时可以热切换；
• 插件既能跑在 Node 端（Host），也能跑在浏览器端（Client）；
• 插件的「权限」是显式授予的——它不会默认接管你的系统。

准备：环境与工具

• 一个能跑 Node.js 20+ 的环境
• DSH 本体（npx @deepseek-ai/dsh web）

第一个插件：一个简单的「打招呼」

return {
  apply(ctx) {
    ctx.effect(() => {
      console.log('[hello-dsh] plugin loaded');
      return () => console.log('[hello-dsh] plugin unloaded');
    });
  },
};

第二个插件：定时提醒（实战）

• 暴露一个 schedule_add 工具给 Agent（添加定时任务）；
• 暴露一个 schedule_list 工具给 Agent（查看所有任务）；
• 在任务到期时，触发 DSH 的事件总线，让前端弹一条提醒。

return {
  inject: ['harness'],
  apply(ctx) {
    const tasks = [];
    ctx.harness.handle('schedule_add', (req) => {
      const id = crypto.randomUUID();
      tasks.push({ id, ...req });
      setTimeout(() => {
        ctx.scope.emit('schedule:fire', { id, ...req });
      }, req.delayMs ?? 0);
      return { ok: true, id };
    });
    ctx.harness.handle('schedule_list', () => tasks);
  },
};

return {
  apply(ctx) {
    ctx.host.on('schedule:fire', (payload) => {
      new Notification(payload.message ?? '提醒', {
        body: payload.message,
      }).show();
    });
  },
};

发布与加载

• 本会话试用：cordis_define + cordis_run，改完用 cordis_run update 切换版本；
• 团队共享：把 Package 提交到一个 Git 仓库，团队成员用 cordis_run + URL 引用；
• 持久化：把插件放到 ${DSH_HOME}/.agent-presets/<id>/ 下，写成 preset，下次启动 DSH 自动加载。

踩坑经验

• ctx.serviceName 不要访问未声明的 Service。要么 inject: [...]，要么用 ctx.get('serviceName') + 检查 undefined；
• 副作用必须用 ctx.effect() / ctx.on()。直接 setInterval 会导致 stop / update 不掉；
• 不要在 Client 代码里用 TypeScript / JSX / import。DSH 不做编译；
• 数据不要用 JSON.stringify 序列化 Services / Events。它们是活对象，会丢失上下文。

写在最后