blacktaok/dsh-skill-zh-overlay

效果

技能卡片展开后，中文说明渲染在原文上方：

从上到下依次是：

1. 「中文说明」徽章 + 分类标签（如 可视化 · 图表）
2. 一句话中文简介 —— 这个技能干什么
3. 要点列表 —— 什么时候该用它、有什么坑
4. 一条分隔线
5. 来源 + 「原文」小按钮 + 「原文已折叠」提示 —— 原文不删，默认折起，点一下展开

四条原则：

• 不重复英文。 面板下一行本来就写着原文，浮层不再抄一遍。
• 原文是中文的不加浮层。 work-report-writer 这类技能的描述本来就是中文， 再叠一层中文只是把同一句话摆两遍，装饰脚本会按中文占比自动跳过。
• 没收录的不占位置。 不会塞一行「暂无中文说明」的占位框糊弄过去 —— 要么真的生成一条，要么什么都不加。
• 没收录但需要中文时，现生成。 见下一节。

中文说明从哪来

一个技能要显示中文，按这个顺序取，取到就停：

第 4 步的触发方式很朴素：你点开一张没有中文的卡片，装饰脚本先放一个 「正在生成中文说明…」的占位块，同时把这条丢进请求队列，攒成一批（最多 8 条） POST 到 /skill-zh-overlay/api/explain。宿主拿到后调用默认模型，要求它输出 {zh, tag, bullets} 三个字段的 JSON，写进 data/auto-zh.json，再把结果并回前端 的那张表 —— 占位块当场换成真正的中文，不用刷新页面。

实测一次生成 约 2 秒，命中缓存后 约 0.1 秒。

缓存怎么失效。 每条缓存都记着当时英文原文的 sha1 前 16 位；技能描述的英文一改 （比如面板作者升级了 SKILL.md），指纹对不上，旧译文自动作废，下次点开重新生成。 不会把过期的中文贴到新内容上。

手写永远压过自动。 模型不可能比校对过的措辞更准，所以 skill-zh-map.json 里有 条目就用条目，自动生成的同名词条会被忽略。想让某个技能强制不加浮层，就在手写表里 写 "noOverlay": true。

安装

dsh plugin add dsh-skill-zh-overlay

装完重启一次 dsh 即可，不用再跑任何脚本 —— 装饰脚本由插件自己在启动时写好。

前置：已经装了 dsh-skill-mcp-panel。插件启动时会去找它的 lib/client.js； 如果还没装（或没放在能找到的位置），日志里会打印一行提示，中文块不生效，但 不影响 dsh 和其他插件启动。

从源码装（或想装在别的 profile）：

git clone https://github.com/blacktaoK/dsh-skill-zh-overlay.git
cd dsh-skill-zh-overlay
pwsh -NoProfile -File install.ps1

install.ps1 做的事：

1. 把插件本体复制进一个 desktop generation 目录 （profiles\.generations\live\dsh-skill-zh-overlay+1.0.0+local0000000）
2. 在 profile 的 package.json 里登记四处，让它出现在插件市场的「已安装」列表里：
   • dependencies —— 市场的 readInstalled() 读这里
   • pnpm.overrides —— link: 指向 generation
   • dsh.profile.bundles[] —— 在列表里 = 启用，移除 = 停用
   • dsh.desktop.generationProjection —— desktop 的版本投影
3. 同步 .generations\desired.json

其他命令：

pwsh -NoProfile -File install.ps1 -Check     # 看当前装了没有
pwsh -NoProfile -File install.ps1 -Revert    # 完整还原（含撤掉前端补丁）

用 dsh plugin add 装的时候就不用跑 install.ps1 —— 这是 dsh plugin add