Ace Tool Skill

ACE工具技能

使用AugmentCode对代码库进行语义模糊搜索。专为在确切的文件名、符号或位置未知时进行高级理解和探索而设计。

🎯 概述

ACE工具通过AugmentCode MCP（模型上下文协议）服务器提供语义代码搜索功能。它解释自然语言查询并检索概念上相关的代码，而不是精确的字符串匹配。

✨ 特性

• 🔍 语义搜索：理解代码意图，而不仅仅是字符串匹配
• 🧠 高层次理解：获取代码概述和关系
• 🎯 上下文感知：提供带有上下文的相关代码片段
• 🚀 持久索引：通过守护进程维护索引状态
• 📊 多个查询：支持各种查询类型

⚠️ 重要提示

• 何时使用：当您不知道确切的文件名、符号或位置，需要语义理解时
• 何时不使用：对于精确的标识符、符号名称或文字字符串匹配，请使用 rg （ripgrep）代替
• 预编辑规则：在编辑任何文件之前，务必首先使用ACE工具收集详细的上下文

📋 先决条件

必需依赖项

1. Bun运行时：JavaScript运行时
2. ACE命令行界面工具：ACE MCP服务器所需的CLI工具

- 存储库：https://github.com/eastxiaodong/ace-tool - 安装：有关设置说明，请参阅CLI工具库

安装

cd ~/.pi/agent/skills/ace-tool

# 1. Install ACE CLI Tool (required dependency)
# Visit: https://github.com/eastxiaodong/ace-tool
# Follow the installation instructions in that repository

# 2. Install dependencies (if needed)
bun install

# 3. Configure ACE MCP Server
cp .env.example .env
# Edit .env with your ACE server credentials

ACE CLI工具设置

ACE CLI工具为语义代码搜索提供了底层功能。在使用此技能之前，您必须先安装它：

# Clone the ACE CLI Tool
git clone https://github.com/eastxiaodong/ace-tool.git
cd ace-tool

# Install and configure
# Follow the repository's README for installation steps

# Make sure the CLI is available in your PATH
ace-tool --version  # Verify installation

🔧 配置

环境变量

创建一个 .env 技能目录中的文件：

# ACE CLI Tool Configuration
ACE_CLI_PATH="/path/to/ace-tool"  # Path to ACE CLI tool (optional if in PATH)

# ACE MCP Server Configuration
ACE_BASE_URL="https://your-ace-server.com/relay"
ACE_API_KEY="your-ace-api-key-here"
ACE_PORT=4231

⚠️ 安全：从不承诺 .env 版本控制。使用 .env.example 作为模板。

验证ACE CLI工具安装

在使用此技能之前，请验证ACE CLI工具是否已正确安装：

# Check if ACE CLI is available
ace-tool --version

# Test basic functionality
ace-tool search "test query"  # Should work if configured

🚀 用法

启动守护进程

守护进程保持索引状态，应启动一次：

cd ~/.pi/agent/skills/ace-tool
bun run daemon.ts

当您使用客户端时，守护进程会自动启动。

启动调试Web UI

对于测试和开发，启动web界面：

cd ~/.pi/agent/skills/ace-tool
bun run start
# or
bun run server

打开浏览器 http://localhost:4231

开发模式（后台程序+Web UI）

同时运行守护进程和web UI：

cd ~/.pi/agent/skills/ace-tool
bun run dev

搜索代码库

# From skill directory
bun run client.ts search "Where is the user authentication handled?"

# From any project directory
bun ~/.pi/agent/skills/ace-tool/client.ts search "How does the payment flow work?"

增强提示（Web UI）

bun run client.ts enhance "Add a login page"

这将打开一个Web UI以进行提示增强。

调试Web UI

启动调试web界面进行测试和开发：

cd ~/.pi/agent/skills/ace-tool
bun run server

然后打开浏览器： http://localhost:4231

web UI提供：

• 🎨 极简主义深色界面
• 🔍 实时搜索测试
• 📊 状态指示器
• 💡 快速示例查询
• 📝 代码结果显示

Web UI功能

• 状态指示器：显示ACE服务器连接状态
• 查询输入：用于自然语言查询的文本区域
• 快速示例：预配置的示例查询
• 结果显示：显示带有文件路径和分数的搜索结果
• 错误处理：清除调试错误消息

使用Web UI

1. 打开浏览器 http://localhost:4231
2. 检查状态指示器（绿色=在线，红色=离线）
3. 在文本区域输入您的搜索查询
4. 点击“搜索”按钮
5. 使用文件路径和代码片段查看结果
6. 使用常见查询的快速示例

Web UI屏幕截图

web UI功能：

• 干净、简约的深色主题
• 显示ACE服务器连接的状态指示器
• 用于查询的大文本区域
• 快速示例按钮
• 实时搜索结果显示
• 调试错误消息

