【声明】本博客所有内容均为个人业余时间创作所述技术案例均来自公开开源项目如GithubApache基金会不涉及任何企业机密或未公开技术如有侵权请联系删除标题208、【Agent】【OpenCode】TUI 内部终端背景色的获取背景上篇 blog【Agent】【OpenCode】TUI 内部18 层 Provider 的职责地图把 18 层 Provider 归成 4 组数据源Args/config/SDK/Sync/KV/Local、UI 结构Route/Theme/Toast/Dialog/Keybind、输入 promptRef/Stash/History/Frecency/Command、生命周期Exit/ErrorBoundary嵌套规则是谁 init 里use了谁谁就嵌在谁内部。其中ThemeProvider属组 2界面结构它决定 TUI 用深色还是浅色主题——但一个前提问题悬着dark/light 的初值mode到底从哪来本篇展开getTerminalBackgroundColor()app.tsx:45-103程序如何探测终端背景色自动定主题OpenCode程序读不到终端背景色这种 OS API——深色还是浅色只有终端自己知道。opencode 的做法是直接问终端发一条 ANSI/OSC 序列终端把背景色说出来程序解析后按亮度判断。app.tsx:121 调用它const mode await getTerminalBackgroundColor()结果喂给 ThemeProvider。完整实现如下app.tsx:45-103asyncfunctiongetTerminalBackgroundColor():Promisedark|light{// cant set raw mode if not a TTYif(!process.stdin.isTTY)returndarkreturnnewPromise((resolve){lettimeout:NodeJS.Timeoutconstcleanup(){process.stdin.setRawMode(false)process.stdin.removeListener(data,handler)clearTimeout(timeout)}consthandler(data:Buffer){conststrdata.toString()constmatchstr.match(/\x1b]11;([^\x07\x1b])/)if(match){cleanup()constcolormatch[1]// Formats: rgb:RR/GG/BB or #RRGGBB or rgb(R,G,B)letr0,g0,b0if(color.startsWith(rgb:)){constpartscolor.substring(4).split(/)rparseInt(parts[0],16)8// 16-bit → 8-bitgparseInt(parts[1],16)8bparseInt(parts[2],16)8}elseif(color.startsWith(#)){rparseInt(color.substring(1,3),16)gparseInt(color.substring(3,5),16)bparseInt(color.substring(5,7),16)}elseif(color.startsWith(rgb()){constpartscolor.substring(4,color.length-1).split(,)rparseInt(parts[0]);gparseInt(parts[1]);bparseInt(parts[2])}constluminance(0.299*r0.587*g0.114*b)/255resolve(luminance0.5?light:dark)}}process.stdin.setRawMode(true)process.stdin.on(data,handler)process.stdout.write(\x1b]11;?\x07)timeoutsetTimeout((){cleanup();resolve(dark)},1000)})}OSC 11程序怎么问终端关键一行是process.stdout.write(\x1b]11;?\x07)app.tsx:96\x1b ] 11 ; ? \x07 ESC OSC 编号 参数 BELOSC 11Operating System Command 11就是查询/设置终端背景色。发?表示查询BEL\x07或ESC \是序列结束符。终端收到后会回一条同格式的应答比如\x1b]11;rgb:1e1e/1e1e/1e1e\x07 XTerm 标准每通道 16 位/ 分隔 \x1b]11;#1e1e1e\x07 有些终端回 hex底层背景ANSI 控制序列家族\x1b]11;...不是孤例它归属于 ANSI 转义序列这个体系。凡是以 ESC\x1b即\033开头、后面跟一个引入符的都算控制序列引入符家族用途示例[CSI光标移动、SGR 颜色ESC[31m红字]OSC操作系统命令ESC]0;标题BEL改窗口标题、ESC]11;?查背景色PDCS设备控制串如终端查询回复的包装\ST字符串终止符常与 BEL 等价用于结束 OSC代码里正则/\x1b]11;([^\x07\x1b])/的字符类[^\x07\x1b]正是为兼容两种结束方式BEL\x07或 ESC\x1bST 的开头字节一到捕获就停。不理解 OSC/ST 的差异这行正则的排除逻辑就看着莫名其妙。raw mode data收下终端的回信终端把应答当成输入发回 stdin所以要先setRawMode(true)并监听dataapp.tsx:94-95。为什么必须 raw mode因为非 raw 模式canonical 模式下终端驱动会做两件好心坏事行缓冲ICANON输入攒到换行才交给程序——终端应答末尾没有换行会被一直憋着信号处理ISIGCtrlC 这类控制键被转成信号SIGINT而不是字节。只有 raw mode 关掉 ICANON/ISIG/ECHO 等才能逐字节收到ESC ] 11;...这种无换行的控制序列。若非 TTYapp.tsx:47进不了 raw mode直接返回dark。收到数据后handlerapp.tsx:58-92用正则抓ESC ] 11;之后的颜色串。⚠️应答分片的边界data 不保证一次到齐stdin的data事件每次给一段字节不能假设整条 OSC 应答一次到齐。如果终端把应答拆成两段——第一段\x1b]11;rgb:1e1e/、第二段1e1e/1e1e\x07——handler 对第一段做正则匹配会失败颜色串不完整、还没出现结束符。opencode 没有做跨 chunk 拼接缓冲遇到分片就匹配不到最终靠 1 秒超时兜底返回dark。这是容忍不完整应答的工程取舍追求简单、可接受偶发误判深色也不愿为分片维护一个累积缓冲。三种颜色格式与亮度判断格式例子解析rgb:rgb:1e1e/1e1e/1e1e每通道16 位parseInt(x,16) 8砍成 8 位##1e1e1e每两位一段parseInt(hex,16)rgb(rgb(30,30,30)十进制解析出 RGB 后算相对亮度app.tsx:87luminance (0.299r 0.587g 0.114b) / 255亮度公式再谈人眼不是均等看待 RGB系数 0.299/0.587/0.114 不是拍脑袋而是BT.601 亮度系数——对应人眼对三种颜色的敏感度对绿色最敏感、红色次之、蓝色最弱所以绿通道权重最高。三个系数和为 1加权后值域正好落在 [0,255]除以 255 归一化到 [0,1]阈值取 0.5。严格说这是工程近似没做 gamma 校正、也没换算到感知均匀的色彩空间如 CIELAB 的 L*。对判深色还是浅色这种二值问题近似足够换来的是实现简单。阈值 0.5 也是经验值——背景偏亮超过一半就认为浅色终端。应答格式差异为什么三种格式都要兼容终端对 OSC 11 查询的应答格式并不统一xterm / 大多数rgb:RRRR/GGGG/BBBB——每通道16 位这是 XTerm 规范格式所以代码要 8把 16 位砍成 8 位部分终端直接回#RRGGBB个别回rgb(R,G,B)十进制。代码三种都解析app.tsx:70-84。一个容忍度边界值得注意若某终端用 8 位回rgb:RR/GG/BB不标准parseInt(x,16) 8会把小于 256 的值右移 8 位直接砍成 0 → 全黑 → 亮度 0 → 误判深色。规范终端都回 16 位这段是对不标准应答的选择性失明。⚠️健壮性与 Windows 副作用函数自带三处兜底非 TTY 直接返回darkapp.tsx:47cleanup 还原现场拿到应答或超时后setRawMode(false)、移除data监听、清定时器app.tsx:52-56——不能把 stdin 留在 raw mode1 秒超时终端不应答就resolve(dark)绝不阻塞启动app.tsx:98-101还有一个 Windows 特有副作用切 raw mode 会重开ENABLE_PROCESSED_INPUT。app.tsx:123-125 的注释原话setRawMode(false) restores the original console mode which re-enables ENABLE_PROCESSED_INPUT所以探完背景色后必须再调一次win32DisableProcessedInput()app.tsx:125否则 Windows 上 CtrlC 又会变回杀进程的信号——这正是 Win32 CtrlC 防御那套机制的用武之地。启动时序与 ThemeProvider 的衔接看 app.tsx 里这段的调用顺序app.tsx:117-152 节选win32InstallCtrlCGuard() / win32DisableProcessedInput() // 先装 CtrlC 守卫 const mode await getTerminalBackgroundColor() // 再探背景色会切 raw mode win32DisableProcessedInput() // 探完立刻重清 flag render(... ThemeProvider mode{mode} ...) // 最后才渲染顺序有讲究守卫在最前保证整个探测过程里 CtrlC 不会被系统拦截探测同步 await最长 1 秒超时即 dark确保 render 前主题已定探测完立刻重清raw mode 带出的 flag。另外mode只是开机默认主题——用户进入 TUI 后仍可在主题对话框切换ThemeProvider 会把选择存进 KV 持久化这个函数只负责第一次渲染时给出合理的深/浅起点。总结环节作用发\x1b]11;?\x07OSC 11 查询终端背景色setRawMode(true)data收终端应答非 TTY 直接 dark正则抓ESC ] 11;后颜色串提取 RGB 说明兼容 BEL / ESC 终止三种格式解析 8归一化成 8 位 RGBBT.601 亮度 阈值 0.5判 dark/light交给 ThemeProvidercleanup 1s 超时还原 raw mode、防死等、容错应答分片再调win32DisableProcessedInput抵消 raw mode 重开ENABLE_PROCESSED_INPUT一句话记忆TUI 拿不到终端背景色 API就用 OSC 11 序列问发\x1b]11;?\x07进 raw mode 收应答非 TTY 或 1 秒超时都兜底 dark正则抓出颜色串rgb:16 位8/#hex/rgb()十进制算 BT.601 亮度、阈值 0.5 定 dark/light 喂给 ThemeProvider 做开机默认主题最后还原 raw mode 并重清 Windows 的ENABLE_PROCESSED_INPUT。OK本篇先到这里如有疑问欢迎评论区留言讨论祝各位功力大涨技术更上一层楼更多内容见下篇 blog【Agent】【OpenCode】TUI 内部tui() 的生命周期 Promise