gcrft123/tailr

Tailr — 审查循环

Tailr 让与您合作的审查者能够在浏览器中标记他们正在运行的开发服务器——点击一个元素，说明问题所在——然后将所有标记一次性作为一个批次交给您。您应用该批次，并逐个报告每个标记的完成情况。

以下规则是整个协议。它们与 tailr init 写入项目 AGENTS.md / CLAUDE.md 的规则完全相同；此插件直接承载这些规则，因此用户仓库中无需编辑任何内容。

Tailr — 来自审查者的视觉标记

审查者在浏览器中标记正在运行的应用，并将所有更改作为一个批次交给您。当 .tailr/session.json 存在时，会话即启动；如果不存在，请将其作为长期运行的后台进程启动——它必须保持运行，因此不要阻塞您的回合等待它：

npx tailr --target http://localhost:<开发服务器端口>

它会打印一个审查 URL（通常是 http://localhost:4100）。告诉审查者使用该 URL，而不是原始端口。Tailr 代理应用并注入其覆盖层；源代码不会被修改。

循环是 wait → pull → 每个标记的 progress → done 或 fail。

命令	MCP 工具	说明
npx tailr status	tailr_status	是否有批次等待？退出码 0 是 · 3 会话已启动，无等待 · 2 无会话
npx tailr wait	tailr_wait	阻塞直到按下“发送”；退出码 0 批次等待中 · 3 超时，重新启动 · 2 会话结束
npx tailr pull	tailr_pull	获取批次租约，输出为 JSON
npx tailr progress <ref>	tailr_progress	报告一个标记已应用
npx tailr done	tailr_done	运行完成
npx tailr fail "reason"	tailr_fail	返回不完整

每个标记包含一个 ref（"01"）、一个 type、产生该标记的 route、尽可能准确的来源 address、一个 CSS selector、元素的文本内容以及审查者的 comment。

• comment — 按描述更改该元素
• remove — 删除该元素
• text — 携带 before/after；将文本更改为 after
• point — 携带页面 x/y 坐标而非元素。审查者标记了一个位置，而非一个具体元素：他们可能希望在那里添加新内容，或仅标记该位置。他们的评论说明了意图。

重要规则

• 将 wait 作为长期运行的后台进程运行，并将其退出视为通知。切勿要求审查者告诉您批次已到达，也切勿轮询。每次关闭运行后重新启动它。
• 每应用一个标记就使用 progress 报告，而不是在最后一次性报告。审查者会在屏幕上看到标记逐个清除；批量报告会让审查者感觉没有进展。
• 始终以 done 或 fail 结束运行。在您执行此操作之前，审查者无法发送另一个批次。如果您遇到无法完成的情况，请使用 fail 说明实际出错的细节——Tailr 不会编造解释，而是将问题返回给您。
• 当来源地址与选择器不一致时，请信任来源地址。
• 带有 "orphaned": true 的标记在发送前失去了其元素。不要猜测其意图——请向审查者提出。
• 如果标记存在歧义，请询问而非自行选择解释。
• 在项目目录中运行这些命令；这样 Tailr 才能找到会话。

从此插件运行命令

此插件注册了 Tailr 的 MCP 服务器，因此 tailr_status、tailr_wait、tailr_pull、tailr_progress、tailr_done 和 tailr_fail 可以直接供您使用。优先使用它们而非 CLI：它们始终存在，而 npx tailr 简写形式仅在安装了 Tailr 的项目中才能解析。

当您确实需要使用 CLI 时，请使用完整的包名，以便在未安装任何依赖的项目中也能工作：

npx -y @gcrft123/tailr <命令>

启动会话是唯一没有 MCP 工具的步骤，因为会话是这些工具所通信的服务器。请将其作为长期运行的后台进程启动——它必须保持运行，因此不要阻塞您的回合等待它：

npx -y @gcrft123/tailr --target http://localhost:<开发服务器端口>

如果项目已将 Tailr 作为依赖项，则直接使用 npx tailr 是等效且更简洁的。