# branchterm

**Repository Path**: ppnt/branchterm

## Basic Information

- **Project Name**: branchterm
- **Description**: rust terminal
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-15
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BranchTerm · 枝端

面向多项目开发的 Rust 原生桌面终端，优先支持 Windows 11。将项目、终端会话和文件预览放在同一个窗口中，适合 PowerShell、Git Bash 及 Codex 等命令行工具的日常工作。

基于 egui/eframe、ConPTY 和 alacritty_terminal，不依赖 WebView。目前为**功能预览版本**，尚未完成 MVP 验收和性能预算实测。

![BranchTerm 深色界面：项目与会话侧栏、终端、文件树及图片预览](docs/images/branchterm-workspace.png)

## 主要功能

| 功能 | 使用方式 |
| --- | --- |
| 项目与多会话 | 按项目分组终端，也可直接创建独立会话；支持固定、最近会话和顶部标签切换 |
| 原生终端 | 运行 PowerShell、Git Bash 或自定义 Shell，支持选择、复制粘贴、回滚和程序鼠标模式 |
| 文件树 | 右侧栏默认收起，点击顶部右侧栏图标展开；支持方向键导航 |
| 文件预览 | Space 打开独立文件标签；文本带行号，PNG/JPEG/BMP 图片、PDF 页面、Word/PPT 文字和 Excel 工作表 |
| 标签管理 | 文件名右侧关闭单个预览，右击文件标签 →「全部关闭」 |
| 默认应用打开 | 文件树中选中文件后按 Enter，通过 Windows 默认应用打开 |
| 中英文与主题 | 设置 → 外观切换中文 / English、深色 / 浅色主题及默认字号，自动保存 |
| 环境与代理 | 全局默认设置与单会话覆盖，支持 HTTP、HTTPS、SOCKS5 / SOCKS5H |
| 历史输出 | 会话关闭后保留启动配置和本地只读文本快照，可重新开启或查看历史 |

## 快速开始

需要 **Windows 11 x64**、**Rust stable MSVC 工具链**和 **Visual Studio C++ Build Tools（含 Windows SDK）**。构建时通过 SDK 的 `rc.exe` 嵌入应用图标；非标准安装可用 `RC` 环境变量指定该工具的完整路径。

```powershell
git clone https://gitee.com/ppnt/branchterm.git
cd branchterm
cargo run --locked
```

构建 release 版本：

```powershell
cargo build --locked --release
```

程序输出到 `target/release/branchterm.exe`。重新构建前先退出该程序，避免 Windows 阻止覆盖正在运行的可执行文件。

Windows x64 构建会同时输出 `conpty.dll` 和 `OpenConsole.exe`；移动或分发程序时必须将这三个文件放在同一目录，并附上 [ConPTY 许可证](vendor/conpty/LICENSE.txt)。固定版本的微软 ConPTY 运行库用于规避部分系统 `conhost.exe` 在 OpenCode 退出时崩溃的问题，来源及校验值见 [运行库说明](vendor/conpty/README.md)。

### 固定到任务栏

启动程序后，右击任务栏图标 →「固定到任务栏」。应用同时提供窗口图标和 exe 内嵌图标。若旧版本已被固定为默认图标，先取消固定旧项，再启动新版并重新固定；固定项应指向长期使用的 exe 路径。

### 创建工作空间

1. 点击「新建会话」即可使用独立终端，无需先创建项目。默认工作目录为用户主目录，可在创建时修改。
2. 需要分组时点击「+ 项目」，填写名称并选择目录；项目旁的 `+` 用于创建项目会话。项目目录可稍后设置，未设置时使用默认工作目录。
3. 选择已检测到的 Shell，或填写自定义可执行文件和启动参数，每行一个参数。PowerShell 预设使用 `-NoProfile`，Git Bash 使用交互式登录 Shell。
4. 在终端中运行命令或手动启动已安装的 Codex 等工具。点击顶部标签或左侧会话切换工作，后台会话继续接收输出。

会话可固定、重命名和重新开启。程序通过 OSC 0/2 设置标题时，顶部标签和侧栏同步显示；动态标题不会覆盖保存的会话名称。

关闭终端标签会结束该 Shell 及其任务，保留启动配置和历史快照；重新开启会启动新进程。右键会话或终端标签 →「查看历史输出」可查看快照。移除项目不会删除磁盘项目文件，但会删除相关历史快照。

### 搜索

Project 搜索仅匹配工程名称；Recents 搜索仅匹配列表中的会话名称与程序显示标题；Files 搜索当前工程目录下的文件名与相对路径。切换工程后 Files 自动切换目录。

