效果
技能卡片展开后，中文说明渲染在原文上方：
从上到下依次是：
- 「中文说明」徽章 + 分类标签（如
可视化 · 图表）
- 一句话中文简介 —— 这个技能干什么
- 要点列表 —— 什么时候该用它、有什么坑
- 一条分隔线
- 来源 + 「原文」小按钮 + 「原文已折叠」提示 —— 原文不删，默认折起，点一下展开
四条原则：
- 不重复英文。 面板下一行本来就写着原文，浮层不再抄一遍。
- 原文是中文的不加浮层。
work-report-writer 这类技能的描述本来就是中文，
再叠一层中文只是把同一句话摆两遍，装饰脚本会按中文占比自动跳过。
- 没收录的不占位置。 不会塞一行「暂无中文说明」的占位框糊弄过去 ——
要么真的生成一条，要么什么都不加。
- 没收录但需要中文时，现生成。 见下一节。
中文说明从哪来
一个技能要显示中文，按这个顺序取，取到就停：
| 顺序 | 来源 | 谁写的 |
|---|
| 1 | data/skill-zh-map.json | 人工手写，校对过，优先最高 |
| 2 | data/auto-zh.json | 上一次自动生成后落盘的缓存 |
| 3 | 本次进程内已生成的 | 缓存 |
| 4 | 现场调用模型生成 | 宿主，用你当前的默认模型 |
第 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 做的事：
- 把插件本体复制进一个 desktop generation 目录
（
profiles\.generations\live\dsh-skill-zh-overlay+1.0.0+local0000000）
- 在 profile 的
package.json 里登记四处，让它出现在插件市场的「已安装」列表里：
dependencies —— 市场的 readInstalled() 读这里pnpm.overrides —— link: 指向 generationdsh.profile.bundles[] —— 在列表里 = 启用，移除 = 停用dsh.desktop.generationProjection —— desktop 的版本投影
- 同步
.generations\desired.json
其他命令：
pwsh -NoProfile -File install.ps1 -Check # 看当前装了没有
pwsh -NoProfile -File install.ps1 -Revert # 完整还原（含撤掉前端补丁）
用 dsh plugin add 装的时候就不用跑 install.ps1 —— 这是 dsh plugin add
的包，loader 会把它登记进 bundles。install.ps1 是「从工作区源码装」的路径。
为什么做这个
dsh-skill-mcp-panel 的技能卡片直接透传各 SKILL.md 里的 description，
而这些描述几乎全是英文。像 hindsight-coding-agent 那种一段话讲完的长描述，
英文读起来慢，读完还不一定记住「这东西什么时候会自己跳出来」。
面板本身没有任何 description 的中文字典——它只负责把 frontmatter 原样贴出来。
所以这里做了一层外挂的中文说明，把「这个技能是干什么的」压成一眼能扫的形式。
一开始的做法是纯手写映射表，但那样每装一个新技能就得回去补一条，很烦。
现在改成手写兜底 + 按需生成：常用技能留手写版保证措辞，其余全交给模型。
它由两半组成
这个功能不是单个文件，而是一个宿主插件 + 一处前端补丁：
| 组成 | 位置 | 干什么 |
|---|
宿主插件 dsh-skill-zh-overlay | 作为 bundle 挂进 profile | ① 合并映射表与缓存，注入 window.__SKILL_ZH_MAP__；② 启动时给面板 client.js 装装饰脚本；③ 开 /skill-zh-overlay/api/explain 按需生成 |
前端补丁 lib/patch.fragment.js | 由插件自动插进 dsh-skill-mcp-panel/lib/client.js | 读那个全局常量，在卡片展开区渲染中文块；缺条目时请求宿主现场生成 |
为什么要拆成两半，各自的原因都挺硬的：
为什么必须改 client.js 本体。
面板的前端束是打包产物，没有留给外部插件的渲染扩展点。这不是偷懒，
是当下唯一能插进去的位置。所以装饰脚本只能以「在 factory 顶部注入一段自包含代码」
的方式落地，由宿主插件在启动时自动完成。
为什么数据走 index 注入，不走 HTTP 路由。
/plugins 是 client-modules 的前缀路由，未知路径一律 404
（@deepseek-ai/dsh-client-modules/lib/index.js:977 的 bundleResource，
未知资源返回 {status:404}，见 lib/index.js:990），
所以自定义 json 放在那里前端根本 fetch 不到。
为什么自动生成走自己的 HTTP 前缀，不用 Typert。
Typert 的一元方法虽然也走 POST /api/<ns>/<method>，但路由前缀归 dsh 所有。
本插件挂在 /skill-zh-overlay/api 下，与 dsh 版本、网关 schema 演进完全解耦，
也不占用别人的命名空间。
仓库结构
dsh-skill-zh-overlay/
├── package.json 插件清单（含 dsh.bundle.patch 指向 cordis.patch.yml）
├── cordis.patch.yml 插件自己的 loader patch：把自己 insert 进来
├── install.ps1 从源码安装的转发入口
├── lib/
│ ├── index.js 宿主侧：合并映射 → 注入 index → 注册生成接口 → 启动时补面板
│ ├── installer.js 前端补丁的安装/还原实现（幂等、带备份、语法自检）
│ └── patch.fragment.js 注入到面板 client.js 的那段装饰脚本
├── data/
│ ├── skill-zh-map.json ★ 手写映射表（可选，覆盖自动生成）
│ └── auto-zh.json 自动生成缓存（首次生成后自动出现）
├── tools/
│ └── apply.ps1 从源码装的安装器（安装 / -Check / -Revert）
├── test/
│ ├── test-installer.mjs 30 条隔离单测（不碰真机）
│ ├── test-auto.mjs 21 条纯函数单测（指纹、中文判定、JSON 容错、合并优先级）
│ └── smoke.mjs 真机冒烟：确认装饰脚本确实进了面板束
└── assets/ README 用的截图
改中文说明
一般不用改。 没收录的技能会自动生成。只有两种情况需要动手写手写表：
想长期固定某个技能的措辞，或者想关掉它的浮层。
手写表在 data/skill-zh-map.json，改完重启 dsh（启动时读一次）。
自动缓存 data/auto-zh.json 反过来是热生效的，删掉某条重启就重新生成。
映射表格式
{
"_readme": "以 _ 开头的键是注释，会被忽略",
"技能名": {
"zh": "一句话中文简介，显示在卡片展开区最上方。",
"tag": "分类标签，显示为小徽章",
"bullets": ["要点一", "要点二（2-4 条，讲清什么时候用 / 有什么坑）"],
"noOverlay": "可选；true = 强制不加浮层"
}
}
技能名 必须和卡片上的技能名完全一致（也是面板写在 DOM 上的 data-skill-name）。
原文本身已经是中文的技能，就算写进映射表也会被跳过
（中文字符占非空白字符 ≥ 30% 即判定为中文原文；宿主和前端用的是同一个判据）。
现在手写了哪些
8 个英文技能，都是措辞想固定下来的：
| 技能 | 分类 |
|---|
archify | 可视化 · 图表 |
diagnose-windows-sandbox-acl | 系统 · 排障 |
generate-image | 图像生成 |
hindsight-coding-agent | 记忆 · 知识库 |
office-docx | Office · Word |
office-pptx | Office · PPT |
office-xlsx | Office · Excel |
reverse-engineer-anything | 逆向工程 |
其余技能（含 data-viz-gen、gov-doc-writing、meeting-recap、work-report-writer
这些原文本来就是中文的）不再占用映射表，各走各的路：中文原文自动跳过，
没写过的英文技能第一次点开时自动生成。
原理
宿主插件 lib/index.js（apply 时做三件事）
│
├─ ① 注册 webserver/index-inject 回调
│ <profile> 渲染 index.html 时推入一行
│ { kind: 'global', name: '__SKILL_ZH_MAP__', value: 手写+缓存 }
│ → <head><script>globalThis["__SKILL_ZH_MAP__"] = {...}</script></head>
│
├─ ② 注册 prefix 路由 /skill-zh-overlay/api
│ POST /explain {skills:[{name,description}]}
│ → 手写命中？用。缓存命中？用。都没有 → ctx.llm.stream 现场生成
│ → 写回 data/auto-zh.json → 返回 {entries, missing}
│
└─ ③ 找 dsh-skill-mcp-panel 的 lib/client.js，把装饰脚本写进去
（幂等：已装就跳过；改过就先还原再重打）
│
▼
lib/patch.fragment.js（在面板 client.js 的 factory 里执行）
│ MutationObserver 盯 [data-skill-name] 卡片
│ 找到展开区 .SKV_cardDetails 里的 p.SKV_meta（面板渲染的原文行）
▼
① 原文是中文 → 什么都不做
② 表里有条目 → 中文块 insertBefore 到原文行前面
③ 表里没条目 → 放「正在生成中文说明…」占位，丢进队列 POST 给宿主；
拿到结果并进表里，下一轮 decorate 就换成真正的中文块
④ 无论哪条路，最后都把原文行折成「来源: xxx + 原文按钮」，点按钮展开
第 ③ 步怎么找到面板。 插件是 junction 安装的，Node 解析模块时给的是
真实路径（落在 profiles/.generations/<gen>/node_modules/...），而面板装在
profiles/<profile>/node_modules/。所以 lib/installer.js 从自身真实路径往上走
到 profiles/，再把它的每个子目录下的 node_modules/dsh-skill-mcp-panel/...
全列出来当候选 —— 这样无论插件在哪个 generation、哪个 profile 都能找到面板。
模型输出怎么保证可解析。 系统提示强制「只输出 JSON，不要 Markdown 代码块」，
解析端仍然容错 ```json 围栏和前后多嘴的解释；实在解析不出就整条丢弃
（missing 数组里会带上技能名），下次点开再试，绝不把半截文本塞进卡片。
单次请求 maxTokens: 700、超时 60 秒、一批最多 8 条。
关键锚点（面板 v2.1.5）：
- 卡片根节点带
data-skill-name（lib/client.js:1569）
- 展开了才有
.SKV_cardDetails，其下 p.SKV_meta 是英文原文 + 来源: xxx（lib/client.js:1604-1609）
- 补丁插入点在
factory: (require) => { 之后（lib/client.js:3）
面板是手风琴：同时只有一张卡展开。点另一张会把当前这张折叠、
.SKV_cardDetails 整个销毁；点回来会重建，补丁靠 MutationObserver
- 点击后补跑（50/150/400ms）重新插入，所以来回切也不会丢。
配置
插件配置（cordis.patch.yml 里 config 段，都可省略）：
provider: '' # 留空 = 用你当前的默认模型
model: '' # 同上
autoGenerate: true # false = 关掉按需生成，只用手写映射
关掉 autoGenerate 后，没写进 skill-zh-map.json 的技能就没有中文块 —— 卡片保持面板原样。
本地自测
node test/test-installer.mjs # 30 条隔离单测，在临时目录里演练，不碰真机
node test/test-auto.mjs # 21 条纯函数单测
node test/smoke.mjs # 真机冒烟：装饰脚本是否确实进了面板束
test-installer.mjs 覆盖：锚点定位、幂等、重复安装不叠加、-Revert 还原、
面板升级后锚点缺失时不写坏文件、越界保护等。
test-auto.mjs 覆盖：指纹稳定性、中文判定（含「恰好三成」的边界）、
模型输出解析（裸 JSON / 代码围栏 / 前后有废话 / 坏 JSON）、合并优先级（手写压自动）。
它需要一份「未打过补丁」的前端束当载荷，按这个顺序找：
- 本机面板的
lib/client.js.skvzh.bak（首次注入前的备份）
- 本机面板的
lib/client.js（没有备份 = 从未注入过）
- 都拿不到就用内置的最小桩（只保留真实锚点行）
所以测试在没装面板的机器上也能跑，不用把一个 200KB 的上游产物固化进仓库。
面板装在非默认 profile 时，用 DSH_PROFILE_DIR 指过去。
已知限制
- 面板插件升级会覆盖
client.js，补丁丢失、中文块消失。
重启 dsh 就会自动补回（apply 里每次都调 ensurePatched）；
原始文件备份在 lib/client.js.skvzh.bak，-Revert 用它还原。
- 按需生成要花模型调用。 每个新技能第一次点开生成一次，之后走缓存不花钱。
不想花就关掉
autoGenerate，或者把它写进手写表。
- 生成质量取决于当前默认模型；写错的话改手写表覆盖它。
- 面板改版后
data-skill-name / .SKV_cardDetails / .SKV_meta 这些锚点可能变，
补丁会静默失效（整体包在 try/catch 里，不影响面板本身）。届时对着新版 client.js
调整 lib/patch.fragment.js 里的选择器。
- 「原文」按钮折叠的是面板自己的那行描述文字，只改显示不改数据；
React 重建子树后会重新装饰，装饰时按
data-skvzh-open 对齐按钮文案，
不会把你手动展开的原文又收回去。
- 卡片是手风琴，点另一张会把当前这张折叠、
.SKV_cardDetails 整个销毁；
再点回来时补丁会重新插入，中文块和「原文」按钮都会回来。
- 位置靠后的「来源: dsh-office」是面板自己渲染的，不属于本项目。
License
MIT
