# godotguid

**Repository Path**: alienity/godotguid

## Basic Information

- **Project Name**: godotguid
- **Description**: godot ai doc for agent with three level
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Godot 引擎知识库

基于图结构的 Godot 4.x 引擎源码分析知识库。

## 🎯 核心特性

- **图结构知识库**: NetworkX + SQLite + ChromaDB 三层存储
- **模块索引系统**: 969 个类按 Godot 源码模块组织 (97.3% 覆盖)
- **三层文档结构**: Concept → API → Implementation 渐进式暴露
- **语义搜索**: 支持向量检索和图遍历
- **继承链追溯**: 821 条继承关系自动解析
- **方法/属性提取**: 支持 METHOD, PROPERTY, SIGNAL, CONSTANT 节点
- **图可视化**: 4 种静态可视化 + 交互式 HTML 图表
- **Web 界面**: Flask 应用，REST API
- **增量更新**: 检测变化并更新，避免全量重建

---

## 📁 项目结构

```
godotguid/
├── knowledge-base/          # 核心知识库 (2,937 个文档)
│   ├── {class}_concept.md   # Concept 层：核心概念
│   ├── {class}_api.md       # API 层：方法签名
│   ├── {class}_implementation.md  # Implementation 层：源码分析
│   ├── README.md            # 知识库说明
│   └── modules.json         # 模块索引 (969 个类) ⭐
│
├── graph_kb/                # 图知识库系统 ⭐
│   ├── __init__.py          # 主 API
│   ├── models.py            # 数据模型
│   ├── networkx_store.py    # NetworkX 存储
│   ├── sqlite_store.py      # SQLite 存储
│   ├── chroma_store.py      # ChromaDB 存储
│   ├── builder.py           # 图构建器
│   │
│   ├── build_graph.py       # 构建图
│   ├── add_inheritance.py   # 添加继承关系
│   ├── import_docs.py       # 导入文档
│   ├── fix_missing_classes.py    # 补充缺失类 ⭐
│   ├── extract_methods_properties.py  # 提取方法/属性 ⭐
│   ├── extract_all_members.py       # 批量提取所有类 ⭐
│   ├── incremental_update.py        # 增量更新 ⭐
│   ├── visualize_graph.py           # 静态可视化 ⭐
│   ├── visualize_interactive.py     # 交互式可视化 ⭐
│   ├── web_app.py                   # Web 界面 ⭐
│   └── test_graph.py        # 功能测试
│
├── graph_kb.db              # SQLite 数据库
├── chroma_graph_db/         # ChromaDB 向量索引
│
└── docs/                    # 文档索引
    ├── INDEX.md             # 总索引
    ├── USAGE_EXAMPLES.md    # 使用示例 ⭐
    └── modules/             # 模块概览
        ├── CORE.md          # Core 模块 (74 类)
        ├── SCENE.md         # Scene 模块 (204 类)
        ├── SERVERS.md       # Servers 模块 (235 类)
        ├── EDITOR.md        # Editor 模块 (49 类)
        └── MODULES.md       # Modules 模块 (30 类)
```

---

## 📊 统计信息

| 指标 | 数值 |
|------|------|
| **知识库文档** | 2,937 个 |
| **映射类数** | 969 个 |
| **覆盖率** | 97.3% |
| **图节点** | 3,616+ 个 |
| **图边** | 4,432+ 条 |
| **继承关系** | 821 条 |
| **向量文档** | 980+ 个 |
| **节点类型** | 8 种 (CLASS, METHOD, PROPERTY, SIGNAL, CONSTANT, MODULE, SUBMODULE, DOC_FILE) |
| **边类型** | 7 种 (contains, inherits, implements, has_property, emits, documented_by, related) |

### 模块覆盖

| 模块 | 类数 | 状态 |
|------|------|------|
| Core | 74 | ✅ 100% |
| Scene | 204 | ✅ 100% |
| Servers | 235 | ✅ 100% |
| Editor | 49 | ✅ 100% |
| Modules | 30 | ✅ 100% |
| Platform | 52 | ✅ 100% |
| Scene Extended | 290 | ✅ 100% |

---

## 🚀 快速开始

### 1. 环境要求

```bash
# Python 3.12+
# 安装基础依赖
pip install networkx chromadb

# 完整依赖（推荐）
pip install -r graph_kb/requirements.txt
# 包含：networkx, chromadb, matplotlib, plotly, flask
```

### 2. 使用图知识库

