ARTICLE · 1338035

两万人写 dsh 插件,我看了源码发现只需要三行

发布时间：2026-11-10 09:49:05 最近访问：2026-11-10 09:49:06

DSH 深度玩法第 2 篇 · 共 5 篇

两万人写 dsh 插件，我看了源码发现只需要三行

一个真实插件的完整诞生——从 1100 行代码里提炼出你只需要懂的四行

在写第一个 dsh 插件之前，我以为插件开发是一件复杂的事——要理解框架、要读文档、要搭脚手架。

写完之后我发现：DSH 不是「一个应用加一堆插件」，它本身就是一摞插件叠起来的。你看到的界面是插件，模型选择器是插件，连 Agent Loop 本身都是插件。写插件不是「给系统加东西」——是第一次真正看懂这个系统是怎么搭起来的。

这个认知转变，来自我花一晚上写了一个真实的插件：一个技能管理器，用来统一管理散落在七八个目录里的 Agent 技能。这篇文章把它的诞生过程完整走一遍——所有代码都是真实运行的，包括那个让我 debug 到凌晨两点的冷启动 bug。

你的问题可能跟我一样

用 dsh 一段时间后，技能（Skills）散落得到处都是：项目里有 .dsh/skills 和 .agents/skills，用户目录有 ~/.dsh/skills，其他 agent 工具还有 ~/.claude、~/.codex、~/.workbuddy 六七个目录。想统一看一眼、想互相同步？只能开文件夹逐个翻。

于是我写了 @local/skill-manager：在 dsh 侧栏里管理所有本机技能，支持查看、启停、跨 agent 一键同步。

插件的最小组成：三行代码，三个文件

先破除神秘感。一个 dsh 插件 = 一个 npm 包 + 一份声明 + 一个入口函数。

声明只需要三行——一个 YAML 文件：

▎ YAML

- insert: - id: skill-manager name: '@local/skill-manager'

意思是：在 profile 的行列表里插入一行，id 是身份，name 指向你的 npm 包。profile 启动时，把每个插件的 patch 依次叠起来，就组成了整个应用。

入口函数也只需要四行：

▎ JS

export const inject = ['skills', 'tools']; export function apply(ctx) { const manager = createSkillManager(ctx); ctx.provide('skillManager', manager); ctx.effect(() => registerTool(ctx, manager)); ctx.inject(['connection'], (innerCtx) => registerRoutes(innerCtx, manager)); }

四个概念，一行一个：

•inject 声明依赖——我的插件需要 skills 和 tools 服务，缺了就不加载

•ctx.provide 把我的 manager 注册成服务，其他插件也能用

•ctx.effect 注册副作用——这里是给 agent 加工具

•ctx.inject(['connection']) 延迟注册 HTTP 路由

最后一行是踩了坑才写对的。下面讲这个坑。

凌晨两点的 bug：一个静默失败的教训

写完前四行代码，工具能用了、服务能查了，但侧栏面板死活不出现。刷新、重启、清缓存——页面 404。

没有报错。没有日志。什么都没有。

折腾了两个小时，翻源码才发现原因：connection 服务在冷启动时还没就绪。如果在 apply 顶层直接取 ctx.get('connection')，会拿到 undefined——然后静默失败，路由注册被跳过，页面 404。没有任何错误提示。

解法就是那行 ctx.inject(['connection'], fn)：把路由注册放进回调，等 connection 就绪了再执行。一行代码，修一个两小时的 bug。

教训：当你的代码「安静地不工作」时，第一件事不是检查逻辑，是检查执行时序。依赖还没就绪的代码不报错——它只是不执行。这个模式在异步初始化的系统里到处都是。

工具注册：description 就是模型的说明书

插件最常见的用途是给 agent 加工具。工具注册有一个容易被低估的设计点：

▎ JS

ctx.tools.register({ name: 'skill_manage', description: [ 'Manage the local skills installed on this machine.', '- list: every skill across project, user, other agent tools', '- get / create / update / set-invocation / remove', '- sync: copy skills into other agents directories', ].join('\n'), parameters: TOOL_PARAMETERS, output: { schema: TOOL_OUTPUT_SCHEMA, render: (_args, value) => renderToolResult(value), }, async execute(args, exec) { return { ok: true, result: toJsonSafe(await dispatch(manager, args, exec)) }; }, });

description 不是注释，它是 prompt 的一部分。这段文字会进入模型的上下文——agent 靠它判断什么时候调用这个工具、怎么传参数。写得越具体，调用越准；写得含糊，agent 就猜。

output.render 是给人看的。工具返回 JSON 给模型，render 函数把它折成人话。原则：一屏之内，别让用户滚动。

不用启动 App 就能测：两百行冒烟测试

写 Host 侧最烦的事：每次改一行代码，都要重启 dsh 验证。一个启动周期 30 秒，一天改 50 次，25 分钟全花在等重启上。

解法：给 ctx 做一个假替身，让插件以为自己运行在真实环境里：

▎ JS

冒烟测试用这个假 ctx 跑真的apply 函数和真的文件系统：断言服务已注册、工具恰好一个、扫描能找到 oil-ui、tai-maas 这些真实技能、同步的 dry-run 计划正确。

两秒钟跑完全部验证，不用启动任何东西。

这个技巧的适用范围远不止 dsh 插件——任何需要「在复杂环境里测试一个小组件」的场景，都可以用假环境替身 + 真逻辑的方式快速验证。

从三行到一千行：中间发生了什么

三行 YAML + 四行 JS 是最小骨架。真实插件最终写了一千一百行——多出来的部分：

•Web 客户端（client.js，六百行）：用官方 sidebar 的插槽注册一个「技能」面板，左边列清单、右边显详情