AI 2026年6月25日 2 分钟阅读

AI Agent 看不懂你的截图？用 Pinpoint 的数字标记法让 Claude Code 精准定位每一像素

tinyash 0 条评论

问题：你和 AI Agent 之间的截图沟通鸿沟

如果你经常用 Claude Code、Codex 或 Cursor 等 AI 编码 Agent 做前端调试或 UI 修复，大概率遇到过这个场景：

你截了一张图发给 Agent，然后打了一段文字描述：「右上角那个按钮颜色不对，旁边的图标也歪了。」

Agent 回复了一段代码。你一看 — 它改了左侧的按钮，不是右上角那个。

问题出在哪里？AI 能「看」到截图，但它不知道你指的究竟是 哪一个 元素。人类可以通过「那个」「这个」「右上角」等模糊指代来沟通，但 Agent 需要精确的坐标和编号。截图本身不携带任何标注信息，而文字描述在粘贴过程中经常丢失或被截断，最终 Agent 只能靠「猜」。

这不仅仅是效率问题 — 来回纠正造成的上下文浪费会直接推高 API Token 消耗，每个无效往返可能花费数百到上千 Token。

Pinpoint 的解决思路：用数字标记代替文字描述

Pinpoint 是一个 macOS 菜单栏原生应用，由独立开发者 Baptiste Bouillot（@croustibat）发布。它解决的核心问题非常直接：让你像跟人类同事沟通一样，在截图上「指一下」再发给 AI Agent。

Pinpoint 的工作原理分三步：

  1. 截图 — 快捷键调出区域选择器，框选目标区域
  2. 标记 — 在截图的关键元素上点击放置编号标记（数字圆圈标号）
  3. 发送 — 复制带标注的截图 + 结构化文本提示词，粘贴到 Claude Code 或 Codex

这个流程借鉴了人类视觉沟通最自然的方式：不说「那个按钮」，而是指着一号标记说「改这个」。Pinpoint 把这种直觉体验带到了 AI Agent 交互中。

快速上手：5 分钟配置

安装

从 GitHub Releases 下载 Pinpoint.dmg，拖入 Applications 文件夹即可。应用已经过 Apple Notarization（公证签名），打开时不会触发系统安全警告。

首次启动后，系统会请求屏幕录制权限（Screen Recording），在 系统设置 → 隐私与安全性 → 屏幕录制 中授予权限后，退出并重新启动 Pinpoint 即可。

系统要求：macOS 15+（Sequoia），Apple Silicon 和 Intel 均可。

基本操作

  • ⌘⇧1 — 触发区域截图，鼠标拖拽选择范围（Esc 取消）
  • 截图后自动打开标注编辑器，在目标元素上单击即可落下编号标记
  • 拖动标记可以调整位置，右侧面板可为每个标记添加备注文字
  • ⌘C — 复制标注后的截图 + 结构化提示文本到剪贴板
  • 菜单栏还有一个「截全屏」选项，适合需要完整页面上下文时使用

核心功能详解

1. Region Capture（区域截图）

Pinpoint 调用 macOS 原生的 ScreenCaptureKit 框架进行截图，支持 Retina 分辨率和多显示器。拖拽选择时实时显示像素尺寸（1280×800 等），方便你精确控制发送给 Agent 的上下文范围。

2. Numbered Markers（编号标记）

这是 Pinpoint 最核心的功能。在标注编辑器中，每次点击画布都会生成一个带圆圈的编号标记。每个标记可以附带文本备注（如「CTA 按钮」「图标偏移」），也可以添加箭头和矩形框做辅助标注。

支持三种标记样式：

  • 实心圆（Filled Disc） — 最醒目，适合主要操作点
  • 指针标（Pointer Pin） — 形似图钉，适合精准定位
  • 轮廓标记（Light Outline） — 比较轻量，适合辅助性标注

三种样式在截图画面和最终导出的图片中保持一致。

3. Structured Prompt（结构化提示）

当你按下 ⌘C 时，Pinpoint 不仅将标注后的 PNG 图片写入剪贴板，还会同时复制一段结构化文本提示：

An image is attached. Numbered (ringed) badges point to specific elements.
Markers (position in % of the image, top-left origin):

1. Primary CTA button · ~62 % × 48 %
2. Misaligned icon · ~12 % × 22 %

## Instructions
Make the CTA full-width on mobile and fix the icon alignment.

这段文本以 Markdown 格式呈现，Claude Code、Codex 等 AI Agent 可以干净地解析每个标记的位置（百分比坐标）和描述。你只需在 ## Instructions 下方补充具体的修改指令即可。

