Technical documentation

看懂系统,
也看清边界。

Rinwa 把安静的阅读界面、本地数据、本地语义搜索、可选 AI Provider 与 operation log 同步组合在一起。这份文档解释每部分运行在哪里,以及哪些仍处于开发阶段。

当前架构

Local-first · Protocol v1
主要存储
每设备 SQLite
本地向量
ONNX · q8 · 256d
同步中继
CouchDB operation log
最近核对
2026 年 7 月 29 日
01 系统概览

每台设备都拥有完整的阅读库。

云端可以提供帮助,但不会成为唯一的数据源。阅读、收藏、搜索与知识记录都先从设备本地开始。

你的设备
界面React 阅读表面电脑 · 平板 · 手机
→
边界Platform + Repository当前 HTTP · 迁移原生 SQLite
→
主要存储SQLite文章 · 状态 · 知识 · 索引
正文抓取队列翻译缓存向量队列加密备份
可选知识库Obsidian受控 Markdown 区块
可选智能AI Provider明确同意后才发送
可选多端Rinwa Sync同步操作,不复制 SQLite
迁移中的边界

桌面与 Web 当前仍以本地 Node API 为完整生产路径。移动 SQLite Adapter 已能编译,但完整阅读路径切换与真实设备验证尚未完成。

03 AI Runtime

先组织证据,再调用 Provider。

AI 辅助首先在本地构造有限上下文。短文章可以使用全文,长文章与全库问题则先检索段落;文章坐标和知识记录会先变成引用 ID,再交给用户选择的服务。

文章划线笔记全库搜索
↓
本地上下文构造器 范围 → 检索 → token 预算 → 引用 ID
[P] 文章[H] 知识[S] 全库
↓ 明确同意
OpenAIOpenRouterOllamaCustomDeepL
↓
流式回答引用校验 · 重试策略 · 用量统计

Provider 边界

问答通过 OpenAI-compatible completions 接入多种服务;翻译可选择 DeepL、OpenAI 或自定义接口。没有 Provider 时,本地阅读不受影响。

运行保护

临时网络、限流和服务端错误只做有限重试;错误请求和无效凭据不会。无法对应证据的引用 ID 会在展示前移除。

密钥与用量

打包客户端把密钥保存在系统安全存储中。Provider 返回详细 usage 时,会分别记录输入、输出、缓存与 reasoning token。

04 同步协议

同步操作,不复制数据库文件。

每台设备都能独立使用。本地修改会变成包含设备序列和 Hybrid Logical Clock 的不可变操作;服务器只中继操作,字段如何合并由客户端决定。

设备 ASQLite本地写入
operation 队列
push→pull←
RINWA SYNCCouchDB不可变、幂等的 operation log
不解析 _changes cursor
pull→push←
设备 BSQLite本地写入
字段时钟合并
01

记录

deviceId:sequence、实体、动作、payload、时间和 HLC 先写入本机。

02

中继

服务器验证有界批次;重复 operation ID 只会成为无害的 CouchDB conflict。

03

合并

只有远端 HLC 更新时才应用对应字段,因此互不相关的修改可以独立收敛。

04

删除

Tombstone 阻止旧订阅、笔记、保存搜索、Connector 或划线操作把数据重新复活。

会同步

订阅 · 阅读状态 · 偏好 · 保存搜索 · Connector 订阅 · 摘要 · 笔记 · 标签 · 引用 · 划线

留在设备

文章正文 · 媒体 · 翻译 · 模型文件 · 向量 · 搜索索引

远端向量搜索尚未启用

服务器可以创建 Qdrant Collection,但协议仍明确返回 semanticSearch: false。当前语义检索发生在本地,远端集合存在不等于功能已经上线。

05 数据与缓存

应用版本与内容版本彼此独立。

修改界面、增加设置或修复手势不会清空文章。正文抽取、翻译、生成摘要和向量分别拥有自己的兼容版本。

层级何时失效失败行为
Feed 内容上游内容哈希改变保留当前 Feed 副本
阅读正文抽取契约与正文哈希改变保留上一份成功正文
翻译管线、目标语言或正文哈希改变原文继续可读
生成摘要摘要契约、语言或正文哈希改变手工摘要不受影响
向量模型、revision、分块或向量契约改变搜索回退到 FTS
06 知识表面

阅读结果可以离开应用。

Obsidian

Rinwa 只管理明确标记的 Markdown 区块,保留周围的用户内容;在 Vault 中修改的标签、笔记与摘录也会重新回到 Rinwa。

本地 MCP

读取工具可以在本地使用;添加订阅、修改状态、保存笔记、创建划线或导出 Obsidian 都要求明确的写入 token。

07 多端架构

一套界面,原生能力留在边界。

React 与 Vite 提供共享阅读表面,Tauri 2 将它交付到桌面与移动端。组件不会直接判断 macOS、Windows、iOS 或 Android;文件、安全存储和系统入口都留在 Platform Adapter。

共享 UIReact · 响应式阅读 · 手势 · 知识
↓
Platform Adaptertransport · 文件 · 链接 · 剪贴板 · 安全存储
↓
macOSWindowsiOS / iPadOSAndroid
08 能力状态

已经实现,不等于已经发布。

当前源码已工作

桌面/API 路径的本地 SQLite、正文队列、逐段翻译、本地向量、混合检索、引用、知识工具、operation log 同步、备份与共享响应式 UI。

预览或迁移中

Android 共享界面安装包、移动 SQLite Repository、原生安全存储迁移,以及 Rinwa 公开品牌迁移。

需要平台验证

移动数据库填充、后台刷新、Android Keystore、iOS/Windows 打包、签名、notarization 与应用商店审核。

需要实现级别的细节?

在 GitHub 阅读源码 ↗