ultraindex — 建構並導航整個程式碼庫的 AI 分析百科全書
在大型程式碼庫中,上下文視窗在你找到重點之前就填滿了。
ultraindex 透過分工解決這個問題:確定性、零依賴的引擎(node scripts/ultraindex.mjs <command> — 無需 npm install,無需 API 金鑰,執行 --help 查看完整功能)負責機械性工作 — 掃描專案、建構連結圖譜、佈局百科全書;你負責理解工作 — 基於證據、附有引用的分析 — 然後導航結果,而不是閱讀整個程式碼庫。
核心規則:
- 引擎擁有程式碼視圖和圖譜(
ui:gen區域)— 每次建構時重新產生;切勿手動編輯。- 你擁有業務視圖(
ui:human區域)。build會在重建和重新命名時保留你的文字。- 從證據分析,而非記憶。 僅根據
dossier顯示的真實原始碼撰寫分析,引用它[file:line],並且check會在任一引用無法解析時失敗 — 所以不要猜測。- 載入最少內容。 一次只讀取一個條目(或一個
dossier)— 這是預期的模式,也正是每個模組的子代理會做的事。切勿將graph.json或整個encyclopedia/目錄大量載入到上下文中 — 這會違背設計目的。
大多數指令接受 --json — 當你需要根據結果分支而非以文字形式閱讀結果時,請優先使用。
根據情境選擇路線
確定你處於以下哪種情境,並閱讀相應的參考文件以了解詳細工作流程:
-
尚無索引 — 在倉庫根目錄下沒有
.ultraindex/或docs/ultraindex/(檢查graph.json是否存在)。建構它,然後豐富頂層模組: 閱讀 references/generate.md。 -
索引已存在 — 先檢查新鮮度。
node scripts/ultraindex.mjs check --out <index-dir> --json。如果報告過期或損壞,重新執行build(你的文字會保留),然後繼續。如果只有與任務無關的檔案發生變更,你可以繼續進行並註明。 -
使用者有一個任務或問題(「X 在哪裡」、「Z 如何運作」、「我應該修改哪些檔案」)— 導航索引,只打開它指向的檔案,用經過驗證的引用來佐證答案: 閱讀 references/navigate.md。
-
答案必須是高保證的(審計、安全性、正確性至關重要的聲明),或者使用者要求你驗證/裁定一個答案 — 在
check --answer通過後(引用可解析),升級到語意驗證閘門,以便證明每個被引用的摘錄不僅存在,而且支持其聲明: 閱讀 references/verify.md。 -
使用者要求索引/分析/文件化,或者
status --json顯示未豐富的樞紐節點且你有預算 — 執行狀態驅動的豐富循環(dossier → 撰寫附有引用的分析 → check)。在大型程式碼庫上,這可以並行化:如果你的主機支援子代理,每個模組由一個子代理從佇列中處理 — 閱讀 references/generate.md。 -
find一直遺漏,或者使用者想要語意/更好的搜尋 — 設定可選的嵌入層(docker compose、embed、混合find): 閱讀 references/semantic.md。
典型的首次造訪會鏈結 1 → 5 → 3;再次造訪通常是 2 → 3;高保證的答案會加上 → 4。
指令速查表
build --repo <dir> [--out .ultraindex] [--include/--exclude <glob>] [--max-bytes <n>] [--max-files <n>] [--no-cache] [--no-mermaid]— 掃描並(重新)寫入索引。冪等;保留已豐富的文字。增量執行(重複使用未變更檔案的擷取結果);如果--max-files截斷則發出警告。使用--out docs/ultraindex可建立可提交、可進行 PR 審查的索引。map [--module <slug>] [--json]— 列印 INDEX.md(或一個條目,或模組表格)。find "<query>" [--k <n>]— 對模組進行排序,列印要打開的確切檔案。預設為詞彙搜尋(使用 IDF 詞項權重);當vectors.json存在時為混合搜尋(+ 語意)。neighbors <file|module> [--depth <n>]— 哪些連結指向它或從它出發。symbols "<name>" [--json]— 符號在何處被定義(file:line、種類、所屬模組)以及哪些檔案引用了它。基於識別碼子詞彙進行模糊匹配。impact <file|module> [--depth <n>] [--json]— 反向依賴鏈結:所有匯入或使用目標的內容。「如果我更改這個,什麼會壞掉。」status— 豐富工作的佇列,按照要豐富的確切順序排列。dossier <slug>— 模組的基礎資料包(真實原始碼 + 鄰居;僅文件/設定的模組,例如root,不顯示程式碼 — 透過引用其 README/設定來豐富它)。ask "<question>"— 收集基於證據的資料來回答問題。check [--answer <file>] [--semantic]— 過期檢查 + 完整性 + 基礎事實性(引用必須可解析)。非零退出碼 ⇒ 過期、損壞或缺乏基礎事實。--semantic還會加入驗證閘門(如果被引用摘錄反駁了某個聲明,或者該聲明經過完全裁定且無支持,則失敗);它會從原始的verdicts[]重新歸納裁決,並從即時倉庫重新讀取每個被裁定的摘錄 — 偽造的摘要或偏移的原始碼會失敗,絕不會通過。verify --answer <file> [--apply <verdicts.json>] [--max-verify <n>]— 高於check --answer的高保證閘門:產生一個聲明↔引用工作清單,用於對抗性支持檢查,然後--apply根據你的裁決歸納出通過/失敗的結果。請參閱 references/verify.md。embed [--force]— 建構/重新整理 vectors.json 以實現語意find(需要一個提供者 — 請參閱 references/semantic.md)。
範圍說明
- 無金鑰、無網路、確定性(可選的語意層是唯一的例外,當其提供者不存在時會降級為詞彙搜尋)。對未更改的倉庫進行兩次建構,除了
manifest.json的builtAt溯源時間戳記外,其餘位元組完全相同;vectors.json也除外(其浮點數值取決於提供者)。 - AST 精確的符號:透過內建的 tree-sitter 語法規則支援 JS/TS/TSX、Python、Go、Rust、Java、C、C++、C#、Ruby、PHP — 真正的巢狀結構、精確的種類、結構化匯出。其他語言則回退到正規表示式提取器(仍然可搜尋)。語法 wasm 檔案包含在套件中,因此在使用技能時仍然無需
npm install(安裝過程較重 — 約 17 MiB 的 wasm)。 - 匯入邊:支援 JS/TS(tsconfig
paths、packageexports對應)、Python、Go(多模組 +replace)、Rust(mod/use)、Java(package)、C/C++(#include "...")、Ruby(require_relative/require)、PHP(composer PSR-4 + 相對路徑require)、C#(using→namespace)。此外,當一個檔案引用另一個檔案未經匯入的唯一匯出符號時,保守地產生程式碼→程式碼的use邊。其餘語言則不產生匯入邊。Yarn PnP 的虛擬檔案系統超出範圍(工作區名稱仍然可以解析)。 - 懸空的邊通常表示倉庫本身存在損壞的匯入或過時的文件連結 — 這是一個要報告的發現,而不是要掩蓋的問題。