终端程序状态协议 (OSC 7501)

A Terminal Protocol for Program Status (OSC 7501)

发布日期： 2026 年 10 月 6 日
作者： Mitchell Hashimoto
参考链接： OSC 7501, the Program Status Protocol

Published: October 6, 2026
Author: Mitchell Hashimoto
Reference: OSC 7501, the Program Status Protocol

文章背景与核心概要

在命令行终端中运行编译、部署以及新兴的自主 AI 智能体 (AI Agent) 等耗时任务时，终端界面往往很难准确获知程序的真实运行状态。以往工具不得不依赖脆弱的屏幕抓取、正则匹配，或是依赖跨 SSH 与容器时极易失效的本地 Socket 接口，导致状态追踪既繁琐又不可靠。为彻底解决这一长期痛点，知名开发者 Mitchell Hashimoto 依托在 Superlogical 与 Ghostty 中的工程实践，正式提出了 OSC 7501 终端转义序列规范。该协议允许命令行程序直接复用现有的伪终端 (PTY) 连接，向终端模拟器精确报告空闲、工作中、等待交互及失败等核心状态。作为一项轻量无外部依赖的标准，OSC 7501 为现代化终端多任务管理及“智能体收件箱”构建了坚实的原生通信基石。

概要

Summary

Mitchell Hashimoto 推出了 OSC 7501——这是一套全新的终端原生转义序列规范，旨在让命令行程序能够直接向终端模拟器通报自身的当前状态 (例如空闲、运行中、被阻塞、已完成或失败)。该通用协议源于作者在 Superlogical 与 Ghostty 中的研发工作，它无需依赖脆弱的屏幕抓取启发式规则或终端外部的非标准 API，彻底解决了长期以来追踪长耗时任务以及“智能体收件箱”状态的行业难题。

Mitchell Hashimoto introduces OSC 7501, a new terminal-native escape sequence specification designed to let command-line programs directly communicate their current state (such as idle, working, blocked, finished, or failed) to the terminal emulator. Born out of work on Superlogical and Ghostty, this generic protocol solves the long-standing problem of tracking long-running tasks and "agentic inboxes" without relying on brittle screen-scraping heuristics or non-terminal APIs.

痛点所在

The Problem

长耗时操作——例如代码编译、服务部署、系统升级以及编程智能体任务——是日常终端工作流中的常客。在过去，终端模拟器主要依靠并不完美的启发式机制来监测这些进程，比如轮询前台进程状态，或是等待输出静止一段时间以判断任务是否结束。

Long-running operations—like builds, deployments, upgrades, and coding agents—are staples of terminal workflows. Historically, terminal emulators have attempted to monitor these processes using imperfect heuristics, such as watching foreground processes or waiting for periods of "quiet" output.

然而，在 SSH 远程会话或容器等复杂环境中，这些临时拼凑的变通方案终究无法以统一且与交互逻辑无关的方式，稳定可靠地传递进度百分比、任务层级以及等待交互的阻塞状态。

Ultimately, these workarounds fail to provide a cohesive, interaction-agnostic way to convey progress, task hierarchies, and blocking states reliably across complex environments like SSH or containers.

聚焦“智能体收件箱”场景

Singling Out "Agentic Inboxes"

随着后台 AI 智能体 (这类程序往往需要频繁暂停以等待人工授权或输入参数) 的快速兴起，催生出了一类被称为“智能体收件箱 (agentic inboxes)”的新型工具 (例如 Herdr、cmux 以及 Agent Deck)。由于缺乏标准化的通信协议，当前这些工具只能退而求其次地采用以下方式：

The rise of background AI agents (which frequently pause to ask for permissions or input) has spawned a new category of tools called agentic inboxes (e.g., Herdr, cmux, and Agent Deck). Without a standardized protocol, these tools resort to:

启发式推断：通过读取窗口标题，或者使用脆弱的正则表达式匹配终端字符 (例如检测盲文字符动画转轮 Braille spinners) 来猜测程序状态；
非终端外部 API：依赖带外本地 Socket 通信，但这在跨 SSH 远程连接或进入容器后就会彻底失效。

Heuristics: Guessing state by reading window titles and matching characters against fragile regexes (such as tracking Braille spinners).

Non-Terminal APIs: Relying on out-of-band local sockets, which break over SSH or inside containers.

而采用终端原生的转义协议，则可以直接复用既有的伪终端 (PTY) 连接通道，天然规避了上述所有限制。

A terminal-native protocol natively bypasses these limitations by utilizing the existing PTY connection.

程序状态协议 (OSC 7501) 解析

The Program Status Protocol (OSC 7501)

OSC 7501 协议允许应用程序通过 PTY 安全地汇报状态变更。转义序列的主体由冒号 : 分隔的 key=value 键值对构成，其中 state 键是必须包含的必选字段：

OSC 7501 allows programs to report state changes safely over the PTY. The body of the sequence consists of key=value pairs separated by :, where the state key is required:

ESC ] 7501 ; state=blocked:kind=permission:app=terraform:msg=QXBwbHkgMyB0byBhZGQsIDEgdG8gY2hhbmdlLCAwIHRvIGRlc3Ryb3k/ ESC \

支持的状态类型

Supported States

`state` 状态值	含义说明
`idle`	处于空闲静止状态，等待用户的下一条指令。
`working`	正在运行工作中 (可附带 `progress` 进度百分比)。
`done`	执行完毕；执行结果已就绪且尚未被用户查看。
`blocked`	暂停运行，等待用户交互操作 (`kind` 用于指定 `permission` 权限请求、`question` 提问或 `auth` 鉴权认证；`msg` 说明具体原因)。
`error`	执行失败并已停止。

state Meaning

idle At rest, waiting for the user's next instruction.

working Running (may include a progress percentage).

done Finished; results are ready and unviewed.

blocked Halted awaiting user action (kind specifies permission, question, or auth; msg explains why).

error Failed and stopped.

Shell 脚本集成示例

Example Shell Integration

将该协议集成到简单的 Shell 脚本中 (比如封装 rsync 任务) 极为轻量，完全不需要任何庞大的 SDK 或 JSON 解析器：

Integrating the protocol into simple shell scripts (like wrapping rsync) requires no heavy SDKs or JSON parsers:

status() {
  printf '\e]7501;state=%s:msg=%s\e\\' "$1" "$(printf '%s' "$2" | base64 | tr -d '\n')"
}

status working "Syncing photos"
rsync -a ~/Photos backup:/photos && status done "Photos synced" || status error "rsync failed"

立即接入与落地实践

Implement It

目前该协议规范已完全定义完毕，并已被整合进 libghostty 和 Rex 等工具中；同时，Terraform、Claude Code、Codex 以及 Homebrew 也均已落地了概念验证 (PoC) 实现。

The specification is fully defined and already integrated into tools like libghostty and Rex, with proof-of-concept implementations across Terraform, Claude Code, Codex, and Homebrew.

欢迎查阅完整的 OSC 7501 规范文档，进一步深入了解记录生命周期、特性探测、terminfo 配置、长度限制以及安全考量等细节。

Read the full OSC 7501 Specification to review details on record lifetimes, feature detection, terminfo, size limits, and security.

`state`	Meaning
`idle`	At rest, waiting for the user's next instruction.
`working`	Running (may include a `progress` percentage).
`done`	Finished; results are ready and unviewed.
`blocked`	Halted awaiting user action (`kind` specifies `permission`, `question`, or `auth`; `msg` explains why).
`error`	Failed and stopped.