coseto6125/egent-code-plexus

自主编码智能体在每个任务中会执行 **20-50 次结构化查询**。这些查询都命中了为人类设计的工具：需要预热的IDE侧边栏、守护进程，以及为阅读而格式化的输出。这种不匹配体现在三种具体的故障模式中： 1. **Token 浪费** — `grep` 输出返回 400 行，而智能体只需要 10 个符号 2. **重构失败** — 一个遗漏的调用点被忽略，因为解析器猜测并出错了 3. **虚构的依赖关系** — 当静态分析无法到达某条边时，工具会凭空捏造一条 `ecp` 的构建旨在消除所有这三种问题。 | 故障模式 | `ecp` 的解决方案 | |---|---| | 原始搜索输出耗尽上下文窗口 | **TOON / 紧凑 JSON** — 仅包含符号、行和边；无填充 | | 遗漏调用点，下游静默中断 | **`impact`** — 基于实际调用和扩展边的精确爆炸半径 | | 智能体推理中虚构的依赖关系 | **`BlindSpot` 记录** — 类型化、诚实的未知项，智能体可绕行 | | 主要语言之外图谱失明 | **31 种语言** — 服务代码、IaC、SQL、智能合约一次性遍历 | ## 🎯 设计原则 每个设计决策都有一个源头：*接收方智能体到底需要什么？* **输出是数据结构。** TOON 和紧凑 JSON 仅携带智能体进行下一步决策所需的信息。无散文摘要。无视觉装饰。无消耗上下文预算的章节标题。默认格式对大多数 LLM 提示来说已是正确选择。 **无状态。零预热。** 每次调用都会 `mmap` 一个零拷贝的 `rkyv` 图文件然后退出。**约 140–170 每次查询（含启动）**。无需保持守护进程运行。无预热阶段。无 "服务器崩溃，请重启" 的恢复路径。智能体可在每个任务中执行 50 次查询而无需支付进程启动开销。 **盲点优于幻觉。** 当 `ecp` 无法静态解析某个调用点（动态分派、反射、未解析的导入）时，它会生成一条 `BlindSpot` 记录：图谱中一个命名的、类型的、明确的空白。智能体可以绕过已知的未知项。它们无法从一个自信的捏造中恢复。 **默认多语言支持。** 31 种语言达到结构深度。服务代码、Dockerfile、GitHub Actions、Terraform、SQL、Move、Solidity —— 一次遍历覆盖所有层。无需切换语言意味着没有图谱盲点。 🎙️ **[智能体访谈](./interviews/README.md)** — Gemini CLI 和 Codex 描述了它们如何在实时自主任务流中使用 `ecp`。 基于 [GitNexus](https://github.com/abhigyanpatwari/GitNexus) 构建，作者 [Abhigyan Patwari](https://github.com/abhigyanpatwari) —— 相同的结构化图概念，使用 Rust 重写，面向不同受众。[PolyForm Noncommercial 1.0.0](./LICENSE.md)；见 [NOTICES.md](./LICENSES/NOTICES.md) 获取必要的署名要求。 ## ⚡ 性能凭证 与另外两个代码图工具（[`codegraph`](https://github.com/colbymchenry/codegraph) (Node + SQLite) 和上游 [`gitnexus`](https://github.com/abhigyanpatwari/GitNexus) (Node)）在相同代码库、相同机器上进行正面比较。`ecp` 是一个无状态的单次 CLI：下面的每个延迟都**包含完整的进程启动**，无守护进程，无预热。 *版本：`ecp` 0.4.2 · `codegraph` 0.9.4 · `gitnexus` 1.6.5。所有工具均设置了 1 MiB 最大文件大小阈值（可配置时，`gitnexus` 硬编码为 512 KB）。`ecp` 数据为 5-7 次运行的中位数。硬件：AMD Ryzen 9 9950X (16 逻辑核心), Linux。* ### `microsoft/vscode` — 14,874 文件，密集的单语言 TypeScript | 指标 | **`ecp`** | `codegraph` | `gitnexus` | |---|---|---|---| | **冷索引** | **4.6 秒** | 166.9 秒 | **DNF** — 27 分钟后终止 | | 峰值 RSS | **~1.0 GiB** | 1.7 GiB | 4.6 GiB (仍在增长) | | 符号查找 / 查询 | **34.6 毫秒** | 169.5 毫秒 | — | | 调用者 / 影响 | **27.2 毫秒** | 172.4 毫秒 | — | | 检查 / 上下文 | **35.0 毫秒** | 415.9 毫秒 | — | | 影响基线 (git-diff) | **725.9 毫秒** | N/A — 无此模式 | — | | 图节点数 | **507,257** | 315,498 | — | | 图边数 | 916,380 | **986,709** | — | | 磁盘索引大小 | **87 MiB** | 671 MiB | — | | 已索引文件数 | **14,874** | 10,814 | — | *`gitnexus` 未能完成 — 27 分钟后卡在其内存图解析阶段（RSS 4.6 GiB，无输出写入）后被终止。* ### `abhigyanpatwari/GitNexus` — 3,232 文件，多语言（三者均能完成的语料库） | 指标 | **`ecp`** | `codegraph` | `gitnexus` | |---|---|---|---| | **冷索引** | **0.74 秒** | 11.2 秒 | 77.6 秒 | | 峰值 RSS | **264 MiB** | 501 MiB | 2.5 GiB | | 查找 / 查询 | **9.4 毫秒** | 103.5 毫秒 | — | | 调用者 / 影响 | **9.2 毫秒** | 104.2 毫秒 | 297.6 毫秒 | | 检查 / 上下文 | **9.4 毫秒** | — | 295.5 毫秒 | | 图节点数 | **49,122** | 19,604 | 30,223 | | 图边数 | **48,271** | 39,155 | 47,218 | | 磁盘索引大小 | **7.7 MiB** | 37 MiB | 306 MiB | | 已索引文件数 | **3,232** | 2,968 | 3,232 | **冷索引速度比 `codegraph` 快 15-37 倍；`gitnexus` 无法在真实大型代码库上完成。在每种规模下，内存占用最低、磁盘索引最小、图最密集。** ### 规模：`.sample_repo` — 22,645 文件，25 种语言，2.1 GB 多语言语料库 **摄入：** | 指标 | 值 | |---|---| | 已索引文件数 | **22,645** 跨 25 种检测到的语言 | | 冷摄入 | **2.60 秒**（解析 + 解析 + 序列化） | | 增量摄入 | **4.9 毫秒**（xxh3_64 哈希遍历，零脏文件） | | 硬件 | AMD Ryzen 9 9950X (16 逻辑核心)，39.2 GiB 内存，Linux 6.6.87 | **每次查询延迟（含进程启动）：** | 查询 | 中位数 | 覆盖内容 | |---|---|---| | `summary` | **1.4 毫秒** | 注册表 mmap — 最小读取 | | `routes` | **142.3 毫秒** | 声明式 + 命令式路由枚举 | | `summary --detailed` | **143.4 毫秒** | 完整注册表 + 按框架置信度评分 | | `impact --direction down` | **145.0 毫秒** | Calls / Extends 边上的 BFS | | `inspect` | **145.6 毫秒** | 符号解析 + 1-跳遍历 | | `find --mode bm25` | **154.5 毫秒** | Tantivy 查询 + 5-桶分区 | | `cypher` (窄范围) | **161.5 毫秒** | 一个模式，一行结果 | | `cypher` (宽范围) | **174.2 毫秒** | 更广泛的模式，更多匹配项 | | `impact --baseline HEAD~1` | **359.0 毫秒** | git diff + 并行按文件解析 + BFS | 重现所有内容：`python scripts/benchmark/benchmark_ecp.py`。 ### Rust 层级竞争对手比较 `scripts/benchmark/benchmark_vs_competitors.py` 针对 [`codescope`](https://github.com/onur-gokyildiz-bhi/codescope) (基于 SurrealDB) 和 `coraline` (基于 SQLite) 在 6 个阶段进行基准测试：`cold-index`、`symbol-find`、`callers`、`file-context`、`route-map`、`cypher`。缺失的阶段标记为 `N/A`（缺失本身是信号）。结果将重新生成 `docs/benchmark-vs-competitors.md`。 ``` python scripts/benchmark/benchmark_vs_competitors.py python scripts/benchmark/benchmark_vs_competitors.py --corpus path/to/repo --iterations 5 --no-plot ``` ## 🆚 与上游 GitNexus 对比 | 维度 | EgentCodePlexus | GitNexus | |---|---|---| | 主要用户 | 自主 AI 代码智能体 | 人类开发者 + IDE 集成 | | 运行时 | 无状态单次 CLI（零预热） | 长期运行的 MCP 服务器 | | 性能 | **< 2.5 秒冷索引 / < 175 毫秒查询** | ~60 秒冷索引 / ~400 毫秒查询 | | 未解析的边 | `BlindSpot` 记录（诚实未知项） | 启发式猜测 | | 默认输出 | TOON / 紧凑 JSON (Token 高效) | Wiki / UI 渲染 | | 语言 | 31 (14 深度 + 17 结构化) | 14 (深度，9 维度) | | 存储 | Rust + `rkyv` 零拷贝 mmap | Node.js + LadybugDB | **完整分析、理念与决策矩阵 → [docs/vs-gitnexus.md](./docs/vs-gitnexus.md)** ## 📦 安装 预编译二进制文件随每个 GitHub Release 发布。安装脚本仅在找不到匹配的资产时才回退到 cargo 源码构建。 ``` # Linux / macOS curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh # Windows PowerShell iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex # 直接 cargo（无安装程序包装器） cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked ``` 更喜欢包管理器？npm 和 PyPI 包会发布相同的预编译二进制文件（无需编译，无需工具链）并自动选择正确的平台： ``` # npm — 无需安装即可运行，或全局安装 npx egent-code-plexus --help npm install -g egent-code-plexus # PyPI — 通过 uv 或 pipx uvx egent-code-plexus --help uv tool install egent-code-plexus # or: pipx install egent-code-plexus # cargo-binstall（预构建，无需源码编译） cargo binstall egent-code-plexus ``` 针对 CPU 优化的源码构建： ``` repo=https://github.com/coseto6125/egent-code-plexus RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist ``` ### 卸载 ``` ecp uninstall # remove agent integrations + ~/.ecp cache + the binary ecp uninstall --dry-run # preview what would be removed, change nothing ``` 一条命令即可撤销所有安装副作用：Claude Code / Codex / Gemini 的钩子、MCP 服务器和技能；按仓库的 git 钩子；`~/.ecp` 索引缓存；以及 `ecp` 二进制文件本身。在 Windows 上，二进制文件在进程退出后通过一个短延迟步骤删除（运行中的 `.exe` 无法自行删除）。 使用 `--agent claude` 限定为单个智能体（保留二进制文件和缓存），或使用 `--keep-cache` 在重装时保留索引缓存。如果你通过包管理器安装，请使用其自带的移除工具： ``` npm uninstall -g egent-code-plexus uv tool uninstall egent-code-plexus # or: pipx uninstall egent-code-plexus cargo uninstall egent-code-plexus ``` ## 🚀 快速开始 无需启动守护进程。无需配置。一条命令从零到可查询的图。 ``` # 索引（增量；首次查询时若索引不存在也会自动建立） ecp admin index --repo . # 查找符号 — 默认精确匹配 ecp find loginUser ecp find login --mode bm25 # BM25 ranking, partitioned into 5 output buckets # 影响范围 — 如果我更改此处，谁会受到影响？ ecp impact validateUser --direction upstream # 完整符号上下文（签名、函数体、调用者、被调用者、一跳影响） ecp inspect validateUser # HTTP 路由映射（声明式 @Get + 命令式 app.get()） ecp routes ecp routes /api/users --method POST # route → handler → caller chain # 文件使用情况：谁在读取/写入此路径？ ecp impact --literal session_meta.json ``` 所有读取命令都接受 `--format text|json|toon`。默认值对每个命令来说都是 Token 最高效的（主要是 `toon`；`find` 默认为 `text`；`cypher`/`summary` 默认为 `json`）。 ## 🛠️ CLI 接口 两个层级：顶层是 **智能体命令**（查询 / 重构 / 验证），`ecp admin` 下是 **管理命令**（注册表 / 钩子 / 破坏性操作）。运行 `ecp --help` 和 `ecp admin --help` 获取完整的标志矩阵。 **智能体命令：** | 命令 | 用途 | |---|---| | `inspect ` | 符号 → 元数据、装饰器、签名、调用者、被调用者、1-跳影响、包含的方法/属性/枚举变体 | | `find ` | 精确 · `--mode fuzzy` · `--mode bm25` (5 个桶：源码 / 测试 / 引用 / 文档 / 配置) | | `find-schema-bindings ` | 镜像字段启发式边 + 跨类/服务的盲点候选 | | `find-transaction-patterns [--class ]` | Saga 补偿/撤销/回滚名称对；≥0.75 → POSSIBLY_RELATED，<0.75 → BLIND_SPOT | | `impact --direction ` | 带置信度过滤的爆炸半径 BFS；`--since ` 用于变更集影响 | | `rename --symbol --new-name ` | 跨 14 种语言的 AST 感知多文件重命名。务必先使用 `--dry-run`。 | | `cypher ''` | openCypher 应急接口；`m.content` 返回源码正文 | | `summary` | 注册表概述、框架覆盖范围、LLM 可操作的盲点目录、图新鲜度 | | `routes []` | HTTP 路由枚举（声明式 + 命令式）；带 ``：处理器 + 调用者链 | | `contracts` | 跨仓库 API 契约清单（路由 / 队列 / RPC） | | `diff` | 解析器差异：绑定层级降级 + 路由/契约变更 | | `tool-map` | 通过导入绑定分析的外部 HTTP / DB / Redis / 队列调用点 | | `shape-check` | HTTP 消费者访问模式与路由响应形状之间的漂移 | | `peers` | 多会话协作：`status / diff / say / inbox / log / thread / watch / gc` | | `review` | 单次审计：影响 + 摘要 + 工具映射 + 形状检查 + 差异，仅高置信度信号 | **管理命令** (`ecp admin `)： | 命令 | 用途 | |---|---| | `index --repo ` | 构建/刷新图；通过 xxh3_64 内容缓存进行增量。`--force` 进行完整重建。 | | `drop / prune / rename-branch` | 索引生命周期：删除、修剪陈旧分支目录、重命名磁盘上的分支 | | `install-hook` | Git 引用事务钩子（自动跟踪分支切换） | | `config` | `.ecp/config.toml` 的交互式 TOML 向导 | | `mcp serve` / `mcp tools` | MCP 服务器（stdio）；`tools` 列出暴露的接口 | 所有命令都从当前工作目录解析 `.ecp/graph.bin`，除非给出 `--graph `。每个面向智能体的命令都是非交互式的；每个输出流都是可解析的。 ### 多会话对等同步 当多个 LLM 会话并行编辑同一个仓库时，`ecp peers` 会显示每个会话的符号级脏状态，并支持直接的会话消息传递。通过 `ECP_SESSION_ID`、`CODEX_SESSION_ID`、`CODEX_THREAD_ID` 或 `CLAUDE_CODE_SESSION_ID` 注册。 ``` # 启动监视器（每个会话一个；接收收件箱推送事件所必需） ecp peers watch --start # 还有谁正在编辑？ ecp peers status # text ecp peers status --format json # {session_id, pid, watcher: alive|dead|not-started} # 检查对等方的脏符号 ecp peers diff [] # 发送消息 ecp peers say "rebasing on main, hold pushes 5min" # broadcast ecp peers say --to "take auth.rs?" # targeted # 读取与管理 ecp peers inbox ecp peers log --limit 20 ecp peers thread # 清理 ecp peers watch --stop && ecp peers gc ``` `watcher` 字段区分 `alive` | `dead` | `not-started` —— 崩溃不会伪装成"功能未使用"。 ### 可验证的代码审查结论 `ecp review --verdicts` 预计算了来自 `ecp diff` 部分的、基于图的结论。直接将 JSON 作为审查上下文传递 —— 避免 LLM 从原始差异中重新推导调用者关系。 ``` ecp review --since main --verdicts --format json ``` | 严重程度 | 规则 | |---|---| | `RISK` | 存在跨文件调用者、公共符号被移除，或差异区域存在盲点 | | `WARN` | 仅文件内调用者，或路由被修改 | | `INFO` | 未找到调用者，或新增公共接口 | 结论类型：`SIGNATURE_OR_BODY_CHANGED` · `NEW_PUBLIC_SURFACE` · `REMOVED_PUBLIC_SURFACE` · `ROUTE_CONTRACT_CHANGED` · `BLINDSPOT_IN_DIFF_REGION` 每个结论都引用了触发它的确切差异部分和图事实。完整规范：[docs/specs/2026-05-22-review-verdicts.md](./docs/specs/2026-05-22-review-verdicts.md)。 ## 🔌 智能体集成 **尽可能使用原生路径** —— 它会连接自动重新索引钩子和工作流技能，教智能体 *何时* 值得进行图查询往返。**MCP 是通用后备方案**，适用于任何支持该协议的宿主。 | 智能体 | 路径 | 连接 | |---|---|---| | Claude Code | 原生 | 钩子 + 技能 + 可选 MCP | | Codex CLI | 原生 | 技能（原生工具待定） | | Gemini CLI | 原生 | 原生技能 **或** MCP | | Cursor · Windsurf · Cline · Copilot · 任何 MCP 宿主 | MCP | MCP 服务器 | 引导式设置：`ecp admin → Agent Integrations → `。用于自动化的可脚本化路径：`ecp admin install `。检查任何宿主：`ecp admin status`。 ### Claude Code ``` ecp admin claude install hooks # settings.json: auto-reindex + context enrichment ecp admin claude install skills all # ecp + simplify skill packs (or: ecp | simplify) ecp admin claude install mcp-server # optional — hooks + skills + CLI already sufficient ``` 钩子在每次 Grep/Glob/Bash 时无需显式工具调用即可馈送图上下文。`ecp` 技能教授符号 / 影响 / 路由 / 契约 / 重命名工作流。`simplify` 推动基于图优先的代码审查。 ### Gemini CLI ``` ecp admin gemini install native-skill # links via `gemini skills link` ecp admin gemini install mcp-server # registers via `gemini mcp add` ``` `native-skill` 和 `mcp-server` 互斥 —— 安装一个会移除另一个。 ### Codex CLI ``` ecp admin codex install skills all # ecp + simplify; native-tools pending Codex wiring ``` **工作流技能：** | 技能 | 使用场景 | |---|---| | `ecp` | 智能体决定图感知工作流是否优于 grep / 文件读取来获取符号、调用者、路由、契约 | | `simplify` | 从 ecp 影响、盲点、出口、形状漂移、解析器差异开始的代码审查 | ### MCP 后备方案 (Cursor, Windsurf, Cline, 任何 MCP 宿主) | 宿主 | 配置文件 | |---|---| | Cursor | `~/.cursor/mcp.json` | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | | Cline (VS Code) | `cline_mcp_settings.json` (MCP 面板 → "编辑 MCP 设置") | | 通用 MCP 宿主 | 宿主特定 | ``` { "mcpServers": { "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] } } } ``` ``` ecp admin mcp tools # verify exposed surface before connecting ecp admin mcp serve # stateless one-shot per call (no warm-up cost) ``` ## 🏗️ 架构 ``` crates/ ├── ecp-core # Zero-copy graph (rkyv + mmap), incremental cache, graph queries ├── ecp-analyzer # Tree-sitter parsers, HTTP route detector, framework confidence ├── ecp-mcp # MCP server (stdio) — exposes core commands as tools └── ecp-cli # `ecp` binary, Tantivy BM25 engine, token-optimized output ``` 解析 → 解析 → 序列化通过一个 MPSC 通道运行到单个构建器线程，该线程组装图并写入零拷贝的 `.ecp/graph.bin`。读取路径（`inspect`、`cypher`、`impact` 等）直接 mmap 此文件 —— 无反序列化步骤。xxh3_64 内容缓存使增量重建在 22k 文件仓库上保持在亚秒级。 ## 🌐 语言覆盖 31 种语言在结构层面被解析。**14 种深度支持**（TypeScript, JavaScript, Python, Java, Kotlin, C#, Go, Rust, PHP, Ruby, Swift, C, C++, Dart）—— 导入、命名绑定、导出、继承、类型、构造函数、配置、框架、入口点、调用和重命名。**17 种仅结构化支持**：Bash, Crystal, Cairo, Dockerfile, Docker Compose, GitHub Actions, HCL, Lua, Markdown, Move, Nim, Solidity, SQL, Verilog, Vyper, YAML, Zig。 📊 **[完整语言能力矩阵](./docs/language-matrix.md)** —— 每种语言的状态和依据。 ## ⚙️ 调优 | 环境变量 | 默认值 | 效果 | |---|---|---| | `ECP_MAX_FILE_BYTES` | `16777216` (16 MiB) | 摄入期间跳过高于此大小的源文件。将最坏情况下的工作线程内存限制在 `num_threads × MAX`。 | | `ECP_CSPROJ_MAX_DEPTH` | `4` | `*.csproj` 发现递归深度。对于深度嵌套的 .NET monorepo，请提高此值。 | ## 📜 许可证与致谢 [PolyForm Noncommercial 1.0.0](./LICENSE.md)。明确允许个人使用、研究、业余项目和非商业组织。**此许可证未授予商业使用权** —— 请联系上游 GitNexus 作者 Abhigyan Patwari 获取商业权利。 构建于： - [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — 原始设计、CLI 接口和概念模型 - [tree-sitter](https://tree-sitter.github.io/) — 稳健的增量 AST 解析 - [rkyv](https://rkyv.org/) — 零拷贝反序列化框架 - [Tantivy](https://github.com/quickwit-oss/tantivy) — 全文搜索引擎 - [Rayon](https://github.com/rayon-rs/rayon) — 用于多核并发 AST 解析的数据并行 - [xxhash (xxh3_64)](https://xxhash.com/) — 用于基于内容的增量索引的非加密哈希 - [DashMap](https://github.com/xacrimon/dashmap) — 用于图组装的并发哈希映射 - [memmap2](https://github.com/RazrFalcon/memmap2-rs) — 用于亚毫秒图访问的零拷贝内存映射 - [msgspec](https://github.com/jcrist/msgspec) — 用于进程间通信的高性能 JSON 序列化 智能体引导（URL 引导、Claude Code 技能、插件安装）：`docs/skills/ecp-onboard/`。并发不变量与重新验证：`./scripts/audit/audit-concurrency.sh`。 ## 🚦 发布状态 已验证的安装路径：`cargo install --git ...`，从源码构建 `ecp`。发布安装程序已包含校验和和来源验证流程，但在二进制下载路径端到端验证之前，需要发布标签和资产。面向智能体的引导技能：[docs/skills/ecp-onboard/ONBOARDING.md](./docs/skills/ecp-onboard/ONBOARDING.md)。辅助配置/设置流程仍在完善中。

标签：AI代理工具, AI编程助手, AI驱动工具, API合同, DNS解析, Rust开发, 云安全监控, 代码分析, 代码搜索, 代码智能图, 代码检索, 代码理解, 冷启动性能, 准确代码图, 凭证管理, 可视化界面, 多语言解析, 大语言模型支持, 威胁情报, 开发者工具, 开发辅助, 开源项目, 影响分析, 快速索引, 性能优化, 查询延迟低, 检测绕过, 索引优化, 结构查询, 自主编码工作流, 自动化编码, 跨仓库分析, 软件工程工具, 软件开发, 通知系统, 静态分析, 高性能查询