bigstyle777/dshp

dshp — DeepSeek Harness 插件工具链

一条命令创建、验证、发布 DeepSeek Harness 插件——平台已知的坑全部提前填好。

从零写一个 DSH 插件，要懂 Cordis 生命周期、bundle/profile 清单体系、patch 层组合，还要——我们在开发本工具时实测踩过——避开若干未写进文档的 Windows 与 npm tag 陷阱。dshp 把这一切编码进一条命令：

npx dshp-cli create my-plugin
cd my-plugin
npx dshp verify        # ✓ 免 boot、无需 API key

为什么需要 dshp？

| 痛点（实测踩过） | dshp 的解法 |
|---|---|
| @deepseek-ai/dsh-tools 的 latest tag 陈旧（0.0.1-rc.1 vs 0.1.0-rc.7），两代家族 peer 互不兼容 | 按模板整组锁定依赖 family（dsh-*、cordis、schemastery）；upgrade 整组原子迁移 |
| Windows：patch 里写裸 C:/... 路径，loader 崩溃 ERR_UNSUPPORTED_ESM_URL_SCHEME | 所有开发 overlay 自动生成 file:/// URL（空格自动编码） |
| Windows：dsh plugin add  被 shell 拆散，pnpm 去装 "SOLO" | 源码模式直接 spawn node（无 shell），引号交给 Node；shell 模式主动拒绝并给出修复指引 |
| pnpm ≥10 拦截 esbuild 安装脚本 → 全新环境 pnpm install 直接失败 | 模板自带 settings-only 的 pnpm-workspace.yaml 白名单 |
| 不 boot 整个应用（还要 API key）就没法验证插件「能否被加载」 | verify 通过 dsh --dump-config 组合真实 profile 并断言插件行存在——秒级、零密钥 |

命令

| 命令 | 作用 |
|---|---|
| dshp create  | 生成插件项目：tool/service 模板、bundle 清单、cordis.patch.yml、开发 overlay、tsconfig、pnpm 设置、README |
| dshp dev | 以开发 overlay 启动 dsh web——TS 源直跑，改动经 HMR 热替换 |
| dshp verify | 两层验证：结构检查（L1）+ --dump-config 真实组合断言（L2）；--dev 验证源码直跑形态 |
| dshp upgrade | 依 npm 实时 dist-tags 整组升级依赖 family；--check 供 CI 使用 |
| dshp versions | 内置 family 与 npm 实时 dist-tags 对比 |

dshp create my-plugin --template tool --tag next
dshp dev                     # http://127.0.0.1:3080 插件已生效
dshp dev -- headless         # 无 UI 运行
dshp verify                  # pnpm build 后（bundle 形态）
dshp verify --dev            # 源码形态，构建前
dshp upgrade --check         # CI：有更新时退出码 1

dsh 探测顺序

1. DSHP_DSH_BIN — 完整自定义命令，如 node --import tsx/esm /apps/cli/src/bin.ts
2. DSHP_DSH_ROOT — deepseek-harness 源码根（源码直跑，无需构建）
3. dshp 同级的 deepseek-harness/ 目录
4. PATH 上的全局 dsh

发布插件

模板默认预构建 npm 路线——用户装到的是编译产物，永远不碰构建脚本白名单：

pnpm build && npm publish

用户侧安装进任意 profile：

dsh plugin --profile my add your-plugin
dsh --profile my --dump-config   # 看到层落地

环境要求

- Node.js ≥ 20（DSH 本体要求 ≥ 22.19）
- pnpm ≥ 10
- 一个 dsh（源码或 npm 版）

路线图

- [ ] dshp test — 带 mock 工具注册表的插件级测试运行器
- [ ] 多文件插件模板（tool + UI 卡片）
- [ ] 向 deepseek-harness 上游提 Windows 修复 PR（记录于 docs/windows-bugs.md）

许可

MIT