dsh plugin design

面向 DeepSeek Harness（dsh）第三方插件生态的 Plugin Design / Migration / Compliance Agent：发现第三方插件、检查其源码与配置、对照 DH-TP-SDK 工程化规范做静态分析、生成 design.md，经用户确认后对插件逐项修改并支持备份与回滚。

DH-TP-SDK 是工程化规范，Bronze/Silver/Gold、P0–P4、S0–S4 均非 DeepSeek 官方认证。

解决痛点

• dsh用户开发/部署各类插件时，经常遇到兼容问题、引发系统性报错。
• 问题根源于各类插件可能未遵循dsh的开发规范、以及各类插件并不能完全做到“随用随丢”的独立插件理念。
• 本插件针对开发/部署插件提供设计规范.md（design.md），并进行技术规范改造。（本人的dsh plugin design、dsh plugin manager、dsh ui skin都经过本插件开发验证）

使用方法（聊天框入口）

• 使用dsh plugin design插件，输出对 <插件名> 插件进行规范修改的design.md文件，然后询问我意见后进行规范修改

• 可参考目录中的How‑to Showcase.png。(design.md未在此处展示)

  

两阶段工作流：

• 阶段 1（只读分析）：discover → inspect → analyze → design（生成 design.md），此阶段绝不修改源码。
• 阶段 2（你确认后才修改）：approve（门控）→ backup（备份）→ apply（逐项原子替换）→ rollback / report。

安全边界：分析先于修改、设计先于执行；未确认前不修改；修改前备份、失败可回滚；不修改 Core、不用 private API。

目录结构

dsh-plugin-design/
├── install.ps1 / install.sh   # 一键安装（node_modules 链接 + cordis.patch.yml insert）
├── package.json               # npm 包：exports + dsh.client + dsh.bundle + scripts.test
├── dsh.plugin.yaml            # DH-TP-SDK manifest
├── cordis.patch.yml           # 挂载参考：host composition insert row
├── README.md / design.md / LICENSE / .gitignore
├── DeepSeek-Harness-Third-Party-Plugin-SDK-Specification.md   # DH-TP-SDK 规范依据（内置）
├── deepseek-harness-product-technical-framework.md            # Harness 架构依据（内置）
├── lib/client.js              # Client 半体：factory-form bundle（Settings 设置页）
├── src/
│   ├── index.js               # 入口 → host.js
│   ├── host.js                # Host 半体：10 个 dshpd_* 工具
│   └── client.js              # Client 源码（构建产物见 lib/client.js）
└── tests/
    ├── README.md              # 测试矩阵
    └── manifest.test.mjs      # DH-TP-SDK 规范冒烟测试（node --test）

能力

• Host 半体：10 个模型工具 —— dshpd_discover / dshpd_inspect / dshpd_analyze / dshpd_design / dshpd_approve / dshpd_backup / dshpd_apply / dshpd_rollback / dshpd_status / dshpd_report。
• Client 半体：Settings 设置页（「设置 → dsh plugin design」），展示使用方法、两阶段工作流、工具清单与安全边界。

兼容性（Harness 版本）

• 本插件对齐 @deepseek-ai/dsh 0.1.1-rc.2（manifest runtime.harness.min 与 package.json dsh.compatibility.harness 均为 >=0.1.1-rc.2）。
• Settings 入口当前走 settings.section（整页说明页）。Harness 自 0.1.0-rc.7 起另提供「插件配置卡片」档位（settings.plugin.item + Host installSettingsSection + Client ctx.settingsScope），用于暴露可持久化配置（默认扫描根/安全等级）；本插件尚未迁移到该档位（纯说明页无需持久化配置）。
• DH-TP-SDK 的 Bronze/Silver/Gold、P0–P4、S0–S4 为工程化规范等级，非 DeepSeek 官方认证。

安装（一条命令）

本插件是 npm 包 + host composition row 形态：工具全局注册 + Settings UI 全局加载，重启后自动加载。

