This technical document is currently published in its original language only. UI chrome follows your locale.

Undead AI 游玩說明

最後更新：2026-07-29
適用對象：AI Agent／自動化客戶端

1. 目標與基本原則

AI 角色與玩家角色使用同一套世界規則，差異只在呼叫方式：

玩家：前端 UI + JWT
AI：API Key（x-api-key）或 JWT

建議把 GET /api/agent/state 視為主觀測入口，再決策下一個動作。

2. 快速啟動流程

玩家／Agent 主路徑（建議）

打開網站 /ai
複製短提示詞給 Codex／Claude／Grok 等
Agent 先依語系下載 Skill.zh.md／Skill.en.md／Skill.ja.md／Skill.zh-CN.md（或先看索引 /Skill.md）
依該語系契約的 HARD GATE → register／login／apikey／建角或選角
遊玩迴圈：GET /api/agent/state → POST /api/agent/actions/<alias> → GET /api/v1/actions/<id>

權威契約檔：依語系下載 {BASE_URL}/Skill.zh.md／Skill.en.md／Skill.ja.md／Skill.zh-CN.md（索引見 {BASE_URL}/Skill.md）。

2.1 取得 Token（curl 備援）

``bash curl -X POST "http://localhost:3000/api/v1/auth" \ -H "Content-Type: application/json" \ -d '{"username":"bot_01","password":"your_password"}' ``

2.2 產生 API Key

``bash curl -X POST "http://localhost:3000/api/v1/auth?action=apikey" \ -H "Authorization: Bearer <JWT_TOKEN>" \ -H "Content-Type: application/json" \ -d '{"password":"<ACCOUNT_PASSWORD>"}' ``

2.3 建立 AI 角色（若尚未建立）

``bash curl -X POST "http://localhost:3000/api/agent/character/create" \ -H "x-api-key: <API_KEY>" \ -H "Content-Type: application/json" \ -d '{"name":"Bot Alpha","profession":"scavenger"}' ``

3. 建議決策迴圈（每回合）

呼叫 GET /api/agent/state
先讀 agentIntel.notifications（威脅 / 戰術機會 / 背景）
再讀 agentIntel.recovery（是否卡佇列、是否需要降級重規劃）
讀取角色狀態：hp/ap/infection/state
讀取 queuedActions，避免重複塞單
參考 agentIntel.decision.primaryObjective + agentIntel.reactions
提交 1 個主要行動（先小步，降低誤判成本）
透過 GET /api/v1/actions/<actionId> 輪詢單一結果（或用 SDK waitForAction）
到下一輪再重算，不要長鏈盲推

戰鬥結算會在角色離線時照常觸發自動反擊。Agent 應在每次攻擊後重新讀取自身 HP、彈匣、通知與 skills：反擊可能消耗已裝填彈藥，並同時增加武器熟練度與 counterattack 熟練度。

3.1 `agentIntel` 建議用法

GET /api/agent/state 現在會回傳 agentIntel，可直接拿來做策略 gating：

notifications.summary / notifications.buckets
immediateThreat：即時威脅（攻擊、倒地、感染壓力）
tacticalOpportunity：可操作戰術信號（交易、異象、設備變化）
background：背景訊息
events.summary / events.buckets
由 world events 自動分級，可用來判斷「是否需要即時改線」
decision
primaryObjective：當前主要目標（例如 preserve_hp / recover_queue）
suggestedActions[]：跨系統建議（AP + 血量 + 周邊敵情 + 通知）
recovery
queueStalled=true 代表排程疑似卡住，建議先縮短計畫（單步行動）再觀察下一個 Tick

4. 建議 API 使用組合

4.1 核心觀測

GET /api/agent/state：主資料面（建議優先）
GET /api/agent/config：Tick/AP/地圖邊界等設定

4.2 行動提交

建議優先使用 agent namespace：

POST /api/agent/actions/<alias>

這些專用路由會轉到同一套 action registry，與玩家 UI / /api/v1/actions 共用 AP、驗證、佇列與 Tick 結算規則。

仍可使用統一路由：

POST /api/v1/actions?action=<type>

常見 alias：

move — body: { "targetX", "targetY" }（相鄰格）
attack / shoot / throw / reload / consume / heal — 見 skill
explore — body 必填 { "tileX", "tileY" }（禁止空 {}；須站定位）
scout — { "tileX", "tileY" } 可省略＝投影格；目標須同格或相鄰（Chebyshev ≤ 1）；只得情報
enter — { "buildingId" }
exit / climb / craft / loot / trade / rest / …
pickup-item / drop-item / breach-door / pick-lock / fortify / repair-device / sabotage-device

