PDF Tool

这个“PDF工具”是一个专门用来查看PDF文件内容的小工具。PDF文件就像一本不能直接修改的电子书，而这个工具能帮你读出书里的故事（也就是文字）。

这个工具什么时候会出现？ 这个工具就像一个需要特定钥匙才能打开的玩具箱。只有当电脑找到了合适的“钥匙”（也就是能处理PDF的模型配置）时，这个工具才会出现让你使用。电脑会按顺序找三把“钥匙”：第一把是专门为PDF准备的模型；如果找不到，就用第二把，一个能看图片的模型；如果还找不到，就用第三把，根据你手头有的其他“钥匙”尽量找一个能用的。如果一把合适的“钥匙”都找不到，这个工具就不会出现。

你需要告诉工具什么？ 使用工具时，你需要告诉它一些信息：

1. 要读哪个文件：你可以用 pdf 告诉它一个文件的地址（就像告诉它一本书放在哪里），或者用 pdfs 告诉它好几个文件的地址（最多10个）。这两个信息可以一起用，工具会把它们合并起来，去掉重复的。如果你什么都不告诉它，它会生气并出错。
2. 你想问它什么：用 prompt 告诉它。比如“总结这份PDF文档”。如果你不说，它会默认问“分析这个PDF文档”。
3. 只读哪几页：用 pages 告诉它。比如“1-5”表示读第1到第5页，“1,3,7-9”表示读第1、3、7、8、9页。页码是从1开始数的。工具会帮你整理好页码，并且不会超过它能读的最大页数。
4. 想让哪个“大脑”来读：用 model 告诉它，格式是“提供者/模型名”。这是可选的，如果你不说，工具会自己选。
5. 文件不能太大：用 maxBytesMb 告诉它文件最大不能超过多少MB（兆字节）。如果你不说，默认是10MB。

工具能读哪些地方的文件？ 工具可以读三种地方的文件：

• 你电脑上的文件路径（比如 /home/你的名字/文件.pdf）。
• 以 file:// 开头的本地文件网址。
• 从网上下载的文件，网址以 http:// 或 https:// 开头。 要注意的是：其他类型的网址（比如 ftp://）它不认识，会拒绝。在“沙箱模式”（一个更安全的模式）下，它不能从网上下载文件。如果设置了只能读特定文件夹的文件，那么其他文件夹的文件它也读不了。

工具是怎么“读”文件的？ 它有两种读书方法： 第一种方法：直接给“大脑”看（原生模式） 这就像直接把整本书递给一个特别聪明、能直接看懂PDF的朋友（比如Anthropic或Google家的“大脑”）。这种方法很快，但有个限制：你不能指定只读哪几页（pages 设置没用），如果指定了，工具会出错。

第二种方法：先自己看一遍再讲（提取回退模式） 如果用的不是上面那两位聪明朋友，工具就得自己先看看书，然后再把看到的内容告诉别的“大脑”。具体步骤是：

1. 先从你选好的页码里，把文字“提取”出来（就像用荧光笔画重点）。最多提取 pdfMaxPages 页，默认是20页。
2. 如果提取出来的文字太少了（少于200个字符），它就会把选中的那些页变成一张张图片（PNG格式），然后把图片也一起给“大脑”看。
3. 最后，它把提取出来的内容（文字或文字加图片）和你提的问题（prompt）一起送给选定的“大脑”。 这种方法需要一些帮手（pdfjs-dist 和 @napi-rs/canvas）。如果选的“大脑”看不懂图片，而PDF里又提取不出文字，工具就会出错。变成图片时，所有图片加起来的像素总数也有一个预算，不能超过4,000,000。

工具是怎么设置的？ 大人们可以通过一个叫“配置”的东西来调整这个工具。比如，可以设置默认用哪个“大脑”来读PDF（pdfModel），默认文件最大多大（pdfMaxBytesMb，默认10MB），以及最多提取多少页（pdfMaxPages，默认20页）。

工具会告诉你什么？ 工具读完文件后，会把“大脑”的回答放在 content[0].text 里给你。同时，它还会在 details 里告诉你一些这次阅读的“小秘密”，比如：实际用了哪个“大脑”（model）、用的是哪种读书方法（native 为true就是第一种，false就是第二种）、以及尝试失败了几次才成功（attempts）。如果读的是一个文件，文件信息在 details.pdf；如果读了多个文件，信息就在 details.pdfs[] 这个列表里。

什么情况下工具会不高兴？ 你要小心，别让工具做下面这些事，不然它会出错：

• 不告诉它要读哪个PDF文件。
• 让它一次读超过10个PDF文件。
• 给它一个它不认识的网址类型（比如ftp://）。
• 在第一种读书方法（原生模式）下，却告诉它只读哪几页。