flomo-note

极简云端卡片笔记技能 — 把网页、文章、想法整理成一条条 flomo memo，直接写入云端账号。

---

项目是什么

flomo-note 是一个 AI 辅助的云端笔记技能，用于将看到的好内容高效沉淀为 flomo 云端卡片。

• 卡片形态 = 一行标签段 + 概念名称行 + 正文，一事一卡、标签聚合
• 本地不落盘：笔记只存在于 flomo 云端账号，本地仅存放技能文档与工具脚本
• 流程机械化：抓取 → 验证 → 提炼 → 定标签 → 查重 → 写作 → 自检并写云 → 复盘；其中验证/核对/查重/复盘由流程闸门脚本强制留痕，漏做无法通过自检

---

规则在哪（本文件不复述）

规则只有三份，分工明确：

本文件只讲「是什么、怎么跑、控制台怎么用」。判据与硬限一律以 SKILL.md 编号为准， 不要在这里补一份摘要——历史上这份摘要就分叉过：README 的旧版核心约定 6 条 vs AGENTS.md 8 条， 卡片格式段也缺概念名判据，按它写卡会被质检拦。

---

快速开始

环境准备

# 克隆仓库
git clone https://github.com/shushuzn/flomo-note.git
cd flomo-note

# 配置 MCP token（本地文件，已 gitignore 不入库）
# 结构见 scripts/flomo_client.py 的 load_token()：mcpServers.flomo.headers.Authorization
cat > .mcp.json <<'JSON'
{"mcpServers":{"flomo":{"url":"https://flomoapp.com/mcp",
  "headers":{"Authorization":"Bearer fmcp_xxxxx"}}}}
JSON

token 解析优先级：.mcp.json 优先，环境变量 FLOMO_TOKEN 仅作后备。两处都没有时，所有脚本命令都会以非 0 退出并打印「未找到 flomo token」——看到该提示即说明下面所有示例都还没到执行阶段。

执行写卡

发送链接给 AI 助手，助手按 9 步 SOP 执行：

1. 抓取 — fetch_article.py 取页并抽正文（webfetch 为主，SPA 补 curl）；抓回即读回全文
2. 验证 — 专业术语/机构/产品/模型简称必须 search 现查（阻塞；结果留痕 verify.json）。先用环境自带的搜索工具；不可用时才用 search_web.py 兜底（它按「查询词块是否真出现在结果里」判定这一路可信，不信就换下一个引擎）
3. 提炼 — 滤营销话术，留事实/数据/因果链
4. 定标签 — tagcheck.py 现采标签树，核存在性与严格两级 #顶层/二级（阻塞）
5. 查重 — dedup.py 关键词逐次现查；闸门另按标签簇整簇翻页比对概念名，同名即阻塞（批量轮次也逐条查）
6. 写作 — 按卡片格式写作
7. 自检并写云 — publish.py --draft --verify 一条链跑完闸门 → 质检 → 写云（只发一次）→ 写后复核；改既有卡加 --update-id（阻塞）
8. 复盘 — dedup.py --id 定向复查近邻，verify_card.py --show-body 打全文做人读自查
9. 更新云端 — 改既有卡同样走这条链的 --update-id （写前确认概念名、写后给覆盖差异）；标签改名用 tag_rename

---

项目结构

flomo-note/
├── SKILL.md / AGENTS.md / ENVIRONMENT.md   # 细则 / 总则 / 环境事实（三份各有唯一职责）
├── scripts/     # 工具：写卡流程、文档自检、控制台后端 —— 逐个职责见下表
├── tests/       # 回归用例 test_*.py，各自用 COVERS 声明它验的是哪些脚本，全离线
├── web/         # 项目控制台前端静态资源（index.html / styles.css / app.js）
├── .github/workflows/ci.yml   # 每次推送/PR 跑同一条 run_tests.sh（不配 secrets）
├── .gitignore                 # 忽略凭据、本机私有导出与现采缓存
└── README.md

树只说位置，职责只在下表。此前树里给每个文件挂注释、表格里再写一遍职责，同一件事有两处描述——改一处忘另一处就会出现「树里说 A、表里说 B」，而没有任何检查会发现。现在文件清单的唯一事实源是下表。

工具在 scripts/，用例在 tests/：判据是「它是不是交付物」——用例不进任何写卡流程，只用来验证流程脚本。混在一层里会让 scripts/ 看不出哪些是入口，改脚本时也容易误以为用例也能直接跑进流程。

文档（唯一事实源）