human-review

human-review

ユーザーは実際のブラウザーで、HTML、Markdown、または localhost のページをレビューします。入力して細かな修正を行い、コメントしたい箇所を選択して、フィードバックをまとめて送信します。

Markdown ファイルはレンダリングされた状態で開きます。引用や編集はレンダリングされたテキストを参照しますが、ファイル自体には一切手を加えません。書式構文を維持しながら、すべての変更を Markdown ソースに適用してください。

一連の流れ

1. HTML または Markdown ファイルを書き込むか更新するか、レビュー対象のローカルページを起動します。

2. ユーザーがレビューできるように開きます。

   npx -y human-review path/to/file.html
   

   ローカル開発サーバーで配信されるページの場合は、別の HTML ファイルとして作り直すのではなく、実際のルートを開きます。

   npx -y human-review http://localhost:3000/wiki
   

3. フィードバックを待ちます。このコマンドは、ユーザーがブラウザーで「送信」を押すまでブロックし、その後、フィードバックの一括分を出力して終了します。

   npx -y human-review poll path/to/file.html
   

   このコマンドは、ユーザーが「送信」をクリックするか、レビューを閉じたときにのみ終了します。再実行する必要はなく、ポーリングの間隔を設定する必要も、--timeout を追加する必要もありません。ローカルサーバーが再起動しても動作し、ポーリングが終了してもフィードバックは保存されるため、失われることはありません。待機方法は、使用しているハーネスによって異なります。

   • Claude Code： run_in_background: true を指定して実行し、ターンを終了します。コマンドが終了すると、出力とともに Claude Code がすぐに再開します。

   • Codex、Cursor、およびその他すべて： アクティブなターン内でフォアグラウンド実行し、feedback または closed が出力されるまで待機します。コマンドをデタッチしたり、バックグラウンドセッションとして起動したりしないでください。デタッチしたコマンドが終了しても、通知されません。レビュー中は、次のようにします。

     • ユーザーからメッセージが届いたら、解説として返信し、同じターン内ですぐにフォアグラウンドポーリングを再開します。ポーリングが feedback または closed を返すまでは、最終応答を送信しないでください。最終応答を送信するとターンが終了し、待機も打ち切られます。
     • シェルツールでコマンドの実行時間に上限がある場合は、上限より少し短い時間を --timeout に指定し、feedback または closed が返されるまで、同じアクティブなターン内で上限付きのポーリングを続けて実行します。

     制限を把握しておいてください。ターンがアクティブな間に限り、確実に機能します。すでに終了したターンは、ユーザーが「送信」を押しても再開されません。その場合、ユーザーからメッセージを受け取った後に status と poll を実行して、フィードバックを取得する必要があります。ポーリングが終了しても、終了したタスクを再開する連携機能はありません。

   {"status":"closed"} が出力された場合、レビューは終了しています。ユーザーがレビューを終了したか、タブを閉じたか、タブが開かれていなかったことを意味します（理由は reason に示されます）。停止し、ポーリングを再開しないでください。unsent は未送信のフィードバック数です。ゼロでない場合は、保存されており、次回復元または破棄できることをユーザーに一行で伝えてください。{"status":"superseded"} は、新しいポーリングが待機を引き継いだことを意味します。このポーリングは黙って停止してください。{"status":"timeout"} は 12 時間後にのみ出力されます。レビューがまだ開いている場合は、status を実行して待機を再開してください。

4. 返された内容を適用し、次のバックグラウンドポーリングを開始します。--ack を指定すると、処理したフィードバックの一括分が消去されます。

   npx -y human-review poll path/to/file.html --ack
   

ユーザーが完了を伝えるまで、手順 3～4 を繰り返します。

新しいターンの開始時など、ポーリングが実行されていない場合に、フィードバックがすでに届いているかどうか確認したい場合は、ブロックせずにすぐ応答する次のコマンドを実行します。

npx -y human-review status path/to/file.html

ポーリングで取得できるフィードバックがある場合は {"status": "feedback-waiting"} が出力され、ブラウザーに残っている未送信のコメントと編集の数も表示されます。

受け取る内容

ユーザーがアクセスしたすべてのページを対象に、ファイルまたは localhost URL ごとにまとめたフィードバックを一括で受け取れます。

