构建可供AI智能体查询的本地代码图谱工具

## 在本地用语法树而不是AI摘要构建代码图谱 让项目分析保持本地化和确定性。基于语法树而非语言模型摘要派生符号、关系和文件，将项目范围内的状态存储在本地索引数据库中，并通过库、命令行界面或智能体协议公开由此得到的知识图谱。 将系统组织为分层管道： - 提取层解析源代码并生成规范符号； - 关系解析层连接导入、名称、框架和其他关系； - 图查询回答调用方、被调用方、路径和影响； - 上下文格式化为使用方准备精简的Markdown或JSON。 不要在主线程上执行繁重的解析。让各层都经过同一个公开入口，并将该入口作为唯一受支持的库接口。如果一个可执行文件有意同时充当安装程序、索引器和协议服务器，就通过同一构建产物测试所有这些角色。 为面向智能体的工具指南保留一个权威来源，最好使用协议初始化响应。不要将同一套指令复制到每个客户端的仓库文件中，因为副本会逐渐偏离，并导致升级或卸载不完整。 ## 固定运行时版本，并把非代码文件一起放进构建 查明并使用仓库中已记录的构建、开发、清理、测试、评估和本地CLI命令。遵守固定的运行时版本范围，并在超出范围时明确失败；较新的运行时主版本并不会自动兼容，而且从源代码运行时所需的最低版本可能比捆绑发行版更严格。 将运行时资产视为构建契约的一部分。把数据库模式、解析器语法、WebAssembly模块和其他非代码文件复制到发行版中。每当增加新资产时，都要更新复制步骤，否则该资产不会随产品发布。 先使用一个范围明确的测试文件或名称模式进行验证，再运行直接受影响的测试套件。当评估套件用于构建测试夹具或为行为评分，而不是执行普通单元测试时，应将它们分开。 在存储语义重要的地方使用真实的存储行为。创建隔离的临时目录，在每次测试后清理，并验证实际的数据库模式，而不是用模拟掩盖它。 ## 统一节点和边的类型，保持公开API精简 在一个模式中定义规范的节点和边类型。提取器和关系解析器必须生成那些完全相同的字符串；不要引入近似重复项，以免在不易察觉的情况下拆分查询、遍历或序列化数据。 保持公开API精简。从公开入口重新导出受支持的类型，并要求命令行和协议适配器使用同一个核心服务，而不是绕过它。 让有关存储的声明明确且可测试。如果产品只有一个支持预写日志和全文搜索的数据库后端，就报告实际运行的后端，保持所有兼容适配器精简，并且不要暗示存在尚未实现的原生或WebAssembly回退方案。 添加语言、框架、查询或模式字段时，应同时更新负责它的提取器或关系解析器、公开契约、序列化、测试以及面向用户的指南。 ## 安装到多个AI客户端时不破坏设置，并能干净卸载 将每个受支持的客户端建模为一个目标，各自拥有配置位置、格式和协议参数。新增客户端时，通过一个目标实现和一个注册表条目完成，而不要把条件分支散布到安装程序各处。 精确地编辑配置。保留无关的TOML表和数组，保留带注释JSON的格式与注释，优先使用现有的受支持文件变体，并且只在全新安装时创建文档规定的默认文件。 安装必须具备幂等性，重新安装必须能够自行修复部分状态，卸载必须只撤销安装程序自身拥有的更改。使用稳定标记移除过时的指令块，但应将当前智能体指南保留在唯一的运行时权威来源中，而不是再写一份副本。 通过参数化契约测试覆盖每个目标，测试同级配置保留、逐字节相同的重复运行、可逆卸载和部分状态恢复。保留客户端特有的工作目录修复，例如当客户端从错误目录启动协议子进程时注入明确的项目路径。 ## 增强智能体已经在用的检索工具 构建检索功能之前，先判断它是否能让智能体已经调用的工具，使用智能体已经提供的输入完成更多工作。不要依赖智能体学习新工具、采用不同的查询方式，或者注意到不显眼的示例和初始化说明。 用精确输入获得精确答案。主要探索工具应接收一组精简的符号名称，包括限定名称，并连接它们之间的流程。辅助节点工具应返回完整源代码以及调用方和被调用方上下文；名称存在歧义时，应在一个响应中返回所有可能的重载。 不要把精确的流程答案塞进无法区分端点的模糊自然语言工具。应在智能体已经选择的工具内部提升覆盖范围，包括静态提取和基于证据的动态关系。 除了令牌使用量，还要优化实际耗时和工具调用次数。节省来自更少的轮次和更小的累积上下文，因此要衡量所有轮次的总用量，而不能只看最终响应。 ## 返回让智能体不必退回直接读文件的回答 让预期内的情况采用成功响应形式。未建立索引的项目、缺失的符号或索引外的文件应返回可执行的指导，而不设置错误标志。真正的错误只用于安全拒绝和实际故障，并且只有在适合重试时才附上次数受限的重试指令。 即使当前根目录尚未建立索引，也要公开工具集合。说明如何选择已建立索引的项目，但把是否建立索引留给用户决定。启动时隐藏工具可能破坏多项目单仓库，以及在建立索引前已经开始的会话。 根据仓库规模，单调增加探索调用预算和输出预算： - 少于500个文件：1次调用，约18,000个字符，每个文件3,800个字符； - 500–4,999个文件：2次调用，约28,000个字符，每个文件6,500个字符； - 5,000–14,999个文件：3次调用，约35,000个字符，每个文件7,000个字符； - 15,000–24,999个文件：4次调用，约38,000个字符，每个文件7,000个字符； - 25,000个或更多文件：最多5次调用，约38,000个字符，每个文件7,000个字符。 较大层级获得的每个文件的预算绝不能小于较小层级。绝不要让智能体退回到直接读取原始文件；应引导它再次调用图工具，并明确说明应将返回的源代码视为已经读取。 ## 把回调和事件的流程从头到尾连通 静态解析会遗漏回调、观察者、事件发射器、响应式渲染、描述符以及其他间接分派。只有在能以充分证据连接规范流程时，才添加范围严格受限的合成器或框架关系解析器。 将每条合成边标记为启发式，记录生成它的机制，并包含注册位置或连接位置。把这一来源信息与流程一同呈现，使使用方能够区分解析得到的事实和推断出的关系。 如果覆盖一个间接跳转后仍让下一个边界断开，那么部分覆盖比完全没有覆盖更糟。闭合从起始动作到可见效果的完整流程，重新测量智能体，并且不要交付仍迫使使用方手工重建流程的半连通路径。 在无法安全推断的运行时边界，宁可保持沉默也不要生成错误的边。扩展关系解析器之前，应验证重新建立索引不会使节点数量膨胀，并抽查合成边的精度。 ## 在真实仓库以及Windows和Linux上检验智能体的表现 对于每种语言和框架，都要在小型、中型和大型真实仓库中，使用至少3个不同的流程问题进行测试。应为每个框架选择规范的端到端流程，而不是选择避开其复杂分派边界的孤立符号。 针对构建产物运行确定性探针。确认探索能在预算内连接预期端点，节点数量在重新建立索引前后保持稳定，并且启发式边具有准确的来源信息。 使用同一刻意选定的能力下限模型和推理强度，对每个实验组至少运行2次智能体A/B测试。记录持续时间、工具调用总数、原始文件读取次数和文本搜索次数；报告范围，而不是挑选一次有利的结果。当启动延迟会让工具不可见时，预热一个常驻协议进程，并根据实际调用而不是初始化快照判断是否已连接。 要求在仓库的探索预算内将原始文件读取和搜索降到近乎为零，比对照组更快完成，并且在对照仓库中没有回归。 在真实平台上验证平台特有的行为。明确区分仅适用于Windows和仅适用于非Windows平台的断言。对于Linux，应在一次性容器中使用全新的平台原生依赖进行构建，并使用init进程回收已经退出的子进程。对于Windows，应在真实虚拟机的本地文件系统中使用全新的依赖；判定原因之前，先将可疑故障与默认分支进行比较。 ## 编写发布说明，把发布交给自动发布工作流 将即将进行的更改写在Unreleased部分下。如果发布工作流会自动提升Unreleased内容，就不要提前创建下一个版本块。 让发布说明对用户真正有用： - 只在适用时，按面向用户的新功能、修复、安全或破坏性更改标题组织内容； - 每个条目用一句通俗的话解释功能或已解决的症状； - 不包含内部路径、实现符号、基准测试细节和空白部分； - 保留有用的议题引用、受支持的平台名称以及用户实际输入的命令。 让自动发布工作流同步锁文件版本、提升变更日志、构建各平台捆绑包、生成校验和、发布版本并发布软件包。除非收到明确要求，否则不要提升版本；如果这些操作由工作流负责，就不要手动发布软件包、推送发布提交或创建标签。 处理议题、评审评论或外部报告之前，应将其与日期对应，并比较已发布状态、已合并但尚未发布的状态以及当前分支。不要把进行中的修复归因于报告者先前能够看到的状态。 将产品需求视为由用户决定的事项，而不是从代码图谱推断出的事实。为每个文档图片URL添加版本，并在资产发生变化时递增其查询标签，以免缓存持续提供过期内容。