@dongfangw/study-kit 0.1.2 → 0.2.0

package/skills/make-mindmap/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: make-mindmap
+description: 把一份缩进大纲（或一段文本路线图 / 章节结构 / 教案环节 / 知识地图）渲染成**可嵌入 md 与 adoc 的思维导图 SVG**，表现形式（布局、主题、连线、密度、逐层样式）全部可配置。用于「把文本路线图换成图」「给某卷/某章建思维导图」「知识地图/结构图/学习路线太丑」「draw a mindmap」等任务。含零依赖渲染器 render.mjs（缩进大纲 → SVG）、7 主题 × 4 布局 × 4 连线 × 3 密度的配置总表、入稿图注写法与三条验收口径。
+metadata:
+  version: "1.1.0"
+---
+
+# 思维导图技能（make-mindmap）
+
+**一句话**：阅读器只做「AsciiDoc/Markdown → HTML」，**没有 diagram 扩展**——所以本技能不做
+"给正文加图块"，而是**先把大纲渲染成矢量 SVG 落盘，再用图片语法引用**。这样在阅读器、
+打印、课件里都能正常显示，且不依赖 Java / Chrome / 联网。
+
+---
+
+## 0. 为什么不是 `[plantuml]` / `[mermaid]` 图块
+
+AsciiDoc 生态里确实有"原生"思维导图，但都不适用于本套件：
+
+| 路线 | 写法 | 依赖 | 为什么不直接用 |
+|---|---|---|---|
+| asciidoctor-diagram + PlantUML | `[plantuml]` 块里 `@startmindmap`…`@endmindmap` | Java + plantuml.jar（+ Graphviz） | 阅读器用**裸 `@asciidoctor/core`**（`ext/adoc-convert`），没装 diagram 扩展 → 图块退化成一段等宽**纯文本**，正是要消灭的东西 |
+| asciidoctor-diagram + Mermaid | `[mermaid]` 块里 `mindmap` | Node + mermaid-cli + 无头浏览器 | 同上，且要拉 Chrome |
+| asciidoctor-kroki | `[mermaid]` / `[plantuml]` | 需要 Kroki 服务端（或公网） | 同上 + 离线不可用 |
+| markmap | Markdown → 交互式 HTML/SVG | node + markmap-cli | 产物是交互式 HTML，`image::` 引不了；导成 SVG 后与本技能路线等价，但多一层依赖 |
+
+**结论**：图的"源"可以是文本，但**入稿物必须是 SVG 文件**。`render.mjs` 就是这条路的
+离线实现（零依赖，纯 Node）。
+
+---
+
+## 1. 三步工作流
+
+```bash
+# ⓿ 自检（可选，确认渲染器在这台机器上能跑）
+node <本技能目录>/render.mjs <本技能目录>/example/示例.mmd --out /tmp/smoke.svg --json
+
+# ① 写大纲（Mermaid mindmap 的缩进子集 + 可选 YAML 前置配置）
+#    放哪儿由你定，惯例是「与正文页同名、放在页面旁边」：<页面名>.mmd
+
+# ② 渲染成 SVG（落进该库的图片目录，文件名按页面编号）
+node <本技能目录>/render.mjs <大纲文件>.mmd --out <库根>/images/<页号>-mindmap.svg
+
+# ③ 正文里按插图写法引用（见 §4.2）
+```
+
+`render.mjs` 与 SKILL.md **同目录**，不需要 `npm install`。别靠猜路径：
+本 SKILL.md 的绝对路径就是定位锚点，`render.mjs` 就在它旁边。
+
+---
+
+## 2. 大纲语法（Mermaid mindmap 子集）
+
+```
+mindmap                        ← 可选关键字
+  root((中心主题))              ← 根；id 可省略，(( )) 里是文本
+    一级分支
+      二级要点                   ← 缩进即层级
+      失效 = 边界条件 :::warn
+    另一条分支
+      50°–55° 是实用窗 :::key
+```
+
+* **层级只由缩进决定**（Tab 视作 4 空格）；`- ` / `* ` / `+ ` 项目符号会被忽略，方便直接粘 Markdown 大纲。
+* **形状**：`((圆))`、`(圆角)`、`[方框]`、`{{六边形}}`；不带括号 = 用配置里的默认形状。
+  `id` 前缀（`a((文本))`）会被吞掉，粘 mermaid 源不用改。
+* **换行**：`<br/>`，或在前置配置的 YAML 里写 `\n`。
+* **样式类**：行尾（或下一行）写 `:::类名 类名2`，类名在配置 `classes:` 里定义。
+  推荐约定：`:::warn` 标"陷阱 / 失效边界"，`:::key` 标"核心判据"——**每张图别超过两类**，
+  否则满屏彩块、层级反而看不见。
+* `%%` 开头是注释；`mindmap` / `outline` 单独成行视为头部关键字。
+* **多根**会自动合成一个虚拟根，不会丢内容（但通常说明大纲该收敛了）。
+
+---
+
+## 3. 配置项总表（"表现形式可配置"就是这一节）
+
+写在大纲文件顶部，夹在 `---` 之间（YAML）。**全部可省**，省了用主题默认值。
+
+```yaml
+---
+title: 图的标题            # 画布标题（正文里另有图注，二者不要重复同一句话）
+subtitle: 一句话交代这张图该怎么读
+layout: right          # right | left | both | tree
+theme: paper           # paper | aero | ink | warm | forest | slate | contrast
+connector: curve       # curve | elbow | straight | arc
+density: normal        # compact | normal | roomy
+numbering: none        # none | arabic | path | circled
+shape: rounded         # rect | rounded | pill | hex | circle | underline | none
+canvasPad: 18          # 画布留白（px）
+background: '#ffffff'  # 也可写 transparent（深色阅读主题下更协调）
+border: false          # 外框
+shadow: false          # 节点投影
+footnote: 判据的取值范围见各页；源文件与正文同步维护
+font:
+  size: 15             # 基准字号；逐层再放大/缩小
+  lineHeight: 1.34
+  family: "'PingFang SC', 'Microsoft YaHei', sans-serif"
+maxNodeWidth: 182      # 二三级节点换行宽度（超了就折行，不会横向长出去）
+rootMaxWidth: 250      # 根节点换行宽度（一般给大些，别让根折行）
+gap:                   # 不写就按 density 预设
+  level: 28            # 层间距（父→子）
+  sibling: 5           # 兄弟间距
+  branch: 18           # 分支之间
+padding:
+  x: 13
+  y: 6.5
+radius: 9
+edgeWidth: [3, 2, 1.35]   # 逐层连线粗细
+palette: ['#1f5fa8', '#2b8a8a', '#c2703a', '#6a4fa3', '#2f7d4f', '#a8434f']
+levels:                # 逐层覆盖（按 depth 0,1,2,3…），优先级最高
+  - {size: 19, weight: 700, fill: '#1b3a63', color: '#ffffff', padX: 17, padY: 9}
+  - {size: 14.8, weight: 650, shape: pill, padX: 9, maxWidth: 200}
+  - {size: 13.6, weight: 500, fill: 'none', color: auto}
+classes:               # :::类名 引用的样式
+  warn: {stroke: '#c8786d', sw: 1.1, fill: '#fdf3f1', color: '#8a1f1f'}
+  key:  {stroke: '#7aa6dc', sw: 1.1, fill: '#eef4fc', weight: 650}
+---
+```
+
+### 3.1 三个"风格旋钮"怎么选
+
+| 旋钮 | 取值 | 什么时候用 |
+|---|---|---|
+| `layout` | `right` | **单向链**（设计链、流程、学习顺序）。阅读顺序自上而下，不被左半边的逆序打断。**窄版心首选。** |
+| | `both` | 真·发散结构（一张知识地图、目录鸟瞰）。左右各半，最像思维导图，但**宽度约翻倍** |
+| | `tree` | 自上而下。分支 ≤4 条才不至于横向出画 |
+| | `left` | 与右侧浮动正文并排时用 |
+| `theme` | 见 §3.2 | 按丛书调性选；`ink` 给印刷稿，`slate` 给深色 |
+| `density` | `compact` | 节点多、想省高度；也用于课件一页塞下 |
+| | `normal` | 默认 |
+| | `roomy` | 概念少、要强调层级呼吸感（章节扉页） |
+
+### 3.2 主题一览
+
+| theme | 底色 | 适用 |
+|---|---|---|
+| `paper` | 白 | 通用印刷稿（默认） |
+| `aero` | 冷白 `#fbfdff` | 工科/工程类正文 |
+| `ink` | 白，全灰阶 | 黑白印刷、投稿 |
+| `warm` | 暖砂 `#fdf8f0` | 人文/导读 |
+| `forest` | 浅绿 `#f5f9f3` | 材料/工艺/生态 |
+| `slate` | 深色 `#22262e` | 深色课件、投屏 |
+| `contrast` | 白 + 纯黑线 | 投影/打印质量差时最保险 |
+
+### 3.3 CLI 覆盖（不改源文件也能换皮）
+
+```bash
+node render.mjs src.mmd --out out.svg --theme ink --layout both --density compact --transparent --scale 1.1
+node render.mjs src.mmd --json        # 只报 节点数 / 层数 / 画布尺寸，先量再定
+node render.mjs --help                # 全部选项
+```
+
+---
+
+## 4. 入稿规范
+
+### 4.1 落盘位置与命名
+
+* 图片进该库的图片目录（正文里 `image::` 相对路径的根），**文件名按页面编号**，
+  便于与正文对照：`<页号>-mindmap.svg`。
+* 大纲源文件放在**正文页旁边**，与页面同名（`<页面名>.mmd`）。
+  `.mmd` 不是库清单 `library.yaml` 声明的扩展名，因此**不会挤进阅读目录**；
+  结构检查器一般也只扫声明过的扩展名，不会报"图片未被引用"。
+* **两者必须同 commit**：改了正文没重渲染，读者看到的还是旧结构。
+* 一库多图时统一放一个图片目录下，别散在各分卷里（否则整卷汇编时 `imagesdir` 会打架）。
+
+### 4.2 正文写法（图注三要素：图意 / 怎么读 / 反例）
+
+```asciidoc
+[[fig-<页号>-<序号>]]
+.图 <页号>-<序号>　一句话说清这张图画的是什么（自绘；源文件 `<页面名>.mmd`，改正文请一并改图）
+image::<相对路径>/<页号>-mindmap.svg[width=100%]
+
+**图意**：这张图把什么结构摊开了。**怎么读**：从哪个节点进、沿什么方向走、每个叶子代表什么。
+**反例**：什么用法会读错（有的话写上，比"注意"有用）。
+```
+
+* 路径一律**相对页面所在目录**写，别用库根绝对路径。
+* **不要**把图块写成 `[plantuml]` / `[mermaid]` / `[source]`——阅读器不认，会退化成纯文本。
+
+### 4.3 尺寸红线（最容易踩）
+
+阅读器书籍版式版心约 `42em`，扣掉内边距后**正文可显示宽度 ≈ 580–600 px**。
+SVG 宽度超过这个值会被等比缩小，**字号跟着缩水**：
+
+| SVG 宽度 | 折到 590px 后的缩放 | 13.6px 叶子字实际渲染 | 判断 |
+|---|---|---|---|
+| 580–640 | 1.00 | 13.6px | ✅ 最佳 |
+| 640–760 | 0.92 | 12.5px | ✅ 可接受 |
+| 760–1000 | 0.78 | 10.6px | ⚠️ 只有配合"点图放大"才勉强 |
+| > 1000 | ≤0.59 | ≤8px | ❌ 换 `layout: right` 或瘦身节点 |
+
+`--json` 打印的 `width` 就是这条红线要看的数。要更宽只能改版心（阅读设置）或拆成两张图。
+
+---
+
+## 5. 验收（写完必跑）
+
+1. **渲染不报错**：`node render.mjs <src> --out <svg> --json` → 有 `nodes/width/height`、无异常。
+2. **图存在且被引用**：跑该库自带的结构检查（若有）；"图片缺失"与"图片未被引用"都应清零。
+   库清单本身用套件自带的校验器：
+   ```bash
+   npx --yes @dongfangw/library-core validate .     # 在库根执行，零 error 才算过
+   ```
+3. **目视**：把 SVG 拖进浏览器（或点阅读器里的图放大），看三件事——
+   ① 分支文字**不换行**（换行 = 该层 `maxWidth` 给小了）；
+   ② 叶子**不顶出**框（顶出 = 该类给了 `sw` 描边但宽度按无框算，调 `padX`）；
+   ③ 图注与正文对得上（改了判据数值，图必须同改）。
+
+---
+
+## 6. 常见故障
+
+| 现象 | 原因 | 修法 |
+|---|---|---|
+| 分支文字被拦腰折行 | `maxNodeWidth` 对一级节点也生效 | 给 `levels[1]` 单独写 `maxWidth`（如 200） |
+| 胶囊两端把字吃掉 | 胶囊端头是半圆，横内边距要 ≥ h/2 | 渲染器已按 `padX ≥ h*0.51` 自动兜底；手写 `padX` 别给太小 |
+| 公式行溢出 / 字符叠在一起 | `$...$` 不是 SVG 文本，不会被渲染 | 用 Unicode 写（`α` `ε` `Λ` `∈` `²`），或 `<br/>` 手动断行 |
+| 图宽 2000px，字小成蚂蚁 | 用了 `tree` 或 `both` 还塞了 6 条分支 | 换 `layout: right`；或拆成两张图 |
+| 深色阅读主题下图是白底卡片 | SVG 自带底 | `--transparent` 重渲染（文字色取主题墨色，深色下仍可读） |
+| 改了正文，图还是老的 | 忘了重渲染 | 把"渲染"写进改稿步骤；`.mmd` 与正文同 commit |
+| YAML 解析报错 | 值里有冒号/井号没引号 | 加引号：`title: "流程：六步"` |
+| `未知 theme/layout/connector` | 枚举值拼错 | 按 §3 表里的字面量写，大小写敏感 |
+
+---
+
+## 7. 与其它技能的分工
+
+| 场景 | 用哪个 |
+|---|---|
+| 正文里某卷/某章的**结构图、设计链、学习路线** | **本技能**（产物进图片目录，正文用 `image::` 引用） |
+| 课件里的一页思维导图 | 本技能出 SVG → 课件技能引用；课件里禁手写字符画 |
+| 学生问"知识地图/学习路线"要**讲解**（不落盘） | `aero-learning-path`（可顺手调本技能出图） |
+| 正文内容本身的撰写/扩写 | 写作类技能（本技能只管"把结构画出来"） |
+
+判据只有一句：**读者要在正文里看到一个层级结构时，正文里不应该出现等宽字符画的树。**

