Skip to content

ACEMCP.md

Latest commit

 

History

History
183 lines (136 loc) · 6.66 KB

ACEMCP.md

File metadata and controls

183 lines (136 loc) · 6.66 KB

代码搜索工具使用说明

📖 简介

代码搜索工具（基于 Acemcp）是一个基于 ACE (Augment Context Engine) 的代码库语义搜索工具，已整合到三术项目中。它能够通过自然语言查询在代码库中搜索相关的代码上下文，帮助 AI 助手更好地理解项目结构和代码实现。

✨ 核心特性

1. 语义搜索

  • 使用自然语言查询搜索代码库
  • 返回与查询语义相关的代码片段
  • 支持多种编程语言和文件类型

2. 增量索引

  • 自动检测项目中的新文件和修改过的文件
  • 仅上传变更内容，提高索引效率
  • 基于 SHA-256 哈希的去重机制

3. 智能文件处理

  • 自动分割大文件（默认每块 800 行）
  • 支持多种文件编码（UTF-8、GBK、GB2312、Latin-1）
  • 自动遵守 .gitignore 规则
  • 可配置的文件扩展名和排除模式

4. 批量上传

  • 支持批量上传文件块，提高传输效率
  • 自动重试机制（最多 3 次，指数退避）
  • 优雅的错误处理和日志记录

🚀 使用方法

在 MCP 客户端中使用

  1. 启用工具

    • 在三术设置界面的 "MCP 工具" 标签页中
    • 找到"代码搜索工具"
    • 点击开关启用该工具

  2. 配置 API 端点

    • 点击工具右侧的配置按钮
    • 填写以下信息：
      • API 端点 URL：ACE 服务的完整地址（如 https://api.example.com）
      • 认证令牌：用于访问 API 的 Bearer Token
    • 其他高级配置（批量大小、文件扩展名等）可根据需要调整，通常使用默认值即可

  3. 测试连接

    • 在配置界面点击"测试连接"按钮
    • 确认 API 端点可正常访问

  4. 使用搜索功能

    • 在 AI 助手中使用自然语言查询
    • 例如：
      • "查找日志配置相关的代码"
      • "搜索用户认证的实现"
      • "找到数据库连接池的初始化代码"

在设置界面中调试

  1. 打开调试面板

    • 在 MCP 工具标签页中找到"代码搜索工具"
    • 点击配置按钮打开配置弹窗
    • 在弹窗底部找到调试区域

  2. 执行搜索测试

    • 填写项目根路径（绝对路径，使用正斜杠 /）
    • 输入搜索查询语句
    • 点击"执行搜索"按钮
    • 查看返回的搜索结果

⚙️ 配置说明

API 端点 URL

  • 格式：http://host:port 或 https://host:port
  • 如果缺少协议前缀，系统会自动补全为 http://
  • 示例：https://api.example.com 或 localhost:8080

认证令牌

  • 用于访问 ACE API 的 Bearer Token
  • 请确保令牌具有足够的权限访问代码库检索接口

💡 提示：其他高级配置（批量大小、文件扩展名、排除模式等）可在配置界面的"高级配置"标签页中调整，通常使用默认值即可满足大多数使用场景。

🔍 搜索查询示例

查找配置代码

查询：日志配置 设置 初始化 logger
返回：与日志设置、logger 初始化和配置相关的代码

查找认证逻辑

查询：用户认证 登录 密码验证
返回：认证处理器、登录函数、密码验证代码

查找数据库代码

查询：数据库连接池 初始化
返回：数据库连接设置、连接池配置、初始化代码

查找错误处理

查询：错误处理 异常 try catch
返回：错误处理模式、异常处理器、try-catch 块

查找 API 端点

查询：API 端点 路由 HTTP 处理器
返回：API 路由定义、HTTP 处理器、端点实现

📁 数据存储

  • 配置：存储在三术的配置文件中
  • 索引数据：~/.acemcp/data/projects.json（项目索引信息）
  • 日志文件：~/.sanshu/log/acemcp.log（工具运行日志）

索引状态与智能等待（与三术 MCP 集成时）

  • 在与「三术」集成使用时，代码搜索工具还支持以下增强能力：
    • 后台增量索引 + 智能等待：在不阻塞调用方的前提下，通过后台文件监听与增量索引维护最新索引，并在索引过程中通过短暂随机等待（默认 1–5 秒）在"速度"与"结果完整度"之间做平衡。
    • 记忆驱动的索引预热：当通过 ji 工具为某个项目添加/查看记忆且已启用 sou 时，会在后台自动触发一次索引预热，方便后续代码搜索立即受益于最新索引。
    • MCP 弹窗中的索引可视化：在「等一下」弹窗中，可以实时看到当前项目的索引状态（空闲/索引中/已同步/失败）以及索引进度条，便于判断当前搜索结果是否已经充分利用最新索引。

🛠️ 高级功能

查看日志

在设置界面中，可以点击"查看日志"按钮查看工具的运行日志，帮助排查问题。

清除缓存

如果索引出现问题，可以点击"清除缓存"按钮清除已索引的项目数据，重新开始索引。

.gitignore 集成

工具会自动读取项目根目录的 .gitignore 文件，并遵守其中的排除规则。无需额外配置。

多编码支持

工具自动检测和处理不同字符编码的文件：

  • UTF-8（优先）
  • GBK
  • GB2312
  • Latin-1

对于无法解码的文件，会使用 UTF-8 错误处理模式，确保不会因编码问题导致索引失败。

⚠️ 注意事项

  1. 项目路径格式

    • 必须使用绝对路径
    • 路径分隔符使用正斜杠 /（即使在 Windows 上）
    • 示例：C:/Users/username/projects/myproject

  2. 网络连接

    • 确保能够访问配置的 API 端点
    • 首次索引可能需要较长时间，取决于项目大小
    • 网络不稳定时会自动重试

  3. 文件权限

    • 确保对项目目录有读取权限
    • 某些系统文件可能无法读取，这是正常现象

  4. 性能考虑

    • 大型项目（数万个文件）的首次索引可能需要几分钟
    • 增量索引通常很快，只处理变更的文件
    • 建议合理配置排除模式，避免索引不必要的文件

🙏 致谢

本工具整合了开源项目 acemcp，感谢原始作者 @qy527145 及其贡献者的优秀工作。

acemcp 项目基于 ACE (Augment Context Engine) 构建，提供了强大的代码库语义搜索能力。本项目在保留原有功能的基础上，将其整合到三术的 MCP 工具生态中，并进行了以下改进：

  • 使用 Rust 重写了核心逻辑，提高了性能和稳定性
  • 集成了配置管理，统一在三术设置界面中管理
  • 添加了连接测试和调试功能
  • 优化了错误处理和日志记录

📚 相关链接