OSC 7501 Program Status Protocol 调研

By 陈成 · Published November 4, 2026

OSC 7501 是什么、解决什么问题,生态跟进到哪了,有哪些争议?

整理日期:2026-11-02 信息来源:X 书签与评论、X 搜索、规范原文、Mitchell 的博客、areweosc7501yet.com、tmux issue、Reddit、Hacker News、pi v1.1.0 与 opencode v2.2.0 源码(第 6 节)

TL;DR


1. 我的书签

在 X History → Bookmarks 里搜 7501 / OSC,命中:

书签 内容 与主题的关系
@ZacharyZhang · ELYTerminal 0.1.3(10-18) 自研终端,约 10 MB。新增会话状态(等你操作 / 出错 / 进行中带进度 / 已完成)和三平台系统通知 直接相关:“程序可以上报状态和进度(OSC 7501、OSC 9;4),也可以发通知(OSC 9 / 777 / 99)。在 herdr 里,会话状态跟随 herdr 的 agent。”
@zoomq · luvus 吐槽(08-25) luvus 0.12.0 内置 agent 表只认 pi,不认 Oh My Pi 的 omp 间接相关:说明“按进程名 / 屏幕文字猜 agent”的老办法很脆弱,正是 OSC 7501 要解决的问题

ELYTerminal 那条推的评论基本是在聊 UI(粉色看板娘 ELY、主题、herdr 快捷键失效),没有讨论协议本身。


2. 协议本体

规范原文:https://www.superlogical.com/rex/docs/build/program-status(当前 rev 0.4,2026-10-10)

2.1 语法

OSC 7501 ; pairs ST        上报
OSC 7501 ; ? ST            特性探测

pairs := pair (":" pair)*
pair  := key "=" value
key   := [a-z]+
value := [A-Za-z0-9_.,+/=-]*      # 不含 : 和 ;,所以无需转义

2.2 状态与生命周期

state 含义 生命周期
idle 空闲,等用户下一条指令 直到被替换或清除
working 运行中,可带 progress 进程退出或下一个 shell prompt(OSC 133 A)时清掉
blocked 必须等用户操作,kind 说明原因 同 working
done 完成,结果还没被看过 进程退出和 prompt 后仍保留,什么时候消失由终端决定
error 失败并停止 同 done
clear 不是状态,删除该 id 及其子 record —
stateDiagram-v2
    [*] --> idle
    idle --> working: 开始任务
    working --> blocked: 需要用户\nkind=permission/question/auth
    blocked --> working: 用户已处理
    working --> done: 完成
    working --> error: 失败
    working --> idle: 用户中断/取消
    done --> [*]: 用户回来看过\n(终端决定)
    error --> [*]: 用户回来看过
    note right of working
      进程退出 / 新 shell prompt
      会丢弃 working 与 blocked
      done 与 error 保留
    end note

规范明确没有心跳,终端不能要求程序重复发送来保活。

2.3 Key 一览

key 值 说明
state 见上 必填。不认识的值会让整条上报被忽略,所以将来新增的状态在旧终端上不会被误当成 idle
id seg/seg/...,每段 ≤32 字符、≤8 层 不填就是 root record。/ 表示父子关系,用于级联清除和继承 app
kind permission / question / auth 只对 blocked 有效
progress 0–100 只对 working / blocked 有效,不填表示不确定进度
app 如 cargo、claude-code 稳定的机器标识,用来分组和选图标。子 record 从祖先继承
title base64 多 record 时给人看的标签
msg base64 一行人类可读描述,终端不能从中解读语义

每次上报都会完整替换对应的 record,所以 app 这类字段每次都要带上。

2.4 多 record(树)

graph TD
    R["root · app=deploy<br/>working: Deploying v2.4.1"]
    A["us-east<br/>working 40%: Pushing image"]
    B["eu-west<br/>blocked kind=permission:<br/>Approve deploy to production?"]
    R --> A
    R --> B

