Lakeboard Converter

**将语雀 Lakeboard（.lakeboard）和 XMind（.xmind）思维导图转换为 Markdown 或全新的 .xmind 文件。**提供 CLI、引导式 TUI、MCP 服务和支持拖放的 Web UI（convert.ledring.dev）。English | 简体中文

快速开始

打开 convert.ledring.dev，即可在浏览器中转换文件。

也可以使用 CLI，无需全局安装（需要 Node 20.12+）：

npx -y lakeboard-converter convert ./map.xmind --format md --out-dir ./out

将 Markdown 输出到 stdout，而不写入文件：

npx -y lakeboard-converter read ./map.xmind --format md

启动 MCP 服务：

npx -y lakeboard-converter mcp

开发

git clone https://github.com/FelixFangX/lakeboard-converter.git
cd lakeboard-converter && npm ci
npm run convert -- ./test-fixtures/test.lakeboard --format md --out-dir ./out

用法

模式	命令
引导式 TUI	npm run dev
CLI	npm run convert -- <file> --format md|xmind|both [--markdown-style generic|xmind] [--out-dir DIR] [--output FILE] [--overwrite]
Web UI	npm run dev:web（生产构建：npm run build:web）
库（源码）	import { convertBuffer, convertFile } from './src/index.js'

除非传入 --overwrite，否则绝不会覆盖现有输出文件。

Web UI

在线演示：https://convert.ledring.dev

Web UI 完全在浏览器中运行：文件不会离开你的设备。它可自托管，不会发起任何第三方请求，包括字体请求。可在本地运行 npm run dev:web，或试用内置的 Lakeboard 和 XMind 示例文件。

部署（Cloudflare Workers）

在环境中设置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 后：

npm ci && npm run deploy:web

wrangler.jsonc 将 dist-web/ 作为静态资源提供，并启用单页应用回退。

若要将预览构建部署到 lakeboard-convert-preview.<subdomain>.workers.dev（它没有自定义域名），请运行 npm run build:web && npx wrangler@3 deploy --env preview。

面向 Agent（MCP 和 --json）

需要 Node 20.12+。MCP 服务提供四个工具：

• convert(path, format?, sheet?, maxNodes?, maxDepth?)：将一份思维导图读取为 md（默认）、json（主题树）或 outline（紧凑的缩进文本）。
• from_markdown(markdown, output?, overwrite?, title?, maxNodes?)：根据 Markdown 大纲生成 XMind 文件。
• convert_many(paths, format?, sheet?, maxNodes?, maxTotalNodes?, maxDepth?)：读取多份思维导图，并共享节点数量上限。
• inspect(path, sheet?)：返回文件大小和主题数量，不包含内容。

convert、convert_many 和 inspect 均为只读操作。from_markdown 只会写入你传入的输出路径。

启动 MCP 服务：

npx -y lakeboard-converter mcp

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "lakeboard-converter": {
      "command": "npx",
      "args": ["-y", "lakeboard-converter", "mcp"]
    }
  }
}

Cursor（.cursor/mcp.json 或 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "lakeboard-converter": {
      "command": "npx",
      "args": ["-y", "lakeboard-converter", "mcp"]
    }
  }
}

Codex CLI（~/.codex/config.toml）：

[mcp_servers.lakeboard-converter]
command = "npx"
args = ["-y", "lakeboard-converter", "mcp"]

通过 CLI 读取文件，或全局安装 CLI：

npx -y lakeboard-converter read ./map.xmind --format md
npm i -g lakeboard-converter

Markdown 转 XMind

from_markdown 支持标题、嵌套列表、编号列表、链接、末尾的 code 标签和 > notes。多个工作表可通过重复的 # Sheet / ## Root 部分表示；每个工作表标题必须恰好包含一个根标题。首个标题或列表项之前的文本会被忽略，并显示警告。

若要写入文件，请传入现有文件夹中的绝对 .xmind 输出路径。不会创建文件夹；若文件已存在，则需要设置 overwrite: true。如果未指定 output，该工具会在 structuredContent.base64 中返回文件。Markdown 输入上限为 2 MB（UTF-8）。maxNodes 默认为 2000（1–50000）；被省略的主题会通过 truncated 和 warnings 报告。

CLI build 必须指定 -o，并会将其解析为绝对路径；使用 --overwrite 可允许覆盖：

npx -y lakeboard-converter build plan.md -o plan.xmind

批量与大小检查

convert_many 接受 1–50 个绝对路径。maxNodes 对每个文件分别生效；maxTotalNodes 的默认值为 10000（范围为 1–200000），适用于整个批次。文本包含转换后的内容；structuredContent 包含每个文件的元数据和错误，但不含 content。单个文件出错不会导致 MCP 调用失败。CLI 多文件 read 也会返回每个文件的结果和错误；如果任何文件失败，则以状态码 1 退出。使用 --max-total-nodes 更改总预算。

inspect 返回字节数、节点数、深度和工作表元数据，不含内容。

npx -y lakeboard-converter read a.xmind b.lakeboard --json
npx -y lakeboard-converter inspect a.xmind --json

从源文件读取

