docs: 打结审计必修落地——DECISIONS 补方案C连接管理与双TransportError两条；CHANGELOG 常驻部署当日闭环+qrcode 修正行；llms.txt 目录补 mcp_windows_deploy/field-test-plan/superpowers；README dev 依赖补 pytest-asyncio；test_bridge docstring 指向 ppclock.bridge_server；部署清单标时点件
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
chenweiandClaude committed
1 parent
a1ed2c2736
commit
a1041b9bad
6 files changed
+11
-4
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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），掉线判定不漏形态 |
|
||||
@@ -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` 桥接。**不需要互联网**。
|
||||
|
||||
@@ -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 测试
|
||||
|
||||
|
||||
@@ -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 = []
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# ppclock-mcp · Windows 部署执行清单（熠管家协作版）
|
||||
|
||||
> 时点件（2026-07-30 测试期清单）。现行部署形态以 docs/sdk/MCP.md §常驻部署 为准。
|
||||
|
||||
目标：把 ppclock-mcp 部署到**蓝牙物理所在的 Windows 服务器**，跑通 stdio 与 HTTP 两种接入实测。
|
||||
约束：**不动** 8971 bridge 与该机任何既有服务；8972 防火墙仅局域网放行；测试期手动启动，不注册系统服务。
|
||||
|
||||
|
||||
Reference in new issue
Block a user