### 浏览与预览文件

点击窗口顶部的右侧栏图标展开文件树。首次展开使用当前项目目录；未选中项目时使用会话启动目录或默认目录。**切换项目后点击「刷新」**，文件树会更新到新项目目录。目前不跟随 Shell 中的 `cd`。

| 文件树操作 | 作用 |
| --- | --- |
| 单击文件或目录 | 选择项目，让文件树获得键盘焦点 |
| `↑` / `↓` | 选择上一项 / 下一项 |
| `→` | 展开目录，或进入已展开目录的子项 |
| `←` | 折叠目录，或返回父目录 |
| `Space` | 打开文件预览；已经打开的文件会激活原标签 |
| 双击文件 | 在文件资源管理器中打开所在目录 |
| 双击文件夹 | 在文件资源管理器中打开该文件夹 |
| `Enter` | 使用系统默认应用打开文件 |
| 标签右侧 `×` | 关闭该文件预览 |
| 右击文件标签 →「全部关闭」 | 清空全部文件预览，保留文件树与终端会话 |

文本预览只读并显示行号；图片按可用空间等比缩小，小图不放大。收起右侧栏会恢复终端显示空间，已打开的文件标签保留。

预览目前有以下边界：

- 最多同时打开 8 个文件标签，文本最多读取前 256 KiB。
- 图片支持 PNG、JPEG、BMP；文件上限 16 MiB，解码尺寸每边不超过 4096 像素，预览缩略图每边最多 2048 像素。
- PDF 使用 Windows 原生渲染器按页显示，支持翻页及输入页码；每页最长边最多 1600 像素。
- Word `.docx` 显示正文及表格分隔；PowerPoint `.pptx` 按幻灯片顺序显示文字；不还原图片、动画或原始排版。旧版 `.doc`、`.ppt` 需另存为新格式。
- Excel `.xlsx`、`.xls`、`.xlsb` 按工作表显示数据及行列坐标；每表最多 200 行 × 32 列，公式显示已保存的值，不重新计算。
- 文档文件上限 64 MiB，Office 最多 256 张幻灯片或工作表、512 KiB 文本；超限或损坏显示错误。SVG、动画及其他二进制文件可按 Enter 使用默认应用打开。
- 每个目录最多显示 2000 项，目录链接不递归展开；使用「刷新」重新读取目录。

### 外观与会话属性

左下角「设置」→「外观」可切换中文 / English、深浅主题和新会话默认字号。语言设置不翻译用户名称、路径、终端输出或文件正文。

右键终端或会话 →「属性」可调整当前标签的字号、Shell 可执行文件和启动参数。Shell 设置在下次启动该会话时生效；当前进程继续使用原 Shell。

## 常用快捷键

| 快捷键 | 功能 |
| --- | --- |
| `Ctrl+Shift+N` | 新建会话 |
| `Ctrl+Tab` | 切换终端标签 |
| `Ctrl+Shift+B` | 展开 / 收起左侧栏 |
| `Ctrl+Shift+T` | 切换深色 / 浅色主题 |
| `Ctrl+,` | 打开设置 |
| `Ctrl+Shift+C` 或 `Ctrl+Insert` | 复制终端选中内容 |
| `Ctrl+Shift+V` 或 `Shift+Insert` | 粘贴文本 |
| `Ctrl+Alt+V` | 向终端应用转发组合键，例如由 Codex 处理图片剪贴板 |
| `Shift+PageUp` / `Shift+PageDown` | 翻阅本地回滚内容 |
| 中键点击终端标签 | 关闭会话并保留历史 |

`Ctrl+C`、`Ctrl+V`、`Ctrl+T` 等控制键传给终端程序。多行粘贴会先显示确认，单次文本粘贴最多 4080 字节。主题切换快捷键在模态对话框打开或会话启动/关闭期间不生效。

普通终端支持拖动选择和滚轮回滚。应用启用鼠标模式时，点击和滚轮按终端协议转发；可用 `Shift+滚轮` 查看本地回滚、`Shift+拖动` 选择、`Shift+右键` 打开宿主菜单。具体交互取决于终端应用对鼠标协议的支持。

## 环境变量与代理

设置 →「环境与网络」配置全局默认值，点击「保存环境设置」。新建会话 →「环境与代理」可覆盖单个会话。

环境变量每行一个 `KEY=value`，值无需加引号：

```text
HTTP_PROXY=http://127.0.0.1:10808
NO_PROXY=localhost,127.0.0.1
MY_SETTING=value=with=equals
```

