ride-receipts-gateway-llm

构建一个骑行账单处理流水线，从 Gmail 收到的账单邮件中提取数据，存入 emails.json 文件，将每封邮件发送至本地 OpenClaw Gateway 的 /v1/responses 接口进行结构化信息抽取，生成 rides.json 数组，并将结果插入 SQLite 数据库。

开始前准备

• 确保已使用 gog CLI 对目标 Gmail 账户完成认证。
• 每次获取邮件前，务必运行 gog auth list，即使用户已指定账户也需执行。
• 若配置了多个账户，必须明确列出真实邮箱地址供用户选择，例如：请选择要使用的账户：(A) name1@example.com 或 (B) name2@example.com？ 不得简化为“默认”或让用户自行推断账户存在情况。
• 若仅配置了一个账户，则直接使用该账户，并简要说明。
• 不得假设名为 default 的账户一定存在。
• 确保本地 OpenClaw Gateway 可访问。
• 确保可通过 OPENCLAW_GATEWAY_TOKEN 环境变量或 ~/.openclaw/openclaw.json 文件获取 Gateway 认证令牌。
• 确保 Gateway 的 HTTP Responses 接口已启用。
• 向用户询问时间范围：全部历史、某日期之后，或两个日期之间。
• 将账单邮件视为敏感的财务/位置数据。
• 告知用户：emails.json 会本地存储已获取的账单邮件，可能包含完整的 HTML 账单内容。
• 在开始抽取前，确认用户同意将原始账单邮件 JSON/HTML 发送至当前本地私有 Gateway 托管的模型。
• 优先使用回环（loopback）或私有 Gateway 目标。仅在用户明确接受数据外流的情况下，才使用非本地 Gateway。

输出产物

主要输出文件：

• data/gateway-llm/emails.json —— 所有获取的账单邮件，以 JSON 数组形式存储；可能包含完整 HTML 内容
• data/gateway-llm/rides.json —— 提取后的骑行记录，以 JSON 数组形式存储
• data/gateway-llm/rides.sqlite —— 可查询的 SQLite 数据库，包含标准化的骑行字段及 extracted_ride_json，但不保留原始邮件 JSON

流水线流程

按顺序执行每一步，任一环节失败则停止并报告错误。

总结与查询建议

• 在总结 SQLite 输出时，不得猜测字段名称。
• 首先通过 PRAGMA table_info(rides) 检查实际表结构，或查阅 references/schema_rides.sql。
• SQL 查询仅基于从实时数据库模式中确认的列名。
• 若实际模式与预期字段不符，应调整查询以匹配真实结构，而非强行使用旧字段名。
• 优先使用在模式中明确存在的稳定维度，如 provider、email_date_text、currency、amount、pickup_city 和 dropoff_city。

1. 初始化数据库

python3 skills/ride-receipts-gateway-llm/scripts/init_db.py \
  --db ./data/gateway-llm/rides.sqlite \
  --schema skills/ride-receipts-gateway-llm/references/schema_rides.sql

2. 从 Gmail 获取账单邮件并保存至 emails.json

python3 skills/ride-receipts-gateway-llm/scripts/fetch_emails_json.py \
  --account <gmail-account> \
  --after YYYY-MM-DD \
  --before YYYY-MM-DD \
  --max-per-provider 5000 \
  --out ./data/gateway-llm/emails.json

说明：

• 如无需时间筛选，可省略 --after / --before 参数。
• 支持的平台查询规则位于 references/provider_queries.json。
• 当前支持的平台包括：Uber、Bolt、Yandex、Lyft、Free Now、Curb 和 Via。

3. 使用 Gateway /v1/responses 接口提取骑行信息至 rides.json

OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789 \
OPENCLAW_GATEWAY_TOKEN=... \
python3 skills/ride-receipts-gateway-llm/scripts/extract_rides_gateway.py \
  --emails-json ./data/gateway-llm/emails.json \
  --out ./data/gateway-llm/rides.json

说明：

