Flomo

flomo

使用 flomo MCP 查询、创建、更新、导入、去重和整理笔记。

什么时候使用

当用户需要以下操作时使用本技能：

• 搜索或汇总 flomo 笔记。
• 按关键词、标签、日期或 id 获取笔记全文。
• 创建或更新 memo。
• 从粘贴文本、PDF、TXT 或 MD 导入笔记。
• 通过官方 WeRead API skill 同步微信读书高亮和笔记。
• 导入前检查重复内容。
• 复用、整理或批量重命名标签。
• 清理 OCR 造成的标点、断句或重复笔记问题。

MCP 工具

优先使用 flomo MCP 完成笔记查询、笔记创建、笔记更新、标签查询和格式规范读取。

常用工具：

• memo_search
• memo_batch_get
• memo_create
• memo_update
• tag_search
• tag_tree
• tag_rename
• get_format_guide
• get_tag_guide

核心能力

• 按关键词、标签、日期或 id 查询笔记。
• 用基于时间窗口的分页方式批量读取笔记，每页不超过 50 条。
• 从粘贴文本或标准化 memo 块创建单条笔记。
• 从 PDF、TXT 或 MD 导入笔记。
• 通过官方 WeRead API skill 同步微信读书高亮和笔记。
• 当笔记边界不确定时，用版面感知提取、页面渲染检查和预览模式解析 PDF 笔记导出。
• 创建笔记前检查精确重复。

工作流

1. 先判断请求属于查询、创建、导入、去重，还是 OCR 标点清理。
2. 将输入标准化为 memo 块；如果来源中有时间，保留来源时间。
3. 写入前先从现有标签树解析目标标签。
4. 需要去重时，先查询已有笔记。
5. 批量读取时，每页保持在 50 条以内，并使用时间窗口分页。
6. 跳过精确重复项，并报告被跳过的内容。
7. 缺少标签时，最多建议两个现有匹配标签。
8. 如果没有合适的现有标签，创建新标签前先确认。
9. 只有当前暴露的 memo_create schema 支持 created_at 时，才传入来源时间；否则在预览中保留来源时间，并询问是否接受使用服务器当前时间写入。
10. 多笔记输入批量导入前，先验证一个样本项。
11. 对诗歌或对换行敏感的笔记，只使用 LF (\n) 换行；不要使用 CRLF (\r\n) 或字面量反斜杠 n。
12. 除非来源中明确存在换行或段落断开，否则将相邻行合并到同一段。
13. 多条来源笔记共享同一日期时，在预览元数据里保留按顺序调整后的来源时间；如果当前 MCP 不支持写入 created_at，不要暗示 flomo 已保留这些时间。
14. 如果来源片段在视觉上是灰色的用户批注，最终笔记正文前加 批注：。
15. 对微信读书同步路径，阅读 references/wechat-reading.md，并不要把本地 Markdown 导出解析当成该路径。

PDF 解析

PDF 导入或 PDF 派生笔记重建时使用这个流程。

1. 当笔记顺序、日期或段落边界重要时，优先使用版面感知提取，而不是普通纯文本提取。
2. 如果提取文本包含乱码、私用区字符、表格碎片、重复截断或明显破损的行，不要直接从该文本层写入。
3. 当内容保真度不确定时，渲染代表性页面并与提取文本对照；OCR 只作为验证或补救手段，不用于猜测缺失内容。
4. 按明确的来源锚点拆分笔记，例如日期、标题、分隔符或重复的笔记卡片结构。边界仍不确定时，切换到预览模式并展示拟拆分结果。
5. 重建换行段落时，合并相邻行；除非来源明确表示真实段落断开、列表、诗歌或其他有意换行。
6. 来源日期可用时在预览元数据中保留来源日期；多条笔记共享同一自然日时，按来源顺序安排递增的来源时间，但写入仍取决于 memo_create 是否支持 created_at。
7. 跳过明显的提取噪声，例如图表标题、孤立表格单元格、重复片段或畸形行，不要强行写成 flomo 笔记。
8. 批量写入多笔记 PDF 前，先创建或预览一个代表性样本，验证标签、时间戳、段落重建和笔记边界行为。

