dsh-plugin-dev

给 DSH 写插件

插件是 TypeScript 模块，跑在 Cordis 之上。DSH 处于 developer preview，官方明确警告有破坏性变更，所以任何行为都要在当前版本上验证。

先问一句：这件事非要插件不可吗？ 如果用自然语言就能说清楚要模型做什么，写技能（一个 Markdown 文件）成本低一个数量级，也不会被上游 API 变更打挂。需要执行代码、接外部服务、挂生命周期钩子的，才需要插件。

最小形态

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  // 在这里注册能力
}

加载方式是写一个 overlay：

- insert:
    - id: my-plugin
      name: '/absolute/path/to/my-plugin.ts'

dsh web --patch ./my-plugin/cordis.yml

路径必须是绝对路径，官方文档明确要求，相对路径不会被解析。

第一个致命陷阱：不要写 default export

这条有官方事故复盘（docs/postmortem/0001），值得完整理解。

export const name = 'acp'
export const inject = ['agents', 'sessions']
export function apply(ctx, config) { }
export default apply          // ← 这一行会让插件彻底失效

Loader 的 unwrapExports 逻辑是 exports.default ?? exports，优先取默认导出。有 export default 时，它解析出来的是裸的 apply 函数，而 inject、name、Config 是挂在模块命名空间上的同级命名导出，取 .default 那一步把整个命名空间丢掉了。

Loader 于是用一个空的 inject 构建 fiber。插件在什么服务都没注入的环境里运行，第一次访问 ctx.xxx 时沿 fiber 树一路找到根，抛出 cannot get property "agents" without inject。

崩在加载时，不是请求处理时。

当时这个 bug 有 178 个绿色测试和 100% 行覆盖率，因为所有测试都是手动挂载插件的，绕过了真实 Loader 路径。

规则：命名空间插件只用命名导出，绝不加 default export。

第二个致命陷阱：!!js 只在 config 里有效

同样有官方复盘（docs/postmortem/0002）。

- insert:
    - id: fs
      name: '@deepseek-ai/dsh-tool-fs'
      disabled: !!js ctx.mode !== 'full'    # ← 永远为真
      config:
        root: !!js process.cwd()            # ← 这里才有效

Cordis 只对插件的 config 做递归插值。disabled、isolate、intercept 这些配置项元数据是直接读取的，拿到的是表达式对象，而对象恒为 truthy。结果是插件在所有模式下永久禁用，且无任何诊断。

规则：条件组合用显式的 overlay 文件，不要在元数据字段上写表达式。

注册工具的两个实测坑

ctx.tools.register() 的参数形态跟直觉不一样，这两条是实际跑出来的报错：

一、必须用 defineTool() 包裹，且必须声明 output

tool "xxx" must declare output { schema, render, presentationMeta? }

output 里要有 schema（返回值的 JSON Schema）和 render（渲染函数）。

二、parameters 不是标准 JSON Schema，且 required 只能填 true