【声明】本博客所有内容均为个人业余时间创作所述技术案例均来自公开开源项目如GithubApache基金会不涉及任何企业机密或未公开技术如有侵权请联系删除标题148、【Agent】【OpenCode】启动分析stderr背景上篇 blog【Agent】【OpenCode】启动分析ANSI DEC分析了\x1b[?25l和\x1b[?25h这两个序列属于 ANSI 转义序列中的 DEC 私有模式DEC Private Mode专门用于控制终端光标的显示与隐藏它们不是 SGR 指令不以m结尾而是以?开头以h/l结尾的模式切换指令这里进度条之所以要隐藏光标是因为进度条会通过\r不断原地刷新同一行如果光标保持可见会出现严重的视觉问题隐藏光标后整个进度条区域变成纯粹的文本渲染刷新过程干净流畅接着介绍了终端编程中常用的几个 DEC 模式并提到关于 SEC 私有模式目前没有一个统一现存的官方标准文档目前业界公认的的权威文档可参考 XTerm Control Sequences最后对比了 DEC 模式与 SGR 的区别下面继续分析OpenCode这里还有个细节\x1b[?25l还有\x1b[?25h这里用的都是 stderr这是个非常关键的工程设计决策选择 stderr 而非 stdout主要基于如下四个核心原因不污染数据流最重要stdout 在 Unix 哲学中是数据通道其输出内容经常被下游程序消费比如# 用户可能这样使用你的 CLImy-cli migrate|jq.resultsmy-cli migrateoutput.json my-cli migrate|greperror如果进度条的\r\x1b[38;5;214m■■■...写入 stdout这些 ANSI 转义序列会直接混入数据流导致jq解析失败JSON 文件损坏grep匹配到乱码等而 stderr 是诊断状态通道专门用于承载与主数据无关的信息比如进度警告错误日志等它默认不会被管道|或重定向捕获用户可以放心地对 stdout 做数据处理同时仍然能在终端看到进度条缓冲行为差异流默认缓冲策略对进度条影响stdout全缓冲连接到管道/文件时进度更新被攒在缓冲区里直到填满才刷新导致进度条长时间不动然后突然跳变stderr无缓冲始终每次 write 立即发送到终端进度条实时平滑刷新进度条依赖高频即时的字符输出如果用 stdout在非 TTY 场景下需要手动调用process.stdout.flushNode.js 中甚至没有同步 flush API而 stderr 天然就是逐字节即时输出的语义正确性进度信息本质上是运行时状态反馈而不是程序的产出结果按照 POSIX 约定stdout 程序的正常输出结果stderr 程序的运行状态诊断信息交互式反馈而进度条等提示都属于后者即使程序最终成功推出exit code 0过程中的状态信息也应该走 stderr与 TTY 检测的一致性首先 TTY 检测的是 stderr那么控制序列也应该写入同一个流总结一下考量维度stdoutstderr管道重定向安全❌ 会污染数据✅ 独立于数据流缓冲行为❌ 可能全缓冲✅ 始终无缓冲语义❌ 数据输出✅ 状态/诊断TTY 一致性❌ 可能与检测目标不一致✅ 检测与写入同一目标总结一句话stdout 是给机器读的stderr 是给人看的而进度条是给人看的状态反馈所以必须走 stderr这里再补充一点stderr 和 stdout 默认都会显示在终端上当直接在终端运行一个程序时比如node my-script.js操作系统就会将该进程的 stdout文件描述符 1和 stderr文件描述符 2同时绑定到同一个终端设备通常是/dev/tty对肉眼来说两个流的输出混在一起看起来完全一样它们的区别只在重定向时才显现只有当显式改变数据流向时差异才会暴露出来比如操作stdoutstderr终端看到的cmd→ 终端→ 终端两者都看到cmd file.txt→ 文件→ 终端只看到 stderrcmd 2 err.log→ 终端→ 文件只看到 stdoutcmdgrep x→ grep→ 终端cmd out.txt 21→ 文件→ 同一文件什么都看不到这里有个关键管道|和重定向只捕获 stdout而 stderr 则会穿透这些操作继续显示在终端上这正是进度条必须用 stderr 的根本原因即使用户把主输出重定向到文件进度条依然可见可以做如下实验# 这条命令只往 stderr 写内容你会发现它确实显示在了终端上echo我是 stderr2# 把 stdout 重定向到文件stderr 仍然显示在终端echostdout 去了文件/tmp/test.txtechostderr 留在终端2# 反过来把 stderr 重定向到文件stdout 仍然显示在终端echostdout 留在终端echostderr 去了文件2/tmp/test.txtOK最后再总结下stderr 不是错误流而是不被管道重定向捕获的诊断流在没有重定向的情况下stderr 和 stdout 一样正常显示在终端上而在有重定向的情况下它是唯一还能被用户直接看到的状态通道OK本篇先到这里如有疑问欢迎评论区留言讨论祝各位功力大涨技术更上一层楼更多内容见下篇 blog
