Imported from soft-zihan/project-mindmap-AIteacher-skill (
SKILL.md). Install upstream withnpx skills add soft-zihan/project-mindmap-AIteacher-skill. Copyright stays with the author.
思维导图教程系统 (Mindmap Tutorial)
为代码项目创建结构化的思维导图教程，帮助快速理解复杂系统架构和实现细节。
产出物
mindmap/
├── mindmap.html # 渲染页面（markmap + marked + mermaid + AI 侧边栏）
├── server.py # 本地服务器（静态文件 + AI API 代理）
└── mindmaps/ # 导图内容文件
├── 01-overview.md # 系统总览
├── 02-xxx.md # 各模块详解
└── ...
执行流程
Phase 0: 收集参数
询问用户（使用 AskUserQuestion）：
- 项目路径 — 本地项目目录的绝对路径
- 模块划分 — 根据源码分析，建议模块划分方案，让用户确认
- AI 问答助手 — 是否启用？（默认：否）
- 如果启用，询问：
- API Base URL — OpenAI 兼容端点
- Model name — 模型名称
- API Key — API 密钥
- 如果启用，询问：
Phase 1: 项目扫描
- 读取项目目录结构，识别语言和框架
- 读取关键配置文件（package.json / pom.xml / go.mod 等）
- 读取 README（如有）
- 识别核心模块和入口文件
Phase 2: 源码分析
对每个模块：
- 读取核心源文件
- 提取：类/方法、数据流、设计决策、边界处理
- 记录专业术语和缩写
Phase 3: 生成导图文件
为每个模块创建一个 .md 文件，格式如下。
Phase 4: 生成模板文件
- 复制
references/template.html到mindmap/mindmap.html - 替换占位符
{{PROJECT_NAME}}和{{PROJECT_DESC}} - 复制
references/server.py到mindmap/server.py - 替换占位符
{{API_URL}}、{{API_KEY}}、{{API_MODEL}}
Phase 5: 启动服务
cd mindmap/
python3 server.py
# 访问 http://localhost:8765/mindmap.html文件格式规范
每个 .md 文件用 --- 分隔为两部分：
第一部分：导图内容（markmap 渲染）
# 模块标题
## 一级概念
### 二级概念
- 三级概念（细节）
- 四级概念（更细节）要求：
- 使用 markdown 标题（
######）和列表（-）构建层级 - 每个专业术语首次出现时必须解释
- 英文缩写必须给出全称和中文含义
- 变量名、类名必须说明用途
第二部分：辅助面板（案例 + 图表）
---
## 架构图/流程图
（mermaid 代码块）
## 案例：XXX 的完整流程
### 案例在整体流程中的位置
（mermaid 图，高亮标注案例覆盖的步骤）
### 场景
（具体场景描述）
### Step 1: ...
（详细步骤，包含具体数据）
### 边界情况
（各种异常场景）要求：
- 案例必须与导图节点一一对应
- 从上到下顺序一致（导图流程 → 案例步骤）
- 每个步骤展示具体输入/输出数据
- 覆盖正常情况和边界情况
面试问答标记
在导图节点中嵌入面试问答，用红色字体标记：
- <font color="#e74c3c">🎤 面试：为什么采用这种架构？</font>
- 原因 1：...
- 原因 2：...要求：
- 面试问答嵌入到对应概念节点下，不是单独一个 section
- 每个模块至少包含 2-3 个高频面试问题
- 答案要具体，包含设计决策的原因
术语解释规范
必须解释的内容：
- 专业术语：如 ReAct、CQRS、Saga 等
- 英文缩写：如 DAG、AST、LLM 等
- 类名/变量名：如 UserRepository、orderStatus 等
- 技术概念：如 Map-Reduce、滑动窗口等
解释格式：
- ReAct（Reasoning + Acting）：一种让模型交替进行推理和行动的模式
- CQRS（Command Query Responsibility Segregation）：命令查询职责分离案例编写规范
结构要求
- 位置图：案例开头用 mermaid 图标注在整体流程中的位置
- 步骤对应：每个步骤对应导图中的一个节点
- 具体数据：展示具体的输入/输出 JSON、数值、状态变化
- 边界情况：至少覆盖 3-5 种异常场景
示例结构
## 案例：用户下单的完整流程
### 案例在整体流程中的位置
（mermaid 图，高亮标注案例覆盖的步骤）
### 场景
用户点击"下单"按钮，订单包含 2 件商品，总价 199 元...
### Step 1: 参数校验
（展示请求 JSON、校验逻辑、错误处理）
### Step 2: 库存扣减
（展示 Redis 操作、分布式锁、回滚逻辑）
### 边界情况
#### 情况 1：库存不足
（展示错误码、用户提示）
#### 情况 2：支付超时
（展示订单状态变化、库存回滚）AI 问答侧边栏
架构
AI 侧边栏采用内联面板设计（非悬浮），通过代理服务器解决 CORS 问题：
浏览器 → server.py (代理) → 实际 API 端点
上下文策略
- 普通页面：AI 获取当前页面的完整 markdown 内容（导图 + 案例）
- 系统总览页：AI 获取所有文档页面的内容（最多 12000 字符）
功能特性
- 流式输出（streaming）
- Markdown 渲染（代码块、表格、列表等）
- 对话历史（保留最近 10 条）
- 清空对话功能
- 快捷建议按钮
内容质量标准
必须做到
- 与源码一致：所有类名、方法名、流程必须与源码一致
- 术语全解释：每个专业术语首次出现时都有解释
- 案例完整：覆盖正常流程和边界情况
- 结构对应：导图和案例从上到下顺序一致
- 面试覆盖：每个模块包含高频面试问题
常见错误
- ❌ 类名与源码不一致
- ❌ 术语不解释（如直接写 CQRS 不说明含义）
- ❌ 案例与导图不对应
- ❌ 案例步骤编号跳跃
- ❌ 面试问答单独成节
检查清单
创建完成后，逐项检查：
- 每个专业术语首次出现时都有解释
- 每个英文缩写都给出全称和中文含义
- 面试问答用红色字体标记并嵌入概念节点
- 案例与导图节点一一对应
- 案例开头有位置图
- 案例步骤编号连续
- 案例覆盖正常流程和边界情况
- 所有类名、方法名与源码一致
- 导图和案例从上到下顺序一致
- AI 侧边栏配置正确
- HTTP 服务可以正常访问
参考文件
references/template.html：HTML 模板（含 AI 侧边栏）references/server.py：代理服务器模板references/example-overview.md：系统总览页示例references/example-module.md：模块详解页示例