dsh-illustrated-teaching · 图解教学

把任何知识点自动渲染成精美图解画廊的 DeepSeek Harness（dsh）插件。 8 套小红书科普风模板 · 结构化数据驱动 · 真实图片检索 · 一键导出画廊页。 专为本科阶段学习与理解设计：严谨、有例子、有总结、第一眼不误导。

✨ 它能做什么

在 Harness 对话里说"图解一下什么是 MOS 管"，插件会：

1. 由模型规划 3-6 张配图，并为每张填入真实知识数据（不是占位文字）
2. 渲染成统一风格的精美卡片（Playwright 高清截图，2x DPR）
3. 生成一个自包含画廊页（图片 base64 内联），返回可点击链接，浏览器直接打开
4. 同时导出 PNG + captions.txt + manifest.json 到本地文件夹

🚀 安装（一条命令）

前提：已安装 DeepSeek Harness（dsh 0.1.0-rc.6）。

dsh plugin --profile web add github:Henryang777/dsh-illustrated-teaching

重启 Harness 后生效。验证安装：

curl http://127.0.0.1:3080/illustrated-teaching/health

返回 JSON（含 Playwright / 中文字体 / 网络状态）即正常。

推荐：把本仓库的 SKILL.md 复制到 ~/.dsh/skills/illustrated-teaching/SKILL.md—— 它是写给模型的"使用说明书"，有了它，对话模型会自动规划配图、调用 API 并把画廊链接回复给你。

💬 使用方式

装好插件 + 技能文件后，直接对话即可：

• "图解一下什么是 PN 结"
• "帮我理解操作系统里进程和线程的区别"
• "科普一下蛋白纯化工艺，要配图"
• "一张图看懂芯片产业链"

模型会正常讲解，然后自动生成配图并在结尾给出 🎨 画廊链接（点击浏览器打开）。

也可以直接调 HTTP API（适合自动化）：

# Windows 建议把 JSON 写入文件再发送，避免引号转义问题
curl -X POST http://127.0.0.1:3080/illustrated-teaching/generate \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

payload.json 最小示例：

{
  "content": "什么是PN结",
  "style": "xiaohongshu",
  "items": [
    {
      "form": "info_card",
      "template": "cross_section",
      "content": "PN结结构剖面",
      "caption": "一张图看懂 PN 结",
      "data": {
        "title": "PN结结构剖面",
        "cover": { "label": "耗尽层", "description": "空间电荷区，内建电场所在" },
        "embeds": [
          { "label": "P 区", "description": "空穴是多数载流子" },
          { "label": "N 区", "description": "电子是多数载流子" }
        ],
        "base": { "label": "半导体基底", "description": "硅或锗单晶" },
        "note": "P 区与 N 区是并排接触的整块区域"
      }
    }
  ]
}

响应关键字段：data.galleryUrl（在线画廊链接）、data.galleryFile（本地自包含 HTML）、data.exportDir（PNG 导出目录）、data.images[]（base64 图片）。

🎨 8 套模板

各模板的 data 字段详见 SKILL.md 速查表与完整示例。

🧠 设计原则（为什么图"看着靠谱"）

• 空间关系真实：并排镶嵌 ≠ 上下分层——物理器件一律走 cross_section，分层堆叠才用 annotate
• 关键部件不缺项：画 MOS 管就必须 G/S/D/B 四端齐全
• 动态机制显式表达：导电沟道这类"加电压才形成"的东西用虚线桥 + 因果描述
• 参数用常见范围：温度/收率/pH 写有据可查的区间，不编造精确值
• 简化主动声明：剖面图自带"简化示意"角标，易误解点写进贴士条

🖼️ 图片管线

模型结构化数据 → 8 套 HTML 模板 → Playwright 截图（2x DPR）
真实图片（可选）：Wikimedia Commons → Wikipedia 搜索，自动署名，失败自动降级 SVG
渲染降级链：Playwright → 系统 Chrome/Edge → SVG 原生渲染

• Playwright 浏览器二选一：npx playwright install chromium，或已装系统 Chrome/Edge（自动探测）
• 也可用环境变量 DSH_ILLUSTRATED_CHROME_PATH 指定浏览器路径
• 无网络时真实图片自动降级为精美 SVG 示意图，不会报错中断

⚙️ 配置参考（可选）

plugins:
  illustrated-teaching:
    defaultTheme: xiaohongshu        # 或 academic 学术风
    exportDir: ~/dsh-illustrated-output
    canvasWidth: 1080
    deviceScaleFactor: 2
    triggers:
      keywords: [什么是, 帮我理解, 讲解, 科普, 教程]
      excludePatterns: ['^\d+\+\d+', 今天几号, '^(你好|谢谢|再见)']

🛠️ 本地开发

pnpm install
pnpm build        # tsc → .dsh-plugin/
pnpm smoke        # 冒烟测试：渲染全部 8 套模板 + 环境自检
pnpm demo         # PN 结演示案例

目录结构：

src/
├── index.ts            # Cordis 插件入口：webServer 路由 + 服务注册
├── service.ts          # 触发判断 → 配图规划 → 渲染 → 导出 → 自检
├── pipeline/           # planner / decision-matrix / mixer / exporter / gallery
├── templates/          # 8 套 HTML/SVG 模板
├── theme/              # 统一 CSS 变量（小红书风 / 学术风）
├── renderer/           # Playwright / SVG 原生 / HTML 内联渲染器
├── search/             # Wikimedia / Wikipedia 真实图片检索
└── cache/              # 图片缓存

🙏 致谢与声明

• 本插件为 DeepSeek Harness（dsh） 开放平台开发的社区插件，感谢 dsh 团队的开放架构
• 视觉风格学习自小红书 / B 站的优秀半导体科普图（芯片产业链全景图、H200 3D 拆解等），仅借鉴版式语言，未使用其图片素材
• 开发过程中使用了 Kimi（Moonshot AI）辅助完成代码与文档
• 生成内容中的知识数据由调用的语言模型提供，请在用于严肃场景前自行核实

📄 License

MIT © 2026 Henryang777