Tax Receipt Compliance

SKILL.md

---\nname: tax-receipt-compliance
description: 财税合规全链路助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。
version: 2.7.0\n---\n
# 财税合规全链路助手

> ⚠️ **使用必读**：本Skill所有功能在本地运行，发票数据绝不外传，但**绝不提供税务咨询**。使用前请先阅读【限制说明】和【风险声明】。

## 功能说明

本Skill提供从发票识别到审批提交的**全链路**财税合规能力。

| 模块 | 功能 | 状态 | 输入 | 输出 |
|------|------|------|------|------|
| 1. 发票OCR识别 | Tesseract本地识别增值税发票 | ✅ 直接可用 | 发票图片 | 结构化JSON |
| 2. 真伪查验 | 对接查验平台，自动获取结果 | ⚠️ 需配置密钥 | 发票代码/号码 | 查验结果 |
| 3. 报销单填充 | 自适应学习模板，一键填充 | ✅ 直接可用 | 发票数据+模板 | Excel文件 |
| 4. 审批对接 | 对接钉钉/企微/飞书审批 | ⚠️ 需配置密钥 | 报销单+配置 | 审批结果 |

> ✅ = 装即用 ｜ ⚠️ = 需在 config.yaml 中配置对应API密钥

### 设计理念

1. **数据安全第一**：所有发票数据处理均在本地，不会上传到任何服务器
2. **企业自主决策**：查验引擎、审批平台的选择权完全交给企业
3. **透明开源**：所有代码可见可审计，无隐藏后门
4. **渐进披露**：基础功能开箱即用，高级功能按配置解锁

## 如何「指挥」它干活

本Skill支持**自然语言对话**，不需要记忆任何命令。以下是各种场景下你可以直接对AI说的话：

### 💬 直接用自然语言说

| 你想做什么 | 直接这样说 |
|-----------|-----------|
| 识别一张发票 | "帮我识别这张发票" / "OCR一下这个发票" / "扫描这张发票" |
| 批量识别 | "把文件夹里所有发票都识别出来" / "批量扫描D:\invoices" |
| 查验真伪 | "帮我查验这张发票的真伪" / "查一下这个发票是不是真的" |
| 生成报销单 | "用公司模板生成报销单" / "把识别结果填到报销单里" |
| 提交审批 | "提交报销审批" / "发起审批" / "把报销单提交给钉钉审批" |
| 批量处理 | "批量识别并生成报销单" / "把整个文件夹的发票都处理完" |
| 环境检查 | "检查环境是否就绪" / "运行预检" |
| 查看帮助 | "这个Skill能做什么" / "怎么用" |

### 📋 更详细的说法（推荐）

**识别发票**：
- "请帮我识别这张发票：D:\发票\20260628.png"
- "扫描这张发票，我要报销"
- "OCR这张发票，结果保存到receipt.json"

**批量处理**：
- "把D:\invoices\里所有发票都识别出来，结果保存到output.json"
- "批量扫描发票文件夹，然后生成合并报销单"

**查验真伪**：
- "帮我查验发票 代码:3100204130 号码:00564189"
- "查一下这张发票是不是真的，发票号是00564189"

**生成报销单**：
- "用模板D:\templates\报销单.xlsx生成报销单"
- "把receipt.json的数据填到报销单模板里"

**提交审批**：
- "把报销单提交到钉钉审批"
- "发起企业微信审批，报销金额11300元"

> 💡 **小贴士**：直接上传发票图片或告诉AI文件路径，AI会自动识别你的意图并执行对应操作。

## 📋 常见问题速查

### 🔧 安装与配置

| 问题 | 快速答案 |
|------|---------|
| 安装Tesseract后提示 `Tesseract not found` | 重启终端，或用 `--tesseract` 参数指定完整路径 |
| 提示 `chi_sim not found` | 重新安装Tesseract，勾选 Chinese (Simplified) 语言包 |
| 为什么不识别图片？ | 检查图片是否清晰、发票类型是否支持（手写/定额发票不支持） |
| 常用安装命令 | Windows: `winget install UB-Mannheim.TesseractOCR` |
| Mac安装 | `brew install tesseract tesseract-lang` |
| Linux安装 | `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim` |

### 📷 OCR识别

