DeepSeek Harness 插件怎么玩：我做了个黄历工具

上一篇我测了 DeepSeek Harness，说它"一切皆插件"是真的。但怎么玩插件，很多人还是没概念。这次我不讲虚的，直接做了一个真实插件跑通，把"怎么装、怎么用"讲明白。

我做的插件是个黄历查询工具。装上之后，agent 就多了一个本事，你问它"今天宜做什么、忌做什么"，它立刻给你返回完整的农历黄历信息。

这个插件从头到尾我都在本机实测过，命令、输出原样贴出来，你可以照着复现。

装上它，agent 就会看黄历了

先给你看成品效果，再说怎么装。

装上黄历插件后，在 Web 界面里直接问 agent：

今天宜做什么，忌做什么？

agent 会调用它新多出来的 today_almanac 工具，返回：

2026-08-14（星期五）农历 丙午年（马年）七月初二干支 丙午年 · 丙申月 · 庚申日冲煞 冲虎（丙寅）煞南宜 入学、酝酿、出行、经络、安床忌 伐木、纳畜、嫁娶、安香

我实测的时候，从提问到拿到完整黄历，5 秒。agent 还能顺手解读，比如"今天庚申日，属虎的朋友行事留意"。

这就是插件的作用，给 agent 加一个它本来没有的工具，让它会做原来不会的事。

怎么安装：一条命令

安装插件包，用的是 DeepSeek Harness 的命令行：

dsh plugin --profile web add @xinyi-it/today-almanac

命令逐段解释：

• • dsh plugin 是插件管理子命令
• • --profile web 指定装到哪个 profile（web 就是 Web 界面用的那个）
• • add @xinyi-it/today-almanac 是装这个插件包

如果你在 Mac 或 Linux 上用源码方式跑（不是全局安装 dsh），dsh 命令要从 Harness 仓库里带 pnpm 前缀跑，并且得先 cd 进仓库目录，否则会报 command not found: dsh：

cd deepseek-harness          # 先进仓库目录pnpm dsh plugin --profile web add @xinyi-it/today-almanac

如果你从本地目录安装（比如拿到插件源码目录，或者自己正在开发调试）：

dsh plugin --profile web add /路径/到/today-almanac-plugin

装完之后，这个包会被加进 profile 的插件层栈。我实测装完，profile 的插件层长这样：

["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@xinyi-it/today-almanac"]

第三位就是我们这个黄历插件，被系统正确识别成了可挂载的插件层。

装完需要重启 Web 界面（停掉再启动 dsh --profile web），插件才会生效。

重启后，打开设置，进插件 → 插件列表，就能看到它。列表里所有已安装的插件（160 个）都会显示出来，每个带状态标签。我搜了一下，我们装的是这样一行：

[today-almanac]    [● 已启用]

插件名 today-almanac，状态"已启用"，右侧下拉箭头还能做禁用、卸载等操作。到这里，插件就算正式安家落户了。

怎么使用：不用学习，直接问

装好之后，你不需要学任何新操作。agent 自动就知道了这个工具的存在，你只需要在对话里问它跟黄历相关的问题就行。

举例：

• • "今天宜做什么、忌做什么"
• • "查一下 2026-06-18 的黄历"
• • "这个月哪天适合搬家"

agent 会在合适的时机自己调用 today_almanac 工具来回答，你完全不用管工具怎么触发。

这个插件是怎么做出来的

上面是"用"的部分。下面讲"做"的部分，这也是理解插件机制的关键。

一个插件的三件套

DeepSeek Harness 的插件分发有个约定：一个 npm 包，只要在 package.json 里声明了 dsh.bundle，它就是一个可安装的插件层。一个可分发插件包由三样东西组成：

1. 插件本体（src/index.js）。核心是 apply 函数里那句 ctx.tools.register()，把工具注册进 agent：

export const name = 'today-almanac'export const inject = ['tools']export function apply(ctx) {  ctx.tools.register({    name: 'today_almanac',    description: '查询农历黄历信息：农历日期、干支、生肖、冲煞、宜忌。date 可选，省略默认今天。',    parameters: {      type: 'object',      properties: {        date: { type: 'string', description: '格式 YYYY-MM-DD，省略默认今天。' },      },    },    async execute(args) {      const { y, m, d } = parseSolarDate(args?.date)      return buildAlmanac(y, m, d)    },  })}

2. 包声明（package.json）。最关键的一行是 dsh.bundle.patch，告诉 Harness 这个包是个插件层：

{  "name": "@xinyi-it/today-almanac",  "version": "0.1.1",  "type": "module",  "main": "src/index.js",  "dsh": {    "bundle": { "patch": "./cordis.patch.yml" }  }}

3. patch 清单（cordis.patch.yml）。声明这个插件层要挂载哪个插件：

- insert:    - id: today-almanac      name: '@xinyi-it/today-almanac'

装命令背后发生了什么

dsh plugin add 这条命令，本质是把参数转给 pnpm，在 profile 目录里装这个包。装完它会检查这个包有没有声明 dsh.bundle，有的话就自动把它加进插件层栈，下次启动就挂载。

我一开始装的时候踩了个坑：ctx.tools.register 的 parameters 必须写成完整的 JSON Schema（带 type: 'object' 和 properties），我偷懒只写了属性，结果 agent 一调用就报错：

Invalid schema for function 'today_almanac': schema must be a JSON Schema of 'type: "object"', got 'type: null'.

改成完整 schema 就通了。

黄历算法：离线，可复现

工具里最花心思的是黄历算法。阳历转农历靠一张 1900 到 2100 年的农历数据表（每年一个十六进制数编码闰月和大小月），干支按农历算年柱、月柱，日柱则按儒略日精确推算，所以同一天的三柱（年月日）是唯一且确定的。宜忌部分用一个固定的规则表映射日期，同一个日期永远返回同一组宜忌，保证可复现。写完插件后，我又让 agent 生成了一个独立的离线脚本，对同一批日期交叉验证，插件输出的黄历和脚本算出来的一字不差。

整个插件 197 行，全部离线计算，不需要联网。

玩法总结：四层，从省事到硬核

实测下来，玩插件有四个层次，看你的需求：

前两层是"用插件"，后两层是"玩插件"。自己写最有意思：你给 agent 定义一个工具，它立刻多一个能力，从写代码到跑通不用碰框架源码。

如果你想给 agent 加别的本事，思路一样：写一个带 execute 的工具函数，打包声明 dsh.bundle，一条 dsh plugin add 装好。至于想做什么工具，就看你需要 agent 会什么了，查天气、算汇率、查快递，都能这么做。

本文为原创内容，首发于公众号「新一技术宅」，转载请注明出处。

项目地址：

• • DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness
• • 黄历插件包（today-almanac）：https://www.npmjs.com/package/@xinyi-it/today-almanac数据来源：DeepSeek Harness 源码实测（2026.08.14）