Xmind CLI

概述

Xmind 本地思维导图

使用 xmind CLI 把内容转成结构清楚、视觉完整且可验证的本地 .xmind 文件，也可以安全地编辑已有文件。

工作方式

创建丰富思维导图时，始终遵循这条主流程：

1. 理解用户目标并选择合适的内容模板。
2. 起草 Markdown，先检查内容是否完整、层级是否合理。
3. 编写生成 spec，并让 CLI 检查输入和生成约束。
4. 必要时先试运行，再生成 .xmind；CLI 负责选择结构与配色、应用局部强调和图片，并处理 Xmind credits 扣费或能力降级。
5. 根据 CLI 的 JSON 报告验证结果；失败时回到 Markdown/spec 修正后重试。

简单概览可以走 quick-map 快速流程；内容较深、需要高级结构、图片或局部视觉强调时走丰富生成流程。编辑已有文件则先读取和验证，只修改用户要求的部分。

关键机制

• 内容先行：先审查内容结构，不让机械验证替代内容质量判断。
• 意图与执行分离：Agent 描述内容和视觉目标，CLI 将其稳定地落实为文件。
• 结果可追溯：结构、配色、局部强调、扣费和降级都以 CLI 的 JSON 报告为准。
• 失败可修正：检查不通过时修改原 Markdown/spec 后重试，不绕过门槛生成残缺文件。

术语

• recipe：内容模板，规定信息如何组织；effective recipe 是权限或降级处理后实际生效的模板。
• visual：视觉规则，指导结构、配色和强调方式。
• route：整张图的结构方案，例如时间轴、流程或层级树。
• baseline：全图默认的结构和配色基础。
• anchors：针对具体节点的局部布局、分组、强调或图片要求。
• skeleton：CLI 中可执行的具体图形骨架。

这些英文名称与 CLI 命令和 JSON 字段一一对应，后文保留原名以避免误操作。

安装与国区登录

command -v node
node --version
command -v npm
command -v xmind
xmind --version
xmind auth status

需要 Node.js 20 或更高版本。若 xmind 未安装，先说明将修改用户的全局 npm 环境并征得同意，再使用系统 Node.js 自带的 npm 安装：

npm install -g @xmindltd/xmind-cli

不要把 CLI 安装进 .workbuddy 等 Agent 托管的 Node 目录。若未登录或状态中的 region 不是 cn，执行：

xmind auth login cn

用户提供 token 时执行：

xmind auth token <value> cn

本 Skill 固定使用 cn：

• 必须为 login 和 token 填写 cn
• 不执行无区域参数的登录命令
• 不使用 global
• 不输出、记录或提交用户 token
• 文件命令需要先完成登录

核心边界

• Agent 负责选择 recipe、起草 Markdown，并描述 route、anchors 和图片等内容与视觉目标。
• xmind generate 负责生成 .xmind、选择结构与颜色、应用 anchors、处理扣费或降级并验证结果。
• xmind advise 免费提供 skeleton 排名、结构分析、每个父节点的子布局建议和草稿测量；具体用法见丰富生成流程。
• xmind create、batch、image、link、read、describe 和 validate 用于快速生成、编辑和检查。
• 不直接修改 .xmind 内部 ZIP/XML。
• 不为了避免 Xmind credits 而降低内容或视觉质量；让 CLI 扣费、降级或报告失败。
• 仅处理本地 .xmind；不使用 xmind-cloud，也不生成 AI 图片。

内容模板（Recipe）与上下文

创建前运行：

xmind skill list

以 CLI 返回的模板目录（catalog）和触发说明为准，不在本 Skill 中维护 recipe 清单。

用户明确指定 recipe，或只有一个明显匹配项时，直接选择；否则先推荐最佳匹配，再给出 2～4 个候选及其内容组织差异，等待用户选择。

从 recipe JSON 记录 requested、effective 和 createSkill。如果服务返回备用结果（fallback），按照 effective 写作并向用户说明降级。

