review-markdown-comments

Markdown コメントのレビュー

ユーザーが指定した Markdown ファイルを直接編集します。

コメント形式

Hubble は、次のポータブルなサブセットを使って Markdown の本文にレビュー状態を保存します。

{==anchored text==}{>>comment body<<}{#c1}
{++suggested insertion++}
{--suggested deletion--}
{~~original text~>replacement text~~}

スレッドの状態は、コメントアンカーの後に、生の JSON を格納した HTML コメントとして続くことがあります。 URI エンコードされていません。Hubble は JSON.parse で直接解析するため、エンコードされたペイロードは解析に失敗し、ノートにリテラルテキストとして表示されます。

Hubble では v、replies、resolved が使われますが、その他のトップレベルキーも指定できます。 必ず "v": 1 としてください。JSON 内の -- は \u002d\u002d にエスケープしてください。リテラルの -- があると HTML コメントが早期に終了するためです。返信の形式は次のとおりです。

{
  "id": "r1",
  "body": "Agent response",
  "author": "agent",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

インラインコードまたはフェンス付きコード内のレビュー マーカーは、コメントではなくリテラルテキストです。

コメントへの対応

1. ファイル全体を読みます。{#c7} のような指定されたコンパクト ID を探します。ユーザーがアンカー付きテキストのみを指定した場合は、代わりに CriticMarkup アンカーを正確に探します。アンカー付きテキストとコメント本文がユーザーの依頼に一致することを確認します。ID または正確なアンカーが見つからない、あるいは曖昧な場合は、作業を中止してその旨を伝えます。
2. 論理コメントの直後にある JSON メタデータを解析します。存在しない場合は、空のオブジェクトから始めます。不正な形式の場合は、上書きせずに中止します。
3. メタデータを往復させます。変更するのは返信リストと resolved のみとし、完全なオブジェクトを再シリアライズします。他のすべてのキーと既存の返信はそのまま保持します。返信は追記のみです。次に未使用の rN ID、author: "agent"、返信本文、現在の UTC 時刻を ISO 8601 形式で指定した createdAt を持つ返信を追加します。
4. ユーザーの依頼に実際に対応できた場合に限り、resolved: true に設定します。明示的な再オープンの依頼の場合は、resolved: false に設定します。了承、テスト、質問、部分的な作業の場合は false のままにします。
5. メタデータブロックはコメントの {#cN} マーカーの直後に記述します（「分割されたアンカー」を参照）。アンカー付きテキストはバイト単位で変更せず、コメント本文、CriticMarkup の区切り記号、提案された編集、無関係な Markdown もすべてそのまま保持します。

分割されたアンカー

1 つの論理コメント ID が複数の CriticMarkup フラグメントに出現することがあります。最後のフラグメントが正式なものです。すべてのマーカーを保持し、メタデータブロックは 1 つだけにして、最後のフラグメントの後に配置します。現在それより前のフラグメントに続いている場合は、そこから移動します。分割によってユーザーの書式設定に影響する可能性がある場合は、その旨を伝えます。

検証

編集後に次の確認を行います。

1. ファイルを再度読み込み、依頼された ID と正確なアンカー付きテキストが残っていることを確認します。
2. 最後のフラグメントの後にあるメタデータを解析し、有効な JSON であること、新しい返信が最後の返信であること、既存の返信とその他のキーが往復して保持されていること、resolved が意図した値であることを確認します。ノートに生のブロックがテキストとして表示されず、コメントが描画されることも確認します。
3. 周辺の Markdown に意図しない変更がないか確認します。追跡対象のファイルでは git diff -- <file> を調べ、無視対象または生成されたファイルでは編集前後のテキストを比較します。
4. 追加した返信と、コメントを解決済みにしたかどうかを報告します。