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. trigger_keywords:

• card
• desk card
• 卡片
• 副屏
• 墨水屏
• e-ink
• M5Paper
• paper card
• glanceable display
• secondary display
• ai-desk-card
• 桌面卡片
• dashboard card allowed-tools:
• Bash
• Read
• Write
• Edit

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.

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:

1. Confirm the cadence + which widgets they want
2. Write/update ~/.ai-desk-card/interests.yaml (see flow 04)
3. Set up the schedule using your agent's native loop primitive:
   • Claude Code: /loop 30m or ScheduleWakeup
   • Codex / Gemini: equivalent scheduling
   • Fallback: cron line via plugin/skills/card-refresh/scripts/refresh_loop.sh

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 this SKILL.md is the agent-agnostic entry point.
• Not a cloud service. Everything runs on the user's machine (daemon at 127.0.0.1:9877 by default) + the device's local Wi-Fi.
• Not a generic e-ink renderer. The widgets, themes, and renderer all target this specific device + grid.

AI Desk Card · 桌面 AI 副屏 Skill

🌏 English version: README.en.md

一个适配 Claude Code / Codex 等 Agent 的桌面副屏 Skill。把 M5Paper V1.1 4.7 寸墨水屏立在显示器旁边，由 AI Agent 推送 widget：天气、日程、todo、PR 队列、AI 状态、休息提醒……

装上 Skill 后，烧固件 / 配 Wi-Fi / 推内容 / 设置定时全部由 Agent 引导，你不用自己跑一行 pio 或 curl。

你 ──说自然语言──▶ AI Agent ──触发──▶ Skill ──自动执行──▶ M5Paper 屏上

30 秒开始

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

也可以把下面这段话直接发给有 shell 权限的 AI Agent：

帮我安装 ai-desk-card Skill。把 https://github.com/op7418/ai-desk-card 克隆到 ~/.claude/skills/ai-desk-card，安装完成后检查 SKILL.md、flows/、daemon/、src/、assets/ 是否存在。

已经装过想更新：

帮我更新 ai-desk-card。请进入 ~/.claude/skills/ai-desk-card 执行 git pull，然后告诉我当前最新 commit。

装完之后，假设你手上有 M5Paper V1.1 + USB-C 数据线，直接对 Agent 说：

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

Skill 会自动：

1. 探测当前状态（PlatformIO / USB 设备 / daemon / Wi-Fi 配没配）
2. 缺啥装啥（PlatformIO 没装就 pipx install）
3. 编译 + 烧 CJK 字体 + 烧固件（约 1 分钟）
4. 启动 daemon
5. 问你 Wi-Fi 密码 → 自动配上
6. 推第一个 widget 上去

之后日常使用就是和 Agent 自然对话：

在卡片上显示今天北京的天气。
让卡片每 30 分钟刷新天气和未读邮件，工作日 8 点到 22 点。
现在卡片上是啥？
晚上 11 点之后自动息屏显示我的名片。

效果

• 🖥 桌面 ambient 副屏：540×960 墨水屏立在显示器旁，瞥一眼就知道今天的状态
• 🤖 AI 主动推送：Agent 决定推什么 widget、什么时候推；你不用自己开浏览器查天气
• 📦 16 种 widget：weather / calendar / todo / focus / inbox / pr-queue / ai-status / git-status / now-playing / break-reminder / scratch / messages / deadlines / next-meeting / system / ai-tasks
• 🎨 服务端渲染：daemon 用 Python + Pillow 渲染像素帧，固件只负责显示；想加新 widget 只改 Python，不用动 C++
• 🔌 三种供电模式自动切换：USB 常开 / USB 数据线 / 电池 + BLE 待机（几个月续航）
• 🌐 Wi-Fi LAN 0.2 秒一帧：本地 HTTP 直推，无云依赖
• 💤 关屏 0 功耗保留最后一帧：墨水屏特性，电池续航 6 个月（架构 C）
• 👆 底栏触屏 chip：点"睡眠"推电子名片 + 深度休眠；点"设置"翻设置页。150ms 点击态反馈
• ⏰ 定时自动息屏：到 quiet hours 自动切到电子名片，daemon 不需要 Agent 在线

