前言¶

在 DeepSeek Harness（DSH）里让模型「画一张图讲清楚」，常见问题是图上的专业名词读者并不认识：流程再漂亮，信息也进不了脑子。反过来，只堆文字解释又难扫读。社区插件 dsh-visual-explainer（维护者 biubiuandmiaomiao）把顺序写进工具链：先做名词轮（大白话），再渲染 PNG 卡片或离线可点的 mermaid 交互页；若跳过名词直接画图，会被门禁拒绝，而不是悄悄产出一张难懂的图。

下面介绍插件定位、四个工具、安装配置与典型用法。事实以 GitHub 仓库 README 为准；社区目录页：skillhub.cn/plugins/biubiuandmiaomiao/dsh-visual-explainer（与 DeepSeek / 幻方无官方从属关系）。

这是什么¶

dsh-visual-explainer 是面向 DeepSeek Harness 的讲解类插件（分类：模型推理）。简介：先把专业/技术名词讲成人话，再把讲解画成一张张 PNG 卡片，或生成一页可点的离线 mermaid 交互页。

当前包版本 0.2.2，许可证 MIT。渲染依赖本机 Chrome 或 Edge 的 headless 模式，不额外装浏览器驱动、出图过程不联网。

核心设计：名词在前，画图在后¶

插件把流水线固定为两步：

1. visual_terms：第 0 轮，把本次讲解里的名词写成 { term, plain, context?, analogy?, pitfall? }，生成可放在回答开头的 markdown，并落盘 terms.md / terms.json。
2. visual_explain：在名词轮之后，根据 HTML 按 <section id="fgN"> 逐张渲染 PNG（先测真实高度再截图，减少底部留白）。

顺序颠倒时，visual_explain 会被门禁直接拒绝（例如提示：先解释名词，再画图）。确实没有名词要解释时，可 visual_terms({ terms: [], note: '…' })，或仅在重渲染旧图等场景对 visual_explain 传 skipTerms: true。

除上述两个主工具外，还有：

插件还注册按需加载的技能手册 skill.md，描述「把一张图讲成小白能懂」的流程与 mermaid 注意点。

环境要求¶

• DeepSeek Harness 桌面版（插件为 host 侧 bundle；README 写明在 Windows 上验证，浏览器路径探测也覆盖 macOS / Linux 常见路径）。
• 本机安装 Chrome 或 Edge。
• Node.js ≥ 20（跑测试或单独使用命令行渲染器时需要）。

安装与启用¶

官方 README 提供的安装方式如下（PowerShell）：

git clone https://github.com/biubiuandmiaomiao/dsh-visual-explainer.git
cd dsh-visual-explainer
pwsh -File .\install.ps1            # 默认 link：源码改动下次重载生效
# 或：打包成 tgz 再装，和源码目录解耦
pwsh -File .\install.ps1 -Mode pack

脚本会解析 pnpm（-Pnpm → DSH_DESKTOP_PNPM → DSH 内置运行时 → PATH），并把包选进 profile 的 dsh.profile.bundles。

装完后须重启一次 DeepSeek Harness：工具在进程启动时注册到 ctx.tools；名词轮是否做过的记录是进程内的，重启后第一次画图会再次要求先解释名词（README 说明这是有意设计）。

验证要点：

• 侧边栏 Plugins 中应能看到 dsh-visual-explainer；
• %TEMP%\dsh-visual-explainer-status.json 里 pluginVersion、toolsRegistered、appliedAt 应与本次启动一致；
• 让模型做一次「图解」，应能调用 visual_terms。

若不用 install.ps1，可在 profile 的 package.json（默认 %USERPROFILE%\.dsh\profiles\desktop\package.json）里添加 dependencies 与 dsh.profile.bundles，再在 profile 目录执行 pnpm install；包内 cordis.patch.yml 会插入插件行（详见 README「手动接线」折叠段）。

配置¶

在 profile 的 cordis.patch.yml 里按行 id 覆盖（也可改包内默认值）：

