Remarc：屏幕标注如何成为AI Agent的结构化输入源

这次我们不看模型部署，看一个很轻量的 agent 工具：Remarc。项目来自 Hacker News 的 Show HN 栏目，核心目标用一句话概括就是：comment on anything on your screen and send it to your agent。简单说，你可以在屏幕上任意位置画框、写评论，然后把这部分内容连同上下文一起发给 agent 去处理。

这个项目踩中了两个热点：屏幕标注交互，以及 ai agent 开发。它本身大概率不是一个重推理项目，不依赖高显存 GPU，真正值得研究的是产品设计和 agent 上下文打包方式。对做 agent 开发、效率工具、团队协作工具的人而言，它是一个很好的参考案例。

本文会做四件事：拆解 Remarc 的产品逻辑和适用场景；梳理这类工具从启动到使用的通用路径；给出 agent 接口对接和批量任务的参考方案；整理实际使用中的常见问题和排查方法。如果你正在做 agent 项目，或者想把“屏幕内容”变成 agent 的结构化输入，这篇可以直接收藏。

1. 核心能力速览

先说一个判断：从项目标题看，Remarc 属于“屏幕标注 + Agent 调用”的工具型项目，而不是传统意义上的模型推理项目。下面是按公开信息整理的能力速览表，未确认的部分我会单独标注。

补充一点：这类工具的价值不在“截图”本身，而在“把用户看到的画面，转成 agent 能理解的指令”。屏幕上的内容是人眼可感知的视觉信息，而 agent 需要稳定的结构化输入。Remarc 这类项目本质上是在做这两者之间的转换层。

2. 适用场景与使用边界

Remarc 解决的是一个问题：用户发现问题时，如何把“视觉位置”和“意图”一起交出去。传统方式是把截图另存、写文字描述、再粘贴到对话框；有了屏幕标注工具，位置、坐标、评论、页面 URL 可以在同一份数据里完成打包。

从产品形态推演，比较适合的使用场景包括：

• 网页 bug 反馈：比如“这个按钮在 1920x1080 下溢出了”，不用描述像素位置，直接在截图上圈出来，agent 收到后可以定位到具体区域。
• 代码评审 / 设计走查：对设计稿或页面截图做批注，把多张标注图发给 agent，让它做视觉差异或样式规则分析。
• 数据看板异常标注：圈出异常指标，写清问题背景，agent 根据上下文给出排查建议或执行查询。
• 长文档批注：对 PDF、网页正文中的疑点做标注，把批注作为提问上下文发送给 agent。
• 团队协作工单：用标注图片代替口述，减少沟通成本，agent 再把工单转成结构化任务。

使用边界也需要明确。Remarc 这类工具不适合实时视频流的细粒度标注，因为它的核心输入是静态画面；如果 agent 模型需要连续帧，截图式产品形态就不太合适。另外，凡是涉及截图内容外发，都必须考虑数据边界。如果对接的是云端 agent 服务，标注截图可能会离开本机，敏感文件、隐私页面、包含他人人脸或个人信息的画面，在发送前需要做脱敏处理。

涉及版权、肖像、隐私的内容，必须先确认授权再使用。不要把带敏感信息的截图直接丢给外部 agent，更不要把标注数据用于未经授权的训练或分析场景。

3. 这类工具的通用技术实现路径

Remarc 的具体实现细节需要看项目仓库。这里只拆解“屏幕标注 + 发给 agent”这类工具通用的技术路径，方便你理解它要做什么，也方便你参考实现自己的版本。

整个链路大致分为四层。

第一层是采集层，负责拿到屏幕内容。浏览器扩展通常会走 Chrome 的chrome.tabs.captureVisibleTab获取当前页面截图；桌面工具则可能用系统级截图 API，或通过快捷键唤起截图。采集时需要注意分辨率、DPR 缩放、页面滚动等因素，否则标注坐标会和实际位置错位。

第二层是标注层，负责交互和渲染。常见方案是在页面或桌面上叠加一个 Canvas 覆盖层，用户画矩形、圆圈、箭头，并填写文字评论。实现时建议把标注层放在独立的 Shadow DOM 里，避免页面样式污染；还要处理窗口缩放、滚动跟随、多显示器等边界情况。

