knowledge-work-plugins 之 PDF Viewer 插件：交互式 PDF 批注、表单填写与签名工作流实战指南

knowledge-work-plugins 之 PDF Viewer 插件：交互式 PDF 批注、表单填写与签名工作流实战指南

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins

本文以 pdf-viewer 插件为对象，系统讲解如何在 Claude Cowork 中利用view-pdf技能与本地 MCP 服务实现交互式 PDF 协作：打开文档、高亮批注、填写表单、加盖印章与放置签名图片，并通过截图实时校验结果。读完本文，你将掌握display_pdf/interact两个核心工具的完整调用契约、十类批注对象的参数体系，以及批注协作、可视化表单填写、视觉签名三条标准工作流，并理解其底层基于@modelcontextprotocol/server-pdf的本地运行原理。

一、插件定位：交互式查看，而非文本摄取

view-pdf技能的核心价值在于让用户与 AI 在同一份文档上可视化协作。技能 frontmatter（SKILL.md）中的描述明确写道：当用户希望打开、展示、查看 PDF 并进行可视化协作（批注、高亮、盖章、填写表单、放置签名或共同审阅标记）时使用；而不建议用于摘要或文本提取。

适用场景（Use）

• 「帮我看看这份合同」/「打开这篇论文」
• 「把关键条款高亮出来让我审阅」
• 「帮我填一下这个表单」
• 「在第 3 页签名」/「每页加上我的首字母」
• 「盖上 CONFIDENTIAL 章」/「标记为已批准」
• 「带我过一遍文档并批注重要部分」

不适用场景（Do NOT use）

用户意图	正确做法
「总结这个 PDF」	直接使用原生 Read 工具
「第 5 页说了什么？」	使用 Read
「提取第 3 节的表格」	使用 Read

正如插件 README 所强调的：当只需要 Claude 原生阅读 PDF 进行摘要或文本提取时，不要使用本插件，原生 Read 对纯摄取场景更快。查看器的价值在于向用户展示文档并协作批注，而不是把文本流式返回给 AI。

二、运行原理与前置条件

插件本身只是 Markdown 描述文件（技能、命令、连接器配置），真正的渲染能力来自一个本地 MCP 服务。根据 CONNECTORS.md 中的连接器清单：

类别	服务端	运行方式
PDF 查看与批注	@modelcontextprotocol/server-pdf	本地 stdio 方式，经npx自动安装并启动

前置条件（Requirements）

• Node.js >= 18：npx运行本地 PDF 服务的基础环境；
• 网络连接（仅远程文档需要）：打开 arXiv、bioRxiv 等远程 PDF 时需要联网；
• 无需任何 API Key 或认证：PDF 服务在插件加载时随本地 MCP 自动启动，不依赖云端服务。

也就是说，插件开箱即用：本地npx拉起 stdio 子进程，无需配置密钥，也不会上传文档到远程。

三、工具契约：list_pdfs/display_pdf/interact

view-pdf技能向 AI 暴露三个工具，理解它们的分工是正确使用的前提。

1.list_pdfs— 枚举可用文档

• 作用：列出可用的本地 PDF 与允许访问的本地目录。
• 参数：无。
• 使用时机：用户给出路径时直接进入display_pdf；未给路径时先调用list_pdfs展示可选文档（见 open.md）。

2.display_pdf— 在交互查看器中打开文档

• url：本地文件路径或 HTTPS 链接；
• page（可选）：初始页码，默认第 1 页；
• elicit_form_inputs（可选）：设为true时，服务端在展示前先提示用户填写表单字段，适合交互式表单填写。

关键约束：每个文档只调用一次display_pdf。返回的viewUUID必须传递给后续每一次interact调用。若再次调用display_pdf，会创建一个独立的新查看器，用新 UUID 发起的interact无法作用到用户当前正在看的那份文档上——这是实践中最容易踩的坑。

如果 PDF 含有可填写字段，display_pdf还会返回formFields（字段名、类型、所在页码、包围盒坐标），这些坐标可直接用于定位签名位置。

3.interact— 打开之后的所有后续操作

display_pdf之后的所有动作都通过interact完成，需传入viewUUID加一个或多个命令。多条命令可通过commands数组在同一次调用中批量提交，命令按顺序依次执行；批处理末尾应追加get_screenshot以可视化校验变更结果。

批注类动作（Annotation actions）

动作	说明
add_annotations	新增批注（类型见下文表格）
update_annotations	修改已有批注（必须带id与type）
remove_annotations	按 id 数组删除批注
highlight_text	按文本查询自动定位并高亮（优于手工绘制 rect，推荐用于文本标记）

