receipts

dsh（DeepSeek Harness）插件：发票/收据/支付截图识别与消费报告。两条识别路径——VLM 桥接（图片 → OpenAI 兼容端点，默认关）与纯文本规则解析（无需网络）——识别结果带 uncertain 待确认标记，用户核对修正后落库到本地 JSON 账本，再按类别/商户/月份聚合出消费报告，自动标记重复票据与金额离群，可导出 CSV。

状态：developer preview。尚未在真实 dsh 运行时中验证，手动验证步骤见下文。

安装与配置

# dsh 配置示例
- id: receipts
  name: dsh-daily-receipts
  config:
    enabled: true
    dataFile: receipts-ledger.json   # 本地账本（JSON，原子写）
    defaultCurrency: CNY             # 识别不出币种时的默认值
    # categories:                    # 类别 → 关键词映射（整体替换默认表）
    #   餐饮: [餐厅, 咖啡, 外卖]
    vlm:                             # 图片识别路径（默认关）
      enabled: false
      baseURL: https://api.openai.com/v1
      apiKeyEnv: OPENAI_API_KEY      # 环境变量名，密钥只从环境变量读
      model: gpt-4o-mini
      timeoutMs: 60000
      maxTokens: 4096

工具

• receipt_scan：识别单张票据（不落库）。text（纯文本，规则解析，无网络）与 path（图片路径，走 VLM）二选一。结果含 merchant/date/amount/currency/category/items[] 与 uncertain（识别不确定的字段名列表）。
• receipt_confirm：把核对/修正后的票据写入本地账本（amount 必填）。
• receipt_list：账本查询，支持日期范围/类别/商户关键词过滤。
• receipt_report：消费报告。按类别/商户/月份聚合；异常标记＝疑似重复票据（同商户同金额同日期）与金额离群（> 均值 + 2σ，至少 3 条才启用）；exportDir 传入目录则把命中明细导出为 CSV。

典型流程：receipt_scan → 用户核对 uncertain 字段 → receipt_confirm 落库 → receipt_list / receipt_report。

两条识别路径的边界

• VLM 桥接：输入 png/jpg/jpeg/webp/gif 图片（PDF 请先截图首页）。插件把图片 base64 内联进 OpenAI 兼容 chat/completions 请求，要求模型返回严格 JSON，解析带容错（提取首个 JSON 块、逐字段校验，坏字段进 uncertain）。未启用/未配置密钥/端点报错都会给出可读的中文错误。
• 纯文本规则：输入任意票据文本（PDF 文本层、其他 OCR 结果等）。金额识别 ¥/￥/$/€ 前缀与「元」后缀、千分位、「合计/总计/Total」行优先；日期识别 YYYY-MM-DD、YYYY/M/D、YYYY.MM.DD、YYYY年M月D日 并校验真实日历；商户取首个不像噪声（发票代码/号码/金额/日期行）的短行。没有合计行时取最大金额并标记 amount 待确认；多日期取首个并标记 date。

权限透明

本插件对宿主环境的影响面，逐条交代清楚：

• 读：用户通过 receipt_scan 的 path 参数显式指定的票据图片文件（只读，绝不修改原始票据）。
• 写：① dataFile 配置的账本 JSON 文件（原子写：临时文件 + rename）；② receipt_report 的 exportDir 参数显式指定的导出目录（写入 receipts-export-<时间戳>.csv）。除此之外不写任何位置。
• 网络：仅当 vlm.enabled: true 且使用图片路径时，访问 vlm.baseURL 配置的唯一端点。纯文本路径与账本/报告功能完全离线。
• 凭证：VLM API Key 只从 vlm.apiKeyEnv 指定的环境变量读取，不写入配置、账本或日志。
• 确认点：无 dsh ask 挂钩；流程上的确认点是 receipt_confirm——receipt_scan 不落库，落库动作由用户核对后显式触发。
• 日志内容：启动日志含账本路径与 VLM 端点地址；不含票据内容、密钥。

⚠️ 隐私提示：使用图片识别时，票据图像的完整内容会发往你配置的 VLM 端点（可能是第三方云服务）。票据通常含姓名、商户、金额等敏感信息；介意请改用 text 参数走纯文本规则路径（完全离线），或把 vlm.baseURL 指向你自建的端点。

已知限制

• 手写体、模糊、褶皱、反光票据的识别率取决于所用 VLM 模型，规则路径对非标准版式同样会退化——所以结果始终带 uncertain 标记，请勿跳过人工核对。
• 多币种只记录原始币种与金额，不做汇兑换算；报告的聚合总额在混币种场景下是直接相加，仅供参考。
• CSV 导出为首版唯一导出格式；XLSX 导出本版不做（需要 Excel 的场景请先用 CSV 中转）。
• 金额离群检测需要至少 3 条带金额记录，且使用总体标准差；样本少时不标记。
• PDF 不直接解析：请截图首页走 VLM，或提取文本层走 text。

手动验证

本仓库的 CI 只覆盖类型检查与纯函数单测。接入真实 dsh 后请手动验证：

1. 在 dsh 配置中启用本插件，确认启动日志出现 receipts: loaded。
2. 纯文本路径：对 receipt_scan 传一段收据文本（含「合计：¥xx」与日期），确认返回结构化结果且 uncertain 为空；再传一段无合计行的文本，确认 amount 出现在 uncertain 中。
3. 确认流：用 receipt_confirm 落库（修正一个字段），然后 receipt_list 能查到该条。
4. 报告：落库若干条后调用 receipt_report，确认类别聚合正确；落库两条同商户同金额同日期的记录，确认被标记为疑似重复。
5. VLM 路径：配置 vlm.enabled: true 与密钥环境变量，对 receipt_scan 传一张票据图片路径，确认识别成功；再把 apiKeyEnv 指向不存在的环境变量，确认报错可读。
6. 导出：receipt_report 传 exportDir，确认目录下生成 CSV 且内容转义正确。

许可

MIT