把AI Agent的“内心戏”变成了桌边的一张纸:ai-desk-card 完整拆解

Vibe-coding 伴侣

你有没有想过，当AI Agent在后台默默工作时，它"想"了什么？我把一块4.7寸墨水屏放在显示器旁边，让Claude Code把它的想法实时"吐"出来。效果出乎意料地好——甚至有点感人。

一、一个安静的问题

我最近发现一个挺微妙的痛点。

Claude Code、Codex 这些 AI 编程 Agent 跑任务的时候，你其实不知道它在干什么。你只看到终端里一行行文字刷刷地过，但具体进度？遇到了什么问题？下一步计划？全在脑子里。

信息太多了，但不是所有信息都值得占用主屏幕。

很多内容只需要"看一眼"。比如 AI 正在跑什么任务？某篇文章的核心结论？今天下一步该做什么？设备还有多少电？

这些信息如果放在聊天窗口、浏览器标签页或者终端里，很容易被淹没。

所以我想：能不能给 Agent 一个物理空间，让它把"心里话"写在上面？

答案是 ai-desk-card。https://github.com/op7418/ai-desk-card

吃灰多年的 Paper，终于有输出情绪价值的时候了。差点被我 20 块扔到小黄鱼去了。

二、它长什么样

直接看效果：一块 M5Paper V1.1（4.7寸电子墨水屏，540×960 分辨率）立在显示器旁边，上面分四个区域显示信息：

[*]
左上：天气
[*]
右上：日历 / AI 状态
[*]
中间：公众号文章摘要、待办事项、当前焦点
[*]
底部：系统状态、Git PR 队列、设备信息

底部还有一条操作栏，可以触控刷新、息屏、重启。

平时它安静地呆在桌边，省电、不刺眼、不打扰。Agent 有信息更新了就推送过去，你瞥一眼就好。

它解决了一个很小但很真实的问题：让低频但重要的信息，有一个不会被淹没的展示位置。

三、代码拆解：三层架构，分工明确

项目分三层，每一层有明确的职责边界。

第一层：固件层（C++，运行在 M5Paper 上）

核心文件：src/main.cpp（约 800 行）

这一层负责最基础的事：联网、接收画面、刷新屏幕、上报状态。

关键设计理念是设备端尽量简单。复杂的排版、字体渲染、卡片布局都不放这里，交给电脑端去处理。

// 固件版本号，和 daemon 做协议兼容性检查#define CARD_VERSION "0.6.4"#define CARD_PROTO 1// RTC 内存保存"上次显示的内容指纹"// 重启后如果指纹一致，跳过清屏，让墨水屏保持上次画面RTC_DATA_ATTR uint32_t g_lastContentMagic = 0;static const uint32_t CONTENT_MAGIC = 0xDE5CCA8D;   // "DESK CARD"

最妙的是这个 RTC_DATA_ATTR 技巧。电子墨水刷新的最大痛点就是闪屏——每次刷新先黑一下再显示。项目用 RTC 内存保存内容指纹，重启时如果指纹一致，直接跳过 EPD.Clear()，画面上次是什么样就是什么样，完全无感。

Widget 系统：src/widgets.cpp（约 240 行）

固件定义了多种 Widget 类型，每一块屏幕区域对应一个 slot：

WidgetType typeFromString(const char* s){if (strcmp(s, "weather")     == 0) return WIDGET_WEATHER;if (strcmp(s, "todo")        == 0) return WIDGET_TODO;if (strcmp(s, "calendar")    == 0) return WIDGET_CALENDAR;if (strcmp(s, "messages")    == 0) return WIDGET_MESSAGES;if (strcmp(s, "ai-status")   == 0) return WIDGET_AI_STATUS;if (strcmp(s, "ai-tasks")    == 0) return WIDGET_AI_TASKS;if (strcmp(s, "scratch")     == 0) return WIDGET_SCRATCH;if (strcmp(s, "focus")       == 0) return WIDGET_FOCUS;if (strcmp(s, "now-playing") == 0) return WIDGET_NOW_PLAYING;if (strcmp(s, "git-status")  == 0) return WIDGET_GIT_STATUS;if (strcmp(s, "system")      == 0) return WIDGET_SYSTEM;return WIDGET_NONE;}WidgetSlot slotFromString(const char* s){if (strcmp(s, "top-left")  == 0) return SLOT_TOP_LEFT;if (strcmp(s, "top-right") == 0) return SLOT_TOP_RIGHT;if (strcmp(s, "middle")    == 0) return SLOT_MIDDLE;if (strcmp(s, "bottom")    == 0) return SLOT_BOTTOM;if (strcmp(s, "full")      == 0) return SLOT_FULL;return SLOT_COUNT;}

