DSH插件体系实战：从核心概念、安装配置到二次开发

先问一个问题：你在用 DSH 跑 AI 任务时，是不是也有这种感觉——核心框架很顺手，但一旦需要接入新模型、新工具、新数据源，就得改主流程代码？改着改着，主分支变得又脆又难维护。后来我接触了 DSH 的插件机制，才发现这类问题其实可以换一种思路解决：框架只做“调度与执行”，把能力扩展全部交给插件。这正是“一切皆插件”的价值所在。本文会围绕 DSH 插件体系的安装、配置、管理、排查和二次开发展开，尽量把底层逻辑和可复制的命令都讲清楚。

如果你刚开始接触 DSH，建议按顺序读完，先搭好环境再去尝试真实插件。如果你已经在用 DSH，可以直接跳到“插件安装与管理完整实战”和“常见问题与排查思路”两章，很多踩坑点都整理在那边。

1. 背景与核心概念

1.1 DSH 是什么

DSH 的全称是 DeepSeek Harness，简单理解就是一套面向 AI Agent / 多智能体场景的“执行编排框架”。在 AI 开发中，Harness 这个概念通常指：负责把模型调用、上下文管理、工具执行、结果回传等环节串起来的那一层“控制台”。

很多团队做 AI 应用时，会先封装一个内部库，把 API 调用、提示词模板和工具函数放在一起。这个方案在小项目里没问题，但业务复杂后，模型版本要换、工具越来越多、不同项目需要的功能也不一样，任何一处改动都可能牵一发动全身。DSH 这类 harness 工具的定位，就是把“被调度的业务能力”和“调度框架本身”解耦，让模型能力、工具函数、前端入口都以插件的形式接入。

它并不是一个大而全的应用，而是一个开放容器。你可以把 DSH 理解成一套“乐高底座”，自己拼装 Agent 能力，而不是从零开始造轮子。正式做技术选型前，我建议你先把 DSH 的源码跑起来，观察它的插件目录、配置文件和加载日志，会比只看文档理解得深很多。

1.2 “一切皆插件”到底指什么

DSH 插件体系里经常能看到一句话：everything is a plugin。意思是模型适配器、工具函数、前端界面、数据导入导出、本地文档读取等能力，都通过插件形态接入核心框架。

这样做有三个好处：

• 核心框架保持精简。调度和编排逻辑稳定，不需要频繁修改主代码。
• 功能边界清晰。每个插件只做一类事，例如“读取 PDF”“执行网页搜索”“调用某个模型”“格式化输出”等。
• 按需组合。同一个框架，web 场景加载网页处理插件，本地桌面场景加载桌面工具插件，互不干扰。

这和传统“把功能写死在代码里”的方式完全不同。用普通 import 导入一个模块时，模块与主程序是编译期绑定；插件则是在运行时动态扫描、动态加载。DSH 维护一张“插件树”，里面记录哪些插件被启用了、它们的依赖是否完整、入口文件能否正常加载。一旦加载失败，会直接影响当前 profile 的执行环境，而不是整个系统崩溃。

理解这一点后，再去看 DSH 的安装命令，就不会认为“装插件 = 拷贝文件到某个目录”。插件安装的本质是：把插件注册到 DSH 的配置体系，并让它在正确的执行上下文中被加载。

1.3 DSH 插件的典型应用场景

从目前社区讨论和实际项目的整理情况来看，DSH 插件主要使用在这几类场景：

1. 模型与多智能体编排：接入不同模型服务、不同 Agent Worker，通过插件描述各自的职责、工具列表和输入输出协议。
2. 本地文档处理：在原有模型中增加“读取 PDF / Word / Markdown / 网页内容”的工具，让模型能基于本地文件做分析和生成。
3. Web 自动化与信息收集：通过--profile web这类场景配置，加载网页抓取、表单操作、浏览器数据解析相关插件。
4. 开发工具集成：把代码诊断、终端命令执行、Git 操作、CI 产物解析等能力封装成插件，让 DSH 成为一个能真正“动手干活”的 Agent。
5. 桌面应用入口：用户使用 dsh desktop 这类的图形界面，插件可以作为功能卡片展示，点击后在后台创建对应任务。