| 问题 | 快速答案 |
|------|---------|
| 识别结果为空/少量内容 | 检查图片质量、光线、平整度、是否安装中文语言包 |
| 识别率低/字段错误 | 使用扫描件、手机扫描APP预处理、核对关键字段 |
| 批量处理部分失败 | 失败文件会单独记录在 `failed_files` 字段中，不影响其他文件 |
| 图片质量要求 | ≥200DPI、光线均匀、无反光、发票平整放置 |
| 提高识别率小技巧 | 扫描全能王APP预处理、使用扫描件、避免强光直射 |

### 🏢 查验与审批

| 问题 | 快速答案 |
|------|---------|
| 查验接口返回失败 | 检查API Key、网络访问、调用频率限制、查看日志 |
| 审批Token获取失败 | 确认API Key正确、应用已开通权限、服务器IP已加白名单 |
| 如何选择查验引擎 | 国税总局(免费) / 百望云/诺诺(付费API Key) / 自建接口 |
| 支持哪些审批平台 | 钉钉、企业微信、飞书、自定义（需实现接口） |
| 审批提交后能撤销吗 | 不可撤销（以各平台规则为准），提交前请核对内容 |

### 📄 模板与数据

| 问题 | 快速答案 |
|------|---------|
| 模板匹配失败 | 检查模板第一行是否为中文表头、文件是否损坏 |
| 金额勾稽关系不匹配 | OCR识别错误时人工核对；0.01元以内差异属正常精度问题 |
| 环境预检通过但OCR仍失败 | Tesseract版本过低（建议4.0+）、语言包不完整（≥5MB） |

### 🛡️ 安全与合规

| 问题 | 快速答案 |
|------|---------|
| 数据安全吗？ | 所有处理在本地完成，不会上传到任何服务器 |
| 日志里有什么？ | 仅记录操作元数据（文件名、时间、状态），不记录发票内容 |
| 能提供税务咨询吗 | 不能，本工具仅为技术支持，不提供税务/财务建议 |

> 📖 **详细解答见下方【故障排除】部分**

---

## 💡 使用技巧与注意事项

> 本节汇总了日常使用中最实用的技巧和注意事项，建议首次使用前快速浏览一遍。

### 基本技巧

| 序号 | 技巧 | 说明 |
|------|------|------|
| 1 | **优先用扫描件** | 扫描件比手机拍照识别率高15%-20%，文字更清晰、无反光 |
| 2 | **手机拍照用扫描模式** | 微信/支付宝/扫描全能王APP都有"文档扫描"功能，能自动去阴影、纠偏 |
| 3 | **批量处理先试一张** | 批量处理前先识别一张确认效果，避免批量失败浪费时间 |
| 4 | **低置信度要核对** | 置信度<0.7时系统会提示警告，此时必须人工核对代码、号码、金额 |
| 5 | **保留原始图片** | 识别失败时，系统会尝试用原始图片（跳过预处理）重新识别 |

### 注意事项

| 序号 | 注意点 | 原因 |
|------|--------|------|
| 1 | ⚠️ **OCR软件是一次性安装** | Tesseract约60MB，安装后永久使用，无需重复下载 |
| 2 | ⚠️ **模糊发票必须手动核对** | OCR对模糊图片无法保证准确率，关键金额字段一定要人工复核 |
| 3 | ⚠️ **API密钥配置后才能查验/审批** | 基础功能（识别+报销单）不需要密钥，查验和审批才需要 |
| 4 | ⚠️ **批量处理部分失败是正常的** | 系统会跳过失败文件继续处理，失败的记录在 `failed_files` 字段 |
| 5 | ⚠️ **日志不记录发票内容** | 仅记录文件名、时间、状态等元数据，发票数据不上传不外传 |

### 模糊发票处理指南

当发票图片模糊、识别效果不好时，按以下步骤处理：

```
步骤1：判断图片质量
  → 图片分辨率<200DPI？ → 重新拍摄/扫描
  → 有反光/阴影？       → 换个角度或光线重拍
  → 发票褶皱严重？      → 展平后重新扫描

步骤2：使用扫描APP预处理（推荐）
  → 扫描全能王 / 白描 / 微信扫一扫
  → APP会自动增强对比度、去阴影、纠偏
  → 保存为JPG后重新识别

步骤3：识别后人工核对
  → 重点核对：发票代码(10-12位数字)、号码(8-20位数字)、金额
  → 金额勾稽检查：金额 + 税额 = 价税合计？
  → 置信度<0.7的字段重点核对

步骤4：手动输入（终极方案）
  → 如果反复识别失败，可直接手动输入发票信息
  → 格式：python scripts/ocr_engine.py --manual
  → 按提示输入发票代码、号码、日期、金额等
```

