xmind-illustrated-map

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xmind Illustrated Map

Xmind 插图思维导图

Prerequisites

前置条件

xmind CLI installed (
```
npm i -g @xmindltd/xmind-cli
```
)
An image generation capability:
- Codex / Gemini CLI: built-in
```
image_gen
```
  works out of the box
- Other agents: configure an external image API and produce a single contact-sheet image as a local file
For text-only maps, stop here and use xmind-file

已安装xmind CLI（
```
npm i -g @xmindltd/xmind-cli
```
）
具备图像生成能力：
- Codex / Gemini CLI：内置的
```
image_gen
```
  可直接使用
- 其他Agent：配置外部图像API并生成单个联系表图像保存为本地文件
若仅需纯文本导图，可停止此处并使用xmind-file

How it works

工作原理

The CLI is a post-processing tool. The agent owns image generation; the CLI plans slots, slices the local contact sheet, and embeds slices into

.xmind

resources.

text

[xmind create] -> [xmind image-plan] -> [agent generates contact-sheet.png] -> [xmind enrich-images]

Minimal artifacts:

```
<file>.xmind
```
— the final map to enrich
```
plan.json
```
— visual slot mapping
```
prompt.txt
```
— debug copy of the prompt
```
contact-sheet.png
```
— final local raster file for attachment

Do not treat an inline preview or a remembered generated asset as completion. Attach only after

contact-sheet.png

exists as a real local file.

该CLI是一个后处理工具。Agent负责图像生成；CLI规划图像插槽，切割本地联系表，并将切片嵌入

.xmind

资源中。

text

[xmind create] -> [xmind image-plan] -> [agent生成contact-sheet.png] -> [xmind enrich-images]

生成的核心文件：

```
<file>.xmind
```
— 最终的待增强思维导图
```
plan.json
```
— 可视化插槽映射文件
```
prompt.txt
```
— 提示词的调试副本
```
contact-sheet.png
```
— 用于嵌入的最终本地光栅文件

请勿将内联预览或已记忆的生成资产视为完成状态。仅当

contact-sheet.png

作为真实本地文件存在时，再进行嵌入操作。

Workflow

工作流

1. Pick the structure strategy

1. 选择结构策略

bash

xmind skill list

Default routing:

History, evolution, staged change:
```
timeline
```
Item index with rich notes:
```
cards
```
Matrix or table-like content:
```
comparison
```
Everything else:
```
default
```

Then load the matching guidance:

bash

xmind skill show recipes/default features features/strategy/<name>

bash

xmind skill list

默认路由规则：

历史、演变、阶段性变化：
```
timeline
```
带详细注释的条目索引：
```
cards
```
矩阵或表格类内容：
```
comparison
```
其他所有情况：
```
default
```

然后加载匹配的指导文档：

bash

xmind skill show recipes/default features features/strategy/<name>

2. Build the markdown first

2. 先编写Markdown内容

Write the map as markdown before generating images.

Rules:

Keep the root title equal to the final map title.
Prefer 4 to 6 strong first-level branches when the map will be illustrated.
Put supporting detail in
```
###
```
and below.
For history/evolution topics, aim for 5 eras plus the root hero so the visual plan becomes a clean 3x2 contact sheet.

在生成图像之前，先以Markdown格式编写思维导图内容。

规则：

根标题需与最终思维导图标题一致。
当思维导图将添加插图时，建议设置4到6个一级分支。
将支持性细节放在
```
###
```
及以下层级。
对于历史/演变类主题，目标设置5个时代分支加上根主题，这样可视化规划会形成整洁的3×2联系表。

3. Create the .xmind

3. 创建.xmind文件

bash

cat <<'MD' | xmind create --stdin --skeleton <skeleton> --color <color> -o output.xmind

bash

cat <<'MD' | xmind create --stdin --skeleton <skeleton> --color <color> -o output.xmind

Topic

主题

Branch

分支

Detail

细节


Recommended defaults:

- History/evolution: `Timeline-1` + `Aurora`
- General knowledge overview: `MindMap-1` + `Aurora`
- Item index: follow the `cards` strategy guidance

Verify immediately:

```bash
xmind read output.xmind


推荐默认配置：

- 历史/演变类：`Timeline-1` + `Aurora`
- 通用知识概述：`MindMap-1` + `Aurora`
- 条目索引：遵循`cards`策略的指导文档

立即验证：

```bash
xmind read output.xmind

4. Plan image slots

4. 规划图像插槽

bash

xmind image-plan output.xmind \
  --grid-shape <auto|quad|timeline-strip|hero-branches|matrix> \
  --output plan.json \
  --prompt-output prompt.txt \
  --topics-output topics.json

Grid shape by content:

```
hero-branches
```
— root hero + major branches
```
timeline-strip
```
— chronological / phased
```
quad
```
— four-part structures (SWOT)
```
matrix
```
— two-axis comparison
```
auto
```
— fallback when no strong signal