root 显示 working,同时子任务 eu-west 是 blocked。两者都成立,展示哪个由终端决定。

2.5 特性探测

program  → OSC 7501 ; ? ST   紧跟 CSI c (DA1)
terminal → OSC 7501 ; ? : states=idle,working,done,blocked,error : kinds=permission,question,auth ST

终端都会回 DA1,所以如果 DA1 的回复先到,就说明终端不支持 OSC 7501,程序不用等超时。探测是可选的,也可以直接发。 这里有个坑:tmux 只回 DA1,所以 Claude Code 在 tmux 里探测失败,不会上报(见第 5 节)。

2.6 安全与限制

2.7 最小接入示例

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"

3. 为什么要有它(Mitchell 的论证)

博客:A Terminal Protocol for Program Status (OSC 7501)(2026-10-06)

flowchart LR
    subgraph Before["以前"]
      P1[Claude Code / Codex / ...] -->|改窗口标题、画 spinner| T1[终端]
      T1 -->|正则匹配标题 / 截屏| H1[herdr / cmux / 各种 inbox]
      P1 -.->|专用 socket API / cmux notify| H1
    end
    subgraph After["OSC 7501"]
      P2[任意程序] -->|"OSC 7501 ; state=blocked:kind=permission ..."| T2[终端 / 多路复用器]
      T2 --> U[Tab 图标 / 通知 / Inbox / Lua 事件]
    end

4. 生态与采用(截至 2026-10-29,数据来自 areweosc7501yet.com / data.json)

timeline
    title OSC 7501 时间线
    2026-09-28 : rev 0.1 草案 (gist)
    2026-10-06 : rev 0.2 / 博客发布 : libghostty-vt 合入解析器
    2026-10-07 : rev 0.3 (无 progress = 不确定进度;可免探测)
    2026-10-09 : Claude Code v2.1.295 支持 : SwiftTerm 合入
    2026-10-10 : rev 0.4 (探测回复可列 states/kinds;移除 terminfo)
    2026-10-11 : Prowl 发布支持
    2026-10-16 : Termius Android Beta 基于 7501 做 agent 通知
    2026-10-18 : ELYTerminal 0.1.3
    2026-10 下旬 : tmux 作者同意做精简版 (单 root record)
类别 ✅ 已发布 🚧 进行中 / PR ⛔ 停滞或拒绝 / ⚪ 无动静
Coding agents Claude Code v2.1.295、Codex CLI rust-v0.163.0、opencode v2.2.0、pi v1.1.0、Amp、goose、Grok Build、Factory Droid、Crush、Kiro CLI、Antigravity CLI、Docker Agent、Mistral Vibe、MiniMax Code、fx Gemini CLI、Qwen Code、Kimi Code、Hermes Agent、OpenClaw ⚪ Cursor CLI、Kilo Code
CLI / 构建工具 Hugo、tuist、Buildkite Agent/CLI Gradle、MSBuild、Composer、Expo、Aspire、UnrealBuildTool、WebKit ⛔ firebase-tools;⚪ Homebrew、Terraform、Neovim、Nix
库 Bubble Tea v2.1.0、charmbracelet/x、OpenTUI crossterm、libvaxis、tqdm —
终端模拟器 iTerm2 v3.7.5、ghostel、Pebrel kitty、Contour、Intelligent Terminal ⚪ Ghostty(本体)、Alacritty、WezTerm、Warp、VS Code、Windows Terminal、Zed、foot、Rio
多路复用器 / Inbox Rex、cmux、Orca、Prowl Herdr、zellij ⛔ tmux(先拒后松口,见下)
引擎 SwiftTerm libghostty-vt ⚪ xterm.js

X 上的落地案例:


5. 争议与反对意见

5.1 tmux:太重了,先做最小子集

