dreamlx/codeindex

# codeindex [🇬🇧 English](README.md) | [🇨🇳 中文](README_zh.md) [](https://badge.fury.io/py/ai-codeindex) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://github.com/dreamlx/codeindex/actions) **让 AI 编程 agent 通过阅读来浏览你的代码库，而不是依靠 grep。** codeindex 是一个**开源的 CLI**，它通过**两阶段 pipeline**（结构化索引（tree-sitter AST） + 可选的 AI 模块单行描述），将任何代码库转化为 AI 可读的导航索引（`README_AI.md`）。Agent 可以浏览 README_AI.md 的层级结构，了解每个模块的用途，并直接跳转到正确的文件——支持 Python、PHP、Java、TypeScript、JavaScript、Swift 和 Objective-C。实际带来的收益是效率的提升，而非魔法（详见下方基准测试）。 **完全离线运行。** 结构化索引完全不需要 AI；AI 描述使用*你*本地的 agent CLI（例如 `claude -p`），因此不会有任何代码离开你的网络环境——非常适合物理隔离的内部网络。采用 MIT 许可证，免费，并旨在保持如此：codeindex 是开源的*导航 (navigate)* 层；推理/检索层位于 [LoomGraph](FOR_LOOMGRAPH.md) 中。 ## 这对 agent 真的有帮助吗？我们进行了实际测量。 大多数“AI 代码理解”工具只是在宣称价值。我们对我们的工具进行了 A/B 测试——并公开了其中不够完美的部分。 在针对 **3 个异构真实项目上的 15 个评分导航问题**的测试中，对比了**带有** `README_AI.md` 与**不带**它的编程 agent： - **平均减少 28% 的 token，节省 19% 的执行时间** —— agent 能更快、更低成本地找到正确文件。 - **回答质量持平。** 它*不会*让答案变得*更准确*——胜在效率而非能力。（缺乏约束的索引甚至损害了几个精确机制问题的回答；此问题已在 [ADR-005](docs/architecture/adr/005-navigation-disclaimer-and-readme-size-cap.md) 中修复。） - **在最大的代码库上收益最小。** 在一个包含 250 个目录的遗留系统中，token 的节省量几乎消失了——扁平的索引只能指向文件，却无法综合跨模块的语义。codeindex 是*导航 (navigate)* 层，而不是*全知全能 (understand-everything)* 层（结合源码阅读 / [Serena](https://github.com/oraios/serena) 以获取精确机制）。 包含失败案例在内的完整数据：**[2026-05 基准测试](docs/benchmark/2026-05-readme-impact.md)**。在你自己的代码库上复现：**[`bench/`](bench/)** （`make setup && make run && make grade`）。 ## 功能 ### 核心：面向 AI Agent 的代码理解 - **两阶段文档生成 pipeline** (v0.23.0) —— 第一阶段：通过 SmartWriter 生成结构化的 README_AI.md；第二阶段：AI 为每个模块生成单行功能描述。AI agent 可以浏览 README_AI.md 层级结构并找到正确的模块，**无需 grep**。 - **智能索引** —— 为 AI agent 优化的分级文档（概览 → 导航 → 详情），每个文件 ≤10KB（作为导航索引，而非技术文档——详见 [ADR-005](docs/architecture/adr/005-navigation-disclaimer-and-readme-size-cap.md)） - **自动 AI 增强** —— 当配置了 AI 后端（根据 [ADR-008](docs/architecture/adr/008-direct-http-api-ai-default.md) 配置的 `ai:` 部分，或作为 CLI 应急出口的 `ai_command`）时，`scan-all` 会自动启用 AI 模块描述。使用 `--no-ai` 可选择退出 - **自动更新钩子** —— 可选的 post-commit 钩子（`codeindex hooks install`）会为发生变更的目录重新生成 README_AI.md。薄包装器模式：`pipx upgrade ai-codeindex` 会自动更新钩子逻辑 ### 解析与分析 - **多语言 AST 解析** —— 通过 tree-sitter 支持 Python、PHP、Java、TypeScript、JavaScript、Swift、Objective-C；更多语言可通过提取器 API 插入（`src/codeindex/extractors/`，欢迎社区贡献） - **调用关系提取** —— 跨 Python、Java、PHP、TypeScript、JavaScript 的函数/方法调用图 - **继承提取** —— 类层次结构和接口关系 - **框架路由提取** —— ThinkPHP 和 Spring Boot 路由表（未来计划支持更多） - **技术债务分析** —— 检测超大文件、God class、符号过载、测试异味 - **单文件解析** —— 带有 JSON 输出的 `codeindex parse `，便于工具集成 - **结构化 JSON 输出** —— `--output json`，用于 CI/CD、知识图谱和下游工具 ### 开发者体验 - **自适应符号提取** —— 根据文件大小，每个文件动态提取 5–150 个符号 - **CLAUDE.md 注入** —— `codeindex init` 会将 codeindex 部分注入到你**项目的** `CLAUDE.md` 中（绝不会修改 `~/.claude`） - **Claude Code 插件** —— 通过 [dreamlx/codeindex-claude](https://github.com/dreamlx/codeindex-claude) 提供 `codeindex:arch` / `:index` / `:hooks` / `:update-guide` 技能 - **基于模板的测试生成** —— 使用 YAML + Jinja2 快速支持新语言（节省 88–91% 的时间） - **并行扫描** —— 可配置 worker 数量的并发目录处理 ## 用例 ### 🏢 企业内部网络（核心场景） **无需外部工具**：当由于网络隔离或安全策略导致 Serena MCP 或其他基于云的代码智能工具不可用时，codeindex 成为**主要的代码理解工具**。 ``` # Enterprise developer workflow git clone codeindex init # Configure project (init --dry-run previews) codeindex scan-all # Structural + AI descriptions (auto) # AI agent 读取 README_AI.md → 查看模块用途 → 直接导航 # 无需 grep 进行代码发现 codeindex tech-debt src/ --output review.md # Code quality analysis ``` **企业选择 codeindex 的原因**： - ✅ **语义导航** —— AI agent 通过 README_AI.md 层级结构理解模块用途 - ✅ **兼容内网** —— 无外部依赖，完全离线 - ✅ **自包含** —— 无需上游 MCP 服务器 - ✅ **版本稳定** —— 由企业控制发布周期 - ✅ **数据主权** —— 代码绝不离开内部网络 ### 🕸️ 知识图谱集成（LoomGraph） **面向企业团队**：codeindex 作为 [LoomGraph](https://github.com/dreamlx/LoomGraph) 知识图谱的**核心数据源**，实现跨组织的语义代码搜索。 ``` # Data pipeline codeindex scan --output json > parse_results.json loomgraph inject parse_results.json # Build knowledge graph # 团队现在可以使用自然语言搜索代码 ``` **双仓库架构**： ``` codeindex (Parse) → LoomGraph (Store + Query) ↓ graph-export NDJSON ↓ SQLite + sqlite-vec AST extraction Knowledge graph + vector search + MCP ``` codeindex 是无状态的解析层；LoomGraph 是自包含的 知识图谱（SQLite + sqlite-vec，无外部 RAG 框架）。 没有 codeindex，LoomGraph 就没有可索引的内容。详见 [LoomGraph 集成指南](docs/guides/loomgraph-integration.md)。 ### 👤 个人开发者（互补场景） **结合 Serena MCP**：对于使用 Claude Code + Serena MCP 的个人开发者，codeindex 提供**互补价值**： - **codeindex**（构建时）：语义架构图（带模块描述的 README_AI.md）+ 质量分析 - **Serena**（实时）：精确的符号导航（`find_symbol`, `find_referencing_symbols`） ``` # Personal developer workflow codeindex init # Setup CLAUDE.md integration codeindex scan-all # Structural + AI descriptions (auto) codeindex hooks install post-commit # Auto-update on commit # Claude Code 读取 README_AI.md → 理解模块用途 → 使用 Serena 获取详细信息 ``` **两者关系**：codeindex 提供“带标签的地图”，Serena 提供“GPS 导航”。 ## 安装 codeindex 是一个 CLI 工具——使用 **pipx** 安装（隔离环境，无依赖冲突）： ``` pipx install ai-codeindex ``` ### 语言解析器 codeindex 使用**延迟加载**机制——仅在需要时才会导入语言解析器。 `pipx install ai-codeindex` 默认会拉取所有解析器。要在稍后将额外依赖注入到 pipx 环境中，或者安装一部分子集： ``` pipx inject ai-codeindex tree-sitter-python tree-sitter-typescript # add to pipx env # 或者在安装时固定一个子集： pipx install "ai-codeindex[python]" # python only pipx install "ai-codeindex[ios]" # Swift + Objective-C ``` ### pipx 的替代方案 ``` pip install --user ai-codeindex # if you don't have pipx ``` ### 从源码安装 ``` git clone https://github.com/dreamlx/codeindex.git cd codeindex pip install -e ".[all]" ``` ## 快速开始 ### 1. 初始化你的项目 ``` cd /your/project codeindex init ``` 此操作会创建： - `.codeindex.yaml` —— 扫描配置（语言、包含/排除模式） - `CLAUDE.md` —— 注入 codeindex 指令，以便 Claude Code 自动使用 README_AI.md - `CODEINDEX.md` —— 项目级别的文档参考 ### 2. 扫描你的代码库 ``` # 扫描所有目录 # 当配置了 ai_command 时 → 自动执行 Phase 1（结构化）+ Phase 2（AI 描述） # 未配置 ai_command 时 → 仅执行 Phase 1（结构化） codeindex scan-all # 仅结构化（跳过 AI enrichment） codeindex scan-all --no-ai # 扫描单个目录 codeindex scan ./src/auth # 为单个目录生成完整的 AI README codeindex scan ./src/auth --ai # 预览 AI prompt 而不执行 codeindex scan ./src/auth --ai --dry-run ``` ### 3. 检查状态 ``` codeindex status ``` ``` Indexing Status ─────────────────────────────── ✅ src/auth/ ✅ src/utils/ ⚠️ src/api/ (no README_AI.md) Indexed: 2/3 (67%) ``` ### 4. 生成索引 ``` # Global symbol index (PROJECT_SYMBOLS.md) codeindex symbols # Module overview (PROJECT_INDEX.md) codeindex index # Git 变更影响分析 codeindex affected --since HEAD~5 ``` ### 更多命令 | 命令 | 描述 | 指南 | |---------|-------------|-------| | `codeindex scan --output json` | 用于工具的 JSON 输出 | [JSON 输出指南](docs/guides/json-output-integration.md) | | `codeindex parse ` | 将单个文件解析为 JSON | [LoomGraph 集成](docs/guides/loomgraph-integration.md) | | `codeindex tech-debt ./src` | 代码质量分析（技术债务 + 测试异味） | 在 v0.22.0 中增强 | | `codeindex debt-scan ./src` | tech-debt 的别名 | 向后兼容 | | `codeindex hooks install` | 用于自动更新的 Git 钩子 | [Git 钩子指南](docs/guides/git-hooks-integration.md) | | `codeindex doctor` | 健康/同步检查（CLI、解析器、CLAUDE.md、插件） | 只读诊断 | | `codeindex config explain ` | 参数帮助 | [配置指南](docs/guides/configuration.md) | ## Claude Code 集成 **codeindex 插件**为 Claude Code 提供了四个由 CLI 支持的技能： ``` /plugin marketplace add dreamlx/codeindex-claude /plugin install codeindex@codeindex-claude ``` | 技能 | 功能描述 | |-------|--------------| | `codeindex:arch` | 根据 `README_AI.md` 回答架构相关或“X 在哪里”的问题 | | `codeindex:index` | 引导你完成 `codeindex init` → `scan-all` 流程 | | `codeindex:hooks` | 设置自动更新的 post-commit 钩子 | | `codeindex:update-guide` | 刷新你项目的 `CLAUDE.md` 中的 codeindex 部分 | `codeindex init` 还会向你的项目的 `CLAUDE.md` 注入 codeindex 部分， 以便 Claude Code 首先读取 `README_AI.md` 文件。（自 v0.25.0 起，`init` 只 处理项目级范围内的文件——详见 [ADR-006](docs/architecture/adr/006-distribution-architecture-split.md）。） **对于没有 Serena 的企业用户**：README_AI.md 和 PROJECT_SYMBOLS.md 成为您**主要的代码导航工具**。 ## 语言支持 | 语言 | 状态 | 起始版本 | 主要功能 | |----------|--------|-------|-------------| | Python | ✅ 支持 | v0.1.0 | 类、函数、方法、import、docstring、继承、调用 | | PHP | ✅ 支持 | v0.5.0 | 类（extends/implements）、方法、属性、PHPDoc、继承、调用 | | Java | ✅ 支持 | v0.7.0 | 类、接口、枚举、record、注解、Spring 路由、Lombok、调用 | | TypeScript/JS | ✅ 支持 | v0.19.0 | 类、接口、枚举、type alias、arrow function、JSX/TSX、import/export、调用 | | Swift | ✅ 支持 | v0.21.0 | 类、struct、枚举、protocol、extension、方法、属性 | | Objective-C | ✅ 支持 | v0.21.0 | 类、protocol、category、属性、方法（实例/类） | | Go | 📋 计划中 | — | package、接口、struct 方法 | | Rust | 📋 计划中 | — | struct、trait、module | | C# | 📋 计划中 | — | 类、接口、.NET 项目 | **想要添加新语言？** 基于模板的测试系统允许你通过编写 YAML 规范来进行贡献——无需 Python 知识。有关详细信息，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ### 框架路由提取 | 框架 | 语言 | 状态 | |-----------|----------|--------| | ThinkPHP | PHP | ✅ 稳定 (v0.5.0) | | Spring Boot | Java | ✅ 稳定 (v0.8.0) | | Laravel | PHP | 📋 计划中 | | FastAPI | Python | 📋 计划中 | | Django | Python | 📋 计划中 | | Express.js | JS/TS | 📋 计划中 | ## 代码质量分析 ### tech-debt：全面质量分析（在 v0.22.0 中增强） `tech-debt` 命令提供全面的代码质量分析现在包括测试异味检测： ``` # JSON 输出（用于 LoomGraph 集成） codeindex tech-debt ./src --format json > debt-data.json # Markdown 报告（用于文档） codeindex tech-debt ./src --format markdown > report.md # Console 输出（用于快速检查） codeindex tech-debt ./src --format console # Alias: debt-scan 也可用（向后兼容） codeindex debt-scan ./src --format json ``` **检测内容包括**： - 🔴 **超大型文件**（>5000行），**大型文件**（>2000行） - 🔴 **God Class**（方法数 >50） - 🔴 **过长的方法**（>80/150行） - 🟡 **高耦合**（内部 import >8） - 🟡 **符号过载**（符号数 >100，噪声比高） - 🧪 **测试异味**（跳过的测试、超大测试文件）—— **v0.22.0 新增** - 📊 **质量评分**（每个文件 0-100 分制） **增强的 JSON 输出（v0.22.0）**： ``` { "timestamp": "2026-03-06T13:45:39Z", "summary": { "total_files": 97, "giant_files": 0, "giant_functions": 3, "test_smells": 64, "avg_maintainability": 9.9 }, "total_files": 97, "average_quality_score": 99.4, "giant_files": [], "giant_functions": [...], "test_smells": [ { "path": "tests/test_example.py", "type": "skipped_test", "details": "Skipped test detected: @pytest.mark.skip at line 42", "line_number": 42 } ], "file_reports": [...] } ``` **核心功能**： - ✅ **统一命令**：所有质量检查的单一入口点 - ✅ **向后兼容**：保留所有现有的 JSON 字段 - ✅ **支持 LoomGraph**：为知识图谱集成提供增强的摘要 - ✅ **框架无关**：跨 Jest、pytest、JUnit 等检测测试异味 - ✅ **KISS 设计**：90% 的代码复用，用于测试检测的简单正则表达式模式 ## 工作原理 ### 两阶段 Pipeline (v0.23.0) ``` Phase 1 (Structural): Directory → Scanner → Parser (tree-sitter) → SmartWriter → README_AI.md Phase 2 (AI Enrichment, automatic when ai_command configured): README_AI.md → symbol names + file names → AI → one-line description → blockquote injection ``` **第一阶段：结构化生成**（始终运行） 1. **Scanner** —— 遍历目录，根据配置模式进行过滤 2. **Parser** —— 通过 tree-sitter 提取符号（类、函数、import、调用、继承） 3. **SmartWriter** —— 生成具有大小限制（≤50KB）的分级文档 4. **Output** —— 输出为针对 AI 消费优化的 `README_AI.md`，或用于工具集成的 JSON **第二阶段：AI 增强**（配置了 `ai_command` 时自动启用） - 为每个非叶子模块生成单行功能描述 - 以块引用形式写入：`> 会员等级管理、积分兑换、权益卡券` - 每个目录约 200-400 个 token，比完整 AI 生成成本低 10-20 倍 - 父目录读取子目录描述以实现层级导航 ### 前后对比：代码导航 ``` Before (structural only): └── Application/ ├── Vip/ — 48 files | 386 symbols ← AI agent cannot determine purpose ├── Pay/ — 23 files | 178 symbols └── SmallProgramApi/ — 31 files | 245 symbols After (structural + AI enrichment): └── Application/ ├── Vip/ — 会员等级管理、积分兑换、权益卡券 | 48 files ├── Pay/ — 支付网关（支付宝/微信/退款） | 23 files └── SmallProgramApi/ — 小程序端API（登录、头像、商品） | 31 files ↑ AI agent can navigate directly ``` ### 双仓库架构（企业知识图谱） ``` ┌────────────────────────────────────────────────────┐ │ Enterprise Intranet Environment │ ├────────────────────────────────────────────────────┤ │ │ │ 📦 Code Repository (Git) │ │ ↓ │ │ 🔍 codeindex (Parse Layer — stateless) │ │ ├── graph-export → NDJSON graph artifact │ │ ├── README_AI.md → architecture docs │ │ └── tech-debt → comprehensive quality scan │ │ ↓ │ │ 🕸️ LoomGraph (Store + Query — stateful) │ │ ├── import-export ← codeindex NDJSON │ │ ├── SQLite + sqlite-vec (graph + vectors) │ │ ├── embeddings + KNN semantic search │ │ └── query CLI + MCP server │ │ ↓ │ │ 💬 AI Agents (Claude Code, Internal Chat) │ │ └── Natural language code search (MCP) │ │ │ └────────────────────────────────────────────────────┘ ``` **codeindex 的角色**：底层（解析）—— LoomGraph 依赖 codeindex 的 `graph-export` NDJSON 作为唯一的数据接缝。codeindex 本身保持无状态 (ADR-007)。 ## 文档 ### 用户指南 | 指南 | 描述 | |-------|-------------| | [入门指南](docs/guides/getting-started.md) | 安装与首次扫描 | | [配置指南](docs/guides/configuration.md) | 解释所有配置选项 | | [进阶用法](docs/guides/advanced-usage.md) | 并行扫描、自定义 prompt | | [Git 钩子集成](docs/guides/git-hooks-integration.md) | 自动化质量检查与文档更新 | | [Claude Code 集成](docs/guides/claude-code-integration.md) | AI agent 设置与 MCP 技能 | | [JSON 输出集成](docs/guides/json-output-integration.md) | 供工具使用的机器可读输出 | | [LoomGraph 集成](docs/guides/loomgraph-integration.md) | 知识图谱数据 pipeline | ### 开发者指南 | 指南 | 描述 | |-------|-------------| | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发环境设置、TDD 工作流、代码风格 | | [CLAUDE.md](CLAUDE.md) | 供 Claude Code 和贡献者快速参考 | | [设计理念](docs/architecture/design-philosophy.md) | 核心设计原则与架构 | | [ADR-005](docs/architecture/adr/005-navigation-disclaimer-and-readme-size-cap.md) | 2026-05：导航契约免责声明 + 大小上限，由基准测试支持 | | [发布自动化](docs/development/QUICK_START_RELEASE.md) | 5 分钟自动化发布工作流 | | [多语言支持](docs/development/multi-language-support-workflow.md) | 添加新的语言解析器 | | [语言支持贡献](docs/development/multi-language-support-workflow.md) | 为新语言基于模板生成测试 | ### 证据与基准测试 | 文档 | 展示内容 | |---|---| | [2026-05 README 影响力基准测试](docs/benchmark/2026-05-readme-impact.md) | 测量了在 3 个异构项目（15 个评分问题）中，带有与不带 `README_AI.md` 时 agent 理解力的差异。核心结论：平均速度提升 19% / token 减少 28%，但在一些细节问题上的速度提升掩盖了质量的下降——修复已发布（见 ADR-005）。 | | [`bench/`](bench/) | 用于生成上述基准测试的可复现测试套件（Makefile + python）；通过 `cd bench && make setup && make run && make grade && make report` 运行你自己的测试。 | ### 规划 - [战略路线图](docs/planning/ROADMAP.md) —— 长期愿景与优先级 - [Changelog](CHANGELOG.md) —— 版本历史与破坏性变更 ## 贡献 欢迎你的贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ``` git clone https://github.com/dreamlx/codeindex.git cd codeindex pip install -e ".[dev,all]" make install-hooks make test ``` ### 发布流程（维护者） ``` make release VERSION=0.17.0 # GitHub Actions: 测试 → PyPI 发布 → GitHub Release ``` 详见 [发布自动化指南](docs/development/QUICK_START_RELEASE.md)。 ## 路线图 **当前版本**：v0.30.0 **近期里程碑**： - v0.23.0 —— **AI 增强的模块描述**：两阶段 pipeline、自动 AI 增强、post-commit 薄包装器 - v0.22.2 —— 在 `pip upgrade` 时自动更新 CLAUDE.md，`/codeindex-update-guide` 技能 - v0.22.0 —— 统一的 tech-debt + 测试异味分析 - v0.21.0 —— Swift 与 Objective-C 语言支持 - v0.19.0 —— 支持 TypeScript/JavaScript 及调用提取 **下一步**： - 框架路由扩展：Express、Laravel、FastAPI、Django (Epic 17) - Go、Rust、C# 语言支持 **已移至 [LoomGraph](https://github.com/dreamlx/LoomGraph)**： - 代码相似性搜索、重构建议、团队协作、IDE 集成 详见 [战略路线图](docs/planning/ROADMAP.md) 了解详细计划。 ## 许可证 MIT 许可证——有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## 致谢 - [tree-sitter](https://tree-sitter.github.io/) —— 快速、增量解析 - [Claude CLI](https://github.com/anthropics/claude-cli) —— AI 集成灵感 - 所有贡献者和用户 ## 支持 - **问题**：[GitHub Discussions](https://github.com/dreamlx/codeindex/discussions) - **Bug**：[GitHub Issues](https://github.com/dreamlx/codeindex/issues) - **功能请求**：[GitHub Issues](https://github.com/dreamlx/codeindex/issues/new?labels=enhancement)

由 codeindex 团队用 ❤️ 打造

标签：AI编程助手, AST解析, Python, SOC Prime, 代码库导航, 代码索引, 开发工具, 文档结构分析, 无后门, 逆向工具