mdnote

mdnote のレビューループ

注釈は、ブラウザー UI から作成され、ファイルの隣にあるサイドカーファイル（<file>.mdnote.json）に保存されます。ブラウザーは開かず、CLI のみを使用します。

サーバーが停止していても、comments と clear は動作し、サイドカーファイルにフォールバックします。mdnote は ~/.bun/bin にインストールされる bun スクリプトです。非対話型シェルで mdnote または bun が見つからない場合は、~/.bun/bin と mise の shim ディレクトリ（~/.local/share/mise/shims）を PATH の先頭に追加してください。

1. レビューを開始する（すでに実行中の場合はスキップ）

ユーザーがまだ実行していない場合（不明な場合は確認してください）、サーバーを起動します。

mdnote <file.md>

バックグラウンド、または別のターミナルで実行してください。ページを配信してブラウザーを開き、ライブリロードのために実行状態を維持します。ユーザーが別の場所にバインドしたい場合は、--host／--port を指定できます。ローカルで使う場合はデフォルトで問題ありません。

ユーザーにファイルを渡し、レビューが終わるまで待機するには、手順 1～2 の代わりにこちらを使用します。

mdnote wait <file.md>

ユーザー用にページを開き（ページ内のバーに待機中であることが表示されます）、ユーザーが Submit をクリックするまで待機して、標準出力に 1 つの JSON エンベロープ {path, submittedAt, annotations} を出力します。annotations が空なら、そのままで承認されたという意味です。そのまま進んでください。それ以外の場合は、エンベロープの注釈を使って手順 3 に進みます。フォアグラウンドで実行し、数分待つ可能性に備えてください。タイムアウトはありません。各注釈には、最初に受信した時点の round 番号が付与されます。そのため、再度待機したときに古い round の注釈は、すでに確認済みのものです（未解決のままである理由は、まだクリアしていないためです）。

2. 注釈を取得する

mdnote comments <file.md> --json

{file, annotations} を返します。各注釈の内容は次のとおりです。

• lineRange：[start, end]。ソースの行番号（1 始まり、範囲に両端を含む）。文書全体への注釈の場合は null
• anchorText：選択されたテキストそのもの。文書全体への注釈の場合は null
• columnRange：[start, end]。選択範囲の列番号（1 始まり、範囲に両端を含む）。start は lineRange[0] の行、end は lineRange[1] の行にあります
• textBefore、textAfter：範囲の直前と直後にあるソース文字をそれぞれ最大 24 文字分。範囲の先頭行と末尾行から取得されます（行端では空文字列）
• note：指示
• status：open | stale

status: "open" のものだけを処理してください。

3. 各注釈を適用する

note は、アンカーされた範囲に対する自由形式の指示です。「もっと簡潔に」なら修正し、「削除」なら削除する、といった具合です。anchorText が null の場合、注釈は文書全体を対象としています。ファイル全体に適用してください。

lineRange を使って該当箇所に移動し、anchorText と照合して正しい範囲であることを確認してください（同じ処理中の以前の編集で行番号がずれている可能性があるため、古い行番号を信用せず、必ず再確認してください）。

columnRange、textBefore、textAfter はテキスト選択の場合にのみ一緒に指定され、1 行に anchorText が複数回あるときに、ユーザーが選択した箇所を特定するための情報です。ソースは lineRange[0] の行から textBefore + <span> + textAfter の順に並んでいます。anchorText は表示上のテキストであるため、ソースの範囲とは異なる場合があります（範囲内に ** や改行が含まれるなど）。anchorText がソースにそのまま現れる場合は、textBefore + anchorText + textAfter を検索してください。その文字列が見つからないか、一意でない場合は、columnRange で範囲を切り出してください。1 行の範囲の場合、lineRange[0] の columnRange[0] - 1 から columnRange[1] の直前までの文字です。これは JS の文字列インデックス（UTF-16 コード単位）で数えます。複数行にまたがる範囲の場合は、その開始列から lineRange[1] の columnRange[1] の列までです。3 つのフィールドがない場合、mdnote では該当箇所を特定できませんでした。lineRange と anchorText のみを頼りにし、行が曖昧な場合はユーザーに確認してください。

4. 対応済みの注釈をクリアする

mdnote clear <file.md> --ids <id>,<id>,...

対応したすべての ID を、カンマ区切りで 1 回の呼び出しに渡してください。完了後にすべてを一度にクリアすることもできます。

mdnote clear <file.md>

ページは自動でライブリロードされるため、操作する必要はありません。

5. 繰り返し

mdnote comments <file.md> --json を再実行します。open アノテーションが返されなくなるまで、編集と解消を繰り返します。

古いアノテーション（status: "stale"。編集後にアンカーテキストが見つからなくなったもの）は、推測で判断するものではありません。解消したり、別の意味に解釈し直したりせず、ユーザーに提示して手動で再確認してもらいます。