365 lines
13 KiB
Go
365 lines
13 KiB
Go
// folderindex.go — 讓目錄索引變成**碎形**：每一層資料夾各有自己的一格，父子接得起來
|
||
// （`inkstone/Arcrun#146`，leo 2026-08-19）。
|
||
//
|
||
// leo 的原話（兩句，就是本檔的全部規格）：
|
||
//
|
||
// 「daemon 可以**碎形**的在每個巢狀資料夾中產生 index & wiki」
|
||
// 「**每一層目錄指向子層次目錄**」
|
||
//
|
||
// 🔴 為什麼不是把 inventory.go 的上限調大：
|
||
//
|
||
// `inventory.go` 的資料模型只有**兩層**——`inventoryCardPath(library)` 讓一個監看根
|
||
// 只能有一張卡，`invTopDirOf(rel)` 只取相對路徑第一段。實測（14 檔／4 層巢狀）產出
|
||
// 1 張卡、3 條「第一層 >> part_of >> 總覽頁」，第二層以下一個節點都沒有。
|
||
// 深度是**寫死在模型裡的**，不是參數。
|
||
//
|
||
// 🔴 為什麼是「一個資料夾一張卡」而不是「一張卡帶全部關聯」：
|
||
//
|
||
// `rag_ingest_card` 對每條 rel 各發一個 POST（foreach）＋upsert 前置的逐筆 DELETE。
|
||
// 把 N 個目錄的關聯塞進同一張卡 ⇒ 單一請求 N 條 rel ⇒ 撞 Workers 免費層
|
||
// **50 subrequests／請求**的天花板（`inventory.go` 的 `maxInventoryRels = 10`
|
||
// 就是為了這面牆才壓的）。拆成一卡一關聯後，**每個請求恆定 1 條 rel**，
|
||
// 天花板與資料夾數量脫鉤；變多的是請求「次數」，那個由既有的 `pace()` 節流吸收。
|
||
//
|
||
// 誠實界線（不要讓讀的人以為它做了沒做的事）：
|
||
// - **空目錄不會有卡**。目錄集合是從 manifest 的檔案路徑反推的，而 `scan.go` 從來
|
||
// 沒有記錄過目錄本身（`d.IsDir()` 只用來決定要不要整棵跳過）。
|
||
// 「空資料夾也要看得見」是 `inkstone/arcrun-rag#106`，要先讓掃描記得目錄才做得到。
|
||
// - 卡片內容是**機械統計**（檔數、子資料夾、最近改了什麼），不經 LLM ——
|
||
// 與 `inventory.go` 同一個理由：這種問題本機掃一遍就有答案，不該跟萃取排同一條隊。
|
||
package collector
|
||
|
||
import (
|
||
"crypto/sha256"
|
||
"encoding/hex"
|
||
"fmt"
|
||
"path"
|
||
"sort"
|
||
"strings"
|
||
"time"
|
||
)
|
||
|
||
const (
|
||
// maxFolderCards＝單一監看根最多產幾張資料夾卡。
|
||
//
|
||
// 🔴 這是一道**會被講出來**的上限，不是安靜截斷（principles「no silent caps」）：
|
||
// 超過時 `syncFolderCards` 會在結果訊息裡指名少送了幾個、從哪一層以下開始少。
|
||
// 200 的由來：一次同步 200 個請求已經是既有 `MaxEventsPerRun`（預設同量級）的規模，
|
||
// 再多就該讓使用者知道「你的資料夾深到要分批」，而不是我們自己吞掉。
|
||
maxFolderCards = 200
|
||
// maxFolderChildrenListed＝卡片上「子資料夾」段最多列幾個。純顯示上限，
|
||
// 不影響關聯（關聯永遠由子卡自己宣告，見檔頭）。
|
||
maxFolderChildrenListed = 50
|
||
// maxFolderFilesListed＝卡片上「本層檔案」最多列幾個。
|
||
maxFolderFilesListed = 100
|
||
)
|
||
|
||
// FolderCard＝一個資料夾在雲端的那一格。
|
||
type FolderCard struct {
|
||
// Rel＝相對監看根的路徑（`""`＝根本身，根不由本檔產卡，見 BuildFolderCards）。
|
||
Rel string
|
||
// Page＝雲端頁名（也是三元組裡的節點名）。
|
||
Page string
|
||
// Path＝合成的 source_uri 鍵（不落地本機，同 inventoryCardPath 的慣例）。
|
||
Path string
|
||
// Parent＝父資料夾的頁名。這就是「每一層指向子層次目錄」的那條邊的另一端。
|
||
Parent string
|
||
// Content＝卡片全文（markdown）。
|
||
Content string
|
||
}
|
||
|
||
// folderCardPageName 回傳某個相對路徑的卡片頁名。
|
||
// 根用 inventoryPageName（沿用既有那張總覽卡，不另開一張打對台）；
|
||
// 子層用 `資料夾：<根名>/<相對路徑>`——帶根名是因為不同監看根可能有同名子資料夾。
|
||
func folderCardPageName(absRoot, rel string) string {
|
||
if rel == "" {
|
||
return inventoryPageName(absRoot)
|
||
}
|
||
base := path.Base(strings.ReplaceAll(strings.TrimRight(absRoot, "/\\"), "\\", "/"))
|
||
if base == "" || base == "." || base == "/" {
|
||
base = "知識資料夾"
|
||
}
|
||
return "資料夾：" + base + "/" + rel
|
||
}
|
||
|
||
// folderCardPath 回傳子資料夾卡的合成路徑。
|
||
// 帶 library（每個監看根唯一）＋相對路徑的 slug ⇒ 同帳號多資料夾不互撞。
|
||
// slug 為空（例如純中文路徑）時退成路徑雜湊，理由同 librarySlug 的 t89。
|
||
func folderCardPath(library, rel string) string {
|
||
slug := pathSlug(rel)
|
||
return ".arcrun-rag/wiki/cards/arcrun-資料夾-" + library + "-" + slug + ".md"
|
||
}
|
||
|
||
// pathSlug 把相對路徑轉成檔名安全的鍵。非 ASCII 一律轉底線分段（同 librarySlug 的規則），
|
||
// 全轉光就退成 sha256 前 8 hex——**路徑穩定所以鍵穩定，兩個不同路徑必然不同鍵**。
|
||
func pathSlug(rel string) string {
|
||
var b strings.Builder
|
||
lastUnderscore := false
|
||
for _, r := range rel {
|
||
switch {
|
||
case (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' || r == '_':
|
||
b.WriteRune(r)
|
||
lastUnderscore = false
|
||
case r >= 'A' && r <= 'Z':
|
||
b.WriteRune(r + 32)
|
||
lastUnderscore = false
|
||
default:
|
||
if !lastUnderscore && b.Len() > 0 {
|
||
b.WriteRune('_')
|
||
lastUnderscore = true
|
||
}
|
||
}
|
||
}
|
||
s := strings.Trim(b.String(), "_")
|
||
sum := sha256.Sum256([]byte(rel))
|
||
short := hex.EncodeToString(sum[:])[:8]
|
||
if s == "" {
|
||
return "d_" + short
|
||
}
|
||
// 一律接上雜湊尾碼：slug 會把「A/B」與「A_B」壓成同一個字串，
|
||
// 只靠 slug 會讓兩個不同資料夾共用一張卡（靜默混層，同 t89 的形狀）。
|
||
return s + "-" + short
|
||
}
|
||
|
||
// dirsFromEntries 從 manifest 的檔案路徑反推出**所有祖先目錄**（含中間層）。
|
||
// 回傳排序過的相對路徑（不含根的 ""）。
|
||
func dirsFromEntries(entries map[string]*ManifestEntry) []string {
|
||
set := map[string]bool{}
|
||
for p, e := range entries {
|
||
if e == nil {
|
||
continue
|
||
}
|
||
rel := strings.ReplaceAll(p, "\\", "/")
|
||
seg := strings.Split(rel, "/")
|
||
if len(seg) < 2 {
|
||
continue // 根層檔案，沒有祖先目錄
|
||
}
|
||
for i := 1; i < len(seg); i++ {
|
||
set[strings.Join(seg[:i], "/")] = true
|
||
}
|
||
}
|
||
out := make([]string, 0, len(set))
|
||
for d := range set {
|
||
out = append(out, d)
|
||
}
|
||
sort.Strings(out)
|
||
return out
|
||
}
|
||
|
||
// parentRel 回傳某個相對目錄的父目錄（頂層目錄的父是根，回 ""）。
|
||
func parentRel(rel string) string {
|
||
if i := strings.LastIndexByte(rel, '/'); i > 0 {
|
||
return rel[:i]
|
||
}
|
||
return ""
|
||
}
|
||
|
||
// BuildFolderCards 為每一個（含有檔案的）子資料夾各做一張卡。純函式、零 IO、輸出確定。
|
||
//
|
||
// 根本身不在回傳值裡——根那張是 `inventory.go` 的總覽卡，兩者分工不重疊：
|
||
// 總覽卡回答「這個監看根整體有什麼」，資料夾卡回答「這一層有什麼、它掛在誰底下」。
|
||
func BuildFolderCards(absRoot string, entries map[string]*ManifestEntry, library string) []FolderCard {
|
||
dirs := dirsFromEntries(entries)
|
||
|
||
// 每層直屬檔案 ／ 每層子目錄 ／ 每層含子孫的總檔數
|
||
direct := map[string][]invFile{}
|
||
subtotal := map[string]int{}
|
||
children := map[string][]string{}
|
||
for p, e := range entries {
|
||
if e == nil {
|
||
continue
|
||
}
|
||
rel := strings.ReplaceAll(p, "\\", "/")
|
||
d := path.Dir(rel)
|
||
if d == "." {
|
||
d = ""
|
||
}
|
||
direct[d] = append(direct[d], invFile{path: path.Base(rel), mtime: e.Mtime})
|
||
for cur := d; ; cur = parentRel(cur) {
|
||
subtotal[cur]++
|
||
if cur == "" {
|
||
break
|
||
}
|
||
}
|
||
}
|
||
for _, d := range dirs {
|
||
p := parentRel(d)
|
||
children[p] = append(children[p], d)
|
||
}
|
||
for k := range children {
|
||
sort.Strings(children[k])
|
||
}
|
||
|
||
cards := make([]FolderCard, 0, len(dirs))
|
||
for _, rel := range dirs {
|
||
page := folderCardPageName(absRoot, rel)
|
||
var b strings.Builder
|
||
sep := " " + strings.Repeat(">", 2) + " "
|
||
|
||
b.WriteString("# " + page + "\n\n")
|
||
|
||
b.WriteString("## 一句話定義\n")
|
||
b.WriteString(fmt.Sprintf("這是「%s」底下的資料夾 `%s`：本層直接放了 %d 份文件，連同子資料夾共 %d 份。本頁由掃描自動整理，隨檔案變動即時更新，不經 AI 萃取。\n\n",
|
||
path.Base(strings.ReplaceAll(strings.TrimRight(absRoot, "/\\"), "\\", "/")),
|
||
rel, len(direct[rel]), subtotal[rel]))
|
||
|
||
// 子資料夾：這一段就是「每一層目錄指向子層次目錄」給人看的那一面
|
||
// （給機器看的那一面是子卡自己的「## 關聯」）。
|
||
b.WriteString("## 子資料夾\n")
|
||
kids := children[rel]
|
||
if len(kids) == 0 {
|
||
b.WriteString("（沒有子資料夾）\n")
|
||
}
|
||
for i, c := range kids {
|
||
if i >= maxFolderChildrenListed {
|
||
b.WriteString(fmt.Sprintf("- （其餘 %d 個子資料夾未列出）\n", len(kids)-i))
|
||
break
|
||
}
|
||
b.WriteString(fmt.Sprintf("- %s（%d 份）\n", path.Base(c), subtotal[c]))
|
||
}
|
||
b.WriteString("\n")
|
||
|
||
b.WriteString("## 本層檔案\n")
|
||
files := direct[rel]
|
||
sort.Slice(files, func(i, j int) bool { return files[i].path < files[j].path })
|
||
if len(files) == 0 {
|
||
b.WriteString("（本層沒有直接放文件，內容都在子資料夾裡）\n")
|
||
}
|
||
for i, f := range files {
|
||
if i >= maxFolderFilesListed {
|
||
b.WriteString(fmt.Sprintf("- （其餘 %d 份未列出）\n", len(files)-i))
|
||
break
|
||
}
|
||
b.WriteString("- " + f.path + "（" + invDateOf(f.mtime) + "）\n")
|
||
}
|
||
b.WriteString("\n")
|
||
|
||
// ── 關聯：**恰好一條**，指向父層。天花板與資料夾數量脫鉤的關鍵就在這裡。──
|
||
parent := folderCardPageName(absRoot, parentRel(rel))
|
||
b.WriteString("## 關聯\n")
|
||
b.WriteString("- " + page + sep + "part_of" + sep + parent + "\n")
|
||
|
||
cards = append(cards, FolderCard{
|
||
Rel: rel, Page: page, Path: folderCardPath(library, rel),
|
||
Parent: parent, Content: b.String(),
|
||
})
|
||
}
|
||
return cards
|
||
}
|
||
|
||
// syncFolderCards 在總覽卡之後送資料夾卡。回 nil＝這輪不必送。
|
||
//
|
||
// 冪等：每張卡的內容雜湊記在 `manifest.folder_card_hashes[rel]`，沒變不送。
|
||
// 失敗不擋主流程（同 syncInventory）；額度訊息換成人話。
|
||
// 上限：`maxFolderCards`，超過的**指名講出來**，不安靜吞掉。
|
||
func syncFolderCards(cfg *DirectConfig, absRoot string, m *Manifest, hasEvents, dryRun bool, now time.Time) []DirectResult {
|
||
if !hasEvents && len(m.FolderCardHashes) > 0 {
|
||
return nil // 靜止輪不重送（同 syncInventory 的③）
|
||
}
|
||
lib := cfg.libraryFor(absRoot)
|
||
cards := BuildFolderCards(absRoot, m.Entries, lib)
|
||
if len(cards) == 0 {
|
||
return nil
|
||
}
|
||
if m.FolderCardHashes == nil {
|
||
m.FolderCardHashes = map[string]string{}
|
||
}
|
||
|
||
// 先刪掉「這輪已經不存在的資料夾」的記帳，避免雜湊表無限長大。
|
||
live := map[string]bool{}
|
||
for _, c := range cards {
|
||
live[c.Rel] = true
|
||
}
|
||
for rel := range m.FolderCardHashes {
|
||
if !live[rel] {
|
||
delete(m.FolderCardHashes, rel)
|
||
}
|
||
}
|
||
|
||
// 🔴 先挑「這輪真的要送的」，**再**套上限——順序反過來就會變成永遠只重試前 200 個，
|
||
// 後面的資料夾一輩子送不上去（而且畫面上看起來一切正常）。
|
||
type pending struct {
|
||
card FolderCard
|
||
hash string
|
||
}
|
||
var todo []pending
|
||
for _, c := range cards {
|
||
sum := sha256.Sum256([]byte(c.Content))
|
||
h := "sha256:" + hex.EncodeToString(sum[:])
|
||
if m.FolderCardHashes[c.Rel] == h {
|
||
continue // 冪等：內容沒變
|
||
}
|
||
todo = append(todo, pending{card: c, hash: h})
|
||
}
|
||
if len(todo) == 0 {
|
||
return nil
|
||
}
|
||
|
||
var dropped []string
|
||
if len(todo) > maxFolderCards {
|
||
for _, t := range todo[maxFolderCards:] {
|
||
dropped = append(dropped, t.card.Rel)
|
||
}
|
||
todo = todo[:maxFolderCards]
|
||
}
|
||
|
||
var out []DirectResult
|
||
wf := cfg.CardIngestWF
|
||
if wf == "" {
|
||
wf = "rag_ingest_card"
|
||
}
|
||
mach := cfg.machineIdentity()
|
||
for _, t := range todo {
|
||
c := t.card
|
||
res := DirectResult{Type: "folder", Path: c.Path}
|
||
if dryRun {
|
||
res.Status = "planned"
|
||
out = append(out, res)
|
||
continue
|
||
}
|
||
pace()
|
||
status, _, err := cfg.postJSON(stepFolderCard, cfg.triggerURL(wf), map[string]any{
|
||
"page_name": c.Page,
|
||
"path": c.Path,
|
||
"card_content": c.Content,
|
||
"library": lib,
|
||
"machine": mach.ID,
|
||
"machine_label": mach.Label,
|
||
})
|
||
res.HTTPStatus = status
|
||
if err != nil {
|
||
res.Status = "failed"
|
||
if isQuotaExhausted(err.Error()) {
|
||
res.Error = "雲端今天的額度用完了，資料夾索引會稍後自動補送（不影響檔案同步）"
|
||
} else {
|
||
res.Error = "資料夾索引上傳失敗（不影響檔案同步）：" + err.Error()
|
||
}
|
||
out = append(out, res)
|
||
// 這一張失敗就停手：後面幾百張多半會撞同一面牆，繼續撞只是把
|
||
// 「一個壞掉的雲端」變成「幾百筆一樣的錯誤」（t195 的 1387 輪教訓）。
|
||
break
|
||
}
|
||
res.Status = "ingested"
|
||
m.FolderCardHashes[c.Rel] = t.hash
|
||
out = append(out, res)
|
||
}
|
||
|
||
if len(dropped) > 0 {
|
||
out = append(out, DirectResult{
|
||
Type: "folder",
|
||
Status: "skipped",
|
||
Error: fmt.Sprintf("資料夾超過單輪上限 %d 個，這輪少送 %d 個（例：%s）——下一輪會接著送",
|
||
maxFolderCards, len(dropped), strings.Join(firstN(dropped, 3), "、")),
|
||
})
|
||
}
|
||
return out
|
||
}
|
||
|
||
// firstN 取前 n 個（不足就全給）。只給訊息用。
|
||
func firstN(ss []string, n int) []string {
|
||
if len(ss) <= n {
|
||
return ss
|
||
}
|
||
return ss[:n]
|
||
}
|