把 Kindle Paperwhite 3 变成 Codex / Claude Code 的桌面额度屏。服务器通过 CodexBar CLI 获取额度，生成中文灰度图片；Kindle 定时联网下载，用 FBInk 显示，然后进入 RTC 待机。
上图使用合成数据。界面显示独立额度窗口的剩余比例、固定重置时间、各 Provider 右上角黑色显示的数据更新时间和异常状态。图片不显示实时钟或冻结的倒计时，适合墨水屏停留展示。
| 部分 | 必须准备的环境 |
|---|---|
| Kindle | 已自行完成 Jailbreak，可通过 Scriptlets 运行 documents/*.sh，已安装支持 PNG 的 FBInk |
| 已适配设备 | Paperwhite 3（PW3），竖屏 1072 × 1448；其他型号需要修改渲染、PNG 校验及电源适配并重新验收 |
| 采集宿主机 | 已安装 CodexBar CLI；Codex 通过它的 OAuth 来源取得额度，Claude 通过本机已登录的 Claude Code（claude 在 PATH 中）取得额度 |
| Python | Python 3.12 为已测试版本；本地预览/测试需安装 requirements.txt 中的 Pillow 和中文字体 |
| 图片服务 | Docker Engine/Desktop 与 Docker Compose；容器只运行本项目的图片/HTTP 服务，不安装 CodexBar、不挂载账户凭据 |
| 网络 | Kindle 与服务器在可互访的局域网；访客 Wi-Fi、AP 隔离、宿主机休眠或 Docker 未运行会影响刷新 |
本项目不负责 Jailbreak、Hotfix、Scriptlets、FBInk 或账户登录的安装。请按 KindleModding 的设备/固件说明自行准备；Scriptlets 入口规范见文档，FBInk 见上游项目。
CodexBar CLI 的安装方式见官方 CLI 文档。只安装菜单栏 App 不代表命令已在 PATH 中，请确认 codexbar --version 可运行。本项目对 Codex 显式使用 --source oauth，对 Claude 显式使用 --source cli（由已登录的 Claude Code 自己完成认证；Claude Code 2.1.x 只把凭据放在钥匙串，CodexBar 默认不再读取，所以 Claude 的 OAuth 来源不可用）；CodexBar 的其他数据源和 Provider 并不会自动被本项目支持。
完整部署路径目前以 macOS + launchd + PW3 为基线。Linux 可运行 Python/Docker 部分，但定时采集、CodexBar OAuth 和设备部署需要自行适配并验证；Windows 原生采集未适配。
- Codex 和 Claude Code 各一个当前默认账户，每源最多三个真实额度窗口。
- 独立处理采集失败：保留该源上次成功数据；首次无数据时显示“暂无额度数据”，不需要停用开关。
- 默认每 300 秒采集一次 Codex、每 900 秒采集一次 Claude（每次会启动 Claude Code 进程）；Kindle 成功后待机 180 秒，连续失败按刷新间隔（至少3分钟）递增，上限15分钟，实际帧间隔还包含联网/下载时间。
- 默认每 1800 秒在下一次成功绘图时执行全屏刷新。
- 记住每个常用网络里找到过的服务器地址，后台把这些已知地址一起探测，换回去过的网络能直接连上；到了新网络或 DHCP 换了 IP，点“重找额度服务器”：进度和结果直接显示在屏幕上，仅手动扫描实际私有
/22至/30，找到后记入列表并自动恢复循环。 - 退出后恢复启动时的 Wi-Fi/屏保状态，下载失败时保留旧画面。
- 休眠期间按电源键（或插USB等提前唤醒）即停止循环并恢复原 Wi-Fi/屏保状态，设备可以正常使用；要继续显示额度时再点“开启Agent额度”。也可随时点“停止 Agent 额度”。
休眠期间无线保持开启，由系统驱动自行处理挂起，唤醒后等待重新联网；脚本不再每轮开关无线（早期版本每轮关闭再开启，曾两次把无线模块卡到必须重启）。只有启动前无线本来是关着的，才会在启动时打开、停止时关回去。耗电影响尚未实测，详见电源与网络行为。
下载或 clone 本仓库后，在项目根目录执行。以下先准备宿主机与服务，Kindle 写入步骤见后面的手顺。
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
codexbar --versionmacOS 本地渲染可使用系统中文字体；Linux 本地测试需安装 fonts-noto-cjk 或配置 QUOTA_FONT / QUOTA_FONT_BOLD。Dockerfile 已安装 Noto CJK，Kindle 无需安装中文字体。
mkdir -p runtime
python -m quota_display.collector --cli "$(command -v codexbar)"标准结果写入 runtime/quota.json，终端只显示各源状态。任何源失败时退出码为 1，但仍写入另一源的成功数据或旧缓存；例如 Claude 尚无额度不阻塞 Codex 图片显示。认证问题应在 CodexBar/对应 Provider 的登录环境解决。
不要把原始 CodexBar JSON、token、cookie 或账户配置复制到本项目。config/providers.json 是无个人信息的公共默认配置；个人间隔/超时配置可放入忽略的 config/providers.local.json 并用 --config 指定。
[ -f .env ] || cp .env.example .env
docker compose up -d --build
curl --fail http://127.0.0.1:8486/healthz浏览 http://127.0.0.1:8486/frame/kindle1.png。默认仅发布到本机；Kindle 使用前，在 .env 设置 QUOTA_BIND_ADDRESS 为当前 LAN IPv4，或在可信局域网设置为 0.0.0.0，再执行 docker compose up -d。
该服务没有 HTTP 认证，可达设备能读取额度图片、标准额度数据及固定设备诊断状态。SERVER_ID 用于发现时核对实例，不是密码；不应直接向公网发布。
将示例 IP 和主机名替换为自己的服务器值；下面命令只生成本地文件，不写 USB。
python scripts/prepare.py kindle \
--server 192.168.1.50 \
--host quota-host.local \
--output build/kindle-install核对包内 server.conf 的 FBInk 路径，默认 /mnt/us/libkh/bin/fbink。备份、USB 安装、安全推出和首次启动按安装手顺执行。点击“开启Agent额度”会真实自检并启用 RTC 省电循环；请先确认设备的 RTC/休眠能力。
点击入口优先显示最近一次成功刷新的 PNG 缓存，遮住 Library，再联网自检并获取新图；没有有效缓存时显示固定的“正在刷新quota信息”占位图。已有任务时只恢复画面，不重复启动。缓存位于设备 /tmp，正常停止保留，设备重启后可能清除；安装快照不会作为占位图使用。
Kindle 上四个日常入口是 开启Agent额度 / 刷新 Agent 额度 / 重找额度服务器 / 停止 Agent 额度。包内另有临时恢复自检入口，详细职责见脚本说明。
macOS 可使用 scripts/prepare.py launchd 生成使用绝对 Python/CLI 路径的 plist，默认 StartInterval=300。生成、安装、停止和回滚步骤见手顺。宿主机睡眠期间不保证采集或 HTTP 可用。
sh scripts/offline-check.sh离线检查只使用合成 fixture 和模拟 HTTP/LIPC/RTC/FBInk，不调用 CodexBar，不启动 Docker，不操作 Kindle。预览输出到 docs/assets/，测试生成物输出到忽略的 build/。
二开请先读 DEV.md；交给 Agent 时可直接使用其中的 handoff 提示词。仓库级约束见 AGENTS.md，贡献说明见 CONTRIBUTING.md。
| 文档 | 内容 |
|---|---|
| 技术设计 | 模块、数据流、失败与恢复边界 |
| 行为 Spec | 数据契约、接口、配置与不变量 |
| 离线省电改进提案 | 已实现：统一3–15分钟退避、已知地址探测、手动发现及RTC剩余等待 |
| 安装手顺 | 采集、Docker、launchd、USB、验证和回滚 |
| 脚本说明 | 五个入口、四个内部脚本、配置与日志 |
| 验证说明 / 验收模板 | 离线与真机验证边界 |
| 发布说明 | 个人文件忽略规则与 GitHub 发布检查 |
| 来源与致谢 | 外部依赖、版本参考和设计来源 |
quota_display/ 标准化、采集、渲染、HTTP 服务
kindle/ POSIX 客户端、配置模板、Scriptlet 入口
config/ 无个人信息的采集默认配置
collector/ 宿主机采集 shell 入口
scripts/ 离线检查、部署包/plist 生成、安装与观察工具
tests/ 合成 fixtures 与自动测试
docs/ 通用文档、Schema、合成预览
.env、runtime/、build/ 和 docs/local/ 为忽略的本地状态，包含个人配置、真实额度、日志、设备备份或安装包，不属于公开源码。
Apache License 2.0。依赖和参考项目保留各自许可。本项目自行构建 Docker 镜像，remote-eink-dashboard 仅为设计参考，没有将其服务或预构建镜像作为运行依赖。