---

## 对话示例

本Skill支持通过自然语言对话方式使用，无需记忆复杂命令。

### 场景1：识别单张发票

```
用户：请帮我识别这张发票 D:\invoices\20260628_001.png
AI：正在识别发票...
    ✓ 发票类型: 增值税专用发票
    ✓ 发票代码: 3100204130
    ✓ 发票号码: 00564189
    ✓ 开票日期: 2026年06月28日
    ✓ 金额: 10,000.00 元
    ✓ 税额: 1,300.00 元
    识别完成，已保存到 receipt.json
```

### 场景2：批量处理

```
用户：把文件夹里所有发票都识别出来
AI：正在批量识别 D:\invoices\ 中的发票...
    共发现 15 个图片文件
    ✓ 20260628_001.png - 识别成功
    ✓ 20260628_002.png - 识别成功
    ⚠ 20260628_003.png - 识别失败（图片模糊）
    ...
    处理完成：成功 12 张，失败 3 张
    结果已保存到 batch_result.json
```

### 场景3：查验发票真伪

```
用户：帮我查验这张发票的真伪
AI：正在查验发票...
    发票代码：3100204130
    发票号码：00564189
    ✓ 查验平台：国税总局
    ✓ 发票状态：正常
    ✓ 查验时间：2026-06-29 10:30:00
```

### 场景4：生成报销单

```
用户：用公司模板生成报销单
AI：正在生成报销单...
    ✓ 识别到 6 个字段映射
    ✓ 已填充：开票日期、销方名称、金额、税额、价税合计、费用说明
    报销单已生成：D:\output\expense_report.xlsx
```

## API调用示例

### Python调用

```python
from scripts.ocr_engine import OCREngine

# 初始化引擎
engine = OCREngine()

# 识别单张发票
result = engine.extract_structured_data("invoice.png")
print(f"发票代码: {result['invoice_code']}")
print(f"金额: {result['amount']}")

# 批量处理
import glob
for file in glob.glob("invoices/*.png"):
    result = engine.extract_structured_data(file)
    print(f"{file}: {result['success']}")
```

### HTTP API调用

```bash
# 启动API服务（需安装flask）
python scripts/api_server.py

# 识别发票
curl -X POST http://localhost:8080/api/ocr \
  -F "file=@invoice.png"

# 批量识别
curl -X POST http://localhost:8080/api/ocr/batch \
  -F "files=@invoice1.png" \
  -F "files=@invoice2.png"
```

## 快速配置向导（一键配置）

**新手推荐**：运行以下命令自动检测环境并推荐最优配置：

```bash
python scripts/config_wizard.py
```

向导会自动完成：
1. 检测Tesseract是否安装，未安装则提供一键安装命令
2. 检测中文语言包是否完整
3. 推荐查验引擎（默认：国税总局平台，免费无需API Key）
4. 生成初始 `config.yaml` 文件
5. 验证配置文件有效性

**手动快速配置**（3步完成）：

```bash
# 1. 复制配置模板
cp templates/config_template.yaml config.yaml

# 2. 编辑配置（只需填写必填项）
# 用编辑器打开 config.yaml，填写：
#   - verify_engine: "tax_bureau" （默认，免费）
#   - approval.platform: "none" （暂不配置审批）

# 3. 验证配置
python scripts/check_env.py
```

> 💡 **提示**：基础功能（发票识别、报销单生成）只需完成环境安装即可使用，无需配置API密钥。查验和审批功能才需要配置API密钥。

## 快速开始

> **30秒摘要**：① 安装Tesseract（约60MB，一次性）→ ② pip安装依赖 → ③ 直接识别发票。基础功能无需配置，查验/审批才需填API密钥。

### 第一步：环境准备（必做，5分钟完成）

**Windows用户**（一键安装）：
```powershell
# 自动下载并安装Tesseract（使用国内镜像，速度快）
.\scripts\install_tesseract.ps1
```

**Linux/macOS用户**：
```bash
bash ./scripts/install_tesseract.sh
```