package/skills/make-mindmap/example//347/244/272/344/276/213.mmd

@@ -0,0 +1,45 @@
+---
+# 示例：一份最小可用的思维导图大纲（同时是配置项的活样例）
+#
+# 自检：node render.mjs example/示例.mmd --out /tmp/smoke.svg --json
+# 想换皮就加 --theme / --layout / --connector / --density，不必改本文件。
+title: 从大纲到插图
+subtitle: 三步工作流与它的三条硬约束
+layout: right
+theme: paper
+connector: curve
+density: normal
+numbering: circled
+shape: rounded
+footnote: 本文件只演示语法与配置，不是任何课程的内容
+font:
+  size: 15
+  lineHeight: 1.34
+maxNodeWidth: 190
+rootMaxWidth: 260
+gap:
+  level: 30
+  sibling: 6
+  branch: 20
+levels:
+  - {size: 19, weight: 700, padX: 17, padY: 9}
+  - {size: 14.8, weight: 650, padX: 9, padY: 6, maxWidth: 200}
+  - {size: 13.6, weight: 500, padX: 10, padY: 4.5}
+classes:
+  warn: {stroke: '#c8786d', sw: 1.1, fill: '#fdf3f1', color: '#8a1f1f'}
+  key: {stroke: '#7aa6dc', sw: 1.1, fill: '#eef4fc', weight: 650}
+---
+mindmap
+  root((思维导图插图))
+    写大纲
+      缩进即层级，项目符号会被忽略
+      形状可选：圆、圆角、方框、六边形
+      行尾 :::类名 挂样式
+    渲染成 SVG
+      零依赖，纯 Node
+      先 --json 量宽高再定稿 :::key
+      宽度超过版心就会被缩小 :::warn
+    接入正文
+      图片语法引用，相对页面目录写路径
+      图注写清「图意 / 怎么读 / 反例」
+      源文件与正文同 commit :::warn