From f9758279717e2ac83e4f3cae7e930534f658213c Mon Sep 17 00:00:00 2001 From: chenwei Date: Fri, 31 Jul 2026 01:02:11 +0000 Subject: [PATCH] =?UTF-8?q?docs:=200.2.0-beta=20=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=E2=80=94=E2=80=94CHANGELOG=20=E5=A4=8D=E6=B5=8B=E4=B8=8E=20bet?= =?UTF-8?q?a=20=E4=BF=AE=E6=AD=A3=E3=80=81=E6=B5=8B=E8=AF=95=E6=95=B0=2019?= =?UTF-8?q?5=E2=86=92207=E3=80=81DECISIONS=20=E7=BB=88=E5=AE=A1=E6=94=BE?= =?UTF-8?q?=E8=A1=8C=E4=B8=8E=E4=BE=9D=E8=B5=96=E9=92=89=E7=89=88=E7=95=99?= =?UTF-8?q?=E7=97=95=E3=80=81Windows=20=E9=83=A8=E7=BD=B2=E6=B8=85?= =?UTF-8?q?=E5=8D=95=20main+--allowed-hosts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude --- CHANGELOG.md | 13 ++++++++++++- DECISIONS.md | 3 +++ PROGRESS.md | 2 +- README.md | 2 +- docs/sdk/API.md | 2 +- docs/sdk/MCP.md | 4 ++-- llms.txt | 8 ++++---- tools/mcp_windows_deploy.md | 7 ++++--- 8 files changed, 28 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e80c205..c5f5c6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # CHANGELOG -## [0.2.0] — 2026-07-30 +## [0.2.0-beta] — 2026-07-31 新增 **ppclock-mcp**：跑在蓝牙物理所在机器上的单层 MCP 服务器，agent 经 stdio 或 streamable HTTP 直驱墨水屏。 @@ -19,6 +19,17 @@ streamable HTTP 直驱墨水屏。 - 有意不暴露：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 黑白红三色）的**完全离线**开发包： diff --git a/DECISIONS.md b/DECISIONS.md index d95425b..cc336e9 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -24,3 +24,6 @@ | 2026-07-29 | **全量烧录实证安全性论证**：产品头校验失败时所有缓冲处理在写 flash 前中止（state[0x70] 恒 0），END 仅写 0xAA 于 [state[0x60]+2]=0x0002 而该字节原本就是 0xAA（无操作），复位后裸启原固件 | 反汇编 END 路径（0x07FCB7C6-0x07FCB7E4）与缓冲写路径（0x07FCB514 依赖中止的头部处理产物 state[0x74]） | 全量跑 OTA 的最坏结果=安全空转+复位；若中途校验通过则自然转正为真实烧录。用户授权下可执行 | | 2026-07-29 | **用户明确授权全量烧录**（301 块+END+复位，gpio_map=BE 序 C），要求全程记录与 review | 用户原话："授权 注意做好记录和review"（此前已授权"做一下审慎测试后刷机"） | 执行范围：fw_tst.img（DIS 版本串 3 字符差异）；留证：状态流日志 docs/suota-flash-log.jsonl；事后验证：scan/connect/DIS 读 | | 2026-07-29 | **G4 固件可控路径选型：B（免线刷软件利用）**，放弃 UART 线刷恢复工厂布局（路径 A 文档保留备查） | 用户原话："肯定是B"；B 路径已具备：图像 flash 持久化写（0x2E000）、EF 激活 flash 写（0x3Fxxx）+ 离线 keygen、全部 BLE 功能可控、SUOTA 工具链就绪（工厂布局设备可直接复用） | 任务说明目标3 以 B 路径达标；A 路径（线刷 .bin + UART）作为可选增强留存 docs/firmware-layout.md | +| 2026-07-31 | 引入 mcp 依赖（ppclock-mcp extra）并钉 `>=1.23,<2` | 0.2.0-beta 新增 MCP 服务器层；GOVERNANCE 要求依赖引入留痕；mcp 2.0 移除 FastMCP/memory API | `<2` 防 2.0 API 断裂；`>=1.23` 因 `transport_security`（DNS 重绑定防护，`--allowed-hosts` 依赖）自 1.23 引入，且 1.23 起含 CVE-2025-66416 修复；本地与 Windows 实测均为 1.29.0 | +| 2026-07-31 | 0.2.0-beta 终审裁定放行项终裁：TRANSPORT_ERRORS 含 OSError 的理论变宽、token 非恒定时间比较、Image.open 惰性解码失败归入 INTERNAL | 终审提出的三处理论风险，需终裁留痕 | 均判低风险放行：OSError 变宽仅使极端平台错误归入 BLE_ERROR（语义可接受）；token 比较在可信 LAN + Bearer 场景时序攻击不可行；Image.open 惰性解码异常有 INTERNAL 兜底且 message 带类型详情 | +| 2026-07-31 | `--allowed-hosts ""` 空串按 None 处理 | 空串逗号拆分得空列表，`TransportSecuritySettings(allowed_hosts=[])` 启用防护后连 localhost 族也 421（自锁） | main() 解析层 `_parse_allowed_hosts` 以 `or None` 归一，保持 mcp 默认 localhost 族；含回归测试 | diff --git a/PROGRESS.md b/PROGRESS.md index ac81a77..9ebcb39 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -220,7 +220,7 @@ - 三新模块：`device_manager.py`（方案 C：按需连接+空闲超时保持+串行锁+掉线重连重试一次）/ `mcp_tools.py`（13 高层工具+统一 ok/error 契约）/ `mcp_server.py`（stdio+streamable HTTP 双模，PPCLOCK_MCP_TOKEN 鉴权，非回环强制 token，--allowed-hosts Host 白名单） - 规格 spec + 实施计划入库（docs/superpowers/specs|plans）；207 测试全绿（新增 42） - **终审关键修复**：全部 fake 曾只说英文 TransportError——真实 bleak 抛中文 `transports.local.TransportError`（与 base 同名互不继承）与未包装 BleakError；捕获面/错误码映射已按真实异常语义重写（类型优先、中英文消息次之） -- **Windows 实测**（熠管家，banyWinServer 192.168.61.35，C:\ppclock）：stdio 全链路通过（scan→connect→set_time→upload_image 15000+15000→set_mode image0；远程无法目视上屏）；HTTP LAN Host 421（mcp DNS 重绑定防护）已修为 --allowed-hosts，复测待回报 +- **Windows 实测**（熠管家，banyWinServer 192.168.61.35，C:\ppclock）：stdio 全链路通过（scan→connect→set_time→upload_image 15000+15000→set_mode image0；远程无法目视上屏）；HTTP LAN Host 421（mcp DNS 重绑定防护）已修为 --allowed-hosts，复测已命中（401/421/200/device_status ok，2026-07-31，详见 spec 末节） - 环境事实：mcp 钉 >=1.10,<2（2.0 移除 FastMCP/memory API；实测 1.29.0） - 文档：docs/sdk/MCP.md（工具参考+部署）、README/llms.txt/API.md/CHANGELOG 同步；工具清单 tools/mcp_windows_deploy.md diff --git a/README.md b/README.md index 0a56e7d..a0a95e5 100644 --- a/README.md +++ b/README.md @@ -115,7 +115,7 @@ ppclock --json ota firmware.img --yes # SUOTA ## 开发 ```bash -.venv/bin/python -m pytest tests/ -q # 195 测试 +.venv/bin/python -m pytest tests/ -q # 207 测试 ``` 治理规则见 `GOVERNANCE.md`；变更记录 `CHANGELOG.md`；决策日志 `DECISIONS.md`。 diff --git a/docs/sdk/API.md b/docs/sdk/API.md index d8475be..7ab439d 100644 --- a/docs/sdk/API.md +++ b/docs/sdk/API.md @@ -1,4 +1,4 @@ -# ppclock SDK · API 参考（v0.2.0） +# ppclock SDK · API 参考（v0.2.0-beta） > 面向二次开发的签名级参考。协议细节见 `docs/protocol.md`，固件内部见 `docs/firmware-analysis.md`。MCP 服务器（ppclock-mcp）工具参考见 `docs/sdk/MCP.md`。 diff --git a/docs/sdk/MCP.md b/docs/sdk/MCP.md index 40af95b..ea0dae8 100644 --- a/docs/sdk/MCP.md +++ b/docs/sdk/MCP.md @@ -1,4 +1,4 @@ -# ppclock-mcp · MCP 服务器参考（v0.2.0） +# ppclock-mcp · MCP 服务器参考（v0.2.0-beta） > 面向 agent 挂载与部署的工具级参考。SDK 签名见 `docs/sdk/API.md`，协议细节见 `docs/protocol.md`。 @@ -11,7 +11,7 @@ streamable HTTP 直接驱动 4.2" 墨水屏设备。 ## 安装 ```bash -pip install -e ".[mcp]" # 追加依赖：mcp>=1.10,<2 +pip install -e ".[mcp]" # 追加依赖：mcp>=1.23,<2 ``` 要求：Python ≥ 3.10、本机蓝牙适配器（bleak）。服务器与被控设备在同一台蓝牙主机上； diff --git a/llms.txt b/llms.txt index 19c002e..a2a5005 100644 --- a/llms.txt +++ b/llms.txt @@ -1,6 +1,6 @@ # ppclock — 4.2寸墨水屏设备（DA14585 BLE）离线 SDK -> AI 消费向项目卡（llms.txt v0.2.0）。人用文档见 README.md；签名级 API 见 docs/sdk/API.md；MCP 服务器见 docs/sdk/MCP.md。 +> AI 消费向项目卡（llms.txt v0.2.0-beta）。人用文档见 README.md；签名级 API 见 docs/sdk/API.md；MCP 服务器见 docs/sdk/MCP.md。 ## 一句话 @@ -10,7 +10,7 @@ ppclock 是 4.2" 400×300 黑白红三色墨水屏设备（Dialog DA14585，广 ```bash python3 -m venv .venv && .venv/bin/pip install -e ".[dev]" -.venv/bin/python -m pytest tests/ -q # 195 全绿 +.venv/bin/python -m pytest tests/ -q # 207 全绿 ``` - 库：`from ppclock import PPClient` @@ -45,7 +45,7 @@ MCP 挂载（agent 直挂 13 工具）：`claude mcp add ppclock -- ppclock-mcp - `tools/`：fw_info/fw_pack（镜像工具）、field_test（真机引导测试）、flash_run、gpio_probe、rppclock.sh（守候重试） - `docs/`：protocol.md（协议规范·唯一事实源）、sdk/API.md、sdk/MCP.md、architecture.md、firmware-analysis.md、firmware-layout.md、field-test-result.md - `analysis/`：三线逆向证据（web/apk/firmware） -- `tests/`：195 测试 +- `tests/`：207 测试 ## 设备事实（实测 NRF-5DBF28） @@ -63,4 +63,4 @@ MCP 挂载（agent 直挂 13 工具）：`claude mcp add ppclock -- ppclock-mcp ## 版本 -0.2.0（CHANGELOG.md）。治理：GOVERNANCE.md（证据纪律/门禁）；历史决策：DECISIONS.md。 +0.2.0-beta（CHANGELOG.md）。治理：GOVERNANCE.md（证据纪律/门禁）；历史决策：DECISIONS.md。 diff --git a/tools/mcp_windows_deploy.md b/tools/mcp_windows_deploy.md index 34569f9..c707980 100644 --- a/tools/mcp_windows_deploy.md +++ b/tools/mcp_windows_deploy.md @@ -19,7 +19,7 @@ python --version # 需 ≥3.10 ```powershell git clone <仓库地址> C:\ppclock # 或把 Linux 侧源码压缩包拷贝解压到 C:\ppclock cd C:\ppclock -git checkout feat/ppclock-mcp # 分支合并 main 后此步改为 git checkout main +git checkout main # 对应 tag v0.2.0-beta git log --oneline -1 # 记录 commit，回报用 ``` @@ -36,7 +36,7 @@ python -m venv .venv ```powershell .\.venv\Scripts\ppclock-mcp --help ``` -预期：打印参数表，含 `--transport/--host/--port/--mac/--connect-timeout/--idle-timeout`。 +预期：打印参数表，含 `--transport/--host/--port/--mac/--connect-timeout/--idle-timeout/--allowed-hosts`。 ## 4. stdio 实测（本机 agent 直挂） @@ -60,7 +60,8 @@ claude mcp add ppclock -- C:\ppclock\.venv\Scripts\ppclock-mcp.exe --mac ```powershell $env:PPCLOCK_MCP_TOKEN = "<随机长串>" -.\.venv\Scripts\ppclock-mcp --transport http --host 0.0.0.0 --port 8972 --mac +.\.venv\Scripts\ppclock-mcp --transport http --host 0.0.0.0 --port 8972 --mac ` + --allowed-hosts "192.168.61.35:8972,localhost:8972,127.0.0.1:8972" # 换成本机局域网地址；缺了 LAN Host 请求被 DNS 重绑定防护 421 ``` 另开终端： ```powershell