iterabloom/hypergumbo

# hypergumbo [](https://codeberg.org/iterabloom/hypergumbo/actions) [](https://pypi.org/project/hypergumbo/) [](https://pypi.org/project/hypergumbo/) [](https://codeberg.org/iterabloom/hypergumbo) hypergumbo 是一个本地优先的 CLI，可以从源代码生成行为图和摘要。该项目的目标是高效地帮助开发者和 LLM 理解代码库。 ``` pip install hypergumbo ``` ``` git clone https://codeberg.org/iterabloom/hypergumbo hypergumbo hypergumbo/ ``` 输出： ``` # hypergumbo hypergumbo is a local-first CLI that generates behavior maps and sketches from source code. The goal of this project is to efficiently help developers and LLMs understand a codebase. > Requires Python 3.10+. For optional extras (embeddings, gitleaks, grammars), run `hypergumbo add-extras` after installing. > Intel Mac users: ## 概述 Python (91%), Markdown (4%), Yaml (3%) 728 files (383 non-test + 345 test) ~320,798 LOC (~129,172 non-test + ~191,626 test) ## 结构 ` ` ` hypergumbo/ ├── .agent │ └── [and 6 other items] ├── .gitea │ ├── SQUASH_TEMPLATE.md │ └── [and 1 other items] ├── .githooks │ ├── commit-msg │ └── [and 9 other items] ├── docs │ ├── CACHE.md │ └── [and 22 other items] ├── packages │ ├── hypergumbo-core │ │ ├── src │ │ │ └── hypergumbo_core │ │ │ ├── analyze │ │ │ │ ├── base.py │ │ │ │ └── [and 3 other items] │ │ │ ├── __main__.py │ │ │ ├── cli.py │ │ │ ├── ir.py │ │ │ └── [and 26 other items] │ │ ├── tests │ │ │ ├── test_framework_patterns.py │ │ │ └── [and 94 other items] │ │ └── [and 2 other items] │ ├── hypergumbo-tracker │ │ ├── src │ │ │ └── hypergumbo_tracker │ │ │ ├── cli.py │ │ │ └── [and 13 other items] │ │ └── [and 5 other items] │ └── [and 4 other items] ├── scripts │ ├── lib │ │ └── forgejo-api.sh │ └── [and 33 other items] ├── tests │ ├── test_bakeoff_deep_reflect.py │ └── [and 2 other items] ├── conftest.py ├── pyproject.toml ├── setup.py └── [and 21 other items] ` ` ` ## Frameworks - pytest - pytorch - transformers ## 测试 345 test files · cargo test, pytest, unittest *~95% estimated coverage (2693/2847 functions called by tests)* ## 配置 [...] ``` **[查看完整示例输出](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/example-output.md)** 使用 `-t` 来控制 token 预算： ``` hypergumbo . -t 1000 # brief overview (structure only) hypergumbo . -t 4000 # good balance for most LLMs hypergumbo . -t 8000 # detailed with many symbols ``` ## 两种输出 **摘要** (`hypergumbo .`) — 专为 LLM 上下文窗口设计的、基于 token 预算的 Markdown。根据图中心性对符号进行排名（★ = 连接度最高）。 **行为图** (`hypergumbo run`) — 包含所有符号、边缘和来源追踪的完整 JSON。用于程序化分析。 ## CLI 命令 ``` hypergumbo [path] # Markdown sketch (default) hypergumbo run [path] # Full JSON behavior map hypergumbo slice --entry X # Subgraph from entry point hypergumbo io-boundaries # Find all I/O (filesystem, network, subprocess, env, IPC, browser storage) hypergumbo verify-claims ... # Verify security claims against analysis hypergumbo routes [path] # List HTTP routes hypergumbo search # Search symbols hypergumbo symbols [path] # Browse symbols with connectivity hypergumbo explain # Detailed symbol info hypergumbo test-coverage # Analyze test coverage (transitive) hypergumbo catalog # List analysis passes ``` 实用标志： ``` hypergumbo . -x # exclude test files (cleaner output) hypergumbo . --no-source # omit source code (included by default) hypergumbo . --no-progress # hide progress indicator (on by default) hypergumbo --help --all # comprehensive help for all commands ``` ### 项目本地污点目录 `verify-claims` 附带从内置 IO 原语目录自动派生的严格默认值。项目可以提供自己的信任区域、净化器和标签映射： ``` hypergumbo verify-claims claims.yaml \ --taint-sources myrepo/taint/sources.yaml \ --taint-sinks myrepo/taint/sinks/ \ --taint-sanitizers myrepo/taint/sanitizers.yaml ``` 每个标志接受一个 YAML 文件或目录（以 `*.yaml` 进行 glob 匹配），并且可以重复使用。可以在 claims YAML 内的 `extra_catalogs: {sources, sinks, sanitizers}` 中声明相同的路径——相对路径会根据 claims 文件目录进行解析。如果用户条目的 `(module, name, kind)` 三元组与内置条目匹配，则会替换内置条目；净化器将被连接合并。 结果会自动缓存在 `~/.cache/hypergumbo/` 中。只需运行： ``` hypergumbo . # auto-runs analysis if no cache exists, then generates sketch ``` 当源文件发生更改时，缓存会自动失效。详情请参见 [docs/CACHE.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/CACHE.md)。 有关所有选项，请参见 `hypergumbo --help`。 ## 它能理解什么 - **语言分析器**：Python、JS/TS、Java、Rust、Go、C/C++ 以及[更多](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/LANGUAGES.md) - **链接器**：横跨四个子类别的第二层边缘恢复阶段——协议（HTTP、WebSocket、消息队列、SQL）、桥接（JNI、wasm_bindgen、Tauri IPC、语言对 FFI）、框架（gRPC、GraphQL、React 组件、依赖注入解析、ORM）、基础设施（包含、继承、模块导入）。[完整目录](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/LINKERS.md)。 - **框架模式**：FastAPI、Django、Rails、Spring Boot、Phoenix、Express 以及[更多](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/FRAMEWORKS.md) - **I/O 边界检测**：映射跨越 FFI 边界的、触及文件系统、网络、子进程、环境、IPC 或浏览器本地存储的每一个调用链 - **污点流分析**：将来自敏感源（环境变量、接收到的网络输入、加密输出、密钥材料）的数据追踪到六个信任区域（`host_fs`、`network`、`host_env`、`ipc`、`browser_storage`、`relay`）的接收器，并具备净化器感知能力 - **供应链层级**：将代码分类为第一方、内部、外部或派生代码，以进行依赖感知分析 ## 工作原理 1. **分析**：扫描仓库以获取语言、文件数量、LOC 2. **提取**：运行特定语言分析器以提取符号和边缘 3. **链接**：跨语言边界连接符号（如 JS fetch → Python 路由） 4. **丰富**：通过 YAML 模式匹配检测框架 5. **分类**：分配供应链层级（第一方、内部、外部、派生） 6. **追踪 I/O**：将调用链映射到 I/O 边界；运行污点流分析 7. **输出**：生成 Markdown 摘要或 JSON 行为图 ### 内部表示 所有分析器都会生成相同的 IR 类型： - **符号**：具有名称、位置和稳定 ID 的代码元素（函数、类、方法） - **边缘**：符号之间的关系（调用、导入、扩展、实现） - **代码范围**：源代码位置（文件、行、列） 这种统一的 IR 使得所有语言分析器和链接器（协议 / 桥接 / 框架 / 基础设施——参见 [ADR-0003-ext](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/adr/0003-linker-subcategory-restoration.md)）能够连贯地协同工作。 ## 架构 ``` packages/ ├── hypergumbo-core/ # CLI, IR, slice, sketch, linkers │ └── src/hypergumbo_core/ │ ├── cli.py # Entry point │ ├── ir.py # Symbol, Edge, Span │ ├── sketch.py # Token-budgeted Markdown │ ├── slice.py # Subgraph extraction │ ├── linkers/ # Tier 2 edge-recovery passes (Protocol/Bridge/Framework/Infrastructure) │ └── frameworks/ # Framework detection (YAML patterns) ├── hypergumbo-lang-mainstream/ # Python, JS, Java, Go, Rust, etc. ├── hypergumbo-lang-common/ # Haskell, Elixir, GraphQL, etc. ├── hypergumbo-lang-extended1/ # Zig, Solidity, Agda, etc. ├── hypergumbo-tracker/ # Structured work tracker for agent governance (MPL-2.0) └── hypergumbo/ # Meta-package (installs all above) ``` 关键设计选择： - **注册表模式**：分析器和链接器通过装饰器进行自注册 - **两遍分析**：首先收集符号，然后解析边缘（支持跨文件引用） - **来源追踪**：每个边缘记录是由哪个分析器/链接器创建的 - **YAML 驱动的模式**：框架检测是声明式的，而非硬编码 ## 开发 ``` git clone https://codeberg.org/iterabloom/hypergumbo.git cd hypergumbo python3 -m venv .venv && source .venv/bin/activate ./scripts/dev-install source .venv/bin/activate # reload to enable pytest alias pytest # runs smart-test (affected tests only) ``` `dev-install` 会安装所有包、git 钩子以及 pytest/smart-test 包装器。要求 100% 的测试覆盖率。 工作流请参见 [CONTRIBUTING.md](CONTRIBUTING.md)（包括外部贡献者的基于 fork 的工作流）、智能测试选择设置和覆盖率要求。Agent 指令位于 [AGENTS.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/AGENTS.md)。 ## 链接 - [docs/USE-CASES.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/USE-CASES.md) — 实用工作流和示例 - [CHANGELOG.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/CHANGELOG.md) — 实现历史 - [docs/LANGUAGES.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/LANGUAGES.md) — 支持的语言 - [docs/LINKERS.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/LINKERS.md) — 链接器目录（协议 / 桥接 / 框架 / 基础设施） - [docs/FRAMEWORKS.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/FRAMEWORKS.md) — 框架模式 - [docs/hypergumbo-spec.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/hypergumbo-spec.md) — 详细规范 - [docs/CITATIONS.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/CITATIONS.md) — 嵌入模型的论文引用 - [docs/CACHE.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/CACHE.md) — 缓存架构 - [docs/agent-supervisor.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/docs/agent-supervisor.md) — `scripts/agent-supervisor` 的操作指南（用于自主代理的 tmux-session 看门狗） - [SECURITY.md](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/SECURITY.md) — 漏洞报告 - [hypergumbo-tracker README](packages/hypergumbo-tracker/README.md) — 用于 AI 代理治理的独立追踪器 ## 许可证 [AGPL-3.0-or-later](https://codeberg.org/iterabloom/hypergumbo/src/branch/dev/LICENSE) 

标签：AI辅助编程, Behavior Map, Codeberg, LLM辅助, Local-first, odt, PyPI, Python, Python 3.10+, 云安全监控, 云资产清单, 代码分析, 代码审查, 代码库理解, 代码搜索, 代码生成, 代码结构, 凭证管理, 大型语言模型, 威胁情报, 安全规则引擎, 开发者工具, 开源, 抽象语法树, 无后门, 本地优先, 渗透测试工具, 源代码解析, 行为映射, 逆向工具, 逆向工程, 防御加固, 静态分析