Leo/Arcrun
1
0
Fork 0
Code Issues 49 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
326 Commits 27 Branches 0 Tags
af3edff856469cd4ae20dec861e61b655d39d5de
Commit Graph

12 Commits

Author SHA1 Message Date
uncle6me-web af3edff856 WIP(kbdb): 語意搜尋零命中的排查——⚠️ 被總管中途叫停，未完成驗證 
leo 2026-08-11 判斷「如果是 Vectorize 沒完成就不用查了」，總管據此停線。
真因已經寫在 repo 自己的註解裡（kbdb/wrangler.toml:43-51，Arcrun#11）：
metadata index 只收「建立後 upsert」的向量，既有向量須 reindex，
否則帶 owner_id filter 一律 0 命中——與實測每一格吻合
（805 筆在、關鍵字搜得到、語意 0、拿自己查自己也 0 ⇒ 不是分數門檻）。

⚠️ 這批改動是排查途中的產物，**沒有走完驗證**，不要當成可用的修法。
保留只是不讓它憑空消失（總管中斷造成，不是它做壞）。
接手的人請先讀 Arcrun#85 上的結論再決定要不要用。

真正的補救是 reindex，而 reindex 要燒 AI 額度
⇒ 卡在 Arcrun#85 的每日額度閘上線之後才能做。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-11 23:05:20 +08:00
uncle6me-web 6846d6ddae fix(semantic): 故障照實說是故障——不再把壞掉說成「沒開通」（leo 2026-08-09 直令） 
一、文案（portal/console/kbdb hint）：語意搜尋是一安裝就提供的功能，
   降級＝故障。橫幅改「語意搜尋目前故障／我們的問題／你不用做任何事」，
   拿掉「還沒開通、想開通請匯出診斷檔」這種要使用者申請開通的假框架。
   kbdb 降級回應加 degraded_reason（module_off / embed_query_failed）。

二、查詢向量化失敗不再偽裝成空結果（leo 點名的謊）：
   semanticSearch 舊行為「AI 額度用完 → 回 []」會讓使用者以為
   自己的知識庫裡沒有這筆資料。改丟 EmbedQueryFailedError，
   route 誠實降級 keyword＋照實告知是暫時故障。

三、源頭機制（裝好的實例為什麼會失去語意搜尋）：
   - acr update：kbdb_embed 判斷 ===true → !==false。config 缺欄位時
     redeploy 會把 [[vectorize]]+[ai] binding 靜默剝掉（wrangler deploy
     整份覆蓋），一台正常實例就此壞掉。init 預設同步翻成 [Y/n]。
   -（另 repo）deploy-all.mjs ensureVectorizeIndex 失敗改致命中止。

四、順手自癒：孤兒向量/下架殘影搜尋時背景清除；空結果且 pending>0
   背景 backfill；no_index 拆「故障」vs「還沒有資料」兩態。

測試：kbdb 146/146（新增 degraded 6 案＋selftest 1 案）；cli 10/10；
瀏覽器端到端兩種故障畫面實測（local wrangler dev＋portal 真登入）。
無 SDD 對應：leo 直令修故障（同 08-07 檢修孔前例的人閘直接授權路徑）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-09 02:05:12 +08:00
uncle6me-web 9344562258 feat(kbdb): embed 自我檢查端點（檢修孔第一塊，2026-08-07 leo 直接指令） 
GET /embed/selftest?owner_id= —— 挑一筆已標記「已嵌入」的卡片，拿它自己的內容做一次
真實語義查詢，檢查「自己是否搜得到自己」。backfillStatus 的 pending/embedded 計數
看不出 Arcrun#11 那種「嵌了但查不到」的故障模式（metadata index 事後才建、既有向量
沒被收錄），本端點是唯一能端到端驗證 index 真的可用的方法。

隱私邊界：只回 {enabled, tested, passed, note} 四個布林/字串欄位，不回卡片內容、
不回 entry id（測試 embed-selftest.test.ts 最後一案專門斷言不洩漏）。

12/12 kbdb vitest 全綠（含既有 embed-backfill 6 案未壞）。
 2026-08-07 18:35:06 +08:00
