Flomo Importer Enhanced

☕️ Make Flomo Memos to Obsidian Notes.

Version 2.4.4 - Enhanced fork from jia6y/flomo-to-obsidian with major improvements

Author: springrain | 公众号: 及时春雨
GitHub: https://github.com/springrain1

• Original Discussion: Discussion
  

🎉 What's New in Version 2.4

�️ WAF Bypass & Background Sync

• Smart WAF Bypass: Defeats Flomo's new anti-bot "403 Forbidden" detection by spoofing standard Chrome User-Agents
• True Silent Sync: Export process runs completely in the background without opening visible browser windows
• Debug Mode: Toggle visible browser windows and verbose logging in settings when troubleshooting is needed

🏷️ Tag-Based Filtering

• Selective Sync: Choose to sync only memos containing specific tags (e.g., #Work #Important)
• Ignores other memos, keeping your Obsidian vault focused and clean

📁 Simplified Attachment Structure

• Old: flomo picture/file/2025-11-03/4852/filename.m4a ❌
• New: flomo attachment/2025-11-03/filename.m4a ✅
• Cleaner, flatter directory structure
• All attachment types supported (images, audio, video)

🔄 Smart Content Update Detection

• Automatically detects when you edit memos in Flomo
• Re-imports updated content without manual intervention
• No duplicates, just the latest version

🗑️ Reset Sync History

• New button in settings to clear sync history
• Useful when changing attachment paths or re-importing
• Shows sync statistics (last sync time, memo count)

⚙️ Dynamic Path Configuration

• Attachment paths now respect your "Flomo Home" setting
• Fully customizable based on your preferences

All Features

• ✅ Auto Sync On Startup & Hourly Auto Sync & Adhoc Sync
• ✅ NEW: Tag-Based Filtering (Sync only specific tags)
• ✅ NEW: Smart WAF Bypass for Background Sync
• ✅ NEW: Debug Mode for Troubleshooting
• ✅ NEW: Smart content update detection
• ✅ NEW: Simplified attachment structure
• ✅ NEW: Reset sync history button
• ✅ Customize target import location
• ✅ Support highlight mark
• ✅ Optional: Create Flomo Canvas (with content | file link)
• ✅ Optional: Create Flomo Moments
• ✅ Experimental: Support Bi-directional Links in memos
• ✅ Experimental: Merge Memos by date

功能详解 (Features in Detail)

This plugin offers several ways to import and manage your Flomo notes within Obsidian:

• 多种同步方式 (Multiple Sync Methods):
  • 启动时自动同步 (Auto Sync On Startup): Enable this in settings to automatically sync when Obsidian starts.
  • 每小时自动同步 (Hourly Auto Sync): Enable this in settings for automatic background sync every hour.
  • 手动同步 (Adhoc Sync / Manual Sync):
    • 自动导出与导入 (Auto Export & Import): Click the "Sync Now" button in the plugin UI. This uses Playwright to log in to Flomo, export your notes as HTML, and import them.
    • 手动导入 (Manual Import): Export your notes as HTML (flomo_backup.zip) from the Flomo website yourself, then select the zip file in the plugin UI to import.
• 增量同步 (Incremental Sync): The core feature. The plugin intelligently identifies and imports only new memos since the last sync, preventing duplicates. It remembers which memos have been imported.
• 自定义导入位置 (Customizable Import Location): Specify the target folder in your Obsidian vault for imported Flomo notes (Flomo Target) and a subfolder for individual memos (Memo Target).
• 支持高亮标记 (Highlight Support): Correctly converts Flomo's <mark> tags to Obsidian's ==highlight== syntax.
• Obsidian 集成 (Obsidian Integrations):
  • Flomo Canvas: Optionally generates an Obsidian Canvas file visualizing your memos, either linking to the memo files or embedding the content directly.
  • Flomo Moments: Optionally generates a Flomo Moments.md file that embeds links to all imported memo files, providing a chronological overview.
• 实验性功能 (Experimental Features):
  • 双向链接支持 (Bi-directional Link Support): Attempts to preserve [[wiki-links]] within your memo content during import.
  • 按日期合并笔记 (Merge Memos by Date): Option to merge all memos from the same day into a single Obsidian note, separated by ---.

代码库结构 (Codebase Structure)

The project is organized as follows:

esbuild.config.mjs  # Build configuration for esbuild (compiles TS to JS)
main.ts             # Plugin entry point: loads settings, adds commands/icons, initializes UI and auto-sync
manifest.json       # Plugin metadata (name, version, author, etc.)
package.json        # Project dependencies and npm scripts (build, dev, version)
styles.css          # Custom CSS styles for the plugin UI
versions.json       # Version history (used by BRAT)
lib/                # Core logic directory
  flomo/            # Flomo-specific functionalities
    auth.ts         # Handles authentication logic (likely using Playwright)
    const.ts        # Defines constants (like cache paths, filenames)
    core.ts         # Core data processing: parses HTML, identifies memos, generates IDs for incremental sync
    exporter.ts     # Handles exporting data from Flomo (using Playwright)
    importer.ts     # Handles importing data into Obsidian: reads files, uses FlomoCore, writes notes
  obIntegration/    # Obsidian-specific integrations
    canvas.ts       # Logic for generating the Flomo Canvas file
    moments.ts      # Logic for generating the Flomo Moments file
  ui/               # User Interface components
    auth_ui.ts      # UI modal for Flomo authentication
    common.ts       # Shared UI helper functions or components
    main_ui.ts      # Main plugin settings and action UI modal
    manualsync_ui.ts# UI section/modal for manual zip file import
    message_ui.ts   # UI components for displaying messages/notices
node_modules/       # Installed npm dependencies

同步逻辑详解 (Synchronization Logic Explained)

Understanding how synchronization works, especially incrementally:

1. 触发 (Trigger): Sync can be triggered automatically (on startup, hourly timer via main.ts) or manually (clicking "Sync Now" in main_ui.ts or using the "Sync Flomo Now" command).
2. 导出 (Export - Auto Sync/Sync Now Button):
   • The FlomoExporter utilizes Playwright (a browser automation tool) to:
     • Log in to your Flomo account (using credentials potentially stored securely).
     • Navigate to the export page.
     • Download the full backup as an HTML file (saved to a location defined in const.ts, e.g., DOWNLOAD_FILE).
3. 导入入口 (Import Entry Point):
   • The FlomoImporter class is instantiated.
   • The importFlomoFile method is called, passing the path to the downloaded HTML file (DOWNLOAD_FILE).
4. 数据读取与解析 (Data Reading & Parsing):
   • FlomoImporter reads the HTML file content.
   • It calls FlomoCore's constructor, passing the HTML data and the list of already synced memo IDs (syncedMemoIds) loaded from the plugin's saved settings (this.settings.syncedMemoIds).
5. 核心处理与增量识别 (FlomoCore):
   • The constructor parses the HTML structure.
   • The loadMemos method iterates through each memo element (<div class="memo">).
   • Crucially for Incremental Sync: For each memo found in the HTML, a unique memoId is generated. This ID is based on a combination of:
     • The memo's exact timestamp.
     • A hash of its content (title, body, attachments).
     • A counter for memos with the exact same timestamp (to differentiate them).
     • An overall sequential counter.
   • This generated memoId is compared against the syncedMemoIds list received from the settings.
   • If the ID is NOT in the list: It's considered a new memo. Its memoId is added to the instance's syncedMemoIds list, newMemosCount is incremented, and the memo's data is added to the memos array to be processed.
   • If the ID IS in the list: It's skipped.
6. 写入 Obsidian (FlomoImporter.importFlomoFile):
   • The method receives the processed data from FlomoCore, including the list of only the newly identified memos.
   • It groups these new memos by date.
   • Based on the "Merge Memos by Date" setting, it writes the content of each new memo (or merged content) to the appropriate file path within the specified Flomo Target and Memo Target folders in your vault.
   • It potentially calls generateMoments and generateCanvas if enabled.
7. 状态保存 (State Saving - main.ts):
   • After importFlomoFile completes, the plugin calls saveSettings().
   • This saves the updated syncedMemoIds list (which now includes the IDs of the newly imported memos) and the current lastSyncTime back into Obsidian's persistent storage for this plugin. This ensures the next sync knows about these newly added memos.
8. 通知 (Notification): A notice is displayed indicating how many memos were found and how many were newly imported.

This detailed ID generation and checking process is the key to reliable incremental synchronization, ensuring only new content is added to your Obsidian vault.

开发与修改指南

开发环境设置

1. 克隆仓库
2. 安装依赖：npm install
3. 安装Playwright (必需)：npx [email protected] install

修改模板和格式

如果需要修改导入的笔记格式或模板:

• 编辑 lib/flomo/importer.ts - 负责将Flomo笔记转换为Obsidian格式
• 编辑 lib/obIntegration/moments.ts - 修改Moments功能的显示方式
• 编辑 lib/obIntegration/canvas.ts - 修改Canvas展示格式

修改UI

• UI相关的修改主要集中在 lib/ui/ 目录下
• 样式修改可以在 styles.css 文件中进行

构建项目

• 开发模式 (实时编译): npm run dev
• 生产构建: npm run build
• 构建后的文件为 main.js

版本管理

• 版本更新: npm run version
• 版本信息在 manifest.json 和 versions.json 中定义

First time to use it?

Install Dependency

• Playwright (MUST HAVE) : npx [email protected] install
• (this plugin was pre-built with version 1.43.1)

Install And Enable the plugin

• Install Flomo Importer and enable it.

  

• Use the command Open Flomo Importer, or use Import Button

  

Auto Sync

• Click on "Auto Sync"

  

• Authentication is required if the first time syncs or the current sign-in expires.

  

• Exporting & Importing

  

Adhoc Sync

📦 Export from Flomo

• Go to Account Details

• Select Export All (as HTML)

  

• Click on Start to export

🎯 Import to Obsidian

• Choose flomo.zip to Import. The Flomo & Memo Home is where to store your memos.

• A Notice pops up when the import is completed.

• Checkout Flmomo Moments and Flomo Canvas 🌅

  

🔄 Upgrading from Version 1.x to 2.0

If you're upgrading from an older version, the attachment path structure has changed. You have two options:

Option A: Clean Re-import (Recommended)

1. Open Flomo Importer settings
2. Click the "Reset Sync History" button
3. Manually delete these old folders in your vault:
   • [Flomo Home]/memos/ (e.g., flomo/memos/ or 10 flomo/memos/)
   • [Flomo Home]/flomo picture/ (if exists)
4. Run sync again
5. All memos and attachments will be re-imported with the new, cleaner structure

Option B: Keep Existing Memos

1. Just sync normally
2. Only new memos will be imported with the new attachment structure
3. Old memos keep their old attachment paths
4. Result: Mixed structure, but nothing breaks

Note: Content update detection works automatically. If you edit a memo in Flomo after upgrading, it will be detected and re-imported.

Plugin Settings

You can customize the following options in the plugin settings page:

• Auto Sync On Startup: Automatically sync when Obsidian is launched.
• Auto Sync Interval: Automatically sync every hour.
• Incremental Sync: Skip already imported memos and only import new ones.
• Merge Memos by Date: Merge multiple memos from the same day into a single file.
• Flomo Target: Folder in Obsidian vault to store Flomo memos (default: flomo).
• Memo Target: Subfolder under Flomo folder to store individual memos (default: memos).
• Canvas & Moments Options: Select display options for Flomo Canvas and Moments.
• Reset Sync History: Clear all synced memo IDs to re-import all memos (useful after changing paths).