把视觉上下文发给智能体

Pinar 会把纯 Markdown 和 HTML 写入剪贴板。文本包含可读标注，外加带围栏的 pinar-visual-context JSON 代码块。请把两者作为整体粘贴；结构化代码块才是机器可读的事实来源。

如果数据包列出了绝对 Screenshot 路径，本地智能体应打开那一张图像；编号徽章是叠加层。screenshot_missing、helper_unavailable 或 viewer_unavailable 这类警告描述的是降级交付，并不会让评论和 DOM 上下文失效。

Chrome 扩展从不会向智能体撰写框自动输入。在“提示”模式下，Command+Enter / Alt+Enter 之后，请自行把剪贴板粘贴到 Cursor、Claude、Codex 或 Grok。文本开头会说明图钉备注可能是改动请求，也可能是解释问题，并把选择器和 DOM 路径当作互补定位器，随后是带围栏的 pinar-visual-context JSON 代码块。如果包含查看器 URL，仅在这些细节不够时再去获取。在“链接”模式下，智能体只收到会话链接，需要有权访问该 .md（Pinar Cloud 链接是私有的，需要 API key 或 MCP）；“关闭”只保存不复制。

把 captureId 和 pinId 当作身份，而不是可以改写的标签。Visual Context 目前编码 schemaVersion 1；parseVisualCapture 会拒绝缺失的 captureId，以及任何不是 1 或旧版 0 的 schemaVersion。只遵循图钉描述的内容。如果对方从未粘贴，请让他们从 Pinar 再复制一次，而不是凭记忆重建图钉。

• 把整份剪贴板粘贴给智能体；不要重打评论或编造新的 captureId。
• 开始改代码前，确认粘贴的文本仍包含闭合的 pinar-visual-context 围栏。
• 如果什么都没粘贴，请对方在 Pinar 中按 Command+Enter / Alt+Enter，并且只遵循图钉备注。

Pinar 还通过 Model Context Protocol 公开其已保存的会话。MCP 客户端可以列出项目、集合、批次、会话、图钉和图钉评论，并可以创建、评论、重命名、移动、重新排序和删除它们。

Pinar 本地服务在你自己的机器上公开 MCP，无需账户、登录或 API 密钥。Pinar Cloud 需要具有所需权限的 API 密钥，密钥的资源范围限制智能体可以读取、评论或修改的内容。

有关客户端配置（包括端点、身份验证头和协议详情），请参阅 Pinar 仓库中的智能体访问指南。

• 智能体创建的会话仅保存页面元数据，不含截图；智能体图钉保存带可选定位器的评论，而不是测量得到的几何信息。
• MCP 不会重新加载或同步浏览器中的草稿；扩展仍是活动草稿的写入者，稍后的显式保存会在相同 id 下替换已保存的会话。
• 分享保持显式：从工作区发布分享，或让具有分享权限的智能体发布或撤销分享。

本地 Pinar 应用为运行在同一台电脑上的智能体提供相同的 Model Context Protocol 界面，并且按设计是开放的：不涉及账户、登录或 API 密钥。请将您智能体的 MCP 客户端指向 Pinar README 中智能体会话访问部分所描述的端点。

README 中的本地 MCP 工具部分列出了每个工具及其参数和返回值。列表工具会分页返回结果，每页最多 50 条，因此智能体可以逐页遍历大型工作区。重新排序工具期望完整的条目列表，会在任何移动发生前拒绝部分列表。

• 由于连接是本地的，智能体只操作本机保存的捕获，永远不需要 Pinar Cloud。
• 云端工具界面的大部分在本地也可用；仅限云端的附加功能涉及智能体密钥和发布分享。

Pinar Cloud 允许 Pro 账户签发专用的智能体密钥。在工作区打开 「设置 → 代理访问」 即可创建一个：为密钥命名，选择权限——「读取」「管理」「共享」或「完全权限」——以及 7、30 或 90 天的有效期。「读取」密钥的范围可以是整个账户，也可以是单个项目、集合、会话或批次。其他权限作用于整个账户。

密钥只在创建后显示一次，请在对话框关闭前复制它——Pinar 只保留一个短前缀，无法再次显示密钥。同时最多可存在 20 个有效密钥。列表中每个密钥都会显示其范围、权限、有效期和最近使用时间，「撤销」会立即结束它。对超出密钥范围的资源发起请求会得到资源不存在的答复，因此密钥永远不会暴露其范围之外的内容。云端智能体访问指南记录了权限矩阵以及每个密钥背后的完整工具界面。

• 让每个智能体或自动化拥有自己的密钥，这样撤销其中一个就不会影响其他。
• 密钥可用于支持自定义标头的 MCP 客户端，也可用于私有 Markdown 链接；「代理访问」面板解释了密钥的用法。