# DeepSeek OCR 默认主链路（2026-07-13）

## 结论
当任务目标是**把扫描件 / PDF 稳定识别出来**，默认主链路使用：

- `~/.hermes/scripts/deepseek_ocr.py`
- provider / API: **SiliconFlow**
- model: `deepseek-ai/DeepSeek-OCR`
- env var: `SILICONFLOW_API_KEY`

不默认回退到本地 `marker-pdf / surya`。只有在以下情形才改走本地链路：
1. 用户明确要求离线 / 本地 OCR；
2. DeepSeek OCR 存在不可回避的外部约束（如目标环境无法提供 API key 或必须完全脱网）；
3. 任务本身不是“先把内容识别出来”，而是明确在做本地 OCR 工具验证 / 对比实验。

## 本次会话得到的稳定经验
### 1. 先定路线，再谈环境
本次一开始把“当前 Python 环境被 marker-pdf 安装污染”讲得太重，容易把讨论带到本地 OCR 包冲突上；但用户真正要的是：

> 能用 DeepSeek OCR 就直接用，不要默认折回本地方案。

所以遇到 OCR 任务，先回答：
- 目标是**稳定抽取内容**，还是**验证本地 OCR 工具**？
- 如果是前者，先走 DeepSeek OCR 主链路。

### 2. 验证必须是真跑，不是口头判断
本次实际验证命令：

```bash
bash -ic 'python3 ~/.hermes/scripts/deepseek_ocr.py "/home/maggie/contract-review/其他任务/ht_page-1.png" -o /tmp/deepseek_ocr_final.md'
```

成功返回：
- 输入/输出 token 计数
- Markdown 文件落地
- 读回输出文件后可见 OCR 表格内容

因此以后汇报“可用”时，必须至少给出：
1. 实际命令；
2. 实际返回；
3. 输出文件或结果句柄。

### 3. `.bashrc` 中的 key 只对交互式 bash 自动生效
本次确认：
- `SILICONFLOW_API_KEY` 写在 `~/.bashrc`
- 非交互 shell 直接执行时，脚本可能读不到该变量
- `bash -ic '...'` 能加载 `.bashrc`，因此验证通过

因此如果 workflow / 子进程依赖这条 OCR 链路，必须显式保证环境变量可见；不要因为一次 `bash -c` 读不到 key，就误判 DeepSeek OCR 不可用。

### 4. 脚本不得偷偷依赖硬编码 fallback key
本次还暴露出：`deepseek_ocr.py` 曾带硬编码 fallback key。正确做法是：
- 只从 `SILICONFLOW_API_KEY` 读取；
- 没有 key 就直接报错退出；
- 避免“看起来可用，其实在吃脚本里藏着的 key”这种假成功。

## 汇报口径
当用户指定“以后都用这个方案”时，回复应直接、简洁：
- 已切换默认 OCR 方案为 DeepSeek OCR；
- 已确认环境变量位置；
- 已实际跑通；
- 本地 marker/surya 不再作为默认主方案。

不要再把话题绕回“当前主对话模型是不是 DeepSeek”。聊天模型链路 ≠ OCR 链路。