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/commands/fill-form.md 为骨架，讲解如何在 Claude Cowork 的 pdf-viewer 插件中通过实时可视化预览完成 PDF 表单填写。你将掌握「用户驱动」与「AI 辅助」两条填充路径、如何应对Text1/Field_7这类无名字段、fill_form的字段值规范，以及如何与签名、标注工作流无缝衔接，最终得到一份可下载的已填写 PDF。

一、先搞清楚：什么是可视化表单填充

/pdf-viewer:fill-form命令帮助用户在实时查看器（live viewer）中完成可填写 PDF 表单。它与程序化表单工具的根本区别在于：每填充一个字段，用户都能在页面上直接看到值落进正确的输入框，而不是只收到一条"填充成功"的消息。

这一点来自 fill-form.md 开篇的定义——它强调的交互本质是「live visual feedback」（实时视觉反馈）与「easy undo/edit」（随时撤销与编辑）。用户在查看器中可以自由拖动、编辑任何字段，也可以随时要求重新调用fill_form填入新值。

二、为什么用它而不是程序化表单工具

原文档 fill-form.md 给出了三个核心理由：

视觉确认（Visual confirmation）：用户看到每个值落在正确的方框里，而不是只看一条成功消息。这对合同、税务表格等需要谨慎确认的文档尤其重要。
无名字段（Unnamed/unlabeled fields）：许多真实世界 PDF 的字段元数据里只有机器名，如Text1、Field_7，甚至完全没有名字。而真正的标签（"Date of Birth"、"SSN"）是打印在渲染页面上、紧邻字段旁边的，不在字段元数据中。此时需要用get_screenshot看清每个字段实际是什么，再按名字填充。
易于更正（Easy correction）：用户可以直接在查看器中编辑或清空任何字段，或要求重新调用fill_form提交新值。

从 pdf-viewer/skills/view-pdf/SKILL.md 可以看到，插件设计者将表单填充明确定位为 "visual, not programmatic"（可视化而非程序化）的工作流，专门处理「字段名晦涩、标签印在页面上而非元数据中」的真实表单。

三、底层环境与工具链（先了解才能动手）

该插件不依赖远程连接器，而是使用一个本地 MCP 服务器。据 pdf-viewer/CONNECTORS.md 说明：

类别	服务器	运行方式
PDF 查看与标注	`@modelcontextprotocol/server-pdf`	通过`npx`本地 stdio 运行（自动安装）

环境要求：Node.js >= 18；如需打开远程 PDF（arXiv、bioRxiv 等）需要联网；无需任何 API Key 或认证，服务器会在插件加载时自动启动（见 README.md）。

填充表单会用到以下 MCP 工具（详见 SKILL.md）：

工具	作用	关键参数 / 返回值
`list_pdfs`	列出可用本地 PDF 与允许访问的目录	无参数
`display_pdf`	在交互式查看器中打开 PDF，每个文档只调用一次	`url`（本地路径或 HTTPS 链接）、`page`（初始页，默认 1）、`elicit_form_inputs`（为`true`时先提示用户填表再显示）；返回`viewUUID`与`formFields`
`interact`	`display_pdf`之后的全部后续动作	传入`viewUUID`+ 一个或多个命令；可通过`commands`数组批量提交，命令按顺序执行
`fill_form`	按名字填充字段	`fields: [{name, value}, ...]`
`get_screenshot`	将页面捕获为图片，用于验证填充结果	`page`
`get_text`	提取页面文本（单次最多 20 页）	用于阅读内容，不适合做摘要

formFields 返回结构

display_pdf返回的formFields包含每个可填写字段的name（名字）、type（类型）、page（页码）、bounding box（包围盒坐标）（见 SKILL.md）。这些坐标同样可用于签名定位。

坐标系统（影响截图与定位）

所有坐标使用PDF 点（1/72 英寸），原点在左上角，Y 轴向下递增；US Letter 页面为 612×792pt（见 SKILL.md）。理解这一点，才能把截图中的视觉标签与formFields的包围盒对应起来。

四、路径一：用户驱动填充（简单、标签清晰的表单）

对于字段标签清晰、用户自己就能看懂的表单，采用最简单的做法：

调用display_pdf并传入elicit_form_inputs: true；
服务器检测到表单字段后，会在查看器打开之前提示用户输入各字段的值；
输入完成后，已填充的 PDF 直接展示给用户。

这条路径适合字段少、名字直观、用户知道自己该填什么的场景，几乎不需要 AI 介入（见 fill-form.md）。SKILL.md同样确认：对简单且标签清晰的表单，用elicit_form_inputs: true让用户预先输入即可（SKILL.md）。

五、路径二：AI 辅助填充（复杂表单、无名字段、已有上下文）

当字段名晦涩（如Text1、Field_7）、字段无名字、或者你手头已有用户上下文时，走完整的 AI 辅助流程（fill-form.md）：

打开并检查：调用display_pdf（不带 elicit），检查返回的formFields——记录每个字段的 name、type、page、bounding box；
截图匹配视觉标签：若字段名晦涩，通过interact→get_screenshot逐页截图，观察每个包围盒旁边的视觉标签，搞清每个字段实际含义；
确定值：对每个字段二选一——
- 从对话上下文中推断（姓名、日期、邮箱等）；
- 向用户提问，并用视觉标签描述字段（例如"第 1 页的 'Date of Birth' 方框"），而非用机器名提问；
填充：interact→fill_form，载荷为fields: [{name, value}, ...]；
验证：interact→get_screenshot逐页截取填充后的页面；
确认：把截图展示给用户，请其确认或直接在查看器中修改。

