# 发票整理

> 发票整理 is an Agent Skill for documents published in the maka-agent/maka-agent repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

为报税或报销系统化整理发票收据时使用，扫描目录识别票据、按日期类别金额归类、生成汇总清单与台账

- Skill name: `发票整理`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/maka-agent/maka-agent/blob/HEAD/apps/desktop/resources/bundled-skills/invoice-organizer/SKILL.md
- Repository: maka-agent/maka-agent (675 GitHub stars when collected)

## SKILL.md

# 发票整理

把散落在一堆目录里、命名混乱的发票收据，整理成一份可用于报销或报税的结构化台账。核心工作是：找出所有票据文件 → 提取关键信息 → 按日期/类别/金额归类 → 生成汇总清单和明细台账。目标是省掉人工逐张登记的苦力活，而不是替用户做财务判断。

## 目标

对指定目录里的发票收据，产出两份可直接使用的成果：**一份 CSV 明细台账**（每张票据一行，字段规整，可导入 Excel/报销系统）和**一份 Markdown 汇总报告**（按类别/月份的金额小计、总计、待核对清单）。整理过程只读不删，金额或信息存疑的一律标注"待核对"，把判断权留给用户。

## 工作流步骤

### 步骤 1：确认范围与规则

动手前先和用户确认（缺失则询问）：

- **目标目录**：要整理哪个目录？是否含子目录？
- **用途**：报销还是报税？这决定分类维度（报销常按人/项目/月份，报税常按发票类型/月份/税额）。
- **时间范围**：只整理某段时间的票据吗？
- **分类维度**：按类别（交通/住宿/餐饮/办公/通讯/会议等）、按月份、按项目或按人。默认按"类别 + 月份"双维度。
- **币种**：是否多币种，是否需要换算（换算需用户提供汇率，不自行假设）。

### 步骤 2：扫描目录、识别票据文件

用 Glob 和 Bash 找出候选文件，不修改任何文件。

- 用 Glob 按常见票据格式扫描：`**/*.pdf`、`**/*.jpg`、`**/*.jpeg`、`**/*.png`、`**/*.ofd`（国内电子发票）、`**/*.xml`、`**/*.xlsx`。
- 用 Bash 辅助列出文件清单及元信息（大小、修改时间），例如用 `ls -la`、`find` 统计数量和分布。**只用只读命令**（ls/find/stat/file/wc 等），不使用任何移动、重命名、删除类命令。
- 初步过滤：明显不是票据的文件（截图、无关文档）先标为"疑似非票据"，交由后续判断，不擅自排除。
- 统计总数并向用户报告扫描结果概览（找到多少个候选文件、分布在哪些目录、各格式数量）。

### 步骤 3：提取关键信息

对每个候选文件提取台账所需字段。**能确定的字段就填，不能确定的留空并标注，绝不猜数字。**

需要提取的核心字段：

- **开票日期**（date）
- **商户 / 开票方**（vendor）
- **金额（价税合计）**（amount）
- **税额**（tax，如有）
- **发票类型**（专票/普票/电子发票/收据等）
- **类别**（transportation/accommodation/meals/office/... 按步骤 1 约定）
- **文件路径**（source_path，保留原始位置，便于溯源）
- **备注 / 状态**（note：如"待核对""图片模糊""金额不清"）

提取方式：

- 文本类文件（PDF 文本层、XML、OFD 解析出的文本、xlsx）：用 Read 读取内容后解析字段。
- **图片和扫描件**：本技能不做 OCR 图像识别。对无法直接读出文本的图片，在台账中登记文件路径和从文件名/目录能推断的信息，其余字段留空并标注"待核对：需人工录入"。
- 从文件名和目录名可以推断的信息（很多人用"20240315-高铁-352元"这类命名）可作为线索，但**必须标注为"推断"**，不能当作确认值——文件名可能是错的。

### 步骤 4：归类与汇总

- 按步骤 1 约定的维度给每条记录归类（类别 + 月份为默认双维度）。
- 计算各维度小计和总计：按类别汇总金额、按月份汇总金额、总金额、总税额。
- **金额校验**：对能读到明细的票据，若"价税合计 ≠ 不含税金额 + 税额"，标注"金额待核对"。发现同一张票据疑似重复（相同金额+日期+商户）时标注"疑似重复"，列出但不自动删除。
- 汇总数字要能对得上：明细行金额之和应等于总计，把这个校验也写进报告。

### 步骤 5：生成台账与报告

用 Write 输出两份文件到用户指定位置（默认目标目录下，或用户给的路径）：

1. **CSV 明细台账**（`invoice-ledger.csv`）：一张票一行，字段见输出格式。
2. **Markdown 汇总报告**（`invoice-summary.md`）：金额小计、总计、待核对清单、疑似重复清单、非票据文件清单。

最后向用户报告：共整理多少张、总金额、有多少张需要人工核对、有哪些疑似问题。

## 输出格式

**CSV 台账（invoice-ledger.csv）** 表头：

```csv
序号,开票日期,商户,类别,金额,税额,发票类型,状态,文件路径
1,2026-03-15,某高铁,交通,352.00,,电子发票,已确认,./2026-03/高铁-352.pdf
2,2026-03-16,某酒店,住宿,,,图片,待核对:金额不清,./2026-03/hotel.jpg
```

**Markdown 汇总报告（invoice-summary.md）** 结构：

```markdown
# 发票整理汇总（<时间范围>）

- 整理目录：<path>
- 票据总数：N 张（已确认 X，待核对 Y）
- 合计金额：¥ZZZ（其中税额 ¥WW）
- 生成时间：<date>

## 按类别汇总
| 类别 | 张数 | 金额 |
|------|------|------|
| 交通 | 12   | 4,230.00 |

## 按月份汇总
| 月份 | 张数 | 金额 |
|------|------|------|

## 待核对清单（需人工确认）
| 序号 | 文件 | 原因 |
|------|------|------|

## 疑似重复
| 序号 | 文件 | 说明 |

## 疑似非票据文件
- <path>
```

## 边界

- **只整理，绝不删除或移动**：本技能不删除、不重命名、不移动任何原始文件，Bash 仅用于只读扫描（ls/find/stat/file 等）。整理产物是新生成的台账文件。
- **不臆造金额和信息**：读不出来的字段一律留空并标注"待核对"，绝不填一个"看起来合理"的数字。从文件名推断的信息必须标注为推断值。
- **金额存疑必标注**：价税不符、图片模糊、疑似重复、疑似非票据的，全部标注并汇总到"待核对/疑似"清单，把核对判断权交回用户。
- **不做 OCR 图像识别**：对纯图片扫描件，只登记路径和可推断信息，提示用户人工录入或使用专门 OCR 工具，不假装识别出了内容。
- **不提供税务/合规裁定**：本技能整理数据、做算术汇总，不判定发票是否合规、能否抵扣、能否报销——这些是财税专业判断，明确提示由用户或财务/税务人员决定。
- **保护财务隐私**：台账仅生成在本地用户指定位置，不外传；涉及金额和商户等敏感信息，不写入任何外部渠道。

---

Source: https://www.openparable.com/skill/documents/%E5%8F%91%E7%A5%A8%E6%95%B4%E7%90%86 (OpenParable). Cite the canonical URL above.