内容
# 代码洞察
[](LICENSE)
> **GraphRAG赋能的AI编程助手项目知识 - 零手动文件读取，最大化令牌节省**
将此内容放入任何项目中，您的AI编程工具（Claude Code、Cursor、Codex）会自动理解整个代码库，无需手动逐一读取文件。
---
## 工作原理
```
您的项目/
├── src/...
├── .codensa/ ←首次运行自动创建
│ ├── graph.json ←依赖 + 符号图（NetworkX）
│ ├── vectors.pkl ←TF-IDF语义搜索索引
│ ├── summary.md ←压缩项目地图
│ └── meta.json ←文件哈希，统计信息
└── .claude/mcp.json ←integrate.py自动写入
```
在首次提示时，MCP服务器：
1. **解析**所有源文件（Python AST，TS/JS/Go的正则表达式）
2. **构建知识图谱**，包括文件 → 导入 → 符号
3. **索引所有代码**到TF-IDF语义搜索存储
4. **生成项目摘要**（技术栈，文件地图，架构）
在后续每次提示中，AI可以调用`project_summary`（一次工具调用）而不是读取30+个文件。
---
## 令牌节省
| 没有此功能 | 有此功能 |
|---|---|
| AI读取10-50个文件以理解项目 | 1次`project_summary`调用提供完整的地图 |
| 类似`grep`的文件扫描 | `semantic_search`立即找到相关代码块 |
| AI询问相关文件 | `find_symbol` + `file_graph`给出准确答案 |
| 上下文窗口充满样板代码 | 仅加载相关代码片段 |
**估计节省：中型项目上每会话减少60-80%的令牌**
---
## 快速开始
### 1. 安装
```bash
# 克隆到您的工具目录或任何方便的位置
git clone https://github.com/yourname/codensa
cd codensa
pip install -e .
```
### 2. 与您的AI工具集成（一条命令）
```bash
# 从您的项目内部运行
cd /path/to/your/project
python /path/to/codensa/integrate.py --index
# 或指定工具
python integrate.py --tool claude # 仅限Claude Code
python integrate.py --tool cursor # 仅限Cursor
python integrate.py --tool all # 所有（默认）
```
这会写入`.claude/mcp.json`和/或`.cursor/mcp.json`，并运行初始索引。
### 3. 开始编码
重启您的AI编程工具。在第一个提示中，服务器会自动索引项目。AI将自动调用`project_summary`（由`CLAUDE.md`引导），并立即了解整个代码库结构。
---
## MCP工具列表
| 工具 | 用途 | 何时使用 |
|------|---------|-------------|
| `project_summary` | Markdown格式的完整项目地图 | **始终是第一个** |
| `semantic_search` | 按描述查找相关代码 | 在打开文件之前 |
| `find_symbol` | 定位类/函数定义 | 代替grep |
| `file_graph` | 文件的导入/调用者 | 了解影响范围 |
| `list_files` | 浏览文件树及其统计信息 | 导航 |
| `get_file_content` | 读取确切的文件内容 | 仅在需要时 |
| `hot_files` | 最常导入的核心模块 | 架构概览 |
| `index_status` | 最后索引时间 | 刷新度检查 |
| `reindex` | 强制完全重新扫描 | 在重大重构后 |
---
## CLI用法
```bash
# 索引项目
codensa index /path/to/project
# 打印项目摘要
codensa summary /path/to/project
# 语义搜索
codensa search "身份验证中间件" /path/to/project
# 检查索引新鲜度
codensa status /path/to/project
# 启动为MCP服务器（stdio - 用于Claude Code / Cursor）
codensa serve /path/to/project
# 启动为HTTP MCP服务器（用于测试/远程）
codensa serve /path/to/project --http --port 8765
# 强制重新索引
codensa serve /path/to/project --reindex
```
---
## 手动MCP配置（Claude Code）
添加到`.claude/mcp.json`：
```json
{
"mcpServers": {
"codensa": {
"command": "codensa",
"args": ["serve", "/绝对路径/to/your/project"],
"env": {
"PROJECT_ROOT": "/绝对路径/to/your/project"
}
}
}
}
```
或直接使用`python`（如果未作为包安装）：
```json
{
"mcpServers": {
"codensa": {
"command": "python",
"args": ["/path/to/codensa/server.py", "/path/to/your/project"]
}
}
}
```
## 手动MCP配置（Cursor）
添加到`.cursor/mcp.json`：
```json
{
"mcpServers": {
"codensa": {
"command": "codensa",
"args": ["serve", "${workspaceFolder}"]
}
}
}
```
---
## 支持的语言
| 语言 | 解析器 | 提取内容 |
|---|---|---|
| Python | AST（内置） | 类，函数，装饰器，文档字符串，导入，调用 |
| TypeScript/TSX | 正则表达式 | 函数，类，接口，导入 |
| JavaScript/JSX | 正则表达式 | 函数，类，要求 |
| Go | 正则表达式 | 函数，结构体，导入 |
| Markdown | 原始文本 | 完整文本用于语义搜索 |
| YAML/TOML/JSON | 原始文本 | 配置键用于搜索 |
---
## 配置
通过环境变量或`.codensa/.config.json`设置：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `PROJECT_ROOT` | 当前工作目录 | 要索引的项目目录 |
| `MAX_FILE_SIZE_KB` | 200 | 跳过大于此大小的文件 |
| `TOKEN_BUDGET` | 8000 | 文件内容响应令牌的最大数量 |
---
## 图谱工作原理
每个索引项目都得到一个有向图谱：
- **文件节点**包含：大小，扩展名，符号，导入
- **符号节点**（`file.py::ClassName`）跟踪定义
- **边**：`defines`（文件 → 符号），`imports`（文件 → 模块）
`hot_files`按入度排名（最常导入 = 对项目最核心）。
`file_graph`显示任意文件周围的局部邻域。
---
## .gitignore推荐
```gitignore
.codensa/
```
索引会自动在文件更改时重建 - 无需提交。
---
## 要求
- Python 3.11+
- `fastmcp`，`networkx`，`tiktoken`，`scikit-learn`
- 无需GPU，无需模型下载，无需API密钥进行索引
---
## 许可证
[MIT](LICENSE) © 2026 Afroz Khan
