unofficial-polestar-api 项目能力评估

评估日期：2026-10-27（Asia/Shanghai）
对象：kildahldev/unofficial-polestar-api
源码快照：43a734327a2ab171c5f3d6f217242d0faacde8a2（main，最新提交日期 2026-09-01）

结论

这是功能覆盖较广、已经有实际车主使用反馈的非官方 Polestar 云端接口库，配有可安装的 Home Assistant 集成。用于个人车主自动化很有价值；用于要求稳定交付的商业车联网产品，当前成熟度不足。

它不是车载系统破解工具，也不是只会查询电量的小脚本。主要价值是把官方 App 背后的部分云端数据和远程命令，变成可以由 Python、Home Assistant 和其他系统调用的接口。接口存在不等于每一车型、市场、账号和软件版本均可用，更不等于官方授权或服务保证。

本次仅进行文档、源码及 GitHub 发布/Issues/PR 静态评估。没有安装依赖、运行项目测试、登录车主账号或向车辆发送命令。车型效果属于项目文档或车主报告，而非本次实车验证。

一、能力覆盖

能力	已实现的接口/集成	重要边界
车辆状态	电量、续航、充电状态/功率/电流/电压、位置和停车位置、里程、车门/窗/锁状态等	后端不一定返回所有字段；位置是云端上报，并非有采样频率保证的车队轨迹
停车预调温	启动/停止，目标温度，部分座椅及方向盘加热参数	不等于驾驶过程中的完整空调遥控；HA 的部分控制是“下次启动参数”，不是实时读回的车内设置
门锁/寻车	锁车、解锁、后备厢解锁、闪灯、鸣笛	“后备厢解锁”不等于控制电动尾门完整开合；依赖账号授权及车辆状态
充电设置	目标 SOC、模式、限流、定时、定时覆盖、保存充电地点及部分地点设置	充电起停不是通用开关；P4 限流等能力存在限制
健康状态	保养提示、部分告警、部分车型四轮胎压数值	P2 数值胎压不可按 P3/P4 同等期待；P4 多个健康字段会保持默认值；存在胎压轮位映射待合并修正
空气净化/OTA	部分空气质量、预净化、软件更新信息及安装/调度命令	P4 预净化/OTA 操作不能认为已被充分验证；版本显示不代表能成功安装
应用集成	异步 Python 库、HACS 集成、多车逐项配置、Demo 模式	HA 每个配置项对应一辆车；不是完整多租户 SaaS/车队平台

源码的 Vehicle 外观类包含 56 个公开异步方法，包括读取、订阅与控制。HA 文档标称功能全部可用时约 106 个实体，这不是 106 个独立远程车控动作，其中有传感器、状态、设置和辅助参数。实际可用数量随车辆而异。[S1][S2][S3]

最容易误读的能力：充电起停

README 的 FAQ 明确表示，StartOverrideChargeTimer / StopOverrideChargeTimer 只覆盖已有的充电定时。若车辆处于没有活动定时的自由充电状态，没有可覆盖的定时，开关可能无效。源码的 start_charging() / stop_charging() 也确实调用这两个接口。

因此，它适合配合定时、目标 SOC 做管理，但不能单凭方法名字宣称支持任意充电会话的开始/停止。若要可靠管理光伏充电、动态负载或物理通断，更合理的是联合充电桩接口：车辆侧提供电量/目标，充电桩侧承担其支持的电流和充电会话控制。定时和 SOC 替代方案也需在具体车型验证。[S1][S4]

二、技术含量与工程成熟度

有价值的工程工作

不只是一个 REST 包装：包括 OIDC/PKCE 登录与令牌刷新、GraphQL 车辆发现、C3 gRPC 服务调用、手工 protobuf 编解码和类型化数据模型。
常用能力通过 Vehicle 统一封装，协议层、服务层和 HA 集成分离，利于扩展和复用。
HA 层同时采用默认 10 分钟轮询与部分长连接流，处理电池、位置、门锁/车门、空调、里程等更新；有退避重试、部分状态合并及命令后延迟刷新。
有配置界面、令牌存储、Dashboard 示例和 Demo 模式，已超过“仅提供源码和调用样例”的阶段。[S2][S3][S5][S6]

