GoDotter 架构说明

本文档描述 godotter 仓库的技术架构、模块边界与数据流。
产品定位：面向 Godot 4.3+ 的 AI 原生编辑器插件（「Godot 版 Cursor」）。

1. 概述

根目录 project.godot（GoDotter Dev）供贡献者在仓库内开发插件；游戏项目通常只 vendor addons/GoDotter/。

2. 系统架构

2.1 双层结构

2.2 典型请求链路

1. 用户在 Forge Dock 输入目标（自然语言或 /plan、/do 等斜杠命令）。
2. EditorBridge 采集当前场景、选中节点、打开脚本、项目根路径等，组装 context bundle。
3. AgentClient 通过 HTTPRequest 异步 POST 到本机后端。
4. 后端结合项目索引、记忆文件、token 策略构建提示词，调用 LLM，返回结构化 JSON（如 Plan）。
5. UI 展示计划、diff、思考 trace；若用户开启文件编辑且通过审批，经双重安全门禁后写盘。

3. 目录结构

godotter/
├── project.godot              # 开发用 Godot 工程（启用插件）
├── README.md / INSTALL.md     # 用户与安装文档
├── 架构.md                    # 本文档
├── LICENSE                    # MIT
└── addons/GoDotter/           # ★ 唯一需要分发的目录
    ├── plugin.cfg             # 插件元数据（当前 v0.2.0）
    ├── GoDotter.gd            # EditorPlugin 入口
    ├── core/                  # GDScript 核心逻辑
    ├── ui/                    # Dock、Diff、向导等 UI
    ├── agents/                # 客户端 Schema / Prompt 参考
    ├── icons/
    └── backend/               # Python FastAPI（随插件打包）
        ├── main.py            # uvicorn 入口
        ├── requirements.txt
        ├── .env.example
        └── src/               # 后端实现
            └── tests/         # 单元 / 集成测试

约定：一个 addon 文件夹 = 完整产品（含 Python 后端），无需单独安装 agent 服务。

4. Godot 插件层（GDScript）

4.1 入口：GoDotter.gd

4.2 状态：ForgeState.gd

设置分为两类，均存于 EditorSettings，但语义不同：

运行时状态（不持久化）：backend_online、project_index、last_plan、active_task_id 等。

默认安全：enable_file_edits = false，approval_mode = "review"。

4.3 主 UI：ForgeDock.gd

聊天模式（无需记斜杠命令）：Full agent、Plan、Execute、Scene、Node、Index、Memory、Fix logs、Visual map、Help。

4.4 核心模块一览

4.5 客户端 Schema：agents/

• AgentSchemas.gd：与后端 schemas.py 对齐的 Plan 等结构校验与文档化 schema。
• AgentPrompts.gd：提示词片段（供 UI 或文档参考）。

5. Python 后端层

5.1 技术栈

• FastAPI + uvicorn
• google-genai、httpx、Pydantic v2、Pillow、python-dotenv

入口：backend/main.py → uvicorn.run("src.app:app", ...)。

5.2 HTTP API 概览

部分路由（如 /agent/validate、/tasks/*）为内部或演进接口，include_in_schema=False。

详细列表见 addons/GoDotter/backend/README.md。

5.3 核心模块

5.4 规划数据模型（Plan）

Architect Agent 返回 JSON，主要字段：

客户端 AgentSchemas.gd 与后端 schemas.py（Pydantic）保持镜像。

6. 安全与信任模型

6.1 双层门禁

用户 Settings（ForgeState）
  ├─ enable_file_edits      （默认 false）
  ├─ enable_scene_edits
  ├─ approval_mode        review | assisted | autopilot | yolo
  └─ max_files_per_run / max_lines_per_file

        ↓

SafetyManager.gd（编辑器）     safety.py（后端）
  ├─ 禁止：addons/、.godot/、project.godot、.import 等
  ├─ 危险操作黑名单（删库、改分支、shell 等）
  └─ review：所有编辑需 UI 批准

        ↓

write_file → 备份 → 可选 git checkpoint → Diff 面板 revert

6.2 设计立场

• 默认只读 AI：规划、解释、可视化，不自动改盘。
• 用户是创意总监：插件是带项目上下文的助手，非仓库所有者。
• 密钥不入库：.env、.godotter_api_key*、config.json 均在 .gitignore。

7. 特色工作流

7.1 Neon Visual Map

1. DebugVisualizer 按节点类型为场景树着色。
2. ScreenshotCapture 截取编辑器视口。
3. 后端 visual_map 将图像 + 节点空间映射送 LLM，回答布局、重叠、层级等问题。

7.2 Fix from logs

• 实时：GoDotterEditorLogger + GoDotterDebuggerHook → LogCollector。
• 后端 log_aggregator + /agent/fix_from_logs 生成批量修复计划。

7.3 项目记忆

• 路径：.godot_forge/memory/（已 gitignore）。
• 用途：架构约定、代码风格、已知 bug 等 Markdown，由 memory_store 注入规划上下文。

7.4 聊天图片

• UI：ChatImageLineEdit（文件选择、拖放、剪贴板）。
• 传输：Base64 经 context_images 进入 plan / execute / agent_run。

8. 配置与密钥

插件启动后端时自动传入 --project-root（当前 Godot 项目绝对路径）。

9. 本地生成数据（gitignore）

10. 开发与验证

版本：插件与后端均为 0.2.0；开发工程标注 Godot 4.6，插件兼容 4.3+。

11. 扩展与边界

11.1 当前明确非目标

• 不替代学习 Godot 引擎本身。
• 非托管 SaaS（后端须本机运行）。
• 非与 Cursor 功能对等的通用 IDE（领域约束为游戏 / Godot）。

11.2 演进中的能力

• MCP 设置（ForgeState 中 mcp_settings，探测 Godot MCP 等）。
• 部分 /agent/*、/tasks/* 路由为内部或实验性接口。
• 3D 资产审查、截图对比等持续迭代。

11.3 推荐扩展点

12. 依赖关系总览

用户 Godot 游戏项目
  └── addons/GoDotter/
        ├── GDScript：感知编辑器 + UI + 人类审批 + HTTP 客户端
        └── backend/：索引 + LLM + 受控文件工具 + 视觉/日志分析
              └── 外网依赖：仅各 Provider 的 API

13. 相关文档

• README.md — 产品介绍、安装、命令表
• INSTALL.md — 分步安装与排错
• addons/GoDotter/backend/README.md — API 与后端 CLI

文档随仓库代码演进；若与实现不一致，以 addons/GoDotter/ 内源码为准。