docs(铁律): 真机开发强制规则 · 集群真源与门禁脚本

机器+卡若AI联合开发；禁止占位/mock冒充交付。新增真机开发铁律、real_device_gate.sh、每轮检查清单；机擎§〇.七与五人SKILL同步；冒烟无设备改exit1。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-24 14:28:29 +08:00
parent 84c1b74798
commit ccfd578407
14 changed files with 449 additions and 17 deletions
--- a/开发文档/10、项目管理/工作日志.md
+++ b/开发文档/10、项目管理/工作日志.md
@@ -19,6 +19,100 @@ related:

 ---

+## 2026-05-24 15:30 | 真机开发铁律 · 集群规则迭代（强制）
+
+### 执行人：火炬 · 机擎全员
+
+- [x] 新增 Cursor 规则 `.cursor/rules/real-device-mandatory.mdc`（最高优先级）
+- [x] 真源文档 `开发文档/2、架构/01-总览/真机开发铁律.md`
+- [x] `workphone.mdc` §零、`机擎/SKILL.md` §〇.七 同步
+- [x] 存客宝 `.cursorrules.md` §工作手机真机铁律 + `工作手机对接/01` §七
+- [x] 卡若AI `运营中枢/参考资料/工作手机真机开发铁律.md` + BOOTSTRAP 热技能
+
+**铁律摘要**：机器+卡若AI 联合开发；禁止占位/模拟冒充交付；验收必须真机留痕。
+
+---
+
+## 2026-05-24 15:45 | 真机铁律 · 集群补全（续）
+
+- [x] 机擎五人 SKILL（阿表/阿机/阿桥/阿端）追加真机铁律引用
+- [x] 存客宝 `.cursorrules` + `工作手机对接/README` + `03-联调验收` 同步
+- [x] 集群引用链闭环：真源 MD → Cursor mdc → 存客宝 → 卡若AI
+
+---
+
+## 2026-05-24 16:00 | 真机铁律 · 五人全员 + 对称文档（续二）
+
+- [x] 阿服 SKILL 追加真机部署铁律
+- [x] 工作手机 `存客宝BFF与工作手机SDK映射表.md` 顶部铁律 + 对称链
+- [x] 存客宝 `02-分板块` + `工作手机开发进度.md` 铁律引用
+
+---
+
+## 2026-05-24 16:10 | 真机铁律 · 门禁脚本 + 跨工作区规则（续三）
+
+- [x] 新增 `real_device_gate.sh`（ADB + SDK 在线设备，失败 exit 1）
+- [x] `workphone_bff_smoke.sh` 无设备改 exit 1（对齐铁律）
+- [x] `系统架构.md` + `开发进度总表.md` 完成判定引用铁律
+- [x] 个人 `.cursor/rules/real-device-mandatory.mdc` 跨工作区 alwaysApply
+
+---
+
+## 2026-05-24 16:15 | 真机铁律 · 机擎完整功能定义 + 注册表（续四）
+
+- [x] 机擎 §3.2.1「完整功能」改为须 `real_device_gate.sh` 或真机留痕
+- [x] 存客宝 `03-联调` BFF 验收前置门禁命令
+- [x] 卡若AI `SKILL_REGISTRY` G15b + 存客宝 SKILL 铁律引用
+- [x] 本机探测：`192.168.110.80:5555` Host down · SDK healthy · devices_online=0
+
+---
+
+## 2026-05-24 14:15 | 设备 ID MD5 字段 · 红米全量资料汇总
+
+### 执行人：@阿机 · @阿桥
+
+- [x] 新增 `sdk/app/services/device_id_util.py`（`device_id_md5` / `enrich_device_id_fields`）
+- [x] API 返回 `device_id_md5`：`connection/status`、`devices/{id}`、`hook/probe`、`hook/data`、`device_fleet`
+- [x] 红米 `xgfe65eimrrofyws` → MD5 `ed25814d9c92b3430696dc96c2142b5f`
+- [!] 当前 ADB 离线，Frida/Hook 需 USB 重连后 oneclick 恢复
+- [x] 新增 `sdk/scripts/upgrade_wechat_and_oneclick.sh`（等 ADB → 装 8069 arm64 → oneclick）
+- [x] 预下载 `/tmp/wechat_apk/weixin8069_arm64.apk`（248MB 官方 arm64）
+
+---
+
+## 2026-05-24 14:25 | 联系客服解封2 · UI 链路对齐截图
+
+### 执行人：@阿机 · @阿端
+
+- [x] `unblock_customer_service.py` 新增限制页直链：安全保护中→联系客服→kf.qq.com→联系专属客服→允许小程序→专属客服会话
+- [x] 保留原「我→设置→安全中心」兜底路径
+- [x] API：`POST /account/unblock-customer-service` 已有，skill `unblock_via_customer_service`
+
+---
+
+## 2026-05-24 14:15 | Obsidian 粘贴图 AI 可读 · 绝对路径闭环
+
+### 执行人：@阿表 · @阿端
+
+- [x] `.obsidian/app.json`：`{folder}/images` + 绝对路径 Markdown（工作手机 + 存客宝 v3）
+- [x] `设备-微信-解封2.md` 去除 4 条 wikilink；5 张图落 `1、需求/修改/images/`
+- [x] vault 根 4 个 `Pasted image` 删除；`.gitignore` 忽略根目录粘贴图
+- [x] 新增 `机擎/scripts/fix_pasted_images.py`（`--vault` 跨项目）
+- [x] AI Read 验收 5/5；全库 0 wikilink 图片引用
+
+---
+
+## 2026-05-24 | BFF 接口概念讲解 + 映射表 13 条同步
+
+### 执行人：@阿桥 · @阿表
+
+- [x] 解答 BEF→BFF（Backend For Frontend）概念与三层调用
+- [x] BFF 13 条路由实机 curl：`status` / `connection/status` / `hook/events` / `message/send` 均 BFF 200
+- [x] `message/send` SDK 层 Hook failed（ADB offline，非 BFF 问题）
+- [x] 映射表 §三 §六 7→13 条；cunkebao `01-总体架构与BFF映射.md` 同步
+
+---
+
 ## 2026-05-24 10:46 | Frida 军训验收终轮 · REST 96/96 + catalog 173/173 + E2E 8/8

 ### 执行人：@阿端 · @阿桥 · @阿机
