CodeFlow：认知负荷优化的代码分析工具
概述
CodeFlow是一款基于Python的强大代码分析工具，旨在帮助开发者和自主代理以最小的认知负担理解复杂的代码库。它能够生成详细的调用图，识别关键代码元素，并提供语义搜索功能，同时始终遵循以人为本、注重人类理解的原则。
通过从抽象语法树（ASTs）中提取丰富的元数据，并利用持久向量存储（ChromaDB），CodeFlow能够实现对代码结构和行为的高效查询与可视化。
该工具提供了三个主要界面：
- 命令行界面工具（CLI Tool）一个用于直接分析和查询代码库的命令行界面。
- MCP服务器一个与AI助手和集成开发环境（IDE）集成的模型上下文协议服务器，用于实时代码分析。
- 统一API一个统一的程序接口，能够自动检测并分析Python和TypeScript代码库。
特点/功能
核心分析能力
- 深度AST元数据提取（Python & TypeScript） 收集关于函数和类的全面详细信息，包括：
- 参数、返回类型、文档字符串 - 圈复杂度和非注释代码行数（NLOC） - 应用了装饰器（例如。， @app.route， @transactional) - 显式捕获的异常 - 局部声明的变量 - 推断出的外部库/模块依赖关系 - 用于高效变更检测的源体哈希
- 统一界面： 一个单一的API，能够自动检测和分析Python和TypeScript代码库，无需手动指定语言。
- 智能调用图生成：
- 构建一个函数到函数调用的图。 - 使用多种启发式方法来识别代码库中的潜在入口点。
- 持久向量存储（ChromaDB）：
- 将所有提取的代码元素和调用边存储为语义嵌入。 - 支持对代码库中的函数及其元数据进行快速语义搜索和过滤查询。 - 将分析结果持久化到磁盘，以便无需重新解析即可即时查询之前分析过的项目。 - 自动清理： 后台进程会移除对已删除文件的无效引用，以保持索引的准确性和高效性。
可视化与输出
- 美人鱼图可视化：
- 生成基于文本的Mermaid流程图语法用于调用图。 - 突出显示与语义查询相关的功能。 - 包括一个 LLM优化模式 为了提供简洁且令牌高效的图表示，以适应大型语言模型的输入，同时提供清晰的别名和完全限定名（FQN）映射。
MCP服务器功能
- 实时分析： 对于动态代码库，实现带有增量更新的文件监视。
- 背景维护： 自动清理向量存储中的陈旧文件引用，以保持索引的准确性。
- 基于工具的API： 通过MCP工具为AI助手提供分析功能。
- 会话上下文： 为复杂分析工作流维护每个会话的状态。
- 综合工具： 语义搜索、调用图生成、函数元数据检索、入口点识别以及Mermaid图表生成。
CLI工具功能
- 批次分析： 完成代码库分析并生成报告。
- 交互式查询： 针对分析过的代码库进行语义搜索。
- 灵活输出： JSON 报告、Mermaid 图表和控制台输出。
- 增量更新： 查询现有分析结果，无需重新处理全部数据。
认知负荷优化
- 该工具的设计遵循了使输出结果和自身代码库易于理解和使用的原理。
- 思维模型的简洁性： 代码和输出中存在清晰、可预测的模式。
- 明确行为： 宁可详尽也不要简略，使隐含的操作变得显而易见（例如，使用装饰器）。
- 信息隐藏与局部性： 模块定义清晰，将相关代码放在一起。
- 最少背景知识要求： 自描述数据，常见模式，减少记忆需求。
- 战略抽象： 仅在确实能降低整体复杂性时才引入新层。
- 线性理解： 代码和输出结构清晰，便于从上至下阅读。
比较
| 系统 | 项目规模 | 索引时间 |
|---|---|---|
| RooCode | 40,000 行代码 | 2.2 分钟 |
| 代码流程 | 40,000 行代码 | 8.6 秒 |
要求
在运行 CodeFlow 之前，请确保您已安装 Python 3.8+ 及以下依赖项：
chromadb
sentence-transformers
mcp[cli]
pyyaml
watchdog>=2.0
pytest
pytest-asyncio
pydantic安装
来自源（或“来源”）
克隆仓库并安装依赖项：
git clone https://github.com/yourusername/codeflow.git
cd codeflow
pip install -e .这将安装包并以可编辑模式运行，同时使CLI工具和MCP服务器都可用。
命令行界面（CLI）工具
CLI 工具作为模块提供：
python -m code_flow_graph.cli.code_flow_graph --helpMCP 服务器
MCP服务器可用作脚本：
code_flow_graph_mcp_server --help用法
CLI 工具
这个（或“该”） code_flow_graph.cli.code_flow_graph 模块是命令行分析的主要入口点。所有命令均以以下开头：
python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY]
替换 [YOUR_CODE_DIRECTORY] 带上你项目的路径。如果省略，则使用当前目录（.）将被使用。
1. 分析代码库并生成报告
这个命令将解析你的代码库，构建调用图，并填充ChromaDB向量存储（持久化存储在 /code_vectors_chroma/), 并生成一个JSON报告。语言检测是自动的。
python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --output my_analysis_report.json2. 查询代码库（分析 + 查询）
进行全面分析，然后立即执行语义搜索。如果代码已更改，这将更新向量存储。
python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --query "functions that handle user authentication"3. 查询现有分析（仅查询）
一旦代码库被分析过（即，已经 code_vectors_chroma/ 目录存在于 [YOUR_CODE_DIRECTORY]), 您可以更快地查询它，而无需重新运行完整的分析：
python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --no-analyze --query "functions related to data serialization"4. 生成Mermaid调用图
您可以为与查询相关的函数生成调用图的Mermaid图表。
标准美人鱼（用于视觉渲染）：
python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --query "database connection pooling" --mermaid输出的是Mermaid语法，可以将其复制到Mermaid查看器中（例如，VS Code扩展、Mermaid.live）进行可视化。
针对AI代理优化的Mermaid（LLM优化版）
python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --query "main entry point setup" --llm-optimized这个输出去除了视觉样式，并使用了节点ID的简短别名，同时明确地 %% Alias: ShortID = Fully.Qualified.Name 评论。这在为大型语言模型（LLMs）提供所有必要的结构信息的同时，最大限度地减少了标记数量。
命令行参数
- `
（位置参数，可选）代码库目录的路径（默认：当前目录）.）。 这也是持久化ChromaDB存储的基础（/code_vectors_chroma/`）。 --output分析报告的输出文件（默认：code_analysis_report.json）。 *仅在全面分析时使用。*--query执行语义查询。--no-analyze(标志) 跳过抽象语法树（AST）提取和图构建。需要--query假设已存在一个向量存储。--mermaid(标志) 为查询结果生成Mermaid图表。需要--query。--llm-optimized(Flag) 生成针对LLM（大型语言模型）令牌数量优化的Mermaid图表（移除样式）。意指--mermaid.
示例报告输出
这个（或：该） code_analysis_report.json 提供了一个全面的JSON结构，包括概要、已识别的入口点、类概要以及详细的调用图（包含所有元数据的函数和边）。
MCP服务器
MCP服务器通过模型上下文协议（Model Context Protocol）提供对CodeFlow分析功能的程序化访问。它可以与AI助手、集成开发环境（IDE）以及其他兼容MCP的工具进行集成。
启动服务器
使用默认配置启动MCP服务器：
python -m code_flow_graph.mcp_server或者使用自定义配置文件：
python -m code_flow_graph.mcp_server --config path/to/config.yaml可用工具
服务器通过MCP协议提供了以下工具：
ping测试服务器连接性semantic_search使用自然语言查询进行语义搜索get_call_graph以JSON或Mermaid格式获取调用图get_function_metadata获取特定函数的详细元数据query_entry_points获取代码库中所有已识别的入口点generate_mermaid_graph生成用于调用图可视化的Mermaid图表cleanup_stale_references手动触发向量存储中陈旧文件引用的清理update_context使用键值对更新会话上下文get_context获取当前会话上下文
与客户端进行测试
使用随附的客户端测试服务器功能：
python client.py这执行了一个握手操作，并测试了基本工具的功能。
配置
MCP服务器配置
MCP服务器使用YAML配置文件（默认： code_flow_graph/mcp_server/config/default.yaml)：
watch_directories: ["code_flow_graph"] # Directories to monitor for changes
ignored_patterns: ["venv", "**/__pycache__"] # Patterns to ignore during analysis
chromadb_path: "./code_vectors_chroma" # Path to ChromaDB vector store
max_graph_depth: 3 # Maximum depth for graph traversal
embedding_model: "all-MiniLM-L6-v2" # Embedding model to use
cleanup_interval_minutes: 30 # Background cleanup interval for stale references通过创建自己的配置文件并将其传递给（程序），来自定义这些设置 --config.
TypeScript 支持
CodeFlow 提供了全面的 TypeScript 分析能力，其功能与 Python 支持相当。它可以分析 TypeScript 应用程序，提取详细的元数据，并为各种 TypeScript 框架构建调用图。
要求
TypeScript 分析是通过基于正则表达式的解析来进行的，无需任何外部依赖。 所有TypeScript语言特性都通过复杂的模式匹配得到支持。
使用示例
基础TypeScript分析
# Analyze a TypeScript project (language detection is automatic)
python -m code_flow_graph.cli.code_flow_graph /path/to/typescript/project --output analysis.json
# Query TypeScript codebase
python -m code_flow_graph.cli.code_flow_graph /path/to/typescript/project --query "user authentication functions"框架特定示例
Angular应用程序分析：
# Analyze Angular project (language detection automatic)
python -m code_flow_graph.cli.code_flow_graph /path/to/angular-app --query "component lifecycle methods"
# Find Angular services
python -m code_flow_graph.cli.code_flow_graph /path/to/angular-app --query "injectable services"NestJS 应用程序分析：
# Analyze NestJS backend (language detection automatic)
python -m code_flow_graph.cli.code_flow_graph /path/to/nestjs-app --query "controller endpoints"
# Find service dependencies
python -m code_flow_graph.cli.code_flow_graph /path/to/nestjs-app --query "database service dependencies"React TypeScript 分析：
# Analyze React TypeScript components (language detection automatic)
python -m code_flow_graph.cli.code_flow_graph /path/to/react-ts-app --query "custom hooks"
# Find component prop types
python -m code_flow_graph.cli.code_flow_graph /path/to/react-ts-app --query "component interfaces"TypeScript 特有功能
类型系统分析：
- 接口检测识别并提取TypeScript接口及其实现
- 类型注解分析函数参数和返回类型
- 泛型类型处理通用类型定义和约束
- 联合类型/交集类型处理复杂类型定义
- 装饰器分析检测Angular、NestJS和自定义装饰器
框架模式识别：
- Angular（注：Angular 是一个用于构建客户端应用程序的开源框架，常用于Web开发）组件、服务、模块、指令装饰器
- NestJS（Nest.js）控制器（Controller）、可注入（Injectable）、模块装饰器（Module decorators）
- 快递路由处理程序和中间件检测
- React组件类和钩子函数检测
TypeScript 配置
该工具自动检测并解析 tsconfig.json 关于项目结构信息：
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}支持的文件类型：
.ts- TypeScript 文件.tsx- TypeScript React/JSX 文件
解析策略
CodeFlow 使用基于复杂正则表达式的解析技术进行 TypeScript 分析，为以下方面提供全面支持：
- 类型注解和泛型
- 类、接口和枚举
- 装饰器和访问修饰符
- 框架模式（Angular、React、NestJS、Express）
- 进出口分析
示例
CLI 工具示例
基本面分析
# Analyze current directory and generate report (language detection automatic)
python -m code_flow_graph.cli.code_flow_graph . --output analysis.json
# Analyze a specific project
python -m code_flow_graph.cli.code_flow_graph /path/to/my/project语义搜索
# Find authentication functions
python -m code_flow_graph.cli.code_flow_graph . --query "user authentication login"
# Search for database operations
python -m code_flow_graph.cli.code_flow_graph . --query "database queries CRUD operations"可视化
# Generate Mermaid diagram for API endpoints
python -m code_flow_graph.cli.code_flow_graph . --query "API endpoints" --mermaid
# LLM-optimized graph for AI analysis
python -m code_flow_graph.cli.code_flow_graph . --query "error handling" --llm-optimizedMCP服务器示例
语义搜索
{
"tool": "semantic_search",
"input": {
"query": "functions that handle user authentication",
"n_results": 5,
"filters": {}
}
}获取函数元数据
{
"tool": "get_function_metadata",
"input": {
"fqn": "myapp.auth.authenticate_user"
}
}生成调用图
{
"tool": "get_call_graph",
"input": {
"fqns": ["myapp.main"],
"format": "mermaid"
}
}更新上下文
{
"tool": "update_context",
"input": {
"current_focus": "authentication_module",
"analysis_depth": "detailed"
}
}测试
MCP服务器测试
运行MCP服务器测试套件：
pytest tests/mcp_server/这包括对以下方面的测试：
- 服务器初始化和工具注册
- 工具功能（语义搜索、调用图等）
- 配置加载
- 文件监视和增量更新
CLI工具测试
通过在测试文件上运行分析来测试CLI工具：
# Test basic functionality
python -m code_flow_graph.cli.code_flow_graph tests/ --output test_report.json
# Test querying
python -m code_flow_graph.cli.code_flow_graph tests/ --query "test functions"集成测试
使用客户端脚本进行端到端测试：
python client.py这测试了MCP协议的握手过程以及基本工具之间的交互。
统一API
为了实现程序化访问，CodeFlow 提供了一个统一的接口，能够自动检测和分析 Python 和 TypeScript 代码库：
from code_flow_graph.core import create_extractor, extract_from_file, extract_from_directory, get_language_from_extension
# Create appropriate extractor based on file type (automatic language detection)
extractor = create_extractor('myfile.ts') # Returns TypeScriptASTExtractor
extractor = create_extractor('myfile.py') # Returns PythonASTExtractor
# Single API for both languages
elements = extract_from_file('myfile.ts') # Works for TypeScript
elements = extract_from_file('myfile.py') # Works for Python
# Directory processing with automatic language detection
elements = extract_from_directory('./src') # Processes all Python and TypeScript files
# Manual language detection
language = get_language_from_extension('file.ts') # Returns 'typescript'
language = get_language_from_extension('file.py') # Returns 'python'统一的接口提供：
- 自动语言检测： 无需手动指定使用 Python 还是 TypeScript
- 工厂模式：
create_extractor()返回适用于文件类型的提取器 - 一致的API： 相同的功能适用于这两种语言
- 简洁抽象： 隐藏了模块化结构下的复杂性
建筑
该工具由四个主要组件构成，设计注重清晰性和可维护性：
核心组件
- 统一界面 (
core/__init__.py)
- 为Python和TypeScript代码库提供一个统一的API。 - 用于自动语言检测和提取器创建的工厂函数。 - 通过隐藏模块化结构的复杂性来简化使用。
- AST 提取器 （
core/ast_extractor.py)
- 将源代码解析成抽象语法树。 - 提取丰富的元数据用于 FunctionElement 和 ClassElement 对象（复杂性、装饰器、依赖项等）。 - 根据（条件）过滤文件 .gitignore 用于相关分析。
- 调用图构建器 (
core/call_graph_builder.py)
- 基于提取的抽象语法树（AST）数据，构建函数调用的有向图。 - 使用多种启发式方法识别应用程序的入口点。 - 提供结构化内容 FunctionNode 并且 CallEdge 对象，包含丰富的元数据。
- 向量存储 (
core/vector_store.py)
- 与……集成 ChromaDB（可译为“色度数据库”或根据具体上下文保留为“ChromaDB”，若需更具体的翻译需结合应用场景） 为了构建一个持久且可查询的知识库。 - 存储函数和边的语义嵌入，以及它们的详细元数据。 - 支持语义搜索（query_functions) 并通过源代码哈希实现高效更新。
MCP服务器架构
- 服务器 (
mcp_server/server.py): 基于MCP SDK的服务器，用于处理MCP协议和工具注册。 - 分析仪 （
mcp_server/analyzer.py): 带有文件监视功能以实现增量更新的核心分析逻辑。 - 工具 （
mcp_server/tools.py): 基于请求/响应模型的MCP工具实现。 - 配置 (
mcp_server/config/): 基于YAML的配置管理。
CLI 工具架构
- 代码图分析器 (
cli/code_flow_graph.py): 分析流程的主要协调者。 - 命令行参数解析和输出格式化。
- 与核心组件集成，用于分析和查询。
贡献；助力
我们欢迎投稿！请参阅 贡献指南 （或如果你创建了类似的，请参考）以了解如何参与的详细信息。
许可证
这个项目遵循MIT许可证授权——详见 许可证 文件中有详细信息。
路线图
- 增强的TypeScript解析功能，与Python功能相当。
- 高级数据流分析（超越简单的局部变量）。
- 与其他可视化工具（如Graphviz）的集成。
- 为各种框架提供更精细的入口点检测。
- 直接集成IDE，实现实时分析和导航。
- 支持其他编程语言。
- 基于网页的交互式代码探索用户界面。
- 用于自定义分析规则的插件系统。
最近完成
- ✅ 统一接口模块单个API，用于自动检测和分析Python及TypeScript
- ✅ 工厂函数:
create_extractor()并且get_language_from_extension()用于简化使用 - ✅ 向后兼容性现有代码在新的模块化结构下继续正常运行
致谢
这个项目是在以下杰出工作的基础上建立起来的：