From 76f7adddd5c66658d8aeec1981309db035181198 Mon Sep 17 00:00:00 2001
From: houhuan <houhuanya@gmail.com>
Date: Wed, 25 Mar 2026 20:35:09 +0800
Subject: [PATCH] docs: add OpenClaw integration guide

---
 OPENCLAW_GUIDE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 OPENCLAW_GUIDE.md

diff --git a/OPENCLAW_GUIDE.md b/OPENCLAW_GUIDE.md
new file mode 100644
index 0000000..143b65b
--- /dev/null
+++ b/OPENCLAW_GUIDE.md
@@ -0,0 +1,51 @@
+# OCR 订单处理系统 - OpenClaw 对接指南
+
+本指南旨在帮助 OpenClaw（或任何自动化 AI 代理）理解如何与本项目进行对接，实现“发送图片 -> 自动处理 -> 返回 Excel”的闭环流程。
+
+## 1. 项目概览
+本项目是一个自动化的采购单处理系统。它通过 OCR 技术识别图片中的表格数据，并根据预设的规则进行清洗（如拆分单位、推算规格），最后生成标准格式的 Excel 采购单。
+
+## 2. 核心工作流
+自动化对接建议遵循以下步骤：
+
+1.  **图片准备**：将收到的采购单图片保存至项目的 `data/input/` 目录。
+2.  **触发处理**：运行 `headless_api.py` 脚本。
+3.  **捕获路径**：从脚本的标准输出（stdout）中获取生成的 Excel 绝对路径。
+4.  **读取结果**：根据获取的路径读取文件并发送回给用户。
+
+## 3. API 接口说明 (headless_api.py)
+
+这是专门为自动化对接设计的入口。
+
+### 运行方式
+```bash
+# 方式 A：自动处理 input 目录中最新的一张图片
+python headless_api.py
+
+# 方式 B：处理指定路径的图片
+python headless_api.py "E:/2025Code/python/orc-order-v2/data/input/invoice_001.jpg"
+```
+
+### 输出规范
+-   **标准输出 (stdout)**：仅在处理成功时打印**最终生成的 Excel 文件的绝对路径**。
+    -   *示例*：`E:\2025Code\python\orc-order-v2\data\result\采购单_invoice_001.xlsx`
+-   **标准错误 (stderr)**：输出所有的运行日志、进度信息、警告以及错误详情。
+    -   *注意*：如果发生“单价校验”差异（即生成价格与商品资料价格差异 > 1 元），相关警告会打印在此流中。
+
+## 4. 关键目录结构
+-   `data/input/`：存放待处理的原始图片（支持 jpg, png, bmp）。
+-   `data/result/`：存放最终生成的标准 Excel 采购单。
+-   `templates/商品资料.xlsx`：系统会自动根据此文件进行单价校验。
+-   `config/suppliers_config.json`：存储供应商的清洗规则。
+
+## 5. 错误代码与异常处理
+-   如果脚本退出码为 `0`：表示处理成功，stdout 包含文件路径。
+-   如果脚本退出码为 `1`：表示处理失败，具体原因请查看 stderr。
+
+## 6. 给 OpenClaw 的建议策略
+1.  **轮询或触发**：当检测到用户发送图片时，先清空或直接写入 `data/input/`。
+2.  **路径捕获**：使用类似 `subprocess.check_output` 的方法运行脚本，捕获最后一行输出作为文件路径。
+3.  **价格预警**：OpenClaw 可以扫描 stderr，如果发现包含 `WARNING: Price validation found...` 字样，可以主动提醒用户：“处理完成，但发现部分商品单价与资料库不符，请核对。”
+
+---
+*由系统自动生成于 2026-03-25*