OCR 标点清理

当某个标签下的导入书摘反复出现 OCR 标点错误时使用，例如数字或拉丁字母被误识别成中文标点。

1. 先用 memo_search(tag=..., has_tag=true, limit=...) 读取目标标签全文；如果结果可能不完整，先分页或扩大检索范围再编辑。
2. 比较内容或判断疑似重复时，忽略重复出现的书名和章节标题样板文本。
3. 扫描返回笔记中的反常符号，并结合当前标签语料和局部句意推断替换规则。
4. 先生成逐条笔记的编辑清单，只用 memo_update 更新高置信度修复项；保留原标签行和时间戳。
5. 不要在来源可能承接上文的地方凭空补标点，例如以闭引号开头的笔记。
6. 编辑后重新读取同一标签，确认已发现的坏符号模式消失。语义搜索结果可能有噪声，最终验证优先使用完整标签重读和人工检查。
7. 报告检测到的映射、已更新笔记数量，以及保留下来的模糊问题。

具体规则

• 不要每次请求都检查实时 MCP 服务 schema；优先使用当前 thread 暴露的工具 schema，除非参数被拒绝、被忽略或返回结果与预期矛盾。
• 如果 memo_create 暴露了 created_at，传入标准化后的来源时间，并在样本笔记返回后核对 created_at。
• 如果 memo_create 没有暴露 created_at，在预览中保留来源时间，并在每个明确批次写入前请求一次人工确认，确认是否接受使用服务器当前时间。
• 当前时间 fallback 被确认后，串行创建笔记。每次 memo_create 成功响应后至少等待 1 秒，再发送下一条创建请求。不要并行创建批量笔记。
• 如果时间参数被拒绝、被静默忽略，或返回时间不一致，停止批次并检查详细 MCP schema 或服务行为；不要继续重试写入。
• 不要用浏览器自动化或私有 API 绕过 MCP schema 来回填时间戳。
• 去重或写入前，将换行统一为 LF。
• 重复比较应使用最终将写入的正文，而不是原始来源文本。
• 只有精确标准化匹配才能自动跳过。
• 如果笔记只是相似，报告为可能重复，不要静默跳过。
• 标签片段中的空格和禁用标点替换为 _。
• 标签片段中移除书名号 《》 和引号 “” 等书名/引用标点，而不是保留。
• 标签中不要使用 emoji。
• 保留用户要求的标签路径，除非来源格式定义了更严格的目标规则。
• 格式很重要时，先读取 flomo 格式规范再组织最终正文。
• 优先重建段落，而不是机械保留来源换行；除非来源明显使用独立段落或诗歌式有意换行。
• 多条提取笔记落到同一自然日时，在 +08:00 时区内按来源顺序为预览元数据分配 00:00、00:01、00:02 等来源时间；不要在不支持 created_at 的写入面承诺回填。
• 来源样式影响语义时，用 批注： 前缀保留灰色批注含义，不尝试保留原始颜色。

确认检查点

• 创建新的顶级标签或分类前，先停止并确认。
• 笔记相似但不是精确重复时，先停止并确认。
• 来源解析混乱到可能拆错笔记边界时，先停止并确认。
• 批量重命名或批量更新大量笔记前，先展示计划和样本。
• 来源时间无法写入时，使用服务器当前时间前先停止并确认。
• 一个确认可以覆盖边界清晰的批次；不要对同一批次的每条笔记重复确认。
• 多笔记导入时，先确认一条样本笔记，再继续写入其余内容。
• 样本笔记必须用 memo_create 成功写入后，才能继续任何批量导入。

失败处理