- id: visual-explainer
  name: dsh-visual-explainer
  config:
    outDir: .dsh-visual   # 相对会话工作目录
    scale: 2              # 2 → 1240px 画布输出 2480px 宽
    width: 1240
    browser: ""           # 留空则自动找 Chrome / Edge
    maxCards: 12          # 单次渲染上限
    termsFirst: true      # true=画图前必须先做名词轮；false=关掉门禁
    explainerDir: .dsh-explain  # visual_interactive 的默认输出目录

典型用法¶

对话侧话术¶

可直接说例如：

• 「用图解讲讲 X」
• 「一张图看懂 X」
• 「先解释这些名词，再画成图」
• 「把这张时序图讲成代码小白能懂，并做成可点的 mermaid 页」

命中技能描述后，模型按手册顺序调工具；也可直接点名工具名。

四步流水线（模型 / 工具调用）¶

// 1. 第 0 轮：名词
visual_terms({
  topic: 'mem0 的 add / search 流程',
  terms: [
    { term: 'Embedding', plain: '把一句话变成一串数字坐标，意思相近的坐标也相近' },
    { term: 'BM25', plain: '老式关键词打分：只认字面，不懂意思' }
  ]
});

// 2. 可选：写起步模板
visual_template({ path: 'explain.html' });

// 3. 出图
visual_explain({ html: '<!doctype html>…', outDir: 'figs' });

// 4. 或者：可点的交互页
visual_interactive({ action: 'scaffold', dir: 'explain', title: '看懂这个系统' });
// 改 explain/index.html 里的 const steps=[...]，然后：
visual_interactive({ action: 'check', dir: 'explain' });

README 中的 mem0 add / search 流程示例展示了多张流水线卡片与打分相关图示，可作为产出形态参考（见仓库 docs/screenshots/）。

卡片约定¶

• 一张卡对应一个结论，id 须为 fg1、fg2、fg3…（渲染器按编号排序）；
• 高度预算约 800px，超出则拆到下一张；
• 须保留模板中的测高脚本（把可见 section 最下沿写入 document.title）；勿改为 documentElement.scrollHeight，否则内容较矮时会出现统一高度与底部留白。

不装 DSH 时单独渲染¶

node renderer.mjs --html explain.html --out figs --scale 2
node renderer.mjs --html explain.html --out figs --figs 1,3
node renderer.mjs --html explain.html --out figs --whole
node renderer.mjs --html explain.html --out figs --height 900

适用场景与注意¶

适合谁：需要在 DSH 对话里稳定产出「先通俗、后可视化」讲解材料的开发者；既要 PNG 卡片嵌入回答，也要离线 mermaid 逐步讲解页的场景。

权限与安全：插件以当前 DSH 桌面进程权限运行，会读写会话工作目录下的输出目录（如 .dsh-visual、.dsh-explain），并调用本机浏览器做截图与自检。安装前请阅读仓库源码与 MIT 许可证；第三方 mermaid 浏览器构建说明见 THIRD_PARTY_NOTICES.md。

交互页限制（README 摘要）：每一步对应一张独立小图；避免在 mermaid 里做「增量显示」导致 alt 未闭合；sequenceDiagram 单条消息建议 ≤10 个汉字，以免窄泳道断词。

故障排查：工具未出现 → 重启 Harness，查 %TEMP%\dsh-visual-explainer-status.json；渲染 0 张 → 查 lastFailures、浏览器路径（browser 或 CHROME_PATH）、HTML 是否含 id="fgN"。完整对照表见 README「故障排查」一节。

结尾¶

dsh-visual-explainer 用「名词轮 + 门禁」把图解讲解拆成可复现的两段式流水线，并辅以模板、PNG 渲染与离线交互页四条工具路径。若你在 DSH 里做技术解读或培训材料，可从 README 的快速开始与四步示例入手。

• 社区目录：https://www.skillhub.cn/plugins/biubiuandmiaomiao/dsh-visual-explainer
• 源码与文档：https://github.com/biubiuandmiaomiao/dsh-visual-explainer