SuperAPI AI 工具集

codebase-exploration

编程与开发

查看项目

更新于 11-16 06:45

技能介绍

用途

codebase-exploration 用于理解一个此前未读过的仓库:它的目录结构、某项行为在哪里实现,以及某个函数何时、为何变成现在这样。技能将“在哪里发生”和“为什么是这样”视作两个不同问题——前者从布局与代码回答,后者从提交历史回答,并要求不凭文件名猜测任何一方。

主要能力与操作顺序

  1. 先看形状而非内容:用 get_repository_tree 并设置 recursive: true 一次取得整体布局;大仓库可用 path_filter 限定前缀,先看顶层,目录名通常已能指出入口、测试与生成代码。
  2. 读项目自述文档:对 README 和贡献指南调用 get_file_contents,它们陈述意图,这是单靠读代码无法还原的。
  3. 确认当前工作位置:list_branches 查看默认分支之外的分支,list_tags 查看项目是否自版本化;若版本化,最新标签比默认分支更适合作为阅读起点,因为它是被主动发布的状态。
  4. 定位行为而非浏览:search_code 加 repo:owner/name 和独特符号直接命中,用 path:、language: 降噪,引号包裹短语做精确匹配;查询保持在 256 字符以内,定位阶段用 fields 只返回 path 和 text_matches。
  5. 读取每个匹配的上下文:搜索结果只是一行,get_file_contents 才能判断它是定义、调用方还是测试。
  6. 知道“在哪里”之后再问“为什么”:list_commits 设置 path 指向该文件,按变更顺序取得其历史。
  7. 报告路径而非结论:写明实际读过的文件、符号与提交,方便他人从终点继续。

关键决策与字段

  • 始终结构优先,先看目录树再按文件名选文件。
  • 搜索范围决定一切:search_code 默认覆盖整个 GitHub,需用 repo: 或 org: 收窄。
  • 优先最小必要读取:目录列表→搜索→单个文件。
  • 生成代码不是证据:vendored 目录、锁文件和生成源码会命中搜索但不反映意图,发现后用 path: 排除。
  • 默认分支未必是真相:最新标签落后于默认分支时,两者描述不同软件,需说明读的是哪一个。
  • 重要字段:recursive 与 path_filter;get_file_contents 的 ref(读分支或标签当前状态)与 sha(读精确提交,工作中唯一稳定的);search_code 的限定符 repo:、org:、path:、filename:、extension:、language:、NOT,排序放在 sort 与 order 而非查询文本;list_commits 的 path(限制到单个文件);get_commit 的 detail(stats 列出变更文件,full_patch 含差异且可能极大,只要消息与作者时可设为 none);fields 用于树读取与搜索以控制返回量。

适用场景

接手陌生仓库、查找某功能实现位置、追溯某函数的提交来源、在单仓库范围内做只读探索。

限制与边界

所有操作均为只读,风险在于范围而非破坏:跨仓库提问需先约定边界,按量读取大文件或大差异前应先说明并取得同意;问题若变为修改,应停在发现处另行确认。异常情况包括:树被截断需用 path_filter 收窄并说明不完整;搜索无结果可能是符号被构造、拼写不同或语言未被索引;匹配过多说明词太常见,应加限定而非翻页;路径找不到可能是被移动或删除,可用 search_commits 查旧名区分;仓库为空或无默认分支应如实报告;文件过大无法返回时应说明并改用树、搜索与提交历史。