名称： vehicle-tracker
描述： 在 Google Sheets 中记录车辆费用（加油、保养、零件），并保存相关照片。支持里程、费用、类别和照片管理。

车辆费用追踪器

一款多语言车辆费用追踪工具，支持 Google Sheets 和本地 Excel 文件。

功能特性

• 多语言支持：通过区域设置文件 (locales/*.json) 支持多种语言
• Google Sheets 集成：通过 API 直接写入 Google Sheets
• 本地 Excel 备用方案：若未配置 Spreadsheet ID，则保存到本地 .xlsx 文件
• 公制/英制单位：可配置单位系统（公里/升 vs 英里/加仑）
• 照片管理：自动保存照片并按时间戳重命名
• 别名功能：支持车辆别名（例如，"我的车" → "Toyota Camry 2020"）
• 默认值：根据类别自动填充数量和单位

🚀 初始化（首次设置）

步骤 1：选择区域设置

可用区域设置：
- zh-TW - 繁體中文 (台湾)
- en-US - 英文 (美国)
- ja-JP - 日本語

步骤 2：创建 config.json

复制下方模板并保存为 skills/vehicle-tracker/config.json：

{
  "locale": "en-US",
  "unit_system": "metric",
  "vehicles": {},
  "aliases": {},
  "default_vehicle": null,
  "category_defaults": {}
}

步骤 3：从区域设置文件复制类别默认值

根据您选择的区域设置和单位系统，复制相应的类别默认值。

英文 (公制)：

{
  "category_defaults": {
    "Gas": { "unit": "liter" },
    "Accessory": { "unit": "pc", "quantity": 1 },
    "Repair": { "unit": "job", "quantity": 1 },
    "Maintenance": { "unit": "service", "quantity": 1 },
    "Purchase": { "unit": "unit", "quantity": 1 }
  }
}

英文 (英制)：

{
  "category_defaults": {
    "Gas": { "unit": "gallon" },
    "Accessory": { "unit": "pc", "quantity": 1 },
    "Repair": { "unit": "job", "quantity": 1 },
    "Maintenance": { "unit": "service", "quantity": 1 },
    "Purchase": { "unit": "unit", "quantity": 1 }
  }
}

繁體中文 (公制)：

{
  "category_defaults": {
    "加油": { "unit": "公升" },
    "周邊": { "unit": "個", "quantity": 1 },
    "維修": { "unit": "件", "quantity": 1 },
    "保養": { "unit": "次", "quantity": 1 },
    "買車": { "unit": "輛", "quantity": 1 }
  }
}

日本語 (公制)：

{
  "category_defaults": {
    "給油": { "unit": "リットル" },
    "アクセサリー": { "unit": "個", "quantity": 1 },
    "修理": { "unit": "件", "quantity": 1 },
    "メンテナンス": { "unit": "回", "quantity": 1 },
    "購入": { "unit": "台", "quantity": 1 }
  }
}

步骤 4：添加您的车辆

选项 A：Google Sheets (推荐用于云端同步)

1. 创建一个 Google 电子表格
2. 与 Google 服务账号共享（请参考 google-workspace 技能）
3. 将 Spreadsheet ID 添加到配置中：

{
  "vehicles": {
    "My Car 2020": "1ABC123...xyz"
  },
  "default_vehicle": "My Car 2020"
}

选项 B：本地 Excel (无需额外设置)

只需添加车辆名称，无需 ID：

{
  "vehicles": {
    "My Car 2020": null
  },
  "default_vehicle": "My Car 2020"
}

文件将保存到 ~/vehicle_tracker/My_Car_2020.xlsx。

步骤 5：添加别名（可选）

{
  "aliases": {
    "car": "My Car 2020",
    "toyota": "My Car 2020"
  }
}

步骤 6：自定义路径（可选）

覆盖默认目录：

{
  "photo_base_dir": "/path/to/photos",
  "local_excel_dir": "/path/to/excel/files",
  "sheet_name": "Expenses"
}

默认路径：~/vehicle_tracker

完整的 config.json 示例

{
  "locale": "en-US",
  "unit_system": "imperial",
  "vehicles": {
    "Toyota Camry 2020": "1ABC123...spreadsheet_id",
    "Honda Civic 2018": null
  },
  "aliases": {
    "camry": "Toyota Camry 2020",
    "civic": "Honda Civic 2018",
    "car": "Toyota Camry 2020"
  },
  "default_vehicle": "Toyota Camry 2020",
  "category_defaults": {
    "Gas": { "unit": "gallon" },
    "Accessory": { "unit": "pc", "quantity": 1 },
    "Repair": { "unit": "job", "quantity": 1 },
    "Maintenance": { "unit": "service", "quantity": 1 },
    "Purchase": { "unit": "unit", "quantity": 1 }
  },
  "photo_base_dir": "~/vehicle_tracker",
  "local_excel_dir": "~/vehicle_tracker"
}

使用方法

预览（试运行）- 务必先执行此步骤！

python3 skills/vehicle-tracker/tracker.py \
  --vehicle "camry" \
  --mileage 15000 \
  --category "Gas" \
  --cost 45.50 \
  --quantity 12.5 \
  --dry-run

执行（用户确认后）

python3 skills/vehicle-tracker/tracker.py \
  --vehicle "camry" \
  --mileage 15000 \
  --category "Gas" \
  --cost 45.50 \
  --quantity 12.5

附带照片

python3 skills/vehicle-tracker/tracker.py \
  --vehicle "camry" \
  --mileage 15200 \
  --category "Maintenance" \
  --cost 89.99 \
  --description "Oil change" \
  --photos "/path/to/receipt.jpg" \
  --dry-run

参数说明

添加新的区域设置

基于现有区域设置文件创建 locales/{code}.json。必需字段：

• language_name
• sheet_name
• columns_metric / columns_imperial
• photo_prefix
• messages
• units_metric / units_imperial
• default_units_metric / default_units_imperial

支持的区域设置