将语义搜索融入 AI 编程工具链：开源 ace-wrapper 的实践笔记
内容提要
作者开源了 ace-wrapper，将 Augment Context Engine 的语义检索封装为 ace 命令，供 AI 编程代理在编辑前从命令行进行语义搜索。它只负责找出候选文件，结论仍需读代码、用 rg 精确搜索和测试验证。作者主张按问题类型选工具：未知关键词用 ace，精确标识符用 rg，结构重构用 ast-grep，并强调提示词应描述行为与数据流，而非堆砌关键词。
延伸解读
语义检索的定位：候选文件而非答案
ace-wrapper 将 Augment Context Engine 的语义检索封装为 ace 命令，但它只负责找出可能相关的候选文件。作者强调，语义检索返回的是“附近”的内容，即使功能不存在也可能找到看似相关的文件。因此，不能将“有结果”等同于“功能存在”，结论必须通过阅读代码、精确搜索和测试来验证。
工具选择策略：按问题类型匹配
作者主张根据问题类型选择工具：未知关键词用 ace 进行语义检索，精确标识符用 rg，结构重构用 ast-grep，外部策略用网络研究，旧决策用记忆。这种分工减少了代理的随机性，先缩小阅读范围，再用确定性工具确认事实，最后修改代码。
提示词设计：描述行为与数据流
好的 ace 查询应描述行为而非堆砌关键词。作者建议包含四类信息：用户动作（点击、拖拽、上传）、运行时边界（前端到后端）、预期效果（持久化配置、显示跳过文件提示）和已知字段（sessionId、requestId）。这比只搜索 upload 或 provider 更稳定，能引导检索系统关注行为和数据流。
工作流约束：将规则固化到工具中
ace-wrapper 代码量很少，核心只是 FileSystemContext.create 和 context.search。作者开源它，是为了保留围绕这几行代码的工作流约束：未知关键词先语义检索、每次查询一个工作流、将结果视为候选文件、读文件后用 rg 确认证据、无证据不下结论。这些规则写入 README、技能和代理提示后，更容易被持续执行。
Q&A
ace-wrapper 是什么？它解决了什么问题？
ace-wrapper 是一个开源工具，它将 Augment Context Engine 的文件系统上下文搜索封装为 ace 命令，让 AI 编程代理在编辑代码前能从命令行进行语义检索。它解决的核心问题是：当代理不知道确切关键词时，直接使用 rg 等精确搜索工具容易让代理在错误的文件中打转，而 ace 能根据行为描述找到候选文件，帮助代理从更好的入口开始阅读代码。
ace 和 rg 在 AI 编程工作流中应该如何配合使用？
ace 和 rg 应作为连续步骤使用：当你知道行为但不知道实现位置时，先用 ace 进行语义检索，找到候选文件；然后阅读这些文件，再用 rg 进行精确搜索，确认具体的标识符、事件、文案或测试是否存在。ace 只负责找出可能相关的文件，不能作为功能存在的证据，最终结论必须通过读代码、精确搜索和测试来验证。
如何安装 ace-wrapper？
可以通过 uv 工具安装：使用 `uv tool install ace-wrapper` 进行全局安装；如果要在本地开发检出中安装，可以使用 `uv tool install /path/to/ace-wrapper`。
使用 ace 进行语义搜索时，查询语句应该怎么写？
好的 ace 查询应描述行为和数据流，避免堆砌关键词。建议包含四类信息：用户动作（如点击、拖拽、上传）、运行时边界（如前端到后端、CLI 处理器到核心服务）、预期效果（如持久化配置、中止循环、显示跳过文件提示）以及已知字段（如 sessionId、requestId）。例如：`timeout 60s ace "用户拖入不支持的文件后应该显示跳过文件提示" -w /repo`。
ace-wrapper 在 Harness Engineering 中扮演什么角色？
ace-wrapper 是 Harness Engineering 中的一个小齿轮，它将开放式的代码发现转变为可重复、受约束的命令。它帮助代理在编辑前先通过语义检索缩小阅读范围，然后用确定性工具确认事实，最后才修改代码。这减少了代理的随机性，让代理先读对地方，而不是盲目编辑。
为什么作者要将 ace-wrapper 开源？
作者开源 ace-wrapper 是因为它的代码量很少，核心只是 `FileSystemContext.create(str(workspace))` 加上 `context.search(args.query)`。作者希望保留围绕这几行代码的工作流约束：未知关键词时从语义检索开始、每次查询只针对一个工作流、将结果视为候选文件、读文件后用 rg 确认精确证据、没有证据不下结论。将这些规则写入工具 README、技能和代理提示中，能让它们更容易被遵守，而不必每次依赖人工提醒。
