GoDotter 架构说明

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

---

1. 概述

维度	说明
形态	Godot EditorPlugin + 本机 Python FastAPI 后端
分发	仅需拷贝 addons/GoDotter/ 到任意 Godot 项目的 addons/
AI	以 Google Gemini 为主；设置层支持 OpenAI、Claude 及 OpenAI 兼容端点
部署	本地优先（默认 127.0.0.1:8765）；项目文件留在本机，仅 LLM API 出网
设计原则	先规划 → 再 diff → 再执行；默认保守，文件写入需显式授权

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

---

2. 系统架构

2.1 双层结构

flowchart TB
    subgraph GodotEditor["Godot 编辑器"]
        GP[GoDotter.gd<br/>EditorPlugin]
        FD[ForgeDock<br/>主 UI]
        FS[ForgeState<br/>状态与设置]
        EB[EditorBridge<br/>编辑器上下文]
        AC[AgentClient<br/>HTTP 客户端]
        SM[SafetyManager / DiffManager / DebugVisualizer 等]
        GP --> FD
        FD --> FS
        FD --> EB
        FD --> AC
        FD --> SM
    end

    subgraph LocalBackend["本机 Python 后端"]
        APP[app.py<br/>FastAPI]
        ORCH[task_orchestrator<br/>规划 / 执行]
        RUN[agent_run<br/>完整 Agent 会话]
        IDX[project_indexer<br/>项目索引]
        GEM[gemini_client<br/>LLM 适配]
        TOOLS[code_tools / safety / git_tools]
        APP --> ORCH
        APP --> RUN
        APP --> IDX
        ORCH --> GEM
        RUN --> ORCH
        TOOLS --> APP
    end

    AC -->|HTTP JSON| APP
    EB -->|context_bundle| AC
    GP -->|OS.create_process| APP

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

职责	说明
Dock 挂载	动态加载 ui/ForgeDock.gd，避免硬编码 res:// 路径失效
后端进程	OS.create_process 启动 backend/main.py，传入 --project-root、--host、--port、--no-reload
端口策略	首选 8765；占用时扫描最多 64 个端口，并写回项目 Settings
日志捕获	GoDotterEditorLogger + GoDotterDebuggerHook → LogCollector（支撑 /fixlogs）
编辑器信号	选择变化、场景切换、文件系统变化 → 刷新 Dock 上下文

4.2 状态：ForgeState.gd

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

类型	键前缀	典型字段
机器级	godotter/machine/	backend_dir、backend_python、provider_api_keys、autostart_backend
项目级	godotter/project/（按项目路径）	model、ai_settings、approval_mode、enable_file_edits

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

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

4.3 主 UI：ForgeDock.gd

Tab	功能
Chat	多模式、多会话、图片附件、思考 trace、计划审批模式
Plan	结构化计划、步骤勾选、可选自动审批倒计时
Inspect	场景 / 节点摘要
Diff	变更预览、按文件 revert
Memory	.godot_forge/memory/ 下 Markdown
Settings	后端 URL、Provider/模型、MCP 探测、文件编辑开关

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

4.4 核心模块一览

模块	职责
AgentClient.gd	与后端 REST 通信；长请求自适应超时与重试
EditorBridge.gd	构建发往后端的 context bundle
ProjectScanner / SceneScanner / ScriptScanner / ResourceScanner	本地项目扫描
TaskQueue.gd	任务队列与状态机
DiffManager.gd	diff 展示与回滚协调
DebugVisualizer.gd	Neon Visual Map（节点着色 + 视口截图）
ScreenshotCapture.gd	编辑器视口截图
LogCollector.gd	聚合 Output / 调试器日志
ValidationRunner.gd / TestRunner.gd	验证与测试钩子
MemoryIndex.gd	记忆文件索引
SafetyManager.gd	客户端路径与操作门禁
SetupWizard.gd	首次运行向导（Python / venv / API key）

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 概览