```python
from graph_kb import GraphKnowledgeBase

kb = GraphKnowledgeBase(
    modules_json_path="knowledge-base/modules.json",
    sqlite_db_path="graph_kb.db",
    chroma_dir="chroma_graph_db"
)

# 查询类信息
node = kb.get_class("CharacterBody2D")
print(f"模块：{node.module}, 子模块：{node.submodule}")

# 查找继承链
chain = kb.find_inheritance_chain("CharacterBody2D")
print(" → ".join(chain))
# characterbody2d → physicsbody2d → collisionobject2d → ...

# 获取完整上下文
context = kb.get_context("Sprite2D")
print(f"继承节点：{len(context['inheritance'])}")
print(f"相关节点：{len(context['related'])}")
print(f"文档：{len(context['documents'])}")

# 语义搜索
results = kb.semantic_search("2D 角色移动", limit=5)
for r in results:
    print(f"{r['metadata']['class_name']}: {r['content'][:50]}...")

# 模块导航
classes = kb.find_by_module("scene")
print(f"Scene 模块：{len(classes)} 个类")
```

### 3. 构建图知识库

```bash
# 基础构建
python3 graph_kb/build_graph.py
python3 graph_kb/add_inheritance.py
python3 graph_kb/import_docs.py

# 补充缺失的类
python3 graph_kb/fix_missing_classes.py

# 提取方法和属性（批量处理所有 969 个类）
python3 graph_kb/extract_all_members.py

# 生成可视化
python3 graph_kb/visualize_graph.py        # 静态图表
python3 graph_kb/visualize_interactive.py  # 交互式 HTML

# 启动 Web 界面
python3 graph_kb/web_app.py
# 访问 http://localhost:5000

# 增量更新
python3 graph_kb/incremental_update.py

# 运行测试
python3 graph_kb/test_graph.py
```

---

## 🛠️ 工具脚本

### 数据构建

| 脚本 | 功能 |
|------|------|
| `build_graph.py` | 从 modules.json 构建基础图结构 |
| `add_inheritance.py` | 从 Godot XML 解析并添加继承关系 |
| `import_docs.py` | 导入 Markdown 文档到 ChromaDB |
| `fix_missing_classes.py` | 补充缺失的类到 modules.json |

### 功能增强

| 脚本 | 功能 |
|------|------|
| `extract_all_members.py` | 批量提取所有 969 个类的方法/属性/信号/常量 ⭐ |
| `incremental_update.py` | 增量更新，检测变化并更新 ⭐ |
| `visualize_graph.py` | 生成 4 种静态可视化图表 |
| `visualize_interactive.py` | 生成交互式 HTML 图表 (Plotly) ⭐ |
| `web_app.py` | Flask Web 界面 + REST API ⭐ |
| `test_graph.py` | 功能测试和验证 |

---

## 📐 三层文档结构

每个 Godot 类的文档包含三个层次：

### Concept 层 (`{class}_concept.md`)

**核心问题**: "是什么？什么时候用？"

- 核心定义
- 类职责和使用场景
- 继承关系
- 与相似类的对比

### API 层 (`{class}_api.md`)

**核心问题**: "怎么调用？参数是什么？"

- 方法总览
- 方法签名和参数说明
- 使用示例

### Implementation 层 (`{class}_implementation.md`)

**核心问题**: "内部怎么工作？"

- 源码位置
- 核心算法
- 性能特征

---

## 🗺️ 模块索引

知识库按 Godot 源码模块组织：

### Core 模块 (core/)

引擎核心系统：Object, Variant, Math, IO, Crypto, Threading

```python
kb.get_class("object")      # 对象系统基类
kb.get_class("variant")     # 变体类型
kb.get_class("vector2")     # 2D 向量
kb.get_class("expression")  # 表达式解析器 ⭐
```

### Scene 模块 (scene/)

场景系统和节点：

- **2D**: Sprite2D, Camera2D, Light2D, Path2D ⭐
- **3D**: MeshInstance3D, Camera3D, Light3D, LimitAngularVelocityModifier3D ⭐
- **GUI**: Button, Label, Control, Range ⭐, Theme ⭐
- **Animation**: AnimationPlayer, Tween
- **Resources**: Resource, PackedScene, SpriteFrames ⭐

### Servers 模块 (servers/)

底层服务器：

- **Rendering**: RenderingServer, RenderingDevice, LightMapper ⭐
- **Physics**: PhysicsServer2D/3D, RayCast2D/3D ⭐
- **Audio**: AudioServer
- **Navigation**: NavigationServer2D/3D

### Editor 模块 (editor/)

编辑器系统（仅 Tools 版本）:

- **UI**: EditorInterface, EditorPlugin
- **Resources**: UndoRedo ⭐
- **Other**: AccessibilityServer ⭐

### Modules 模块 (modules/)

可选模块：XR, GDScript, WebSocket, Video

---

## 🔍 查询示例