尚未达到稳定商业底座

包元数据明确标注 Development Status :: 3 - Alpha。截至评估日，最新 HACS 发布为 v0.3.2，2026-09-01；Python 包保持 0.3.1，这是 HACS-only 修复，不是版本遗漏。[S7][S8]
GitHub 快照约 91 stars、13 forks、两位已合并贡献者，维护集中在主作者；13 个开放 Issue 和 7 个开放 PR。数量不是质量分数，但不足以推断有长期支持团队。[S9]
已发生两次外部变化导致的故障：v0.3.1 修复官方 App 版本头导致的 HTTP 426；v0.3.2 对车辆列表的后端 schema 漂移采用已配置 VIN 回退。说明协议维护确实重要，不能只部署一次便假设长期可用。[S8]
仓库有 69 个命名测试函数/方法的静态定义，重点是模型编解码及少量发现/HA 启动回归。现有 workflows 有 HACS/hassfest 验证，但没有看到执行 pytest 的工作流；本次未运行测试。这不能证明 56 个车辆方法均已完成实车端到端覆盖。[S10]
流连接连续失败达到阈值后会放弃，需要重载集成恢复；取数失败会保留历史值。因此自动化不能把“仍有数值”当成“刚刚成功更新”，应增加数据新鲜度和失败告警。[S5]

综合判断：功能广度强于稳定性，家庭场景价值强于商业交付成熟度。

三、车型与地区兼容性

项目 README 主张实现 C3 后端。虽有 PCCS 配置定义，但当前主入口仍走 C3 发现流程，不能据此扩大到所有 Polestar/Volvo 后端。[S1][S6]
P2/P3/P4 均有车主使用/反馈线索，但没有完整、逐型号/年款/软件/地区验收矩阵。
P4 的 Issue #20 报告电量、充电状态、空调、门锁、鸣笛、里程、胎压等较多能力可用；窗户控制、预净化、多个空调定时及部分诊断字段不可用/未知。这是特定车主的报告，不是普遍保证。[S11]
P2 的 Issue #22 报告升级至 P5.1.17 后实时位置停更，停车位置仍可更新，而官方 App 位置正常。说明“官方 App 有功能”并不保证第三方实现持续正确。[S12]
登录提供者硬编码为 polestarid.eu.polestar.com，车辆列表使用 eu-north-1 地址，App locale 为 SE；没有看到供使用者选择中国区的配置。不能直接认定中国区账号能用，也不能仅凭 URL 断言一定不能用。地区兼容性是实施前首个验证门槛。[S6]

四、当前值得重视的开放问题

项目	状态/证据	对使用的影响
HA 启动时断网不自动恢复	Issue #39（2026-10-26）；源码通用异常直接抛出，未转成 `ConfigEntryNotReady`	家庭系统重启后可能需要手工重载
App 修改目标 SOC 不及时回写	Issue #33；PR #34 指出流更新可能重置轮询定时	状态显示及自动化判断可能滞后；本次未运行复现
充电命令响应解析	开放 PR #35 / #36；当前 charge-now 只读嵌套响应	后端执行与 HA 报告成功/失败可能不一致；PR 尚未成为已发布能力
胎压轮位映射	开放 PR #37，作者提供两车物理胎压对比；主分支尚未合并	不宜直接把当前数值/告警当成特定轮位的可靠安全判断
限流最大值	`number.py` 的 HA 滑块最大值硬编码 32 A；Issue #27 报告北美 48 A 车型受限	地区适配尚不完整
12 V 电池影响	README 明确未确认；Issue #24 仍有相关疑问	云端连接不代表绝不触发车辆通信/唤醒；避免擅自声称零影响

这里区分了“源码可观察限制”和“用户/PR 报告”；不是一次完整安全审计，也没有把未合并修复视为当前已解决。[S1][S5][S13]