> **关于OCR软件大小**：Tesseract安装包约60MB（含中文语言包），是一次性安装，安装后永久使用，无需联网运行。选择本地OCR而非在线API的原因是：发票数据属于敏感财务信息，本地处理可确保数据零外泄。这是数据安全与软件体积之间的权衡。

**安装Python依赖**：
```bash
pip install Pillow pytesseract openpyxl pyyaml
```

> 安装完成后运行预检脚本检查环境：
> ```bash
> python scripts/check_env.py
> ```

### 第二步：配置（可选，基础功能无需配置）

```bash
# 复制配置模板
cp templates/config_template.yaml config.yaml
```

> 💡 **新手提示**：不编辑 `config.yaml` 也能使用基础功能（发票识别、报销单生成）。只有查验真伪和提交审批才需要配置对应API密钥。

### 第三步：开始使用

```bash
# 识别单张发票（直接可用，无需配置）
python scripts/ocr_engine.py --input path/to/invoice.png --output receipt.json

# 生成报销单（直接可用，无需配置）
python scripts/template_matcher.py fill --config config.yaml --receipt receipt.json --template templates/expense_basic.xlsx

# 查验发票真伪（需先配置查验引擎）
python scripts/verify_engine.py --invoice-code 3100204130 --invoice-number 00564189 --date "2026年06月28日" --amount 10000

# 提交审批（需先配置审批平台）
python scripts/approval_engine.py --config config.yaml --expense expense_output.xlsx

# 环境预检
python scripts/check_env.py
```

## 详细配置说明

见 `references/setup-guide.md`

## 示例

### 示例1：识别单张发票

**输入**：

```
识别发票 D:\invoices\20260628_001.png
```

**输出**：

```json
{
  "success": true,
  "invoice_type": "增值税专用发票",
  "invoice_code": "3100204130",
  "invoice_number": "00564189",
  "invoice_date": "2026年06月28日",
  "seller_name": "上海某某科技有限公司",
  "amount": 10000.00,
  "tax_rate": 0.13,
  "tax_amount": 1300.00,
  "total": 11300.00,
  "remark": "*信息技术服务费*",
  "confidence": 0.96
}
```

### 示例2：查验发票真伪

**输入**：

```
查验发票 代码:3100204130 号码:00564189 日期:2026-06-28 金额:10000.00
```

**输出**：

```json
{
  "engine": "国税总局查验平台",
  "status": "ready",
  "verify_url": "https://inv-veri.chinatax.gov.cn/index.html?fpdm=3100204130&fphm=00564189",
  "message": "已为您生成查验链接，点击即可查验",
  "params": {
    "invoice_code": "3100204130",
    "invoice_number": "00564189",
    "billing_date": "2026-06-28",
    "amount": 10000.00
  }
}
```

> 如配置了百望云/诺诺API Key，会自动调用第三方API获取查验结果。

### 示例3：生成报销单

**输入**：

```
用模板 D:\templates\公司报销单.xlsx 生成报销单，数据来自 D:\invoices\receipt.json
```

**输出**：

```
模板分析完成：识别到 6 个字段映射，置信度 0.8+
报销单已生成：D:\output\expense_report_20260629.xlsx
已填充 6 个字段：开票日期、销方名称、金额、税额、价税合计、费用说明
```

### 示例4：批量识别并合并为报销单

```bash
python scripts/batch_process.py --input D:\invoices\ --template D:\templates\公司报销单.xlsx --output D:\output\合并报销单.xlsx
```

### 示例5：提交审批

```bash
python scripts/approval_engine.py --config config.yaml --expense D:\output\报销单.xlsx --user-id manager123 --amount 11300 --expense-type 信息技术服务
```

## 发票类型支持与图片要求

> **30秒摘要**：支持增值税专票/普票/电子票。识别效果高度依赖图片质量——扫描件>拍照，清晰>模糊，建议分辨率≥200DPI。

### 支持的发票类型

- ✅ 增值税专用发票
- ✅ 增值税电子发票
- ✅ 增值税普通发票
- ✅ 电子发票（PDF格式，需安装poppler）

### 暂不支持

- ❌ 手写发票
- ❌ 定额发票
- ❌ 机动车销售发票
- ❌ 二手车销售发票
- ❌ 海关缴款书

### 图片质量要求（直接影响识别率）