第三层是打包层，负责把上下文转成 agent 可读的结构化数据。一份完整的标注数据至少应该包含：截图（或截屏 URL）、标注坐标、评论文字、来源页面 URL、采集时间、任务 ID。坐标建议做 0 到 1 的归一化，这样不同分辨率下标注位置不会漂移。

{ "task_id": "task-20250610-001", "source": "browser-extension", "target_url": "https://example.com/dashboard", "captured_at": "2025-06-10T10:30:00Z", "image": { "format": "jpeg", "width": 1920, "height": 1080 }, "image_base64": "...", "annotations": [ { "id": "a1", "type": "rect", "x": 0.32, "y": 0.45, "width": 0.12, "height": 0.06, "color": "#ff0000", "comment": "这个按钮在 1920x1080 下溢出了" } ], "note": "请定位并修复页面样式问题" }

第四层是发送层，负责把打包后的数据交给 agent。这里又可以分成几种形态：直接调用 agent 的 HTTP API；把任务投递到消息队列；或者通过 agent 框架的工具调用能力，把标注数据作为工具输入。具体走哪种方式，取决于 agent 后端的能力和架构。

4. 本地部署与启动方式

Remarc 的启动方式需要以项目 README 为准。下面给出的是这类工具通用的本地部署检查路径，适用于大多数浏览器扩展 + 后端 agent 服务的组合。

4.1 环境准备

先确认本机环境：

• 是否安装 Node.js 或 Python，版本按项目文档要求；
• 浏览器版本是否支持扩展开发模式；
• 如果是桌面工具，确认操作系统版本和窗口管理器兼容性；
• 如果 agent 服务在本机运行，预留一个可用的服务端口。

浏览器扩展的加载方式一般是：打开浏览器的扩展管理页，开启开发者模式，选择“Load unpacked / 加载已解压的扩展程序”，选中项目构建后的目录。如果项目需要构建，先执行依赖安装和构建命令。

# 通用示例，安装依赖并构建，实际命令以项目 README 为准 npm install npm run build

Python 项目则可能是：

# 通用示例，安装依赖并启动服务 pip install -r requirements.txt python app.py --host 127.0.0.1 --port 8000

4.2 启动顺序

更稳妥的顺序是：先启动 agent 后端服务，再启动前端标注工具，最后在配置里填上 agent 服务地址。这样可以避免工具启动后找不到后端接口的问题。

启动后需要验证几件事：

• 标注层是否正常显示，能否在屏幕上画框、写字；
• 截图是否能正确生成；
• 点击“发送给 agent”后，后端是否收到请求；
• 后端返回的结果是否能回到前端展示。

如果本地端口被占用，可以先用命令检查。

# 查看端口占用，比如 8000 端口 lsof -i :8000

如果端口冲突，把服务端口换掉，并在前端工具配置中同步修改。这里不写死项目端口，以实际文档为准。

5. Agent 接口对接与数据格式

Remarc 的关键点在于“send it to your agent”。做 agent 开发的人会关心一个问题：agent 端到底接收什么格式的数据？

从通用设计角度，可以按三种方式对接。

5.1 自定义 HTTP API

如果 agent 后端是自己开发的，最直接的方式是定义一个 JSON 接口。请求体带上任务 ID、提示词、截图 base64、标注数组和来源信息。后端解析后，把标注坐标和评论内容一起塞进 agent 的 prompt，或者作为多模态输入传给视觉模型。

curl -X POST http://127.0.0.1:8000/api/agent/run \ -H "Content-Type: application/json" \ -d '{ "task_id": "task-20250610-001", "prompt": "请根据截图中的标注位置和评论，定位问题并给出修复方案", "image_base64": "...", "annotations": [] }'

Python 调用示例：

import json import requests agent_url = "http://127.0.0.1:8000/api/agent/run" with open("annotation.json", "r", encoding="utf-8") as f: payload = json.load(f) response = requests.post(agent_url, json=payload, timeout=120) print(response.json())

注意：大图的 base64 会很长。如果截图分辨率太高，建议在上传前做压缩或裁剪，避免请求体过大。

5.2 兼容 OpenAI / Anthropic 风格接口

如果 agent 后端是 OpenAI 兼容接口，可以做一个适配层，把标注数据转成多模态消息格式。通常是把截图 base64 放进 image_url 字段，把用户评论和标注坐标放进文本消息，让模型一次性看到画面和位置描述。