@@ -3498,6 +3592,15 @@ v3.1: Agent 内置 AI Brain → 心跳驱动自主决策 → Frida优先/u2兜

 ---

+### 2026-05-24 | 卡洛发消息+朋友圈（阻塞 ADB）
+
+**需求**: 微信给「卡洛/卡若」发「你好」+ 发朋友圈 + 成功截图回传  
+**结果**: ❌ 未完成 — 无线 ADB `192.168.110.80:5555` Connection refused；USB 无设备；云端 WS Agent 已掉线  
+**已做**: 后台脚本 `sdk/scripts/run_kaluo_msg_moments.sh`（等 ADB 600s 后自动 oneclick→发消息→朋友圈→截图到 `5、接口/images/`）  
+**待卡若**: 手机开「无线调试」或 Type-C 插线授权 + 打开微信前台 → 脚本自动续跑
+
+---
+
 ### 2026-05-24 | Frida 一键 + Hook 探测 BFF + 页面诊断条

 **完成项**:
@@ -3567,9 +3670,119 @@ v3.1: Agent 内置 AI Brain → 心跳驱动自主决策 → Frida优先/u2兜
 2. 次要：重复 Agent 抢连、phantom 端口轮换后旧进程连错端口
 3. `frida_workphone_oneclick.sh`：启动前杀旧 Agent、再拉微信、等 `RPC ping: pong` 再结束
 4. `ensure_ws_agent.sh`：同步拉微信 + 等 RPC 就绪
+5. `wait_adb_device.sh` 新建；oneclick 启动前 wait 90s
+6. `agent.py`：Frida 回调 `call_soon_threadsafe`；成功通道 `websocket/frida`

-**阻塞**: 无线 ADB `192.168.110.80:5555` Connection refused（手机 IP 可达，需重开无线调试/USB）
+**阻塞**: 无线 ADB `192.168.110.80:5555` Connection refused（手机 IP 可达，需 USB 或重开无线调试）

 **进度**: 99.9%（脚本加固 ✅ · 真机 matrix 待 ADB 恢复）

