@rokoai/fapiao 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rokoai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# 发票整理 Skill
+
+这是一个给 Codex 使用的发票整理 skill，用来把本地发票 PDF、服务商 invoice/receipt、Gmail 邮件里的发票附件，整理成按月份归档的文件夹和 CSV 台账。
+
+它适合处理这些场景：
+
+- 整理中国电子发票 PDF
+- 整理 ChatGPT、云服务、软件订阅等海外服务的 invoice 和 receipt
+- 从 Gmail 搜索近期发票邮件并下载附件
+- 按月份创建 `YYYY-MM/` 文件夹和 `YYYY_M.csv` 台账
+- 按规则重命名发票文件
+- 去重重复发票或重复下载的邮件附件
+- 写入统一 CSV 字段：日期、类型、金额、支付账户、用途、分类、是否报销、发票、备注
+
+## 安装
+
+```bash
+npx @rokoai/fapiao
+```
+
+安装后会把 skill 复制到：
+
+```text
+~/.codex/skills/fapiao
+```
+
+之后在 Codex 里这样调用：
+
+```text
+$fapiao
+```
+
+例如：
+
+```text
+$fapiao 整理这个月的发票，更新 CSV 台账
+```
+
+## 工作方式
+
+这个 skill 会把当前工作目录当成发票归档根目录，不依赖任何固定的本地路径。默认结构是：
+
+```text
+2026-05/
+2026_5.csv
+```
+
+CSV 表头固定为：
+
+```csv
+日期,类型,金额,支付账户,用途,分类,是否报销,发票,备注
+```
+
+归档文件名示例：
+
+```text
+2026-05-09+加油+362.00.pdf
+2026-05-16+ChatGPT Plus订阅+138.00+invoice.pdf
+2026-05-16+ChatGPT Plus订阅+138.00+receipt.pdf
+```

