dsh-illustrated-teaching

Readme

# dsh-illustrated-teaching · 图解教学

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

![License](https://img.shields.io/badge/license-MIT-blue)

---

## ✨ 它能做什么

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

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

## 🚀 安装（一条命令）

前提：已安装 [DeepSeek Harness](https://github.com/deepseek-ai/dsh)（dsh 0.1.0-rc.6）。

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

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

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

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

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

## 💬 使用方式

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

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

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

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

```bash
# 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` 最小示例：

```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 示意图，不会报错中断

## ⚙️ 配置参考（可选）

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

## 🛠️ 本地开发

```bash
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）](https://github.com/deepseek-ai/dsh)** 开放平台开发的社区插件，感谢 dsh 团队的开放架构
- 视觉风格学习自小红书 / B 站的优秀半导体科普图（芯片产业链全景图、H200 3D 拆解等），仅借鉴版式语言，未使用其图片素材
- 开发过程中使用了 [Kimi](https://www.kimi.com/)（Moonshot AI）辅助完成代码与文档
- 生成内容中的知识数据由调用的语言模型提供，请在用于严肃场景前自行核实

## 📄 License

[MIT](./LICENSE) © 2026 Henryang777