uncle6me-web 05b215c9f7 語意門檻改相對式＋下架連帶刪向量（leo 兩個實測回饋） 
## ① 「關懷型 AI 命中 20 筆、只有前 3 筆相關」⇒ 閾值太寬（leo 判斷正確）
固定門檻兩頭都不對，因為每個查詢的分數尺度不同（實測 youlin 實例）：
  關懷型 AI          正解 0.645-0.770，雜訊起於 0.547  ← 固定 0.5 放進 6 筆雜訊
  閉環機             正解 0.552-0.638，雜訊起於 0.446  ← 固定 0.6 砍到剩 2/4（＝早上的 0 命中）
  人力媒合系統規劃書   正解 0.842，雜訊起於 0.550
⇒ 改**相對門檻** max(0.45, top×0.8)。五組實測：固定 0.5 混入 9 筆雜訊／
  固定 0.6 有兩組正解被砍／相對式四組雜訊 0 且正解全留。

## 🔴 寫測試才發現的真問題：門檻不能在 Vectorize 那層算
Vectorize 的 indexed metadata 沒有 status ⇒ 那層不知道誰已下架。
若最高分是下架殘影（t24 復現案 0.971），拿它算門檻＝0.777，
會把 0.6 的正解一起砍光 ⇒ **又變成 0 命中**。
⇒ 相對門檻移到 routes/entries.ts，接在「hydrate＋濾下架」之後；
  embed.ts 只留絕對下限。新增測試鎖住這個順序。

## ② leo：「理論上它的向量也要刪掉，就不會有殘影了吧？」——對，補上
單筆真刪已接 deleteByIds（b7af622），但「移除整個庫」走軟刪、向量原地不動。
⇒ deprecate-by-library 同時 deleteByIds ＋ is_embedded 歸零（D1 與 Vectorize 不說兩套話）；
  backfill 兩條路徑（含 reindex）都排除 deprecated，否則下次補嵌會把殘影養回來。
不違背 t135「資料保留可還原」：D1 那列原封不動，還原後跑 backfill 重嵌即可。
回應新增 vectors_deleted，刪失敗誠實回 0 不假裝清乾淨。

驗：kbdb 91/91 綠（新增 4 項相對門檻測試，含「下架殘影不得決定門檻」）

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-05 18:47:10 +08:00
uncle6me-web 0ff369f818 修語意搜尋全 0 命中：分數門檻沒跟著 bge-m3 換代（換模型漏掉的第五處） 
leo 2026-08-05 實撞：「新上傳的『loop-engine-north-star.md』語義 0 命中，
但舊的『人力媒合系統規劃書』語義 2 命中」。

## 根因不在向量——向量是好的
直打 Vectorize 實測（youlin 實例、bge-m3、1024 維 index）：
  搜「閉環機」→ loop-engine-north-star.md 穩坐第 1-4 名（0.638/0.603/0.588/0.552）
D1 與 Vectorize 也對得上：659 筆 embeddable 全 is_embedded=1、index vectorCount 659。

真兇是 **min_score 門檻綁在舊模型的分數尺度上**：
  舊 bge-base-en-v1.5：中文分數全擠 0.65-0.90（沒區辨力）⇒ t183 取 0.75 砍雜訊，對
  新 bge-m3          ：尺度整體下移（相關 0.5-0.85、雜訊 0.4 上下）⇒ 0.75 砍掉的是正解
leo 看到的「舊檔中、新檔不中」由此而來——「人力媒合系統規劃書」拿 0.842 僥倖存活，
其餘全被門檻掃掉。08-05 換 bge-m3 的「四處同步」清單（embed.ts／deploy.ts／
deploy-all.mjs／worker.js）**漏了這第五處**，因為它不在 kbdb 而在 portal 呼叫端。

## 改動
· kbdb/src/embed.ts：新增 DEFAULT_MIN_SCORE=0.5，**緊鄰 DEFAULT_EMBED_MODEL**
    ——門檻是模型的性質，放模型旁邊，下次換模型的人一定會看到
· cypher-executor/src/routes/portal-data.ts：拿掉硬寫的 0.75，
    只在使用者顯式指定時才傳 min_score（不再各自持有一份數字＝不再漂移）
· console-ui/public/portal/os-split.test.mjs：修好被今天 fe0ee82 弄壞的自測
    （結尾標記寫死文案 ⇒ 改文案就炸「抽不到函式區塊」；改成錨定結構）
    ＋斷言同步改成 Mac 給 DMG

## 0.5 怎麼來的（實測分布，不是猜的）
「閉環機」            0.638/0.603/0.588/0.552 全是目標檔 ── 斷崖 ── 0.446 才是雜訊
「火星座標 奧林帕斯山」 0.750…0.500 全對，0.475 以下才是雜訊
「人力媒合系統規劃書」   0.842 對，0.550 起是雜訊
誠實 trade-off：0.5 非每個查詢都乾淨（「AI 上課名冊」0.658 的 ax-academy 會擠進來），
但「偶有雜訊」遠優於現況「什麼都搜不到」。

