在电子墨水设备上实现手写输入与 AI 实时交互听起来像是科幻电影里的场景但 Maxime Rivest 开源的 Riddle 项目确实将 reMarkable Paper Pro 变成了现实版的“汤姆·里德尔日记”。这个项目不是简单的聊天界面移植而是通过 Rust C/C 混合技术栈结合视觉大模型和硬件级墨水动画创造出了完全不同的交互体验。实际部署 Riddle 需要跨越几个技术门槛reMarkable 开发者模式激活、交叉编译环境搭建、视觉 API 集成、以及最关键的墨水渲染优化。本文将基于官方仓库和实际部署经验从环境准备到故障排查完整走通整个流程重点解释为什么某些步骤必须按特定顺序执行以及如何避免常见的设备变砖风险。1. 理解 Riddle 的架构设计为什么选择混合技术栈Riddle 的核心目标是在低功耗电子墨水屏上实现“墨水消失-AI思考-手写回复”的魔法效果。这要求系统必须同时处理硬件事件捕获、AI推理延迟隐藏和墨水动画流畅性三大挑战。单纯用高级语言或单一技术栈很难兼顾性能与开发效率因此项目采用了分层架构。1.1 输入层为什么直接使用 evdev 而不是标准输入库reMarkable 的电磁笔输入通过 Linux 内核的 evdev 接口暴露Riddle 的 Rust 部分直接监听/dev/input/event*设备文件。这种看似原始的方式其实有重要考量标准输入库如 libinput 会引入额外抽象层增加 10-20ms 延迟。对于需要精确捕捉笔触起落和压力变化的场景直接读 evdev 可以获取原始 4096 级压力数据。关键代码结构如下// riddle/src/pen.rs pub struct Pen { device: File, current_strokes: VecStroke, } impl Pen { pub fn new(device_path: str) - ResultSelf { let device OpenOptions::new() .read(true) .write(false) .open(device_path)?; Ok(Pen { device, current_strokes: Vec::new() }) } pub fn poll_events(mut self) - ResultVecPenEvent { let mut events Vec::new(); let mut buffer [0u8; size_of::input_event() * 64]; // 非阻塞读取避免主循环卡死 match self.device.read(mut buffer) { Ok(bytes_read) { for chunk in buffer.chunks_exact(size_of::input_event()) { let event: input_event unsafe { std::ptr::read(chunk.as_ptr() as *const input_event) }; // 处理 EV_KEY, EV_ABS 等事件类型 events.push(self.process_event(event)); } } Err(e) if e.kind() ErrorKind::WouldBlock {} Err(e) return Err(e.into()), } Ok(events) } }这种底层读取方式虽然高效但也带来了兼容性风险不同 reMarkable 固件版本的 event 设备路径可能变化需要在实际设备上确认/dev/input/event0到event3中哪个对应电磁笔。1.2 渲染层为什么需要 C/C 接管电子墨水驱动电子墨水屏的刷新原理与 LCD 完全不同它不是简单像素切换而是需要根据内容变化程度选择不同的波形模式。reMarkable 使用的 E Ink Carta 屏幕支持局部刷新和全局刷新但官方 xochitl 应用并不暴露细粒度控制接口。这就是 quill 子项目C/C存在的价值它直接链接设备厂商的libqsgepaper.so库通过逆向工程的 ABI 接口控制墨水刷新// quill/src/quill.c typedef int (*quill_init_fn)(void); typedef int (*quill_buffer_fn)(void* buffer, int width, int height); typedef int (*quill_swap_fn)(int mode, int x, int y, int w, int h); quill_init_fn quill_init; quill_buffer_fn quill_buffer; quill_swap_fn quill_swap; void load_vendor_libs() { void* handle dlopen(libqsgepaper.so, RTLD_LAZY); quill_init (quill_init_fn)dlsym(handle, quill_init); quill_buffer (quill_buffer_fn)dlsym(handle, quill_buffer); quill_swap (quill_swap_fn)dlsym(handle, quill_swap); }这种接管模式带来性能提升的同时也引入了严重风险如果墨水刷新控制不当可能导致屏幕残影甚至永久性损伤。这就是为什么项目文档强调“仅在演示模式使用接管模式”。1.3 AI 集成层视觉模型与 OCR 的技术取舍传统思路可能会选择 OCR 识别手写文字后再发送文本到 LLM但 Riddle 直接发送整个页面 PNG 图像到视觉模型。这种设计有几个工程考量避免 OCR 错误累积手写字体识别率通常只有 70-80%错误会直接影响后续对话质量保留视觉上下文用户可能在页面画图表、箭头或特殊标记这些信息对理解意图很重要简化技术栈现代多模态模型如 GPT-4o-mini 的视觉理解能力已经足够可靠无需维护独立的 OCR 管道代价是每次交互需要传输 100-300KB 的 PNG 图像相比纯文本通信带宽需求增加 10-100 倍。对于按 token 计费的 API 服务成本结构也完全不同。2. 环境准备从零搭建 reMarkable 开发环境在 reMarkable Paper Pro 上运行自定义代码需要先开启开发者模式这个过程会 void 设备保修且操作不当有变砖风险。以下是经过实际验证的稳妥步骤。2.1 激活开发者模式不同固件版本的方法略有差异但核心流程一致进入设置 - 关于 - 版权信息页面连续点击 reMarkable logo 10 次直到出现开发者菜单开启“开发者模式”选项通过 USB-C 连接电脑设备会显示“USB 网络已连接”验证开发者模式是否成功激活# 检查设备是否响应 SSH ping -c 3 10.11.99.1 # 尝试 SSH 登录初始无密码 ssh [email protected]如果连接失败可能需要检查 USB 网络共享设置。在 Windows 上还需要安装相应的 RNDIS 驱动程序。2.2 安装必要的工具链在 reMarkable 设备上直接编译不可行资源有限需要配置交叉编译环境。以下是 Ubuntu/Debian 环境的配置步骤# 安装 ARM64 交叉编译工具链 sudo apt install gcc-aarch64-linux-gnu g-aarch64-linux-gnu # 安装 Rust 和 ARM64 目标 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh source ~/.cargo/env rustup target add aarch64-unknown-linux-gnu # 创建交叉编译配置 mkdir -p ~/.cargo cat ~/.cargo/config.toml EOF [target.aarch64-unknown-linux-gnu] linker aarch64-linux-gnu-gcc EOF对于 C/C 部分的编译还需要 reMarkable SDK。由于许可证限制SDK 不能直接分发需要从设备提取必要的库文件# 从已连接的设备提取库文件 ssh [email protected] tar czf - /usr/lib/libqsgepaper.so | tar xzvf -2.3 部署应用加载器reMarkable 没有标准的应用商店机制需要借助第三方启动器。目前最稳定的是 xovi AppLoad 组合# 下载 xovi 安装脚本 wget https://github.com/ddvk/remarkable2xochitl/files/xxxxxx/xovi_install.sh chmod x xovi_install.sh # 通过 SCP 上传到设备 scp xovi_install.sh [email protected]:/home/root/ # 在设备上执行安装 ssh [email protected] cd /home/root ./xovi_install.sh安装完成后重启设备应该能看到 xovi 界面通过手势或侧边栏访问 AppLoad 应用列表。3. 构建和部署 Riddle有了基础环境后开始具体构建 Riddle 组件。项目包含 Rust 主应用和 C/C 渲染库两部分需要分别编译。3.1 编译 Rust 主应用首先克隆仓库并检查依赖git clone https://github.com/MaximeRivest/riddle.git cd riddle # 检查 Cargo.toml 中的依赖项 # 特别注意 openssl-sys 和 curl-sys 可能需要额外配置配置 OpenSSL 交叉编译环境这是最常见的编译失败点# 安装 ARM64 OpenSSL 开发包 sudo apt install libssl-dev:aarch64 # 设置环境变量让 openssl-sys 能找到交叉编译版本 export OPENSSL_DIR/usr/aarch64-linux-gnu export OPENSSL_INCLUDE_DIR$OPENSSL_DIR/include export OPENSSL_LIB_DIR$OPENSSL_DIR/lib开始编译cargo build --release --target aarch64-unknown-linux-gnu如果编译成功在target/aarch64-unknown-linux-gnu/release/下应该能找到riddle可执行文件。3.2 编译 quill 渲染库quill 子项目需要访问设备特定的库文件编译过程更复杂cd quill # 创建库文件链接从之前提取的文件 ln -s /path/to/extracted/libqsgepaper.so . # 修改 build.sh 中的设备 IP 地址 sed -i s/10.11.99.1/你的设备IP/g build.sh # 执行编译 chmod x build.sh ./build.sh编译过程中最可能遇到的错误是库版本不匹配。reMarkable 固件 3.26 和 3.27 的 ABI 有细微差别需要确保提取的库文件版本与设备当前版本一致。3.3 配置应用清单和启动脚本AppLoad 需要通过清单文件识别应用信息。创建external.manifest.json{ name: The Diary, description: Tom Riddles Diary - Vision LLM on e-ink, version: 0.2.0, author: Maxime Rivest, main: appload-launch.sh, icon: diary.png }创建启动脚本appload-launch.sh这是控制运行模式的关键#!/bin/bash # 检查运行模式窗口模式还是接管模式 if [ $1 takeover ]; then # 停止 xochitl 服务完全控制屏幕 systemctl stop xochitl ./riddle --mode takeover # 退出时恢复原界面 systemctl start xochitl else # 窗口模式在 xochitl 内部运行 ./riddle --mode windowed fi给脚本执行权限并打包部署文件chmod x appload-launch.sh zip -r riddle-appload-aarch64.zip riddle quill/libquill.so external.manifest.json appload-launch.sh3.4 部署到设备通过 SCP 上传到设备的 AppLoad 目录scp riddle-appload-aarch64.zip [email protected]:/home/root/xovi/exthome/appload/在设备上解压并配置环境变量# 在设备 SSH 会话中操作 cd /home/root/xovi/exthome/appload/ unzip riddle-appload-aarch64.zip cp oracle.env.example oracle.env # 编辑 oracle.env 添加 API 密钥 vi oracle.env环境变量文件内容示例# oracle.env RIDDLE_OPENAI_KEYsk-your-api-key-here RIDDLE_OPENAI_BASEhttps://api.openai.com/v1 RIDDLE_OPENAI_MODELgpt-4o-mini4. 配置 AI 后端OpenAI 兼容 API 集成Riddle 支持两种 AI 后端OpenAI 兼容 API 和本地 pi RPC 服务。对于大多数用户OpenAI 兼容方案更易用。4.1 获取和配置 API 密钥虽然项目名称暗示 Claude Fable但实际上使用标准的 OpenAI 视觉 API。支持任何兼容 OpenAI 格式的服务# 标准 OpenAI export RIDDLE_OPENAI_KEYsk-... export RIDDLE_OPENAI_BASEhttps://api.openai.com/v1 export RIDDLE_OPENAI_MODELgpt-4o-mini # OpenRouter 示例可能更便宜 export RIDDLE_OPENAI_KEY$OPENROUTER_API_KEY export RIDDLE_OPENAI_BASEhttps://openrouter.ai/api/v1 export RIDDLE_OPENAI_MODELopenai/gpt-4o-mini # 本地部署的兼容服务 export RIDDLE_OPENAI_KEYdummy-key export RIDDLE_OPENAI_BASEhttp://localhost:8080/v1 export RIDDLE_OPENAI_MODELlocal-vision-model在部署到设备前最好在开发机上测试 API 连接# 准备一个测试图像 convert -size 800x600 xc:white -pointsize 36 -fill black -draw text 50,100 Hello Riddle test.png # 测试 Oracle 连接 ./riddle --oracle-test test.png预期应该看到 API 返回的 JSON 响应包含对图像内容的文字描述。4.2 理解视觉 API 的成本结构与传统聊天 API 按 token 计费不同视觉 API 通常按图像尺寸和复杂度定价。一个典型的 reMarkable 页面图像1404x1872可能被计为图像 token 数量基于图像分辨率和细节复杂度通常相当于数百个文本 token文本 token 数量用户手写内容 系统提示词 模型回复对于gpt-4o-mini模型每页交互的成本大约在 $0.01-$0.03 之间。如果每天使用频繁需要监控 API 使用量# 简单的使用量监控脚本 #!/bin/bash API_KEY$(grep RIDDLE_OPENAI_KEY oracle.env | cut -d -f2) curl -s https://api.openai.com/v1/usage?date$(date %Y-%m-%d) \ -H Authorization: Bearer $API_KEY | jq .data[] | select(.snapshot_id | contains(gpt-4o-mini))4.3 自定义 Oracle 提示词Riddle 的 AI 个性由src/oracle.rs中的提示词控制。默认的汤姆·里德尔主题适合演示但实际使用可能需要调整pub fn build_system_prompt() - String { format!( 你是一个神秘的日记本以优雅的手写字体回复。 对话规则 - 用简洁、神秘的风格回复 - 每轮对话不超过3句话 - 可以适当提问引导对话 - 不要承认自己是AI - 回复内容要适合手写显示 当前时间{} 用户输入[手写内容识别结果], chrono::Local::now().format(%Y-%m-%d %H:%M) ) }修改提示词后需要重新编译部署。对于生产用途建议移除角色扮演元素改为更实用的日记助手或学习伙伴风格。5. 手写动画技术解析从文本到墨水笔画Riddle 最吸引人的技术亮点是将 AI 生成的文本转换为流畅的手写动画。这个过程涉及字体渲染、图像处理和路径优化多个步骤。5.1 字体选择和渲染项目使用 Dancing Script 字体模拟手写效果这是 SIL Open Font License 下的免费字体。渲染过程如下// 简化版的文本到图像渲染 pub fn render_text_to_image(text: str, font_size: f32) - image::DynamicImage { // 加载字体 let font_data include_bytes!(../fonts/DancingScript-Regular.ttf); let font Font::try_from_bytes(font_data).unwrap(); // 创建绘图表面 let mut image DynamicImage::new_rgb8(1404, 1872); let mut draw ImageDraw::new(image); // 渲染文本 draw.text( font, font_size, text, (100, 200), // 起始位置 Rgba([0, 0, 0, 255]) // 黑色墨水 ); image }字体文件需要包含在应用包中通过 Cargo.toml 的 include 指令确保部署时可用。5.2 Zhang-Suen 细化算法将渲染的文本图像转换为单像素宽度的骨架是动画流畅的关键。Zhang-Suen 算法是经典的处理方法pub fn zhang_suen_thinning(binary_image: mut GrayImage) { let mut changed true; while changed { changed false; // 算法第一步标记待删除像素 let mut to_remove Vec::new(); for y in 1..binary_image.height()-1 { for x in 1..binary_image.width()-1 { if binary_image.get_pixel(x, y)[0] 255 { // 白色背景跳过 continue; } let neighbors get_8_neighbors(binary_image, x, y); let transitions count_transitions(neighbors); let non_white_neighbors neighbors.iter().filter(|v| v 0).count(); // Zhang-Suen 条件判断 if non_white_neighbors 2 non_white_neighbors 6 transitions 1 (neighbors[0] 255 || neighbors[2] 255 || neighbors[4] 255) (neighbors[2] 255 || neighbors[4] 255 || neighbors[6] 255) { to_remove.push((x, y)); } } } // 删除标记的像素 for (x, y) in to_remove { binary_image.put_pixel(x, y, Luma([255])); changed true; } // 算法第二步类似逻辑条件略有不同 // ... 省略重复代码 } }这个算法需要迭代执行直到没有更多像素可删除最终得到文本的骨架表示。5.3 路径追踪和动画序列从骨架图像生成笔画路径是最后一步pub fn trace_skeleton_to_strokes(skeleton: GrayImage) - VecStroke { let mut strokes Vec::new(); let mut visited HashSet::new(); for y in 0..skeleton.height() { for x in 0..skeleton.width() { if skeleton.get_pixel(x, y)[0] 0 !visited.contains((x, y)) { // 找到新的笔画起点 if let Some(stroke) trace_stroke(skeleton, x, y, mut visited) { strokes.push(stroke); } } } } strokes } fn trace_stroke(skeleton: GrayImage, start_x: u32, start_y: u32, visited: mut HashSet(u32, u32)) - OptionStroke { let mut points Vec::new(); let (mut x, mut y) (start_x, start_y); // 沿着骨架追踪直到端点 while !visited.contains((x, y)) { visited.insert((x, y)); points.push((x, y)); // 查找下一个连接点 let next find_next_point(skeleton, x, y, visited); if let Some((nx, ny)) next { x nx; y ny; } else { break; // 到达笔画终点 } } if points.len() 1 { Some(Stroke::new(points)) } else { None } }生成的笔画序列会按照书写速度回放创造出真实的手写体验。动画速度需要与 e-ink 刷新率匹配避免出现闪烁或拖影。6. 运行验证和故障排查部署完成后需要通过系统化测试验证所有组件正常工作。以下是常见的验证步骤和问题解决方法。6.1 启动流程验证启动应用后按顺序检查以下环节硬件输入检测在屏幕上书写观察墨水是否正常显示空闲检测停止书写后约 2.8 秒原有墨迹应该开始淡出API 调用通过设备日志观察是否发起视觉 API 请求响应接收API 返回后应该看到手写动画开始动画完成整个回复书写完成后所有墨迹逐渐淡出检查设备日志的方法# 在设备上查看 Riddle 日志 journalctl -f -u xochitl | grep riddle # 或者直接查看应用输出如果在前台运行 ssh [email protected] cd /home/root/xovi/exthome/appload/riddle ./riddle --mode windowed6.2 常见问题及解决方案问题现象可能原因检查方法解决方案应用启动失败依赖库缺失ldd riddle检查动态链接安装缺失的 ARM64 库文件笔输入无响应输入设备权限问题ls -l /dev/input/event*将用户添加到 input 组API 调用失败网络连接或密钥错误在设备上curl api.openai.com检查网络设置和 API 密钥墨水显示异常渲染模式不匹配检查当前运行模式切换 windowed/takeover 模式动画卡顿设备性能不足查看系统资源使用关闭其他后台进程6.3 性能优化建议对于日常使用可以调整以下参数改善体验减少 API 调用频率# 修改触发延迟默认 2800ms export RIDDLE_IDLE_TIMEOUT5000 # 延长到 5 秒优化图像质量# 降低图像分辨率节省带宽 export RIDDLE_IMAGE_QUALITY80 # 默认 95本地缓存优化// 在 src/cache.rs 中添加对话历史缓存 // 避免相同问题重复调用 API7. 生产环境注意事项将 Riddle 用于实际日记或笔记场景时需要额外考虑隐私、可靠性和维护性。7.1 隐私和数据安全所有页面图像都会发送到第三方 API 服务需要明确数据处理政策选择可信的 API 提供商了解他们的数据保留和隐私政策本地预处理可以考虑在发送前对敏感内容进行模糊处理定期清理设置自动删除旧的对话记录和缓存图像7.2 可靠性设计当前实现是单点运行几个改进方向看门狗机制#!/bin/bash # 简单的进程监控脚本 while true; do if ! pgrep -x riddle /dev/null; then echo Riddle 进程异常退出重新启动 systemctl restart riddle-service fi sleep 30 done状态恢复// 定期保存当前状态到文件 pub fn save_session_state() - Result() { let state SessionState { current_page: self.current_page.clone(), conversation_history: self.history.clone(), last_backup: Utc::now(), }; let state_json serde_json::to_string(state)?; std::fs::write(session_backup.json, state_json)?; Ok(()) }7.3 扩展可能性Riddle 的基础架构可以支持多种扩展多语言支持替换字体和提示词支持不同语言专业领域优化为数学、编程、艺术等场景定制提示词离线模式集成本地小模型减少 API 依赖多设备同步通过云存储在不同 reMarkable 设备间同步日记这个项目的真正价值不在于复现哈利波特魔法而是展示了如何将现代 AI 能力与专注的硬件体验结合。对于寻求减少数字干扰、同时保留智能助手能力的用户这种形式可能代表了一种新的技术方向。实际部署过程中最需要耐心的是交叉编译环境配置和设备特定库的兼容性。一旦基础环境就绪后续的定制和优化反而相对直接。建议先从窗口模式开始验证基本功能再逐步尝试更复杂的接管模式优化。