• 对传输错误、超时和 5xx 失败，使用短暂退避重试。
• 对认证失败、校验失败或用户明确拒绝，不要原样重试。
• 来源文件无法可靠解析时，切换到预览模式，不要猜测。
• 如果某页在时间窗口分页后仍返回 50 条，缩小窗口后再继续。
• 如果客户端显示 Auth required，先执行 MCP/Auth 恢复流程，再重试写入。

MCP/Auth 恢复

当 memo_search、tag_search、memo_create 或 memo_update 返回 Auth required、401 Unauthorized、陈旧传输错误或批处理中途工具失败时，使用这个流程。

1. 立刻停止盲目重试；重复的同样调用可能造成重复写入，或掩盖真实失败点。
2. 切换线程或重启前，记录当前操作、目标标签、最后成功的 note id、失败的 memo id 或来源项，以及任何本地预览产物。
3. 区分失败类型：
   • 配置缺失：Codex 配置中没有 flomo MCP server。
   • 线程/会话陈旧：一个线程失败，但新线程或其他当前线程仍能调用 flomo MCP。
   • 全局认证过期：新线程也返回认证错误。
4. 对线程/会话陈旧问题，在新线程或 Codex 重启后从记录的失败项继续；如果前面的写入已经成功，不要重跑整个标签或来源文件。
5. 对全局认证过期，等待重新授权或重新连接，再从记录的检查点继续。
6. 恢复后，继续写入前先重读受影响的标签或 ids，避免重复创建或重复更新已处理笔记。
7. 长批量操作中，每次成功写入或移动来源文件后保留轻量检查点，方便后续从最后未完成项继续。

输出约定

• 查询请求：先返回紧凑结果，包括 id、created_at、tags 和短摘录。
• 创建或导入请求：报告已创建、已跳过或被阻塞的内容。
• 去重检查：区分精确重复和可能的近似重复。
• 如果对标签、日期或笔记拆分做了假设，要明确说明。

来源特定规则

• 普通粘贴文本、TXT 或 Markdown：一条笔记对应一个 memo 块，并在来源日期存在时保留日期。
• 通用 PDF 导入：合并相邻换行来重建段落，除非能看出真实段落或换行边界。
• 通用 PDF 导入：按检测到的日期锚点拆分为多条笔记；多条笔记共享同一日期时，在预览元数据里按来源顺序每条递增 +1min。
• 通用 PDF 导入：将灰色批注文本转换为普通文本，并加 批注： 前缀。
• 微信读书同步：导入前先阅读 references/wechat-reading.md。
• 微信读书同步：通过官方 WeRead API skill 获取笔记，不要把本地 Markdown 导出解析当成该路径。
• 微信读书同步：每条笔记正文第一行写章节名，正文中间留一个空行，最后加目标标签。
• 微信读书同步：不要添加书名、作者、来源链接、API 元数据或额外标签。
• 微信读书同步：在预览元数据中保留来源高亮/笔记时间。只有当前 create schema 支持 created_at 时才用作写入时间；否则执行已确认的当前时间 fallback 和 1 秒串行间隔。
• 微信读书同步：从自己的阅读笔记标签树解析目标标签；如果分类或书籍级标签没有清晰现有匹配，停止确认。

查询细节

• 按关键词、标签或日期过滤发现笔记时，先用 memo_search。
• 只有已知 ids 且需要全文时，才用 memo_batch_get。
• 读取大量笔记时，每页保持在 50 条以内，并使用时间窗口分页。
• 如果结果正好等于限制值，假设可能被截断，继续分页。

标签操作

• 标签名直接写在正文中，例如 #读书/心理学。
• 批量改标签路径时，优先使用 tag_rename，不要逐条 memo_update，除非正文也需要改。
• 重命名前先读取 get_tag_guide 和目标标签树。
• 重命名后重新读取标签树，验证旧路径消失、新路径存在。

脚本

可用时复用这些辅助脚本：

• scripts/flomo_common.py
• scripts/flomo_create.py
• scripts/flomo_query.py
• scripts/normalize_input.py
• scripts/paginate_by_time.py
• scripts/dedup_notes.py
• scripts/test_flomo_create.py