适合 / 不适合

✅ 合适：

• 想要 always-on 桌面副屏，但不想再开第二台亮屏显示器
• 已经在用 Claude Code / Codex / Cursor 等 Agent，想给它一个物理 ambient 输出
• 喜欢墨水屏低疲劳感（不刺眼、不抢注意力）
• 接受第一次 ~10 分钟硬件配置（之后 0 维护）

❌ 不合适：

• 需要快速刷新内容（股票实时、视频、动效）— 墨水屏不行
• 不想买硬件 / 不想烧固件
• 需要复杂触屏交互（墨水屏触屏可用但慢）

常见使用场景

平台支持

硬件准备

⚠️ 不需要事先装 PlatformIO / 编译器 / Python 环境 — Skill 检测到缺什么会让 Agent 自己装。

安装

方式一：一行命令（推荐）

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

方式二：让 AI 帮你装

把下面这段话复制粘贴给 Claude Code / Cursor / 任何有 shell 权限的 AI Agent：

帮我装 ai-desk-card 这个 Skill。请按下面步骤做：

1. 确保 ~/.claude/skills/ 目录存在（不存在就创建）
2. 执行 git clone https://github.com/op7418/ai-desk-card.git ~/.claude/skills/ai-desk-card
3. 验证：ls ~/.claude/skills/ai-desk-card/ 应该看到 SKILL.md、flows/、plugin/、daemon/、src/、assets/
4. 装好告诉我，之后我说"帮我把卡片装上"就会触发这个 Skill

方式三：手动 clone

git clone https://github.com/op7418/ai-desk-card.git ~/.claude/skills/ai-desk-card

触发关键词

装好后 Agent 会在你说这些时自动唤起 Skill：

• "卡片" / "副屏" / "墨水屏" / "桌面卡片"
• "把 X 显示在卡片上" / "show X on my card"
• "刚拿到 M5Paper" / "first-time setup" / "刷固件"
• "每 N 分钟刷新" / "auto-refresh"
• "卡片息屏" / "显示名片" / "睡眠"
• "ai-desk-card"

使用流程

Skill 是结构化工作流，Agent 会按下面顺序自动跑（你不用记每一步）：

1. 入职 (flow 01) — 探测 PlatformIO / USB 设备 → 引导你烧固件
2. 传输诊断 (flow 02) — 设备连不上时定位问题
3. 配 Wi-Fi (flow 03) — 把 Wi-Fi 凭证写进设备 NVS
4. 写偏好 (flow 04) — 第一次问"你想看哪些卡片，多久刷一次"
5. 推 widget (flow 05) — 日常推送的热路径
6. 设定时 (flow 06) — Agent 用自己的 loop / cron 定时刷
7. 息屏 (flow 07) — 推电子名片 + 设备深度休眠 0 功耗

完整子流程在 flows/ 目录。Skill 主路由在 SKILL.md。

16 种 Widget

工作日常：

• weather 天气 · calendar 今日日程 · next-meeting 下个会
• todo 待办 · focus 当前专注任务 · deadlines deadline 提醒
• inbox 收件箱 · messages 消息 · pr-queue PR 队列
• git-status git 状态 · system 系统状态 · now-playing 正在播放

笔记 / 节奏：

• scratch 便签 · break-reminder 休息提醒

AI 监控：

• ai-status 当前 AI session · ai-tasks AI 任务列表

4 个槽位 / 2-1-1 布局：

┌────────────┬────────────┐
│ top-left   │ top-right  │  ← 270×280 各占半
├────────────┴────────────┤
│         middle          │  ← 540×340 整条
├─────────────────────────┤
│         bottom          │  ← 540×280 整条
├─────────────────────────┤
│  bottom bar (chip 区)   │  ← 60 px，含"睡眠""设置"chip
└─────────────────────────┘

还有一个 full（540×960）覆盖全屏，用来推电子名片 / 启动 splash 等。

完整 schema 在 plugin/skills/card-widget/schemas/。

自动刷新（可选）

Skill 第一次问你"想看哪些卡片、什么时段刷"时，会帮你写 ~/.ai-desk-card/interests.yaml：