+---
+
+### 2026-05-24 | 微信全量验收汇总 + 自动跑批
+
+**完成项**:
+1. 新增 `run_full_wechat_acceptance.sh`：等 ADB → oneclick → hook 数据 → REST 96 项 → catalog 173 项 → MD/JSON 报告
+2. 汇总报告：`5、接口/06-验收与矩阵/2026-05-24_微信全量验收_汇总报告.md`（今日最佳 **96/96 + 173/173**）
+3. 后台跑批已启动（600s 等 USB/无线 ADB）
+
+**阻塞**: 真机 ADB 未连接，实时复验待设备恢复
+
+**进度**: 99.5%（历史全绿 ✅ · 实时复验待 ADB）
+
+---
+
+### 2026-05-24 | 开发文档说明头图批量生成
+
+**完成项**:
+1. 脚本 `8、部署/05-测试验收/scripts/generate_doc_header_banners.py` — Pillow 批量生成说明头图
+2. **141** 篇 MD 已插入 frontmatter 后 `![文档说明](…/images/doc-headers/*.png)`（跳过工作日志/追加版等 **84** 篇）
+3. 阿表 SKILL **§四C** + 根 `开发文档/images/doc-headers/` + 总 README 约定更新
+
+**进度**: 99.9%
+
+---
+
+### 2026-05-24 | 开发文档说明头图 · AI 图替换 PIL
+
+**完成项**:
+1. **11** 张目录级 AI 头图（1～10 + 根 README）+ **7** 张主题 AI 头图（系统架构 / Frida验收 / 110验收 / Soul调研 / 存客宝对接 / 五图手册 / 开发进度）
+2. **147/147** 个 `doc-headers/*.png` 已全部替换为 AI 生成图（非 Pillow 扁平条）
+3. **25+** 篇「主文档」已升级为**独版** AI 头图（API契约/全量目录/SDK服务端/Agent/微信矩阵/Frida部署/存客宝映射/业务需求/技术选型/前端规范/目录总览/Hook多设备/E2E/一键接入等）
+4. 修复 `README_请先读我.md` / `_副本.md` 重复插入 **31×** 说明图 → 各保留 **1** 条置顶
+
+**进度**: 100%（Obsidian 打开任意 MD 可见图标化说明头图）
+
+---
+
+### 2026-05-24 | 存客宝回退「仅 BFF 接口层」
+
+**卡若要求**: 存客宝与工作手机对接只写接口，不改 Job/Bridge/Adapter。
+
+**完成项**:
+1. 删 Bridge/SendMessageController/seed 脚本；恢复 Job、Stats、Adapter
+2. 保留 `WorkPhoneSDK` + `GetWorkPhoneStatusController` 十条 `/v1/workphone/*`
+3. GitHub `cunkebao_v3` develop **`038024c67`**
+
+**进度**: 存客宝接口层 100% · 业务切 SDK 另开需求
+
+---
+
+### 2026-05-24 | 存客宝 BFF 复验 · ADB 仍离线
+
+**完成项**:
+1. BFF 复验：`POST /v1/auth/login` 200 → `GET /v1/workphone/connection/status` 200（`ws=0 adb=0`）
+2. `POST /v1/workphone/hook/execute` ping → 200「设备不在线: 192.168.110.80:5555」（透传正常）
+3. `auto_recover_adb_oneclick.sh` 增强：ping 通但 5555 关时日志提示开无线调试/USB
+4. 后台 `auto_recover` pid 68958 持续轮询；手机 `.80` ping 通，5555/39329 全关，子网无 ADB
+
+**卡点**: 需手机侧开「无线调试」或 USB 一次 `adb tcpip 5555`；脚本会自动 oneclick
+
+**进度**: 接口层 100% · 真机 E2E ~90%（等 ADB）
+
+---
+
+### 2026-05-24 | 微信解封·联系客服自动化（需求设备-微信-解封2）
+
+**完成项**:
+1. 5 张截图全部读图反推：安全保护中→联系客服→终止使用说明(kf.qq.com)→联系专属客服→允许小程序→微信安全专属客服
+2. 升级 `sdk/agent/skills/wechat/unblock_customer_service.py` 7 阶段状态机（含 H5/小程序授权弹窗专项处理）+ 文案锚点常量 + 截图归档 + 阻断项解析
+3. WechatSkill 注册 `unblock_via_customer_service`；SDK 路由 `POST /api/v3/account/unblock-customer-service`
+4. **批量常规操作**：`sdk/scripts/wechat_unblock_batch.py` + `sdk/config/unblock_targets.example.yaml`（多设备×多账号，concurrency 可调）
+5. 用户手册：`9、手册/02-操作指南/微信解封_联系客服批量操作手册.md` 3 步走 + 6 状态解读 + FAQ
+6. 后端方案：`6、后端/02-设备端/微信解封_联系客服自动化方案.md` v2 含真实链路 + 批量章节
+7. SUCCESS/REJECT 关键词补 5 条；smoke test 100% 通过
+8. SDK 实例已重启，`openapi.json` 6 条 unblock 端点（含新路由）；端到端 HTTP 200 通
+
+**待真机**: ADB 恢复后执行 `python3 sdk/scripts/wechat_unblock_batch.py -c sdk/config/unblock_targets.yaml`
+
+**进度**: 代码+批量+手册 100% · 真机验收待 ADB
+
+---
+
+### 2026-05-24 | 存客宝回退「仅 BFF 接口层」
+
+**卡若要求**: 存客宝与工作手机对接只写接口，不改 Job/Bridge/Adapter。
+
+**完成项**:
+1. 删 Bridge/SendMessageController/seed 脚本；恢复 Job、Stats、Adapter
+2. 保留 `WorkPhoneSDK` + `GetWorkPhoneStatusController` 十条 `/v1/workphone/*`
+3. GitHub `cunkebao_v3` develop **`038024c67`**
+
+**进度**: 存客宝接口层 100% · 业务切 SDK 另开需求
+
+---
+
+### 2026-05-24 | 存客宝 BFF 复验 · ADB 仍离线（补记）
+
+**完成项**:
+1. BFF 复验：`POST /v1/auth/login` 200 → `GET /v1/workphone/connection/status` 200（`ws=0 adb=0`）
+2. `POST /v1/workphone/hook/execute` ping → 200「设备不在线: 192.168.110.80:5555」（透传正常）
+3. `auto_recover_adb_oneclick.sh` 增强：ping 通但 5555 关时日志提示开无线调试/USB
+4. 后台 `auto_recover` pid 68958 持续轮询；手机 `.80` ping 通，5555/39329 全关，子网无 ADB
+
+**卡点**: 需手机侧开「无线调试」或 USB 一次 `adb tcpip 5555`；脚本会自动 oneclick
+
+**进度**: 接口层 100% · 真机 E2E ~90%（等 ADB）
+
 ---
