MRCC/docs/AI助搭功能策划文档.md

# 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 服务器) |