Ghostel桌面通知与进度报告教程:OSC 9/777协议实时监控终端任务的完整配置
Ghostel桌面通知与进度报告教程:OSC 9/777协议实时监控终端任务的完整配置
Ghostel 是一款基于 libghostty 引擎的 Emacs 终端模拟器,它原生支持 OSC 9 / OSC 777 桌面通知和 ConEmu OSC 9;4 进度报告协议——当你在终端里跑编译、下载、AI Agent 等长任务时,Ghostel 能把「构建完成」「任务失败」推送为系统桌面通知,并在模式线实时显示 [42%] 这样的进度条。本教程带你用不到 5 分钟完成全部配置。
为什么需要终端桌面通知?🔔
在 Emacs 里跑 make、cargo build、pip install 或 Claude Code 这类耗时命令时,你经常要切到别的窗口写代码、看文档。传统终端只能等程序跑完回到缓冲区看结果,而 Ghostel 利用两个成熟的终端转义协议,让通知「主动找到你」:
| 协议 | 来源 | 携带信息 | 用途 |
|---|---|---|---|
| OSC 9 | iTerm2 风格 | 仅正文(BODY) | 简单桌面通知,如「构建完成」 |
| OSC 777 | rxvt notify 扩展 |
标题 + 正文 | 带主题的通知,如「CI: 测试失败」 |
| OSC 9;4 | ConEmu 风格 | 状态 + 百分比(0-100) | 任务进度实时监控 |
解析工作全部由 src/handler.zig 中的原生 VT 处理器完成,与 Ghostty 终端使用同一套解析器,性能开销几乎为零。
快速开始:3步启用桌面通知 ⚡
Ghostel 的通知功能开箱即用,默认处理器 ghostel-default-notify 的降级策略很聪明:
- 装了 [alert] 包 → 自动调用系统通知(macOS 用 osascript,Linux 用 libnotify,还有 Growl、terminal-notifier 等后端),可通过
alert-default-style调整样式。建议先安装:M-x package-install RET alert RET - 没装 alert → 自动降级为 Emacs 回显区
message提示,不丢通知。 - 完全不想通知 → 把
ghostel-notification-function设为nil即可静默。
核心变量定义在 lisp/ghostel.el,标题为空时(OSC 9 只带正文的场景)会自动回退使用当前缓冲区名作为摘要。
验证配置是否生效
在任意 Ghostel 缓冲区里跑一行命令,立即验证桌面通知:
printf '\e]777;notify;测试通知;你好 Ghostel\e\\'
如果弹出系统通知,说明配置成功 ✅。空标题和空正文同时为空的序列会被自动丢弃,避免弹出无意义的空通知。
进度报告:用 OSC 9;4 让模式线变成进度条 📊
ConEmu 风格的 OSC 9;4 是长任务进度的标准方案,构建工具、Claude Code 等 AI Agent、下载器都在用它上报百分比。Ghostel 把这些报告分派给 ghostel-progress-function,支持 5 种状态:
set→ 模式线显示[42%]indeterminate→ 显示[...](不确定进度)error→ 红色显示[err 73%]pause→ 显示[paused 25%]remove→ 清除进度指示器
两个内置处理器二选一:
| 处理器 | 效果 | 依赖 |
|---|---|---|
| ghostel-default-progress | 纯文本百分比,如 [42%] |
零依赖 |
| ghostel-spinner-progress | 不确定进度时动画旋转条,确定进度时回退文本 | [spinner] 包 |
配置建议:ghostel-progress-function 会在加载时自动检测——装了 spinner.el 就默认用动画版,否则用纯文本版。想指定动画风格时,调整 ghostel-spinner-type(默认 progress-bar,可换成 horizontal-moving 等)。
进阶:SSH 远程场景的通知转发 🌐
通过 ssh 连接远程机器时(Ghostel 的 TRAMP 远程终端同样支持这些协议),通知发生在远端 Emacs 上,你的本地桌面却收不到。Ghostel 提供了专门的解决方案 ghostel-tty-forward-notify:
- 在 tty 框架(
emacs -nw/emacsclient -t)中,它把 OSC 9 / OSC 777 原样重新发送到外层终端——远程 Emacs 上的通知就能出现在你本地桌面上; - 在 GUI 框架中,自动回退到
ghostel-default-notify本地弹出。
在配置里加一行即可启用:
(setq ghostel-notification-function #'ghostel-tty-forward-notify)
⚠️ 注意:如果中间隔了 tmux 或 screen,转义序列会被它们拦截丢弃,转发将失效——建议远程直连或让 tmux 透传 OSC。
常见问题(FAQ)
Q:通知处理器会不会卡住终端输出?
不会。通知通过 run-at-time 异步分派(见 ghostel--handle-notification),慢速后端(DBus、osascript 等)不会阻塞终端解析;处理器报错也只记录消息,不会让终端崩溃。
Q:进度显示会残留吗?
不会。终端执行 RIS 全复位序列(如切换全屏 TUI)时,Ghostel 会显式派发 remove 状态清除模式线进度,避免残留旧数据。
Q:如何自定义通知的去向?
ghostel-notification-function 接收 (标题 正文) 两个字符串参数,你可以把它设为任意 lambda,把通知转发到消息应用、日志或其他任何地方。
总结
Ghostel 让 Emacs 终端拥有了与独立 Ghostty 终端同级的 VT 能力:OSC 9/777 桌面通知 + ConEmu 进度报告,配合模式线实时反馈,长任务不再需要你来回切窗口盯守。更多协议细节(OSC 7 目录跟踪、OSC 133 提示符导航等)可阅读官方文档 README.org 的「Notifications and progress」章节,行为验证可参考 test/ghostel-osc-test.el 中的完整测试用例。

