DeepSeek Harness 插件使用指南

本文来自真实操作记录：在聊天里让 agent 装插件、装天气插件并查天气、对比 token 消耗、装插件市场，最后从零写一个航班查询插件。
文中的命令、输出、数字都是实测结果。

一、插件是什么

一句话：插件是给 DeepSeek Harness（DSH）加装的"配件"。
打个比方：DSH 本身像一部手机，自带电话、短信、相机。但你想查天气、查航班、想接微信、想让侧边栏长出文件树，就得装 App——插件就是这些 App。
技术上它并不神秘：

• 插件就是一个普通的 npm 包，在 package.json 里声明两样东西之一：
  • dsh.bundle —— 提供一层配置（比如"插入一个 id 为 xxx 的插件行"）；
  • dsh.client —— 提供界面（侧边栏、设置页、按钮）。
• 执行 dsh plugin add 后，这个包被装进某个 profile 的依赖里，包名被追加到该 profile 的 bundles 列表。
• 下次启动（或热加载）时，DSH 按 bundles 顺序逐层叠加配置，插件就生效了。
  一句必须记住的话：插件以"受信代码"的身份，在你的机器上、你的权限下运行。它能读你的文件、能联网、能调用你的接口。所以——只装源码可信的插件。

二、插件能带来什么好处

1. 省 token（最直观）

以"查南京天气"为例：

1. 代码替代模型做机械劳动：取数、换算、排版都在插件进程里完成。
2. 输出 token 更贵：多数 API 输出单价是输入的 3~5 倍。
3. 没有纠错回合：网页抓取会遇到反爬、超时、正文缺失，一重试就再烧一轮。
4. 事实更稳：也省掉了"模型把 17.4°C 抄成 1.74°C"这类风险。

2. 更快、更稳

一次工具调用 vs 三四轮往返，延迟差是秒级的；数据来自固定接口，不会因为某次搜索改版就崩。

3. 能力扩展

天气只是最小例子。社区插件覆盖：侧边栏工作台、上下文压缩、IM 接入（微信/飞书/钉钉）、图片理解、余额看板、工作流编排……

4. 可插拔，不动核心

装 = 加一条依赖；卸 = 删一条依赖。不修改 DSH 源码，升级 DSH 也不会覆盖你的改动。

5. 但也有反向成本（别忽略）

工具定义（名称、描述、参数说明）会随每次请求一起发给模型，不管你这一轮用不用，大约 60~90 tokens/次请求。

• 只查一轮天气：省 3,000+，付十几轮 × 80 ≈ 1,000，仍然划算；
• 装 20 个插件：每轮多背几千 tokens 的工具定义，可能由赚变亏。
  结论：按需装，用完卸。

三、插件怎么装

3.1 最常用的方法：直接跟 agent 说（推荐）

不用记命令，不用开终端。 你只要把话说清楚，agent 会自己完成剩下的步骤。
你可以这么说：

1. 确认来源——包名 / GitHub 仓库 / 本地目录 / 一个链接；
2. 纠正写法——比如裸名 dsh-market 在 npm 上其实不存在（404），真正的包是 @dsh-market/plugin；
3. 判断 profile——桌面版必须装进 desktop，装到 web 会"命令成功但界面没反应"；
4. 执行 + 校验——跑 dsh plugin add，再读 package.json 确认 bundles 里出现了包名，必要时提醒你重启。
   为什么这是主流：包名、scope、版本、profile 这些细节最容易出错，而 agent 可以现查、现改、现验证。

两个小提醒：① 说清楚"装到我现在这个界面"，避免装错 profile；② 来源要给全（名称或路径），agent 不会去猜一个不存在的包。

3.2 真实案例：一句话装好

本会话里就发生过两次：
案例一——你说「帮我安装这个地址下的插件」，给了本地路径 ...\dsh-weather-plugin：
识别为本地目录 → 判断桌面版用 desktop → 执行安装 → 读 package.json 校验 → 立刻调用 weather 工具查了一次南京，确认工具真的能用。
案例二——你贴了一条命令 dsh plugin --profile web add dsh-market：
agent 发现两个问题：① npm 上 dsh-market 返回 404，真正的包是 @dsh-market/plugin；② web 不是你当前界面用的 profile（是 desktop）。于是改写成 dsh plugin --profile desktop add @dsh-market/plugin 执行成功。
这就是"聊天里装"的价值：它会替你纠错，而不是把错误命令原样跑一遍。

