yuukiLike/zeromd

zeromd

Platform
Shell
License
Obsidian
iCloud

本地优先的 Obsidian 多端同步方案。零成本，零注册，零维护。

为什么做这个

最 AI 友好的知识库不是某个带 API 的 SaaS 产品，而是你硬盘上的一堆 markdown 文件。

而 .md 的进化还没结束——Mermaid 已经让纯文本变成了可交互的图表，这只是开始。

Obsidian 把所有笔记存成 .md 文件。AI 工具（如 Claude Code）可以直接读写你的知识库：

零 API   零插件   零中间层

Claude Code 天然能做这些事
Grep "系统设计" ~/vault/         # 搜索所有笔记
Read ~/vault/某篇笔记.md        # 读取内容
Edit ~/vault/某篇笔记.md        # 修改、补充
Glob "*/.md" ~/vault/         # 遍历整个知识库

对比 Notion 等云端方案：

|  | Obsidian vault | Notion |
|--|---------------|--------|
| AI 接入 | 直接读文件，零配置 | 需要 API + OAuth + MCP |
| 数据格式 | 标准 markdown | 私有 block 结构，需解析 |
| 读写速度 | 本地 I/O，毫秒级 | 网络请求 + rate limit |
| 版本历史 | Git log 完整记录每次变更 | 无 |
| 数据所有权 | 文件在你的硬盘上 | 存在别人的服务器上 |

本地文件 + 标准格式 = 不需要"接入"，天然就在一起。

zeromd 做的事很简单：让这个本地知识库在你的所有设备间保持同步。

架构

graph LR
subgraph icloud ["☁️ iCloud — 秒级同步"]
direction LR
iPhone["📱iPhone"]
Mac["💻macOS"]
end

subgraph git ["🍀 Git — 每 5 分钟"]
direction LR
GitHub["🍀GitHub"]
end

iPhone  Mac
Mac  GitHub
GitHub -.->|可选| Windows["🖥️Windows"]

style icloud fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style git fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#15803d
style iPhone fill:#3b82f6,color:#fff,stroke:#2563eb,stroke-width:2px
style Mac fill:#3b82f6,color:#fff,stroke:#2563eb,stroke-width:2px
style GitHub fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
style Windows fill:#94a3b8,color:#fff,stroke:#64748b,stroke-width:2px,stroke-dasharray: 5 5

- macOS ↔ iOS：iCloud 自动同步（秒级）
- macOS ↔ GitHub：Git 定时同步（每 5 分钟，有改动才提交）

Windows 用户可 git clone 仓库后配合 obsidian-git 插件同步。

快速上手

前提：Mac 上已安装 Obsidian，并创建了 iCloud vault。

bash  分支，再把本地 main 强制对齐到 origin/main。

同步原理

iCloud（macOS ↔ iOS）：苹果系统自动处理，vault 存在 ~/Library/Mobile Documents/iCloud~md~obsidian/Documents//，秒级同步。

Git（macOS ↔ GitHub）：launchd 定时任务每 5 分钟执行 sync.sh：
mermaid
flowchart TD
subgraph trigger ["⏰ 每 5 分钟 — launchd"]
check{"📂有改动？"}
end

subgraph sync ["🍀 同步流水线"]
stage["➕ git add -A"]
commit["💾 git commit"]
pull["⬇️ git pull --rebase"]
push["⬆️ git push"]
end

check -->|否| skip(["💤 跳过 — 无事发生"])
check -->|是| stage
stage --> commit --> pull --> push
push --> done(["✅ 已同步到 GitHub"])
pull -->|冲突| err(["⚠️ 需手动处理gmd doctor 排查"])

style trigger fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style sync fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#15803d
style check fill:#3b82f6,color:#fff,stroke:#2563eb,stroke-width:2px
style stage fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
style commit fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
style pull fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
style push fill:#16a34a,color:#fff,stroke:#15803d,stroke-width:2px
style skip fill:#94a3b8,color:#fff,stroke:#64748b,stroke-width:2px
style done fill:#15803d,color:#fff,stroke:#166534,stroke-width:2px
style err fill:#ef4444,color:#fff,stroke:#dc2626,stroke-width:2px

