tmmpr 终端思维导图工具技术分析
一、概述
1. 项目简介
A. 是什么
tmmpr（terminal mind mapper）是一个基于 Linux 终端的思维导图应用程序，允许用户在无限画布上创建、组织和连接笔记。它将终端环境转变为数字白板，支持通过键盘高效操作。
B. 核心价值
- 在无图形界面环境中实现可视化思维整理
- 纯键盘操作，符合 Vim 用户习惯
- 轻量级实现，无需复杂的图形环境依赖
C. 技术栈
- 语言：Rust 2024 Edition
- 框架：Ratatui 0.30.0（TUI 框架）
- 终端处理：Crossterm 0.29.0
- 数据序列化：Serde + Serde_json
二、核心架构
1. 应用结构
graph TB
A[main.rs] --> B[app.rs]
A --> C[input.rs]
A --> D[ui.rs]
A --> E[states/]
A --> F[utils/]
E --> E1[StartState]
E --> E2[MapState]
E --> E3[SettingsState]
C --> C1[事件处理]
C --> C2[按键映射]
D --> D1[render_start]
D --> D2[render_map]
D --> D3[render_settings]
2. 状态管理
应用采用状态机模式，通过 Screen 枚举管理三个主要界面：
| 状态 | 职责 | 渲染函数 |
|---|---|---|
| Start | 启动界面，提供新建、打开、最近文件功能 | render_start |
| Map | 核心思维导图编辑界面 | render_map |
| Settings | 设置配置界面 | render_settings |
3. 核心数据结构
pub struct App {
pub running: bool, // 主循环控制
pub screen: Screen, // 当前界面状态
}
pub enum Screen {
Start(StartState),
Map(MapState),
Settings(SettingsState),
}三、工作原理
1. 主循环机制
sequenceDiagram
participant M as main()
participant T as Terminal
participant A as App
participant E as Event Handler
participant R as Renderer
M->>T: 初始化终端
M->>A: 创建 App 实例
loop 主循环
A->>E: handle_events()
E->>A: 更新状态
A->>R: 判断是否需要重绘
alt 需要重绘
A->>T: terminal.draw()
T->>R: 调用对应 render 函数
end
A->>A: 检查 running 状态
end
M->>T: 恢复终端
2. 视口与画布系统
无限画布实现
- 坐标系统：正坐标空间（0,0 到无穷大）
- 视口管理：通过 viewport_offset 控制可见区域
- 导航方式：hjkl 键移动视口，H/J/K/L 快速移动
渲染优化
- 按需重绘：通过 needs_clear_and_redraw 标志控制
- 增量更新：仅在状态变化时重绘界面
四、功能模块
1. 多模式操作
tmmpr 采用类 Vim 的模式系统：
| 模式 | 功能 | 切换键 |
|---|---|---|
| Normal | 视口导航、通用命令 | 默认模式 |
| Visual | 选择和管理笔记 | v 键进入 |
| Visual (Move) | 移动笔记位置 | m 键切换 |
| Visual (Connection) | 管理笔记连接 | c/C 键切换 |
| Edit | 文本编辑 | i/a 键进入 |
2. 笔记与连接系统
笔记属性
- 位置坐标（x, y）
- 文本内容
- 颜色标识
- 连接端口（上下左右）
连接管理
- 支持多对多连接
- 自定义连接颜色
- 可配置连接侧边
- 连接旋转和删除功能
3. 数据持久化
自动保存
- 可配置自动保存间隔
- 防止数据丢失
备份系统
- 打开文件时自动备份
- 运行时定期备份
- 可配置备份频率（每日、每周等）
五、技术特性
1. Rust 2024 Edition
项目使用最新的 Rust 2024 Edition，这意味：
- 采用最新的语言特性和优化
- 改进的错误处理机制
- 更好的编译器诊断
2. 依赖分析
从 Cargo.toml 可看出项目的精简设计：
[dependencies]
ratatui = "0.30.0" # TUI 框架
crossterm = "0.29.0" # 跨平台终端操作
color-eyre = "0.6.5" # 错误处理
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.149" # JSON 序列化
home = "0.5.12" # 目录路径解析
chrono = { version = "0.4.43", features = ["serde"] }
tempfile = "3.24.0" # 临时文件处理依赖设计原则：
- 最小化依赖数量（仅 7 个）
- 使用成熟稳定的库版本
- 特性按需启用（如 chrono 的 serde 特性）
3. 测试覆盖
项目保持约 54% 的测试覆盖率，主要集中在：
- 业务逻辑测试
- 状态管理测试：/src/states/*/tests/
- 输入处理测试：/src/input/map/tests/
- 工具函数测试：/src/utils/tests/
测试策略：
- TUI 层（/src/ui/）通过手动测试验证
- 核心逻辑通过自动化测试覆盖
- 已知问题：部分测试会修改实际配置文件
六、应用场景
1. 适用场景
- SSH 远程环境下的思维整理
- 服务器运维笔记管理
- 无桌面环境的架构设计
- 命令行用户的快速头脑风暴
2. 系统要求
- 操作系统：Linux（主要支持）
- Rust 版本：1.85.0+
- 终端：支持 Unicode 的终端模拟器
七、项目状态
1. 当前状态
- 核心功能完整可用
- 基本的创建、编辑、连接功能正常
- 自动保存和备份系统运作良好
2. 已知限制
- Vim 模式编辑器功能有限
- 代码结构需要重构
- 测试环境隔离不完善
- 部分硬编码路径影响可测试性
3. 开发路线图
短期目标
- 代码重构和模块化改进
- 修复测试套件的配置文件污染问题
- 解耦硬编码路径
- 完善内联和文档注释
- 改进编辑模式功能
长期目标
- 添加图片支持功能
- 扩展 Vim 编辑器能力
八、技术亮点
1. 状态驱动架构
通过 Screen 枚举和独立的状态结构，实现清晰的界面切换逻辑。
2. 事件驱动模型
主循环持续监听终端事件，由事件处理器更新应用状态，触发按需重绘。
3. 模块化设计
代码按功能划分为 app、input、ui、states、utils 五大模块，职责明确。
4. 错误处理
使用 color-eyre 提供友好的错误报告和回溯信息。
九、安装与使用
1. 安装方式
从 Crates.io 安装（推荐）
cargo install tmmpr从源码编译
git clone https://github.com/tanciaku/tmmpr.git
cd tmmpr
cargo build --release
# 二进制文件位于 ./target/release/tmmpr2. 快速上手
# 启动应用
tmmpr
# 主要快捷键
? / F1 # 显示帮助
h/j/k/l # 移动视口
a # 添加笔记
v # 选择笔记
s # 保存
q # 退出十、总结
tmmpr 是一个设计精良的终端思维导图工具，通过 Rust 和 Ratatui 实现了高效的无图形界面思维整理。项目采用清晰的状态机架构和模块化设计，代码简洁且功能完整。虽然当前仍处于活跃开发阶段，部分功能有待完善，但核心实现稳定可用，为 Linux 终端用户提供了一个独特的思维导图解决方案。
项目的成功要素在于：
- 精准的定位：服务终端用户的思维整理需求
- 熟悉的交互：Vim 风格的快捷键降低学习成本
- 稳定的技术栈：Rust + Ratatui 保证性能和可靠性
- 持续的迭代：明确的开发路线图和社区反馈机制
参考资料
- tmmpr GitHub Repository
- [Reddit - [TUI] tmmpr - terminal mind mapper](https://www.reddit.com/r/commandline/comments/1qljci8/tui_tmmpr_terminal_mind_mapper/)
- tmmpr on Lib.rs
- [Reddit - [Media] [TUI] tmmpr - terminal mind mapper](https://www.reddit.com/r/rust/comments/1qljnpe/media_tui_tmmpr_terminal_mind_mapper/)