Skymotor Skill

这个 skill 用于首驱 Skymotor 电动车的车辆状态查询、电子围栏管理和天气辅助。

触发条件

当用户表达以下任一意图时，调用此 skill：

• 查询首驱 Skymotor 车辆状态、位置、电量、续航、开关机或充电状态。
• 查询、创建、更新、删除、检查电子围栏，或查询围栏告警记录。
• 保存当前位置为“家”“公司”等常用地点别名。
• 询问“骑车去公司天气如何”“明早去某地天气怎样”这类基于当前车辆位置的天气场景。

资源入口

• 核心脚本：scripts/skymotor_query.py
• 配置模板：config.example.json
• 接口说明：references/api-spec.md
• 本地敏感配置和运行态数据不应随 skill 发布；使用本地 config.json 和 state.json 时必须保持在发布包之外。

执行规则

1. 先识别用户意图，再调用脚本。
2. 如果环境变量 SKYMOTOR_DEVICESERVICE_KEY、命令行 --api-key、本地 config.json.apiKey 都没有可用 Key，提示用户提供首驱 Skymotor Device Service Key。
3. Key 来源优先级固定为：环境变量 SKYMOTOR_DEVICESERVICE_KEY > 命令行 --api-key > 本地 config.json.apiKey。
4. 先获取绑定车辆列表，再选择目标车辆。
5. 用户指定车辆名称或围栏名称时，先精确匹配，再模糊匹配；若命中多个候选，返回结构化候选列表让用户明确选择。
6. 用户未指定车辆时，优先选择 state = 1 的当前使用中车辆，否则取列表第一辆。
7. 只有在用户明确要求位置、围栏或天气时，才进一步查询位置。
8. 如果用户提供的是“家/公司”这类别名，优先读取本地保存的坐标别名；本地没有时再尝试地址转坐标。
9. 不要编造经纬度、围栏 ID、车辆状态或天气结果。

缺少 Key 时固定提示：

查询首驱 Skymotor 车辆位置需要首驱 Skymotor Device Service Key，请提供你的 Key。

（报名参加首驱 OpenClaw 内测活动并取得内测资格即可获取，详情关注首驱公众号动态）

高风险操作

删除围栏属于高风险操作：

• 脚本执行 --delete-fence 时必须显式追加 --confirm-delete 才会真正删除。
• 如果脚本返回 confirmation_required，先向用户展示 fenceId、围栏名称、半径、状态等确认信息，并等待用户明确确认后再重试。
• 不要用模糊名称直接执行删除；若脚本返回 choose_fence，必须让用户选择明确的 fenceId 或更精确名称。
• 查询和删除围栏时，后端最终只使用围栏 ID；用户输入名称时，脚本会先查询围栏列表并解析成真实 ID。纯数字名称也必须先按列表解析，不要直接当作 ID。

固定错误文案

当脚本返回以下错误时，优先使用固定回复文案，不要让外层直接暴露原始技术细节：

• 缺少 Key： 查询首驱 Skymotor 车辆位置需要首驱 Skymotor Device Service Key，请提供你的 Key。
• 401 Unauthorized 或服务端明确指示 Key 无效： 提供的首驱 Skymotor Device Service Key 无效或已失效，请检查后重新提供。
• multiple_vehicle_matches： 我匹配到了多辆首驱 Skymotor 车辆，请从候选列表里指定更精确的车辆名称或 deviceNo。
• multiple_fence_matches： 我匹配到了多个围栏，请从候选列表里指定 fenceId 或更精确的围栏名称。
• confirmation_required： 删除围栏属于高风险操作，请确认围栏信息后再执行删除。
• weather_query_failed 或 forecast_query_failed： 天气服务暂时不可用，建议稍后重试。
• fence_list_failed、status_query_failed、alarm_list_failed： 首驱 Skymotor 服务暂时未返回可用数据，请稍后重试；如果持续失败，再检查 Key 和网络环境。

命令模板

默认查询：

export SKYMOTOR_DEVICESERVICE_KEY=your_key_here
python scripts/skymotor_query.py

指定车辆：

python scripts/skymotor_query.py --api-key your_key_here --device-name "Y3"

本地配置文件：

{
  "apiKey": "your_skymotor_device_service_key_here"
}

创建围栏：

python scripts/skymotor_query.py --api-key your_key_here --create-fence "我家:39.9042:116.4074:3000"

列出围栏和告警：

python scripts/skymotor_query.py --api-key your_key_here --list-fences
python scripts/skymotor_query.py --api-key your_key_here --alarm-list

检查、更新、删除围栏：

python scripts/skymotor_query.py --api-key your_key_here --check-fence "12345"
python scripts/skymotor_query.py --api-key your_key_here --update-fence "12345:新围栏:39.9042:116.4074:5000"
python scripts/skymotor_query.py --api-key your_key_here --delete-fence "12345" --confirm-delete

保存当前位置和查询通勤天气：

python scripts/skymotor_query.py --api-key your_key_here --save-current-location-as "家"
python scripts/skymotor_query.py --api-key your_key_here --commute-to "公司" --distance-km 12

输出要求

• 默认优先返回结构化 JSON。
• 对位置类请求，仅输出地址文本。
• 对围栏类请求，应明确说明围栏名称、半径、是否在围栏内、与中心点距离。
• 如果围栏详情接口失败但列表缓存命中，应说明只能确认围栏存在，无法判断车辆是否在围栏内。
• 若电量百分比字段为空，应明确说明电量暂不可用，并优先返回续航里程等可用字段。
• 对失败请求，应保留失败原因，不要伪造成功结果。
• 对多目标冲突请求，应返回 choose_device 或 choose_fence，而不是猜测用户意图。
• 详细 API 字段、返回结构、地理编码和天气配置见 references/api-spec.md。