fix(invoice-organizer): 统一报告文件名约定 / unify report file naming (#120)

## 问题 / Problem

真机三轮整理实测:Agent 全部写出 `报告/整理报告-<运行日期>.md`,而技能里只定义了 `报告/<YYYY-MM>.md`。

**原因不是模型不听话。** 测试范围跨了 2020-08 到 2024-09 共十几个月,`<YYYY-MM>`
在多月场景下无从填写——技能没给出这种情况的文件名,Agent 只能自己发明一个。

**后果不是难看,而是会攒垃圾。** `invoice-automation` 的定时任务每月重建的是 `报告/<上月
YYYY-MM>.md`;与按运行日期命名的手工报告永远不会互相覆盖,用户目录里会留下一堆内容重叠、无从分辨新旧的报告。

Three real-machine runs all produced `报告/整理报告-<run date>.md`, while the
skills only define `报告/<YYYY-MM>.md`. The runs spanned 2020-08 through
2024-09, so `<YYYY-MM>` was unfillable and the agent improvised. Because
the scheduled monthly job rebuilds `报告/<last month YYYY-MM>.md`, the two
naming schemes never overwrite each other and the user's directory
accumulates overlapping reports with no way to tell which is current.

## 改动 / Changes

- `invoice-workflow` 第 7 步补一张表,把两种文件名钉死:

  | 本次覆盖 | 文件名 | 例 |
  | --- | --- | --- |
  | 恰好一个自然月 | `报告/<YYYY-MM>.md` | `报告/2024-08.md` |
  | 跨多个月 | `报告/<起始 YYYY-MM>_<结束 YYYY-MM>.md` | `报告/2020-08_2024-09.md` |

并写明月份按**开票日期**归属(与台账同口径)、同名直接覆盖(报告是从 `.index/ledger.json`
全量重建的派生产物,不像台账需要先备份)、以及**为什么不许用运行日期命名**
- `invoice-ledger` 与 `references/月度报告模板.md` 同步该约定
- 目录布局示例与中英 USAGE 一并标注跨月形态

## 为什么不在本 PR 里 bump 版本 / Why no version bump here

`contentSource` 的 `ref` 必须 pin 到**已合并的 commit**,本 PR 合并前拿不到那个 SHA。先 bump
版本会让目录声称 1.0.1、却仍按指向 1.0.0 内容的 pin 去取文件——比不 bump 更糟。版本号、pin 与 changelog
留到后续 PR 一起改。

The `contentSource` ref must pin to an already-merged commit, which does
not exist until this PR lands. Bumping the version now would advertise
1.0.1 while still serving 1.0.0 content. Version, pin and changelog
follow in a second PR.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---

## 追加:台账四张表必须全建 / Also: all four ledger sheets must always exist

真机压测(只有 1 张发票)产出的 `台账.xlsx` **只有三张表**——Agent 判定「按销售方汇总」在单一销售方下冗余而略过:

```
发票测试(23 张) → ['明细', '月度汇总', '按销售方汇总', '异常']
发票压测(1 张)  → ['明细', '月度汇总', '异常']          ← 少一张
```


技能写的是「四张表,顺序固定」,但没说「即使为空也必须存在」。台账是要被重复重建、被用户自己写公式引用、被下一次整理覆盖的产物;表的位置一旦随数据量浮动,「第
3 张是按销售方汇总」这类引用就会在下个月悄悄指错。已在 `invoice-ledger` 里把这条钉死。

A stress run with a single invoice produced only three sheets — the
agent judged the per-seller summary redundant. The skill said "four
sheets, fixed order" but never said "even when empty". Sheet positions
that float with row count silently break user formulas and rebuilds; now
pinned.
This commit is contained in:
2026-09-04 11:56:48 -04:00
committed by GitHub
parent 98251c9a1d
commit 7560a58642
5 changed files with 49 additions and 9 deletions

View File

@@ -27,7 +27,7 @@
```
发票/
├── 台账.xlsx依赖不可用时为 台账.csv
├── 报告/2024-08.md
├── 报告/2024-08.md(票都开在同一月;跨月时是 报告/2020-08_2024-09.md
├── 归档/2024/08/20240815_某某酒店管理有限公司_1959.98_24312000000000020002.pdf
├── _inbox/ 刚下载、尚未处理
├── _quarantine/ 解析失败或判定为非发票(每份都附一个 .reason.txt 说明原因)