tmux#5713

  1. 提案人给出复现:tmux 只回 DA1,Claude Code 的探测因此判定不支持。pi 可以用 PI_PROGRAM_STATUS=1 跳过探测,但 tmux 会把未知 OSC 直接丢掉。
  2. nicm 第一次回复:“为时过早,先看别的终端和程序会不会跟进。”第二次回复:“pane 标题、OSC 9 进度条、OSC 133 已经够用了。”然后关闭了 issue。
  3. 社区列出支持者名单后,nicm 松口,但仍批评协议“太复杂、太重”:
    • “最低要求是每个 pane 存 64 条 record,这很荒谬。最低应该是 1 条,record 和 id 做成可选扩展。”
    • Codex 实际只发两种序列:state={}:app=codex 和 state=clear。
    • 计划:每个 pane 只存一条 root record,忽略 kind 和可能的 title。不做“进程退出时清除”,只在 OSC 133 A 时清除。暴露 program_state / program_name / program_message 三个 format 变量。
    • 欢迎提 PR。

5.2 “就是给 AI agent 量身定做的”

5.3 已有标准:UAPI.15 OSC 3008、SIGINFO、BEL

5.4 Ghostty 自己的态度

r/Ghostty 上有人说它是被 “shotgun merged” 进 Ghostty main 的,目前只在 libghostty 层面。areweosc7501yet 也显示 Ghostty 本体是 idle。作者本人的终端还没对用户开放这个功能,这一点挺有意思。

5.5 其他建议


6. 实现对照:pi v1.1.0 与 opencode v2.2.0

两份源码分析:pi 看的是 earendil-works/pi tag v1.1.0(引入提交 503c605,Mario Zechner,10-07);opencode 看的是 anomalyco/opencode tag v2.2.0(10-27)和它依赖的 OpenTUI 0.7.0。只读代码,没有在真实终端里跑过。

6.1 一张表看差异

pi v1.1.0 opencode v2.2.0
分层 pi-tui 编码和探测,coding-agent 的 ProgramStatusReporter 把 agent 事件映射成状态 opencode 只调 renderer.setProgramStatus(),校验、base64 和写入都在 OpenTUI 的 Zig native 层
record 只有 root,不发 id / title / progress root 汇总 + 每个待处理会话一条子记录(id = session ID,不合规就用 ses_<sha256 前 16 位>);子 agent 并进根会话,不单独成记录
用到的 state 六种全用:idle / working / blocked / done / error / clear 只有 idle / working / blocked / clear,不发 done、error
kind permission(confirm 对话框)、question(select / input / editor)、auth(登录) permission(工具权限)、question(表单),没有 auth
msg 会话名、对话框标题、错误首行;不放 prompt 和模型输出 固定文案:Permission needs input、Input needs response,汇总时 N sessions need input / N sessions working;会话标题放 title
探测 发 OSC 7501;? + DA1,DA1 先到即不支持,没有超时;结果决定发不发 也发探测,但结果不用于门控,不管支不支持都照发
开关 PI_PROGRAM_STATUS=1 跳过探测直接发,=0 永不发 没有开关
tmux 不做 passthrough,探测必然失败,什么都不发 不做 passthrough(刻意的:外层终端分不清 pane),序列只交给 tmux 自己
退出 TUI.stop() 发 clear,Ctrl+Z、外部编辑器、模式切换也会 clear 再补发 想在卸载时发 clear,但 renderer 已经 _isDestroyed,实际发不出去
去重 / 失败 JSON.stringify 比上一次,不限流 同样按 JSON.stringify 去重;写失败(suspend、背压)不重试,要等下次状态变化
覆盖范围 只有 interactive 模式,-p / json / rpc 不报 只有打开的 tab 和当前查看的会话

6.2 pi 的状态映射

