# AI Builder 用户手册

> 版本 1.3.0 | Minecraft 1.20.4 | Fabric Mod

---

## 目录

1. 安装与环境要求
2. 首次配置
3. 快捷键一览
4. 命令一览
5. 功能详解
6. 配置项说明
7. 蓝图格式规范
8. 文件目录结构
9. 常见问题与注意事项

---

## 安装与环境要求

| 项目 | 要求 |
|------|------|
| Minecraft 版本 | 1.20.4 |
| Mod 加载器 | Fabric Loader >= 0.15.0 |
| Java 版本 | >= 17 |
| 前置 Mod | Fabric API（必须） |

安装步骤：

1. 安装 Fabric Loader（>= 0.15.0）
2. 安装 Fabric API
3. 将 ai-builder-1.3.0.jar 放入 .minecraft/mods/ 目录
4. 启动游戏

---

## 首次配置

首次启动后，Mod 会在 ai-helper/config/ai-builder.properties 自动生成默认配置文件。
你必须配置 AI API 密钥才能使用 AI 功能。

快速配置方法（二选一）：

- 方法一：游戏内命令
  /aiconfig api_key 你的API密钥
  /aiconfig api_base_url 你的API地址
  /aiconfig model 你的模型名称

- 方法二：按 K 键 -> 进入"AI 聊天设置"页面进行可视化配置

> 本 Mod 支持任何 OpenAI 兼容的 API 接口（如 OpenAI、Kimi、DeepSeek 等）。

---

## 快捷键一览

| 按键 | 功能 | 生效场景 |
|------|------|----------|
| K | 打开 Mod 设置主菜单 | 游戏中 |
| Enter | 发送消息 | AI 聊天界面 |
| Escape | 关闭当前界面 | 所有 Mod 界面 |
| Page Up / Page Down | 滚动聊天记录 | AI 聊天界面 |
| 鼠标滚轮 | 滚动列表/聊天 | 所有可滚动界面 |
| 上/下 方向键 | 导航文件列表 | NBT/TXT 浏览器 |
| Backspace | 返回上级目录 | NBT/TXT 浏览器 |
| Delete | 删除选中文件 | NBT/TXT 浏览器 |
| Enter | 放置结构/进入文件夹 | NBT/TXT 浏览器 |

---

## 命令一览

### AI 核心命令

| 命令 | 说明 |
|------|------|
| /ai <消息> | 与 AI 对话，AI 可自动执行建造等操作 |
| /ai build <蓝图名> | 在脚下位置建造指定蓝图 |
| /ai blueprints | 列出所有已加载的蓝图 |
| /ai reload_blueprints | 重新从磁盘加载蓝图文件 |
| /ainew | 清空对话历史，开始新对话 |
| /aistop | 终止当前正在进行的 AI 回复 |

### 配置命令

| 命令 | 说明 |
|------|------|
| /aiconfig show | 显示当前配置 |
| /aiconfig api_base_url <值> | 设置 API 地址 |
| /aiconfig api_key <值> | 设置 API 密钥 |
| /aiconfig model <值> | 设置 AI 模型名称 |
| /aiconfig web_search <on/off> | 开启/关闭联网搜索 |
| /aiconfig tavily_api_key <值> | 设置 Tavily 搜索密钥 |
| /aiconfig reload | 重新加载配置文件 |

### 工具命令

| 命令 | 说明 |
|------|------|
| /aipos | 显示当前玩家坐标和所在维度 |
| /ailog [on/off] | 开启/关闭日志转发到聊天框 |
| /ailog level <error/warn/info/debug> | 设置日志最低显示级别 |
| /aitest | 生成测试日志，验证日志系统 |

### NBT 结构命令

| 命令 | 说明 |
|------|------|
| /ainbt | 打开 NBT 结构浏览器（GUI） |
| /ainbt list | 列出 nbts/ 目录下所有 .nbt 文件 |
| /ainbt info <文件名> | 查看指定 NBT 文件的详细信息 |
| /ainbt all | 查看所有 NBT 文件的摘要 |
| /ainbt place <文件名> | 在玩家脚下位置放置 NBT 结构 |

