# AI Builder 用户手册

> 版本 1.4.1 | Minecraft 1.20.4 | Fabric Mod

## 安装与环境要求

需要 Minecraft 1.20.4、Fabric Loader 0.15.0 或更高版本、Java 17 或更高版本，以及 Fabric API。安装依赖后，将 `ai-builder-1.4.1.jar` 放入 `.minecraft/mods/`，启动游戏并按 `K`。

## 首次配置

首次启动会创建 `ai-helper/config/ai-builder.properties`。使用 AI 前必须设置 API 密钥：

```text
/aiconfig api_base_url 你的 API 地址
/aiconfig api_key 你的 API 密钥
/aiconfig model 你的模型名称
```

也可按 `K` → **AI 聊天设置**。Mod 支持 OpenAI 兼容接口和 Anthropic Messages 接口。`api_format=auto` 会根据地址自动选择格式；需要时直接编辑配置文件为 `openai` 或 `anthropic`，再执行 `/aiconfig reload`。

## 快捷键

| 按键 | 功能 |
|---|---|
| `K`（默认、可重绑） | 打开 AI Builder 设置菜单 |
| `Enter` | 在 AI 聊天界面发送消息；在结构浏览器放置结构或进入文件夹 |
| `Escape` | 关闭当前 Mod 界面 |
| `Page Up` / `Page Down`、鼠标滚轮 | 滚动聊天或文件列表 |
| 上/下方向键、`Backspace`、`Delete` | 在统一结构浏览器导航、返回上级或删除选中文件 |

可在「选项 → 控制 → 按键绑定」的 **AI Builder** 分类中重绑 `K`。其他按键为界面内固定操作。

## 命令

### AI 与工具命令

| 命令 | 说明 |
|---|---|
| `/ai <消息>` | 与 AI 对话；AI 可执行受支持的建造操作 |
| `/ai blueprints` | 列出已加载的 TXT 蓝图 |
| `/ai reload_blueprints` | 从磁盘重载 TXT 蓝图 |
| `/ai test_stairs` | 放置楼梯朝向调试样例 |
| `/ainew` | 清空对话历史 |
| `/aistop` | 终止当前 AI 请求 |
| `/aipos` | 显示当前坐标和维度 |

### 配置命令

| 命令 | 说明 |
|---|---|
| `/aiconfig show` | 显示 API、模型、联网搜索与 Tavily 配置 |
| `/aiconfig api_base_url <值>` | 设置 API 地址 |
| `/aiconfig api_key <值>` | 设置 API 密钥 |
| `/aiconfig model <值>` | 设置模型 |
| `/aiconfig web_search <on/off>` | 开启或关闭联网搜索 |
| `/aiconfig tavily_api_key <值>` | 设置 Tavily API 密钥 |
| `/aiconfig reload` | 重载手动编辑后的配置文件 |

`/aiconfig` 不是通用键值命令。截图、上下文、流式输出和语言请在设置界面调整；`api_format` 请直接编辑配置文件后重载。

### 结构命令

| 命令 | 说明 |
|---|---|
| `/ainbt list` | 列出 NBT 和 Litematica 结构 |
| `/ainbt info <文件名>` | 显示 NBT 或 Litematica 结构详情 |
| `/ainbt all` | 显示全部结构摘要 |
| `/ainbt place <文件名>` | 在玩家脚下放置 NBT 或 Litematica 结构 |

`/ainbt` 没有无参数 GUI；图形化浏览器请使用 `K` → **加载结构**。

> 聊天框日志转发和“生成测试日志”由可选的 debug-menu 模组提供，不属于 AI Builder 命令。

## 功能详解

### AI 聊天与建造

按 `K` → **AI 聊天**，或输入 `/ai <消息>`。聊天界面支持最多 20 条消息（10 轮）上下文、1024 字符输入、TXT 蓝图引用、取消请求和增量流式显示。截图功能默认关闭。

AI 可放置、填充或清除方块，给予物品，生成实体，设置时间/天气，传送和生成/放置蓝图。填充或清除单次最多 10,000 方块，给予最多 64 件物品，生成最多 20 个实体。`execute_command` 以权限等级 2 运行，但服务器管理、封禁、踢人和停止/保存等危险根命令会被拒绝；AI 不能执行任意原版命令。

蓝图坐标为相对坐标：X 向东、Y 向上、Z 向南，原点在玩家脚下。支持 V1 和 MCBLUEPRINT v2 TXT 蓝图。

### 统一结构浏览器

`K` 菜单中的 **加载结构** 支持浏览、搜索、删除和放置以下文件，且支持子文件夹：