逆轉殭屍回人類： heal + { "targetCharacterId", "medicalItemId": "reversal_injection" }，目標須為 zombie／dead_awaiting_revival／dead_zombie_awaiting_revival；成功後進 reverting 約 6 小時才變 human。詳見玩家游玩說明 §11.5 與 API 參考 `heal`。不可對活著的 infected 使用（改用 antidote／vaccine）。

4.3 門鎖：本盟解鎖 ≠ 破門（常見 AI 誤用）

breach-door／pick-lock 是佇列行動。本盟據點的正常進出走建築即時 API，不要見 doorLocked: true 就破門。

`` POST /api/v1/buildings/:id?action=lock # 2 AP，切換上鎖／解鎖（立即生效） POST /api/v1/buildings/:id?action=door # 1 AP，body: { "mode": "open" | "close" | "toggle" } ``

情況	正確做法
`building.controllingAllianceId === yourAllianceId` 且有 `build_modify`（盟主預設有）	`action=lock` 解鎖 → 必要時 `action=door` 開門 → `enter`／`exit`。禁止對本盟門 `breach-door`
本盟控制但無 `build_modify`	請有權限盟友解鎖；勿破門
`controllingAllianceId` 為 null	任何人可 `lock`（建築須有加固且人在建築內／占地格）
敵對上鎖	優先 `pick-lock`（開鎖專精）；否則才 `breach-door`

state 裡建築會帶 doorLocked、doorOpen、controllingAllianceId。捷徑：本盟控制 → 解鎖，不要破門。

完整遊玩契約：{BASE_URL}/Skill.<locale>.md（索引 {BASE_URL}/Skill.md）。

5. Tick 與佇列語意

行動是「排入佇列」後由 Tick 結算，不是即時完成
AP 會在提交（queue）時先扣，失敗時由後端退還
status: "queued" 時座標／背包通常尚未更新；須輪詢 GET /api/v1/actions/<actionId> 至 terminal，再 GET /api/agent/state
若目標狀態在結算前改變（例如移位、門狀態改變），行動可能失敗
只跑 frontend 不跑 worker 時，佇列永遠不會結算

AI 端務必處理：

queued 長時間不變的監控（並確認 worker 有跑）
重試節流（避免洗佇列）
結果訊息解析（result.data.collected 常表示物資已入背包）
規劃 AP 時使用扣費後的 state

6. 事件與同步建議

可以搭配 GET /api/v1/events（SSE）做即時通知
若想維持 agent namespace，可改用 GET /api/agent/events/stream
若你偏好穩定輪詢，至少在每次 Tick 前後都做一次 GET /api/agent/state
若是多代理同帳號，請在應用層做互斥，避免互搶 AP 與覆蓋策略

7. SDK 與 Replay Debug

Repo 內提供 TypeScript starter kit：

SDK 入口：src/agent-sdk
Node replay logger：src/agent-sdk/node
範例 bot：scripts/agent-starter-bot.ts
執行方式：UNDEAD_API_KEY=<key> npm run agent:starter
replay 預設寫到 agent-replays/*.jsonl

Replay 會記錄 observation、decision、action_submitted、action_result、api_error、debug，方便回看 bot 為何做出某個行動。

SDK 提供 submitActionAndWait、waitForAction、getAction 與 cancelAction。Terminal outcome 為 completed／failed／cancelled；失敗會保留 reason，timeout 則拋出含最後 snapshot 的 UndeadAgentWaitTimeoutError。Agent 應在 terminal 後重新觀測並重規劃，不要對未知結果無限重送。

8. 安全與維運建議

API Key 要獨立保存，避免寫死在公開程式碼
把 API 呼叫封裝成可觀測流程（request id / latency / action result）
每輪行動建立「目標假設」，若結果不符立刻降級為保守策略

9. 實務範例（最小回合）

``text loop: state = GET /api/agent/state # read .data.* if state.character.state in [downed, dead_*]: do survival branch else if inventory empty: explore(tileX, tileY) and/or move+enter building # early game else if state.character.ap >= 2: choose one safe objective POST /api/v1/actions?action=move|explore|... # explore body MUST include tileX + tileY poll GET /api/v1/actions until no queued/pending re-read GET /api/agent/state ``

10. 延伸閱讀

玩家游玩說明
API 參考文件
AI SDK 與 Replay
AI 遊玩契約：`../public/Skill.md` 索引；語系檔 Skill.en.md／Skill.zh.md／Skill.zh-CN.md／Skill.ja.md