---

## 功能详解

### AI 聊天

使用方式：
- 命令行：/ai 帮我建一栋木屋
- 聊天界面：按 K -> 点击"AI 聊天"

AI 聊天界面功能：
- 多轮对话记忆（最多保留 20 条消息 / 10 轮对话）
- 实时流式输出（可在设置中开启）
- 引用 TXT 蓝图文件作为上下文（点击"引用"按钮选择文件）
- 可随时点击"终止思考"取消正在进行的 AI 请求
- 支持截图发送（AI 可分析游戏画面）
- 终止命令：使用 /aistop 可在命令行终止 AI 生成

注意事项：
- 对话历史会在游戏运行期间保持，使用 /ainew 或聊天界面的清除按钮可重置
- 输入框最大长度 1024 字符
- 流式输出模式下，AI 回复会逐步显示，减少等待感

---

### AI 建造

AI 可以通过自然语言指令执行以下操作：

| 操作 | 示例 |
|------|------|
| 放置方块 | "在我前方放一个石砖" |
| 批量填充 | "用橡木板填充一个 5x3x5 的区域" |
| 清除区域 | "清除我前方 10 格内的所有方块" |
| 给予物品 | "给我 64 个钻石" |
| 设置时间 | "把时间设为白天" |
| 设置天气 | "让天气放晴" |
| 传送 | "把我传送到 100 64 200" |
| 生成实体 | "在我面前生成一只猪" |
| 执行命令 | AI 可执行原版 Minecraft 命令 |
| 建造蓝图 | "帮我建一栋小木屋"（AI 生成蓝图并自动放置） |

坐标系统：
- AI 使用相对坐标：forward（前方）、right（右方）、up（上方），基于玩家朝向
- 也支持绝对坐标：直接指定 x/y/z 世界坐标
- 蓝图坐标：X=东、Y=上、Z=南，原点为玩家脚下

限制：
- 单次填充最多 10,000 个方块
- 单次生成最多 20 个实体
- 给予物品每组最多 64 个

---

### NBT 结构管理

打开方式：
- 命令：/ainbt
- 按 K -> 点击"加载结构 (NBT)"

功能：
- 浏览 nbts/ 目录下的所有 .nbt 文件（支持子文件夹）
- 搜索/过滤文件名
- 查看文件详情（大小、方块数量、方块种类、数据版本）
- 双击文件名或点击"放置"按钮在玩家脚下放置结构
- 删除文件（需二次确认）
- 打开系统文件管理器查看文件

命令行方式：
- /ainbt list - 列出所有文件
- /ainbt info <文件名> - 查看详情
- /ainbt place <文件名> - 放置结构
- 文件名支持空格代替路径分隔符（如 "ancient_city barracks"）

放置规则：
- 结构以玩家脚下位置为原点放置
- 自动跳过空气和结构空位方块
- 完整保留方块实体数据（箱子内容物、告示牌文字等）
- 告示牌自动兼容 1.20+ 格式

注意事项：
- 放置大型结构可能需要一定时间
- 确保放置区域有足够空间
- NBT 文件必须是 Minecraft 标准结构格式

---

### TXT 蓝图管理

打开方式：
- 按 K -> 点击"加载结构 (TXT)"

功能：
- 浏览 txts/ 目录下的所有 .txt 蓝图文件
- 搜索/过滤文件名
- 双击或点击"放置"按钮在玩家脚下建造
- AI 生成的蓝图会自动保存到 txts/ai-generated/ 目录

放置规则：
- 以玩家脚下为原点
- V2 格式：X 方向=东，Y 方向=上，Z 方向=南
- V1 格式：行方向=Z+（南），列方向=X+（东）
- 附着方块（按钮、火把等）会自动推断朝向
- 床会自动生成头部方块

---

### 选区工具

打开方式：
- 按 K -> 点击"选区工具"

使用流程：

1. 设置选区坐标
   - 手动输入两个对角坐标（X Y Z）
   - 或点击"坐标1=当前位置"/"坐标2=当前位置"快速设置

2. 确认选区
   - 点击"确认选区"按钮
   - 确认后，游戏中会显示蓝色半透明高亮框标记选区范围

