READMESource: main@18f82e87
dsh 插件开发指南
写给想给 DeepSeek Harness(dsh)写插件的人:从最小可运行插件,到带前端面板、本地引擎和发布流程的完整插件。
适用版本:dsh
0.2.2-rc.1(2026-11)。插件 API 仍在演进,升级 dsh 后请先对照官方文档。
这本指南解决什么
- 插件由哪些文件组成,dsh 怎么加载它;
- host 工具、client 槽位、构建产物三者的硬约束;
- 本地怎么装、为什么“装了不生效”、怎么排查;
- 带本地进程/持久化/后台任务时怎么做才不坑;
- 怎么测试、怎么发布、怎么兼容不同 dsh 版本。
不包含:dsh 本体开发、UI 设计规范、模型能力调优。
阅读路径
| 你的目标 | 读这些 |
|---|---|
| 先跑起来一个插件 | 00 快速开始 → 01 概念地图 |
| 写工具 / 接服务 | 02 插件解剖 → 03 Host 工具 |
| 加侧边栏或面板 | 04 Client 槽位 |
| 打包、安装、调试 | 05 构建产物 → 06 安装调试与升级 |
| 接本地引擎 / 存数据 | 08 引擎、持久化与后台任务 |
| 发版上架 | 07 发布与 Hub |
| 出问题了 | 12 版本兼容与踩坑 |
目录
| 文档 | 内容 |
|---|---|
| 00 快速开始 | 20 分钟做出一个可安装的最小插件 |
| 01 概念地图与术语 | profile / bundle / host / client / Cordis 的关系 |
| 02 插件解剖与加载 | package.json 字段、cordis patch、入口解析 |
| 03 Host 工具与生命周期 | 工具注册、依赖注入、清理、并发 |
| 04 Client 槽位与 bundle | 侧边栏/主区面板、loader 合约、数据通道 |
| 05 构建产物与自检 | esbuild 两套参数、产物检查 |
| 06 安装调试与升级 | link/tgz、重启、卸载、回滚 |
| 07 发布与 Hub | 打包验收、元数据、发布检查 |
| 08 引擎、持久化与后台任务 | 本地进程、定时任务、原子写 |
| 09 测试策略 | 单测、桩宿主、bundle 合同、验收 |
| 10 国际化与发现性 | locale、关键词、Hub 展示 |
| 11 安全与权限 | 写操作确认、路径校验、密钥、路由 |
| 12 版本兼容与踩坑 | 兼容声明 + 常见失败模式 |
最小模板
scaffold/ 是一个可直接复制的插件模板:一个 host 工具 + 一个主区面板。
cp -R scaffold my-plugin
cd my-plugin && npm install && npm run build
dsh plugin --profile web add "link:$PWD"
# 重启 dsh
模板里的代码在 00 快速开始 有逐段解释。
反馈与贡献
- 文档写错或跑不通:用 Issue 模板「文档问题」,注明章节与 dsh 版本;
- 缺少某类经验:用 Issue 模板「内容建议」;
- 提交前请阅读 CONTRIBUTING.md:只收录去标识化的通用内容,不含具体产品、私有仓库或个人信息;
- 新增文档要同步更新上面的目录表。
许可
文档采用 CC BY 4.0;scaffold/ 与文中的代码片段采用 MIT。
No comments yet. Be the first to write one.