- `ai-helper/structures/nbts/` 中的 `.nbt`；
- `ai-helper/structures/litematic/` 中的 `.litematic`；
- `ai-helper/structures/txts/` 中的 V1/V2 `.txt` 蓝图。

NBT/Litematica 放置会跳过 `air` 和 `structure_void`，保留方块状态、方块实体数据和结构实体，并转换旧格式告示牌数据。AI 生成的 TXT 蓝图保存到 `ai-helper/structures/txts/ai-generated/`。

### 选区工具

在 `K` 菜单中打开 **选区工具**。设置两个对角坐标（或使用当前位置）并确认后会显示高亮框；关闭界面时选区草稿会保留。分析/导出界面可统计方块并在服务端导出：

- **TXT / MCBLUEPRINT v2**：始终导出容器物品和非空告示牌正反面文字；
- **NBT**：保留方块实体数据；
- **Litematica**：保留方块实体数据，并可选择是否包含实体。

### 联网搜索、网页抓取与截图

联网搜索要求 `web_search_enabled=true` 并设置 `tavily_api_key`。AI 请求搜索时最多获取 5 条 Tavily 结果，超时为 120 秒。网页抓取超时为 30 秒，返回的纯文本最多保留 8,000 字符。

开启 `screenshot_enabled` 后，聊天界面会关闭 2 tick 再截图，图片最大宽度为 512 px，临时保存为 `ai-helper/screenshots/ai_chat_temp.png`；`/ai` 使用 `ai_temp.png`。

## 配置项

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

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `api_base_url` | `https://api.kimi.com/coding/v1/messages` | API 端点 |
| `api_key` | `your-api-key-here` | API 密钥，必须设置 |
| `model` | `kimi-for-coding` | 模型名称 |
| `screenshot_enabled` | `false` | 是否从 AI 聊天发送游戏截图 |
| `context_enabled` | `true` | 是否启用多轮上下文 |
| `web_search_enabled` | `true` | 是否允许 Tavily 联网搜索 |
| `tavily_api_key` | 空 | Tavily API 密钥 |
| `stream_output_enabled` | `true` | 是否增量显示 AI 回复 |
| `language` | `en_us` | `zh_cn` 或 `en_us` |
| `api_format` | `auto` | `auto`、`openai` 或 `anthropic` |

**AI 聊天设置**可修改四个布尔开关；API 设置页面可修改地址、密钥、模型和 Tavily 密钥。手动编辑后执行 `/aiconfig reload`。语言请通过 `K` → **Mod 语言设置**切换；下次客户端启动会重新跟随当前 Minecraft 游戏语言。

## 蓝图格式

