Clawshier

通过四步流水线处理一张收据或发票图像，然后以简短摘要形式回复本次添加的内容。

输入处理

• 若用户提供了图像的本地文件路径，则直接使用该路径。
• 若用户在聊天中发送了图像，且存在本地附件路径，则使用该路径。
• 若图像无可用的本地文件路径，请提示用户重新以文件形式发送，或提供一个您可执行的路径。
• 若用户明确指定了收据日期，请保留该日期，并以 --date YYYY-MM-DD 形式传递给第 3 步。

工作流

运行安全流水线执行器（safe pipeline runner）。若执行失败，最多重试 2 次，之后再将错误暴露给用户。

主路径 — 安全流水线执行器

执行以下命令：

node {baseDir}/scripts/run_pipeline.js --image 

若用户明确提供了日期，则始终以 ISO 格式传入：

node {baseDir}/scripts/run_pipeline.js --image  --date 2026-03-25

该执行器依次完成 OCR → 结构化 → 校验/去重 → 内部存储（使用 JSON 文件，而非经 Shell 插值的流水线字符串）。

它会写入以下位置：

• 月度支出工作表（MM-YY）
• Invoice Archive Breakdown
• Summary

同时，若存在默认的 Sheet1 工作表，也会将其移除。

处理器兼容性说明

各独立处理器仍支持 stdin/stdout 方式用于测试；但在自动化调用本技能时，应优先使用 scripts/run_pipeline.js，或各处理器提供的 --input-file/--output-file 参数，**切勿**将不可信的收据内容或 LLM 输出嵌入 Shell 命令中执行。

若 OCR 判定图像并非收据或发票，请告知用户：

我未能在此图像中识别出收据或发票。能否尝试拍摄一张更清晰的照片再试？

若校验器报告为重复条目，则立即中止并通知用户：

该收据似乎已录入系统（供应商、日期与总金额均匹配现有条目），跳过处理。

成功回复格式

成功执行后，请按如下格式回复：

已添加支出：{vendor} — {total} {currency}，日期 {date}（{category}）。对应电子表格中的第 #{row} 行（工作表 {MM-YY}）。

若用户明确请求追踪（tracing）、调试（debugging）或成本追踪（cost tracing），请附加一份紧凑的分步追踪摘要（基于最近一次记录的追踪文件）。否则请保持成功回复简洁。

失败回复格式

若某一步骤经重试后仍失败，请明确指出失败步骤，并附上原始错误消息。

注意事项

• 请严格使用 {baseDir} 占位符，确保命令不依赖当前工作目录。
• 对于历史发票，请优先使用 --date YYYY-MM-DD 显式指定日期，避免依赖当日日期推断逻辑。
• OCR 后端选择为机器级配置：CLAWSHIER_VISION_PROVIDER=openai|ollama|auto（默认值：openai）。
• auto 模式优先尝试本地 Ollama，失败后回退至 OpenAI；设为 ollama 可强制仅使用本地 OCR。
• 可通过 CLAWSHIER_OLLAMA_MODEL、CLAWSHIER_OLLAMA_HOST 和 CLAWSHIER_OLLAMA_MAX_DIMENSION 控制 Ollama OCR 后端行为。
• 当环境变量中存在 CLAWSHIER_TEST_MODE=1 时，各处理器将使用本地测试数据集（test fixtures）及本地模拟表格存储（mock sheet store）。建议在调用真实 API 前，先启用此模式进行安全冒烟测试（smoke test）。
• 可选追踪功能：设置 CLAWSHIER_TRACE=1 后，系统将记录每一步的耗时与用量元数据至 .clawshier-last-trace.json；仅当用户明确请求 tracing/debugging/cost tracing 时，才在聊天中展示该追踪信息。