# code-knowledge-extractor

**Repository Path**: dr12730/code-knowledge-extractor

## Basic Information

- **Project Name**: code-knowledge-extractor
- **Description**: 将 Python 项目拆解成知识图谱
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-27
- **Last Updated**: 2025-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python 代码知识图谱构建工具

## 简介

本项目旨在分析 Python 项目源代码，将其拆解为函数、方法、类、全局变量等基本单元（知识节点），并构建一个包含这些单元及其相互关系的知识图谱。

最终目标是当您查询某个代码元素（如函数或方法）的全路径名称时，能够轻松检索到理解该元素所需的充足上下文信息（它调用了谁、谁调用了它、它引用了什么、谁引用了它、它继承自谁等）。如果初始上下文不足，可以基于检索到的关联节点进行二次检索，直至上下文信息足够清晰。

输出结果为一个 JSON 文件，包含了所有提取到的知识节点及其关系。

## 核心特性

*   **深度代码解析：** 使用 Python 内置的 `ast` 模块进行静态分析。
*   **多粒度单元识别：** 精确识别模块、类、函数、方法（实例、类、静态）、全局变量。
*   **元数据提取：** 获取文档字符串、函数/方法签名、类型注解、装饰器等信息。
*   **依赖关系捕获：** 识别代码单元之间的调用 (`calls`)、引用 (`references`)、继承 (`inherits_from`) 关系。
*   **双向链接构建：** 通过两阶段处理，不仅记录出向依赖，还构建反向链接（`called_by`, `referenced_by`），方便上下文追溯。
*   **嵌套结构支持：** 记录类、函数、方法内部定义的嵌套类和函数。
*   **路径解析：** 将文件路径转换为对应的 Python 模块/包导入路径 (`full_path`)。
*   **可配置性：** 支持通过正则表达式排除不需要分析的文件或目录。
*   **JSON 输出：** 生成结构化的 JSON 文件，便于后续处理和查询。

## 工作原理

本项目采用两阶段（Two-Pass）的解析策略来构建知识图谱：

1.  **第一阶段（Pass 1: 初始解析）**
    *   **目标：** 专注于独立解析每个代码单元（模块、类、函数、方法、变量），提取其 **内部信息** 和 **出向依赖**。
    *   **过程：** `AstVisitor` 遍历抽象语法树，识别不同类型的节点，提取如文档字符串、签名、实现源码等信息，并记录该单元 **调用** 了哪些其他函数/方法 (`calls`)、**引用** 了哪些变量/类 (`references`)、**继承自** 哪些基类 (`inherits_from`) 等。
    *   **产出：** 生成包含上述信息的节点数据列表。此时，**反向链接** 字段（如 `called_by`, `referenced_by`）被初始化为空列表 `[]`。

2.  **第二阶段（Pass 2: 链接构建）**
    *   **目标：** 利用第一阶段的输出，构建节点间的 **反向链接**。
    *   **过程：**
        *   读取第一阶段生成的全部节点数据。
        *   为所有节点建立一个基于 `full_path` 的快速查找索引（字典）。
        *   遍历所有节点，检查其 `calls`, `references`, `inherits_from` 等出向依赖字段。
        *   对于每一个出向链接（例如，节点 A 调用了节点 B 的 `full_path`），通过索引找到目标节点 B。
        *   在目标节点 B 的对应反向链接字段（如 `called_by`）中，添加源节点 A 的 `full_path`。
    *   **产出：** 更新节点数据列表，填充 `called_by` 和 `referenced_by` 字段，形成完整的双向知识图谱。

这种两步法将局部解析和全局链接解耦，提高了处理效率和代码的可维护性。

## 安装

1.  **克隆仓库：**
    ```bash
    git clone <your-repository-url> # 替换为你的仓库 URL
    cd code-knowledge-extractor
    ```

2.  **安装依赖和项目：**
    建议在 Python 虚拟环境中使用。
    ```bash
    python -m venv venv
    source venv/bin/activate  # Linux/macOS
    # venv\Scripts\activate  # Windows

    # 安装项目及其依赖 (pydantic 等)
    pip install .
    ```
    如果需要进行开发和修改，可以使用编辑模式安装：
    ```bash
    pip install -e .
    ```

## 使用方法

本项目提供了一个命令行工具 `code-knowledge` 来执行分析。

**基本语法：**

```bash
code-knowledge <project_directory> [options]
```

**参数说明：**

*   `<project_directory>`：**（必需）** 需要分析的 Python 项目的根目录路径。
*   `-o <文件路径>`, `--output <文件路径>`：**（可选）** 指定输出 JSON 文件的路径。默认为当前目录下的 `code_knowledge.json`。
*   `-e <正则表达式>`, `--exclude <正则表达式>`：**（可选）** 指定需要 **排除** 的文件或目录路径的正则表达式。此选项可以使用多次，用于过滤掉不需要分析的内容（如虚拟环境、测试文件、数据文件等）。
*   `-v`, `--verbose`：**（可选）** 启用详细的调试（DEBUG）级别日志输出，有助于追踪解析过程。