导航类动作（Navigation actions）

动作	说明
navigate	翻页，参数page
search	搜索（有反馈）
find	静默搜索
search_navigate	按matchIndex跳转到匹配项
zoom	缩放，比例范围0.5–3.0

提取类动作（Extraction actions）

• get_text：提取页面范围文本，单次最多 20 页。用途是读取内容以决定批注什么，不得用于摘要；
• get_screenshot：将页面截取为图片，用于核对批注效果（每次批处理结束都应调用）。

表单动作（Form action）

• fill_form：按字段名填充，负载形如fields: [{name, value}, ...]。

四、批注类型全景：坐标体系与参数表

所有批注都必须包含id（唯一字符串）、type（类型）、page（从 1 开始的页码）。坐标单位为PDF 点（1/72 英寸），原点位于页面左上角，Y 轴向下增大；美式 Letter 纸为 612×792 pt。

类型	关键属性	用途
highlight	rects、color?、content?	标记重要文本
underline	rects、color?	强调术语
strikethrough	rects、color?	标记删除内容
note	x、y、content、color?	便签式评论
freetext	x、y、content、fontSize?	页面可见文本
rectangle	x、y、width、height、color?、fillColor?	框选区域
circle	x、y、width、height、color?、fillColor?	圆形区域
line	x1、y1、x2、y2、color?	画线/箭头
stamp	x、y、label、color?、rotation?	加盖 APPROVED、DRAFT、CONFIDENTIAL 等印章
image	imageUrl、x?、y?、width?、height?	签名、首字母、Logo

图片批注（image）接受本地文件路径或 HTTPS URL（不支持 data: URI）；宽高省略时自动检测。用户也可以把图片直接拖拽到查看器上完成同样的放置。

五、三大交互工作流

5.1 协作式批注（AI 主导）

这是插件最典型的用法，对应 annotate.md 中的「AI 驱动默认流程」：

1. display_pdf打开文档；
2. interact→get_text读取相关页区（≤20 页）理解内容；
3. 向用户提案要做的批注（说明将标记什么），例如：

   "我会高亮第 2 页的终止条款，在旁边加一条备注 'Review 30-day window'，并在第 1 页盖上 DRAFT 章，可以吗？"

4. 获准后，interact→add_annotations+get_screenshot；
5. 展示截图给用户，接受修改意见并迭代；
6. 完成时提醒用户可从查看器工具栏下载带批注的 PDF。

Manual 模式：若用户给出明确指令（如「高亮第 3 段」「每页盖 CONFIDENTIAL」），跳过提案步骤直接执行，但仍需用截图确认。

实操要点（Tips）：

• 文本标记优先用highlight_text（自动找坐标），优于手工rects；
• 相关批注尽量合并到同一次interact调用批量提交；
• 每次批处理以get_screenshot收尾，让用户看到结果；
• 每批提案控制在3–5 条批注，便于用户逐批审阅。

5.2 可视化表单填写（视觉反馈，而非程序化填充）

与无头表单工具不同，本流程给用户实时视觉反馈，尤其擅长处理真实世界里字段名晦涩或未命名的表单——标签印在页面上而非字段元数据里。

AI 辅助流程（复杂表单 / 未命名字段）：

1. display_pdf（不带 elicit），检查返回的formFields（name、type、page、bounding box）；
2. 若字段名晦涩（如Text1、Field_7），用interact→get_screenshot截取含字段的页面，将包围盒与视觉标签一一对应；
3. 用视觉标签向用户征询取值，或根据对话上下文推断；
4. interact→fill_form，随后get_screenshot展示结果；
5. 用户确认，或直接在查看器中编辑修正。

用户驱动流程（简单且标签清晰的表单）：直接调用display_pdf并设置elicit_form_inputs: true，服务端会先检测表单字段并在查看器打开前提示用户输入，随后展示填充完成的 PDF。

W-9 示例对话（出自 fill-form.md）：

用户：帮我填一下这个 W-9 表。AI：display_pdf→ 得到 formFields：f1_1、f1_2、f1_3、c1_1……（晦涩命名）AI：interact→get_screenshot第 1 页 → 发现f1_1紧邻 "Name"、f1_2是 "Business name"、c1_1是 "Individual" 复选框AI：「我能看到 Name、Business name、Address、TIN 和税务分类复选框。我会用已知信息填 Name 和 Date——你的 TIN 和公司地址是多少？」AI：获得回答后 →interact→fill_form+get_screenshotAI：「这是填好的表单[截图]。签名行还是空的——需要我用/pdf-viewer:sign帮你签名吗？」

