60 lines
4.3 KiB
Markdown
60 lines
4.3 KiB
Markdown
# CHANGELOG
|
||
|
||
## [0.2.0-beta] — 2026-07-31
|
||
|
||
新增 **ppclock-mcp**：跑在蓝牙物理所在机器上的单层 MCP 服务器，agent 经 stdio 或
|
||
streamable HTTP 直驱墨水屏。
|
||
|
||
### MCP 服务器
|
||
- `ppclock-mcp` 命令（`ppclock.mcp_server:main`）：stdio / streamable HTTP 双模，
|
||
HTTP 绑非回环地址强制 `PPCLOCK_MCP_TOKEN` Bearer 鉴权（ASGI 中间件，不符 401）
|
||
- 13 个工具（`ppclock.mcp_tools`）：scan_devices / device_status / set_time / set_mode /
|
||
toggle / upload_image（路径或 base64，6 抖动+6 调整参数）/ render_template（6 模板）/
|
||
countdown / countdown_off / calendar_text / set_sleep / clear_screen / raw_send
|
||
- 统一输出契约与 CLI `--json` 同构：`{"ok","tool","data"|"error":{"code","message","hint"?}}`，
|
||
错误码 CONNECT_TIMEOUT / DEVICE_NOT_FOUND / BLE_ERROR / INVALID_PARAM / INTERNAL
|
||
- **DeviceManager 公开为子包能力**（`ppclock.device_manager`，方案 C 连接管理）：
|
||
按需连接 + 空闲保持，守候窗口覆盖设备 30-60s 广播窗口（`--connect-timeout` 默认 90s），
|
||
空闲自动断开（`--idle-timeout` 默认 300s），全操作串行，掉线重连重试一次
|
||
- 有意不暴露：OTA / 激活 / LUT / WiFi / 轮播（高危或本固件 no-op，走 SDK/CLI）
|
||
- 文档：`docs/sdk/MCP.md`（工具参考 + agent 挂载 + Windows 部署）
|
||
|
||
### beta 修正与复测（2026-07-31）
|
||
- **HTTP 复测通过**（熠管家，LAN 主机 192.168.61.56 → 192.168.61.35:8972）：无 token 401 /
|
||
非法 Host 421 / 真实 LAN Host 200（serverInfo=ppclock）/ `device_status` 全链 ok；
|
||
详见 spec 末节（`docs/superpowers/specs/2026-07-30-ppclock-mcp-design.md`）
|
||
- **mcp 依赖地板抬至 `>=1.23`**：`transport_security`（`--allowed-hosts` 依赖的
|
||
DNS 重绑定防护）自 1.23 引入，且 1.23 起含 CVE-2025-66416 修复；钉 `mcp>=1.23,<2`
|
||
（2.0 将移除 FastMCP API）
|
||
- **`--allowed-hosts` 空串防护**：`--allowed-hosts ""` 逗号拆分得空列表，会启用防护并
|
||
连 localhost 族一并 421（自锁）；现按 None 处理（保持 mcp 默认），含回归测试
|
||
- 常驻部署（Windows 服务化 + token 持久化）随熠管家进行，不在本发布内
|
||
|
||
## [0.1.0] — 2026-07-30
|
||
|
||
首个 SDK 化发布。4.2寸墨水屏设备（DA14585 BLE，400×300 黑白红三色）的**完全离线**开发包：
|
||
协议三线逆向（Web JS/APK/固件反汇编）+ 实机互证，全部功能经真机验证。
|
||
|
||
### SDK
|
||
- **`PPClient` 统一门面**：`via_local`（本机 bleak）/ `via_bridge(host, mac)`（经 bridge 远程 BLE）/ `via_uri` / `scan_devices`
|
||
- 设备操作全集：对时（含 `tz` 时区偏移）、模式/切换、传图（6 抖动+调整+槽位）、本地 6 模板渲染上传、倒计时（时钟/日历/前缀/日历中文字）、休眠、停车牌、轮播、LUT、WiFi 透传、raw 直发、SUOTA OTA
|
||
- **离线激活**：`activate_auto`——EFEF 取设备 ID → MAC 反解 → 本地 keygen（破解厂商云激活，实机验证）
|
||
- `transports`（base/local/bridge）与 `firmware`（image 解析重打包/ota）分包；`Transport` 协议开放自定义传输
|
||
- **BLE bridge 一等公民**：`ppclock-bridge` 命令（bleak 单文件服务端，Windows/Linux 原生运行），JSONL/TCP RPC，解决本机无蓝牙或 USB/IP 透传断流场景
|
||
|
||
### CLI（同一能力面）
|
||
`ppclock` 17 子命令 + `--json` 机器契约 + `batch` JSONL 单连接批量（agent 编排友好）+ `--via bridge://` / `PPCLOCK_VIA`
|
||
|
||
### 固件工具
|
||
镜像解析/修改/重打包（'pQ' 头 + zlib CRC32，字节级往返一致）；SUOTA 客户端（fef5 自定义 UUID 映射，实机推至产品头门禁）；工厂线刷布局已解析（pP 引导+双 bank+pR 产品头，docs/firmware-layout.md）
|
||
|
||
### 测试与文档
|
||
- 165 自动化测试全绿（协议/图像/命令/CLI/bridge/keygen/ota/fw/client 八个域）
|
||
- AI-native 文档：`docs/sdk/API.md` + `llms.txt`
|
||
- 逆向证据链：analysis/（web/apk/firmware 三域）+ docs/（架构/协议/固件分析/布局/实测记录）
|
||
|
||
### 已知限制
|
||
- 停车牌命令设备端不显示（厂商固件家族渲染差异，K1 待查）
|
||
- 本机设备为裸闪存布局（无 'pR' 产品头），SUOTA 止于设备内部门禁；线刷恢复布局路径已成文备查
|
||
- 轮播/WiFi 配置在本固件版本为 no-op（固件证据）
|