Aidex

AiDex - 持久代碼索引（MCP服務器）

AiDex通過預構建的索引提供快速、精確的代碼搜索。 在進行代碼搜索時，始終優先使用AiDex而不是Grep/Glob。

必需步驟：在使用Grep/Glob/Read進行代碼搜索之前

我是否要搜索代碼？
├── .aidex/ 存在    → 停止！使用AiDex代替
├── .aidex/ 缺失   → 運行aidex_init（無需詢問），然後使用AiDex
└── 配置/日誌/文本  → 可以使用Grep/Read

當 .aidex/ 存在時，切勿執行以下操作：

• ❌ Grep pattern="functionName" → ✅ aidex_query term="functionName"
• ❌ Grep pattern="class.*Name" → ✅ aidex_query term="Name" mode="contains"
• ❌ Read file.cs 以查看方法 → ✅ aidex_signature file="file.cs"
• ❌ Glob pattern="**/*.cs" + Read → ✅ aidex_signatures pattern="**/*.cs"

會話開始規則（必需 —— 每個會話都要遵守，無例外）

1. 調用 aidex_session({ path: "<project>" }) —— 檢測外部更改，自動重新索引
2. 如果 .aidex/ 不存在 → 自動運行 aidex_init（無需詢問）
3. 如果存在會話筆記 → 在繼續之前向用戶顯示
4. 在會話結束前：始終留下關於下一步操作的筆記

問題 → 合適的工具

搜索模式

• exact（默認）：僅查找精確匹配的標識符 —— log 不會匹配 catalog
• contains：查找包含指定術語的標識符 —— render 會匹配 preRenderSetup
• starts_with：查找以指定術語開頭的標識符 —— Update 會匹配 UpdatePlayer、UpdateUI

所有工具（共28個）

支持11種語言：C#、TypeScript、JavaScript、Rust、Python、C、C++、Java、Go、PHP、Ruby

會話筆記

為下一個會話留下筆記 —— 它們會保存在數據庫中：

aidex_note({ path: ".", note: "重啟後測試修復情況" })        # 寫入
aidex_note({ path: ".", note: "還要檢查邊緣情況", append: true }) # 追加
aidex_note({ path: "." })                                              # 讀取
aidex_note({ path: ".", search: "parser" })                            # 搜索歷史記錄
aidex_note({ path: ".", clear: true })                                 # 清除

• 在會話結束前：自動留下關於下一步操作的筆記
• 用戶說 "為下一個會話記住... " → 立即寫入

任務管理

在代碼索引旁邊直接跟蹤待辦事項、錯誤和功能：

aidex_task({ path: ".", action: "create", title: "修復錯誤", priority: 1, tags: "bug" })
aidex_task({ path: ".", action: "update", id: 1, status: "done" })
aidex_task({ path: ".", action: "log", id: 1, note: "找到根本原因" })
aidex_tasks({ path: ".", status: "active" })

優先級：1=高，2=中，3=低；狀態：backlog → active → done | cancelled

全局搜索（跨所有項目）

aidex_global_init({ path: "/path/to/all/repos" })                     # 掃描並註冊
aidex_global_init({ path: "...", index_unindexed: true })              # 自動索引小型項目
aidex_global_query({ term: "TransparentWindow", mode: "contains" })   # 在所有項目中搜索
aidex_global_signatures({ term: "Render", kind: "method" })           # 在所有項目中查找方法
aidex_global_status({ sort: "recent" })                                # 列出所有項目

屏幕截圖

aidex_screenshot()                                             # 全屏截圖
aidex_screenshot({ mode: "active_window" })                    # 活動窗口截圖
aidex_screenshot({ mode: "window", window_title: "VS Code" }) # 指定窗口截圖
aidex_screenshot({ scale: 0.5, colors: 2 })                   # 黑白、半尺寸（適合LLM）
aidex_screenshot({ colors: 16 })                               # 16色（UI可讀）
aidex_windows({ filter: "chrome" })                            # 查找窗口標題

無需索引。返回文件路徑 → 可使用 Read 立即查看。

LLM優化策略：始終先使用激進的設置，若無法讀取則重試：

