转载请注明出处❤️

作者：测试蔡坨坨

原文链接：caituotuo.top/44c6d4ca.html

1 背景

你好，我是测试蔡坨坨。

最近被 AI 生成的长文档折磨得很痛苦。

你应该也遇到过类似的场景：让 AI 帮你整理需求、生成方案、补充测试点，结果它很听话，一口气给你吐出几千行 Markdown。内容看起来挺全，但真正 Review 的时候，人就麻了。

线性文本太难建立全局结构。你想知道某段逻辑属于哪个模块、有没有前置条件、异常分支前后有没有遗漏，就只能上下翻。翻着翻着，脑子里的结构断了，Review 变成了体力活。

于是我用 Vibe Coding 做了一个小工具：CC MD MindMap。

它把 Markdown 文档变成可导航、可编辑、可标记的思维导图，让你从「从头读到尾」变成「按结构找问题」。

界面组成：

2 为什么做这个？

以前我们写文档，通常是边想边写。结构大概率在自己脑子里。

现在不一样。AI 可以很快生成一份看起来完整的需求说明、测试方案、技术调研、接口文档。但它的问题是：长度起来了，但你对结构没有参与感。

3 它是什么？

CC MD MindMap 通过思维导图将 Markdown 转为可导航的结构化视图，并支持节点状态标记，帮助用户降低长文档的阅读和 Review 成本。

Markdown 仍是唯一数据源，导图与源码实时联动，无需维护两份文件。

它有两种运行方式：

服务端模式（可选）：

如果要启用 AI 对话能力，需要先在项目目录下创建 .env 文件：

1
2
3
4

OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://api.openai.com
CC_MD_MINDMAP_USER=your-user
CC_MD_MINDMAP_PASSWORD=your-password

其中 OPENAI_API_KEY 是必填项。

OPENAI_BASE_URL 可以指向兼容 OpenAI Responses API 的服务地址。CC_MD_MINDMAP_USER 和 CC_MD_MINDMAP_PASSWORD 同时设置后，会启用登录校验。

然后运行部署脚本：

1

bash deploy.sh

Windows 用户可以用：

1

deploy.cmd

启动后访问：

1

http://127.0.0.1:8787/

日志会输出到 ai-proxy.log。

市面上的方案对比

我也调研了一下市面上的解决方案，没有一款完全合适。

4 功能简介

4.1 支持打开文件/文件夹

工具支持打开单个或多个 Markdown 文件，也支持直接打开一个文件夹，递归读取里面的 Markdown。

你也可以把文件或文件夹拖到页面上加载。

在 Chromium 系浏览器里优先使用 File System Access API，用户授权后修改可以直接写回原文件。

这里有个细节我很喜欢：文件句柄会记录在 IndexedDB 里，项目快照和偏好会记录在 localStorage 里。下次打开时，能尽量恢复之前的工作状态。

4.2 Markdown 解析规则

CC MD MindMap 会把常见 Markdown 元素转成导图节点：

你不需要学新格式。原来怎么写 Markdown，现在还怎么写，工具只是多给你一张结构图。

4.3 在导图上直接编辑

CC MD MindMap 支持直接在导图上编辑节点，实时同步到 Markdown 源码，不用来回切视图：

拖拽这一点对梳理文档很有用。拖到节点中部会成为子节点，拖到上/下边缘则插入为同级（前或后）。工具会根据父节点类型自动调整输出格式——父节点是标题就生成标题，是列表项就生成列表项。

4.4 给节点打状态标识

这是我做这个工具时最想要的功能。

Review 文档不是一次性读完就结束，工具内置了 3 种节点状态：

状态以节点左侧色条、节点内标识、顶部统计数字三处体现，并写回 Markdown。提交到 Git，别人也能看到这些标记。

如果你想批量处理，可以用 Cmd/Ctrl + 点击 做多选，然后按 1 / 2 / 3 批量打状态，按 0 清除状态。

工具栏还有「上一个/下一个已标识节点」导航按钮，点击后自动展开祖先路径并滚到可见区域。文档里标了二十个问题点，不用自己找，逐个跳过去就行。

4.5 节点备注

有些 Review 结论不适合直接写进正文，比如：

• 「这里需要找后端确认」
• 「这个逻辑和上周版本不一致」
• 「这个异常分支要补一个用例」

工具支持给节点添加备注，备注会序列化成 HTML 注释：

1

<!-- note: 这里需要找后端确认 -->

普通阅读时基本无感，工具解析时能拿出来用，也不会把 Review 信息塞进正文里弄脏文档。

4.6 搜索、过滤和 Review 模式

CC MD MindMap 的搜索围绕节点结构做了处理，不只是定位某一行文本。

4.6.1 搜索会保留上下文

