ride-insights

一个由 [DataHive AI](https://datahive.ai) 开发的隐私优先出行智能技能。

使用此技能从 Gmail 收取拼车账单，本地提取结构化行程数据，并生成丰富的个人洞察，包括支出分析、出行习惯、重复路线、可能的常驻地点、时段模式等。

您还可以将匿名化的数据报告分享给 DataHive AI，参与任务并获得奖励（[任务博客](https://datahive.ai/blog/)）。

本技能采用独特的本地处理方式，展示了 OpenClaw 的真正能力：代理智能在本地处理敏感源数据，确保原始数据不会被外部共享。

仅限本地运行：此技能需要一个回环（loopback）OpenClaw 网关，若网关 URL 指向其他位置则会失败。

当用户希望上传数据至 DataHive 以获取积分时，生成一份匿名化/可共享的 CSV 版本行程记录，避免暴露原始账单邮件或明显个人标识信息。

开始前准备

• 要求 gog CLI 已对目标 Gmail 账户完成认证。
• 在获取邮件前始终运行 gog auth list，即使用户已指定账户。
• 若配置了多个账户，请明确列出真实邮箱地址供选择，例如：应使用哪个账户：(A) name1@example.com 或 (B) name2@example.com？ 不得简化为“默认”或让用户自行推断存在哪些账户。
• 若仅配置了一个账户，则直接使用该账户，并简要说明。
• 不得假设名为 default 的账户一定存在。
• 要求可访问本地 OpenClaw 网关。
• 要求通过 OPENCLAW_GATEWAY_TOKEN 或 ~/.openclaw/openclaw.json 中的 gateway.auth.token（旧版回退路径：gateway.token）提供网关认证令牌。
• 若提取器通过环境变量配置，请仅声明并使用以下三项：OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_URL 和 OPENCLAW_GATEWAY_MODEL。
• 要求启用网关的 HTTP 响应端点。
• 向用户询问日期范围：全部时间、某日期之后，或两个日期之间。
• 将账单邮件视为敏感的财务/位置数据。
• 告知用户：data/ride-insights/emails.json 会本地存储已获取的账单邮件，可能包含完整的 HTML 账单内容。
• 告知用户：提取过程会将每封邮件的原始 JSON 数据包（含账单 HTML 内容时）发送至本地网关的 /v1/responses 端点。
• 在提取前，确认用户是否同意将原始账单邮件 JSON/HTML 发送至当前本地网关支持的模型。
• 始终使用本地回环网关。若配置的网关 URL 非本地地址，应直接报错，不得降级至任何远程或私有主机。
• 描述本地运行保证时，需明确指出仅接受 localhost、127.0.0.1 和 ::1 作为网关主机。

输出结果

主要输出文件：

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

保留说明：

• emails.json 会持续保存原始获取的账单内容，直到用户手动删除。
• rides.json 和 rides.sqlite 会持续保存本地提取的行程数据，直到用户删除。
• 匿名化 CSV 文件有意排除原始账单内容和直接标识符，但仍属于衍生数据集，应视作潜在敏感信息。

处理流程

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

1. 初始化数据库

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

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

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

注意事项：

• 如无需日期筛选，请省略 --after / --before 参数。
• 支持的平台查询规则位于 references/provider_queries.json。
• 当前覆盖的平台包括：Uber、Bolt、Yandex、Lyft、Free Now、Curb 和 Via。
• 默认处理上限为所选时间段内最多 50 封邮件，因网关提取消耗大量 token。
• 提取前，请统计 data/ride-insights/emails.json 中已获取的邮件数量。
• 若获取数量 ≤ 50 封，正常继续。
• 若获取数量 > 50 封，询问用户是否处理全部邮件，或维持默认的 50 封上限。
• 除非用户明确批准更高数量，否则仅处理前 50 封邮件。
• 用户提示应简洁明了，提及限制存在的原因是为了控制 token 使用量/成本。

3. 通过网关 /v1/responses 提取行程数据并写入 rides.json

python3 skills/ride-insights/scripts/extract_rides_gateway.py \
  --emails-json ./data/ride-insights/emails.json \
  --out ./data/ride-insights/rides.json

注意事项：

• 若 ~/.openclaw/openclaw.json 已包含 gateway.auth.token，建议在不导出 OPENCLAW_GATEWAY_TOKEN 的情况下运行提取器。
• 提取器也接受旧版配置项 gateway.token，但推荐使用当前标准路径 gateway.auth.token。
• 提取器还可读取 OPENCLAW_GATEWAY_URL 和 OPENCLAW_GATEWAY_MODEL；这些环境变量应在技能元数据或打包契约中明确声明为依赖项。

• 该脚本逐封邮件进行处理。
• 将原始邮件的 JSON 数据发送至网关的 /v1/responses 接口。
• 对于此敏感数据流，拒绝任何非本地网关主机，并且不提供覆盖选项。
• 预期输出为符合当前骑行数据模式的纯 JSON 格式。
• 失败请求最多重试 3 次。
• 每次成功提取后，将数据写入 data/ride-insights/rides.json，以实现进度检查点记录。
• 如果 data/ride-insights/rides.json 已存在，则跳过其中已包含 gmail_message_id 的邮件。
• 若遇到速率限制问题，可使用 --delay-ms <n> 参数重新运行。
• 默认提取上限为 50 封邮件，除非用户明确批准处理更多邮件。
• 应用默认上限时，按 data/ride-insights/emails.json 中记录的顺序选取邮件，仅提取前 50 封。

4. 将 rides.json 插入 SQLite

python3 skills/ride-insights/scripts/insert_rides_json_sqlite.py \
  --db ./data/ride-insights/rides.sqlite \
  --rides-json ./data/ride-insights/rides.json

5. 生成骑行洞察

请以代理动作形式执行，而非独立的洞察脚本。

推荐工作流程：

• 优先使用 data/ride-insights/rides.json 作为主要数据源，因其直接保留了提取出的骑行对象。
• 使用 data/ride-insights/rides.sqlite 进行轻量级、确定性的统计、筛选、分组和交叉验证。
• 在查询 SQLite 前，通过 PRAGMA table_info(rides) 检查表结构，或查阅 skills/ride-insights/references/schema_rides.sql 文件。
• SQL 查询仅基于从实际数据库或参考文件中确认的字段。
• 将骑行记录与简洁的事实性背景摘要一并输入到当前启用的网关模型中。
• 要求模型生成 8 到 10 条简短的行为洞察。

注意事项：

• 优先关注解释性分析，而非简单聚合。
• 关注如消费习惯、重复地址、可能的常驻地点、重复路线、通勤类行为、工作日/周末规律、时段模式、异常情况以及高端骑行选择等模式。
• 使用 rides.json 获取每条骑行的丰富上下文，使用 rides.sqlite 快速进行事实核查；在需要时结合两者。
• 由 SQL 提供的依据应保持简洁易读，不得转换为原始 SQL 输出。
• 输出内容应简洁且面向人类阅读。
• 不要随意创建标签（如“家”“工作地”），除非重复性极强支持该判断；否则使用更温和的表述，如“可能的基地”“频繁到达地点”或“类似通勤模式”。

6. 导出匿名化 CSV 报告

当用户要求导出匿名化/可共享的骑行报告时，请使用内置的 Python 导出脚本。

python3 skills/ride-insights/scripts/export_anonymized_rides_csv.py \
  --db ./data/ride-insights/rides.sqlite \
  --out ./data/ride-insights/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 分钟的时间保持不变。
• 当可用时，导出标准化后的 distance_km 和 duration_min（从 extracted_ride_json 中读取）；不可用时留空。
• 从 CSV 输出中排除街道地址、支付方式、司机信息、备注、邮件主题、消息 ID 以及任何原始提取的 JSON 内容。
• 当用户请求匿名化 CSV 时，应在工作区中生成真实的 .csv 文件，不得将内容内联粘贴至聊天。
• 将文件保存至稳定路径，如 data/ride-insights/anonymized_rides.csv。
• 若要发送至聊天，请使用 OpenClaw 的外部媒体附件机制：先发送一行简短文字，再另起一行，内容为 MEDIA:./data/ride-insights/anonymized_rides.csv。
• 附带消息应非常简短，例如：

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

紧随其后的是 MEDIA: 行。

• 不得在聊天中内联粘贴 CSV 文本。
• 为确保附件发送清晰，允许并建议保存本地副本。

限制条件

• 仅使用本技能内附的脚本。
• 不得静默切换至直接的提供商 API 或嵌入式代理内部逻辑。
• 不得虚构字段；未知字段使用 null。
• 地址和时间字符串保持原样。
• 用户可见输出应简洁：仅包含计数、路径和失败信息。

参考资料

• 数据库模式：skills/ride-insights/references/schema_rides.sql
• 服务商 Gmail 查询语句：skills/ride-insights/references/provider_queries.json