From ccfd5784073f830addfbd07b946b0ebf6b734338 Mon Sep 17 00:00:00 2001 From: Manus AI Date: Sun, 24 May 2026 14:28:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E9=93=81=E5=BE=8B):=20=E7=9C=9F=E6=9C=BA?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E5=BC=BA=E5=88=B6=E8=A7=84=E5=88=99=20=C2=B7?= =?UTF-8?q?=20=E9=9B=86=E7=BE=A4=E7=9C=9F=E6=BA=90=E4=B8=8E=E9=97=A8?= =?UTF-8?q?=E7=A6=81=E8=84=9A=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 机器+卡若AI联合开发；禁止占位/mock冒充交付。新增真机开发铁律、real_device_gate.sh、每轮检查清单；机擎§〇.七与五人SKILL同步；冒烟无设备改exit1。 Co-authored-by: Cursor --- 开发文档/10、项目管理/工作日志.md | 215 +++++++++++++++++- 开发文档/10、项目管理/开发进度总表.md | 6 +- 开发文档/2、架构/01-总览/真机开发铁律.md | 59 +++++ 开发文档/2、架构/01-总览/系统架构.md | 5 + .../02-业务对接/存客宝BFF与工作手机SDK映射表.md | 40 +++- .../05-测试验收/scripts/real_device_gate.sh | 64 ++++++ .../05-测试验收/scripts/workphone_bff_smoke.sh | 5 +- .../8、部署/05-测试验收/真机开发每轮检查清单.md | 44 ++++ 机擎/SKILL.md | 18 +- 机擎/阿服/SKILL.md | 2 + 机擎/阿机/SKILL.md | 2 + 机擎/阿桥/SKILL.md | 2 + 机擎/阿端/SKILL.md | 2 + 机擎/阿表/SKILL.md | 2 + 14 files changed, 449 insertions(+), 17 deletions(-) create mode 100644 开发文档/2、架构/01-总览/真机开发铁律.md create mode 100755 开发文档/8、部署/05-测试验收/scripts/real_device_gate.sh create mode 100644 开发文档/8、部署/05-测试验收/真机开发每轮检查清单.md diff --git a/开发文档/10、项目管理/工作日志.md b/开发文档/10、项目管理/工作日志.md index bb3d3f15fc..42f083b9f4 100644 --- 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） + --- \ No newline at end of file diff --git a/开发文档/10、项目管理/开发进度总表.md b/开发文档/10、项目管理/开发进度总表.md index b404a1ba9c..4aeee729f6 100644 --- 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） ``` --- diff --git a/开发文档/2、架构/01-总览/真机开发铁律.md b/开发文档/2、架构/01-总览/真机开发铁律.md new file mode 100644 index 0000000000..5dd8333056 --- /dev/null +++ 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/ +├── _*/ +└── 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` | + +--- + +**每次对话、每次开发、每次验收 — 按本铁律执行。** diff --git a/开发文档/2、架构/01-总览/系统架构.md b/开发文档/2、架构/01-总览/系统架构.md index bda446c4f6..74c4684e71 100644 --- 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） diff --git a/开发文档/5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md b/开发文档/5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md index e7257cf6f6..4fe959787f 100644 --- 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` diff --git a/开发文档/8、部署/05-测试验收/scripts/real_device_gate.sh b/开发文档/8、部署/05-测试验收/scripts/real_device_gate.sh new file mode 100755 index 0000000000..f07ec48247 --- /dev/null +++ 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 diff --git a/开发文档/8、部署/05-测试验收/scripts/workphone_bff_smoke.sh b/开发文档/8、部署/05-测试验收/scripts/workphone_bff_smoke.sh index 9020c8ecd4..096d3ffe9f 100755 --- 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" diff --git a/开发文档/8、部署/05-测试验收/真机开发每轮检查清单.md b/开发文档/8、部署/05-测试验收/真机开发每轮检查清单.md new file mode 100644 index 0000000000..c3f2b0d49c --- /dev/null +++ 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 ` 存客宝 BFF 链 + +## C. 实现 + +- [ ] 代码改在 `sdk/app` / `sdk/agent` / Hook JS / BFF（存客宝） +- [ ] **无** `NotImplemented` / 硬编码 success 冒充真机结果 +- [ ] Hook action 已在真机 `hook/probe` 或 `hook/execute` 验证 + +## D. 留痕（标完成前） + +- [ ] 证据目录：`8、部署/05-测试验收/_*/` 或矩阵日期目录 +- [ ] `工作日志.md` 追加（含 serial、条数、HTTP、E2E x/y） +- [ ] 存客宝对接变更同步 `cunkebao_v3/开发文档/工作手机对接/` + +## E. 进度 + +- [ ] **阿表**：无 B/C/D 证据 **不标** ✅ / 100% +- [ ] 卡若复盘 📌 含真机数字 + +--- + +**违规定义**：跳过 B 仍标完成 · mock pytest 当 E2E · BFF 未连真机 SDK diff --git a/机擎/SKILL.md b/机擎/SKILL.md index 34add7eb89..1976921e7f 100644 --- 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) | 项 | 约定 | |----|------| diff --git a/机擎/阿服/SKILL.md b/机擎/阿服/SKILL.md index b846c4c2fa..2c4c0c2f93 100644 --- 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`。 + --- ## 一、关键路径（均相对工作手机仓库） diff --git a/机擎/阿机/SKILL.md b/机擎/阿机/SKILL.md index 2a145f466b..47c7ca1f16 100644 --- 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-测试验收/`。 + --- ## 一、关键路径（均相对工作手机仓库） diff --git a/机擎/阿桥/SKILL.md b/机擎/阿桥/SKILL.md index 77ebb3aa0d..95d1d05476 100644 --- 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) 与存客宝 `开发文档/工作手机对接/`。 + --- ## 一、业务收口（服务端 ↔ 中间层 ↔ 设备端） diff --git a/机擎/阿端/SKILL.md b/机擎/阿端/SKILL.md index a2d301379a..9f276a6b2d 100644 --- a/机擎/阿端/SKILL.md +++ b/机擎/阿端/SKILL.md @@ -32,6 +32,8 @@ related: **岗位职责**：联调、E2E、手册、体验验收；开发文档 4、前端；9、手册；代码/联调与测试（sdk/tests 等）。 +**真机铁律（强制）**：**拒收无真机证据的完成标记**；E2E 须真机 serial + 留痕；见 [机擎/SKILL.md §〇.七](../SKILL.md)。 + --- ## 一、关键路径（均相对工作手机仓库） diff --git a/机擎/阿表/SKILL.md b/机擎/阿表/SKILL.md index 8b9f0bd21e..7dda0abacc 100644 --- a/机擎/阿表/SKILL.md +++ b/机擎/阿表/SKILL.md @@ -33,6 +33,8 @@ related: **岗位职责**：进度总表、工作日志、多端并行、验收；对应 `开发文档/10、项目管理/`；无代码模块，只看文档与总表。 +**真机铁律（强制）**：无真机证据（`8、部署/05-测试验收/` 或 E2E 数字）**不得**在总表/日志标 ✅ 或 100%；见 [机擎/SKILL.md §〇.七](../SKILL.md)。 + --- ## 一、关键路径（均相对工作手机仓库）