当前位置：

社区首页

电脑数码

智能设备

智能机器人

文章详情

为 AI Agent 配个身体：用Claude Code连接StackChan

从一个用AI的痛点说起

日常用 Claude Code ，一个绕不开的体验是：无脑审批流。前几次还仔细看看，后续更多是眯着眼睛看大致思路，始终要盯着屏幕，不断看终端上弹出的确认提示，按 y 或 n。

单独看每一次都不算什么。但当你让 Claude Code 连续跑几轮任务时，你的注意力就被绑在了终端窗口上。注意力一直集中在审批代码。LangChain 创始人 Harrison Chase 在他的万字长文里有一句精准的概括：瓶颈从实现转移到了评审。

能不能把这个审批环节"搬"到屏幕外？不再需要紧盯屏幕。

这几天在玩的StackChan 刚好能Agentic Engineering下这件事。

StackChan：一个开源的桌面机器人

之前介绍过 StackChan，不到 100 美元的 ESP32-S3 开源桌面机器人，带触屏、舵机、摄像头、IMU、麦克风，WiFi 连网。最开始拿到硬件时，我只是简单接了个 AI Agent，让它能说话和动头。

问题是 StackChan 自带的固件不支持这些功能。其面向 M5Stack 的云端服务，和我们的场景差得远。

所以我基于 StackChan Local（https://github.com/xuruiray/stackchan-local）这个开源项目，从重写了固件。没有在原始固件上二次开发，而是用 ESP-IDF 从零搭建了一套新的固件架构，专门面向本地桌面场景。

开源项目架构

StackChan Local的原始设计目标是让 StackChan 通过局域网本地运行，由桌面端负责控制台和应用编排。整体架构分三块：

图片

固件：三层架构

固件用 ESP-IDF 5.5.4 编写，明确分三层：

• hardware 层：板级配置、I2C/SPI 总线、各芯片驱动（摄像头 GC0308、触摸 FT6336、IMU BMI270、舵机、音频编解码器等）。只管硬件 IO，不碰任何业务逻辑。
• services 层：组合硬件驱动，编排应用行为。包括显示服务（LVGL 渲染）、运动服务（舵机控制）、传感器服务（遥测采集）、音频服务，以及最关键的 local_companion 服务：负责 WebSocket 连接、命令分发、遥测上报。
• system 层：启动顺序、系统上下文、生命周期管理、设置和诊断。

固件启动后主动通过 WiFi 连接局域网内的 Desktop Daemon，建立 WebSocket 长连接，保持心跳，等待命令下发。

Desktop Daemon：中间桥梁

Daemon 跑在 Mac 上，是固件和上层应用之间的桥梁（说白了就是个翻译器，把 HTTP 请求翻译成固件能懂的 WebSocket 命令）。它同时开两个端口：