换句话说，DSH 插件并不是为了“让功能更多”而存在，而是为了让不同场景共享同一个执行底座，从而减少重复开发。

2. 环境准备与安装方式

2.1 运行环境与版本说明

DSH 本质上是一个应用工具，社区常见的运行方式包括源码运行、CLI 安装，以及 Docker 部署。不同运行方式对环境的要求不太一样：

• 安装 DSH CLI 或运行 Web 服务，一般需要 Node.js 环境，推荐使用 pnpm 或 bun 作为包管理器。
• 如果使用桌面版，则需要安装对应的图形界面客户端。
• 如果使用 Docker，可以在容器内运行，宿主只需要 Docker 环境。

不同 DSH 版本的命令参数、插件配置格式可能有差异。下面所有命令采用通用示例，真实执行时请先通过dsh plugin --help或项目 README 确认入口名称，不要直接照抄到生产环境。版本没有统一要求，本文示例以常见 Node.js + pnpm 环境为例，重点是演示配置思路。

2.2 获取 DSH：源码、CLI 与 Docker

第一种是从源码运行。这种方式适合需要阅读源码或开发自定义插件的用户。通常操作如下：

git clone <你的 DSH 项目仓库地址> dsh cd dsh # 安装依赖 pnpm install # 如果项目有构建步骤，先构建 pnpm run build # 通过包管理器启动 CLI pnpm dsh --version

注意，这里的仓库地址需要以你实际获取到的 DSH 源码地址为准。不同仓库的结构差异很大，有些项目根目录直接是 CLI，有些则是 monorepo 多包结构，需要先进入apps/cli之类的目录再执行安装命令。

第二种是全局安装或使用 CLI 运行时。如果 DSH 发布了 npm 包或提供了二进制文件，可用下面这种形式：

# 示例，具体包名请以官方安装文档为准 npm install -g @dsh/cli dsh --version

如果你下载的是压缩包，则把它解压后加入 PATH 环境变量。因为 DSH 生态推进较快，不排除部分命令在后续版本改名。

第三种是 Docker 部署。对局域网访问、服务化运行更友好。构建或拉取 DSH 镜像后，可以用类似下面的命令启动：

docker run -it --rm \ -v "${PWD}/dsh-data:/root/.dsh" \ -p 3000:3000 \ <dsh-image> \ dsh web --host 0.0.0.0

这里的<dsh-image>需要替换成你自己构建的镜像名或官方镜像名。把数据目录挂载出来的目的，是为了让插件安装结果、配置文件在容器重建后不丢失。

2.3 验证基础环境

不管你用哪种方式安装，都建议先执行两步检查：

dsh --version dsh doctor

dsh --version用于确认可执行文件是否可用；dsh doctor则是一个常见的诊断命令，用来检查运行环境是否满足要求。如果doctor输出了缺失依赖、权限错误或网络不通的提示，先解决这些问题，否则后续插件安装可能会出现莫名其妙的失败。

如果 DSH 还需要读取模型 API Key，通常可以通过环境变量或配置文件注入，不要在终端里明文写出密钥。更安全的做法是设置环境变量并在配置文件中引用：

export DSH_MODEL_API_KEY="sk-xxxx"

注意：这一步仅用于本地开发测试。在共享服务器上请使用密钥管理服务，不要把真实 Key 写到可以被 Git 跟踪的文件中。

2.4 网络环境与模型服务

DSH 加载插件时，可能需要访问远端插件源；实际运行任务时，也可能需要调用模型接口。因此，在安装插件之前，请务必确认以下几点：

• 当前服务器或本机可以访问需要的插件源地址。
• 如果需要代理访问外部模型 API，应在 DSH 配置中设置相关连接参数。
• 企业内网环境通常无法直接访问公网，建议配置内部镜像源或采用离线安装方式。

