docs: GOVERNANCE §6 Git 远端协作治理 + DECISIONS 2026-08-01

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -6,3 +6,4 @@ __pycache__/
 analysis/apk/jadx-out/
 analysis/apk/native/
 analysis/firmware/fw.asm
+._*

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,20 @@ 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 默认），含回归测试
+- **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
 
 首个 SDK 化发布。4.2寸墨水屏设备（DA14585 BLE，400×300 黑白红三色）的**完全离线**开发包：

DECISIONS.md

@@ -24,3 +24,9 @@
 | 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），掉线判定不漏形态 |
+| 2026-08-01 | 建立 Gitea 远端（chenwei/qianbian）并增补 Git 协作治理（GOVERNANCE §6） | 用户要求版本控制上云 + 后续治理迭代；此前仓库仅本地 | main 主干直提、分支短命、身份诚实不改写、推送前三项检查（净树/全绿/无 secret）、大文件仅原始输入随库 |

GOVERNANCE.md

@@ -63,3 +63,12 @@ qianbian/
 - 分析环境：Python 3.12（venv 于 `.venv/`）、jadx、capstone、bleak。
 - 依赖锁定：`requirements.txt` 固定版本；新增依赖需记录于 DECISIONS.md。
 - 外部工具一律装在本机，不修改系统关键组件。
+
+## 6. Git 与远端协作（2026-08 增补，DECISIONS 2026-08-01）
+
+1. **远端**：Gitea 实例，chenwei 账户下同名仓库 `qianbian`（remote 名 `origin`）。URL 见 DECISIONS.md 2026-08-01 条目。
+2. **分支策略**：`main` 为唯一主干，直接提交；实验性大改动用 `<topic>` 短分支，回合并即删。不使用 force push 改写 main 历史。
+3. **提交身份**：agent 工作用 `agent <agent@local>`，人工工作用本人身份——不混用、不改写历史身份，保证溯源诚实。
+4. **推送前检查**：工作树干净、`pytest` 全绿、无新增 secret（token/私钥/真实密码）。测试用口令（如 `pw123456`）允许但必须在测试/文档语境。
+5. **大文件**：`app/` 原始输入（APK 9.3MB、固件 72KB）随库分发（项目自包含要求）；其余 >1MB 产物须为文档/证据类文本，二进制中间产物一律 gitignore + 再生方法入库（analysis/README.md）。
+6. **同步纪律**：每个工作会话开始先 `git pull --ff-only`；结束前提交并 `git push`。冲突时以远端为准 rebase 本地未提交改动，禁止 `--force`。

PROGRESS.md

@@ -220,8 +220,14 @@
 - 三新模块：`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）
+- 环境事实：mcp 钉 >=1.23,<2（2.0 移除 FastMCP/memory API；1.23 起有 transport_security + CVE-2025-66416 修复；实测 1.29.0）
+
+### 2026-07-31：0.2.0-beta release + 常驻部署（生产性测试开始）
+
+- **release**：节点审计 8 项必修落地（版本 7 处统一 0.2.0b1、mcp 地板 >=1.23、--allowed-hosts 空串自锁修复+回归、文档数 208、DECISIONS 留痕）；tag `v0.2.0-beta` @ 5130bb7（旧 v0.2.0 删除）；208 测试全绿
+- **常驻部署**（熠管家，banyWinServer）：SYSTEM 计划任务 `BanyTech-PPCLOCK-MCP`（AtStartup + 999 次/1 分钟恢复 + runner 5 秒子进程重启）；token CSPRNG 生成 ACL 仅 SYSTEM/Administrators；日志 `C:\ProgramData\OpenClaw\ppclock-mcp\logs\`；验证：LAN 200/device_status ok/杀进程 5 秒自动拉起复 200；8971 与防火墙不变
+- **运维记录**：`/home/cwmine/vps/host-win/maintain_logs/2026-07-31_ppclock-mcp-production-test-service.md`；运行问题经 Bridge task `ppclock-mcp-ops` 回报本 session 统一迭代
 - 文档：docs/sdk/MCP.md（工具参考+部署）、README/llms.txt/API.md/CHANGELOG 同步；工具清单 tools/mcp_windows_deploy.md
 
 ### 会话时间线
@@ -232,3 +238,9 @@
 - P1：Web JS 协议提取（子代理）→ APK 反编译互证（子代理）→ 固件逆向（子代理）
 - P2：protocol/image/commands/transport/cli/templates/textbitmap 全 TDD 实现
 - P3：batch/本地模板/ota/keygen 增强；fw 工具链；文档终稿
+
+**生产接口实测**（2026-07-31，熠管家代跑，原始 JSON 入库）：
+- A 疑案闭环：「connected=false」为 OpenClaw 侧解析误读（读了顶层 connected/mac 而非 data.*，缺字段强转 false），非服务问题；原始 payload data.connected=true / data.mac=18:BC:5A:5D:BF:28 / connect_count=2
+- B 授权六步全过（每步 HTTP 200/isError=false/ok=true）：set_time tz=8 → upload_image slot0（bytes 15000+15000）→ set_mode image0 → countdown 2026-12-31 目标 → countdown_off（自回滚）→ device_status connected=true；屏显目视归用户
+- 观察项：supervisor.log 09:16-09:18 曾现 exit -1 每 6 秒重启循环约 2 分钟（疑端口占用竞态，runner 加日志重定向后 09:20:50 起稳定至今）——运维关注，非代码缺陷结论待续观
+- **目视闭环**（2026-07-31）：首轮"屏幕未变"系夹具顺序缺陷（countdown(mode=clock) 覆盖 image0 可见态）；单步 set_mode(image0) 复测，**用户目视确认 MCP-PROD-TEST 测试图上屏**——生产链路 agent→MCP→BLE→屏 全链目视闭环

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` 桥接。**不需要互联网**。
@@ -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    # 208 测试
 ```
 
 治理规则见 `GOVERNANCE.md`；变更记录 `CHANGELOG.md`；决策日志 `DECISIONS.md`。

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`。
 

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）。服务器与被控设备在同一台蓝牙主机上；
@@ -127,6 +127,21 @@ setx PPCLOCK_MCP_TOKEN "<token>"          # 或按服务方式注入环境变量
 - 不动既有 **8971** bridge 与其他服务：8972 为独立端口、独立进程。
 - `--mac` 建议显式指定设备地址，避免自动扫描误绑其他 `NRF-` 设备。
 
