Probe

我们阅读代码的频率是编写代码的10倍。 Probe是一款代码与Markdown上下文引擎，内置代理，专为企业级代码库设计。

如今的AI编码工具大多采用“原始人式”的方法：用grep搜索一些文件，随机读取几行，然后寄希望于运气。这种方法在小型项目中或许奏效，但在真正的大型代码库面前却显得力不从心。

Probe则是一款专为阅读和推理而打造的上下文引擎。 它将你的代码视为代码，而非文本。通过AST解析理解代码结构；语义搜索精准定位关键内容。只需一次调用，你就能获得完整且有意义的上下文信息。

Probe代理专为代码理解而设计。它精通如何使用Probe引擎，在整个代码库中进行搜索、提取和推理。无论是基于规范的开发、代码审查、新员工入职，还是任何需要先理解后编写的任务，Probe代理都能完美胜任。

相比之下，其他工具往往需要10次以上的代理循环才能完成同样的工作，而Probe只需一次调用——更深入、更干净，且噪音更少。

---

目录

• 为什么选择Probe？
• 快速入门
• 功能特性
• 使用模式
  • Probe代理（MCP）
  • 原生MCP工具
  • CLI代理
  • 直接CLI命令
  • Node.js SDK
• LLM脚本
• 安装指南
• 支持的语言
• 文档
• 环境变量
• 贡献指南
• 许可证

---

为什么选择Probe？

大多数代码搜索工具无外乎两类：基于文本的（如grep、ripgrep）或基于嵌入的（如需要索引和嵌入模型的向量搜索）。而Probe则走出了第三条路：无需任何配置的AST感知型结构化搜索。

	grep/ripgrep	嵌入式工具（grepai、Octocode）	Probe
设置时间	无	几分钟（索引+嵌入服务）	无
代码理解能力	仅文本	文本片段（可能截断函数中间部分）	AST感知（返回完整的函数/类）
搜索方式	正则表达式	向量相似度	Elasticsearch风格的布尔查询 + BM25
结果质量	行片段	~512字符的文本块	完整的语义代码块
排序机制	无（按行顺序）	余弦相似度	BM25/TF-IDF/混合算法，配备SIMD加速
外部依赖	无	嵌入API（Ollama/OpenAI）	无
Token意识	无	部分支持	支持（--max-tokens，会话去重）
离线可用性	是	仅限本地模型	始终可用
AI代理集成	无	MCP服务器	完整的代理流程 + MCP + Vercel AI SDK

关键洞察：AI代理并不需要嵌入式搜索

基于嵌入的工具主要解决词汇不匹配的问题——比如用户输入“authentication”，而代码中却是verify_credentials。然而，当AI代理作为消费者时，LLM本身已经能够处理这一问题：

用户：“找到认证逻辑”
  -> LLM生成：probe搜索 "verify_credentials OR authenticate OR login OR auth_handler"
  -> Probe在毫秒级内返回完整的AST节点