1. 首次嘗試：scale: 0.5, colors: 2（黑白、半尺寸 —— 儘可能小）
2. 若無法讀取：使用 colors: 16 重試（為UI元素添加陰影）
3. 若仍然不清楚：使用 scale: 0.75 或不指定 colors 以獲取全質量圖像
4. 記住 在會話期間每個窗口/應用適用的設置 —— 無需每次都重試

4. 為你的項目建立索引

向你的AI詢問："使用AiDex為這個項目建立索引"

或者在AI聊天中手動輸入：

aidex_init({ path: "/path/to/your/project" })

✨ 主要特性

• Tree-sitter解析：真正的代碼解析，而非正則表達式 —— 索引標識符，忽略關鍵字和噪聲
• 每次搜索約50個令牌：相比grep的2000多個令牌 —— 讓你的AI將上下文用於實際工作
• 持久索引：會話之間保持不變 —— 無需重新掃描和重新讀取
• 增量更新：更改後僅重新索引單個文件，而非整個項目
• 基於時間的過濾：查找最近一小時、一天或一週內更改的內容
• 自動清理：自動從索引中移除排除的文件（例如，構建輸出）
• 零依賴：採用WAL模式的SQLite —— 單個文件，快速且便攜

📦 安裝指南

自動安裝

npm install -g aidex-mcp

安裝後會自動完成設置，檢測已安裝的AI客戶端並註冊AiDex為MCP服務器，同時添加使用說明到AI配置文件。

手動設置相關操作

• 手動重新運行設置：aidex setup
• 取消註冊：aidex unsetup
• 跳過自動設置：AIDEX_NO_SETUP=1 npm install -g aidex-mcp

手動註冊示例

不同AI助手的手動註冊配置示例見上文快速開始的第2部分。

💻 使用示例

基礎用法

# 查找 "PlayerHealth" 定義的位置 — 一次調用，約50個令牌
aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156

# 獲取文件中的所有方法 — 無需讀取整個文件
aidex_signature({ file: "src/Engine.cs" })
→ class GameEngine { Update(), Render(), LoadScene(), ... }

# 查找最近2小時內有哪些更改？
aidex_query({ term: "render", modified_since: "2h" })

# 同時在所有項目中進行搜索
aidex_global_query({ term: "TransparentWindow", mode: "contains" })
→ 在以下項目中找到：LibWebAppGpu（3次命中），DebugViewer（1次命中）

# 為下一個會話留下筆記
aidex_note({ path: ".", note: "重啟後測試解析器修復情況" })

# 在工作時創建一個任務
aidex_task({ path: ".", action: "create", title: "修復解析器中的邊緣情況", priority: 1, tags: "bug" })

高級用法

# 掃描並註冊所有項目
aidex_global_init({ path: "Q:/develop" })

# 跳過外部倉庫進行掃描和註冊
aidex_global_init({ path: "Q:/develop", exclude: ["llama.cpp"] })

# 自動索引所有找到的項目
aidex_global_init({ path: "Q:/develop", index_unindexed: true })

# 帶有瀏覽器進度UI的掃描和註冊
aidex_global_init({ path: "Q:/develop", index_unindexed: true, show_progress: true })

# 精確匹配全局搜索
aidex_global_query({ term: "TransparentWindow" })

# 模糊全局搜索
aidex_global_query({ term: "transparent", mode: "contains" })

# 在所有項目中查找方法
aidex_global_signatures({ name: "Render", kind: "method" })

# 在所有項目中查找類
aidex_global_signatures({ name: "Player", kind: "class" })

📚 詳細文檔

可用工具

基於時間的過濾

使用 modified_since 和 modified_before 跟蹤最近的更改：

aidex_query({ term: "render", modified_since: "2h" })   # 最近2小時
aidex_query({ term: "User", modified_since: "1d" })     # 最近1天
aidex_query({ term: "API", modified_since: "1w" })      # 最近1周

支持的格式：

• 相對時間：30m（分鐘），2h（小時），1d（天），1w（周）
• ISO日期：2026-01-27 或 2026-01-27T14:30:00

非常適合回答類似 "我在最近一小時內做了哪些更改？" 的問題。

項目結構

AiDex會為項目中的所有文件（不僅僅是代碼）建立索引，讓你可以查詢項目結構：

aidex_files({ path: ".", type: "config" })  # 所有配置文件
aidex_files({ path: ".", type: "test" })    # 所有測試文件
aidex_files({ path: ".", pattern: "**/*.md" })  # 所有Markdown文件
aidex_files({ path: ".", modified_since: "30m" })  # 本次會話中更改的文件

