xyou
f70b061d1a
CI / Go Backend (push) Canceled after 0s
初始化 monorepo: Go后端(7微服务) + Unity客户端(9模块) + 启动器 HTML5原型: Three.js 3D体素世界, Perlin噪声地形, 原版材质, 22种方块 Minecraft创造模式背包: 双栏布局, 拖拽移动物品, 方向性元件引脚 AI助搭策划文档 + 客户端/服务端骨架 + Docker Compose + CI
293 lines
12 KiB
Markdown
293 lines
12 KiB
Markdown
# 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 服务器) |
|