Aethvion/Aethvion-ProjectMapper
GitHub: Aethvion/Aethvion-ProjectMapper
面向 AI 编程助手的代码知识图谱工具，通过一次性静态扫描构建结构化索引，让 agent 精准查询所需上下文从而大幅降低 token 消耗。
Stars: 0 | Forks: 0
# Aethvion Project Mapper
## 快速开始
**第 1 步 — 安装 `uv`**（一次性操作，自动管理 Python）：
```
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
**第 2 步 — 安装 Project Mapper：**
```
uv tool install "aethvion-project-mapper[languages]"
```
**第 3 步 — 连接到你的 agent：**
| Agent | 设置指南 |
|---|---|
| Claude Code | [docs/howto/setup-pm-on-claude-code.md](docs/howto/setup-pm-on-claude-code.md) |
| Cursor | [docs/howto/setup-pm-on-cursor.md](docs/howto/setup-pm-on-cursor.md) |
| Antigravity (Google) | [docs/howto/setup-pm-on-antigravity.md](docs/howto/setup-pm-on-antigravity.md) |
| Codex | [docs/howto/setup-pm-on-codex.md](docs/howto/setup-pm-on-codex.md) |
或者直接跳转到下方的[完整 MCP 配置部分](#mcp-stdio-claude-code--cursor--antigravity--codex)查看原始 JSON。
第一次来这里？[`docs/explained/`](docs/explained/README.md) 文件夹涵盖了[Project Mapper 是什么](docs/explained/what-is-project-mapper.md)、[MCP 工具是什么](docs/explained/what-is-mcp.md)、[PM 在你的机器上具体读取和存储了什么](docs/explained/what-does-pm-access.md)，以及[完整的工具参考](docs/explained/pm-tools-reference.md)。
## 为什么会有这个项目
AI 编程 agent（Claude Code、Cursor、Copilot 等）在每次执行任务时都会搜索你的文件——读取源代码文件、追踪导入、通过 grep 寻找上下文。这不仅昂贵而且缓慢，当 agent 真正发现关键内容之前，上下文窗口早就被半相关的内容填满了。
Project Mapper 只需扫描你的代码库一次，就能构建出一个结构化的知识图谱，涵盖每个模块、类、函数及其关系，并让 agent 在几毫秒内查询*他们只需要的内容*，从而将 token 成本平均降低 **87–92%**。
## 基准测试数据
在 [11 个真实的代码库](docs/benchmarks/README.md)中进行了测量——包括 Python、Java/Kotlin、C#、PHP、C、Go、Ruby、TypeScript/JS、Rust、C++、Swift——文件数量从 57 到 11,083 不等。
### 汇总（所有 11 个项目的几何平均数）
| 模式 | Token 减少 | 相对于正常模式的速度提升 |
|:---|:---|:---|
| **PM Full** | **~87%** | **~快 380 倍** |
| **PM Slim** | **~92%** | **~快 380 倍** |
在输入 100,000 个 token 时，PM 通常只使用 **~13,000**（Full）或 **~8,000**（Slim）个 token。
PM Slim 仅返回名称 + 文件路径 + 行号——足以满足导航和重构任务的需求。PM Full 返回完整的实体上下文。有关每个代码库的具体数据，请参阅[完整基准测试套件](docs/benchmarks/README.md)；有关 3 项测试的审计对比，请参阅[安全基准测试](docs/benchmarks_security/README.md)。
### 查询延迟（实测）
| 查询 | 延迟 |
|---|---|
| 上下文查询 | 1–100 ms（缓存已预热） |
| 影响查询 | < 1–10 ms |
### 会话启动 — 实体映射加载（实测）
实体映射存储为一个在每次扫描结束时构建的单一快照文件。
| 代码库大小 | 加载时间 |
|---|---|
| ~400 个实体 | < 50 ms |
| ~12,000 个实体 | ~145 ms |
| ~33,000 个实体 | ~300 ms |
### 规模化时的财务影响（模型推算）
| 团队规模 | 每月 AI 编程成本（预估） | 使用 PM 节省的费用 |
|---|---|---|
| 独立开发者 | $80 | $74 |
| 10 人团队 | $2,400 | $2,230 |
| 100 人团队 | $48,000 | $44,600 |
| 企业级（1,000 名开发者） | $480,000 | $446,400 |
## 它的功能
1. **静态扫描** — 遍历你的项目，通过 AST 分析提取每个模块 / 类 / 函数。此步骤无需 AI。
2. **知识图谱** — 将实体 + 关系（imports、calls、extends、depends_on 等）存储在本地 JSON 数据库中。
3. **Agent 查询** — 10 个 MCP 工具，agent 可以调用它们来代替直接读取原始文件：
| 工具 | 回答的问题 |
|---|---|
| `pm_context` | "在动 auth 系统之前我需要了解什么？" |
| `pm_impact` | "如果我修改 `UserService` 会破坏什么？" |
| `pm_path` | "`RateLimiter` 是怎么跟支付流程连起来的？" |
| `pm_find` | "`validateToken` 定义在哪里？" |
| `pm_orphans` | "有哪些代码从未被调用过？" |
| `pm_security` | "这个代码库里有安全漏洞吗？" |
| `pm_contribute` | "记录一下我给 endpoint X 加了限流" |
| `pm_stats` | "这个数据库里已经索引了什么？" |
| `pm_delta` | "自上次扫描以来有什么变化？" |
| `pm_scan` | "立刻扫描这个项目目录" |
有关每个工具的完整文档，请参阅 [PM 工具参考](docs/explained/pm-tools-reference.md)。
## 安全扫描
`pm_security` 是内置于 Project Mapper 中的独立 SAST 风格扫描器。只需一次调用即可检查整个代码库——除了安装之外，没有任何扫描依赖或设置。
- **132+ 个模式**，涵盖 8 种语言中的 OWASP Top 10 (A01–A10)：Python、TypeScript/JS、Java、Go、C#、PHP、Ruby、C/C++
- **执行时间 1–5 秒**，适用于任何大小的代码库
- **路由可达性污点分析** — ⚡ 标记已确认可从 HTTP handler 访问的发现结果
- **每次发现都包含 CWE 映射**，拥有稳定的发现 ID 以便持久化分类管理，支持跨扫描的快照差异对比
它旨在与 `pm_context` 配合使用：`pm_security` 在几秒钟内捕获 100% 文件中可通过模式检测到的漏洞；`pm_context` 随后弥补模式无法检测到的逻辑缺陷和 IDOR 漏洞。有关在 OWASP Juice Shop 上的 3 项测试对比，请参阅[安全基准测试](docs/benchmarks_security/README.md)。
## 其他访问方式
### HTTP API
```
# 安装
pip install aethvion-project-mapper
# 启动 server
uvicorn server:app --port 7474
# 扫描你的项目
curl -X POST http://localhost:7474/api/project-mapper/scan \
-H "Content-Type: application/json" \
-d '{"project_root": "/path/to/your/project", "enrich": false}'
# 为任务查询 context
curl -X POST http://localhost:7474/api/project-mapper/query/context \
-H "Content-Type: application/json" \
-d '{"q": "add rate limiting to auth endpoints", "detail_level": "medium"}'
```
文档位于 **http://localhost:7474/docs**
### Docker
```
docker compose up
# Server 运行于 http://localhost:7474
```
挂载你的项目：
```
# docker-compose.yml — 将 PROJECTS_DIR 设置为你的代码根目录
PROJECTS_DIR=/home/you/code docker compose up
```
### MCP stdio (Claude Code / Cursor / Antigravity / Codex)
单一的全局配置让每个会话都能访问 Project Mapper。AI 会在调用 `pm_scan` 时传入项目根目录，因此你无需预先指定——只需告诉 Claude（或 Cursor 等）扫描当前项目，它就会处理剩下的事情。
**第 1 步 — 安装 `uv`**（一次性操作，如果已经安装可跳过）：
```
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 已经有 Python？或者：
pip install uv
```
`uv` 会管理自己的 Python 环境——即使未安装 Python，上面的 curl/PowerShell 安装脚本也能正常工作。
**第 2 步 — 安装 Project Mapper**（一次性操作）：
```
uv tool install "aethvion-project-mapper[languages]"
```
这会将 `pm-mcp` 安装为全局命令，并下载所有语言解析器。首次运行大约需要 30 秒，后续启动则是瞬间完成。
**第 3 步 — 添加到你的 agent 配置并重启：**
**Claude Code** — 添加到 `~/.claude/settings.json`：
```
{
"mcpServers": {
"project-mapper": {
"type": "stdio",
"command": "pm-mcp",
"args": ["--db", "workspace"]
}
}
}
```
**Cursor** — 添加到 `.cursor/mcp.json`：
```
{
"mcpServers": {
"project-mapper": {
"command": "pm-mcp",
"args": ["--db", "workspace"]
}
}
}
```
**Antigravity (Google)** — 添加到 `~/.gemini/antigravity/mcp_config.json`：
```
{
"mcpServers": {
"project-mapper": {
"type": "stdio",
"command": "pm-mcp",
"args": ["--db", "workspace"]
}
}
}
```
**备选方案 — 无需安装，直接使用 uvx 运行：**
```
{
"command": "uvx",
"args": ["--from", "aethvion-project-mapper[languages]", "pm-mcp", "--db", "workspace"]
}
```
**可选 — 锁定到单个项目：**
如果你总是开发同一个代码库，可以添加 `PM_PROJECT_ROOT`，这样 AI 就永远不需要明确指定它了：
```
{
"mcpServers": {
"project-mapper": {
"...",
"env": { "PM_PROJECT_ROOT": "/absolute/path/to/your/project" }
}
}
}
```
## 配置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `PM_DATA_DIR` | `~/.aethvion_pm/data` | 所有数据库的根目录 |
| `PM_LOG_LEVEL` | `INFO` | 日志级别：DEBUG / INFO / WARNING / ERROR |
| `PM_DB_NAME` | `default` | MCP server：数据库名称 |
| `PM_DB_PATH` | *(未设置)* | MCP server：明确的数据库路径 |
| `PM_PROJECT_ROOT` | *(未设置)* | MCP server：pm_scan 的默认项目根目录 |
## 项目结构
```
project_mapper/
├── config.py — DATA_DIR config
├── routes.py — FastAPI router (/api/project-mapper/*)
├── scanner.py — Async background scan engine
├── ingestor.py — CodeAnalysis → AethvionDB entities
├── code_analyzer.py — Python AST extractor
├── query.py — Impact / context / shortest-path algorithms
├── cleanup.py — Incremental scan maintenance
├── delta.py — Filesystem diff (no DB writes)
├── mcp_tools.py — 10 MCP tool schemas + handlers
├── mcp_server.py — JSON-RPC 2.0 stdio MCP server
└── db/
├── entity_schema.py — Entity data model + validation
├── entity_writer.py — Create / update / delete entities
├── name_index.py — Thread-safe name → ID index
├── file_manifest.py — File ↔ entity provenance tracking
├── snapshot.py — Fast-load snapshot cache
└── db_registry.py — Named database registry
server.py — FastAPI app entry point
```
## 增量扫描
后续扫描仅处理自上次运行以来 SHA-256 哈希值发生变化的文件。
在之前已扫描过的 10,000 个文件的代码库中，增量模式通常只需处理
不到 1% 的文件——扫描时间从约 60 秒骤降至 2 秒以内。
```
# 全量扫描（首次或强制刷新）
curl -X POST .../scan -d '{"project_root": "...", "incremental": false}'
# 增量扫描（默认 — 仅限已更改的文件）
curl -X POST .../scan -d '{"project_root": "..."}'
```
## 许可证
**开源核心：** [GNU AGPL v3](LICENSE)
可自由使用、修改和自托管。网络使用要求将你的修改部分开源。
**商业许可证：** [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md)
面向需要专有许可、SLA 或集成支持团队的可用选项。
## 支持开发
如果 Project Mapper 为你节省了 token、时间或金钱——请考虑赞助。这能保障项目的持续维护以及新语言 / 功能的不断推出。
[](https://github.com/sponsors/Aethvion)
查看完整的[赞助者列表](https://github.com/Aethvion/.github/blob/main/SPONSORS.md)。
*由 Aethvion 团队用心打造。*
标签：AI编程辅助, MCP, SOC Prime, 上下文优化, 安全专业人员, 开发工具, 请求拦截, 逆向工具, 错误基检测, 静态代码分析