介绍
# Mechanic — Vehicle Maintenance Tracker
追踪任意组合车辆的里程和保养间隔 —— 包括卡车、轿车、摩托车、房车、越野车、全地形车（ATV）、船只等。可解码 VIN（车辆识别代号）以自动填充车辆规格，查询制造商推荐的保养计划，记录保养历史，估算费用，监控召回，追踪燃油经济性，管理保修，并主动提醒即将到期和逾期的保养服务。
## 数据存储
所有用户数据位于 `<workspace>/data/mechanic/` 中：
| 文件 | 用途 | |------|---------| | `state.json` | 所有车辆：当前里程/工时、历史记录、保养记录、燃油日志、保修、服务商、紧急信息 | | `<key>-schedule.json` | 单车保养计划，包含间隔和成本估算 |
**约定：** 技能逻辑位于 `<skill>/`，用户数据位于 `<workspace>/data/mechanic/`。这保证了在技能更新或重新安装时数据的安全。
## 首次设置
如果 `<workspace>/data/mechanic/state.json` 不存在： 1. 创建 `<workspace>/data/mechanic/` 目录 2. 询问用户想要追踪哪些车辆 3. 对于每辆车，运行 **添加新车** 工作流（包括为每辆车选择登记频率） 4. 创建包含车辆条目的 `state.json` 5. 设置 cron 任务（参见 **里程检查设置**）
### 状态文件结构 ```json { "settings": { "check_in_tz": "America/Phoenix" }, "providers": [ { "id": "jims_diesel", "name": "Jim's Diesel Repair", "location": "123 Main St, Mesa, AZ", "phone": "480-555-1234", "specialties": ["diesel", "trucks"], "rating": 5, "notes": "Great with Power Stroke engines" } ], "vehicles": { "f350": { "label": "2021 Ford F-350 6.7L Power Stroke", "schedule_file": "f350-schedule.json", "check_in_frequency": "monthly", "current_miles": 61450, "last_updated": "2026-01-26", "last_check_in": "2026-01-26", "vin": "1FT8W3BT0MED12345", "vin_data": { "decoded": true, "decoded_date": "2026-01-26", "year": 2021, "make": "Ford", "model": "F-350", "trim": "Lariat", "body_class": "Pickup", "drive_type": "4WD", "engine": "6.7L Power Stroke V8 Turbo Diesel", "displacement_l": 6.7, "cylinders": 8, "fuel_type": "Diesel", "transmission": "10-Speed Automatic", "doors": 4, "gvwr_class": "Class 3", "bed_length": "8 ft", "wheel_base": "176 in", "plant_country": "United States", "plant_city": "Louisville", "raw_response": {} }, "business_use": false, "business_use_percent": 0, "mileage_history": [ {"date": "2026-01-26", "miles": 61450, "source": "user_reported"} ], "service_history": [ { "service_id": "oil_filter", "date": "2025-11-15", "miles": 58000, "hours": null, "notes": "Full synthetic Motorcraft FL-2051S", "actual_cost": 125.00, "provider": { "id": "jims_diesel", "name": "Jim's Diesel Repair", "parts_warranty_months": 12, "labor_warranty_months": 6 } } ], "fuel_history": [ { "date": "2026-01-20", "gallons": 32.5, "cost": 108.55, "odometer": 61300, "mpg": 14.2, "notes": "Regular fill-up" } ], "warranties": [ { "type": "factory_powertrain", "provider": "Ford", "start_date": "2021-03-15", "end_date": "2026-03-15", "start_miles": 0, "end_miles": 60000, "coverage_details": "Engine, transmission, drivetrain components", "status": "active" } ], "recalls": { "last_checked": "2026-01-26", "open_recalls": [], "completed_recalls": [] }, "emergency_info": { "vin": "1FT8W3BT0MED12345", "insurance_provider": "State Farm", "policy_number": "SF-123456789", "roadside_assistance_phone": "1-800-555-1234", "tire_size_front": "275/70R18", "tire_size_rear": "275/70R18", "tire_pressure_front_psi": 65, "tire_pressure_rear_psi": 80, "oil_type": "15W-40 CK-4 Full Synthetic", "oil_capacity": "15 quarts", "coolant_type": "Motorcraft Orange VC-3DIL-B", "def_type": "API certified DEF", "tow_rating_lbs": 20000, "gvwr_lbs": 14000, "gcwr_lbs": 37000, "key_fob_battery": "CR2450", "fuel_type": "Diesel (Ultra Low Sulfur)", "fuel_tank_gallons": 48, "notes": "" } } }, "last_service_review": "2026-01-26" } ```
**顶层字段：** - `settings` — 全局设置（时区等） - `providers` — 可复用的服务商列表 - `vehicles` — 以短代码为键（例如 `f350`、`rv`、`crf450`） - `last_service_review` — 上次全面审查的日期
**每车字段：** - `label` — 人类可读的车辆名称 - `schedule_file` — 保养计划 JSON 的路径 - `check_in_frequency` — 询问里程的频率（每周/每两周/每月/每季度） - `current_miles` / `current_hours` — 最新的读数 - `last_updated` / `last_check_in` — 日期追踪 - `vin` — 车辆识别代号（用于召回、VIN 解码和紧急信息） - `vin_data` — 来自 NHTSA VPIC API 的解码 VIN 数据（规格、发动机、变速箱等） - `business_use` — 车辆是否用于商业用途（布尔值） - `business_use_percent` — 商业使用百分比 (0-100) - `mileage_history` — 按时间顺序排列的里程/工时条目数组 - `service_history` — 按时间顺序排列的已完成保养服务数组（包含可选的 `actual_cost` 和 `provider`） - `fuel_history` — 按时间顺序排列的加油记录数组 - `warranties` — 保修记录数组 - `recalls` — 召回监控状态（上次检查时间、开启/已完成） - `emergency_info` — 快速参考的车辆规格和紧急联系人
## 读取状态
在技能加载时，读取： 1. `<workspace>/data/mechanic/state.json` — 所有车辆的当前状态 2. 相关的 `<key>-schedule.json` 文件，取决于当前讨论的内容
## 添加新车
当用户想要追踪一辆新车时：
### 1. 收集车辆信息 **首先询问 VIN。** 如果用户提供了 VIN，请运行 **VIN 解码**（见下文）以自动填充年份、品牌、型号、发动机、变速箱、驱动类型和其他规格。这可以节省用户回答你可以自动查找的问题的时间。
询问： - **VIN**（强烈推荐 —— 自动填充规格，启用召回监控，紧急信息） - **年份、品牌、型号**（仅在未提供 VIN 时询问） - **发动机/配置**（仅在未提供 VIN 或 VIN 解码不完整时询问） - **使用模式** — 每日通勤、拖拽、越野、周末玩具等 - **当前里程/工时** - **商业用途？** — 如果是，占多大百分比？（启用税收扣除追踪） - **保修信息** — 是否有任何有效的原厂或延长保修？到期日期/里程？ - **紧急信息** — 保险公司、道路救援号码、轮胎尺寸（可以稍后填写）
如果用户手头没有 VIN，请继续手动收集信息并注明稍后可以添加 VIN 以解锁自动填充和召回监控功能。
### 2. 确定负载等级
询问使用情况以对保养计划进行分类：
| 用途 | 负载等级 | 影响 | |-------|-----------|--------| | 正常通勤 | 正常 | 标准间隔 | | 拖拽、重载 | 严苛 | 缩短间隔（通常为正常间隔的 50-75%） | 越野、多尘环境 | 严苛 | 缩短间隔，更频繁更换滤芯 | | 极端温度（炎热沙漠、严寒） | 严苛 | 缩短间隔，注意液体/电池问题 | | 赛道/赛车 | 严苛+ | 激进的间隔，专用液体 | | 轻度使用、车库停放 | 正常 | 标准间隔，但注意基于时间的保养项目 |
大多数制造商都会发布“正常”和“严苛/特殊条件”两种保养计划。请使用匹配的那一种。
### 3. 选择登记频率
询问他们希望多久被询问一次该车辆的里程/工时：
| 频率 | 最适用于 | |-----------|----------| | **每周** | 越野车、赛车、商业/车队、高里程日常通勤车 | | **每两周** | 活跃的骑手/驾驶员、保养间隔短的车辆 | | **每月** | 大多数轿车和卡车（推荐的默认值） | | **每季度** | 季节性车辆、低里程、车库收藏车、存放的船只 |
根据车辆类型和使用模式建议频率，但允许用户覆盖。
### 4. 查询保养计划
**查找该特定年份/品牌/型号/发动机的制造商推荐保养间隔：** - 使用网络搜索查找官方保养计划 - 查阅车主手册中的间隔 - 参考爱好者论坛以获取实际建议 - 考虑步骤 2 中的负载等级
### 5. 构建计划文件
创建 `<workspace>/data/mechanic/<key>-schedule.json`：
```json { "vehicle": { "year": 2021, "make": "Ford", "model": "F-350", "type": "truck", "engine": "6.7L Power Stroke V8 Turbo Diesel", "transmission": "10R140 10-Speed Automatic", "duty": "severe", "notes": "Tows fifth wheel RV" }, "services": [ { "id": "oil_filter", "name": "Engine Oil & Filter Change", "interval_miles": 7500, "interval_months": 6, "details": "Specific oil type, filter part number, capacity, and any special instructions.", "priority": "critical", "cost_diy": "$XX-XX", "cost_shop": "$XX-XX", "cost_dealer": "$XX-XX", "cost_note": "Optional note about related expensive repairs" } ] } ```
**每个保养项目必需的字段：** - `id` — 唯一的 snake_case 标识符 - `name` — 人类可读的名称 - 至少一个间隔：`interval_miles`、`interval_months`、`interval_hours` 或 `interval_rides` - `details` — 具体零件、液体、容量和任何警告 - `priority` — `critical`（关键）、`high`（高）、`medium`（中）或 `low`（低） - `cost_diy`、`cost_shop`、`cost_dealer` — 预估成本范围
**研究成本：** - 搜索该特定车辆每项服务的典型成本 - DIY = 仅零件成本 - Shop = 独立维修厂 - Dealer = 制造商经销商 - 为那些故障/维修成本远高于保养成本的项目添加 `cost_note`
### 6. 添加到状态
将车辆添加到 `state.json` 的 `vehicles` 对象下：
```json { "<key>": { "label": "2021 Ford F-350 6.7L Power Stroke", "schedule_file": "<key>-schedule.json", "check_in_frequency": "monthly", "current_miles": 61450, "current_hours": null, "last_updated": "2026-01-26", "last_check_in": "2026-01-26", "vin": null, "vin_data": { "decoded": false }, "business_use": false, "business_use_percent": 0, "mileage_history": [ {"date": "2026-01-26", "miles": 61450, "source": "user_reported"} ], "service_history": [], "fuel_history": [], "warranties": [], "recalls": { "last_checked": null, "open_recalls": [], "completed_recalls": [] }, "emergency_info": { "vin": null, "insurance_provider": null, "policy_number": null, "roadside_assistance_phone": null, "tire_size_front": null, "tire_size_rear": null, "tire_pressure_front_psi": null, "tire_pressure_rear_psi": null, "oil_type": null, "oil_capacity": null, "coolant_type": null, "tow_rating_lbs": null, "gvwr_lbs": null, "key_fob_battery": null, "fuel_type": null, "fuel_tank_gallons": null, "notes": "" } } } ```
**键命名：** 使用简短、易记的代码 — `f350`、`civic`、`r1`、`rv`、`crf450`、`harley`、`bass_boat` 等。
### 7. 更新 Cron 任务
更新 cron 任务提示以包含新车。如果该车辆的频率高于当前的 cron 计划，请更新 cron 以更高频率触发。
### 8. VIN 解码与自动填充
如果提供了 VIN，请运行 **VIN 解码** 以自动填充车辆规格、紧急信息字段和计划文件的车辆部分。向用户展示解码后的信息以供确认。
### 9. 运行初始召回检查
如果提供了 VIN，请立即检查是否有未决召回（参见 **NHTSA 召回监控**）。如果没有 VIN，则按品牌/型号/年份检查。
## 车辆类型和特殊注意事项
| 类型 | 追踪单位 | 主要保养项目 | |------|-------|----------------------| | **轿车** | 英里 | 机油、滤芯、刹车、轮胎、变速箱、冷却液 | | **卡车** | 英里 | 同轿车 + 差速器油、分动箱（4WD）、如拖拽则刹车磨损更重 | | **摩托车** | 英里 | 机油、链条/链轮、气门间隙、减震油、刹车油、冷却液（水冷）、轮胎（磨损更快） | | **越野车** | 工时 + 次数 | 空气滤芯（每次骑行！）、机油（非常频繁）、气门间隙、减震保养、链条、冷却液 | | **ATV/UTV** | 工时 + 英里 | 类似越野车 + 万向节防尘套、皮带（CVT）、绞盘保养 | | **房车/拖车** | 英里 + 月份 | 屋顶/密封胶检查、扩展舱、轮毂轴承、电刹车、轮胎（基于年限）、水系统、发电机、冬季化 | | **船只** | 工时 | 机油、水泵叶轮、下机舱油、锌/牺牲阳极、冬季化、拖车轴承 | | **第五轮/拖车** | 英里 + 月份 | 无发动机，但包括：轴承、刹车、轮胎、屋顶、密封、扩展舱、水管、液化气、季节性准备 |
### 间隔类型
保养服务可以使用任意组合： - `interval_miles` — 基于里程表 - `interval_hours` — 发动机/使用工时（发电机、越野车、船只） - `interval_months` — 基于时间（所有东西都会随老化） - `interval_rides` — 按使用次数（例如越野车空气滤芯 = 每次骑行）
**无论哪个间隔先达到，都会触发保养。**
---
## VIN 解码与自动填充
当用户提供 VIN 时（在车辆设置期间或之后），使用免费的 NHTSA VPIC API 对其进行解码，以自动查找并存储车辆规格。
### NHTSA VPIC API (VIN 解码器)
**端点：** `https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/{VIN}?format=json`
无需 API 密钥。免费且无限制。
**示例：** ``` GET https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/1FT8W3BT0MED12345?format=json ```
### 需提取的关键字段
API 返回一个 `Results` 数组，其中包含一个约 140+ 个字段的对象。提取并映射这些字段：
| VPIC 字段 | 映射到 | 备注 | |------------|---------|-------| | `ModelYear` | `vin_data.year` | 车辆年份 | | `Make` | `vin_data.make` | 制造商 | | `Model` | `vin_data.model` | 车型名称 | | `Trim` | `vin_data.trim` | 配置级别 (Lariat, XLT 等) | | `BodyClass` | `vin_data.body_class` | 皮卡、SUV、摩托车等 | | `DriveType` | `vin_data.drive_type` | 4WD, AWD, RWD, FWD | | `DisplacementL` | `vin_data.displacement_l` | 发动机排量（升） | | `EngineCylinders` | `vin_data.cylinders` | 气缸数 | | `FuelTypePrimary` | `vin_data.fuel_type` | 汽油、柴油、电动等 | | `EngineModel` | `vin_data.engine` | 结合排量用于标签 | | `TransmissionStyle` | `vin_data.transmission` | 自动、手动、CVT | | `TransmissionSpeeds` | (附加到 transmission) | “10速自动” | | `Doors` | `vin_data.doors` | 车门数 | | `GVWR` | `vin_data.gvwr_class` | 车辆总重评级等级 | | `WheelBaseShort` | `vin_data.wheel_base` | 轴距（英寸） | | `BedLengthIN` | `vin_data.bed_length` | 货箱长度（如适用） | | `PlantCountry` | `vin_data.plant_country` | 组装国家 | | `PlantCity` | `vin_data.plant_city` | 组装城市 |
**注意：** 如果不适用，许多字段会返回空字符串 `""`。仅存储非空值。
### VIN 数据存储
将解码后的数据存储在 `state.json` 中车辆的 `vin_data` 对象里：
```json { "vin_data": { "decoded": true, "decoded_date": "2026-01-27", "year": 2021, "make": "Ford", "model": "F-350", "trim": "Lariat", "body_class": "Pickup", "drive_type": "4WD", "engine": "6.7L Power Stroke V8 Turbo Diesel", "displacement_l": 6.7, "cylinders": 8, "fuel_type": "Diesel", "transmission": "10-Speed Automatic", "doors": 4, "gvwr_class": "Class 3", "bed_length": "8 ft", "wheel_base": "176 in", "plant_country": "United States", "plant_city": "Louisville", "raw_response": {} } } ```
将 `raw_response` 存储为完整的 VPIC 结果对象以供参考——它包含可能以后有用的额外字段（例如 `AirBagLocFront`、`SeatBeltsAll`、`TPMS`、`ActiveSafetySysNote` 等）。
如果 `vin_data.decoded` 为 `false` 或缺失，则表示尚未解码 VIN。
### 自动填充工作流
当 VIN 被解码时：
1. **更新 `vin_data`** —— 存储所有解码字段 2. **更新 `label`** —— 根据解码的年份/制造商/车型/发动机构建（例如 “2021 Ford F-350 6.7L Power Stroke”） 3. **更新 `emergency_info`** —— 自动填充可推导的字段： - `fuel_type` 来自 `FuelTypePrimary` - `gvwr_lbs` 来自 `GVWR`（解析重量等级以估算磅数） 4. **更新计划文件** —— 用解码的规格填充 `vehicle` 部分 5. **呈现给用户** —— 显示解码的内容，确认准确性，并询问 VIN 无法告知的任何信息（使用模式、负荷水平、保险等）
### 解码时机
| 触发条件 | 操作 | |---------|--------| | 添加带有 VIN 的新车辆 | 立即解码，自动填充 | | 用户提供现有车辆的 VIN | 解码，回填 `vin_data` 和任何空字段 | | 用户说“查询我的 VIN” | 解码并显示规格 | | 用户更改/更正 VIN | 重新解码并更新 |
### 稍后添加 VIN
如果在添加车辆时未提供 VIN，且用户后来提供了： 1. 解码 VIN 2. 存储在 `vin_data` 中 3. 更新 `vin` 字段 4. 回填任何空的 `emergency_info` 字段 5. 如果解码信息更具体，则更新 `label` 6. 使用新的 VIN 立即运行召回检查 7. 确认更新内容
### VIN 解码呈现格式
向用户呈现解码的 VIN 数据时： ``` 🔍 VIN Decoded — [VIN] ━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 Vehicle Year: [year] | Make: [make] | Model: [model] Trim: [trim] | Body: [body_class] Drive: [drive_type] | Doors: [doors]
🔧 Powertrain Engine: [engine] ([displacement]L, [cylinders] cyl) Fuel: [fuel_type] Transmission: [transmission]
📏 Specs GVWR: [gvwr_class] Wheel Base: [wheel_base] Bed Length: [bed_length] (if truck)
🏭 Built in [plant_city], [plant_country] ━━━━━━━━━━━━━━━━━━━━━━━━━━━ ```
### 局限性 - **VPIC 是 NHTSA 数据** —— 最适用于美国市场车辆。进口/外国市场 VIN 的数据可能不完整。 - **拖车和房车** —— 由于拖车、第五轮拖车和房车由不同的制造商生产且 VIN 编码各异，VIN 解码可能返回有限的数据。 - **摩托车和动力运动** —— 覆盖范围各异。日本品牌（Honda, Yamaha, Kawasaki, Suzuki）通常解码良好。较小的制造商可能不行。 - **1981 年前的车辆** —— VIN 直到 1981 年才标准化。较旧的 VIN 无法解码。 - 如果解码返回的数据稀疏，则回退到手动输入和网上搜索规格。
---
## NHTSA 召回监控
使用免费的 NHTSA API（无需 API 密钥）监控所有跟踪车辆的未决召回。
### API 端点 - **按制造商/车型/年份：** `https://api.nhtsa.dot.gov/recalls/recallsByVehicle?make=Ford&model=F-350&modelYear=2021` - **按 VIN（更精确）：** `https://api.nhtsa.dot.gov/recalls/recallsByVin?vin=XXXXX`
如果存储了 VIN，则优先使用基于 VIN 的查找。否则回退到制造商/车型/年份。
### 召回数据存储 state.json 中每辆车： ```json { "recalls": { "last_checked": "2026-01-26", "open_recalls": [ { "nhtsa_id": "26V-123", "component": "FUEL SYSTEM", "summary": "Fuel line may crack under pressure", "consequence": "Fuel leak, fire risk", "remedy": "Dealer will replace fuel line at no cost", "date_reported": "2025-12-01", "status": "open" } ], "completed_recalls": [ { "nhtsa_id": "24V-456", "component": "ELECTRICAL", "summary": "Battery cable may corrode", "date_completed": "2025-06-15", "notes": "Done at dealer" } ] } } ```
### 检查时机 - **每月定时任务：** 将召回检查包含在里程检查定时任务中。无论车辆的检查频率如何，每月检查所有车辆的召回情况。 - **添加车辆时：** 添加新车辆时立即检查。 - **按需：** 用户询问“我的卡车有召回吗？”
### 召回报告格式 包含在服务审查输出中： ``` ⚠️ OPEN RECALLS - [NHTSA ID] — [Component]: [Summary] Remedy: [What the dealer will do] ⚡ Contact your dealer to schedule this recall service (free) ```
当用户报告完成召回时，将其从 `open_recalls` 移至 `completed_recalls`，并附上完成日期。
---
## 燃油 / MPG 跟踪
记录加油情况以监控燃油经济性、尽早检测机械问题并跟踪燃油支出。
### 记录加油
当用户说“加满油”、“加了汽油/柴油”或报告加油时： 1. 捕获：**日期**、**加仑数**、**成本**（总价或每加仑价格）、**里程表读数** 2. 计算 MPG：`(current_odometer - previous_odometer) / gallons` 3. 附加到车辆的 `fuel_history` 数组 4. 检查 MPG 异常
### 燃油历史记录条目 ```json { "date": "2026-01-20", "gallons": 32.5, "cost": 108.55, "price_per_gallon": 3.34, "odometer": 61300, "mpg": 14.2, "partial_fill": false, "notes": "" } ```
### MPG 计算 - **每次加油 MPG：** `(current_odometer - previous_fill_odometer) / gallons`（如果上次是部分加油则跳过） - **滚动平均值：** 最近 10 次加油的平均值（如果少于 10 次则取全部） - **趋势：** 比较最近 3 次加油与滚动平均值
### 异常检测
如果某次加油的 MPG **比滚动平均值低 15% 以上**，则标记它： ``` ⚠️ MPG Alert — [Vehicle] Last fill-up: 10.5 MPG (your average is 14.2 MPG) 26% below your rolling average — this could indicate: - Tire pressure issues - Air filter needs replacement - Fuel system issue - Change in driving conditions (heavy towing, headwinds) - Mechanical problem developing
Check tire pressures first, then review recent driving conditions. ```
### 燃油报告格式
当被问及“我的燃油经济性如何？”或“MPG 报告”时： ``` ⛽ Fuel Report — [Vehicle] Last fill-up: [X] MPG on [date] Rolling average: [X] MPG (last 10 fills) Trend: [improving/stable/declining] Total fuel cost (YTD): $[X] Total gallons (YTD): [X] Average cost per gallon: $[X] ```
### 部分加油
如果用户没有完全加满油，请标记 `partial_fill: true`。跳过该条目进行 MPG 计算（数学计算不准确），但仍跟踪成本和加仑数。
---
## 实际成本跟踪
跟踪用户在维护上实际支付的金额，以建立准确的支出记录。
### 捕获成本
当用户记录已完成的维护服务时： 1. 确认服务详细信息后，询问：**“你最终付了多少钱？”**（如果他们主动提供，则接受） 2. 作为 `actual_cost` 存储在 service_history 条目中 3. 如果他们不知道或不想分享，请将其保留为 null —— 不要阻止记录
### 服务历史记录条目（包含成本） ```json { "service_id": "oil_filter", "date": "2025-11-15", "miles": 58000, "hours": null, "notes": "Full synthetic, Motorcraft filter", "actual_cost": 125.00, "cost_type": "shop", "provider": { "id": "jims_diesel", "name": "Jim's Diesel Repair" } } ```
`cost_type` 值：`diy`、`shop`、`dealer`、`warranty`、`recall`（免费）
### 支出分析
跟踪并按要求报告： - **每年每辆车：** “你今年在 F-350 上花了 X 美元” - **实际 vs 预估：** 比较 `actual_cost` 与计划中的成本预估 - **类别细分：** 按服务类型分组（换油、滤清器、轮胎等） - **历史总计：** 每辆车的维护总支出
### 年度摘要
被问及或年终时： ``` 💰 [Year] Maintenance Summary — [Vehicle] Total spent: $[X] Services performed: [count] Biggest expense: [service] — $[X] Average cost per service: $[X] vs. Estimated: $[X] ([over/under] by [X]%) ```
---
## 保修跟踪
跟踪保修以了解保修范围并在过期前收到警报。
### 保修条目结构 ```json { "type": "factory_powertrain", "provider": "Ford", "start_date": "2021-03-15", "end_date": "2026-03-15", "start_miles": 0, "end_miles": 60000, "coverage_details": "Engine, transmission, transfer case, driveshaft, axle assemblies", "status": "active", "contact_phone": "1-800-392-3673", "claim_number": null, "notes": "" } ```
### 保修类型 | 类型 | 典型保修范围 | |------|-----------------| | `factory_bumper_to_bumper` | 除易损件外的所有项目，期限最短 | | `factory_powertrain` | 发动机、变速箱、动力传动系统 —— 期限较长 | | `factory_corrosion` | 车身锈蚀 —— 通常 5 年以上 | | `factory_emissions` | 排放组件 —— 联邦强制要求主要组件 8 年/8 万英里 | | `extended` | 第三方或制造商延长保修 | | `parts_warranty` | 来自维修厂/经销商的特定零件（例如“新发电机，2年保修”） | | `labor_warranty` | 维修厂对特定维修的人工保修 |
### 过期警报
每次服务审查时检查保修。出现以下情况时发出警报： - 距离 end_date **3 个月内**，或 - 距离 end_miles **3,000 英里内**（以先到者为准）
警报格式： ``` ⚠️ WARRANTY EXPIRING SOON [Vehicle] — [Warranty type] from [Provider] Expires: [date] or [miles] miles (whichever first) Remaining: ~[X] months / ~[X] miles Coverage: [details] 💡 Schedule any warranty-covered concerns before expiration! ```
### 保修范围检查
当用户询问“这是否在保修范围内？”或标记到期服务时： 1. 检查车辆的所有有效保修 2. 将服务类型与保修范围匹配 3. 如果可能覆盖：“这可能包含在 [提供商] 的 [保修类型] 中（[日期]过期）。在自掏腰包支付前请联系他们。”
### 状态值 - `active` —— 当前生效 - `expiring_soon` —— 在警报阈值内 - `expired` —— 已过结束日期或结束里程 - `claimed` —— 已提交保修索赔
---
## 出行前 / 季节性检查清单
当提及旅行或季节变化时，生成特定于车辆的检查清单。
### 触发短语
当用户说类似以下内容时激活： - “我要去旅行” / “公路旅行” / “要去 [地点]” - “这周末拖东西” / “把房车拖到 [地点]” - “为冬天做准备” / “该过冬了” - “春天来了” / “该解除过冬了” - “这周末去越野” / “小道骑行”
### 检查清单生成
通过结合以下内容构建检查清单：
1. **逾期/即将到期的服务** —— 从该车辆的服务审查中提取 2. **目的地天气** —— 如果给出地点，检查天气预报（热、冷、雨、雪、海拔） 3. **出行类型项目** —— 根据他们正在做的事情 4. **季节性项目** —— 根据当前日期和地点
### 拖车检查清单（卡车 + 拖车/房车） ``` 🚛 Pre-Tow Checklist — [Truck] + [Trailer/RV]
TRUCK: □ Engine oil level □ Coolant level □ DEF level (diesel) □ Tire pressures (loaded spec: front [X] psi, rear [X] psi) □ Brake controller connected and tested □ Transmission temp gauge working □ All lights working □ Mirrors adjusted for towing
HITCH/CONNECTION: □ Fifth wheel / gooseneck / ball mount secured □ Pin box / kingpin locked (verify with tug test) □ Safety chains crossed under tongue □ Breakaway cable attached □ 7-pin connector — test all lights (brake, turn, running, reverse) □ Breakaway battery charged
TRAILER/RV: □ Tire pressures (spec: [X] psi) — check age on sidewall □ Wheel lug torque (spec: [X] ft-lbs) □ Slides fully retracted and locked □ Awning secured □ Fridge set to travel mode (or propane off) □ All compartments latched □ Stabilizer jacks fully up □ Roof vents closed □ TV antenna down □ Water heater bypass (if applicable) □ LP gas tank valve position (check local laws for travel) □ Cargo secured inside (open fridge, cabinets after arrival)
OVERDUE/DUE SERVICES: [List any from service review] ```
### 季节性检查清单
**入冬前 / 冬季化：** - 防冻液保护液位（用比重计测试） - 电池负载测试（寒冷会使容量降低 30-50%） - 雨刮片和玻璃水（耐寒型） - 轮胎状况（全季轮胎还是冬季轮胎？ - 发动机缸体加热器工作情况（柴油卡车） - 房车：完整冬季化程序（吹出管路、房车防冻液、热水器排水、旁路） - 船舶：冬季化发动机、给气缸喷防锈油、稳定燃油、排水系统
**入夏前 / 解除过冬保护：** - AC 系统检查（在需要之前先运行一下） - 冷却液液位和状况 - RV：解除水路过冬保护，给水箱消毒，检查 AC 设备 - 检查轮胎胎压（受热会升高） - 检查皮带和软管（高温会加速磨损）
**出行前（通用）：** - 所有液位 - 轮胎胎压和状况 - 灯光和信号灯 - 刹车（目视检查或近期已保养） - 雨刮器片 - 应急工具包（搭电线、手电筒、急救包） - 行驶证和保险在有效期内
---
## 里程预测
计算驾驶节奏并预测未来的保养何时到期。
### 计算 需要在 `mileage_history` 中有至少 **2 个数据点**，且间隔至少 14 天。
``` average_miles_per_month = (latest_miles - earliest_miles) / months_between_readings ```
使用完整的历史记录以获得稳定的平均值，但如果驾驶模式发生显著变化，则更侧重于近期数据。
### 保养日期预测 针对每一项保养： 1. 计算剩余里程：`next_due_miles - current_miles` 2. 预测月数：`miles_remaining / average_miles_per_month` 3. 预测日期：`today + projected_months` 4. 同时单独检查基于时间的间隔
包含在保养审查中： ``` 📅 Projected Service Dates - Oil Change: ~[Month Year] (at ~[X] miles) - Fuel Filters: ~[Month Year] (at ~[X] miles) - Trans Fluid: ~[Month Year] (at ~[X] miles) ```
### 预算预测 当被询问或包含在审查中时： ``` 💰 Next 6-Month Budget Forecast — [Vehicle] At [X] miles/month, expect: - Oil change (~[Month]): $[X] - Fuel filters (~[Month]): $[X] - Cabin air filter (~[Month]): $[X] Total estimated: $[X] ```
### 数据不足 如果少于 2 个数据点或读数间隔太近： - 备注：“Need more mileage history to project dates — will be available after next check-in” - 仍然显示基于里程的预估，但不显示日期
---
## 服务提供商跟踪
跟踪在哪里进行了保养，以便于参考和管理提供商。
### 捕获提供商信息 记录已完成的保养时，可选询问： - **Shop name**（或 "same as last time" / "DIY"） - **Location**（城市/地址） - **Phone number** - **Satisfaction rating** (1-5) - **Parts warranty**（月） - **Labor warranty**（月）
不要让这变得繁琐——如果他们只是说“换了我的机油”，先记录保养，然后随口问一下是在哪里换的。如果他们看起来不感兴趣，则跳过。
### 提供商存储 提供商存储在两个地方：
1. state.json 根目录下的全局 `providers` 数组 —— 可跨车辆复用： ```json { "id": "jims_diesel", "name": "Jim's Diesel Repair", "location": "123 Main St, Mesa, AZ", "phone": "480-555-1234", "specialties": ["diesel", "trucks"], "rating": 5, "notes": "Great with Power Stroke engines" } ```
2. 每个 service_history 条目 —— 通过 `id` 引用以及任何特定于保养的质保： ```json { "provider": { "id": "jims_diesel", "name": "Jim's Diesel Repair", "parts_warranty_months": 12, "labor_warranty_months": 6 } } ```
### 提供商查询 处理如下问题： - "Where did I get my last oil change?" → 在 service_history 中搜索最近的 oil_filter 条目，返回提供商 - "What shop did I use for the transmission service?" → 按 service_id 搜索 - "Show me all services at Jim's" → 按 provider.id 过滤 service_history - "What's Jim's phone number?" → 在 providers 数组中查找 - "Same shop as last time" → 使用最近 service_history 条目中的提供商
---
## 税务抵扣集成
对于标记为商用的车辆，帮助跟踪可抵扣的维护费用。
### 配置 在 state.json 中针对每辆车： ```json { "business_use": true, "business_use_percent": 50 } ```
如果 `business_use` 为 `true` 且未设置百分比，则假定为 100%。
### 抵扣跟踪 当在商用车辆上完成带有 `actual_cost` 的保养时：
1. 计算可抵扣部分：`actual_cost × (business_use_percent / 100)` 2. 向用户说明： ``` 💼 Tax Note: This $450 trans fluid service is 50% business use. Deductible amount: $225.00 (vehicle maintenance expense) ``` 3. 建议记录到 tax-professional 技能： ``` Want me to log this to your tax deductions? → $225.00 as vehicle maintenance expense ```
### 与 Tax-Professional 技能集成 如果用户确认，参考 `skills/tax-professional/SKILL.md` 并记录到 `data/tax-professional/YYYY-expenses.json`： ```json { "date": "2026-01-15", "category": "vehicle_maintenance", "description": "Trans fluid service — F-350 (50% business use)", "amount": 225.00, "vehicle": "f350", "full_cost": 450.00, "business_percent": 50, "receipt": false } ```
### 年度税务摘要 在被请求时或报税季节： ``` 💼 [Year] Business Vehicle Deductions — [Vehicle] Total maintenance costs: $[X] Business use: [X]% Deductible amount: $[X] Services included: [count] services ```
---
## 应急信息卡
存储并快速检索关键车辆信息，以用于道路救援、零件查询或快速参考。
### 应急信息结构 在 state.json 中针对每辆车： ```json { "emergency_info": { "vin": "1FT8W3BT0MED12345", "insurance_provider": "State Farm", "policy_number": "SF-123456789", "roadside_assistance_phone": "1-800-555-1234", "tire_size_front": "275/70R18", "tire_size_rear": "275/70R18", "tire_pressure_front_psi": 65, "tire_pressure_rear_psi": 80, "oil_type": "15W-40 CK-4 Full Synthetic", "oil_capacity": "15 quarts", "coolant_type": "Motorcraft Orange VC-3DIL-B", "def_type": "API certified DEF", "trans_fluid": "Motorcraft Mercon ULV", "tow_rating_lbs": 20000, "gvwr_lbs": 14000, "gcwr_lbs": 37000, "payload_lbs": 4300, "key_fob_battery": "CR2450", "fuel_type": "Diesel (Ultra Low Sulfur)", "fuel_tank_gallons": 48, "lug_nut_torque_ft_lbs": 165, "jack_points": "Frame rails, front and rear", "notes": "" } } ```
### 快速访问查询 即时响应： - "What's my VIN?" → 返回 VIN - "What are my truck's tire specs?" → 轮胎尺寸和胎压 - "What oil does my truck take?" → 机油类型和容量 - "Insurance info?" → 提供商、保单号、电话 - "Roadside assistance number?" → 电话号码 - "What's my tow rating?" → 牵引评级、GVWR、GCWR - "Key fob battery?" → 电池类型 - "Lug nut torque?" → 扭矩规格
### 应急卡格式 当被询问“emergency info”或“vehicle card”时： ``` 🚨 Emergency Info — [Vehicle Label] ━━━━━━━━━━━━━━━━━━━━━━━━━━━ VIN: [vin] Insurance: [provider] — Policy #[number] Roadside: [phone]
🔧 Specs Tires: F:[size] R:[size] Pressure: F:[X]psi R:[X]psi Oil: [type] ([capacity]) Coolant: [type] Fuel: [type] ([tank] gal) Key fob battery: [type]
📏 Ratings Tow: [X] lbs | GVWR: [X] lbs GCWR: [X] lbs | Payload: [X] lbs Lug torque: [X] ft-lbs ━━━━━━━━━━━━━━━━━━━━━━━━━━━ ```
### 信息填充 添加新车时，收集可用信息。许多规格可以根据年份/品牌/型号进行查询。让用户随着时间的推移填写个人信息（保险、道路救援电话）。字段在被填充之前可以为 null。
---
## 每英里成本分析
计算每英里基础上的车辆拥有总成本。
### 计算 需要包含至少 2 个数据点的里程历史。
``` total_miles_driven = latest_miles - earliest_miles (from mileage_history)
Maintenance cost per mile = total_actual_costs / total_miles_driven Fuel cost per mile = total_fuel_cost / total_miles_driven Total operating cost per mile = (total_actual_costs + total_fuel_cost) / total_miles_driven ```
### 报告格式 当被询问“cost per mile”或“operating cost”时： ``` 📊 Cost Per Mile — [Vehicle] Period: [earliest date] to [latest date] ([X] miles driven)
Maintenance only: $[X.XX]/mile Fuel only: $[X.XX]/mile (if fuel tracking active) Total operating: $[X.XX]/mile
💡 National averages (approximate): Cars: ~$0.10/mi maintenance, ~$0.12/mi fuel Trucks: ~$0.14/mi maintenance, ~$0.20/mi fuel (diesel) Heavy-duty diesel (towing): ~$0.18/mi maintenance, ~$0.25/mi fuel ```
### 车队概览 如果跟踪多辆车，显示对比： ``` 📊 Fleet Cost Per Mile [Vehicle 1]: $[X.XX]/mi (maintenance) | $[X.XX]/mi (total) [Vehicle 2]: $[X.XX]/mi (maintenance) | $[X.XX]/mi (total) Fleet average: $[X.XX]/mi ```
### 备注 - 仅包含记录了 `actual_cost` 的保养（跳过 null） - 如果没有燃料数据，仅显示维护成本 - 如果数据周期较短（<3 个月或 <1,000 英里），发出警告：“Limited data — will become more accurate over time” - 随着昂贵的一次性保养分摊到更多里程上，每英里成本自然会下降
---
## 里程检查
单个 cron 作业 **每周**（最高可能频率）运行一次，并根据每辆车的 `check_in_frequency` 和 `last_check_in` 日期检查哪些车到期需要检查。它还执行每月的召回检查。
> Prompt: "Mechanic skill: mileage check"
触发时： 1. 读取 `<workspace>/data/mechanic/state.json` 2. 对于每辆车，检查是否到期进行检查： - 将 `last_check_in` 日期与 `check_in_frequency` 进行比较 - **Weekly**：如果距上次检查 7+ 天则到期 - **Biweekly**：如果 14+ 天 - **Monthly**：如果 30+ 天 - **Quarterly**：如果 90+ 天 3. **每月召回检查**：如果距任何车辆的 `recalls.last_checked` 已过 30+ 天，则从 NHTSA API 获取最新召回并更新状态 4. 如果 **没有车辆到期检查 且 未发现新召回**，则回复 `HEARTBEAT_OK`（静默跳过） 5. 如果有车辆到期，**仅针对到期的车辆** 询问当前读数 6. 如果发现新召回，即使没有车辆到期进行里程检查，也要将它们包含在消息中 7. 当他们响应时更新状态和 `last_check_in` 8. 为更新的车辆运行 **Service Review**（包括质保提醒、预测、召回）
### 里程检查设置
创建一个 **每周** 运行的单个 cron 作业。它将在内部过滤哪些车辆到期。查看 `<workspace>/USER.md` 获取时区。
**Cron 表达式：** `0 17 * * 0`（用户时区每周日下午 5 点）
**Cron 作业配置：** - **Session：** 隔离，投递到他们的聊天频道 - **Prompt：** 读取 mechanic 技能，从 `data/mechanic/state.json` 加载状态。检查每辆车的 `check_in_frequency` 和 `last_check_in` 以确定哪些到期。同时检查召回，如果距上次召回检查已过 30+ 天。如果均未到期且无新召回，回复 HEARTBEAT_OK。否则，仅针对到期车辆询问当前读数，报告任何新召回，然后运行包含费用、质保提醒和预测的服务审查。保持对话风格。
### 更改频率
用户可以随时更改每辆车的频率： - "Check my dirt bike weekly" → 更新该车辆的 `check_in_frequency` - "Ask about the truck less often" → 切换到 quarterly - "Change all vehicles to monthly" → 更新所有车辆
在 `state.json` 中更新车辆的 `check_in_frequency` 并确认更改。
## 里程/工时更新
当用户报告里程或工时时（在任何情况下，不仅仅是每月）：
1. 更新车辆的 `current_miles` 和/或 `current_hours` 2. 将 `last_updated` 设置为今天 3. 追加到 `mileage_history`： ```json {"date": "YYYY-MM-DD", "miles": <value>, "source": "user_reported"} ``` 4. 运行 **Service Review**
## 服务审查
在任何里程/工时更新后，分析车辆计划文件中的所有保养。
### 针对每个保养项目： 1. 从 `service_history` 中找出**上次进行此保养的时间**（通过 `service_id` 匹配） 2. 如果从未进行过，则假定为在 **0 英里 / 0 小时**（车辆购入时）完成 3. 根据所有适用的间隔进行计算： - `miles_since_service` vs `interval_miles` - `months_since_service` vs `interval_months` - `hours_since_service` vs `interval_hours` 4. 分类： - **🔴 OVERDUE**：超过任何间隔 - **🟡 DUE SOON**：在任何间隔的 15% 以内 - **🟢 OK**：尚未到期
### 报告格式
**完整报告（发现问题时）：** ``` 🔧 Vehicle Service Report
━━━ [Vehicle Label] @ [miles] mi ━━━
⚠️ OPEN RECALLS - [NHTSA ID] — [Component]: [Summary] Remedy: [description] (FREE at dealer)
⚠️ WARRANTY ALERTS - [Warranty type] from [Provider] — expires [date] or [miles] mi [X] months / [X] miles remaining
🔴 OVERDUE - [service] — [X] miles/months overdue 💰 DIY: $X | Shop: $X | Dealer: $X [💼 [X]% deductible] (if business use)
🟡 DUE SOON - [service] — due in ~[X] miles/months 💰 DIY: $X | Shop: $X | Dealer: $X
📅 PROJECTED SCHEDULE (next 6 months) - [service] — ~[Month Year] at ~[X] mi ($[X] est.) - [service] — ~[Month Year] at ~[X] mi ($[X] est.) Total upcoming (6mo): ~$[X]
⛽ FUEL ECONOMY Current: [X] MPG | Average: [X] MPG | Trend: [stable/improving/declining] [⚠️ MPG Alert if applicable]
💰 SPENDING (YTD) Maintenance: $[X] | Fuel: $[X] | Total: $[X] Cost per mile: $[X.XX]
[Repeat for each vehicle]
🟢 [count] services current across all vehicles ```
**一切正常（简短）：** ``` 🔧 All vehicles current ✅ [Vehicle] @ [mi] — next: [soonest service] at ~[miles] (~[Month]) No open recalls | Warranties current ```
**当多个保养同时到期时**，提供打包的总预估，并建议在一次进店中合并完成。
### 条件部分 仅包含具有相关数据的部分： - 如果没有未决召回，跳过召回部分 - 如果没有即将到期，跳过质保提醒 - 如果没有 fuel_history 数据，跳过燃油经济性 - 如果里程数据不足，跳过预测 - 如果没有 actual_cost 数据，跳过支出 - 如果车辆不是商用，跳过税务说明
## 记录已完成的保养
当用户说他们完成了保养时（例如，“just got my oil changed”，“did the fuel filters at 65k”）：
1. 识别是哪辆车以及哪项保养 2. 询问他们花了多少钱（随意地——“What'd that run you?” / “How much was it?”） 3. 可选捕获提供商（“Where'd you take it?” / “Same shop as last time?”） 4. 添加到该车辆的 `service_history`： ```json { "service_id": "<matching id>", "date": "YYYY-MM-DD", "miles": <mileage_at_service>, "hours": <hours_if_applicable>, "notes": "<any details the user mentions>", "actual_cost": <amount_or_null>, "cost_type": "shop", "provider": { "id": "<provider_id>", "name": "<provider_name>", "parts_warranty_months": null, "labor_warranty_months": null } } ``` 5. 如果是商用车辆，说明可抵扣部分 6. 如果适用，提议记录到 tax-professional 7. 确认记录了什么 8. 重新计算该保养的下次到期日期
## 即席查询
处理有关任何跟踪车辆的问题。如果有歧义，询问是哪辆车。
**示例：** - "When's my next oil change?" → 检查相关车辆 - "What oil does my truck take?" → 参考计划详情或 emergency_info - "What maintenance do I need?" → 全面审查，所有车辆 - "I just hit 70,000 miles" → 更新里程，运行审查 - "Got new tires at 61k" → 记录服务，从那里跟踪轮换 - "I just got a new [vehicle]" → 指导添加车辆 - "How much would an oil change cost?" → 参考费用估算 - "What's the most urgent thing?" → 在所有车辆中确定优先级 - "Any recalls on my truck?" → 检查 NHTSA API - "How's my fuel economy?" → 油耗 (MPG) 报告 - "How much have I spent this year?" → 支出汇总 - "Is my warranty still good?" → 检查保修状态 - "Is this covered under warranty?" → 将服务与有效保修匹配 - "I'm heading on a road trip" → 出行前检查清单 - "When will my trans fluid be due?" → 里程预测 - "Where did I get my last oil change?" → 服务提供商查询 - "What's my VIN?" → 紧急信息 - "Look up my VIN" / "Decode my VIN" → 运行 VIN 解码，显示规格 - "Here's my VIN: [VIN]" → 解码、存储、自动填充并运行召回检查 - "What are my tire specs?" → 紧急信息 - "Cost per mile?" → 运营成本分析 - "How much will I spend on maintenance in the next 6 months?" → 预算预测
## 环境意识
检查 `<workspace>/USER.md` 以获取用户位置，并据此定制建议：
**炎热气候（沙漠、南部各州）：** - 高温会显著缩短电池寿命 - 轮胎紫外线损伤 —— 建议为停放车辆使用轮胎罩 - 冷却系统压力更大 - 橡胶部件（皮带、软管、密封件）老化更快 - 泥蜂/胡蜂在通风口和排气管中筑巢（尤其是房车）
**寒冷气候（北部各州、山区）：** - 冬季化对于房车和船只至关重要 - 低温下电池容量降低 - 检查防冻液保护级别 - 寒冷季节前检查炉灶/供暖系统
**多尘/越野环境：** - 发动机和空调滤芯需要更频繁的检查 - 发电机空气滤芯（房车） - 检查等速 (CV) 万向节防尘套（ATV/UTV）
**沿海/海洋环境：** - 腐蚀隐患 - 更频繁地清洗底盘 - 检查电气连接
## 费用估算
在标记逾期或即将到期的服务时，**务必包含费用估算**： - **DIY** —— 仅零件成本 - **修理厂** —— 独立维修技师 / 专业修理厂 - **经销商** —— 制造商授权经销商
包含任何关于昂贵故障场景的 `cost_note` 警告。
在展示一批服务时，提供在单次修理厂访问中打包服务的**总估算**。
## 重要常规说明
- **变速箱冲洗** —— 许多现代变速箱（尤其是 Ford 10R 系列、CVT）应**仅**采用放油加注，切勿冲洗。务必检查制造商建议。 - **房车车顶** —— 水侵入是房车的头号杀手。始终强调密封胶和车顶检查。 - **轮胎年限** —— 无论胎面深度如何，轮胎都应在 5-6 年时更换，尤其是房车/拖车轮胎。 - **严苛工况** —— 如果有人拖曳、装载、越野驾驶或在极端温度下操作，无论他们是否意识到，几乎都应按照严苛/特殊条件计划进行保养。 - **零件号** —— 在计划详情中包含 OEM（原厂）零件号。用户随后可以找到等效的售后市场零件。 - **季节性项目** —— 根据用户位置和一年中的时间，标记冬季化、解除冬季化以及季节性准备。 - **发电机运行时数** —— 与车辆里程分开跟踪。发电机有自己的保养间隔。 - **紧急电池**（拖车） —— 经常被遗忘。包含在拖车/房车检查中。 - **召回完成** —— 在经销商处始终免费。切勿为召回维修付费。 - **保修工作** —— 记录一切。保留收据。在服务历史中记录保修索赔号。 - **燃油跟踪一致性** —— 为了准确计算油耗，每次务必加注到相同液位（满箱）。标记部分加注。