Location Awareness

核心用法

location-awareness 是一个多源位置服务聚合工具，支持 Home Assistant、OwnTracks、GPSLogger 及通用 HTTP API 四种数据源。用户可通过单一命令接口 scripts/location.sh 完成位置查询、地理围栏管理、智能提醒、POI 发现及出行规划等操作。

主要功能模块：

• 实时定位：获取当前坐标、所在区域及地图链接
• ETA 计算：支持步行、骑行、驾车三种模式，基于 OpenStreetMap 数据估算时间与距离
• 地理围栏：自定义半径、区域标签、冷却时间，支持启用/禁用及自动化触发
• 位置提醒：一次性到达提醒，触发后自动删除
• 历史追溯：查询特定地点的到访时间、今日轨迹及停留时长统计
• POI 发现：按类别（咖啡馆、酒吧等）搜索周边设施，支持距离筛选

显著优点

1. 隐私优先设计：支持自托管数据源（Home Assistant、GPSLogger），位置数据无需经过第三方云服务；纯本地配置文件管理，支持环境变量注入敏感信息
2. 多源兼容性：四种主流方案覆盖从智能家居生态到极简文件追踪的不同场景
3. 灵活的自动化集成：通过 OpenClaw 内置 cron 实现周期性检查与通知，无需外部 systemd 服务
4. 语义化地理围栏：支持区域（region）和类别（category）标签，便于批量筛选与管理
5. 离线友好：基于 OpenStreetMap 的地理编码与 POI 数据，减少商业 API 依赖

潜在缺点与局限性

• 数据源依赖：需用户自行配置并维护 Home Assistant、OwnTracks 或 GPSLogger，无开箱即用的托管服务
• 精度受限：GPSLogger 文件模式存在刷新延迟；HTTP 模式依赖外部 API 稳定性
• 移动端适配：无原生移动应用，依赖第三方追踪工具的数据推送
• 电池消耗：持续 GPS 追踪对移动设备电量影响需用户自行权衡
• 地理编码局限：OpenStreetMap 在某些地区的 POI 覆盖度和地址解析准确性可能不及 Google Maps

适合人群

• 已部署 Home Assistant 或注重自托管隐私的技术用户
• 需要基于位置的自动化工作流（如到家触发家务提醒、离开公司发送状态更新）
• 通勤规划与日常轨迹管理的效率工具爱好者
• 对商业位置服务数据收集持谨慎态度的隐私敏感用户

常规风险

• 位置数据泄露：配置文件若权限设置不当，可能导致家庭坐标等敏感信息暴露
• API 令牌管理：Home Assistant/OwnTracks 的长期访问令牌需安全存储，建议优先使用环境变量注入
• 地理围栏误触发：半径设置过小或 GPS 漂移可能导致频繁误报；冷却时间配置不当可能遗漏有效触发
• 自动化依赖：cron 任务若配置错误可能导致提醒遗漏或重复通知

核心用法

location-awareness 是一款专注于隐私优先的位置管理 skill，通过整合用户自托管的 GPS 数据源（Home Assistant、OwnTracks、GPSLogger 等），实现无需依赖商业位置服务的本地化位置感知。

主要功能模块

1. 实时位置查询

• status：获取当前位置、所在地理围栏区域、地图链接
• herewego：快速获取 HERE WeGo 地图导航链接
• 支持坐标输出与反向地理编码（街道地址解析）

2. 智能路线规划（ETA）

• 支持步行、骑行、驾车三种交通模式
• 可计算到已保存地点、任意坐标或任意地名（通过 OpenStreetMap 地理编码）
• 自定义行进速度配置

3. 地理围栏与自动化

• 创建基于半径的地理围栏（10-10000米可调）
• 支持进入/离开触发动作与冷却期机制
• 启用/禁用规则切换，避免重复触发

4. 位置提醒系统

• 单次提醒："到某地时提醒我XX"
• 接近预警：设置接近某地的距离阈值提醒
• 与 OpenClaw Cron 集成，实现后台自动检查

5. 地点管理与 POI 发现

• 保存当前位置为自定义地点（支持区域/分类标签）
• 搜索附近兴趣点（咖啡馆、餐厅、酒吧等）
• 按区域和分类筛选地点列表

6. 位置历史分析

• 查询上次访问某地点的时间
• 查看指定天数内的行程轨迹
• 统计在各地点的停留时长与访问频次

---

显著优点

| 维度 | 优势 |

|------|------|

| **隐私架构** | 本地优先设计，支持完全自托管（Home Assistant、GPSLogger 文件），位置数据不流经第三方商业服务 |

| **多源兼容** | 统一抽象层支持 4 种位置提供商，用户可按需切换，避免供应商锁定 |

| **零第三方依赖** | 纯 Python 标准库实现，无 pip 依赖，彻底消除供应链攻击面 |

| **灵活配置** | 同时支持 config.json 文件配置与环境变量注入（含 `env:VAR_NAME` 语法），便于密钥管理和容器化部署 |

| **开放生态** | 基于 OpenStreetMap 等开放数据，POI 搜索与地理编码无需 API Key |

| **自动化集成** | 原生支持 OpenClaw Cron，可设置 5 分钟间隔的后台检查，触发 Signal 等渠道通知 |

---

潜在缺点与局限性

| 问题 | 说明 |

|------|------|

| **OSRM HTTP 明文传输** | 路由计算默认使用 HTTP 而非 HTTPS（RISK-001），存在中间人攻击风险；建议用户配置自定义 HTTPS OSRM 服务器 |

| **无内置缓存机制** | 频繁的位置查询和 POI 搜索会重复调用外部 API，响应速度受网络影响，且可能触发服务限流 |

| **POI 数据依赖 OSM** | OpenStreetMap 数据质量因地区差异较大，部分偏远地区或新兴商业设施可能缺失 |

| **历史数据本地存储** | `.location_state.json` 持久化存储触发记录，虽为功能必需，但缺乏自动清理机制，长期运行文件可能膨胀 |

| **输入验证待加强** | place_id 生成采用简单字符串替换，特殊字符可能导致意外命名冲突（RISK-002） |

---

适合人群

• 隐私敏感用户：希望避免 Google/Apple 位置服务的数据收集
• Home Assistant 玩家：已有自托管智能家居基础设施，希望扩展位置自动化
• 极客/开发者：偏好可审计的纯标准库实现，需要高度定制化位置工作流
• 离线优先场景：需要在没有稳定互联网连接时仍能访问保存的地点和基础位置功能

---

常规风险

| 风险类别 | 等级 | 说明 |

|----------|------|------|

| 数据泄露 | 低 | 位置历史存储于本地 JSON 文件，建议设置适当文件权限（600） |

| 配置泄露 | 中 | Token 可能误写入 config.json 并提交至 Git，务必使用环境变量模式 |

| 网络嗅探 | 低 | OSRM 路由请求为 HTTP 明文，敏感行程可能被网络层截获 |

| 误触发 | 低 | 地理围栏半径设置过小或 GPS 漂移可能导致误报，建议室内场景半径≥50米 |

安全部署建议：使用 env:VAR_NAME 语法配置所有敏感凭证；定期清理 ~/.openclaw/skills/location-awareness/scripts/.location_state.json；为 OSRM 配置自托管 HTTPS 实例或等待上游修复。