Mind Elixir Plaintext Format

Mind Elixir 纯文本格式

本技能介绍 Mind Elixir 纯文本格式规范，以及如何在该格式与 Mind Elixir JSON 数据结构之间进行转换。纯文本格式非常适合人工编辑、AI 生成和流式处理场景。

1. 格式概览

纯文本格式采用类似 Markdown 列表的缩进语法。每行表示思维导图中的一个节点，缩进（每级 2 个空格）用于定义层级关系。

基本结构

- Root Node
  - Child Node 1
    - Child Node 1-1
    - Child Node 1-2
  - Child Node 2
    - Child Node 2-1

关键规则：

• 根节点以 -（短横线后跟空格）开头
• 每个子节点相对于其父节点缩进 2 个空格
• 每行节点以 - 开头，后跟一个空格和主题文本

2. 高级功能

2.1 节点引用（ID）

使用 [^id] 语法为节点分配自定义 ID，以便交叉引用：

- Root
  - Node A [^id1]
  - Node B [^id2]

格式： 在主题文本末尾使用 [^customId]。

2.2 节点链接

使用 > 前缀和箭头语法在节点之间创建连接：

双向链接

- Root
  - Node A [^id1]
  - Node B [^id2]
  - > [^id1] (10,20) <-Link Label-> (-10,-20) [^id2]

格式： > [^sourceId] (delta1X,delta1Y) <-Label-> (delta2X,delta2Y) [^targetId]

• (delta1X,delta1Y)：控制点相对于起始节点的偏移量。
• (delta2X,delta2Y)：控制点相对于结束节点的偏移量。

提示

坐标可选：手动编写或生成纯文本时（例如通过 AI），可以省略 (x,y) 坐标。Mind Elixir 在渲染时会自动计算默认的平衡偏移量。不过，将数据导出回纯文本时，会包含这些坐标，以保留在 UI 中进行的任何手动调整。

单向链接

- Root
  - Node A [^id1]
  - Node B [^id2]
  - > [^id1] >-Forward Link-> [^id2]

格式：

• 正向：> [^sourceId] >-Label-> [^targetId]

2.3 节点样式

使用类似 JSON 的语法应用内联样式：

- Root
  - Styled Node {"color": "#e87a90"}
  - Another Node {"color": "#3298db", "background": "#ecf0f1"}

格式： 在主题文本末尾使用 {"property": "value", "property2": "value2"}。

常用属性：

• color：文本颜色（十六进制代码）
• background：背景颜色（十六进制代码）
• fontSize：字体大小（以字符串表示的数字，例如 "16"）

2.4 总结节点

创建总结节点，以可视化方式归纳前面的同级节点：

- Root
  - Node 1
  - Node 2
  - Node 3
  - } Summary of all above nodes

格式：

• } Summary text - 总结所有前面的同级节点
• }:N Summary text - 总结前 N 个同级节点（例如，}:2 表示最近的 2 个节点）

- Root
  - Node 1
  - Node 2
  - Node 3
  - }:2 Summary of Node 2 and Node 3

2.5 完整示例

- Project Planning
  - Phase 1: Research [^phase1]
    - Market Analysis {"color": "#3298db"}
    - Competitor Study {"color": "#3298db"}
    - }:2 Research Summary
  - Phase 2: Development [^phase2]
    - Frontend {"color": "#2ecc71"}
    - Backend {"color": "#2ecc71"}
    - Testing {"color": "#f39c12"}
    - } Development Summary
  - Phase 3: Launch [^phase3]
    - Marketing
    - Deployment
  - > [^phase1] (50,0) >-Leads to-> (-50,0) [^phase2]
  - > [^phase2] >-Leads to-> [^phase3]

3. 转换 API

3.1 纯文本转 Mind Elixir 数据

Mind Elixir 提供了用于解析纯文本的内置转换器：

import { plaintextToMindElixir } from 'mind-elixir/plaintextConverter'

const plaintext = `
- Root Node
  - Child 1
  - Child 2
`

const mindElixirData = plaintextToMindElixir(plaintext)
// Returns MindElixirData object ready for mind.init() or mind.refresh()

3.2 Mind Elixir 数据转纯文本

你也可以将现有思维导图转换回纯文本格式，以便导出和保存数据：

import { mindElixirToPlaintext } from 'mind-elixir/plaintextConverter'

const mindElixirData = mind.getAllData()
const plaintext = mindElixirToPlaintext(mindElixirData)
// Returns a string containing the mind map in plaintext format

3.3 集成示例

import MindElixir from 'mind-elixir'
import { plaintextToMindElixir } from 'mind-elixir/plaintextConverter'

// 1. Parse plaintext
const plaintext = `
- My Mind Map
  - Topic 1
    - Subtopic 1.1
    - Subtopic 1.2
  - Topic 2
`

const data = plaintextToMindElixir(plaintext)

// 2. Initialize Mind Elixir
const mind = new MindElixir({
  el: '#map',
  direction: MindElixir.RIGHT,
})

mind.init(data)

4. 使用场景

4.1 AI 生成的思维导图

纯文本格式非常适合大模型生成：

// Prompt example for AI
const prompt = `
Generate a mind map in plaintext format about "Web Development".
Use this format:
- Root Topic
  - Subtopic 1
    - Detail 1.1
  - Subtopic 2
`

// Then parse the AI response
const aiResponse = await callAI(prompt)
const data = plaintextToMindElixir(aiResponse)
mind.refresh(data)

4.2 基于文件的思维导图

将思维导图存储为 .txt 或 .md 文件：

// Load from file
const response = await fetch('/mindmaps/project.txt')
const plaintext = await response.text()
const data = plaintextToMindElixir(plaintext)
mind.init(data)

4.3 协作编辑

纯文本格式便于在版本控制中合并：

# Easy to diff and merge in Git
git diff mindmap.txt

5. 错误处理

始终使用 try-catch 块包装解析操作：

function safeParse(plaintext: string): MindElixirData | null {
  try {
    return plaintextToMindElixir(plaintext)
  } catch (error) {
    console.error('Parse error:', error)
    // Return fallback data
    return {
      nodeData: {
        id: 'root',
        topic: 'Parse Error',
        children: []
      }
    }
  }
}

6. 最佳实践

1. 保持缩进一致：每级始终使用 2 个空格
2. ID 唯一：使用引用时，确保 ID 在文档中唯一
3. 链接位置：链接可以放在任何位置，但应放在相关节点附近，以便阅读
4. 验证：解析前验证纯文本，尤其是用户输入
5. 流式处理：对于流式处理场景，增量解析并妥善处理不完整数据

7. Format Specification Summary

Feature	Syntax	Example
Node	- Topic	- My Node
Node with ID	- Topic [^id]	- Node A [^id1]
Node with Style	- Topic {"prop": "value"}	- Node {"color": "#ff0000"}
Bidirectional Link	> [^id1] (x,y) <-Label-> (x,y) [^id2]	> [^a] (10,20) <-connects-> (-10,-20) [^b]
Forward Link	> [^id1] (x,y) >-Label-> (x,y) [^id2]	> [^a] (10,20) >-leads to-> (-10,-20) [^b]
Summary (all)	} Summary text	} Overview
Summary (N nodes)	}:N Summary text	}:3 Last three items

8. TypeScript Types

import type { MindElixirData, NodeObj } from 'mind-elixir'

// Converter functions
function plaintextToMindElixir(plaintext: string): MindElixirData
function mindElixirToPlaintext(data: MindElixirData): string