Marlin - GitHub 原生的流式笔记应用

#项目背景

在云笔记应用泛滥的时代，用户面临着两大痛点：

• ▸数据失控：笔记被锁在 Notion、Evernote 等平台的黑盒数据库里，迁移困难
• ▸性能妥协：每次操作都需要等待服务器响应，离线不可用

Marlin 诞生于对这两个问题的反思：能否既拥有云服务的便捷，又保留本地应用的性能和数据主权？

#核心功能

🔒 数据主权 - 你的笔记，你的仓库

• ▸每个 Workspace 对应一个 GitHub 私有仓库（命名格式：{name}.marlin）
• ▸笔记以标准 Markdown 文件存储在 notes/ 目录，文件名为时间戳
• ▸无需担心服务商倒闭或收费变更，数据永远可访问

⚡ Local-First - 零延迟体验

• ▸使用 IndexedDB 作为本地缓存，所有 UI 操作秒级响应
• ▸写作、搜索、标签过滤完全离线可用
• ▸GitHub 同步在后台静默进行，用户无感知

💬 流式体验 - 像聊天一样记笔记

• ▸摒弃传统笔记的"文件夹 → 笔记本 → 笔记"层级
• ▸采用时间流展示，输入即发送，零心理负担
• ▸通过 #标签 组织内容，自动提取并生成索引

🎨 HIG 设计 - 原生应用般的精致

• ▸严格遵循 Apple Human Interface Guidelines
• ▸One Surface 设计理念：统一的背景层级，毛玻璃效果
• ▸完整的深色模式支持，细腻的动画与交互

#技术实现

架构特点

• ▸前端：Next.js 15 App Router + React 19
• ▸运行环境：Edge Runtime（部署于 Cloudflare Pages，全球低延迟）
• ▸认证：Auth.js v5 + GitHub OAuth（无需自建用户系统）
• ▸本地数据库：Dexie.js（IndexedDB 封装）
• ▸编辑器：Tiptap（Headless WYSIWYG）

安全设计

• ▸所有 GitHub API 请求通过 Edge Function 代理（/api/proxy）
• ▸Access Token 加密存储在 HttpOnly Session Cookie 中，客户端无法访问
• ▸防止 Token 泄露到浏览器控制台或第三方脚本

同步策略

1. ▸初次同步：使用 Git Tree API 递归获取 notes/ 目录结构
2. ▸差异对比：本地 SHA 与远程 SHA 比对，识别变更文件
3. ▸批量下载：通过 GitHub Blob API 并发下载（限流 5 个/次）
4. ▸乐观更新：本地写入立即生效，后台上传失败则回滚并提示

#商业化进程

当前状态

• ▸✅ 核心功能已完成并上线（marlinnotes.com）
• ▸✅ 支持多 Space 管理、标签系统、活跃度热力图
• ▸🚧 正在开发：全局搜索、笔记归档、公开分享链接

开源策略

• ▸协议：BSL 1.1（Business Source License）
• ▸个人使用免费，商业化部署需要授权
• ▸四年后自动转为 Apache 2.0 开源协议

目标用户

• ▸开发者 / DevOps 工程师
• ▸Markdown 重度用户
• ▸关注数据隐私和长期归档的用户

#关键经验

1. Edge Runtime 的坑与解

• ▸问题：Cloudflare Workers 不支持 Node.js 内置模块（fs, crypto）
• ▸解决：全面迁移到 Web Standard API（TextEncoder, Web Crypto, fetch）

2. GitHub API Rate Limit

• ▸问题：REST API 限制 5000 次/小时，大量笔记时会超限
• ▸解决：混合使用 GraphQL API（单次请求获取多个文件），减少 80% 请求量

3. IndexedDB 性能优化

• ▸问题：上千条笔记时，全表查询会卡顿
• ▸解决：建立复合索引 [space+date]，使用 useLiveQuery 进行增量更新