DeepSeek Harness 插件开发：从零编写第一个插件

Skill 是“给 agent 写手册”，插件是“给 agent 装新能力”。这一篇从零写一个最小插件：注册一个自己的工具。你需要的背景只有插件机制与 Cordis 入门里的三个概念：行、inject、apply。

插件的最小形态

一个插件就是一个模块，导出三样东西：

export const name = "hello-tool"                    // 插件名（行 id 用它）
export const inject = ["tools"]                     // 需要什么服务

export function apply(ctx) {
  // 在这里注册工具
}

name：插件身份
inject：依赖声明——这里要 tools 服务（工具注册表）
apply(ctx)：插件被挂载时执行，ctx 上挂着所有注入的服务

注册一个工具：三步

以“把文本转大写”的工具为例：

import { defineTool } from "@deepseek-ai/dsh-base"   // 工具定义助手

export const name = "hello-tool"
export const inject = ["tools"]

export function apply(ctx) {
  ctx.tools.register(defineTool({
    name: "uppercase",
    description: "将输入文本转为大写。当用户要求转换大小写时使用。",
    parameters: {
      text: { type: "string", required: true },
    },
    async execute(params) {
      return { text: params.text.toUpperCase() }
    },
  }))
}

三个要点：

name 是 agent 看到的名字——模型靠它点名调用，起名要表意
description 决定 agent 会不会用——和 Skill 一样，写清触发场景
参数声明决定调用时的输入校验——类型、必填一目了然

挂载你的插件

插件写好后，要让它进入组合。最直接的方式：在 profile 的配置里加一行：

- id: hello-tool
  name: "my-plugin-package/hello-tool"   # 你的包名 + 导出路径

挂载后 agent 的工具列表里就多出 uppercase。加载失败时看两件事：行是否在配置树里（dump 命令）、依赖的 tools 服务是否存在。

插件还能做什么

注册工具只是起点。通过注入不同服务，插件可以：

想做什么	注入的服务	做什么
提供自己的服务给别人用	—	导出服务定义，`ctx.provide(...)`
贡献提示词段	`systemPrompt`	给 agent 的人设加一段
监听事件	—	订阅生命周期事件做联动
提供 Skill 来源	`skills`	让插件自带技能

思路是统一的：声明依赖 → 在 apply 里用 ctx 干活。

开发时的三个纪律

先看官方参考：工具注册、服务注入的完整签名以官方文档站 reference 区为准（见官方文档地图）
不修改随部署分发的文件：开发插件放自己的包/preset，不动内置组合（呼应创建 Agent Preset 的纪律）
测试用隔离 workspace：插件里的工具会被 agent 真调用，出错时别伤及真实项目

常见问题

问题	解答
挂载后工具不出现？	dump 配置树确认行已加载；查插件加载日志
agent 不用我的工具？	检查 description 是否写清触发场景
inject 的服务拿不到？	该服务没有提供方——确认依赖行也在组合里
想改内置工具行为？	不直接改，写新插件或用配置禁旧挂新