kevinzhow/raft-flutter · 上手攻略

  • 仓库：kevinzhow/raft-flutter
  • 链接：https://github.com/kevinzhow/raft-flutter
  • 分类：database / Raft consensus / distributed systems / desktop & mobile client
  • 作者：spark
  • 更新：2026-10-14

§0 三证 checklist - GitHub URL：✅ 已 fetch（README + docs/architecture.md + docs/deployment.md + docs/release-evidence.md） - 顶会 venue+年份：⚠️ 这是客户端工程仓库，无学术会议背书；"对齐目标"是上游 Raft Web 客户端 1.17.5（README 自陈，引用 docs/source-reference.json）。 - README 子模块 anchor：✅ docs/architecture.md（架构）+ docs/development.md（开发流程）+ docs/deployment.md（自部署）+ docs/parity-and-alignment.md（Web 客户端对齐）+ docs/release-evidence.md（release 验收）

一、是什么

kevinzhow/raft-flutter 是一个用 Flutter 写的 Raft 桌面/移动原生客户端。Raft 在这里是 botiverse/raft-source 项目的同一款协作平台（"humans and AI agents collaborate as peers"），本仓库通过 HTTP + Socket.IO 与 Raft 服务端通信，并在功能行为上对齐 Raft Web 客户端的某个固定版本（README 注明 Web 1.17.5，raft-source 26f77ef，出处见 docs/source-reference.json）。

仓库卡片标注 73 stars / +14 周增，目录结构是 monorepo 形态：

  • apps/raft_flutter — 主 app（lib/、android/、ios/、linux/、macos/、windows/、test/、integration_test/、test_driver/）；
  • packages/raft_ui — 设计系统（生成的 tokens 与 component recipes）；
  • packages/raft_client — 纯 Dart 客户端（HTTP / Socket.IO / secure-storage / typed errors）；
  • packages/raft_sync — sync 状态机（seq/epoch/dedupe/gap repair/read state）；
  • packages/flutter_chat_ui — vendored 的聊天 UI 包；
  • tool/ — flutter 包装脚本、各类 gates（check-project、ds-audit、source-hash）、parity、性能、打包、生成器。

二、解决什么问题

  1. 多端原生客户端：让 Raft 协作平台在 Windows / Linux / macOS / Android / iOS 都有原生体验，而不是只能跑 Chrome 里的 Web 版本；
  2. Web 客户端视觉/功能 parity：仓库的"是否完成"判断标准是 Web 客户端 parity（详见 docs/parity-and-alignment.md 与 docs/feature-parity.csv）；
  3. 设计系统 discipline：通过 tool/ds-audit 强制 apps/raft_flutter/lib 下所有尺寸都从设计 token 取，禁止魔法字面量；
  4. 同 source 跨平台验收证据：README 给出"Linux + Android full-app functional flows passed on the same source"，并区分"local use" vs "released acceptance"。

三、快速安装

⚠️ 仓库强烈推荐用 tool/flutter 包装脚本跑命令（pinned SDK）。README 显式写：

# 1) 拉取 + 装依赖（含 bindings_generator 子包）
git clone https://github.com/kevinzhow/raft-flutter
cd raft-flutter
tool/flutter pub get --enforce-lockfile
(cd apps/raft_flutter/tool/bindings_generator && ../../../../tool/flutter pub get --enforce-lockfile)

# 2) 跑起来，默认连 https://api.raft.build
cd apps/raft_flutter && ../../tool/flutter run

# 3) 若要连本地自托管 Raft 服务（README 给出 --dart-define 入口）
cd apps/raft_flutter && ../../tool/flutter run \
    --dart-define=RAFT_ORIGIN=http://localhost:13041

按 README 平台表，各平台的最小要求与构建命令如下（README 表格 verbatim 抽取）：

平台 状态 最低 OS / 架构 构建命令（在 apps/raft_flutter 下）
Android 已 verify：真机 + emulator 全流程，released-APK smoke minSdk = max(Flutter default, 24)，compileSdk/targetSdk 37；设备只支持 ARM64；x86_64 仅 emulator ../../tool/flutter build apk --release
Linux 已 verify：X11/GTK 全流程 x86_64 only；tool/prepare-media-linux 只支持 Ubuntu amd64；Wayland/其他发行版未 verify 先 tool/prepare-media-linux，再 ../../tool/flutter build linux --release
macOS 本地使用 + Keychain 迁移/session 恢复确认；通知、媒体、完整 accessibility/lifecycle 仍 pending macOS 12+，Apple Silicon（ARM64）only；Xcode 项目排除 x86_64 ../../tool/flutter build macos --release
iOS Simulator debug build 已编译（含 5 套 icon palette）；未安装/未在真机跑；签名/Keychain/notifications/media 未 accept Xcode project deployment target 15.0（ios/Flutter/AppFrameworkInfo.plist 写 14.0，docs/background-inbox.md 写 14+；以项目设置为准） ../../tool/flutter build ios --simulator --debug（需要 Xcode 的 Mac）
Windows Release 构建并运行；设置按钮通知显示、icon、warm click-to-return 已确认；full-app/a11y/cold-click 未 accept x64，Windows 11 verify；需要 Windows App Runtime 1.7 x64 python ../../tool/flutter build windows --release --no-pub（见 docs/development.md#windows）

四、核心用法

4.1 与 Raft 服务端通信

仓库不重复造 Raft 服务端——它假设你已经有一个 Raft server（公网 https://api.raft.build 或自托管 http://localhost:13041）。packages/raft_client 把 HTTP + Socket.IO 封装成 typed errors，所有平台调用都走同一份纯 Dart 代码。

4.2 设计系统的"硬约束"

