和 AI Agent 协作时有一个很常见的尴尬场景你在屏幕上看到一段报错信息、一张设计稿或者一份数据报表心里已经想好要让 Agent 做什么却还要手动截图、粘贴文字、补充背景再花时间把需求描述清楚。整个过程既繁琐又容易丢失“现场信息”。Remarc 这个项目给出了一种更直接的交互方式在屏幕上的任意内容上做批注然后把批注连同屏幕上下文一起发送给你的 Agent。本文不打算只复述项目介绍而是把 Remarc 拆开来看它解决什么问题、背后的交互范式是什么、如果要自己实现一个类似能力技术架构和最小原型该怎么做以及围绕 Agent 开发最常见的坑和工程化建议。对正在研究 AI Agent 开发、想了解“人类意图如何高效传递给 Agent”的开发者这篇文章会比较有参考价值。1. 背景与核心概念1.1 Remarc 是什么Remarc 是一个在 Hacker News 的 Show HN 板块公开的项目。从标题 “comment on anything on your screen and send it to your agent” 可以看出它的核心能力有两个在屏幕上的任意内容中添加评论或批注comment。将批注和对应的屏幕上下文发送给 Agent 处理。表面上看它像一个“截图 标注 发送”的工具但本质上有很大不同。普通截图工具只负责把屏幕变成图片聊天助手只负责接收你输入的文字。Remarc 做的事情是把“用户正在看什么、用户对哪里不满意、用户希望 Agent 做什么”这三件事合并成一次操作。这里的关键词是“上下文”。Agent 要完成一个任务除了需要明确的目标指令还需要足够的背景信息。如果背景信息靠用户手动粘贴一方面效率低另一方面很容易漏掉细节。Remarc 的思路是你在屏幕上看到的内容就是最好的上下文批注位置就是最精确的指代两者组合起来Agent 收到的指令会非常具体。1.2 AI Agent 到底是什么在进入 Remarc 的架构分析之前先统一一下对 AI Agent 的认知。简单说Agent 是一个能感知环境、做出决策并执行动作的 AI 系统。和普通聊天机器人相比Agent 最大的特点是可以“动手”。一个典型的 Agent 工作循环包括接收用户目标和上下文。规划任务步骤。调用工具比如读文件、查数据库、执行命令、调用 API。观察工具返回的结果。根据结果修正计划继续执行。最终输出结果。支撑这个循环的技术底座包括大语言模型LLM、函数调用Function Calling / Tool Use、记忆管理、任务编排等。你可以把 LLM 理解为大脑把工具理解为手脚把编排逻辑理解为神经系统。Agent 开发的核心工作就是把这些组件合理组织起来让系统在真实场景中稳定完成任务。1.3 屏幕批注与 Agent 的交互范式Remarc 采用的交互方式可以理解为一种“意图标记”模式。用户在屏幕上画一个框、写一句话本质上是告诉 Agent“注意这里这是我要你处理的对象。”这种模式有几个明显优势减少上下文损耗。用户不需要把屏幕内容手动转述给 Agent批注本身已经指向了具体区域。降低描述成本。用户只需要说“这里报错了”或者“这个按钮间距不对”而不是重新贴一遍完整内容。提高任务准确性。结合屏幕截图、页面结构和批注位置Agent 能更准确地理解用户意图。从人机交互的角度看这种模式其实解决了 Agent 使用中的一个核心矛盾Agent 需要结构化输入而人类最自然的表达方式是“指着某个东西说话”。Remarc 这类工具本质上是在人类直觉和 Agent 输入要求之间搭了一座桥。1.4 Harness 和 Agent 的区别最近在搜索 Agent 开发资料时会经常看到 harness 和 agent 两个词同时出现很多人分不清两者关系。简单来说Agent智能体是“大脑”负责理解目标、规划步骤、决定调用哪个工具。Harness执行框架是“身体”负责运行 Agent 的循环逻辑、管理工具注册与调用、维护上下文窗口、处理权限和超时等运行时问题。把 Remarc 放到这个框架里看会更清楚屏幕批注能力可以算作 Harness 层的一个“上下文输入组件”它负责把外部世界屏幕画面转换成 Agent 能理解的输入而真正做决策的部分仍然是 Agent 核心。理解这种分层对后面分析技术架构很有帮助。2. 适用场景与产品价值2.1 典型使用场景从产品形态来看Remarc 这类工具最适合以下场景。第一是前端页面问题反馈。设计师或测试人员看到页面上的样式问题直接在对应位置画框批注Agent 结合截图和批注生成修复代码或修改建议。这比传统模式下“截图 写长篇问题描述 等待开发理解”要高效得多。第二是数据分析与报表解读。业务人员看到报表中某个异常数字直接在数字上做批注Agent 结合数据上下文解释波动原因或者生成进一步分析的 SQL。用户不需要手动把数字抄进对话框。第三是文档与代码评审。评审者在代码片段或文档段落上打点评论Agent 根据评论内容给出修改意见、解释逻辑问题甚至直接生成补丁。第四是错误排查与告警处理。屏幕上出现一条报错日志用户框选报错内容并添加说明Agent 结合日志上下文给出排查建议。这类场景对“上下文完整性”要求很高刚好是屏幕批注的强项。2.2 与截图工具、聊天助手的区别你可能会有疑问这些东西我手动复制粘贴给 ChatGPT 不也能做吗确实能但体验和效率完全不同。为了看清差异我把三类工具放在一起对比工具类型核心能力主要局限截图标注工具截取屏幕、添加标记标记只停留在图片上无法变成结构化指令聊天助手接收文字和图片生成回答需要用户手动整理上下文指代不精确Remarc 这类工具屏幕批注 上下文提取 Agent 执行依赖 Agent 能力需要关注隐私与权限可以这样理解截图工具解决的是“保存现场”聊天助手解决的是“理解问题”而 Remarc 类型的工具解决的是“把现场直接变成 Agent 可以执行的任务”。它把两个环节合并了。2.3 适合什么类型的用户从功能设计看Remarc 主要面向两类用户。一类是重度 Agent 使用者他们每天都在和不同的 Agent 协作希望减少“搬运上下文”的时间另一类是跨角色协作场景中的非开发人员比如测试、设计、运营他们不一定懂技术但能通过屏幕批注的方式把问题和意图准确传递给 Agent。值得注意的是这类工具并不适合所有场景。如果任务本身不依赖屏幕信息或者用户需要的是开放式头脑风暴那么直接和对话式 Agent 沟通反而更自然。屏幕批注类工具的核心价值始终在“所见即所达”这个点上。3. 技术架构拆解3.1 整体分层从工程角度看一个“屏幕批注 Agent”工具通常包含四层每一层各司其职用户操作 ↓ 屏幕捕获层获取当前屏幕或目标窗口内容 ↓ 标注交互层接收用户框选、文字评论等操作 ↓ 上下文提取层把屏幕内容转成文本或结构化数据 ↓ Agent 通信层封装消息调用 Agent 服务返回结果这种分层的好处是每一层都可以独立替换。比如屏幕捕获层可以用操作系统 API也可以用浏览器扩展上下文提取层可以用 OCR也可以直接读取 DOM 结构Agent 通信层可以对接本地模型也可以对接云端 Agent 服务。3.2 屏幕捕获层屏幕捕获层负责解决“用户看到了什么”的问题。常见实现方案有三种。操作系统级 API。Windows、macOS 都提供了屏幕截取能力配合窗口句柄可以定位到具体窗口。这种方式覆盖面广几乎能捕获任何桌面应用但需要处理不同系统的权限授权。浏览器扩展。通过 Chrome Extension 或 Firefox Add-on 捕获当前标签页好处是能直接拿到页面 DOM 结构和元素位置上下文提取非常方便坏处是只能覆盖浏览器内的内容。无头浏览器或系统级注入。这种方式适合自动化测试场景但对普通用户来说侵入性太强一般在消费级产品中不会采用。从 Remarc “comment on anything on your screen” 的描述看它的目标应该是覆盖整个屏幕而不仅是浏览器因此大概率是操作系统级方案或者多种方案组合。3.3 标注交互层标注交互层的核心是解决“用户指的位置”和“Agent 理解的位置”之间的映射问题。用户在屏幕上画了一个矩形框这个框的坐标是基于屏幕坐标系的。Agent 拿到这个坐标后需要知道它对应的是哪个应用、哪个窗口、页面上的哪一部分。如果不做坐标转换Agent 看到一堆像素坐标是没有意义的。这里通常需要引入一个“锚定”机制记录当前工作区分辨率、窗口位置和大小。记录批注框在窗口内的相对坐标。如果捕获的是网页还需要通过 DOM 元素命中去定位具体节点。标注交互层的体验也很关键。框选、箭头、高亮、文字评论这些交互动作要足够轻量不能让用户在批注上花太多时间否则工具的反而是负担。3.4 上下文提取层只把一张截图丢给 Agent 往往不够。大部分 Agent 的语言理解能力基于文本图片虽然可以识别但精度和成本都不如文本直接。因此需要把屏幕内容转换成 Agent 更容易理解的形式。上下文提取层常见的手段包括OCR 识别。把截图中的文字提取出来在数据报表、日志、文档场景中特别有用。浏览器 DOM 文本提取。如果捕获的是网页直接读取可见区域的文本、标题、按钮文字准确性远高于 OCR。元素属性提取。记录批注位置附近的标签名、class、id 等属性方便 Agent 生成精准的代码或查询语句。元数据补充。包括当前页面 URL、窗口标题、操作系统、应用名称等。这一层设计的好坏直接决定 Agent 对用户意图的理解质量。上下文太粗Agent 会答非所问上下文太细又会浪费 token甚至让 Agent 被无关信息干扰。3.5 Agent 通信层Agent 通信层负责把标注数据和提取后的上下文封装成消息发送给 Agent 执行服务。需要考虑的问题包括消息格式。通常是一个包含角色、内容、附件的结构化对象。同步还是异步。简单任务可以同步等待结果耗时操作应该异步执行并提供进度反馈。错误处理。Agent 服务超时、模型返回格式异常、工具调用失败都需要有兜底逻辑。通知机制。任务完成后通过系统通知或在应用内提醒用户查看结果。很多 Agent 开发新手只关注“怎么调用模型 API”忽略了通信层。实际上一个稳定的产品往往把大量精力花在超时重试、异步任务管理和异常恢复上。4. 最小原型实现思路下面用一个简化原型演示核心链路。需要先说明以下代码不是 Remarc 的官方源码而是为了说明这类工具的工作原理写的实现思路示例。具体 API 和依赖版本请以你的实际环境和项目官方文档为准。4.1 技术选型为了快速验证核心链路可以选择 Python 作为原型语言用到的库包括mss或Pillow屏幕截图。pytesseractOCR 文本识别可选。requests或openai调用 Agent 服务。json定义标注和上下文数据结构。选择 Python 的原因是生态成熟、示例代码短适合演示概念。实际产品如果要覆盖桌面端交互建议用 Electron、Tauri 或原生桌面框架标注交互体验会好很多。4.2 定义标注数据结构屏幕批注和上下文的序列化格式是核心设计。一个可用的 JSON 结构如下{ annotation: { type: rectangle, content: 这个按钮点击后没有反应, position: { screen_width: 2560, screen_height: 1440, x: 320, y: 480, width: 180, height: 60 } }, context: { app: Chrome, window_title: 订单管理后台 - 生产环境, url: https://example.com/admin/orders, text: 订单号: 202506001\n状态: 待发货\n操作按钮: 发货, 取消, 打印, ocr_text: 页面出现的全部文字内容 } }这个结构的关键点在于把“用户说了什么”和“屏幕上有什么”分开Agent 可以结合annotation.position和context.text定位到具体元素。实际项目中建议给结构加版本号方便后续兼容升级。4.3 屏幕采集与上下文封装下面是一个简化示例演示如何采集屏幕截图并封装上下文。# 文件路径screen_context.py import json import mss from PIL import Image def capture_screen(regionNone, output_pathscreenshot.png): 截取屏幕指定区域region 格式为 (left, top, width, height) with mss.mss() as sct: monitor {left: region[0], top: region[1], width: region[2], height: region[3]} if region else sct.monitors[1] sct_img sct.grab(monitor) img Image.frombytes(RGB, sct_img.size, sct_img.bgra, raw, BGRX) img.save(output_path) return output_path def build_context(annotation, screenshot_path): 将标注坐标和截图路径封装成上下文结构 return { annotation: annotation, context: { screenshot_path: screenshot_path, element_hint: annotation.get(position), scene: 用户对当前屏幕内容进行了批注请结合批注内容处理, } } if __name__ __main__: region (320, 480, 180, 60) path capture_screen(region) annotation { type: rectangle, content: 这个按钮点击后没有反应, position: {x: 320, y: 480, width: 180, height: 60} } payload build_context(annotation, path) print(json.dumps(payload, ensure_asciiFalse, indent2))这个示例里capture_screen负责按坐标截取屏幕区域build_context负责把标注信息和截图路径封装成结构化数据。实际产品中这里的region应该来自用户在标注交互层画的矩形框。4.4 Agent 调用客户端接下来把封装好的数据结构发送给 Agent 服务。这里以 OpenAI 兼容接口为例演示思路。# 文件路径agent_client.py import json from openai import OpenAI client OpenAI() # 按你的实际服务配置 base_url 和 api_key def send_to_agent(payload): messages [ { role: system, content: 你是屏幕协作助手。用户会在屏幕上做批注并附上上下文 请根据批注内容和上下文理解用户意图并给出可执行建议。 }, { role: user, content: json.dumps(payload, ensure_asciiFalse) } ] response client.chat.completions.create( modelgpt-4o-mini, messagesmessages, temperature0.2 ) return response.choices[0].message.content if __name__ __main__: sample_payload { annotation: {content: 这个按钮点击后没有反应}, context: {text: 订单状态待发货操作按钮发货、取消、打印} } result send_to_agent(sample_payload) print(result)这段代码将标注数据和上下文作为用户消息发送系统提示词中注明了助手的工作方式。你可以根据实际 Agent 框架替换成工具调用、任务队列等更复杂的逻辑。4.5 完整链路与验证把两步串起来一个最小原型就完成了用户框选屏幕区域并写入批注文字。build_context封装标注和上下文。send_to_agent调用 Agent返回处理建议。在这个原型基础上可以继续扩展的功能包括OCR 自动提取截图中文字、DOM 元素定位替换坐标、异步任务进度通知、多轮对话记忆等。每一步扩展都会让工具更接近可用产品但核心链路始终是“屏上批注 → 上下文提取 → Agent 执行”这三段。5. 常见问题与排查思路在开发和运行这类工具时会碰到不少问题。下面按高频程度整理成表格再展开说明几个典型的。问题现象常见原因解决思路Agent 执行提供方长时间无响应服务超时、模型负载高、网络链路问题检查超时配置增加重试切换备用服务批注坐标和页面元素对不上分辨率变化、窗口缩放、多显示器保存相对坐标记录窗口位置和缩放比OCR 识别结果乱码或缺失图片清晰度不足、字体怪异提高截图分辨率结合 DOM 文本提取Agent 返回内容与批注无关上下文结构不清晰、提示词缺失优化数据结构补充系统提示词屏幕内容涉及敏感信息用户无感知上传增加脱敏处理和用户确认机制5.1 Agent 执行超时错误很多 Agent 开发者在日志中看到类似错误The agent execution provider did not respond in time. This may indicate the ...这条错误的核心信息是“执行提供方没有及时响应”。可能的原因有三个。第一你调用的 Agent 服务承载能力有限任务队列堆积导致超时。第二模型生成时间本身就很长超过了客户端设置的 timeout。第三网络代理、认证失效或服务端故障导致请求悬挂。排查时建议按顺序检查查看 Agent 服务侧日志确认请求是否到达。检查客户端超时配置适当延长。如果是长时间任务改成异步提交避免同步等待。增加重试和降级策略比如切换到备用模型服务。这类超时问题在 Agent 开发中非常常见尤其是接入了本地模型或第三方执行框架后稳定性会比官方 API 差一些。设计时不要假设服务永远可用。5.2 批注坐标映射问题另一个高频问题是用户在不同分辨率或缩放比例下做批注结果坐标和截图内容对不上。解决思路是不要直接存绝对像素坐标。保存时同时记录当前屏幕分辨率和缩放比例。所在窗口的位置和大小。批注在窗口内的相对坐标也就是百分比坐标。Agent 拿到相对坐标后再根据实际截图尺寸还原绝对位置这样可以兼容多显示器和窗口拖动的情况。5.3 隐私与权限问题屏幕内容很可能包含敏感信息比如内部系统地址、个人数据、密钥等。把整张截图发送给云端 Agent本身就有泄露风险。这类问题最好的解决思路是提前预防发送前让用户确认或者对截图进行模糊处理只保留批注区域附近的内容。产品设计上要遵循最小化原则能只发送局部区域就不要发送整屏。6. 工程化与最佳实践从“能跑的 Demo”到“能上线的产品”中间还差不少工程细节。下面几条是我认为最值得注意的。6.1 标注数据结构版本化批注数据格式是前后端、用户与 Agent 之间的协议。一旦发布出去就很难随意修改。建议在数据结构中增加schema_version字段后续升级时保留向后兼容。{ schema_version: 1.0, annotation: { }, context: { } }版本化能避免“旧客户端生成的数据新 Agent 解析不了”这类兼容性灾难。6.2 上下文裁剪与 token 管理屏幕内容可能非常长整页文本全部塞进上下文既浪费 token又会干扰 Agent 判断。建议在发送前做裁剪优先发送批注区域附近的文本。过滤掉无意义的导航文字、广告、固定页脚。对长文本做摘要控制上下文在模型窗口的合理范围内。上下文质量比上下文数量更重要。给 Agent 一堆无关信息反而会降低任务完成准确率。6.3 隐私保护与最小权限屏幕批注类工具天然拥有高权限能读取用户屏幕上的一切。开发和使用时都要非常克制只在用户主动批注时才采集屏幕内容。不后台持续截图。发送前展示将要上传的数据摘要。提供“仅批注区域”或“全部模糊”等选项。支持本地模型把数据不出设备作为可选模式。这一点不是可选项而是产品能长期存在的基本要求。6.4 日志与可观测性Agent 任务链路长涉及截图、OCR、模型调用、工具执行多个环节。建议给每次请求生成一个trace_id贯穿所有日志方便排查问题。trace_id: 8f2a1c9e-4b3d-41d6-9f0a-7c1e2a9b8d4f 1. 2026-01-01 10:00:01 capture_screen success 2. 2026-01-01 10:00:02 build_context success 3. 2026-01-01 10:00:05 agent call success, cost2.8s日志里要记录关键节点的耗时、参数摘要和错误信息但不要记录完整的屏幕截图内容避免日志本身变成敏感信息泄漏点。6.5 异步任务与状态反馈Agent 任务耗时长用户等待过程中需要知道“发生了什么”。建议把任务设计成异步执行用户提交批注后立即返回任务 ID。后台执行采集、提取、调用 Agent 等步骤。用户通过轮询或 WebSocket 获取进度。任务完成后通过系统通知提醒。状态反馈能显著提升用户体验也能降低超时报错的感知。6.6 安全边界与变更规范如果工具涉及执行 Agent 返回的代码或 SQL一定要增加人工确认步骤。Agent 的输出不能直接无条件执行尤其是删除、更新、写入类操作。生产环境变更必须经过授权、测试环境验证和备份这和任何自动化运维工具的规则是一致的。7. 总结与学习路线Remarc 这个项目的价值不只是一款具体工具更是一种值得借鉴的交互范式把“看见问题”和“派发任务”合并成一步。屏幕批注作为上下文输入填补了人类自然表达和 Agent 结构化输入之间的缝隙。这种思路在 Agent 应用越来越普及的背景下会有更多适用场景。如果你对 Agent 开发感兴趣下一步的学习路线可以这样安排掌握 LLM API 基础理解消息结构、温度参数、上下文窗口。学习提示词工程重点是结构化输出和少量示例。掌握函数调用Function Calling让模型能使用工具。学习主流 Agent 框架的任务编排模式理解 ReAct、Plan-and-Execute 等循环思想。深入工程化主题可观测性、任务评估、安全权限、成本控制。在动手实践方面我建议你先不要急着做完整的桌面应用而是先复刻一个最小链路截取屏幕区域 → 封装批注 JSON → 调用 Agent 接口返回结果。跑通之后再逐步加入 OCR、元素定位、异步任务这些能力。这样既能快速看到效果又能一步步理解 Agent 应用的工程复杂度。屏幕上的信息是用户意图最丰富的载体而 Agent 是未来最高效的执行者。能在这两者之间做好翻译的工具一定会越来越多Remarc 是其中一个值得关注的尝试。如果你也在做类似的 Agent 应用欢迎先动手搭一个原型踩过一轮坑之后你会对“上下文为王”这句话有更深的体会。