## 驗
· kbdb 87/87 綠（三筆斷言隨新契約更新：預設不再是「不過濾」）
· cypher-executor 9 failed/301 passed＝**與改動前逐數相同**（git stash 前後各跑一次）⇒ 既有債
· portal os-split 自測 10/10 綠

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-05 18:00:43 +08:00
uncle6me-web b9b5d98d75 併 bge-m3 換代（#59）＋補上分支漏做的另一半：Vectorize index 也換 
leo 2026-08-05：「換 embed model 當然要合併，當然要換 vectorize，**原本的根本不能用**」
——我把已拍板的事當成待裁決，錯了。

## 為什麼非換不可（08-03 leo 拍板，5 組中文測資實證）
  @cf/baai/bge-base-en-v1.5   768   排序正確 2/5   margin -0.0413   1660ms  ← 舊
  @cf/baai/bge-m3            1024        5/5        +0.1410    959ms  ← 新
舊英文模型嵌中文：分數全擠在 0.65-0.81，區辨力接近沒有＝**根本不能用**。

## 🔴 分支只做了一半，另一半我補上
feat/embed-model-m3-t59 只改 kbdb（embed.ts / types.ts / 測試），**完全沒動 deploy.ts**
⇒ 就算合併，安裝器仍會建 **768 維的舊 index**，新向量根本收不進去。
（git show f3af5d3 --stat 實查：只有 3 個檔，全在 kbdb/）

本次補上安裝器那半：
· KBDB_VECTORIZE_INDEX: arcrun-kbdb-embed → **arcrun-kbdb-embed-m3**（換名字，非只換維度）
· ensureVectorizeIndex: dimensions 768 → **1024**
· kbdb/wrangler.toml 說明與 metadata-index 指令同步改新名（照抄不會建錯 index）
· embed.ts docstring「768 維向量」→ 1024（分支漏改，會誤導）

## 為什麼要換「名字」不是只改維度
① 維度 768→1024，舊 index 收不進新向量
② 就算維度相同也不能沿用——不同模型的向量混在同一 index 比對出來是垃圾，
   而 #58（Vectorize vector delete 未接）代表舊向量刪不掉
   ⇒ **開新名字反而順手繞開 #58**，且新舊並存可回滾。

## 查證（歷史警察 Q0-Q3，非假設）
· git log --all -S"arcrun-kbdb-embed-m3" / -S"dimensions: 1024" 皆空 ⇒ 無分支改過，非重造輪子
· **metadata index 用同一個常數**（deploy.ts:426 ensureVectorizeMetadataIndexes）
  ⇒ t36 的四個 metadata index（owner_id/entry_type/source/library，Arcrun#11 根因修復）
  會自動建在新 index 上，**不會因改名而遺失**——這點特地查過，不是假設。

## 驗
· kbdb 測試 87/87 綠（含新增 4 項 embed-model-config）
· cli tsc --noEmit **零錯誤**
· 三處一致性機械確認：embed.ts=bge-m3／deploy.ts=dimensions 1024／index=arcrun-kbdb-embed-m3
· 踩到並記錄：註解寫 `**dimensions=1024**​/metric` 會因 `*/` 提早關掉 block comment（TS1127）