> ⚠️ **重要提醒**：Tesseract OCR识别效果**高度依赖图片质量**。模糊、反光、低分辨率的图片会导致识别率显著下降。

| 质量等级 | 分辨率 | 光线 | 平整度 | 预期准确率 |
|---------|--------|------|--------|-----------|
| 优秀 | ≥300DPI | 均匀 | 无褶皱 | 95%+ |
| 良好 | 200-300DPI | 较均匀 | 轻微褶皱 | 85-95% |
| 可用 | 150-200DPI | 一般 | 有褶皱 | 70-85% |
| 较差 | <150DPI | 反光/阴影 | 严重褶皱 | <70%，建议重新拍摄 |

**图片质量自检清单**：
- [ ] 发票代码和号码区域是否清晰可辨？
- [ ] 金额数字是否有模糊或重影？
- [ ] 是否有反光或阴影遮挡关键信息？
- [ ] 发票边缘是否完整可见？
- [ ] 图片分辨率是否足够（建议手机相机≥1200万像素）？

> **提高识别率的小技巧**：
> 1. 用手机相机拍摄时，开启"文档模式"或"扫描模式"
> 2. 避免强光直射，减少反光
> 3. 发票平整放置，不要弯曲
> 4. 确保发票代码、号码区域清晰可见
> 5. 如果无法识别，请检查图片中是否有手写涂改
> 6. **推荐使用扫描件**，比拍照效果更好
> 7. 可使用手机扫描APP（如"扫描全能王"）预处理图片

## 限制说明

> **30秒摘要**：仅支持增值税发票（不支持手写/定额），数据全部本地处理（不上传），不提供税务咨询。

### 功能限制

| 限制项 | 具体说明 |
|--------|---------|
| OCR识别 | 仅支持增值税发票（专票/普票/电子票） |
| 暂不支持 | 手写发票、定额发票、机动车发票、二手车发票 |
| 查验功能 | 需企业自行申请API密钥，Skill不代为申请 |
| 审批功能 | 需企业管理员在对应平台开通审批API权限 |

### 技术限制

| 限制项 | 具体说明 |
|--------|---------|
| 运行环境 | Python 3.8+ |
| 必须安装 | Tesseract OCR + 中文语言包 |
| 图片格式 | PNG/JPG/TIFF/PDF（PDF需要poppler） |
| 语言 | 中文简体，其他语言准确率显著下降 |
| 并发 | 单线程处理，一次一张 |

### 安全限制

| 限制项 | 具体说明 |
|--------|---------|
| 数据上传 | 绝不将发票图片上传到任何第三方服务器 |
| API调用 | 仅在用户明确授权后执行，且仅调用用户配置的平台 |
| 日志 | 仅记录操作元数据（文件名、时间、状态），不记录发票内容 |
| 临时文件 | 识别完成后自动清理，保留不超过24小时 |

## 错误代码速查表

| 错误代码 | 问题描述 | 解决方案 |
|---------|---------|---------|
| `Tesseract not found` | Tesseract未安装或未加入PATH | 运行 `install_tesseract.ps1` 并重启终端 |
| `chi_sim not found` | 中文语言包未安装 | 重新安装Tesseract，勾选Chinese语言包 |
| `PIL not found` | Pillow未安装 | `pip install Pillow` |
| `pytesseract not found` | pytesseract未安装 | `pip install pytesseract` |
| `openpyxl not found` | openpyxl未安装 | `pip install openpyxl` |
| `pdf2image not found` | PDF转图片工具未安装 | `pip install pdf2image` + 安装poppler |
| `empty result` | OCR未识别到文字 | 检查图片质量、光线、平整度 |
| `low confidence` | 识别置信度低于0.7 | 建议重新拍摄，或手动输入发票信息 |
| `verify_engine not configured` | 查验引擎未配置 | 编辑config.yaml，填写对应API Key |
| `approval_engine not configured` | 审批引擎未配置 | 编辑config.yaml，选择并填写审批平台 |
| `token_failed` | 获取AccessToken失败 | 检查API Key/Secret是否正确 |
| `template_not_found` | 模板文件不存在 | 检查template路径是否正确 |

## 风险声明

> **30秒摘要**：数据本地处理不上传、查验结果由第三方平台提供、审批不可撤销、本工具不提供税务咨询。

> 🔴 **使用本Skill前，请务必仔细阅读以下条款：**

