enhancement: import-markdown CLI 過程監控 — 預設顯示相關 log

[jlin53882]

標題

enhancement: import-markdown CLI 過程監控 — 預設顯示相關 log

分類

enhancement / CLI

嚴重程度

low（功能正常運作，但缺少過程監控）

問題描述

import-markdown CLI 執行時缺乏過程 log，使用者無從確認：

• 掃描到哪些檔案？
• 跳過了哪些項目？原因為何（長度不足、格式不符，去重命中）？
• 成功匯入了哪些？
• 失敗的原因是什麼？

目前祇有最後一行 Summary，無法追蹤進度。

預期行為

執行時能看到每個階段的相關 log，例如：

[scan] found 8 markdown files across 2 workspace(s):
  [scan] [agent-1] /path/to/agent-1/memory/2026-05-01.md
  [scan] [agent-2] /path/to/agent-2/memory/2026-05-01.md
[scan] reading: /path/to/agent-1/memory/2026-05-01.md
[scan] reading: /path/to/agent-2/memory/2026-05-01.md
[import] parsed 120 entries from 8 file(s)
[import] dedup check: enabled
  [skip] dedup [agent-1]: 記得買牛奶
[import] 115 entries need embedding (5 dedup hits)
[import] embedded batch 1/12 (10 entries)
[import] stored batch 1 (100 entries, total: 100)
...
Memory Import Status:
• Files found: 8
• Entries processed: 120
• Imported: 115
• Skipped (too short): 5
• Skipped (dedup): 5
• Embed batches: 12
• bulkStore calls: 2
• Elapsed: 3421ms

原則：相關 log 預設顯示，不需要 --verbose 之類的開關。

目前進度

✅ 已完成（PR #735）

實作內容	說明
Phase 1a	平行讀取多個檔案 (Promise.all) + [scan] found N files across X workspace(s): + 逐檔 [scan] [scope] filepath
Phase 1b	解析 bullet lines，收集至 allEntries + [scan] reading: filepath
Phase 2a	batchSize 控制並行 retriever.retrieve() 做 dedup check
Phase 2b	embedBatchPassage() + bulkStore() + FLUSH_THRESHOLD=100
--no-dedup	dedup 預設啟用，可用 --no-dedup 禁用
--batch-size	控制每批 embed 數量（預設 10）
backup dir	從 openclaw.json 的 home 欄位解析，fix path=undefined 當機
回傳值	skippedShort, skippedDedup, errorCount, elapsedMs
skipped 語意	dedup hit 同時計入 skipped 和 skippedDedup（PR #719 語意對齊）
Summary 格式	Memory Import Status: + Files found:、Entries processed:、Skipped (too short):、Skipped (dedup):、Errors:、Embed batches:、bulkStore calls:、Elapsed:
Dry-run summary	完整 Memory Import Status 格式 + [DRY-RUN] No entries were actually imported.
測試	19 tests pass, 0 fail ✅

❌ 已關閉（被 PR #735 吸收）