## 既有實例遷移（尚未執行，需對實例操作）
建新 index → 重部署 kbdb（binding 指新 index）
→ POST /embed/backfill {"reindex":true} 到 remaining=0 → 舊 index 可刪。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-05 13:46:33 +08:00
Leo f3af5d3631 feat(#59): embed 模型可配置，預設換成 bge-m3——英文模型嵌中文會排錯 
leo 2026-08-03 拍板「換 m3」。#59 本體（模型應可配置＋index 版本化）。

## 為什麼換：實測，不是憑感覺
5 組中文問答測資（每組 1 問 + 2 段相關 + 3 段無關，無關的刻意放同一知識庫裡的其他主題），
margin = min(相關分數) − max(無關分數)，margin ≤ 0 代表排序是錯的：

  @cf/baai/bge-base-en-v1.5      768   排序正確 2/5   平均 margin -0.0413  1660ms ← 舊
  @cf/google/embeddinggemma-300m 768   4/5   +0.1275   1174ms
  @cf/baai/bge-m3               1024   5/5   +0.1410    959ms ← 新（最好且最快）
  @cf/qwen/qwen3-embedding-0.6b 1024   4/5   +0.1381   3238ms

最刺眼的一組：問「知識庫問答為什麼要標出處？」→「會議室預約規則」0.7789
竟然高於真正相關的 0.7306。這正是 leo 2026-07-18 回報的「問 RAG 卻引用會議室規範」，
過去只被描述成「semantic 排名近乎雜訊」，其實是**排序錯誤**，而且五組錯三組。
英文 bge 系列的分數全擠在 0.65-0.81（區辨力接近沒有）——中文對它就是看不懂的 token。

## 改動
- `EMBED_MODEL` 常數 → `DEFAULT_EMBED_MODEL='@cf/baai/bge-m3'` + `embedModel(env)`，
  可由 `env.EMBED_MODEL` 覆寫（#59 要的「可配置」），空字串/空白視為沒設。
- 寫入端（embedOnWrite / backfill）與查詢端（semanticSearch）共用同一個 getter
  ——兩邊不同步是最惡毒的 bug：不報錯、分數全垃圾、外面完全看不出來。已加測試守。

## 換代必須換 index（安裝器那半在 arcrun-rag 同名分支）
① 維度 768→1024，舊 index 收不進新向量
② 就算維度一樣也不能沿用——不同模型的向量混在同一個 index 比對出來是垃圾，
   而 #58（Vectorize vector delete 未接）代表舊向量刪不掉
⇒ 開新 index 反而順手繞開 #58。

既有實例遷移：建新 index → 重部署 kbdb（binding 指新 index）
→ POST /embed/backfill {reindex:true} 重嵌到 remaining=0 → 舊 index 可刪。

驗證：kbdb 全套 87/87 綠（含新增 4 項）；tsc 與基線相同（只剩既有的 auth.test.ts 那筆）；
打包實跑產物 grep：kbdb bundle 只有 @cf/baai/bge-m3、舊英文模型 0 殘留。
 2026-08-03 03:48:28 +00:00
Claude 65d85eb08f fix(kbdb): search keyword 補 source filter（#66）＋semantic 曝 top_k/min_score 帶 score（#67） 
#66：/entries/search keyword 路徑 source 解析後丟棄（#5.1 只接了 listEntries 那半）——
searchEntries 尾端加 source?（既有 positional caller 全不用改），conds 補與 listEntries
同款 json_extract(metadata_json,'$.source') 謂詞；route keyword 分支與 semantic 降級
分支兩處傳入。

#67：semantic 固定 topK=20、零分數閾值、低分尾硬湊數——route 曝 top_k（預設 20、封頂
100）與 min_score（預設 0＝不過濾）query 參數；semanticSearch 依 min_score 截低分尾；
semantic 回應 entry 附 score 欄（加欄不改形）。壞值（非數字/非正）視同沒帶，不 400。

向後相容：不帶新參數時輸出與現況一致（semantic 僅多 score 資訊）；不動表（D6）、
不動 D1 結構（API-as-Wall）。測試：新增 search-source-and-score.test.ts 13 條
（source 謂詞形狀/route 下傳/降級不洩 filter/min_score 截斷/topK 透傳封頂/壞值防呆/
不帶參數行為不變），kbdb vitest 33/33 綠、tsc 0。

關聯 #66 #67。merge 後需 gated redeploy kbdb worker（leo 閘）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JUmjwkHLVBHM3ydhT1WSW3
 2026-07-19 07:53:46 +00:00
Leo 7f409646e5 portal-auth P1（#24 #25）：KBDB library filter 地基（不 merge，待總管審） (#50) 2026-07-14 03:50:06 +00:00
kbdb-cc befc63cfe0 fix(kbdb/embed): 語意查詢 metadata 過濾根因修復（Arcrun#11） 
根因：Vectorize index 建了卻從沒建 metadata index。CF Vectorize v2 要對某
metadata 欄位下 filter，必須先為該欄建 metadata index，否則帶 owner_id/
entry_type/source 過濾的語意查詢一律回 0 命中（app 端 filter 接線本來就對）。
且 metadata index 只索引「建立後 upsert」的向量 → 既有向量須重推才會被收錄。

- deploy.ts：加 ensureVectorizeMetadataIndexes()，隨部署冪等建 owner_id/
  entry_type/source（string）三個 metadata index（self-host/官方帳號皆自動）。
- embed.ts / routes/embed.ts：backfillEmbeddings 加 reindex+offset，重推「所有
  embeddable（含 is_embedded=1）」既有向量，讓事後建立的 metadata index 收錄；
  POST /embed/backfill {"reindex":true} 觸發，offset 分頁到 remaining=0。
- wrangler.toml：註解補 create-metadata-index 手動步驟 + reindex 提示。
- tests：mock DB 對齊 LIMIT?/OFFSET? 與 reindex predicate；補 reindex 測試。

leo21c 已驗：owner_id=leo / entry_type 過濾修前 0→修後命中，不帶過濾不變。
已知後續（非本 bug 症狀）：source 值 89-91 bytes 超過 Vectorize string
metadata index 的 64-byte 索引上限 → source 過濾對長值失效，另案。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HJiLCRUU2o3aSpPEzVCt2o
 2026-07-06 06:03:43 +00:00
Claude 55a47d7c18 kbdb(embed): add batch backfill endpoint for pre-Vectorize entries (issue #7 / T2.4 缺口) 
embed 模組原本只有 embedOnWrite（寫入即嵌），對「開 Vectorize binding 之前就寫入」或
embed-on-write 當時漏掉的既有 entry 沒有回填路徑 → is_embedded=0 永遠補不回，語義查詢回 0 筆。

新增（base，對 entries 做；embedding 是 base 唯一職責，非 graph 插件）：
- embed.ts: backfillEmbeddings()——找 is_embedded=0 且 isEmbeddable(metadata.embed===true) 的 entry，
  批次補嵌（單次 AI.run 陣列 + 單次 VECTORIZE.upsert 陣列 + 單次 UPDATE IN，一批≈3 subrequest）、
  設 is_embedded=1，冪等、分批（limit 1-100，回傳 processed/remaining，可重複呼叫直到清零）。
  模組未開誠實回 enabled:false（不假綠）。backfillStatus() 回 pending/embedded 計數。
- routes/embed.ts: POST /embed/backfill、GET /embed/backfill/status；模組未開回 409 + capability_hint。
- index.ts: mount /embed。
- tests/embed-backfill.test.ts: 5 vitest（off no-op / 補嵌+標記 / 冪等 / 分批 remaining / status）。

base 維持對內容語意無知（只認通用 embed 旗標，不知 triplet/wiki）。tsc exit 0、vitest 5/5。
端到端（leo21c，wrangler 直推、非 acr update）：pending 5→processed 5→remaining 0，
Vectorize vectorCount 0→5，/entries/search?mode=semantic 由 0 筆→5 筆（語義排序命中）。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BDtnGPJpAzp8UqHfAo8o1s
 2026-07-05 04:37:04 +00:00
uncle6me-web 934b9265d9 feat: KBDB self-hosted 查詢 + embed 模組 + thin-shell 收窄 + search_workflow（code done 待端到端） 
按 issue 分段標明（檔 #5/#8 改動交疊處無法乾淨拆檔，故併一個 commit）：

#4 thin-shell §3.1 自力救濟階梯 + code-node 規則（純文檔/規則，code-node 零件未實作）
#5 KBDB source filter（json_extract metadata_json 零建表）+ 能力對照；documents 聚合與
   DELETE proxy 部分擱置等頂層 T8
#7 base embed 模組（kbdb/src/embed.ts）+ vectorize 開關（deploy/config/wrangler.toml 註解範本）
   + 語義查詢降級閉環（mode=semantic 未開→LIKE+capability_hint）
#8 部分（workflow-discovery）：
   - KBDB /entries/search 加 base 通用 entry_type filter（entry-crud/embed/route/kbdb-proxy 透傳）
   - /webhooks/named 強制 description（空→400，訊息要求操盤 AI 據實寫一句）
   - 部署雙寫 entry_type=workflow embeddable entry（waitUntil 非阻塞，供 search）
   - cypher GET /workflows/search + MCP u6u_search_workflows（優先語意、降級 hint）
   - cypher POST /workflows/backfill-search-entries（無 desc 列出不編造）
   - GET /webhooks/named 補回 description/created_at 欄位（為 list 來源收斂備）

⚠️ tsc 綠 = code done，非完成（mindset §7 禁假綠）：
- #7/#8 端到端待 leo21c 部署驗（Vectorize 需官方憑證、CC 跑不了）
- #8 ①-a（MCP deploy 改打 /webhooks/named）未做、MCP deploy 那半仍 404
- #8 端到端（強制填擋空/語義命中/租戶隔離/降級 hint）未驗

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-27 17:52:52 +08:00