# 让 ds-audit 扫 apps/raft_flutter/lib，禁止尺寸字面量
tool/ds-audit apps/raft_flutter/lib
# source-hash 保证生成的 token 不被手动改
tool/source-hash

设计 token 在 packages/raft_ui/lib/src/tokens/*.g.dart（由 tool/gen-tokens 从 vendored raft-ui 0.5.27 CSS 生成）；component recipes 在 packages/raft_ui/lib/src/recipes/*.g.dart（由 tool/recipes/run 生成）。两份都不允许手改。

4.3 与 Web 客户端做 visual parity 检查

# README 直接引用的入口
tool/parity            # 基础 parity 套件
tool/parity-ext/       # 扩展套件
tool/alignment-audit.py  # 对齐审计（参见 docs/parity-and-alignment.md）

README 强调"Widget Preview never substitutes for platform tests (accessibility, IME, lifecycle, notifications)"——parity 工具只做像素/结构对齐，平台侧的 a11y / 输入法 / 生命周期 / 通知仍要真机测。

4.4 性能调优与调试

docs/performance.md + tool/performance/ 提供 perf lab；CI 端 .github/workflows/performance.yml 在 hosted runner 上跑 Python guards，在 self-hosted runner 上跑 Linux profile。

4.5 平台特定限制（README 原文边界）

  • iOS 用 BGAppRefresh 周期性刷新 Activity 通知；Android 没有 background fetch，通知靠 live socket，所以 Settings → Notifications 会要求用户把 Raft 从 battery optimization 白名单里放出来。FCM / APNs / UnifiedPush 未注册。
  • Android PDF 用 PdfRenderer；Linux PDF 走系统的 poppler-utils；macOS 则回退到下载（无 in-app preview）。
  • Android 原生 share；其他平台未做 native share。
  • Windows 通知走 Windows App SDK + raft-notification: 协议，需要管理员权限注册一次协议（详见 docs/windows-notifications.md）；"退出后再收远程消息"未实现。
  • iOS / Android icon preset 在 App settings → Appearance，且与系统 native launch assets 双向校验（详见 docs/custom-app-icons.md）。

五、典型适用场景

  • 想给 Raft 写一个跨平台原生客户端：本仓库就是答案，但要先评估 parity 工作量；
  • 想把 Flutter 设计 token 体系落地为"硬约束"：可参考 tool/ds-audit + tool/gen-tokens 的完整链路；
  • 想在多端复用同一份 sync 状态机：参考 packages/raft_sync（seq/epoch/dedupe/gap repair/read state，从 Web 客户端移植）；
  • 想做"自管 CI + self-hosted runner for performance"：参考 .github/workflows/performance.yml + tool/performance/；
  • 想找 Flutter + Rust FFI 实战样例：参考 tool/bindings_generator（Android Performance Hint FFI bindings，独立 package）。

六、坑与注意

  1. parity ≠ 平台验收：README 自陈"Pixel-level visual parity with the Web client is not accepted yet"——能用 parity 工具对齐，不代表能在所有平台 a11y/lifecycle 验收。
  2. iOS 真机未安装/未跑；只验过 simulator debug build。CocoaPods fallback 是本地生成的，没有 Podfile 入仓。
  3. macOS 是 dev 安装，不是 Developer ID distribution / notarization，也没公开 macOS release 接受。已有安装升级时必须保持同一 signing identity + Data Protection Keychain 配置，否则 plain ad-hoc build 读不到已迁移的 session。
  4. Linux 只验了 Ubuntu amd64 x86_64；Wayland 与其他发行版未 verify。
  5. Windows 通知要管理员权限注册 raft-notification: 协议；App Runtime 1.7 x64 是硬依赖。
  6. 不要手改 packages/raft_ui/lib/src/tokens/*.g.dart / recipes/*.g.dart：它们是生成的，hash 会被 source-hash 守住，改了就报错。
  7. minSdk 取 max(Flutter default, 24)：跟 Flutter 升级耦合，升级前先确认 tool/android-install 的拒绝策略（README 写明 ARM64 only for device）。
  8. Performance ≠ 120 fps：README 自陈"Stable 120 fps across every page, scroll and resize has not been established."——synthetic profile 改善 ≠ 真机稳定。
  9. bindings_generator 是独立 package：pub get 时必须单独跑一次 (cd apps/raft_flutter/tool/bindings_generator && ...pub get)，否则 Android build 会缺 FFI binding。
  10. apps/raft_flutter 是相对路径的起点：所有 tool/flutter 命令必须 cd apps/raft_flutter 之后再用 ../../tool/flutter ... 调；不在仓库根跑。

七、与同类对比

客户端 平台覆盖 形态 与上游 Web parity 关注度
kevinzhow/raft-flutter（本仓库） Win/Linux/macOS/Android/iOS（状态不一） Flutter 原生 monorepo 极高（独立 tool/parity + tool/alignment-audit.py + feature-parity.csv）
Raft Web 客户端（官方） Web SPA n/a（基线）
通用 Electron wrapper 桌面 Web shell 通常不做 pixel parity，只做功能
通用 React Native wrapper 移动 JS bridge 通常不做 pixel parity

⚠️ "通用 Electron/RN wrapper"行只是粗略坐标，不代表具体项目的实际策略。

八、一句话推荐结论

Raft 协作平台用户的桌面/移动原生入口、且能接受"iOS/Wayland/macOS notarization 仍 pending"的现实：本仓库就是当前最贴近 Web parity 的 Flutter 实现；想找一个 production-ready 的开箱即用 cross-platform Raft 客户端：README 自陈"Full platform acceptance is still pending"，目前仍是 experimental 状态。