MaximeRivest/Riddle

来源：https://github.com/MaximeRivest/Riddle

riddle —— 汤姆·里德尔的日记，专为 reMarkable Paper Pro 设计

用笔在页面上书写。暂停片刻后，日记会 喝掉你的墨水 —— 你的字迹渐渐融入纸中 —— 页面思考片刻，然后一句回答以流畅的手写体一笔一画地浮现，再缓缓消失。没有屏幕发光、没有键盘、没有聊天界面。只有墨水在纸上显现。

这就是来自演示视频（https://x.com/MaximeRivest）的日记。

🪄 新手从这里开始

你需要一台 reMarkable Paper Pro，并已开启开发者模式且安装启动器。如果觉得步骤繁琐，其实不然 —— remagic (https://github.com/maximerivest/remagic) 会引导你开启开发者模式，并通过一条命令完成所有设置。回到这里，放入 riddle，然后开始给汤姆写信。

如果你已经安装了 xovi + AppLoad？可以从 remagic (https://github.com/maximerivest/remagic) 目录安装、获取预编译包，或者从源码构建。

通过 remagic 安装（最简便）

remagic install riddle # 校验和验证下载 → AppLoad
remagic config riddle   # 浏览器中的设置表单（+ 手机二维码）

然后在 AppLoad 中：点击 Reload，然后点击 The Diary。书写，然后停笔。（也可以直接在平板的 Store 应用中安装。）

安装预编译包

1. 从最新发布版 (https://github.com/MaximeRivest/riddle/releases/latest) 下载 riddle-<版本>.zip，解压到文件夹：
   unzip riddle-*.zip -d riddle
2. 将文件夹复制到平板：
   scp -O -r riddle [email protected]:/home/root/xovi/exthome/appload/
3. 添加 API 密钥：在该文件夹中执行 cp oracle.env.example oracle.env，并将你的 RIDDLE_OPENAI_KEY 填入其中（任何兼容 OpenAI 的密钥）。或者跳过此步骤以使用 pi。
4. 在 AppLoad 中：点击 Reload，然后点击 The Diary。书写，然后停笔。

⚠️ 此操作会修改你的设备。 它将以 root 身份运行，停止供应商 UI（在接管模式下），并直接驱动电子墨水引擎。仅已在 reMarkable Paper Pro（ferrari，aarch64，OS 3.26–3.27）上测试。可能不适用于其他型号或操作系统版本，使用风险自负。与 reMarkable AS 无关。在安装任何内容之前，请确保 SSH 访问正常工作 —— 那是你的逃生舱。

工作原理

笔（原始 evdev，完整 4096 级压力，硬件事件率）
│
笔画
▼
riddle ── 空闲 2.8 秒 → 提交页面 → PNG ──► oracle（常驻 LLM 进程，
│                                           逐句流式回复）
▼
笔画（Dancing Script → 骨架化为单像素笔迹路径）
显示后端
├── qtfb — 窗口模式，在 xochitl 内（AppLoad 应用）
└── quill — 完全接管：停止 xochitl，直接驱动供应商电子墨水引擎，实现即时墨水（最低延迟）

• riddle/ — 应用（Rust）。笔输入、墨水表面、手写合成（栅格化 → Zhang-Suen 细化 → 笔画跟踪 → 动画回放）、oracle 进程管理器以及两个显示后端。
• quill/ — 接管显示宿主（C/C++）。一个基于 epfb-re (https://github.com/asivery/epfb-re) 风格的 QImage 构造函数拦截垫片，位于供应商 libqsgepaper.so 波形引擎之上，暴露为一个小型 C ABI（quill_init / quill_buffer / quill_swap），riddle 通过 --features takeover 链接。还附带一组小型演示（scribble 笔触到玻璃延迟测试，以及地图、图片和 GIF 渲染器）。

手势

神谕（日记中的“灵魂”）

日记的回复来自一个视觉 LLM，它读取你提交页面上的手写内容（以内联 PNG 形式发送）。有 两个后端，在启动时选择 —— 根据你的情况选择其一：

选项 A — 任何兼容 OpenAI 的 API（最简单，零设置）

设置 API 密钥后，riddle 直接与兼容 OpenAI 的 /chat/completions 端点通信。适用于 OpenAI、OpenRouter、Groq、本地服务器 —— 任何支持该格式的服务。平板上无需额外软件。

export RIDDLE_OPENAI_KEY="sk-..."                      # 必需
export RIDDLE_OPENAI_BASE="https://api.openai.com/v1"  # 可选（默认）
export RIDDLE_OPENAI_MODEL="gpt-4o-mini"               # 可选；模型必须支持图像
export RIDDLE_OPENAI_REASONING="low"                   # 仅限思考模型
export RIDDLE_OPENAI_MAX_TOKENS="2000"                 # 防止回复过长

任何支持视觉的模型都适用。在平板上，这些变量位于二进制文件旁边的 oracle.env 中（参见 oracle.env.example，或直接运行 remagic config riddle —— 它提供一键预设给 OpenAI、OpenRouter 和 Gemini）。

使用 OpenRouter 的示例：

export RIDDLE_OPENAI_KEY="$OPENROUTER_API_KEY"
export RIDDLE_OPENAI_BASE="https://openrouter.ai/api/v1"
export RIDDLE_OPENAI_MODEL="openai/gpt-4o-mini"

与思考模型（Gemini 3.x、o 系列）相关的两个注意事项：设置 RIDDLE_OPENAI_REASONING=low 以获得更快的首次墨水显现（某些提供商会拒绝非思考模型上的该字段 —— 在此情况下请勿设置）；确保 RIDDLE_OPENAI_MAX_TOKENS 足够大 —— 隐藏的思考 token 也会计入，过小的上限会限制可见回复。

启动日记前验证你的设置：

riddle --oracle-test path/to/handwriting.png   # 打印流式回复

实测在设备上首次墨水显现约需 0.9–1.1 秒。HTTPS 内置于 riddle 中（纯 Rust，无需额外库）。

选项 B — pi（更强大路径）

如果你已经在运行 pi (https://github.com/badlogic/pi-mono)，riddle 将使用常驻的 pi --mode rpc 进程（Node + 订阅身份验证已加载一次），因此每次交互仅需支付模型延迟。当 未设置 RIDDLE_OPENAI_KEY 时自动使用。

两者都逐句流式回复，因此 quill 会在模型完成前几秒就开始书写。人物提示词位于 riddle/src/oracle.rs。

构建

从 x86_64 交叉编译。两种版本：

窗口模式（AppLoad/qtfb）—— 最简便

需要设备上安装 xovi + AppLoad (https://github.com/asivery/rm-appload)。

cd riddle
cargo build --release --target aarch64-unknown-linux-gnu

将二进制文件、external.manifest.json、appload-launch.sh 一起安装到 /home/root/xovi/exthome/appload/riddle/。

接管模式（即时墨水）—— 演示中的版本

需要 reMarkable SDK 工具链（~/rm-sdk-3.26），因为链接的供应商 Qt 库需要其 glibc，以及从 你自己的设备 中提取的 libqsgepaper.so（它是专有代码，未在此分发）：

cd quill && ./build.sh            # 通过 SSH 从设备提取 libqsgepaper.so，
                                  # 构建 libquill.so + 演示
cd ../riddle && ./build-takeover.sh
./scripts/make-bundle.sh          # 将 AppLoad 包暂存到 dist/riddle/

暂存的 dist/riddle/ 是自包含的（二进制、libquill.so、启动脚本、清单）—— 将其复制到 /home/root/xovi/exthome/appload/riddle/，或通过 remagic publish dist/riddle 发布到目录。通过 AppLoad（appload-launch.sh）启动会分离到一个临时 systemd 单元，停止 xochitl，运行日记，并在退出时 始终恢复 xochitl —— 通过电源按钮、五指点击或 SIGTERM 退出。如果卡住：ssh [email protected] 'systemctl start xochitl'。

字体

回复手写体使用 Dancing Script (https://github.com/googlefonts/DancingScript)（SIL OFL 1.1 — 参见 riddle/fonts/OFL.txt）。

许可证

本仓库中所有内容均采用 MIT 许可证（参见 LICENSE）。它所拦截的供应商库（libqsgepaper.so、Qt）不包含在内，必须从你自己的设备/SDK 获取。