### 1. 数据安全责任

- 所有发票数据仅在用户本地设备处理，不会上传到任何服务器
- **但用户需自行确保本地设备的安全**，Skill开发者不对数据泄露承担责任
- 用户需自行负责API密钥的安全保管
- 建议定期轮换API密钥（每90天一次）

### 2. 查验结果免责声明

- 查验引擎返回的结果由第三方平台提供
- Skill仅提供技术对接，**不对查验结果的准确性负责**
- 如对查验结果有疑问，请直接联系相关税务平台

### 3. 审批操作责任

- 审批提交后不可撤销（以各平台规则为准）
- Skill不审批内容的合规性和真实性
- 用户对提交的报销单内容负全部责任

### 4. 财务合规要求

- 本工具仅为技术支持工具，**不提供任何税务咨询或财务建议**
- 所有财务决策应由专业财务人员做出
- 需专业税务意见时，请咨询持牌税务顾问

### 5. 禁止行为

使用本Skill，用户不得：
- 伪造、变造发票
- 使用假发票报销
- 虚增报销金额
- 报销与业务无关的费用
- 进行其他违反财务法规的行为

### 6. 企业自主决策清单

使用前，请确认您已决定以下事项：

- [ ] 查验引擎选择：□ 国税总局平台（免费） □ 百望云 □ 诺诺发票 □ 自建接口
- [ ] 审批平台选择：□ 钉钉 □ 企业微信 □ 飞书 □ 自建系统 □ 暂不使用
- [ ] 数据安全策略：日志保留期限、临时文件清理频率
- [ ] 合规审查：内部审计、外部审计计划

## 配置文件模板

```yaml
# config.yaml - 企业自主配置
# 本文件为示例模板，企业需根据实际情况填写
# 未配置的功能模块将提示手动操作

# ==================== 查验引擎配置 ====================
verify_engine: "tax_bureau"
# 可选值:
# - "tax_bureau": 国税总局查验平台（免费，无需API Key）
# - "bairong": 百望云API（需API Key+Secret）
# - "nuonuo": 诺诺发票API（需API Key+Secret）
# - "custom": 企业自建接口（需接口地址）

# 百望云（如选择bairong）
bairong:
  api_key: "在此填写您的百望云API Key"
  api_secret: "在此填写您的百望云Secret"

# 诺诺发票（如选择nuonuo）
nuonuo:
  api_key: "在此填写您的诺诺发票API Key"
  api_secret: "在此填写您的诺诺发票Secret"

# 自建查验接口（如选择custom）
custom:
  endpoint: "https://your-company.com/api/verify"
  method: "POST"
  headers:
    Authorization: "Bearer YOUR_TOKEN"

# ==================== 审批平台配置 ====================
approval:
  platform: "none"  # dingtalk / wecom / feishu / none

  # 钉钉审批
  dingtalk:
    app_key: ""
    app_secret: ""
    process_code: ""

  # 企业微信审批
  wecom:
    corp_id: ""
    secret: ""
    template_id: ""

  # 飞书审批
  feishu:
    app_id: ""
    app_secret: ""
    approval_code: ""

  # 自建审批系统
  custom:
    endpoint: ""
    method: "POST"
    headers: {}
    timeout: 30

# ==================== 模板映射配置 ====================
template:
  path: "templates/expense_basic.xlsx"  # 报销单模板路径
  field_mapping:
    invoice_date: "开票日期"
    seller_name: "销方名称"
    amount: "金额（不含税）"
    tax_amount: "税额"
    total: "价税合计"
    remark: "费用说明"
    invoice_code: "发票代码"
    invoice_number: "发票号码"
```

## 故障排除

### 常见问题

**Q1: 安装Tesseract后仍然提示 `Tesseract not found`**

A: 通常是PATH环境变量未生效。

- **Windows**：重启PowerShell/终端，或手动运行 `refreshenv`
- **Linux/macOS**：运行 `source ~/.bashrc` 或 `source ~/.zshrc`
- 紧急方案：使用 `--tesseract` 参数指定完整路径：
  ```bash
  python ocr_engine.py --tesseract "C:\Program Files\Tesseract-OCR\tesseract.exe" --input 发票.png
  ```

**Q2: 识别结果为空或仅识别到少量内容**

