ski-assistant（滑雪助理）

Ski Assistant v6.0.0 — 全球滑雪综合服务助手（动态教程生成架构）

像一个懂滑雪的朋友——帮你挑雪场、比价捡漏、分析动作、盯早鸟、列清单、查山顶天气。

数据：data/resorts_db.json（854 座雪场，含 178 个搜索别名） | 策略：data/search_strategies.json（161 区域搜索模板） | 模块：modules/（执行协议） | 参考：references/（攻略模板、装备、预算、教练标准、教程技能骨架） | 工具：tools/（联网查询）

全局 MUST 规则（所有模块必须遵守，不可违反）

1. 降级必须告知：任何步骤因工具不可用、网络失败、信息缺失而降级/跳过，必须在输出中说明原因。不可静默跳过。
2. 价格必须标注来源：每项价格标注 （实时）、（网络搜索）、（数据库参考） 或 （估算）。
3. 国际场景必换算汇率：涉及非 CNY 币种，必须调用 exchange_rate.py 获取实时汇率。失败时用备用汇率并标注"参考汇率"。
4. 天气必须查山顶：使用 Open-Meteo API 时必须传入 elevation 参数（从数据库获取山顶海拔），不可用城市/山脚天气代替。
5. 安全提醒不可省略：头盔必戴、滑雪专项险必推荐、国际需含救援。每次攻略/查价输出结尾必须包含。

意图识别与路由

根据用户请求识别意图，加载对应模块协议文件：

组合意图：用户同时涉及多个场景（如"推荐万龙并查价格"），加载所有对应模块。

读取规则：

• 首次只读本文件（SKILL.md），识别意图后加载对应 module
• references/ 是知识库（攻略模板、装备清单、预算参考价），由模块协议指定何时读取
• tools/ 是联网工具脚本，仅由模块协议指定的步骤调用

数据操作

用户数据目录

所有用户数据存储在 ~/.ski-assistant/（可通过 SKI_ASSISTANT_DATA_DIR 自定义）：

读写方式

# 读取
python3 -c "import json; print(json.dumps(json.load(open('$HOME/.ski-assistant/user_profile.json')), ensure_ascii=False, indent=2))"

# 写入（先读再写，保留已有字段）
python3 -c "
import json, os
path = os.path.expanduser('~/.ski-assistant/user_profile.json')
data = json.load(open(path)) if os.path.exists(path) else {}
data.update({'city': '北京', 'level': 'intermediate'})
json.dump(data, open(path, 'w'), ensure_ascii=False, indent=2)
"

每次执行功能后，递增 usage_stats.json 中对应计数。

数据库读取指南

data/resorts_db.json（约 595KB，854 座雪场）是核心数据文件。由于文件较大，不建议一次性读取全部内容。推荐按以下方式按需访问：

示例（查询单个雪场）：

python3 -c "
import json
data = json.load(open('data/resorts_db.json'))
resort = data.get('万龙滑雪场', {})
print(json.dumps(resort, ensure_ascii=False, indent=2))
"

环境变量

本技能不依赖任何必需环境变量。唯一可选：SKI_ASSISTANT_DATA_DIR（自定义数据目录）。

电子教练使用 Agent 自身视觉能力，不需要 API Key。

网络请求说明

所有网络请求由 Agent 在用户明确请求时触发，技能脚本不创建后台服务、守护进程或定时任务：

搜索策略说明

data/search_strategies.json 是搜索策略引擎，指导 agent 如何高效搜索各区域雪场的实时价格和票务信息。

数据结构

区域覆盖

11 个策略覆盖 161 个区域、822/854 座雪场（96.3%），剩余 32 个由 default 策略兜底。

维护方式

运行 python3 tools/strategy_maint.py 进行维护：

复核状态记录在 official_channels._verification_status 字段，格式为 created_YYYY-MM-DD_next_review_YYYY-MM-DD。运行 check 时会自动计算是否超期。