3.3 命令行方式（想自己掌控时用）

dsh plugin --profile <profile名> add <来源>

dsh plugin 本质是把参数透传给 pnpm，在 profile 目录里执行。所以 pnpm 的动词都能用：add / remove / why / list。

3.4 先搞清楚装到哪个 profile

profile 是"一套可启动的配置"，同一台机器可以有多套：

• 桌面版 App：固定用 desktop（目录 ~/.dsh/profiles/desktop）
• 命令行 dsh web：通常用 web
  查当前用哪个（Windows）：

Get-Process -Name 'DeepSeek Harness' | Select-Object Id,Path,StartTime
# 再看 ~/.dsh/profiles 下哪个目录的 package.json 修改时间 ≈ 上面进程的启动时间

3.5 三种来源

3.6 装完怎么验证

看 profile 的 package.json：

"dependencies": { "@dsh-market/plugin": "^0.4.16" },
"dsh": { "profile": { "bundles": [
  "@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-weather", "@dsh-market/plugin"
]}}

bundles 里出现了包名，才算真正"挂上"了。

3.7 卸载

dsh plugin --profile desktop remove @dsh-market/plugin

依赖和 bundle 层一起删。

3.8 什么时候需要重启

• 只注册服务端能力（如工具 weather、flight）→ 通常热加载，立刻可用；
• 带界面（dsh.client，如侧边栏市场）→ 需要重启 App；
• 改了插件源码 → 也要重启，已加载的模块不会因为文件变了就重新导入（见 6.6）。

四、插件市场

4.1 地址

地址可以检索网站直接搜DSH社区插件市场，此处无法展示链接
社区维护的 DSH 插件索引站（页脚写明：community project, not affiliated with DeepSeek AI）。
规模（抓取时）：

4.2 能做什么

• 按分类浏览（UI / 会话 / 记忆 / 工具 / 技能智能体 / 工作流 / 集成 / 模型 / 开发运维 / 知识 / 娱乐）；
• 按 star 看热度、按更新时间看活跃度；
• 详情页有简介、star/fork、许可证、版本、可一键复制的安装命令，还有 FAQ 排障。

4.3 热度前五（按 star，已去重）

提醒：① 第 1 名 repo 创建 5 周就 57k star，热度异常，且原理是把 prompt 发给不明公共网关；② “Verified” 只代表人工收录，不是安全审计。

4.4 在 DSH 菜单栏里装市场（推荐）

不想每次开浏览器复制命令，就把市场做成 App 内入口。最省事的说法就是：

「帮我装个插件市场」
对应命令（注意包名带 scope，裸名 dsh-market 在 npm 上不存在，会 404）：

dsh plugin --profile desktop add @dsh-market/plugin

实测输出：

+ @dsh-market/plugin 0.4.16
Done in 5.6s using pnpm v11.28.5

该包声明了 dsh.client，所以重启 App 后，侧边栏/设置里会出现「插件市场」：浏览、搜索、猜你喜欢、一键安装、已装管理。
同类别名（选一个即可，别重复装）：

五、实战：装天气插件、查天气

5.1 安装

实际用户的做法：在聊天框里说一句就行。

「帮我装一下 C:\Users\huyu\WorkBuddy\2026-11-03-10-41-41\dsh-weather-plugin 这个插件」
agent 会自动走完整个流程：识别这是本地目录 → 判断你的桌面版要装进 desktop profile → 执行安装 → 读 package.json 确认 bundles 里挂上了 → 顺手调用一次工具，确认真能用。你不用开终端，也不用记任何命令。
如果你想自己敲命令，等价操作是：

