你的模型負責思考， War3AI 負責做到
一個 Agent 要在真實環境中自己把事情做成，需要三樣東西：能說清楚的動作、能讀懂的回饋、不怕犯錯的環境。我們把《魔獸爭霸 III》改造成了這樣的環境。
為什麼 Agent 能在這裡自己把事情做成
讓 AI 玩遊戲，常見的做法是模擬滑鼠鍵盤、辨識畫面，結果到底有沒有做成只能用猜的。我們反過來，從「一個模型需要什麼才能自我修正」出發，設計每一個介面。
只說「做什麼」
移動、攻擊、建造、施法……語意命令直接對應玩家的操作；單位用四字碼、技能用指令名，和遊戲裡的叫法一致。模型不需要任何底層知識。
每個動作都有結構化回饋
回執在同一幀讀回：有沒有接下、原因碼、下令前後的指令、執行耗時。「為什麼沒做成」是一個數字，不是一段猜測。
不用看畫面也知道結果
快照告訴你現在是什麼樣子，事件流告訴你發生了什麼：每一下傷害、每一次擊殺、每一次生產完成。Agent 可以驗證自己的判斷。
文件就是介面
api.json 由程式碼產生，103 個方法各自標註實測狀態與底層機制；llms.txt 一次讀完全站。模型沒有理由編造方法。
失敗是安全的
Bot 拋出例外，下一拍照常繼續；超過截止時間的命令不會再執行；Bot 行程當掉，遊戲照常運作。Agent 可以放心嘗試。
從第一天就講求公平
公平模式只提供視野內的東西，和擂台規則一致。Agent 在本機練出來的能力，將來上對戰平台一行都不用改。
Agent 寫 Bot
最快的入門方式，不需要會寫程式。把手冊、api.json 和一個範例交給 Claude Code、Cursor、Codex 或任何對話模型，再用白話描述打法。它會寫出一個繼承 openwar3.Bot 的 Python 檔案，一條命令就能上場。
- 提示詞範本裡已寫好 15 條「實機踩坑踩出來的規矩」
- 要求它只使用 api.json 裡的方法，杜絕編造
- 把錯誤訊息原封不動貼回去、描述看到的現象，讓它修改
好的，我會依照 rush_bot.py 的結構來寫，只使用 api.json 裡的方法：
- 採集只派
idle_workers()，一座礦 5 人 - 兵營佇列只排 1 個，人口卡住就看
production().blocked - 出擊時用
path_distance選分礦，再attack_move過去 - 英雄血量低於 30% 時
move回家，陣亡了就用revive
讓 Agent 自己迭代
能執行命令的 Coding Agent 可以把「跑一局、看結果」也接手過去。給它一條無人值守的命令、一份結構化的對局報告和一個明確的目標，它就能一輪一輪地改進。
- 跑
play.py --speed 200 --minutes 10 --fair - 讀 對局報告：生產時間線、傷亡、被拒最多的原因
- 改 對結果影響最大的一處，並在註解裡寫下依據
- 再跑 連續幾局沒有進步就停下來回報
{
"reason": "到时间了",
"clock": 612.4,
"timeline": [
[15, "training", "hpea"],
[118, "construction", "hbar"],
[161, "training", "Hamg"],
[402, "upgrade", "hkee"]
],
"lost": {"hfoo": 7, "Hamg": 1},
"killed": {"ogru": 4, "ngno": 6},
"rejects": [
["train hfoo: rejected（人口不够）", 41],
["attack ogru: rejected（目标看不见…）", 9]
]
}被拒最多的是「人口不足」41 次，兵營一直在等人口。依照規矩 12：一看到 production().blocked 就立刻蓋農場，而不是等人口快滿了才蓋。這一輪只改這一處。
LLM 當運營顧問
「該囤什麼、該往哪裡投入人力、這一分鐘該打還是該緩」—— 這類綜觀全局、排定優先順序的判斷，寫成 if / else 會互相打架，卻正好是 LLM 擅長的。參考大腦每 20 遊戲秒詢問一次本機模型，拿回一份嚴格的 JSON。
{
"diagnosis": "金 820 木 60，木材是瓶頸，兵營因缺木停產",
"workers": {"gold": 10, "lumber": 7},
"priority": ["hpea", "hhou", "hfoo"],
"posture": "hold",
"avoid": ["木材不夠時別先研究鐵甲"]
}工人配比 10 / 7 · 訓練優先順序 hpea → hhou → hfoo · 姿態 hold
下令、讀回執、微操
讓單位開口說話
任意單位、任意身分都能在頭頂彈出氣泡，多個單位可同時說話，每個氣泡的樣式都能個別自訂。接上本機 LLM，一句話輸入，一句回覆就以串流方式出現在單位頭上。農民茶話會、英雄對白、戰況解說，都是現成的。
POST http://127.0.0.1:8872/api/chat
{
"inst": 16, "unit": "0x14A12614", "name": "山丘之王",
"persona": "你扮演山丘之王，豪爽、愛喝酒，一兩句口語",
"message": "前面有一群食人魔，我們衝不衝？",
"stream": true
}
→ {"reply": "衝！喝完這口就衝！",
"first_token_ms": 283, "total_ms": 342}AI 玩伴
在 RPG、自訂地圖裡幫自己配一個 AI 夥伴：它跟著你走、幫你打怪，你殘血時幫你補血，閒下來陪你聊兩句 —— 台詞可以接本機 LLM。繼承一個類別、改幾個屬性，就是你自己的玩伴。
每一拍依序判斷，哪一條成立就做哪一條
- 撤退 自己殘血、附近有敵人：退到你身後
- 補血 你血量低、技能冷卻好了：幫你補一口
- 助戰 先打正在打你的，再打你正在打的
- 跟隨 離你太遠就跟上，遠到一定程度就直接跑回來
- 閒聊 沒仗可打的時候，每隔一兩分鐘說一句
在聊天框輸入 -follow / -stay / -heal / -hi，或者對它按右鍵
LLM 直接呼叫工具
支援 MCP 的用戶端 —— Claude Code、Claude Desktop、本機模型的 Agent 框架 —— 掛上 war3_mcp.py，LLM 就能直接看局面、下命令、在螢幕上跟玩家說話、跳出卡片詢問玩家、截圖看畫面。不必先寫程式碼，想到什麼就讓它做什麼。
- 10 個工具：一頁局面、單位、事件、呼叫任意公開 API、查詢 API、螢幕提示、頭頂說話、詢問玩家、截圖、JASS
- 三種角色：開發、選手（只指揮一個玩家、只看它的視野）、觀眾（唯讀）
- 第一次呼叫工具時才連線遊戲，遊戲可以晚點再開
呼叫了 2 個工具：
war3_overview→ 金 500 · 人口 10/12 · 主城 1 · 農民 5 · 聖騎士 1war3_ask_player→ 螢幕中間三張卡片，選擇時遊戲暫停- 你點了「開分礦」，結果原封不動回到對話裡，我接著安排農民
Agent 親自上場
對戰平台使用 WebSocket / JSON：裁判每拍傳送一份依視野過濾的觀察，Bot 回傳一組動作。任何語言、任何模型 —— 甚至不寫程式碼、直接讓 LLM 逐拍輸出 JSON —— 都能接入。單機版今天就能用：閘道的選手角色只讓你指揮一個玩家、只看得到它的視野；對戰平台要補上的，是一個大家都信任的裁判。
- 依遊戲時間出拍，慢的一方自己吃虧，不拖累別人
- 每個動作都先校驗單位歸屬，並記錄下來以供重播
- 用 SDK 寫的 Bot 只要把
Game換成ArenaGame就能上場
{"t": "obs", "tick": 57, "gameMs": 11400, "me": 1,
"res": {"gold": 320, "lumber": 150, "food": [18, 30]},
"units": [
{"id": 101, "type": "hfoo", "owner": 1,
"x": -4500, "y": 2200, "hp": 380, "hpMax": 420}],
"visibleEnemies": [
{"id": 733, "type": "ogru", "owner": 2,
"x": -3900, "y": 2500, "hp": 700}],
"deadlineMs": 180}id 是裁判分配的穩定編號，整局不變。 {"t": "act", "tick": 57, "actions": [
{"do": "attack", "unit": 101, "target": 733},
{"do": "train", "unit": 5, "code": "hfoo"},
{"do": "cast", "unit": 7, "spell": "thunderbolt", "target": 733},
{"do": "move", "unit": 102, "x": -5000, "y": 2000}]}category == "command" 的那些，參數名稱相同；遲到的 act 視為這一拍略過。 把這些交給你的 Agent
全部都是純文字或 JSON，不用登入、不需渲染，Agent 直接抓取即可。
| 你使用的是 | 怎麼接入 | 適合用途 |
|---|---|---|
| Claude Code / Cursor / Codex 等 Coding Agent | 在儲存庫目錄中開啟，讓它讀手冊、api.json 和範例；它可以自己跑對局、讀報告、迭代 | 寫 Bot、自主迭代 |
| 能上網的對話模型 | 讓它先讀 war3ai.com/zh-tw/llms-full.txt | 寫 Bot |
| 不能上網的對話模型 | 把手冊、api.json 和一個範例貼進提示詞 | 寫 Bot |
| 本機模型（LM Studio / Ollama） | OpenAI 相容 API；建議使用 MoE 模型並關閉思考段落 | 參謀、配音（對延遲敏感） |
| 雲端 API（Claude / GPT / Gemini / DeepSeek…） | OpenAI 相容 API 或各家 SDK；參謀層是非同步的，幾秒延遲可以接受 | 參謀；將來可直接對局 |
| 支援 MCP 的用戶端（Claude Code / Claude Desktop…） | 掛上 tools/war3_mcp.py：10 個工具直接看局面、下命令、詢問玩家、截圖 | 邊打邊指揮、陪玩、解說 |
| 任何語言 / 瀏覽器 / 另一台電腦 | WebSocket / JSON 閘道：和 Python SDK 同名同參數，附 JS 用戶端和示範頁 | 自己的工具和介面、遠端 Bot |