Henryang777/dsh-illustrated-teaching

dsh-illustrated-teaching · 图解教学

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

License

✨ 它能做什么

在 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 套模板

| 模板 | template 值 | 适用场景 | 视觉特点 |
|------|------------|----------|----------|
| 思维导图 | mindmap | 知识框架、概念关联 | 中心圆+贝塞尔曲线+彩色分支卡片 |
| 产业链/路径 | chain | 上下游、学习路径、演进史 | 阶段卡片+箭头+总结公式条 A→B=结论 |
| 网格卡片 | grid_card | 多知识点并列 | 黄圈编号+emoji 图标+荧光贴士条 |
| 对比分类 | compare | A vs B、分类科普 | 彩色分栏+勾选标记+“例：”典型例子行 |
| 记忆卡片 | memory | 复习背诵 | 正面概念/背面定义+要点 |
| 流程步骤 | process | 工艺流程、操作指南 | 时间线+编号圆点+关键参数块+设备/作用注解 |
| 分层拆解 | annotate | 真正的分层堆叠（协议栈/地质层） | 爆炸分层+左右引线标注 |
| 剖面结构 | cross_section | 物理器件结构（MOS/PN 结/三极管） | 基底+并排镶嵌区块+覆盖层+沟道虚线+简化示意角标 |

各模板的 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