xmind-file

Xmind 文件

用于在本地生成和编辑 .xmind 的运行时协议。

入口技能负责执行顺序和交付门槛。配方负责内容。 Visual 负责语义锚点规划。CLI 负责机械执行： generate、文件 IO、计费／降级、锚点、图片和验证。

设置

which xmind || npm install -g "$(find ~/.claude /mnt/skills -name 'xmind-cli-*.tgz' 2>/dev/null | head -1)" 2>/dev/null || npm install -g @xmindltd/xmind-cli
xmind auth status

如果尚未认证，请运行 xmind auth login 或 xmind auth token <value>。 文件命令需要登录。

核心边界

• Agent 提供语义判断：配方、markdown、路线意图、锚点和图片目标。
• xmind generate 将语义规范编译为 .xmind：路线门槛、 骨架／颜色、计费／降级、创建、锚点、图片、验证和 JSON 报告。
• xmind advise、create、batch、image 和 validate 仍是更底层的 工具，用于快速导图、编辑、修复和检查。
• 不要为了避免消耗额度而削弱内容或视觉效果。选择合适的产物； 让 CLI 计费、降级或报告。
• 从 JSON 标准输出的 billing.consumed 汇总本轮额度；缺少 billing 表示 0。

配方选择

起草前运行 xmind skill list，并将其配方目录和触发条件 作为事实来源。不要在此技能中维护配方清单。

如果用户指定了配方，或者你有充分把握认为某个配方最适合所请求的产物， 则直接选择。否则，推荐最匹配的配方，展示目录中 2-4 个相关选项， 简要说明每个选项会如何塑造产物，然后等待用户选择再起草。把握不大时， 优先让用户选择。

这不会覆盖 CLI／服务端回退。如果 xmind skill show 因无法使用高级配方 或 Xmind 额度而返回 effective: "quick-map"，请遵循有效配方，并明确 说明回退情况。

加载上下文

需求	加载
了解功能	xmind skill list
创建内容丰富的新导图	xmind skill show markdown-grammar recipe/<chosen> visual --json
创建免费的快速导图	xmind skill show markdown-grammar recipe/quick-map --json
编辑现有导图	xmind skill show edit/guide
底层修复操作	xmind skill show visual/layout-style visual/node-style
工作执行叠加层	xmind skill show task-overlay

对于配方 JSON，记录 requested、effective 和 createSkill。如果 CLI 提供了回退配方，则基于 effective 起草，并使用其 createSkill。

临时文件 IO

在 /tmp 下使用稳定的临时路径；不要在多条命令中使用 $$、$RANDOM 或 mktemp。

• 草稿：/tmp/xmind-draft-<id>.md
• 生成规范：/tmp/xmind-generate-<id>.json
• 已下载／用户提供的图片：应是持久保留至附件完成的真实磁盘文件。

成功交付后，只删除生成的临时 markdown／规范文件。除非用户要求， 切勿删除最终 .xmind、用户提供的输入文件或持久下载的资源。

生成规范

对于内容丰富的生成任务，编写语义规范并让 CLI 进行编译。

