\r \r

cloud-driver-print\r

\r ---\r \r

🔥 Agent 自动化打印 — 一步到位（先看这里）\r

\r 最常见场景：用户说"打印这个文件到施乐/某打印机，打N份"。\r \r Agent 在非交互环境下，必须带齐所有参数一步执行，脚本有 input() 的地方会 EOF 报错。\r \r

标准命令（直接复制改参数）\r

\r

# === DOCX/PDF 统一入口：DOCX 自动走 _cvturl，超时自动降级 LibreOffice ===\r
CDF_PRINT_CONFIG_JSON='{"copies":2}' \\r
  python print_file_for_skill.py /path/to/file.docx \\r
    --ip 192.168.x.x \\r
    --driver "Xerox WorkCentre 7835" \\r
    --no-config-prompt \\r
    --json\r
```\r
\r
> `print_file_for_skill.py` 内置降级：`_cvturl`（60s 超时）→ 失败自动 LibreOffice 本地转 PDF 重新上传。\r
\r
**参数速查：**\r
| 场景 | 必带 flag |\r
|------|----------|\r
| 非交互环境 | `--no-config-prompt --json` |\r
| 指定份数 | `CDF_PRINT_CONFIG_JSON='{"copies":N}'` |\r
| 黑白/彩打 | `CDF_PRINT_CONFIG_JSON='{"color":"MONOCHROME"}'` | COLOR / MONOCHROME |\r
| 单双面 | `CDF_PRINT_CONFIG_JSON='{"side":"DUPLEX"}'` | ONESIDE / DUPLEX / TUMBLE |\r
| A3/A4 纸张 | `CDF_PRINT_CONFIG_JSON='{"paperConfig":{"name":"A4","width":210,"height":297}}'` |\r
| 驱动未保存 | `search_driver.py "型号" --ip 192.168.x.x --pick 1 --json` |\r
| IP 未登记 | `discover.py --ip 192.168.x.x` |\r
\r
---\r
\r
## ⚡ 三步流程（决策树）\r
\r
```\r
用户说"打印" \r
  ├─ 打印机已知？─否→ discover.py --list 或 --ip 登记\r
  │     └─ 型号为 "-"？→ ipptool 探测型号（详见故障降级 §4）\r
  ├─ 驱动已保存？─否→ search_driver.py --pick 1 --json 自动选\r
  └─ print_file_for_skill.py 文件 --ip ... --driver ... --no-config-prompt --json\r