### 继承链追溯

```python
chain = kb.find_inheritance_chain("Button")
# button → basebutton → control → canvasitem → node → object
```

### 上下文提取

```python
context = kb.get_context("RigidBody2D")
```

### 语义搜索

```python
results = kb.semantic_search("如何检测 2D 碰撞")
```

### 模块浏览

```python
scene_classes = kb.find_by_module("scene")
core_classes = kb.find_by_module("core")
```

### 方法/属性查询（提取后）

```python
# 获取类的所有方法
methods = kb.networkx.find_all_methods("class:button")
for method in methods:
    print(f"{method.name}: {method.properties.get('signature')}")

# 获取类的所有属性
properties = kb.networkx.find_by_type("PROPERTY")
```

---

## 📊 可视化

### 静态可视化

```bash
cd graph_kb
python3 visualize_graph.py
```

**输出目录**: `visualizations/`

1. **继承树** (`characterbody2d_inheritance.png`)
2. **模块结构** (`scene_module.png`)
3. **类关联** (`sprite2d_connections.png`)
4. **全图概览** (`full_overview.png`)

### 交互式可视化

```bash
cd graph_kb
python3 visualize_interactive.py
```

**输出目录**: `visualizations_interactive/`

- `characterbody2d_inheritance.html` - 交互式继承树
- `module_sunburst.html` - 模块旭日图

**查看**: 用浏览器打开 HTML 文件

---

## 🌐 Web 界面

```bash
cd graph_kb
python3 web_app.py
```

**访问**: http://localhost:5000

**功能**:
- 📊 统计仪表板
- 🔍 类搜索
- 🌳 继承链展示
- 📄 文档关联
- 🔗 REST API

**API 端点**:
```
GET /                          # Web 界面
GET /api/class/<name>          # 查询类信息
GET /api/search?q=<query>      # 语义搜索
GET /api/module/<name>         # 查询模块类列表
GET /api/stats                 # 获取统计信息
```

---

## 📖 文档索引

- **[docs/INDEX.md](docs/INDEX.md)** - 文档总索引
- **[docs/USAGE_EXAMPLES.md](docs/USAGE_EXAMPLES.md)** - 详细使用示例 ⭐
- **[docs/modules/CORE.md](docs/modules/CORE.md)** - Core 模块详解
- **[docs/modules/SCENE.md](docs/modules/SCENE.md)** - Scene 模块详解
- **[docs/modules/SERVERS.md](docs/modules/SERVERS.md)** - Servers 模块详解
- **[docs/modules/EDITOR.md](docs/modules/EDITOR.md)** - Editor 模块详解
- **[docs/modules/MODULES.md](docs/modules/MODULES.md)** - Modules 模块详解
- **[knowledge-base/README.md](knowledge-base/README.md)** - 知识库文档说明
- **[graph_kb/ADVANCED_FEATURES.md](graph_kb/ADVANCED_FEATURES.md)** - 高级功能指南 ⭐
- **[FINAL_SUMMARY.md](FINAL_SUMMARY.md)** - 最终总结 ⭐

---

## 🎯 当前状态

### 已完成 ✅

- [x] 图知识库系统 (NetworkX + SQLite + ChromaDB)
- [x] 模块索引 (969 个类，97.3% 覆盖)
- [x] 继承关系解析 (821 条边)
- [x] 三层文档结构 (2,937 个文档)
- [x] 语义搜索能力
- [x] 上下文追溯算法
- [x] 缺失类补充 (53 个) ⭐
- [x] 方法/属性节点提取 ⭐
- [x] 批量提取所有类 (extract_all_members.py) ⭐
- [x] 增量更新功能 ⭐
- [x] 静态可视化 (4 种类型) ⭐
- [x] 交互式可视化 (Plotly) ⭐
- [x] Web 界面 (Flask + REST API) ⭐
- [x] 完整测试套件

### 可选增强 🔄

- [ ] Agent 工具集成
- [ ] 知识图谱推理
- [ ] 自动问答系统

---

## 🔗 相关资源

- [Godot 官方文档](https://docs.godotengine.org/)
- [Godot GitHub 仓库](https://github.com/godotengine/godot)
- [Godot 源码](https://github.com/godotengine/godot)
- [功能完善报告](FEATURE_COMPLETE.md) - 详细改进记录
- [最终总结](FINAL_SUMMARY.md) - 完整项目总结 ⭐

---

## 📄 许可证

本项目与 Godot 引擎保持一致，使用 MIT 许可证。

---

**最后更新**: 2026-03-18  
**Godot 版本**: 4.7.0-dev  
**核心内容**: 2,937 个文档，969 个类，8 种节点类型，7 种边类型，11 个工具脚本