Business View
v1.2.0-stable

ENGINEERING
DATA SOVEREIGNTY.

逆向工程 Notion Internal API，實現超速資料遷移。
遞迴爬取、斷點續傳，文件優化以及全自動化的 Confluence 整合。

zsh — node-1
➜ ~ python crawl_notion_api.py
[INFO] Initializing reverse API connection...
[INFO] Authenticated as user_8a2d...
[INFO] Found 517 pages in workspace.
> Processing Page: 'API Specification' (ID: a1b2...)
> Recursively fetching children... [OK]
_

// README.md: THE_WHY

"In the era of AI & Vibe Coding, building tools is faster than ever. But Token costs and Time are real."

AI 大時代讓很多事情變的更快速更輕鬆，所以我們更必須計算 ROI，從真實痛點出發，而非為了 AI 而 AI。

我們必須找到問題點，然後評估是否划算，然後幹掉它：
手動遷移 500+ Notion 頁面 = 120+ 小時 無腦勞動。(每次成本)
開發爬蟲與自動化管道 = 一次性 開發成本 + 1 小時 執行)

這就是為什麼我們快速用 AI 寫工具程式：為了將人類從重複勞動中解放，去解決更困難的問題。

PERFORMANCE_METRICS

benchmark_result.json
MANUAL_MIGRATION (est.)
Time: 129.0 hrs
NOTION_CRAWLER (v1.2)
Time: 0.5 hrs
> Speedup Factor: 258x
> Data Integrity: 100%
> Memory Usage: <150MB (Streaming)

Exponential Efficiency

基於 500+ 個頁面的真實遷移數據測試。人工搬運不僅耗時 (預估 9 分鐘/頁)，且容易遺漏層級結構。 Notion Crawler 透過並行處理與自動化轉換，將數週的工作縮短至 1 小時內完成。

517
PAGES PROCESSED
0
DATA LOSS
258x
FASTER

SYSTEM_ARCHITECTURE

Notion Crawler System Architecture Diagram showing Recursive Crawler, Markdown Transpiler, and Confluence Integrator data flow

Recursive Crawler Engine

  • Reverse Internal API：直接串接 `loadPageChunk` 取得結構化 Block 資料，速度比 Playwright 快 10 倍。
  • 遞迴遍歷 (Recursive)：自動解析子頁面 (Sub-pages) 與 Database Rows，精確保留無限層級結構。
  • 反偵測機制：實作 Exponential Backoff 與 Jitter 隨機延遲，有效規避 429 Rate Limit。

Markdown Transpiler

  • AST 解析：將原始 JSON 解析為抽象語法樹，確保 Table, Callout, Code Block 等複雜元件精確渲染。
  • Knowledge Stitcher：自動識別並縫合分散的 API 參數頁面 (Input/Output/Schema)，重組為單一 Truth。

Resilience & Failover

  • Dual-Domain Failover：優先嘗試 `notion.so`，遇錯自動切換至 `notion.site` 鏡像域名，確保 99.9% 可用性。
  • Connection Pooling：使用 `requests.Session` 維持 TCP 連線池，減少 TLS 握手開銷，提升大量爬取效能。
  • Granular Checkpoints：SQLite/JSON 記錄 Page ID 狀態，實現 100% 斷點續傳。

Confluence Integrator

  • BFS Traversal：採用廣度優先策略上傳，確保父頁面絕對優先於子頁面建立，避免 Orphan Pages。
  • Smart Transform：自動將 Mermaid 區塊轉換為 Confluence Macro，並修復頁面間的相對連結 (Internal Links)。
  • Auto-Root Management：自動在 Space 根目錄建立 `Notion_KB`，支援 `--clean` 遞迴刪除以進行乾淨重部署。

Legacy Mode (Fallback)

  • Playwright Renderer：完整瀏覽器模擬，透過 DOM 解析 Breadcrumb 決定路徑，解決 API 無法處理的特殊 Edge Case。
  • Interactive Crawling：支援 Auto-Scroll 觸發 Lazy Loading、自動展開 Toggle、載入 Database。
  • Stealth Mode：使用 Headed 模式與隨機延遲 (3-10s) 繞過 Cloudflare 驗證。

Test Suite (Quality Gate)

  • 130 Unit Tests：使用 pytest 覆蓋三大核心模組的純函式、渲染邏輯與合併策略，確保每次變更不破壞既有行為。
  • Zero-IO Pure Testing：RichText 轉換、Block 渲染、標題消歧等核心邏輯皆為純函式測試，無需 Mock 外部服務。
  • Filesystem Isolation：合併與樹建構測試使用 pytest tmp_path fixture，完全隔離不污染真實檔案系統。

DEV_EXPERIENCE (DX)

開發者的時光機：快速迭代工具
// DEBUG MODE: OFFLINE
enable --offline-replay
> Loading snapshot `dump_20250131.json`
> Mocking API responses...
> Ready. (0ms latency)
Offline Replay

