国际象棋云库(简称"云库") API 接口分为两部分,访问云库,可以直接通过基于 HTTP 的 RESTful API 实现。
此外,在原有的 UCI 引擎通讯协议上扩展了云库相关的指令,云库、界面及引擎各自分工,更加清晰便捷地处理开局库、思考细节和残局库数据。
云库 API 接口访问格式为:http://www.chessdb.cn/cdb.php?action=[ACTION]{&[OPTION1]=[VALUE1]...&[OPTIONn]=[VALUEn]}
其中各项定义为:
ACTION:操作类型,例如查询所有着法信息 (queryall)、自动出步 (query / querybest)、提交后台计算 (queue) 等
OPTION & VALUE:设置参数,例如设置局面 (board) 、设置是否自动学习 (learn) 等
必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
可选参数:showall,设置为是否只返回未知着法,例如 &showall=0 或 &showall=1 ,默认为0,只返回已知着法数据
可选参数:egtbmetric,设置为残局库类型,例如 &egtbmetric=dtz 或 &egtbmetric=dtm ,默认为 dtz ,使用 DTZ 残局库
可选参数:learn,设置为是否自动学习该局面的相关着法,例如 &learn=0 或 &learn=1 ,默认为1,自动学习与该局面有关的着法
返回结果:以 | 号分隔的着法信息,每项包含以 , 号分隔的着法 (move)、分值 (score)、排序 (rank)、胜率 (winrate) 及备注 (note)
若局面代码错误,返回 invalid board ,若所查询的局面没有已知着法,返回 unknown ,若走棋方被将死或困毙,返回 checkmate / stalemate
必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
可选参数:endgame,设置为是否只返回残局库数据,例如 &endgame=0 或 &endgame=1 ,默认为0,返回所有数据
可选参数:egtbmetric,设置为残局库类型,例如 &egtbmetric=dtz 或 &egtbmetric=dtm ,默认为 dtz ,使用 DTZ 残局库
可选参数:learn,设置为是否自动学习该局面的相关着法,例如 &learn=0 或 &learn=1 ,默认为1,自动学习与该局面有关的着法
返回结果:以 | 号分隔的着法信息,常规着法为 move:[MOVE] ,残局库着法为 egtb:[MOVE] ,候选着法为 search:[MOVE]
候选着法需引擎进一步计算,此时可将这些着法以 searchmoves 的形式发送给引擎
若局面代码错误,返回 invalid board ,若所查询的局面没有符合自动出步规则的着法,返回 nobestmove
必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
可选参数:egtbmetric,设置为残局库类型,例如 &egtbmetric=dtz 或 &egtbmetric=dtm ,默认为 dtz ,使用 DTZ 残局库
可选参数:learn,设置为是否自动学习该局面的相关着法,例如 &learn=0 或 &learn=1 ,默认为1,自动学习与该局面有关的着法
返回结果:云库对该局面的评估分值,格式为 eval:[SCORE]
若局面代码错误,返回 invalid board ,若所查询的局面没有已知评估数据,返回 unknown
必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
可选参数:egtbmetric,设置为残局库类型,例如 &egtbmetric=dtz 或 &egtbmetric=dtm ,默认为 dtz ,使用 DTZ 残局库
可选参数:learn,设置为是否自动学习该局面的相关着法,例如 &learn=0 或 &learn=1 ,默认为1,自动学习与该局面有关的着法
返回结果:云库对该局面的思考细节,格式为 score:[SCORE],depth:[DEPTH],pv:[MOVE1]{...|[MOVEn]}
若局面代码错误,返回 invalid board ,若所查询的局面没有已知思考细节,返回 unknown
必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
返回结果:ok 表示成功
若局面代码错误,返回 invalid board ,若所提交的的内容被云库筛选策略过滤,返回空
必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
必须参数:move,设置为需要提交学习的着法,例如 &move=move:c3c4
返回结果:ok 表示成功
若局面代码错误,返回 invalid board ,若所提交的的内容被云库筛选策略过滤,返回空
通常情况下,应由界面实现以上的云库访问操作,引擎无需与云库直接通讯。
界面可以通过扩展 UCI 协议,将更多信息告知引擎,引擎可以借助云库的思考细节加速计算,并更加灵活地控制开局库、残局库的使用。
向引擎发送 go 命令时,附加 bookmove [MOVE] ,告知引擎开局库着法,引擎自行判断是否采纳,可以立即返回 bestmove [MOVE] 或开始计算
此项在分析模式 (go infinite) 或后台思考 (go ponder) 时无效,并位于 searchmoves 之前
在引擎计算过程中,向引擎发送 hint score [SCORE] depth [DEPTH] pv [MOVE1]{... [MOVEn]} ,告知引擎思考细节
向引擎发送 go 命令时,附加 egtbmove [MOVE] ,告知引擎残局库着法,引擎自行判断是否采纳,可以立即返回 bestmove [MOVE] 或开始计算
此项在分析模式 (go infinite) 或后台思考 (go ponder) 时无效,并位于 searchmoves 之前