临时文件

使用稳定路径，不跨命令使用 mktemp、$$ 或 $RANDOM。其中 <id> 使用与本次任务相关的稳定短名称（slug）：

/tmp/xmind-draft-<id>.md
/tmp/xmind-generate-<id>.json

成功交付后只删除本次生成的临时 Markdown 和 spec。不要删除最终 .xmind、用户输入或需要保留的图片。

丰富生成

1. 加载并起草

xmind skill list
xmind skill show markdown-grammar recipe/<chosen> visual --json

遵循 effective recipe 规定的内容密度（density）、结构形态（shape）、备注策略（notes posture）和自检规则（self-check）。使用纯 CommonMark：先写可见标题骨架，再添加必要的备注，最后确定 anchor 候选。

将内容保存到 /tmp/xmind-draft-<id>.md。

2. 获取结构建议

起草后可按需运行 xmind advise：第一种模式根据结构目标、语气和草稿测量给出根骨架排名及内容密度要求；第二种模式给出指定 skeleton 的结构分析和各父节点子布局建议。

xmind advise --structural-type "<type>" --tone-tag "<tag>" --density "<light|standard|deep>" --stdin < /tmp/xmind-draft-<id>.md
xmind advise --skeleton "<name>" --stdin < /tmp/xmind-draft-<id>.md

3. 编写 spec

{
  "version": 1,
  "markdown": { "path": "/tmp/xmind-draft-<id>.md" },
  "recipe": {
    "name": "<requested recipe>",
    "effective": "<effective recipe>",
    "createSkill": "<createSkill>"
  },
  "route": {
    "structuralType": "<radial_overview|mixed_modular|temporal_axis|procedural_flow|matrix_board|causal_ribs|hierarchy_tree|part_whole>",
    "structureCommitment": "<required|preferred|optional>",
    "toneTag": "<tech|nature|retro|elegant|fresh|sweet|vivid|plain>",
    "density": "<light|standard|deep>"
  },
  "baseline": {
    "skeleton": "auto",
    "color": "auto",
    "diversify": true,
    "seed": "<stable id>"
  },
  "anchors": {
    "layout": [],
    "group": [],
    "focus": [],
    "image": []
  }
}

按照 visual 提供的语义选择 route、baseline 和 anchors，不自行维护结构或颜色规则。

4. 内容质量门槛（Semantic Quality Gate）

运行 CLI 前把 Markdown/spec 当作内容审查：

• 所选 recipe 必须匹配用户目标；不要让 quick-map 顶替本应使用的深度 recipe。
• 顶层分支覆盖不同且完整的维度，不使用宽泛的兜底分类。
• 重要分支具有可见子结构，notes 不承载主要层级。
• anchor 目标已存在于真实内容中，并能按标题定位。
• route 描述根节点关系，anchors 只描述局部例外。

任一条件不满足时，先修改同一份 Markdown/spec 并重新通过本检查，再运行 xmind generate check。

5. 检查并生成

xmind generate check --spec /tmp/xmind-generate-<id>.json
xmind generate --spec /tmp/xmind-generate-<id>.json --dry-run -o "<output>.xmind"
xmind generate --spec /tmp/xmind-generate-<id>.json -o "<output>.xmind"

深层思维导图、可能使用高级结构或 baseline 选择很重要时执行试运行（dry-run）。若结构检查（route gate）阻止生成，修改同一份 Markdown/spec 后重试。

以最终 JSON 为准：validation.ok 必须为 true，所有必需的 anchors.applied[].success 必须为 true。机械验证通过后仍要检查内容是否真实、充分且符合 recipe。

快速生成

仅在 effective recipe 为 quick-map 时使用。<free-skeleton> 必须取自 effective recipe 的模式表（mode table）；除非用户明确指定，否则使用其中的免费 skeleton。

