# AIArchitect

**Repository Path**: cyanbukkit/AIArchitect

## Basic Information

- **Project Name**: AIArchitect
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-28
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIArchitect · Minecraft AI 建筑师插件

> 让大模型（LLM）把你的文字需求直接变成可撤销的 Minecraft 建筑。支持 OpenRouter 与 SiliconFlow，全流程可配置，兼容 WorldEdit 的 `//undo` / `//redo`。

![status](https://img.shields.io/badge/build-successful-2ea44f) ![java](https://img.shields.io/badge/Java-8-1f6feb) ![gradle](https://img.shields.io/badge/Gradle-KTS-blue) ![minecraft](https://img.shields.io/badge/Paper-1.16.5-ffdb4d) ![worldedit](https://img.shields.io/badge/WorldEdit-7.2.0-4d97ff)

## 项目概览
- 核心定位：根域大语言模型（Claude / ChatGPT / Gen3 / Kimi K2 / Maxmini…）→ 结构化建筑指令 → 批量方块构建
- 交互流程：`/aib start` 开启会话 → 玩家给出需求 → 放置起始方块 → 指定平台与模型 → 异步请求生成建筑指令 → `/aib build xxx.txt` 执行建造
- 变更管理：使用 WorldEdit 的会话与历史记录，建造后可 `//undo` 撤销、`//redo` 重做（整栋建筑为一个操作单元）
- 配置化：支持自定义 AI 提示词（prompt_lines）、生成结果目录（result_dir）、API Key、热重载 `/aib reload`

## 特性亮点
- BlockState（方块状态）级控制：支持 `minecraft:block_name[key=value,...]` 完整状态配置，如楼梯朝向、台阶上下、是否注水等
- 范围填充语法：除单点外支持区域构建，轻松生成墙体、地面、屋顶等结构
- Undo/Redo 友好：所有改动绑定在玩家的 WorldEdit 会话历史中，撤销恢复完整建筑状态
- 版本兼容：适配未来材质降级（如 PALE_OAK → OAK 系列）保障跨版本稳定构建
- 纯 Gradle KTS 构建：避免 ShadowJar，`gradle build` 即可

## 安装与运行
1. 服务器环境要求：
   - Java `8`
   - Paper `1.16.5`（或兼容版本）
   - 安装插件：`WorldEdit 7.2.0`
2. 构建插件：
   - 在仓库根目录执行：
     ```bash
     ./gradlew build
     ```
     看到 `BUILD SUCCESSFUL` 即编译成功
3. 部署插件：
   - 将生成的 `build/libs/*.jar` 放入服务器 `plugins/` 目录
   - 启动服务器，确认日志无报错
4. 配置密钥：
   - 编辑 `src/main/resources/config.yml`：
     ```yaml
     openrouter:
       api_key: "YOUR_OPENROUTER_KEY"
     siliconflow:
       api_key: "YOUR_SILICONFLOW_KEY"
     result_dir: "result"
     prompt_lines:
       - "...多行提示词..."
     ```
   - 在游戏内执行 `/aib reload` 热重载配置

## 指令与交互
- `/aib` 无子命令时显示彩色帮助
- `/aib start` 开始会话，按提示输入需求（文字）
- 放置一个起始方块（基础方块），确定相对坐标原点
- 输入平台与模型：`openrouter:gpt-4o` 或 `siliconflow:Qwen2-72B-Instruct`
- 等待生成完成后，使用：
  - `/aib list` 查看生成文件
  - `/aib build <文件名>` 执行建造（自动记录至 WorldEdit 历史）
- 变更管理：`//undo` 撤销整栋建筑，`//redo` 重做
- 配置热重载：`/aib reload`

## 建造指令格式（AI 输出）
- 单点格式：
  ```
  dx;dy;dz;BlockState
  ```
  例：
  ```
  0;0;0;minecraft:stone_brick_stairs[facing=north,half=bottom,shape=straight,waterlogged=false]
  ```
- 范围格式（区域填充）：
  ```
  dx1;dy1;dz1;dx2;dy2;dz2;BlockState
  ```
  例：
  ```
  -10;0;-10;10;0;10;minecraft:grass_block
  ```
- 分隔符：同一行内使用 `|` 分隔多条；或使用多行分隔
- 坐标体系：所有偏移均以玩家放置的“起始方块”为原点（相对坐标）
- BlockState 示例（楼梯/台阶/水）：
  ```
  minecraft:oak_stairs[facing=east,half=top]
  minecraft:stone_slab[type=bottom]
  minecraft:glass[waterlogged=false]
  ```

## 配置项说明
- `openrouter.api_key`：OpenRouter 平台密钥
- `siliconflow.api_key`：SiliconFlow 平台密钥
- `result_dir`：AI 生成的建筑结果文件目录（默认 `result`）
- `prompt_lines`：聊天提示词（会自动拼接为多行，支持变量）
  - 支持变量：`{requirement}`（玩家需求文本）、`{version}`（服务器版本字符串）
- 游戏内热重载：`/aib reload`

## 架构与实现
- 指令处理：`AIBCommand` 通过反射注册命令，提供 `start/list/build/reload`
- 会话管理：`SessionManager` 跟踪玩家状态与需求，并异步请求平台 API
- AI 平台：
  - OpenRouter：`https://openrouter.ai/api/v1/chat/completions`
  - SiliconFlow：`https://api.siliconflow.cn/v1/chat/completions`
- 结果解析：Gson 提取 `choices[0].message.content`
- 方块构建：`BuildingService`
  - 单点与范围两种语法
  - `Bukkit.createBlockData(String)` 解析 BlockState 字符串
  - 使用 `LocalSession.createEditSession(wePlayer)` 绑定玩家会话
  - `localSession.remember(edit)` 记录到历史，保障 `//undo` / `//redo`
- 兼容降级：PALE_OAK 系列自动降级至 OAK 系列，避免未来材质导致构建失败

## 快速示例
```text
1;0;1;minecraft:stone_brick_stairs[facing=north,half=bottom,shape=straight,waterlogged=false]
0;0;0;10;5;0;minecraft:stone_bricks
```

## 安全提醒
- 请勿将 API Key 写入版本库或公开分享
- 服务器端仅保存必要请求与生成结果文件，建议启用访问控制与日志审计

## 研发规范与建议
- 构建：`gradle build`（KTS），避免 ShadowJar
- 依赖（compileOnly）：`paper-api`、`worldedit-bukkit`、`worldedit-core`、`gson`
- 版本：Java 8 / Paper 1.16.5 / WorldEdit 7.2.0

## 违规建筑识别理论 (AI Content Moderation)
针对 Minecraft 建筑可能出现的违规结构（如淫秽色情造型、仇恨符号等），本插件规划引入“多模态三级风控体系”。由于建筑是 3D 体素结构，单纯的关键词过滤无法识别“形状上的违规”，因此需要引入视觉识别与几何分析。

### 1. 核心挑战
- **隐晦性**：用户可能输入正常指令（如“两个球体中间加一个柱子”），但组合后形成违规形状。
- **体素化**：Minecraft 建筑由方块组成，需要从离散坐标中提取语义特征。

### 2. 识别算法架构

#### 第一道防线：提示词审计 (Textual Audit)
- **机制**：在发送给生成式 AI 之前，对用户的自然语言需求进行意图识别。
- **逻辑**：
  1. 检测敏感词（Regex/Trie树）。
  2. 使用小参数模型（如 Llama-Guard）判断 Prompt 是否包含暗示性违规内容。
- **动作**：若违规，直接拒绝请求，不消耗昂贵的生成模型 Token。

#### 第二道防线：几何特征启发式扫描 (Geometric Heuristics)
- **机制**：对生成的坐标数据（`List<String>`）进行数学特征分析。
- **算法示例**：
  - **高度/宽度比异常检测**：检测孤立的细长柱状结构。
  - **球体/柱体组合检测**：检测特定半径的球体与柱体的邻接关系（如底部双球+中间柱体结构）。
  - **连通域分析 (Connected Components)**：分析建筑的拓扑结构，提取骨架 (Skeletonization)。

#### 第三道防线：多视图视觉识别 (Multi-view Vision Recognition) —— *最核心方案*
- **原理**：利用大模型强大的视觉识别能力（VLM），将 3D 建筑“拍”成 2D 照片进行审核。
- **流程**：
  1. **虚拟渲染 (Virtual Rendering)**：
     - 不在游戏中实际生成，而是在内存中构建 3D 矩阵。
     - 将坐标点映射为二值化图像（黑白剪影）。
     - 生成 **正视图、侧视图、俯视图** 等 3-5 张 2D 截面图或深度图。
  2. **视觉模型推断 (VLM Inference)**：
     - 调用支持视觉的 API（如 GPT-4o, Claude 3.5 Sonnet, Gemini Pro Vision）。
     - **Prompt 示例**：
       > "Analyze these 2D projections of a 3D voxel structure. Does this shape structurally resemble human genitalia, hate symbols (like swastikas), or other offensive imagery? Answer with probability."
  3. **决策**：
     - 安全分 > 0.9：自动建造。
     - 疑虑分 > 0.5：进入人工审核队列（Admin Review）。
     - 违规分 > 0.8：直接拦截并警告玩家。

### 3. 响应机制
- **拦截 (Block)**：构建前直接终止，并向玩家显示“建筑结构违规”。
- **撤回 (Auto-Undo)**：若构建后被异步检测出违规，自动执行 `//undo` 并清除历史。
- **审计 (Log)**：记录违规玩家 ID、Prompt 及生成的建筑指纹。

### 4. 扩展：手动建造实时监控 (Manual Build Watchdog)
针对玩家手动搭建（而非 AI 生成）的违规建筑，系统提供可配置的**实时监控开关**。

- **配置开关**：`config.yml` -> `watchdog.enable_manual_check: true`
- **核心逻辑**：
  1. **事件驱动与防抖 (Event Debounce)**：
     - 监听 `BlockPlaceEvent`，但不实时计算（避免卡顿）。
     - 维护一个“活跃区块列表”，当玩家在某区域连续放置方块停止后（如静止 5秒），触发一次局部扫描。
  2. **3D 卷积模式匹配 (3D Convolutional Pattern Matching)**：
     - 针对特定的隐晦违规结构（如用户定义的“空气-方块”交替阵列），使用 3x3x3 的卷积核进行快速扫描。
     - **示例模式识别**：
       ```text
       层3: 空气 方块 空气
       层2: 空气 方块 空气
       层1: 方块 空气 方块
       ```
     - 这种结构将被定义为 `Pattern_Phallic_Abstract`，一旦匹配度超过阈值即标记为可疑。
  3. **复用视觉管线**：
     - 将手动搭建的可疑区域（ROI）提取出来，同样通过“虚拟渲染 -> VLM 视觉识别”流程进行二次确认。

## 路线图（Roadmap）
- 自定义 Operation 封装整栋建筑的变更单元，增强撤销一致性
- 扩展语法：空心填充、掩码（mask）、边框模式、条件放置
- 多模型支持与提示词模板库（Prompt Library）
- 可视化预览与进度反馈

## 致谢
- 感谢 WorldEdit 团队提供强大的编辑能力
- 感谢 OpenRouter / SiliconFlow 提供稳定的 LLM 基础设施