From a1041b9bad398eeda4dc12da105fc4930cd3efbb Mon Sep 17 00:00:00 2001 From: chenwei Date: Fri, 31 Jul 2026 15:01:52 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=89=93=E7=BB=93=E5=AE=A1=E8=AE=A1?= =?UTF-8?q?=E5=BF=85=E4=BF=AE=E8=90=BD=E5=9C=B0=E2=80=94=E2=80=94DECISIONS?= =?UTF-8?q?=20=E8=A1=A5=E6=96=B9=E6=A1=88C=E8=BF=9E=E6=8E=A5=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E4=B8=8E=E5=8F=8CTransportError=E4=B8=A4=E6=9D=A1?= =?UTF-8?q?=EF=BC=9BCHANGELOG=20=E5=B8=B8=E9=A9=BB=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=E5=BD=93=E6=97=A5=E9=97=AD=E7=8E=AF+qrcode=20=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=E8=A1=8C=EF=BC=9Bllms.txt=20=E7=9B=AE=E5=BD=95?= =?UTF-8?q?=E8=A1=A5=20mcp=5Fwindows=5Fdeploy/field-test-plan/superpowers?= =?UTF-8?q?=EF=BC=9BREADME=20dev=20=E4=BE=9D=E8=B5=96=E8=A1=A5=20pytest-as?= =?UTF-8?q?yncio=EF=BC=9Btest=5Fbridge=20docstring=20=E6=8C=87=E5=90=91=20?= =?UTF-8?q?ppclock.bridge=5Fserver=EF=BC=9B=E9=83=A8=E7=BD=B2=E6=B8=85?= =?UTF-8?q?=E5=8D=95=E6=A0=87=E6=97=B6=E7=82=B9=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude --- CHANGELOG.md | 3 +++ DECISIONS.md | 2 ++ README.md | 2 +- llms.txt | 4 ++-- tests/test_bridge.py | 2 +- tools/mcp_windows_deploy.md | 2 ++ 6 files changed, 11 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c5f5c6b..14f24dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,7 +28,10 @@ streamable HTTP 直驱墨水屏。 （2.0 将移除 FastMCP API） - **`--allowed-hosts` 空串防护**：`--allowed-hosts ""` 逗号拆分得空列表，会启用防护并 连 localhost 族一并 421（自锁）；现按 None 处理（保持 mcp 默认），含回归测试 +- **qrcode 补入 dependencies**：0.1.0 遗留，`templates.py` qrcode 模板硬依赖 + （`render_qrcode` 内 import qrcode），pyproject 现钉 `qrcode>=7` - 常驻部署（Windows 服务化 + token 持久化）随熠管家进行，不在本发布内 + （2026-07-31 当日已完成常驻部署并生产目视闭环，见 docs/sdk/MCP.md §常驻部署、PROGRESS 末节） ## [0.1.0] — 2026-07-30 diff --git a/DECISIONS.md b/DECISIONS.md index cc336e9..fc56e7b 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -24,6 +24,8 @@ | 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-30 | MCP 连接管理选型**方案 C：按需连接 + 空闲保持 + 串行锁 + 掉线重连一次** | 三方拉扯：设备长睡眠（广播窗口仅 30-60s）vs agent 连续操作体验（每操作重连会撞睡眠窗口）vs 电池（常连使设备保持清醒耗电） | 首次操作守候连接（窗口覆盖 30-60s 广播），操作后保持连接、空闲 `--idle-timeout`（默认 300s）自动断开让设备睡眠；一把 asyncio.Lock 串行全部操作；操作中掉线重连重试一次再向上抛；退化配置：`--idle-timeout 0`（每操作即断，最省电）或大值（近常连，体验最佳）；详见 docs/superpowers/specs/2026-07-30-ppclock-mcp-design.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 族；含回归测试 | +| 2026-07-31 | **双 TransportError 历史包袱在 MCP 层适配，SDK 零改动** | `transports.base.TransportError` 与 `transports.local.TransportError` 同名但互不继承（历史包袱）；真实 bleak 写/读路径还裸抛 `BleakError` 不包装 | 改 SDK 会动公开语义、风险大于收益；MCP 层 `device_manager.py:19-26` 以 `TRANSPORT_ERRORS` 全家捕获兜底（base/local 两类 + BleakError + OSError + asyncio.TimeoutError），掉线判定不漏形态 | diff --git a/README.md b/README.md index 2ef58c8..3bbe65b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Python SDK（`PPClient`）+ CLI（`ppclock`）+ BLE 桥（`ppclock-bridge`）， ```bash python3 -m venv .venv -.venv/bin/pip install -e ".[dev]" # 依赖：bleak、pillow（dev: pytest） +.venv/bin/pip install -e ".[dev]" # 依赖：bleak、pillow（dev: pytest、pytest-asyncio） ``` 运行要求：蓝牙适配器（本机 bleak）**或** 他机蓝牙经 `ppclock-bridge` 桥接。**不需要互联网**。 diff --git a/llms.txt b/llms.txt index 1801d18..8e45660 100644 --- a/llms.txt +++ b/llms.txt @@ -42,8 +42,8 @@ MCP 挂载（agent 直挂 13 工具）：`claude mcp add ppclock -- ppclock-mcp ## 目录 - `src/ppclock/`：client.py（门面）/ protocol / image_pipeline / templates / transports(base,local,bridge) / firmware(image,ota) / cli / bridge_server / ppclock-mcp（mcp_server 入口 / device_manager 连接管理 / mcp_tools 13 工具） -- `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 +- `tools/`：fw_info/fw_pack（镜像工具）、field_test（真机引导测试）、flash_run、gpio_probe、rppclock.sh（守候重试）、mcp_windows_deploy.md（Windows 部署清单） +- `docs/`：protocol.md（协议规范·唯一事实源）、sdk/API.md、sdk/MCP.md、architecture.md、firmware-analysis.md、firmware-layout.md、field-test-plan.md、field-test-result.md、superpowers/（specs+plans） - `analysis/`：三线逆向证据（web/apk/firmware） - `tests/`：208 测试 diff --git a/tests/test_bridge.py b/tests/test_bridge.py index e957569..628ac10 100644 --- a/tests/test_bridge.py +++ b/tests/test_bridge.py @@ -9,7 +9,7 @@ from ppclock.transports import bridge class FakeBridgeServer: - """模拟 tools/bridge_server.py 的 JSONL 协议。""" + """模拟 ppclock.bridge_server 的 JSONL 协议。""" def __init__(self): self.received = [] diff --git a/tools/mcp_windows_deploy.md b/tools/mcp_windows_deploy.md index c707980..fabb9c4 100644 --- a/tools/mcp_windows_deploy.md +++ b/tools/mcp_windows_deploy.md @@ -1,5 +1,7 @@ # ppclock-mcp · Windows 部署执行清单（熠管家协作版） +> 时点件（2026-07-30 测试期清单）。现行部署形态以 docs/sdk/MCP.md §常驻部署 为准。 + 目标：把 ppclock-mcp 部署到**蓝牙物理所在的 Windows 服务器**，跑通 stdio 与 HTTP 两种接入实测。 约束：**不动** 8971 bridge 与该机任何既有服务；8972 防火墙仅局域网放行；测试期手动启动，不注册系统服务。