什么是Repo Surveyor
Repo Surveyor 是一款专为开发者设计的仓库分析工具，旨在帮助开发者在无法使用 Cartograph CLI 或 MCP 等自动化工具时，快速理解项目结构、定位关键文件并生成任务上下文。它通过手动但系统化的方式，引导用户发现源代码、配置文件及入口文件，同时自动跳过生成的、第三方依赖和构建输出目录，从而避免信息过载。该工具的核心价值在于提供一种轻量但高效的“人工图谱”构建流程，确保在自动化工具不可用时仍能保持对代码库的清晰认知。
Repo Surveyor 的工作流程强调从入口点出发，识别高影响力文件，追踪强依赖枢纽，而非通读整个代码树。这种策略不仅提升了效率，也确保了分析结果与 Cartograph 的输出格式保持一致，便于后续集成或文档化。无论你是需要快速搭建新功能的上下文，还是为团队准备架构说明文档，Repo Surveyor 都能帮助你提炼出最小但最有用的文件集合，并自动生成可直接用于文档的摘要内容。
此外，当 OpenProse 插件启用时，Repo Surveyor 会优先使用 `openprose/` 目录下的模板作为起点，进一步简化文档生成过程。尽管推荐在 Cartograph 可用时使用 `use-cartograph`，但在其缺失或受限的场景下，Repo Surveyor 成为了一个可靠且结构清晰的替代方案，尤其适合需要手动验证或补充自动化输出的开发场景。
核心功能特点
- 自动识别并跳过生成的、第三方依赖和构建输出文件，聚焦于核心源码与配置
- 基于入口点、调用关系和 API 表面进行文件重要性排序，突出关键依赖枢纽
- 支持生成最小任务上下文文件集，便于快速进入特定开发任务
- 输出格式与 Cartograph 一致，包含关键文件列表、依赖枢纽和文档就绪摘要
- 兼容 OpenProse 插件，支持从模板生成结构化文档内容
- 适用于 Cartograph 不可用或需手动验证分析结果的场景
适用场景
Repo Surveyor 特别适用于那些因网络限制、版本不兼容或部署问题导致 Cartograph CLI 或 MCP 无法正常运行的场景。例如，在某些企业内部环境中，自动化工具可能因权限或配置问题被禁用，此时开发者仍需要一种高效的方式理解大型代码库的结构。Repo Surveyor 提供了一种无需依赖外部服务的本地解决方案，允许开发者手动执行类似图谱分析的操作，确保项目理解不中断。
另一个典型应用场景是代码审查或新成员入职培训。当需要为新功能编写技术文档或向团队成员解释系统架构时，Repo Surveyor 能快速提取相关文件并生成简洁的上下文摘要，大大减少前期调研时间。它特别适合处理复杂项目中的局部修改——比如仅关注某个微服务模块而忽略其他无关组件，从而提升开发专注度。
此外，在持续集成（CI）流水线中，若自动化分析步骤失败，Repo Surveyor 可作为备用手段生成临时报告，供人工审核使用。由于其输出格式与 Cartograph 对齐，这些报告可直接嵌入到项目 Wiki 或 README 文件中，维持文档的一致性和可读性。总之，任何需要快速建立代码库心智模型、生成任务上下文或补充自动化分析缺失环节的开发场景，都适合使用 Repo Surveyor。