注意

これは、思考コメントの仕様のドラフト（草案）です。

ドラフトとは言っても、既に Electron 将棋はこの内容を前提に実装しています。

はじめに

エンジンの思考結果を棋譜コメントに書き込む際のフォーマットを定めます。

背景

エンジンの読み筋や評価値を記録する方法として、よく既存の棋譜フォーマットのコメント行が用いられます。 KIF 形式や CSA 形式はコメント行のプレフィクスを規定しています。 しかし、コメントに読み筋や評価値などの情報を書く方法を定めているわけではありません。 エンジンの思考に関する情報は、各アプリケーションが独自のフォーマットで書いているのが実情です。

主に出回っているデータは Floodgate や ShogiGUI、ぴよ将棋などによって出力されたものだと考えられます。

Floodgate の記法 はエンジン開発者の間で認知されていますが、一般のユーザーが事前知識無しで理解できる表記ではありません。 また、読み筋と評価値以外の情報を書く方法は規定していません。

ShogiGUI の記法はスペース区切りで 1 行に全ての情報を記載します。 Floodgate と違って、日本語の項目名や KIF 形式の指し手表記が使われるため、そのままでも一般ユーザーにとってある程度読みやすい表記です。 しかし、細かい仕様が明記されておらず、いくつかのアプリケーションが同様の表記を用いているものの、ShogiGUI との互換性が必ずしも担保されているわけではないようです。

ぴよ将棋の記法については、ドキュメントが見つかっておらず、同じ表記に対応した他のソフトウェアも見つかっていません。

仕様

構文

KIF形式、KI2形式またはCSA形式のコメント行に次の形式でキーと値のペアを書きます。

構文 (# と * の使い分けは後述):
#{キー}={値}
*{キー}={値}

正規表現:
^[*#][^*#= ]+=.*$`

例1:
*読み筋=△３二金▲２四歩

例2:
#評価値=-290

KIF 形式や KI2 形式ではコメントの先頭にアスタリスク * を付与するため、それらの形式で書き出す際の 1 行の出力は **Name=Value または *#Name=Value となります。 CSA 形式の場合は Floodgate の拡張仕様 にならってコメントの先頭にアポストロフィーとアスタリスク '* を付与し、 '**Name=Value または '*#Name=Value となります。

行頭の * と # は次のように使い分けます。

• * : 対局したエンジンの情報
• # : 対局外（検討・解析）の情報

キー名に * や # 、 = を含めることはできません。 行頭から最初のイコール = までにスペースを含めることはできません。 イコール = の後から行末（改行を含まない）までの全ての文字が Value に該当します。 Value は空文字やスペースだけで構成することもできます。 ただし、 Value に数値や定義済みの名前を書く場合はスペースを含めてはいけません。

1 回の思考に関する情報は連続した行にまとめて書きます。 逆に、対局時と検討時の両方の情報を記載する、あるいは複数回実行した検討結果を記載する場合は、本仕様のキーと値のペアではない行（空行でも良い）を 1 行以上挟まなければなりません。 以下は対局に加えて 2 回の棋譜解析を行った場合の例です。

対局エンジンの思考結果
*Name11=Value11
*Name12=Value12

解析エンジンの思考結果A
#Name21=Value21
#Name22=Value22

解析エンジンの思考結果B
#Name31=Value31
#Name32=Value32

項目の種類

現在定義済みの項目は次の表の通りです。 新しいキー名が今後追加される可能性があります。 数値を扱う項目は、言及がない限り実数を含めた 10 進数であるものとします。

キー	値	整形用の空白文字	説明	Electron将棋実装Ver.
評価値	数値	不可	先手から見た評価値（先手有利が正の値）	v1.3.0
詰み	（後述）	不可	即詰みがある場合にその勝敗と手数を示す。	v1.10.0
読み筋	KI2 の指し手表記	可(指し手と指し手の間のみ)	例: △３二金▲２四歩	v1.3.0
深さ	数値	不可	USI の depth に相当	v1.7.0
ノード数	数値(自然数)	不可		v1.14.0
エンジン	改行以外の任意の文字列	不可（空白もエンジン名の一部とみなす）		v1.7.0

「詰み」の値は以下の形式とします。

構文:
{勝敗}
{勝敗}:{詰手数}手

正規表現:
(先手勝ち|後手勝ち)(:[0-9]+手)?

例えば 先手勝ち:15手 なら後手玉に 15 手詰みが生じていることを表します。 なお、あくまでも個々のエンジンが主張する値を示すものなので、最短手数であることや詰んでいることを保証するものではありません。 記載すべき手数の情報が無い場合には勝敗だけを書きます。

NOTE: Electron 将棋の古いバージョンについて

Electron 将棋の古いバージョンでは読み筋に KIF 形式に似た表記（ △３二金(41)▲２四歩(25) のように移動元の座標を括弧内に書く方法）を使用していました。 そのため Electron 将棋では KIF 形式と KI2 形式のどちらでも読み込み可能になっていますが、人にとっての読みやすさを考慮して原則 KI2 形式で表記するものとします。

NOTE: 使用する記号について

近年では Unicode に ☗ や ☖ が登録されているため、インターネット上でこれらの文字をよく見かけるようになりました。 しかし、 KIF 形式や KI2 形式ではまだ Shift_JIS を使うユーザーが多いことを考えると、コメント中にこれらの文字を含めないほうが無難です。 そのため、本仕様では従来の KI2 にならって ▲ や △ を用いるものとします。

ユーザー定義の項目

このドキュメントで定義されない Name を使用することも可能ですが、以下の指針に従うものとします。

• Name は値を指し示すのに適した名詞を選ぶ。
  • Name と Value が is の関係になる。
  • 別の意味で使われそうな言葉を避ける。
  • 全角スペースや一部の記号など視認しづらい文字を使用しない。
• Name と Value の解釈が自明でない場合は、 Name にアプリケーション固有のプレフィクスを付ける。
  • 他のアプリケーションでも使うことになりそうな名前だったり、値の書き方が一通りに限定されないものだとトラブルになりやすい。
  • 例: Electron 将棋なら ES- を付ける。
• 評価値は先手から見た値を記す。
  • 後手の指し手のコメントにおいても正の値が先手有利、負の値が後手有利を表す。
  • ただし、評価値の差を表す値（2手前からどれだけ有利になったか、等）はその限りではない。
• Shift_JIS で表せない文字を使用しない。
  • KIF 形式や KI2 形式では UTF-8 への移行が進んでいないため互換性を意識する。

サンプル

互角
#評価値=92
#読み筋=△８五歩▲７八金△８六歩▲同　歩△同　飛▲２四歩△同　歩▲同　飛△３二金▲３四飛△３三角▲５八玉△７六飛▲７七角△５二玉▲８四飛△８二歩▲８三歩△７二金▲８二歩成△同　銀
#深さ=15
#エンジン=たぬきHao や王7.6.1（検討用1スレ）

互角
*評価値=101
*読み筋=△８五歩▲７八金△３二金▲２四歩△同　歩▲同　飛△８六歩▲同　歩△同　飛▲３四飛△３三角▲６八玉△７六飛▲３六歩△５二玉▲３七桂△７四飛▲同　飛△同　歩▲３八銀△２八飛▲３三角成△同　桂▲８三角△２二飛成▲７四角成△２八龍
*深さ=23