xmind skill show markdown-grammar recipe/quick-map --json
xmind create 
  --from-markdown "/tmp/xmind-draft-<id>.md" 
  --skeleton "<free-skeleton>" 
  --color "Dawn-#ffffff-MULTI_LINE_COLORS" 
  --skill "<createSkill>" 
  -o "<output>.xmind"
xmind validate "<output>.xmind" --quiet

验证成功后无需额外运行 read 或 describe；仅在验证失败、用户要求检查或确实需要修复时运行。告诉用户这是快速概览，而不是丰富生成流程。需要更深内容、视觉 anchors 或高级结构时，可重新选择完整 recipe。

编辑现有文件

先加载编辑指导并检查文件：

xmind skill show edit/guide
xmind read "<file>.xmind"
xmind describe "<file>.xmind"
xmind validate "<file>.xmind" --quiet

若编辑涉及布局、样式、颜色或节点视觉，再加载视觉规则：

xmind skill show visual/layout-style visual/node-style

• 保留与当前任务无关的用户内容和样式。
• 多项修改优先使用一次 xmind batch，单项修改使用直接命令。
• 不确定目标节点时先读取文件，不要猜测。
• 用户明确要求编辑现有文件时可以原地修改；任务或输出目标不明确时，不覆盖原文件。
• 修改后重新执行 read、describe 和 validate。

图片与链接

图片可以来自用户提供的本地文件、公开栅格图片 URL 或 Wikipedia 页面图片。SVG、私有网络 URL 和非图片响应会被拒绝。

丰富生成时，把图片声明在 spec 的 anchors.image 中，由 xmind generate 最后统一附加，并以生成 JSON 中的 anchors.applied 和 validation 为准。不要在丰富生成后默认逐个调用 xmind image 打补丁。

编辑现有文件时才使用：

xmind image "<file>.xmind" --topic "<topic>" --input "<local-image>"
xmind image "<file>.xmind" --topic "<topic>" --url "<https-image-url>"
xmind image "<file>.xmind" --topic "<topic>" --wiki "<Wikipedia title>"

添加或移除链接：

xmind link "<file>.xmind" --topic "<topic>" --url "https://example.com"
xmind link "<file>.xmind" --topic "<topic>" --file "../documents/example.pdf"
xmind link "<file>.xmind" --topic "<topic>" --remove

本地文件链接保存为绝对 file:/// URI，不嵌入目标文件；需要跨设备使用时采用 HTTPS URL。

多项编辑使用 xmind batch 时，href 接受 href 或 file，且只能填写其中一个：

{"op":"href","topic":"本地资料","file":"../documents/example.pdf"}

交付门槛

丰富生成必须满足：

• 国区登录状态有效
• effective recipe 已加载并遵循
• 内容质量门槛已通过
• generate check 通过
• 需要时已执行 dry-run
• 最终 JSON 的 validation.ok 为 true
• 必需 anchors 全部成功
• 已从 billing.consumed 读取 Xmind credits 消费；缺少 billing 时按 0 处理
• 临时 Markdown/spec 已清理

快速生成必须满足：

• 使用 recipe/quick-map，且未被用来替代本应使用的深度 recipe
• 除非用户明确指定，使用 effective recipe 模式表中的免费 skeleton
• createSkill 已传给 xmind create --skill
• xmind validate 无结构错误

最终回复使用用户语言，提供文件路径、验证结果和一两项重要设计选择。解释结构、配色、anchors、扣费或降级时，只以 CLI JSON 的以下字段为依据，不自行编造理由：

• route.skeletonReason
• route.colorReason
• anchors.applied
• billing.consumed
• billing.balance
• billing.unit
• downgraded

只能称为“Xmind credits”，不得称为 OpenAI、Codex、模型或 token credits。非简单生成还应说明 recipe 为什么适合，但不要粘贴完整大纲。

提供 1～2 个具体后续动作，例如深化一个分支、调整图片或样式、编辑现有文件，或生成更轻量的版本。

如果文件已经在 Xmind 中打开，提醒用户关闭并重新打开以刷新 CLI 修改。