Location Awareness

核心用法

location-awareness 是一个命令行驱动的位置感知技能，通过统一封装 scripts/location.sh 脚本，提供从基础定位到复杂地理围栏自动化的一站式解决方案。用户可通过自然语言触发查询——如"步行回家多久"自动解析为 eta home --mode walk，返回距离与预估时间；支持保存自定义地点、设置基于位置的提醒（到达某处时触发）、查询历史轨迹（"上周我在公司待了多久"）等功能。

架构上采用 Provider 模式解耦数据源，默认对接 Home Assistant 的 device_tracker 实体，同时支持 OwnTracks、通用 HTTP API 及 GPSLogger 本地文件四种接入方式，配置集中于 scripts/config.json，密钥支持环境变量、密码管理器或命令动态获取。地理围栏系统为核心亮点：每个围栏包含经纬度、半径、冷却时间、关联动作及启用状态，配合 systemd 定时器可实现全自动化的 cron 检查与多渠道通知（Signal/Telegram 等）。

显著优点

• 多源兼容性强：覆盖主流自托管方案（HA/OwnTracks）与极简文件模式，降低接入门槛
• 隐私优先设计：数据可完全本地流转（GPSLogger 模式），不依赖第三方云服务
• 响应极简：设计哲学要求"Terse"输出，直接返回结果无废话，适合自动化脚本和消费
• 灵活扩展：JSON 输出模式、speeds_kmh 自定义速度、区域/分类标签系统支持复杂查询
• 自动化闭环：systemd 定时器 + clawdbot message send 实现"到达即通知"的完整工作流

潜在缺点与局限性

• 依赖外部 GPS 源：本身不具备定位能力，需预先配置稳定的 Provider，断链即失效
• 配置门槛较高：config.json/geofences.json 手动编辑 + systemd 服务管理，对非技术用户不够友好
• 地理编码依赖 OpenStreetMap：eta 对陌生地点的解析质量受 OSM 数据完整性制约
• 无内置持久化数据库：历史查询依赖 Provider 或本地文件，长期轨迹存储能力有限
• 权限管理粗放：仅通过文件系统权限保护配置，缺乏多用户或细粒度访问控制

适合人群

• Home Assistant 深度用户：已有设备追踪实体，希望扩展 CLI 自动化场景
• 隐私敏感的技术从业者：追求自托管、最小化云端暴露的位置管理方案
• 量化自我爱好者：需要统计驻留时长、到访频率等维度的个人数据分析师
• 地理位置自动化需求者：如"到达超市推送购物清单"、"离开办公室发送通知"等场景

常规风险

• 位置数据泄露：config.json 若包含明文 token 且权限配置不当，存在敏感信息泄露风险；建议配合 pass: 或 env: 模式管理密钥
• 地理围栏漂移：GPS 精度与半径设置不匹配可能导致误触发或漏触发，需根据场景微调 radius_m
• 依赖链故障：Provider 服务中断、systemd 定时器未启用或通知渠道配置错误会导致自动化静默失效
• 历史数据精度：基于采样点的驻留统计可能遗漏短时停留，不适用于精确考勤或法律举证

核心用法

location-awareness 是一个面向本地化生活自动化的 GPS 追踪工具，通过统一的 scripts/location.sh 脚本提供 15+ 个命令，涵盖四大功能维度：

实时位置查询：status 返回当前所在区域或街道地址；herewego 生成 HERE WeGo 地图链接；nearby 搜索周边 POI（咖啡馆、酒吧等），支持半径过滤。

路径规划：eta 支持步行/骑行/驾车三种模式，可计算到已保存地点或任意地址的时间距离，底层调用 OSRM 开源路由引擎。

地理围栏与提醒：addplace 保存自定义地点并设置触发半径；remind 创建到达特定位置时的一次性提醒；geofences 管理可启停的自动化规则。

历史与统计：history 查询"上次何时在某地"或"今日行程"；stats 生成按地点停留时长的周报。

数据来源支持四种模式：Home Assistant（推荐）、OwnTracks、通用 HTTP API、GPSLogger 本地文件，配置通过 config.json 或环境变量完成。自动通知依赖 systemd timer，每 5 分钟检查一次触发条件。

显著优点

• 零外部依赖：核心代码仅使用 Python 标准库，无 pip 安装风险，部署轻量化。
• 多源兼容：无缝对接智能家居生态（Home Assistant）和隐私优先方案（OwnTracks/本地文件）。
• 开源地图栈：完全基于 OpenStreetMap 生态（Nominatim 地理编码、Overpass POI 查询、OSRM 路径规划），避免商业 API 限制与隐私条款。
• 灵活的 secret 解析：支持 env:、pass:（Unix 密码管理器）、cmd: 三种凭据注入方式，兼顾便捷与安全。
• 本地化执行：所有数据处理在本地完成，仅坐标查询时连接 OSM 服务，敏感位置历史不上云。

潜在缺点与局限性

• T3 来源可信度：作者为个人开发者账号，无公开 GitHub 仓库背书，需用户自行审计代码。
• 数据未加密：geofences.json 和 .location_state.json 以明文存储精确坐标和时间戳，设备物理访问即可读取。
• cmd: 前缀风险：配置中 cmd: 允许执行任意 shell 命令解析 secret，虽设 5 秒超时，但配置文件篡改可导致命令注入。
• 隐私合规缺口：缺乏 GDPR 级别的数据收集同意机制，向 OpenStreetMap 发送坐标时数据可能留存于第三方日志。
• 网络配置无白名单：用户可配置任意 HTTP 端点作为数据源，无域名限制，存在误连恶意服务的可能。

适合人群

• Home Assistant 用户：希望将手机定位数据用于本地生活自动化（到家开灯、离家布防）。
• 隐私敏感型极客：愿意用明文存储换取完全本地控制，拒绝 Google/Apple 位置服务。
• 量化自我爱好者：需要统计"本周在办公室多久"、"每月去健身房次数"等场景。
• 自行车/步行通勤者：依赖 ETA 功能规划出行，可自定义骑行速度参数。

常规风险

| 风险类型 | 说明 | 缓解建议 |

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

| 位置数据泄露 | 明文存储的坐标文件被本地其他应用/用户读取 | 手动设置文件权限 0600，或使用全盘加密 |

| 配置文件篡改 | `cmd:` 命令注入或恶意 API 端点配置 | 审计 config.json，避免使用 `cmd:` 前缀 |

| 第三方服务暴露 | 坐标发送至 OSM 进行反向地理编码 | 高敏感场景部署本地 Nominatim 实例 |

| 通知渠道外泄 | 通过 Signal/Telegram 发送位置提醒时数据流经第三方 | 使用自建通知网关或本地日志替代 |

整体而言，该 Skill 适合技术用户构建本地化、去商业化的位置感知系统，但需接受数据加密和作者可信度的 trade-off。