补充说明：

• 签名域通常独立，先填文本字段，再交接给签名命令放置图片；
• 复选框/单选框的值为true/false或选项字符串；
• 用户始终可以直接在查看器中拖拽编辑字段。

5.3 视觉签名（非认证签名）

签名本质上是一条image类型批注，完整工作流见 sign.md：

1. 获取签名图：向用户索要签名/首字母图片的本地路径（PNG/JPG）；若没有，建议其制作并保存到已知路径；
2. 打开 PDF：display_pdf（或复用已有viewUUID），检查返回的formFields中是否有签名类型字段（含页码与包围盒坐标）；
3. 定位目标：有签名域则用其坐标；否则询问「签在哪一页的什么位置？（如第 3 页右下角）」；
4. 放置：interact→add_annotations：

{"action": "add_annotations", "annotations": [ {"id": "sig1", "type": "image", "page": 3, "imageUrl": "/path/to/signature.png", "x": 400, "y": 700, "width": 150} ]}

宽高省略时按图片自动检测； 5.校验：跟随get_screenshot截取该页并展示给用户，位置不对用update_annotations调整； 6.每页加首字母：在单次add_annotations调用中为每页批量提交一条image批注。

签名放置小贴士：imageUrl接受本地路径或 HTTPS URL（不支持 data: URI）；用户也可直接把签名图拖拽到查看器；坐标原点在左上角，美式 Letter 纸的典型右下角签名位置约为x: 400, y: 700；可与表单填写命令配合完成完整表单流程。

免责声明：本流程放置的是视觉签名图片，不是经过认证或加密的数字签名。需要具备法律约束力的电子签名时，请使用专门的签名服务。此声明在 sign.md 与 README.md 中均有明示。

六、支持的文档来源

根据 SKILL.md 与 open.md 的说明，display_pdf的url支持三类来源：

• 本地文件：位于客户端 MCP 根目录下的路径，也可直接拖入工作目录；
• arXiv：arxiv.org/abs/...这类/abs/URL 会自动转换为 PDF 链接；
• 任意直接 HTTPS PDF 链接：bioRxiv、Zenodo、OSF 等——必须使用直接 PDF 链接，而不是论文落地页。

打开文档后，可根据文档类型主动提供下一步建议（来自 open.md）：

• 合同/报告→「要我高亮关键章节或加审阅备注吗？」
• 表单→「这张表有可填写字段——需要我帮你填吗？」
• 学术论文→「要我带你过一遍并批注关键发现吗？」

七、边界范围（Out of Scope）

明确不属于view-pdf技能职责的事项：

• 摘要 / 文本提取—— 使用原生 Read 工具；
• 认证数字签名—— 仅支持图片盖章；
• PDF 创建—— 仅对已存在的 PDF 操作，不生成新文档。

八、配套 Slash 命令速查

插件在commands/目录下提供了四个显式调用的斜杠命令（见 README.md 命令表）：

命令	功能
/pdf-viewer:open	在交互查看器中打开 PDF
/pdf-viewer:annotate	逐段浏览文档，提案并应用批注，共同审阅
/pdf-viewer:fill-form	交互式填写 PDF 表单字段
/pdf-viewer:sign	在页面上放置签名或首字母图片

这些命令是可选的快捷入口；技能（Skill）本身会在场景相关时自动触发。需要核对工具连接状态时，可查阅 CONNECTORS.md。

九、最佳实践小结

1. 严格区分摄取与协作：摘要、提文本用原生 Read；可视化协作才进查看器；
2. 一个文档一次display_pdf：牢记viewUUID，避免多实例错乱；
3. 批量 + 截图闭环：批注命令打包进同一次interact，末尾必跟get_screenshot；
4. 文本批注优先highlight_text：让服务端自动定位文本，避免手工 rect 坐标误差；
5. 表单字段名晦涩时先截图：用视觉标签对应用户语义，再执行fill_form；
6. 签名仅为视觉效果：需要法律效力时切换到专门电子签名服务；
7. 遵守范围边界：不做摘要、不做认证签名、不做 PDF 创建。

十、深入阅读

• 技能定义：pdf-viewer/skills/view-pdf/SKILL.md
• 插件总览与命令表：pdf-viewer/README.md
• 本地 MCP 连接方式：pdf-viewer/CONNECTORS.md
• 各场景命令手册：open.md、annotate.md、fill-form.md、sign.md

该插件采用 Apache License 2.0 开源（见 pdf-viewer/LICENSE），全部组件均为 Markdown 描述文件，无代码、无构建步骤，可直接阅读或按团队流程裁剪使用。

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins