eink-push/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目定位

eink-push 是 JM monorepo 中一个独立的 Python 工具，与其余 Java/Vue 子项目技术栈无关，不受父级 CLAUDE.md 的 jm-cloud/uniapp/admin 开发约束。

作用：把日期天气、Claude Code 用量、橘喵今日经营合成为一张 400×300 三色（黑/白/红，BWR） PNG，推送到局域网墨水屏设备（喵喵固件，开源：https://gitee.com/gxp666111/miaomiao）。纯 Python + Pillow，无浏览器依赖，适合 cron 定时运行。

分支 feature/colorful：新设备在黑白外支持红色，本分支把渲染升级为黑/白/红三色。当前版式为上中下三段：A 大时钟+日期 / 天气（定位南京·江宁）；B Claude Usage 主角（5h/7d 用量进度条 + 时间维度对比 pace，用量吃紧转红预警）；C 橘喵今日实时三列。红作语义强调（用量预警、涨、定位、天气太阳/闪电），仍无真灰阶、不抖动，全图只三种纯色。近30天趋势图当前隐藏（renderer._trend_chart 及依赖保留、未调用，随时可挂回）。

命令

pip install -r requirements.txt        # 仅 Pillow>=10.0；urllib 用标准库
cp .env.example .env                   # 首次：复制模板并填入真实凭证 + 设备 host
python3 main.py                        # 取数据 → 渲染 → 推送（设备 host 取自 .env 的 EPD_HOST）
python3 main.py --render-only          # 只渲染到 output/dashboard.png，不推送（本地调试渲染时用这个）

sh run.sh                              # cron 包装脚本：cd 项目目录 + vfox python 绝对路径 + 追加日志到 output/cron.log

# 临时覆盖：真实环境变量优先级高于 .env
EPD_HOST=epd400a44.local python3 main.py

无测试、无 lint。调试渲染效果就跑 --render-only 看 output/dashboard.png。

配置统一走 .env：所有凭证/参数放同目录 .env（已在 .gitignore，本机专用；模板见已提交的 .env.example）。config.py 顶部用零依赖加载器 _load_dotenv() 把 .env 写入 os.environ，再由各 os.environ.get(...) 读取；采用 setdefault，故真实环境变量（cron/命令行注入）优先级高于 .env。config.py 内不再保留任何明文凭证（fallback 为空串）。可配置项：EPD_HOST（局域网设备 mDNS host，默认 epd400a44.local）、JM_BASE_API/JM_CLIENT_ID/JM_CLIENT_SECRET/JM_GRANT_TYPE/JM_TENANT_ID、QWEATHER_HOST/QWEATHER_KEY/WEATHER_LOCATION(默认南京·江宁)/WEATHER_TTL、USAGE_LOCAL_PATH/USAGE_WARN。

定时部署：由 macOS launchd LaunchAgent 触发 run.sh（不再用 cron——cron 在现代 macOS 上易被 TCC/权限静默拦截，launchd 是系统原生调度器）。LaunchAgent plist 装在 ~/Library/LaunchAgents/com.jm.eink-push.plist（机器专用，未入库，等价于 run.sh/.env 的本机产物），StartInterval=300 + RunAtLoad=true：登录/重启后立即跑一次，此后每 5 分钟一次。用 LaunchAgent（非 LaunchDaemon）是因为脚本依赖当前用户目录下的文件（~/.claude/usage-snapshot.json、.env），必须在用户会话下运行——机器需已登录（或开了自动登录）才能保证开机即触发。run.sh 内部逻辑不变：cron 不继承登录环境，故脚本内 python 写死 vfox 绝对路径、并 cd 到项目目录后追加日志到 output/cron.log（cd 后 config.py 才能就近找到 .env）；launchd 自身的 stdout/stderr 另落 output/launchd.log（正常应为空，非空说明进程本身起不来，而非业务报错）。常用排查：launchctl list | grep com.jm.eink-push 看是否常驻及最近退出码，launchctl kickstart -k gui/$(id -u)/com.jm.eink-push 手动立即触发一次；改 plist 后需 launchctl bootout + bootstrap 重新加载才生效（热改文件不会自动生效）。每 5 分钟触发：业务数据每次都刷新，天气靠缓存、用量读本地文件，避免高频打接口（见 data.py）。

架构（数据 → 渲染 → 推送 三层）

main.py 串联三层，各层职责单一、低耦合：

• data.py — 唯一数据入口 get_dashboard_data()，返回固定结构的 dict：date/weather/mao/usage。日期时间用真实系统时间；橘喵今日经营由 _mao() 经 jm_api、天气由 _weather() 经 weather_api（和风，定位南京·江宁）、Claude 用量由 _usage() 经 usage_local，任何异常都回退占位 "--"，不回退 mock。改数据保持返回结构不变即可（renderer 依赖其 key：weather.icon 为和风图标代码；mao.cols[].hb/tb 为环比/同比 (direction, text)，direction 为 None 时不画三角；usage.bars[] 为 {k, pct(或 None), time_pct?}、usage.warn 为转红阈值）。注：_mao 仍会拉 mao.trend，但趋势图当前隐藏、renderer 不使用它。
  • 缓存（为 launchd 每 5 分钟独立进程而设，必须落盘）：天气 .weather_cache.json（TTL=WEATHER_TTL，默认 15min）、趋势 .trend_cache.json（按日期 key，每天只拉一次）；两者拉取失败沿用旧缓存。用量不自建缓存——直接读 statusline 生产的本地快照 ~/.claude/usage-snapshot.json（见 usage_local），失败即 "--"。两个缓存文件已在 .gitignore。
  • 用量的 pace（时间维度对比）：_usage() 每次按当前时间现算 time_pct=(窗口已流逝/窗口长)、pace=pct−time_pct（>0 超前↑ / <0 节余↓）；故即使 utilization 来自可能滞后的本地缓存，pace 仍随时钟准确推进。5h 窗口 18000s、7d 窗口 604800s。
• jm_api.py — jm-devops 后端统计接口客户端，设备密钥授权（grant_type=client_secret，免验证码）。先用 CLIENT_ID + CLIENT_SECRET 调 POST /auth/login 换 token（进程内缓存、按 expire_in 提前刷新），再带 Authorization: Bearer <token> + clientid 头调 /system/statistics/{realtime,recent-days}；遇 401 清 token 重登一次重试。token 字段为蛇形 access_token/expire_in。注：历史上曾免鉴权直调、更早曾用账号密码+验证码 OCR 登录（ddddocr 不稳定），现统一为 client_secret 授权——密钥即长期凭证，务必走 HTTPS、优先用 JM_CLIENT_SECRET 环境变量、可在后端 sys_client 轮换。
• weather_api.py — 和风天气（QWeather）客户端。用用户专属 API Host（QWEATHER_HOST）+ X-QW-Api-Key 头鉴权；响应 gzip 压缩（按 magic number 手动解压）、返回 code 为字符串。get_now() 取实时（now.text 中文天气 / now.temp / now.icon 图标代码），get_today() 取 /3d 的 daily[0] 今日温区。QWEATHER_HOST/QWEATHER_KEY 未配置时直接抛错→天气区显示 "--"。
• usage_local.py — Claude Code 用量本地读取，不发任何网络请求（生产者/消费者模式）：只读 config.USAGE_LOCAL_PATH（默认 ~/.claude/usage-snapshot.json）。生产者 = 打过补丁的 claude-statusline：其 bin/statusline.sh 把每次 Claude Code 经 stdin 喂来的权威实时额度落盘为该快照（schema 同 /api/oauth/usage：five_hour/seven_day 的 utilization + resets_at）；本模块作消费者读取。活跃使用时快照几乎持续刷新、准确；空闲时停在最后一次。文件缺失/损坏→用量区 "--"。注：resets_at 可能是 epoch 数字（Claude Code stdin 给的就是 epoch）或 ISO 串，data._parse_reset_ts 两者兼容。（曾评估直调 /api/oauth/usage，改为读本地快照以免网络请求。）
• renderer.py — DashboardRenderer.render(data) 返回 PIL 'RGB' 模式、仅黑/白/红三色图；render_to_file() 落盘。布局硬编码为上中下三段，两道 hdash 横规分隔（y=90 / 200）：
  • A 顶部（0–90）：大时钟(F48)+日期（左）/ 天气（右：红定位水滴 + 温度 + 天气·温区 + 全矢量图标）。
  • B 中部主角 Claude Usage（_label 标题 + 两条 _usage_row）：每条单行 = 左标签 5h/7d(F13) + 粗进度条 + 百分比(F16) + 时间维度对比 pace(F13，_pace)；pct≥warn→该条进度条(含边框)与百分比转红预警；pace 用上/下三角替代 +/−（超前↑ / 节余↓）。整行「标签·进度条·百分比·三角」用 _mid() 按墨迹竖直中心对齐到同一中线。
  • C 底部 橘喵今日实时（_label + 三列，版式对齐主分支）：■ 橘喵·今日实时 + 上次更新，列内 名(F12)/值(F24 粗)/环比·同比(_cmp_line)，相对标题偏移 +18/+34/+64/+82，底部留 ~11px 下边距。
  • 红色点缀系统（改配色务必克制）：模块顶部 BLACK/WHITE/RED，RED=(255,0,0) 是给设备红通道的明确信号。红只用在：① 定位水滴（_loc_pin(fg=RED)）② 天气太阳/闪电（_weather_icon(accent=RED)，云/雨/雪/雾/月仍黑）③ 用量进度条与百分比(pct≥warn) + pace 超前(↑) ④ 环比/同比「涨」的三角与数值（_cmp_line，跌/标签仍黑）。配色铁律：红与黑同属深色、红叠黑对比极低，故红只压白底或作大块实心（白字压红），绝不红字压黑底。加红先问「是否承载语义」。
  • _trend_chart（当前隐藏）：近30天三指标折线，用 _styled_polyline() 按 solid/dashed/dotted 区分、主指标(流水)红线，各指标按自身极值独立归一化。已保留但 render() 未调用，想恢复即在 C 前挂回。
  • 天气图标全矢量手绘（无图片资源）：_weather_category() 把和风 icon 代码归并为 8 类（sunny/clear_night/cloudy/overcast/thunder/rain/snow/fog，识别不了回退 cloudy），再由 _weather_icon() 用 _sun/_cloud 等基元按 1bit 描边画出；改天气展示从这里动。
