OpenCode 读不了 Word/PDF/Excel?我是这么解决的

前天我在公众号简单发了贴图，OpenCode可以解析各种格式的文档啦，有朋友在后台问具体怎么实现的。今天抽空把整个过程整理一下，从发现问题到找到解决方案再到整理工具包，一次性讲清楚。

为什么要解决这个问题

前段时间在用 OpenCode 写测试工具的时候，想着让 AI 直接读本地的 Word和PDF，根据文档定义的接口以及需求直接帮我生成接口自动化的脚本，这样应该能省不少事。

结果一用就发现，理想很丰满，现实很骨感：

想让 AI 分析 PDF 需求文档 → 报错：模型不支持 PDF
想让 AI 分析 Word 接口文档 → 报错：模型不支持这种格式
脚本运行报错，截图丢进去 → AI 不能识别图片

最后只能自己手动整理接口示例，手动复制需求，运行报错AI改了几次都没成功的话就截图丢给豆包去分析。

我问研发的同事怎么解决这个问题，他们建议：

用在线转换工具把word或者pdf转换成md格式的文件，再把md文件给AI
或者安装一个多模态agent

我不想这么干，觉得麻烦，也不想花钱，普通牛马能用免费的就用免费的。我在想应该有其他解决办法，而且是一步到位的那种。

问题不在OpenCode，在模型

我一开始也纳闷，Kimi 网页版明明能直接上传图片、PDF、Word，怎么到了 OpenCode 就不行了？

后来查了一下才明白：我们在 OpenCode 里接的 DeepSeek V4 免费版、Kimi K2，本质上都是纯文本模型。

打个比方：Kimi 网页版像是一部带摄像头的手机，能直接拍照识物；而 OpenCode 里调用的 Kimi K2 API，更像是一部只能收发短信的功能机，它只认文字。

所以问题不是 OpenCode 不行，而是我们发给它的东西，它"看"不懂。

那怎么办？先把文档翻译成文字，再喂给它。这就是这套方案的核心思路。

解决思路

解决思路：文档 → 文本 → AI

整个链路其实不复杂：

文件 → Python 脚本提取文本 → 纯文本 → AI 分析 → 输出结果

这样做的好处如下：

不挑模型：DeepSeek、Kimi，或者其他文本模型都能用
不花钱：不用去买 GPT-4o、Claude 这种多模态 API
本地跑：文档内容不用上传到第三方平台
一次配置，长期复用：脚本写好后，只需要执行一次脚本，一步到位。关键是团队其他人也能复用

具体怎么做

准备环境

前置环境准备：

Python 3.10+
Microsoft Word（只有解析旧版 .doc时才需要）
Tesseract-OCR（图片识别用，可选，有在线 OCR 兜底）

OCR下载地址：https://github.com/UB-Mannheim/tesseract/wiki下载：`tesseract-ocr-w64-setup-5.x.x.exe`

安装python依赖

### 安装 Word / PDF / 图片 OCR 依赖pip install python-docx pdfplumber pytesseract pillow### 安装 Excel 解析依赖pip install pandas openpyxl xlrd

写解析脚本

写了 4 个脚本，每个脚本负责一类文件：

doc_extract.py：负责 .docx、.pdf、图片
parse_doc.py：负责旧版 .doc
parse_xlsx.py：负责 .xls、.xlsx
parse_xmind.py：负责 .xmind

核心逻辑就是调用 Python 库，把文件内容提取成文本。

配置opencode规则

这一步很关键。需要在 OpenCode 里配一个 AGENTS.md 规则文件，告诉 AI：

看到文件后缀是:
.docx、.pdf、.png、.xls、.xlsx、.doc、.xmind
直接执行对应的 Python 脚本，不要自己用 read 工具去读文件。

没有这一步，AI 还是会傻傻地去读二进制文件，然后报错。

过程中我拆过的几个坑

坑1：Plan 模式下 AI 说不能执行脚本

同时打开多个回话窗口，有个回话窗口在Plan模式就不能解析文件，但是另外一个窗口是可以正常的解析各种格式文档的。

AI说需要切换到build模式才可以。

后来实际验证发现，Plan 模式只是不能改文件，执行 Python 脚本完全没问题。

我把这个点明确写进了 AGENTS.md，避免 AI 再误判。

坑2：拖图片进窗口，AI 直接返回错误

拖图时 OpenCode 框架会先调用 read 工具，报一个 "Cannot read" 的错误。有些 AI 会把这个错误直接抛给用户。

后来我把 AGENTS.md 写得更强硬，明确要求 AI：忽略这个错误，直接执行 Python 脚本。

坑3：Tesseract 装在 D 盘，脚本找不到

最早脚本只扫描 C 盘的默认安装路径。同事的 Tesseract 装在 D 盘，图片识别失败，分析原因是脚本的路径写死了C盘。

后来我改成扫描 C~Z 所有磁盘，还支持用 TESSERACT_CMD 环境变量自定义路径。

坑4：install 脚本加 PATH 后没生效

一开始工具包的install.ps1 只把 PATH 写进注册表，当前 PowerShell 会话没刷新，导致同事执行完install.ps1后环境变量没添加成功。

后来我在脚本里加了 env:Path 刷新，安装完立刻生效。

我封装了两个工具包

为了降低团队同事的上手门槛，我把这些东西打包成了两个版本：

工具包	模式	特点	适合谁
OpenCode文档识别工具包.zip	AGENTS.md 全局规则	一键安装、依赖预装、全局生效	想快速上手的同学
document-parser.zip	OpenCode Skill	不污染 PATH、自动检测依赖	想长期维护的同学