+### 常驻部署（2026-07-31 生产性测试实例）
+
+参考实现（banyWinServer 192.168.61.35，v0.2.0-beta，熠管家运维）：
+
+- **常驻方式**：SYSTEM 计划任务 `BanyTech-PPCLOCK-MCP`（AtStartup、最高权限、
+  执行时间不限、Task Scheduler 999 次/1 分钟恢复）；runner 脚本另有 5 秒子进程重启。
+- **token**：Windows CSPRNG 生成，存 `C:\ProgramData\OpenClaw\ppclock-mcp\token.txt`，
+  ACL 仅 SYSTEM/Administrators 可读；不入仓、不写日志。
+- **日志**：同目录 `logs\`——`supervisor.log` 记版本/启动参数/退出，
+  stdout/stderr 按次落文件。
+- **验证基线**：真实 LAN Host initialize 200、`device_status` ok；
+  杀 8972 进程后 5 秒自动拉起、initialize 复 200。
+- agent 挂载：`http://192.168.61.35:8972/mcp` + `Authorization: Bearer <token>`。
+- 运维记录原件：`/home/cwmine/vps/host-win/maintain_logs/2026-07-31_ppclock-mcp-production-test-service.md`。
+
 ## 不暴露的能力
 
 以下 SDK 能力**有意不**注册为 MCP 工具：

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   # 208 全绿
 ```
 
 - 库：`from ppclock import PPClient`
@@ -42,10 +42,10 @@ 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（守候重试）
+- `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-result.md
+- `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/`：195 测试
+- `tests/`：208 测试
 
 ## 设备事实（实测 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。

pyproject.toml

@@ -4,17 +4,20 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ppclock"
-version = "0.2.0"
+version = "0.2.0b1"
 description = "4.2寸墨水屏设备离线 CLI 上位机（DA14585 BLE，agent 友好）"
 requires-python = ">=3.10"
 dependencies = [
     "bleak>=0.22",
     "pillow>=10",
+    # 纯 Python 离线库，不违反零网络不变量；templates.py qrcode 模板硬依赖
+    "qrcode>=7",
 ]
 
 [project.optional-dependencies]
 dev = ["pytest>=8", "pytest-asyncio"]
-mcp = ["mcp>=1.10,<2"]
+# 地板 1.23：transport_security（--allowed-hosts 依赖）自 1.23 引入 + CVE-2025-66416 修复
+mcp = ["mcp>=1.23,<2"]
 
 [project.scripts]
 ppclock = "ppclock.cli:main"

requirements.txt

@@ -1,6 +1,8 @@
 androguard==4.1.4
 bleak==3.0.2
 capstone==5.0.9
+# MCP 服务器依赖；钉版理由见 DECISIONS 2026-07-31；本文件为 GOVERNANCE 指定的依赖冻结
+mcp==1.29.0
 pillow==12.3.0
 pytest==9.1.1
 pytest-asyncio==1.4.0

src/ppclock/__init__.py

@@ -16,7 +16,7 @@
 - bridge_server：BLE 桥服务端（ppclock-bridge 命令）
 - device_manager / mcp_tools / mcp_server：MCP 服务器（ppclock-mcp 命令）
 """
-__version__ = "0.2.0"
+__version__ = "0.2.0b1"
 
 from .client import PPClient
 from .transports.base import Transport, TransportError

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 = []

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 防火墙仅局域网放行；测试期手动启动，不注册系统服务。
 
@@ -19,7 +21,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 +38,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 +62,8 @@ claude mcp add ppclock -- C:\ppclock\.venv\Scripts\ppclock-mcp.exe --mac <MAC>
 
 ```powershell
 $env:PPCLOCK_MCP_TOKEN = "<随机长串>"
-.\.venv\Scripts\ppclock-mcp --transport http --host 0.0.0.0 --port 8972 --mac <MAC>
+.\.venv\Scripts\ppclock-mcp --transport http --host 0.0.0.0 --port 8972 --mac <MAC> `
+    --allowed-hosts "192.168.61.35:8972,localhost:8972,127.0.0.1:8972"   # 换成本机局域网地址；缺了 LAN Host 请求被 DNS 重绑定防护 421
 ```
 另开终端：
 ```powershell