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 处理来源Hacker News Show HN 公开项目核心功能在屏幕上任意内容上做标记/评论把上下文打包后交给 agent与 agent 的关系作为 agent 的“观察输入源”提供截图、坐标、评论等结构化上下文开源情况以项目仓库说明为准平台支持大概率覆盖浏览器扩展或桌面辅助工具形态具体以仓库 README 为准硬件门槛从产品形态看以 CPU 环境为主无明确高显存要求启动方式需按项目文档确认浏览器扩展可走开发者模式加载是否支持 API核心价值在 agent 对接接口形式需以实际实现为准是否支持批量任务取决于 agent 端能力和工具对任务队列的支持适合人群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 buildPython 项目则可能是# 通用示例安装依赖并启动服务 pip install -r requirements.txt python app.py --host 127.0.0.1 --port 80004.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, encodingutf-8) as f: payload json.load(f) response requests.post(agent_url, jsonpayload, timeout120) 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, encodingutf-8) as f: payload json.load(f) try: resp requests.post(AGENT_URL, jsonpayload, timeout120) 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 调用”工具常见的现象、原因和排查方向。遇到问题时先看这本账能省很多时间。问题现象可能原因排查方式解决方案标注层无法显示Canvas 覆盖层层级被页面覆盖或框架样式冲突打开 DevTools 检查覆盖层是否渲染用 Shadow DOM 隔离或用更高 z-index 容器标注位置和实际位置错位未处理 DPR 缩放、滚动偏移或分辨率差异在不同分辨率下对比标注坐标坐标做归一化并在截图时记录滚动偏移截图截不到视频 / Canvas 内容浏览器安全机制或合成层限制查看 console 报错和捕获结果改用桌面级截图或提示用户手动截图发送给 agent 后无响应agent 服务未启动、接口地址错误、请求体过大查看后端日志和前端 network 面板确认 agent 地址、检查请求体大小、加重试agent 返回超时模型推理慢、上下文过长、网络波动查看 agent 服务端响应时长缩短 prompt、压缩截图、调大 timeout 参数执行器提示 did not respond in timeagent 执行 provider 响应超时常见于网络或后端负载问题检查 provider 状态和日志优化网络、调整执行器超时配置、错峰重试中文字符乱码请求编码或响应编码不一致检查 HTTP 请求头 Content-Type统一使用 UTF-8 编码批量任务卡住队列消费慢、并发过高、任务未设置超时查看队列长度和进程堆栈加超时、失败重试和并发上限排查时记住一个顺序先看前端是不是把数据发出去了再看后端是不是收到了最后看 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 开发接入方式。