# pmap **Repository Path**: fansxnet/pmap ## Basic Information - **Project Name**: pmap - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-31 - **Last Updated**: 2026-10-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CodeGraph — 有记忆的项目代码地图 Rust 实现的本地代码索引工具,为 **AI agent 编码**而生:把项目解析成「符号 + 调用链 + 模块标签 + LLM 功能描述」的知识图谱,并在此基础上构建**业务模块地图**。代码零注释,AI 也能快速、准确地定位到具体代码。 核心能力一览: | 能力 | 说明 | |---|---| | 代码地图 | 11 种语言的符号/调用图/导入依赖,调用链带模块路径与标签 | | 注释替代 | 符号 / 文件 / 模块三层摘要,由大模型全量或增量填充,随代码演进自动继承 | | 业务地图 | 树形业务模块(业务名/摘要/HTTP 入口/归属文件),目录骨架自动生成、业务语义由 AI 定义 | | 实时增量 | `watch` 常驻监听,抖动合并后只重解析变化文件(单文件 ~10ms) | | MCP 集成 | 12 个工具挂进 ZCode/Claude 等 agent,即查即用 | | 项目记忆 | 本仓库的 PLAN.md 即开发接力文档(多 agent 并行开发约定) | ## 支持语言(18 种,对齐开源 CodeGraphContext 语言清单) Rust · TypeScript · TSX · JavaScript · Python · Go · Java · Kotlin · Scala · Lua · Bash · Elixir · **C · C++ · C# · Ruby · PHP · Swift** (为控制二进制体积与编译时间,舍弃了 Dart/Perl/Haskell 三个冷门语言——grammar 源码保留在 vendor/,需要时改 build.rs 一行即可加回。全部 grammar 统一 vendor 编译,规避 tree-sitter crate 的 links 多版本限制。) ## 构建 ```bash cargo build --release # 产物 target/release/codegraph(.exe) ``` 需要 C 编译器(tree-sitter;本机为 MinGW gcc + windows-gnu 工具链,MSVC 亦可)。Kotlin grammar 已 vendor 至 `vendor/`,由 `build.rs` 直接编译,无额外依赖。 ## 快速开始 ```bash # 1. 初始化(生成 .codegraph.toml、.gitignore 追加 .codegraph/、首次扫描) codegraph init # 2. 常驻实时增量更新(开发时保持运行) codegraph watch # 3. 让 AI 补摘要(注释替代) codegraph llm scan # 导出缺摘要的符号/模块/文件 + 提示词 # 把 .codegraph/llm/prompt.md 交给大模型,结果存 .codegraph/llm/descriptions.json codegraph llm apply # 回填 # 4. 业务模块地图 codegraph business # 树形查看(目录骨架自动生成) codegraph llm scan --business # 导出业务骨架交 AI 定义业务语义 codegraph llm apply --business # 5. 日常查询 codegraph brief # 项目简报(agent 接手先看) codegraph search <关键词> # 搜符号 codegraph show <符号> # 详情:签名/文档/摘要/调用关系 codegraph calls <符号> --depth 2 # 调用链(含模块与标签) codegraph file <路径> # 文件视图:符号/依赖/入口/摘要 codegraph context "任务描述" # 三层检索的代码上下文包(给 LLM) codegraph stats # 四层摘要覆盖率统计 ``` ## 命令参考 | 命令 | 说明 | |---|---| | `init` | 初始化:默认配置 + .gitignore 追加 + 首次扫描 | | `scan [--full]` | 增量扫描(默认跳过未变文件);`--full` 强制全量重建 | | `watch` | 常驻监听文件变化,实时增量更新索引 | | `search [--kind fn\|method\|class\|struct\|iface\|trait\|enum] [--limit N] [--regex]` | 搜索符号(名称/限定名/文档/描述/标签,相关度排序) | | `show <符号>` | 符号详情:签名、文档、LLM 摘要与描述、调用/被调列表 | | `calls <符号> [--direction in\|out\|both] [--depth N]` | 调用链树形展开,每个节点带模块与标签 | | `file <路径>` | 文件视图:包、标签、摘要、依赖、HTTP 入口、符号清单 | | `tree [前缀]` | 目录树 + 模块摘要 + 每文件符号数 | | `business` | 业务模块地图(树形) | | `stats` | 索引统计:文件/节点/边/外部调用/四层摘要覆盖率 | | `context "<描述>" [--limit N]` | 三层检索(模块摘要 → 文件摘要与入口 → 符号),输出 LLM 友好的上下文包 | | `brief` | 项目简报:规模、目录分布、高扇出核心符号、agent 使用指南 | | `llm scan [--limit N] [--business]` | 导出待补摘要清单(增量)与提示词;`--business` 导出业务骨架 | | `llm apply [--file F] [--business F\|-]` | 回填描述;`--business` 回填业务树 | | `llm stats` | 四层摘要覆盖率 | | `mcp [--project 路径]` | 以 MCP server(stdio JSON-RPC)运行 | | `dump-tree <文件>` | 调试:打印某文件的 tree-sitter 语法树 | 全局选项:`--project <路径>` 指定项目根(默认当前目录)。 ## 配置文件 `.codegraph.toml` ```toml [scan] languages = [] # 为空 = 全部 11 种;也可只挑 ["rust", "python"] max_file_kb = 1024 # 超过此大小的文件跳过 [ignore] # 在 .gitignore 基础上追加的忽略规则(gitignore 语法,裸目录名自动展开为任意层级) patterns = [ "**/node_modules/**", "**/target/**", "**/dist/**", "**/__pycache__/**", ] [tags] # 相对路径 glob -> 附加标签(调用链与检索使用) # "src/api/**" = ["api", "http"] [watch] debounce_ms = 500 # 文件事件抖动合并窗口 [llm] description_language = "中文" # 生成的摘要语言 max_snippet_lines = 24 # 导出符号时的源码片段行数 batch_size = 60 # 单次导出符号数上限 ``` 忽略规则优先级:内置(`.codegraph` 永远忽略)> `.gitignore`(无需 git 仓库也生效)> 配置 patterns。 ## LLM 三层摘要(注释替代) 数据模型中每层都有 AI 填充位: | 层 | 字段 | 用途 | |---|---|---| | 符号 | `desc`(2~4 句功能描述)、`summary`(≤30 字)、`tags` | `show`/`calls`/`search`/`context` 直接引用 | | 文件 | `summary` | `file`/`tree`/`context` 引用 | | 模块(目录) | `name`/`summary`/`desc`/`tags` | 目录注释,`tree`/`context` 引用 | 工作流(增量语义): 1. `codegraph llm scan` — 导出**只含缺摘要的**对象(JSON + 现成提示词 prompt.md;符号带源码片段) 2. 把 prompt.md 交给任意大模型,得到 JSON(结构见 prompt 内说明) 3. `codegraph llm apply` — 校验回填并落盘快照 继承规则:文件重解析时,**限定名 + 签名都相同**的符号保留描述——小改动不丢 AI 记忆;签名变了视为需要重新描述。回填建议携带 `qualified` 限定名(数字 id 在重扫后不稳定,id 失效时自动按 qualified 兜底)。 ## 业务模块地图 业务模块 ≠ 目录。地图分两部分: - **自动骨架**:`scan` 时按目录推导生成(含每目录自动探测的 HTTP 入口),开箱即用 - **AI 定义节点**:`llm scan --business` 导出骨架(每节点含文件/符号/路由清单)→ AI 重组为业务树(如 `用户/登录`)并填业务名、摘要、入口 → `llm apply --business` 回填(自动校验文件引用,剔除已删除文件的引用并提示) HTTP 入口探测为跨语言通用启发式:调用名末段为 `GET/POST/PUT/DELETE/...` 且首参为字符串路径字面量(覆盖 gin/express/fastapi/actix/axum 等常见写法,含 Python 装饰器)。 ## MCP 集成 ZCode 工作区配置(本仓库已启用,见 `.zcode/config.json`): ```json { "mcp": { "servers": { "codegraph": { "command": "E:\\worktree\\codegraph\\target\\release\\codegraph.exe", "args": ["mcp", "--project", "你的项目路径"] } } } } ``` 12 个工具: | 工具 | 作用 | |---|---| | `codegraph_search` | 按关键词搜索符号 | | `codegraph_show` | 符号详情与调用关系 | | `codegraph_calls` | 调用链(in/out/both + 深度) | | `codegraph_file` | 文件视图 | | `codegraph_context` | 三层检索上下文包 | | `codegraph_brief` | 项目简报 | | `codegraph_stats` | 索引统计 | | `codegraph_business` | 业务模块地图 | | `codegraph_tree` | 目录树 | | `codegraph_reindex` | 增量重扫(改完代码后调用) | | `codegraph_llm_pending` | 导出缺摘要清单(含 prompt) | | `codegraph_llm_apply` | 回填描述/业务树 | 全工具功能冒烟:`python -u scripts/mcp_full_test.py`(12/12 通过)。 ## 架构 ``` src/ main.rs CLI 定义与分发(clap derive) config.rs .codegraph.toml + 忽略规则(gitignore 语义) + 标签 glob lang.rs 语言枚举 / 扩展名 / 模块路径推导 graph.rs 图模型 Node/Edge/FileEntry/ModuleInfo/BizNode/Route + 名字索引 + 校验和快照 extract/mod.rs RawFile 模型 + tree-sitter 通用辅助 + 路由启发式 extract/*.rs 每语言一个提取器(符号/调用/导入/文档注释/路由) scan.rs 走盘(ignore crate) → rayon 并行解析 → 增量合并 → 描述继承 → 业务骨架 query.rs search/show/calls/file/tree/business/stats/context/brief llm.rs 三层摘要导出/回填 + 业务树导出/回填 watch.rs notify 监听 + 抖动合并 mcp.rs stdio JSON-RPC server(12 工具) build.rs 编译 vendored kotlin grammar ``` 依赖方向:`main → scan → extract/graph/config`;`query/llm/mcp/watch` 只依赖 `graph/config/scan`。 ## 性能 实测(Windows release 构建,热缓存): | 项目 | 文件 | 全量扫描 | 增量 | |---|---|---|---| | ripgrep (Rust) | 105 | 223ms | 34ms | | gin (Go) | 99 | 139ms | — | | axios (TS/JS) | 275 | 279ms | — | | 合成项目 | 2000 | 解析 615ms(并行) | 326ms | | hutool (Java, gitee) | 2297 | 解析 656ms | 441ms | 查询 52~60ms(含进程启动与快照加载)。watch 单文件更新 ~10ms。 设计要点:xxh3 内容哈希 + mtime 双重跳过未变文件 → rayon 并行解析 → 只重建变化文件的边(悬空边合并后统一补解析)→ 原子写快照。冷盘首次扫描受杀毒实时扫描影响会显著变慢,与索引算法无关。 ### 快照自愈 快照封装格式:`MAGIC("CGSNAP01") + payload 长度 + xxh3 校验和 + bincode payload`(版本号内嵌)。加载时校验长度与校验和——截断/损坏/版本不匹配秒级识别并自动全量重建,读取瞬时失败(文件被外部进程短暂干扰)自动重试 3 次。注意:损坏自动重建会丢失 AI 描述(描述随代码可增量再补)。 ## 已知限制 - 未解析的调用边主要指向标准库/第三方依赖(索引只覆盖项目内符号),`stats` 单独列出 - 业务树中 AI 定义的 `files` 引用在代码删除后会失效(待任务 T11:显示"代码缺失"标记) - Elixir `@doc` 为简化提取;复杂语法(C++ 模板、Python 动态特性等)按"够用"策略 - 快照自动重建会丢失 AI 描述,需重新 `llm scan/apply`(增量填充成本低) - 符号 id 在全量重建后不稳定——回填请携带 `qualified` ## 开发本项目(agent 接力) 读根目录 **PLAN.md**(唯一的开发接力文档):架构地图、并行冲突边界、任务池、进度时间线、踩坑经验。约定:认领任务改状态、完成追加时间线、经验沉淀到「经验与坑」,全部由 agent/人工直接编辑,程序不读写。