SuperAPI AI 工具集

codebase-memory

编程与开发

查看项目

更新于 10-23 01:40

技能介绍

Codebase Memory 是一套代码知识图谱查询工具,通过 MCP 工具提供结构化的代码检索与分析能力。文档说明,图谱工具通常以约 500 tokens 返回精确的结构结果,而 grep 约需 80K tokens,因此建议在代码发现时优先使用图谱工具,而非 grep、glob 或文件搜索。

主要能力

工具优先顺序为:search_graph(按模式查找函数、类、路由和变量)、trace_path(追踪函数的调用方或被调用方)、get_code_snippet(读取指定函数或类源码)、check_index_coverage(在给出结论前校验候选路径与遗漏区间)、query_graph(用 Cypher 查询复杂模式)、get_architecture(获取项目高层摘要)。此外还有 index_repository、index_status、list_projects、delete_project、search_code、detect_changes、get_graph_schema、manage_adr、ingest_traces 等工具,共 15 个 MCP 工具。

常见问题与工具对应关系:谁调用了 X 用 trace_path 的 inbound;X 调用了谁用 outbound;完整调用上下文用 both;按名称模式查找用 search_graph;死代码用 search_graph 并设 max_degree=0、exclude_entry_points=true;跨服务边用 query_graph 的 Cypher;本地变更影响用 detect_changes;带风险标签的追踪用 trace_path 的 risk_labels=true;文本搜索用 search_code 或 Grep。

@current 解析机制

index_status(project="@current") 优先解析已存在的当前根索引。对于未建立索引的链接工作树,只有在两棵工作树均干净、共享同一 Git common 目录与 HEAD,且图谱记录的 Branch 快照匹配时,@current 才会借用规范检出图谱。文档要求 search_graph、query_graph、trace_path、get_code_snippet、get_graph_schema、get_architecture 与 index_status 持续使用 @current,以便每次调用重新校验借用快照;可通过 pi_cbmem_resolution 查看解析情况,borrowed_canonical_base 表示结果是只读借用的图谱证据。search_code、check_index_coverage、detect_changes、manage_adr、ingest_traces、delete_project、index_repository 不应使用 @current。若 @current 因脏、分叉、过期、缺失或歧义上下文被拒绝,不应改用规范项目名绕过守卫;应索引工作树或改用当前根的文件读取与 grep。文档也指出,借用覆盖只能视为尽力而为,因为 Codebase Memory 不提供不可变代际租约或完整语义输入比较。

使用流程

探索流程:先 index_status(@current) 校验活动检出;不可用时用 list_projects 取得确切项目名;再用 get_graph_schema 了解节点与边类型;用 search_graph 查找代码;用 get_code_snippet 读取源码;用 check_index_coverage 校验每条证据路径。

追踪流程:先用 search_graph 找到确切名称;再用 trace_path(direction="both", depth=3) 追踪关系;用 get_code_snippet 验证关键结论;用 check_index_coverage 校验证据路径;用 detect_changes 将 Git diff 映射到受影响符号。

回退 grep/glob 的场景:搜索字符串字面量、错误消息或配置值;搜索 Dockerfile、shell 脚本、配置文件等非代码文件;MCP 工具返回结果不足时。

证据分级

分为 Scout(Tier 1,快速正向查找,结论为暂定,不做否定或穷尽性断言)、Verify(Tier 2,默认,任务导向的图谱证据、相关追踪方向、关键结论的精确片段和分页)、Auditor(Tier 3,限定范围的全量验证,要求当前代际、完整相关分页、必要时双向调用与更广关系,并披露全部限制)。任何层级在得知候选路径后都需调用一次 check_index_coverage 并传入所有证据路径;对否定或穷尽性结论需补充相关范围。干净结果只表示没有记录到缺口,不构成完整性证明;遇到部分、跳过、排除、过期、待定或未知覆盖时,应先读取或 grep 报告的范围。

会话与子代理

会话开始或压缩后,先尝试 index_status(@current),再用 list_projects 或确切名称的 index_status 回退,然后选择层级。派生子代理前,应在父会话查询图谱与覆盖情况,并传递层级、项目、代际或新鲜度、限定范围、查询与分页状态、限定符号、路径、调用链发现、覆盖证据(含区间与原因)、已执行的源码回退以及未解决问题。子代理不必然继承 MCP 访问或父对话;若子代理没有 MCP 工具,不得声称具备 MCP 访问,应使用给定证据并读取或 grep 精确源码,尤其是每个报告的遗漏覆盖区间。

质量分析示例

死代码:search_graph(project="<name>", max_degree=0, exclude_entry_points=true)。高扇出:query_graph 使用 MATCH (f)-[:CALLS]->() WITH f, count(*) AS n WHERE n >= 10 RETURN f.name, n ORDER BY n DESC LIMIT 20。高扇入同理,把箭头方向反转为 ()-[:CALLS]->(f)。

边类型包括 CALLS、HTTP_CALLS、ASYNC_CALLS、DATA_FLOWS、IMPORTS、DEFINES、DEFINES_METHOD、HANDLES、IMPLEMENTS、OVERRIDE、USAGE、CALL_REFERENCE、CONFIGURES、FILE_CHANGES_WITH、SIMILAR_TO、SEMANTICALLY_RELATED、CONTAINS_FILE、CONTAINS_FOLDER、CONTAINS_PACKAGE。

Cypher 示例:MATCH (a)-[r:HTTP_CALLS]->(b) RETURN a.name, b.name, r.url_path, r.confidence LIMIT 20;MATCH (f:Function) WHERE f.name =~ '.Handler.' RETURN f.name, f.file_path;MATCH (a)-[r:CALLS]->(b) WHERE a.name = 'main' RETURN b.name。

注意事项

search_graph 的 relationship 参数按节点度数过滤;要看实际边需用 query_graph 的 Cypher。query_graph 有 10 万行上限,宽查询需加 LIMIT 或改用 search_graph 分页。trace_path 需要确切名称,先用 search_graph 按模式查找。direction="outbound" 会漏掉跨服务调用方,需用 both。search_graph 结果默认每页 50 条,需检查 has_more 并使用 offset。@current 是 pi-cbmem 的读取别名,不是 Codebase Memory 项目或共享索引身份。

限制与未提供信息

资料未说明安装方式、支持的编程语言范围、索引构建成本、许可与收费模式、部署环境要求。