插件开发工具箱 eighteentang/dsh-plugin-dev-tools

DSH 开发工具箱

给 DSH（DeepSeek Harness） 插件开发者的一小组工具，外加一份随插件分发的开发经验库。

装一次，之后你自己开关里面的每个小工具。

它解决什么问题

开发 DSH 插件时会遇到很多文档里没写、只能踩出来的坑，比如：

- 复制到剪贴板为什么静默失败
- 为什么改了插件代码、重启插件却没生效（其实是必须重启客户端）
- 为什么自己建的 agent 收到消息却永远不执行
- 为什么悬浮框会疯狂闪烁

每个人各踩一遍、各花几小时，是纯浪费。

所以这个插件做三件事：

1. 界面定位 —— 按 Alt 悬浮任意界面元素，显示它的名字与完整路径，一键复制
2. 开发经验库 —— 23 条实测踩出来的坑，装插件就自动获得；而且索引会注入到 AI 助手的提示词里，让它也少犯同样的错
3. 两道关卡注入到 AI 的工作流里 ——动手前的强制自检（先查官方文档 / 查框架实现 / 找现成写法），开工前的需求对齐（四要素确认 → 规划 → 再确认才动手）

安装

前置

- 已安装 DSH 桌面客户端
- 会把插件装进你的 DSH profile

步骤（推荐：从 GitHub 直接装，一行地址）

1. 打开 DSH → 侧边栏 插件 页面 → Add plugin
2. 填入：

github:eighteentang/dsh-plugin-dev-tools

3. 确认插件列表里出现 dsh-plugin-dev-tools 且为启用状态
4. 重启一次客户端（DSH 按文件路径缓存已加载的模块，必须重启才加载新代码）

不需要构建授权。 这个插件是纯 JavaScript，没有 build/prepare 脚本，所以 pnpm 没有脚本要跑，也就不会要求你在 pnpm-workspace.yaml 里加 allowBuilds。
（带 TypeScript 构建的插件才需要那一步。）

备选：本地路径安装

想改代码、或者网络不通时用这个：

1. 下载本仓库（Code → Download ZIP，或 git clone）
2. 把 dev-tools 这个文件夹放到一个长期保留的位置（路径里不要有中文和空格，例如 D:\dsh-plugins\dev-tools）
3. 插件页 → Add plugin → 填那个文件夹的绝对路径，例如 D:\dsh-plugins\dev-tools
4. 同样需要重启一次客户端

⚠️ 用本地路径装时，DSH 会把它记成 link: 形式 —— 这种方式不会安装该包的依赖。
本插件零依赖，所以没影响；但如果你在改它、并加了依赖，记得手动补。

确认装好了

打开 设置 → 开发工具，应该看到一个总开关和几个小工具。

用法

界面定位（Alt + 悬浮）

1. 把鼠标放到想定位的界面元素上，按一下 Alt
2. 浮框出现在光标旁，显示它属于哪个区域、完整 CSS 路径、尺寸
3. 浮框不会跟着鼠标走 —— 你可以从容地把鼠标移到「复制」按钮上
4. 也可以按 Ctrl+Alt+C 直接复制，不用瞄准按钮
5. 点浮框外面收起；再按 Alt 重新定位

复制出来的内容长这样，可以直接贴给 AI 助手或同事：

【界面定位】侧边栏底部动作区 slot: sidebar.footer.action 元素: div.dvt-controls 路径: body > div.app > div.sidebar > div.dvt-controls 尺寸: 120×26 top=720 left=12 说明: 💀 结束进程按钮渲染在这里

看到「（未收录的元素）」说明那个位置还没登记过名字 ——把复制到的路径发给我们，就能给它起个名字，以后大家都用那个叫法。

结束进程按钮（💀）

侧边栏底部的一个 💀 按钮：结束 DSH 宿主进程。

点它 → 确认 → DSH 弹出恢复框 → 在那里选「重启」（干净的自动重启，约 7 秒）或「退出」。

那个框不是报错，是正常流程 —— DSH 外壳把"宿主进程终止"一律当异常处理，所以任何结束宿主的操作都会经过它。

为什么不做成"直接重启"按钮：DSH 没有对外的重启接口。
它的重启原语是 app.relaunch() + quitWithoutConfirmation()，写在 lib/main.js 的崩溃恢复对象里，只被 fail() 调用，没有任何 IPC 暴露（42 个 preload 通道里没有 restart / quit / shutdown）。
自己 kill 进程再拉起要慢 9 倍（实测 64 秒 vs 7 秒），所以不如把选择交给官方那个框。

开发模式总开关

打开后三件事生效：

1. 注入"动手前的强制自检清单" —— AI 每次动手前要先查官方文档、查框架实现、找现成写法可抄；并且明确"搜不到不等于不存在"
2. 注入"开工前定需求"流程 —— 用户提出"我想做一个 XX"时，先对齐四要素（名字 / 用途 / 使用场景 / 工作空间），确认后才规划，规划再确认才动手
3. 注册 record_experience 工具 —— AI 踩到新坑时可以直接记进经验库