開發解析邏輯時直接讀取本地 Snapshot，完全無需聯網，讓迭代速度提升 100 倍。

// PRE-FLIGHT CHECK
run --dry-run
> Simulating write operations...
> [SKIP] POST /wiki/rest/api/content
> No changes applied.
Dry Run Mode

模擬轉譯與上傳流程，只輸出日誌而不執行寫入，確保與現有 Confluence 資料無衝突。

// ERROR RECOVERY
status --checkpoints
> Pending: 42 pages
> Failed: 3 pages (Rate Limited)
> Resuming from last success...
Smart Resume

程式重啟時自動讀取 Checkpoint，跳過已成功 (Success) 的頁面，僅重試失敗項目。

CLI_COMMANDS

使用逆向 API 快速爬取，無需瀏覽器介面。適用於大批量資料抓取。

INPUT
python crawl_notion_api.py --token $NOTION_TOKEN_V2 --page $ROOT_PAGE_ID

將零散檔案合併為 API 文件，並啟動 MkDocs 本地伺服器預覽。

INPUT
python build_knowledge_base.py && mkdocs serve

自動讀取 output 目錄並上傳至指定 Space。`--source all` 代表全量上傳。

INPUT
python upload_to_confluence.py --source all --space ENGINEERING

FALLBACK_STRATEGY

PLAN B — WHEN API FAILS

Why We Need a Fallback

Notion 內部 API (loadPageChunk) 屬於非公開端點，隨時可能變更格式、加入驗證或限流。 若爬蟲被識別為自動化工具，API 請求將直接返回 403 或 429。

因此本專案內建 Playwright 瀏覽器模式作為完整備援方案： 以真實瀏覽器渲染頁面，完全繞過 API 層，確保在任何情境下都能完成資料遷移。

Headed Browser Mode
使用非 Headless Chromium 渲染，完整執行 JavaScript，繞過 Cloudflare Bot Detection。
Randomized Delay (3-10s)
每次請求間隔 3~10 秒隨機延遲，模擬人類瀏覽行為，避免固定節奏被偵測。
Auto-Scroll & Expand
自動觸發 Lazy Loading、展開 Toggle Block、載入 Database 完整列表，不遺漏任何內容。
Breadcrumb Path Resolution
解析頁面 DOM 中的 Breadcrumb 導覽列，精確還原頁面層級結構與儲存路徑。
crawl_notion.py — Playwright
$ python crawl_notion.py
[INFO] Launching Chromium (headed mode)...
[INFO] User-Agent: Chrome/131.0 (Windows)
[INFO] Navigating to notion.site/...
[INFO] Waiting 6.2s (random delay)...
[INFO] Auto-scrolling page content...
[INFO] Expanding 3 toggle blocks...
[INFO] Breadcrumb: Project > Auth > Login
[INFO] Saved: output/Project/Auth/Login.md
[INFO] Waiting 4.8s (random delay)...
[INFO] Processing next page...
_
API vs Playwright 比較
API Mode Playwright
速度 ~10 min ~3 hrs
反偵測 Header 偽裝 真實瀏覽器
API 依賴 非公開 API 零 API 依賴
Cloudflare 可能被攔截 完全繞過
斷點續傳 ✓ ✓
記憶體 <50MB ~500MB

TEST_SUITE

pytest — 130 tests across 3 core modules
130
TEST CASES
3
MODULES COVERED
0.3s
EXECUTION TIME
100%
PASS RATE
pytest -v --tb=short
$ pytest -v --tb=short
======================== test session starts ========================
collected 130 items
 
test_crawl_notion_api.py::TestSanitizeFilename::test_basic PASSED
test_crawl_notion_api.py::TestRichTextConvert::test_bold PASSED
test_crawl_notion_api.py::TestApplyDecorations::test_equation PASSED
test_crawl_notion_api.py::TestBlockToMarkdown::test_table_2x2 PASSED
test_build_knowledge_base.py::TestStripH1::test_removes_h1 PASSED
test_build_knowledge_base.py::TestMergeStandardSplit::test_basic PASSED
test_upload_to_confluence.py::TestEscapeXml::test_ampersand PASSED
test_upload_to_confluence.py::TestConvertMd::test_mermaid PASSED
... 122 more passed ...
 
======================== 130 passed in 0.32s ========================
MODULE COVERAGE
crawl_notion_api.py 44 tests
RichTextConverter • BlockToMarkdown • sanitize_filename • page ID helpers
upload_to_confluence.py 34 tests
_escape_xml • PageNode tree • title conflicts • MD→Confluence conversion
build_knowledge_base.py 32 tests
strip_h1 • extract_api_meta • Mermaid generators • merge functions (tmp_path)
TEST CATEGORIES
Pure Functions ~50
Rich Text Parsing ~27
Block Rendering ~16
File Merge (I/O) ~9
Tree Building ~12
MD→Confluence ~5
RUN TESTS
pip install pytest && pytest -v --tb=short