11 种 Widget 类型 × 5 个 Slot 位置，组合出无限可能。固件自己不决定显示什么——它只负责把 daemon 送来的画面像素刷到屏幕上。

还有通信层：src/ble_bridge.cpp、src/http_server.cpp、src/wifi_bridge.cpp、src/frame_receiver.cpp

四个文件实现了完整的通信栈：Wi-Fi 连接、HTTP API 接收、BLE 桥接（用于无 USB 线的场景）、像素帧接收和组包。设备可以通过 USB 串口、Wi-Fi HTTP、或 BLE 三种方式接收画面数据。

第二层：渲染引擎（Python，运行在电脑上）

核心文件：daemon/card_daemon.py（约 1500 行）

这是整个项目的大脑。daemon 跑在你的电脑上，默认监听 127.0.0.1:9877。

"""API:    POST /widget        push or replace one widget    DELETE /widget?slot=...   clear a slot (no slot = all)    GET  /widget        snapshot of cached widgets    POST /widgets/preview     Pillow-rendered 540x960 PNG for desktop    GET  /pair-status   { connected, transport }    POST /unpair        forward unpair cmd to device"""

AI Agent（Claude Code / Codex）通过 HTTP API 发送 Widget 数据 → daemon 接收 → 调用渲染引擎生成 540×960 灰阶图片 → 转换为 4bpp 像素帧 → 通过 USB/BLE 发送到设备。

渲染引擎：daemon/card_render.py（约 1200 行）

这一层的设计哲学很有意思：

"""Design philosophy (set during v0.6 migration):  - ONE font size (28pt body, 28pt bold for headlines)  - Hierarchy via dividers, inverted bars, spacing, boxes  - No font-size variation. No createRender drama. No glyph gaps.  - Inspired by Swiss minimalist e-ink dashboards (TRMNL etc.)"""

一套字体打天下。用分隔线、反转条、间距、线框来体现层级——不靠字号变化。这个选择非常务实：电子墨水屏分辨率有限，多字号意味着中文字体渲染的复杂度暴增，代码里还特别写了 "No createRender drama. No glyph gaps."，显然是踩过坑之后的顿悟。

布局定义：

SLOT_RECTS = {"top-left":  (0,   0,   270, 280),"top-right": (270, 0,   270, 280),"middle":    (0,   280, 540, 340),"bottom":    (0,   620, 540, 280),"full":      (0,   0,   540, 960),}

四个固定区域 + 一个全屏模式，像素级精确。

第三层：Agent 工作流（Hermes Agent / Claude Code Skill）

项目提供了一个完整的 Skill 系统，让 AI Agent 可以自动完成从烧录到推送的所有操作。

8 个工作流文件在 flows/ 目录下：

文件	作用
`01_install.md`	首次安装 + 烧固件
`02_transport.md`	传输诊断（USB / BLE）
`03_wifi.md`	Wi-Fi 配置
`04_interests.md`	兴趣偏好配置
`05_push.md`	推送 widget
`06_schedule.md`	定时推送
`07_sleep.md`	息屏 + 深度休眠
`08_paper_color.md`	M5Paper Color 专属流程

整个过程全由 Agent 引导：你说"帮我把 ai-desk-card 装上"，Agent 自动探测状态、安装 PlatformIO、编译固件、烧录、配 Wi-Fi、推内容。你不用自己跑一行 pio 或 curl。

四、实操：从零到推送一条信息

如果你手上有 M5Paper V1.1，跟着走只要三步：

第一步：装 Skill

在 Claude Code/Codex/Hermes Agent 中输入：