代理支持 `http://`、`https://`、`socks5://`、`socks5h://`，自动设置 `HTTP_PROXY`、`HTTPS_PROXY` 和 `ALL_PROXY`。单会话可选择继承全局、不使用代理或自定义代理。

优先级从低到高为：**系统环境 → 全局代理 → 全局环境变量 → 单会话代理 → 单会话环境变量**。Windows 环境变量名不区分大小写。配置只影响下次启动的进程及其子进程，不修改系统全局代理；是否使用代理取决于各应用对环境变量的支持。

## 配置、历史与当前限制

配置保存在 `%LOCALAPPDATA%/BranchTerm/config.json`，有效配置会备份为 `config.json.bak`，保存使用临时文件原子替换。损坏或未知版本的配置不会自动覆盖。开发测试可用 `BRANCHTERM_CONFIG` 指定独立配置文件。

历史快照保存在配置文件旁的 `config.history/<会话 ID>.txt`，每会话最多 2 MiB，超限裁剪最旧内容。有新输出时后台约每 2 秒更新，正常关闭等待最终保存。快照是终端网格和可用回滚的纯文本，不保留颜色，不完整记录 TUI 每一帧或已清屏内容；异常退出可能丢失最近未保存的部分。

重新启动应用只恢复项目和会话配置，不恢复进程、不重放历史命令。历史快照可能包含终端中显示的数据，存储和清理遵循本机数据管理。

当前最多同时运行 10 个会话，每会话 2000 行历史，网格上限 300×150，待写输入上限 256 KiB。历史行数不代表字节内存预算已经实现。OSC 52 默认禁用，终端输出中的链接和命令不会自动触发系统动作。

中文 IME、多 DPI、复杂字形、Codex 交互、鼠标协议和长时间资源使用仍有待验证的场景。Windows Job 在 Shell 创建后绑定，存在绑定前创建后代进程的竞态。功能测试通过不等于全部 MVP 验收通过，具体状态见[实现与验证记录](docs/implementation-status.md)及[验收测试](docs/acceptance-tests.md)。

## 开发与验证

在仓库根目录执行：

```powershell
cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
cargo test --locked -p egui-winit --lib branchterm_tests
cargo build --locked --release
```

真实 ConPTY 集成测试默认忽略，需要显式执行。本机若存在 `.cargo-local` 依赖缓存，可使用开发脚本：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/dev.ps1 -Task run
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/dev.ps1 -Task test
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/dev.ps1 -Task pty-test
```

`-ExecutionPolicy Bypass` 仅作用于该脚本进程，不修改系统执行策略。Cargo 不在 PATH 时可通过 `-CargoPath` 指定可执行文件。

## 代码与文档

| 路径 | 内容 |
| --- | --- |
| `src/app.rs` | 应用状态、项目与会话生命周期 |
| `src/navigation.rs` | 项目侧栏、终端标签、自绘窗口控件和主题 |
| `src/files.rs` | 文件树、键盘导航、文本与图片预览、文件标签 |
| `src/document_preview.rs` | PDF 页面、Word/PPT 内容与 Excel 工作表预览 |
| `src/i18n.rs` | 中英文界面文案 |
| `src/preferences.rs`、`src/config.rs` | 设置、会话属性、配置校验与持久化 |
| `src/terminal.rs`、`src/job.rs` | ConPTY、VT 模型、I/O worker 和 Windows Job |
| `src/view.rs`、`src/input.rs` | 终端绘制、选择、IME 与输入编码 |
| `src/history.rs`、`src/folder_picker.rs` | 历史快照和 Windows 原生目录选择器 |
| `scripts/dev.ps1` | 开发命令与可选本地依赖缓存 |
| `build.rs`、`assets/` | Windows 图标资源编译及窗口/可执行文件图标 |

图标源绘制脚本为 `scripts/generate-icon.py`，修改图标时使用 Python 与 Pillow 重新生成 `assets/branchterm.png` 和多尺寸 `.ico`；日常 Cargo 构建不需要 Python。

- [文档索引](docs/README.md)
- [产品需求](docs/product-requirements.md)
- [架构与选型](docs/architecture.md)
- [MVP 路线图](docs/mvp-roadmap.md)
- [验收测试](docs/acceptance-tests.md)
- [实现与验证记录](docs/implementation-status.md)

工程名称左侧的箭头可折叠或展开该工程下的会话；默认展开，折叠不会停止会话，点击 + 新建会话时自动展开。状态在当前运行期间保留。