• 该脚本逐封邮件处理。
• 将原始邮件 JSON 发送到 Gateway 的 /v1/responses 接口。
• 默认情况下拒绝非本地 Gateway 主机用于此类敏感数据传输；若用户明确信任目标，可通过设置 OPENCLAW_ALLOW_NONLOCAL_GATEWAY=1 强制启用。
• 脚本期望返回符合当前骑行数据模式的纯 JSON 格式。
• 失败请求最多重试 3 次。
• 每次成功提取后即写入 rides.json，实现进度检查点。
• 若 rides.json 已存在，将跳过 gmail_message_id 已存在于其中的邮件。
• 若遇到速率限制，可重新运行并添加 --delay-ms <n> 参数增加延迟。

4. 将 rides.json 插入 SQLite 数据库

python3 skills/ride-receipts-gateway-llm/scripts/insert_rides_json_sqlite.py \
  --db ./data/gateway-llm/rides.sqlite \
  --rides-json ./data/gateway-llm/rides.json

5. 从 SQLite 生成基于模式的摘要报告

python3 skills/ride-receipts-gateway-llm/scripts/summary_rides_sqlite.py \
  --db ./data/gateway-llm/rides.sqlite

说明：

• 该脚本首先检查 rides 表的实时模式。
• 动态选择可用的时间/金额字段，而非依赖固定的模式版本。
• 建议使用此脚本生成按服务商/月份/货币/城市等维度的汇总，避免因字段名不一致导致问题。

6. 生成简短的骑行洞察

此步骤应作为代理动作执行，而非独立的洞察脚本。

推荐工作流：

• 当 data/gateway-llm/rides.json 可用时，直接读取以保留提取后的骑行对象。
• 可选地查询 data/gateway-llm/rides.sqlite 获取少量基础统计，但不要输出原始 SQL 结果。
• 将骑行记录与简洁的事实摘要输入当前活跃的 Gateway 托管模型。
• 请求模型生成 8 到 10 条简短的行为洞察。

7. 导出匿名化 CSV 报告

当用户要求提供匿名化或可共享的乘车报告时，请使用内置的 Python 导出脚本。

python3 skills/ride-receipts-gateway-llm/scripts/export_anonymized_rides_csv.py \
  --db ./data/gateway-llm/rides.sqlite \
  --out ./data/gateway-llm/anonymized_rides.csv

导出规则：

• 仅从 SQLite 数据库读取数据。
• 仅包含以下列：provider, email_month, start_time_15m, end_time_15m, currency, amount, distance_km, duration_min, pickup_city, pickup_country, dropoff_city, dropoff_country。
• 将 email_date_text 转换为仅保留月份的格式，如 2025-05。
• 将 start_time_text 和 end_time_text 向上舍入至最近的 15 分钟时段；恰好在整点 15 分钟的时间保持不变。
• 若存在 extracted_ride_json 中的标准化数据，导出 distance_km 和 duration_min；若缺失则留空。
• 不包含街道地址、支付方式、司机信息、备注、主题、消息 ID 以及任何原始提取的 JSON 内容。
• 当用户请求匿名化 CSV 时，应在工作区中生成一个真实的 .csv 文件，不要将 CSV 文本直接粘贴到聊天中。
• 将文件保存至稳定路径，例如 data/gateway-llm/anonymized_rides.csv。
• 若要发送至聊天，请使用 OpenClaw 的外部媒体附件机制：先写一句简短说明，再另起一行，内容为 MEDIA:./data/gateway-llm/anonymized_rides.csv。
• 附带的消息应尽量简洁，例如：

Done — I regenerated the anonymized CSV and attached the updated file.

然后是单独一行的 MEDIA: 指令。

• 禁止在聊天中直接粘贴 CSV 内容。
• 本地保存副本是允许且推荐的，以便干净地发送附件。

限制条件

• 仅使用本技能内附的脚本。
• 不得擅自切换至直接的平台 API 或嵌入式代理内部逻辑。
• 绝不虚构字段；未知字段使用 null 表示。
• 地址和时间字符串保持原样输出。
• 用户可见输出应简洁：仅包含数量、路径和失败情况。

参考资料

• 数据库模式：skills/ride-receipts-gateway-llm/references/schema_rides.sql
• 平台 Gmail 查询模板：skills/ride-receipts-gateway-llm/references/provider_queries.json