帮我安装 ai-desk-card Skill。克隆 https://github.com/op7418/ai-desk-card检查 SKILL.md、flows/、daemon/、src/、assets/ 是否存在。

或者一键命令：

npx skills add https://github.com/op7418/ai-desk-card --skill ai-desk-card

第二步：烧固件

插上 M5Paper（USB-C 数据线），对 Agent 说：

帮我把 ai-desk-card 装上。我手上是 M5Paper V1.1，USB-C 已经插好了。

Agent 会自动：

探测当前环境（PlatformIO / USB 设备 / daemon）
缺啥装啥（没 PlatformIO 就 pipx install）
编译 CJK 中文字体 + 烧录固件（约 1 分钟）

第三步：推 Widget

配置完成后，直接说：

把今天的天气和待办推上屏

或者更有趣的玩法：

把我刚读的这篇公众号文章总结推送到中间的 slot

更进阶的，还可以设置定时推送：

每天早上 9 点推送天气和日历，每 30 分钟刷新一次待办

五、源代码里值得细品的几个设计

1. 双向缓存系统

Daemon 有一个 Widget 缓存机制，在 daemon 重启后自动恢复上次显示的内容：

_WIDGET_CACHE_PATH = os.path.join(    os.environ.get("TMPDIR", "/tmp"), "ai_desk_card_widget_cache.json")

配合固件的 RTC_DATA_ATTR 技术，即使设备断电重启，屏幕上也还是上次的内容。墨水屏的"记忆"被软件层面巧妙延续了。

2. 推送去抖

PUSH_DEBOUNCE_S = 1.5

电子墨水屏的刷新周期约 500ms，但如果 Agent 在短时间内连续推送 3 次画面，实际效果是屏幕疯狂闪烁。1.5 秒的去抖窗口确保每次推送之间留足缓冲时间。

3. Widget Schema 定义

项目中包含了 17 个 JSON Schema 文件（plugin/skills/card-widget/schemas/），每个 Widget 类型都有严格的格式定义：

weather.schema.jsontodo.schema.jsoncalendar.schema.jsongit-status.schema.jsonpr-queue.schema.jsonnow-playing.schema.json...

这保证了 AI Agent 生成的 Widget 数据一定是符合预期的格式，不会出现把天气当待办解析的乌龙。

4. 息屏名片

当设备长时间无活动（或手动触发睡眠），固件会自动从 LittleFS 读取 sleep_card.bin 显示，然后进入深度休眠。这个"息屏名片"甚至可以自定义——你的 AI Agent 可以生成一段文字，渲染成名片样式再推上去。

六、情绪价值：它给我的感觉

我用了这个项目两周后，最深的感受是：

AI Agent 不再是"黑箱"了。

以前用 Claude Code 写代码，我只能看到终端的滚动输出。它搜到了什么？下一步计划？为什么停在这里？这些信息要么没有，要么需要我主动去问。

有了 ai-desk-card，Agent 会把它的"思考过程"直接推上那块墨水屏：

[*]
正在重构模块 X...
[*]
发现了 Y 文件中的潜在 bug
[*]
等待你确认数据库迁移
[*]
今天完成了 3 个 PR 的 review

就像有一个安静的小伙伴在旁边，默默在本子上写笔记。

而且墨水屏的物理存在感本身就很特别。它不像弹窗那样强迫你注意，也不像通知角标那样制造焦虑。它就在那里，你想看的时候瞥一眼，不想看的时候它也不骚扰你。

在信息过载的时代，这种"不打扰的知情权"，反而成了奢侈品。

七、项目信息

[*]
项目名称： ai-desk-card
[*]
开源地址： https://github.com/op7418/ai-desk-card
[*]
硬件需求： M5Paper V1.1 或 M5Paper Color（4.7寸墨水屏）
[*]
软件需求： Claude Code / Codex / Hermes Agent 任一
[*]
协议： MIT

项目跑在 M5Paper 上，daemon 已连续运行超过 48 小时，累计推送 70+ 次。写入此文时，墨水屏上刚推送进来一条："今天下午2点有团队同步会，别迟到。"

—— 有时候，一个好的提示不需要 2K 分辨率。

真不错，不同的时段还可以显示不同的内容。