车辆费用追踪器

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

功能特性

• i18n 支持：通过本地化文件（locales/*.json）提供多种语言支持
• Google Sheets 集成：通过 API 直接写入 Google Sheets
• 本地 Excel 回退机制：若未配置 Spreadsheet ID，则自动保存至本地 .xlsx 文件
• 公制/英制单位系统：可配置单位体系（km/L 或 mi/gal）
• 照片管理：自动保存并按时间戳重命名照片
• 别名支持：支持为车辆设置别名（例如，“my car” → “Toyota Camry 2020”）
• 默认值填充：根据费用类别自动填充数量与单位

🚀 初始化（首次设置）

步骤 1：选择您的语言环境（Locale）

可用的语言环境：

• zh-TW — 繁體中文（台湾）
• en-US — English（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 Service Account（参见 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"
}

使用方法

预览（Dry Run）——请务必首先执行！

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

命令行参数

新增语言环境（Locale）

参考现有语言环境文件，创建 locales/{code}.json。以下字段为必需项：

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

已支持的语言环境