DeepSeek Harness 插件开发入门：写你的第一个 dsh 插件

dsh 插件到底是什么

一个 DeepSeek Harness 插件就是一个 Cordis 插件。Cordis 是 Harness 底层的元框架，只负责插件的加载、卸载与依赖关系；Harness 的每个具体组件——工具、存储、策略、主循环、UI 面板——都是不同的 Cordis 插件，插件之间通过服务与事件协作。

这是理解 dsh 插件的第一要义：插件不是"外挂"，它可以替换或扩展智能体的任意部分：

• 给模型加一个能自主调用的工具（标题生成、数据库连接……）
• 换掉系统提示词，甚至换掉整个主循环
• 拦截工具执行，做审批、记录、改写
• 注册新的 UI 面板、状态栏或皮肤
• 提供沙箱后端或新的模型供应商

先记住几个官方锚点：

• npm 包名：@deepseek-ai/dsh
• CLI 命令：dsh（安装 npm install -g @deepseek-ai/dsh，运行 dsh --profile web）
• 社区插件的 GitHub 官方指定 topic：dsh-plugin
• 底层框架：Cordis

能力接缝：服务、提供方、消费方

每种能力（执行命令、读写文件、网络访问、模型调用、沙箱隔离）都被拆成三个相互独立的角色：

1. 服务（Service） —— 接口规范；
2. 提供方（Provider） —— 具体实现；
3. 消费方（Consumer） —— 使用该能力的一方。

三者解耦，模型看到的接口恒定不变。想换搜索引擎？注册另一个提供方就行，消费方和模型毫无感知。社区插件之所以能换掉 Harness 这么多部件，靠的就是这套接缝。

插件树

运行中的 dsh 是一棵插件树，由多层配置按固定顺序叠加：Bundle（官方成套配置）→ Profile（你的具名组装清单）→ Patch（你的覆盖层，可定位到单个插件条目），上层覆盖下层。插件被卸载时，它注册的一切自动撤销——注册必须是可逆副作用，这是硬性约定。

一个最小插件的骨架

每个插件是一个函数（或带生命周期钩子的对象），接收一个 Cordis context，声明自己提供什么、消费什么。概念骨架长这样：

import { Context, Service } from '@cordisjs/core';

export const name = 'my-plugin';

// 1. 插件提供的服务
export class Greeting extends Service {
  constructor(ctx: Context) {
    super(ctx, 'greeting');
  }

  hello() {
    return 'hello from my-plugin';
  }
}

// 2. 插件本体
export function apply(ctx: Context) {
  ctx.provide('greeting', new Greeting(ctx));

  // 3. 响应事件——例如智能体启动时
  ctx.on('agent/start', () => {
    ctx.logger.info('my-plugin loaded');
  });
}

Harness 目前是 v0.1、接口在快速迭代，上面的代码看"形状"即可，别当契约用。动手前务必以官方文档和 plugin-template 仓库的最新约定为准。

官方仓库强制执行的工程约定

官方仓库的自动化门禁把一套规则写成了硬约束，你的插件值得照抄：

• 注册必须是可逆副作用 —— 卸载不留残余；
• 配置错误必须在加载时报错，不能静默跳过；
• 跨边界标识符用品牌类型（branded types），不让裸字符串在各层之间泄漏；
• 随部署变化的参数放进配置，不硬编码。

质量门禁同样硬核：源码目录逐文件 100% 单元测试覆盖率、无 API Key 也能跑的快照回放测试、真实 API 端到端测试、跨文件代码克隆检测、文档与代码同步检查（文档过期直接阻断 CI）。

不同能力往哪里插

看你做什么，接缝位置不同：

• 工具 —— 注册模型可调用的工具，与内置工具走同一条流水线（审批、守卫、日志全生效）；
• Agent 事件 —— turn/start、step/start、工具执行前后、模型请求前后的钩子；
• UI —— Web UI 本身就是第二棵插件树：页面先声明侧边栏、对话区、输入区、设置区等挂载位，插件把自己的组件注册进去；
• 存储 / 会话 —— 替换会话与日志的持久化方式；
• 沙箱 / 模型 —— 提供自己的沙箱后端或模型适配器（任意 OpenAI 兼容端点均可）。

发布与收录

1. 把插件推到公开的 GitHub 仓库；

2. README 写清：一句话说明、安装方式、（最好还有）它需要访问什么；

3. 给仓库加上 dsh-plugin topic —— 它是官方指定的社区标记，其他工具和目录靠它发现插件；

4. 向我们的 awesome 列表提 PR —— 这是本站的唯一数据源：

   • cccakeee/awesome-dsh-plugins —— 在对应分类标题（中英文均可）下加一行。

5. 有 npm 包的话，挂到 registry 类索引上，让 dsh 工具链能直接发现。

合并后，本目录会在下一次同步时自动收录（同步机制见生态盘点）。

最后一句提醒

插件是以智能体权限运行的代码。安装别人的插件前，读源码、查许可证、看它要什么权限，先在隔离工作区里试用；你自己发布的插件，也应该如实说明它会读什么、写什么、往网络上发什么。

继续探索

• 安全地安装插件 —— 安装行的另一头
• Profile、Patch 与 Preset —— 你的插件落在插件树的哪一层
• 沙箱、审批与密钥 —— 插件接入的安全模型
• 提交插件 —— 完整的收录清单