A: 按顺序排查：
1. 图片质量是否过低？（拍摄光线、平整度、分辨率）
2. 发票类型是否支持？（手写发票不支持）
3. 是否安装了中文语言包？（运行 `tesseract --list-langs` 检查是否有 `chi_sim`）
4. 尝试提高图片预处理质量（在代码中调整阈值参数）
5. 尝试用原始图片（未预处理）重新识别 — 某些情况下预处理反而会降低图片质量

**Q3: 提示 `PermissionError` 或 `Occupied`**

A: 文件被其他程序关闭。请关闭所有占用目标文件的程序后重试。

**Q4: 查验接口返回失败**

A: 排查顺序：
1. 检查API Key/Secret是否正确（无多余空格）
2. 检查网络是否可访问对应平台
3. 检查是否超出调用频率限制
4. 查看 `logs/verify_engine.log` 了解详细错误

**Q5: 模板匹配失败**

A: 检查以下几点：
1. 模板文件第一行是否为中文表头
2. 模板文件是否未损坏（用Excel打开确认）
3. 字段名是否在预设映射表中（见 `common_mappings`）
4. 可尝试手动指定映射关系

**Q6: 如何减小识别结果文件体积？**

A: 处理完成后，删除 `output/` 目录下的中间文件（`.json`、`.xlsx`），仅保留最终需要的文件。Skill会自动清理临时文件。

**Q7: 支持哪些审批平台？**

A: 钉钉、企业微信、飞书、自建系统（需实现接口）。

**Q8: 如果审批平台不在列表中怎么办？**

A: 使用 `custom` 选项，填写企业自建审批系统的接口地址和鉴权方式。

**Q9: OCR识别率低，很多字段识别错误**

A: 识别效果主要取决于图片质量，请尝试以下方法：
1. **图片质量**：确保分辨率≥200DPI，光线均匀，无反光
2. **推荐使用扫描件**：扫描件比拍照效果更好，文字更清晰
3. **使用手机扫描APP**：如"扫描全能王"、"白描"等APP预处理图片，可显著提升识别率
4. **图片格式**：优先使用JPG或PNG，避免PDF（需额外安装poppler）
5. **发票类型**：仅支持增值税专票/普票/电子票
6. **手动校验**：识别后人工核对关键字段（代码、号码、金额）
7. **模板学习**：使用 `template_matcher.py analyze` 分析模板结构

**Q10: 批量处理时部分文件失败**

A: 正常现象，不影响其他文件。失败的文件会记录在JSON输出的 `failed_files` 字段中，包含：
- `file`：文件路径
- `error`：错误原因
- `tip`：建议操作
- `suggestions`：具体改进建议

**Q11: 审批Token获取失败**

A: 排查步骤：
1. 确认API Key/Secret正确（无空格、大小写正确）
2. 确认应用已开通审批权限（钉钉/企微/飞书管理后台）
3. 确认服务器IP已在白名单中
4. 确认Token未过期（默认2小时有效期）
5. 检查网络是否可访问对应API地址

**Q12: 如何选择合适的查验引擎？**

A: 根据企业需求选择：
- **国税总局平台（推荐）**：免费，无需API Key，生成链接手动查验
- **百望云/诺诺发票**：需付费API Key，自动返回查验结果
- **自建接口**：适合有自建查验系统的企业

**Q13: 金额勾稽关系不匹配怎么办？**

A: 可能原因：
1. OCR识别错误：人工核对金额、税额、价税合计
2. 小数精度问题：系统自动四舍五入，0.01元以内差异可忽略
3. 特殊发票：部分发票金额计算方式不同

**Q14: 环境预检通过但OCR仍失败**

A: 可能原因：
1. Tesseract版本过低（建议4.0+）
2. 中文语言包不完整（检查文件大小≥5MB）
3. 图片质量极差（重新拍摄）
4. 发票类型不支持（手写发票、定额发票不支持）

### 日志文件说明

如果以上方案均无法解决问题，请查看日志文件获取详细信息：

```
logs/
├── ocr_engine.log          # OCR识别详情
├── verify_engine.log       # 查验详情
├── template_matcher.log    # 模板匹配详情
├── approval_engine.log     # 审批详情
└── error.log               # 错误日志（优先查看）
```

## 支持与反馈

- 问题反馈：请在SkillHub平台提交Issue
- 功能建议：欢迎提交Pull Request
- 邮箱：联系Skill开发者

