honow48-tech/CodeBread

剖析任何代码库，看清它的真实连接方式。
一个交互式、零依赖的关系映射图：文件 → 函数 → API 路由 → 数据库表。

## 这是什么 CodeBread 会扫描项目，提取每一个函数和类，映射出所有内容的连接方式——**前端 → API → 后端 → 数据库**——并将其渲染为浏览器中的交互式节点图。点击文件可将其剖析展开为其中的函数；点击函数可查看它调用的所有内容以及调用它的所有内容，并完整展示端到端的链条。 **它解决的问题：** 接手一个不是你写的代码库——或者是由 AI 为你生成的代码库——却不知道任何东西在哪里。逐个阅读文件无法快速建立心智模型。CodeBread 为你构建模型：它找到路由，顺着 `fetch()` 调用找到响应它们的处理程序，顺着处理程序找到它们触及的表，并绘制出整个路径。 ## 为什么开发这个工具 这最初是一个个人工具。我不断使用 AI 生成项目，然后盯着结果发呆，不知道各个部分是如何组合在一起的——哪个文件调用了哪个，API 的边界到底在哪里，什么操作了数据库。我想要一个能直接向我*展示*这一切的工具，而不是让我在文件树中逐个文件地去 `grep`。CodeBread 就是那个工具。 这是一个 v1.0 版本——我已在自己项目中积极使用它，并且会持续为其添加新功能。如果它对你也有用，那就更好了。欢迎提交 Issue 和 PR。 ## 使用的技术栈 - **后端/分析引擎：** 纯 Python **标准库**——无需任何第三方包，除了 Python 本身之外，不需要 `pip install` 任何东西。Python 使用标准库的 `ast` 进行解析，其他所有语言均使用结构化正则表达式进行解析（见下方的语言支持表）。 - **前端：** 原生 **JavaScript + SVG**，无框架，无构建步骤，无需 `npm install`。整个 UI 只有三个文件（`app.js`、`index.html`、`style.css`）。 - **服务端：** 基于标准库中 `http.server` 构建的微型本地服务器。 就是这样。克隆它，运行它，无需编译任何内容。 ## 安装 ``` pip install codebread ``` 可选额外步骤（在扫描时实现更好的 `.gitignore` 匹配）： ``` pip install codebread[full] # adds pathspec ``` 需要 **Python 3.9+**。除此之外无需其他依赖。 更倾向于从源码运行以便贡献代码吗？ ``` git clone https://github.com/honow48-tech/CodeBread.git cd CodeBread pip install . # or: python codebread.py --path /path/to/project ``` ## 使用 ``` codebread --path /path/to/project # scan + open the UI in your browser codebread # prompts for the path ``` 这就是完整的快速入门：将其指向一个文件夹，随后会打开一个浏览器标签页，里面已经是扫描好的关系映射图。 ### CLI 参考 | 标志 | 作用 | |---|---| | `--path, -p PATH` | 要扫描的根文件夹（如果省略则会提示输入） | | `--port 8137` | 本地服务器端口（如果被占用，会自动在附近寻找空闲端口） | | `--json out.json` | 将完整关系图导出为 JSON | | `--load out.json` | 重新打开已保存的扫描结果，无需重新扫描 | | `--html out.html` | 导出**独立的静态 HTML** 文件，方便分享 | | `--diff old.json new.json` | 对比两次保存的扫描结果并打印出差异（新增、移除、修改的文件/函数/表） | | `--no-open` | 不自动打开浏览器 | | `--no-serve` | 仅扫描 + 导出，不启动服务器 | | `--version` | 打印已安装的版本号 | ## 功能特性 - **侧边资源管理器** —— 完整的文件夹树，可像文件管理器一样展开；每个文件都标有其所属的层级颜色。 - **轨道布局（默认）** —— 文件在空间中自由浮动，均匀展开以保持连接线不交错。展开一个文件，其内部函数会围绕中心排列成整齐的圆环，并由直线轮辐连回中心。此外还提供了一种**自由**力导向布局（可在右下角切换）。 - **专注模式** —— 清空画布，让你一次只检查一个文件：在资源管理器中选择一个文件，界面上将只显示该文件、其内部函数及其直接关联。关闭此模式即可返回全局概览。 - **渐进式展现（OSINT 风格）** —— 点击文件将其剖析展开为带编号的函数；点击函数即可绘制出它调用的内容以及调用它的内容。让密集的代码库依然保持良好的可读性。 - **全链路高亮** —— 选择任意节点，其完整的端到端调用链路都会被点亮（前端 `fetch()` → `GET /api/users` 路由 → 处理程序 → `users` 表），所有无关的内容都会变暗。 - **右键操作** —— 每个节点、连线和空白画布上都有右键上下文菜单：展现连接、专注查看某文件、在 IDE 视图中打开、跳转到路由的源/目标位置、复制名称或路径等等。 - **洞察面板** —— 标记孤立的函数（未检测到调用者）和循环调用链，两者均可点击以直接跳转查看。 - **Diff 模式** —— 对比两次保存的扫描结果（`--diff old.json new.json`），清晰查看它们之间的具体差异。 - **小地图 + 面包屑导航** —— 包含可拖动视口的整个关系图的实时小地图，以及显示当前所选内容真实文件夹路径的面包屑导航。 - **键盘导航** —— `←`/`→` 在选中节点的相邻项之间切换，`↑`/`↓` 在你的选择历史中前进/后退，`/` 进行搜索。 - **详情面板** —— 显示参数、返回类型、自动生成的描述（“函数 3 · 处理 GET /api/users · 查询 users 表”），以及所有调用者和被调用者，均可点击。 - **查看实际代码** —— 每个函数都有一个可展开的 **▸ 查看代码** 区域：带有真实行号的语法高亮源码。完整的 **IDE 视图**（⌗）可整体打开任何文件，并带有大纲侧边栏。 - **搜索**（`/`）和位于顶部的**层级过滤器**（前端 / 后端 / 数据库 / 配置）。 - **警告，从不静默** —— 无法读取的文件、不支持的语言以及权限问题都会以 ⚠ 徽章的形式显示并出现在警告列表中，从不隐藏。在配置文件中发现的密钥也会被自动脱敏掩码。 ## 它如何划分层级 基于评分的启发式方法，结合了框架导入特征（React/Vue → 前端，Flask/Express → 后端，SQLAlchemy/Prisma → 数据库）、目录约定（`/client`、`/server`、`/models`…）、文件扩展名以及提取到的事实（定义了路由 → 后端，定义了模型 → 数据库）。对于模糊不清的文件，会被标记为 **未分类**，而不是盲目猜测。 ## 孤立节点 + 循环依赖检测的工作原理 - **孤立的函数**：任何被检测到入站调用次数为零的函数/方法，且既不是路由处理程序，也不是常见的框架入口点（`__init__`、`main`、`setUp`、测试函数等）。会在节点上使用徽章进行标记，并列在洞察面板中——这是寻找死代码的良好起点（属于启发式算法，并非穷举：可能会漏掉静态解析器无法识别的调用）。 - **循环调用链**：对调用图进行迭代式的循环检测（不使用递归，因此在大型代码库上是安全的），标记出在循环中相互调用的函数，既在节点上进行标记（↻ 徽章），也作为链条列表显示在洞察面板中。 ## 项目结构 ``` codebread.py ← runnable entry point (no install needed) codebread/ cli.py ← argparse CLI scanner.py ← .gitignore-aware recursive walker languages.py ← language detection / binary sniffing parsers/ python_parser.py ← ast-based Python extractor javascript_parser.py ← JS/TS/Vue/Svelte extractor generic_parser.py ← Java/C#/Go/PHP/Ruby + SQL + config classifier.py ← frontend/backend/database/config scoring connections.py ← call graph + API↔route + fn↔table matching + orphan/cycle detection analyzer.py ← pipeline orchestration diff.py ← compares two saved scans server.py ← stdlib local web server export.py ← JSON + single-file HTML export web/ ← the UI (vanilla JS + SVG, zero dependencies) assets/ ← logo (.svg source + .png for the README — GitHub blocks same-repo SVG embeds) ``` ## 路线图 在 v1.0 版本中已完成： - [x] 孤立函数和循环依赖检测 - [x] 两次扫描结果之间的 Diff 模式 - [x] 专注模式、轨道布局、右键操作、小地图、面包屑导航 尚未实现但已计划： - [ ] “解释此函数” —— 生成通俗语言的 AI 摘要按钮 - [ ] 更精确的多语言解析（目前除 Python 外，其他所有语言均使用结构化正则表达式） - [ ] 自动化测试套件 有想法吗？欢迎提交 Issue。 ## 许可协议 [MIT](LICENSE) —— 随意使用、修改、发布或出售。除了保留许可文件外，无需其他归属说明。全文请参阅 [LICENSE](LICENSE)。

标签：SOC Prime, 云安全监控, 代码可视化, 代码地图, 开发工具, 数据可视化, 架构分析, 逆向工具, 静态分析