3. 分析/导出
   - 点击"分析/导出选区"进入导出界面
   - 可查看选区内方块统计（种类、数量）
   - 导出为 V2 蓝图文本
   - 导出为 .nbt 文件（保留方块实体数据）
   - 导出为 .txt 文件（保留容器内容物）

导出格式：
- NBT 导出：生成标准 Minecraft 结构文件，保留箱子内容物、告示牌文字等
- TXT 导出：生成 MCBLUEPRINT v2 格式文本，包含容器内容物信息
- 蓝图导出：生成 MCBLUEPRINT v2 格式文本，包含所有方块状态属性

注意事项：
- 选区坐标在关闭界面时会自动保存为草稿
- 清除选区会同时移除高亮渲染
- NBT 和 TXT 导出在服务端执行，可完整读取方块实体数据

---

### 联网搜索与网页抓取

前提条件：
- 在配置中设置 tavily_api_key（Tavily API 密钥）
- 开启 web_search_enabled

使用方式：
- 直接对 AI 说"搜索一下如何建造哥特式教堂"
- AI 会自动判断是否需要联网搜索
- 搜索结果会作为上下文提供给 AI，AI 据此生成回答或建造指令

网页抓取：
- AI 可以抓取指定 URL 的网页内容
- 例如："帮我看看这个网页的内容 https://..."

注意事项：
- 搜索返回前 5 条结果
- 搜索超时时间为 120 秒
- 需要有效的 Tavily API 密钥

---

### 截图分析

前提条件：
- 在设置中开启"截图功能"（screenshot_enabled）

使用方式：
- 在 AI 聊天界面发送消息时，Mod 会自动截取当前游戏画面
- AI 可以分析画面内容并据此回答问题

注意事项：
- 截图会自动缩放至最大宽度 512px
- 截图有 2 tick 延迟以确保画面干净（关闭聊天界面后截取）
- 截图临时保存在 ai-helper/screenshots/ai_temp.png
- 可在设置中随时关闭此功能

---

## 配置项说明

配置文件位置：ai-helper/config/ai-builder.properties

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| api_base_url | 字符串 | https://api.kimi.com/coding/v1/messages | AI API 端点（OpenAI 兼容） |
| api_key | 字符串 | your-api-key-here | API 认证密钥（必须手动设置） |
| model | 字符串 | kimi-for-coding | AI 模型名称 |
| screenshot_enabled | 布尔 | true | 是否启用截图功能 |
| context_enabled | 布尔 | true | 是否启用多轮对话记忆 |
| web_search_enabled | 布尔 | true | 是否启用联网搜索 |
| tavily_api_key | 字符串 | （空） | Tavily 搜索 API 密钥 |
| stream_output_enabled | 布尔 | false | 是否启用流式输出 |
| language | 字符串 | en_us | Mod 界面语言（zh_cn 或 en_us） |

修改方式：
- 游戏内命令：/aiconfig <键> <值>
- 按 K -> AI 聊天设置（可视化开关）
- 直接编辑配置文件（可使用 /aiconfig reload 重新加载，无需重启）

---

## 蓝图格式规范

### V2 格式（推荐）

```
# MCBLUEPRINT v2
# name: 我的建筑
# size: 5x3x5
# origin: 0,0,0
# 坐标原点在结构西北角最低层，x向东，y向上，z向南

## BLOCKS
0,0,0   oak_planks
1,0,0   oak_stairs   facing=north   half=bottom
2,0,0   oak_door   facing=south   half=lower   hinge=left   open=false
0,1,0   glass_pane
3,0,2   oak_log   axis=y
```

格式说明：
- 首行必须为 "# MCBLUEPRINT v2"
- # name: 指定蓝图名称
- # size: 指定尺寸（可选，仅供参考）
- # origin: 指定原点位置（可选）
- 方块行格式：x,y,z   方块ID   [属性=值 ...]
- 坐标为相对坐标（原点为 0,0,0）
- 支持所有原版方块状态属性
- # 开头的行为注释

### V1 格式（旧版兼容）

