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. 等待反馈。此命令会一直阻塞，直到用户在浏览器中点击 Send，然后输出整批反馈并退出：

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

   只有在用户点击 Send 或关闭审阅时，命令才会退出。 无需重新运行，也不必定期轮询，更不用添加 --timeout。 即使本地服务器重启，命令也会继续运行；即使轮询进程终止，反馈也会保存，因此绝不会丢失。如何等待取决于你的运行环境：

   • Claude Code： 使用 run_in_background: true 运行命令，然后结束当前轮次。 Claude Code 会在命令退出时立即唤醒你并提供输出。

   • Codex、Cursor 和其他环境： 在当前活动轮次中前台运行命令，并持续等待，直到它输出 feedback 或 closed。不要将其分离运行，也不要将其作为后台会话启动：分离的命令完成时，不会有任何东西唤醒你。在审阅进行期间：

     • 如果用户发送消息，请以评论的形式回复，并立即在同一轮次中恢复前台轮询。在轮询返回 feedback 或 closed 之前，不要发送最终回复——最终回复会结束当前轮次并终止等待。
     • 如果你的 Shell 工具会限制命令运行时长，请将 --timeout 设为略低于该上限，并在同一活动轮次中连续运行有时限的轮询，直到其中一次返回 feedback 或 closed。

     请注意限制：只有在当前轮次保持活动状态时，这种方式才可靠。如果轮次已经结束，用户点击 Send 时不会唤醒你；用户必须先给你发消息，然后你再运行 status 和 poll 来获取整批反馈。轮询退出后，没有任何机制可以恢复已结束的任务。

   如果输出 {"status":"closed"}，则审阅已结束：用户结束了审阅、关闭了标签页，或者没有打开标签页（reason 会说明具体原因）。停止操作，不要再启动轮询。如果 unsent 不为零，请用一行告知用户：未发送的反馈已保留，下次可以选择恢复或丢弃。{"status":"superseded"} 表示你启动了更新的轮询，由它负责等待——请静默停止当前轮询。只有等待 12 小时后才会出现 {"status":"timeout"}；如果审阅仍在进行，请运行 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、本地主机页面、自行渲染的 HTML）表示修改 仅存在于本批次中——请自行将其应用到源文件。
• kind: "deleted" 类型的修改表示用户删除了整个区块： 也要从源文件中删除，不必询问原因。
• 标记为 truncated: true 的修改，其文本已在 200k 个字符处截断；请从页面本身读取 区块内容，而不要从 after_html 读取。
• 存在 before_html/after_html 时，用户更改的是格式，而不只是文字——包括粗体、斜体、下划线和链接。请使用 HTML 版本保留格式，并转换为源文件所用的语法（例如，将 <strong> 转换为 Markdown/MDX 中的 **）。
• kind: "url" 类型的页面是在审阅界面中直接编辑的。其 file 和 url 字段指向本地主机路由，而不是可写文件。请找到对应的项目源文件（例如 MDX、TSX 或模板），在其中应用所有修改和删除，然后确认，以便路由重新加载。绝不要将渲染后的 HTTP 响应写回应用。
• 当修改的 after_html 包含 <img src="assets/..."> 时，表示用户粘贴了一张图片：该文件已存在于审阅文件旁边的 assets/ 文件夹中。保留其相对路径——在 Markdown 中使用 ![](assets/...) 引用。绝不要重新生成图片或将其内嵌。
• 在本地主机页面上，粘贴的图片会放在 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 是该区块的标签，而不是正文。
• 在确认之前复制所有 staged_assets 文件：--ack 会删除它们。
• 只有 overall_note 的批次，其 pages 数组为空。
• 修复 pages 中的每个页面，而不只是第一个。
• 不要回复。 这里没有聊天。保存文件后，页面会自动重新加载，用户届时就能看到你的修改。

更好的编辑标签（可选）

为你创建的区块命名，编辑列表就会使用你的名称，而不是根据 DOM 猜测：

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

data-block 用于命名区域，以便编辑列表识别。data-container 还会使该区块可作为评论目标。