常见的一种启动卡顿现象是：deepseek harness 卡在 pnpm dsh web，很多人以为命令卡死，其实是 Web 服务在等待模型测试连接或插件源下载请求超时。可以先用较短超时参数、关闭调试日志观察，也可以直接查日志定位。

3. 插件机制核心拆解

3.1 插件树、Profile 与运行上下文

在 DSH 中，插件树（plugin tree）是一个比较重要的数据结构。它记录了当前环境下所有可加载插件、它们的入口文件、依赖关系以及启用状态。执行插件加载时，DSH 会自上而下扫描这棵树，如果某个节点的入口文件缺失、依赖无效或加载顺序出现问题，就会报错。

Profile 则定义了“当前使用场景”。可以把它理解成一组插件配置的快照。例如，--profile web指面向 Web 任务的插件集合，里面可能包含浏览器采集、网页解析、页面工具等插件；开发代码场景则可能切换到另一个 profile。这样做的好处是：同一个 DSH 安装目录下，不同用途的任务不会互相污染。

使用插件时，你会在很多地方看到类似这样的写法：

dsh plugin --profile web add dshmarket

这条命令的含义是：向web这个 profile 添加dshmarket插件源。dshmarket通常指 DSH 的插件市场地址，类似 VS Code 中的插件市场或 npm 的 registry。

3.2 插件市场与 Awesome DSH Plugin

DSH 的插件市场一般叫 DSH Market。它解决了“去哪里找插件、如何分发插件”的问题。社区中也出现了例如awesome-dsh-plugin这样的清单型仓库，专门整理高质量 DSH 插件，便于开发者检索。

与 npm 不同的是，DSH Market 不一定只有一个公共源。你可以使用本地源、私有源，也可以只把某个目录作为插件源。小型团队在内部只发布几个自研插件时，没必要搭建完整市场服务，把插件目录放到 Git 仓库并定义好版本号即可。

添加市场源后，需要刷新插件列表或重新扫描插件树，新市场里的插件才会出现在搜索结果中。如果添加完成后搜索不到，优先检查市场地址是否能正常访问，以及当前 profile 是否允许安装该类型插件。

3.3 插件加载的基本过程

插件加载过程大致分为四步：

1. 解析入口。DSH 读取插件清单，找到入口文件，确认该文件存在。
2. 解析依赖。插件声明的依赖需要先被加载，如果缺少依赖，整个插件会被标记为加载失败。
3. 注册能力。插件把自己支持的能力注册到当前运行上下文，比如“支持读取 PDF 的工具”“支持搜索浏览器页面的工具”。
4. 运行验证。在带必要权限的上下文中执行一次初始化，确认插件能正常工作。

这个过程中最常见的错误之一就是：

