ARTICLE · 1035201
DeepSeek Harness 插件开发
DeepSeek Harness 插件开发
从零编写你的第一个 Agent 插件
导语：DeepSeek Harness（dsh）基于 Cordis 框架构建了一套完整的插件系统。本文聚焦于如何编写 dsh 插件，从环境准备到插件上架，手把手实操演示。
一、Cordis 核心概念
理解 dsh 插件系统，先要掌握 Cordis 的五个核心概念。
插件（Plugin）：实现 Service 的对象，可以是带有 inject 和 apply(ctx) 字段的函数，也可以是 Service 子类。插件生命周期由 Cordis 管理，挂载时启动，卸载时自动撤销所有注册。
上下文（Context）：服务的容器，每个服务占据稳定的 ctx.<key>（如 ctx.tools、ctx.llm、ctx.sessions）。其他插件通过 key 查找服务，而非直接导入具体实现——这保证了组件间的松耦合。
注入（Inject）：插件通过 inject 声明所需服务依赖，Cordis 保证这些服务就绪后才启动插件。加载顺序通过服务依赖表达，无需手动编排启动序列。
类型化事件（Typed Events）：服务间通过事件通信，支持五种分发模式——emit（观察）、waterfall（瀑布式包装）、parallel（并行）、serial（串行）、bail（短路）。
可逆注册（Reversible Registration）：所有注册都通过 ctx.effect() 或 ctx.on() 安装，reload 和 teardown 时自动撤销。这意味着可以随时动态加载或卸载插件，而不用担心遗留状态污染。
二、环境准备
安装 dsh
dsh 支持 npm 安装和源码运行两种方式：
# 方式一：npm 安装（推荐）npx @deepseek-ai/dsh --version# 方式二：源码运行git clone https://github.com/deepseek-ai/deepseek-harness.gitcd deepseek-harnesspnpm installpnpm run buildpnpm dsh --version
创建插件项目
推荐使用官方插件模板创建项目结构：
# 使用 dsh 提供的脚手架工具创建插件项目npx create-dsh-plugin my-first-plugin# 生成的目录结构：my-first-plugin/├── src/│ ├── index.ts # 插件入口│ ├── plugin.ts # 插件核心逻辑│ └── types.ts # 类型定义├── package.json├── tsconfig.json└── README.md
三、编写第一个插件：文件搜索工具
下面编写一个 file-search 插件，功能是根据关键词在项目中搜索文件路径，并返回匹配结果。
步骤 1：定义插件类型
// src/types.tsimport type { Service } from '@deepseek-ai/dsh-cordis';// 声明插件提供的工具接口export interface FileSearchTool { name: 'file_search'; description: 'Search files by keyword in project';
步骤 2：实现插件逻辑
// src/plugin.tsimport type { Service } from '@deepseek-ai/dsh-cordis';
步骤 3：注册插件入口
// src/index.tsimport { fileSearchPlugin } from './plugin';export default fileSearchPlugin;// 插件包导出格式export const packageInfo = { name: 'dsh-file-search', version: '0.1.0', description: 'Search files in project by keyword', main: './dist/index.js',};
四、Agent Loop 事件机制
理解 dsh 的 Agent Loop 机制，是编写高级插件（如拦截器、记忆系统）的前提。
关键设计点：
agent/pre-step：可以在模型看到输入之前改写或拒绝它——适合实现内容审核、提示词注入等拦截逻辑 tool/call*：触发工具执行流水线，每个工具调用都是一个独立事件 所有模型可见的输入都必须能从不志事件中重建——这保证了会话的完整可回放性
五、Profile 与 Bundle 组合机制
dsh 通过 Profile 和 Bundle 两层机制组织运行配置，这套机制让框架既有合理默认值，又保留完全透明的可定制性。
Profile 是具名组装，列出自己叠放的组合包、树外插件，并保存用户的 cordis.patch.yml。官方 Profile 包括：web（带 UI）、headless（一次性运行）、sdk（SDK 服务器）、acp（自动化专用）。
Bundle 是 Cordis 配置项及其挂载代码的分发格式，每个 Bundle 通过 dsh.bundle 字段声明自己的 patch 文件。dsh-base 是多个 Profile 的共享底层，提供模型适配器、工具、持久化、沙箱与审批策略等基础能力。通过 --dump-config 可以查看当前运行的完整配置树。
六、插件市场与生态
dsh 的插件市场已汇聚超过 11000 个社区插件，涵盖 UI、工具、记忆、自动化等各方面：
七、与 Claude Code、Codex 的横向对比
dsh 的最大差异点在于完全开源 + 插件生态。不同于 Claude Code 和 Codex 的闭源封闭，dsh 的每一个组件都可以被替换，社区可以自由贡献插件。这让它既有 DeepSeek 官方背书，又具备极高的可定制性。
八、发布与安装插件
本地安装测试
# 编译插件cd my-first-pluginpnpm run build# 本地安装到 dshdsh plugin add ./dist# 启动 dsh 验证插件dsh --profile web# 在 dsh 中使用插件命令：/file_search --keyword handler
发布到插件市场
插件测试通过后，可以提交到官方插件市场：
# 在 awesome-dsh-plugin 仓库提交 PR# 仓库地址：https://github.com/awesome-dsh-plugin/awesome-dsh-plugin# PR 通过后，你的插件将出现在官方插件市场中dsh plugin add dsh-file-search # 其他用户可直接安装
九、总结
本文核心要点：
Cordis 是 dsh 的核心，提供了注入依赖、类型化事件、可逆注册三大基础能力 编写 dsh 插件只需实现 inject+apply(ctx)接口，遵循约定优于配置原则Agent Loop 通过事件链驱动， agent/pre-step提供了强大的拦截扩展能力Profile + Bundle 分层设计让框架既有默认值，又完全透明可定制 11000+ 插件生态覆盖各类场景，编写插件后可提交 PR 到官方市场
相关资源
GitHub：github.com/deepseek-ai/deepseek-harness 官方文档：deepseek-harness.github.io/deepseek-harness/ 插件市场：awesome-dsh-plugin.com Cordis 论文：arXiv 2608.25512