generate-mindmap

生成基于认知科学方法论的交互式思维导图。支持 Markdown 大纲或 JSON 输入，一条命令同时导出 HTML（可交互编辑、8 种布局、深浅双主题）、PNG、JPG、SVG、PDF、XMin...。生成基于认知科学方法论的交互式思维导图。支持 Markdown 大纲或 JSON 输入，一条命令同时导出 HTML（可交互编辑、8 种布局、深浅双主题）、PNG、JPG、SVG、PDF、XMin。触发关键词: 生成基于认知, generate, xmin, 科学方法论的, html, 支持, mindmap, 大纲或。

把内容提炼成放射状知识结构，一条命令导出多种格式。核心特色：

• Markdown 大纲直接输入 —— 不必手写 JSON，也没有 shell 引号转义问题
• 一次生成多格式 —— --format html,png,xmind 一条命令搞定
• 深空 / 纸墨双主题 —— --theme midnight|paper，HTML 内还有 🌓 一键切换
• 结构质检报告 —— 自动按认知负荷·双重编码·渐进分化·MECE·概念图关系等原则检查，输出改进建议
• 交互式 HTML —— 双击编辑、Enter 加兄弟 / Tab 加子节点、拖到另一节点上改挂父子关系、拖到空白处按位置重排兄弟顺序（拖动后始终自动整齐布局，不会拉乱连线）、拖根平移全图、8 种布局、右键菜单；节点标签超过 20 字符自动省略（…）保持版面整洁，双击节点在编辑框中查看并修改完整内容；点「HTML」按钮绑定文件后，之后每次改动自动写回该 HTML 文件（Chrome/Edge），不支持时回退为下载含全部编辑的自包含文件

使用流程

步：按 提炼结构，写入一个 Markdown 大纲文件（避免把内容塞进 shell 参数——引号和特殊字符会出问题）：

bash

cat > /tmp/mindmap_outline.md << 'EOF'

## 🔬 维度一 [#4A90D9]
- 具体证据 A
- 量化数据 B
  - 更具体的事实

## 💰 维度二 [#27AE60]
- 证据 C
- 证据 D
EOF

语法规则：# 一级标题 = 中心节点；## = 主分支（可在行尾用 [#十六进制] 指定颜色）；- 列表按缩进（2 空格一层）嵌套为子节点。也可以省略 # 标题，此时 --title 会作为中心节点。

第二步：一条命令生成全部格式：

bash

python3 {baseDir}/generate_mindmap.py \
  --title "主题名" \
  --format html,png,xmind \
  --data-file /tmp/mindmap_outline.md \
  --output "主题名.html"

--output 只需给一个路径，其余格式自动换扩展名。省略 --output 时自动选择输出目录：$MINDMAP_OUTPUT_DIR → /mnt/user-data/outputs（ 沙箱）→ ~/.skill-platform/workspace（Skill平台）→ 当前目录。

第三步：查看 stderr 中的质检报告（📋 一行摘要 + ⚠ 警告）。如出现警告（分支超过 6 个、总节点超 40、标签过长、单子节点分支等），先修改大纲再重新生成，不要把警告丢给用户。

第四步：向用户汇报，必须包含脚本 stdout 中 ✅ ... → 路径 的完整绝对路径，并说明各格式用途：HTML 浏览器打开可交互编辑（双击改文字、Enter 加兄弟节点、Tab 加子节点、把一个节点拖到另一个节点上可改变其父子归属、拖动中心节点平移整图、右上角切主题；点「HTML」按钮绑定文件后，在 Chrome/Edge 中之后的改动会自动保存回该文件，其它浏览器则每次点按钮另存为含全部改动的新文件）、PNG 直接嵌入文档分享、XMind 可在 XMind 软件继续编辑。

输入格式

Markdown 大纲（首选，见上）。JSON（需要精确控制时）：

json

{
  "central": "核心洞见",
  "branches": [
    {"label": "🔬 维度一", "color": "#4A90D9",
     "children": ["证据A", {"label": "证据B", "children": ["事实1", "事实2"]}]}
  ]
}

JSON 也通过 --data-file 传入（自动识别 JSON / Markdown）；--data-file - 读 stdin；--data '...' 仅限极短内容。主分支若缺 emoji，脚本会按语义关键词自动补充。

命令参考

参数	说明
--title	必填。导图标题（大纲无 # 标题时兼作中心节点）
--data-file	数据文件路径（JSON 或 Markdown），- 为 stdin
--data	内联数据字符串（仅限短内容）
--format	逗号分隔多格式：html,svg,png,jpg,pdf,xmind（默认 html）
--theme	midnight 深空（默认）/ paper 纸墨（适合打印、白底文档）
--output	输出路径；多格式时自动换扩展名；省略则用自适应工作目录
--scale	PNG/JPG/PDF 像素密度，默认 2.0
--quality	JPG 质量 1–100，默认 92
--no-lint	关闭质检报告
--no-auto-install	禁止自动安装 Pillow，仅打印安装指引

