DeepSeek Harness 插件开发入门教程：半小时给 AI 装上手（附完整代码）

DeepSeek Harness 插件开发入门教程：半小时给 AI 装上"手"（附完整代码）

目录

1. 问题背景：从"聊天"到"执行"的鸿沟
2. [架构解析：Cordis 插件框架](#架构解析：Cordis 插件框架)
3. 环境搭建
4. 最小插件实现（含踩坑记录）
5. 配置挂载
6. 实战：自动生成日报草稿
7. [打包发布与 Vibe Coding](#打包发布与 Vibe Coding)
8. 边界、安全与总结

一、问题背景：从"聊天"到"执行"的鸿沟

DeepSeek 开源的 Harness（代号"黑色鲸鱼"）不是新模型，而是给大模型套在外面的执行层 。一句话公式：Model + Harness = Agent------模型负责思考，Harness 负责执行。

发布仅一周，GitHub 上 dsh-plugin 标签的社区插件已超过 900 个。其核心口号"一切皆插件"意味着模型、工具、界面、会话记录全部由插件拼装，用户无需修改源码即可扩展任意能力。

然而多数用户拿到 Harness 后仍停留在对话层面，就像"买了台数控机床，天天拿它当锤子敲钉子"。本文将从零演示插件开发全流程。

二、架构解析：Cordis 插件框架

Harness 底层采用 Cordis 插件框架，核心思想：所有能力都是"插件"，插件本质是一个导出固定结构的 TypeScript 文件。

官方自带的 195 个包（命令执行、会话记录等）全部由插件构成，用户插件与官方插件地位完全平等，没有"二等公民"。

三、环境搭建

步骤	操作	说明
1	node --version	需要 Node.js 22.19+
2	npx @deepseek-ai/dsh web	启动本地工作台
3	访问 http://127.0.0.1:3080	本地网页界面，数据在本机
4	填写 DeepSeek API Key	在 platform.deepseek.com 注册

四、最小插件实现（含踩坑记录）

一个注册 hello_world 工具的最小插件：

// my-plugin.ts
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'my-plugin'
export const inject = ['tools']
export function apply(ctx) {
  ctx.tools.register(defineTool({
    name: 'hello_world',
    description: '向某人打招呼，用来验证插件是否加载成功',
    parameters: {
      who: { type: 'string', required: true, description: '要打招呼的人' }
    },
    output: {
      schema: { type: 'object', additionalProperties: false, properties: { message: { type: 'string', required: true } } },
      render: (_args, value) => [{ type: 'text', text: value.message }]
    },
    async execute(args) {
      return { message: `你好，${args.who}，插件加载成功` }
    }
  }))
}

踩坑记录（实测）：

1. 必须具名导出 ：使用 export default 会导致注入声明被静默丢弃，插件看似加载实则不生效，且不报错。
2. schema 约束 ：对象类型输出的 schema 必须声明 additionalProperties: false，否则注册失败。
3. 注入顺序 ：inject: ['tools'] 表示等待工具注册表就绪后再执行。

五、配置挂载

创建 cordis.yml 声明插件挂载信息：

- insert:
  - id: my-plugin
    name: '/绝对路径/你的目录/my-plugin.ts'

注意：路径必须为绝对路径，Cordis 不支持相对路径。

带补丁启动：

pnpm dsh web --patch ./cordis.yml

在对话中触发「用 hello_world 跟小虎打个招呼」，返回"你好，小虎，插件加载成功"即验证成功。

六、实战：自动生成日报草稿

痛点：每日下班前撰写日报、每周五汇总五篇日报为周报，重复机械且易遗漏。

import { defineTool } from '@deepseek-ai/dsh-tools'
import { readFileSync, writeFileSync, existsSync } from 'fs'
export const name = 'daily-draft'
export const inject = ['tools']
export function apply(ctx) {
  ctx.tools.register(defineTool({
    name: 'gen_daily_draft',
    description: '读取昨天的待办，按模板生成今天的日报草稿',
    parameters: {
      workspace: { type: 'string', required: true, description: '工作区目录绝对路径' }
    },
    output: { schema: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', required: true } } },
      render: (_a, v) => [{ type: 'text', text: `草稿已生成，${v.path}` }] },
    async execute(args) {
      const todoPath = `${args.workspace}/todo.md`
      const draft = existsSync(todoPath)
        ? `【草稿待确认】\n昨日待办：\n${readFileSync(todoPath, 'utf-8')}\n（请核对当天实际进展后填写）`
        : '【草稿待确认】今日暂无昨日待办记录，请补充。'
      const out = `${args.workspace}/daily-$(date +%F).md`
      writeFileSync(out, draft)
      return { path: out }
    }
  }))
}

设计要点：只生成草稿并明确标注"待确认"，绝不替用户编造未发生的内容------通过规则约束规避 AI 幻觉风险。

七、打包发布与 Vibe Coding

本地使用绝对路径即可，发布到社区需在 package.json 声明：

{
  "name": "dsh-daily-draft",
  "type": "module",
  "main": "my-plugin.ts",
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

安装命令：dsh plugin --profile web add github:账号/仓库

Vibe Coding 提示：DSH 插件结构（单文件 + apply 入口 + YAML）天生适合 AI 生成，可将规范提交给 Cursor 等工具秒级生成完整源文件。

八、边界、安全与总结

维度	说明
版本稳定性	当前 0.1.0 预发布版，官方明确接口仍会调整，建议尝鲜而非生产部署
安全风险	插件本质是本机运行的代码，来源不明插件等同交出系统权限，仅安装官方或高星插件
技术门槛	需要一定 TypeScript 基础，但相比完整编程语言学习坡度平缓

核心观点：真正的自动化不是学会所有工具，而是只需要说一句话，工具自己串起来干活。

下一步方向：将日报插件串联周报插件，实现周五自动汇总。