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. 读取完整文件。查找请求的紧凑 ID，例如 {#c7}； 如果用户只提供了锚定文本，则改为查找准确的 CriticMarkup 锚点。 确认锚定文本和评论正文与用户请求相符。如果 ID 或准确锚点缺失或有歧义，请停止并报告歧义。
2. 解析紧跟在该逻辑评论后面的 JSON 元数据。如果不存在，则从空对象开始。如果格式错误，请停止，不要覆盖。
3. 对元数据进行往返处理：只修改回复列表和 resolved，然后重新序列化完整对象 — 其他所有键和已有回复都必须保留。回复只能追加：添加一条回复，使用下一个未使用的 rN ID、author: "agent"、响应正文，以及当前 UTC 时间作为 ISO-8601 格式的 createdAt。
4. 仅当用户请求已实际处理时，才设置 resolved: true。对于明确的重新打开请求，设置 resolved: false。 致谢、测试、问题和未完成的工作都应保持为 false。
5. 将元数据块写在评论的 {#cN} 标记后（参见“分片锚点”）。锚定文本必须逐字节保持不变，评论正文、CriticMarkup 分隔符、建议的编辑内容以及所有无关 Markdown 也都必须保持不变。

分片锚点

一个逻辑评论 ID 可能出现在多个 CriticMarkup 片段中。最后一个片段为准：保留所有标记，只保留一个元数据块，并将其放在最后一个片段之后 — 如果元数据块当前跟在较早的片段后面，则将其移到最后一个片段之后。如果分片可能影响用户的格式，请报告分片情况。

验证

编辑后：

1. 重新读取文件，确认请求的 ID 和准确的锚定文本仍然存在。
2. 解析最后一个片段之后的元数据，并确认其为有效 JSON、新回复是最后一条回复、旧回复和其他键已往返保留，且 resolved 的值符合预期。确认备注会正常显示评论，而不是将原始块显示为文本。
3. 检查周围的 Markdown 是否有意外更改：对于受 Git 跟踪的文件，检查 git diff -- <file>；对于被忽略或生成的文件，则比较修改前后的文本。
4. 报告你留下的回复，以及是否已解决该评论。