```
{{layered blueprint|name=小木屋
|A=Oak Planks
|B=Oak Stairs-rot90
|C=Oak Door
|----第1层|
AAAA
ABBA
AAAA
|----第2层|
A  A

A  A
}}
```

格式说明：
- 以 {{layered blueprint|name=名称 开头
- |字符=方块名称 定义图例
- 支持旋转：-rot0、-rot90、-rot180、-rot270
- 支持属性：+bottom、+top、+head、+foot
- |----第N层| 分隔不同高度层
- 空格表示空气

---

## 文件目录结构

```
.minecraft/
|- ai-helper/                    <- Mod 数据根目录
|  |- config/
|  |  |- ai-builder.properties   <- 配置文件
|  |- nbts/                      <- NBT 结构文件目录
|  |  |- my_house.nbt
|  |  |- ancient_city/
|  |  |  |- city_center/
|  |  |  |- structures/
|  |  |- bastion/
|  |- txts/                      <- TXT 蓝图文件目录
|  |  |- small_house.txt
|  |  |- ai-generated/           <- AI 自动生成的蓝图
|  |- screenshots/               <- AI 截图临时文件
|     |- ai_temp.png
|     |- ai_chat_temp.png
|- mods/
   |- ai-builder-1.3.0.jar
```

- ai-helper/：Mod 的数据根目录，与 mods/、config/ 同级
- ai-helper/config/：配置文件目录
- ai-helper/nbts/：存放 .nbt 结构文件，支持子文件夹分类
- ai-helper/txts/：存放 .txt 蓝图文件，AI 生成的蓝图保存在 ai-generated/ 子目录
- ai-helper/screenshots/：AI 截图临时文件
- 所有目录均支持任意深度的子文件夹

---

## 常见问题与注意事项

### Q: AI 没有回复 / 报错
- 检查 API 密钥是否正确配置：/aiconfig show
- 确认 API 地址可访问
- 使用 /ailog on 查看详细日志
- 使用 /aitest 验证日志系统是否正常

### Q: 如何终止 AI 回复
- 聊天界面中：点击"终止思考"按钮
- 命令行：输入 /aistop

### Q: 联网搜索不工作
- 确认已设置 tavily_api_key
- 确认 web_search_enabled 为 true（可通过 /aiconfig web_search on 开启）
- 检查网络连接

### Q: 蓝图放置位置不对
- 蓝图以玩家脚下位置为原点
- V2 格式：X=东、Y=上、Z=南
- V1 格式：行=南、列=东
- 建议在空旷平地上放置

### Q: NBT 结构放置后方块缺失
- 确认 NBT 文件版本与当前 Minecraft 版本兼容
- 部分旧版方块 ID 可能已更改
- 结构空位（structure_void）会被自动跳过

### Q: AI 输出被截断
- AI 模型有 token 上限，大型蓝图可能被截断
- Mod 会自动尝试解析已有部分并放置
- 可以让 AI "继续生成剩余部分"

### Q: 如何切换语言
- 按 K -> "Mod 语言设置"
- 或修改配置：/aiconfig language en_us（英文）/ /aiconfig language zh_cn（中文）

### Q: 流式输出和普通输出的区别
- 流式输出：AI 回复逐字显示，减少等待感，适合长回复
- 普通输出：等待 AI 完整回复后一次性显示
- 通过设置开关：/aiconfig stream_output_enabled true

### Q: 修改配置后需要重启吗
- 命令行修改（/aiconfig）立即生效
- 手动编辑配置文件后，使用 /aiconfig reload 即可加载，无需重启

### 安全注意事项
- API 密钥存储在本地配置文件中，请勿分享配置文件
- AI 执行的操作（放置方块、填充等）不可撤销，建议在重要建筑附近操作前备份存档
- 联网搜索和网页抓取会向外部服务器发送请求，请注意隐私

### 性能建议
- 避免一次性填充超大区域（>10,000 方块）
- 大型 NBT 结构放置可能造成短暂卡顿
- 流式输出模式在网络延迟较高时体验更好

---

## 许可证

MIT License

作者：liuzeen1234
源码：https://github.com/liuzeen1234/minecraft-AI-helper