version: 1

slots:
  top-left:  weather
  top-right: calendar
  middle:    todo
  bottom:    inbox

schedule:
  cadence:  "30m"           # 5m / 15m / 30m / 1h / 2h
  hours:    "08-22"
  days:     "mon-fri"
  timezone: "Asia/Shanghai"

data_sources:
  weather:
    city: "Beijing"
  calendar:
    source: "macos"          # 或 google / ics-url
  todo:
    source: "reminders"      # 或 things3 / todoist
  git_status:
    repo: "/Users/you/code/main-project"

# 到 quiet_hours.start 自动切到电子名片 + deep sleep
# daemon 后台自动处理，不需要 Agent 在线
quiet_hours:
  enabled: true
  start:   "23:00"
  end:     "07:00"

定时触发方式：

• Agent 原生 loop（推荐）：Claude Code 的 /loop 30m、ScheduleWakeup 等
• cron：crontab -e 加一行 */30 8-21 * * 1-5 bash /path/to/ai-desk-card/plugin/skills/card-refresh/scripts/refresh_loop.sh
• 纯 Python 无 AI 兜底：weather / system / git 这几个不需要 AI，直接跑 fallback_refresh.py

三种供电模式

架构 C 是最爱：屏挂在桌边几个月不充电，AI Agent 推内容时 BLE 唤醒一次 → 拉 Wi-Fi → HTTP 推帧 → 30 秒 linger 后断 Wi-Fi。一次推送约 0.2 mAh，24 次/天 × 6 个月 = 1150 mAh 电池。

目录结构

ai-desk-card/
├── SKILL.md                  ← 任意 Agent 的入口
├── scripts/state.sh          ← 状态探测：JSON 输出 daemon/transport/wifi/device/interests 状态
├── flows/                    ← 7 个子流程（每个 ~60-100 行）
│   ├── 01_install.md             零状态硬件 + 固件烧录
│   ├── 02_transport.md           daemon 连不上设备的诊断
│   ├── 03_wifi.md                Wi-Fi 配网
│   ├── 04_interests.md           interests.yaml 引导写入
│   ├── 05_push.md                推 widget 热路径
│   ├── 06_schedule.md            定时刷新协议
│   └── 07_sleep.md               电子名片 + deep sleep
├── plugin/                   ← Claude Code 兼容层（slash 命令 + 共享脚本）
│   ├── plugin.json
│   ├── commands/             ← /card-* 命令
│   ├── scripts/              ← start.sh / stop.sh / status.sh
│   └── skills/               ← 子 skill，由主 SKILL.md 间接调用
├── daemon/
│   ├── card_daemon.py        ← HTTP 桥 + 传输层 + 后台 loop
│   ├── card_render.py        ← widget view 渲染
│   ├── card_render_settings.py
│   └── card_render_sleep.py  ← 电子名片渲染
├── src/                      ← 固件 (frame_receiver / wifi / http / ble / 触屏 poll)
├── assets/
│   ├── profile.yaml          ← 你的电子名片信息（息屏时显示）
│   ├── qr.png                ← 可选 QR
│   └── avatar.png            ← 可选头像
├── data/cjk.ttf              ← CJK 字体（首次烧到 LittleFS）
├── platformio.ini
├── partitions.csv
├── HANDOVER.md               ← 工程交接
└── PRODUCT.md                ← 产品定位

工作原理（一图看懂）

你说话                                        M5Paper
  │                                               ▲
  ▼                                               │
AI Agent ──────┐                                  │
               │ 触发 Skill                        │
               ▼                                  │
          SKILL.md 路由表                          │
               │                                  │
               │  scripts/state.sh 探测：          │
               │  · pio / firmware / daemon       │
               │  · device.alive / wifi           │
               │  · interests.yaml                │
               │                                  │
               └─▶ 选 7 个子 flow 之一             │
                       │                          │
                       ▼                          │
                  Agent 自动执行                   │
                       │                          │
                       ▼                          │
              POST 到 daemon (127.0.0.1:9877)     │
                       │                          │
                       ▼                          │
              daemon 渲染（Python + Pillow）       │