Aidex

AiDex

AI 编码 Agent 的持久大脑。

AiDex 是一个 MCP 服务，为 AI 编码助手提供记忆、语义搜索和实时遥测功能——本地优先，兼容各种模型。适用于任何兼容 MCP 的 AI 助手：Claude Code、Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code Copilot 等。

三大支柱

🧠 记忆 — 任务、笔记和会话笔记会在每次聊天后保留。自动记录历史、安排任务、跨会话保持连续性。你的 AI 能记住今天的重要事项，并在明天继续了解它们。

🔍 搜索 — 三种模式：exact（标识符）、semantic（概念）、hybrid（融合两者的 RRF）。将代码、文档和工作区项目嵌入同一排名。跨项目搜索——一次查询即可搜索所有代码库。可选的 LLM 层可转换非英语查询并对结果重新排序。

🌐 遥测 — LogHub 通过 HTTP 接收来自任何应用的实时日志（无需 SDK）。AI 关注代码的实际行为，而不只是它的描述。日志会在 Viewer 中实时流式传输。

支持 14 种语言——C#、TypeScript、JavaScript、Rust、Python、C、C++、Java、Go、PHP、Ruby、HCL/Terraform、Kotlin、Swift——另支持 Astro frontmatter

# Find where "PlayerHealth" is defined — 1 call, ~50 tokens
aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156

# All methods in a file — without reading the whole file
aidex_signature({ file: "src/Engine.cs" })
→ class GameEngine { Update(), Render(), LoadScene(), ... }

# What changed in the last 2 hours?
aidex_query({ term: "render", modified_since: "2h" })

# Search across ALL your projects at once
aidex_global_query({ term: "TransparentWindow", mode: "contains" })
→ Found in: LibWebAppGpu (3 hits), DebugViewer (1 hit)

# Leave a note for your next session
aidex_note({ path: ".", note: "Test the parser fix after restart" })

# Create a task while working
aidex_task({ path: ".", action: "create", title: "Fix edge case in parser", priority: 1, tags: "bug" })

目录

• 内容一览
• 语义搜索和 LLM 层 🆕
• 问题
• 解决方案
• 为什么不直接用 Grep？
• 工作原理
• 功能
• 支持的语言
• 快速开始
• 可用工具
• 按时间筛选
• 项目结构
• 会话备注
• 任务待办
• 全局搜索
• AI 指南
• 日志中心
• 调试面板
• 屏幕截图 — 针对大模型优化
• 交互式 Viewer
• CLI 用法
• 性能
• 技术
• 贡献
• 许可证

语义搜索和 LLM 层

v2.0 新增了通过本地运行的嵌入模型实现的语义搜索——即使 AI 不知道确切的标识符，也能找到函数。

三种模式——根据问题选择合适的工具

嵌入的内容

• 代码 — 每个方法和类型，采用三层分块（签名 + 文档注释 + 加权标识符集合）
• 文档 — Markdown 章节（README、CHANGELOG、docs/、计划文件），按标题边界拆分
• 工作区 — 任务、任务日志、会话笔记、归档笔记历史

一种排序，涵盖所有类型。像 “如何从外部程序写入日志” 这样的查询，会首先显示 README 的 ## Log Hub 章节，然后是 commands/log.ts 中的 log 方法，接着是任何相关任务。

设置

// Enable embeddings on a project (one-time, ~30s for AiDex itself, cached afterwards)
aidex_init({ path: ".", embeddings: true })

// Search
aidex_search({ query: "how do we batch requests to the LLM", path: "." })
aidex_search({ query: "retry with backoff", scope: "all" })  // across every embedded project

也可以在 Viewer 的 Settings 选项卡中设置（aidex_settings({ path: ".", open: true })）——可切换嵌入、LLM 提供商、模型和隐私开关。

可选的 LLM 层

配置 Anthropic / OpenAI / OpenRouter / Ollama / HuggingFace API 密钥后，AiDex 可以：

• 翻译非英语查询 → “wie speichere ich Logs lokal” 可找到正确的代码
• 扩展含糊的查询，将其转换为 2-4 个具体子查询（通过 RRF 合并）
• 重排排名靠前的检索候选项

隐私开关 llm_send_code 默认关闭——只会发送原始查询和元数据（路径、名称、锚点）。代码正文保留在本地。设置按项目生效，可在 Settings 中轻松验证。

本地优先：使用纯嵌入即可完全离线运行。LLM 层为可选功能，绝非必需。

问题

每次 AI 助手搜索代码时，它都会：

• 使用 Grep 搜索数千个文件 → 数百条结果涌入上下文
• 逐个读取文件以了解结构 → 消耗更多上下文
• 在会话结束时忘记所有内容 → 一切从头开始