LLM会将用户的意图转化为精确的布尔查询。Probe则提供了一套为此量身定制的强大查询语言（AND、OR、+required、-excluded、"exact phrases"、ext:rs、`lang:python等），结合会话去重功能，代理可以在短时间内执行3-4次快速搜索，覆盖的范围远超单次嵌入式查询——而且速度更快、结果确定，无需任何前期配置。

---

快速入门

方法一：通过MCP使用Probe代理（推荐）

我们的内置代理可与Claude Code原生集成，利用其身份验证机制，无需额外的API密钥。

在~/.claude/claude_desktop_config.json中添加以下内容：

{
  "mcpServers": {
    "probe": {
      "command": "npx",
      "args": ["-y", "@probelabs/probe@latest", "agent", "--mcp"]
    }
  }
}

Probe代理专为阅读和推理代码而设计。它可以借助Claude Code的身份验证（或Codex的身份验证），也可以通过你自己的API密钥与任何模型配合使用（例如GOOGLE_API_KEY）。

方法二：通过MCP使用原生Probe工具

如果你更倾向于直接访问搜索/查询/提取工具，而不经过代理层：

{
  "mcpServers": {
    "probe": {
      "command": "npx",
      "args": ["-y", "@probelabs/probe@latest", "mcp"]
    }
  }
}

方法三：直接使用CLI（无需MCP）

你可以直接在终端中使用Probe，无需任何AI编辑器：

# 使用Elasticsearch语法进行语义搜索
npx -y @probelabs/probe search "authentication AND login" ./src

# 提取第42行的代码块
npx -y @probelabs/probe extract src/main.rs:42

# AST模式匹配
npx -y @probelabs/probe query "fn $NAME($$$) -> Result<$RET>" --language rust

方法四：CLI代理

你可以在终端中直接提问关于任何代码库的问题：

# 一次性问答（适用于任何LLM提供商）
npx -y @probelabs/probe@latest agent "认证功能是如何实现的？"

# 具备代码编辑能力
npx -y @probelabs/probe@latest agent "重构登录函数" --allow-edit

---

功能特性

• 代码感知：Tree-sitter AST解析准确理解代码的实际结构
• 语义搜索：Elasticsearch风格的查询（AND、OR、NOT、短语、过滤条件）
• 完整上下文：返回完整的函数、类或结构体——而不是可能中断函数的文本片段
• 无需索引：对任何代码库即时响应。无需嵌入模型、向量数据库或任何配置
• 确定性：相同的查询始终返回相同的结果。没有模型差异，也没有过时的索引
• 完全本地化：你的代码永远不会离开你的设备。搜索过程中无需任何API调用
• 极速运行：SIMD加速的模式匹配 + ripgrep扫描 + rayon并行计算
• 智能排序：BM25、TF-IDF以及混合算法，并可选BERT重新排名
• Token意识：支持--max-tokens预算和基于会话的去重，避免重复上下文
• 内置代理：支持多提供商（Anthropic、OpenAI、Google、Bedrock），具备重试、回退和上下文压缩功能
• 多语言支持：Rust、Python、JavaScript、TypeScript、Go、C/C++、Java、Ruby、PHP、Swift、C#等

---

使用模式

Probe 代理（MCP）

使用 Probe 结合 AI 编辑器的推荐方式。Probe 代理是一种专门的代码助手，它能够对你的代码进行推理——而不仅仅是模式匹配。

{
  "mcpServers": {
    "probe": {
      "command": "npx",
      "args": ["-y", "@probelabs/probe@latest", "agent", "--mcp"]
    }
  }
}

为什么使用代理？

• 专为理解和推理代码而设计
• 借助 Claude Code / Codex 的身份验证（或使用你自己的 API 密钥）
• 针对复杂问题提供更智能的多步推理
• 内置代码编辑、任务委派等功能

代理选项：

选项	描述
--path <dir>	搜索目录（默认：当前目录）
--provider <name>	AI 提供者：anthropic、openai、google
--model <name>	覆盖模型名称
--prompt <type>	角色设定：code-explorer、engineer、code-review、architect
--allow-edit	启用代码修改
--enable-delegate	启用向子代理的任务委派
--enable-bash	启用 Bash 命令执行
--max-iterations <n>	最大工具迭代次数（默认：30）

---

原生 MCP 工具

直接访问 Probe 的搜索、查询和提取工具——无需代理层。当你希望你的 AI 编辑器直接调用 Probe 工具时，可以使用此方式。

{
  "mcpServers": {
    "probe": {
      "command": "npx",
      "args": ["-y", "@probelabs/probe@latest", "mcp"]
    }
  }
}

可用工具：

• search - 使用 Elasticsearch 风格查询的语义代码搜索
• query - 基于 AST 的结构化模式匹配
• extract - 按行号或符号名称提取代码块
• symbols - 列出文件中的所有符号（函数、类、常量），并附带行号

---

CLI 代理

直接在终端运行 Probe 代理：

# 一次性提问
npx -y @probelabs/probe@latest agent "排名算法是如何工作的？"

# 指定搜索路径
npx -y @probelabs/probe@latest agent "查找 API 端点" --path ./src

# 启用代码编辑
npx -y @probelabs/probe@latest agent "为 login() 添加错误处理" --allow-edit

# 使用自定义角色
npx -y @probelabs/probe@latest agent "审查这段代码" --prompt code-review

---

直接 CLI 命令

用于脚本编写和直接代码分析。

搜索命令

probe search <PATTERN> [PATH] [OPTIONS]

示例：

# 基本搜索
probe search "authentication" ./src

# 布尔运算符（Elasticsearch 语法）
probe search "error AND handling" ./
probe search "login OR auth" ./src
probe search "database NOT sqlite" ./

# 搜索提示（文件过滤）
probe search "function AND ext:rs" ./           # 仅 .rs 文件
probe search "class AND file:src/**/*.py" ./    # src/ 目录下的 Python 文件
probe search "error AND dir:tests" ./           # tests/ 目录下的文件

# 限制结果以适应 AI 上下文窗口
probe search "API" ./ --max-tokens 10000

关键选项：

选项	描述
--max-tokens <n>	限制返回的总 token 数
--max-results <n>	限制结果数量
--reranker <algo>	排序算法：bm25、tfidf、hybrid、hybrid2
--allow-tests	包含测试文件
--format <fmt>	输出格式：markdown、json、xml

抽取命令

probe extract <FILES> [OPTIONS]

示例：

# 提取第 42 行的函数
probe extract src/main.rs:42

# 按符号名称提取
probe extract src/main.rs#authenticate

# 提取行范围
probe extract src/main.rs:10-50

# 从编译器输出中提取
go test | probe extract

符号命令

probe symbols <FILES> [OPTIONS]

示例：

# 列出文件中的符号
probe symbols src/main.rs

# JSON 格式输出，便于程序化使用
probe symbols src/main.rs --format json

# 多个文件
probe symbols src/main.rs src/lib.rs

查询命令（AST 模式）

probe query <PATTERN> [PATH] [OPTIONS]

示例：

# 查找 Rust 中的所有异步函数
probe query "async fn $NAME($$$)" --language rust

# 查找 React 组件
probe query "function $NAME($$$) { return <$$$> }" --language javascript

# 查找具有特定方法的 Python 类
probe query "class $CLASS: def __init__($$$)" --language python

---

Node.js SDK

在你的应用程序中以编程方式使用 Probe。

import { ProbeAgent } from '@probelabs/probe/agent';

// 创建代理
const agent = new ProbeAgent({
  path: './src',
  provider: 'anthropic'
});

await agent.initialize();

// 提问
const response = await agent.answer('认证是如何工作的？');
console.log(response);

// 获取 token 使用情况
console.log(agent.getTokenUsage());

直接函数：

import { search, extract, query, symbols } from '@probelabs/probe';

// 语义搜索
const results = await search({
  query: 'authentication',
  path: './src',
  maxTokens: 10000
});

// 提取代码
const code = await extract({
  files: ['src/auth.ts:42'],
  format: 'markdown'
});

// 列出文件中的符号
const fileSymbols = await symbols({
  files: ['src/auth.ts']
});

// AST 模式查询
const matches = await query({
  pattern: 'async function $NAME($$$)',
  path: './src',
  language: 'typescript'
});

Vercel AI SDK 集成：

import { tools } from '@probelabs/probe';

const { searchTool, queryTool, extractTool } = tools;

// 与 Vercel AI SDK 结合使用
const result = await generateText({
  model: anthropic('claude-sonnet-4-6'),
  tools: {
    search: searchTool({ defaultPath: './src' }),
    query: queryTool({ defaultPath: './src' }),
    extract: extractTool({ defaultPath: './src' })
  },
  prompt: '查找认证代码'
});

---

LLM 脚本

Probe 代理可以使用 execute_plan 工具来运行确定性的多步代码分析任务。LLM 脚本是一个沙盒化的 JavaScript DSL，AI 可以在此生成可执行的计划，将搜索、提取和 LLM 推理结合在一个管道中。

// AI 生成的 LLM 脚本示例（await 会自动注入，无需手动编写）
const files = search("authentication login")
const chunks = chunk(files)
const analysis = map(chunks, c => LLM("总结认证模式", c))
return analysis.join("\n")

主要特性：

• 代理集成 - Probe 代理调用 execute_plan 工具来运行脚本
• 自动 await - 异步调用会自动等待（无需编写 await）
• 所有工具可用 - search()、query()、extract()、LLM()、map()、chunk()，以及任何 MCP 工具
• 沙盒执行 - 安全、隔离的 JavaScript 环境，并带有超时保护

有关语法和示例，请参阅完整的 LLM 脚本文档。

---

安装

NPM（推荐）

npm install -g @probelabs/probe

curl（macOS/Linux）

curl -fsSL https://raw.githubusercontent.com/probelabs/probe/main/install.sh | bash

PowerShell（Windows）

iwr -useb https://raw.githubusercontent.com/probelabs/probe/main/install.ps1 | iex

从源码安装

git clone https://github.com/probelabs/probe.git
cd probe
cargo build --release
cargo install --path .

---

支持的语言

语言	文件扩展名
Rust	.rs
JavaScript/JSX	.js, .jsx
TypeScript/TSX	.ts, .tsx
Python	.py
Go	.go
C/C++	.c, .h, .cpp, .cc, .hpp
Java	.java
Ruby	.rb
PHP	.php
Swift	.swift
C#	.cs
Markdown	.md

---

文档

完整文档可在 probelabs.com/probe 查看，或在本地 docs/ 目录中浏览。

入门指南

• 快速入门 - 5 分钟内上手使用
• 安装 - NPM、curl、Docker 以及从源码构建
• 功能概览 - 核心功能介绍

Probe CLI

• 搜索命令 - 类 Elasticsearch 风格的语义搜索
• 提取命令 - 提取包含完整 AST 上下文的代码块
• 符号命令 - 列出文件中的所有符号及其行号
• 查询命令 - 基于 AST 的结构化模式匹配
• CLI 参考 - 完整的命令行参考

LSP 与索引

• LSP 功能 - --lsp 模式为语义代码智能带来的增强
• LSP 快速参考 - 日常 LSP 命令速查表
• 索引概述 - 项目索引的概念与工作流程
• 索引 CLI 参考 - probe lsp index* 命令参考

LSP 功能包括调用层次结构增强（extract --lsp）、直接符号操作（probe lsp call definition|references|hover|...）、守护进程诊断（probe lsp logs --analyze）以及工作区索引（probe lsp index、probe lsp index-status）。

Probe Agent

• Agent 概述 - 什么是 Probe Agent 以及何时使用
• API 参考 - ProbeAgent 类文档
• Node.js SDK - 完整的 Node.js SDK 参考
• MCP 集成 - 编辑器集成指南
• LLM 脚本 - 可编程编排 DSL

指南与参考

• 查询模式 - 有效的搜索策略
• Probe 对比 - 与嵌入式搜索、知识图谱、LSP 工具的对比
• 架构 - 系统设计与内部实现
• 环境变量 - 所有配置选项
• 常见问题 - 常见问题解答

---

环境变量

# AI 供应商密钥
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...

# 供应商选择
FORCE_PROVIDER=anthropic
MODEL_NAME=claude-sonnet-4-6

# 自定义端点
ANTHROPIC_API_URL=https://your-proxy.com
OPENAI_API_URL=https://your-proxy.com

# 调试
DEBUG=1

---

贡献

我们欢迎各位贡献！请参阅我们的贡献指南。

如有任何问题或需要支持：

• GitHub Issues
• Discord 社区

---

许可证

---

如有任何问题或想参与贡献，请在 GitHub 上提交 issue，或加入我们的 Discord 社区 进行讨论与支持。祝编码愉快——也祝搜索顺利！

Probe 快速上手指南

Probe 是一款专为大规模代码库设计的代码与 Markdown 上下文引擎。它基于 AST（抽象语法树）解析而非简单的文本匹配，能够理解代码结构，提供完整的函数、类或模块上下文，是 AI 编程助手的理想搭档。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS, 或 Windows (WSL 推荐)
• Node.js：版本 18.0 或更高（用于运行 npx 命令）
• 无需额外依赖：Probe 无需配置向量数据库、嵌入模型或建立索引，开箱即用。
• 网络环境：首次运行需下载 npm 包。若国内访问 npm 较慢，可临时设置镜像源：

  export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
  

安装步骤

Probe 无需全局安装，推荐通过 npx 直接运行最新稳定版。

方式一：直接在终端使用（推荐新手）

无需修改配置文件，直接在命令行调用：

npx -y @probelabs/probe@latest --help

方式二：集成到 AI 编辑器 (MCP)

若需在 Claude Code 或其他支持 MCP 的编辑器中使用 Probe Agent，请编辑配置文件 ~/.claude/claude_desktop_config.json (Mac/Linux) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)，添加以下内容：

{
  "mcpServers": {
    "probe": {
      "command": "npx",
      "args": ["-y", "@probelabs/probe@latest", "agent", "--mcp"]
    }
  }
}

注：此配置将启用内置的 Probe Agent，它会自动复用编辑器的认证信息。

基本使用

1. 语义搜索代码

使用类似 Elasticsearch 的布尔语法搜索代码，返回完整的代码块而非碎片行。

# 搜索包含 "authentication" 和 "login" 的代码
npx -y @probelabs/probe search "authentication AND login" ./src

# 限定文件类型搜索 (仅 Rust 文件)
npx -y @probelabs/probe search "function AND ext:rs" ./

# 限制输出 Token 数量以适应 AI 上下文窗口
npx -y @probelabs/probe search "API endpoint" ./ --max-tokens 5000

2. 提取特定代码块

根据行号或符号名称精准提取代码，保持结构完整。

# 提取 src/main.rs 第 42 行所在的完整函数
npx -y @probelabs/probe extract src/main.rs:42

# 通过符号名称提取 (如函数名 authenticate)
npx -y @probelabs/probe extract src/auth.ts#authenticate

3. 启动 CLI 智能助手

直接在终端向 Probe Agent 提问，让它分析整个代码库。

# 单轮问答：询问认证逻辑如何实现
npx -y @probelabs/probe@latest agent "How is authentication implemented?"

# 多轮交互并允许修改代码 (需谨慎使用)
npx -y @probelabs/probe@latest agent "Refactor the login function" --allow-edit

4. AST 结构查询

使用结构化模式匹配查找特定代码形态（如所有异步函数）。

# 查找 Rust 中所有的异步函数
npx -y @probelabs/probe query "async fn $NAME($$$)" --language rust

# 查找 React 函数组件
npx -y @probelabs/probe query "function $NAME($$$) { return <$$$> }" --language javascript