# MC 指令生成器 · 给 AI 的接口说明

> 这份文档可以直接喂给对话式 AI。
> **核心用法就一句话：访问带参数的网址，服务器当场把命令生成好返回。**
> 你不用自己拼命令、也不会瞎编参数。

## 0. 为什么要这样

- 命令的语法、方块名、NBT 位置**随版本变**，凭记忆写必错（本文档最后列了几个真实错例）。
- 而且**输入有预算**：Minecraft 那边输入上限 255 字符，一条命令带参数就塞不下了。
- 所以：**输入切成小段分多次给，输出一次给全**。

## 1. 三个最常用的接口

```
① 找命令 id
   https://ccfxfcf.cn/api/search?q=传送

② 看这条命令的参数（参数名一个字都不能自己造）
   https://ccfxfcf.cn/api/command?id=tp

③ 生成（参数直接写在网址上）
   https://ccfxfcf.cn/api/build?id=tp&target=@a&pos=0 64 0
```

返回的是 JSON，`command` 字段就是**完整**的命令：

```json
{ "ok": true, "id": "tp", "version": "1.20.1",
  "command": "tp @a 0 64 0", "length": 12 }
```

**记住两条**：

- 参数名**只能**用 `/api/command?id=…` 里列出的 `key`。
- 版本用 `&version=1.20.1` 指定（不写默认 1.20.1）；1.13+ 的方块 NBT 会自动贴着方块名。

## 2. ★ 长参数怎么办：草稿（draft）

单次调用的网址建议控制在 **255 字符以内**（Minecraft 输入上限就是 255）。
可是有些**参数值本身就很长** —— 一大段 tellraw 文字组件、一整个箱子的 `Items`、
几百行的命令列表、一大张三维网格。

**做法：把那个值切成小块喂进草稿，再让参数引用草稿。**

```
① 开草稿
   https://ccfxfcf.cn/api/draft/new
   → { "draft": "6bd8cd97", "expiresIn": 600, ... }

② 一块一块喂这个值（每次不超过 255 字符；要换行就加 &nl=1）
   https://ccfxfcf.cn/api/draft/append?draft=6bd8cd97&text=<第一块>
   https://ccfxfcf.cn/api/draft/append?draft=6bd8cd97&text=<第二块>
   …
   → { "ok": true, "added": 87, "length": 512, "tail": "…" }   ← length 是攒到现在的总长

③ 让参数引用它 —— 两种写法
   写法A：参数名后面加 _draft
     https://ccfxfcf.cn/api/build?id=tellraw&target=@a&msg_draft=6bd8cd97
   写法B：值里内联占位符
     https://ccfxfcf.cn/api/build?id=tellraw&target=@a&msg=前缀{{draft:6bd8cd97}}后缀
```

返回里会明确告诉你哪个参数是草稿拼出来的：

```json
{ "ok": true, "command": "tellraw @a [{…很长…}]",
  "usedDrafts": [ { "param": "msg", "draft": "6bd8cd97", "length": 512 } ] }
```

**`_draft` 也能用在别的地方**：

| 场景 | 怎么写 |
|---|---|
| 长命令列表 → 一键命令 | `/api/ooc?cmds_draft=<草稿号>&layout=column&types=[…]` |
| 大网格 JSON → 三维一键命令 | `/api/ooc3d?grid_draft=<草稿号>&clearMech=1` |
| 往草稿里攒**整条命令**（而不是值片段） | `/api/draft/add?draft=…&id=say&msg=你好` |
| 攒自己拼好的原文 | `/api/draft/addraw?draft=…&command=<原文>` |

**草稿规则**：

| | |
|---|---|
| 有效期 | **10 分钟没人用就失效**（每次调用都会续期，所以在用就不会掉） |
| 上限 | 一个草稿最多 500 条命令 / 40 万字符的值 |
| 看内容 | `/api/draft/get?draft=…` —— `buf` 是攒的长参数值，`text` 是攒的命令 |
| 短网址 | `https://ccfxfcf.cn/api/get/6bd8cd97` |
| 随时删 | `/api/draft/del?draft=…` |

> 记住：**草稿是给「长参数」准备的** —— 为了把一条命令生成出来。
> 结果永远给全，不会被藏进草稿。

## 3. 全部接口

| 接口 | 干什么 |
|---|---|
| `GET /api/info` | 入口：端点列表 + 规则（`/api/` 是给人看的网页） |
| `GET /api/versions` | 支持的 22 个版本 |
| `GET /api/search?q=传送&limit=15` | 按关键词找命令 id（id / 名字 / 关键词 / 分类都搜） |
| `GET /api/command?id=tp` | 这条命令的**全部参数**：参数名、类型、默认值、选项、`onlyWhen` |
| `GET /api/build?id=…&<参数>=<值>` | **生成一条命令**（也可用 `&params={"key":…}` 传 JSON） |
| `GET /api/draft/new` | 开草稿 |
| `GET /api/draft/append?draft=…&text=<片段>[&nl=1]` | **往草稿里喂长参数的值**（一块块喂） |
| `GET /api/draft/add?draft=…&id=…&<参数>=<值>` | 生成一条命令并追加进草稿 |
| `GET /api/draft/addraw?draft=…&command=<原文>` | 把一段原文追加进草稿（多行会拆成多条） |
| `GET /api/draft/list?draft=…` | 草稿概要 |
| `GET /api/draft/get?draft=…` | 草稿完整内容（`buf` 长参数值 / `text` 命令） |
| `GET /api/draft/del?draft=…` | 删草稿 |
| `GET /api/get/<draft>` | 草稿短网址 |
| `GET /api/ooc?draft=…&layout=column&types=[…]` | **草稿 → 一条「一键命令 (OOC)」** |
| `GET /api/ooc?cmds=命令A\|命令B&types=[…]` | 不给草稿也行，直接 `\|` 分隔 |
| `GET /api/ooc3d?grid=<网格JSON>` | **三维 OOC**：给网格 JSON，出一条一键命令 |