--- a/开发文档/10、项目管理/开发进度总表.md
+++ b/开发文档/10、项目管理/开发进度总表.md
@@ -12,9 +12,13 @@ related:
  - "[[项目目录总览]]"
  - "[[10、项目管理/03-计划与专项/项目落地执行表|项目落地执行表]]"
 ---
+
+![文档说明](images/doc-headers/开发进度总表_65c8da.png)
+
 # 工作手机SDK v3.1 → v4.0 - 开发进度总表

 > **唯一进度文档** | 更新：2026-05-24  
+> **完成判定（强制）**：标 ✅/100% 须符合 [真机开发铁律](../2、架构/01-总览/真机开发铁律.md)（真机 E2E 留痕，禁止占位/mock）  
 > **Sprint 看板**：[[10、项目管理/03-计划与专项/项目落地执行表|项目落地执行表]] §零（实时跟踪）
 > 含：现有模块 + Hook增强模块 + AI Brain + 管理端 + 多设备部署 + **v4.0 AI数智员工统一APK** 全量任务拆解

@@ -36,7 +40,7 @@ related:
 已完成（Phase 8: Frida全功能）████████████████████████ 100% ← 110个Hook操作/24模块/v3.1
 进行中（Phase 9: 自动注册）  ████████████████████░░░░ 85%  ← 全自动注册引擎/SIM读取/验证码
 已完成（Phase 10: v4.0 APK） ████████████████████████ 100% ← AI数智员工统一安装包，28模块
