前言¶

DeepSeek Harness（DSH）采用「一切皆插件」的架构。开发一个新工具插件通常需要处理配置、Schema 定义、打包发布等繁琐流程。dsh-plugin-template 提供了一个最小可用骨架，包含纯 ESM 架构、零依赖配置以及脚手架脚本，帮助开发者快速起步。

插件简介¶

本仓库是 DSH 插件的模板代码，用于创建新的 npm bundle 插件。
- 名称：dsh-plugin-template
- 维护者：ZhijiangTang
- 分类：客户端
- 许可证：MIT
- 核心价值：脚手架一个新工具插件的最小可用骨架。

核心特性¶

• 纯 ESM 架构，无需 Babel/TypeScript 编译步骤。
• 零依赖，直接使用 peerDependencies 中的核心库。
• 包含 hello_world 占位工具，展示参数定义、输出 schema、渲染和执行逻辑。
• mount 自检机制走真实的 ctx.tools.execute 管道。
• 提供内置 scaffold.sh 脚手架脚本。

使用步骤¶

先做 X，再做 Y。以下以创建新包名 dsh-mytool 为例。

1. 初始化项目¶

使用模板仓库自带的脚手架脚本生成骨架。

bash scripts/scaffold.sh dsh-mytool

2. 修改配置文件¶

生成后需手动调整核心配置：

• package.json：
• 删除 private: true 字段（否则无法发布 npm）。
• 修改 name 为你的 npm 包名。
• 修改 keywords，例如 ["dsh-plugin", "dsh-mytool"]。
• cordis.patch.yml：
• 修改 id：插件的稳定身份，每次启动重新挂载。
• 修改 name：按 npm 包名引用代码。
• index.js：
• 修改插件名 export const name。
• 修改工具名 name: 'hello_world'。
• 根据需求重写参数定义、输出 schema 和执行逻辑。

3. 本地验证¶

本模板本身不是可安装插件（private: true），需先发布或通过 file: 协议本地加载。

# 安装本地插件（必须使用 file: 协议）
dsh plugin --profile px-tdemo add file:./plugins/dsh-mytool

# 启动并观察自检日志
dsh --profile px-tdemo --port 0 2>&1 | grep -m1 'self-test ok'

4. 发布¶

配置无误后，发布到 npm。

cd plugins/dsh-mytool
pnpm publish

常见注意点¶

• 本地安装协议：本地测试必须使用 file:./目录 协议，./目录 会被解析为符号链接导致找不到模块。
• Schema DSL 限制：output.schema 不接受顶层 required 数组，必须使用属性级 required: true。
• pnpm 24h 门控：新版本发布不满 24h，pnpm add 可能解析到旧版，建议显式指定版本号。
• 原生依赖处理：若插件包含原生依赖（如 node-pty），需在 profile 的 pnpm-workspace.yaml 中配置 allowBuilds。插件尽量保持零原生依赖。
• 非发布仓库：本仓库本身设置了 private: true，不发布 npm，仅作为模板使用。

总结¶

dsh-plugin-template 是一个轻量级的开发脚手架，适合需要快速搭建 DSH 插件的开发者。它通过零依赖、无构建步骤的纯 ESM 设计，降低了开发门槛。
- GitHub：https://github.com/ZhijiangTang/dsh-plugin-template
- 目录页：https://www.skillhub.cn/plugins/ZhijiangTang/dsh-plugin-template