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. 在会话结束前：始终留下关于下一步操作的笔记

问题 → 合适的工具

| 问题 | 工具 | |----------|------| | "X 在哪里定义？" | aidex_query term="X" | | "查找包含 X 的所有内容" | aidex_query term="X" mode="contains" | | "所有以 X 开头的函数" | aidex_query term="X" mode="starts_with" | | "文件 Y 有哪些方法？" | aidex_signature file="Y" | | "探索 src/ 目录下的所有文件" | aidex_signatures pattern="src/**" | | "项目概述" | aidex_summary + aidex_tree | | "最近有哪些更改？" | aidex_query term="X" modified_since="2h" | | "今天有哪些文件发生了更改？" | aidex_files path="." modified_since="8h" | | "我是否曾经编写过 X？" | aidex_global_query term="X" mode="contains" | | "哪个项目包含类 Y？" | aidex_global_signatures term="Y" kind="class" | | "所有已索引的项目有哪些？" | aidex_global_status |

搜索模式

• exact（默认）：仅查找精确匹配的标识符 —— log 不会匹配 catalog
• contains：查找包含指定术语的标识符 —— render 会匹配 preRenderSetup
• starts_with：查找以指定术语开头的标识符 —— Update 会匹配 UpdatePlayer、UpdateUI

所有工具（共28个）

| 类别 | 工具 | 用途 | |----------|-------|---------| | 搜索与索引 | aidex_init, aidex_query, aidex_update, aidex_remove, aidex_status | 索引项目，搜索标识符（精确/包含/以...开头），进行时间过滤 | | 签名信息 | aidex_signature, aidex_signatures | 在不读取文件的情况下获取类和方法信息 | | 项目概述 | aidex_summary, aidex_tree, aidex_describe, aidex_files | 获取入口点、文件树、按类型列出文件 | | 跨项目操作 | aidex_link, aidex_unlink, aidex_links, aidex_scan | 链接依赖项，发现项目 | | 全局搜索 | aidex_global_init, aidex_global_query, aidex_global_signatures, aidex_global_status, aidex_global_refresh | 在所有项目中进行搜索 | | 准则设置 | aidex_global_guideline | 持久化AI指令和约定（键值对，全局） | | 会话管理 | aidex_session, aidex_note | 跟踪会话，留下笔记（可搜索历史记录） | | 任务管理 | aidex_task, aidex_tasks | 内置任务管理，支持优先级、标签和自动记录历史 | | 屏幕截图 | aidex_screenshot, aidex_windows | 支持LLM优化的屏幕截图（缩放 + 减少颜色，无需索引） | | 交互式查看器 | aidex_viewer | 具有文件树、签名信息、任务的交互式浏览器UI |

支持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" })

📚 详细文档

可用工具

| 工具 | 描述 | |------|-------------| | aidex_init | 为项目建立索引（创建 .aidex/ 目录） | | aidex_query | 按术语进行搜索（精确/包含/以...开头） | | aidex_signature | 获取单个文件的类和方法 | | aidex_signatures | 获取多个文件的签名信息（使用通配符） | | aidex_update | 重新索引单个更改的文件 | | aidex_remove | 从索引中移除已删除的文件 | | aidex_summary | 项目概述 | | aidex_tree | 带有统计信息的文件树 | | aidex_describe | 为概述添加文档说明 | | aidex_link | 链接另一个已索引的项目 | | aidex_unlink | 移除已链接的项目 | | aidex_links | 列出已链接的项目 | | aidex_status | 索引统计信息 | | aidex_scan | 在目录树中查找已索引的项目 | | aidex_files | 按类型列出项目文件（代码/配置/文档/资产） | | aidex_note | 读取/写入会话笔记（会话之间保持持久） | | aidex_session | 开始会话，检测外部更改，自动重新索引 | | aidex_viewer | 在浏览器中打开交互式项目树 | | aidex_task | 创建、读取、更新、删除带有优先级和标签的任务 | | aidex_tasks | 按状态、优先级或标签列出和过滤任务 | | aidex_screenshot | 截取屏幕截图（全屏、窗口、区域），可选择缩放和减少颜色 | | aidex_windows | 列出打开的窗口，用于截图目标选择 | | aidex_global_init | 扫描目录树，将所有已索引的项目注册到全局数据库中 | | aidex_global_status | 列出所有已注册的项目及其统计信息 | | aidex_global_query | 在所有已注册的项目中搜索术语 | | aidex_global_signatures | 在所有项目中按名称搜索方法/类型 | | aidex_global_refresh | 更新统计信息，从全局数据库中移除过时的项目 |

基于时间的过滤

使用 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 —— 每张图片可节省数千个令牌。

为什么这很重要

| | 原始截图 | 优化后（scale=0.5, colors=2） | |---|---|---| | 文件大小 | ~100 - 500 KB | ~5 - 15 KB | | 消耗的令牌数 | ~5,000 - 25,000 | ~250 - 750 | | 文本是否可读？ | 是 | 是 | | 颜色数量 | 1600万（24位） | 2（黑白） |

在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" })                            # 查找窗口标题

优化参数

| 参数 | 值 | 描述 | |-----------|--------|-------------| | scale | 0.1 - 1.0 | 缩放因子（0.5 = 半分辨率）。大多数HiDPI屏幕的分辨率通常是2 - 3倍。 | | colors | 2, 4, 16, 256 | 颜色减少。2 = 黑白，非常适合文本截图。 |

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 的别名使用。

🔧 技术细节

性能表现

| 项目 | 文件数量 | 项目项数量 | 索引时间 | 查询时间 | |---------|-------|-------|------------|------------| | 小型（AiDex） | 19 | 1,200 | <1s | 1 - 5ms | | 中型（RemoteDebug） | 10 | 1,900 | <1s | 1 - 5ms | | 大型（LibPyramid3D） | 18 | 3,000 | <1s | 1 - 5ms | | 超大型（MeloTTS） | 56 | 4,100 | ~2s | 1 - 10ms |

技术选型

• 解析器：Tree-sitter - 真正的解析，而非正则表达式
• 数据库：采用WAL模式的SQLite - 快速、单个文件、零配置
• 协议：MCP - 可与任何兼容的AI配合使用

项目结构

.aidex/                  ← 在你的项目中创建
├── index.db             ← SQLite数据库
└── summary.md           ← 可选文档

AiDex/                   ← 本仓库
├── src/
│   ├── commands/        ← 工具实现
│   ├── db/              ← SQLite包装器
│   ├── parser/          ← Tree-sitter集成
│   └── server/          ← MCP协议处理程序
└── build/               ← 编译输出