-已完成（Phase 11: 项目结构） ████████████████████████ 100% ← 根目录非SDK收编、1～10顶层、Obsidian配色+图谱
+已完成（Phase 11: 项目结构） ████████████████████████ 100% ← 根目录非SDK收编、1～10顶层、Obsidian配色+图谱、**147篇 AI 说明头图**（deploy_doc_header_ai.py）
 ```

 ---
--- a/开发文档/2、架构/01-总览/真机开发铁律.md
+++ b/开发文档/2、架构/01-总览/真机开发铁律.md
@@ -0,0 +1,59 @@
+# 真机开发铁律
+
+> **版本**：v1.0 · **更新**：2026-05-24  
+> **性质**：强制规则 · 集群真源  
+> **Cursor 规则**：`.cursor/rules/real-device-mandatory.mdc`
+
+---
+
+## 一、原则
+
+**所有功能 = 机器（真机）开发 + 卡若AI 辅助实现。**  
+占位、模拟、假数据**不得**作为交付形态；占位若存在，必须在同一迭代内替换为真机可验收实现。
+
+## 二、真机定义
+
+| 层级 | 要求 |
+|------|------|
+| 硬件 | Root Android 工作机（Magisk + su 授权） |
+| 连接 | ADB（USB 或无线）+ 设备 Agent WebSocket |
+| 控制 | Frida Hook（主）/ 已验证 ADB-u2（辅） |
+| 服务 | 工作手机 SDK `:8899` 运行中 |
+| 业务链 | 存客宝/触客宝须 **BFF → SDK → 真机** 至少一次 E2E |
+
+## 三、禁止与允许
+
+**禁止**
+
+- 占位函数、硬编码 success、虚构设备列表
+- 仅用 Mock 测试宣称功能完成
+- 矩阵/进度表无真机证据标 ✅ 或 100%
+
+**允许（非交付）**
+
+- 离线 pytest mock（`sdk/tests/`，不依赖 8899）
+- 开发中临时 stub：**须**在 PR/日志标明「待真机」，且当轮或下轮补齐
+
+## 四、验收留痕路径
+
+```
+开发文档/8、部署/05-测试验收/
+├── screenshots/
+├── <YYYY-MM-DD>_*/
+└── scripts/
+    ├── real_device_gate.sh      # 真机门禁（ADB + SDK 在线设备）
+    └── workphone_bff_smoke.sh     # BFF 冒烟（无设备 exit 1）
+```
+
+## 五、集群同步
+
+| 仓库 | 引用位置 |
+|------|----------|
+| 工作手机 | `.cursor/rules/real-device-mandatory.mdc`、`机擎/SKILL.md` §〇.七 |
+| 存客宝 cunkebao_v3 | `.cursor/rules/.cursorrules.md` §工作手机真机铁律 |
+| 卡若AI | `运营中枢/参考资料/工作手机真机开发铁律.md` |
+| Agent 清单 | `8、部署/05-测试验收/真机开发每轮检查清单.md` |
+
+---
+
+**每次对话、每次开发、每次验收 — 按本铁律执行。**
--- a/开发文档/2、架构/01-总览/系统架构.md
+++ b/开发文档/2、架构/01-总览/系统架构.md
@@ -14,6 +14,9 @@ related:
  - "[[开发文档/README|开发文档总入口]]"
  - "[[开发进度总表]]"
 ---
+
+![文档说明](../images/doc-headers/系统架构_72eb68.png)
+
 # 工作手机SDK v3.0 → v4.0 系统架构
 > 创建日期：2026-01-26 | 架构师：卡若 | 状态：已确认
 > 
@@ -21,6 +24,8 @@ related:
 > 
 > **重大更新(2026-03-16)**：v4.0 AI数智员工统一APK — 设备端全面Kotlin重写，五通道融合单APK

+> **铁律（2026-05-24 · 强制）**：所有功能以 **Root 真机** 验收；禁止占位/mock 冒充交付。详见 [真机开发铁律.md](真机开发铁律.md)
+
 ---

 ## 〇、v4.0 AI数智员工统一APK（2026-03-16）
--- a/开发文档/5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md
+++ b/开发文档/5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md
@@ -14,11 +14,15 @@ related:
  - "[[开发文档/README|开发文档总入口]]"
  - "[[开发进度总表]]"
 ---
+
+![文档说明](../images/doc-headers/存客宝BFF与工作手机SDK映射表_d5ac98.png)
+
 # 存客宝 BFF 与工作手机 SDK 映射表

 > **版本**: v1.0 | **更新**: 2026-05-24 | **负责人**: @阿桥  
 > **存客宝代码**: `cunkebao_v3/Server/application/common/util/WorkPhoneSDK.php`  
-> **工作手机真源**: [工作手机API全量接口目录.md](../01-规范与统一层/工作手机API全量接口目录.md)
+> **工作手机真源**: [工作手机API全量接口目录.md](../01-规范与统一层/工作手机API全量接口目录.md)  
+> **铁律（强制）**: [真机开发铁律](../../2、架构/01-总览/真机开发铁律.md) — 本表每条映射 **须真机 E2E** 验收，禁止占位/mock 冒充完成。对称文档：存客宝 `开发文档/工作手机对接/01-总体架构与BFF映射.md` §七

 ---

@@ -64,8 +68,14 @@ related:
 | `/v1/workphone/ai/task` | POST | `POST /api/v3/devices/{device_id}/ai/task` | ✅ 已注册 |
 | `/v1/workphone/ai/standing-order` | POST | `POST /api/v3/devices/{device_id}/ai/standing-order` | ✅ 已注册 |
 | `/v1/workphone/ai/execute` | POST | `POST /api/v3/devices/{device_id}/ai/execute` | ✅ 已注册 |
+| `/v1/workphone/hook/events` | GET | `GET /api/v3/hook/events` | Hook 事件列表；可选 `device_id` / `event_type` / `limit` |
+| `/v1/workphone/hook/events/sync` | POST | SDK 事件 + `WorkPhoneEventBridge` | 拉取 Hook 事件并同步存客宝业务 |
+| `/v1/workphone/connection/status` | GET | `GET /api/v3/connection/status` | WS / ADB 连接状态 |
+| `/v1/workphone/hook/probe` | GET | `GET /api/v3/hook/probe/{device_id}` | Frida / 微信就绪探测 |
+| `/v1/workphone/message/send` | POST | `POST /api/v3/message/send` | 发消息；可选 `channel`（hook/adb） |
+| `/v1/workphone/hook/execute` | POST | `POST /api/v3/hook/execute` | Hook 统一执行入口 |

-前端定义见：`cunkebao_v3/Cunkebao/src/pages/mobile/mine/workphone/api.ts`
+前端定义见：`cunkebao_v3/Cunkebao/src/pages/mobile/mine/workphone/api.ts`（Hook 事件两条暂无 api.ts 封装，可直接调 BFF）

 ---

@@ -166,17 +176,23 @@ related:

 ---

-## 六、BFF 路由清单（7 条，已全部注册）
+## 六、BFF 路由清单（13 条，已全部注册）

-| 前端 api.ts | BFF 路由 | SDK 目标 | 状态 |
-|-------------|----------|----------|------|
-| `fetchWorkPhoneStatus` | `GET /v1/workphone/status` | workbench + devices | ✅ |
-| `fetchWorkPhoneDevice` | `GET /v1/workphone/device` | `GET /api/v3/devices/{id}` | ✅ |
-| `fetchWorkPhoneScreenshot` | `POST /v1/workphone/screenshot` | screenshot | ✅ |
-| `fetchAIBrainStatus` | `GET /v1/workphone/ai/status` | `GET /api/v3/devices/{id}/ai/status` | ✅ |
-| `pushAITask` | `POST /v1/workphone/ai/task` | `POST .../ai/task` | ✅ |
-| `pushAIStandingOrder` | `POST /v1/workphone/ai/standing-order` | standing-order | ✅ |
-| `executeAITask` | `POST /v1/workphone/ai/execute` | ai/execute | ✅ |
+| 前端 api.ts | BFF 路由 | 方法 | SDK 目标 | 状态 |
+|-------------|----------|------|----------|------|
+| `fetchWorkPhoneStatus` | `/v1/workphone/status` | GET | workbench/overview + devices + connection | ✅ |
+| `fetchWorkPhoneDevice` | `/v1/workphone/device` | GET | `GET /api/v3/devices/{id}` | ✅ |
+| `fetchWorkPhoneScreenshot` | `/v1/workphone/screenshot` | POST | screenshot | ✅ |
+| `fetchAIBrainStatus` | `/v1/workphone/ai/status` | GET | `GET /api/v3/devices/{id}/ai/status` | ✅ |
+| `pushAITask` | `/v1/workphone/ai/task` | POST | `POST .../ai/task` | ✅ |
+| `pushAIStandingOrder` | `/v1/workphone/ai/standing-order` | POST | standing-order | ✅ |
+| `executeAITask` | `/v1/workphone/ai/execute` | POST | ai/execute | ✅ |
+| — | `/v1/workphone/hook/events` | GET | Hook 事件列表 | ✅ |
+| — | `/v1/workphone/hook/events/sync` | POST | 事件同步存客宝 | ✅ |
+| `fetchWorkPhoneConnection` | `/v1/workphone/connection/status` | GET | `GET /api/v3/connection/status` | ✅ |
+| `fetchHookProbe` | `/v1/workphone/hook/probe` | GET | `GET /api/v3/hook/probe/{id}` | ✅ |
+| `sendWorkPhoneMessage` | `/v1/workphone/message/send` | POST | `POST /api/v3/message/send` | ✅ |
+| `executeWorkPhoneHook` | `/v1/workphone/hook/execute` | POST | `POST /api/v3/hook/execute` | ✅ |

 代码：`cunkebao_v3/Server/application/cunkebao/config/route.php` · `GetWorkPhoneStatusController.php` · `WorkPhoneSDK.php`

--- a/开发文档/8、部署/05-测试验收/scripts/real_device_gate.sh
+++ b/开发文档/8、部署/05-测试验收/scripts/real_device_gate.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# 真机开发铁律 · 门禁检查（Agent/CI 可调用）
+# 真源：开发文档/2、架构/01-总览/真机开发铁律.md
+# 用法：./real_device_gate.sh [device_serial]
+# 环境：REAL_DEVICE_GATE_SKIP=1 仅跳过（不得用于标功能完成）
+
+set -euo pipefail
+
+SDK_URL="${WORKPHONE_SDK_URL:-http://127.0.0.1:8899}"
+EXPECT_SERIAL="${1:-}"
+FAIL=0
+
+if [[ "${REAL_DEVICE_GATE_SKIP:-}" == "1" ]]; then
+  echo "SKIP: REAL_DEVICE_GATE_SKIP=1（不得用于功能完成验收）"
+  exit 0
+fi
+
+echo "== 真机门禁 =="
+
+if ! command -v adb >/dev/null 2>&1; then
+  echo "FAIL: adb 未安装"
+  exit 1
+fi
+
+adb_out=$(adb devices 2>/dev/null | tail -n +2 | grep -v '^$' | grep -v 'offline' || true)
+if [[ -z "$adb_out" ]]; then
+  echo "FAIL: 无 ADB 在线设备（真机铁律：禁止无设备标完成）"
+  FAIL=1
+else
+  echo "OK: ADB 设备"
+  echo "$adb_out" | sed 's/^/  /'
+fi
+
+if [[ -n "$EXPECT_SERIAL" ]]; then
+  if ! echo "$adb_out" | grep -q "$EXPECT_SERIAL"; then
+    echo "FAIL: 期望 serial 不在线: $EXPECT_SERIAL"
+    FAIL=1
+  else
+    echo "OK: 期望 serial 在线: $EXPECT_SERIAL"
+  fi
+fi
+
+health=$(curl -s -m 8 "${SDK_URL}/health" 2>/dev/null || echo "")
+if [[ -z "$health" ]]; then
+  echo "FAIL: SDK health 无响应 ($SDK_URL)"
+  FAIL=1
+else
+  echo "OK: SDK health"
+  device_count=$(python3 -c "import json,sys; d=json.loads(sys.argv[1]); print(len(d.get('device_ids') or []))" "$health" 2>/dev/null || echo 0)
+  if [[ "$device_count" -lt 1 ]]; then
+    echo "FAIL: SDK 无在线 Agent 设备（真机铁律）"
+    FAIL=1
+  else
+    echo "OK: SDK 在线设备数=$device_count"
+  fi
+fi
+
+if [[ "$FAIL" -ne 0 ]]; then
+  echo "== 门禁未通过 =="
+  exit 1
+fi
+
+echo "== 门禁通过 =="
+exit 0
--- a/开发文档/8、部署/05-测试验收/scripts/workphone_bff_smoke.sh
+++ b/开发文档/8、部署/05-测试验收/scripts/workphone_bff_smoke.sh
@@ -16,8 +16,9 @@ if [[ -z "$DEVICE_ID" ]]; then
 fi

 if [[ -z "$DEVICE_ID" ]]; then
-  echo "无在线设备，跳过 device 级测试"
-  exit 0
+  echo "FAIL: 无在线设备（真机铁律：禁止无设备标冒烟通过）"
+  echo "提示: 连接真机 Agent 后重试；仅 SDK 层检查时显式 REAL_DEVICE_GATE_SKIP=1"
+  exit 1
 fi

 echo "device_id: $DEVICE_ID"
--- a/开发文档/8、部署/05-测试验收/真机开发每轮检查清单.md
+++ b/开发文档/8、部署/05-测试验收/真机开发每轮检查清单.md
@@ -0,0 +1,44 @@
+# Agent 真机开发 · 每轮检查清单
+
+> **强制** · 打印本清单或在 Agent 对话中逐项核对  
+> **真源**：`开发文档/2、架构/01-总览/真机开发铁律.md`  
+> **门禁**：`scripts/real_device_gate.sh`
+
+---
+
+## A. 开发前
+
+- [ ] 已读 `机擎/SKILL.md` §〇.七 或 `.cursor/rules/real-device-mandatory.mdc`
+- [ ] 目标功能 **不是** 占位/mock/假 success
+- [ ] 已知验收 action/API（矩阵或 BFF 映射表）
+
+## B. 环境（须 exit 0）
+
+```bash
+bash 开发文档/8、部署/05-测试验收/scripts/real_device_gate.sh [serial]
+```
+
+- [ ] ADB 有 `device` 状态 serial
+- [ ] SDK `:8899/health` → `devices_online >= 1`
+- [ ] （可选）`bash .../workphone_bff_smoke.sh <serial>` 存客宝 BFF 链
+
+## C. 实现
+
+- [ ] 代码改在 `sdk/app` / `sdk/agent` / Hook JS / BFF（存客宝）
+- [ ] **无** `NotImplemented` / 硬编码 success 冒充真机结果
+- [ ] Hook action 已在真机 `hook/probe` 或 `hook/execute` 验证
+
+## D. 留痕（标完成前）
+
+- [ ] 证据目录：`8、部署/05-测试验收/<YYYY-MM-DD>_*/` 或矩阵日期目录
+- [ ] `工作日志.md` 追加（含 serial、条数、HTTP、E2E x/y）
+- [ ] 存客宝对接变更同步 `cunkebao_v3/开发文档/工作手机对接/`
+
+## E. 进度
+
+- [ ] **阿表**：无 B/C/D 证据 **不标** ✅ / 100%
+- [ ] 卡若复盘 📌 含真机数字
+
+---
+
+**违规定义**：跳过 B 仍标完成 · mock pytest 当 E2E · BFF 未连真机 SDK
--- a/机擎/SKILL.md
+++ b/机擎/SKILL.md
@@ -36,6 +36,22 @@ related:

 ---

+## 〇.七、真机开发铁律（强制 · 每次必守）
+
+> **真源**：`开发文档/2、架构/01-总览/真机开发铁律.md` · Cursor：`.cursor/rules/real-device-mandatory.mdc`
+
+| 铁律 | 说明 |
+|------|------|
+| **机器 + 卡若AI** | 功能由机擎在卡若AI 能力下落地，**不得**只做文档/接口壳 |
+| **真机验收** | Root 工作机 + ADB + Agent WS + Frida；**禁止** mock/占位冒充完成 |
+| **留痕** | 证据 → `8、部署/05-测试验收/`；无真机戳 **阿表不得标 100%** |
+| **存客宝链** | BFF → SDK → 真机 E2E 至少一次（对称文档见存客宝 `开发文档/工作手机对接/`） |
+| **pytest 边界** | 离线 mock 仅回归，**≠** 功能交付（见 § 〇.六 单元/离线 pytest） |
+
+**违规定义**：固定假 success、矩阵 ✅ 无证据、Hook 未 attach 即标通过 → 立即补真机或回滚。
+
+---
+
 ## 〇.二、快速读取并了解整个项目

 **每次进入项目或新人上手**，按下列顺序读取即可快速建立全局认知：
@@ -216,7 +232,7 @@ related:

 ### 3.2.1 飞书群复盘（完整功能交付时**必触发**）

-> **定义「完整功能」**：本轮已落地可验收能力（代码/配置已保存）、**至少一次**验证通过（curl/E2E/真机）、**工作日志已写**；非仅讨论或半成品。
+> **定义「完整功能」**：本轮已落地可验收能力（代码/配置已保存）、**至少一次真机验证通过**（`real_device_gate.sh` 或 E2E/Hook 留痕；**禁止** mock/无设备标通过）、**工作日志已写**；非仅讨论、占位或半成品。细则：[真机开发铁律](../开发文档/2、架构/01-总览/真机开发铁律.md)

 | 项 | 约定 |
 |----|------|
--- a/机擎/阿服/SKILL.md
+++ b/机擎/阿服/SKILL.md
@@ -32,6 +32,8 @@ related:

 **岗位职责**：Docker、端口、环境、凭证；开发文档 8、部署；7、数据库；代码 scripts/、docker。

+**真机铁律（强制）**：部署/一键脚本须能在 **真机环境** 复现（ADB + Agent + Frida）；见 [机擎/SKILL.md §〇.七](../SKILL.md) 与 `frida_workphone_oneclick.sh`。
+
 ---

 ## 一、关键路径（均相对工作手机仓库）
--- a/机擎/阿机/SKILL.md
+++ b/机擎/阿机/SKILL.md
@@ -32,6 +32,8 @@ related:

 **岗位职责**：服务端、设备端、Agent、unified、设备连接、adb/health；开发文档 6、后端；代码模块 sdk/app、sdk/agent。

+**真机铁律（强制）**：见 [机擎/SKILL.md §〇.七](../SKILL.md) — 实现必须在 Root 真机可调；**禁止占位/mock 冒充交付**；证据归档 `8、部署/05-测试验收/`。
+
 ---

 ## 一、关键路径（均相对工作手机仓库）
--- a/机擎/阿桥/SKILL.md
+++ b/机擎/阿桥/SKILL.md
@@ -32,6 +32,8 @@ related:

 **岗位职责**：业务收口、交互矩阵、PHP/TS SDK、unified契约；开发文档 5、接口；代码 sdk/php-sdk、sdk/typescript-sdk。

+**真机铁律（强制）**：BFF/SDK 契约须 **BFF → SDK → 真机** curl 验收；见 [机擎/SKILL.md §〇.七](../SKILL.md) 与存客宝 `开发文档/工作手机对接/`。
+
 ---

 ## 一、业务收口（服务端 ↔ 中间层 ↔ 设备端）
--- a/机擎/阿端/SKILL.md
+++ b/机擎/阿端/SKILL.md
@@ -32,6 +32,8 @@ related:

 **岗位职责**：联调、E2E、手册、体验验收；开发文档 4、前端；9、手册；代码/联调与测试（sdk/tests 等）。

+**真机铁律（强制）**：**拒收无真机证据的完成标记**；E2E 须真机 serial + 留痕；见 [机擎/SKILL.md §〇.七](../SKILL.md)。
+
 ---

 ## 一、关键路径（均相对工作手机仓库）
--- a/机擎/阿表/SKILL.md
+++ b/机擎/阿表/SKILL.md
@@ -33,6 +33,8 @@ related:

 **岗位职责**：进度总表、工作日志、多端并行、验收；对应 `开发文档/10、项目管理/`；无代码模块，只看文档与总表。

+**真机铁律（强制）**：无真机证据（`8、部署/05-测试验收/` 或 E2E 数字）**不得**在总表/日志标 ✅ 或 100%；见 [机擎/SKILL.md §〇.七](../SKILL.md)。
+
 ---

 ## 一、关键路径（均相对工作手机仓库）