一个“X 定义在哪里？”的问题就可能消耗 2,000 多个 token。这样做 10 次，仅导航就会耗掉一半上下文。

解决方案

索引一次，永久查询：

# Before: grep flooding your context
AI: grep "PlayerHealth" → 200 hits in 40 files
AI: read File1.cs, File2.cs, File3.cs...
→ 2000+ tokens consumed, 5+ tool calls

# After: precise results, minimal context
AI: aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156
→ ~50 tokens, 1 tool call

结果：代码导航所用的上下文减少 50-80%。

为什么不直接使用 Grep？

Grep 的实际成本：每条 Grep 结果都包含周围的上下文。在大型项目中搜索 User，会得到数百条命中结果——注释、字符串、部分匹配项。AI 会逐一读取，因噪声而消耗上下文 token。

AiDex 为标识符建立索引：它使用 Tree-sitter 真正解析代码。搜索 User 时，会得到类定义、方法参数、变量声明，而不是每条提到“user”的注释。

工作原理

1. 为项目建立一次索引（每 1000 个文件约需 1 秒）

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

2. 让 AI 搜索索引，而不是使用 Grep

   aidex_query({ term: "Calculate", mode: "starts_with" })
   → All functions starting with "Calculate" + exact line numbers
   
   aidex_query({ term: "Player", modified_since: "2h" })
   → Only matches changed in the last 2 hours
   

3. 获取文件概览，无需读取整个文件

   aidex_signature({ file: "src/Engine.cs" })
   → All classes, methods, and their signatures
   

索引存储在 .aidex/index.db（SQLite）中——速度快、可移植、无外部依赖。

功能

• Tree-sitter 解析：真正解析代码，而非使用正则表达式——为标识符建立索引，并忽略关键字和噪声
• 每次搜索约 50 个 token：Grep 则需 2000 多个——让 AI 将上下文留给实际工作
• 持久化索引：跨会话保留——无需重新扫描或读取
• 增量更新：更改后只需为单个文件重新建立索引，无需处理整个项目
• 按时间筛选：查找过去一小时、一天或一周内的变更
• 自动清理：自动从索引中移除排除的文件（例如构建输出）
• 零依赖：采用 WAL 模式的 SQLite——单个文件、速度快、可移植

支持的语言

快速开始

前置条件

• Node.js ≥ 20（使用 node --version 检查）
  • macOS：brew install node 或 nvm install 20 && nvm use 20
  • Linux：使用你的包管理器或 nvm
  • Windows：nodejs.org
  • 如果你使用 nvm，仓库附带了 .nvmrc——运行 nvm use 会自动选择合适的版本。

1. 安装

npm install -g aidex-mcp

就这样。 安装后会自动运行设置程序——它会检测已安装的 AI 客户端（Claude Code、Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code Copilot），并将 AiDex 注册为 MCP 服务。它还会将使用说明添加到你的 AI 配置中（~/.claude/CLAUDE.md、~/.gemini/GEMINI.md）。

手动重新运行设置程序：aidex setup | 取消注册：aidex unsetup | 跳过自动设置：AIDEX_NO_SETUP=1 npm install -g aidex-mcp

2. 或手动向你的 AI 助手注册

对于 Claude Code（~/.claude/settings.json 或 ~/.claude.json）：

{
  "mcpServers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex",
      "env": {}
    }
  }
}

对于 Claude Desktop（Windows 上为 %APPDATA%/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}

注意： aidex 和 aidex-mcp 都可以用作命令名称。

重要： 配置中的服务名称决定了 MCP 工具前缀。请使用上面所示的 "aidex"——这样你会得到 aidex_query、aidex_signature 等工具名称。使用其他名称（例如 "codegraph"）会相应地改变前缀。

对于 Gemini CLI（~/.gemini/settings.json）：

{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}

对于 VS Code Copilot（在命令面板中运行 MCP: Open User Configuration）：

{
  "servers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex"
    }
  }
}

对于其他 MCP 客户端：请参阅客户端文档，了解 MCP 服务配置。

3. 让 AI 真正使用它

将以下内容添加到 AI 的指令中（例如 Claude Code 的 ~/.claude/CLAUDE.md，或 AI 客户端对应的文件）。这会告诉 AI 何时以及如何使用 AiDex，而不是使用 grep：

## AiDex - Persistent Code Index (MCP Server)

AiDex provides fast, precise code search through a pre-built index.
**Always prefer AiDex over Grep/Glob for code searches.**

### REQUIRED: Before using Grep/Glob/Read for code searches

我是否要搜索代码？ ├── 存在 .aidex/ → 停止！改用 AiDex ├── 不存在 .aidex/ → 运行 aidex_init（无需询问），然后使用 AiDex └── 配置/日志/文本 → 可以使用 Grep/Read