顶部搜索框可以用 Cmd/Ctrl + F 聚焦。

搜索时会匹配节点正文和表格单元格，大小写不敏感。命中节点会高亮，非命中节点会淡化。

如果命中内容藏在折叠分支里，工具会自动展开对应路径。

这个体验比纯文本搜索舒服一些，因为你看到的不只是某一行，而是它在整份文档里的位置。

4.6.2 状态过滤适合做收尾

搜索框旁边有 ✅ / ❌ / ⏳ 这 3 个 chip，可以按状态过滤节点。

比如你只想看所有 ❌ 问题节点，就点一下 ❌。

如果要看「待处理 + 问题」，就同时选 ⏳ 和 ❌。

这对测试 Review 很有用。开会前，你可以直接拉出所有问题点；收尾时，只看还没处理完的节点。

4.6.3 Review 模式只看被标记的内容

Review 模式更狠一点：它只显示已标识节点及其祖先路径，其他节点直接隐藏。

比如一份需求文档有 200 个节点，你标了 12 个问题点。普通模式下，这 12 个点仍然散在文档里；Review 模式下，你能直接看到它们在结构中的位置。

旁边还有 Review 摘要面板，会按状态分组列出当前文件所有已标识节点，并显示祖先路径。点击某一条，就能跳回对应节点。

4.7 源码与导图双向联动

我一直觉得，文档工具最怕「两个视图各玩各的」。

如果你在源码里改了一段文字，导图没反应；或者你点了导图节点，源码不知道该滚到哪里，那用几次就会放弃。

CC MD MindMap 做了三类联动：

右侧源码面板有 3 种模式：

• 源码：直接编辑 Markdown。
• 渲染：看 Markdown 渲染效果。
• 分栏：源码和渲染预览同时显示。

分栏模式下，源码 textarea 和渲染预览会做双向滚动同步。读长文档时，这个细节能少很多来回找位置的动作。

源码编辑也保留了一些常用快捷键：

4.8 导出与分享

你在本地看得很爽，但别人没装环境怎么给他看？

CC MD MindMap 提供了 3 种导出方式：

导出独立 HTML 这个功能挺适合 Review 交付。

你可以把当前 Markdown 内容和 md-mindmap.html 打包到一个 HTML 文件里，对方双击就能看到当时的脑图状态，不需要部署服务。

4.9 文件树管理

左侧文件树不只是展示已加载的文件，还支持直接新建文件、新建文件夹和删除（需浏览器文件系统写权限）。只想从视图里移掉某个文件但不动磁盘的，有单独的「移除」选项。侧边栏可以收起，也可以拖拽调整宽度。

每个文件右侧会显示 ✅/❌/⏳ 的数量徽章，已加载文件实时统计，其他文件按文档里的 emoji 估算。管理多份文档时，不用逐个打开就能看出哪个文件问题最多。

4.10 保存、撤销与主题

自动保存：有文件写权限时，最后一次变更后约 400ms 自动写回原文件。没有写权限时保存到浏览器缓存，可手动下载。

外部变更检测：工具会定时检查磁盘上的文件修改时间。如果文件被编辑器改了，浏览器里的内容会自动刷新，但正在编辑时不会立即覆盖。

撤销/重做：按文件维护历史记录，最多 100 步，覆盖源码编辑、节点增删、状态标记和结构调整。

主题：支持亮色/暗色切换，偏好持久化到本地。

5 AI Chat

如果只看前端功能，CC MD MindMap 已经能覆盖大部分本地 Review 场景。

但我还加了一个可选的 ai-proxy.js。

它的作用是让 AI 在回答前可以检索本地 Markdown 内容，少一点张口就来的概率。

5.1 知识源来自哪里？

服务模式下，AI 可用的知识源有两类：

• 浏览器端正在编辑的 Markdown。
• 服务进程目录下递归扫描到的 .md / .markdown 文件。

它会自动忽略 node_modules、.git、.idea 这些目录。

如果同路径下浏览器版本和磁盘版本都有，优先使用浏览器正在编辑的版本，避免内容重复或过期。

5.2 内置工具清单

ai-proxy.js 给模型提供了几个本地检索工具：

比如你可以问：

1

帮我找出当前文档里所有和退款相关的异常分支，并按模块归类。

或者：

1

这份需求文档里有哪些已经标记为 ❌ 的问题点？每个问题点给我带上祖先路径。

6 写在最后

AI 让我们生成文档的速度变快了，但 Review 的速度没跟上。

以后只会更多：AI 写需求草稿、AI 写测试点、AI 写技术方案、AI 整理会议纪要。质量还是得靠人看懂结构、发现问题、留下判断。

CC MD MindMap 也适合经常和长文档打交道的同学试试。

先把结构摊开，很多问题就没那么难找了。