```\r
\r
> **流程内置降级：`_cvturl`（60s 超时）→ 失败自动 LibreOffice 本地转换 + 重新上传。无需手动干预。**\r
>\r
> **型号探测参考：** `references/printer-identification-ipptool.md` — EPSON L6270 完整识别案例。\r
\r
---\r
\r
## 📋 常用命令\r
\r
### 打印机管理\r
```bash\r
python discover.py --timeout 5          # 扫描局域网打印机\r
python discover.py --list               # 列出已保存打印机\r
python discover.py --ip 192.168.1.25    # 按 IP 登记单台\r
python connect_printer.py 192.168.1.25  # 测试 9100 连通性\r
```\r
\r
### 驱动搜索（非交互用 --pick）\r
```bash\r
python search_driver.py "Xerox WorkCentre 7835"                      # 只搜索\r
python search_driver.py --ip 192.168.65.130 --pick 1 --json          # 自动选第一个并回写\r
python search_driver.py "HP M404" --ip 192.168.1.25 --pick 1 --json  # 指定查询词+自动选\r
```\r
\r
### 打印\r
```bash\r
# DOCX/PDF 一把梭（内置转换降级）\r
python print_file_for_skill.py file.docx --ip 192.168.x.x --driver "..." --no-config-prompt --json\r
```\r
\r
---\r
\r
## 🌐 云端 API 规范\r
\r
云端服务：`https://any.webprinter.cn`\r
\r
| 函数 | 路径 | HTTP | Content-Type | 超时 |\r
|------|------|------|-------------|------|\r
| `uploadFileMCP` | `/openapi/mcpClient/uploadFileMCP` | POST | `multipart/form-data` | 120s |\r
| `convert_url_to_pdf` | `/openapi/cdf/_cvturl` | POST | **`application/json`** | 60s |\r
| `print_for_skill` | `/openapi/cdf/_pfs` | POST | **`application/json`** | 300s |\r
\r
**Headers（所有接口）：** `Accept: application/json`, `tid: cdf_ai_terminal`, `ttp: AI`\r
\r
### ⚠️ 陷阱：form-encoded → 404\r
\r
`_cvturl` 和 `_pfs` 用 form-encoded（`application/x-www-form-urlencoded`）会返回 **HTTP 404**，但换 JSON body 后正常。这是路由不匹配，不是接口未部署。代码中这两个函数已使用 `_post_json()`。\r
\r
### curl 调试\r
\r
```bash\r
# _pfs（JSON body，含 fileName 原始文件名）\r
curl -s -X POST "https://any.webprinter.cn/openapi/cdf/_pfs" \\r
  -H "Content-Type: application/json" -H "tid:cdf_ai_terminal" -H "ttp:AI" \\r
  -d '{"printer":{"driver":"Xerox WorkCentre 7835","name":"Xerox WorkCentre 7835","portType":"NET","portAddr":"192.168.65.130"},"url":"...PDF_URL...","fileName":"新建 DOCX 文档.docx","config":{"copies":2}}'\r
\r
# _cvturl（JSON body）\r
curl -s -X POST "https://any.webprinter.cn/openapi/cdf/_cvturl" \\r
  -H "Content-Type: application/json" -H "tid:cdf_ai_terminal" -H "ttp:AI" \\r
  -d '{"repoId":"ZIM_STORAGE","path":"EeW88JMOkyAA1Qv5/..."}'\r
```\r
\r
---\r
\r
## 🚫 硬性约束\r
\r
> **禁止将原始文件（PDF/DOCX/图片等）直接通过 TCP 9100 或其他端口发送到打印机。**\r
>\r
> 所有打印数据必须经过云端 `_pfs` 渲染管道生成，客户端只负责从 `_pfs` 返回的 `fileUrl` 下载二进制数据后发送到打印机 9100 端口。\r
>\r
> ❌ 禁止行为：\r
> ```python\r
> # NEVER do this — 直接发送原始文件\r
> s = socket.create_connection(('192.168.x.x', 9100))\r
> s.sendall(open('/tmp/file.pdf', 'rb').read())\r
> ```\r
>\r
> ✅ 正确流程：上传 → _cvturl 转换 → _pfs 渲染 → 下载 fileUrl 二进制 → 发送到打印机\r
\r
---\r
\r
## 🧯 故障降级\r
\r
> **诊断参考文件：**\r
> - `references/pfs-empty-fileurl-debug.md` — `_pfs` fileUrl 返回 0 字节的完整复现与诊断（含间歇性规律和 fileUrl `//0` 格式线索）\r
> - `references/epson-l6270-experience.md` — EPSON L6270 Series 完整接入参考（发现、IPP识别、驱动、已知问题）\r
> - `references/printer-identification-ipptool.md` — IPP 探测打印机型号完整案例\r
> - `references/session-20260515-pfs-cvturl.md` — _cvturl 超时处理和接口规范\r
\r
### 1. _cvturl 超时 → 内置自动降级\r
`print_file_for_skill.py` 已内置：`_cvturl` 失败后自动调用 LibreOffice 本地转 PDF 并重新上传，无需手动干预。\r
\r
`_pfs` 成功后会返回 `fileUrl`。该 URL 指向二进制打印数据；`_pfs` 本身不实际触发打印，客户端需要下载该二进制内容并发送到目标打印机的 `9100`（或记录中的原始 TCP 端口）。\r
\r
### 2. _pfs 返回 success 但 fileUrl 下载 0 字节 — 已确认真实故障\r
\r
**现象：** `_pfs` 返回 `"success": true` + 有效 `fileUrl`，但从 fileUrl 下载得到 200 OK + **0 bytes**。`print_file_for_skill.py` 报错：`发送打印数据失败：下载到的打印数据为空。`\r
\r
**根因：** 云端驱动渲染管道对特定 PDF 格式/打印机型号未能输出有效二进制数据。`_pfs` 本身调用成功（业务层面无错误），但渲染产物为空。此 Bug 已在 EPSON L6270 Series + fpdf2 生成的 PDF 上复现。\r
\r
**诊断步骤：**\r
```bash\r
# 1. 直接调 _pfs 获取原始响应\r
curl -s -X POST "https://any.webprinter.cn/openapi/cdf/_pfs" \\r
  -H "Content-Type: application/json" -H "tid:cdf_ai_terminal" -H "ttp:AI" \\r
  -d '{"printer":{"driver":"EPSON L6270 Series","name":"EPSON L6270 Series","portType":"NET","portAddr":"192.168.66.139"},"url":"...PDF_URL...","config":{},"fileName":"test.pdf"}' \\r
  | python3 -m json.tool\r
\r
# 2. 下载 fileUrl 验证大小\r
curl -s -o /tmp/pfs_dl.bin -w "HTTP %{http_code}, size: %{size_download}\
" \\r
  -H "tid:cdf_ai_terminal" -H "ttp:AI" "\x3C_pfs返回的fileUrl>"\r
```\r
\r
**处理方案：** `print_file_for_skill.py` 报错退出，需反馈给用户排查云端渲染管道（联系后端确认驱动/PDF兼容性）。**禁止绕过 _pfs 直接发送原始文件。**\r
\r
### 3. search_driver.py EOF → 加 --pick\r
无 stdin 时交互式 `input()` 报 EOF，用 `--pick 1 --json` 自动选第一个候选。\r
\r
### 4. 打印机型号无法识别 → ipptool 兜底\r
\r
当 `discover.py --ip` 返回型号为 `-`（无法自动识别）时，按以下顺序探测：\r
\r
| 优先级 | 方式 | 命令示例 | 成功率 |\r
|--------|------|---------|--------|\r
| ① | **IPP（最可靠）** | `ipptool -tv http://\x3CIP>:631/ipp/print get-printer-attributes.test` | 极高 |\r
| ② | HTTP 首页 | `curl -s --max-time 5 http://\x3CIP>/` | 中等 |\r
| ③ | SNMP | `snmpget -v2c -c public \x3CIP> 1.3.6.1.2.1.25.3.2.1.3.1` | 低 |\r
\r
**IPP 返回的关键字段：**\r
- `printer-make-and-model` → 精确型号（如 `EPSON L6270 Series`）\r
- `printer-device-id` → 含 MFG/MDL/CMD 等完整标识\r
- `printer-info` → 打印机友好名称\r
- `marker-levels` → 墨量/碳粉余量（单位 %）\r
- `pages-per-minute` / `pages-per-minute-color` → 打印速度\r
\r
**典型用法：**\r
```bash\r
# 一步获取型号 + 墨量\r
ipptool -tv http://192.168.x.x:631/ipp/print get-printer-attributes.test 2>/dev/null \\r
  | grep -E 'printer-make-and-model|printer-info|marker-levels|marker-names|pages-per-minute'\r
```\r
\r
> ⚠️ 有些打印机 IPP 监听在 80 端口而非 631，可尝试 `http://\x3CIP>/ipp/print`。\r
\r
---\r
\r
## 🏗️ 架构\r
\r
```\r
print_file_for_skill.py      ← 入口（上传+转换+下载打印数据+9100发送）\r
  ├── cdf/ai/skillPrint.py   ← REST 适配层 (uploadFileMCP / _cvturl / _pfs + fileUrl下载/9100发送)\r
  ├── cdf/ai/config.py       ← 服务地址 + headers 构建\r
  ├── cdf/ai/searchDriver.py ← 驱动搜索\r
  ├── printer_store.py       ← 本地 Markdown 打印机记录 (printers/*.md)\r
  └── driver_workflow.py     ← 驱动搜索→选择→回写 工作流\r
\r
discover.py                  ← 网络发现 / IP登记 / 列表\r
connect_printer.py           ← TCP 9100 连通性检查\r
search_driver.py             ← 驱动搜索 CLI 入口\r
```\r
\r
## 适配要求\r
\r
1. `cdf/ai/` 下维护云端服务地址和 headers。\r
2. 所有打印请求带 `tid: cdf_ai_terminal` + `ttp: AI`。\r
3. 鉴权通过环境变量 `CDF_PRINT_API_KEY` 注入 Bearer Token（可选）。\r
\r
## 依赖\r
\r
- Python 3.10+\r
- `zeroconf`（mDNS 打印机发现，可选）\r
- **LibreOffice**（DOCX→PDF 本地转换降级，必需）\r