feat: 项目初始化 + 3D方块世界原型 + AI助搭系统

初始化 monorepo: Go后端(7微服务) + Unity客户端(9模块) + 启动器 HTML5原型: Three.js 3D体素世界, Perlin噪声地形, 原版材质, 22种方块 Minecraft创造模式背包: 双栏布局, 拖拽移动物品, 方向性元件引脚 AI助搭策划文档 + 客户端/服务端骨架 + Docker Compose + CI
2026-08-08 14:07:56 +08:00
parent 9500c4c80a
commit f70b061d1a
1972 changed files with 159760 additions and 6 deletions
@@ -0,0 +1,292 @@
+# MRCC 游戏内 AI 助搭功能策划文档
+
+> 版本: v1.0 | 日期: 2026-08-07 | 状态: 设计阶段
+
+## 1. 功能概述
+
+### 1.1 定义
+
+**AI 助搭**是 MRCC 游戏内置的智能助手系统，具备三大核心能力：
+
+| 能力 | 描述 | 示例 |
+|------|------|------|
+| **问答解惑** | 解答电路原理、元件属性、游戏机制相关问题 | "红石中继器怎么用？" "AND 门真值表是什么？" |
+| **助搭电路** | 根据需求描述，建议元件选型与放置方案 | "帮我搭一个二进制计数器" "这个电路怎么优化延迟？" |
+| **操作游戏** | 经用户确认后，AI 直接执行放置/连线/删除等游戏操作 | "把红石灯放到 (10,5)" "连接拉杆和第一个中继器" |
+
+### 1.2 设计目标
+
+- **零门槛上手**：新手无需查阅文档，直接用自然语言提问
+- **渐进式辅助**：从问答 -> 建议 -> 自动搭建，用户始终拥有最终决策权
+- **上下文感知**：AI 能感知当前画布状态、选中元件、游戏模式等上下文
+- **安全可控**：AI 的游戏操作必须经用户确认，支持撤销
+
+### 1.3 用户场景
+
+```
+场景 A：新手学习
+  用户："红石信号会衰减吗？"
+  AI："会。红石粉每传播 1 格衰减 1 点强度，满强度 15 最多传 15 格。
+       中继器可以恢复至满强度。需要我在画布上演示吗？"
+  用户："好的"
+  AI：[放置 电源 -> 15格红石粉 -> 红石灯，并标注信号强度]
+
+场景 B：电路设计辅助
+  用户："帮我搭一个 XOR 门"
+  AI："XOR 门可以用以下方案实现：
+       方案1: 2x NOT + 1x AND + 1x OR (成本 550 红石币, 延迟 3 tick)
+       方案2: 4x NAND (成本 880 红石币, 延迟 2 tick)
+       推荐方案1，性价比更高。需要我自动放置吗？"
+  用户："用方案1"
+  AI：[在画布上放置元件并连线，用户可预览后确认]
+
+场景 C：电路分析与优化
+  用户："分析一下我当前的电路"
+  AI："当前电路分析结果：
+       - 元件数: 23, 总成本: 1,840 红石币
+       - 信号路径: 电源 -> 中继器 x2 -> AND 门 -> 红石灯
+       - 最大延迟: 4 tick (可优化)
+       - 问题: 第 7 格红石粉信号已衰减至 0，导致断路
+       - 建议: 在第 5 格处添加中继器恢复信号"
+```
+
+## 2. 技术架构
+
+### 2.1 整体架构
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Unity 客户端                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
+│  │ AIChatPanel  │  │ AIAdvisor    │  │ AIAction  │ │
+│  │ (聊天 UI)    │  │ (电路分析)   │  │ Executor  │ │
+│  │              │  │              │  │ (操作执行) │ │
+│  └──────┬───────┘  └──────┬───────┘  └─────┬─────┘ │
+│         │                 │                │       │
+│  ┌──────┴─────────────────┴────────────────┴─────┐ │
+│  │          AIAssistantManager (核心协调器)        │ │
+│  └──────────────────────┬─────────────────────────┘ │
+│                         │                            │
+│  ┌──────────────────────┴─────────────────────────┐ │
+│  │          AIContextProvider (上下文采集)          │ │
+│  │  - 当前画布状态  - 选中元件  - 游戏模式  - 关卡信息│ │
+│  └──────────────────────────────────────────────────┘ │
+└─────────────────────────┬───────────────────────────┘
+                          │ HTTPS (REST + SSE)
+┌─────────────────────────┴───────────────────────────┐
+│                   ai-service (:8087)                  │
+│  ┌──────────┐  ┌───────────┐  ┌──────────────────┐  │
+│  │ Chat     │  │ Circuit   │  │ Action Planner   │  │
+│  │ Handler  │  │ Analyzer  │  │ (操作规划器)      │  │
+│  └────┬─────┘  └─────┬─────┘  └────────┬─────────┘  │
+│       │              │                 │             │
+│  ┌────┴──────────────┴─────────────────┴──────────┐  │
+│  │              LLM Gateway (大模型网关)            │  │
+│  │  - 意图识别  - 电路知识检索  - 操作序列生成      │  │
+│  └───────────────────────┬────────────────────────┘  │
+│                          │                            │
+│  ┌───────────────────────┴────────────────────────┐  │
+│  │           Knowledge Base (知识库)               │  │
+│  │  - 80 种元件规格  - 电路设计模式  - 关卡攻略     │  │
+│  └────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────┘
+```
+
+### 2.2 技术选型
+
+| 领域 | 方案 | 说明 |
+|------|------|------|
+| LLM 引擎 | OpenAI GPT-4o / Claude 3.5 / 国产模型 | 支持多模型切换，按成本和延迟选择 |
+| 检索增强 | RAG (元件手册 + 电路模式库) | 减少幻觉，确保元件数据准确 |
+| 流式输出 | Server-Sent Events (SSE) | 打字机效果，降低用户等待感 |
+| 操作规划 | Function Calling / Tool Use | LLM 输出结构化操作指令 |
+| 上下文管理 | 滑动窗口 + 电路状态摘要 | 控制 Token 消耗 |
+| 本地缓存 | 常见问题本地缓存 | 减少 API 调用，支持离线问答 |
+
+## 3. API 设计
+
+### 3.1 REST API
+
+| 方法 | 路径 | 说明 | 鉴权 |
+|------|------|------|------|
+| POST | `/api/ai/chat` | 发送聊天消息，返回 AI 回复 | 是 |
+| POST | `/api/ai/analyze` | 分析当前电路，返回诊断报告 | 是 |
+| POST | `/api/ai/suggest` | 根据需求生成电路搭建方案 | 是 |
+| POST | `/api/ai/execute` | 执行 AI 规划的操作序列 | 是 |
+| GET | `/api/ai/history` | 获取聊天历史 | 是 |
+| POST | `/api/ai/feedback` | 用户对 AI 回复反馈 (赞/踩) | 是 |
+
+### 3.2 核心数据结构
+
+```json
+// 聊天请求
+{
+  "sessionId": "sess_abc123",
+  "message": "帮我搭一个 XOR 门",
+  "context": {
+    "mode": "creative",
+    "canvasSize": "128x128",
+    "componentCount": 0,
+    "selectedComponent": null,
+    "levelId": null
+  }
+}
+
+// 聊天响应 (SSE 流式)
+{
+  "sessionId": "sess_abc123",
+  "type": "text|action|analysis|error",
+  "content": "XOR 门可以用以下方案实现...",
+  "actions": [
+    {
+      "type": "place",
+      "component": "NOT_GATE",
+      "x": 10, "y": 20,
+      "rotation": 0,
+      "description": "放置 NOT 门 (输入反相器 1)"
+    },
+    {
+      "type": "wire",
+      "from": {"x": 10, "y": 20},
+      "to": {"x": 12, "y": 20},
+      "description": "连接 NOT 门到 AND 门"
+    }
+  ],
+  "requiresConfirmation": true
+}
+
+// 电路分析报告
+{
+  "summary": "当前电路共 23 个元件，存在 1 处断路",
+  "metrics": {
+    "componentCount": 23,
+    "totalCost": 1840,
+    "maxDelay": 4,
+    "signalPaths": 2
+  },
+  "issues": [
+    {
+      "severity": "error",
+      "type": "signal_loss",
+      "location": {"x": 7, "y": 5},
+      "description": "信号在第 7 格衰减至 0，导致断路",
+      "suggestion": "在第 5 格处添加中继器恢复信号"
+    }
+  ],
+  "optimizations": [
+    {
+      "type": "delay_reduction",
+      "description": "移除冗余中继器可减少 1 tick 延迟",
+      "estimatedImprovement": "-1 tick"
+    }
+  ]
+}
+```
+
+## 4. 客户端模块设计
+
+### 4.1 模块结构
+
+| 脚本 | 职责 |
+|------|------|
+| `AIAssistantManager` | 核心协调器，管理 AI 会话生命周期，协调各子系统 |
+| `AIChatController` | 聊天 UI 控制器，处理消息收发与流式显示 |
+| `AICircuitAdvisor` | 电路分析与建议，解析 AI 返回的电路方案 |
+| `AIActionExecutor` | 操作执行器，将 AI 操作指令转换为游戏内动作 |
+| `AIContextProvider` | 上下文采集器，收集当前游戏状态供 AI 参考 |
+| `AIModels` | 数据模型定义 (请求/响应/操作指令) |
+
+### 4.2 操作执行流程
+
+```
+用户发送消息
+    │
+    ▼
+AIAssistantManager.HandleUserMessage()
+    │
+    ├─► AIContextProvider.CollectContext()  // 采集画布状态
+    │
+    ├─► ai-service POST /api/ai/chat        // 发送到服务端
+    │       │
+    │       ▼ (SSE 流式响应)
+    │   解析响应类型:
+    │       ├─ text     → AIChatController.AppendText()
+    │       ├─ action   → AIActionExecutor.QueueActions()
+    │       └─ analysis → AICircuitAdvisor.ShowReport()
+    │
+    ├─► AIActionExecutor (如果有操作指令)
+    │       │
+    │       ├─ 显示操作预览 (高亮待放置位置)
+    │       ├─ 用户确认 → 执行操作 (调用 PlacementController)
+    │       ├─ 用户拒绝 → 取消，记录反馈
+    │       └─ 用户编辑 → 修改后执行
+    │
+    └─► AIChatController.UpdateChatHistory()
+```
+
+### 4.3 安全约束
+
+- AI 操作**必须经用户确认**后才执行，不可自动执行
+- 每次操作最多放置 **20 个元件**，超出需分批确认
+- AI 不可操作**命令方块**和**结构方块**（仅创意模式手动放置）
+- 解谜模式下，AI 仅提供文字提示，**不可直接放置元件**
+- 所有 AI 操作支持**一键撤销** (记录操作前快照)
+
+## 5. 服务端设计
+
+### 5.1 ai-service 微服务
+
+| 属性 | 值 |
+|------|-----|
+| 端口 | 8087 |
+| 语言 | Go 1.22 / Gin |
+| 依赖 | LLM API、Redis (会话缓存)、PostgreSQL (历史记录) |
+
+### 5.2 LLM Gateway 设计
+
+```
+用户消息 + 上下文
+       │
+       ▼
+┌──────────────┐
+│  意图识别     │ → 问答 / 助搭 / 分析 / 操作
+└──────┬───────┘
+       │
+       ├─ 问答 → 检索知识库 → LLM 生成回复
+       ├─ 助搭 → 生成电路方案 → LLM 验证可行性
+       ├─ 分析 → 本地电路引擎分析 → LLM 生成建议
+       └─ 操作 → LLM Function Calling → 生成操作序列
+       │
+       ▼
+┌──────────────┐
+│  响应组装     │ → 统一格式输出
+└──────────────┘
+```
+
+### 5.3 知识库构建
+
+知识库包含以下结构化数据，供 RAG 检索：
+
+- **元件百科**：80 种元件的编号、属性、成本、使用说明
+- **电路模式库**：常见电路设计模式 (XOR 门、计数器、时钟发生器等)
+- **关卡攻略库**：240 关的通关提示 (仅提示，不给完整答案)
+- **红石原理**：信号衰减、延迟、BUD 更新等技术原理
+
+## 6. 开发计划
+
+| 阶段 | 内容 | 依赖 |
+|------|------|------|
+| Phase 1 | 基础聊天 + 元件问答 (接入 LLM API) | ai-service 骨架 |
+| Phase 2 | 电路上下文采集 + 电路分析报告 | 客户端仿真引擎 |
+| Phase 3 | AI 操作预览 + 确认执行 + 撤销 | 客户端编辑器 |
+| Phase 4 | RAG 知识库 + 电路方案生成 | 全部元件数据 |
+| Phase 5 | 解谜模式提示 (不操作) + 关卡攻略 | 关卡数据 |
+
+## 7. 成本估算
+
+| 项目 | 预估 |
+|------|------|
+| LLM API 调用 | $0.01-0.05 / 次对话 (GPT-4o) |
+| 月度 API 成本 (1000 DAU, 日均 5 次) | ~$1,500-7,500 |
+| 缓存命中率目标 | >40% (常见问题本地缓存) |
+| 本地模型备选 | Qwen2.5-7B (降低成本，需 GPU 服务器) |