/mindmap-zh

name: mindmap-zh
user-invocable: true
description: 从文件、URL、粘贴的文本或一个主题生成可交互的 Markmap 思维导图（中文版）。
allowed-tools: Bash, Read, Write, Glob, WebFetch

思维导图技能 — 生成可交互的 Markmap

触发方式

`/mindmap-zh <输入> [--render] [--output <路径>]`

`<输入>` 为以下之一：

• **文件路径** — 读取该文件并生成导图
• **URL**（`http://` 或 `https://`）— 抓取页面内容并生成导图
• **粘贴的文本 / 笔记** — 直接对文本生成导图
• 一个简短的**主题** — 基于模型自身知识生成导图

参数：

• `--render` — 写出 `.md` 后，额外生成一个独立的可交互 `.html`
• `--output <路径>` — 将 `.md` 写到指定路径，而非默认路径

> **跨平台说明：** 本技能使用 Claude Code 的工具名（`Read`、`Write`、`Glob`、`Bash`、`WebFetch`）。在 **GitHub Copilot CLI** 上请使用对应工具（`view`、`create`、`glob`、`bash`、`web_fetch`）——见 [`references/copilot-tools.md`](references/copilot-tools.md)。两个平台上的工作流完全一致。

工作流

第 1 步：判定输入类型

先去除参数，再对剩余部分分类并加载内容：

1. 若是 **URL**（以 `http://` 或 `https://` 开头），用 **WebFetch** 抓取（要求其返回页面正文）。抓取到的内容即为内容。**优先**判断此项，先于文件/文本/主题规则。 2. 否则，若是一个**已存在文件**的路径，用 Read 读取。其内容即为内容。 3. 否则，若是**较长或多行的文本**（大致 > 12 个词，或包含换行），按**原始文本**处理。该文本即为内容。 4. 否则按**主题**处理：基于模型自身知识生成内容。

遇到以下情况，停下来询问用户（切勿擅自猜测）：

• **URL 抓取失败**（网络错误、被拦截、或页面为空）→ 报告情况并询问：是否改为基于自身知识对该页面主题生成导图，或换一个 URL？不要凭空编造页面内容。
• **看起来像文件路径**（以 `.md`/`.txt` 结尾，或包含 `/` 或 `\`）但**文件不存在** → 报告 `未找到文件：<路径>`，并询问：改为按主题生成，还是修正路径？
• 输入为**空或仅有空白字符** → 请用户提供内容或主题。
• 输入**确实有歧义**（一个既可能是文本、也可能是主题的短语）→ 默认按**主题生成**，并用一句话说明你的假设，以便用户纠正。

第 2 步：构建层级结构（混合策略）

将内容转化为节点层级：

• 若内容**本身已有结构**（清晰的标题 / 项目符号大纲）：沿用其大纲，但**把每个节点压缩为简短短语**（≤ 约 8 个字词）。不要逐句照抄。
• 若内容是**无结构**的文本或一个**主题**：提取关键概念，归纳为 **4–7 个主分支**，每个分支配简洁的子要点。

规则：

• **深度：** 目标 3–4 层。
• **用短语而非句子：** 每个节点都是简短标签。
• **可读性优先于完整性：** 对篇幅很大的来源，映射其结构与要点——而非每一行。对无结构/主题/大型来源，目标 **4–7 个主分支**；当来源本身已有结构时，则沿用其自身大纲。大胆精简。

第 3 步：写出 Markmap `.md`

按下文 **Markmap 格式** 所示的样式写出文件。

输出路径：

• 文件输入 `foo.md` → `foo.mindmap.md`（同目录）。
• URL 输入 → 取页面标题的 slug（或 URL 最后一段路径）→ 当前目录下的 `<slug>.mindmap.md`。
• 文本输入 → 取导图 H1 标题的 slug → 当前目录下的 `<slug>.mindmap.md`（slug 规则同主题）。
• 主题输入 → 当前目录下的 `<主题-slug>.mindmap.md`（slug = 小写，空格 → `-`）。
• `--output <路径>` 覆盖默认路径，按所给值写出。
• **写入前，用 Glob 检查目标是否已存在。** 若已存在，在 `.mindmap.md` 前插入计数 — `<名称>-2.mindmap.md`、再 `<名称>-3.mindmap.md`……取第一个未被占用的名称。显式 `--output` 路径同样适用此后缀规则。**切勿静默覆盖已有文件。**

写入后，告诉用户确切路径以及查看方式：在 https://markmap.js.org 打开，或使用 VS Code 的 “Markmap” 扩展。

第 4 步（仅当带 `--render`）：渲染为 HTML

`render.sh` 位于本 SKILL.md 同级的 `scripts/` 文件夹内。若你尚不知其绝对路径，用 Glob 定位（`**/skills/mindmap-zh/scripts/render.sh`），再按该路径运行：

bash <skill-dir>/scripts/render.sh "<输出.md>"

• 成功时，它会在 stdout 打印 `.html` 路径——请告知用户。
• 若返回非零（例如未安装 `npx`，退出码 3），`.md` 仍是有保证的交付物。告诉用户已跳过渲染，并展示它打印的手动命令（退出码 3 的“缺少 npx”情形会打印一条）。**不要**把这视为整个任务的失败。

Markmap 格式

按如下样式写出 `.md`：

---
title: <导图标题>
markmap:
  colorFreezeLevel: 2
  maxWidth: 300
---

# <中心主题>

## <分支 1>
- <要点>
  - <子要点>
- <要点>

## <分支 2>
- <要点>

• 有且仅有**一个 `#` 一级标题**——根 / 中心主题。
• `##` 二级标题 = 主分支；`###` 与 `-` 列表项 = 更深层级。
• 行内 markdown（`**加粗**`、`` `代码` ``、链接）允许使用并会原样传递。
• 保持 frontmatter 默认值（`colorFreezeLevel: 2`、`maxWidth: 300`）不变。

示例

输入（一段有结构的片段）：

> # 检索增强生成（RAG） > ## 索引 > 切分文档、做嵌入、存储向量。 > ## 检索 > 对查询做嵌入，找到最近邻的片段。 > ## 生成 > 把检索到的上下文注入提示词。

输出 `检索增强生成.mindmap.md`：

---
title: 检索增强生成（RAG）
markmap:
  colorFreezeLevel: 2
  maxWidth: 300
---

# 检索增强生成（RAG）

## 索引
- 切分文档
- 嵌入片段
- 存储向量

## 检索
- 对查询做嵌入
- 找到最近邻片段

## 生成
- 注入上下文到提示词

说明

• 默认路径**无需依赖**（仅用 Read/Write；URL 输入还会用到 WebFetch）。
• `--render` 需要 Node.js / `npx`（使用 `npx markmap-cli`，无需全局安装）。