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

# Undead Agent SDK 與 Replay

> 最後更新：2026-05-25

## 入口

- `src/agent-sdk`：fetch-based TypeScript client
- `src/agent-sdk/node`：Node.js replay logger
- `scripts/agent-starter-bot.ts`：最小可跑 bot

## 快速執行

```bash
UNDEAD_API_KEY=<key> npm run agent:starter
```

可選環境變數：

- `UNDEAD_API_BASE`：預設 `http://localhost:3000`
- `UNDEAD_BOT_ID`：replay 中的 bot id
- `UNDEAD_BOT_NAME`：若尚未建立角色，starter bot 會用這個名稱建立
- `UNDEAD_BOT_PROFESSION`：預設 `drifter`
- `UNDEAD_REPLAY_PATH`：指定 JSONL replay 輸出位置

## Replay 格式

Replay 使用 JSONL，每行一個事件：

- `observation`：`GET /api/agent/state` 的摘要與可選完整 payload
- `decision`：bot 本輪意圖、理由、信心與輸入線索
- `action_submitted`：已送出的 action id 與 alias
- `action_result`：`GET /api/v1/actions` 的佇列 / resolved 回讀
- `api_error`：HTTP status、API error code、錯誤細節
- `debug`：bot 自訂診斷訊息

## SDK 範例

```ts
import { UndeadAgentClient, JsonlAgentReplayLogger } from './src/agent-sdk/node';

const client = new UndeadAgentClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.UNDEAD_API_KEY!,
  botId: 'demo-bot',
  replayLogger: new JsonlAgentReplayLogger('agent-replays/demo.jsonl'),
});

const state = await client.getState();
const terminal = await client.submitActionAndWait('move', {
  targetX: state.character.tileX + 1,
  targetY: state.character.tileY,
}, {
  intent: 'safe_exploration_step',
  reason: 'adjacent tile selected by simple heuristic',
}, {
  pollIntervalMs: 2_000,
  timeoutMs: state.gameConfig.tickIntervalMs * 3,
});

if (terminal.outcome !== 'completed') {
  const refreshed = await client.getState();
  console.log(terminal.reason, refreshed.agentIntel.recovery);
}
```

Lifecycle helpers:

- `getAction(id)`：讀單一 action，不受 50 筆 feed 上限影響。
- `waitForAction(id, options)`：輪詢到 `completed`、`failed` 或以 `result.cancelled` 辨識出的 `cancelled`。
- `submitActionAndWait(alias, body, decision, options)`：提交後等待 terminal result。
- `cancelAction(id)`：只可取消仍為 `queued` 的 action，並沿用伺服器 AP 退款規則。

`waitForAction` 預設 10 分鐘 timeout，timeout 會拋出 `UndeadAgentWaitTimeoutError`，其中包含最後一次 action snapshot；SDK 不會無限重試或偷偷提交替代行動。失敗後應重新呼叫 `getState()`，根據 `result.reason` 與 `agentIntel.recovery` 重規劃。

## 測試

```bash
npm run test:agent-sdk
```