winstonec/codebase-surface-to-core-mapper

# Codebase Cartographer：面向 AI 辅助代码审查的智能仓库映射 [](https://winstonec.github.io/codebase-surface-to-core-mapper/) 一个结构化的推理框架，使 AI agent 能够通过渐进式深度优先分析方法，系统地探索和评估未知代码库——从表层工件到核心实现逻辑。 ## 仓库概述 Codebase Cartographer 将审查陌生代码仓库这一繁重的任务，转化为一种有条理的、逐层的发现过程。可以把它想象成在将你的 AI agent 派往未知领域之前，交给它一张地形图和一个指南针。agent 不会再淹没在繁杂的文件和文件夹中，而是遵循一条结构化的路径，这条路径反映了资深人类开发者接触新代码库时的自然方式：由外而内。 此技能专为 AI 驱动的代码审查助手、自动化 CI/CD pipeline 以及需要快速理解仓库架构而无需人工干预的开发者生产力工具而设计。 ## 🧭 核心架构 (Mermaid) ``` flowchart TD A[Repository Surface] --> B[Artifact Layer] B --> C[Configuration Layer] C --> D[Dependency Layer] D --> E[API Surface Layer] E --> F[Implementation Layer] F --> G[Testing Layer] G --> H[Documentation Layer] A --> A1[README, License, .gitignore] B --> B1[Build scripts, CI/CD configs] C --> C1[Config files, env templates] D --> D1[Package.json, requirements.txt] E --> E1[Public APIs, exports] F --> F1[Core logic modules] G --> G1[Test suites, fixtures] H --> H1[Wiki, API docs, examples] style A fill:#4a90d9,color:#fff style H fill:#50b06a,color:#fff ``` ## ⚡ 示例 Profile 配置 ``` codebase_cartographer: review_depth: 4 layer_order: ["surface", "config", "dependencies", "api", "implementation", "tests"] surface_analysis: readme_checklist: true license_compliance: true gitignore_audit: true dependency_analysis: detect_outdated: true check_vulnerabilities: true flag_unused_imports: true implementation_analysis: complexity_threshold: 10 test_to_code_ratio: 0.3 documentation_coverage: 0.4 ``` ## 🚀 示例控制台调用 ``` cartographer review ./path/to/repo \ --depth 4 \ --format markdown \ --output review_report.md \ --ai-provider openai \ --model gpt-4-turbo \ --verbose ``` ## 📱 Emoji 操作系统兼容性表 | 操作系统 | 支持情况 | 备注 | |:----------------:|:---------:|-------| | 🐧 Linux | ✅ 完整 | 原生支持，推荐用于生产环境 | | 🍎 macOS | ✅ 完整 | 已在 Ventura 和 Sonoma 上测试 | | 🪟 Windows | ⚠️ 部分 | 高级功能需要 WSL2 | | 📱 Android (Termux) | ✅ 基础 | 仅限于表层扫描 | | 🍏 iOS (a-Shell) | ❌ | 不支持 | ## 🔥 功能列表 ### 核心功能 - **渐进式深度分析**：从顶层工件到实现细节逐层审查代码库，防止认知超载 - **多层架构扫描器**：按顺序分析 README 准确性、许可证合规性、依赖健康状况、API 表面设计和测试覆盖率 - **智能 Context Window 管理**：动态分割大型代码库，在保持逻辑连贯性的同时，确保不超出 AI 模型的 token 限制 - **跨仓库比较**：使用相同的评估标准在多个仓库之间生成比较报告 ### AI 集成 - **OpenAI API**：优化了使用 GPT-4 Turbo 的 function calling，用于生成结构化输出 - **Claude API**：使用 Anthropic 的 Claude 3.5 Sonnet 进行细致的代码质量评估和架构模式识别 - **混合模式**：针对不同的层使用不同的模型（例如，表层使用 GPT-4，实现层使用 Claude） ### 开发者体验 - **响应式 UI 仪表盘**：在长时间的审查过程中提供实时进度可视化，并带有可折叠的分区导航 - **多语言支持**：支持生成包含日语、德语、西班牙语和法语在内的 12 种以上语言的审查评论和报告 - **7x24 客户支持**：自动化问题检测和解决建议，并可选转接人工服务 - **自定义规则引擎**：使用基于 YAML 的规则定义和条件逻辑来定义你自己的审查标准 ## 🤖 OpenAI API 集成 Codebase Cartographer 利用 OpenAI 的 function calling 功能，将原始的代码检查转化为结构化的审查工件。每一层分析都对应一个带有类型参数的独立 function call： - `analyze_surface_layer(repo_path, focus_areas)` → 返回 README 准确性得分、许可证类型和文件结构图 - `evaluate_dependencies(repo_path, depth)` → 生成带有漏洞注释的依赖关系图 - `audit_api_design(repo_path, interface_patterns)` → 生成带有一致性得分的 API 表面分析 - `assess_test_coverage(repo_path, threshold)` → 计算覆盖率指标并识别测试盲区 系统会自动使用缩减的 context window 重试失败的调用，并跨层维护对话状态，以在最终报告中保持叙述的连贯性。 ## 🧠 Claude API 集成 对于更深层次的架构分析，Codebase Cartographer 利用了 Claude 的扩展 context window 和细致的推理能力： - **模式识别**：Claude 能够识别未明确记录的架构模式（MVC、微服务、事件驱动） - **代码异味检测**：超越静态分析，检测逻辑不一致、过早优化和架构反模式 - **文档对齐**：将代码结构与 README 声明进行比较，标记出文档记录的架构与实际实现之间的差异 - **重构建议**：生成具体的、分步的重构提案，并附带预估的工作量和风险等级 当实现层分析检测到 Cartographer 复杂度量表上的得分超过 8 分时，Claude pipeline 将自动触发。 ## 🎨 核心功能详解 ### 响应式 UI 仪表盘 Web 仪表盘可适应任何屏幕尺寸，随着每一层完成分析提供实时进度指示。每个审查层都会显示自己的进度条、已用时间和发现的问题数量。仪表盘使用 WebSocket 连接进行实时更新，使漫长的审查过程感觉是交互式的，而不是静止的。 ### 多语言支持 报告会利用 AI 驱动的本地化技术自动翻译成用户偏好的语言。该系统通过使用保留特定领域术语的专用代码审查词汇表，确保在各种语言中保持技术准确性。初始翻译支持超过 30 种语言，社区贡献还可以添加更多语言。 ### 7x24 客户支持 当 AI 检测到无法完全解决的关键问题时，它会自动通过具有优先级别的工单系统升级给人工专家。该支持系统包括： - 包含诊断摘要的自动首次回复 - 根据问题类别分配人工专家 - 带有 SLA 监控的解决情况跟踪 - 用于模型改进的解决后反馈收集 ## ⚠️ 免责声明 **重要提示**：Codebase Cartographer 是一款 AI 辅助分析工具，不能替代对生产关键系统的人工代码审查。自动化分析可能会遗漏需要领域专业知识的上下文相关问题、业务逻辑错误或安全漏洞。务必通过人工审查来验证 AI 生成的发现，特别是对于安全敏感的代码。本工具按“原样”提供，不提供任何关于适销性或特定用途适用性的保证。Codebase Cartographer 生成的报告应被视为建议性的，而非权威性的。对于基于自动化分析输出做出的决定，开发者不承担任何责任。使用风险由您自行承担。 ## 📜 许可证 本项目基于 MIT 许可证授权 - 详见 [LICENSE](https://opensource.org/licenses/MIT) 文件。 ## 📥 下载 [](https://winstonec.github.io/codebase-surface-to-core-mapper/) *版本 2.4.1 - 发布于 2026 年* *Codebase Cartographer：因为每个代码库都值得一次正式的介绍。*

标签：AI辅助, Petitpotam, SOC Prime, 代码审查, 代码库分析, 后端开发, 开发工具, 结构化推理, 自动化分析, 跨站脚本, 逆向工具