内容设计四步法

完整的认知科学依据（Buzan 放射性思考、Paivio 双重编码、Miller/Sweller 认知负荷、语义网络、Ausubel 渐进分化、MECE 完全穷尽、Novak 概念图关系）与详细规范见 {baseDir}/references/methodology.md——生成前先读它。执行时的硬约束：

1. 中心节点 = 核心洞见，不是话题标签。✅ "AI 正从工具变为协作者"；❌ "AI 发展趋势"。
2. 主分支 3–6 个 = 理解维度，不是原文章节。同级抽象层次一致，每个分支带一个不重复的 emoji，颜色与语义一致（蓝=机制、绿=成果、橙=问题、紫=背景、黄=资源、青=流程、红=警告）。定稿前做 MECE 自检：这些维度是否完全穷尽了主题、有无遗漏或重叠（总结类任务尤其关键）。
3. 子节点 = 具体证据（机制、数据、案例、对比、行动、限制），每分支 2–5 个，优先可想象的具体词。渐进分化：从中心到叶子概括度逐层递减，不出现"子节点比父节点更宽泛"的倒挂。
4. 节点 4–12 字、全图 ≤ 40 节点、≤ 4 层。主题内在复杂度过高时拆成多张图而非硬压缩。生成后核对质检报告（会提示 MECE、渐进分化、关系型表述等）。

关系表达（概念图）：内容里若是因果/时序/对比/条件等非从属关系，别硬塞进父子层级——因果优先鱼骨图、时序优先时间线，或在措辞里保留关系词（"导致""优于""若…则"），避免把关系信息压扁丢失。

按内容类型选维度框架与布局：分析类"是什么·为什么·怎么做·结果"（左右均衡）；问题解决"根因·影响·方案·评估"（鱼骨图）；学习类"概念·机制·场景·误区"；项目类"目标·策略·执行·风险"（树形）；时间/流程类按顺序（时间线）；头脑风暴自由发散（辐射/力导向）。布局在 HTML 中随时可切换。

依赖说明

• 零系统级 C 库依赖。 HTML/SVG/XMind 纯 Python；PNG/JPG/PDF 需 Pillow（pip install pillow）。若检测到 Playwright 则优先用它渲染 PNG/JPG（质量更高、保留 emoji）。
• Pillow 缺失时脚本会尝试 pip install pillow（先普通安装、再 --user，绝不使用 --break-system-packages）；在受管环境失败会打印指引。共享或锁定环境请加 --no-auto-install 并让用户自行安装。
• Pillow 后备渲染会去掉 emoji（系统字体不含彩色 emoji）；若用户在意 emoji 的图片效果，安装 Playwright 或让用户在 HTML 中用浏览器导出。
• 中文乱码/方块：Pillow 渲染依赖系统 CJK 字体（微软雅黑 / PingFang / Noto CJK），Linux 无 CJK 字体时建议 apt install fonts-noto-cjk。

示例

{baseDir}/examples/：ai_trends.html、product_launch.html、python_learning.html（可直接用浏览器打开体验交互与主题切换），以及对应 .json 数据和 outline_example.md 大纲示例。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent( Code / Cursor / Codex / CLI等)
• 操作系统: Windows / macOS / Linux

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

• 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)

可用性分类

• 分类: MD+execute(纯Markdown指令,部分功能需要exec命令行执行能力)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务

核心能力

• 生成基于认知科学方法论的交互式思维导图
• 支持 Markdown 大纲或 JSON 输入，一条命令同时导出 HTML（可交互编辑、8 种布局、深浅双主题）、PNG、JPG、SVG、PDF、XMin
• 触发关键词: 生成基于认知, generate, xmin, 科学方法论的, html, 支持, mindmap, 大纲或

适用场景

场景	输入	输出
基础使用	用户请求	处理结果

不适用于：需要人工判断的复杂决策场景

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	检查网络连接后重试，参考国内替代方案

常见问题

Q1: 如何开始使用Generate Mindmap？

A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。

Q2: 遇到错误怎么办？

A: 请参考错误处理章节，按照表格中的处理方式操作。

Q3: Generate Mindmap有什么限制？

A: 请参考已知限制章节了解具体限制。

已知限制

• 需要LLM支持，无LLM环境无法使用
• 复杂场景可能需要人工辅助判断
• 性能取决于底层模型能力