npm run build
node /abs/path/lakeboard-converter/dist/cli.js mcp
node dist/cli.js read ./test-fixtures/test.lakeboard --format json --json
node dist/cli.js convert ./test-fixtures/test.xmind -f md --out-dir out --json

每个单文件 CLI 读取 JSON 结果都包含 schemaVersion: 1、source、format、nodeCount、maxDepth 和 content。使用 --json 时，错误会输出 {"error": "..."} 并以状态码 1 退出。贡献者请参阅 AGENTS.md。

输出与限制

所有 XMind 工作表都会包含在内。Lakeboard 文档只有一个以根节点命名的工作表。未命名的 XMind 工作表使用 Sheet N。包含多个工作表时，通用 Markdown 会使用 # <sheet title>，后接 ## <root title> 和主题列表。单个工作表仍使用 # <root title>。第一层列表项从第 0 列开始；更深层级的项每层缩进两个空格。备注与对应项的内容列对齐。链接主题直接使用 [Title](url)，包括标题；标题中的方括号会转义。通用 Markdown 会将标签作为代码跨度放在标题后，例如 - Split vendor chunk `P1` `tech-debt` 。大纲使用 - Title [P1, tech-debt]；有多个工作表时，每个大纲前都会添加工作表标题。

XMind 导入专用 Markdown 为每个工作表使用一个根列表，列表之间以空行分隔，不含标题。它会省略标签，以免标签成为导入主题标题的一部分。

CLI read、convert 和 inspect 接受 --sheet <index|name>（从 1 开始的索引或不区分大小写的精确标题）。MCP 接受字符串或整数形式的 sheet。所选工作表会记录在 selectedSheet 中；如果选择项未知，则会列出可用工作表。

lakeboard-converter read /absolute/path/map.xmind --sheet Roadmap --max-nodes 5000 --max-depth 3 --json
lakeboard-converter convert ./map.xmind --sheet 2 --format md

readMindMap(file, format, options)、CLI read 和 MCP 的默认 maxNodes 为 2000；有效值为 1 到 50000 之间的整数。可选的 maxDepth 是非负整数。根节点的深度为 0，因此只有子节点的根节点对应 maxDepth: 1。限制会按先序遍历方式跨工作表裁剪主题。truncated 和 warnings 会报告被省略的主题。提高限制或选择工作表即可读取更多内容。文件转换没有大小限制。CLI read（不带 --json）和 MCP 文本会以 > Note: ... 的形式附加警告。

MCP 请使用绝对路径：对于 convert，相对路径会根据服务的工作目录解析，该目录可能与终端中的目录不同。CLI read 和 MCP convert 会使用主目录展开开头的 ~ 或 ~/（Windows 上也支持 ~\）。对于不存在的相对路径，错误信息会显示解析后的路径和服务的工作目录。

单文件读取 JSON 和 MCP convert 结果

CLI read --json 保留 schemaVersion: 1 和现有字段，并新增 sheets: [{ index, title, nodeCount, maxDepth }]、可选的 selectedSheet: { index, title }、truncated 和 warnings。计数反映截断前所选输入的情况；maxDepth 始终将根节点计为深度 0。

对于 format: "json"，content 是单个工作表的主题树。从 0.4.0 开始，多个工作表会生成 { sheets: [{ index, title, root: AgentTopic }] }。这些树以及 Markdown 和大纲同样适用上述限制。

MCP convert 会返回一个纯文本块，其中包含 Markdown、大纲文本或美化后的 JSON 树。它还会返回 structuredContent，内容为 { schemaVersion, file, source, format, nodeCount, maxDepth, sheets, selectedSheet?, truncated, warnings }，并依据工具注册的 outputSchema 进行验证。文本不再是 JSON 字符串化的结果封装。警告会以最后一行 > Note: ... 的形式附加。出错时会通过 isError: true 返回清晰的错误消息；该工具仍为只读。

Cursor CLI 在无头模式下（cursor-agent -p）需要 --force（以及 --approve-mcps），否则工具调用会被拒绝。

工作原理

.lakeboard ─┐                          ┌─ renderGenericMarkdown → # root + nested list
            ├─ parse → MindMapDocument ─┼─ renderXmindMarkdown  → root list per sheet for XMind import
.xmind ─────┘     (TopicNode tree)      └─ renderXmind          → minimal .xmind package

接缝是 src/index.ts 中的 convertBuffer / convertFile。每种输入格式都会解析为一个 MindMapDocument，因此新增格式只需编写一个解析器，无需更改渲染器。CLI 和 TUI 使用该接缝。Web UI 使用自己的浏览器转换器，并共享回退 ID 分配逻辑；Agent 使用 src/agent.ts 中的 readMindMap、readMindMaps、inspectMindMap 和 buildMindMap，这些函数从 src/index.ts 导出。只有在提供了明确的输出路径时，buildMindMap 才会写入文件。

保留文本、层级、顺序、备注和链接。读取所有 XMind 工作表。标签以内联形式显示在通用 Markdown 和大纲中。不保留样式、颜色和布局。不支持 XMind 8（旧版 XML）。

测试

npm test            # vitest specs at the convert, readMindMap and MCP seams, using test-fixtures/
npm run typecheck

许可证

MIT