fill_form的命令载荷结构为：

{ "action": "fill_form", "fields": [ { "name": "f1_1", "value": "张三" }, { "name": "f1_2", "value": "Acme 科技有限公司" } ] }

配合 SKILL.md 的批量建议，可以在一次interact调用中用commands数组串联多个动作——例如把fill_form和get_screenshot放进同一批命令，命令按顺序执行，结尾的截图即用于验证本次填充。

六、完整实战：W-9 表单填写全流程

原文档 fill-form.md 给出了一个非常完整的对话示例，这里展开讲解每一步背后的逻辑：

用户：Help me fill out this W-9

第一步：识别晦涩字段名。你调用display_pdf，返回的formFields是f1_1、f1_2、f1_3、c1_1……——典型的加密机器名，用户根本无法分辨。

第二步：截图定位视觉标签。你调用interact→get_screenshot截取第 1 页，对照包围盒发现：f1_1紧邻 "Name"，f1_2是 "Business name"，c1_1是 "Individual" 复选框。这一步正是本插件相对程序化表单工具的核心优势——标签印在页面上，用截图去看，而不是猜元数据。

第三步：用视觉标签与用户确认缺失信息。你对用户说："我能看到 Name、Business name、Address、TIN 和税务分类复选框。我会先填入已知的姓名和日期——你的 TIN 和营业地址是什么？"这里的原则是：描述字段时永远用用户看得懂的视觉标签，而不是f1_1这种机器名。

第四步：批量填充并验证。拿到答案后，interact→fill_form提交所有字段值，紧接着get_screenshot截取填充后的页面展示给用户。

第五步：处理剩余部分。你补充道："这是填充后的表单 [截图]。签名行还是空的——需要我用/pdf-viewer:sign帮你加签名吗？"

这个示例完整覆盖了「识别 → 定位 → 询问 → 填充 → 验证 → 移交」的闭环，是 AI 辅助路径的教科书式应用。

七、字段值规范：复选框、单选按钮与文本框

填充时需要注意字段类型的取值约定（fill-form.md）：

复选框 / 单选按钮（Checkbox/radio）：值为true/false，或该选项的字符串（例如税表里的 "Individual"）。
文本框（Text）：直接传要填写的字符串即可。

例如填写 W-9 中的税务分类复选框：

{ "action": "fill_form", "fields": [ { "name": "c1_1", "value": true }, { "name": "c1_2", "value": false } ] }

八、与签名工作流联动：先填文本，再签图像

原文档 fill-form.md 特别提醒：签名区域通常是独立字段，先填充文本字段，再把图像签名交给/pdf-viewer:sign。/pdf-viewer:sign的工作流详见 pdf-viewer/commands/sign.md：

获取签名图像路径（PNG/JPG，本地文件或 HTTPS 链接，不支持 data: URI）；
display_pdf打开 PDF，检查formFields中是否有签名类型字段（含页码与包围盒坐标）；
有签名域就用其坐标定位，否则询问"第几页、页面什么位置"；
interact→add_annotations放置 image 类型标注：

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

宽度/高度省略时会根据图像自动检测；坐标原点为左上角，US Letter 页面上签名通常放在x: 400, y: 700附近。放置后用get_screenshot验证，位置不对可用update_annotations调整。

免责声明（来自 sign.md 与 README.md）：这放置的是签名的视觉图像，不是经过认证的加密数字签名；需要法律效力的电子签名请使用专用签名服务。

九、注意事项与最佳实践

综合 fill-form.md、SKILL.md 与 open.md 的说明：

viewUUID 只认一次：display_pdf每次调用都会创建独立的查看器，携带旧 UUID 的interact调用无法触达用户正在看的那个查看器，务必复用首次返回的viewUUID（SKILL.md）。
用户可直接编辑：任何时刻，用户都能在查看器中拖动、编辑字段，或要求重新调用fill_form——这是可视化方案相比程序化填充的兜底能力。
完成后的导出：填充或标注完成后，提醒用户可从查看器工具栏下载标注后的 PDF 副本（README.md）。
不要用查看器做纯内容提取：如果用户只是要摘要或文本提取，应直接用 Claude 的原生 Read 工具读取 PDF 路径，不要打开查看器（open.md、SKILL.md）。
批量提交命令：把相关动作放进同一次interact的commands数组，并在每批末尾追加get_screenshot，让用户看到每步变化（SKILL.md）。
支持的表单来源：本地文件路径、arXiv/abs/链接（自动转换为 PDF URL）、任意直接 HTTPS PDF 链接（bioRxiv、Zenodo、OSF 等，注意用 PDF 直链而非落地页）。

十、相关命令与文档索引

命令 / 文件	说明
pdf-viewer/commands/fill-form.md	本文主体：交互式表单填充的完整规范
pdf-viewer/commands/open.md	打开 PDF：`display_pdf`/`list_pdfs`与支持来源
pdf-viewer/commands/sign.md	放置签名 / 首字母图像标注
pdf-viewer/commands/annotate.md	协作式标注：高亮、备注、图章等
pdf-viewer/skills/view-pdf/SKILL.md	插件技能主文档：全部工具、标注类型与工作流
pdf-viewer/CONNECTORS.md	本地 MCP 服务器配置与运行方式
pdf-viewer/README.md	插件总览、命令表与使用边界