前言¶

在 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 及其他插件启动。

展开卡片后你会看到什么¶

技能卡片展开后，中文说明渲染在原文上方，自上而下大致是：

1. 「中文说明」徽章与分类标签（例如 可视化 · 图表）
2. 一句话中文简介
3. 要点列表（何时用、注意点）
4. 分隔线
5. 来源信息、「原文」按钮与「原文已折叠」提示

四条行为原则（与 README 一致）：

• 浮层不重复抄面板下一行已有的英文原文。
• 原文已是中文的技能不加浮层（非空白字符里中文占比 ≥ 30% 即判定为中文原文）。
• 没有可用中文时不会塞「暂无说明」占位框；要么生成真实内容，要么不加块。
• 需要中文但未收录时，在用户点开卡片时触发生成。

中文说明从哪来¶

按优先级取数，取到就停：

第 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 加重启即可试用。

• 社区目录：https://www.skillhub.cn/plugins/blacktaoK/dsh-skill-zh-overlay
• 源码与文档：https://github.com/blacktaoK/dsh-skill-zh-overlay