AI 代理可以透過查看剛剛標註的頁面來驗證自己的註釋。使用 GroupDocs.Annotation.Mcp，Claude、Cursor 或 GitHub Copilot 中的 LLM 會對文件進行註釋，請求伺服器將該頁面渲染為包含註釋的 PNG，並判斷位置是否正確。伺服器在本機執行此工作；提示語只有一句：

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

逐步說明（含設定與故障排除）請參考文件：
如何讓 AI 代理看到它所註釋的文件頁面

注意：generate_pages_preview 目前在 Linux（包括 Docker 映像）上處理 PDF 檔案會失敗；在使用前請參閱 誠實的限制。

為什麼無法看到輸出的代理會錯誤地報告成功？

大多數文件工具都是寫入專用。代理呼叫它們後說「完成」只是因為呼叫已返回。對於註釋而言，這種說法可能在沒有錯誤訊息的情況下是錯的：呼叫成功，但突出顯示位於錯誤的段落。座標 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 套用到重新排版的草稿後，預覽可顯示匯入的註記是否仍位於正確位置。
  • 在聊天中向審閱者展示結果，無需開啟檔案。
  • 辨識評估徽章。 在評估模式下，試用徽章會印在每一頁上，因而在渲染的圖像中可見。

範例會話（節錄）

你：   在 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 頁，已渲染突出顯示)
       突出顯示位於「交付」段落上方一個區塊，應在付款條款之上。將其向下移動。
       [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 時所有格式皆可渲染。

深入了解