UCI协议
以下用法按 official Pikafish 的提交 1c66b9b 核对。命令如何启动和结束一次搜索,另见 引擎运行与通信。
一次完整分析怎样交接?
以下是界面依次发送的命令示例。先等 uciok,再设置选项;收到 readyok 后设置局面并开始分析:
uci
setoption name Threads value 2
isready
position startpos moves b0c2 b9c7
go movetime 1000b0c2、b9c7 分别是红黑马从初始位置走出。引擎建立这两步的历史,再按一秒步时搜索,过程中输出 info,结束输出 bestmove。界面根据 bestmove 落子,并在下一次分析前发送更新后的 position。
如果使用 go infinite,结束时发送 stop 并等待 bestmove。等待期间继续读取标准输出,才能让线程完成交接;换局面或改选项放在本次搜索结束之后。
quit
请求停止搜索并退出引擎。若搜索仍在进行,会先等待工作线程收尾,期间可能还有搜索结果或 bestmove 输出。
ucinewgame
进行新的一局时,界面应向引擎发送 ucinewgame 指令以清除置换表和搜索历史等。该指令不负责设置开局局面,仍需发送 position。执行可能需要一段时间,界面可在之后使用 isready 确认前面的处理已完成。若原有搜索尚未结束,应先发送 stop 并等待 bestmove。
setoption
设置引擎选项,用法:
setoption name <id> [value <x>]其中,<id> 是 UCI 选项名,<x> 是你要设置的值。
例如界面要将引擎的线程数设置为 16,可发送:
setoption name Threads value 16某些选项,如 Clear Hash(清空置换表),可省略 value 直接使用,例如:
setoption name Clear Hash关于 UCI 选项,详见“UCI选项”页面,这里不再赘述。
修改选项前应先结束搜索。部分设置会输出 info string 等状态信息;未知选项或无效设置也可能产生提示,不能依赖“完全没有输出”。
isready
用于确认引擎能够应答,收到后输出 readyok。搜索期间也可回复,因此 readyok 不代表搜索已经结束;结束搜索应使用 stop 并等待 bestmove。
uci
用于获取引擎相关信息(如名称、作者、UCI 选项等)。下面是旧版的输出示例,具体选项、默认值和范围应以正在使用的引擎输出为准:
id name Pikafish 2024-02-18
id author the Pikafish developers (see AUTHORS file)
option name Debug Log File type string default
option name Threads type spin default 1 min 1 max 1024
option name Hash type spin default 16 min 1 max 33554432
option name Clear Hash type button
option name Ponder type check default false
option name MultiPV type spin default 1 min 1 max 128
...
uciok其中,uciok 是必需的。如果界面输入 uci 后,没有接收到引擎输出的 uciok,那么界面会认为该程序不是 UCI 引擎。
position fen
给引擎输入 FEN 局面。
例如:
position fen 3k1a3/4a4/5n3/9/9/9/9/9/9/4KR3 w或者在此基础上加上 movelist(历史着法):
position fen 5a3/3ka4/5n3/9/9/9/9/9/9/4K1R2 w - - 0 1 moves g0f0 d8d9注意
本页核对的 Pikafish 版本需要 position 前缀,不能直接发送裸 FEN。坐标着法的列为 a 至 i,行为 0 至 9。附带历史着法有助于引擎判断重复、长将和长捉;只有最后一张 FEN 不能还原完整历史。
成功设置通常没有直接回复;局面或历史着法出错时,当前实现会输出 CRITICAL ERROR 并退出。
position startpos
设置当前局面为起始局面(rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w)。也可在后面附加 moves 和历史着法;需要保留 position 前缀。
成功设置通常没有直接回复;非法历史着法会导致错误输出并退出。
go
让引擎分析当前的局面(当前局面可通过 position 指令设置)。
可以加入以下参数:
searchmoves <move1> <move2> ... <movei>:指定搜索的走法(界面“变招”功能需要使用该参数),在当前解析器中必须放在本行其他参数之后。UCI 协议中没有banmoves指令(这是 UCCI 协议中的)。infinite:无限制分析(直到发送stop)。ponder:后台思考。wtime,btime:红方和黑方剩下的时间(ms)。winc,binc:红方和黑方的加秒(ms)。movestogo:用于多少时间走多少步的时间制,告诉引擎获得新的时间还剩多少步,在中国象棋里面一般不会用到。depth:指定层数。nodes:指定搜索的节点数。mate:找到指定步数内的决定性胜负距离时停止搜索;不只限于己方获胜。movetime:指定步时(ms)。perft:统计到指定层数的合法走法路径数;一层是一方走一步,不执行正常评分搜索。
输入 go 后,引擎将搜索当前局面并输出搜索结果。达到对应的限制或用户发送 stop 指令后,引擎即终止搜索。
go infinite 需用 stop 结束;后台思考在预计着法命中时用 ponderhit 转为正常搜索。普通搜索收尾后会输出 bestmove,go perft 则输出路径统计。详见 搜索生命周期。
d
输出当前的局面、局面 FEN、key 信息和将军信息。该指令供引擎开发调试使用。
eval
输出当前局面的评估信息。该指令供引擎开发调试使用。
export_net
导出权重,可指定文件名。
flip
上下翻转棋盘,并交换红黑棋子和行棋方,主要用于检查评估的对称性。
compiler
输出编译器及引擎指令集信息。
bench
当前版本另有 speedtest 测速命令,工具用途与区别见 运行诊断。
