代码库智能分析

智能代码库分析工具，自动理解项目结构、模块边界和依赖关系。

版本: 1.0
功能特性: 增量索引缓存、符号搜索、智能问答、架构图生成

---

快速开始

1. 首次索引（自动缓存）

bash
cd /path/to/project
python3 /path/to/codebase-intelligence/scripts/main.py analyze .

首次运行会创建 .codebase-intelligence/ 目录并缓存索引。后续查询秒级响应！

2. 智能问答

bash

查找代码位置

python3 main.py ask Where is authentication implemented?

了解工作流程

python3 main.py ask How does the user login flow work?

查找修改方法

python3 main.py ask What files need to change to add OAuth?

3. 符号搜索

bash

查找类定义

python3 main.py analyze --symbol UserManager --symbol-type class

查找函数

python3 main.py analyze --symbol authenticate --symbol-type func

4. 依赖分析

bash

查看文件依赖

python3 main.py deps src/auth.py

查看依赖该文件的内容

python3 main.py deps src/utils.py --reverse

5. 生成架构图

bash

Mermaid 图表

python3 main.py diagram --format mermaid

流程图

python3 main.py diagram --format mermaid-flow --entry-points main.py app.py

---

命令列表

命令	功能	示例
analyze	分析代码库（带缓存）	main.py analyze . --stats
analyze --search

搜索文件 | main.py analyze --search auth | | analyze --symbol | 查找符号 | main.py analyze --symbol User | | ask | 智能问答 | main.py ask How does X work? | | deps | 依赖分析 | main.py deps src/main.py --reverse | | diagram | 生成图表 | main.py diagram --format mermaid | | index | 更新索引 | main.py index --export index.json |

---

功能特性

✅ 增量缓存

• - 首次分析后自动缓存
• 后续仅更新修改过的文件
• 大型项目也能秒级响应

bash

第一次：建立索引（可能需要几秒）

python3 main.py analyze .

第二次：秒级响应！

python3 main.py analyze . # 瞬间完成

✅ 符号索引

自动索引：

• - 函数定义
• 类/接口定义
• 导入语句
• 文件元数据（语言、行数）

✅ 智能问答

支持的问题类型：

• - 定位: Where is X? → 定位代码
• 工作原理: How does X work? → 理解流程
• 定义: What is X? → 查找定义
• 依赖: What depends on X? → 依赖分析
• 修改: How to add X? → 修改建议

✅ 多语言支持

语言	符号解析	依赖提取
Python	✅	✅
JavaScript/TypeScript

✅ | ✅ | | Go | ✅ | ✅ | | Java | ✅ | ✅ | | Rust | ✅ | ⚠️ | | Ruby | ⚠️ | ⚠️ | | PHP | ⚠️ | ⚠️ |

---

使用示例

场景 1：接手新项目

bash

1. 获取整体概览

python3 main.py analyze /path/to/project --stats

2. 了解主要模块

python3 main.py analyze --search module

3. 查找核心类

python3 main.py analyze --symbol App --symbol-type class

4. 了解工作流程

python3 main.py ask How does data flow through the system?

5. 生成架构图

python3 main.py diagram --format mermaid-component

场景 2：重构前分析

bash

1. 检查依赖待重构模块的内容

python3 main.py deps src/old-module.py --reverse --depth 3

2. 了解影响范围

python3 main.py ask What would break if I refactor the auth module?

3. 查看修改建议

python3 main.py ask How to migrate from class X to class Y?

场景 3：代码审查

bash

查看变更影响

python3 main.py ask What depends on src/utils/helpers.py?

---

配置说明

忽略文件

在 .codebase-intelligence.json 中配置：

json
{
ignore: [
node_modules,
.git,
*.test.js,
vendor/
],
entryPoints: [
src/main.py,
src/index.js
]
}

缓存位置

默认缓存位置：/.codebase-intelligence/codebase_index.pkl

也可指定：

bash
python3 main.py analyze . --cache-dir /path/to/cache

---

输出格式

Markdown 报告

bash
python3 main.py analyze --stats

包含：

• - 项目概览
• 语言分布表
• 模块结构树
• 符号统计

JSON 导出

bash
python3 main.py index --export index.json

结构化数据，包含完整索引信息。

Mermaid 图表

bash
python3 main.py diagram --format mermaid

可直接在 Markdown/GitHub/GitLab 中渲染。

---

性能表现

项目规模	首次索引	增量更新
小（<100文件）	<1秒	<0.1秒
中（100-1000文件）

2-5秒 | <0.5秒 |
| 大（1000-5000文件） | 10-30秒 | <2秒 |

---

文件结构

skills/codebase-intelligence/
├── SKILL.md # 本文件
└── scripts/
├── main.py # ⭐ 统一入口
├── indexer.py # 索引引擎（带缓存）
├── ask_v2.py # 智能问答
├── analyze.py # 基础分析
├── deps.py # 依赖分析
└── diagram.py # 图表生成

---

集成方式

Git 钩子

bash

.git/hooks/pre-commit

python3 scripts/main.py index

CI/CD

yaml

.github/workflows/analysis.yml

• - name: 分析代码库

run: |
python3 scripts/main.py analyze --stats
python3 scripts/main.py diagram --format mermaid > architecture.md

---

后续规划 / 路线图

• - [x] 增量缓存
• [x] 符号索引
• [x] 智能问答
• [ ] AST 解析（提高准确性）
• [ ] 接入 LLM（语义理解）
• [ ] 实时监听模式
• [ ] Web 界面

---

生产就绪？✅

当前状态：可用，适合日常使用

• - 缓存机制 ✅
• 增量更新 ✅
• 符号索引 ✅
• 智能问答 ✅
• 性能优化 ✅

待完善：

• - AST 解析（当前使用正则，存在 5-10% 误差）
• LLM 集成（当前基于关键词匹配）