安装与配置


# 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 后请手动验证：

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

许可

MIT

安装

说明文档

安装与配置

工具

两条识别路径的边界

权限透明

已知限制

手动验证

许可