CodeTank：给 Codex 养一只电子浣熊

一、项目缘起

平时使用 Codex 处理编译、测试、检索和多会话任务时，电脑窗口不一定始终处于前台。CodeTank 希望把这些抽象的生命周期事件变成一眼就能看懂的桌面场景：Codex 正在思考时，小浣熊会思考；执行 Shell、构建或测试时，它会进入工作动画；需要用户授权或输入时，屏幕会弹出对话框并播放提示音。

项目定位是“AI 桌面工作搭子”，不是把对话内容搬到另一块屏幕，而是用更轻量、更有情绪的方式呈现 AI 是否忙碌、正在做什么，以及什么时候需要人回来处理。

二、硬件与显示

已验证的硬件组合：

• – 涂鸦 T5AI-Board V1.02

• – 3.5 英寸 480×320 ILI9488 显示屏，横屏显示

• – GT1151 触摸控制器

• – T5AI-Board 板级 `audio_codec` 与扬声器

• – Wi-Fi STA 直连或 TuyaOpen AP 配网

固件基于 TuyaOpen 和 LVGL。场景按 480×320 物理分辨率全屏布局，角色保持原生像素比例；右上角使用独立的四态 Wi-Fi 图标显示 OFF、AP、CONNECTING 和 CONNECTED。GT1151 已接入板级硬件，但当前界面定位为只读状态终端，暂不支持在屏幕上直接批准 Codex 权限请求。

三、Codex 如何驱动硬件

数据链路如下：

Codex lifecycle hooks
→ 本机 ~/.codetank/hook.sock
→ Python Bridge
→ 局域网 TCP 19872
→ T5AI-Board
→ LVGL 场景、角色动画、对话框与提示音

开发板作为 TCP 服务端，本机 Bridge 使用 Python 标准库实现，负责断线重连并重新同步时间、会话和通知状态。相比 BLE，这种方式更容易调试，也适合开发板和电脑位于同一可信局域网的使用场景。

当前映射覆盖提交新消息、普通工具调用、Shell/构建/测试、图片检查、网络检索、MCP 调用、上下文压缩、子代理、授权请求、停止和会话结束等事件。例如：

• – 提交消息：`thinking`

• – 编辑或普通工具：`typing`

• – Shell、构建与测试：`building`

• – 图片检查：`debugger`

• – 网络检索：`wizard`

• – MCP 调用：`beacon`

• – 上下文压缩：`sweeping`

• – 子代理工作：`conducting`

• – 等待授权：Alert 动画、对话框和提示音

• – 一轮任务结束：`Waiting for input`

任务结束后显示 `Waiting for input` 是设计行为，表示 Codex 已停止并等待下一条消息；下一次 `UserPromptSubmit` 会立即清除该对话框。

四、多会话与反馈

CodeTank 最多同时显示四个 Codex 会话角色，更多会话通过 `+N` HUD 表示。新会话进入时播放 `walking`，离开时播放 `going_away`，并自动重新排列位置。子代理数量、Bridge 断线、授权请求和任务完成都有可视反馈。

项目还提供联网、通知、完成和警告四类原创提示音。工具动画至少展示约 2.25 秒，避免很快结束的 Shell、搜索或图片检查动作完全看不到；长时间思考和待机也会在多组动画间轮换，让场景不再只有单一待机姿势。

五、动画资源流水线

角色是一只穿深海军蓝连帽衫、带青色 Codex 风格装饰的灰色小浣熊。项目包含 19 组动画、共 200 帧。

为了让任何人都能换成自己的角色，我把流程拆成“生成 + 本地确定性处理”两部分：

1. 用 ChatGPT Image 生成角色标准图并人工确认正面、侧面、3/4 视角、表情、服装和比例。

2. 每个动作生成一张纯 `#00FF00` 绿幕精灵表，使用 4×2、4×3 或 4×4 固定网格。

3. `tools/mascot_pipeline.py` 自动切帧、色键抠图、联合裁剪、基准线对齐和最近邻像素化。

4. 所有动作映射到共享 32 色调色板，避开透明键冲突。

5. 自动打包为 RGB565/RLE 固件资源、帧偏移和统一动画注册表。

6. 对生成头文件反向解码，校验帧数、空帧、越界、调色板、透明键和 RLE 往返一致性。

源图、提示词、Manifest、调色板和审批后的动作精灵表都保留在 `assets/mascot/`；中间缓存不会提交。替换角色时只要保留动作名、帧数和网格规格，就能继续兼容主机侧 TCP 动作协议。

六、电脑端预览与测试

项目提供无窗口 LVGL 9 软件模拟器，可以在不连接开发板的情况下直接复用固件场景、字体和 RGB565/RLE 资源生成 480×320 截图：

python3 tools/generate_lvgl_previews.py

输出包括待机、思考、四会话、等待/授权和 Bridge 断线五种状态，以及一张总览图。另有一键演示脚本，可在真机上依次验证动画、四会话并发、HUD、对话框、Wi-Fi 图标和声音：

cd source/host
python3 codetank_demo.py --quick

七、开源地址

GitHub：<https://github.com/Eilgnaw/CodeTank>

仓库包含 TuyaOpen 固件、Codex Hook Bridge、演示脚本、主机测试、动画源图与流水线、音效生成脚本、LVGL 桌面渲染器及完整中文使用指南。

项目主体使用 Apache License 2.0。从 clawd-tank 适配的场景、通知、RLE 和资源转换逻辑保留原 MIT 许可证与署名；小浣熊图像由 ChatGPT Image 为本项目生成，提示音由项目脚本原创合成。

安全提示：TCP 协议面向可信局域网，没有传输加密或客户端认证，不应将 19872 端口暴露到公网；Tuya UUID、AuthKey 和 Wi-Fi 密码只保存在被 Git 忽略的本地配置中。