• pusher.py — 直连局域网墨水屏设备（喵喵固件，开源：https://gitee.com/gxp666111/miaomiao，web/ 即设备自带管理页，可浏览器打开 http://<EPD_HOST>/ 调试同一套接口）。push_image() 先调 GET /images 拿画廊已存图片名单，逐个 POST /delete_image?name=清空（单张删除失败不阻塞后续），再 POST /upload（Content-Type: image/png，body 为原始 PNG 字节，非 multipart）触发设备转换+刷屏。清空画廊是刻意设计：设备把每次 /upload 都追加存一份到画廊（GET /images 可见），不清理会越推越多、且设备当前 current_mode 为 slideshow 会轮播到旧图；先清后传使画廊恒为 1 张，等价于始终静态展示最新一张。清理非核心：拉取画廊列表本身失败也不阻塞后续 /upload（跳过清理，直接推）。_request() 对连接类异常（urllib.error.URLError，含 mDNS .local 域名解析瞬时失败）内置重试（RETRY_TIMES=2，间隔 RETRY_DELAY=2s）——mDNS 基于组播 UDP，偶发丢包很正常，单次失败不该让整轮推送直接跳过。注：历史上曾走 Zectrix 公网 API（POST /devices/{id}/display/image + 设备 MAC + ZECTRIX_API_KEY），现统一为局域网直连。
• config.py — 顶部 _load_dotenv() 先加载同目录 .env，再定义 API、设备、画布尺寸、字体路径、推送参数；凭证 fallback 为空串，真实值来自 .env/环境变量。

墨水屏渲染约束（改 renderer.py 必读）

设备是 三色（黑/白/红）、无真灰阶——灰阶只能抖动成网点（难看），所以底色只用黑白 + 红作稀缺强调，靠构图/字号/留白建立层级，不要引入灰色填充或抖动：

• 红只作语义强调：方向（涨）、警示（闪电）、强调（定位/主折线）；红占墨保持很小（<10% 墨迹），滥用会稀释注意力、破坏层级。整图只允许三种纯色 (0,0,0)/(255,255,255)/(255,0,0)——渲染后可用 img.getcolors() 自查，出现第四种色（多为抗锯齿灰边）即为 bug。矢量图元(line/ellipse/polygon/arc)默认不抗锯齿故为纯色；文字靠 fontmode="1" 保持纯色。

• 字体固定用 Fusion Pixel 12px 点阵字体（fonts/，OFL 协议），首选整数倍尺寸 12/24/48（F12/F24/F48）最锐利；用量区为拿到合适的字号层级另用了 F13/F16（1.08x/1.33x 非整数倍，笔画略不均，属有意取舍），靠 d.fontmode = "1" 关抗锯齿仍保持纯色不糊。跨字号竖直居中统一用 _mid()（按 getbbox 墨迹中心对齐）。

• 加粗用「伪粗体」：_draw() 按 1~bold px 水平偏移叠绘笔画（点阵字体只有单一字重）。

• 推送时 DITHER = False（硬阈值），纯黑白图最锐利，勿改成 true。

• 坐标、字号均为像素网格上的硬编码常量；调布局时注意各区分隔线 hdash 的 y 值与下方组件位置联动。

注意

• 所有凭证均在 .env（不提交）；config.py 不再内置明文 fallback。分享代码时给出 .env.example 即可，真实 .env 切勿入库。
• .gitignore 已忽略：output/、__pycache__/、*.pyc、两个缓存文件 .weather_cache.json/.trend_cache.json、本机专用的 run.sh、含凭证的 .env（模板 .env.example 入库）。改缓存逻辑后想强制重拉，删掉对应缓存文件即可。