跳到主要内容
ansicode

OSC 9 ; 4 — ConEmu 进度指示器（Windows Terminal / Ghostty）

把实时进度百分比 / 暂停 / 错误状态推送到任务栏或标签图标 —— ConEmu 协议，被 Windows Terminal 1.18+ 标准化。

字节形式

涵盖所有常见的字符串字面量写法，方便正反查找。

\\x1b[\x1b]9;4;<state>;<percent>\x07
\\033[\033]9;4;<state>;<percent>\007
\\e[\e]9;4;<state>;<percent>\a
ESC [ESC ] 9 ; 4 ; STATE ; N BEL
hex1b 5d 39 3b 34 3b ... 3b ... 07

说明

ConEmu 把 OSC 9 重用为进度条 —— 与 iTerm2 的 OSC 9 ; <消息> 通知（slug osc-notification）不同；第二个 token ;4 是消歧符。终端将进度状态转发给所在的环境 UI：Windows Terminal 更新任务栏图标（Windows 11 统一进度 UX）；Ghostty / WezTerm 给标签指示器上色；ConEmu 在标题栏画一条水平进度条。四种状态（;4; 后第一个数字）：

- 0 —— 移除 / 清除进度（显式复位）。 - 1 —— 正常进度，<percent> 0–100 —— 默认线性进度条。 - 2 —— 错误状态，<percent> 0–100 —— 进度条转红，用于带进度的构建失败。 - 3 —— 不确定 —— <percent> 忽略；渲染不定形旋转 / 流条。 - 4 —— 警告 / 暂停，<percent> 0–100 —— 黄色。

用法：长时间 CLI 命令（docker pull、cargo build、ffmpeg 转码、apt 类安装器）在每个有意义步骤后发 OSC 9 ; 4 ; 1 ; <pct>，成功时发 OSC 9 ; 4 ; 0。失败时：OSC 9 ; 4 ; 2 ; <最后 pct>，用户确认后可选再发 0。不支持的终端静默丢弃 —— 可无条件发送。关键细节：\x1b]9; 前缀与 iTerm2 通知 OSC 9 撞名；几乎所有同时实现两者的模拟器以是否带 ;4 作判别，所以完整发送 \x1b]9;4;<state>;<pct>\x07，不要缩写。

规范出处: ConEmu OSC 9;4 / Windows Terminal 1.18+ / Ghostty

参数

state0 移除、1 正常、2 错误、3 不确定、4 警告 / 暂停。
percent0–100 整数（state=3 不确定时忽略；1/2/4 必需）。

示例

bash
# Build-progress wrapper:\nfor pct in 10 30 60 90; do\n  make step-$pct\n  printf '\033]9;4;1;%d\007' "$pct"\ndone\nprintf '\033]9;4;0\007'   # clear on success
python
import sys, time\nfor pct in range(0, 101, 5):\n    sys.stdout.write(f'\x1b]9;4;1;{pct}\x07'); sys.stdout.flush()\n    time.sleep(0.05)\nsys.stdout.write('\x1b]9;4;0\x07')
go
// Indeterminate while waiting on the network:\nfmt.Print("\x1b]9;4;3\x07")\ndoSlowFetch()\nfmt.Print("\x1b]9;4;0\x07")
javascript
// Error red-bar at 50%:\nprocess.stdout.write('\x1b]9;4;2;50\x07')
c
/* Warning / paused state at 75%: */\nprintf("\x1b]9;4;4;75\x07"); fflush(stdout);

在哪里用到

实际会发出该序列的工具——把抽象字节锚定到你已经用过的命令上。

  • winget install发 `\x1b]9;4;1;<percent>\x07` 让 Windows Terminal 在任务栏图标上画绿色进度段 —— 无需聚焦即可从任务栏一眼看到安装进度
  • PowerShell Write-Progress现代 PSReadLine 把 `Write-Progress` 桥接到 OSC 9;4 —— pwsh 脚本里的进度条在 Windows Terminal 上自动作为任务栏进度显示
  • npm, pnpm, yarn install progressNode 终端库（`npmlog`、`gauge`）在 `COLORTERM` 提示 Windows Terminal 时可选发出 OSC 9;4 —— 长时间安装在任务栏进度旁同时绘制
  • robocopy /tee, MSBuild publishrobocopy 的 `/tee` 管道与 MSBuild 发布目标在新版 Win11 上都用 OSC 9;4 包装进度 —— 复制或构建完成即使提示符被切到后台也会在任务栏显示
  • ConEmu, Cmder (origin of OSC 9;4)ConEmu 首创 `\x1b]9;4;<state>;<value>\x07` 家族 —— 微软为 Windows Terminal 兼容性原封不动地采纳，所以为 ConEmu 进度 API 写的任何工具在 WT 中无需修改即可运行

常见问题

针对这条序列，开发者真正会去搜索的问题的简短回答。

哪些终端真正显示 OSC 9;4 进度？长什么样？
Windows Terminal（1.20+）、ConEmu、较新的 WezTerm 会把 OSC 9;4 渲染为任务栏 / 标签进度指示器 —— Windows 在任务栏按钮上画进度条，WezTerm 在标签标题里画。iTerm2 有独立的私有形式（OSC 1337;）。Linux 终端（gnome-terminal、konsole、xterm）和 macOS Terminal.app 完全忽略 OSC 9;4。不存在可移植的进度序列 —— 通过 \x1b]9;4;0;0\x07（清除状态）配合 XTVERSION 等已知查询做特性探测后再决定是否发送，或退回 TTY 级进度条。
OSC 9;4;state;percent 里 state 值 0–4 各自代表什么？
0 = 清除 / 无进度（隐藏指示器）；1 = 普通进度（使用 percent）；2 = 错误（红色进度条，按 percent）；3 = 不确定 / 转圈（无百分比）；4 = 警告 / 暂停（黄色进度条，按 percent）。Windows Terminal 全支持；ConEmu 把 4 当 1。任务结束时必须再发 state 0 —— 进程退出后任务栏还卡在 100% 是常见 UX 缺陷。

终端支持

xterm
不支持
Linux console (fbcon)
不支持
macOS Terminal.app
不支持
iTerm2
不支持
Windows Terminal
支持
cmd.exe / ConPTY
不支持
kitty
部分
alacritty
不支持
WezTerm
支持
Ghostty
支持
GNOME Terminal
不支持
Konsole
不支持
tmux
部分
GNU screen
不支持

相关序列

在家族食谱中

OSC 食谱 · 6. 内联图片与进度 —— `OSC 1337` 与 `OSC 9 ; 4`