前言¶
在 DeepSeek Harness（DSH）里用 dsh-skill-mcp-panel 浏览技能时，卡片展开后看到的 description 大多直接来自各技能的 SKILL.md frontmatter，而这类描述几乎都是英文。长段落读起来慢，也不容易一眼判断「什么时候该用这个技能」。
面板本身不负责维护中文字典，只把原文贴出来。dsh-skill-zh-overlay 是在面板之上加的一层说明浮层：展开卡片时，最上方先出现中文速览、分类标签和要点列表；面板原有的英文原文默认折起，需要时点「原文」再展开。没收录的英文技能在第一次点开时，由宿主用你当前的默认模型现场生成说明并写入缓存；原文已是中文的会自动跳过，避免重复叠两层中文。
这是什么¶
- 插件名称：
dsh-skill-zh-overlay - 维护者：blacktaoK
- 分类：记忆（社区目录归类）
- 许可证：MIT（见仓库 README）
- 前置：已安装 dsh-skill-mcp-panel
实现上是「宿主 bundle + 对面板 client.js 的前端补丁」：宿主合并映射表与缓存、注入全局数据、提供按需生成接口；补丁在卡片展开区渲染中文块。未装面板或找不到其 lib/client.js 时，日志会有提示，中文块不生效，但不影响 DSH 及其他插件启动。
展开卡片后你会看到什么¶
技能卡片展开后，中文说明渲染在原文上方，自上而下大致是：
- 「中文说明」徽章与分类标签（例如
可视化 · 图表） - 一句话中文简介
- 要点列表（何时用、注意点）
- 分隔线
- 来源信息、「原文」按钮与「原文已折叠」提示
四条行为原则（与 README 一致）：
- 浮层不重复抄面板下一行已有的英文原文。
- 原文已是中文的技能不加浮层（非空白字符里中文占比 ≥ 30% 即判定为中文原文）。
- 没有可用中文时不会塞「暂无说明」占位框；要么生成真实内容，要么不加块。
- 需要中文但未收录时，在用户点开卡片时触发生成。
中文说明从哪来¶
按优先级取数，取到就停：
| 顺序 | 来源 | 说明 |
|---|---|---|
| 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 后返回前端，占位块当场替换，无需刷新页面。README 中给出的体验参考为：首次生成约 2 秒，命中缓存约 0.1 秒。
缓存与原文绑定：每条缓存记录英文原文 sha1 的前 16 位；SKILL.md 描述变更后指纹不匹配，旧译文作废，下次点开重新生成。skill-zh-map.json 中的手写条目始终压过同名自动生成；若某技能要强制不加浮层，可在手写表设 "noOverlay": true。
安装与启用¶
官方安装命令（来自 README）：
dsh plugin add dsh-skill-zh-overlay
装完后重启一次 DSH 即可；装饰脚本由插件在启动时写入，无需再跑额外脚本。
若尚未安装 dsh-skill-mcp-panel，应先安装面板插件，否则本插件的中文浮层不会生效。
从源码安装或指定 profile 时，README 提供了 install.ps1 路径（复制 generation、登记 package.json 等）；通过 dsh plugin add 安装时不需要再执行 install.ps1。
典型用法¶
日常使用：安装并重启后，打开技能面板，展开任意英文技能卡片即可。已有手写或缓存的会立即显示中文块；没有的会在首次展开时自动生成。
长期固定措辞或关闭浮层：编辑插件包内 data/skill-zh-map.json，改完后重启 DSH（启动时读一次手写表）。自动缓存 data/auto-zh.json 可删条目后重启以触发重新生成。
映射表示例格式：
{
"_readme": "以 _ 开头的键是注释，会被忽略",
"技能名": {
"zh": "一句话中文简介，显示在卡片展开区最上方。",
"tag": "分类标签，显示为小徽章",
"bullets": ["要点一", "要点二（2-4 条，讲清什么时候用 / 有什么坑）"],
"noOverlay": "可选；true = 强制不加浮层"
}
}
技能名 须与卡片上的名称一致（对应 DOM 上的 data-skill-name）。仓库 README 列出了 8 个已手写的英文技能（如 archify、hindsight-coding-agent、office-docx 等）；其余英文技能可走自动生成，原文已是中文的（如 work-report-writer）会自动跳过。
可选配置¶
在 cordis.patch.yml 的 config 段（均可省略）：
provider: '' # 留空 = 用你当前的默认模型
model: '' # 同上
autoGenerate: true # false = 关掉按需生成，只用手写映射
按需生成走 /skill-zh-overlay/api 前缀，与 DSH 主路由解耦；生成侧单次 maxTokens: 700、超时 60 秒、每批最多 8 条（见 README「原理」一节）。
适用场景与注意¶
适合：经常在 DSH Web 里通过 dsh-skill-mcp-panel 挑技能、希望英文 description 有中文速览和要点，又不想为每个新技能手工维护译文的开发者。
注意：
- 插件以当前 DSH 进程权限运行，会对
dsh-skill-mcp-panel的lib/client.js做幂等补丁；安装前建议查看 GitHub 仓库 源码与 MIT 许可证。 - 自动生成依赖你配置的默认模型与网络；解析失败时该技能会出现在响应的
missing中，可再次点开重试。 - 社区目录 SkillHub 插件页 与 GitHub 由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态奉行「一切皆插件」，本插件是面板体验上的增强，而非 DSH 内置能力。
结尾¶
dsh-skill-zh-overlay 把技能卡片上的英文说明压成可扫读的中文浮层，用手写映射保证常用技能措辞，其余按需生成并带原文指纹的缓存失效策略。若你已在用技能 MCP 面板，一条 dsh plugin add 加重启即可试用。
