Community寫作與編輯github.com

maxgfr/ultraindex

將整個程式碼倉庫(程式碼 + 文件)索引為一份可導航、經 AI 分析的百科全書 — 包含地圖、每個模組的條目以及類型化連結圖譜 — 讓 AI 能在大型程式碼庫中工作,而不會填滿其上下文。一個自動路由的 skills.sh 技能,支援基於證據、附有引用的分析以及可選的本地(Ollama)語意搜尋。

ultraindex 是什麼?

ultraindex 是一個 AI 代理技能,旨在解決在大型程式碼庫中工作時,上下文視窗過快被填滿的問題。它透過分工來實現:一個零依賴的 Node.js 引擎(`node scripts/ultraindex.mjs`)負責機械性工作,如掃描專案、建構連結圖譜和佈局百科全書;而使用者(或 AI 代理)則負責理解工作,進行基於證據、附有引用的分析。引擎會產生一個包含 `INDEX.md` 地圖和每個模組條目的索引,並提供 `find`(詞彙/混合語意搜尋)、`neighbors`(鄰居查詢)、`symbols`(符號定義與引用)、`impact`(逆向依賴鏈分析)和 `ask`(基於證據的問題回答)等指令。它還包含一個高保證的驗證閘門(`verify`),用於審計或安全關鍵任務,該閘門會對照即時來源對抗性地檢查每個引用,透過 `check --semantic` 進行語意驗證。該技能支援多種平台(Claude Code、Codex 等),並可選用基於 Ollama 的本地語意嵌入層,所有操作均在本地執行,無需 API 金鑰或網路連線(語意層除外)。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraindex

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

ultraindex — 建構並導航整個程式碼庫的 AI 分析百科全書

在大型程式碼庫中,上下文視窗在你找到重點之前就填滿了。 ultraindex 透過分工解決這個問題:確定性、零依賴的引擎(node scripts/ultraindex.mjs <command> — 無需 npm install,無需 API 金鑰,執行 --help 查看完整功能)負責機械性工作 — 掃描專案、建構連結圖譜、佈局百科全書;你負責理解工作 — 基於證據、附有引用的分析 — 然後導航結果,而不是閱讀整個程式碼庫。

核心規則:

  1. 引擎擁有程式碼視圖和圖譜(ui:gen 區域)— 每次建構時重新產生;切勿手動編輯。
  2. 你擁有業務視圖(ui:human 區域)。build 會在重建和重新命名時保留你的文字。
  3. 從證據分析,而非記憶。 僅根據 dossier 顯示的真實原始碼撰寫分析,引用它 [file:line],並且 check 會在任一引用無法解析時失敗 — 所以不要猜測。
  4. 載入最少內容。 一次只讀取一個條目(或一個 dossier)— 這是預期的模式,也正是每個模組的子代理會做的事。切勿將 graph.json 或整個 encyclopedia/ 目錄大量載入到上下文中 — 這會違背設計目的。

大多數指令接受 --json — 當你需要根據結果分支而非以文字形式閱讀結果時,請優先使用。

根據情境選擇路線

確定你處於以下哪種情境,並閱讀相應的參考文件以了解詳細工作流程:

  1. 尚無索引 — 在倉庫根目錄下沒有 .ultraindex/ 或 docs/ultraindex/(檢查 graph.json 是否存在)。建構它,然後豐富頂層模組: 閱讀 references/generate.md。

  2. 索引已存在 — 先檢查新鮮度。 node scripts/ultraindex.mjs check --out <index-dir> --json。如果報告過期或損壞,重新執行 build(你的文字會保留),然後繼續。如果只有與任務無關的檔案發生變更,你可以繼續進行並註明。

  3. 使用者有一個任務或問題(「X 在哪裡」、「Z 如何運作」、「我應該修改哪些檔案」)— 導航索引,只打開它指向的檔案,用經過驗證的引用來佐證答案: 閱讀 references/navigate.md。

  4. 答案必須是高保證的(審計、安全性、正確性至關重要的聲明),或者使用者要求你驗證/裁定一個答案 — 在 check --answer 通過後(引用可解析),升級到語意驗證閘門,以便證明每個被引用的摘錄不僅存在,而且支持其聲明: 閱讀 references/verify.md。

  5. 使用者要求索引/分析/文件化,或者 status --json 顯示未豐富的樞紐節點且你有預算 — 執行狀態驅動的豐富循環(dossier → 撰寫附有引用的分析 → check)。在大型程式碼庫上,這可以並行化:如果你的主機支援子代理,每個模組由一個子代理從佇列中處理 — 閱讀 references/generate.md。

  6. 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、package exports 對應)、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 的虛擬檔案系統超出範圍(工作區名稱仍然可以解析)。
  • 懸空的邊通常表示倉庫本身存在損壞的匯入或過時的文件連結 — 這是一個要報告的發現,而不是要掩蓋的問題。

相關技能