package/bin/install.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const source = path.join(packageRoot, "skill");
+const destination = path.join(os.homedir(), ".codex", "skills", "fapiao");
+
+function copyDirectory(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+if (!fs.existsSync(source)) {
+  console.error(`Missing bundled skill directory: ${source}`);
+  process.exit(1);
+}
+
+copyDirectory(source, destination);
+
+console.log(`Installed fapiao skill to ${destination}`);
+console.log("Invoke it in Codex with: $fapiao");

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@rokoai/fapiao",
+  "version": "0.1.0",
+  "description": "Codex skill for organizing invoice PDFs, Gmail invoice emails, and monthly CSV ledgers.",
+  "type": "module",
+  "bin": {
+    "fapiao": "./bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "README.md"
+  ],
+  "keywords": [
+    "codex",
+    "skill",
+    "invoice",
+    "fapiao",
+    "gmail"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RokoSkills/fapiao.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: fapiao
+description: Organize Chinese and service-provider invoice PDFs, receipts, Gmail invoice emails, monthly invoice folders, and root-level monthly CSV ledgers from the current working directory. Use when the user asks to整理发票, process new invoice PDFs, search Gmail for recent invoice emails, rename invoice/receipt files, write or audit monthly CSV rows, deduplicate invoices, or update an invoice archive.
+---
+
+# Fapiao
+
+Manage an invoice archive rooted at the current working directory. Treat the current directory as the archive root; never hardcode or depend on a user's private absolute paths.
+
+## Archive Layout
+
+Use one folder per month:
+
+```text
+YYYY-MM/
+```
+
+Use one root-level CSV per month, not inside the month folder:
+
+```text
+YYYY_M.csv
+```
+
+Examples:
+
+```text
+2026-05/
+2026_5.csv
+```
+
+CSV header:
+
+```csv
+日期,类型,金额,支付账户,用途,分类,是否报销,发票,备注
+```
+
+When preparing a month, run:
+
+```bash
+python3 scripts/ensure_month.py 2026 6
+```
+
+If `scripts/ensure_month.py` is missing in the archive, create the month folder and CSV manually with the fixed header.
+
+## Workflow
+
+1. Confirm the target year and month from the user's request or current date.
+2. Check the local archive state first. If the target month folder or root monthly CSV is missing, create it.
+3. On macOS, inspect `~/Downloads` for invoice-related PDFs created or modified in the last 7 days. Copy likely invoice PDFs into the archive before processing. Do not move or delete the originals.
+4. Decide whether to check Gmail:
+   - Check Gmail when the user says to search Gmail, check mail, or download invoice emails.
+   - Skip Gmail when the user asks to organize local invoices or process files already in the directory.
+   - If ambiguous, infer from wording.
+5. Process new PDFs in the target month folder, including PDFs downloaded from Gmail and files the user already placed there.
+6. Extract fields, deduplicate, rename files, and write one CSV row per real expense.
+7. Final-check new PDF count, new CSV rows, skipped duplicates, and any Gmail messages that could not be processed.
+8. Commit only when the user asks for a commit or push.
+
+## Gmail
+
+Use connected Gmail tools when available. Do not use generic web search for Gmail mail.
+
+Before Gmail work, check whether the Gmail connector/plugin is available. If unavailable, unauthorized, or inaccessible, notify the user clearly and continue any local-only workflow.
+
+Search recent invoice emails with:
+
+```text
+newer_than:1d 发票 -in:spam -in:trash
+```
+
+For each Gmail hit, record sender, subject, received time, body summary, attachments, filenames, sizes, and MIME types. Process only messages with attachments or body links to PDF downloads.
+
+Download usable invoice PDFs into the target month folder first, using original or temporary filenames. Prefer PDF for the final archive. Use XML as structured metadata. Treat OFD as auxiliary unless the user explicitly asks to archive it.
+
+Rules:
+
+- If a PDF attachment is `application/pdf`, read and download it directly when the connector allows it.
+- If a PDF attachment is mislabeled as `application/octet-stream` and the connector cannot read or download it, mark it for manual Gmail web download; do not invent a file.
+- If the body contains `PDF格式下载` and `XML格式下载`, use XML to identify fields and save the PDF as the final archived file.
+- Deduplicate across emails by invoice number plus amount/date/seller before saving duplicates.
+
+## Downloads Discovery
+
+For macOS Downloads discovery, use filename keywords, MIME type, and PDF detection heuristics. Likely keywords include:
+
+```text
+发票 invoice receipt fapiao pdf 电子发票
+```
+
+Copy likely PDFs into the archive root or target month folder before processing. Keep originals in Downloads untouched.
+
+## Field Extraction
+
+Prioritize these fields:
+
+- Date: use Date paid or payment date first; otherwise use invoice issue date or 开票日期.
+- Amount: use 价税合计, Total, or Amount paid.
+- Purpose: summarize from 项目名称 or Description.
+- Payment account: include receipt payment method when present, for example `Mastercard - 4516`.
+- Remark: include seller/payee, invoice number, receipt number, order number, project detail, USD amount, and exchange rate as applicable.
+
+## Naming Rules
+
+Chinese invoice PDF:
+
+```text
+YYYY-MM-DD+事项+金额.pdf
+```
+
+Examples:
+
+```text
+2026-05-09+加油+362.00.pdf
+2026-05-09+代订住宿服务费+387.00.pdf
+```
+
+USD service with both invoice and receipt:
+
+```text
+YYYY-MM-DD+服务名+人民币金额+invoice.pdf
+YYYY-MM-DD+服务名+人民币金额+receipt.pdf
+```
+
+Examples:
+
+```text
+2026-05-16+ChatGPT Plus订阅+138.00+invoice.pdf
+2026-05-16+ChatGPT Plus订阅+138.00+receipt.pdf
+```
+
+## Classification
+
+Use these defaults unless the extracted document indicates a better category:
+
+- 成品油、汽油、加油站: 用途 `加油`, 分类 `交通费`
+- 住宿、酒店、民宿: 用途 `代订住宿服务费` or `住宿`
+- 沃尔玛、山姆、食品、日用品: 用途 `购物`, 分类 `办公/日用品` when appropriate
+- 软件订阅、云服务、AI 服务: concrete service name, 分类 `软件服务费`
+
+## CSV Rules
+
+Write one row per real expense, not one row per file. If the same expense has both invoice and receipt, write one row and put both relative paths in `发票`, separated by Chinese semicolon `；`.
+
+Use paths relative to the archive root:
+
+```text
+2026-05/2026-05-16+ChatGPT Plus订阅+138.00+invoice.pdf；2026-05/2026-05-16+ChatGPT Plus订阅+138.00+receipt.pdf
+```
+
+Chinese invoice example:
+
+```csv
+2026-05-09,成品油电子发票（普通发票）,362.00,,加油,交通费,,2026-05/2026-05-09+加油+362.00.pdf,发票号码：xxx；销售方：xxx；项目：92号汽油
+```
+
+Invoice plus receipt example:
+
+```csv
+2026-05-16,Invoice/Receipt,138.00,Mastercard - 4516,ChatGPT Plus订阅,软件服务费,,2026-05/2026-05-16+ChatGPT Plus订阅+138.00+invoice.pdf；2026-05/2026-05-16+ChatGPT Plus订阅+138.00+receipt.pdf,OpenAI ChatGPT Plus Subscription (per seat)；金额：20.00 USD；汇率：6.9；Invoice：xxx；Receipt：xxx
+```
+
+Receipt-only example:
+
+```csv
+2026-05-16,Receipt,138.00,Mastercard - 4516,ChatGPT Plus订阅,软件服务费,,2026-05/2026-05-16+ChatGPT Plus订阅+138.00+receipt.pdf,仅有收据，无 invoice；OpenAI ChatGPT Plus Subscription (per seat)；金额：20.00 USD；汇率：6.9；Receipt：2079-5046-5382
+```
+
+## USD Services
+
+Always write RMB in the `金额` column, not USD.
+
+Use fixed exchange rate `6.9` unless the user says otherwise:
+
+```text
+RMB = USD * 6.9
+20.00 USD * 6.9 = 138.00 RMB
+```
+
+For USD services:
+
+- 金额: RMB with two decimals
+- 用途: concrete service, for example `ChatGPT Plus订阅`
+- 分类: usually `软件服务费`
+- 支付账户: receipt card/account if present
+- 备注: service content, USD amount, exchange rate, and invoice/receipt numbers
+
+## Deduplication
+
+Treat files as duplicates when invoice/receipt number, amount, date, and seller/payee match.
+
+For duplicates:
+
+- Keep one archived file.
+- Write only one CSV row.
+- Do not count duplicate downloads as additional expenses.
+
+## Git
+
+Only commit or push when the user asks.
+
+Before committing:
+
+```bash
+git status --short
+```
+
+Confirm changes are only invoice archive changes intended for the run. Do not commit `.DS_Store`.
+
+Suggested commit message for archive updates:
+
+```text
+Update invoice archive
+```
+
+Suggested commit message for workflow/rule changes:
+
+```text
+Update invoice workflow
+```

package/skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Fapiao"
+  short_description: "Organize invoice PDFs and CSV ledgers"
+  default_prompt: "Use $fapiao to organize this month's invoice PDFs and update the CSV ledger."
+
+policy:
+  allow_implicit_invocation: true

package/skill/scripts/ensure_month.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+import argparse
+import csv
+from pathlib import Path
+
+
+HEADER = ["日期", "类型", "金额", "支付账户", "用途", "分类", "是否报销", "发票", "备注"]
+
+
+def ensure_month(year: int, month: int, root: Path) -> tuple[Path, Path]:
+    month_dir = root / f"{year:04d}-{month:02d}"
+    csv_path = root / f"{year:04d}_{month}.csv"
+
+    month_dir.mkdir(parents=True, exist_ok=True)
+
+    if not csv_path.exists():
+        with csv_path.open("w", newline="", encoding="utf-8-sig") as handle:
+            writer = csv.writer(handle)
+            writer.writerow(HEADER)
+
+    return month_dir, csv_path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Create an invoice month folder and CSV ledger.")
+    parser.add_argument("year", type=int)
+    parser.add_argument("month", type=int)
+    parser.add_argument("--root", default=".", help="Archive root. Defaults to current directory.")
+    args = parser.parse_args()
+
+    if args.month < 1 or args.month > 12:
+        parser.error("month must be between 1 and 12")
+
+    month_dir, csv_path = ensure_month(args.year, args.month, Path(args.root).resolve())
+    print(f"Ensured folder: {month_dir}")
+    print(f"Ensured CSV: {csv_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())