Mori：macOS 原生工作区终端一、概述1. 简介A. 是什么Mori 是一款专为 macOS 设计的原生工作区终端应用。它以项目和 Worktree 为核心组织方式，底层由 tmux 和 libghostty 提供支持。B. 为什么用摆脱零散的终端标签页管理，将 git 仓库作为一等项目持久化会话，关闭应用后重新打开，tmux 中的所有内容仍在运行原生 macOS 体验，侧边栏、命令面板、通知、键盘快捷键一应俱全GPU 渲染终端，基于 libghostty（Ghostty 的渲染引擎）实现 Metal 加速Worktree 感知，同一仓库的多个分支可并排运行，会话相互独立C. 用后能做什么在项目和分支间快速切换，而非在匿名标签页中迷失为每个 worktree 维护独立的 tmux 会话使用原生 macOS 界面管理终端工作流2. 前置知识A. 必备技能基本终端操作和 tmux 使用经验Git 工作树（worktree）概念macOS 基本操作B. 推荐知识tmux 会话管理Ghostty 终端配置二、系统架构1. 工作原理Mori 采用分层架构，将项目、worktree、tmux 会话和 UI 层有机结合。graph TD A[Project git 仓库] --> B[Worktree 分支检出] B --> C[tmux Session 持久化会话] C --> D1[Window 1 标签页] C --> D2[Window 2 标签页] C --> D3[Window 3 标签页] D1 --> E1[Pane 分屏] D2 --> E2[Pane 分屏] D2 --> E3[Pane 分屏]2. 应用架构Mori 采用模块化架构设计，各组件职责清晰。graph TB App[Mori App AppKit + SwiftUI] App --> Core[MoriCore 模型与状态] App --> UI[MoriUI SwiftUI 视图] App --> Tmux[MoriTmux tmux CLI 集成] App --> Git[MoriGit Git 状态发现] App --> Terminal[MoriTerminal libghostty 渲染] App --> Persistence[MoriPersistence SQLite 存储] App --> IPC[MoriIPC Unix Socket + ws CLI] style App fill:#f9f,stroke:#333,stroke-width:2px style Terminal fill:#bbf,stroke:#333,stroke-width:2px style Tmux fill:#bfb,stroke:#333,stroke-width:2px3. 组件说明MoriCore：应用数据模型和可观察状态管理MoriUI：SwiftUI 侧边栏视图MoriTmux：tmux 命令行集成（actor 模式）MoriGit：Git worktree 和状态发现（actor 模式）MoriTerminal：libghostty 终端表面MoriPersistence：基于 GRDB 的 SQLite 持久化MoriIPC：Unix socket IPC 和 ws 命令行工具三、环境准备1. 系统要求macOS 14（Sonoma）或更高版本tmuxmise（任务运行器）Zig 0.15.2 + Xcode（用于构建 libghostty）2. 安装依赖安装 tmux：brew install tmux安装 mise：brew install mise安装 Zig（用于构建 libghostty）：brew install zig3. 获取源码git clone https://github.com/vaayne/mori.git cd mori四、构建与运行1. 快速构建Mori 使用 mise 作为任务运行器，提供以下命令：mise run build # Debug 构建 mise run build:release # Release 构建 mise run dev # 构建并运行 mise run test # 运行所有测试 mise run clean # 清理构建产物2. libghostty 构建首次运行时，mise run build 和 mise run build:release 会自动引导 libghostty XCFramework 的构建。也可以手动构建：mise run build:ghostty # 需要 Zig 0.15.2 + Xcode该命令会自动下载 Metal Toolchain（如果缺失）。3. 验证安装mise run dev成功启动后，你将看到 Mori 的原生 macOS 界面，左侧为项目侧边栏，右侧为终端区域。五、核心功能1. 项目管理Mori 以项目为核心组织单元，每个项目对应一个 git 仓库。通过 CLI 可以管理项目：mori project list # 列出所有项目 mori open /path/to/repo # 打开项目2. Worktree 管理Worktree 是 Mori 的核心概念，允许同一仓库的不同分支并排运行：mori worktree create <project> <branch> # 创建新 worktree mori focus <project> <worktree> # 聚焦到指定 worktree每个 worktree 拥有独立的 tmux 会话，互不干扰。3. tmux 会话管理Mori 通过 tmux CLI 集成实现会话管理。每个 worktree 对应一个 tmux session：mori send <project> <worktree> <window> "command" # 发送命令 mori new-window <project> <worktree> <name> # 创建新窗口六、键盘快捷键1. 核心快捷键快捷键功能Cmd + T新建标签页（tmux window）Cmd + W关闭分屏Cmd + D右侧分屏Cmd + Shift + D下方分屏Cmd + 1-9跳转到指定标签页Ctrl + Tab / Ctrl + Shift + Tab循环切换 worktree2. 高级功能快捷键功能Cmd + Shift + N新建 worktreeCmd + Shift + P命令面板Cmd + B切换侧边栏Cmd + G打开 LazygitCmd + E打开 Yazi完整快捷键列表请参考官方文档 docs/keymaps.md。七、终端配置1. Ghostty 配置Mori 使用 Ghostty 的配置系统。在 ~/.config/ghostty/config 中自定义终端设置。Mori 仅覆盖少量嵌入相关设置（无窗口装饰、最后一个窗口不退出）。2. 配置示例# 字体设置 font-family = JetBrains Mono font-size = 14 # 颜色主题 background = 1e1e1e foreground = d4d4d4 # 光标样式 cursor-style = bar cursor-style-unfocused = hollow # 滚动缓冲 scroll-limit = 10000八、工作流示例1. 多项目开发场景graph LR A[Mori 启动] --> B[选择项目] B --> C{选择 Worktree} C --> D[feature 分支] C --> E[main 分支] C --> F[hotfix 分支] D --> G[tmux Session 1] E --> H[tmux Session 2] F --> I[tmux Session 3]2. 典型使用流程打开 Mori 应用在侧边栏选择项目使用 Cmd + Shift + N 创建新 worktree在 worktree 中打开多个 tmux 窗口（编辑器、日志、测试等）使用 Cmd + 1-9 在窗口间快速切换关闭 Mori，tmux 会话保持运行重新打开 Mori，所有工作状态完好如初九、常见问题1. 构建问题Zig 版本不匹配：确保使用 Zig 0.15.2Xcode 未安装：从 App Store 安装 XcodeMetal Toolchain 下载失败：检查网络连接，手动下载2. 运行问题tmux 版本过旧：使用 brew 升级 tmux权限问题：确保 Mori 有访问终端的权限3. 配置问题Ghostty 配置不生效：检查配置文件路径 ~/.config/ghostty/config快捷键冲突：在系统设置中检查是否有冲突的快捷键十、参考资料参考资料Mori GitHub 仓库mise 官方文档tmux 官方文档Ghostty 官方网站