ai-desk-card
Drive a physical e-ink desk card (M5Paper 540×960) sitting next to the user's monitor. Use whenever the user wants to: - show / push / display ANYTHING on their card / 卡片 / 副屏 / 墨水屏 / e-ink display / desk card / glanceable display / secondary display - set up the device for the first time (flash firmware, pair, provision Wi-Fi) — phrases like "刚拿到 M5Paper", "怎么装卡片", "first-time setup", "刷固件", "卡片没反应" - schedule recurring pushes / "每小时刷一次" / "工作时间显示日历" / "auto-refresh every 30 min" - configure what the card shows (weather, todos, calendar, inbox, PR queue, AI status, focus, scratch, deadlines, messages, now-playing, git-status, system, next-meeting, break-reminder, ai-tasks) - put the device to sleep / show business card / "息屏" / "睡眠" Single Skill, agent-agnostic: probes current state, then routes to the right sub-flow. Never asks "is the daemon running" — it checks.
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ai-desk-card
- description
- Drive a physical e-ink desk card (M5Paper 540×960) sitting next to the user's monitor. Use whenever the user wants to: - show / push / display ANYTHING on their card / 卡片 / 副屏 / 墨水屏 / e-ink display / desk card / glanceable display / secondary display - set up the device for the first time (flash firmware, pair, provision Wi-Fi) — phrases like "刚拿到 M5Paper", "怎么装卡片", "first-time setup", "刷固件", "卡片没反应" - schedule recurring pushes / "每小时刷一次" / "工作时间显示日历" / "auto-refresh every 30 min" - configure what the card shows (weather, todos, calendar, inbox, PR queue, AI status, focus, scratch, deadlines, messages, now-playing, git-status, system, next-meeting, break-reminder, ai-tasks) - put the device to sleep / show business card / "息屏" / "睡眠" Single Skill, agent-agnostic: probes current state, then routes to the right sub-flow. Never asks "is the daemon running" — it checks.
- allowed-tools
- [ "Bash", "Read", "Write", "Edit" ]
- trigger_keywords
- [ "card", "desk card", "卡片", "副屏", "墨水屏", "e-ink", "M5Paper", "paper card", "glanceable display", "secondary display", "ai-desk-card", "桌面卡片", "dashboard card" ]
02 资源文件 74
- 其他.gitignore131 B
- 资产文件assets/profile.yaml1.7 KB
- 资产文件assets/qr.png3.9 KB
- 脚本daemon/card_daemon.py61.5 KB
- 脚本daemon/card_render_color.py26.0 KB
- 脚本daemon/card_render_settings_color.py3.7 KB
- 脚本daemon/card_render_settings.py9.2 KB
- 脚本daemon/card_render_sleep_color.py5.1 KB
- 脚本daemon/card_render_sleep.py16.0 KB
- 脚本daemon/card_render.py39.6 KB
- 脚本daemon/color_daemon.py14.9 KB
- 其他data/sleep_card.bin253.1 KB
- 参考文档flows/01_install.md3.1 KB
- 参考文档flows/02_transport.md2.0 KB
- 参考文档flows/03_wifi.md1.9 KB
- 参考文档flows/04_interests.md3.0 KB
- 参考文档flows/05_push.md3.2 KB
- 参考文档flows/06_schedule.md3.6 KB
- 参考文档flows/07_sleep.md2.7 KB
- 参考文档flows/08_paper_color.md5.6 KB
- 参考文档HANDOVER.md22.6 KB
- 许可证LICENSE36.6 KB
- 资产文件partitions.csv389 B
- 参考文档PLAN_RENDERING_V06.md11.9 KB
- 参考文档PLAN.md7.1 KB
- 其他platformio.ini2.2 KB
- 参考文档plugin/commands/card-install.md436 B
- 参考文档plugin/commands/card-onboard.md517 B
- 参考文档plugin/commands/card-refresh.md583 B
- 参考文档plugin/commands/card-sleep.md651 B
- 参考文档plugin/commands/card-start.md300 B
- 参考文档plugin/commands/card-status.md212 B
- 参考文档plugin/commands/card-stop.md98 B
- 参考文档plugin/commands/card-widget.md407 B
- 参考文档plugin/commands/card-wifi-setup.md629 B
- 参考文档plugin/plugin.json899 B
- 脚本plugin/scripts/install.sh752 B
- 脚本plugin/scripts/sleep.sh776 B
- 脚本plugin/scripts/start.sh1.2 KB
- 脚本plugin/scripts/status.sh612 B
- 脚本plugin/scripts/stop.sh207 B
- 脚本plugin/scripts/widget.sh1.0 KB
- 脚本plugin/scripts/wifi_setup.sh3.1 KB
- 参考文档PRODUCT.md15.3 KB
- 参考文档README.en.md16.2 KB
- 参考文档README.md16.4 KB
- 脚本scripts/color_push.py11.4 KB
- 脚本scripts/state.sh4.2 KB
- 其他src/ble_bridge.cpp7.4 KB
- 其他src/ble_bridge.h1.3 KB
- 其他src/frame_receiver.cpp9.3 KB
- 其他src/frame_receiver.h2.3 KB
- 其他src/http_server.cpp9.9 KB
- 其他src/http_server.h1.5 KB
- 其他src/main.cpp29.9 KB
- 其他src/paper_color/audio.cpp1.7 KB
- 其他src/paper_color/audio.h678 B
- 其他src/paper_color/feedback_led.cpp1.3 KB
- 其他src/paper_color/feedback_led.h547 B
- 其他src/paper_color/frame_buffer.cpp1.2 KB
- 其他src/paper_color/http_server.cpp11.3 KB
- 其他src/paper_color/http_server.h956 B
- 其他src/paper_color/main.cpp6.4 KB
- 其他src/paper_color/sht40.cpp1.4 KB
- 其他src/paper_color/sht40.h477 B
- 其他src/paper_color/wifi_bridge.cpp2.5 KB
- 其他src/paper_color/wifi_bridge.h590 B
- 其他src/sleep_card.cpp1.6 KB
- 其他src/sleep_card.h888 B
- 其他src/widgets.cpp9.8 KB
- 其他src/widgets.h6.2 KB
- 其他src/wifi_bridge.cpp5.2 KB
- 其他src/wifi_bridge.h1.5 KB
- 脚本tools/build_sleep_card.py2.0 KB
03 SKILL.md 正文
ai-desk-card — single Skill entry point
A 540×960 e-ink panel sitting next to the user's monitor. AI agents push widgets to it; the daemon renders frames server-side and ships pixels over Wi-Fi / USB / BLE. This Skill is the only thing an agent needs to call — it auto-detects state and routes to the right flow.
Step 1 — ALWAYS probe state first
Before doing anything, run the state probe. Do not ask the user "have you done X" — find out by checking.
bash $SKILL_DIR/scripts/state.sh
($SKILL_DIR is wherever this Skill is installed. If your agent runtime
sets $CLAUDE_PLUGIN_ROOT, use that. Otherwise use the repo root.)
Output is JSON with this shape:
{
"hardware": { "pio_installed": bool, "m5paper_usb": str|null },
"firmware": { "flashed": bool, "ours": bool, "version": str|null },
"daemon": { "running": bool, "pid": int|null },
"transport": { "connected": bool, "type": "BLETransport|SerialTransport|WiFiTransport|null" },
"device": { "alive": bool, "last_seen_seconds": int|null,
"active_transport": "Wi-Fi|USB|BLE|null",
"battery_pct": int|null, "uptime": str|null },
"wifi": { "provisioned": bool, "ip": str|null },
"interests": { "configured": bool, "path": str|null }
}
The most important field is device.alive. It tells you whether the
device has sent a status report in the last ~90 s. transport.connected
only says "daemon picked a transport class"; device.alive says "we're
actually hearing back from the device right now."
Step 1.5 — Identify the device profile
The Skill supports two devices with different panels + daemons:
- M5Paper V1.1 (540×960 grayscale, GT911 touch, BLE pair) — original
- M5Paper Color (600×400 Spectra 6 color, 3 physical buttons, audio + SHT40) — new in v0.10
If GET /heartbeat returns device_status.device == "M5PaperColor"
(via color_daemon.py running), use the Color path described in
flows/08_paper_color.md:
- env:
pio run -e paper-color - daemon:
python3 daemon/color_daemon.py --device-ip <IP> - Wi-Fi provision: Serial JSON
cmd:wifi_set(no BLE pairing UX) - slot names:
top-left / top-right / bottom-left / bottom-right - extra widgets:
ambient(SHT40 temp+humid) - physical buttons: 顶=sleep / 下左=refresh / 下中=settings
Otherwise (default) use the V1.1 path through the routing table below.
The two daemons can't run on the same port simultaneously — pick one based on which device is in front of the user. The Skill flows below work for V1.1 unless explicitly noted.
Step 2 — Route based on state
Walk the decision tree in this order. First mismatch wins; fix it, then re-probe.
| Condition | Next action | Detail flow |
|---|---|---|
firmware.flashed == false AND no device.alive |
First-time hardware setup | flows/01_install.md |
daemon.running == false |
Start the daemon | bash $SKILL_DIR/plugin/scripts/start.sh |
device.alive == false AND transport.connected == false |
Device unreachable — could be asleep, off, BLE not paired. Tell user, suggest physical wake (tap rotary / plug USB) | flows/02_transport.md |
device.alive == false AND transport.connected == true (daemon connected something but no status_report in 90s) |
Device transport up but not responding — restart daemon, then probe | flows/02_transport.md |
wifi.provisioned == false (and user wants always-on or battery mode) |
Provision Wi-Fi | flows/03_wifi.md |
interests.configured == false AND user just asked for "auto-refresh" or "定时推送" |
Ask about interests, write ~/.ai-desk-card/interests.yaml |
flows/04_interests.md |
device.alive == true + user said "push X" |
Build widget JSON, POST to daemon | flows/05_push.md |
device.alive == true + user said "schedule" / "每 N 分钟" / "auto" |
Set up scheduled push | flows/06_schedule.md |
device.alive == true + user said "sleep" / "息屏" |
Push business card + deep sleep | flows/07_sleep.md |
Always tell the user which step you're on. Don't operate silently.
Step 3 — Push a widget (the hot path)
When state is OK and user asks to show something:
curl -sf -X POST "${CARD_DAEMON_URL:-http://127.0.0.1:9877}/widget" \
-H 'Content-Type: application/json' \
-d @- <<'JSON'
{
"slot": "top-left",
"type": "weather",
"data": { "city": "Beijing", "temp_c": 22, "icon": "sun", "summary": "晴" }
}
JSON
- slot: string. Layout is 2-1-1 not 2x2 —
top-left(270×280) ·top-right(270×280) ·middle(540×340) ·bottom(540×280) ·full(540×960, takes over the whole screen). - type: one of 16 — see
plugin/skills/card-widget/schemas/for full JSON schemas with examples. - Wi-Fi: response in ~0.2 s. USB: 1–32 s. BLE frame-data: broken — small commands only.
Full per-widget schema + theme reference: plugin/skills/card-widget/SKILL.md
Step 4 — When to suggest scheduled pushes
If the user's request implies recurrence ("keep my calendar updated", "check email every hour", "show me today's todos throughout the day"), don't just push once. Instead:
- Confirm the cadence + which widgets they want
- Write/update
~/.ai-desk-card/interests.yaml(see flow 04) - Set up the schedule using your agent's native loop primitive:
- Claude Code:
/loop 30morScheduleWakeup - Codex / Gemini: equivalent scheduling
- Fallback: cron line via
plugin/skills/card-refresh/scripts/refresh_loop.sh
- Claude Code:
The Skill provides the what (interests + push) — your agent provides the when (loop primitive).
Constraints to never violate
- No silent operations. Every sub-step gets a one-line update to the user.
- No retry loops. If something fails, surface the diagnostic and stop.
- No assuming state. Always re-probe after fixing something.
- No font escape hatches. The CJK TTF doesn't include ▢ ▶ ✎ ♪ ↑ ↓ ● ○ — … °. Use the safe glyph set documented in plugin/skills/card-widget/SKILL.md.
- Wi-Fi preferred over USB / BLE. 0.2 s vs 1-32 s vs broken.
Hardware: what the user needs
- M5Paper V1.1 (~¥600 / $90) — primary target
- USB-C data cable (one time, for flashing)
- Optional: USB-C charger for always-on Wi-Fi mode
What this Skill is NOT
- Not a Claude-Code-only plugin. The
plugin/directory is provided for CLIs that consume slash commands, but thisSKILL.mdis the agent-agnostic entry point. - Not a cloud service. Everything runs on the user's machine (daemon at
127.0.0.1:9877by default) + the device's local Wi-Fi. - Not a generic e-ink renderer. The widgets, themes, and renderer all target this specific device + grid.
04 同仓库更多 Skills
blender-web-3d
Work with Blender from Claude — headless CLI or the Blender MCP — to build, modify, render, and publish any 3D model as a stunning, fast Three.js/Next.js web experience (gltf-transform meshopt/KTX2, AgX colour pipeline, custom GLSL shaders and material patches, procedural sky/planet, bloom, adaptive quality, runtime batching, baked lightmaps, Vercel deploy). Use whenever the user wants to create, improve, fix, render, or iterate on a Blender model or scene — "improve the model", "make it look stunning", "render this", "make a 3D web demo", "export to GLB", "use blender", "looks wrong in the browser", "optimize the 3D scene", "add shaders", "it's slow", or screenshot-driven feedback on a 3D asset. Also for debugging a Three.js viewer that renders black, glows wrong, or loses/detaches parts, and for choosing Blender MCP vs headless CLI. Ships a runnable demo model and viewer template.
guizang-ppt-skill
生成横向翻页网页 PPT(单 HTML 文件),含 WebGL 背景、章节幕封、数据大字报、图片网格等模板。提供两种风格:① "电子杂志 × 电子墨水"(衬线 + 流体背景 + 暖色) ② "瑞士国际主义"(无衬线 + 网格点阵 + IKB/柠檬黄/柠檬绿/安全橙高亮)。当用户需要制作分享 / 演讲 / 发布会风格的网页 PPT,或提到"杂志风 PPT"、"瑞士风 PPT"、"Swiss Style"、"horizontal swipe deck"时使用。
youtube-clipper
YouTube 视频智能剪辑工具。下载视频和字幕,AI 分析生成精细章节(几分钟级别), 用户选择片段后自动剪辑、翻译字幕为中英双语、烧录字幕到视频,并生成总结文案。 使用场景:当用户需要剪辑 YouTube 视频、生成短视频片段、制作双语字幕版本时。 关键词:视频剪辑、YouTube、字幕翻译、双语字幕、视频下载、clip video
slack-gif-creator
Toolkit for creating animated GIFs optimized for Slack, with validators for size constraints and composable animation primitives. This skill applies when users request animated GIFs or emoji animations for Slack from descriptions like "make me a GIF for Slack of X doing Y".
create-master
基于佛教经典文献,生成特定高僧大德的 AI 教学角色
writing-dna-skill
从至少 20 篇完整文章中蒸馏可复用的写作 DNA,分析语言、文章结构、选题逻辑、素材策略、认知框架和视觉风格,并生成 Writing-DNA.md;按该 DNA 写作时会读取全部蒸馏产物和 5 篇相关原文。用于中英文作者、账号、品牌或出版物的风格分析与一致性写作。 Distill reusable Writing DNA from at least 20 complete articles for Chinese or English authors, publications, brands, and accounts; use for language, structure, topic logic, source strategy, cognitive-frame, and visual-style analysis.