# MoonMarkMind 规则说明 本文档描述 MoonMarkMind 的核心数据规则：Markdown 如何进入脑图模型，脑图模型如何回写 Markdown，以及 Web 交互应保持的行为边界。 ## 1. 总体数据流 ```text Markdown 文本 -> lib/outline_parser 解析结构线索并构建 OutlineNode 层级树 -> lib/outline_parser 维护结构编辑与 Markdown 回写 -> lib/markdown_render / packages/markdown_to_html 渲染 HTML 富文本预览 -> lib/mindmap_render / packages/markdown_to_mindmap 渲染静态 HTML/SVG 脑图 -> app/web 组织浏览器端编辑器、脑图交互、预览和导出 -> cmd/cli 复用 Web 渲染链路导出单个 Markdown 文件为 PNG / SVG / HTML ``` Markdown 是主数据源。脑图中的结构编辑最终应能回写为可读 Markdown；可复用包和 CLI 都应围绕同一解析、渲染和导出规则工作。 ## 2. Markdown 到脑图 ### 2.1 标题 Markdown 标题是脑图层级的主要来源。 - `#` 到 `######` 分别对应 1 到 6 级标题。 - 顶层存在一个隐式 `ROOT` 节点，不直接显示为用户节点。 - 标题文本成为节点标题。 - 标题下方直到下一个同级或更高级标题之前的内容，作为节点正文。 - 跳级标题需要被稳定处理，不能破坏父子关系。 示例： ```md # 项目 ## 目标 ### 范围 ## 计划 ``` 对应结构： ```text ROOT └─ 项目 ├─ 目标 │ └─ 范围 └─ 计划 ``` ### 2.2 列表 列表既可以作为节点正文，也可以在适合结构化展示时转为层级节点。 - 无序列表支持 `-`、`*`、`+`。 - 有序列表支持 `1.`、`2.` 等 Markdown 常见写法。 - 缩进表示列表层级。 - 任务项 `[ ]` 和 `[x]` 应保留勾选状态。 ### 2.3 正文内容 标题下的正文应尽量保留 Markdown 表达，不应因为脑图渲染而丢失文本。 支持的常用内容包括： - 加粗、斜体、删除线。 - 行内代码和代码块。 - 链接和图片。 - 任务项。 - 表格。 - LaTeX 行内公式和块级公式。 ### 2.4 空文档和非标题文档 - 空文档应生成可用的空状态，而不是异常中断。 - 没有标题但有正文的 Markdown，应以默认根内容或可编辑初始节点承载。 - 解析失败或遇到不完整语法时，应尽量保留原文可编辑性。 ## 3. 脑图模型 ### 3.1 节点字段 脑图节点至少需要表达以下信息： - `id`：节点标识。 - `text`：节点标题。 - `body`：节点正文。 - `children`：子节点列表。 - `depth` 或 `level`：层级信息。 - `kind`：标题、列表项或其他结构类型。 - `collapsed`：是否折叠。 - `hidden`：是否隐藏。 具体内部表示由 MoonBit 类型实现，公开 API 以 `pkg.generated.mbti` 为准。 ### 3.2 编辑操作 模型层提供确定性的结构编辑操作： - 新增子节点。 - 新增同级节点。 - 删除节点。 - 重命名节点。 - 上移和下移节点。 - 拖拽移动节点。 - 缩进节点，使其成为相邻节点的子节点。 - 提升节点，使其成为父节点的同级节点。 - 折叠或展开节点。 - 隐藏或显示节点。 这些操作必须保持树结构合法：不能出现环、孤儿节点或无法回写的层级。 ### 3.3 回写 Markdown 脑图回写 Markdown 时遵循以下原则： - 1 到 6 级节点优先回写为标题。 - 超过 6 级的结构回写为嵌套列表，避免生成非法标题。 - 节点正文跟随节点标题输出。 - 任务项、代码块、表格、链接、图片和公式尽量保持原始 Markdown 形式。 - 删除、移动、缩进、提升后，回写结果应能再次解析为等价结构。 ## 4. Web 交互规则 ### 4.1 编辑器与脑图同步 - 用户修改 Markdown 后，脑图应刷新。 - 用户选中脑图节点后，编辑器应能定位到相关 Markdown 区域。 - 节点编辑操作应同步更新 Markdown。 - 同一输入在多次刷新后应保持结构一致。 ### 4.2 布局 支持三类布局： - 逻辑图布局：强调从左到右的推导关系。 - 脑图布局：强调中心主题和分支。 - 树状图布局：强调从上到下的父子层级。 布局只影响视觉组织，不应改变 Markdown 数据。 ### 4.3 样式 支持两类主要节点样式： - 填充卡片样式。 - 线框/分支线样式。 样式切换只影响展示，不应改变模型数据。 ### 4.4 详情级别 详情级别用于控制节点正文的展示密度： - 全部：展示完整内容。 - 中等：展示适量摘要。 - 精简：突出标题和结构。 详情级别只影响展示，不应删除 Markdown 内容。 ## 5. 导出规则 ### 5.1 PNG PNG 导出用于分享和文档插图，应尽量保留当前脑图的视觉样式、布局和连接线。 ### 5.2 SVG SVG 导出用于高清展示和继续编辑，应保留矢量结构、文本和连接线。 ### 5.3 HTML HTML 导出用于独立打开和演示，应保留必要的运行时逻辑，在页面加载后重新计算连接线和视图尺寸。 ## 6. 异常与边界条件 需要重点覆盖的边界： - 空 Markdown。 - 只有正文、没有标题。 - 标题跳级。 - 深度超过 6 级。 - 节点删除后选中态失效。 - 节点移动到自身或子树内部。 - 代码块中包含看似标题或列表的文本。 - 表格、公式、图片等富文本内容位于节点正文中。 - 导出时脑图尺寸大于当前视口。 ## 7. 验收映射 - 完成度：README 和 ACCEPTANCE 中的关键功能路径可触发声明范围。 - 工程质量：MoonBit 模块按解析/模型、Markdown 渲染、脑图渲染、可复用包、Web 交互、CLI 导出拆分。 - 可解释性：本文档解释核心规则，README 和验收说明解释运行方式、模块边界与关键功能路径。 - 用户体验：Web 页面提供直接编辑、HTML 富文本预览、示例加载和导出能力。