ARTICLE · 1023164
30 分钟造出你的第一个 DSH 插件:手把手实战
上篇拆了 Cordis 微内核，这篇落地。DSH 插件开发没有想象中难——它本质就是一个 export 出来的函数。我用一个真实例子带你从零写一个「日报生成器」插件，并把我踩过的坑一次性列清。
一、开发前准备
Node.js >= 22.19（ModLens 等插件已要求此版本，建议直接上 22）。 先装好 dsh：npx @deepseek-ai/dsh web 启动 Web UI，默认在 http://127.0.0.1:3080。 开发阶段用创造模式（Creator）：可检查运行中的运行时、在内存里试验插件，不用反复重启。
⚠️ 提醒：DSH 处于开发者预览，官方明说会有破坏性兼容变更。装任何插件一定点名具体版本号，别用 @latest 裸装——pnpm 11 的 minimumReleaseAge 会让 @latest 装到一天前的旧包。
二、插件的标准结构：命名导出，禁 export default
DSH 插件只认命名导出，name / inject / Config / apply 必须是顶层命名导出。一个最常见的坑是写了 export default——Cordis 会静默丢弃这些元数据，插件看起来装上了却什么都不做。
// my-plugin/index.ts import type { Context } from '@deepseek-ai/cordis' export const name = 'daily-report' // 必填：插件名 export const inject = ['tools'] // 声明依赖：等 tools 就绪才启动 export function apply(ctx: Context) { ctx.tools.register({ name: 'gen_daily_report', description: '生成今日工作日报', parameters: {/* JSON Schema */}, execute: async (args) => { // 你的逻辑 return { content: '今日日报已生成' } }, }) }三、动手：写一个「日报生成器」插件
目标：注册一个工具，agent 调用后扫描工作区改动、调用 LLM 总结、输出 Markdown 日报。核心就是往 ctx.tools 里注册一个带 execute 的函数。
export const name = 'daily-report' export const inject = ['tools', 'llm'] export function apply(ctx) { ctx.tools.register({ name: 'daily_report', description: '根据 git 改动生成当日工作日报', parameters: { type: 'object', properties: { since: { type: 'string', description: '起始日期' } }, }, execute: async ({ since }) => { const diff = await ctx.shell.exec(`git diff --since=${since}`) const summary = await ctx.llm.chat( `总结以下改动为日报：${diff}` ) return { content: summary } }, }) }四、Fiber 与副作用清理：走得干净
插件注册定时器、监听事件、开连接时，用 ctx.effect() 包起来并返回 disposer。Fiber 状态机会在卸载时按后进先出顺序撤销——外部资源（定时器、DB 连接、HTTP 服务）必须手动包 effect，Cordis 自身的 API 注册则自动清。
export function apply(ctx) { ctx.effect(() => { const timer = setInterval(() => {/* 心跳 */}, 1000) return () => clearInterval(timer) // 卸载时自动调用 }) }五、避坑清单（血泪版）
禁 export default：元数据会被静默丢弃，插件空转。 isolate realm 撞车：多个插件修改同一全局对象会互相覆盖，隔离作用域别乱用。 装完重启：装插件后重启 dsh web 才生效，不是只刷新浏览器（装宿主侧更新更要重启进程）。 Config 用 schemastery：配置校验走 standard-schema，别手写松散对象。 ctx.get vs ctx.inject：临时取值用 get，声明长期依赖用 inject 数组。
💡 提示：先在创造模式里实验，确认行为后打包成 Bundle（package.json 里 dsh.bundle 指向 cordis.patch.yml），再用 --patch 挂载到 profile，全程不用改 DSH 源码。
📌 一句话总结：DSH 插件开发 = 写一个 apply(ctx) 函数 + 命名导出元数据 + 用 ctx.effect 管好副作用。30 分钟足够造出第一个能跑的插件。
下一篇：纯文本模型看不了图怎么办？ModLens 给 DeepSeek 装一双眼睛，实操来了。