qianrui.mmmy
115 lines
2.9 KiB
Markdown
115 lines
2.9 KiB
Markdown
# Texas Hold X
|
||
|
||
一个标准库实现的多 AI Agent 德州扑克服务。核心代码不依赖第三方包，便于先验证规则和 Agent 协议，再接入 LLM、远程 Agent 或更完整的前端。
|
||
|
||
## 已实现能力
|
||
|
||
- 一盘游戏支持 2-12 个 Agent，开局筹码相同。
|
||
- 一盘游戏可以连续运行多局 Texas Hold'em。
|
||
- 服务按真实牌局顺序向当前行动 Agent 发送观察信息。
|
||
- 观察信息包含玩家筹码、公共牌、当前玩家手牌、底池、历史动作、可用动作和跟注/加注边界。
|
||
- 支持盲注、四条街下注、弃牌、过牌、跟注、下注、加注、全下、边池和摊牌结算。
|
||
- 支持本地 Agent 和 HTTP Agent。
|
||
- 支持 Human Agent 和 OpenAI-compatible AI Agent 的终端过程输出。
|
||
|
||
## 运行服务
|
||
|
||
```bash
|
||
python -m texas_holdem.server --host 127.0.0.1 --port 8000
|
||
```
|
||
|
||
创建一盘 3 人游戏：
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/games \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"game_id": "demo",
|
||
"seed": 42,
|
||
"starting_stack": 1000,
|
||
"small_blind": 5,
|
||
"big_blind": 10,
|
||
"players": [
|
||
{"id": "agent_1", "name": "Agent 1", "type": "calling"},
|
||
{"id": "agent_2", "name": "Agent 2", "type": "random"},
|
||
{"id": "agent_3", "name": "Agent 3", "type": "calling"}
|
||
]
|
||
}'
|
||
```
|
||
|
||
运行 10 局：
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/games/demo/hands/run \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"count": 10, "until_one_left": false}'
|
||
```
|
||
|
||
查看游戏状态：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/games/demo
|
||
```
|
||
|
||
## HTTP Agent 协议
|
||
|
||
玩家配置可以使用远程 HTTP Agent：
|
||
|
||
```json
|
||
{
|
||
"id": "llm_agent",
|
||
"name": "LLM Agent",
|
||
"agent": {
|
||
"type": "http",
|
||
"endpoint": "http://127.0.0.1:9101",
|
||
"timeout_seconds": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
服务会向 `endpoint` 发送当前行动玩家的观察 JSON。Agent 返回：
|
||
|
||
```json
|
||
{"action": "call"}
|
||
```
|
||
|
||
可用动作包括：
|
||
|
||
- `fold`
|
||
- `check`
|
||
- `call`
|
||
- `bet`
|
||
- `raise`
|
||
- `all_in`
|
||
|
||
`bet` 和 `raise` 的 `amount` 表示当前下注轮中该玩家希望达到的总下注额，也就是观察中 `amount_mode: "street_total"` 的含义。
|
||
|
||
## AI Agent
|
||
|
||
启动一个可接入 OpenAI-compatible Chat Completions API 的 AI Agent：
|
||
|
||
```bash
|
||
python -m texas_holdem.ai_client \
|
||
--host 127.0.0.1 \
|
||
--port 9101 \
|
||
--base-url https://api.openai.com/v1 \
|
||
--api-key "$OPENAI_API_KEY" \
|
||
--model gpt-4o-mini \
|
||
--keep-history
|
||
```
|
||
|
||
AI Agent 会在终端输出：
|
||
|
||
- 收到的 `/game` 游戏快照；
|
||
- 收到的 `/act` 行动请求；
|
||
- 大模型流式返回内容，默认灰色显示；
|
||
- 最终解析出的 action，或失败时的 fallback action。
|
||
|
||
默认每次 `/act` 会清屏，和 Human Agent 一致；加 `--keep-history` 后保留历史滚动输出。可用 `--no-stream` 关闭流式请求，用 `--no-color` 关闭灰色 ANSI 输出。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
python -m unittest discover -v
|
||
```
|