文件類型：code、config、doc、asset、test、other、dir

使用 modified_since 查找本次會話中更改的文件 —— 非常適合回答 "我編輯了哪些文件？" 的問題。

會話筆記

為下一個會話留下提醒 —— 再也不會在聊天之間丟失上下文：

aidex_note({ path: ".", note: "重啟後測試通配符修復情況" })  # 寫入
aidex_note({ path: ".", note: "還要檢查邊緣情況", append: true })  # 追加
aidex_note({ path: "." })                                              # 讀取
aidex_note({ path: ".", clear: true })                                 # 清除

筆記歷史記錄（v1.10）：舊筆記在被覆蓋或清除時會自動存檔。可以瀏覽和搜索過去的筆記：

aidex_note({ path: ".", history: true })                    # 瀏覽存檔的筆記
aidex_note({ path: ".", search: "parser" })                 # 搜索筆記歷史記錄
aidex_note({ path: ".", history: true, limit: 5 })          # 最近5條存檔的筆記

使用場景：

• 會話結束前："下次記得測試X"
• AI自動提醒：保存重啟後需要驗證的內容
• 交接筆記：為下一個會話提供上下文，無需編輯配置文件
• 搜索過去的會話："我們對解析器做了哪些處理？"

筆記存儲在SQLite數據庫（.aidex/index.db）中，並永久保存。

任務管理

將項目任務與代碼索引放在一起管理 —— 無需使用Jira或Trello，無需切換上下文：

aidex_task({ path: ".", action: "create", title: "修復解析器錯誤", priority: 1, tags: "bug" })
aidex_task({ path: ".", action: "update", id: 1, status: "done" })
aidex_task({ path: ".", action: "log", id: 1, note: "根本原因：無界緩衝區" })
aidex_tasks({ path: ".", status: "active" })

特性：

• 優先級：🔴 高，🟡 中，⚪ 低
• 狀態：backlog → active → done | cancelled
• 標籤：對任務進行分類（bug、feature、docs 等）
• 歷史記錄：每次狀態更改都會自動記錄，還可以手動添加筆記
• 查看器集成：瀏覽器查看器中的任務標籤頁，即時更新
• 持久性：任務在會話之間保持不變，存儲在 .aidex/index.db 中

你的AI助手可以在工作時創建任務（"在解析器中發現一個錯誤，將其添加到待辦事項列表中"），跟蹤進度，並在下一個會話中繼續之前的工作。

全局搜索

在所有已索引的項目中同時進行搜索。非常適合回答 "我是否曾經編寫過一個透明窗口？" 或 "我在哪裡使用過那個算法？" 等問題。

設置

aidex_global_init({ path: "Q:/develop" })                              # 掃描並註冊
aidex_global_init({ path: "Q:/develop", exclude: ["llama.cpp"] })      # 跳過外部倉庫
aidex_global_init({ path: "Q:/develop", index_unindexed: true })       # 自動索引所有找到的項目
aidex_global_init({ path: "Q:/develop", index_unindexed: true, show_progress: true })  # 帶有瀏覽器進度UI

這會掃描你的項目目錄，將所有使用AiDex建立索引的項目註冊到全局數據庫（~/.aidex/global.db）中，並通過檢測項目標記（.csproj、package.json、Cargo.toml 等）報告任何未索引的項目。

使用 index_unindexed: true 時，它還會自動為所有發現的代碼文件數量 ≤500 的項目建立索引。較大的項目會單獨列出，供用戶決定。添加 show_progress: true 可以在瀏覽器中打開即時進度UI（http://localhost:3334）。

搜索

aidex_global_query({ term: "TransparentWindow" })                      # 精確匹配
aidex_global_query({ term: "transparent", mode: "contains" })          # 模糊搜索
aidex_global_signatures({ name: "Render", kind: "method" })            # 查找方法
aidex_global_signatures({ name: "Player", kind: "class" })             # 查找類

工作原理