**示例：**

```bash
# 分析位于 /path/to/my_project 的项目，将结果保存到 output/graph.json
# 同时排除所有 tests 目录下的内容和 .venv 目录
code-knowledge /path/to/my_project -o output/graph.json -e ".*/tests/.*" -e ".*/\.venv/.*"

# 分析当前目录下的项目，并启用详细日志
code-knowledge . -v
```

## 输出格式

输出是一个 JSON 文件，其顶级结构是一个列表，列表中的每个元素是一个代表代码知识节点的 JSON 对象。

每个节点对象包含以下关键信息（具体字段取决于节点类型 `type`）：

*   `type`: 节点类型（`module`, `class`, `function`, `method`, `variable`）。
*   `full_path`: 节点的全局唯一 Python 风格导入路径（例如 `my_package.utils.helper_function`）。
*   `name`: 节点在其直接上下文中的本地名称（例如 `helper_function`）。
*   `docstring`: 节点的文档字符串（如果有）。
*   `module_full_path`: （针对类、函数、方法、变量）其所属模块的 `full_path`。
*   `signature`: （针对函数、方法）参数签名字符串。
*   `return_type_hint`: （针对函数、方法）返回类型注解字符串。
*   `implementation`: （针对函数、方法）该单元的源代码字符串（可选）。
*   `calls`: (针对函数、方法) 此单元直接调用的其他函数/方法的 `full_path` 列表 (Pass 1 提取)。
*   `references`: (针对函数、方法、类等) 此单元引用的其他变量、类、属性等的 `full_path` 列表 (Pass 1 提取)。
*   `inherits_from`: (针对类) 直接父类的 `full_path` 列表 (Pass 1 提取)。
*   `called_by`: **调用** 此函数/方法的其他单元的 `full_path` 列表 (Pass 2 填充)。
*   `referenced_by`: **引用** 此单元（类、变量、函数、方法）的其他单元的 `full_path` 列表 (Pass 2 填充)。
*   `methods`: (针对类) 类中定义的方法的 `full_path` 列表。
*   `class_variables`: (针对类) 类变量的详细信息列表。
*   `instance_variables`: (针对类) 推断出的实例变量的详细信息列表。
*   `nested_classes`: (针对类、函数、方法) 内部定义的类的 `full_path` 列表。
*   `nested_functions`: (针对类、函数、方法) 内部定义的函数的标识符列表（如 `parent.full_path.<locals>.nested_func`）。
*   ... 以及其他类型特有的字段。

**示例片段：**
```json
[
  {
    "type": "function",
    "name": "load_data",
    "full_path": "my_project.data_utils.load_data",
    "module_full_path": "my_project.data_utils",
    "signature": "(file_path: str) -> pandas.DataFrame",
    "return_type_hint": "pandas.DataFrame",
    "docstring": "从指定的 CSV 文件加载数据。",
    "calls": [
      "my_project.processing.DataProcessor.clean_column",
      "pandas.read_csv"
    ],
    "references": [
      "my_project.config.DEFAULT_CHUNK_SIZE",
      "my_project.models.RawDataContainer"
    ],
    "called_by": [ // 由 Pass 2 填充
        "my_project.main.process_file"
    ],
    "referenced_by": [], // 由 Pass 2 填充
    "nested_classes": [],
    "nested_functions": []
  },
  {
    "type": "method",
    "class_name": "DataProcessor",
    "class_full_path": "my_project.processing.DataProcessor",
    "name": "clean_column",
    "full_path": "my_project.processing.DataProcessor.clean_column",
    "method_type": "instance",
    // ... other fields ...
    "called_by": [ // 由 Pass 2 填充
        "my_project.data_utils.load_data"
    ],
    "referenced_by": []
  }
  // ... more nodes
]
```

## 配置

主要的配置项是文件/目录的排除规则。

*   **默认规则：** 在 `src/code_knowledge_extractor/config.py` 文件中的 `DEFAULT_EXCLUDE_PATTERNS` 定义了一些常见的排除模式（如 `__pycache__`, `venv`, `tests`, `docs` 等）。
*   **命令行覆盖/添加：** 可以通过 `-e` 或 `--exclude` 命令行参数添加自定义的排除规则。这些规则会与默认规则合并使用。
*   **语法：** 排除模式使用的是 Python 的标准 `re` 模块支持的正则表达式语法。模式将与文件的 **绝对路径**（转换为 POSIX 风格 `/` 分隔符）进行匹配。

## 开发状态

本项目目前处于 **Alpha/开发中** 阶段。核心的代码解析和链接功能已经实现，但可能仍然存在未发现的 Bug，或者在处理某些复杂的 Python 语法特性时不够完善。性能方面在大项目上可能需要进一步优化。

## 贡献

欢迎通过提交 Issue 报告 Bug、提出改进建议，或者通过 Pull Request 直接贡献代码。

## 许可证

本项目采用 MIT 许可证授权。详情请参阅 `LICENSE` 文件（如果仓库中包含）。