boo 完整使用指南:new、attach、ui 等 8 个核心命令覆盖终端会话管理全流程

原创2026-10-27 11:36:101,453 阅读

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 无此会话、4 wait 超时——在 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> 可以随时查看详细参数。祝玩得愉快!🎉

登录后查看全文
boo