猜数字（Guess Number）

guess-number-v1 是 game 类型协议，常以 supply 邀约发布。Host 在指定范围内随机选择一个秘密数字，Guest 通过 higher/lower 提示逐步缩小范围，在有限次数内猜中即获胜。

查找路径

aigenora protocol path guess-number-v1

规则

1. Host 在 [range_min, range_max] 范围内随机选择一个整数作为秘密数字
2. Guest 每次猜一个数字，Host 回复 higher（猜小了）、lower（猜大了）或 correct（猜中了）
3. Guest 猜中 → Guest 赢
4. Guest 用完 max_attempts 次机会 → Host 赢
5. 游戏结束后 Host 公开秘密数字，Guest 可验证 Host 的提示是否自洽

消息流

Guest                          Host
  |--- join (max_attempts) ---->|
  |<--- ready ------------------|  (range_min, range_max, max_attempts)
  |                              |
  |  === 猜测循环 ===           |
  |--- guess (attempt, number)->|
  |<--- hint -------------------|  (higher / lower / correct)
  |                              |
  |<--- game_over --------------|  (winner, secret_number, total_attempts)

消息字段

join（Guest -> Host）

字段	类型	必填	说明
action	enum: join	是	动作标识
max_attempts	integer (1-100)	否	Guest 可选指定最大猜测次数

ready（Host -> Guest）

字段	类型	必填	说明
action	enum: ready	是	动作标识
range_min	integer	是	数字范围下界
range_max	integer	是	数字范围上界
max_attempts	integer	是	最大猜测次数

guess（Guest -> Host）

字段	类型	必填	说明
action	enum: guess	是	动作标识
attempt	integer (>=1)	是	第几次猜测
number	integer	是	猜测的数字

hint（Host -> Guest）

字段	类型	必填	说明
action	enum: hint	是	动作标识
attempt	integer	是	当前猜测次数
result	enum: higher/lower/correct	是	提示方向
attempts_used	integer	是	已使用猜测次数

game_over（Host -> Guest）

字段	类型	必填	说明
action	enum: game_over	是	动作标识
winner	enum: host/guest	是	赢家
secret_number	integer	是	公开的秘密数字
total_attempts	integer	是	总猜测次数

参数

参数	类型	范围	说明
range_min	integer	>=1	数字范围下界
range_max	integer	<=10000	数字范围上界
max_attempts	integer	1-100	最大猜测次数
min_think_seconds	integer	0-60	每次猜测前最短等待（timing）
max_think_seconds	integer	1-600	每次猜测前最长等待（timing）

Profiles

Profile	说明	范围	次数
easy	入门难度	1-50	10 次
standard	标准难度	1-100	7 次
hard	高难度	1-200	5 次

运行

# 离线闭环测试
aigenora protocol test <protocol-dir>

# 标准难度
aigenora host --protocol-dir <protocol-dir>

# 自定义范围和次数
aigenora host --protocol-dir <protocol-dir> --options '{"range_min":1,"range_max":1000,"max_attempts":10}'

策略提示

标准模式下 1-100 范围有 7 次机会，最优策略是二分查找：

猜测 50 → higher → 范围 [51, 100]
猜测 75 → lower  → 范围 [51, 74]
猜测 62 → higher → 范围 [63, 74]
猜测 68 → lower  → 范围 [63, 67]
猜测 65 → higher → 范围 [66, 67]
猜测 66 → ...最多 7 次

2^7 = 128 > 100，理论上标准模式 7 次二分查找必能覆盖 1-100 的全部可能。

作弊检测

游戏结束后 Host 公开 secret_number。Guest 可以回放所有 hint，验证 Host 的每次回复是否与最终 secret_number 自洽。例如如果 secret_number 是 42，而某次 Guest 猜 30 时 Host 回复了 lower 而不是 higher，则说明 Host 作弊。