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. 抓取 — webfetch 为主，SPA 补 curl；抓回即读回正文
2. 验证 — 专业术语/机构/产品/模型简称必须 search 现查（阻塞；结果留痕 verify.json）
3. 提炼 — 滤营销话术，留事实/数据/因果链
4. 定标签 — tag_tree 现采，严格两级 #顶层/二级（阻塞）
5. 查重 — memo_search 关键词 + tag_tree 同主标签逐条比对，两路并查（阻塞）
6. 写作 — 按卡片格式写作
7. 写云前自检 — 先过流程闸门 sop_gate.py，再过文本质检 validate_memo.py，均 EXIT=0 才许写云（阻塞）
8. 复盘 — 三路现查（memo_search + tag_tree + memo_recommended 传本卡 id）
9. 更新云端 — memo_update 覆盖式或 tag_rename

---

项目结构

flomo-note/
├── AGENTS.md                  # 项目总则（顶层目标与全局约定）
├── SKILL.md                   # 执行细则（唯一细则源）
├── ENVIRONMENT.md             # 运行环境事实（路径、代理、通道）
├── web/                       # 项目控制台前端（Claude 风格，静态资源）
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── scripts/
│   ├── memo_util.py           # 签名/指纹/关键词 唯一实现
│   ├── flomo_client.py        # flomo MCP 调用唯一入口
│   ├── sop_gate.py            # SOP 流程闸门（代跑核对/查重/复盘，出凭证）
│   ├── validate_memo.py       # 写云前文本质检 + 闸门凭证校验
│   ├── check_skill_docs.py    # 技能文档内容纪律自检
│   ├── sni_fetch.py           # SNI 被阻断时的取件通道
│   ├── extract_arxiv_html.py  # arXiv HTML 正文抽取
│   ├── cleanup.py             # 收尾强制清理残留（文件与目录）
│   ├── git_tunnel.py          # GitHub 本地透传通道
│   ├── push_skill.sh          # 文档改动强制推送
│   ├── serve_console.py       # 控制台本地服务（静态文件 + JSON 接口）
│   ├── console_cloud.py       # 控制台云端只读访问（白名单 / 字段精简）
│   ├── console_data.py        # 控制台本地数据抽取（供上面两者共用）
│   ├── run_audit.sh / audit_skill.sh    # 技能文档结构审计
│   ├── run_tests.sh           # 一键跑全部离线回归
│   └── test_*.py              # 各脚本配套回归用例
├── .gitignore                 # 忽略凭据与现采缓存
└── README.md                  # 本文件

---

项目控制台

控制台把云端 MCP 的能力接出来——不只列出来，而是在页面上直接可用。分四个视图：

python scripts/serve_console.py            # 启动，默认 http://127.0.0.1:8787
python scripts/serve_console.py --open     # 启动后自动开浏览器
python scripts/serve_console.py --port 9000

服务在启动那一刻加载脚本模块，改了脚本要重启进程才生效。端口已被占用时启动会 直接报错退出：两个实例同时监听同一端口会让页面内容时新时旧，极难排查。

