boo 完整使用指南:new、attach、ui 等 8 个核心命令覆盖终端会话管理全流程
boo 完整使用指南:new、attach、ui 等 8 个核心命令覆盖终端会话管理全流程
boo 是一个 GNU screen 风格的终端复用器(terminal multiplexer),基于 libghostty(libghostty-vt)构建,使用 Zig 编写。它的核心能力是:会话(session)在你断开连接后继续运行,重新附加(attach)时屏幕内容、滚动历史和窗口标题都能原样恢复。本文用 8 个核心命令——new、attach、ui、ls、send、peek、wait、kill——带你完整走一遍终端会话管理全流程。
为什么需要 boo 🛠️
传统 GNU screen 自带一个年代久远的终端仿真器,现代程序输出的新转义序列它常常"看不懂",重绘时内容就会丢失或错乱。boo 把这层换成了 Ghostty 的 VT 核心(libghostty-vt):
- 会话永不掉线:
Ctrl-A d分离(detach),boo attach随时接回; - 忠实重绘:基于 libghostty 保存的终端状态重放 SGR 样式、光标、滚动区域和终端模式;
- 全屏幕会话管理器:
boo ui用侧边栏列出所有会话; - 自动化友好:
send、peek、wait都支持--json且无需 TTY,天然适合脚本和 AI Agent 驱动交互式程序。
架构上,你的终端通过 Unix socket 连接每个会话独立的守护进程,守护进程持有 PTY 并驱动 ghostty-vt 终端流,详见 src/protocol.zig、src/daemon.zig 和 src/window.zig。
一键安装:两种方式快速上手 📦
方式一:官方安装脚本(Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/coder/boo/main/install.sh | sh
安装脚本会自动识别架构(x86_64/aarch64)、下载对应预编译二进制,默认装到 /usr/local/bin(不可写时落到 ~/.local/bin)。可用 BOO_VERSION 固定版本、BOO_INSTALL_DIR 指定安装目录,脚本逻辑见 install.sh。
方式二:源码构建
需要 Zig 0.15.2,libghostty 依赖会自动拉取并从源码构建:
git clone https://gitcode.com/gh_mirrors/boo10/boo
cd boo && zig build
# 产物位于 zig-out/bin/boo
也可以用 Nix:nix develop 进入带正确 Zig 版本的环境,nix build 打包到 ./result/bin/boo(配置见 flake.nix)。
8 个核心命令总览 🗂️
| 命令 | 别名 | 作用 |
|---|---|---|
boo new |
— | 创建会话(默认附加) |
boo attach |
at、a |
附加到已有会话 |
boo ui |
i |
全屏会话管理界面 |
boo ls |
list |
列出所有会话 |
boo send |
— | 向会话"打字" |
boo peek |
— | 读取会话当前屏幕 |
boo wait |
— | 阻塞等待输出满足条件 |
boo kill |
— | 结束一个或全部会话 |
💡 前缀匹配:所有带 <name> 参数的命令都接受会话名的唯一前缀,比如 boo attach bu 就能命中名为 build 的会话。解析逻辑在 src/main.zig#L131-L158。
会话生命周期:new → attach → ls
boo new:一条命令创建会话
boo new # 运行 $SHELL,立即附加
boo new work # 命名会话
boo new build -d -- make -j # 后台创建(-d 分离),运行 make -j
不带名字时,会话以当前目录名命名,重名则回退到进程 PID。-- 之后是会话里要运行的命令;-d 启动不附加并在 stdout 打印会话名(方便脚本捕获);--rows/--cols 指定初始终端尺寸;--cwd 指定工作目录。完整参数说明见 src/help.zig#L64-L91,实现入口在 src/main.zig#L257-L363。
boo attach:重新接回你的屏幕
boo attach build # 重新附加
boo at bu # 效果相同,用前缀
附加时,屏幕、滚动历史、光标和标题都从 libghostty 的终端状态恢复——正是"人肉"盯着时会看到的样子。注意每个会话只允许一个附加客户端:如果你在另一台机器上再次 attach,旧客户端会被礼貌地"偷走"(steal),提示 <a href="https://link.gitcode.com/i/f07127ba07439e23b3a24057435480a7" target="_blank">session build attached elsewhere],见 [src/main.zig#L382-L403。
boo ls:快速盘点所有会话
boo ls # 名称、附加状态、空闲时间、窗口标题
boo ls --json # JSON 数组,供脚本消费
输出包含 name、attached、idle_ms、unread、bell_idle_ms、title 六个字段。unread 标记你有未读输出,bell_idle_ms 标记你不在时响过的"铃"(比如 Agent 完成了回合),非常适合写轮询脚本。实现在 src/main.zig#L430-L505。
boo ui:全屏会话管理器 🖥️
boo ui # 别名:boo i
左侧边栏列出全部会话(名称下方显示窗口标题),右侧视口实时渲染当前聚焦的会话。侧边栏标记很有用:
- ●(粗体蓝):你离开时有 bell 响起——"该你了";
- •(暗淡):有未读输出;
- *:被其他客户端附加中。
鼠标操作:点击会话即聚焦(同样遵循 steal 规则),点击其 x 可终止(需确认),视口内滚轮可回看历史,拖拽可选择复制(OSC 52)。常用快捷键:
| 按键 | 作用 |
|---|---|
C-a c |
创建新会话并聚焦 |
C-a k |
终止聚焦的会话(需确认) |
C-a g |
按名称跳转会话 |
C-a n / C-a p |
下一个 / 上一个会话 |
C-a s |
显示或隐藏侧边栏 |
C-a d |
退出 UI(会话继续运行) |
更多绑定见 boo help ui(src/help.zig#L116-L178)与 src/ui.zig、src/keys.zig。
自动化三件套:send、peek、wait ⚡
这三个命令除 attach 外都不需要终端,是 boo 作为脚本/AI Agent 沙箱的核心。
boo send:像打字一样输入
boo send build --text 'make test' --enter # 输入并提交
boo send build --key C-c # 发送中断
printf 'y\n' | boo send build # 从 stdin 管道输入(二进制安全)
--text 是字面量发送:无转义处理、无隐式换行,没有引号地狱;--key 支持 Enter, Tab, Escape, Space, Backspace, Up, Down, Left, Right, Home, End, C-a..C-z(键名到字节序列的映射见 src/main.zig#L587-L620);stdin 模式二进制安全,仅排除 NUL。
boo peek:读取"人眼所见"的屏幕
boo peek build | tail -20
boo peek build --scrollback | grep -n error
peek 输出的是从终端状态重建的渲染屏幕,而不是原始字节日志——有序、完整重绘、稳定。--scrollback 包含完整历史,--json 额外给出尺寸、光标和标题。实现在 src/main.zig#L665-L723。
boo wait:告别 sleep 轮询
boo wait build --text 'PASS' --timeout 2m # 等到屏幕出现 PASS
boo wait build --idle # 等到输出安静 2 秒
--text 做子串匹配;--idle 在输出静默 2 秒后返回(静默阈值定义在 src/main.zig#L726);--timeout 超时退出码为 4,时长支持 500ms、2s、1m、4h、1d 等单位。
标准自动化循环
boo new build -d -- bash # 1. 无头会话
boo send build --text 'make' --enter # 2. 输入
boo wait build --idle # 3. 等输出稳定
boo peek build --scrollback # 4. 读屏
boo kill build # 5. 清理
完整说明见 boo help automation(src/help.zig#L342-L387)。
清理与收尾:kill 和 rename 🧹
boo kill build # 结束会话:进程收到 SIGHUP,守护进程退出
boo kill --all # 结束所有会话并清理残留 socket
boo rename work api-server # 重命名,不影响正在运行的程序
kill 的实现见 src/main.zig#L787-L835,rename 见 src/main.zig#L836-L850。
会话内快捷键速查(前缀 Ctrl-a)⌨️
| 按键 | 动作 |
|---|---|
C-a d、C-a C-d |
分离(会话继续运行) |
C-a l、C-a C-l |
重绘屏幕 |
C-a a |
发送一个字面的 C-a |
绑定遵循 GNU screen 默认,详见 boo help keys(src/help.zig#L324-L340)。
退出码与环境变量:脚本友好的细节 🔧
- 退出码:
0成功、1错误、2用法错误、3无此会话、4wait 超时——在 src/main.zig#L16-L20 中统一定义; BOO_DIR:socket 目录(默认$XDG_RUNTIME_DIR/boo,否则/tmp/boo-<uid>);BOO_LOG:将守护进程与boo ui的日志追加到该文件,便于调试;BOO_VERSION/BOO_INSTALL_DIR:控制安装脚本行为。
项目结构与源码导航 📂
| 模块 | 说明 |
|---|---|
| src/main.zig | CLI 入口与 8 个核心命令分发(L66-L77) |
| src/help.zig | 全部帮助文本,一处维护 |
| src/client.zig | 客户端:TTY 原始模式 + socket 传输 |
| src/daemon.zig | 会话守护进程 |
| src/window.zig | PTY 子进程 + ghostty-vt 终端流 |
| src/protocol.zig | 帧化 Unix socket 协议 |
| src/ui.zig / src/keys.zig | 全屏 UI 与按键处理 |
| test/integration.zig | 真实 PTY 上的端到端测试 |
| bench/render.zig | 渲染基准测试 |
构建与测试命令:zig build(构建)、zig build test(单元测试)、zig build test-integration(PTY 集成测试)、zig build test-all(全部)。
已知限制,先知道不踩坑 ⚠️
boo 还年轻,不是 GNU screen 的即插即用替代品:
- 每会话仅一个附加客户端(attach 会 steal),没有
-x共享; - 每会话单窗口:无分屏和标签页,建议"一个任务一个会话",用
boo ui切换; C-a前缀暂不可配置;粘贴内容中的0x01字节会被当作前缀(GNU screen 同样如此,boo ui因 bracketed paste 免疫);- 会话运行在
TERM=xterm-256color下。
小结
用一句话串联全流程:boo new 开会话 → boo attach 接回来 → boo ui 总调度 → boo ls 查状态 → boo send / boo wait / boo peek 驱动与观测 → boo kill 收场。这 8 个命令就覆盖了从交互使用到脚本自动化的全部场景,配合 boo help <command> 可以随时查看详细参数。祝玩得愉快!🎉