极简开源终端HUD：让AI Coding CLI过程可见可控

在终端里使用 ClaudeCode、Codex、OpenCode 这类 AI Coding CLI 工具时最明显的痛点往往是“看不见过程”。模型是否正在思考当前执行到哪个步骤上一次请求耗时多久哪些文件被改动这些信息常常被大量滚动日志淹没。等到需要做决策时关键状态却已经滚到视线之外。终端 HUDHeads-Up Display要解决的就是这个问题它不取代 CLI 本身而是在 CLI 进程旁边提供一个常驻信息面板把最重要的状态、进度、耗时和事件摘要从噪声中提取出来。本文围绕“为 AI Coding CLI 工具做一个极简开源终端 HUD”这个主题展开会先讲清楚这类 CLI 工具的输出特性再给出一个可以运行的最小骨架然后解释参数、渲染、排错和扩展。文章中的示例用于说明实现思路实际接入某个具体工具时需要根据工具的日志格式、环境变量和启动参数做适配。1. 先理解 AI Coding CLI 工具在终端的输出特性1.1 CLI 工具为什么需要 HUDClaudeCode、Codex、OpenCode 这类工具的共同特点是它们本质上是一个长时间运行的交互式 CLI 进程同时承担“对话、分析、改代码、执行命令、持续决策”等多个任务。开发者启动一次会话后终端里会持续输出模型思考过程、命令执行结果、文件变更列表、错误提示等信息。这种输出模型与传统编译工具完全不同。编译工具通常是一次性输出结果失败后退出AI Coding CLI 却是“请求-响应-再请求”的循环每次模型调用都可能持续数十秒而且内部状态经常变化模型正在思考、正在调用函数、正在等待用户确认、正在执行命令、已经完成。如果只靠原始终端滚动很难回答几个基础问题当前这一步模型处于什么阶段。本次会话已经发起多少次请求。最近一次事件发生在什么时间。有没有错误事件混在正常日志里。这些信息正是 HUD 面板可以补充的。HUD 不改变 CLI 本身的交互方式只负责在旁边建立一个“状态仪表盘”。1.2 ClaudeCode、Codex、OpenCode 输出的共性事件流、日志、状态提示虽然这些 CLI 工具由不同团队开发输出细节也不同但从终端外部捕获输出时可以归纳出三种共性形态。第一种是结构化事件流。很多 CLI 在非交互模式下会输出 JSON 行每一行就是一个事件内部包含事件类型、时间戳、请求 ID、耗时、token 数量等字段。HUD 最适合解析这类输出因为它不需要猜测文本语义直接读取字段即可。第二种是普通日志文本。CLI 的 stderr 通常用来输出运行日志、错误堆栈、警告信息。这类文本没有统一 schema需要靠关键字匹配做提取例如error、warn、completed、failed。第三种是控制台转义序列。交互模式下CLI 可能直接操作终端光标位置输出进度条或动态刷新区域。这部分内容对 HUD 非常不友好因为捕获到的不是纯文本而是包含大量\x1b[...的控制字符。接入 HUD 时建议优先让 CLI 进入非交互/结构化输出模式避免解析转义序列。1.3 HUD 与传统日志查看器、tmux 布局的区别有人会问我已经在用 tmux 分屏或者用tail -f查看日志为什么还需要一个 HUDtmux 分屏只是把不同的终端窗口并列摆放它不能聚合和分析内容。开发者需要在两个终端之间来回切换视线自己从日志里找关键字段整个过程依赖人脑解析。日志查看器例如tail -f、less、日志平台擅长展示“完整的原始日志”但并不擅长展示“当前状态的摘要”。日志是时间序列而 HUD 关心的是状态聚合当前阶段、事件计数、最近错误、平均耗时。因此 HUD 的定位更接近“仪表盘”而不是“日志全文”。它读取数据、做轻量聚合、渲染摘要。原始日志仍然应该保留在 CLI 主窗口中HUD 只是辅助显示器。2. HUD 最小架构与核心数据结构2.1 一条主线进程 - 事件解析 - 状态聚合 - 渲染一个极简 HUD 可以抽象成四个环节。进程管理启动或接入目标 CLI 进程读取 stdout 和 stderr。事件解析把原始行转换成结构化事件。状态聚合根据事件更新当前状态包括运行阶段、事件总数、最后事件、错误列表。渲染在终端特定区域绘制状态面板。它们之间应该用队列解耦。读取线程只管往队列里放原始行解析线程或主循环只管从队列取数据。这样做的好处是如果 CLI 短时间内输出大量内容读取线程不会阻塞 CLI 本身HUD 也能按自己的节奏消费数据。读取 stdout/stderr | v 事件队列线程安全 | v 事件解析与状态聚合 | v 终端渲染循环2.2 事件流的数据结构与状态模型事件是 HUD 的最小数据单元。设计上不要太复杂一个事件至少包含来源、时间戳和原始文本可选的字段是解析后的对象。from dataclasses import dataclass, field from typing import Any, Optional dataclass class Event: source: str # stdout / stderr timestamp: float # 事件发生时间 raw: str # 原始行 parsed: Optional[dict] None # 解析后的结构化字段状态对象负责聚合事件结果。它的字段不需要和事件一一对应而是输出“当前最关心的内容”。dataclass class HUDState: running: bool False event_count: int 0 error_count: int 0 last_event: str last_event_time: float 0.0 active_stage: str idle recent_errors: list field(default_factorylist)这个模型已经覆盖了文章开头提到的几个核心问题运行状态、事件量、错误量、最近事件、当前阶段。接入新 CLI 时只需要调整active_stage的推断规则不需要改整体架构。2.3 项目目录结构最小项目可以只有三个文件。hud/ ├── main.py # 入口启动子进程并启动渲染循环 ├── parser.py # 事件解析与状态聚合 └── ui.py # 终端渲染实际工程可以拆得更细例如增加adapters/目录按 CLI 类型放解析器。但小项目阶段不急着抽象先跑通完整链路更重要。# parser.py 示例按关键字更新状态 def update_state(state: HUDState, event: Event) - None: state.event_count 1 state.last_event event.raw state.last_event_time event.timestamp lowered event.raw.lower() if error in lowered or failed in lowered: state.error_count 1 state.recent_errors state.recent_errors[-9:] [event.raw] state.active_stage error elif completed in lowered or done in lowered: state.active_stage completed elif thinking in lowered: state.active_stage thinking这段代码的关键点是状态更新是“增量”的不依赖完整历史。即使 HUD 内存里只保留最近 N 条事件也能正确维护计数。实际项目中active_stage的字段名要按 CLI 的日志风格调整关键字规则最好抽成配置。3. 用 Python 实现一个极简 HUD 骨架3.1 环境准备示例使用 Python 3.10 及以上版本依赖只使用标准库。这样做的目的是让骨架在没有第三方包的情况下也能运行方便理解核心逻辑。python3 --version在 macOS 和 Linux 上标准库自带的curses可用于终端渲染。Windows 上默认可能没有curses需要先安装windows-curses才能运行示例。pip install windows-curses注意项目如果分发给用户不要把windows-curses写进核心依赖里它只在 Windows 平台需要。建议在安装脚本里按平台条件安装。3.2 读取子进程输出读取子进程输出的难点在于CLI 的输出可能不是一次性结束的而是一行一行持续产生。必须使用独立线程读取 stdout 和 stderr避免管道阻塞。import subprocess import threading import queue import time def _read_stream(stream, source, q): for line in iter(stream.readline, ): q.put(Event(sourcesource, timestamptime.time(), rawline.rstrip(\n))) def spawn_cli(command): proc subprocess.Popen( command, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue, bufsize1, envNone, ) event_queue queue.Queue() threading.Thread( target_read_stream, args(proc.stdout, stdout, event_queue), daemonTrue, ).start() threading.Thread( target_read_stream, args(proc.stderr, stderr, event_queue), daemonTrue, ).start() return proc, event_queue这里的关键参数有三个textTrue让 Python 把字节流转成字符串省去手动解码。bufsize1使用行缓冲保证每产生一行就进入队列而不是等缓冲区填满。daemonTrueHUD 退出时阻塞线程不会阻止程序退出。实际接入 CLAUDE 类 CLI 时command列表里很可能需要额外参数来关闭交互模式或启用 JSON 输出否则 CLI 检测到 stdout 不是 TTY 后可能根本不输出进度信息。3.3 解析事件并聚合状态对 JSON 行做结构化解析时要遵循“先判类型再取字段”的原则。import json def parse_event(event: Event) - Event: if not event.raw.startswith({): return event try: payload json.loads(event.raw) except json.JSONDecodeError: return event event.parsed payload return event解析完成后用更新函数把事件写入状态对象。def consume(event_queue, state): while True: try: event event_queue.get_nowait() except queue.Empty: break event parse_event(event) update_state(state, event)consume放在主循环里每次取完当前队列而不是阻塞等待是为了让渲染循环保持稳定的刷新频率。如果每次get()都阻塞渲染就会被拖慢。3.4 渲染终端面板极简渲染可以分成两步先绘制面板内容再刷新到终端。为了减少闪烁可以先构建完整字符串再一次性输出。def render(state) - str: lines [] lines.append(HUD - AI Coding CLI Monitor) lines.append( * 40) lines.append(frunning : {state.running}) lines.append(fevents : {state.event_count}) lines.append(ferrors : {state.error_count}) lines.append(fstage : {state.active_stage}) lines.append(flast event : {state.last_event[:80]}) lines.append(- * 40) for err in state.recent_errors[-3:]: lines.append(f! {err[:60]}) return \n.join(lines)接着写主循环def main(): command [your-cli, --json] proc, event_queue spawn_cli(command) state HUDState(runningTrue) try: while True: consume(event_queue, state) state.running proc.poll() is None print(\033[2J\033[H, end) print(render(state)) time.sleep(0.2) if not state.running: break finally: proc.terminate()\033[2J清屏\033[H回到光标原位。这个写法在普通终端可用但会导致整个屏幕被重绘。更优雅的做法是使用 alternate screen例如进入时输出\033[?1049h退出时输出\033[?1049l。3.5 运行与验证用一段模拟输出验证骨架。建一个临时脚本fake_cli.py每 0.5 秒输出一行日志。import time for i in range(20): print(fthinking step {i}) time.sleep(0.2) print(error: something failed)然后把main.py中command改为[sys.executable, fake_cli.py]运行。预期现象是顶部显示running: True。事件计数逐渐增加。状态从thinking切换到completed或error。脚本结束后running变为False程序退出。验证时不要只看“界面能动”还要验证错误计数是否准确、最后事件是否与 CLI 输出一致、退出后子进程是否真的被终止。4. 关键参数与配置说明4.1 刷新率刷新率直接影响 CPU 占用和视觉流畅度。如果刷新频率过高例如每秒 30 次主循环会频繁清屏和重绘消耗不必要的 CPU如果过低例如每秒 2 次事件信息会明显滞后。一般场景下 5 到 10 帧每秒即可也就是refresh_interval设置在 0.1 到 0.2 秒之间。CLI 工具本身不是高频刷新的游戏终端不需要追求 60 帧。refresh_interval: 0.2调大刷新间隔时要注意如果终端窗口被缩放或状态变化很快面板会显得迟滞。建议把刷新间隔做成启动参数而不是硬编码。4.2 布局与面板权重HUD 面板可以放在左侧、右侧、底部或顶部。侧边栏的典型宽度是 40 到 60 个字符底部栏可以做成只占两行的高度。布局参数需要和终端窗口大小联动。终端太窄时侧边栏会挤占 CLI 主区域。推荐的做法是先读终端宽度再按比例计算面板宽度。参数含义默认值调整影响refresh_interval渲染刷新间隔秒0.2过小 CPU 高、闪烁过大会出现状态滞后panel_position面板位置left/right/bottomright影响主 CLI 区域的可读性panel_width侧边栏字符宽度40过窄显示不全过宽压缩主区域max_buffer事件缓冲区行数5000过小会丢事件过大会增加内存占用error_keywords错误触发关键字列表error, failed过滤过宽会误报过滤过窄会漏报json_mode是否解析 JSON 行事件true关闭后只能做纯文本关键字匹配4.3 事件过滤规则不是所有输出行都应该进入状态聚合。实际 CLI 输出中会夹杂大量无关日志例如启动横幅、版权信息、调试输出。过滤规则可以设计成两组正则包含规则和排除规则。只有“不被排除且命中包含规则”的行才被解析如果包含规则为空则所有不排除的行都处理。filter: include: [] exclude: - ^\\[debug\\] - ^\s*$过滤规则要谨慎。排除规则太宽会把关键错误一起过滤掉。最简单的安全策略是错误关键字永远不参与排除即使某行同时命中 debug 前缀和 error 关键字也要优先保留并标记为错误。4.4 配置加载顺序配置加载建议按以下顺序覆盖内置默认值。用户配置文件。环境变量。命令行参数。后加载的配置拥有更高优先级这样可以保证用户临时调试时不需要改配置文件。5. 排错HUD 不渲染、输出卡顿、事件丢失5.1 现象HUD 界面闪烁或没画面闪烁的直接原因通常是“清屏加重绘”尤其在高频刷新时。如果print(\033[2J\033[H)每次迭代都执行终端会出现明显闪动。缓解方式只在面板内容变化时刷新进入和退出 alternate screen减少完整清屏次数改用定位光标后的局部更新。last_render while True: consume(event_queue, state) panel build_panel(state) if panel ! last_render: print(\033[2J\033[H, end) print(panel) last_render panel另一个常见原因是终端不支持 ANSI 转义序列。Windows 旧版终端、部分远程终端、某些编辑器内置终端都可能对转义序列支持不完整。建议先用最小命令验证终端能力printf \033[2J\033[H\033[32mOK\033[0m\n如果能正常显示绿色 OK说明终端支持否则需要换终端或降级渲染方案。5.2 现象子进程输出没有出现在 HUD 里可能原因有三个第一子进程启用了输出缓冲。虽然设置了bufsize1但目标 CLI 可能自己内部做了缓冲或者检测到 stdout 不是 TTY 后切换到了非交互输出模式。这种情况下CLI 根本没有输出进度信息。第二日志全部输出到了文件而不是终端。很多 AI Coding CLI 支持把会话保存到文件终端只保留少量提示。此时 HUD 需要读取日志文件而不是只读 stdout/stderr。第三环境变量影响输出。部分 CLI 通过环境变量控制日志级别默认日志级别可能是 info但 HUD 需要的字段在 debug 级别才出现。排查顺序是先直接手动运行一次 CLI确认它能输出什么再检查 CLI 是否有--json、--log-level、--non-interactive这类参数最后在 HUD 里临时打印原始事件确认队列中是否真的有数据。5.3 现象键盘快捷键失效或按键被 HUD 抢走HUD 和 CLI 子进程共享同一终端键盘输入只会到达其中一个。如果 HUD 自己处理 stdinCLI 就会收不到用户输入反过来如果所有输入都交给 CLIHUD 的快捷键就失效。推荐策略是先用条件分支区分按键全局快捷键例如退出 HUD由 HUD 处理其他按键传给 CLI 进程的 stdin。实现时可以向 CLI 的proc.stdin写入输入内容。command [your-cli] proc, event_queue spawn_cli(command) import sys, tty, termios old termios.tcgetattr(sys.stdin.fileno()) tty.setraw(sys.stdin.fileno()) try: while proc.poll() is None: key sys.stdin.read(1) if key \x1b: break if proc.stdin: proc.stdin.write(key) proc.stdin.flush() finally: termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, old)这种“透传输入”逻辑要非常小心。一旦进入 raw 模式CtrlC、方向键、回车都会成为普通字节需要自己处理控制序列。最小实现建议只处理退出键其余全部透传。5.4 排错清单问题现象常见原因检查方式处理建议界面闪烁每次刷新都清屏观察刷屏频率内容不变不重绘使用 alternate screen子进程输出为空缓冲、非 TTY 模式、输出到文件手动运行 CLI 查看输出打印原始事件调整 CLI 参数或改读日志文件快捷键失效stdin 归属冲突测试直接输入 vs HUD 透传区分全局键和透传键Windows 无画面缺少 curses/ANSI 支持执行 printf 验证检查依赖安装安装 windows-curses换终端事件计数不涨过滤规则太宽事件被丢弃打印被过滤的行先关过滤确认后再细化规则退出后子进程残留未调用 terminate/waitps查看进程在 finally 中终止并等待回收6. 适配多种 CLI 工具的通用策略6.1 按输出协议适配stdout JSON、stderr 日志、终端转义ClaudeCode、Codex、OpenCode 虽然是不同工具但都会遵循“程序输出”的基本规则。HUD 接入它们时不需要针对每个工具写一套全新框架只需要写一个适配器把工具的原始输出映射到统一事件模型。如果工具支持 JSON 输出就在启动参数里开启如果不支持就退回到文本关键字匹配。优先使用结构化输出因为文本解析的结果很难稳定。适配器可以定义成一个简单接口。class CliAdapter: def build_command(self) - list: raise NotImplementedError def parse_event(self, raw: str) - dict: raise NotImplementedError def infer_stage(self, event: dict) - str: raise NotImplementedError每个具体工具的适配器负责三件事构造启动命令、解析原始行、推断当前阶段。主循环完全不知道底层是哪个 CLI只依赖CliAdapter的返回结果。6.2 按状态区适配运行时、暂停、完成、错误CLI 的状态往往比“正在执行/已退出”丰富。实际场景中会有等待用户确认、正在调用模型、正在执行命令、遇到错误等待恢复、已经完成会话。状态推断规则要先做“错误优先”再区分其他状态。这是因为错误判断最关键。只要出现错误关键字就应该立即把状态切到 error即使后续行看起来像正常输出。错误之后可能出现恢复提示恢复规则要单独写否则面板会一直停在 error。合理的优先级是错误优先级最高。明确完成/退出信号次之。中间过程状态thinking、executing、waiting按关键字匹配。无法识别时保持原状态。6.3 表格三种输出形态的适配估算输出形态解析难度能提取的信息接入建议JSON 行事件低token 数、耗时、阶段、错误码优先开启解析稳定纯文本日志中阶段、错误、事件时间配置关键字规则规则要经过样本测试控制台转义序列高难以稳定提取尽量让 CLI 关闭交互模式避免直接解析6.4 安全性边界HUD 只读不写接入新工具时HUD 的职责边界要清晰它只读取 CLI 输出并展示状态不应该修改 CLI 的配置、登录信息、工作区文件或环境变量。任何需要持久化配置的操作都应该交给 CLI 本身。事件数据至少在内存中保留一部分即可不需要把完整会话写入磁盘。如果要做“最近 N 条错误”功能内存队列就足够。这样既能降低隐私风险也能避免 HUD 因写入日志而产生额外故障点。7. 生产环境落地建议与扩展方向7.1 从骨架到可分发工具的差异教学骨架只解决“跑起来”的问题要分发给其他开发者使用还需要补齐几个环节错误处理子进程崩溃时要显示原因而不是静默退出。信号处理收到 CtrlC 时要同时退出 HUD 并终止子进程。配置外置默认配置放在包里用户配置文件放在用户目录。安装脚本不同平台需要不同的终端依赖。版本兼容CLI 工具更新后事件格式可能变化适配器要有版本检测或降级逻辑。以打包为例Python 项目可以用 PyInstaller 打成单文件但体积较大Go 和 Rust 项目的分发会更简单。选择实现语言时要把“用户是否需要装 Python 环境”作为一个决策因素。7.2 跨平台终端兼容性终端渲染的最大坑是平台差异。macOS 的 Terminal、iTerm2、Windows Terminal、VS Code 内置终端对 ANSI 的支持程度不同字体宽度、快捷键转发、剪贴板行为也不同。做兼容性的最低成本方案是使用成熟的终端 UI 库例如 Python 的textual、Rust 的ratatui、Go 的bubbletea。这些库已经处理了大量光标、颜色、重绘、事件细节。如果坚持只用标准库建议先在目标平台上做完整的冒烟测试不要假设某个转义序列在所有终端都有效。7.3 性能与资源占用HUD 的资源占用通常很低但要注意两个放大器。一是事件队列积压如果 CLI 瞬间输出上万行而 HUD 来不及消费内存可能持续增长。解决办法是限制队列长度超过上限时丢弃中间事件只保留最新事件。def get_or_create(queue, maxlen5000): # 用 deque(maxlen) 管理事件防止无界增长 pass二是渲染开销全屏清屏在低端设备或远程终端上开销明显。建议把“是否变化才重绘”作为默认行为并且允许用户降低刷新率。7.4 部署到生产前检查清单接入一个新的 AI Coding CLI 并对外发布前建议逐项确认能构造出稳定的启动命令不依赖用户手动设置终端参数。能正确解析至少三种真实输出样本正常事件、错误事件、空输出。错误关键字规则已经用真实日志测试过没有明显误报和漏报。事件队列有上限内存占用不会随会话时间无限增长。退出逻辑完整HUD 退出时子进程一定要被终止或交还给用户。快捷键不会和 CLI 本身的快捷键冲突。在目标操作系统上分别验证过渲染效果。配置文件支持从默认值升级到用户配置不需要改代码。对 CLI 的非交互模式和 JSON 输出模式有明确检测避免静默降级。7.5 扩展方向接下来可以做的扩展按优先级排列支持把事件写入本地日志文件方便事后分析。增加 token 与耗时统计按会话周期聚合。支持监听日志文件而不是只监听 stdout/stderr适配“输出到文件”的 CLI。增加多会话切换让 HUD 同时监控多个 CLI 子进程。提供可配置的键盘快捷键而不是固定的全局按键。接入插件机制让社区为新的 CLI 写适配器不用改主程序。对一个极简 HUD 来说第一步永远是先稳定捕获事件流。只要事件模型稳定后续的统计、过滤、持久化都是锦上添花。不要在一开始就堆砌功能先解决“能不能稳定看到状态”这个基础问题再考虑界面复杂度。