{ "model": "your-agent-model", "messages": [ { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,..." } }, { "type": "text", "text": "标注坐标：(0.32, 0.45)，评论：这个按钮在 1920x1080 下溢出了。请定位并修复。" } ] } ] }

这是 agent 开发中比较通用的多模态输入结构，基本不依赖 Remarc 本身，适合所有需要把“截图 + 标注”传给模型的项目。

5.3 通过 agent 框架或 MCP 工具接入

如果你用的是 agent 框架，可以把 Remarc 封装成框架里的一个“工具调用输入源”。典型的流程是：用户截图标注 → 工具调用触发 → 标注数据被当作工具参数传给 agent → agent 根据参数决定下一步动作。

比如在 agent 框架里注册一个screen_annotation_ingest工具，它的输入参数就是上文的 JSON 数据结构。这样做的好处是，标注能力可以被复用，不只是“发给某个 agent”，而是“让 agent 在需要时主动去读取屏幕标注”。

从搜索热词看，agent 框架、agent 开发、agent 项目是当前关注度很高的方向。Remarc 这类工具，本质上是在为 agent 框架补充一种新的“观察输入”。如果你正在开发 agent，建议把标注数据结构设计成独立模块，而不是和具体界面耦合。

6. 批量任务与自动化场景

Remarc 作为交互式工具，主要使用场景是单次发送。但从工程角度，批量任务往往比单次调用更有价值。比如你已经积累了一批带标注的截图 JSON，想统一发给 agent 处理，就可以写一个批量脚本。

import glob import json import time import requests AGENT_URL = "http://127.0.0.1:8000/api/agent/run" def run_batch(annotation_dir: str, sleep_seconds: int = 1): files = sorted(glob.glob(f"{annotation_dir}/*.json")) if not files: print("没有找到标注文件") return for path in files: with open(path, "r", encoding="utf-8") as f: payload = json.load(f) try: resp = requests.post(AGENT_URL, json=payload, timeout=120) result = resp.json() print(path, "->", result.get("status", "unknown")) except Exception as exc: print(path, "-> failed:", exc) time.sleep(sleep_seconds) if __name__ == "__main__": run_batch("./annotations")

批量任务设计时要注意几个点：

• 任务幂等性：每个任务要有唯一 task_id，重复发送时后端能识别并去重；
• 超时控制：单张截图如果包含大量标注，agent 处理时间可能很长，超时时间要放宽，超过 120 秒时按实际情况调整；
• 失败重试：网络抖动、agent 服务重启都会导致失败，脚本里要加重试逻辑；
• 日志记录：至少记录每条任务的请求时间、状态、返回耗时和错误信息。

如果 agent 处理的是大量标注图片，建议在批量脚本外层加一个队列，比如用 Redis 或本地文件队列，避免一次性把几十个请求全部打到 agent 服务上。批量任务卡住时，优先检查 agent 服务日志和队列消费进度。

7. 资源占用与性能观察

屏幕标注工具虽然不显眼，但资源占用仍然值得关注。尤其当它需要处理高分屏截图时，性能问题会直接影响使用体验。下面给出通用观察方法和优化方向，具体数值以本机测试为准。

7.1 截图体积与内存

一张 1080p 的 JPEG 截图，base64 编码后体量通常在几百 KB 到 1MB 以上，具体取决于画面复杂度。如果截图是 PNG，体积会更大。工具运行时，截图数据会在内存里暂存，频繁截图时内存占用会上升。

优化方向：

• 截图时优先选 JPEG 而不是 PNG；
• 限制截取区域，只截用户标注的局部区域；
• 把长边压缩到 1600px 左右，减少数据量；
• 发送完成后及时释放内存中的 base64 数据。

7.2 CPU 和网络开销

标注层渲染、坐标计算、base64 编码都会产生 CPU 开销。正常情况下这种开销很低，但在高分屏 + 多显示器 + 长页面截图的组合下，需要注意。

如果 agent 服务是云端部署，还要关注上传带宽。一张几 MB 的截图在弱网环境下可能明显卡顿，建议前端做两件事：压缩后上传，以及显示发送进度。

7.3 如何观察

浏览器扩展可以用扩展管理页或 DevTools 的 Performance 面板观察事件循环耗时；桌面工具可以在任务管理器里看进程 CPU 和内存。agent 后端要重点看响应时间曲线，尤其是批量场景。如果发送任务后 agent 迟迟不返回，先用后端日志确认是网络问题还是模型推理时间过长。

7.4 降低显存 / 内存占用的通用思路

如果 agent 端是本地运行的视觉模型，输入图片尽量压缩，因为图片分辨率会直接影响模型输入的 token 数量。标注工具本身不一定需要 GPU，但 agent 端如果跑本地模型，显存占用要按模型规格评估。先小尺寸测试，再逐步提高分辨率，是减少资源占用风险的最直接方式。

8. 常见问题与排查方法

下面整理的是这类“屏幕标注 + agent 调用”工具常见的现象、原因和排查方向。遇到问题时先看这本账，能省很多时间。

排查时记住一个顺序：先看前端是不是把数据发出去了，再看后端是不是收到了，最后看 agent 是否执行并返回。大多数问题出在“发送层”和“agent 上下文构造层”这两段。

9. 最佳实践与合规使用建议

如果你准备基于 Remarc 做自己的 agent 工作流，或者想参考它的思路做内部工具，下面这些实践建议可以直接用上。

9.1 先小规模验证再扩展

第一次使用不要直接批量发几十张截图。先用一张包含文字、图片、按钮的普通页面做测试，确认标注坐标正确、agent 能返回有效结果，再逐步扩大范围。这样能提前暴露大多数集成问题，成本也很低。

9.2 数据结构单独抽象

把“标注数据”设计成独立的数据结构，不要和具体的 UI 写死。这样同一个标注模块可以同时对接自定义 API、OpenAI 兼容接口和 agent 框架。坐标归一化、图片压缩、任务去重都放在数据层处理，前端只负责交互。

9.3 数据安全与隐私保护

使用屏幕标注类工具时，隐私风险比普通文本工具更高，因为截图可能包含账号页面、内部系统、个人信息、他人人脸等内容。建议：

• 默认只在本地环境处理截图，明确需要时才发送到远程 agent；
• 发送前脱敏，比如打码账号、手机号、人脸；
• 如果 agent 是云端服务，确认服务方是否记录和保存请求数据；
• 对包含版权内容的截图，不要用于未经授权的场景；
• 对外发布的教程或演示材料，避免出现真实业务系统界面。

这些边界不是形式主义。屏幕标注工具把“看到的内容”直接变成数据流，一旦截图外发，就很难再控制传播范围。

9.4 日志、审计与任务持久化

批量场景下，建议把每次发送的标注 JSON 和 agent 返回结果都存一份。这样即使某次任务失败，也可以从本地日志重放，而不是让用户重新标注一遍。

{ "task_id": "task-20250610-001", "status": "pending", "request_at": "2025-06-10T10:30:00Z", "response_at": null, "retry_count": 0, "last_error": "" }

任务状态机用简单的 pending + running + success + failed 就够用了，不用一开始就设计复杂队列。

9.5 权限控制与访问范围

agent 接口不要无鉴权暴露在公网。本地开发时绑定127.0.0.1，部署到团队内网时加 token 或 API key。如果是浏览器扩展，注意后台脚本要避免跨域请求泄露。

10. 总结与下一步

Remarc 最值得关注的点，不是截图标注本身，而是它把“屏幕观察”变成了 agent 的结构化输入。你在屏幕上看到问题，随手标注，agent 拿到的不仅仅是图片，而是包含位置、评论、来源和时间的完整上下文。这种交互方式很适合做 bug 反馈、UI 走查、数据看板异常分析和团队协作工单。

拿到项目后，最先验证三件事：一是标注能否在任意页面正常显示；二是标注坐标在分辨率变化后是否漂移；三是发送给 agent 的数据是否包含截图、坐标和评论，并且 agent 能拿到后返回有效结果。

最容易踩的坑也基本集中在同一块：坐标归一化、截图 base64 体积、agent 超时。这三处只要有一个没处理好，整个链路都跑不通。

后续如果想继续扩展，推荐两个方向：一个是用 MCP 或 agent 框架把标注能力注册成工具，让 agent 需要时可以主动读取屏幕标注；另一个是做一个本地标注任务队列，把“单次人工发送”升级成“批量异步处理”。这样 Remarc 就不只是一个截图转发工具，而是一个真正能进入 agent 工作流的视觉上下文入口。

建议先把数据结构层设计好，接口方面从通用 HTTP JSON 开始试，跑通后再兼容 OpenAI 风格接口。这种路径改动小、见效快，也是最稳妥的 agent 开发接入方式。