• PR fix(import-markdown): dedup by default + retrieve() + stats (#719+#720) #733（含 PR feat(import-markdown): --no-dedup by default, new return fields, unified summary (closes #715) #719 + PR fix(import-markdown): dedup uses retrieve() hybrid search (fixes rank-1 gap) #720）：已被 PR fix(import-markdown): batch pipeline Phase 1+2a+2b + retrieve() dedup + PR719 log alignment (#730+#732+#719+#720) #735 吸收。ctx.retriever.retrieve()、dedup stats、--no-dedup、scan/log 格式全部已在 PR fix(import-markdown): batch pipeline Phase 1+2a+2b + retrieve() dedup + PR719 log alignment (#730+#732+#719+#720) #735 的同一個 commit 樹中實作並對齊。
• PR feat(import-markdown): --no-dedup by default, new return fields, unified summary (closes #715) #719、PR fix(import-markdown): dedup uses retrieve() hybrid search (fixes rank-1 gap) #720：已關閉，內容已合併至 PR fix(import-markdown): dedup by default + retrieve() + stats (#719+#720) #733，隨後被 PR fix(import-markdown): batch pipeline Phase 1+2a+2b + retrieve() dedup + PR719 log alignment (#730+#732+#719+#720) #735 吸收。

完整實作對照表

功能	PR #719	PR #720	PR #733	PR #735
dedup 預設開啟	✅	—	✅	✅
--no-dedup flag	✅	—	✅	✅
retrieve() 取代 bm25Search	—	✅	✅	✅
skippedShort/skippedDedup/errorCount 回傳	✅	—	✅	✅
Log 格式對齊（[scan]、[skip] dedup [scope]:）	✅	—	✅	✅ 對齊
Phase 1 平行讀檔	—	—	—	✅
Phase 2a 批次 dedup	—	—	—	✅
Phase 2b 批次 embed + bulkStore	—	—	—	✅
batch-size 參數	—	—	—	✅
backup dir openclaw.json 解析	—	—	—	✅
skipped 包含 dedup hits（PR #719 語意）	⚠️	—	⚠️	✅ 對齊
Scan log（Phase 1a/1b）	✅	—	✅	✅ 對齊
Summary Memory Import Status: 格式	✅	—	✅	✅ 對齊

已知的後續優化方向

• Bloom Filter dedup：第二次跑同樣檔案時，bloom filter 可在 O(1) 內直接 skip，零 API 呼叫。尚未實作。（見 Issue enhancement: import-markdown CLI 過程監控 — 預設顯示相關 log #715 Comment rerankEndpoint属性没有加到openclaw.plugin.json里面 #3）

相關 Issue / PR

• 原始實作：PR feat: add import-markdown CLI command #426（feat: add import-markdown CLI command）
• Batch pipeline + dedup fix：PR feat(import-markdown): batch processing pipeline + test rewrite #730
• Backup dir fix：PR fix(backup): resolve backup dir from openclaw.json home field #732
• 最終合併 PR：fix(import-markdown): batch pipeline Phase 1+2a+2b + retrieve() dedup + PR719 log alignment (#730+#732+#719+#720) #735 ✅
• PR feat(import-markdown): --no-dedup by default, new return fields, unified summary (closes #715) #719 + fix(import-markdown): dedup uses retrieve() hybrid search (fixes rank-1 gap) #720 → PR fix(import-markdown): dedup by default + retrieve() + stats (#719+#720) #733（已關閉，被 fix(import-markdown): batch pipeline Phase 1+2a+2b + retrieve() dedup + PR719 log alignment (#730+#732+#719+#720) #735 吸收）
• 後續修復：PR fix(import-markdown): P0 missing return + register test in CI #482、PR fix(import-markdown): CI測試登記 + .md目錄skip保護 (#588) #589、PR fix(import-markdown): CI測試登記 + .md目錄skip保護 (Issue #588) #649
• 相關 Issue：[import-markdown] workspace-glob 導致 nested agent workspace 被略過 #484、fix(import-markdown): CI 測試未完整登記 + .md 目錄造成 import abort #588

[jlin53882]

補充：Issue #715 發現的關聯 Bug — Dedup 只檢查 BM25 第一名

Bug A（發現於 PR #482 review 後）

問題位置：cli.ts line 708-709

// 現有壞掉的實作：
const existing = await ctx.store.bm25Search(text, 5, [effectiveScope]);
if (existing.length > 0 && existing[0].entry.text === text) {
  //                                            ↑
  //                              只檢查 BM25 rank 第一名
  //                              排名 2~5 完全忽略

問題說明：

BM25 是 keyword-based 排序演算法，當資料庫中已有完全相同的文字時，BM25 可能因為文件長度、關鍵字密度等因素，把「完全相同」的那筆記錄排在 rank 2~5，而 rank 1 是「語意相似但文字稍不同」的筆記。這時 dedup 會漏掉，相同文字被重複匯入。

受影響範圍：

• PR fix(import-markdown): P0 missing return + register test in CI #482 的 commit 2cd9771（existing.some() 修復）從未進 upstream/master
• upstream/master 目前同時有 Bug A（existing[0]）和 Bug B（workspace glob 用 includes() fuzzy match）

---

建議修復方式：BM25 + Reranker + Exact Match

不走 LLM，純演算法三階段流程：

text = "記得買牛奶"
     ↓
【Stage 1: BM25 廣召回】
ctx.store.bm25Search(text, 20, [effectiveScope])
→ 快速用關鍵字召回 top-20 候選
     ↓
【Stage 2: Hybrid + Reranker 精排序】
ctx.retriever.retrieve({
  query: text,
  limit: 20,
  scopeFilter: [effectiveScope],
  source: "cli"
})
→ BM25 + Vector hybrid merge
→ Reranker cross-encoder 重新打分排序
     ↓
【Stage 3: Exact Match 把關】
if (results[0]?.entry.text === text) {
  // reranker 認為最相關的那筆記，跟 text 完全相同
  skipped++;
  skippedDedup++;
  continue;
}
→ 否則正常寫入

為什麼用 retrieve() 而不是自己寫 fetch call：

• retrieve() 是 official codebase 已實作好的方法，封裝了 BM25 + Vector hybrid + Reranker 流程
• 直接 reuse 不用重新寫，context 初始化後天然就有 ctx.retriever 可用
• Gateway 在跑時 plugin 初始化完成後，retrieve() 的底層依賴（store/embedder/reranker）都是獨立的 client，不需 gateway 盯著

實作代價：只需改一行（替換 bm25Search 為 retrieve），邏輯結構幾乎相同。

跟 smart-extractor 的對比：

	smart-extractor	import-markdown（此提案）
Stage 1	Vector cosine similarity (>= 0.7)	BM25 keyword recall
Stage 2	LLM 裁決（昂貴）	Reranker cross-encoder（本地，便宜）
Stage 3	—	Exact match 把關

import-markdown 不需要 LLM 是因為輸入是使用者自己寫的 Markdown bullet，只需確認「完全相同」就 skip，不需要理解語意。

---

與 PR #719 的關係

• PR feat(import-markdown): --no-dedup by default, new return fields, unified summary (closes #715) #719（feat(import-markdown): --no-dedup by default, new return fields, unified summary）：修 Issue enhancement: import-markdown CLI 過程監控 — 預設顯示相關 log #715 的 log 格式 + return type，dedup 核心邏輯完全沒動
• Bug A 修復：獨立的實作改動，可以放在 PR feat(import-markdown): --no-dedup by default, new return fields, unified summary (closes #715) #719 一起 review，或另外開一個 PR

---

需確認的事

1. ctx.retriever.config.rerank === "cross-encoder" 且 rerankApiKey/rerankEndpoint 有設定（James 的 reranker: 172.31.224.1:19999）
2. ctx.embedder 有初始化（embedPassage 在 CLI 中本來就有用）

[jlin53882]

目前測試，dedup/dry run 計數還有一些相關內容還在調整中，如果有想法歡迎一起討論

[jlin53882]

Dedup 效能瓶頸分析與優化方案

現況問題

PR #730 的 dedup 實作（cli.ts Phase 2a）：

// CHUNK=50，每批 50 個並行 retrieve()
const results = await Promise.all(
    chunk.map(({ e }) =>
        ctx.retriever.retrieve({
            query: e.text,
            limit: 20,
            scopeFilter: [e.effectiveScope],
            source: "cli"
        })
    )
);

問題：每一個 entry 都走完整 semantic search pipeline：

階段	成本	Dedup 是否需要
embedQuery()	高（外部 API）	❌ 不需要
reranker API	最高（外部 HTTP）	❌ 不需要
vectorSearch	低（本地 LanceDB）	❌ 不需要
BM25	低（本地 Tantivy）	❌ 不需要
text === text 比對	極低	✅ 唯一需要的

核心問題：dedup 只需要「這段文字是否已存在」，卻被迫跑了完整的 semantic search + embedQuery + reranker。第二次跑同樣檔案時，所有 entry 全部被 skip，但仍然完整跑過整個昂貴的 pipeline。

---

設計方案

方案 A：Bloom Filter + LanceDB hash lookup ⭐ 推薦

新 entry 的 dedup 檢查流程：
  1. textHash = SHA256(text + effectiveScope)
  2. bloomFilter.mightContain(textHash)?
       └─ NO  → 確認是 new，直接放行（零 API 呼叫）
       └─ YES → 查 LanceDB 確認（走 retrieve，但 bloom false positive 很少）

優點：

• 第二次跑同樣檔案：99%+ entry 在 O(1) 內直接 skip，零 API 呼叫
• Bloom filter 記憶體極小（10 萬筆 entry ≈ 1.2 MB）
• 不改變現有 retrieve() 任何 call site（semantic search 完全不受影響）
• 可漸進式實作：先用 new Set<string>（單次 session），再擴展到可持久化的 Bloom filter

缺點：

• 需要新增 bloomFilter 資料結構
• 需要在寫入時同步更新 text hash

---

方案 B：在 LanceDB 加 textHash 欄位

在 store 的 entry schema 加一個 textHash 欄位，dedup 時直接：

async findByTextHash(textHash: string, scope: string): Promise<MemoryEntry | null> {
    return this.table
        .query()
        .where("textHash", textHash)
        .where("scope", scope)
        .first();
}

優點： 完全在 LanceDB 內完成，不需要額外資料結構
缺點： LanceDB scalar filter 是掃描，不是 indexed lookup（entry 數量多時會變慢）

---

方案 C：只跳過 reranker（局部優化）

在 retrieve() 加 skipReranker: true flag，節省外部 API 呼叫。

優點： 最小改動
缺點： 仍然要跑 embedQuery + vector + BM25 + fusion，節省有限

---

推薦原因（方案 A）

1. 精準解決核心痛點：第二次跑同樣檔案時，Bloom filter 可直接回傳 SKIP，完全繞過 retrieval pipeline
2. 架構乾淨：Bloom filter 是一個 pure in-memory fast-path，不影響現有 semantic search（retrieve() 的其他 call site 完全不受影響）
3. 錯誤安全：Bloom filter 的 false positive 特性——只會保守地多走幾次 retrieve() 確認，絕不會漏掉真正的新內容
4. 漸進式實作：
   • Phase 1：先做 in-memory Set<string>（單次 session 有效，無持久化）
   • Phase 2：擴展到 Bloom filter + 磁碟持久化（跨 session 有效）

---

實作輪廓

// src/dedup/dedup-filter.ts
class DedupFilter {
    // Phase 1: O(1) bloom check
    mightContain(textHash: string): boolean;

    // Phase 2: LanceDB 確認（bloom hit 的情況很少）
    async confirmHit(textHash: string, scope: string): Promise<boolean>;

    // 寫入時同步標記
    add(textHash: string): void;
}

// cli.ts Phase 2a 改造後
for (const e of dedupNeeded) {
    const hash = sha256(e.text + e.effectiveScope);
    if (dedupFilter.mightContain(hash)) {
        const confirmed = await dedupFilter.confirmHit(hash, e.effectiveScope);
        if (confirmed) { skippedDedup++; continue; }
    }
    pendingEntries.push(e);
    dedupFilter.add(hash);
}

---

歡迎大家討論這個方向，有興趣實作可以認領。

[jlin53882]

Updated PR — the fix is now in #733 ().

Summary of what was delivered:

• Dedup enabled by default (use --no-dedup to disable)
• Uses ctx.retriever.retrieve() (hybrid vector+BM25 + rerank) instead of raw bm25Search()
• New stats: skippedShort, skippedDedup, errorCount in return value and console output
• 14/14 tests pass

This PR supersedes #719 and #720.

[jlin53882]

最新進度

✅ PR #730 + #732 已合併至 PR #735

PR735 = PR730(batch pipeline) + PR732(backup dir fix)，一次送出審查。

實作內容	說明
Phase 1a	平行讀取多個檔案 (Promise.all)
Phase 1b	解析 bullet lines，收集至 allEntries
Phase 2a	CHUNK=50 平行 retriever.retrieve() 做 dedup check
Phase 2b	embedBatchPassage() + bulkStore() + FLUSH_THRESHOLD=100
--no-dedup	dedup 預設啟用，可用 --no-dedup 禁用
--batch-size	控制每批 embed 數量（預設 10）
backup dir	從 openclaw.json 的 home 欄位解析，fix path=undefined 當機
回傳值	新增 skippedShort, skippedDedup, errorCount, elapsedMs
測試	19 tests pass, 0 fail ✅