01 / LOCAL本地是第一落点作答先写 SQLite 或 IndexedDB，不登录也能完成核心学习。
SYSTEM ARCHITECTURE
学习先落在本机，
云端只做该做的事。
KotoPlanet 不是“断网就空白”的网页壳。课程、作答和复习先在设备上完成；登录同步、AI 对话与语音能力，才通过受控的边缘服务连接出去。
当前公开架构 · 2026.08
一次学习操作LOCAL FIRST
- 01 · 默认本机直接完成无需登录
课程、练习与记录不等网络。
- 02 · 登录后按需同步进度
由 Worker 代理到 Supabase。
- 03 · 主动使用调用 AI 与语音不留录音
先检查配额，再受控转发。
02 / EDGE联网能力统一收口账号、业务接口与 MCP 经过 Worker；只有 Web 内容从 R2 直取。
03 / CONTENT内容独立发布课程仓库单独生成版本，Web 无需重建，iOS 随新包获得完整离线内容。
整体拓扑
一张图，
把真实关系看完整。
虚线框是仓库边界，箭头是实际调用与发布方向。图中保留 Astro 官网、iOS、Web、Admin、MCP、Worker、存储和外部服务之间的完整关系。
左右滑动查看完整关系
客户端边缘服务数据外部服务内容打包时拷入★练习入口
真实数据流
不是所有操作，
都要走同一条路。
下面四条路径对应真实使用场景，也解释了为什么离线学习、跨端同步和 AI 能力可以同时存在。
01
离线学习
打开一课，直接在设备里完成。
iOS 从安装包读取课程与音频，作答写进 SQLite。未登录时链路就在这里结束。
Bundle学习SQLite
02
跨设备同步
登录以后，才把本地进度带上云端。
客户端经 Worker 验证与代理，把学习记录写入 Supabase，再与另一台设备合并。
本地记录WorkerSupabase
03
AI 与语音
先过限流与配额，再连接外部能力。
对话文本、待朗读文本或录音片段只为当次功能转发；发音评测完成后不保存录音。
主动请求检查配额返回结果
04
MCP 学习入口
换到 AI 客户端，仍然是同一份进度。
ChatGPT、Claude 或 Cursor 经 OAuth 接入 MCP；完成练习后，结果通过 Worker 写回真实学习记录。
AI 客户端MCP写回进度
工程边界
应用代码与课程内容，
各自独立演进。
MONOREPOKotoPlanet 应用仓库
- Expo 项目同一套业务能力服务 iOS 与 Web
- Astro SSG官网首页、架构、支持和条款页面
- Admin运营后台独立构建与登录
- Worker静态托管、API、MCP 与配额
CONTENT REPOKotoPlanet 内容仓库
- CSV 是真源词汇、语法、阅读与听力可审查
- 构建时生成统一产出结构化数据和音频
- 版本化发布R2 指针让 Web 内容独立更新
- 离线快照同一版本内容进入 iOS 安装包
架构只是实现，边界才是承诺。