用3D打印和状态机制作Claude Code硬件副屏

在使用 Claude Code 执行长时间后台任务时，常会遇到一个令人困扰的问题：将复杂任务提交至后台后便转而处理其他事务，几小时后返回查看，终端光标虽在闪烁、表面看似一切正常，但仔细核查便会发现，任务早在几十分钟前就卡在某个人机确认环节，就这么悄无声息地悬停在那里——白白浪费了大量算力与时间。

系统通知在理论上可以解决这一痛点，但前提是你必须恰好守在电脑前，且未被海量其他消息所淹没。对于动辄需要运行几十分钟甚至更久的后台任务而言，“后台静默卡死”确实是一个极易被忽视的盲区。

一、灵光乍现

于是，我动手打造了一款实体状态 Mini 副屏——通过 3D 打印外壳、HDMI 小屏与本地状态服务，将 Claude Code 的运行状态以红绿灯形式实时映射到桌面上。

红灯 —— AI 正在全速运行，持续消耗 CPU 与 Token 资源；
黄灯 —— AI 正等待用户确认，任务卡在半路，这是最容易被遗漏的关键状态；
绿灯 —— AI 处于空闲状态，任务已完成或尚未开始。

整个方案成本可控、复现门槛较低，下面将按照硬件组装、软件状态机实现、前端展示的顺序逐步展开说明。

二、硬件准备

1、Mini 显示器外壳

外壳无需从头自行建模，直接采用开源方案即可。在拓竹 MakerWorld 上搜索 "Mocintosh 摸鱼小副屏"，作者提供了两款不同尺寸供选择：

个人更推荐 2.8 寸版本，不仅打印耗时更短，而且 640×480 的分辨率对于静态状态展示而言已经绰绰有余。

2、HDMI显示屏

屏幕可在电商平台搜索 "HDMI 显示屏方案 2.8 寸麦金塔模型屏"，选购时需注意以下两点：

• 务必选择 HDMI 直驱方案，避免购买 SPI 或 I2C 驱动屏，否则需要额外转接板，且外壳可能不兼容；
• 留意屏幕排线的出线方向，部分屏幕的 FPC 排线从左侧引出，部分从右侧引出，需确保与外壳的走线槽匹配。

避坑提示：macOS 对 640×480 这类非标准小尺寸屏幕的支持较为有限，首次连接时可能默认以 1080p 输出导致黑屏。建议在系统设置中按住 Option 键点击"缩放"，强制选择 640×480 分辨率；或在 Windows 环境中先调好分辨率再切换回 macOS 使用。

三、组装使用

1、安装驱动板

按下图所示步骤安装即可，注意不要压到屏幕排线，使用螺丝将驱动板可靠固定。

2、组装外壳

四、软件架构：三层状态机

硬件只是躯壳，核心价值在于软件架构。整体分为三个层次：

Claude Code (Hook) → monitor.js (状态机) → 浏览器前端 (副屏展示)

1、状态灯控制

三种状态直接对应红绿灯信号：
红灯 / running：AI 正在执行工具调用或生成回复内容，算力满载运行；
黄灯 / awaiting：本轮输出已结束，但不确定是任务完成还是下一轮思考前的短暂间隙；
绿灯 / idle：确认任务真正结束，系统进入空闲状态。

黄灯到绿灯的切换采用了一个 3 秒倒计时的缓冲逻辑。Claude Code 的 Agent 模式遵循"思考→工具→思考"的循环，两轮之间会存在短暂间隙。如果直接切换至绿灯，状态灯会频繁闪烁。引入 3 秒阈值后，只有系统真正进入空闲状态才会切换至绿灯。

2、技术架构

下面来看具体的技术实现架构：

• 第一部分： 当你在 Claude Code 中发送消息、Claude 执行工具调用、Claude 回答完毕——这三个时机均会自动触发相应脚本，将当前状态通过网络推送给本地服务。
• 第二部分： 本地服务（monitor.js）就像一个交通灯控制器，职责单一：管理三种颜色状态的切换。收到「开始工作」信号→ 立即亮起红灯，同时取消任何等待中的倒计时；收到「本轮结束」信号→ 亮起黄灯，并悄悄启动一个 3 秒倒计时。若 3 秒内没有新的「开始工作」信号→ 切换至绿灯，表示任务真正结束；若 3 秒内收到新的「开始工作」信号→ 倒计时取消，回到红灯状态继续执行。
• 第三部分： 浏览器中的页面每 250ms 轮询一次控制器「当前是什么颜色？」，获取答案后同步给动画主题播放对应的视觉效果。

一句话总结： 红灯表示正在执行，黄灯表示等待确认，绿灯表示可以交互。

3、如何使用

完整代码已托管至 GitHub：github.com/chenfengyan…

用户发消息
│
├─ UserPromptSubmit hook → set-state.sh busy → 红灯
│
├─ PreToolUse hook → set-state.sh busy → 红灯（持续）
│  │
│  └─ 若工具为 AskUserQuestion / AskFollowupQuestion
│     → set-state.sh waiting (persistent) → 黄灯（持续，不倒计时）
│     └─ 等待用户回复后 → UserPromptSubmit 再次触发 → 回到红灯
│
├─ Stop hook → set-state.sh waiting → 黄灯（3 秒倒计时）
│  │
│  └─ 若 Claude 继续工作（多 turn）→ PreToolUse 再次触发 → 回到红灯
│
└─ Stop hook 触发后 3 秒内无新事件
   ↓
monitor.js 判定为 idle → 绿灯

• Hooks 通过 curl POST 推送到 monitor.js（不再依赖文件系统）
• monitor.js 在内存中维护状态：收到 busy 立即取消倒计时；收到 waiting 根据 persistent 字段决定具体行为——普通 Stop 启动 3 秒倒计时，AskUserQuestion 则持续黄灯直到用户回复
• 前端每 250ms 轮询 /api/status，严格跟随服务端状态，通过 postMessage 同步给 iframe 主题
• 绿灯由服务端倒计时逻辑决定：前端不包含任何计时逻辑

项目结构如下：

MyBetterDisplay/
├── start.sh          # ⭐ 一键启动（首次运行执行这个即可）
├── stop.sh           # 停止监控服务
├── install.sh        # 安装 BetterDisplay 应用
├── index.html        # 监控主页（主题切换器）
├── claude-status/
│   ├── monitor.js    # HTTP 监控服务（端口 4242）
│   ├── set-state.sh  # Hook 脚本（由 Claude Code 调用）
│   └── install-hooks.sh # 向 settings.json 注入 hooks
└── themes/           # 19 个动画主题（每个独立 HTML 文件）

快速开始：

# 脚本自动完成：检查依赖 → 注入 hooks → 启动服务 → 打开浏览器。
bash start.sh

# 停止服务
bash stop.sh

五、主题扩展

为了让 Mini 显示器的展示不再单调，除了标准红绿灯模式外，还扩展了多种视觉主题。反正都是让 AI 来生成，稍微扩展一下也无妨。

六、总结

3D 打印外壳 + HDMI 副屏 + 本地状态机，整个方案实现下来并不复杂。从 DIY 外壳设计，到硬件显示器组装，再到软件程序适配，整条链路完整贯通，软硬件创意结合，值得亲自动手尝试一番。