feat: Python/Java SDK 接入清单与打包文档

对真实 nixmsg 跑 DEVELOPMENT 第 9 节接入清单（跳过仅 JS 跨域），补 README/示例，并修 Paho/HiveMQ 真机联调死锁与鉴权分类。

docs/DEVIATIONS.md

@@ -853,6 +853,43 @@
    - 备选方案：依赖库自带重连再改 Clean Start（易漏）。  
    - 影响：无。
 
+### S2-PY/JAVA 4–5 2026-09-30
+
+1. **接入清单对真实 nixmsg，跳过仅 JS 跨域**  
+   - 原条款：DEVELOPMENT 第 9 节 15 条；任务 4 用 T0.5 启动器起真实服务端。  
+   - 实际做法：Python `tests/harness.py` + `test_checklist.py`、Java `TestHarness` + `ChecklistTest` 自行 `go build`/`admin init`/`serve`（临时目录、`127.0.0.1:0`），管理登录后 `PUT /api/admin/registration` 开注册。覆盖清单 1–13、15；第 14 条（仅 JS 跨域）不做。  
+   - 原因：总控指示跳过 JS 专属跨域；不改服务器业务代码。  
+   - 备选方案：复用 Go `test/harness` 包（SDK 测试不便依赖）。  
+   - 影响：无。
+
+2. **清单第 4 条「ack 丢失后服务器重推」未在真机选择性复现**  
+   - 原条款：模拟 ack 丢失后服务器重推，SDK 自动再确认且不重复回调。  
+   - 实际做法：集成测验证同消息号防重与断线入队重交送达一次；「选择性丢弃 SDK 发出的 ack 帧」在真实 broker 上做不到，去重再 ack 仍由假传输单测覆盖。  
+   - 原因：不改服务器、无中间代理注入丢包。  
+   - 备选方案：toxiproxy 按包过滤（超出本任务、且难按 MQTT 应用帧过滤）。  
+   - 影响：清单 4 真机为部分通过；假传输路径完整。
+
+3. **下行 `resp` 与业务帧分流，避免 auto_ack 自死锁**  
+   - 原条款：自动模式回调后发 ack；回调串行。  
+   - 实际做法：MQTT/`publishes` 回调里对 `resp` 立即完成 pending；`msg` 等进单线程队列再处理（可在队列线程里同步 `ack`/`request`）。Paho 使用 `MQTTv5` 常量与 `transport=websockets`，并等待 SUBACK。  
+   - 原因：若 `resp` 与 `msg` 同队列，auto_ack 等待 `resp` 会永久卡住。  
+   - 备选方案：ack 只发布不等待（弱化协议确认）。  
+   - 影响：与 DEVELOPMENT 行为一致，修复真机联调阻塞。
+
+4. **HiveMQ 鉴权失败与顶号原因码解析**  
+   - 原条款：CONNACK 鉴权失败停重连；`0x8E` 顶号停重连。  
+   - 实际做法：`connect().get()` 抛出的 `Mqtt5ConnAckException` / 文案含 `BAD_USER_*` 时归为 `bad_credentials`（令牌场景 Client 层改为 `session_invalid`）；断开原因从 `Mqtt5DisconnectException` 读 `SESSION_TAKEN_OVER`。`connectSync` 等到终态再返回，避免与 attemptConnect 竞态报 `busy/RECONNECTING`。  
+   - 原因：HiveMQ 失败路径多为异常而非成功返回的 CONNACK 对象。  
+   - 备选方案：无。  
+   - 影响：无。
+
+5. **任务 5：README/示例与打包试跑，不发布**  
+   - 原条款：包名与许可证；工具试跑确认能打包；README 与最小示例；真正发布在 Z3。  
+   - 实际做法：更新两端 README；Python `examples/minimal.py`；Java `asia.asio.nixmsg.examples.MinimalExample`；`python -m build` 产出 wheel/sdist；`mvn package -DskipTests` 产出 jar；`javap` major version 52（Java 8）。未上传 PyPI/Maven。  
+   - 原因：本波范围。  
+   - 备选方案：无。  
+   - 影响：无。
+
 ## 测试交付 Q
 
 ### Q1 / Q4 骨架 2026-09-30