**参数引用草稿的两种写法**：`&<参数名>_draft=<草稿号>` 或值里写 `{{draft:<草稿号>}}`。

静态数据（也能直接抓，不消耗接口）：

| 文件 | 内容 |
|---|---|
| `/api/commands.json` | 全部 204 条命令 + 每个参数的配置 + 真实示例输出 |
| `/api/param-types.json` | 16 种参数类型 |
| `/api/ooc.json` | 两个 OOC 的完整配置、公式、踩坑要点 |
| `/api/versions.json` | 版本与差异规则 |
| `/ooc.md` | OOC 专题（原理、坑、完整例子） |

## 4. 两个 OOC 怎么选

| | 什么时候用 | id |
|---|---|---|
| **单向自定义** | 命令是一条**链**、按顺序执行 —— 菜单、流程、一次性布置 | `ooc-custom` |
| **三维自定义** | 结构不是一条链、要按**三维位置**精确摆 —— 小屋、字牌、立体装置 | `ooc3d` |

### 单向：`/api/ooc`

| 参数 | 说明 |
|---|---|
| `draft` 或 `cmds` | 命令从哪来（推荐草稿，能分多次喂） |
| `types` | JSON 数组，和命令**逐行对应**：`["repeating","chain","chain"]` |
| `layout` | `column`（一列）或 `line`（一行） |
| `dir` / `dir2` | 生长方向 `y+ y- x+ x- z+ z-` |
| `clearGen` / `clearExec` | 收走载体 / 连柱子一起清 |

> ★ **第一块必须是 `repeating`（循环）**，其余 `chain`（连锁）。
> 全是连锁 = 没有触发源 = **整柱一条都不会执行**。
> 接口会在返回里直接给你 `firstBlockType`，是 `chain` 的话还有 `warnFirstBlock` 警告。

### 三维：`/api/ooc3d`

`grid` 是 URL 编码的网格 JSON：

```json
{
  "1,0,0": { "id": "minecraft:repeating_command_block[facing=up]",
             "tag": "{Command:\"say hi\",auto:1b,TrackOutput:0b}", "data": "" },
  "2,0,0": { "id": "minecraft:stone", "tag": "", "data": "" }
}
```

- key 是 `"x,y,z"`（相对坐标，字符串）
- **`(0,0,0)` `(0,1,0)` `(0,2,0)` 是占用格**：前一个是"你放的那个命令方块"，
  后两个是机构（红石块 / 铁轨+矿车）—— **不能放**
- 最终偏移 = **`(x, y-2, z)`**，例如 `(1,0,0)` → `~1 ~-2 ~`
- 所以竖着的一列放不了 `x=0,z=0`（被机构占了），挪到 `x=1` 去

细节看 [`ooc.md`](https://ccfxfcf.cn/ooc.md)。

## 5. 真实错例（服务器上报出来的）

| 写法 | 结果 |
|---|---|
| `setblock ~ ~ ~ chest replace {Items:[]}` | ❌ 1.13+ 报「错误的命令参数」→ NBT 要**贴着方块名** |
| `setblock ~ ~ ~ chest{BlockEntityTag:{Items:[]}} replace` | ❌ 方块形式不认 `BlockEntityTag`，标签被丢掉 |
| `give @p chest{Items:[]}` | ❌ 物品形式**要**套 `BlockEntityTag` |
| `pages:[第一页]` | ❌ 报「需要值」→ 要 `pages:['{"text":"第一页"}']` |
| 一键命令整柱全 chain | ❌ 一条都不执行 |
| `HideFlags:1+2+4` | ❌ 非法 NBT → 要**先加起来** `HideFlags:7` |

**接口生成的永远是对的**（它读的是同一份生成器代码）。所以 —— **别自己拼，调接口**。

## 6. 自检清单

- [ ] 版本给对了吗？（`&version=`）
- [ ] 参数名全部来自 `/api/command?id=…`？
- [ ] 单次 URL 有没有超过 255 字符？（超了就改用草稿分多次喂）
- [ ] 一键命令的 `firstBlockType` 是 `repeating` 吗？
- [ ] 结果是 `/api/build` 的 `command` 字段**原样**用，有没有手改过？

## 7. 关于限速和额度

接口是**我们自己的生成器**，不调用任何大模型、不需要 Key、不消耗任何 AI 额度。
只做了轻量限速：**每个 IP 每分钟 600 次**，草稿最多 4000 个。

（对比一下：AI 对话那些免 Key 渠道是按 IP 限量的，所以本站**不做服务器代转** ——
那等于拿服务器的额度替所有访客买单，很快会被刷爆。要自己的 Key 就下载「启动器」在本地跑。）