• 使用SQLite的 ATTACH DATABASE 直接查詢項目數據庫 —— 無需複製數據
• 結果會緩存在內存中（TTL為5分鐘），以便快速重複查詢
• 項目會分批處理（每次8個），以遵守SQLite的附件限制
• 每個項目都將自己的 .aidex/index.db 作為唯一的事實來源
• 自動去重：包含子項目的父項目會自動跳過（例如，當 MyApp/Frontend/ 和 MyApp/Backend/ 作為單獨的已索引項目存在時，MyApp/ 會被移除）

管理

aidex_global_status()                                                  # 列出所有項目
aidex_global_status({ sort: "recent" })                                # 最近索引的項目優先
aidex_global_refresh()                                                 # 更新統計信息，移除過時的項目

屏幕截圖 — LLM優化

截取屏幕截圖並將其大小 最多減少95%，以適應LLM上下文。典型的截圖大小從 ~100 KB 減少到 ~5 KB —— 每張圖片可節省數千個令牌。

為什麼這很重要

在AI上下文中，大多數截圖用於讀取文本 —— 錯誤消息、日誌、UI標籤。為此並不需要1600萬種顏色。

使用方法

aidex_screenshot()                                             # 全屏截圖（全質量）
aidex_screenshot({ mode: "active_window" })                    # 活動窗口截圖
aidex_screenshot({ mode: "window", window_title: "VS Code" }) # 指定窗口截圖
aidex_screenshot({ scale: 0.5, colors: 2 })                   # 黑白、半尺寸（最適合文本）
aidex_screenshot({ scale: 0.5, colors: 16 })                  # 16色（UI可讀）
aidex_screenshot({ colors: 256 })                              # 256色（質量較好）
aidex_screenshot({ mode: "region" })                           # 交互式選擇區域
aidex_screenshot({ mode: "rect", x: 100, y: 200, width: 800, height: 600 })  # 按座標截圖
aidex_windows({ filter: "chrome" })                            # 查找窗口標題

優化參數

AI助手的推薦策略

工具描述會告知LLM自動進行優化：

1. 首先採用激進設置：scale: 0.5, colors: 2（儘可能小）
2. 如果無法讀取：使用 colors: 16 重試（為UI元素添加陰影）
3. 如果仍然不清楚：嘗試 scale: 0.75 或全綵色
4. 記住：在會話的剩餘時間內，緩存每個窗口/應用適用的設置

這樣，AI可以瞭解每個應用的合適設置，而不會在過大的圖像上浪費令牌。

特性

• 5種截圖模式：全屏、活動窗口、指定窗口（按標題）、交互式區域選擇、按座標矩形截圖
• 跨平臺：Windows（PowerShell + System.Drawing）、macOS（sips + ImageMagick）、Linux（ImageMagick）
• 多顯示器支持：選擇要捕獲的顯示器
• 延遲功能：在截圖前等待N秒（例如，先打開菜單）
• 大小報告：顯示原始大小 → 優化後的大小以及節省的百分比
• 自動路徑：默認保存到臨時目錄，文件名固定
• 無需索引：獨立工作，無需 .aidex/ 目錄

交互式查看器

在瀏覽器中直觀地探索已索引的項目：

aidex_viewer({ path: "." })

打開 http://localhost:3333，其中包含：

• 交互式文件樹 - 點擊展開目錄
• 文件簽名信息 - 點擊任何文件查看其類型和方法
• 即時重新加載 - 在你編碼時自動檢測更改
• Git狀態圖標 - 查看哪些文件已修改、已暫存或未跟蹤

使用 aidex_viewer({ path: ".", action: "close" }) 關閉。

CLI使用方法

aidex scan Q:/develop       # 查找所有已索引的項目
aidex init ./myproject      # 從命令行對項目進行索引

aidex-mcp 可作為 aidex 的別名使用。

🔧 技術細節

性能表現

技術選型

• 解析器：Tree-sitter - 真正的解析，而非正則表達式
• 數據庫：採用WAL模式的SQLite - 快速、單個文件、零配置
• 協議：MCP - 可與任何兼容的AI配合使用

項目結構

.aidex/                  ← 在你的項目中創建
├── index.db             ← SQLite數據庫
└── summary.md           ← 可選文檔

AiDex/                   ← 本倉庫
├── src/
│   ├── commands/        ← 工具實現
│   ├── db/              ← SQLite包裝器
│   ├── parser/          ← Tree-sitter集成
│   └── server/          ← MCP協議處理程序
└── build/               ← 編譯輸出