[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79946":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":41,"readmeContent":42,"aiSummary":43,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":44,"discoverSource":45},79946,"ai-desk-card","op7418\u002Fai-desk-card","op7418","桌面 AI 副屏 Skill：M5Paper 墨水屏 + AI Agent 推送 widget。装 Skill 后由 Agent 自动引导烧固件、配 Wi-Fi、推送内容。本地运行、无云依赖。","https:\u002F\u002Fgithub.com\u002Fop7418\u002Fai-desk-card",null,"Python",103,7,80,2,0,1,5,19,4,2.71,"Other",false,"main",true,[27,28,29,30,31,32,33,34,35,36,37,38,39,40],"ai-agent","ai-skill","ambient-display","claude-code","codex","dashboard","desk-card","e-ink","esp32","glanceable-display","m5paper","secondary-display","skill","skills","2026-06-12 02:03:56","# AI Desk Card · 桌面 AI 副屏 Skill\n\n![GitHub stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fop7418\u002Fai-desk-card?style=flat-square)\n![License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fop7418\u002Fai-desk-card?style=flat-square)\n![Skill](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSkill-Agent-111111?style=flat-square)\n![M5Paper](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FM5Paper-V1.1-0A7CFF?style=flat-square)\n![Claude Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude%20Code-Supported-6B5B95?style=flat-square)\n![Codex](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCodex-Supported-222222?style=flat-square)\n\n> 🌏 **English version: [README.en.md](.\u002FREADME.en.md)**\n\n一个适配 Claude Code \u002F Codex 等 Agent 的桌面副屏 Skill。把 [M5Paper V1.1](https:\u002F\u002Fdocs.m5stack.com\u002Fen\u002Fcore\u002Fm5paper) 4.7 寸墨水屏立在显示器旁边，由 AI Agent 推送 widget：天气、日程、todo、PR 队列、AI 状态、休息提醒……\n\n**装上 Skill 后，烧固件 \u002F 配 Wi-Fi \u002F 推内容 \u002F 设置定时全部由 Agent 引导**，你不用自己跑一行 `pio` 或 `curl`。\n\n![AI Desk Card 桌面效果](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fb4777ba7-d668-42c1-9920-3e6d8bef534e)\n\n```\n你 ──说自然语言──▶ AI Agent ──触发──▶ Skill ──自动执行──▶ M5Paper 屏上\n```\n\n## 30 秒开始\n\n```bash\nnpx skills add https:\u002F\u002Fgithub.com\u002Fop7418\u002Fai-desk-card --skill ai-desk-card\n```\n\n也可以把下面这段话直接发给有 shell 权限的 AI Agent：\n\n```text\n帮我安装 ai-desk-card Skill。把 https:\u002F\u002Fgithub.com\u002Fop7418\u002Fai-desk-card 克隆到 ~\u002F.claude\u002Fskills\u002Fai-desk-card，安装完成后检查 SKILL.md、flows\u002F、daemon\u002F、src\u002F、assets\u002F 是否存在。\n```\n\n已经装过想更新：\n\n```text\n帮我更新 ai-desk-card。请进入 ~\u002F.claude\u002Fskills\u002Fai-desk-card 执行 git pull，然后告诉我当前最新 commit。\n```\n\n装完之后，假设你手上有 M5Paper V1.1 + USB-C 数据线，直接对 Agent 说：\n\n```text\n帮我把 ai-desk-card 装上。我手上是 M5Paper V1.1，USB-C 已经插好了。\n```\n\nSkill 会自动：\n\n1. 探测当前状态（PlatformIO \u002F USB 设备 \u002F daemon \u002F Wi-Fi 配没配）\n2. 缺啥装啥（PlatformIO 没装就 `pipx install`）\n3. 编译 + 烧 CJK 字体 + 烧固件（约 1 分钟）\n4. 启动 daemon\n5. 问你 Wi-Fi 密码 → 自动配上\n6. 推第一个 widget 上去\n\n之后日常使用就是和 Agent 自然对话：\n\n```text\n在卡片上显示今天北京的天气。\n让卡片每 30 分钟刷新天气和未读邮件，工作日 8 点到 22 点。\n现在卡片上是啥？\n晚上 11 点之后自动息屏显示我的名片。\n```\n\n## 效果\n\n- 🖥 **桌面 ambient 副屏**：540×960 墨水屏立在显示器旁，瞥一眼就知道今天的状态\n- 🤖 **AI 主动推送**：Agent 决定推什么 widget、什么时候推；你不用自己开浏览器查天气\n- 📦 **16 种 widget**：weather \u002F calendar \u002F todo \u002F focus \u002F inbox \u002F pr-queue \u002F ai-status \u002F git-status \u002F now-playing \u002F break-reminder \u002F scratch \u002F messages \u002F deadlines \u002F next-meeting \u002F system \u002F ai-tasks\n- 🎨 **服务端渲染**：daemon 用 Python + Pillow 渲染像素帧，固件只负责显示；想加新 widget 只改 Python，不用动 C++\n- 🔌 **三种供电模式自动切换**：USB 常开 \u002F USB 数据线 \u002F 电池 + BLE 待机（几个月续航）\n- 🌐 **Wi-Fi LAN 0.2 秒一帧**：本地 HTTP 直推，无云依赖\n- 💤 **关屏 0 功耗保留最后一帧**：墨水屏特性，电池续航 6 个月（架构 C）\n- 👆 **底栏触屏 chip**：点\"睡眠\"推电子名片 + 深度休眠；点\"设置\"翻设置页。150ms 点击态反馈\n- ⏰ **定时自动息屏**：到 quiet hours 自动切到电子名片，daemon 不需要 Agent 在线\n\n## 适合 \u002F 不适合\n\n**✅ 合适**：\n\n- 想要 always-on 桌面副屏，但不想再开第二台亮屏显示器\n- 已经在用 Claude Code \u002F Codex \u002F Cursor 等 Agent，想给它一个物理 ambient 输出\n- 喜欢墨水屏低疲劳感（不刺眼、不抢注意力）\n- 接受第一次 ~10 分钟硬件配置（之后 0 维护）\n\n**❌ 不合适**：\n\n- 需要快速刷新内容（股票实时、视频、动效）— 墨水屏不行\n- 不想买硬件 \u002F 不想烧固件\n- 需要复杂触屏交互（墨水屏触屏可用但慢）\n\n## 常见使用场景\n\n| 你说 | Agent 干什么 |\n|------|------|\n| \"帮我把 ai-desk-card 装上\" | 完整入职流程：探测状态 → 烧固件 → 起 daemon → 配 Wi-Fi |\n| \"在卡片上显示今天的天气\" | 推 weather widget |\n| \"把日程贴上去\" | 推 calendar widget，自动读 macOS 日历 |\n| \"显示我现在在做的任务\" | 推 focus widget |\n| \"让卡片每 30 分钟刷新\" | 写 `~\u002F.ai-desk-card\u002Finterests.yaml` + 注册 loop |\n| \"23 点自动息屏显示名片\" | 配 quiet_hours，daemon 后台自动处理 |\n| \"卡片连不上\" | 触发诊断 flow：探测 → 定位问题 → 给修复建议 |\n| \"我换 Wi-Fi 了\" | 重新走 wifi-setup flow |\n| \"卡片现在显示啥\" | curl daemon 拿当前帧的 PNG 预览 |\n\n## 平台支持\n\n| 平台 | 状态 | 说明 |\n|------|------|------|\n| Claude Code | ✅ 主力测试 | 原生 Skill 工作流 + slash 命令兼容层 |\n| Codex CLI | 🟡 同 SKILL.md 格式 | 应该可用，未深度测试 |\n| Gemini CLI | 🟡 应该可用 | 同上 |\n| Cursor | 🟡 可用 | 需要 shell 权限 |\n| Aider | 🟡 可用 | 同上 |\n| 自写 Agent | ✅ | 只要识别 SKILL.md + 有 shell 权限就行 |\n\n## 硬件准备\n\n| 项目 | 说明 |\n|------|------|\n| **M5Paper V1.1** | 主力支持。约 ¥600 \u002F $90。[官方店](https:\u002F\u002Fshop.m5stack.com\u002Fproducts\u002Fm5paper-v1-1) \u002F Amazon \u002F AliExpress |\n| M5Paper V1.0 | 大概率可用，电池阈值参数 (`4150 mV`) 可能要调 |\n| M5Paper S3 | 需要 1-2 天移植（BLE stack 不同）|\n| USB-C **数据线** | 烧固件时用一次。普通\"只充电\"线不行 |\n| (可选) USB-C 充电器 | 想用\"常插电 + Wi-Fi 常开\"模式需要 |\n\n> ⚠️ **不需要事先装 PlatformIO \u002F 编译器 \u002F Python 环境** — Skill 检测到缺什么会让 Agent 自己装。\n\n## 安装\n\n### 方式一：一行命令（推荐）\n\n```bash\nnpx skills add https:\u002F\u002Fgithub.com\u002Fop7418\u002Fai-desk-card --skill ai-desk-card\n```\n\n### 方式二：让 AI 帮你装\n\n把下面这段话复制粘贴给 Claude Code \u002F Cursor \u002F 任何有 shell 权限的 AI Agent：\n\n> 帮我装 `ai-desk-card` 这个 Skill。请按下面步骤做：\n>\n> 1. 确保 `~\u002F.claude\u002Fskills\u002F` 目录存在（不存在就创建）\n> 2. 执行 `git clone https:\u002F\u002Fgithub.com\u002Fop7418\u002Fai-desk-card.git ~\u002F.claude\u002Fskills\u002Fai-desk-card`\n> 3. 验证：`ls ~\u002F.claude\u002Fskills\u002Fai-desk-card\u002F` 应该看到 `SKILL.md`、`flows\u002F`、`plugin\u002F`、`daemon\u002F`、`src\u002F`、`assets\u002F`\n> 4. 装好告诉我，之后我说\"帮我把卡片装上\"就会触发这个 Skill\n\n### 方式三：手动 clone\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fop7418\u002Fai-desk-card.git ~\u002F.claude\u002Fskills\u002Fai-desk-card\n```\n\n### 触发关键词\n\n装好后 Agent 会在你说这些时自动唤起 Skill：\n\n- \"卡片\" \u002F \"副屏\" \u002F \"墨水屏\" \u002F \"桌面卡片\"\n- \"把 X 显示在卡片上\" \u002F \"show X on my card\"\n- \"刚拿到 M5Paper\" \u002F \"first-time setup\" \u002F \"刷固件\"\n- \"每 N 分钟刷新\" \u002F \"auto-refresh\"\n- \"卡片息屏\" \u002F \"显示名片\" \u002F \"睡眠\"\n- \"ai-desk-card\"\n\n## 使用流程\n\nSkill 是结构化工作流，Agent 会按下面顺序自动跑（你不用记每一步）：\n\n1. **入职 (flow 01)** — 探测 PlatformIO \u002F USB 设备 → 引导你烧固件\n2. **传输诊断 (flow 02)** — 设备连不上时定位问题\n3. **配 Wi-Fi (flow 03)** — 把 Wi-Fi 凭证写进设备 NVS\n4. **写偏好 (flow 04)** — 第一次问\"你想看哪些卡片，多久刷一次\"\n5. **推 widget (flow 05)** — 日常推送的热路径\n6. **设定时 (flow 06)** — Agent 用自己的 loop \u002F cron 定时刷\n7. **息屏 (flow 07)** — 推电子名片 + 设备深度休眠 0 功耗\n\n完整子流程在 [`flows\u002F`](.\u002Fflows\u002F) 目录。Skill 主路由在 [`SKILL.md`](.\u002FSKILL.md)。\n\n## 16 种 Widget\n\n**工作日常**：\n- `weather` 天气 · `calendar` 今日日程 · `next-meeting` 下个会\n- `todo` 待办 · `focus` 当前专注任务 · `deadlines` deadline 提醒\n- `inbox` 收件箱 · `messages` 消息 · `pr-queue` PR 队列\n- `git-status` git 状态 · `system` 系统状态 · `now-playing` 正在播放\n\n**笔记 \u002F 节奏**：\n- `scratch` 便签 · `break-reminder` 休息提醒\n\n**AI 监控**：\n- `ai-status` 当前 AI session · `ai-tasks` AI 任务列表\n\n**4 个槽位 \u002F 2-1-1 布局**：\n\n```\n┌────────────┬────────────┐\n│ top-left   │ top-right  │  ← 270×280 各占半\n├────────────┴────────────┤\n│         middle          │  ← 540×340 整条\n├─────────────────────────┤\n│         bottom          │  ← 540×280 整条\n├─────────────────────────┤\n│  bottom bar (chip 区)   │  ← 60 px，含\"睡眠\"\"设置\"chip\n└─────────────────────────┘\n```\n\n还有一个 `full`（540×960）覆盖全屏，用来推电子名片 \u002F 启动 splash 等。\n\n完整 schema 在 [`plugin\u002Fskills\u002Fcard-widget\u002Fschemas\u002F`](.\u002Fplugin\u002Fskills\u002Fcard-widget\u002Fschemas\u002F)。\n\n## 自动刷新（可选）\n\nSkill 第一次问你\"想看哪些卡片、什么时段刷\"时，会帮你写 `~\u002F.ai-desk-card\u002Finterests.yaml`：\n\n```yaml\nversion: 1\n\nslots:\n  top-left:  weather\n  top-right: calendar\n  middle:    todo\n  bottom:    inbox\n\nschedule:\n  cadence:  \"30m\"           # 5m \u002F 15m \u002F 30m \u002F 1h \u002F 2h\n  hours:    \"08-22\"\n  days:     \"mon-fri\"\n  timezone: \"Asia\u002FShanghai\"\n\ndata_sources:\n  weather:\n    city: \"Beijing\"\n  calendar:\n    source: \"macos\"          # 或 google \u002F ics-url\n  todo:\n    source: \"reminders\"      # 或 things3 \u002F todoist\n  git_status:\n    repo: \"\u002FUsers\u002Fyou\u002Fcode\u002Fmain-project\"\n\n# 到 quiet_hours.start 自动切到电子名片 + deep sleep\n# daemon 后台自动处理，不需要 Agent 在线\nquiet_hours:\n  enabled: true\n  start:   \"23:00\"\n  end:     \"07:00\"\n```\n\n定时触发方式：\n\n- **Agent 原生 loop（推荐）**：Claude Code 的 `\u002Floop 30m`、`ScheduleWakeup` 等\n- **cron**：`crontab -e` 加一行 `*\u002F30 8-21 * * 1-5 bash \u002Fpath\u002Fto\u002Fai-desk-card\u002Fplugin\u002Fskills\u002Fcard-refresh\u002Fscripts\u002Frefresh_loop.sh`\n- **纯 Python 无 AI 兜底**：weather \u002F system \u002F git 这几个不需要 AI，直接跑 `fallback_refresh.py`\n\n## 三种供电模式\n\n| 模式 | 状态 | 推帧延迟 | 续航 |\n|------|------|---------|------|\n| **A** 常插电 | USB-C 供电 + Wi-Fi 长开 | 0.2 s | n\u002Fa（供电中）|\n| **B** USB only | USB 数据线（还没配 Wi-Fi） | 1 s 区域 \u002F 32 s 全帧 | n\u002Fa（供电中）|\n| **C** 电池 + BLE 待机 | Wi-Fi 关，daemon 通过 BLE 唤醒 | 5 s 唤醒 + 0.2 s 推 | ~6 个月 |\n\n架构 C 是最爱：屏挂在桌边几个月不充电，AI Agent 推内容时 BLE 唤醒一次 → 拉 Wi-Fi → HTTP 推帧 → 30 秒 linger 后断 Wi-Fi。一次推送约 0.2 mAh，24 次\u002F天 × 6 个月 = 1150 mAh 电池。\n\n## 目录结构\n\n```\nai-desk-card\u002F\n├── SKILL.md                  ← 任意 Agent 的入口\n├── scripts\u002Fstate.sh          ← 状态探测：JSON 输出 daemon\u002Ftransport\u002Fwifi\u002Fdevice\u002Finterests 状态\n├── flows\u002F                    ← 7 个子流程（每个 ~60-100 行）\n│   ├── 01_install.md             零状态硬件 + 固件烧录\n│   ├── 02_transport.md           daemon 连不上设备的诊断\n│   ├── 03_wifi.md                Wi-Fi 配网\n│   ├── 04_interests.md           interests.yaml 引导写入\n│   ├── 05_push.md                推 widget 热路径\n│   ├── 06_schedule.md            定时刷新协议\n│   └── 07_sleep.md               电子名片 + deep sleep\n├── plugin\u002F                   ← Claude Code 兼容层（slash 命令 + 共享脚本）\n│   ├── plugin.json\n│   ├── commands\u002F             ← \u002Fcard-* 命令\n│   ├── scripts\u002F              ← start.sh \u002F stop.sh \u002F status.sh\n│   └── skills\u002F               ← 子 skill，由主 SKILL.md 间接调用\n├── daemon\u002F\n│   ├── card_daemon.py        ← HTTP 桥 + 传输层 + 后台 loop\n│   ├── card_render.py        ← widget view 渲染\n│   ├── card_render_settings.py\n│   └── card_render_sleep.py  ← 电子名片渲染\n├── src\u002F                      ← 固件 (frame_receiver \u002F wifi \u002F http \u002F ble \u002F 触屏 poll)\n├── assets\u002F\n│   ├── profile.yaml          ← 你的电子名片信息（息屏时显示）\n│   ├── qr.png                ← 可选 QR\n│   └── avatar.png            ← 可选头像\n├── data\u002Fcjk.ttf              ← CJK 字体（首次烧到 LittleFS）\n├── platformio.ini\n├── partitions.csv\n├── HANDOVER.md               ← 工程交接\n└── PRODUCT.md                ← 产品定位\n```\n\n## 工作原理（一图看懂）\n\n```\n你说话                                        M5Paper\n  │                                               ▲\n  ▼                                               │\nAI Agent ──────┐                                  │\n               │ 触发 Skill                        │\n               ▼                                  │\n          SKILL.md 路由表                          │\n               │                                  │\n               │  scripts\u002Fstate.sh 探测：          │\n               │  · pio \u002F firmware \u002F daemon       │\n               │  · device.alive \u002F wifi           │\n               │  · interests.yaml                │\n               │                                  │\n               └─▶ 选 7 个子 flow 之一             │\n                       │                          │\n                       ▼                          │\n                  Agent 自动执行                   │\n                       │                          │\n                       ▼                          │\n              POST 到 daemon (127.0.0.1:9877)     │\n                       │                          │\n                       ▼                          │\n              daemon 渲染（Python + Pillow）       │\n                       │                          │\n                       ▼                          │\n              HTTP \u002F USB \u002F BLE 推帧 ───────────────┘\n```\n\n## FAQ\n\n**Q: 真的不用我自己烧固件？**\n不用。装完 Skill 后跟 Agent 说\"帮我装卡片\"，Agent 会探测状态 → 装 PlatformIO（如果没装）→ `pio run -t upload` → 烧 CJK 字体 → 全程告诉你它在干什么。\n\n**Q: 我没有 M5Paper V1.1，别的硬件可以吗？**\nM5Paper V1.0 大概率能用。M5Paper S3 需要移植（BLE stack 不同）。Inkplate \u002F Waveshare 等其他 ESP32 + e-ink 板还没支持，roadmap 上有。\n\n**Q: 必须用 Claude Code 吗？**\n不必。`SKILL.md` 是 agent-agnostic 入口，任何识别这格式 + 有 shell 权限的 Agent 都能用（Codex \u002F Cursor \u002F Aider \u002F 自写 Agent）。`plugin\u002F` 里的 slash 命令是 Claude Code 用户的便利层，不是核心。\n\n**Q: 网络情况？**\n全本地。daemon 在你电脑上跑 (127.0.0.1:9877)，设备和电脑同 Wi-Fi LAN 直连。**ESP32 只支持 2.4 GHz**，5 GHz only 的 SSID 连不上。\n\n**Q: 中文显示豆腐块？**\n漏了烧 LittleFS 字体。跟 Agent 说\"再跑一次 uploadfs\"就好。\n\n**Q: 怎么更新固件？**\n跟 Agent 说\"帮我更新 ai-desk-card 然后重新烧一次\"。Skill 会拉新代码 + build + upload。\n\n**Q: 不在 macOS 上能用吗？**\ndaemon 在 Linux 也应该能跑（未深度测试）。Windows 需要 WSL2。烧固件部分 PlatformIO 跨平台。\n\n**Q: 数据会上云吗？**\n不会。daemon 默认绑 127.0.0.1（除了 device→daemon 的 status_report 走 LAN）。Wi-Fi 凭证写在设备 NVS，不会进 daemon 日志、不会进 git。\n\n## Roadmap\n\n- M5Paper V1.0 \u002F S3 移植验证\n- Inkplate \u002F Waveshare 等其他 e-ink 板支持\n- Captive portal Wi-Fi 配网（不用通过 daemon）\n- 硬件按钮长按 2s 关机时拦截 → 先推名片再 deep_sleep（Plan C）\n- 更多 widget schema（feishu \u002F 微信 \u002F Linear \u002F Notion）\n- 多设备 dashboard 同步\n\n## 贡献\n\n欢迎 Issue 和 PR：https:\u002F\u002Fgithub.com\u002Fop7418\u002Fai-desk-card\n\n最有价值的贡献：\n\n- 硬件实拍照 \u002F 视频（帮新用户看清产品形态）\n- Linux \u002F Windows 上 daemon 测试报告\n- M5Paper V1.0 \u002F S3 移植验证\n- 新 widget schema + 渲染器\n- 翻译 \u002F 文档优化\n\n## License\n\nGPL-3.0 with attribution clause · 见 [LICENSE](.\u002FLICENSE)\n\n内嵌 EPDGUI 框架（来自上游 M5Paper_FactoryTest）：MIT，© 2020 m5stack\n","AI Desk Card 是一个桌面副屏项目，通过 M5Paper 墨水屏和 AI Agent 推送各种 widget 信息。其核心功能包括自动引导烧固件、配置 Wi-Fi 和推送内容，支持多种 widget 如天气、日程、todo 等，并且本地运行无云依赖。该项目使用 Python 开发，具有服务端渲染能力，可以轻松添加新 widget。适用于希望拥有 always-on 桌面副屏但不想增加额外显示器的用户，特别是已经使用 Claude Code 或 Codex 等 AI Agent 的人群。此外，墨水屏低疲劳感的特点也使其成为长时间工作时的理想选择。不过，对于需要快速刷新内容或复杂触屏交互的应用场景，该项目可能不太适合。","2026-06-11 03:58:39","CREATED_QUERY"]