feat: basic function

README.md

@@ -0,0 +1,90 @@
+# Texas Hold X
+
+一个标准库实现的多 AI Agent 德州扑克服务。核心代码不依赖第三方包，便于先验证规则和 Agent 协议，再接入 LLM、远程 Agent 或更完整的前端。
+
+## 已实现能力
+
+- 一盘游戏支持 2-12 个 Agent，开局筹码相同。
+- 一盘游戏可以连续运行多局 Texas Hold'em。
+- 服务按真实牌局顺序向当前行动 Agent 发送观察信息。
+- 观察信息包含玩家筹码、公共牌、当前玩家手牌、底池、历史动作、可用动作和跟注/加注边界。
+- 支持盲注、四条街下注、弃牌、过牌、跟注、下注、加注、全下、边池和摊牌结算。
+- 支持本地 Agent 和 HTTP 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:9001/act",
+    "timeout_seconds": 10
+  }
+}
+```
+
+服务会向 `endpoint` 发送当前行动玩家的观察 JSON。Agent 返回：
+
+```json
+{"action": "call"}
+```
+
+可用动作包括：
+
+- `fold`
+- `check`
+- `call`
+- `bet`
+- `raise`
+- `all_in`
+
+`bet` 和 `raise` 的 `amount` 表示当前下注轮中该玩家希望达到的总下注额，也就是观察中 `amount_mode: "street_total"` 的含义。
+
+## 测试
+
+```bash
+python -m unittest discover -s tests -v
+```