Planning rules:

Default target is the root plus key first-level branches.
Keep image coverage selective. Do not try to illustrate every leaf.
Treat the root image as a hero summary and branch images as visual anchors.
If root or first-level branch titles change before attaching, rerun
```
image-plan
```
.

bash

xmind image-plan output.xmind \
  --grid-shape <auto|quad|timeline-strip|hero-branches|matrix> \
  --output plan.json \
  --prompt-output prompt.txt \
  --topics-output topics.json

按内容选择网格形状：

```
hero-branches
```
— 根主题图 + 主要分支图
```
timeline-strip
```
— 按时间顺序/阶段划分
```
quad
```
— 四部分结构（如SWOT分析）
```
matrix
```
— 双轴对比
```
auto
```
— 无明确信号时的 fallback 选项

规划规则：

默认目标是根主题加上关键一级分支。
选择性覆盖图像，不要尝试为每个叶子节点添加插图。
将根主题图像视为核心概览，分支图像作为视觉锚点。
如果在嵌入前根主题或一级分支标题发生变化，请重新运行
```
image-plan
```
。

5. Generate one contact sheet

5. 生成联系表

Use the agent's image generation capability with the contents of

prompt.txt

Prompt discipline:

Generate one contact sheet, not one image per topic.
Match the planned grid. For six slots, ask for
```
3 rows by 2 columns
```
.
Require clear panel boundaries and uniform gutters so slicing is reliable.
Require one consistent art direction across all panels.
Require no text, numbers, watermarks, logos, or labels.

After generation, ensure the final raster exists as a local file:

bash

contact-sheet.png

The image may initially be under

$HOME/.codex/generated_images/...

; move or copy it into the run directory before attaching.

使用Agent的图像生成能力，结合

prompt.txt

中的内容生成图像。

提示词规范：

生成一张联系表，而非每个主题单独生成一张图像。
匹配规划的网格。例如6个插槽，要求生成
```
3行×2列
```
的布局。
要求清晰的面板边界和统一的间距，确保切割可靠。
要求所有面板采用一致的艺术风格。
要求图像中无文字、数字、水印、logo或标签。

生成后，确保最终的光栅文件已保存为本地文件：

bash

contact-sheet.png

图像初始可能存储在

$HOME/.codex/generated_images/...

目录下；在嵌入前，请将其移动或复制到当前运行目录。

6. Attach images

6. 嵌入图像

Use the saved plan:

bash

xmind enrich-images output.xmind --use-plan plan.json --contact-sheet contact-sheet.png

Or use the current map directly for the common root-plus-branches case:

bash

xmind enrich-images output.xmind --contact-sheet contact-sheet.png --limit 6

This step:

slices the contact sheet locally
attaches each slice to the planned topics
writes images into
```
.xmind
```
```
resources/*
```
cleans unreferenced old resources

使用已保存的规划文件：

bash

xmind enrich-images output.xmind --use-plan plan.json --contact-sheet contact-sheet.png

或者对于常见的根主题加分支的情况，直接使用当前导图：

bash

xmind enrich-images output.xmind --contact-sheet contact-sheet.png --limit 6

此步骤会：

在本地切割联系表
将每个切片嵌入到规划好的主题中
将图像写入
```
.xmind
```
的
```
resources/*
```
目录
清理未被引用的旧资源

7. Verify the result

7. 验证结果

bash

xmind read output.xmind
unzip -l output.xmind

Success criteria:

the root and planned first-level branches have images
```
content.json
```
uses
```
xap:resources/...
```
the zip contains matching
```
resources/*.png
```
panel order matches the intended topic order

bash

xmind read output.xmind
unzip -l output.xmind

成功标准：

根主题和规划的一级分支已添加图像
```
content.json
```
中使用了
```
xap:resources/...
```
路径
压缩包中包含对应的
```
resources/*.png
```
文件
面板顺序与预期的主题顺序一致

Example

示例

For

The Evolution of Transportation

Use
```
timeline
```
Create 5 historical eras as first-level branches

Run

image-plan ... --output plan.json --prompt-output prompt.txt --topics-output topics.json

Generate one 3x2 contact sheet with the agent's image gen capability
Put the generated raster at
```
contact-sheet.png
```

Run

xmind enrich-images output.xmind --use-plan plan.json --contact-sheet contact-sheet.png

Verify the
```
.xmind
```
zip contains 6 embedded resources

以“交通运输的演变”为例：

使用
```
timeline
```
结构策略
创建5个历史时代作为一级分支

运行

image-plan ... --output plan.json --prompt-output prompt.txt --topics-output topics.json

使用Agent的图像生成能力生成一张3×2的联系表
将生成的光栅文件保存为
```
contact-sheet.png
```

运行

xmind enrich-images output.xmind --use-plan plan.json --contact-sheet contact-sheet.png

验证
```
.xmind
```
压缩包中包含6个嵌入资源