关掉后这些立即撤下（不是隐藏，是真正注销），注入的内容变成 0 字符。

注入的体量：开着时约 5.5 KB/次（自检清单 + 工作流约 1.8 KB，经验索引约 3.7 KB）。
经验库全文（约 17 KB）不进上下文，AI 需要细节时自己去读。

开发经验库

这是本插件最有价值的部分。

它在 experience/经验库.md，随插件分发 ——你装插件就自动获得。而且它的索引会被注入到 AI 助手的提示词里，所以 AI 也会知道"有这些坑存在"，而不是重新踩一遍。

当前版本

打开 设置 → 开发工具，页面里会显示：

开发经验库 [⟳ 刷新]
版本 2026-09-26 条数 23 条更新于 2026-09-26 指纹 b941c37b 那个 ⟳ 是「刷新」按钮（重新读取经验库），不是重启按钮。
它存在的意义：你替换掉经验库文件后，不用重启客户端就能看到新数字。

想要新版怎么办

1. 到本仓库看 experience/经验库.md 有没有更新
2. 有就下载、直接替换掉插件文件夹里的那一份
3. 回到设置页点「⟳ 刷新」—— 不用重启客户端

怎么判断“是不是有更新”：比对设置页显示的条数与指纹。
只看日期不够 —— 有人可能只是修正了一条旧经验（条数没变，但内容变了）。

怎么贡献一条经验

踩到新坑后：

1. 在 experience/经验库.md 末尾追加一条（格式照抄现有的）
2. 更新文件顶部注释里的 entries（条数）、updatedAt（日期）、fingerprint（指纹）
3. 提 PR

格式（固定格式是为了能被脚本解析并注入提示词）：

E15 · 一句话标题（写症状，不要写“要注意 XX”）

- 范围：通用 | 项目特定 —— 可选，缺省为“通用”
- 症状：你会看到什么现象
- 解法：该怎么做
- 细节：可选补充（为什么、怎么查、实测案例）

写作标准：

| 要 | 不要 |
| 写具体症状（“点复制按钮没反应，粘贴是空的”） | 写原则（“要注意剪贴板权限”） |
| 写可执行的解法（给命令、给函数名） | 写方向（“建议参考框架实现”） |
| 一条一个坑 | 一条混好几个问题 |

原则 AI 本来就知道，具体症状才能让它对上号。

标注 范围：项目特定 的条目不会被注入到别人的提示词里 ——它们只留在文件里作范例（讲的是某个具体产品的架构取舍，对别人没参考价值）。

目录结构

dev-tools/
├─ package.json 插件清单（声明“我是插件”、入口、浏览器半） ├─ cordis.patch.yml 加载器行声明 ├─ index.js 宿主半（跑在 DSH 主进程里） ├─ client.js 客户端半（跑在页面里，必须单文件、零 import） ├─ app-control.js 结束进程接口 + 经验库查询 + 诊断接口 ├─ dev-rule.js 提示词注入（自检清单）+ 开发模式状态 ├─ workflow.js “开工前定需求”那段注入文本 ├─ experience.js 经验库解析、索引生成、追加条目 ├─ experience-tool.js record_experience 工具 └─ experience/ ├─ 经验库.md ← 23 条实测踩坑（随插件分发） └─ README.md 经验库的使用与贡献说明

已知限制与设计取舍

- 结束进程会弹一次恢复框：DSH 桌面外壳把“宿主进程被终止”一律当异常。
插件侧无法消除（框架没有对外的重启接口）。所以这里索性不做“重启按钮”，只做“结束进程”，把重启/退出交给那个框选
- 经验库的项目特定条目不进提示词：这是有意的（避免占别人的 context）
- 经验索引里的“解法”只截 60 字（“症状”给 100 字）：症状用来“对上号”，解法只用来判断值不值得去读全文。这样索引从 4.4 KB 降到 3.7 KB
- Config 无法被内省：因为外部插件 import 不到 asar 内部的 @deepseek-ai/schemastery，只能手写 Standard Schema，于是 Config.listConfigs 显示 status: "unsupported"。功能不受影响
- 本地路径安装是 link: 形式，不会安装依赖：本插件零依赖所以没影响

关于“为什么有些做法看起来奇怪”

源码里那些注释不是装饰。它们记录了实测踩出来的坑，比如：

- 为什么 ctx.inject(deps, cb) 不能用 ctx.get(deps) 代替
- 为什么 tools.register 的 parameters 必须是 JSON Schema 而不是简写
- 为什么开关状态放内存而不是文件
- 为什么 useEffect 的依赖数组里不能放它自己 setState 的 state
- 为什么 single 槽位可以用更低的 priority 遮蔽 shipped 的注册
- 为什么 CSS 注释里不能出现反引号、也不能让 markdown 加粗紧贴路径（前者截断模板字符串，后者凑出 */ 提前结束注释 —— 都实测踩过）

改代码前读一下注释，能省下你重新踩一遍的时间。
更详细的事故记录在 experience/经验库.md，23 条，每条都是踩出来的。

许可证

MIT