Location Awareness

核心功能

location-awareness 是一套完整的本地优先位置感知系统，通过 scripts/location.sh 统一入口提供：

• 实时定位：查询当前位置、坐标、所在区域及地图链接
• 智能ETA计算：步行、骑行、驾车三种模式的到达时间预估（基于OpenStreetMap地理编码，可自定义速度）
• 地理围栏(Geofences)：持久化保存的地点，支持半径、区域标签、分类标签，可触发自动化动作
• 位置提醒：单次提醒（到达某地时触发，自动删除）与接近警报（proximity alerts）
• POI发现：基于类别的周边兴趣点搜索（咖啡馆、酒吧、餐厅等），支持距离过滤
• 历史统计：到访记录查询、停留时长统计、本周/本月活动分析

显著优点

1. 隐私架构：纯本地运行，支持多种自托管数据源（Home Assistant、OwnTracks、GPSLogger），无需依赖第三方云服务
2. 灵活配置：支持环境变量、密码管理器（pass:）、命令输出（cmd:）等多种密钥注入方式
3. 自动化就绪：systemd定时器集成，实现真正的"到达某地自动通知"工作流
4. 响应式输出：默认人类可读，加--json即转为机器可解析，适合脚本管道

局限性与风险

• 依赖外部基础设施：需自行部署Home Assistant或OwnTracks服务端，初始配置门槛较高
• 精度受数据源限制：GPSLogger文件模式存在刷新延迟；HTTP模式依赖网络稳定性
• 地理编码偏见：ETA查询虽偏向当前位置，但OpenStreetMap数据覆盖度因地区而异
• 单一失败点：所有功能集中在一个shell脚本，若脚本损坏则全技能失效

适合人群

• 已运行Home Assistant的智能家居用户
• 对位置隐私敏感、拒绝Google/Apple位置服务的用户
• 需要"到达办公室自动开启勿扰模式"等自动化场景的技术爱好者
• 希望量化通勤时间、停留习惯的自我追踪者

常规风险

| 风险项 | 等级 | 说明 |

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

| 位置数据泄露 | 中 | 配置文件需妥善保管，建议用`env:`或`pass:`而非明文 |

| 误触发通知 | 低 | 地理围栏半径建议≥30米，避免GPS漂移导致频繁进出 |

| 依赖失效 | 中 | 定期检查systemd timer状态，避免静默停止更新 |

核心功能

location-awareness 是一个开源的位置感知 Skill，专为注重隐私的用户设计。它通过统一接口整合多种 GPS 数据源（Home Assistant、OwnTracks、GPSLogger、通用 HTTP），实现实时定位追踪与智能地理围栏管理。

主要能力

实时位置服务：查询当前坐标、所在区域（支持反向地理编码为街道地址）、快速生成 HERE WeGo 地图链接。

智能 ETA 计算：基于步行、骑行、驾车三种模式计算到达任意地点的时间与距离。支持已保存地点、坐标对或 OpenStreetMap 地理编码搜索。内置可配置的移动速度参数。

地理围栏与自动化：创建带半径的虚拟边界，进入/离开时触发自定义动作。支持冷却时间设置避免重复触发，可启用/禁用规则。

位置提醒系统：设置"到达某地时提醒我做某事"的一次性提醒，自动清理已送达提醒。

地点管理与探索：保存常用地点（支持区域/类别标签）、查看历史到访记录、统计各地点停留时长、搜索周边 POI（咖啡馆、酒吧、餐厅等）。

技术亮点

• 零第三方依赖：纯 Python 标准库实现，杜绝供应链攻击风险
• 多源凭证安全存储：支持环境变量、pass 密码管理器、命令输出动态获取
• 本地状态持久化：geofence 配置、提醒、历史记录均以 JSON 本地存储
• systemd 集成：通过定时器实现后台自动检查与通知推送

显著优点

1. 隐私优先设计：数据不外流至商业服务商，OpenStreetMap 等开源服务仅用于匿名查询
2. 模块化架构：provider 层抽象允许无缝切换不同定位后端
3. 终端友好：所有命令行输出简洁直接，支持 --json 便于脚本集成
4. 低资源占用：无需常驻进程，依赖 cron/systemd 定时触发

潜在局限与风险

| 方面 | 说明 |

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

| **网络依赖** | 实时 ETA 和 POI 搜索需联网，OSRM demo 服务使用 HTTP 明文传输（可被中间人篡改路由结果） |

| **配置复杂度** | 需手动编辑 JSON 配置、设置 systemd 定时器，对非技术用户门槛较高 |

| **移动客户端** | 依赖外部应用（Home Assistant Companion、OwnTracks）上报位置，本身不提供移动端 |

| **凭证管理** | 默认配置文件含空占位符，若误将真实 token 硬编码存在泄露风险 |

| **shell 执行面** | `cmd:` 类型 secret 解析使用 `shell=True`，配置被篡改时存在命令注入可能 |

安全评估摘要

CLS-Certify 评级 A级（70分）：代码结构清晰，无恶意模式，静态分析通过。主要关注点：4 个外部 API 调用（OpenStreetMap、OSRM、Home Assistant 等）均为可信服务；OSRM 使用 HTTP 明文为已知局限；subprocess 调用受 5 秒超时限制。

适合人群

• Home Assistant 用户：希望脱离云端位置服务，实现本地化地理围栏
• 隐私敏感者：拒绝 Google/Apple 持续位置追踪，愿自建替代方案
• 自动化爱好者：需要将位置数据与现有 shell/Python 工作流集成
• 技术 DIY 用户：具备 Linux 基础，能配置 systemd 和编辑 JSON

不适合：寻求开箱即用体验的非技术用户、需要离线地图功能者、对实时性要求极高的场景（依赖 cron 轮询）。

常规风险提示

• 地理位置属敏感个人信息，需确保符合 GDPR 等当地隐私法规
• 定期清理 scripts/.location_state.json 避免位置轨迹长期累积
• 配置文件权限建议设为 600，防止其他用户读取凭证
• 社区维护项目（T3 可信度），建议关注更新或自行 Fork 维护