{
  "status": "feedback",
  "pages": [
    {
      "file": "/abs/path/to/page.html",
      "edits_saved": true,
      "comments": [
        { "id": "c_1", "kind": "selection", "quote": "the exact text they selected",
          "anchor": { "prefix": "...", "quote": "...", "suffix": "..." },
          "feedback": "what they want changed" }
      ],
      "edits": [
        { "label": "Problem body", "kind": "edited",
          "before": "the original wording",
          "after": "their exact new wording",
          "after_html": "their exact new wording with <strong>formatting</strong>" }
      ]
    }
  ],
  "overall_note": "feedback not tied to any one page"
}

ルール

• edits はユーザーがすでに行った変更です。 after はユーザーが指定した正確な文言です。そのまま引き継ぎ、決して元に戻さないでください。HTML が別の形式（MDX、Markdown、テンプレート）から生成されている場合は、次回のビルドで修正が消えないよう、after をソースにも適用してください。
• edits_saved: true は、編集内容がすでにディスク上のファイルに保存されていることを示します。 プレーンな HTML ファイルはユーザーの入力に応じて自動保存されるため、手元のファイルは古い状態です。変更を加える前にファイルを読み直し、対象を絞って変更してください。以前に作成した内容から再生成すると、ユーザーの作業が消えてしまいます。edits_saved: false（Markdown、localhost ページ、自己レンダリング HTML）の場合、編集内容はこのバッチ内にしかありません。ソースに自分で適用してください。
• kind: "deleted" の編集は、ユーザーがブロック全体を削除したことを示します。理由を尋ねずに、ソースからも削除してください。
• truncated: true とマークされた編集は、テキストが 200k 文字で切り詰められています。after_html からではなく、ページ自体からブロックを読み取ってください。
• before_html／after_html がある場合、ユーザーは単語だけでなく書式（太字、斜体、下線、リンク）も変更しています。HTML 版の書式を、ソースの記法に変換して引き継いでください（例：Markdown／MDX では <strong> → **）。
• kind: "url" のページは、レビュー UI 上で直接編集されています。file フィールドと url フィールドは書き込み可能なファイルではなく、localhost のルートを示します。対応するプロジェクトソース（MDX、TSX、テンプレートなど）を見つけ、すべての編集と削除を適用してください。その後、ルートが再読み込みされるよう確認してください。レンダリング済みの HTTP レスポンスをアプリに書き戻してはいけません。
• 編集の after_html に <img src="assets/..."> が含まれている場合、ユーザーが画像を貼り付けています。ファイルはレビュー対象のファイルと同じ階層の assets/ フォルダーにすでにあります。その相対パスを保持し、Markdown では ![](assets/...) として参照してください。画像を再生成したり、インライン化したりしないでください。
• localhost ページでは、貼り付けた画像は staged_assets に格納されます。ローカルの path をアプリの適切なアセットフォルダーにコピーし、after_html 内の一時的なプレビュー URL を置き換えて、ユーザーが挿入した位置に画像を保持してください。ソースに一時的なプレビュー URL を残してはいけません。
• kind: "moved" の編集は、ユーザーがブロック全体を移動したことを示します。内容を書き換えずに、移動先をソースに反映してください。移動後のブロックは、テキストが moved_after で始まるブロックの直後、テキストが moved_before で始まるブロックの直前に配置します（どちらも 90 文字で切り詰められており、末尾が … の場合があります）。moved_after が空の場合、コンテナー内の先頭に配置します。
• 各コメントは quote を使って探してください。これはユーザーが選択したレンダリング済みのテキストです。Markdown やテンプレート化された HTML では、書式の記法やタグをまたいでいる場合があります。anchor.prefix と anchor.suffix は、周囲のテキストを使って場所を特定するための情報です。
• kind: "element" はブロック全体を指すため、quote は本文ではなくラベルです。
• --ack を実行すると staged_assets が削除されるため、実行前にファイルをコピーしてください。
• overall_note だけを含むバッチでは、pages 配列は空です。
• 最初のページだけでなく、pages 内のすべてのページを修正してください。
• 返信を書かないでください。 ここにチャットはありません。ファイルを保存するとページは自動的に再読み込みされ、ユーザーはそこで変更を確認できます。

より分かりやすい編集ラベル（任意）

作成するセクションに名前を付けると、ユーザーの編集リストには DOM から推測された名前ではなく、その名前が表示されます。

<p data-block="Problem body">…</p>
<div data-container="Metrics callout">…</div>

data-block は編集リストで使われる領域名を指定します。data-container を付けると、ブロックをコメント対象としてクリックできるようになります。