{
  "version": 1,
  "markdown": { "path": "/tmp/xmind-draft-<id>.md" },
  "recipe": {
    "name": "<requested recipe>",
    "effective": "<effective recipe>",
    "createSkill": "<recipe item 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，进行基线选择、锚点系列语义、目标选择， 并通过其锚点质量门槛。

语义质量门槛

运行 generate 前，检查草稿的内容，而不仅仅是 markdown：

• 所选配方符合用户目标；不要让 quick-map 取代所需的深度导图。
• 顶层分支应涵盖不同方面，不应是宽泛的兜底分类。
• 重要分支应有清晰可见的子级结构；不要让备注承载真正的层级关系。
• 锚点目标应已存在于可信的内容中，并可通过标题找到。
• 路线字段描述根节点关系，锚点描述局部例外。

如果未通过此门槛，请先修改 markdown／规范，再运行 CLI。机械验证无法 检测出浅层或语义虚假的导图。

流程 A：丰富生成

1. 加载上下文：

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

2. 根据生效的方案草拟 Markdown。

   遵循方案的密度、形态、语义信号、注释规范和自检要求。 先草拟可见的标题骨架，再添加有选择性的注释和锚点候选项。将纯 CommonMark 写入 /tmp/xmind-draft-<id>.md。

3. 根据 Visual 定义的路由和基线语义，编写 /tmp/xmind-generate-<id>.json。

4. 预检并视情况试运行：

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

   对于深度导图、支持高级功能的基线，或基线很重要的情况，请进行试运行。如果路由门控阻止生成，请修改同一份 Markdown/规格文件。

5. 生成：

   xmind generate --spec /tmp/xmind-generate-<id>.json -o <file>.xmind
   

   以标准输出中的 JSON 为准。如果 validation.ok 为 false，或任何 anchors.applied[].success 为 false，请修复同一份 Markdown/规格文件并重新运行。通过 CLI 验证是必要条件，但并非充分条件；交付前还要重新检查语义门控。

6. 仅在需要时检查：

   xmind read <file>.xmind
   xmind describe <file>.xmind
   xmind validate <file>.xmind --quiet
   

流程 Q：快速免费生成

在所选方案为 quick-map 时使用。

1. 加载：

   xmind skill list
   xmind skill show markdown-grammar recipe/quick-map --json
   

2. 根据生效的方案草拟精简的 Markdown。

3. 从生效方案的模式表中选择模式和免费骨架。

4. 创建并验证：

   xmind create --from-markdown /tmp/xmind-draft-<id>.md --skeleton <free-name> --color Dawn-#ffffff-MULTI_LINE_COLORS --skill <createSkill> -o <file>.xmind
   xmind validate <file>.xmind --quiet
   

   仅在验证失败、用户提出要求，或显然需要进行小幅修复时，才运行 read/describe。

5. 说明范围限制。

   告知用户这是快速概览，并非完整的丰富导图流程。如果用户想要更深入的标题/注释、视觉锚点、图片或支持高级功能的结构，可提供使用更完整方案重新生成的选项。

流程 B：编辑现有导图

1. 加载 edit/guide；只有在编辑会改变视觉处理方式时才加载 visual。

2. 先检查：

   xmind read <file>.xmind
   xmind describe <file>.xmind
   xmind validate <file>.xmind --quiet
   

3. 根据当前结构制定计划，并保留与本次编辑无关的用户更改。

4. 对多项操作编辑使用一次 xmind batch；对单项编辑使用直接命令。

5. 重新运行 read、describe 和 validate。

图片

图片输入可以是用户提供的本地文件、稳定的栅格图片 URL，或 Wikipedia 页面中的图片。不要将图片生成为此技能的一部分。此代码库不提供图片生成工作流。

远程图片 URL 必须是公开的栅格图片。SVG、私有/本地网络 URL 和非图片负载都会被拒绝。

对于流程 A，请在 anchors.image 中声明图片，以便 xmind generate 最后附加图片。对于编辑：

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

链接

单个主题使用 link。本地路径会解析为绝对 file:/// URI，并按照 Xmind Desktop 写入的格式进行 URL 编码：

xmind link <map>.xmind --topic "Reference" --url "https://example.com"
xmind link <map>.xmind --topic "Local map" --file "../maps/example.xmind"
xmind link <map>.xmind --topic "Reference" --remove

对于批量编辑，href 接受 href 或 file（必须且只能填写其中一项）：

{"op":"href","topic":"Local map","file":"../maps/example.xmind"}

本地文件链接指向原始文件，不会将其嵌入或复制到 .xmind 归档中。它们只能在存在该绝对路径的计算机上使用。若导图必须可移植，请使用 https URL。

交付门槛

对于流程 A：

• 已加载并遵循生效的方案。
• 生成规格指向临时 Markdown 文件，并包含 recipe.createSkill。
• xmind generate check 已通过。
• 对于非简单导图，已进行试运行；若跳过，则已说明原因。
• 最终生成报告中的 validation.ok: true。
• 所有必需的 anchors.applied[].success 值均为 true。
• 费用已从 billing.consumed 中读取。
• 成功后已删除临时 Markdown/规格文件。

对于流程 Q：

• 已加载并遵循 recipe/quick-map。
• 除非明确覆盖，否则使用免费骨架。
• 已将 createSkill 传递给 xmind create --skill。
• xmind validate 未报告结构错误。

用户沟通

对于较复杂的生成任务，请用用户的语言简要说明结果：

• 说明该主题为何适合这种思维导图结构。
• 说明哪些可见节点或分组启发了主要的视觉设计。
• 说明生成是否使用了 Xmind 积分。切勿将其称为 OpenAI、Codex、模型或 token 积分。

以 CLI JSON 为准，尤其是 route.skeletonReason、route.colorReason、anchors.applied、billing.consumed、billing.balance、billing.unit 和 downgraded。如果缺少 billing，则将本轮的 Xmind 积分消耗视为 0。

提供一到两个具体的后续操作：深化某个分支、比较不同的方案、调整图片或样式、编辑现有的 .xmind 文件、创建更简洁或免费的版本，或运行验证与检查。

最终回复：给出文件路径、验证结果和一到两个重要的设计选择。除非用户要求，否则不要贴出完整大纲。

如果文件已在 Xmind 中打开，之后的 CLI 修改可能不会立即显示；请告知用户关闭并重新打开 Xmind 以刷新。