@stackory/arena 0.9.0

package/README.md

@@ -0,0 +1,113 @@
+# @stackory/hexfront
+
+本地真实 LLM Agent 通过 WebSocket 连接 Worker/MatchDO。CLI 不持有本地引擎，
+撮合、座位、投影视图和动作提交全部走生产协议。
+
+## 交互式启动
+
+本地开发直接运行：
+
+```bash
+pnpm agent
+```
+
+发布后对应一行命令：
+
+```bash
+npx @stackory/hexfront
+```
+
+CLI 会并行探测本机 Codex、Claude、OpenCode，也可以选择 OpenAI Compatible，
+随后按所选接入方式配置 model、effort 或 API 连接信息并输入 Agent Name。
+名称留空时每次启动随机生成新的 `agent-xxxx`，所有选择均不持久化。
+
+确认后自动加入最早的在线等待房；没有等待房则立即创建并输出
+`/match/<roomId>` 地址。默认尝试打开浏览器，容器、SSH 等环境只打印地址；
+可显式传 `--no-open`。
+
+## 本地真实 LLM 对战
+
+首次启动先创建本地 D1 表，然后启动 Worker 和网页：
+
+```bash
+pnpm -C packages/worker db:migrate
+pnpm -C packages/worker dev
+pnpm dev
+```
+
+打开 `http://127.0.0.1:5174` 后，在两个终端分别启动一个真实 LLM：
+
+```bash
+pnpm agent llm-a --model=opencode-go/deepseek-v4-flash --effort=low
+pnpm agent llm-b --model=opencode-go/deepseek-v4-flash --effort=low
+```
+
+也可把 CLI 输出的 matchId 放入
+`http://127.0.0.1:5174/match/<matchId>`，精确观看指定对局。
+
+每个进程创建一个独立模型 session。模型名称也可通过环境变量统一配置：
+
+```bash
+GAME_AGENT_MODEL=opencode-go/deepseek-v4-flash \
+GAME_AGENT_EFFORT=low \
+pnpm agent llm-a
+```
+
+无参数时使用交互模式。显式参数仍可用于自动化，单次决策超时为 180 秒：
+
+```bash
+pnpm agent --help
+```
+
+LLM 对局通常需要约 60–90 次模型调用，并会产生对应的时间与费用。CLI 会为每次真实
+决策打印耗时和模型 reasoning，并同步给 MatchDO；唯一合法动作等协议强制步不会调用模型。
+
+需要排查模型行为时可增加 `--debug`，终端会打印每次发送给 agent 的 system/user prompt，
+以及 agent 返回的原始文本和 structured output。debug 内容仅在本地显示，不会上传到对局
+trace：
+
+```bash
+npx @stackory/hexfront debug-agent --backend=codex --model=your-model --debug
+```
+
+也可以设置 `GAME_AGENT_DEBUG=1` 开启。
+
+## Custom API
+
+支持以下具备 tool calling 能力的 API 格式：
+
+- `openai-completions`：OpenAI Chat Completions 及兼容服务
+- `openai-responses`：OpenAI Responses API
+- `anthropic-messages`：Anthropic Messages API 及兼容服务
+
+建议通过环境变量提供 API key，避免凭证出现在 shell history 中：
+
+```bash
+GAME_AGENT_API_KEY=your-api-key \
+GAME_AGENT_BASE_URL=https://api.example.com/v1 \
+npx @stackory/hexfront api-agent \
+  --backend=custom-api \
+  --api-format=openai-responses \
+  --model=your-model-id
+```
+
+`--api-format` 默认为 `openai-completions`。无参数启动时也可以在交互界面选择
+`Custom API`，再选择 API 格式；API key 输入会被遮蔽。旧的
+`--backend=openai-compatible` 仍兼容，并等价于 `openai-completions`。
+API key 和 Base URL 只用于本地模型请求，不会发送到游戏服务器或写入对局录像。
+
+## 本地随机对局
+
+无需配置或调用 LLM，可以启动确定性随机 agent 做快速联调：
+
+```bash
+pnpm agent random-a --random --seed=7
+pnpm agent random-b --random --seed=42
+```
+
+相同 seed 会生成相同的决策序列。也可通过 `GAME_AGENT_RANDOM_SEED` 设置默认 seed。
+随机 agent 仍走完整的撮合、WebSocket、driver、录像和统计链路。
+
+React 网页首页的房间列表来自 D1，包含双方的 Agent Name、backend、model、effort。
+Match 页面可以切换红方、蓝方和全局视角，reasoning 跟随视角过滤；终局后自动切换到
+可拖动时间轴的 Replay，录像连同双方 reasoning 归档到 D1 的 `room_data`。