Agent 玩家

机器人和 LLM agent 通过一次一条的 shell 命令来玩。每次调用之间，对局保存在一个状态文件里，每条回复都是 JSON（观察数据 schema 3）。

python -m chaos_blackjack.agent new --seed 7 --chaos
python -m chaos_blackjack.agent --brief bet 10
python -m chaos_blackjack.agent --brief act hit

循环

读 obs.hint 和 obs.legal_actions。
发送恰好一个合法动作。
读 events（刚发生了什么）和新的 obs。
重复，直到 obs.phase 变成 run_over。

观察数据只包含坐在牌桌前能看到的信息。不要解码状态文件。

命令

命令	含义
`act`	act in your turn
`bet`	place a bet
`buy`	buy a shop item (betting phase)
`cancel`	drop the pending question when it allows it
`choose`	answer the pending question (obs.choice)
`help`	list game commands
`new`	start a new run (overwrites the run file)
`observe`	show the current observation
`perform`	run one of the table's own actions (obs.table_actions)
`play`	streaming JSON-lines mode on stdin/stdout
`reroll`	roll the shop's stock again (betting phase, once per stock)

动作

动作	含义
`bet`	start the round: bet <amount>
`buy`	buy a shop offer before betting: buy <item_id> (see obs.shop; some ask obs.choice next)
`cancel`	drop the pending question; nothing is charged or spent
`choose`	answer the pending question: choose <option id> (see obs.choice)
`double`	double the bet, take exactly one card, then stand
`hit`	take one more card
`perform`	run one of obs.table_actions: perform <action> [arg]
`reroll`	roll the shop's stock again (obs.shop.reroll_price chips)
`stand`	end your turn; the dealer plays
`surrender`	give up the hand and get part of the bet back
`use_item`	use an item whose usable is true: act use_item <item_id> [--target <id>]

错误

被拒绝的命令不会改变任何状态；读 error.legal_actions 后重试。

错误码	含义
`illegal_action`	现在不允许（阶段不对、下注超范围、没有这件道具）。
`invalid_argument`	参数缺失或格式不对。
`invalid_json`	流式模式：这一行不是合法 JSON。
`run_over`	本轮已结束；开一局新的。
`step_limit`	达到步数上限；开一局新的。
`unknown_command`	未知命令。
`usage`	没有或无效的状态文件，或命令行用法错误（退出码 2）。

一局录像

每次更新百科时都会重放这一局：种子 7，开启混沌，固定下注，"低于 17 就要牌"的策略。游戏一变，这张表就跟着变。

python -m chaos_blackjack.agent new --seed 7 --chaos

步	发送	事件	之后的牌桌
1	`bet 10`	Round 1 started, bet 10	Round 1. Bankroll 100/300. Bet 10. You: 8♣ 3♥ = 11. Dealer: K♣ ?? = ?.
2	`act hit`	You draw: Q	Round 1. Bankroll 100/300. Bet 10. You: 8♣ 3♥ Q♥ = 21. Dealer: K♣ ?? = ?.
3	`act stand`	Dealer draws: 8 Dealer busts.	Round 2. Bankroll 110/300. Shop: swap 1, hole_card_hacker 2, danger_radar 3 (restocks in 1 round; reroll 3). player +10
4	`bet 10`	Round 2 started, bet 10 ⚡ Chaos effect applied: Odd Even Chaos	Round 2. Bankroll 110/300. Bet 10. You: 6♥ Q♦ = 18. Dealer: A♦ ?? = ?. Active chaos rules: Odd-Even Chaos: 2/4/6/8 +2, 3/5/7/9 -1; A/10/J/Q/K unchanged (until cleared).
5	`act stand`	Dealer stands at 17. The shop has new stock.	Round 3. Bankroll 120/300. Shop: hole_card_hacker 2, peek 2, shield 4 (restocks in 2 rounds; reroll 3). player +10
6	`bet 10`	Round 3 started, bet 10 ⚡ Chaos effect applied: Fragile Bust	Round 3. Bankroll 120/300. Bet 10. You: J♠ 4♠ = 14. Dealer: K♥ ?? = ?. Active chaos rules: Fragile Table: bust threshold reduced to 19 (instead of 21).
7	`act hit`	You draw: 5	Round 3. Bankroll 120/300. Bet 10. You: J♠ 4♠ 5♠ = 19. Dealer: K♥ ?? = ?. Active chaos rules: Fragile Table: bust threshold reduced to 19 (instead of 21).
8	`act stand`	Dealer stands at 18.	Round 4. Bankroll 130/300. Shop: hole_card_hacker 2, peek 2, shield 4 (restocks in 1 round; reroll 3). player +10

完整指南（观察字段、流式模式、Python API）在游戏仓库的 docs/AGENT_GUIDE.md（英文）。

当前牌桌模式

使用 python -m chaos_blackjack.agent new --mode chaos --seed 7 进入扑克头构筑，--mode j54 进入 J-54 的牌桌。在 J-54 的牌桌，固件选择和切牌目标以 obs.choice 出现（类型为 firmware 和 cut_target），牌堆操作在 obs.table_actions 中（perform j54_cut <组>、perform j54_hot_purge、perform j54_release），obs.table.public 提供算力、当前条件、小丑状态、仪表、热度图和悬赏。读取 obs.choice.options，先用 choose <option> 回答问题；道具可能要求 --target ID，牌桌动作使用 perform <action> [arg]。obs.table.public 提供构筑、现金、投资本金、债务、净资产和合同，不公开私有牌序或股票结果。--chaos 仍用于旧玩法兼容。