• 8787 端口（WebSocket）：等待固件连接。负责设备注册、心跳追踪、命令路由、遥测接收。
• 8788 端口（HTTP + WebUI）：提供 REST 接口（/api/rgb、/api/expression、/api/hardware/* 等）和浏览器控制台。控制台按芯片或硬件模块分页面，覆盖电源、触摸、IMU、摄像头、舵机、RGB、音频、网络等，每个模块独立展示遥测数据和支持的安全命令。

Daemon 还提供了 MCP 工具服务，让上层 Agent 可以直接查询设备状态、控制硬件。可选的 Python sidecar 通过 OpenCV 运行本地人脸位置检测，驱动舵机追踪。

通讯原理

所有通讯基于结构化的 JSON 协议，通过 WebSocket 传输：

握手：固件连接后发送 handshake（设备 ID、固件版本、硬件能力列表），Daemon 回复 daemon.hello（协议版本、心跳间隔、功能特性）。
命令下发：Daemon 向固件发送 robot.command，包含命令类型（say、moveHead、react 等 13 种）和参数。固件收到后分发给对应服务执行，执行完回 ACK。
遥测上报：固件持续向 Daemon 上报传感器数据（IMU 10Hz、电池状态 2Hz、摄像头帧可配置 FPS）和事件（触摸、按键等）。

这套架构天然具备（vibe coding）扩展性，任何能发 HTTP 请求的客户端都可以通过 Daemon 的 REST API 控制设备。接下来要解决的是：Claude Code 怎么接入。

Claude Code需求：从哪里拦截？

回到需求本身：Claude Code 每次要写文件、执行命令时，我们需要在它真正执行之前"拦一下"，把操作信息发到 StackChan 上，等在触屏上确认后再放行。

这意味着我们需要一个拦截Hook。之前研究Claude Code 安全时就知道，它提供了 Hook 机制：可以在工具执行前后插入自定义的 Shell 脚本。PreToolUse 钩子正好满足需求：在工具调用之前触发，脚本的退出码决定操作是否继续（exit 0 放行，exit 2 拒绝）。

第一层：Hook 脚本——拦截与转发

在项目的 .claude/settings.json 中配置 Hook（当然你根据你的需要可以放在Claude全局或项目级别）：

{ "hooks": { "PreToolUse": [{ "matcher": "Write|Edit|NotebookEdit|Bash|mcp__filesystem__(write|edit|move)_file|mcp__github__(push_files|create_or_update_file)", "hooks": [{ "type": "command", "command": "scripts/confirm-hook.sh" }] }] } }

matcher 用正则匹配所有写操作：写文件、编辑文件、执行 Bash 命令、GitHub 推送。每当 Claude Code 要执行写操作时，会先调用 Hook 脚本。

脚本通过 stdin 收到一份 JSON，包含工具名和操作参数。它的工作很直接：

解析操作信息：从 JSON 中提取工具名和目标（文件路径或命令内容），用一段 Python 做格式化。
构造请求体：打包成 { requestId, title, message, waitForResponse: true, timeoutMs: 60000 }。
POST 到 Daemon：用 curl 发送到 http://:8788/api/claude/confirm。关键是 curl 会阻塞在这里，直到 Daemon 返回结果或自身超时（65 秒）。
根据响应退出：解析 JSON 中的 response 字段，confirmed → exit 0，cancelled 或无响应 → exit 2。

# 核心逻辑（简化） resp=$(curl -s --max-time 65 -X POST http://IP:8788/api/claude/confirm -H "Content-Type: application/json" -d "$body") if [ -z "$resp" ]; then exit 2; fi # Daemon 不可用，拒绝 result=$(echo "$resp" | python3 -c "import sys,json; print(json.load(sys.stdin).get("response","confirmed"))") [ "$result" = "cancelled" ] && exit 2 # 用户取消 exit 0 # 放行

这里有一个重要的设计选择：curl 是需要处理为同步阻塞的。脚本启动后，整个 Claude Code 的工具调用就停在这里，等设备那边做出决定。这正好是我们想要的效果：人不点，Claude Code 就不会继续下一步。

第二层：Daemon——HTTP 到 WebSocket 的桥接

Daemon 收到 /api/claude/confirm 请求后，需要把它翻译成固件能理解的 WebSocket 消息。

这里有两种模式：

• Fire-and-forget：发个命令过去，不等结果。适合展示通知类信息。
• 阻塞等待：发命令后卡住 HTTP 连接，直到设备回传用户操作或超时。这正是审批场景需要的。

Daemon 提供了 showConfirmAndWait() 方法来实现阻塞模式：

showConfirmAndWait(options): 1. 通过 WebSocket 向固件发送 showConfirm 命令 2. 在内存中注册一个 pendingConfirms[requestId] = { resolve, timer } 3. 启动 setTimeout 超时定时器 4. return new Promise(...) —— 阻塞在这里

这个 Promise 什么时候 resolve？两种情况：

• 在设备上点了按钮：固件通过 WebSocket 发回 userResponse 事件，Daemon 的 WebSocket 消息处理器根据 requestId 找到对应的 pending confirm，调用 resolve()。
• 超时：定时器触发，自动 resolve 为 { response: "timeout" }。

HTTP 连接一直挂着，直到 Promise resolve，然后把结果序列化为 JSON 返回给 curl。整个过程对 curl 来说就是同步阻塞的。它只是发了一个 HTTP 请求，等了一会儿，拿到了结果。

第三层：固件——LVGL 确认对话框

固件收到 showConfirm 命令后，由 local_companion 服务的命令分发器路由到显示服务，在 LVGL 上渲染一个确认对话框。

固件侧的实现要点：

• 对话框渲染：用 LVGL 创建一个模态弹窗，显示标题（工具名）和消息（文件路径或命令），底部两个按钮 Confirm / Cancel。
• 触屏回调：FT6336 触摸驱动的点击事件绑定到按钮回调。用户点 Confirm，回调函数将结果写入 userResponse 事件。
• 事件回传：userResponse 作为标准的 robot.event 通过 WebSocket 发回 Daemon，包含 requestId 和 response（confirmed / cancelled）。
• 超时兜底：如果用户一直不点，固件侧也有超时机制，自动关闭对话框并回传 timeout。

有个同步模型的细节值得提一下：Daemon 到固件之间是异步消息驱动的（发命令 → 等事件），但 Daemon 对外暴露的 HTTP 接口通过 Promise 把异步转成了同步阻塞。Hook 脚本只需要处理同步的 curl 调用，不用关心底层的事件等待逻辑。

把三层串起来

三层各自就位后，完整的数据流是这样的：

图片

换个角度看：Claude Code 想改一个文件，StackChan 屏幕弹出对话框显示文件名，看一眼没问题就点 Confirm。回到电脑前发现操作已经完成了。审批不再需要再盯着屏幕。

图片

潜在的不足：Claude Code的Hook目前没有降级机制

这套方案目前有一个短板。

Hook 脚本的退出码只有两种：exit 0（允许）和 exit 2（拒绝）。没有第三种状态。

这意味着：

• 当 Daemon 不可用时，curl 请求超时，脚本 exit 2，Claude Code 的所有写操作直接被拒绝。不是"回退到终端屏幕上弹出审批"，而是硬拒绝（当然也可以默认通过，这样可能会导致失控）。
• 当固件没连上时，Daemon 收到请求但没有设备可以弹窗，最终超时返回，同样是拒绝。
• Claude Code 的 Hook 机制本身不支持降级：它只认 exit code，没有办法在 Hook 失败时说"这个 Hook 无效了，请回退到你原来的审批流程"。

理想情况是 Hook 服务可用时走设备审批，不可用时自动回退到终端的 y/n 审批。但 Claude Code 目前没提供这种中间态。

这是当前方案最大的局限：它是一个"全有或全无"的设计。要么 StackChan 在线且正常工作，要么所有写操作都被卡住。你需要在配置里手动启用或禁用 Hook，来切换审批模式。