Location Awareness

核心功能

Location Awareness 是一款基于 Shell 脚本的位置管理技能，通过统一的 scripts/location.sh 接口提供完整的位置服务栈。核心能力包括：

• 多源定位接入：支持 Home Assistant、OwnTracks、GPSLogger、HTTP API 四种隐私可控的数据源
• 实时位置查询：当前坐标、所在区域、地图链接一键获取
• 智能 ETA 计算：步行、骑行、驾车三种模式的到达时间预估（支持自定义速度）
• 地理围栏系统：可配置半径、冷却时间、触发动作的持久化围栏规则
• 位置提醒：到达指定地点时触发一次性通知
• 历史轨迹回溯：查询特定地点的最后到访时间、本周在各处的停留时长统计
• POI 发现：基于 OpenStreetMap 搜索附近咖啡馆、酒吧等场所，支持距离筛选

显著优点

1. 隐私优先设计：支持本地 GPSLogger 文件模式，无需云端服务；所有数据存储于本地 JSON
2. 多源灵活适配：从企业级 Home Assistant 到极简 HTTP 端点均可对接
3. 自动化集成：通过 OpenClaw 内置 Cron 实现周期性位置检查与通知，无需 systemd
4. 密钥安全机制：支持环境变量、pass 密码管理器、文件挂载三种密钥注入方式
5. 输出格式双模：默认人类可读文本，--json 开关适配脚本化工作流

潜在局限

• 依赖外部定位数据源，本身不产生 GPS 数据
• ETA 计算基于直线距离与固定速度，未考虑实际路况
• 地理围栏精度受定位源刷新频率影响（建议 5 分钟 Cron 间隔）
• 需要管理员手动配置 JSON 文件，无交互式初始化向导
• OpenStreetMap 地理编码质量因地区而异

适合人群

• 已部署 Home Assistant / OwnTracks 的智能家居用户
• 希望自建位置服务、拒绝商业追踪的隐私敏感者
• 需要地理位置触发自动化（如到家开灯、到店提醒购物清单）的效率用户
• 开发者与运维人员，需将位置数据集成至现有 Shell 工作流

常规风险

• 位置数据泄露：配置文件中硬编码的 token 需妥善保管，建议优先使用 env: 或 pass: 引用
• Geofence 误触发：半径设置过小或冷却时间过短可能导致重复通知
• API 依赖：Home Assistant 或 OwnTracks 服务不可用时将导致位置查询失败
• 电池消耗：高频定位上报可能影响移动设备续航（建议合理设置上报间隔）

核心用法

location-awareness 是一款隐私优先的位置感知工具，通过整合 Home Assistant、OwnTracks、GPS Logger 等用户自托管或可信开源服务，实现 GPS 追踪与位置智能功能。核心能力涵盖四大场景：

实时定位与导航：查询当前位置、生成地图链接，并支持步行、骑行、驾车三种模式的到达时间（ETA）预估，自动调用 OpenStreetMap 进行地理编码。

地理围栏与提醒：用户可保存自定义地点（带半径、区域、类别标签），设置进入/离开触发的一次性提醒或周期性规则，支持通过 OpenClaw 内置 cron 实现自动检查与通知推送。

位置历史与统计：回溯"上次何时在某地"、"今日去过哪里"，并生成周度/自定义时段的驻留时长与到访次数统计。

附近 POI 发现：按类别（咖啡馆、酒吧、餐厅等）及距离筛选周边兴趣点，支持区域过滤与多维度列表排序。

所有命令统一通过 scripts/location.sh 调度，输出风格极简，可直接嵌入自动化工作流。

显著优点

• 隐私架构设计：优先支持 Home Assistant 等私有部署方案，位置数据不离用户控制；核心处理本地完成，外部 API 仅用于地图服务调用。
• 零依赖轻量实现：1057 行 Python/Bash 代码，纯标准库开发，消除供应链攻击面。
• 凭证管理灵活：支持环境变量、pass 密码管理器、文件及明文多种 secret 加载方式，无硬编码风险。
• 开源生态兼容：深度集成 OpenStreetMap、OSRM、Overpass 等知名开源地图服务，透明可信。

潜在缺点与局限性

• 外部 API 依赖：ETA 计算、POI 搜索、地理编码均需联网调用第三方服务，离线场景失效；OSRM 演示服务器存在 HTTP 明文请求（可配置为 HTTPS）。
• 配置门槛：需预先部署 Home Assistant 或 OwnTracks 后端，并完成 JSON 配置文件与 geofence 规则的手动编辑，对非技术用户不够友好。
• T3 信任级别：个人开发者维护，虽代码审查无异常，但长期维护与漏洞响应能力弱于企业级项目。
• 隐私合规待完善：用户授权机制与数据流向说明可更前置，GDPR 同意流程未强制内置。

适合人群

• 已部署 Home Assistant 或 OwnTracks 的智能家居进阶用户
• 重视位置隐私、拒绝商业云服务追踪的技术爱好者
• 需要地理围栏自动化（如"到超市提醒买牛奶"）的效率工具用户
• 愿意维护 JSON 配置与 shell 命令的 CLI 偏好者

常规风险

• 位置数据外泄：GPS 坐标上传至 OpenStreetMap/OSRM 进行编码与路由计算，虽服务可信，但用户需知情同意。
• API 服务稳定性：依赖的公共演示服务器（如 OSRM）可能有速率限制或服务中断风险，生产环境建议自建实例。
• 凭证配置误操作：Home Assistant Token 若权限过大或泄露，可能导致智能家居系统被未授权访问，建议配置只读权限并定期轮换。
• 自动化误触发：地理围栏半径与冷却时间设置不当可能导致频繁通知，需根据实际场景调试参数。