& 'C:\Users\huyu\AppData\Local\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd' `
  plugin --profile desktop add "C:\Users\huyu\WorkBuddy\2026-11-03-10-41-41\dsh-weather-plugin"

输出：

dependencies:
+ dsh-weather 0.1.0 <- ..\..\..\WorkBuddy\2026-11-03-10-41-41\dsh-weather-plugin
Done in 663ms using pnpm v11.28.5

weather 工具立刻出现（无需重启），实测查询南京：

南京（江苏 · 中国）
2026-11-03 13:45 实测
阴 17.4°C（体感 15.4°C）
湿度 53%｜东风 8.9 km/h｜降水 0 mm
未来 3 天
11-03  毛毛雨  13.3 ~ 17.4°C  降水概率 63%
11-04  毛毛雨  14.6 ~ 18.7°C  降水概率 100%
11-05  阴  13.3 ~ 20.8°C  降水概率 0%

两次查询的时间戳分别是 13:45 和 14:15，都是实时拉的——说明插件真的在联网，不是缓存。

5.2 分工

• 模型负责：判断"用户问天气"→ 选工具 → 传参 city="南京"；
• 插件负责：解析地名 → 请求 api.open-meteo.com → 结构化 JSON → 用自己的 render 排版。
  凡是能写成代码的事，就别让模型去"想"。

六、自己写一个插件：航班查询

前面都是"装别人的"。这一节从零做一个插件，证明写插件没那么难。

6.0 先说结论：你可以完全不看后面的技术细节

如果你只是想要一个能查航班的工具，6.1~6.5 里的文件、目录结构、数据源选型全都跟你无关。你只需要说一句：

「帮我写一个能查航班的插件」
然后什么都不用管——等 agent 回你"做好了、装上了、已经测通"，你直接自己试一句「CA1501 飞哪条线」验收即可。写得对不对、装没装上、数据准不准，一次真实调用就看得出来，不需要你去读代码。
后面的技术内容，是写给两类人的：想自己改代码的人，以及想判断"这个插件靠不靠谱"的人。

6.1 定需求、选数据源

需求：一句「CA1501 飞哪条线」，返回航司、起降机场、实时位置。
数据源选型（关键：免 Key，否则用户还要去注册）：

{"response":{"flightroute":{
  "callsign_iata":"CA1501","callsign_icao":"CCA1501",
  "airline":{"name":"Air China","iata":"CA"},
  "origin":{"name":"Beijing Capital International Airport","iata_code":"PEK","municipality":"Beijing"},
  "destination":{"name":"Shanghai Hongqiao International Airport","iata_code":"SHA","municipality":"Shanghai (Minhang)"}
}}}

发现一个小惊喜：adsbdb 同时接受 IATA（CA1501）和 ICAO（CCA1501），省掉一张航司代码映射表。

6.2 目录结构

dsh-flight-plugin/
├── package.json        # 声明 dsh.bundle → 它才是一个"可安装的 bundle"
├── cordis.patch.yml    # bundle 层：把一个 id 为 dsh-flight 的插件行插进配置
├── lib/index.js        # 插件本体（纯 ESM，不需要编译）
└── test/verify.mjs     # 纯网络自检，不依赖 DSH 就能跑

6.3 三个文件

① package.json —— 关键是 dsh.bundle：

{
  "name": "dsh-flight",
  "version": "0.1.0",
  "type": "module",
  "main": "lib/index.js",
  "peerDependencies": {
    "@deepseek-ai/cordis": "*",
    "@deepseek-ai/dsh-tools": "*",
    "@deepseek-ai/schemastery": "*"
  },
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

② cordis.patch.yml —— 声明"装了我之后，往配置里插一行"：

- insert:
    - id: dsh-flight
      name: dsh-flight
      config:
        livePosition: true
        timeoutMs: 10000
        liveTimeoutMs: 4000

③ lib/index.js —— 本体只有四块：

import { defineTool } from '@deepseek-ai/dsh-tools';
import Schema from '@deepseek-ai/schemastery';
export const name = 'dsh-flight';
export const inject = ['tools'];          // ★ 不写就不等 tools 就绪，表现为"装了但工具不出现"
export function apply(ctx, config) {
  ctx.tools.register(defineTool({
    name: 'flight',
    description: '查询航班的航线与实时位置……',
    parameters: {
      flight: { type: 'string', description: '航班号，例如 CA1501' },
    },
    output: {
      schema: { /* 每个字段都标 required: true */ },
      render: (_args, value) => [{ type: 'text', text: renderText(value) }],
    },
    async execute(args, exec) {
      const signal = AbortSignal.any([          // ★ 必须观测调用方取消
        exec.signal,
        AbortSignal.timeout(config.timeoutMs ?? 10000),
      ]);
      const route = await fetchRoute(args.flight, signal);
      const live = await fetchLive(route.callsign_icao);  // 失败自动降级
      return { flight: {...}, live, observedAt: localStamp() };
    },
  }));
}

三个"看起来不起眼但会要命"的细节：

1. inject = ['tools'] —— Cordis 并发加载，不声明就不会等工具注册表就绪；
2. output.schema 里每个属性都要 required: true —— 否则渲染函数里到处要判空；
3. execute 里必须观测 exec.signal —— 用户中断后请求还在跑。

6.4 装上并验证（真实输出）

& '...\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add `
  'C:\Users\huyu\WorkBuddy\2026-11-03-10-41-41\dsh-flight-plugin'