4. Legend Baked In（内嵌图例）

这是一个非常实用的设计细节。大多数聊天 UI（包括 Claude Code 的终端界面）在粘贴图片和文字时，经常只保留图片而丢弃剪贴板中的另一部分文本。Pinpoint 的可选「图例内嵌」模式会将所有标记描述和指令直接渲染到图片内部，这样即使文字部分丢失，Agent 仍然能从图片中读取标记对应的信息。

5. The Shelf（截图库）

Pinpoint 内置了一个截图历史库（Shelf），所有历史截图自动保存到 ~/Library/Application Support 中。你可以：

  • 浏览、收藏、重命名历史截图
  • Quick Look 快速预览
  • 重新打开任意历史截图的标注编辑器，继续编辑标注后重新发送

这对于需要反复调试同一 UI 元素的场景非常实用 — 不需要每次重新截图。

6. 隐私与安全

所有截图均存储在本地 macOS 文件系统中，不会上传至任何远程服务器。Pinpoint 使用 ScreenCaptureKit 原生框架，没有网络权限请求，也不需要用户注册或登录。

实战场景：用 Pinpoint + Claude Code 调试前端页面

假设你正在用 Claude Code 修改一个 React 组件的响应式布局：

  1. 在浏览器中打开页面，按下 ⌘⇧1 框选需要修改的区域
  2. 在截图上标记：
  • 标记 1：「移动端菜单按钮」— 点击后菜单不展开
  • 标记 2：「商品卡片间距」— 间距比桌面端大了 2 倍
  • 标记 3：「Footer 文字」— 超出容器边界
  1. 为标记 3 添加箭头标注指向溢出区域
  2. 在 Instructions 中写：「修复以上 3 个移动端样式问题，保持 Tailwind 现有类名风格」
  3. ⌘C 复制内容，粘贴到 Claude Code 终端

Claude Code 收到的结构化提示包含了精确的坐标信息和每个标记的说明，它知道标记 1 是汉堡菜单按钮、标记 2 是卡片间距、标记 3 是 Footer 溢出。不再需要在文字里反复描述「左边第二个…不是，是上面的那个…」。

从源码构建

Pinpoint 使用 XcodeGen 管理 Xcode 项目，依赖极少：

brew install xcodegen
git clone https://github.com/croustibat/Pinpoint.git
cd Pinpoint
xcodegen generate
open Pinpoint.xcodeproj

在 Xcode 中按 ⌘R 即可运行。如果不想配置签名证书：

xcodegen generate && xcodebuild -scheme Pinpoint \
  -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO build

项目结构清晰，PinpointApp.swift 是入口，Exporter.swift 处理最终的图片+文本导出逻辑，EditorView.swift 管理标注编辑器 UI。如果你想贡献自定义标记样式或新的导出格式，修改成本很低。

对比其他方案

方案精度操作成本隐私
手打文字描述「左上角第三个按钮」低（模糊）低依赖聊天工具
截图 + Paint 手动画圈中高（需切应用）本地
Pinpoint高（百分比坐标）低（快捷键 + 单击）纯本地
Browser Debugger 截图工具高中本地

Pinpoint 的精确定位能力（百分比坐标 + 编号引用 + 结构化文本）是其他方案不具备的 — Claude Code 可以直接在代码中引用「标记 1 的位置」而无需猜测。

已知局限

  • 仅支持 macOS 15+，暂不支持 Windows 或 Linux。开发者用 Swift/SwiftUI 原生实现，跨平台移植需要重写截图和权限逻辑。
  • 需屏幕录制权限，首次配置需要进系统设置开启。
  • 当前 GitHub Stars 较少（项目 2026-06-16 创建），但代码质量扎实，MIT 许可，可以放心使用。

总结

Pinpoint 解决的是一个很小但非常痛的体验问题：如何让 AI Agent 精确理解你在 UI 截图上想表达的内容。 它没有做复杂的 AI 推理或云服务，而是老老实实做好截图标注 + 结构化提示这件事。对于每天用 Claude Code 调试前端、设计还原的开发者来说，Pinpoint 能显著减少和 Agent 之间的「无效沟通」次数 — 这不仅省时间，更省钱（减少 Token 浪费）。

  • 项目地址：https://github.com/croustibat/Pinpoint
  • 下载地址：https://github.com/croustibat/Pinpoint/releases/latest
  • 官方网站：https://pinpoint-ashy.vercel.app
  • License：MIT
  • 开发者：Baptiste Bouillot（@croustibat）

相关链接

AI AI 工具 Claude Code 开发工具 开源 教程

发表评论

你的邮箱地址不会被公开，带 * 的为必填项。