**NEVER do this when .aidex/ exists:**
- ❌ `Grep pattern="functionName"` → ✅ `aidex_query term="functionName"`
- ❌ `Grep pattern="class.*Name"` → ✅ `aidex_query term="Name" mode="contains"`
- ❌ `Read file.cs` to see methods → ✅ `aidex_signature file="file.cs"`
- ❌ `Glob pattern="**/*.cs"` + Read → ✅ `aidex_signatures pattern="**/*.cs"`

### Session-Start Rule (REQUIRED — every session, no exceptions)

1. Call `aidex_session({ path: "<project>" })` — detects external changes, auto-reindexes
2. If `.aidex/` does NOT exist → run `aidex_init` automatically (don't ask)
3. If a session note exists → **show it to the user** before continuing
4. **Before ending a session:** always leave a note about what to do next

### Question → Right Tool

| Question | Tool |
|----------|------|
| "Where is X defined?" | `aidex_query term="X"` |
| "Find anything containing X" | `aidex_query term="X" mode="contains"` |
| "All functions starting with X" | `aidex_query term="X" mode="starts_with"` |
| "What methods does file Y have?" | `aidex_signature file="Y"` |
| "Explore all files in src/" | `aidex_signatures pattern="src/**"` |
| "Project overview" | `aidex_summary` + `aidex_tree` |
| "What changed recently?" | `aidex_query term="X" modified_since="2h"` |
| "What files changed today?" | `aidex_files path="." modified_since="8h"` |
| "Have I ever written X?" | `aidex_global_query term="X" mode="contains"` |
| "Which project has class Y?" | `aidex_global_signatures term="Y" kind="class"` |
| "All indexed projects?" | `aidex_global_status` |

### Search Modes

- **`exact`** (default): Finds only the exact identifier — `log` won't match `catalog`
- **`contains`**: Finds identifiers containing the term — `render` matches `preRenderSetup`
- **`starts_with`**: Finds identifiers starting with the term — `Update` matches `UpdatePlayer`, `UpdateUI`

### All Tools (30)

| Category | Tools | Purpose |
|----------|-------|---------|
| Search & Index | `aidex_init`, `aidex_query`, `aidex_update`, `aidex_remove`, `aidex_status` | Index project, search identifiers (exact/contains/starts_with), time filter |
| Signatures | `aidex_signature`, `aidex_signatures` | Get classes + methods without reading files |
| Overview | `aidex_summary`, `aidex_tree`, `aidex_describe`, `aidex_files` | Entry points, file tree, file listing by type |
| Cross-Project | `aidex_link`, `aidex_unlink`, `aidex_links`, `aidex_scan` | Link dependencies, discover projects |
| Global Search | `aidex_global_init`, `aidex_global_query`, `aidex_global_signatures`, `aidex_global_status`, `aidex_global_refresh` | Search across ALL projects |
| Guidelines | `aidex_global_guideline` | Persistent AI instructions & conventions (key-value, global) |
| Sessions | `aidex_session`, `aidex_note` | Track sessions, leave notes (with searchable history) |
| Tasks | `aidex_task`, `aidex_tasks` | Built-in backlog with priorities, tags, summaries, auto-logged history, scheduled/recurring tasks |
| Log Hub | `aidex_log` | Universal log receiver — any program sends logs via HTTP, AI queries them, live in Viewer |
| Screenshots | `aidex_screenshot`, `aidex_windows` | Screen capture with LLM optimization (scale + color reduction, no index needed) |
| Viewer | `aidex_viewer` | Interactive browser UI with file tree, signatures, tasks, and live logs |

**14 languages:** C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby, HCL/Terraform, Kotlin, Swift — plus Astro frontmatter

### Session Notes

Leave notes for the next session — they persist in the database:

aidex_note({ path: ".", note: "重启后测试修复效果" }) # 写入 aidex_note({ path: ".", note: "还要检查边缘情况", append: true }) # 追加 aidex_note({ path: "." }) # 读取 aidex_note({ path: ".", search: "parser" }) # 搜索历史记录 aidex_note({ path: ".", clear: true }) # 清除

- **Before ending a session:** automatically leave a note about next steps
- **User says "remember for next session: ..."** → write it immediately

### Task Backlog

Track TODOs, bugs, and features right next to your code index:

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

计划任务和定期任务

aidex_task({ path: ".", action: "create", title: "检查 PR 状态", due: "3d", interval: "3d", task_action: "gh pr list" })

Priority: 1=high, 2=medium, 3=low | Status: `backlog → active → done | cancelled`

### Global Search (across all projects)

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" }) # 列出所有项目

### Screenshots

aidex_screenshot() # 全屏 aidex_screenshot({ mode: "active_window" }) # 当前活动窗口 aidex_screenshot({ mode: "window", window_title: "VS Code" }) # 指定窗口 aidex_screenshot({ scale: 0.5, colors: 2 }) # 黑白、半尺寸（适合大模型） aidex_screenshot({ colors: 16 }) # 16 色（便于阅读 UI） aidex_windows({ filter: "chrome" }) # 查找窗口标题

No index needed. Returns file path → use `Read` to view immediately.

**LLM optimization strategy:** Always start with aggressive settings, then retry if unreadable:
1. First try: `scale: 0.5, colors: 2` (B&W, half size — smallest possible)
2. If unreadable: retry with `colors: 16` (adds shading for UI elements)
3. If still unclear: `scale: 0.75` or omit `colors` for full quality
4. **Remember** what works for each window/app during the session — don't retry every time.

4. 为项目建立索引

向你的 AI 提问：“使用 AiDex 为此项目建立索引”

或者在 AI 聊天中手动操作：

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

可用工具

按时间筛选

使用 modified_since 和 modified_before 跟踪近期更改：

aidex_query({ term: "render", modified_since: "2h" })   # Last 2 hours
aidex_query({ term: "User", modified_since: "1d" })     # Last day
aidex_query({ term: "API", modified_since: "1w" })      # Last week

支持的格式：

• 相对时间：30m（分钟）、2h（小时）、1d（天）、1w（周）
• ISO 日期：2026-01-27 或 2026-01-27T14:30:00

非常适合回答 “我在过去一小时内改了什么？” 之类的问题。

项目结构

AiDex 会为项目中的所有文件（不仅限于代码）建立索引，让你可以查询项目结构：

aidex_files({ path: ".", type: "config" })  # All config files
aidex_files({ path: ".", type: "test" })    # All test files
aidex_files({ path: ".", pattern: "**/*.md" })  # All markdown files
aidex_files({ path: ".", modified_since: "30m" })  # Changed this session

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

使用 modified_since 查找本次会话中更改的文件，非常适合回答 “我编辑了什么？”

会话笔记

为下次会话留下提醒——再也不会在聊天之间丢失上下文：

aidex_note({ path: ".", note: "Test the glob fix after restart" })  # Write
aidex_note({ path: ".", note: "Also check edge cases", append: true })  # Append
aidex_note({ path: "." })                                              # Read
aidex_note({ path: ".", clear: true })                                 # Clear

笔记历史（v1.10）：覆盖或清除旧笔记时，会自动将其归档。浏览并搜索过往笔记：

aidex_note({ path: ".", history: true })                    # Browse archived notes (shows summaries)
aidex_note({ path: ".", search: "parser" })                 # Search note history (searches summaries too)
aidex_note({ path: ".", history: true, limit: 5 })          # Last 5 archived notes

笔记摘要（v1.15）：写入或清除笔记时提供 summary，归档的笔记便会附带这句描述。历史记录随后会显示摘要，而不是截断的文本：

aidex_note({ path: ".", note: "New focus", summary: "Previous session: finished parser refactoring" })

使用场景：

• 结束会话前：“记得下次测试 X”
• AI 自动提醒：保存重启后需要验证的内容
• 交接笔记：为下次会话保留上下文，无需编辑配置文件
• 搜索过往会话：“我们之前对解析器做了什么？”

笔记存储在 SQLite 数据库（.aidex/index.db）中，并会永久保留。

任务待办列表

将项目任务与代码索引放在一起——无需 Jira、Trello，也无需切换上下文：

aidex_task({ path: ".", action: "create", title: "Fix parser bug", priority: 1, tags: "bug", summary: "Parser crashes on nested generics in C#" })
aidex_task({ path: ".", action: "update", id: 1, status: "done" })
aidex_task({ path: ".", action: "log", id: 1, note: "Root cause: unbounded buffer" })
aidex_tasks({ path: ".", status: "active" })

计划任务与重复任务

任务可以设置截止日期和重复间隔。每次会话开始时，系统都会报告所有项目中已逾期的任务：

# One-shot: remind in 3 days
aidex_task({ path: ".", action: "create", title: "Review PR", due: "3d", task_action: "Check if PR was submitted" })

# Recurring: check every week
aidex_task({ path: ".", action: "create", title: "Check dependencies", due: "1w", interval: "1w", task_action: "npm outdated" })

# Auto-execute: runs the action automatically when due
aidex_task({ path: ".", action: "create", title: "Refresh stats", due: "1d", interval: "1d", auto_go: true })

**截止时间格式：**相对时间（"30m"、"2h"、"3d"、"1w"）或 ISO 日期（"2026-04-10"）

每次调用 aidex_session 时，任务调度器都会检查 ~/.aidex/global.db，查找所有项目中的到期任务——即使你正在处理其他项目也一样。重复任务每次触发后都会自动更新截止日期。

功能：

• 摘要：每个任务附带一句话目录摘要——无需阅读完整详情即可浏览待办列表
• 优先级：🔴 高、🟡 中、⚪ 低
• 状态：backlog → active → done | cancelled
• 标签：对任务分类（bug、feature、docs 等）
• 历史记录：每次状态变更都会自动记录，也支持手动添加备注
• 计划安排：截止日期、重复间隔、操作，以及跨所有项目自动执行
• 查看器集成：浏览器查看器中的任务选项卡支持实时更新
• 持久保存：任务存储在 .aidex/index.db 中，会在会话之间保留

AI 助手可以在工作时创建任务（“发现解析器有个 bug，把它添加到待办列表”）、跟踪进度，并在下次会话中从上次中断处继续。

全局搜索

一次搜索所有已建立索引的项目。非常适合查找*“我以前写过透明窗口吗？”或“我在哪里用过那个算法？”*

设置

aidex_global_init({ path: "Q:/develop" })                              # Scan & register
aidex_global_init({ path: "Q:/develop", exclude: ["llama.cpp"] })      # Skip external repos
aidex_global_init({ path: "Q:/develop", index_unindexed: true })       # Auto-index all found projects
aidex_global_init({ path: "Q:/develop", index_unindexed: true, show_progress: true })  # With browser progress UI

这会扫描你的项目目录，将所有已建立 AiDex 索引的项目注册到全局数据库（~/.aidex/global.db），并通过检测项目标记文件（.csproj、package.json、Cargo.toml 等）报告发现的未建立索引项目。

设置 index_unindexed: true 后，还会自动为发现的代码文件数不超过 500 个的项目建立索引。更大的项目会单独列出，供用户决定。添加 show_progress: true 可在浏览器中打开实时进度界面（http://localhost:3334）。

搜索

aidex_global_query({ term: "TransparentWindow" })                      # Exact match
aidex_global_query({ term: "transparent", mode: "contains" })          # Fuzzy search
aidex_global_signatures({ term: "Render", kind: "method" })            # Find methods
aidex_global_signatures({ term: "Player", kind: "class" })             # Find classes

工作原理

• 使用 SQLite 的 ATTACH DATABASE 直接查询项目数据库——无需复制数据
• 将结果缓存在内存中（TTL 为 5 分钟），以加快重复查询
• 每批处理 8 个项目，以遵守 SQLite 的附加数据库数量限制
• 每个项目都将自己的 .aidex/index.db 作为唯一真实数据源
• 自动去重：自动跳过包含子项目的父项目（例如，当 MyApp/Frontend/ 和 MyApp/Backend/ 作为独立项目分别建立索引时，会移除 MyApp/）

管理

aidex_global_status()                                                  # List all projects
aidex_global_status({ sort: "recent" })                                # Most recently indexed first
aidex_global_refresh()                                                 # Update stats, remove stale

AI 指南

将持久化的编码规范、审查清单和 AI 指令集中存放在一处，并在所有项目间共享。

aidex_global_guideline({ action: "set", key: "review", value: "Always check: error handling, null safety, no hardcoded strings" })
aidex_global_guideline({ action: "set", key: "style", value: "Use PascalCase for classes, camelCase for methods, 4-space indent" })
aidex_global_guideline({ action: "get", key: "review" })               # Retrieve a guideline
aidex_global_guideline({ action: "list" })                             # Show all guidelines
aidex_global_guideline({ action: "list", filter: "code" })             # Filter by name
aidex_global_guideline({ action: "delete", key: "old-rule" })          # Remove a guideline

使用场景：

• 代码审查清单：明确告诉 AI 每次审查时要检查哪些内容
• 编码规范：只需保存一次团队的风格规范，即可在任何项目中引用
• 发布清单：用于发布的分步流程
• 项目无关的指令：无需再在每次会话中重复粘贴相同的上下文

指南存储在 ~/.aidex/global.db 中，无需 aidex_init 即可在所有项目中使用。向 AI 提问：“加载审查指南并将其应用于此文件。”

Log Hub — 通用日志记录

让任何程序都能成为 AI 助手的日志来源。你的应用通过 HTTP POST 发送日志，AI 通过 MCP 查询日志，你则可以在 Viewer 中实时查看——无需依赖项，也无需在代码中进行任何设置。

工作原理

Your Program ──HTTP POST──→ AiDex Log Hub (port 3335) ──→ Ring Buffer
                                        │                      │
                                        │ WebSocket             │ MCP query
                                        ↓                      ↓
                                   Viewer (Logs tab)      AI Assistant
                                   (you see live)       (queries & analyzes)

快速开始

1. AI 启动 Log Hub：aidex_log({ action: "init" })
2. AI 打开 Viewer：aidex_viewer({ path: "." }) — Logs 选项卡会显示实时流
3. 在程序中添加一行代码：

// C#
await new HttpClient().PostAsJsonAsync("http://localhost:3335/log",
    new { level = "info", source = "MyApp", message = "Player spawned", data = new { x = 10, y = 20 } });

# Python
requests.post("http://localhost:3335/log", json={"level": "info", "source": "MyApp", "message": "Done"})

// JavaScript
fetch("http://localhost:3335/log", {
    method: "POST", headers: {"Content-Type": "application/json"},
    body: JSON.stringify({level: "info", source: "MyApp", message: "Started"})
});

# PowerShell
Invoke-RestMethod -Uri http://localhost:3335/log -Method POST -ContentType "application/json" -Body '{"level":"info","source":"Script","message":"Done"}'

HTTP API

字段： level（debug/info/warn/error）、source（应用名称）、message（文本，必填）、data（可选 JSON）、timestamp（可选，毫秒）

功能

• 环形缓冲区：固定大小的内存 FIFO（默认 10,000 条记录）——覆盖最旧的记录
• 零开销：调用 init 前不会启动服务、创建缓冲区或占用资源
• 持久化：可选的 SQLite 存储，并自动清理 7 天前的数据（persist: true）
• 消费模式：使用 consume: true 查询时会移除返回的记录——非常适合轮询
• Viewer 集成：Logs 选项卡支持 WebSocket 实时流、级别/来源/文本筛选和自动滚动
• 即发即忘：只需发送 POST 请求即可——如果服务未运行，请求会静默失败

Control API——让 AI 驱动你的应用

日志和仪表板小组件沿着 应用 → AI 的方向流动。Control API 则是返回通道：AI → 应用。它将 Log Hub 变成一个小巧、零依赖的命令总线——这样，AI 助手就能驱动任何正在运行的程序，而无需你编写服务端。

AI 设置命令；你的应用轮询获取命令、执行命令，并回传结果：

AI ──control_set {id,cmd}──→  Hub  ←──GET /control──  Your App (polls ~1s)
AI ←──control_get──── result ─ Hub  ←──POST /control── runs it, posts result + ack

• control_set { id, value } — AI（或 Viewer 滑块/开关）设置一个控制槽。
• GET /control — 应用读取所有当前控制值。
• POST /control — 应用回写结果／确认信息。
• POST /control/press { id } — 为一个 button 控制项登记一次按下操作。计数器由 hub 管理，因此多个已打开的仪表板产生的按下操作会累加，而不会相互覆盖。
• control_get — AI 读取应用上报的内容。
• POST /control/subscribe （可选） — 使用推送替代轮询，见下文。

使用推送替代轮询。 如果你的应用运行着自己的 HTTP 服务，可以通过 { "port": 8080 } 订阅一次（hub 会回调发送方的地址，路径默认为 /control），也可以提供完整的 { "url": "http://192.168.1.50:8080/control" }，还可以选择仅订阅 { "ids": [...] } 中的项目。从此以后，每次发生变化都会立即以 POST 方式发送到该 URL，内容与 GET /control 返回的扁平 { id: value } 映射相同。没有空闲请求，也无需等待下一次轮询。hub 不会因你的应用而阻塞（超时为 1.5 秒，同一时间仅有一个请求在途；期间发生的变化会合并，因此最新值总会最后送达）；只会调用私有网络 IP 地址；连续 3 次投递失败后会取消订阅——重新订阅具有幂等性，可以随时进行。POST /control/unsubscribe { url } 可移除订阅。推送是补充，而非替代：请保留较慢的轮询（约 30 秒一次）作为安全保障；即便漏掉推送，按钮计数器也能确保无碍。

button 的值是按下计数器，而不是标志——你的应用按自己的节奏轮询，因此应与上次看到的计数进行比较，而不是检测它是否为“已按下”。任何向后的跳变都表示 hub 已重启或面板已清空：采用当前值，不要将其解读为按下了上百万次。

按照惯例，两个槽即可实现完整的请求／响应：AI 写入一个 *_cmd 槽，应用写入一个 *_result 槽，再用一个 *_ack 计数器确保每条命令都恰好执行一次（每次都递增命令 id；应用会跳过已处理过的任何 id）。

这就是完整协议。客户端只需要使用你已有的 HTTP 库。

实例——AI 控制 Autodesk Fusion 360

一个约 30 行的 Fusion 360 插件（仅使用 urllib，不需要 SDK）会轮询 GET /control，在 Fusion 的主线程上执行命令，并回传结果。无需其他任何东西，AI 助手就驱动 Fusion 以参数化方式设计出完整的 3D 外壳——包括草图、拉伸、带热熔嵌件的螺丝柱圆顶、USB-C 开孔、复位／按钮孔，并通过读取实际面的几何数据来验证每一步。

这种模式适用于各种场景：只要能够发送 POST 和 GET 请求，无论是 Blender、CNC 控制器、游戏还是家庭自动化 hub，都能通过几行代码变得可由 AI 操控，无需专门编写服务端。这个实现中有两条安全规则同样适用：

• **单线程 GUI API：**轮询循环绝不能直接调用应用 API。应触发事件，并在主线程上执行命令（这是 Fusion 的官方模式；任何非线程安全的 UI／COM API 也都适用）。
• **幂等性：**记录最后处理过的 id 并确认它——轮询意味着你会反复看到同一条命令，因此应跳过已执行的命令。

调试仪表板

滚动日志流非常适合查看何时发生了什么，但对于快速变化、反复更新的值（音频电平、缓冲区填充量、FPS、传感器读数）却毫无用处。调试仪表板则恰恰相反：这是一个固定槽位面板，每个值都有固定位置，并会原位覆盖，而不是滚动消失。它位于 Viewer 的 Live 标签页中，采用硬件监控器（MSI Afterburner / HWiNFO）风格。

它使用同一个 Log Hub 服务，无需额外设置。程序通过 HTTP POST 发送工具更新；再次发送相同的 id 即可更新对应工具。

工具类型

发送工具

# A single widget — id is the fixed slot, type is required on first send
curl -X POST http://localhost:3335/panel -H "Content-Type: application/json" \
  -d '{"id":"mic","type":"plot","value":0.73,"group":"Audio","label":"Mic Level","unit":"dB"}'

# A gauge with threshold zones (green < warn < yellow < crit < red)
curl -X POST http://localhost:3335/panel -H "Content-Type: application/json" \
  -d '{"id":"gpu_temp","type":"gauge","value":67,"min":0,"max":100,"warn":75,"crit":90,"group":"Hardware"}'

字段： id（必填）、type（label/progress/gauge/plot/slider/number/toggle/button，首次发送时必填）、value（数值、状态字符串，或表示完整绘图帧的数值数组）、group、label、unit、min、max、warn、crit、color、order。 端点： POST /panel（单个）、POST /panels（批量）、POST /panel/clear（单个时使用 {id}，全部清除时使用空内容）。

生命周期

• 服务会为每个 id 保留最后状态，因此新打开或重新加载的 Viewer 会立即显示完整仪表板。
• 约 3 秒未更新的卡片会变灰，并标记为“过期”。
• 清除会执行完全重置：清空存储。只有再次发送带有 type 的工具后，来源才会重新出现（仅发送值而不带类型、且对应 id 已清除的更新会被忽略）。
• 具有背压保护——浏览器运行缓慢不会导致服务的发送队列无限增长。

试用 — 内置演示

可直接运行的演示会展示所有工具类型的动画（音频波形、在各个区域间变化的 GPU 仪表、按正弦波 → 锯齿波 → 三角波 → 方波循环的信号发生器、延迟尖峰）：

# 1. Start the Log Hub + Viewer from your AI assistant:
#      aidex_log({ action: "init" })
#      aidex_viewer({ path: "." })       → click the Live tab
# 2. Run the demo (from the AiDex repo root):
node scripts/demo-dashboard.mjs           # endless loop, Ctrl+C to stop (clears on exit)

也可以使用 Live 标签页中的 ▷ Demo 按钮——它会将运行命令复制到剪贴板，再粘贴到终端中。（浏览器无法自行启动进程。）即使仪表板仍为空，该按钮也会保留在工具栏中，因为它可以帮你创建第一个工具。scripts/demo-dashboard.ps1 是一个只需一条命令的启动器，会先检查 Log Hub。

同时运行两次会启动两个实例，它们会争用同一批工具（肉眼可见地闪烁）——启动另一个实例前，请先停止旧实例（Ctrl+C）。

截图 — 针对大模型优化

截取屏幕截图并将其缩小至原大小的 5%，以便用于大模型上下文。典型截图的大小会从约 100 KB 降至约 5 KB——每张图可节省数千个 token。

为什么这很重要

AI 上下文中的大多数截图都是为了读取文本，例如错误消息、日志、UI 标签。为此，你不需要 1,600 万种颜色。

用法

aidex_screenshot()                                             # Full screen (full quality)
aidex_screenshot({ mode: "active_window" })                    # Active window
aidex_screenshot({ mode: "window", window_title: "VS Code" }) # Specific window
aidex_screenshot({ scale: 0.5, colors: 2 })                   # B&W, half size (best for text)
aidex_screenshot({ scale: 0.5, colors: 16 })                  # 16 colors (UI readable)
aidex_screenshot({ colors: 256 })                              # 256 colors (good quality)
aidex_screenshot({ mode: "region" })                           # Interactive selection
aidex_screenshot({ mode: "rect", x: 100, y: 200, width: 800, height: 600 })  # Coordinates
aidex_windows({ filter: "chrome" })                            # Find window titles

优化参数

面向 AI 助手的推荐策略

工具说明会提示大模型自动进行优化：

1. 先采用激进设置：scale: 0.5, colors: 2（尽可能缩小）
2. 如果无法阅读：使用 colors: 16 重试（为 UI 元素增加阴影）
3. 如果仍不清晰：尝试 scale: 0.75 或全彩
4. 记住：在本次会话剩余时间内，按窗口/应用缓存有效设置

这样，AI 就能为每个应用找到合适的设置，而不会把 token 浪费在过大的图片上。

功能

• 5 种捕获模式：全屏、活动窗口、指定窗口（按标题）、交互式区域选择、基于坐标的矩形区域
• 跨平台：Windows（PowerShell + System.Drawing）、macOS（sips + ImageMagick）、Linux（ImageMagick）
• 多显示器：选择要捕获的显示器
• 延迟：捕获前等待 N 秒（例如，先打开菜单）
• 尺寸报告：显示原始尺寸 → 优化后尺寸以及节省的百分比
• 自动路径：默认保存到临时目录，使用固定文件名
• 无需索引：可独立运行，无需 .aidex/

交互式查看器

在浏览器中直观地探索已建立索引的项目：

aidex_viewer({ path: "." })

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

• 交互式文件树 - 点击可展开目录
• 文件签名 - 点击任意文件即可查看其类型和方法
• 实时重新加载 - 编写代码时会自动检测更改
• Git 状态图标 - 查看哪些文件已修改、已暂存或未跟踪
• 搜索选项卡 - 跨代码、文档、任务和笔记进行语义／精确／混合搜索，并可选用 LLM 层（翻译 + 重排）
• Live 选项卡 - 实时调试面板：固定槽位小组件（图表、仪表、进度）以及交互式滑块、开关和按钮，可通过 /control 通道驱动正在运行的程序
• Logs 选项卡 - Log Hub 的实时日志流，支持筛选（级别、来源、文本搜索）
• Tasks 选项卡 - 查看和管理任务待办列表
• Settings 选项卡 - 配置嵌入和 LLM 提供商（隐私开关默认关闭）

调试面板 — 实时双向交互

Live 选项卡是一个带有固定槽位的实时面板：再次发送相同的 id 时，值会原位更新，而不会滚动消失。交互式 slider／number／toggle／button 小组件会将操作传回源端（HTTP /control，或使用 aidex_log control_set，让 AI 也能调整正在运行的程序）。button 携带的是按下计数器，而非标志，因此源端以自己的节奏轮询时也不会漏掉点击。完整指南：docs/loghub-panel-dashboard.md。

Controls 组中包含每种交互式控件各一个：一个滑块、两个切换开关，以及一个旁边显示按下计数器的按钮。继续向下滚动，多个来源会共用同一个面板 — hub 不知道任何值的含义，因此合成器固件和演示脚本可以并存，彼此互不知晓：

滑块会实时响应 — 观看 GIF：

查看器的其他部分

使用 aidex_viewer({ path: ".", action: "close" }) 关闭

CLI 用法

aidex scan Q:/develop       # Find all indexed projects
aidex init ./myproject      # Index a project from command line

aidex-mcp 可用作 aidex 的别名。

性能

技术

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

项目结构

.aidex/                  ← Created in YOUR project
├── index.db             ← SQLite database
└── summary.md           ← Optional documentation

AiDex/                   ← This repository
├── src/
│   ├── commands/        ← Tool implementations
│   ├── db/              ← SQLite wrapper
│   ├── parser/          ← Tree-sitter integration
│   └── server/          ← MCP protocol handler
└── build/               ← Compiled output

社区

GitHub 讨论区 — 提出问题、分享你的配置、提出想法。

贡献

完整详情请参阅 CONTRIBUTING.md。简要说明：

• 发现 Bug？ → 提交问题
• 有想法？ → 发起讨论
• 想添加新语言？ → 在 src/parser/languages/ 中添加关键词文件并提交 PR

许可证

MIT 许可证 - 请参阅 LICENSE

作者

Uwe Chalas & Claude