dsh-invoice-organizer

从散落的邮箱附件，到可核验的发票台账，只需要一句话。

一个独立实现、MIT 协议的 DeepSeek Harness（DSH）发票整理插件。它把邮箱访问、附件处理、去重、归档和 Excel 汇总留在本机，由 DSH 当前会话所选模型（包括 Codex）审阅候选发票并决定提交哪些记录；不绑定特定模型，也不需要单独的桌面 App。

你：扫描本月发票，先核对公司抬头和税号，确认后再归档。

DSH：扫描附件 → 提取字段 → 排除错抬头 → 去重预览
你：确认整理。
DSH：归档原件 → 生成 Excel → 汇总张数与金额

为什么做成 DSH 插件

• 模型可替换：使用 DSH 当前选择的模型，包括 Codex，不锁定单一模型供应商。
• 本地优先：附件、扫描清单、归档文件和 Excel 默认留在本机。
• 先核对再写入：扫描与提交分成两个工具，支持 dry-run，避免模型直接改文件。
• 结果可追溯：保留发票号码、归档路径与 SHA-256，方便复核来源和重复件。

能做什么

• 只读扫描本地目录，或通过 IMAP 只读下载指定日期范围内的 PDF、OFD、XML、ZIP 发票附件
• 提取文本和常见发票字段，按购买方名称和税号双重校验
• 把候选结果交给 DSH 当前模型复核与修正
• 按发票号码优先、文件 SHA-256 兜底去重
• 先 dry-run，再生成归档目录与 invoice_summary.xlsx
• 邮箱授权码只从 DSH credential reference 读取，不进入模型参数或日志

当前版本不内置 OCR。没有文本层的扫描 PDF 会进入人工复核，避免把高风险的错误金额自动记账。

安装

要求：Node.js 22.19+、Python 3.10+、DSH 0.1.1-rc.2 或兼容版本。

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
npm install
npm run build
dsh plugin --profile <profile> add /absolute/path/to/dsh-invoice-organizer

安装后，在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 覆盖配置。allowedRoots 默认空数组，插件会拒绝一切文件读写，必须显式列出允许的目录：

- id: dsh-invoice-organizer
  config:
    pythonExecutable: /absolute/path/to/dsh-invoice-organizer/.venv/bin/python
    imapHost: imap.qq.com
    imapPort: 993
    imapMailbox: INBOX
    imapUsername: your-address@qq.com
    imapAuthCodeEnv: DSH_INVOICE_IMAP_AUTH_CODE
    dataDir: ~/.dsh-invoice-organizer
    allowedRoots:
      - /Users/you/Invoices
    defaultCompany: 示例科技有限公司
    defaultTaxId: YOUR_COMPANY_TAX_ID
    defaultOutputDir: /Users/you/Invoices/organized

在 DSH 的凭据设置中保存 DSH_INVOICE_IMAP_AUTH_CODE。不要把邮箱密码或授权码写入配置文件、聊天消息或 Git 仓库。

使用方式

在 DSH 对话中说：

扫描 2026-09-01 到 2026-09-15 的发票，先给我看候选和总额，不要写文件。

模型会先调用 invoice_scan，复核后用 invoice_commit(commit=false) 预览。确认要整理时，再让它以 commit=true 写入归档和 Excel。

安全边界

• IMAP 始终以 readonly=True 打开邮箱，不改已读状态、不移动或删除邮件。
• 文件路径必须位于 allowedRoots；空列表默认拒绝。
• ZIP 有单文件、总大小和文件数限制，并丢弃路径信息，防止目录穿越。
• 扫描阶段冻结附件并记录 SHA-256；提交前再次校验，防止内容被替换。
• 购买方名称和税号不匹配时，提交会失败。

开发验证

npm run check

路线图

• 图片型 PDF 本地 OCR
• 更多邮箱服务的配置向导
• 增量扫描与跨期历史去重
• 可自定义的报销模板和费用分类规则

欢迎提交 Issue 或 Pull Request。

License

MIT © 2026 Lawrence Tang