为什么 5 分钟：30 秒太碎，1 小时太慢，5 分钟刚好写完一段想法。可改 ~/Library/LaunchAgents/com.zeromd.sync.plist 中的 StartInterval。

方案选型

| 替代方案 | 不选的原因 |
|----------|-----------|
| iCloud 全平台 | Windows 同步差，无版本历史 |
| Obsidian Sync | ~$4/月，10 年 ≈ $480 |
| 纯 Git 全平台 | iOS 无好用的免费 Git 方案 |
| Notion | 私有格式，数据不在本地，AI 接入需要 API |
| 自建服务 | 运维成本高，停维即断 |

本方案：iCloud 管 Apple 生态同步，Git 管跨平台 + 版本历史。成本为零。

风险与缓解

| 风险 | 缓解 |
|------|------|
| iCloud 同步 .git 导致损坏 | 概率低；远程仓库是完整备份 |
| macOS 关机时 iOS 编辑无法推到 Git | 开机后自动补推 |
| Git 冲突 | pull --rebase + 纯文本易解决 |
| GitHub 中断 | 本地 + iCloud 双备份 |

常用命令
bash
gmd                      # 查看同步状态（等同于 gmd status）
gmd doctor               # 健康检查，逐项诊断
gmd sync                 # 立即手动同步
gmd log                  # 查看最近 20 条同步日志
gmd log 50               # 查看最近 50 条
gmd setup                # 智能安装（幂等，已完成的步骤自动跳过）
gmd help                 # 极简帮助（支持中文、英文和日语）
md 也能用，向后兼容

未指定语言时，gmd help 和 gmd doctor 会使用 macOS 的首选语言。命令后追加的语言优先级最高：zh 表示中文（也支持便利别名 cn），en 表示英文，ja 表示日语，例如 gmd help ja 或 gmd doctor cn。若需持久覆盖，可在 shell 配置中加入 export ZEROMD_LANG=zh（也可使用 cn、en 或 ja）。

改了 vault 名字？ 不需要任何操作。sync.sh 会自动扫描 iCloud 目录，找到有 .git 的 vault。

同步出问题？ 运行 gmd doctor 逐项排查。

后台任务停了？ 重新运行 gmd setup。想切换 vault？ 运行 gmd init。

HTTPS 认证失败？ GitHub 不支持用账号密码做 Git push。更新系统里保存的 Git HTTPS 凭证，或者把仓库改成 SSH。

新电脑上冒出旧 commit？ 首次同步会先对比 origin/main。如果发现本地状态过旧或已分叉，zeromd 会先把旧状态保存在 zeromd-backup- 分支里，再把本地 main 对齐到远端分支。

卸载
bash
bash scripts/uninstall.sh

笔记不受影响，iCloud 同步照常，只是不再自动推 GitHub。

参与贡献
bash
bash tests/run.sh

纯 bash 测试套件，零依赖。修改 scripts/ 下的文件后务必运行测试，PR 前确保全部通过。

项目结构

zeromd/
├── scripts/
│   ├── zeromd               # CLI 客户端（gmd status/sync/doctor/log/setup/help）
│   ├── setup.sh            # 智能安装器（幂等，8 个阶段）
│   ├── install.sh          # 向后兼容包装 → setup.sh
│   ├── uninstall.sh        # 卸载
│   └── sync.sh             # 自动同步（每 5 分钟）
├── tests/
│   ├── run.sh              # 测试运行器
│   ├── test_zeromd.sh       # CLI 测试
│   ├── test_sync.sh        # 同步逻辑测试
│   └── test_setup.sh       # 安装逻辑测试
├── install-remote.sh       # curl 一键安装入口
├── com.zeromd.sync.plist    # launchd 任务模板
├── LICENSE
├── README.md               # English
├── README.zh.md            # 中文
└── README.ja.md            # 日本語