plugin tree failed to load: failed to apply loader entry include (cordi...

从字面看，DSH 在加载插件树时，无法应用某个 loader 入口的 include 配置，常见原因包括插件目录结构不对、入口文件不存在、插件清单中的 include 字段写法错误，或者插件依赖了另一个还未安装的插件。这不是模型问题，而是插件环境问题，优先检查插件文件路径，不要一上来就重装依赖。

3.4 为什么插件能带来“自进化”

如果把 DSH 看作一个可以自主完成任务的智能体运行框架，那插件的价值就在于：它让这个智能体的能力边界可以持续更新，而不需要升级核心框架。

例如，今天你安装了一个“读取 PDF”插件，DSH 就具备了处理本地 PDF 文档的能力；明天你安装一个“代码诊断”插件，DSH 就多了一个自动 review 本地代码的工具。这个过程有点像一个系统在“给自己加新器官”，这就是社区所说的“自进化”含义。

真正的演进路径应该是：先由开发者编写或挑选新插件，在测试环境中验证，然后在受控条件下为 DSH 动态加载。这不是让系统自行无限制地下载插件，而是把扩展能力做成了标准化通道。对用户而言，使用体验是从“我遇到了一个新功能需求”，变成“我安装了一个新插件，DSH 恢复了执行能力”。

4. 插件安装与管理完整实战

4.1 开始前先看帮助

磨刀不误砍柴工。无论你看到多少现成的 DSH 插件安装命令，第一步都应该查看当前版本的插件帮助信息：

dsh plugin --help

如果插件命令还支持子命令，再继续查看：

dsh plugin install --help dsh plugin source --help

不同版本的参数并不完全一致。常见子命令包括：

• search搜索插件
• install安装插件
• uninstall卸载插件
• list列出已安装插件
• tree查看插件依赖树
• doctor诊断插件环境

先把帮助信息过一遍，能避免对着旧教程敲一堆无效命令。

4.2 为 Web 场景添加 dshmarket

假设你要在 Web 任务中使用 DSH 的社区插件，首先需要把插件市场源加到对应的 profile。根据社区常见命令：

dsh plugin --profile web add dshmarket

这条命令执行后，DSH 会把 dshmarket 记为webprofile 的资源来源，之后你在该 profile 下搜索和安装插件时，就能找到市场中已经发布并适配该 profile 的插件。

如果执行后提示找不到 profile，可以先创建一个新的 profile 或切换到已有 profile。有些版本会使用--profile=web的语法，效果一样：

dsh plugin --profile=web add dshmarket

添加完成后，验证源是否生效：

dsh plugin list --profile web

它能打印当前 profile 已经加载和可用的插件源信息。

4.3 搜索与安装插件

插件源配好后，可以在 DSH 插件市场中搜索你想要的插件。举例来说，如果你需要 PDF 解析能力，可以先搜索：

dsh plugin search pdf --profile web

假设搜索结果中存在名为dsh-pdf-reader的插件，安装命令一般是这样：

dsh plugin install dsh-pdf-reader --profile web

不同插件可能要求不同的运行权限，比如读取文件系统、调用外部 API、执行本地命令。安装时，DSH 会在依赖树中写入记录，并让你确认授权策略。这里需要特别留神：不要习惯性点击全面授权，应该只给最小权限。

安装扩展时你也可以手动指定版本。这里建议锁定版本，避免新版本 API 不兼容导致核心流程异常：

dsh plugin install dsh-pdf-reader@0.1.0 --profile web

当然，具体版本号以你搜索到的实际版本为准。

4.4 查看插件树并验证加载

安装完成后，第一件事不是立刻使用，而是查看插件树：

dsh plugin tree

输出结果会展示层级关系。例如：

dsh └── web profile ├── dsh-market-source └── dsh-pdf-reader └── pdf-parser-core

其中，pdf-parser-core是dsh-pdf-reader依赖的底层库。如果这一层缺失，dsh-pdf-reader会加载失败。

随后可以执行一次环境诊断：

dsh plugin doctor

它会检查已安装插件是否存在入口缺失、依赖不完整、权限配置不合法等问题。出现红色警告时不要忽略。

4.5 给 DSH 增加读取本地 PDF 的能力

DSH 插件体系可以包含现成插件，也可以调用本地能力。假设你暂时没有找到合适的 PDF 插件，或者想验证某个思路，可以先写一个轻量 Python 脚本，作为外部工具让 DSH 调用。

先用pdfplumber写一个 PDF 文本提取脚本：

# 文件路径：tools/pdf_to_text.py import sys import pdfplumber def pdf_to_text(path: str) -> str: text_parts = [] with pdfplumber.open(path) as pdf: for page in pdf.pages: content = page.extract_text() or "" text_parts.append(content) return "\n".join(text_parts) if __name__ == "__main__": if len(sys.argv) < 2: print("Usage: python pdf_to_text.py <pdf_path>", file=sys.stderr) sys.exit(1) print(pdf_to_text(sys.argv[1]))

安装依赖：

pip install pdfplumber

运行验证：

python tools/pdf_to_text.py demo.pdf

输出是纯文本后，再把脚本接入 DSH。如果你使用的是支持“命令工具”的 DSH 版本，可以在配置中声明一个工具，让它执行python tools/pdf_to_text.py <path>，并由 DSH 捕获 stdout 输出。

这里要注意权限边界：让 DSH 读取用户指定的 PDF 没问题，但不要让 Agent 无差别扫描服务器全部文件。路径参数必须经过工具函数校验，避免路径穿越风险。

这种做法虽然不是严格意义上的 DSH 插件封装，但思路通用：先让外部脚本能稳定运行，再通过插件或工具配置接入 Agent 上下文。DSH 核心价值就是保留这种“逐步替换”的灵活性。

4.6 插件的更新、清理与生态维护

插件越装越多后，会遇到版本更新和冗余插件问题。

需要更新某个插件时，可以先查看已安装版本：

dsh plugin list

更新命令因版本而异，常见形式为：

dsh plugin update dsh-pdf-reader

如果发现插件不再使用，及时卸载：

dsh plugin remove dsh-pdf-reader --profile web

如果只想清理未被依赖引用的缓存包或孤儿文件，可以使用清理类命令。例如部分版本提供：

dsh plugin prune

在清理前，先导出当前插件清单，便于回滚：

dsh plugin list --output json > plugins-backup.json

养成这样的习惯，能避免误删关键插件后无法恢复。

5. 桌面端与多智能体场景

5.1 dsh desktop 中管理插件

在图形界面下安装插件与在命令行中安装略有不同。DSh desktop 一般会扫描 CLI 中已经添加的插件源，并在界面上列出“可安装插件”“已安装插件”和“插件依赖状态”。

常见操作步骤：

1. 打开 dsh desktop，进入“插件”或“扩展”面板。
2. 搜索目标插件。
3. 点击安装，并在权限弹窗中确认勾选项。
4. 安装完成后重启当前项目或刷新插件面板。

如果命令行与桌面端使用同一份 DSH 数据目录，两端会看到相同的插件列表。若桌面端没有显示某插件，可能是两端数据目录不一致，也可能是桌面端需要重新读取配置文件。

特别注意：桌面端如果加载失败，很多情况下并不需要重装插件，而是先看“插件日志”。它会比命令行输出更详细地记录加载栈，能直接定位到对应 loader。

5.2 DSH 多智能体场景的插件设计

DSH 的“多智能体”能力来自多个 Agent Worker 的配合。每个 Worker 完成一类子任务，而插件则描述了这些 Worker 的能力边界与调用规则。

在真实项目中，比较简洁的做法是：为一个角色准备一个插件，插件内声明它支持的工具、模型参数和输入输出协议。比如“代码审查 Worker”加载与 Git 操作、静态扫描相关的插件；“文档处理 Worker”加载 PDF 读取、Markdown 转换等插件。

编排时，由 DSH 的 harness 决定把任务分配给哪个 Worker。这要求插件设计中有一个容易忽略的约束：插件描述要足够准确。如果插件声明的能力范围过大，调度器可能把 PDF 任务发给代码审查 Worker，导致执行失败。

推荐为每个 Worker 制作能力清单，保持插件只做一件事。多智能体不是插件数量越多越好，而是边界越清楚越好。

5.3 Docker 部署与局域网访问

Docker 部署的一大好处是环境隔离和进程管理简单。常见部署方式是启动一个 Web 模式的 DSH 服务，宿主机或局域网内其他设备通过浏览器访问。

启动命令可参考：

docker run -d \ --name dsh-server \ -v "${PWD}/dsh-data:/root/.dsh" \ -p 3000:3000 \ <dsh-image> \ dsh web --host 0.0.0.0 --port 3000

启用--host 0.0.0.0后，容器监听所有网卡，局域网内其他设备就能通过宿主机 IP 访问。例如宿主机 IP 是192.168.1.10，同一网段浏览器输入http://192.168.1.10:3000即可打开 DSH 服务。但此时任何拿到该 IP 端口的人都能尝试访问，所以必须先做好访问控制。

安全建议如下：

• 不要用默认空密码或公开的固定 token。
• 尽量只在可信内网开放端口。
• 如果需要在公网访问，请使用反向代理并配置 HTTPS 与身份认证。
• 对插件安装接口、Agent 执行接口单独做权限隔离，避免未授权人员向 DSH 下发任意命令。

另外，容器内的数据目录只挂载一个dsh-data目录，不要直接把宿主机根目录挂进去。插件有权限读取某些宿主文件时，容器隔离将形同虚设。

6. 常见问题与排查思路

6.1 常见错误对照表

6.2 插件树 failed to load 排查

遇到failed to apply loader entry include类错误，建议按以下顺序排查：

1. 查看插件目录是否正确。DSH 启动时会从配置目录扫描插件，如果手动拷贝文件到错误位置，自然加载不出来。
2. 检查插件入口字段。插件清单中entry指向的文件是否存在，是否因为打包过程漏掉了源文件。
3. 检查依赖是否完整。插件 A 依赖插件 B，但 B 未安装，A 也会加载失败。此时执行dsh plugin tree可以看出依赖关系。
4. 尝试在干净 profile 中单独安装该插件。如果一个 profile 中插件过多导致冲突，这种方式能够判断问题是否由组合引起。

6.3 模型能力与插件配置不符

有朋友遇到过“DSH 中无法使用 opencode go deepseek v4 flash vision exp”这类情况，本质上是新模型或视觉能力被封装成插件后，当前 DSH 版本还不认识该能力描述。解决思路是检查插件支持的模型标识与运行时模型标识是否一致；若插件是第三方适配，核心框架升级后，旧插件的 manifest 可能需要同步更新。

最保守的方式是：在 DSH 中先使用该插件官方推荐的模型组合确认可运行，再逐步切换。不要因为插件名字里带“Vision”就认为当前模型一定具备视觉理解能力，这往往需要多模态模型同时配合加载。

6.4 pnpm dsh web 卡住的定位思路

如果你是在源码仓库中启动 Web 端，遇到“卡住”可参考以下排查过程：

• 先确认是否经历过完整构建。很多情况下，直接执行pnpm dsh web并不会自动构建前端资源。
• 再检查端口。可能端口被其他进程占用，DSH 在等待端口释放但没有明显日志。
• 最后观察网络请求。Web 服务启动时若尝试访问远端插件市场或模型服务，网络不通时启动线程会长时间等待。

分步执行一般能更快定位：

pnpm build:web pnpm dsh web --port 5173 --host 127.0.0.1

如果仍然卡住，开启调试日志：

DEBUG=dsh:* pnpm dsh web --port 5173

日志会明确打印阻塞在哪一步。

7. 最佳实践与工程建议

7.1 插件命名与目录规范

团队内使用 DSH 插件时，最好提前约定一套命名规范。插件名建议采用厂商-领域-功能结构，例如myteam-pdf-reader、myteam-git-review。避免只叫reader或helper这种含糊名称，一旦插件数量增加，很难一眼判断功能。

插件目录内至少应包含：

plugin.json entry.js README.md

plugin.json建议字段如下，不同版本字段名可能不同：

{ "name": "myteam-pdf-reader", "version": "0.1.0", "description": "Read local PDF files into plain text", "entry": "entry.js", "capabilities": ["document:pdf:read"] }

描述字段写得越清楚，调度器和人越容易识别它的用途。

7.2 插件源可信度管理

安装插件前，建议先确认插件来源。官方市场或团队私有源相对可靠；一些个人整理的awesome-dsh-plugin清单可以作为发现插件的入口，但清单本身并不对插件内容负责。

在引入一个第三方插件的完整流程应当是：

1. 查看插件仓库的 star、issue、最近提交时间。
2. 阅读入口文件和依赖清单，特别关注是否包含网络请求、命令执行等高风险权限。
3. 在测试环境安装并观察日志。
4. 确认没有异常后，再把它纳入生产 profile。

7.3 密钥与最小权限原则

DSH 核心框架越强，插件权限越要克制。插件一旦拥有访问模型的 API Key，或者能读文件、执行命令，它实际上就获得了和当前用户相似的能力。必须将插件权限按最小范围授予。

推荐做法是：在配置中为不同插件分配独立 token 或密钥，不要全部使用同一个管理员 Key。例如 PDF 插件只需要文件读取权限，那就不应允许它访问外网。

7.4 日志与错误定位

插件排错严重依赖日志。日志分级建议如下：

• ERROR：插件加载失败、权限校验失败、外部 API 调用失败。
• WARN：插件依赖缺失但未阻断启动、插件使用已废弃 API。
• INFO：插件安装、卸载、更新时间，以及关键任务执行流程。
• DEBUG：具体参数、调用堆栈、HTTP 请求详情。

一个很实用的排查技巧是：在插件安装之前先记录一份干净的dsh plugin list，出问题后对比插件树，能快速看到新增节点的影响范围。

7.5 性能与依赖清理

插件数量增多后要注意两条性能陷阱：

• 插件在启动时初始化，如果每个插件都建立网络连接、加载大语言模型 tokenizer，启动时间会线性增长。
• 同类型插件共存时，可能重复安装相同依赖，造成磁盘空间浪费和版本冲突。

定期执行依赖清理是必要的。尤其当你从旧版本升级 DSH 后，旧插件缓存可能无法兼容，继续保留只会干扰插件树加载。清理前先备份清单，然后卸载不再需要的插件。

8. 从使用到二次开发：如何动手写一个 DSH 插件

如果你已经熟练安装和管理 DSH 插件，下一步可以尝试自己编写一个最小插件。这里以一个假想的本地插件目录为例，结合前面提到的最小 manifest 结构，解释开发流程。

环境里准备三个文件：

my-first-plugin/ ├── plugin.json ├── entry.js └── README.md

plugin.json描述插件基本信息；entry.js负责把能力注册到 DSH 执行上下文。因为不同 DSH 版本插件 SDK 接口差异较大，这里给出的是思路，不是保证可运行的模板。

// 文件路径：my-first-plugin/entry.js // 该文件的具体导出方式以 DSH 插件的开发文档为准 export async function register(ctx) { ctx.registerCapability("demo:hello", async (payload) => { const name = payload.name || "DSH"; return { message: `Hello, ${name}` }; }); }

如果在开发插件时，遇到“先跑通最小功能”的问题，我建议先不要直接对接 LLM，而是能把一个简单 meta 工具注册上去并调用成功，再逐步丰富能力。

再进一步设计插件结构时，注意区分“数据加载”“Agent Worker”“界面扩展”三类插件。这样在 DSH 跨平台、跨模型演进时，核心框架升级不会导致你的插件全面失效。开发者应该围绕通用协议做适配，而不是绑定某一个模型的内部实现。

为了让插件在 DSH 启动时被扫描到，根据你的环境把目录放到 DSH 插件的扫描路径，或者用插件安装命令进行本地安装：

dsh plugin install ./my-first-plugin

安装后执行：

dsh plugin list

看到my-first-plugin出现在列表中，就说明本地开发到运行验证的最小闭环已经建立。接下来可以做的优化包括：给插件补充单元测试、增加日志记录、加入超时与重试，还有一个很重要的点——为插件编写文档。DSH 插件生态现在还处于快速成长期，很多插件功能相似但质量参差，文档能直接影响别人是否愿意使用。这也是社区贡献者最值得投入的地方。

如果你在真实项目中想用 DSH 构建一套可持续进化的 Agent 系统，我的建议是先控制插件数量，把核心场景跑稳，再逐步引入新能力。一切皆插件，是让系统保持可演进的好思想；但真正让系统稳定运转的，还是清晰的能力边界、可信的插件源和规范的管理流程。

希望这篇 DSH 插件实战能帮你少踩一些坑。使用过程中如果遇到 DSH 版本差异或新报错，欢迎在评论区交流。