Mindmap Zh

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

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

## 触发方式
`/mindmap-zh <输入> [--render] [--output <路径>]`

这里使用斜杠命令表示调用方式，并非要求宿主提供特定 API。若宿主不支持斜杠命令，请通过其支持的机制调用 `mindmap-zh` 技能，传入相同的输入和参数。

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

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

## 智能体能力要求

使用当前会话中可用的工具完成下列操作，不要求特定工具名称。遵守宿主的权限和审批规则；安装技能不会授予额外权限。

| 操作 | 所需能力 |
|---|---|
| 基础 `.md` 输出 | 检查路径并创建文件；文件输入还需读取文件。 |
| URL 输入 | 使用可用的网页获取能力读取页面正文。 |
| `--render` | 执行命令，且运行所附脚本的环境具备 Bash 和 Node.js / `npx`。 |

若无法检查或写入文件，请说明缺失的能力或权限，并询问用户如何继续，不要声称文件已保存。网页访问或渲染不可用时，按对应步骤处理。

## 工作流

### 第 1 步：判定输入类型
先去除参数，再对剩余部分分类并加载内容：

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

遇到以下情况，停下来询问用户（切勿擅自猜测）：
- **网页访问不可用或 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 <路径>` 覆盖默认路径，按所给值写出。
- **写入前，使用可用的文件系统检查能力检查目标是否已存在。** 若已存在，在 `.mindmap.md` 前插入计数 — `<名称>-2.mindmap.md`、再 `<名称>-3.mindmap.md`……取第一个未被占用的名称。显式 `--output` 路径同样适用此后缀规则。**切勿静默覆盖已有文件。**

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

### 第 4 步（仅当带 `--render`）：渲染为 HTML
`render.sh` 位于已安装的本 SKILL.md 同级的 `scripts/` 文件夹内。根据宿主提供的技能位置或可用的文件查找能力定位它，再使用命令执行能力按绝对路径运行：

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

- 若无法执行命令、找不到脚本，或缺少 Bash / Node.js / `npx`，保留 `.md` 并明确说明未生成 HTML 的原因。提供 `npx --yes markmap-cli "<输出.md>" -o "<输出.html>" --no-open` 手动命令，代入实际输出路径，供用户在具备 Node.js 的环境中执行。不要声称 HTML 文件已生成。
- 成功时，它会在 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）

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

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

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

## 说明
- 默认路径**无需额外运行时依赖**，只需文件系统操作能力；URL 输入还需网页访问能力。
- 自动执行 `--render` 需要命令执行能力、Bash 和 Node.js / `npx`（使用 `npx markmap-cli`，无需全局安装）。