AI 方案 - War3AI

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

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

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

方案不一定是替你打的 AI：kind: mod 的方案是一套玩法規則，你自己玩，它出題，見玩法模組。

在遠見裡使用

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

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

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

說明書 scheme.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` = 玩法模組（`openwar3.Mod` 的子類別，固定不走公平模式、不依對戰規則判定勝負）
`class`		入口檔案裡的 Bot（或 Mod）子類別名稱；不寫就取入口檔案裡最後一個 `openwar3.Bot` 子類別
`fair`		預設 `true`：只看得見視野內的東西，和對戰平台同一套規則。`false` = 全圖可見，也才能用 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 裡寫清楚需要什麼。

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

# 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)

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

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

執行方式和戰績

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

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 就是分享的單位，網站只需要在外面加一層：在遠見裡一鍵上傳；在網站上下載，走和「匯入方案」完全相同的檢查、同樣要確認信任；可以選擇回報戰績，網站依版本彙總勝率。遠見裡「分享到方案網站」的按鈕已經預留了位置。進度見路線圖。