页面按需拉 /api/*：

写与「带参数执行」走 POST：

POST 上只有两类用途：改动云端的写接口，与 /api/cloud/tool 这个带参数跑读工具的入口。 没有「执行命令」「跑脚本」的位置。

tag 参数须给完整标签路径（如 AI/RAG）：云端不接受裸顶层名（传 AI 查不到）。 memo_search 单次返回受云端上限约束（上限值由接口给出），到顶时界面会提示改用关键词、 标签或日期继续筛。日期须为 YYYY-MM-DD 且真实存在——云端对不合法日期不报错， 只返回 0 条，界面因此在本地先拦一道，避免这种静默空结果。

云端访问全部收敛在 console_cloud.py，三条边界：

• 两套白名单：读只放行 READONLY_TOOLS、写只放行 WRITE_TOOLS，两个集合分别恰等于 各方法实际调用的工具（回归用例按源码扫描 + write=True 标记锁定，不留无人使用的权限空位）； 读路径上写工具一律拒（不带 write=True 放不出写请求），白名单外的任何工具名一并拒；
• 不落盘（H26）：卡片正文只在进程内存与 HTTP 响应之间传递，不写缓存、不写访问日志； 唯一例外是流程闸门要求的当轮草稿（memo_body*.txt），由收尾清理按近轮窗口回收；
• token 不出进程：凭证只在建连时使用，响应里只有「可用 / 不可用」这一事实。

写不是直通：写卡须走格式闸门与流程闸门（见 SKILL.md），控制台把这两道闸门做成 可操作的步骤而不是绕开它——POST /api/cloud/validate 报待修项，POST /api/cloud/gate 现跑 sop_gate.py 出凭证，写入后一律按 id 回读全文验收（H1 / H2 / H11），更新前还要 先回读原文（H22）。任一闸门不过即 ERR 阻断，一个字节都不会发到云端。写工具因此不走 能力页的通用执行入口，只在「云端笔记」（新建 / 编辑）与「标签」（重命名）两个过闸门的 专属入口发生。

标签树只在云端、本地不留快照：控制台不缓存标签树，每次现采云端， 避免「界面显示的标签与云端实际不一致」这类漂移。

---

卡片格式（骨架示意）

#标签/二级
概念名称

直接写结论句，不带任何模板前缀。

要点：
- 要点一（依据）
- 要点二

结构只有三层：首行标签段 → 第二行概念名 → 空一行 → 正文。判据不在本文件复述，一律查 SKILL.md 编号： 格式骨架 H14、无来源无状态 H15、无载体信息 H16、标签严格两级 H17/H18、 概念名须为名词短语（不含切片、不含谓语）H6b/H6d、材料不是概念时如何提取 H6c。 写前自检 scripts/validate_memo.py 会把这些判据逐条机械拦截，EXIT=0 才许写云。

本节历史上复写过一份规则摘要，已与 SKILL 分叉（缺 H6b/H6c/H6d 的概念名判据， 按旧摘要写卡会产出不合规签名，而签名是幂等查重与闸门凭证的共同依据）。 因此这里只留骨架示意，判据回到唯一源。

---

脚本工具

flomo_client.py

# 列出标签树（须拿全量）
python scripts/flomo_client.py tag_tree --file tag_tree_args.json   # {"limit":2000}

# 搜索 memo（参数为 JSON，形如 {"keywords":"...","limit":10}）
python scripts/flomo_client.py memo_search --file search.json

# 新建 memo（参数 {"content":"...","format":"markdown"}）
python scripts/flomo_client.py memo_create --file create.json

# 更新 memo（覆盖式，参数 {"id":"...","content":"..."}）
python scripts/flomo_client.py memo_update --file update.json

# 读全文（参数 {"ids":["..."]}）
python scripts/flomo_client.py memo_batch_get --file read.json

参数一律以 JSON 传入（--file 或内联 JSON 字符串），避免中文引号被转全角。

sop_gate.py（流程闸门）

# 术语卡：须先备好 verify.json（第 2 步网络搜索留痕）
python scripts/sop_gate.py --memo memo_body.txt --verify verify.json
# 更新场景可加 --anchor-id  作推荐锚点
# 确认非术语卡：用 --skip-web 替代 --verify（凭证中留痕 web_skipped）

闸门会代跑查重两路、复盘三路，全过后在 .sop_gate/ 落一份带正文指纹的凭证。退出码非 0 即未过，禁写云。

validate_memo.py

# 从文件读取并自检
python scripts/validate_memo.py memo_body.txt

# 从命令行参数读取 / 从 JSON 读取 content
python scripts/validate_memo.py --content "#标签/细分\n\n概念名\n\n正文..."
python scripts/validate_memo.py --create create.json

# 特殊场景降级（闸门问题转 WARN，常规写卡禁用）
python scripts/validate_memo.py --no-gate memo_body.txt

自检通过标准：EXIT=0（0 ERR）。闸门凭证缺失 / 签名不符 / 正文指纹不符 / 已过期 / 验证未执行，任一情形判 ERR 阻断写云。

---

工作流示例

graph LR
    A[用户发链接] --> B(webfetch 抓取)
    B --> C{抓取成功?}
    C -->|否| D[补 curl / search 替代来源]
    C -->|是| E[search 验证术语]
    E --> F[tag_tree 现采]
    F --> G[memo_search 关键词 + 同标签逐条 两路查重]
    G --> H{命中?}
    H -->|同事件| I[memo_update 合并]
    H -->|无重复| J[按格式写作]
    J --> K[sop_gate.py 流程闸门]
    K --> L[validate_memo.py 文本质检]
    L --> M{均 EXIT=0?}
    M -->|否| N[修正后重试]
    M -->|是| O[memo_create 写云]
    O --> P[memo_recommended 传本卡 id 复盘]

---

安全须知

• .mcp.json 含个人 Bearer token，已加入 .gitignore，不会入库
• 云端无删除 API（memo_delete 不存在），删除卡片只能在 flomo App 手动完成
• 清空卡片 = memo_update(content=' ')，属常规写云动作、免确认执行；会连带置空该卡标签，只挂在它上面的独占标签会从标签树消失——引用标签簇名前须现采 tag_tree

---

License

MIT License — 见 LICENSE 文件。

此前徽章曾指向一个不存在的文件（属错误陈述），现 LICENSE 已补齐，徽章与文件一致。