五、最适合拿来做什么

1. 家庭车辆中控和提醒——优先级最高

在 Home Assistant 的手机/墙面屏查看电量、续航、插枪状态、车门、停车位置；根据剩余电量发补能提醒，离家后提示疑似未锁车。执行提醒之前核对数据时间和车辆在线状态。涉及解锁不建议无确认自动执行。[S1][S2]

2. 出行准备自动化——优先级高

按工作日/日历触发停车预调温，结合天气、插枪和电量条件决定是否启动；出发前提醒是否达到所需电量。日历读取、规则和通知由 HA 或自建系统承担，项目不是自带的完整出行助手。[S2][S3]

3. 家庭能源/充电管理——价值高，但需要配套

配合电价时段、家庭负载或光伏信息，管理目标电量和充电定时。真实动态光伏跟随和可靠通断应联合充电桩接口，不能依赖该项目的定时覆盖开关。费用和电量结算需要充电桩/电表数据，车辆瞬时功率不是完整计费记录。[S3][S4]

4. 自定义车辆 Dashboard、App、小组件——适合原型

Python 库可作为服务端适配层，支持自定义 Web 看板或通知服务；外观可以与车主的其他设备统一。需要另做接口服务、用户界面、权限、数据存储及部署，并在服务端保护车主凭据，不能直接把账号密码或长期 token 塞进公开前端。[S3][S6]

5. 车辆数据记录和分析——需要自建历史库

定期记录电量、里程、充电状态，生成使用趋势和补能提醒。项目提供数据接口，不是现成的长期轨迹库、充电账单系统或电池健康诊断产品。长期记录位置需要最小化保存和访问限制；不能靠电量/续航几个字段推断准确 SOH。[S2][S3]

6. AI 车主助手——是可扩展方向，不是现成能力

可在外部增加受控 API/MCP 接口，让助手回答“还剩多少电”“车停在哪”“出发前是否需要充电”，以及在确认后启动预调温。项目本身没有现成 AI/MCP 层。解锁、车窗、充电设置和 OTA 需要独立权限、人工确认、结果读回与审计；不宜让模型随意自主操作。[S3]

六、不适合直接做什么

对外承诺高可用、官方支持的多租户车队 SaaS。
安全关键的防盗追踪、可靠紧急解锁或按秒连续定位。
离线车控、CAN/OBD 诊断、刷 ECU、增加马力、辅助驾驶控制。
车内摄像头/视频监控、车机任意 App 控制、未授权 VIN 查询。
把所有型号、地区、软件版本统一视为“支持”。

上述判断来自当前代码与依赖边界；不是对未来无法扩展的断言。手工填写 VIN 仍需有效账号和后端授权，不是绕过车主身份。[S1][S3][S6]

七、凭据与实施建议

账号登录用到 Polestar ID 邮箱/密码；HA 把凭据保存到配置项并在 .storage 保存 token。独立库的文件 token store 是 JSON 文件并设置 0600 权限，不是应用层加密仓库。标准 TLS/PKCE 机制不等于完整商业安全方案。勿把 HA 备份、日志、token 文件及管理界面公开暴露。[S6][S14]

推荐顺序：

确认车型、年款、账号市场与该后端能否互通。
先验证读取：电量、停车位置、门锁与数据时间；区分 unknown、默认值和旧数据。
再验证低风险控制：停车预调温、闪灯；观察官方 App/车辆结果，而非仅看 API 返回。
加入断网恢复、过期数据告警、保守刷新间隔及令牌保护。
最后才考虑充电自动化、解锁或 OTA；不可用的功能不要以“界面有按钮”交付。

若目标是“让自己的极星接入智能家居”，值得试。若目标是“做一个能长期稳定卖给别人用的产品”，更适合作为协议研究和原型起点，而非现成底座。

来源索引

以下 GitHub 源码链接固定到本次 commit；Issues/PR 链接状态以 2026-10-27 读取结果为准。