dependencies:
+ dsh-flight 0.1.0 <- ..\..\..\WorkBuddy\2026-11-03-10-41-41\dsh-flight-plugin
Done in 412ms using pnpm v11.28.5

热加载生效，直接调用工具（无需重启）：

CA1501（CCA1501） · Air China
航线：Beijing PEK → Shanghai (Minhang) SHA
  Beijing Capital International Airport（PEK · Beijing）
        ✈
  Shanghai Hongqiao International Airport（SHA · Shanghai (Minhang)）
实时位置：暂未获取到（该航班当前无广播，或数据源限流）。
数据源：adsbdb｜查询于 2026-11-03 15:12

换成反向航线同样成立：

MU5101（CES5101） · China Eastern Airlines
航线：Shanghai (Minhang) SHA → Beijing PEK

实时位置那句"暂未获取到"不是 bug，而是设计好的降级：OpenSky 匿名接口常限流，超时 4 秒就放弃，不让它拖慢主结果。网络好时它会显示高度/地速/航向。

6.5 顺带说：也可以让 agent 帮你写

这次航班插件就是"说一句需求 → agent 写代码 → 装 → 自测"完成的。开发过程里 agent 通常会：

1. 先 curl 数据源确认字段（避免写完才发现没有你要的数据）；
2. 按最小结构建三个文件；
3. 本地跑 node test/verify.mjs 先验证数据层，再装进 profile；
4. 装完立刻调用一次工具，用真实输出确认端到端通了。
   对不会写 JS 的用户来说，这条路比查文档快得多；会写的人则可以只让 agent 做"脚手架 + 排障"。

七、注意事项

1. 插件 = 受信代码。装之前看源码，尤其是要联网、读文件、执行命令的。
2. 装错 profile 是最常见的坑。桌面版是 desktop，不是 web。
3. 包名要完整。scoped 包必须带 @scope/，裸名往往不存在。
4. 界面类插件要重启；工具类可以热加载；改源码也要重启。
5. 别贪多。每个插件都给每轮请求加几十 tokens 的固定成本。
6. market 是社区站，热度、排名、Verified 徽章都不等于安全背书。

八、速查表

# 最省事：直接跟 agent 说
「帮我装个插件市场」
「把 C:\path\to\plugin 装上」
「帮我写个能查航班的插件」

# 命令行
dsh plugin --help                          # 看用法
dsh plugin --profile desktop add @dsh-market/plugin
dsh plugin --profile desktop add "C:\path\to\plugin"
dsh plugin --profile desktop add github:owner/repo
dsh plugin --profile desktop remove @dsh-market/plugin
# 校验是否挂上
cat ~/.dsh/profiles/desktop/package.json   # 看 bundles 里有没有包名

本文档基于实测整理，命令与输出均为原文。插件生态迭代很快，具体包名与版本请以官方 README 为准。