## 更新日志

### v2.7.0 (2026-06-30)
- **新增**：【使用技巧与注意事项】章节，汇总5项基本技巧+5项注意事项，一目了然
- **新增**：【模糊发票处理指南】，4步流程应对图片模糊场景
- **新增**：OCR引擎 `--manual` 手动输入模式，OCR失败时可直接手动输入发票信息
- **新增**：长章节增加"30秒摘要"，减少阅读时间（快速开始/发票类型/限制说明/风险声明）
- **新增**：OCR软件大小说明，解释60MB安装包的必要性（数据安全 vs 软件体积的权衡）
- **改进**：手动输入模式支持金额勾稽自动检查，输入不一致会提示警告

### v2.6.5 (2026-06-30)
- **修复**：修复bug


### v2.6.0 (2026-06-30)
- **新增**：【如何「指挥」它干活】章节，包含自然语言对话示例表格（8种场景+详细说法）
- **新增**：【常见问题速查】集中解答板块，按6大类（安装配置/OCR识别/查验审批/模板数据/安全合规）组织
- **改进**：FAQ和常见问题从分散在多处改为集中速查表+详细解答两部分，查找更方便
- **改进**：触发词章节扩展为更详细的"如何指挥"说明，降低用户上手门槛
- **改进**：所有错误提示保持专业术语+通俗解释的平衡

### v2.5.0 (2026-06-29)
- **改进**：版本号升至 2.5.0
- **改进**：图片质量要求增加"图片质量自检清单"，帮助用户提前发现图片问题
- **改进**：图片质量要求增加扫描件推荐和手机扫描APP建议
- **改进**：图片质量要求顶部增加醒目的"识别效果高度依赖图片质量"提醒
- **改进**：FAQ Q2增加"尝试用原始图片重新识别"的排查建议
- **改进**：FAQ Q9增加"推荐使用扫描件"和"手机扫描APP预处理"建议
- **改进**：所有脚本错误提示在专业术语后增加通俗解释，方便非技术用户理解
- **改进**：ocr_engine.py 低置信度阈值从0.6调整为0.7，更早提醒用户核对
- **改进**：check_env.py 输出格式优化，失败项用更醒目的标识

### v1.3.0 (2026-06-29)
- **改进**：OCR引擎增加PSM模式回退机制（6→3→4→11→12）
- **改进**：OCR引擎增加图片质量预检（尺寸、模式、亮度检查）
- **改进**：OCR引擎提供详细的识别失败诊断和建议
- **改进**：查验引擎增加参数格式校验和类型转换
- **改进**：查验引擎增加重试机制和指数退避
- **改进**：审批引擎增加Token获取重试和超时设置
- **改进**：审批引擎增加报销单文件存在性检查
- **改进**：审批引擎增加配置完整性验证
- **改进**：发票解析器支持更多日期格式和金额格式
- **改进**：发票解析器增加金额勾稽检查和日期有效性验证
- **改进**：模板匹配器增加文件格式检查和表头完整性验证
- **改进**：批量处理增加失败文件记录和统计
- **改进**：环境预检增加Tesseract版本和语言包完整性检查
- **改进**：错误代码速查表增加更多FAQ条目（Q9-Q14）
- **改进**：所有脚本增强错误处理和容错能力

### v1.1.0 (2026-06-29)
- **新增**：环境预检脚本 `scripts/check_env.py`
- **新增**：错误代码速查表
- **新增**：发票图片质量要求和拍摄建议
- **升级**：真伪查验引擎 `verify_engine.py`，真正对接国税总局/第三方平台
- **升级**：审批引擎 `approval_engine.py`，真正获取Token并调用API
- **升级**：安装脚本增加预检环节
- **升级**：模板匹配支持PDF格式（需poppler）
- **改进**：所有脚本增加更详细的错误提示
- **改进**：配置文件中增加timeout设置

### v1.0.0 (2026-06-28)
- 初始版本发布
- 支持增值税发票OCR识别
- 支持多种查验引擎接口
- 支持模板自适应学习
- 支持多种审批平台对接

## 免责声明

本工具仅提供发票识别和报销单生成的技术支持，**不提供任何税务咨询或财务建议**。所有财务决策应由专业财务人员做出。使用者需确保符合当地法律法规。使用本工具即表示接受《风险声明》中的全部条款。