Weiqi Text Protocol
第22版
目录
1 前言1.1 概述
1.2 文本编码
1.3 通讯模式
1.4 辅助符号
2 文本格式
2.1 命令
2.1.1 命令格式
2.1.2 命令说明
2.2 响应
2.2.1 响应格式
2.2.1.1 命令有效或成功
2.2.1.2 命令无效或失败
2.2.2 响应说明
2.3 注释
2.3.1 注释格式
2.3.2 注释说明
3 文本类型
3.1 空
3.2 真假
3.3 整数
3.4 小数
3.5 颜色
3.6 着点
3.7 着手
3.8 局面
3.9 规则
3.10 时限
3.11 普通文本
4 内部状态
4.1 内部状态系列
4.2 内部状态缺省值
5 命令列表
5.1 基本命令
5.1.1 管理命令
5.1.1.1 协议版本
5.1.1.2 程序名称
5.1.1.3 程序版本
5.1.1.4 命令列表
5.1.1.5 退出
5.1.2 设置命令
5.1.2.1 设置路数
5.1.2.2 清空棋盘
5.1.2.3 设置局面
5.1.2.4 设置规则
5.1.2.5 设置时限
5.1.3 对弈命令
5.1.3.1 下子
5.1.3.2 生成着手
5.1.3.3 悔子
5.1.3.4 分析
5.1.3.5 停止
5.2 扩展命令
6 版权
7 致谢
1 前言
1.1 概述
本协议中文名称为"围棋文本协议"，英文名称为"Weiqi Text Protocol"，简称"WTP"。程序启动后如果在对自己的首次输入中获取字符串"WTP"或"wtp"，应理解为外部对象请求使用本协议与自己通讯。
1.2 文本编码
文本使用gb18030编码。1.3 通讯模式
程序与外部的交互通讯由“命令-响应”模式驱动。程序始终监测对自己的输入，获取文本后进行分析、处理，然后输出响应。在通讯过程中，程序是被动的，外部对象反复向程序发送命令，推动对弈的进行，直至终局、中止通讯。外部对象可能来自操作系统的控制台终端，或者是一个图形用户界面，或者是某种语言的脚本，或者是某种协议的计算机网络连接，但本协议并不关心它是谁。
1.4 辅助符号
在本协议中，下面的这些符号用来辅助说明文本的类型或使用方法，实际使用该文本时，并不包含这些符号。部分符号含义如下：( ) 圆括号。表示圆括号中的文本仅仅是对这个文本实际值的描述。使用时用实际的值代替这个文本。
[ ] 方括号。表示方括号中的文本是可选的。
... 省略号。表示重复前一字符，或者重复前一行文本。
" " 双引号。表示多字节文本。
' ' 单引号。表示单字节字符。
2 文本格式
2.1 命令
2.1.1 命令格式
格式如下：[id ]name[ argument]\n
实际运用的形式可能是下列之一：
name\n
name argument\n
id name\n
id name argument\n
2.1.2 命令说明
命令一般由命令名称和参数两部分组成，之间用一个空格符' '相隔。也可以没有参数。命令名称前可以加命令编号，与命令名称之间也用一个空格符' '分隔。用一个换行符'\n'表示一条命令结束。
命令与参数只能在一行中。一行命令只能有一个命令名称。
一次只能发送一行命令。
命令编号只能是不小于0的整数。
命令名称只能由下列字符组成：
小写拉丁字母；
下划线'_'；
连字符'-'。
命令名称只能小写拉丁字母开头。
命令参数中不能有下列字符，如果有将忽略：
小于十进制32的控制符；
删除符（十进制127）。
2.2 响应
2.2.1 响应格式
2.2.1.1 命令有效或成功
如果命令有效或成功，程序输出的文本为返回值。格式如下：
=[id][ value]\n\n
方括号中的部分是可选项。实际运用的形式可能是下列之一：
=\n\n
= value\n\n
=id\n\n
=id value\n\n
如果返回值是多行，格式如下：
=[id] value\n
...\n
value\n\n
方括号中的部分是可选项。实际运用的形式可能是下列之一：
= value\n
...\n
value\n\n
=id value\n
...\n
value\n\n
2.2.1.2 命令无效或失败
如果命令无效或失败，程序输出的文本为错误消息。格式如下：
?[id][ message]\n\n
方括号中的部分是可选项。实际运用的形式可能是下列之一：
?\n\n
? message\n\n
?id\n\n
?id message\n\n
如果错误消息是多行，格式如下：
?[id] message\n
...\n
message\n\n
方括号中的部分是可选项。实际运用的形式可能是下列之一：
? message\n
...\n
message\n\n
?id message\n
...\n
message\n\n
2.2.2 响应说明
响应一般由结果、返回值或错误消息两部分组成，之间用一个空格符' '分隔。也可以没有返回值或错误消息。如果认为命令有效或成功，结果以字符'='表示，该字符后面如有文本，是返回值；否则，以字符'?'表示，该字符后面如有文本，是错误消息。
如果接收的命令中含有命令编号，则在响应输出的字符'='或'?'后紧接着输出该命令编号。
用两个连续的换行符"\n\n"表示对一行命令的响应结束。
响应如果有多行，除最后一行外，每行结束用一个换行符'\n'表示。
返回值、错误消息可以是除下列字符外的其他任何字符：
小于十进制32的控制符，除换行符（十进制10）外；
删除符（十进制127）。
如果返回值、错误消息中含有上述字符，忽略掉，而不是视为无效。
2.3 注释
2.3.1 注释格式
格式如下：#text\n
如果注释是多行，格式如下：
#text\n
...
#text\n
2.3.2 注释说明
一行中字符'#'后面的文本为注释，可以忽略。用一个换行符'\n'表示一行中的注释结束。
注释可以出现在一行命令字符串的后半部分，或者一行响应字符串的后半部分。或者整行都是注释。
虽未接受命令的请求，程序也可以自行输出注释。
注释文本可以是任意可打印字符。
3 文本类型
命令的参数和响应的返回值是有类型的，程序和外部对象根据文本类型对参数和响应值进行分析、处理。3.1 空
格式如下：(null)
"(null)"在这里说明不是任何值，实际使用时没有任何字符来表示。
3.2 真假
格式如下：true|false
真为表示"true"，假表示为"false"。
3.3 整数
格式如下：int
以阿拉伯数字表示的十进制整数。
3.4 小数
格式如下：float
以阿拉伯数字表示的十进制小数。
3.5 颜色
格式如下：B|W|E
对局双方或棋盘点的颜色，用大写拉丁字母表示，黑方'B'，白方'W'，空点'E'。
3.6 着点
格式如下：XY|PASS|RESIGN
棋盘为正方形，有效范围5至25路。缺省为标准的19路。着点以先纵后横的棋盘坐标描述。以左下角为原点。从左到右为纵线X，用大写拉丁字母表示。从下到上为横线Y，以阿拉伯数字表示。纵线坐标有效范围'A'-'Z'，其中跳过字母'I'。横线坐标有效范围1-25。
如果是虚着，则以"PASS"表示。如果不下子而认输，以"RESIGN"表示。
如果是着点系列，两个着点间以空格符' '分隔。
3.7 着手
格式如下：(B|W) (XY|PASS|RESIGN)
由颜色和着点两部分组成。
如果是着手系列，从第二手开始省略颜色部分，该手颜色总是前一手的对方；两个着点间以空格符' '分隔。
3.8 局面
格式如下：B|W|E...
...
由棋盘各行下子点的颜色组成，到边路则换行。
3.9 规则
格式如下：name: value, ...
由名值对系列组成。名与值之间以冒号':'分隔，名值对之间以逗号','分隔。
有效模式如下：
name 一个表示规则名称的字串。如"Chinese"。
name: value 一个名值对。如"Komi: 7.5"。
name: value, ... 多个名值对组成的系列。如"Name: Chinese, Ko: Simple, Score: Area, Tax: None, WhiteHandicapBonus: N, Komi: 7.5, AllowMultiStoneSuicide: false, FriendPassOk: true"。
3.10 时限
格式如下：maintime overtime overcount
由基本时间（maintime）和读秒时间（overtime）、读秒次数（overcount）组成，以整数表示。时间单位为秒。
有效模式如下：
0 0 0 无时间限制。
maintime 0 0 使用基本时间。先用完基本时间的一方，超时判负。
0 overtime overcount 使用读秒时间。在读秒时间内下子，不扣除读秒次数。用时达到读秒时间，但未下子，扣除读秒次数一次。读秒次数为零的一方，超时判负。
maintime overtime overcount 基本时间内，对下子没有要求。基本时间用完后，使用读秒时间，下子按读秒规则进行。
3.11 普通文本
格式如下：string
除小于十进制32的控制符、删除符（十进制127）以外的字符组成的字符串。推荐单行长度为不要超过1024字节。
4 内部状态
4.1 内部状态系列
棋盘路数贴子
时限和用时
下子前的局面
着手历史
程序始终维护上述内部状态。这些状态是生成着手的基础，可能被外部改变。
4.2 内部状态缺省值
棋盘路数：19贴子：0
时限和用时：无
下子前的局面：空
着手历史：无
未经通讯改变，上述程序内部状态总是为缺省值。
5 命令列表
5.1 基本命令
遵循本协议的程序进行对弈必须支持的命令集。5.1.1 管理命令
5.1.1.1 协议版本
protocol_version参数：无。
影响：无。
失败：从不。
输出：整数。
说明：本协议版本号。支持的协议版本应当向下兼容。
5.1.1.2 程序名称
name参数：无。
影响：无。
失败：从不。
输出：普通文本。
说明：程序名称。不要包含版本号。
5.1.1.3 程序版本
version参数：无。
影响：无。
失败：从不。
输出：普通文本。
说明：程序的版本号。如果程序没有设置版本号，输出空。
5.1.1.4 命令列表
list_commands参数：无。
影响：无。
失败：从不。
输出：普通文本。多行。
说明：程序支持的本协议命令列表。每行一个命令名称。不能将多个命令名称放在一行，这样将被识别为一个命令。
5.1.1.5 退出
quit参数：无。
影响：程序与外部的会话中止，连接关闭。
失败：从不。
输出：无。
说明：退出交互通讯状态。在关闭与一个程序的连接前，必须调用此命令，在获得响应后再关闭连接，确保程序能作一些清理工作。
5.1.2 设置命令
5.1.2.1 设置路数
boardsize参数：整数。必需。
影响：棋盘路数。
失败：如果参数文本格式错误、不支持指定路数。
输出：无。如果失败，输出错误消息。
说明：设置棋盘路数。如果是标准19路棋盘，无需发送此命令。
5.1.2.2 清空棋盘
clear_board参数：无。
影响：下子前的局面、着手历史。
失败：从不。
输出：无。
说明：下子前的局面、着手历史设置为缺省值。
5.1.2.3 设置局面
set_position参数：着手系列。必需。
影响：下子前的局面。
失败：如果参数文本格式错误、着手无效。
输出：无。如果失败，输出错误消息。
说明：设置下子前的原始局面。如果执行此命令前棋盘非空，将先清空棋盘。
5.1.2.4 设置规则
rule参数：规则。必需。
影响：规则。
失败：如果参数文本格式错误、不支持指定规则。
输出：无。如果失败，输出错误消息。
说明：规则选项由名值对组成，如果不识别或不支持某个选项，不该视为错误，而应忽略它。
5.1.2.5 设置时限
time_settings参数：时限。必需。
影响：时限。
失败：如果参数文本格式错误。
输出：无。如果失败，输出错误消息。
说明：设置时限。
5.1.3 对弈命令
5.1.3.1 下子
play参数：着手。必需。
影响：着手历史。
失败：参数文本格式错误、着手无效。
输出：无。如果失败，输出错误消息。
说明：下子。
5.1.3.2 生成着手
genmove参数：颜色。必需。
影响：着手历史。
失败：从不。
输出：着点。
说明：生成着手并在程序内部下子。
5.1.3.3 悔子
undo参数：无或整数。
影响：着手历史。
失败：如果程序没有正式着手可取消。
输出：无。如果失败，输出错误消息。
说明：取消最后一手着手。
5.1.3.4 分析
analyze参数：颜色。必需。
影响：无。
失败：从不。
输出：着点信息。
说明：分析当前局面，输出下子候选着点信息。
5.1.3.5 停止
stop参数：无。
影响：无。
失败：从不。
输出：无。
说明：停止任何正在进行的思考或分析。
5.2 扩展命令
一个程序可以根据需要，添加自定义的扩展命令，但不能与本协议已定义的命令同名，不能修改或覆盖本协议已定义的命令。同时，命令及响应的文本格式应当遵守本协议的规范。推荐在创建一个扩展命令时，按如下格式给出命令的说明：
名称
参数：(有无，类型)。
影响：(有无，被改变的内部状态)。
失败：(会否，原因)。
输出：(有无，类型)。
说明：(使用指导)。