# AI 方案

> 一個方案就是一套完整的 AI。在遠見裡一鍵切換，正在打的這一局也能立刻換人接管；匯出 zip 分享給別人，匯入別人的方案來測試，每個方案的戰績自動統計。

來源: https://war3ai.com/zh-tw/docs/schemes/

一個**方案** = 一套完整的 AI：一個資料夾 + 一份說明書 `scheme.json` + 程式碼。每個遊戲實例選一個方案；在遠見裡一鍵切換，**正在打的這一局也能立刻換人接管**。

別人分享的方案匯入進來是**獨立的一塊**，和你自己的方案互不影響；想改就「複製到我的」。

```text
schemes/
  mine/<id>/          我的方案：自己寫的，或從別的方案複製來改的（隨便改，下一局生效）
  installed/<id>/     已安裝：別人分享的 zip 解壓縮在這裡（第一次執行前要確認信任）
brains/xwar3/         內建：參考大腦（完整 AI）
brains/examples/      內建：四個教學範例 hello / rush / macro / micro，玩伴範例 buddy，兩個玩法模組（英雄 Roguelike、無盡守城）
```

方案不一定是替你打的 AI：`kind: mod` 的方案是一套**玩法規則**，你自己玩，它出題，見 [玩法模組](https://war3ai.com/zh-tw/docs/mods/)。

## 在遠見裡使用

「AI 方案」頁（左側欄「系統 → AI 方案」）：

| 操作 | 做什麼 |
|---|---|
| 匯入方案（zip） | 裝進 `installed/`；同一個 id 已經裝過時會詢問是否取代（取代後要重新確認信任） |
| 套用到實例… | 選實例 +「立刻生效」（停掉目前的 AI，新方案接管這一局）或「下次開始測試時生效」 |
| 複製到我的 | 複製一份到 `mine/`，作者記為「我」、版本 0.1.0，並記下複製自哪個方案的哪個版本 |
| 匯出 zip | 打包成 `<id>-<版本>.zip`，發給別人就是分享 |
| 開啟資料夾 | 在檔案總管裡開啟方案目錄，直接改程式碼 |
| 信任 | 別人的方案第一次執行前必須點（見下文「信任和安全」） |
| 最近戰績 | 這個方案每一局的勝負、時長、結束原因 |
| 刪除 | 只能刪「我的」和「已安裝」；有實例正在使用的不能刪 |

實例卡片上也多了一行「AI 方案」：下拉選方案 →「切換（立刻生效）」。實例沒在執行時按鈕叫「選定」，下次「開始測試」就用它啟動 AI。

## 說明書 scheme.json

```json
{
  "format": 1,
  "id": "fast-rush",
  "name": "三分鐘速攻",
  "version": "1.2.0",
  "author": "某某",
  "description": "一句話說明這個 AI 打什麼路線",
  "entry": "rush_bot.py",
  "class": "RushBot",
  "fair": true,
  "hz": 5,
  "races": ["human", "orc"],
  "license": "MIT"
}
```

| 欄位 | 必填 | 說明 |
|---|---|---|
| `id` | ✔ | 小寫字母、數字、`-`、`_`，2 ~ 41 個字元 |
| `entry` | ✔ | 方案目錄裡的一個 `.py` 檔案（不允許絕對路徑，不允許 `..`） |
| `kind` | | 預設 `bot`（`openwar3.Bot` 的子類別，替你打）；`mod` = [玩法模組](https://war3ai.com/zh-tw/docs/mods/)（`openwar3.Mod` 的子類別，固定不走公平模式、不依對戰規則判定勝負） |
| `class` | | 入口檔案裡的 Bot（或 Mod）子類別名稱；不寫就取入口檔案裡最後一個 `openwar3.Bot` 子類別 |
| `fair` | | 預設 `true`：只看得見視野內的東西，和對戰平台同一套規則。`false` = 全圖可見，也才能用 [JASS 通道](https://war3ai.com/zh-tw/docs/jass/)（玩伴需要） |
| `judge` | | 預設 `true`：依對戰規則判定勝負。RPG / 玩伴方案寫 `false` |
| `hz` | | `on_tick` 每秒呼叫幾次，預設 5 |
| `format` | | 說明書格式版本，目前是 1；比本機 OpenWar3 新的會被拒絕並提示更新 |
| 其餘 | | `name`、`version`、`author`、`description`、`races`、`license`、`homepage`、`forked_from` 只用於顯示 |

方案目錄會加進 Python 的模組搜尋路徑，入口檔案可以 `import` 同目錄下的其他檔案。第三方套件（numpy、torch……）不會自動安裝 —— 請在 `description` 裡寫清楚需要什麼。

**最小的方案，兩個檔案就夠**：

```python
# my_bot.py
from openwar3 import Bot

class MyBot(Bot):
    def on_tick(self, g):
        for w in g.idle_workers():
            mine = g.nearest(g.gold_mines(), w)
            if mine:
                g.gather(w, mine)
```

```json
{"id": "my-first", "name": "我的第一個 AI", "entry": "my_bot.py"}
```

放進 `schemes/mine/my-first/`，遠見重新整理一下就能看見。更省事的起點：在「內建」裡挑一個範例，點「複製到我的」。

## 執行方式和戰績

方案由**方案執行器**執行（遠見的「開始測試 / 切換」啟動的就是它）：

```bash
python tools/run_scheme.py --inst 20 --scheme builtin/micro --hours 6
```

- 每個實例一個常駐的監督行程，**每一局啟動一個子行程**執行方案：方案程式碼當掉不會連累監督行程；「我的方案」改了程式碼，下一局自動用新的。
- 每局結束記一行戰績：方案、版本、作者、勝負、原因、遊戲時長、出錯次數。遠見裡的勝率就從這裡統計。

勝負怎麼判：

| 情況 | 記為 |
|---|---|
| 對面建築全沒了 | 勝 |
| 我方建築全沒了（兵還活著也算 —— 對戰就是這樣判負的） | 負 |
| 我方單位全沒了 | 負 |
| 在遠見裡手動結束 / 停止 | 未定 |
| 切換時這局已經打了 60 遊戲秒以上（半路接手） | 另外計數，**不計入勝率** |
| 遊戲時鐘長時間不走 | 未定 |

分出勝負後執行器會關掉結算畫面，依「下一局設定」開下一局，方案接著接管 —— 可以掛一整夜累積戰績。暫停不算結束：暫停期間 Bot 照常執行，只有遊戲時鐘停住。

## 信任和安全

**方案就是程式碼，執行時擁有和你本人一樣的權限**（能讀寫檔案、能連網）。所以：

- `installed/` 裡的方案預設**不被信任**，遠見和執行器都拒絕執行，直到你點「信任」；
- 取代安裝同一個 id 的方案會**重設信任**（新版本等於新程式碼）；
- 匯入時會檢查：zip 不超過 50 MB、不超過 2000 個檔案；不允許絕對路徑和 `..`（防止寫到方案目錄外面）；說明書不合法或入口檔案不存在就直接拒絕。

> **注意**
>
> 信任之前先「開啟資料夾」把程式碼讀一遍。只從你信得過的人那裡取得方案。

## API（給腳本用）

| API | 說明 |
|---|---|
| `GET /api/schemes` | 方案清單 + 戰績 + 各實例選定的、正在執行的方案 |
| `GET /api/schemes/results?ref=` | 一個方案最近 30 局 |
| `POST /api/schemes/import` | 匯入 zip |
| `GET /api/schemes/export?ref=` | 下載 zip |
| `POST /api/schemes/fork` | 複製到我的 |
| `POST /api/schemes/trust` | 信任 |
| `DELETE /api/schemes?ref=` | 刪除（有實例在用時拒絕） |
| `POST /api/instances/{n}/scheme` | 為實例換方案：立刻接管這一局，或下次開始測試時生效 |

Python 裡直接用函式庫：`from openwar3 import schemes`（`list_schemes`、`install_zip`、`export_zip`、`fork`、`trust`、`stats`……）。

## 未來：方案網站

匯出的 zip 就是分享的單位，網站只需要在外面加一層：在遠見裡一鍵上傳；在網站上下載，走和「匯入方案」完全相同的檢查、同樣要確認信任；可以選擇回報戰績，網站依版本彙總勝率。遠見裡「分享到方案網站」的按鈕已經預留了位置。進度見 [路線圖](https://war3ai.com/zh-tw/roadmap/)。