类别	方法	路径	说明
健康	GET	/health	状态与 API key 检测
AI	GET	/ai/capabilities	模型能力
AI	POST	/ai/test_model_settings	测试模型配置
项目	POST	/project/index	扫描并索引项目
项目	POST	/project/context	按查询检索相关上下文
Agent	POST	/agent/plan	Architect：生成结构化 Plan
Agent	POST	/agent/execute	Code Agent：执行计划写文件
Agent	POST	/agent/run	完整会话：plan → 校验 →（可选）execute
视觉	POST	/agent/visual_map	Neon 2D 空间分析
视觉	POST	/agent/visual_review_3d	3D 资产多角度审查
日志	POST	/agent/fix_from_logs	从运行日志生成修复计划
工具	POST	/tools/read_file	安全读文件
工具	POST	/tools/write_file	安全写文件（含备份）
工具	POST	/tools/revert_file	从备份恢复
Git	GET	/tools/git_status	Git 状态
记忆	GET	/memory	读取项目记忆 Markdown

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

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

5.3 核心模块

模块	职责
app.py	FastAPI 应用、生命周期、路由注册、配置加载
task_orchestrator.py	Architect 提示词与 build_plan / execute_plan
agent_run.py	单次 HTTP 内的 plan → validate → execute 闭环
project_indexer.py	场景/脚本索引与紧凑上下文
context_engine.py	合并插件 hints、记忆、索引片段
gemini_client.py	多 Provider LLM 调用
ai_model_settings.py	Gemini / OpenAI / Claude 预设解析
code_tools.py / file_tools.py	读写、diff、备份
safety.py	路径必须在项目内；禁止敏感路径
validators.py	计划路径校验、GDScript/.tscn 启发式
visual_map.py	截图 + 节点空间图 + AI 分析
asset3d_review.py	3D 多角度审查
memory_store.py	.godot_forge/memory/
log_aggregator.py	日志聚合与 fix 计划
token_policy.py	上下文 token 预算
context_images.py	聊天图片注入上下文
git_tools.py	状态与 checkpoint
godot_cli.py	无头 Godot 脚本检查等

5.4 规划数据模型（Plan）

Architect Agent 返回 JSON，主要字段：

字段	类型	说明
summary	string	变更摘要
relevant_files / relevant_scenes	string[]	涉及资源（须来自索引，禁止臆造路径）
assumptions / risks	string[]	假设与风险
steps	object[]	步骤：description、files_affected、risk_level 等
validation_plan	string[]	验证清单（含编辑器内运行场景等）
approval_required	bool	是否需人工批准

客户端 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. 配置与密钥

来源	说明
编辑器 Settings	同步到 backend/.godotter_api_key 或 .godotter_api_keys.json
环境变量	GEMINI_API_KEY、GOOGLE_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY、OPENAI_BASE_URL 等
backend/.env	CLI/测试；shell 变量优先于 .env（main.py 中 override=False）
backend/config.json	从 config.example.json 复制，可覆盖 model、port 等（gitignore）

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

---

9. 本地生成数据（gitignore）

路径	内容
.godot/	Godot 编辑器缓存
.godot_forge/	索引、聊天会话、记忆、运行日志等
backend/.venv/	Python 虚拟环境
backend/config.json、.godotter_api_key*	本地配置与密钥

---

10. 开发与验证

检查项	方式
GDScript	godot --headless --path --check-only
Python 单元测试	cd addons/GoDotter/backend && python -m unittest discover -s tests -v
规划集成测试	tests/test_plan_towers_integration.py（需 GEMINI_API_KEY，否则 skip）

版本：插件与后端均为 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 推荐扩展点

层级	扩展方式
新斜杠命令 / 聊天模式	ForgeDock.gd 路由 + 对应后端端点
新工具	app.py 注册 + code_tools / 新模块 + SafetyManager / safety.py 规则
新 LLM Provider	gemini_client.py、ai_model_settings.py、Settings UI
上下文来源	EditorBridge、project_indexer、memory_store

---

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/ 内源码为准。*