中国象棋云库API接口说明

 

概述

 

中国象棋云库(简称"云库") API 接口分为两部分,访问云库,可以直接通过基于 HTTP 的 RESTful API 实现。

此外,在原有的 UCI 引擎通讯协议上扩展了云库相关的指令,云库、界面及引擎各自分工,更加清晰便捷地处理开局库、思考细节和残局库数据。

 

RESTful API 接口

 

云库 API 接口访问格式为:http://api.chessdb.cn:81/chessdb.php?action=[ACTION]{&[OPTION1]=[VALUE1]...&[OPTIONn]=[VALUEn]}

 

其中各项定义为:

 

ACTION:操作类型,例如查询所有着法信息 (queryall)、自动出步 (query / querybest)、提交后台计算 (queue) 等

 

OPTION & VALUE:设置参数,例如设置局面 (board) 、设置禁着 (ban) 等

 

查询所有着法信息 (queryall)

 

必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w

 

可选参数:ban,设置为禁止着法列表,以 | 号分隔,例如 &ban=move:c3c4|move:b2e2|move:c0e2 ,默认为空,允许所有着法

 

可选参数:showall,设置为是否只返回未知着法,例如 &showall=0 或 &showall=1 ,默认为0,只返回已知着法数据

 

可选参数:egtbmetric,设置为残局库类型,例如 &egtbmetric=dtc 或 &egtbmetric=dtm ,默认为 dtm ,使用 DTM 残局库

 

可选参数:learn,设置为是否自动学习该局面的相关着法,例如 &learn=0 或 &learn=1 ,默认为1,自动学习与该局面有关的着法

 

返回结果:以 | 号分隔的着法信息,每项包含以 , 号分隔的着法 (move)、分值 (score)、排序 (rank) 及备注 (note)

 

若局面代码错误,返回 invalid board ,若所查询的局面没有已知着法,返回 unknown ,若走棋方被将死或困毙,返回 checkmate / stalemate

 

查询最佳、随机或候选着法 (querybest/query/querysearch)

 

必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w

 

可选参数:ban,设置为禁止着法列表,以 | 号分隔,例如 &ban=move:c3c4|move:b2e2|move:c0e2 ,默认为空,允许所有着法

 

可选参数:endgame,设置为是否只返回残局库数据,例如 &endgame=0 或 &endgame=1 ,默认为0,返回所有数据

 

可选参数:egtbmetric,设置为残局库类型,例如 &egtbmetric=dtc 或 &egtbmetric=dtm ,默认为 dtm ,使用 DTM 残局库

 

可选参数:learn,设置为是否自动学习该局面的相关着法,例如 &learn=0 或 &learn=1 ,默认为1,自动学习与该局面有关的着法

 

返回结果:以 | 号分隔的着法信息,常规着法为 move:[MOVE] ,残局库着法为 egtb:[MOVE] ,候选着法为 search:[MOVE

 

候选着法需引擎进一步计算,此时可将这些着法以 searchmoves 的形式发送给引擎

 

若局面代码错误,返回 invalid board ,若所查询的局面没有符合自动出步规则的着法,返回 nobestmove

 

查询评估分值 (queryscore)

 

必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w

 

可选参数:ban,设置为禁止着法列表,以 | 号分隔,例如 &ban=move:c3c4|move:b2e2|move:c0e2 ,默认为空,允许所有着法

 

可选参数:egtbmetric,设置为残局库类型,例如 &egtbmetric=dtc 或 &egtbmetric=dtm ,默认为 dtm ,使用 DTM 残局库

 

可选参数:learn,设置为是否自动学习该局面的相关着法,例如 &learn=0 或 &learn=1 ,默认为1,自动学习与该局面有关的着法

 

返回结果:云库对该局面的评估分值,格式为 eval:[SCORE]

 

若局面代码错误,返回 invalid board ,若所查询的局面没有已知评估数据,返回 unknown

 

查询思考细节 (querypv)

 

必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w

 

可选参数:ban,设置为禁止着法列表,以 | 号分隔,例如 &ban=move:c3c4|move:b2e2|move:c0e2 ,默认为空,允许所有着法

 

可选参数:egtbmetric,设置为残局库类型,例如 &egtbmetric=dtc 或 &egtbmetric=dtm ,默认为 dtm ,使用 DTM 残局库

 

可选参数:learn,设置为是否自动学习该局面的相关着法,例如 &learn=0 或 &learn=1 ,默认为1,自动学习与该局面有关的着法

 

返回结果:云库对该局面的思考细节,格式为 score:[SCORE],depth:[DEPTH],pv:[MOVE1]{...|[MOVEn]}

 

若局面代码错误,返回 invalid board ,若所查询的局面没有已知思考细节,返回 unknown

 

查询棋规裁定 (queryrule)

 

必须参数:board,设置为 FEN 格式的起始局面代码,例如 &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w

 

必须参数:movelist,设置为历史着法,以 | 号分隔,例如 &movelist=c3c4|g6g5|h2g2|h7e7,需要至少4个历史着法

 

可选参数:reptimes,设置为从第几次循环开始裁定,范围为1~10,例如 &reptimes=3 ,默认为1,循环一次即裁定

 

返回结果:从起始局面按照历史着法走棋后,最终局面各着法的棋规裁定结果,以 | 号分隔,格式为 move:[MOVE],rule:[RESULT]

 

其中 RESULT 表示裁定结果, none 表示不涉及棋规, draw 表示和棋, ban 表示犯规

 

若起始局面代码错误,返回 invalid board ,若历史着法不足或错误,返回 invalid movelist ,若走棋方被将死或困毙,返回 checkmate / stalemate

 

提交后台计算 (queue)

 

必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w

 

返回结果:ok 表示成功

 

若局面代码错误,返回 invalid board ,若所提交的的内容被云库筛选策略过滤,返回空

 

提交学习局面着法 (store)

 

必须参数:board,设置为 FEN 格式的局面代码,例如 &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w

 

必须参数:move,设置为需要提交学习的着法,例如 &move=move:c3c4

 

返回结果:ok 表示成功

 

若局面代码错误,返回 invalid board ,若所提交的的内容被云库筛选策略过滤,返回空

 

UCI 协议扩展

 

通常情况下,应由界面实现以上的云库访问操作,引擎无需与云库直接通讯。

界面可以通过扩展 UCI 协议,将更多信息告知引擎,引擎可以借助云库的思考细节加速计算,并更加灵活地控制开局库、残局库的使用。

 

开局库着法提示 (bookmove)

 

向引擎发送 go 命令时,附加 bookmove [MOVE] ,告知引擎开局库着法,引擎自行判断是否采纳,可以立即返回 bestmove [MOVE] 或开始计算

 

此项在分析模式 (go infinite) 或后台思考 (go ponder) 时无效,并位于 searchmoves 之前

 

思考细节提示 (hint)

 

在引擎计算过程中,向引擎发送 hint score [SCORE] depth [DEPTH] pv [MOVE1]{... [MOVEn]} ,告知引擎思考细节

 

残局库着法提示 (egtbmove)

 

向引擎发送 go 命令时,附加 egtbmove [MOVE] ,告知引擎残局库着法,引擎自行判断是否采纳,可以立即返回 bestmove [MOVE] 或开始计算

 

此项在分析模式 (go infinite) 或后台思考 (go ponder) 时无效,并位于 searchmoves 之前