dranshrad/codex-ast-mapper

 # Codex-AST Repo Mapper **仓库智能引擎** — 使用 Tree-sitter 遍历代码库，构建语义依赖图，并生成**受 token 预算限制的** LLM 上下文包，支持超高密度的 XML、JSON IR 或 Mermaid 图表。 采用 **GNU AGPL v3** 授权。 ## 为何开发此工具 LLM 不需要原始源码堆砌。它们需要的是**结构**：模块、公开 API、继承关系以及内部 import — 全部被压缩到一个严格的 token 预算内。 ``` Repository → Parser → Extractor → Semantic IR → RepoGraph → Compression → Exporters ├─ XML ├─ JSON └─ Mermaid ``` ## 安装 ``` pipx install poetry poetry install poetry run codex-ast-mapper --help ``` ## 演示 ``` poetry run codex-ast-mapper --dir . --lang python --max-tokens 800 asciinema play docs/demo/map-repo.cast # 重新生成 GIF: agg --speed 1.5 --font-size 14 --theme monokai docs/demo/map-repo.cast docs/demo/map-repo.gif ``` 请参阅 [docs/demo/map-repo.md](docs/demo/map-repo.md)。 ## 用法 ``` # 默认：用于 LLM 开发者上下文的 hyper-dense XML poetry run codex-ast-mapper --dir . --lang python --max-tokens 4000 # 带有 edges + importance scores 的 JSON IR poetry run codex-ast-mapper --format json --mode review -m 3000 -q # Mermaid module 依赖图 poetry run codex-ast-mapper --format mermaid --mode planning -o graph.mmd # 在 stderr 上显示 top graph hubs poetry run codex-ast-mapper --graph-stats --dir . ``` | Flag | 描述 | |------|-------------| | `--dir` / `-d` | 仓库根目录 | | `--lang` / `-l` | `python` \| `typescript` \| `go` \| `all` | | `--format` / `-f` | `xml` \| `json` \| `mermaid` | | `--mode` | `developer` \| `review` \| `planning` \| `docs` \| `refactor` | | `--max-tokens` / `-m` | 硬性 Tiktoken (`cl100k_base`) 预算 | | `--graph-stats` | 在 stderr 打印模块/边缘枢纽信息 | | `--output` / `-o` | 将产物写入指定路径 | | `--quiet` / `-q` | 隐藏诊断信息 | ## 输出格式 ### XML (默认) ``` Walk root honoring gitignore. ``` ### JSON 包含 `modules`、`edges` (`imports` / `inherits` / …) 以及供下游工具使用的各模块 `importance` 分数。 ### Mermaid ``` flowchart LR src_parser["src.parser"] --> src_models["src.models"] ``` ## LLM 模式 | 模式 | 优先保留内容 | |------|-------------| | `developer` | 完整签名、文档、import | | `review` | 公开 API；尽早剥离辅助代码 | | `planning` | 激进压缩（缩写类型，无文档） | | `docs` | Docstring + 公开签名 | | `refactor` | 高中心度模块、继承关系、入度 | 当超出预算时：剥离辅助代码 → 文档 → 类型缩写 → import → **首先剔除重要性最低的模块**。 ## 架构 | 层级 | 模块 | |-------|--------| | 遍历 + 解析 | `src/parser.py` | | 作用域提取 | `src/ast_extractor.py` | | 图表 + 重要性 | `src/graph.py` | | 导出器 | `src/exporters/` | | 预算 | `src/tokenizer_util.py` | | CLI | `src/cli.py` | ## 基准测试 ``` poetry run python benchmarks/run_bench.py ``` 示例（本仓库，本地运行）： | files | modules | edges | wall_s | files_per_s | tokens | compression_ratio | rss_mb | prune_level | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 21 | 21 | 349 | 0.23 | 90 | 4449 | 22.18 | ~83 | none | 请在本地重新运行以获取特定于您机器的数值。压缩比的计算方式为原始源码字符数 ÷ 生成的 token 数。 ## 使用场景 - **LLM 上下文包** — 在严格的预算下将 `--format xml` 注入 agent prompt - **代码审查** — 使用 `--mode review` 查看公开 API 层 - **规划** — 使用 `--format mermaid` 进行依赖关系定向 - **工具开发** — 使用 `--format json` 供编辑器、bot 和 CI 检查使用 ## 路线图 | 版本 | 重点 | |---------|--------| | **0.2** (当前) | 语义 IR、RepoGraph、JSON/Mermaid、模式、重要性剪枝 | | **0.5** | 调用图、跨模块引用 | | **1.0** | 仓库智能平台 | | **2.0** | LLM 原生的语义仓库 OS | ## 开发 ``` poetry run ruff check src tests poetry run ruff format src tests poetry run mypy src poetry run pytest -q ``` ## 许可证 [GNU Affero General Public License v3.0](LICENSE) 本项目使用 **AGPL-3.0**（而非 GPL-3.0），因此网络托管或 服务封装的部署也必须提供相应的源代码。 对于此套件而言，这是一个深思熟虑的 copyleft 选择 — 并非未经考量的默认设置。 ## 相关项目 | 项目 | 作用 | |---|---| | [codex-ast-mapper](https://github.com/dranshrad/codex-ast-mapper) | 将仓库压缩为受 token 预算限制的 LLM 上下文 | | [llm-cst-refactorer](https://github.com/dranshrad/llm-cst-refactorer) | 保持格式的类型与 docstring 重构 | | [automated-self-correction-loop](https://github.com/dranshrad/automated-self-correction-loop) (ASCL) | 执行 → 诊断 → 修复循环 | | [voice-notes-to-anthropic-artifacts](https://github.com/dranshrad/voice-notes-to-anthropic-artifacts) | 本地 STT → Anthropic → `~/Artifacts` | | [anthropic-audio-gateway](https://github.com/dranshrad/anthropic-audio-gateway) | 浏览器音频 ↔ 实时提供商适配器 |

标签：DLL 劫持, SOC Prime, Token优化, Tree-sitter, 代码分析, 依赖图, 凭证管理, 大语言模型, 开发工具, 逆向工具