Files

T

CI / Go Backend (push) Canceled after 0s

Details

初始化 monorepo: Go后端(7微服务) + Unity客户端(9模块) + 启动器

HTML5原型: Three.js 3D体素世界, Perlin噪声地形, 原版材质, 22种方块

Minecraft创造模式背包: 双栏布局, 拖拽移动物品, 方向性元件引脚

AI助搭策划文档 + 客户端/服务端骨架 + Docker Compose + CI

2026-08-08 14:07:56 +08:00

12 KiB

Raw Blame History

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 核心数据结构

// 聊天请求
{
  "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 服务器)

12 KiB Raw Blame History Unescape Escape

MRCC 游戏内 AI 助搭功能策划文档

1. 功能概述

1.1 定义

1.2 设计目标

1.3 用户场景

2. 技术架构

2.1 整体架构

2.2 技术选型

3. API 设计

3.1 REST API

3.2 核心数据结构

4. 客户端模块设计

4.1 模块结构

4.2 操作执行流程

4.3 安全约束

5. 服务端设计

5.1 ai-service 微服务

5.2 LLM Gateway 设计

5.3 知识库构建

6. 开发计划

7. 成本估算

12 KiB

Raw Blame History