```text
# MCBLUEPRINT v2
# name: example
# size: 5x6x5
# origin: 0,0,0
# 坐标原点在结构西北角最低层，x向东，y向上，z向南
# 格式：x,y,z  block_id  [key=value ...]

## BLOCKS

# --- 第 1 层 (y=0) ---
2,0,2   oak_log   axis=y
3,0,2   short_grass
0,0,3   short_grass
2,0,4   short_grass
4,0,4   short_grass

# --- 第 2 层 (y=1) ---
2,1,2   oak_log   axis=y

# --- 第 3 层 (y=2) ---
0,2,0   oak_leaves   distance=4   persistent=false   waterlogged=false
1,2,0   oak_leaves   distance=3   persistent=false   waterlogged=false
2,2,0   oak_leaves   distance=2   persistent=false   waterlogged=false
3,2,0   oak_leaves   distance=3   persistent=false   waterlogged=false
0,2,1   oak_leaves   distance=3   persistent=false   waterlogged=false
1,2,1   oak_leaves   distance=2   persistent=false   waterlogged=false
2,2,1   oak_leaves   distance=1   persistent=false   waterlogged=false
3,2,1   oak_leaves   distance=2   persistent=false   waterlogged=false
4,2,1   oak_leaves   distance=3   persistent=false   waterlogged=false
0,2,2   oak_leaves   distance=2   persistent=false   waterlogged=false
1,2,2   oak_leaves   distance=1   persistent=false   waterlogged=false
2,2,2   oak_log   axis=y
3,2,2   oak_leaves   distance=1   persistent=false   waterlogged=false
4,2,2   oak_leaves   distance=2   persistent=false   waterlogged=false
0,2,3   oak_leaves   distance=3   persistent=false   waterlogged=false
1,2,3   oak_leaves   distance=2   persistent=false   waterlogged=false
2,2,3   oak_leaves   distance=1   persistent=false   waterlogged=false
3,2,3   oak_leaves   distance=2   persistent=false   waterlogged=false
4,2,3   oak_leaves   distance=3   persistent=false   waterlogged=false
1,2,4   oak_leaves   distance=3   persistent=false   waterlogged=false
2,2,4   oak_leaves   distance=2   persistent=false   waterlogged=false
3,2,4   oak_leaves   distance=3   persistent=false   waterlogged=false
4,2,4   oak_leaves   distance=4   persistent=false   waterlogged=false

# --- 第 4 层 (y=3) ---
1,3,0   oak_leaves   distance=3   persistent=false   waterlogged=false
2,3,0   oak_leaves   distance=2   persistent=false   waterlogged=false
3,3,0   oak_leaves   distance=3   persistent=false   waterlogged=false
0,3,1   oak_leaves   distance=3   persistent=false   waterlogged=false
1,3,1   oak_leaves   distance=2   persistent=false   waterlogged=false
2,3,1   oak_leaves   distance=1   persistent=false   waterlogged=false
3,3,1   oak_leaves   distance=2   persistent=false   waterlogged=false
4,3,1   oak_leaves   distance=3   persistent=false   waterlogged=false
0,3,2   oak_leaves   distance=2   persistent=false   waterlogged=false
1,3,2   oak_leaves   distance=1   persistent=false   waterlogged=false
2,3,2   oak_log   axis=y
3,3,2   oak_leaves   distance=1   persistent=false   waterlogged=false
4,3,2   oak_leaves   distance=2   persistent=false   waterlogged=false
0,3,3   oak_leaves   distance=3   persistent=false   waterlogged=false
1,3,3   oak_leaves   distance=2   persistent=false   waterlogged=false
2,3,3   oak_leaves   distance=1   persistent=false   waterlogged=false
3,3,3   oak_leaves   distance=2   persistent=false   waterlogged=false
4,3,3   oak_leaves   distance=3   persistent=false   waterlogged=false
0,3,4   oak_leaves   distance=4   persistent=false   waterlogged=false
1,3,4   oak_leaves   distance=3   persistent=false   waterlogged=false
2,3,4   oak_leaves   distance=2   persistent=false   waterlogged=false
3,3,4   oak_leaves   distance=3   persistent=false   waterlogged=false

# --- 第 5 层 (y=4) ---
2,4,1   oak_leaves   distance=1   persistent=false   waterlogged=false
1,4,2   oak_leaves   distance=1   persistent=false   waterlogged=false
2,4,2   oak_log   axis=y
3,4,2   oak_leaves   distance=1   persistent=false   waterlogged=false
2,4,3   oak_leaves   distance=1   persistent=false   waterlogged=false

# --- 第 6 层 (y=5) ---
2,5,1   oak_leaves   distance=2   persistent=false   waterlogged=false
1,5,2   oak_leaves   distance=2   persistent=false   waterlogged=false
2,5,2   oak_leaves   distance=1   persistent=false   waterlogged=false
3,5,2   oak_leaves   distance=2   persistent=false   waterlogged=false
2,5,3   oak_leaves   distance=2   persistent=false   waterlogged=false
```

V2 方块行格式为 `x,y,z   方块ID   [属性=值 ...]`。`# name:`、`# size:`、`# origin:` 为可选元数据；`#` 开头为注释。旧版 V1 字符网格蓝图仍兼容：行向南、列向东，空格表示空气。

## 文件目录

```text
.minecraft/
├── ai-helper/
│   ├── config/ai-builder.properties
│   ├── structures/
│   │   ├── nbts/
│   │   ├── litematic/
│   │   └── txts/
│   │       └── ai-generated/
│   └── screenshots/
│       ├── ai_temp.png
│       └── ai_chat_temp.png
└── mods/ai-builder-1.4.1.jar
```

所有结构目录均支持任意深度的子文件夹。

## 常见问题与注意事项

**AI 没有回复：** 使用 `/aiconfig show` 检查密钥和地址，并确认网络可用。可选 debug-menu 可提供聊天日志帮助排查。

**如何切换语言或流式输出：** 分别使用 `K` → **Mod 语言设置**和 `K` → **AI 聊天设置**；没有 `/aiconfig language` 或 `/aiconfig stream_output_enabled` 命令。

**手动修改配置后：** 执行 `/aiconfig reload`，无需重启。

**安全与性能：** API 密钥保存在本地。AI 操作不可撤销，请备份重要存档。搜索和抓取会请求外部服务；大型结构放置可能造成短暂卡顿。

## 许可证

MIT License

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