stateDiagram-v2
  [*] --> idle: TUI 启动
  idle --> working: agent_start / 手动 /compact
  done --> working: agent_start
  error --> working: agent_start
  working --> done: agent_settled 且最后一条正常
  working --> error: agent_settled 且 stopReason=error
  working --> idle: agent_settled{aborted}(Esc)
  state "blocked (permission | question | auth)" as blocked
  working --> blocked: 对话框 / 登录
  idle --> blocked: 对话框 / 登录
  blocked --> working: 全部关闭,回到底层状态
  working --> [*]: stop() → clear
  done --> [*]: stop() → clear

6.3 opencode 的状态映射

会话(含子 agent)条件 子记录
有权限请求 blocked:kind=permission
有 question / 表单 blocked:kind=question
running 或有非 synthetic 的 pending working
都没有(空闲、完成、中断、出错) clear(之前没发过就不发)

root 的汇总规则:恰好 1 个 blocked 或 1 个 working 时,直接复用那条会话记录(去掉 id);多个时报 N sessions …,多个 blocked 且 kind 不一致就省略 kind;都没有就是 idle。整条链路靠 Solid 的 createEffect 驱动,数据一变就重算,只把有变化的记录发出去。

opencode 的这部分代码经历过一次回滚:PR #55172(10-13)引入,随 OpenTUI 0.6 升级一起被 revert,PR #55339(10-19)重新加回。v2.2.0 是第一个带这个功能的正式 release,但 release notes 里没提。

6.4 退出 bug(opencode)

sequenceDiagram
  participant O as opencode
  participant R as OpenTUI renderer
  participant S as Solid root
  O->>R: destroyRenderer() → renderer.destroy()
  R->>R: _isDestroyed = true
  R->>S: emit("destroy") → dispose
  S->>O: onCleanup → send(ROOT, clear)
  O->>R: setProgramStatus({state: clear})
  R-->>O: false(已销毁,什么也不写)

后果:退出前 root 是 working / blocked 时,终端按规范会自己丢弃,影响不大;但最常见的是退出前处于 idle,规范只说终端 MAY 丢弃 idle,所以部分终端里会残留一条 idle。单测的 mock renderer 永远返回 true,没测出来。修法很简单:在 renderer.destroy() 之前先发 clear,和现在先清终端标题的做法一样。

6.5 两家共同的问题

这也印证了 Orca 作者那句"多数 agent harness 实现得零零散散,仍然需要 hooks 兜底":同样标着"已发布",pi 和 opencode 能给终端的信息差了一大截。


7. 我的看法

  1. 对 agent 编排工具来说,这是确定的利好。herdr 和 cmux 这类工具可以去掉大部分正则规则。Claude Code、Codex、pi、opencode 这些主力 agent 都已经支持,覆盖了大部分实际使用场景。
  2. tmux 是最大的短板。大量人在 tmux 里跑 agent,tmux 不回探测,Claude Code 就不会上报。tmux 精简版发布之前,tmux 用户还得靠 hooks 或 w1 这类 wrapper,也可以自己在 Claude Code 的 Stop / Notification hook 里往 /dev/tty 写序列。
  3. 规范有分层的余地。nicm 的“单 root record 作为最低要求,id 和多 record 作为可选扩展”很有道理。如果规范转交 UAPI group,rev 1.0 很可能朝这个方向调整。
  4. 自己的 CLI 接入成本很低:在 agent 进入等审批 / 等输入 / 完成 / 失败时各发一条 OSC 7501,带上 app=<name>。探测时记得跟一个 CSI c,避免等待超时。
  5. “已支持”不等于“支持得好”。areweosc7501yet 只看有没有发布,不看实现了哪些部分。从 pi 和 opencode 的代码看,至少要分三档:只有 working / blocked(opencode);完整的单 record,含 done / error(pi);多 record 加层级 id(目前两家都没做到)。自己接入时可以照 pi 的状态映射做,再补上两家都缺的:退出时保留 done / error,失败了重试,blocked 的 msg 写清楚在等什么。

参考链接

规范与官方

支持追踪

实现源码

X

Reddit / HN

Read this report as Markdown · Cite it (BibTeX)