前言¶
给 DeepSeek Harness（DSH） 写插件时，很多问题不会写在官方文档里：剪贴板复制静默失败、改了代码重启插件却不生效（实际要重启客户端）、自建 agent 收消息却不执行、悬浮框闪烁等。每个人各自踩一遍、各自花几小时，成本重复。
dsh-plugin-dev-tools（维护者 eighteentang）是面向 DSH 插件开发者的一小组客户端工具，并随插件分发一份开发经验库。装一次后，在 设置 → 开发工具 里按需开关各子功能。当前版本 1.5.1，许可证 MIT。社区目录页：SkillHub 插件页；源码：GitHub。
这是什么¶
一句话：界面元素定位（Alt + 悬浮）、随插件分发的踩坑经验库、开发模式下向 AI 工作流注入自检与需求对齐流程。
插件分类为客户端；纯 JavaScript，无 build/prepare 脚本，从 GitHub 安装时不需要构建授权（不必在 pnpm-workspace.yaml 里配置 allowBuilds）。
核心功能¶
界面定位（Alt + 悬浮）¶
- 鼠标移到目标 UI 上，按一下 Alt。
- 光标旁出现浮框：区域归属、完整 CSS 路径、尺寸等。
- 浮框不跟随鼠标，便于点「复制」；也可用
Ctrl+Alt+C直接复制。 - 点浮框外收起；再按 Alt 重新定位。
复制结果可直接贴给 AI 或同事，格式示例：
【界面定位】侧边栏底部动作区
slot: sidebar.footer.action
元素: div.dvt-controls
路径: body > div.app > div.sidebar > div.dvt-controls
尺寸: 120×26 top=720 left=12
说明: 💀 结束进程按钮渲染在这里
若显示「（未收录的元素）」，表示该位置尚未在插件内登记名称；把路径反馈给维护者即可补充。
开发经验库¶
经验全文在仓库 experience/经验库.md，随插件安装。README 写明当前 77 条实测条目；设置页会显示版本、条数、更新日期与指纹（资料示例：版本 2026-10-13，指纹 78594924）。
- 索引会注入 AI 助手提示词（开发模式总开关打开时），让模型知道「有哪些坑」，而不是全文进上下文（全文约 10.3 万字符；索引按固定预算装配，开着开发模式时注入体量约 6.6 千字符/次）。
- 更新经验库文件后，在设置页点 ⟳ 刷新 即可，不必重启客户端；是否真有更新应比对条数与指纹，不能只看日期。
- 开发模式开启时会注册
record_experience工具，便于 AI 把新坑记入经验库。
贡献格式与解析规则见 README；标注「项目特定」的条目不会注入到他人提示词。
开发模式总开关¶
打开后：
- 动手前强制自检 —— 查官方文档、查框架实现、找现成写法；明确「搜不到不等于不存在」。
- 开工前定需求 —— 用户说「想做 XX」时，先对齐四要素（名字 / 用途 / 使用场景 / 工作空间），确认后再规划，规划再确认才动手。
- 注册
record_experience与经验索引注入。
关闭后上述注入与工具真正注销（非仅隐藏），注入字符数为 0。
结束进程按钮（💀）¶
侧边栏底部 💀：结束 DSH 宿主进程。确认后会出现 DSH 恢复框（框架把宿主终止一律当异常，属正常流程），可在框内选「重启」（README 称约 7 秒）或「退出」。插件未提供「一键重启」，因 DSH 当前无对外重启 IPC；自行 kill 再拉起 README 实测慢得多。
开发诊断¶
在右侧边栏引导页选择「开发诊断」tab（需先选一次才会固定出现）。用于回答「改完代码为什么没生效」：结论条、环境（link/复制安装、路径、热重载是否监听源码）、关键文件内容哈希比对（! 需重启 / ~ 已生效 / · 一致）、进程内服务清单、经验库一致性、宿主最近日志等。宿主插件 console.log 桌面端不落盘；插件将日志写入 ~/.dsh/dev-tools.log（512 KB 上限）。只读自检 JSON：GET http://127.0.0.1:8800/dev-tools/self-check。
README 说明：改 .js 源码需重启客户端（ESM 缓存）；改 experience/经验库.md 等运行期读盘文件不必重启；profile 配置/patch 通常不必重启（HMR 监听配置）。@deepseek-ai/dsh-base 的 patch 将 HMR config.root 设为 []，默认不监听插件源码，以 base 为准。
安装与启用¶
前置¶
- 已安装 DSH 桌面客户端。
- 插件会装进当前 DSH profile。
从 GitHub 安装（推荐）¶
- 打开 DSH → 侧边栏 插件 → Add plugin。
- 填入：
github:eighteentang/dsh-plugin-dev-tools
- 确认列表中出现 dsh-plugin-dev-tools 且为启用。
- 重启一次客户端（DSH 按路径缓存已加载模块，新代码需重启才加载）。
本地路径安装（备选）¶
下载仓库，将 dev-tools 文件夹放到无中文、无空格的长期路径，Add plugin 时填该文件夹绝对路径。同样需重启客户端。本地路径为 link: 形式时不会安装依赖；本插件零依赖，一般无影响。
确认¶
打开 设置 → 开发工具，应看到总开关与各小工具；经验库元数据与 ⟳ 刷新按钮也在此页。
典型用法小结¶
| 场景 | 操作 |
|---|---|
| 问 AI「这个按钮在哪个 slot」 | Alt 定位 → 复制路径与 slot |
| 让 AI 少踩文档外的坑 | 打开开发模式总开关，利用经验索引与自检注入 |
| 用户提新需求 | 依赖注入的「四要素 → 规划 → 再确认」流程 |
改插件 .js 不生效 |
开发诊断 tab 看文件哈希与服务；必要时重启客户端 |
| 只更新经验库 markdown | 替换文件 → 设置页 ⟳ 刷新 |
适用场景与注意¶
适合谁：正在开发或维护 DSH 插件、需要定位客户端 UI、希望把踩坑经验沉淀并共享给助手上下文的人。
权限与安全：插件在当前 DSH 进程权限下运行，可结束宿主进程、写 ~/.dsh/ 下日志、注册 AI 工具与提示词注入。安装前请自行查看 源码与 LICENSE，确认可接受维护者与代码行为。
生态说明：DSH 主张「一切皆插件」；SkillHub 等为社区目录，与 DeepSeek / 幻方无官方从属关系，本文不以「官方应用商店」表述。
已知限制（摘自 README）：结束进程必过恢复框；Config.listConfigs 可能显示 unsupported（外部插件无法内省 asar 内 schemastery）；经验索引中解法截 60 字、症状 100 字，细节需 AI 读全文文件。
结尾¶
dsh-plugin-dev-tools 把「界面怎么叫、坑在哪里、动手前先查什么」收进一个可开关的客户端插件：定位用 Alt，经验库随包分发并在开发模式下注入索引，改代码有没有生效用开发诊断对照磁盘与进程状态。
- 目录页：https://www.skillhub.cn/plugins/eighteentang/dsh-plugin-dev-tools
- GitHub：https://github.com/eighteentang/dsh-plugin-dev-tools
