flomo-sync

SKILL.md

---
name: flomo-sync
description: 将 flomo 所有记录 memo 同步/备份到本地 Markdown 文件的工具。使用 scripts/flomo-sync.py 脚本通过 flomo API 拉取 memo，支持增量同步、附件下载、多文件输出。当用户需要备份 flomo、同步 flomo memo 到本地、导出 flomo 笔记为 Markdown 时使用。
---

# flomo-sync

将 flomo 所有 memo 增量同步为本地 Markdown 文件。

## 前置入参要求（必须）

执行本技能前，必须先明确并拿到以下入参：

- 当前项目主路径（绝对路径），例如 `/Users/xxx/project-name`
- flomo token（来自项目主路径下 `.flomo.config`，避免在对话中明文暴露）

`--dir` 必须基于“当前项目主路径”传入绝对路径，禁止使用相对路径（如 `./output`、`../backup`）。

## 快速开始

### 1. 安装依赖（Python 3.10+）

```bash
pip install requests markdownify
```

### 2. 配置 token

在项目主路径下创建 `.flomo.config`，并包含 `token=<access_token>`。

**安全建议（强烈推荐）**：
- 优先使用 `.flomo.config` 保存 token，不要在对话中直接粘贴 token，避免泄露给 LLM。
- 执行同步时优先使用 `python scripts/flomo-sync.py`（自动从 `.flomo.config` 读取）。

#### `.flomo.config` 格式说明

- **通用规则**：一行一个 `key=value`；以 `#` 开头的行为注释；空行忽略。
- **flomo-sync 所需**：`token=<access_token>`；支持带或不带 `Bearer ` 前缀，例如：
  - `token=1023456|AA000000ABCDEFGHIJKHLMNOP000000000000000`
  - `token=Bearer 1023456|AA000000ABCDEFGHIJKHLMNOP000000000000000`
- **获取 token**：在浏览器打开 [https://v.flomoapp.com](https://v.flomoapp.com) 登录后，按 `F12` → Network → 点击任意请求 → Headers → 复制 `Authorization` 的值（形如 `Bearer 1023456|...`）。备用：Application → Local Storage → `me` → 复制 `access_token`。
- 同一文件可同时包含 `url=` 供 flomo-add 使用（与 flomo-add 共用一配置文件）。

### 3. 运行同步

```bash
# 基本用法（文档规范：必须传 --dir 且为绝对路径）
python scripts/flomo-sync.py --dir /abs/path/to/output

# 推荐：以当前项目主路径作为基准拼接输出目录
# 例：当前项目主路径=/Users/yourname/my-project
python scripts/flomo-sync.py --dir /Users/yourname/my-project/output/flomo-sync

# 临时排障：仅在本地终端通过命令行传入 token（不要在对话中提供 token）
# token 含 | 必须用单引号
python scripts/flomo-sync.py --token '1023456|AA000000...' --dir /abs/path/to/output

# 自定义输出目录
python scripts/flomo-sync.py --dir /Users/yourname/Desktop/flomo-sync

# 只拉取指定日期后更新的 memo
python scripts/flomo-sync.py --after 2024-01-01 --dir /abs/path/to/output

# 不下载附件到本地（保留远程 URL）
python scripts/flomo-sync.py --no-download --dir /abs/path/to/output
```

> 文档规范要求：执行同步时必须传 `--dir` 且使用绝对路径。实现层面为兼容保留兜底：未传 `--dir` 时，默认写入当前执行目录。

### 运行输出示例（含条目级进度）

```text
==================================================
flomo → Markdown 同步工具
==================================================

after=2024-01-01（来源: 命令行 --after）

  第 1 页（游标 updated_at=1704067200 slug=''）… 拉取 93 条
    页内处理 [########################] 93/93
    → 已处理，累计 93 条
  第 2 页（游标 updated_at=1709155652 slug='MTI3MTMwMzQ0'）… 拉取 27 条
    页内处理 [########################] 27/27
    → 已处理，累计 120 条

✅ 完成！新增 12 条，更新 3 条，跳过 105 条（耗时 2.1s）
```

## 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--token` | flomo access_token（可从 `.flomo.config` 读取）。支持 `Bearer <token>` 格式 | — |
| `--dir` | 输出目录绝对路径（文档规范：必传）。必须基于“当前项目主路径”确定 | —（未传时实现默认当前执行目录） |
| `--after YYYY-MM-DD` | 仅拉取该日期后更新的 memo | 自动读取 `.flomo.lock` |
| `--no-download` | 不下载附件，保留远程 URL | 否（默认下载） |

## 输出格式

每条 memo 生成独立 `.md` 文件，命名格式为 `{日期}_{标签}_{内容前6字}_{slug}.md`：

```markdown
---
slug: MTI3MTMwMzQ0
created_at: 2024-07-11 00:20:04
updated_at: 2024-07-11 00:20:04
tags: [英语/如何学习]
source: android
---

#英语/如何学习

你不是学不会，你只是不学

**附件:**
![photo.png](images/2024/07/11/MTI3MTMwMzQ0_photo.png)
```

## 增量同步机制

脚本自动维护 `.flomo.lock` 文件，记录上次同步的最大 `updated_at` 时间戳。下次运行时自动从该时间点（减 1 天容错）开始拉取，无需手动指定 `--after`。

## 常见问题

- **`sign 错误`**：token 无效或过期，重新从浏览器获取
- **`请先登录`**：未传入 token 或 token 不完整
- **附件处理**：图片（`.png/.jpg/.gif` 等）以 `![name](path)` 嵌入，音频（`.m4a/.mp3` 等）以 `[name](path)` 链接；加 `--no-download` 保留原始远程 URL

## 文件说明

```
skills/flomo-sync/
├── SKILL.md
├── scripts/
│   └── flomo-sync.py       # 主脚本
└── assets/                 # 预留
```

运行后会在输出目录产生：

```
output/
├── images/YYYY/MM/DD/      # 本地附件
├── {日期}_{标签}_{摘要}_{slug}.md  # 每条 memo（独立模式）
└── flomo_export.md          # 合并文件（--single 模式）
```