给 DSH 写插件：从一个入口按钮说起

用 DSH 久了，会遇到一类共同的问题：有些事你天天在做，但界面上没地方做，只能回到终端敲命令。

我给自己的一个需求写了插件，这篇文章讲两件事：插件是怎么长出来的，以及它是怎么工作的。
过程里想明白的一些东西，对写别的插件也一样。

一、插件不是外挂，它和内置功能坐同一张桌子

这是理解 DSH 插件最关键的一句话。

DSH 的界面不是焊死的一整块，而是拼出来的。官方在界面上留了很多空位：侧边栏的底部、输入框旁边那一排小按钮、
设置里的每一页、会话标题右边的动作区 —— 这些都是空位。

关键在于：DSH 自己的功能也放在这些空位上，插件放的也是同一批空位。

这意味着一个做得好的插件不会显得突兀。位置是官方预留的，颜色和字号跟着主题走，
侧边栏收起来的时候，它也跟着变成图标。它和内置功能享受同样的待遇。

拿我的插件举例。侧边栏底部本来就是这个样子：

侧边栏底部
┌────────────────┐
│  技能管理        │   ← 我的插件插在这里
├────────────────┤
│  ⚙ 设置         │   ← DSH 内置
└────────────────┘

我不是把按钮画在那儿的，是插在了一个「设置上方的动作位」上。

二、每个空位都有一份说明书

空位不是随便插的。每个空位都写着三件事：

这就是为什么我的入口正好落在「设置」上面。不是巧合，也不是我算出来的坐标 ——
侧边栏底部本来就是个从上往下的容器，顺序就是「动作区在前、设置在后面」。我插进动作区，它自然就在设置上方。

插件的自由度，其实来自「位置有人管」。 你不需要知道界面怎么排版，
只要找到合适的空位、按说明书插进去，它就会出现在本来该在那个位置的地方。

三、我的插件做什么

点侧边栏「设置」上方的入口，会在应用里弹出一个面板（不会跳到浏览器的新标签页）。
左边是列表，右边是内容。

看得见有什么。 列表把所有条目列出来，上面有搜索框，输入关键词就能筛。

不用去翻文件。 点任意一条，右边直接显示它的完整内容，按正常排版显示。

能直接打开文件夹。 想知道它是怎么组织的、或者想改它，点一下就跳到所在目录。

删得干净，也删得回来。 删除会把所有相关位置一起移走，而不是只清掉看得见的那一个。
而且是移进系统自己的回收站，不是直接抹掉 —— 删错了还能捡回来。

会把有问题的挑出来。 格式不合规的条目，DSH 不会加载，但它不报错、也不提示，
文件就静静躺在那里。插件会把它标出来，这是我最喜欢的一个功能：这类失败是无声的，靠自己翻发现不了。

四、它背后是怎么工作的

一个 DSH 插件最多由两半组成，一半在后台，一半在界面上。

  界面上的一小块              后台的一小块
┌──────────────────┐      ┌──────────────────┐
│ 一个入口按钮       │      │ 读磁盘上的目录     │
│ 一个弹出的面板     │ ←──→ │ 判断哪些是有效的    │
│ （几乎不干活）     │      │ 移动文件、生成页面  │
└──────────────────┘      └──────────────────┘

后台那一半管真实的事情：读目录、判断有效性、移动文件。
这些必须在后台做，因为界面那一半碰不到你的文件系统。

界面那一半只负责一件事：在侧边栏放一个按钮，点了弹出一个面板。

我刻意让界面这一半保持得很薄。薄到什么程度？它连列表长什么样都不知道 ——
因为面板里显示的那一屏，是一张由后台生成、发过来的网页。

五、为什么面板里要套一个网页

这是这个插件上我做的最重要的一个决定。

最直接的做法，是在界面那一半里把列表、按钮、内容渲染全部写一遍。能做，但有个隐患：
同一个页面的样子会存在两份实现 —— 一份给弹出的面板用，一份给独立页面用。
改一次样式要改两处，很快就开始不一致。

所以我反过来做：页面只写一份，写在后台；界面那一半只负责把它嵌进面板。

这样做带来三个好处，都是使用者能感受到的：

一是不容易坏。 没有两份代码要同步，也就不存在「这边改了那边没改」的错位。

二是很稳。 这个页面里一行脚本都没有。搜索是一个最普通的网页表单，删除是两步确认加一次提交。
没有脚本，就没有脚本出错、卡住、被拦截的问题。

三是边界更清楚。 面板里的网页拿不到应用本身的运行环境，它只能通过后台留给它的那几个入口做事。

六、两条我给自己定的底线

写这个插件时，有两件事我一开始就决定不做。

第一条：删除必须可以后悔。 我第一版自己做了个回收站 —— 删除后先放进插件自己的目录，还能恢复。
后来想通了：系统本来就有回收站了，再教用户「这个插件还有一个回收站」，是纯粹的多余。
现在删除就是移进系统回收站，和你自己拖进去是一回事。

第二条：要操作的路径不能来自点击。 这个插件会调用系统命令帮忙打开文件夹、移动文件。
听起来有点危险，所以我把规则定死了：按钮只传一个名字，具体动哪个目录，由后台自己查出来。
你点的是「删除某个技能」，后台自己去查它在哪 —— 而不是你告诉它一个路径，它照着执行。
这样从结构上就不存在「被诱导去操作别的目录」的可能。

七、怎么装，怎么用

从代码目录安装是这样：

dsh plugin --profile web add link:/path/to/your-plugin

卸载就是把 add 换成 remove，再重启一次。装了什么、装在哪里，在设置里的「插件」那一页都能看到。

八、想自己写一个

如果你也想给 DSH 添点什么，或者想改我这份，代码是公开的：

https://atomgit.com/gcw_cJbJuamU/dsh-skill-manager

MIT 协议，随便拿去用。装法、开发说明，以及几个开发时会遇到的坑，都写在 README 里。

收尾

这个插件我前后改了三版。先做成设置里的一页，读长东西太挤；后来改成在新标签页打开，跳出去那一下体验是断的；
现在这一版才算顺手。

回头看，花时间最多的不是写功能，是搞清楚界面上哪块地方是留给我的。搞清楚之后，剩下的反而简单。

如果你也遇到过「这件事我每周手动做三次」的时刻，那大概就值得一个插件。