1. 点击“搜索”按钮
2. 使用文件路径和代码片段查看结果
3. 使用常见查询的快速示例

API终点

• GET /：Web UI页面
• GET /api/status：检查ACE服务器状态
• POST /api/search：执行语义搜索

API调用示例:

curl -X POST http://localhost:4231/api/search \\
  -H "Content-Type: application/json" \\
  -d '{"query": "Where is authentication handled?"}'

📖 查询示例

良好的语义查询

# Search for functionality
"Where is the user authentication handled?"
"How does the payment flow work?"
"Where are API endpoints defined?"

# Search for patterns
"How are errors handled in this codebase?"
"Where is state management implemented?"
"How do components communicate with each other?"

# Search for concepts
"Where is the database connection established?"
"How are user sessions managed?"
"Where is authentication middleware defined?"

何时改用rg

# Use rg for exact matches
rg "class UserAuthentication"
rg "function authenticateUser"
rg "API_KEY"

🏗️ 建筑

组件

1. daemon.ts：维护索引状态的持久守护进程
2. client.ts：用于与ACE MCP服务器交互的客户端脚本
3. server.ts：用于测试和开发的Web UI服务器
4. ACE命令行界面工具：提供核心功能的外部依赖性
5. .ace工具/：日志和缓存的运行时目录

数据流

User Query → Web UI / Client → ACE CLI Tool → ACE MCP Server → Indexed Code → Results

依赖关系

ACE Tool Skill (this repository)
        ↓ depends on
ACE CLI Tool (eastxiaodong/ace-tool)
        ↓ uses
ACE MCP Server

ACE命令行界面工具 充当此技能和ACE MCP服务器之间的桥梁，提供核心语义搜索功能。

Web UI架构

Browser → server.ts → ACE MCP Server → Results → Display
         ↓
     Static HTML

📊 输出格式

搜索结果包括：

• 相关代码片段
• 文件路径
• 比赛背景
• 语义相关性得分

🛠️ 故障排除

Daemon无法启动

# Check if port is available
lsof -i :4231

# Check ACE server connectivity
curl https://your-ace-server.com/relay/health

未找到结果

• 尝试重新表述您的查询
• 检查守护进程是否正在运行
• 验证ACE MCP服务器是否可访问

连接错误

• 验证中的ACE_BASE_URL .env
• 检查ACE_API_KEY是否正确
• 确保与ACE服务器的网络连接

🔒 安全注意事项

• 🔐 永不承诺 .env -它包含敏感的API密钥
• 🔐 使用 .env.example -配置模板
• 🔐 旋转API键 -定期更新ACE API密钥
• 🔐 访问控制 -限制对ACE MCP服务器的访问

📚 整合

具备知识库技能

ACE工具可用于扫描知识库文档的代码：

# Scan codebase for concepts
bun ~/.pi/agent/skills/knowledge-base/lib.ts scan

# This internally uses ACE Tool for semantic understanding

其他技能

ACE工具可以与其他需要代码理解的Pi Agent技能集成：

• 知识构建器：分析项目结构
• 系统设计：了解代码架构
• 项目规划师：分析现有代码模式

📝 最佳实践

1. 使用语义查询描述你要找的东西，而不是确切的术语
2. 预编辑上下文：编辑文件前始终收集上下文
3. 与rg结合：使用ACE进行理解，使用rg进行精确匹配
4. 迭代查询：如果结果不相关，请优化您的查询
5. 检查守护进程：确保守护进程正在运行以获得最佳性能

🤝 贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

📄 许可证

MIT许可证-请参阅 许可证 文件

🔗 资源

• ACE命令行界面工具: https://github.com/eastxiaodong/ace-tool-所需依赖关系
• 增补代码: https://augmentcode.dev/
• MCP协议: https://modelcontextprotocol.io/
• Pi代理: https://github.com/badlogic/pi-mono
• ACE MCP服务器：请与管理员联系以获取访问权限

🤝 依赖项

外部依赖

此技能取决于以下外部工具：

• ACE命令行界面工具：ACE MCP服务器所需的CLI工具

- 提供核心语义搜索功能 - 充当此技能和ACE MCP服务器之间的桥梁 - 必须单独安装和配置

安装顺序

1. 从以下位置安装ACE CLI工具https://github.com/eastxiaodong/ace-tool
2. 根据ACE CLI工具的文档配置ACE CLI工具
3. 安装此技能（克隆和配置）
4. 配置 .env 使用您的ACE服务器凭据
5. 开始使用

整合

此技能包含ACE CLI工具，以提供：

• Web UI界面
• Pi代理集成
• 标准化配置
• 增强的用户体验

📞 支持

对于问题或疑问：

• 检查 问题 页
• 审查现有文件
• 请联系您的ACE MCP服务器管理员

______________________________________________________________________

状态: ✅ 生产就绪

版本: 1.0.0

最后更新: 2026-01-07

维护者：Dwsy