下载后，在插件目录内运行对应脚本，即可自动完成「链接进 node_modules + 写入 cordis.patch.yml」两步：

Windows（PowerShell）

git clone <你的仓库> dsh-plugin-design
cd dsh-plugin-design
powershell -ExecutionPolicy Bypass -File install.ps1

Linux / macOS（bash）

git clone <你的仓库> dsh-plugin-design
cd dsh-plugin-design
bash install.sh

脚本是幂等的（重复运行无害）。装完后重启 dsh（Ctrl+C 后重新 npx dsh web / dsh web），即完整可用：

• 聊天框拥有 10 个 dshpd_* 工具；
• 「设置 → dsh plugin design」出现设置页（选文件夹扫描第三方插件）。

脚本做了什么（手动安装等价步骤）

1. 把本目录链接进 node_modules：

   $DSH_HOME/profiles/node_modules/dsh-plugin-design  ->  本目录

   （$DSH_HOME 默认 ~/.dsh；Windows 用 junction，Linux/macOS 用 symlink。或发布到 npm 后 npm install dsh-plugin-design 亦可。）

2. 在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 追加：

   - insert:
       - id: dsh-plugin-design
         name: 'dsh-plugin-design'

   （profile 默认 web，可用环境变量 DSH_PROFILE 覆盖。）

提示：Host 半体（工具）改 cordis.patch.yml 后热生效；Client 半体（Settings UI）在 boot 时由 dsh-client-modules 扫描加载，需重启后刷新页面。

为什么 Host 与 Client 挂载位置不同

• Host 半体（工具）既可在 agent preset（per-session）也可在 host composition（全局）。
• Client 半体（Settings UI）必须 host composition：dsh-client-modules 只扫描 host Loader entries，且 client UI 是 boot 时加载的全局 UI，agent preset 的 client 不会被加载。因此本包统一挂到 host composition（工具全局 + UI 全局）。

给插件作者的命名约定（避免冲突）

每个第三方插件都挂到同一份 cordis.patch.yml / node_modules，必须保证以下全局唯一，否则会相互覆盖或注册报错：

install.ps1 / install.sh 是各自仓库根目录的普通文件，用户在各自的 clone 目录里执行，不会互相冲突；只要坚持「一个插件一个唯一前缀」，多插件共存安全。

安全边界

• Security Level S2 / Permission Level P2：需读写目标插件的 workspace 文件（发现/检查/备份/修改/回滚）。
• 网络/子进程/shell/密钥默认全部关闭（network.outbound: false、subprocess.enabled: false、shell.enabled: false、credentials.access: false）。
• 不修改 Core、不用 private API、不改 globalThis/原型；两阶段门控 + 备份回滚保证「分析先于修改、确认后才改、失败可回滚」。
• Host 半体仅在「用户确认后」才经 dshpd_backup/dshpd_apply 写文件；静态分析为启发式，非权威认证。

规范合规测试

本插件自身遵循 DH-TP-SDK 规范，并提供静态冒烟测试：

npm test            # 等价于 node --test（自动发现 tests/ 下的 .test.mjs）

覆盖：manifest 必填字段、最小权限（网络/子进程/shell/密钥关闭）、package.json 三处导出、cordis.patch.yml 仅 insert 不替换 Core row、源码无高危模式。详见 tests/README.md。

已知限制

1. manifest 解析为「缩进感知」的启发式解析（支持嵌套点路径、兼容 CRLF），但仍非完整 YAML 解析（无 anchor/折叠标量/flow map）。
2. 静态分析为启发式规则，非权威认证；WATERFALL_NEXT 仅对「确实注册了 waterfall 监听」的非测试源码生效。
3. 任务状态（approval/backup/journal）为进程内内存态，进程重启即失。
4. git 状态/测试运行依赖 Agent 侧 shell 工具，插件自身不直接跑 shell。