DeepSeek Harness 插件开发实战：从最小插件到自动化日报

导语

DeepSeek 开源的 Harness（代号"黑色鲸鱼"）不是新模型，而是给大模型套在外面的"执行层"。核心口号"一切皆插件"------模型、工具、界面、会话记录全部由插件拼装。本文从技术视角拆解 Harness 的插件机制（Cordis 框架），给出从环境搭建、最小插件编写、配置挂载到自动化实战的完整流程，并客观评估当前版本的边界与安全注意事项。

问题定义：从"聊天"到"执行"的鸿沟

多数用户拿到 Harness 后只停留在对话层面，就像"买了台数控机床，天天拿它当锤子敲钉子"。真正发挥价值的方式是编写插件，将重复劳动外包给 AI。Harness 发布仅一周，GitHub 上 dsh-plugin 标签的社区插件已超过 900 个。

架构解析：Cordis 插件框架

Harness 底层采用 Cordis 插件框架，核心思想：所有能力都是"插件"，插件本质是一个导出固定结构的 TypeScript 文件。官方自带的 195 个包（命令执行、会话记录等）全部由插件构成，用户插件与官方插件地位完全平等。

环境搭建

需要 Node.js 22.19+（node --version 验证）
启动命令：npx @deepseek-ai/dsh web
本地界面：http://127.0.0.1:3080（数据完全在本机）
首次使用需配置 DeepSeek API Key（platform.deepseek.com 注册）

最小插件实现

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

typescript 复制代码

// 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}，插件加载成功` }
    }
  }))
}

踩坑记录

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

配置挂载

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

yaml 复制代码

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

注意：路径必须为绝对路径（Cordis 不支持相对路径）。带补丁启动：

bash 复制代码

pnpm dsh web --patch ./cordis.yml

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

实战：自动生成日报草稿

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

typescript 复制代码

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 幻觉风险。

打包发布

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

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 基础，但相比完整编程语言学习坡度平缓

总结

DeepSeek 通过 Harness 打开了"执行层"的大门。核心观点：真正的自动化不是学会所有工具，而是只需要说一句话，工具自己串起来干活。 下一步方向：将日报插件串联周报插件，实现周五自动汇总。