An AI 代理可以通过查看它刚刚标注的页面来验证自己的标注。使用 GroupDocs.Annotation.Mcp，Claude、Cursor 或 GitHub Copilot 中的 LLM 对文档进行标注，请求服务器将页面渲染为包含标注的 PNG，并判断标注位置是否正确。服务器在本地完成工作；提示语只有一句话：

Highlight the payment clause on page 2, then show me the page.

逐步的配置和故障排除版本在文档中： How to let an AI agent see the document page it annotated.

注意：generate_pages_preview 目前在 Linux 上（包括 Docker 镜像）处理 PDF 文件会失败；请在构建前查看 Honest limits。

为什么无法看到输出的代理会错误地报告成功？

大多数文档工具都是写入式的。代理调用它们后只会说“完成”，因为调用返回了。对于标注来说，这种说法可能是错误的，却没有任何错误信息显示：调用成功，但高亮标记位于错误的段落。坐标 x 和 y 是文档坐标，若让代理高亮“付款条款”，它必须自行猜测该条款所在位置，除非有其他信息指示。

区别在于“我添加了一个高亮”和“高亮位于付款条款”。只有第二种说法有意义，只有查看页面才能验证它。

代理如何渲染带标注的页面图像并进行检查？

这些工具形成一个简短的循环。

  1. add_annotation 写入标注并保存为 contract_annotated.pdf。原始文件保持不变。
  2. generate_pages_preview 将该文件的页面渲染为 PNG 图像，标注已嵌入，并以内联方式返回。pages 参数可设为 2、1-3 或 1,3,5。如果省略，则返回第 1 页。
  3. 代理查看图像。如果高亮覆盖了错误的文本，update_annotation 可以修改其内容或位置、大小，而无需重新开始。

预览返回一个描述渲染内容的文本块，随后为每页返回一个图像块。一次调用最多渲染五页。

在对生成的文件进行链式编辑之前，将 GROUPDOCS_MCP_OUTPUT_PATH 设置为除存储文件夹之外的其他文件夹。使用默认设置（输出落在存储文件夹）时，第二次写入会因 being used by another process 而失败；使用单独的输出文件夹时，add_reply、update_annotation 和 remove_annotations 对生成的文件都能成功。使用 Docker 镜像时，传入 -e GROUPDOCS_MCP_OUTPUT_PATH=/data/output。下面的会话假设已进行此设置，生成的文件位于 output/ 下。

代理需要哪些条件才能工作？

  • 能够显示图像内容的客户端。 Claude Desktop 能做到。终端客户端可能只能报告返回了图像。工具的行为在两者之间相同，只是图像可能不会被显示。
  • 具备视觉能力的模型。 图像仅对能够接受图像输入的模型有帮助。
  • 小范围的页面。 渲染是该服务器最耗时的调用。只请求你需要的页面，而不是整份五十页的文件。

预览还有哪些其他用途？

  • 在标注前定位。 先渲染页面，让模型读取页面内容，然后使用模型推导出的坐标而非猜测来放置标注。
  • 检查合并。 在对重新排版的草稿执行 import_annotations 后，预览可以显示导入的批注是否仍在正确位置。
  • 在聊天中向审阅者展示结果，无需打开文件。
  • 发现评估徽章。 在评估模式下，每页都会盖上试用徽章，因此在渲染的图像中可见。

示例会话（节选）

这是一幅基于工具文档行为构建的示例说明，并非实际截图。它假设在预览渲染器能够处理 PDF 文件的平台上运行，例如使用 dnx 的 Windows。

你:   在 contract.pdf 的第 2 页高亮付款条款，然后展示该页。

代理: [calls add_annotation: type=highlight, page=2, x=100, y=250,
        text="Payment clause"]
       已在 contract.pdf 第 2 页添加高亮标注。
       [calls generate_pages_preview on output/contract_annotated.pdf, pages="2"]
       (图像：第 2 页，已渲染高亮标注)
       高亮位于“Delivery”段落上方一个块的位置，而不是付款条款。将其向下移动。
       [calls get_annotations, then update_annotation: y=330]
       已在 output/contract_annotated.pdf 中更新注释 1。
       (代理将每次调用返回的文件名传递给下一次调用。)

渲染在哪里运行，哪些内容会离开机器？

引擎在你的机器上生成 PNG。随后图像会像其他消息内容一样传输到模型提供商，因此在使用云托管模型时，预览会将该页的图片发送出去。对于敏感文档，请使用本地部署的模型。

诚实的限制

  • Linux 上的预览。 generate_pages_preview 目前在 Linux 上（包括 Docker 镜像）处理 PDF 文件会失败（Gdip 的 TypeInitializationException：System.Drawing.Common 在非 Windows 平台上不受支持）；Word 和其他 Office 文档可以渲染，在 Windows 使用 dnx 时所有格式均可渲染。其他十个工具不受影响。
  • 评估模式。 在评估模式下，试用徽章会被盖在标注文件和预览的每页顶部。使用输出前请检查 get_license_status。
  • 近似放置仍保持近似。 预览只能让模型发现标注位置错误；它不会把猜测的坐标转换为精确坐标。
  • 仅文本模型无法检查。 仅文本模型仍然只能收到文本块，无法判断页面的实际外观。

常见问题

AI 能够检查评论落在页面的哪个位置吗？
可以，只要模型接受图像输入。代理使用 generate_pages_preview 渲染带标注的页面并检查图片，必要时使用 update_annotation 调整标注。

如何为代理预览带标注的 PDF 页面？
按页码请求，例如“渲染标注合同的第 1‑3 页，以便我检查评论”。代理会将 pages 设置为 1-3，PNG 会以内联方式返回。

为什么预览在我的 Docker 容器中失败？
对于 PDF 文件，工具在 Linux（包括 Docker 镜像）上会因 Gdip 类型初始化错误而失败。Word 和其他 Office 文档可以渲染，在 Windows 使用 dnx 时所有格式均可渲染。

深入了解