siyu-bank/workphone-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 上传开发文档与机擎

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
卡若
2026-02-24 17:29:32 +08:00
parent ef4c68c66c
commit 1574f14aaf
67 changed files with 17696 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -3,9 +3,7 @@
# 不上传的目录
资料/
机擎/
.cursor/
开发文档/
scripts/
*.py[cod]
__pycache__/

BIN
开发文档/10、项目管理/AI开发流程.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 MiB

19
开发文档/10、项目管理/README.md Normal file
View File

@@ -0,0 +1,19 @@
# 10、项目管理
**项目**：工作手机SDK v3.0（进度以本目录**开发进度总表**为唯一入口，按 **M1～M12 业务/功能模块** 做精度管理；已完成与待开发均以总表为准。）本项目由**本仓库内**的「存客宝项目管理」Skill 总控（`存客宝项目管理/SKILL.md`）+「工作手机项目管理」执行（`Skill-工作手机项目管理/SKILL.md`，负责人存机）；卡若AI 与之为交互关系，每次使用前先整理项目，再分配工作与更新迭代。
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 **96%**；M1～M4、M7～M11 已 100%，M5 约 75%、M8 约 95%，M6 待做、M12 约 50%。模块拆解见 [2、架构/系统架构.md](../2、架构/系统架构.md) §3.0。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [开发进度总表.md](开发进度总表.md) | **唯一进度文档**：M1～M12 完成度、待办、验证 |
| [工作日志.md](工作日志.md) | 每次对话记录，持续追加 |
| [验收与项目说明.md](验收与项目说明.md) | 验收清单、对接清单、差距分析、开发计划与说明（合并） |
**多 Agent 并行**：[多端并行开发模块拆解.md](多端并行开发模块拆解.md)（设备端/服务端/中间层/数据库四层拆解、待开发项、并行边界与分工）。

46
开发文档/10、项目管理/五方向学习与调查结论.md Normal file
View File

@@ -0,0 +1,46 @@
# 五方向学习与调查结论
> **来源**：用户要求安置五个问题方向，向卡若AI 分配学习与调查并继续完成
> **执行**：机擎按岗位认领；学习资料来自卡若AI _共享模块/task_decomposer、机擎 references、开发文档与代码
> **更新**：2026-02-07
---
## 一、五个问题方向与分配
| 方向 | 执行人 | 学习/调查来源 | 结论摘要 |
|------|--------|----------------|----------|
| **1. 接口契约与 PHP/TS SDK 一致性** | 阿桥 | 卡若AI 深度理解与任务拆解；接口规范 §1.5、§2.1；unified.php / typescript-sdk | 契约已对齐；TS 返回类型已修正为 sent/failed/total、error_code/timeout_seconds |
| **2. 联调可观测与排障** | 阿机 | 卡若AI 验证不通过_回溯思考；unified/ws_hub 日志 | 已有 [message/send]、[_send_via_sdk]、[ws_hub] 关键日志；排障看 9、手册 与 E2E 指南 |
| **3. 部署与环境一致性** | 阿服 | 卡若AI deploy/、references；sdk/app/.env.example、start_sdk.sh、8、部署 | .env.example 与 8、部署/README 已覆盖；跨环境靠环境变量与本地环境凭证 |
| **4. E2E 与联调验收清单** | 阿端 | 卡若AI 思考与总结格式；sdk/tests、9、手册 | test_api + test_wechat_e2e 已就绪；验收清单见 SDK操作手册、微信消息E2E验证指南 |
| **5. 进度与文档可维护** | 阿表 | 卡若AI 任务拆解、definitions_of_done；开发进度总表、工作日志 | 总表 100% 与当前一致；9、手册 README 已改为 100%；文档≤3 主文档规则未超 |
---
## 二、向卡若AI 学习与调查的资料（统一引用）
- **执行流程**：`_共享模块/task_decomposer/references/卡若AI统一执行流程_所有模型必守.md`
- **深度理解与拆解**：`_共享模块/task_decomposer/references/深度理解与任务拆解_市面最佳实践调研.md`
- **验证不通过**：`_共享模块/task_decomposer/references/验证不通过_回溯思考与解决方案查找流程.md`
- **工作手机中间层**：机擎 `references/工作手机中间层抽象.md`、阿桥 `阿桥-ISFJ-对接中间层/中间层/SKILL.md`
机擎执行时：先理解问题→查上述资料与开发文档/代码→执行（改代码/文档）→汇报；有疑可继续向卡若AI 请教并沉淀到本目录或 references。
---
## 三、本轮已完成的变更
- **阿桥**：TypeScript SDK `sendMessage` 返回类型增加 `error_code`、`timeout_seconds`；`batchSendMessage` 返回类型改为 `sent`/`failed`/`total`（与 unified 一致）。PHP SDK 已支持 timeout_seconds 与 batch-send 路径，无需改。
- **阿服**：无代码变更；8、部署/README 此前已补「跨环境一致性」；.env.example 已含 MONGO_URI、MESSAGE_SEND_TIMEOUT 等。
- **阿端**：9、手册/README 进度描述更新为 100%，并注明 E2E 需本地环境。
- **阿表**：本文档新增；工作日志已追加本条；总表保持 100%。
- **阿机**：无代码变更；可观测性已在系统架构 §二 与接口规范中体现。
---
## 四、后续建议
- 存客宝/触客宝接入时，直接使用 PHP/TS SDK 最新类型，便于处理 `data.success`、`data.error_code`、`data.sent/failed/total`。
- 联调排障：先看 `/health`、设备列表、[message/send] 日志与 9、手册/微信消息E2E验证指南。
- 新需求或新接口：先更新 unified 与 接口规范，再由阿桥同步两 SDK 与本文档。

539
开发文档/10、项目管理/工作日志.md Normal file
View File

@@ -0,0 +1,539 @@
# 工作手机SDK v3.0 - 工作日志
> **管理Skill**: 工作手机/机擎/SKILL.md（火炬+五人）
> **记录规则**: 每次对话结束自动追加
---
### 2026-02-24 | 工作手机项目上传 Gitea + GitHub
**执行人**: 阿服
**本次完成**:
- [x] 初始化 Git 仓库，配置 .gitignore（排除 github-repos、.gradle、app/build、.env 等）
- [x] 首次提交（230 文件）
- [x] 创建 GitHub 私有仓库 fnvtk/workphone-sdk 并推送成功
- [x] 配置 Gitea 远程 fnvtk/workphone-sdk
- [ ] Gitea 推送：需先在 open.quwanzhi.com 手动创建仓库（Push to create 未开启）
**仓库**:
- GitHub: https://github.com/fnvtk/workphone-sdk
- Gitea: http://open.quwanzhi.com:3000/fnvtk/workphone-sdk（创建后可推送）
**同步脚本**: scripts/sync_to_gitea_github.sh
---
### 2026-02-10 | 全量开发文档整合与完善（调研→开发文档10目录）
**执行人**: 机擎全员（阿表/阿机/阿桥/阿端/阿服）
**本次完成**:
**整合调研材料（12份→开发文档）**:
- [x] 创建 `1、需求/技术调研与方案选型.md` — 融合12份调研文件，含选型结论+竞品对比+复刻路径
- [x] 合并 `成本与需求澄清.md` 入 `项目概述.md`（≤3文档规则）
**架构扩展**:
- [x] 创建 `2、架构/Hook通道与多设备多服务器架构.md` — 双通道路由+Frida集成+多设备多服务器
- [x] 合并 `对接与方案补充.md` 入 `系统架构.md`（≤3文档规则）
**前端管理端**:
- [x] 创建 `4、前端/管理端前端开发规范（毛玻璃风格）.md` — 苹果毛玻璃UI+React组件+页面设计
**接口设计**:
- [x] 创建 `5、接口/Hook模块管理接口.md` — 模块CRUD+脚本管理+设备模块+Hook事件API
**后端开发指南**:
- [x] 创建 `6、后端/docs/07-设备端Hook开发指南.md` — FridaManager/ScriptLoader/HookExecutor/EventReporter完整代码
- [x] 创建 `6、后端/docs/08-微信Hook脚本开发.md` — 微信Frida脚本+Java Hook+Syscall拦截+逆向方法
**部署扩展**:
- [x] 创建 `8、部署/设备端Hook安装部署.md` — Root/Gadget安装+多设备批量部署+验证清单
- [x] 合并 `部署流程与提示词.md` 入 `本地Docker部署指南.md`（≤3文档规则）
**项目管理**:
- [x] 重写 `10、项目管理/开发进度总表.md` — Phase 1-4全量任务拆解（H1-H33 + F1-F14 + D1-D8）
- [x] 更新全部受影响目录README索引（1/2/4/5/8共5个）
**文档统计**:
- 新增：7个文档
- 合并：3个文档（数据完整保留）
- 删除：3个已合并的原文件
- 所有目录均满足≤3主文档规则
**项目进度**: 65%（Phase 1完成100%, Phase 2-4待开发）
**下一步**: 按开发进度总表Phase 2.1开始执行（H1-H5架构扩展，预估2天）
---
### 2026-02-10 | 机擎复刻 Frida 与奥创的管理与注入 — 实现路径
**执行人**: 机擎（阿机/阿桥）
**本次完成**:
- [x] 撰写《机擎复刻Frida与奥创管理注入_实现路径.md》
- [x] 结论：可实现，需新增 Hook 通道、模块管理、Frida 集成
- [x] 复刻目标：奥创管理形态（模块列表、Scope、启用/禁用）、Frida 注入形态（attach、脚本、rpc.exports）
- [x] 能力提取：VivWxjz 等效（消息同步、发消息、联系人、朋友圈）
- [x] 四阶段实现路径：架构扩展 → 设备端 Frida 集成 → Hook 脚本开发 → 私域管理端
- [x] 整体架构图、优先级表、约束与风险
**文档路径**: `资料/机擎复刻Frida与奥创管理注入_实现路径.md`
---
### 2026-02-10 | 奥创微信控制接口与插件提取复用指南
**执行人**: 机擎（阿机/阿桥）
**本次完成**:
- [x] 创建《奥创微信控制接口与插件提取复用指南.md》
- [x] 插件与包名完整清单（XESlciw Manager、VivWxjz、AI数智员工）
- [x] 007 云端 API 接口推断与机擎映射
- [x] VivWxjz libvivwxjz.so 导出符号、Syscall 拦截点
- [x] 机擎 WechatSkill 与奥创能力一一对照
- [x] 复用开发建议与速查表
**文档路径**: `资料/奥创微信控制接口与插件提取复用指南.md`
---
### 2026-02-10 | XESlciw 与 Frida 及机擎详细对比分析
**执行人**: 机擎（阿机/阿桥）
**本次完成**:
- [x] 创建《XESlciw与Frida及机擎详细对比分析.md》
- [x] XESlciw vs Frida 架构、能力、接口清单对比
- [x] 机擎统一 API、WebSocket、设备端接口全量清单
- [x] 三者功能合适度分析及选型建议
- [x] 按场景/开发阶段的选型指引
**文档路径**: `资料/XESlciw与Frida及机擎详细对比分析.md`
---
### 2026-02-07 | 设备端完善 - 自动与服务器交互、能力声明、配置拉取
**执行人**: 机擎（阿机）
**进度**: 设备端 M8 保持 100%；目的达成「设备自动与服务器交互、拥有完整设备端」
**本次完成**:
- [x] 注册后上报 `agent_started` 事件，服务端可记录设备上线
- [x] 设备能力声明增加 `skill_wechat/douyin/xhs/xianyu`、`event`、`device_request`
- [x] 连接成功后自动向服务端 `get_config`，收到 `device_request_ack` 后应用下发的 `heartbeat_interval`
- [x] README 明确：server_url 填基础地址、设备自动注册并上报能力、自动与服务器交互
**下一步**: 维护与迭代；可选 E2E 全绿、M6 抓包按需。
---
### 2026-02-10 | 第7次对话 - 机擎团队合并升级（1人=1目录+能力增强）
**执行人**: 火炬（卡若AI 大总管协同）
**对话主题**: 机擎AI开发小组全面合并升级，清理重复目录，整合Skill+学习材料+外部资源
**任务**:
- 将5人的多个重复目录合并为1人=1目录的精简结构
- 整合所有Skill内容（去重合并）
- 从卡若AI学习相关能力（全栈开发、工作手机中间层、数据管理等9个Skill）
- 搜索GitHub/SkillsMP获取外部开发能力（uiautomator2、DroidRun、Fremko、Android-MCP等）
- 升级机擎总控SKILL.md为v2.0
**完成项**:
- [x] 读取并分析5人共13个重复目录的所有SKILL/README内容
- [x] 从卡若AI获取9个相关Skill（火炬全栈开发、工作手机中间层、金盾数据管理等）
- [x] 搜索GitHub获取5个相关开源项目（uiautomator2 v3.5.0、DroidRun 7.6k⭐、Fremko、Android-MCP、mcp-android-server）
- [x] 搜索SkillsMP获取4类推荐Skill（CI/CD 6091个、测试 3464个、LLM&AI 10372个、代码质量 3185个）
- [x] 创建新的合并目录：阿表/、阿机/、阿桥/、阿端/、阿服/（各含1个合并版SKILL.md v2.0）
- [x] 每人SKILL.md包含：人设+技能点(去重合并)+学习材料(卡若AI+GitHub+SkillsMP)+关键路径+触发词
- [x] 阿桥：将3个重复目录（阿桥-ISFJ-对接中间层/、阿桥-ISFJ-接口对齐-业务与中间层/、阿桥-对接中间层/）+ 业务SKILL + 中间层SKILL 合并为1个完整SKILL
- [x] 升级机擎/SKILL.md至v2.0：新增§七外部能力增强（卡若AI+GitHub+SkillsMP）、更新§九.2目录结构
- [x] 删除11个旧重复目录
- [x] 更新.cursor/rules/workphone.mdc路径引用
- [x] 本条工作日志
**目录变更**（清理前→清理后）:
- 清理前：每人2-3个目录（共13个），命名不统一
- 清理后：每人1个目录（共5个），命名简洁（阿表/、阿机/、阿桥/、阿端/、阿服/）
- 已删除：阿表-ISTJ-进度验收/、阿表-ISTJ-盯节点-进度与验收/、阿机-ISTP-后端Agent/、阿机-ISTP-上机就干-服务端设备端Agent/、阿桥-ISFJ-对接中间层/、阿桥-ISFJ-接口对齐-业务与中间层/、阿桥-对接中间层/、阿端-ENFP-联调/、阿端-ENFP-先跑通-联调与体验/、阿服-ISTJ-部署/、阿服-ISTJ-稳了再发-部署与环境/
**进度变化**: 无模块百分比变更（纯结构优化与能力增强）
**遇到的问题**: 无
**下次计划**:
- 按需继续迭代各人SKILL中的学习材料
- 可选：从SkillsMP/GitHub安装具体Skill到项目中
- 继续维护与E2E全绿
**提示词摘要**: "机擎小组合并升级，1人=1目录，整合所有Skill，整合学习材料，从卡若AI和GitHub/SkillsMP搜索相关开发能力，让团队具备完整开发工作手机SDK的能力"
---
## 日志记录
---
### 2026-02-07 | 五方向学习与调查：向卡若AI 分配学习并完成
**用户诉求**：安置五个问题方向，向卡若AI 分配学习与调查相应资料并继续完成。
**执行人**：阿桥、阿机、阿端、阿服、阿表（按机擎 § 一.二 分配）
**学习与调查来源**：卡若AI _共享模块/task_decomposer/references（深度理解与任务拆解、验证不通过回溯）、机擎 references/工作手机中间层抽象.md、阿桥中间层 SKILL、开发文档/5、8、9、10 与 sdk 代码。
**完成项**:
- [x] **方向1（阿桥）**：接口契约与 PHP/TS SDK 一致性——调查 unified 与两 SDK；TS 的 sendMessage 返回类型增加 error_code、timeout_seconds；batchSendMessage 返回类型改为 sent/failed/total，与接口规范一致。PHP 已对齐。
- [x] **方向2（阿机）**：联调可观测与排障——结论：已有 [message/send]、[ws_hub] 等关键日志；排障见 9、手册 与 E2E 验证指南。
- [x] **方向3（阿服）**：部署与环境一致性——结论：.env.example、8、部署/README 已覆盖；无新增变更。
- [x] **方向4（阿端）**：E2E 与联调验收——9、手册/README 进度描述更新为 100%；验收清单见 SDK操作手册、微信消息E2E验证指南。
- [x] **方向5（阿表）**：进度与文档可维护——新增 10、项目管理/五方向学习与调查结论.md；总表与工作日志一致，100%。
**下一步**：维护与迭代；接入方使用 SDK 时按最新类型处理 success/error_code 与 batch 的 sent/failed/total。
---
### 2026-02-07 | 本地模型驱动架构审视 + 机擎全员执行与反馈
**驱动**：本地模型（qwen2.5:1.5b）输出 5 条架构方向 → 机擎按岗位落实并文档化。
**执行人**：阿桥、阿机、阿服（按机擎 § 一.二 分配）
**完成项**:
- [x] **接口契约（阿桥）**：接口规范 §2.1 响应与实现对齐——data.success/message_id/error/error_code/timeout_seconds；§1.5 补充 batch_send 返回 data.sent/failed/total 及 503 说明。
- [x] **模块边界（阿机）**：系统架构 §二 增加「模块边界」——unified→_execute_skill→ws_hub/ADB；设备端 WebSocket；扩展仅改 Skill 与路由。
- [x] **容错与可观测（阿机）**：系统架构 §二 表格增加「容错与可观测」原则与实现方式。
- [x] **部署跨环境（阿服）**：8、部署/README 增加「跨环境一致性」——环境变量、init_db、端口与凭证入口。
- [x] **进度**：总进度仍 100%；本轮为文档与架构补齐，无代码功能变更。
**下一步**：若你还有架构/体验上的顾虑，直接说（例如：需要更多监控指标、想收口某类错误码），机擎继续按「提问→分配→执行→反馈」循环；否则可进入日常维护与可选 E2E 全绿。
---
### 2026-02-07 | 下一步：数据库初始化可运行 + 凭证与文档补齐
**执行人**: 金盾（数据库线）
**完成项**:
- [x] **init_db 带认证运行**：使用本地凭证 `MONGO_URI=mongodb://admin:admin123@localhost:27017` 执行 `sdk/app/scripts/init_db.py`，devices/commands/execution_logs/capture_data/messages/api_keys 索引已创建。
- [x] **凭证与文档**：本地环境凭证.md 增加 SDK 用 MongoDB 的 MONGO_URI 与首次建库命令；7、数据库/README 增加「首次建库与索引」节。
- [x] **sdk/app/.env.example**：新增示例，含 MONGO_URI、REDIS_URL、MESSAGE_SEND_TIMEOUT 等注释项。
**下一步**: 维护与迭代；可选 E2E 全绿、M6 抓包按需。
---
### 2026-02-07 | 全量完成：联调契约 + AI Agent 联调 + 验收与进度 100%
**执行人**: 机擎（按顺序全量完成）
**完成项**:
- [x] **抖/红/闲鱼与设备端联调**：在 开发文档/5、接口/接口规范.md 增加 §1.5「服务端与设备端联调契约」— 下发格式、设备端 response 格式、send_message/get_messages/batch_send_message 的 data 约定。
- [x] **AI Agent 设备端联调**：agent.py 的 _execute_agent_task 接入 SkillExecutor；含「微信」走 execute_wechat_task、「抖音」走 execute_douyin_task，其余走 execute_command；ImportError 时降级返回「任务引擎未加载」。
- [x] **微信 E2E**：SDK 健康 200、无设备时 message/send 返回 200+设备离线；E2E 脚本已就绪，全绿需本地「SDK+Agent+模拟器微信」后执行 test_wechat_e2e.py。
- [x] **完整测试与验收**：开发进度总表更新为 100%；M5/M12 标为 100%；验收与项目说明、多端拆解摘要已更新；待完成调整为「E2E 全绿可选、M6 抓包按需」。
**下一步**: 维护与迭代；可选：本地跑通 E2E 全绿、M6 抓包按需。
---
### 2026-02-07 | 开发优先：发消息超时可配置 + E2E + 机擎 Skill 开发优先节
**执行人**: 机擎（开发目标驱动）
**目标**: 以开发项目、推进功能为主；吸收并优化 Skill 内容服务开发。
**完成项**:
- [x] **发消息超时可配置**：`config.MESSAGE_SEND_TIMEOUT`（默认 60s），环境变量可覆盖；`_send_via_sdk` 使用该配置
- [x] **超时返回明确**：设备响应超时返回 HTTP 200 + `data.success=false` + `data.error="timeout"`，不无限挂起
- [x] **关键日志**：`[message/send]` 入参与通道、`[_send_via_sdk]` 下发与超时、`[ws_hub]` 设备响应超时
- [x] **E2E**：`test_wechat_e2e.py` 在 error=timeout 时判 API 行为正确；微信消息E2E验证指南 增加「超时与可观测性」节
- [x] **机擎 Skill**：增加 § 〇.六「开发优先」— 下一步开发项、关键代码路径、发消息超时说明、E2E 命令、启动命令；原则为「做开发、推进项目，不是为了整理」
- [x] **开发进度总表**：总进度 98%→99%；M5 88%→90%；待完成中「发消息超时可配置」标为已完成
**下一步**: 抖/红/闲鱼 与设备端联调、微信 E2E 全绿、AI Agent 设备端联调、完整测试与验收。
---
### 2026-02-07 | 执行整理+学习安排落地、开发文档入口改为机擎
**执行人**: 机擎（阿表/阿机）
**完成项**: 快速读取（README、进度总表、工作日志）、adb/health 检查（模拟器在线、8899 返回 200）；开发文档 README 与工作日志管理 Skill 改为机擎；本对话按 § 〇.二～〇.五 执行与学习。
**下一步**: 抖/红/闲鱼联调、微信 E2E、AI Agent 联调、完整验收。
---
### 2026-02-07 | 发消息超时问题转交火炬处理并建任务单
**执行人**: 卡若AI（转交）
**对话主题**: 工作手机微信给吉咪宇发消息接口超时 → 通知负责人、处理问题、学习优化、新功能开发清楚
**任务**:
- 将问题与改进要求通知到指定管理人员（火炬）
- 建立可执行任务单，包含处理动作、学习与优化、新功能开发清单
**完成项**:
- [x] 创建火炬待办任务文档：`卡若AI/04_卡火（火）/火炬/存客宝项目管理/工作手机业务/references/待办-火炬-发消息超时与可观测性优化.md`
- [x] 任务内容：问题描述与根因分析、必须完成的处理动作、学习与优化要求、新功能开发清单（F1 超时可配置、F2 可观测性、F3 to_id 文档、F4 E2E 验证、F5 异步可选）
- [x] 工作手机业务 SKILL 增加「待办」小节，索引该任务文档，便于火炬优先处理
**下一步**:
- 火炬按任务单完成：复现与定位 → 修复 → 学习沉淀 → 完成 F1～F4（高/中优先级）→ 更新状态与工作日志
**提示词摘要**: "然后把这个通知到指定的相应的那个管理的人员，然后把这个问题处理掉，然后让他学习并且优化一下新的一个功能，帮我开发清楚"
---
### 2026-02-07 | 开发进度同步存客宝 + 闲鱼服务端 Skill + 持续开发与测试约定
**执行人**: 火炬（存客宝项目管理）
**对话主题**: 开发进度同步到存客宝、存客宝具备该技能、继续开发直至完整完成并完成测试
**任务**:
- 每次开发完成后将进度同步给存客宝（存客宝需具备该技能）
- 继续开发直至项目完整完成并完成测试
**完成项**:
- [x] 存客宝侧新增「工作手机开发进度」文档：`cunkebao_v3/开发文档/工作手机对接/工作手机开发进度.md`（由工作手机项目同步更新）
- [x] 存客宝项目管理 Skill 增加「每次对话结束 → 同步进度到存客宝」步骤（2.3 第 4 条）；存客宝每一次均可在此查看最新进度
- [x] 服务端闲鱼 Skill：新建 `sdk/app/skills/xianyu/`（skill.py + __init__.py），与设备端闲鱼对应，供 unified 路由与 ADB 占位
- [x] 开发进度总表更新：总进度 97%→98%，M5 85%→88%，闲鱼服务端路由标记已完成
- [x] 本次进度已同步到存客宝侧文档
**进度变化**:
- 总进度: 97% → **98%**
- M5 脚本引擎: 85% → **88%**
**下一步**:
- 服务端抖/红/闲鱼与设备端联调；微信消息 E2E 验证；AI Agent 设备端联调
- 完整测试与验收（按 9、手册 与 验收清单 执行至 100%）
**提示词摘要**: "继续开发，把开发进度同步给存客宝，每一次存客宝都需要有这个技能，继续往下开发直到完整完成整个项目并完成测试"
---
### 2026-02-07 | 中间层抽象为 Skill，完成度 100%
**执行人**: 火炬（工作手机中间层 Skill）
**对话主题**: 中间层抽象成 Skill，负责功能模块开发及与服务端/设备端交付
**任务**:
- 将中间层抽象为卡若AI Skill，负责各功能模块开发与 unified/设备端契约对齐
- 继续开发至 100% 并汇报进度
**完成项**:
- [x] 新增「工作手机中间层」Skill：`存客宝项目管理/工作手机中间层/SKILL.md`
- [x] 新增 references：`工作手机中间层抽象.md`（职责、功能模块、协作关系、交付物）
- [x] 存客宝项目管理 SKILL 增加中间层分配与触发词、文件索引
- [x] 多端拆解 §3 标明负责 Skill，中间层与当前 unified 契约 100% 对齐
- [x] PHP/TS SDK 已覆盖消息/好友/群/标签/朋友圈/设备/AI/批量/快捷方法（含 batchAddFriend、xianyuSend、soulSend）
**进度变化**:
- 中间层（与当前契约对齐）: **100%**
- 未完成百分比: **0%**
**下一步**:
- unified 新增或变更接口时，由工作手机中间层 Skill 在两 SDK 中同步更新
- 新中间层（如触客宝专用 API）按产品排期单独交付
**提示词摘要**: "把中间层也抽象成一个 skill，负责各功能模块开发、跟服务端/设备端 skill 的交互都通过你来安排跟交付，继续往下开发直到完成百分百"
---
### 2026-02-06 20:00 | 第1次对话 - SDK核心开发
**执行人**: 火炬
**对话主题**: 工作手机SDK完整开发
**任务**:
- 创建SDK核心服务（FastAPI + WebSocket）
- 开发统一API路由（消息、好友、群聊、标签、朋友圈）
- 开发PHP SDK客户端
- 开发TypeScript SDK客户端
- 创建存客宝对接文档
**完成项**:
- [x] SDK服务端框架（FastAPI）
- [x] WebSocket Hub设备管理
- [x] 统一API路由（unified.py）全部接口
- [x] PHP SDK（WorkPhoneClient.php）含所有功能
- [x] TypeScript SDK（typescript-sdk/）含所有功能
- [x] 存客宝对接文档
**进度变化**:
- 服务端API: 0% → 75%
- 存客宝对接: 0% → 55%
- 基础设施: 0% → 95%
**遇到的问题**: 无
**下次计划**: 完善微信技能实现、部署测试
**提示词摘要**: "把SDK开发出来让存客宝直接使用工作手机的各个接口"
---
### 2026-02-06 20:15 | 第2次对话 - Agent端技能开发
**执行人**: 火炬
**对话主题**: 完善设备端Agent技能实现
**任务**:
- 完善微信Agent端技能（群聊、标签、朋友圈等）
- 创建抖音Agent端技能
- 创建小红书Agent端技能
**完成项**:
- [x] 微信技能全功能（群管理、标签、朋友圈、批量操作）
- [x] 抖音技能（私信、粉丝、评论、视频互动）
- [x] 小红书技能（私信、粉丝、评论、笔记互动、笔记发布）
**进度变化**:
- 微信技能: 40% → 75%
- 抖音技能: 0% → 50%
- 小红书技能: 0% → 50%
- 设备端Agent: 30% → 65%
**遇到的问题**: 无
**下次计划**: 服务端路由补全、真机测试
**提示词摘要**: "创建抖音和小红书技能实现"
---
### 2026-02-06 20:30 | 第3次对话 - 本地部署和项目管理
**执行人**: 火炬
**对话主题**: 本地Docker全量部署 + 创建项目管理Skill
**任务**:
- 启动工作手机SDK服务
- 创建存客宝Docker部署配置
- 创建存客宝PHP集成（WorkPhoneSDK.php）
- 创建项目管理Skill
- 创建开发进度总表
- 端口规划登记
**完成项**:
- [x] SDK服务启动（Docker, 端口8899）
- [x] 存客宝docker-compose.yml（MySQL + Redis + Server + 前端）
- [x] Server Dockerfile（PHP 7.4 + Nginx）
- [x] Cunkebao Dockerfile（Node 20 + Nginx）
- [x] Touchkebao Dockerfile（Node 20 + Nginx）
- [x] PHP SDK集成到存客宝后端（WorkPhoneSDK.php）
- [x] SDK配置文件（config/workphone.php）
- [x] 一键启动脚本（start.sh）
- [x] 启动说明文档
- [x] 项目管理Skill创建
- [x] 开发进度总表创建
- [x] 端口规划完成
**进度变化**:
- 本地部署: 0% → 35%
- 存客宝对接: 40% → 55%
- 开发文档: 40% → 55%
**遇到的问题**:
- Apple Silicon (M4 Pro) 不兼容x86 Android Docker镜像，需改用AVD方案
**下次计划**:
- 配置Android Studio AVD虚拟机
- 启动MySQL并导入存客宝数据
- 构建并启动存客宝前端
- 补全开发文档各子目录
**提示词摘要**: "创建项目管理Skill、本地部署、开发文档展开、虚拟手机、端口管理"
---
### 2026-02-06 20:45 | 第4次对话 - Skill创建+文档展开+虚拟机+部署
**执行人**: 火炬 + 卡资
**对话主题**: 创建存客宝项目管理Skill + 开发文档全面展开 + 红米13虚拟机 + 本地部署
**完成项**:
- [x] 创建存客宝项目管理Skill（SKILL.md + 检查脚本）
- [x] 创建开发进度总表（含所有模块百分比）
- [x] 创建工作日志系统（自动记录每次对话）
- [x] 端口规划登记表（避免冲突）
- [x] 安装Android模拟器（SDK + ARM64系统镜像）
- [x] 创建红米13 AVD虚拟机（1080x2400, Android 14）
- [x] 启动模拟器成功（emulator-5554在线）
- [x] 系统状态检查脚本（check_system.sh）
- [x] 展开开发文档：6、后端/SDK服务端实现文档.md
- [x] 展开开发文档：6、后端/Agent端技能实现文档.md
- [x] 展开开发文档：7、数据库/数据库设计文档.md
- [x] 展开开发文档：8、部署/本地Docker部署指南.md
- [x] 展开开发文档：9、手册/系统使用手册.md
- [x] 展开开发文档：10、项目管理/开发进度追踪.md
- [x] MySQL + Redis Docker配置并开始下载
- [x] 修复端口冲突（8080→8081，微信占用）
- [x] 注册Skill到卡若AI总索引
**进度变化**:
- 开发文档: 55% → 70%
- 本地部署: 35% → 50%
- 总体: 42% → 48%
**遇到的问题**:
- Apple Silicon不兼容x86 Android Docker镜像 → 改用AVD方案 ✅
- 端口8080被微信占用 → 后端改用8081 ✅
- MySQL镜像下载较慢（网络限制）→ 后台下载中
**下次计划**:
- 等MySQL下载完成并初始化数据
- 构建并启动存客宝后端服务
- 验证完整闭环（前端→后端→SDK→手机）
**提示词摘要**: "创建Skill管理存客宝项目、展开开发文档、部署虚拟手机、本地Docker全量部署"
---
### 2026-02-07 | 第5次对话 - 设备端功能补全（存客宝 Skill 检查 + 开发文档）
**执行人**: 火炬
**对话主题**: 按存客宝项目管理 Skill 检查开发文档，完成设备端（手机端）剩余功能
**任务**:
- 用存客宝 Skill 检查整体开发文档
- 完成设备端剩余功能（闲鱼 Skill、抖音/小红书补全）
- 按整体开发需求继续研发设备端
**完成项**:
- [x] 新建闲鱼 Skill（`agent/skills/xianyu/`）：`__init__.py` + `skill.py`
- [x] 闲鱼实现：send_message、get_messages、get_contacts、add_friend、follow_user、unfollow_user、batch_send_message（包名 com.taobao.idlefish）
- [x] 在 `skills/__init__.py` 注册 xianyu（get_skill + SKILL_REGISTRY）
- [x] 在 skill_executor 中增加闲鱼包名映射（com.taobao.idlefish → xianyu）
- [x] 抖音/小红书设备端补全：send_message 增加 @retry、@with_error_handling（与微信一致）
- [x] 闲鱼 send_message 增加相同错误处理装饰器
- [x] 更新开发进度总表（M5 85%、M8 100%，总进度 97%）
- [x] 更新多端并行开发模块拆解（设备端闲鱼/抖/红标为已完成）
- [x] 工作日志本条记录
**进度变化**:
- M5 脚本引擎: 75% → 85%
- M8 Agent 端: 95% → 100%
- 总进度: 96% → 97%
**遇到的问题**: 无
**下次计划**:
- 服务端抖音/小红书/闲鱼 unified 路由补全（routers/unified.py、app/skills/xianyu/）
- 微信消息 E2E 端到端验证
- 可选：M6 抓包、M12 AI Agent 集成
**提示词摘要**: "存客宝 skill 检查开发文档、完成设备端剩余功能、按整体开发需求继续研发设备端"
---
### 2026-02-07 | 第6次对话 - 存客宝 AI 下服务端/设备端 SDK 抽象与 event/device_request
**执行人**: 火炬
**对话主题**: 在存客宝 AI 底下写服务端与设备端 SDK 抽象；设备端需通知服务端时通过 event/device_request；解决与验证问题
**任务**:
- 在存客宝 AI（卡若AI 存客宝项目管理）下把服务端、设备端 SDK 写成抽象文档
- 设备端能力与依赖抽象，需要服务端时通知服务端 SDK 来操作
- 实现 event/device_request 协议并验证
**完成项**:
- [x] 新建 `存客宝项目管理/references/工作手机服务端SDK抽象.md`：服务端职责、入口、设备端→服务端/服务端→设备端消息类型、统一接口与 Skill 路由、验证要点
- [x] 新建 `存客宝项目管理/references/工作手机设备端SDK抽象.md`：设备端职责、能力抽象（连接/Skill/通知服务端）、依赖、开发与验证要点
- [x] 在存客宝项目管理 SKILL.md 九、相关文件索引 中增加上述两个 SDK 抽象文档引用
- [x] 服务端 ws_hub：处理 `event`、`device_request`、`status_report`；实现 `_handle_device_request`（get_config、log_result），回 `device_request_ack`
- [x] 设备端 agent：`_send_event(event, data)`、`_send_device_request(action, params)`；技能执行完成后自动发 `event`（skill_done）；处理 `device_request_ack`
- [x] 服务端 SDK 抽象文档增加「验证要点」小节
**进度变化**: 无模块百分比变更（文档与协议补全）
**遇到的问题**: 无
**下次计划**:
- 服务端 unified 抖/红/闲鱼路由补全
- 可选：event/device_request 落库（MongoDB）或转发业务
**提示词摘要**: "存客宝 AI 底下把服务端设备端 SDK 写上、设备端抽象出来、需要交互服务端时通知服务端 SDK、继续开发、解决所有问题和验证"

252
开发文档/10、项目管理/开发进度总表.md Normal file
View File

@@ -0,0 +1,252 @@
# 工作手机SDK v3.0 - 开发进度总表
> **唯一进度文档** | 更新：2026-02-10
> 含：现有模块 + Hook增强模块 + 管理端 + 多设备部署 全量任务拆解
---
## 一、项目进度总览
```
整体进度: ████████████████░░░░░░░░░ 65%
已完成（Phase 1: SDK基础） ████████████████████████ 100% ← M1-M12
进行中（Phase 2: Hook增强） ░░░░░░░░░░░░░░░░░░░░░░░░ 0% ← H1-H12
规划中（Phase 3: 管理端） ░░░░░░░░░░░░░░░░░░░░░░░░ 0% ← F1-F14
规划中（Phase 4: 部署上线） ░░░░░░░░░░░░░░░░░░░░░░░░ 0% ← D1-D8
```
---
## 二、Phase 1: SDK基础（已完成 100%）
| 模块 | 名称 | 进度 | 验证 |
|:----:|------|:----:|------|
| M1 | SDK服务端骨架 | ✅ 100% | `curl http://localhost:8899/health` |
| M2 | WebSocket Hub | ✅ 100% | 设备连接后可收发消息 |
| M3 | 设备管理 | ✅ 100% | `curl http://localhost:8899/api/v3/devices` |
| M4 | 统一API路由 | ✅ 100% | POST /message/send 成功 |
| M5 | 微信Skill | ✅ 100% | 发消息/加好友/发朋友圈 |
| M6 | 抓包服务 | ⏸️ 按需 | Frida SSL Bypass |
| M7 | 数据库 | ✅ 100% | MongoDB + Redis |
| M8 | 设备端Agent | ✅ 100% | Agent连接+执行指令 |
| M9 | 抖音Skill | ✅ 100% | 私信/粉丝/评论 |
| M10 | 小红书Skill | ✅ 100% | 私信/粉丝/笔记 |
| M11 | 部署 | ✅ 100% | Docker一键部署 |
| M12 | AI Agent | ✅ 100% | 自然语言控制 |
---
## 三、Phase 2: Hook增强（0% → 目标100%）
### 3.1 架构扩展（预估2天）
| ID | 任务 | 文件/模块 | 预估 | 状态 | 依赖 |
|:--:|------|-----------|:----:|:----:|:----:|
| H1 | Channel枚举增加HOOK | `sdk/app/routers/unified.py` | 1h | ⬜ | - |
| H2 | 设备能力扩展(supports_hook等) | `sdk/app/services/device_manager.py` | 1h | ⬜ | - |
| H3 | ChannelRouter路由逻辑(Hook优先) | `sdk/app/routers/unified.py` | 2h | ⬜ | H1,H2 |
| H4 | WebSocket协议扩展(hook_event) | `sdk/app/ws_hub.py` | 2h | ⬜ | H1 |
| H5 | 降级机制(Hook失败→u2) | `sdk/app/services/unified_service.py` | 2h | ⬜ | H3 |
### 3.2 设备端Frida集成（预估5天）
| ID | 任务 | 文件/模块 | 预估 | 状态 | 依赖 |
|:--:|------|-----------|:----:|:----:|:----:|
| H6 | 创建hook/目录结构 | `sdk/agent/hook/` | 0.5h | ⬜ | - |
| H7 | HookConfig配置模型 | `sdk/agent/hook/config.py` | 0.5h | ⬜ | - |
| H8 | FridaManager(生命周期) | `sdk/agent/hook/frida_manager.py` | 4h | ⬜ | H6,H7 |
| H9 | ScriptLoader(脚本管理) | `sdk/agent/hook/script_loader.py` | 3h | ⬜ | H6 |
| H10 | HookExecutor(指令执行) | `sdk/agent/hook/hook_executor.py` | 2h | ⬜ | H8,H9 |
| H11 | EventReporter(事件上报) | `sdk/agent/hook/event_reporter.py` | 2h | ⬜ | H6 |
| H12 | Agent主文件扩展(通道选择) | `sdk/agent/agent.py` | 2h | ⬜ | H8-H11 |
| H13 | 能力上报扩展 | `sdk/agent/agent.py` | 1h | ⬜ | H12 |
### 3.3 Hook脚本开发（预估10天）
| ID | 任务 | 文件/模块 | 预估 | 状态 | 依赖 |
|:--:|------|-----------|:----:|:----:|:----:|
| H14 | 脚本框架+工具函数 | `hook/scripts/common.js` | 2h | ⬜ | - |
| H15 | 微信：消息接收Hook | `hook/scripts/wechat_hook.js` | 4h | ⬜ | H14 |
| H16 | 微信：联系人获取 | `hook/scripts/wechat_hook.js` | 2h | ⬜ | H14 |
| H17 | 微信：发送消息Hook | `hook/scripts/wechat_hook.js` | 8h | ⬜ | H14 |
| H18 | 微信：好友请求监听 | `hook/scripts/wechat_hook.js` | 2h | ⬜ | H14 |
| H19 | 微信：添加/通过好友 | `hook/scripts/wechat_hook.js` | 4h | ⬜ | H17 |
| H20 | 微信：朋友圈发布 | `hook/scripts/wechat_hook.js` | 4h | ⬜ | H17 |
| H21 | 微信：朋友圈浏览/点赞 | `hook/scripts/wechat_hook.js` | 3h | ⬜ | H20 |
| H22 | 微信：群管理 | `hook/scripts/wechat_hook.js` | 4h | ⬜ | H17 |
| H23 | Syscall拦截(网络层) | `hook/scripts/syscall_hook.js` | 6h | ⬜ | H14 |
| H24 | 微信多版本适配测试 | - | 4h | ⬜ | H15-H22 |
### 3.4 模块管理API（预估2天）
| ID | 任务 | 文件/模块 | 预估 | 状态 | 依赖 |
|:--:|------|-----------|:----:|:----:|:----:|
| H25 | MongoDB hook_modules集合 | `sdk/app/models/` | 1h | ⬜ | - |
| H26 | 模块CRUD API | `sdk/app/routers/modules.py` | 4h | ⬜ | H25 |
| H27 | 设备模块状态API | `sdk/app/routers/modules.py` | 2h | ⬜ | H26 |
| H28 | 脚本上传/下载API | `sdk/app/routers/scripts.py` | 3h | ⬜ | H25 |
| H29 | Hook事件历史API | `sdk/app/routers/hooks.py` | 2h | ⬜ | H4 |
### 3.5 测试（预估2天）
| ID | 任务 | 预估 | 状态 | 依赖 |
|:--:|------|:----:|:----:|:----:|
| H30 | Frida连接单元测试 | 2h | ⬜ | H8 |
| H31 | HookExecutor单元测试 | 2h | ⬜ | H10 |
| H32 | 模块API集成测试 | 2h | ⬜ | H26 |
| H33 | Hook E2E测试(真机) | 4h | ⬜ | H15-H17 |
**Phase 2 总预估：~88h（约11个工作日）**
---
## 四、Phase 3: 管理端（0% → 目标100%）
| ID | 任务 | 预估 | 状态 | 依赖 |
|:--:|------|:----:|:----:|:----:|
| F1 | 项目初始化(Next.js+Tailwind+Shadcn) | 2h | ⬜ | - |
| F2 | 毛玻璃基础组件库 | 4h | ⬜ | F1 |
| F3 | 布局(侧边栏+导航+骨架屏) | 4h | ⬜ | F2 |
| F4 | 仪表盘页面 | 6h | ⬜ | F3 |
| F5 | 设备列表+详情页 | 8h | ⬜ | F3 |
| F6 | 模块管理页面 | 6h | ⬜ | F3,H26 |
| F7 | 消息中心(实时流) | 6h | ⬜ | F3,H29 |
| F8 | 任务调度页面 | 4h | ⬜ | F3 |
| F9 | 风控中心页面 | 4h | ⬜ | F3 |
| F10 | 数据统计页面 | 6h | ⬜ | F3 |
| F11 | 系统设置页面 | 3h | ⬜ | F3 |
| F12 | WebSocket实时通信集成 | 4h | ⬜ | F1,H4 |
| F13 | API对接+错误处理 | 4h | ⬜ | F1 |
| F14 | 响应式适配+动画优化 | 4h | ⬜ | F2-F11 |
**Phase 3 总预估：~65h（约8个工作日）**
---
## 五、Phase 4: 部署上线（0% → 目标100%）
| ID | 任务 | 预估 | 状态 | 依赖 |
|:--:|------|:----:|:----:|:----:|
| D1 | frida-server安装脚本 | 2h | ⬜ | - |
| D2 | Agent安装脚本(含Hook) | 3h | ⬜ | H12 |
| D3 | 批量部署脚本 | 2h | ⬜ | D1,D2 |
| D4 | 服务端Docker更新(含模块管理) | 3h | ⬜ | H26 |
| D5 | 管理端Docker化+Nginx | 2h | ⬜ | F14 |
| D6 | 多服务器注册中心 | 4h | ⬜ | D4 |
| D7 | 5台真机测试验证 | 8h | ⬜ | D1-D5 |
| D8 | 上线文档+操作手册 | 4h | ⬜ | D7 |
**Phase 4 总预估：~28h（约3.5个工作日）**
---
## 六、全量里程碑
```
Phase 1: SDK基础 ✅ 已完成
│
▼
Phase 2: Hook增强 ⬜ 11个工作日
│
│ 3.1 架构扩展 2天 ──┐
│ 3.2 设备端Frida 5天 ──┤── 可并行
│ 3.3 Hook脚本 10天 ──┤
│ 3.4 模块管理API 2天 ──┘
│ 3.5 测试 2天
│
▼
Phase 3: 管理端 ⬜ 8个工作日 ← 与Phase 2可部分并行
│
│ 前端基础(F1-F3) 2天 ──┐
│ 核心页面(F4-F8) 5天 ──┤── 与Phase 2.3并行
│ 增值页面(F9-F11) 2天 ──┘
│
▼
Phase 4: 部署上线 ⬜ 3.5个工作日
│
│ 脚本+Docker(D1-D5) 2天
│ 真机测试(D7) 1天
│ 文档(D8) 0.5天
│
▼
上线！ 预计总工期: 约20个工作日（并行执行后约15天）
```
---
## 七、开发优先级排序
### 7.1 P0 — 必须完成（核心链路）
| 优先级 | 任务组 | ID列表 | 预估 |
|:------:|--------|--------|:----:|
| P0-1 | 架构扩展（Hook通道） | H1-H5 | 8h |
| P0-2 | 设备端Frida核心 | H6-H13 | 15h |
| P0-3 | 微信Hook(收发消息) | H14-H17 | 16h |
| P0-4 | 管理端基础框架 | F1-F5 | 24h |
| P0-5 | 设备安装脚本 | D1-D3 | 7h |
| P0-6 | 真机验证 | D7 | 8h |
### 7.2 P1 — 重要功能
| 优先级 | 任务组 | ID列表 | 预估 |
|:------:|--------|--------|:----:|
| P1-1 | 模块管理API | H25-H29 | 12h |
| P1-2 | 微信Hook(好友/群) | H18-H22 | 17h |
| P1-3 | 管理端核心页面 | F6-F8, F12-F13 | 24h |
| P1-4 | 测试 | H30-H33 | 10h |
| P1-5 | 版本适配 | H24 | 4h |
### 7.3 P2 — 增值功能
| 优先级 | 任务组 | ID列表 | 预估 |
|:------:|--------|--------|:----:|
| P2-1 | Syscall拦截 | H23 | 6h |
| P2-2 | 风控+统计页面 | F9-F11 | 13h |
| P2-3 | 多服务器注册中心 | D6 | 4h |
| P2-4 | 响应式+动画 | F14 | 4h |
---
## 八、验证方式速查
| 功能 | 验证命令 |
|------|----------|
| 服务端健康 | `curl http://localhost:8899/health` |
| 设备列表 | `curl http://localhost:8899/api/v3/devices` |
| 发消息(u2) | `curl -X POST http://localhost:8899/api/v3/message/send -d '...'` |
| 发消息(Hook) | `curl -X POST ... -d '{"channel":"hook",...}'` |
| Frida状态 | `adb shell "su -c 'pidof wp-agent'"` |
| 模块列表 | `curl http://localhost:8899/api/v3/modules` |
| 设备模块 | `curl http://localhost:8899/api/v3/devices/{id}/modules` |
| Hook事件 | WebSocket订阅 `/hook/events/stream` |
| 管理端 | 浏览器访问 `http://localhost:3000` |
---
## 九、测试凭证
| 项 | 值 |
|----|-----|
| 测试账号 | 15880802661 |
| 密码 | kr123456 |
| SDK地址 | http://localhost:8899 |
| 管理端地址 | http://localhost:3000 |
| MongoDB | mongodb://localhost:27017/workphone_sdk |
| Redis | redis://localhost:6380 |
---
## 十、文档索引
| 目录 | 核心文档 | 说明 |
|------|----------|------|
| 1、需求 | 技术调研与方案选型.md | 12份调研整合+选型结论 |
| 2、架构 | Hook通道与多设备多服务器架构.md | 双通道+多设备架构设计 |
| 4、前端 | 管理端前端开发规范（毛玻璃风格）.md | 苹果毛玻璃UI设计规范 |
| 5、接口 | Hook模块管理接口.md | 模块管理+脚本+事件API |
| 6、后端/docs | 07-设备端Hook开发指南.md | Frida集成完整代码 |
| 6、后端/docs | 08-微信Hook脚本开发.md | 微信Hook脚本开发 |
| 8、部署 | 设备端Hook安装部署.md | 真机安装+多设备部署 |
| 10、项目管理 | 本文档 | 全量进度+任务拆解 |

135
开发文档/10、项目管理/验收与项目说明.md Normal file
View File

@@ -0,0 +1,135 @@
# 验收与项目说明（合并）
> 合并自：验收清单、对接清单、差距分析与完成报告、开发计划、项目管理说明与计划 | 更新：2026-02-07
> **进度入口**：本目录以 [开发进度总表.md](开发进度总表.md) 为唯一进度文档，按 **M1～M12 业务/功能模块** 管理。
---
## 一、验收清单摘要
| 验收标准 | 状态 | 验证方式 |
|----------|------|----------|
| 本机访问并控制所有服务（存客宝/触客宝/SDK/Swagger） | ✅ | localhost:3000/3001/8081/8899、8899/docs |
| 工作手机状态与服务器数据同步 | ✅ | /health、devices_online、last_heartbeat、project_id |
| 微信任务执行结果回传 | ✅ | send_command、response、408 超时 |
| 数据/设备管理/操作闭环 | ✅ | 本地 DB、注册→心跳→监控、服务器→SDK→回传 |
---
## 二、对接清单摘要
| 对接项 | 状态 | 说明 |
|--------|------|------|
| 存客宝 ↔ 工作手机 | ✅ | PHP/TS SDK、统一 API、登录认证 |
| SDK ↔ 设备 | ✅ | WebSocket、注册、心跳、指令 ACK、ADB 模式 |
| SDK ↔ 数据库 | ✅ | MongoDB、Redis、MySQL |
| 设备 ↔ 微信 | ✅ | 消息发送/接收：Skill+unified+超时已就绪；E2E 脚本 test_wechat_e2e.py（需环境）；通讯录/聊天记录 📋 后期 |
---
## 三、差距分析摘要（需求 vs 实现）
- 环境/数据库/统一账号/不用奥创/服务器唯一控制/设备状态/心跳可配置/指令 ACK/三大闭环：**均已 ✅**。
- 微信消息发送接收：**✅ Skill + unified + 超时 + E2E 脚本已就绪**；完整 E2E 需本地 SDK+Agent+模拟器微信；通讯录/聊天记录：**📋 后期**。
- 遗留：通讯录/聊天记录（中）；M6 抓包（按需）。
---
## 四、开发计划摘要（6 周 MVP）
| 阶段 | 核心交付 | 验收 |
|------|----------|------|
| Week 1-2 | 服务端框架 + WebSocket | 设备连接、心跳、设备列表 API |
| Week 3-4 | Agent + Frida + 脚本引擎 | 远程执行 UI、微信基础脚本 |
| Week 5 | 微信/抖音/小红书脚本 | 发消息/获取消息 |
| Week 6 | 存客宝对接、集成测试 | 替换奥创调用 |
---
## 五、项目管理说明
- **进度只看两处**：[开发进度总表.md](开发进度总表.md) + [2、架构/系统架构.md](../2、架构/系统架构.md) §3.0 模块拆解。
- **工作日志**：每次对话追加 [工作日志.md](工作日志.md)。
- 原《AI开发引擎》《模板使用说明书》《开发计划》全文、《开发进度追踪》等已合并入本说明；详细任务分解见开发计划历史。
---
## 六、多端并行开发模块拆解（合并保留，不丢数据）
> 四层：设备端 | 服务端 | 中间层 | 数据库。代码根：设备端 `sdk/agent/`，服务端 `sdk/app/`，中间层 `sdk/php-sdk/`、`sdk/typescript-sdk/`。
- **设备端**（`sdk/agent/`）：agent.py、skill_executor、skills/wechat|douyin|xhs|xianyu 已 100%；_execute_agent_task 已接 SkillExecutor（微信/抖音任务可执行）；待：Frida/抓包（按需）。
- **服务端**（`sdk/app/`）：unified、ws_hub、device_manager、adb、skills 已 100%；联调契约见 5、接口/接口规范 §1.5；M6 抓包按需。
- **中间层**（`sdk/php-sdk/`、`sdk/typescript-sdk/`）：PHP/TS SDK 与 unified 契约 100%；unified 新增时两 SDK 同步更新。
- **数据库**：MongoDB/Redis/MySQL 已就绪；按模块扩展集合/表。
- **并行边界**：改 agent.py/ws_hub/device_manager 时与改 Skill/unified 的人协调；中间层仅依赖服务端契约，冲突少。
---
## 附录 A：验收清单全文（合并保留）
### 验收标准 1：本机访问并控制所有服务
| 检查项 | 状态 | 验证方式 |
|--------|------|----------|
| 存客宝前端 | ✅ | http://localhost:3000 |
| 触客宝前端 | ✅ | http://localhost:3001 |
| 存客宝后端 | ✅ | curl POST localhost:8081/v1/auth/login |
| SDK 服务 | ✅ | curl localhost:8899/health |
| AI 数字员工界面 | ✅ | http://localhost:8899/static/index.html |
| Swagger 文档 | ✅ | http://localhost:8899/docs |
### 验收标准 2：工作手机状态与服务器数据同步
| 检查项 | 状态 | 验证方式 |
|--------|------|----------|
| 设备在线 | ✅ | GET /health 或 /api/v3/devices |
| 心跳更新 | ✅ | 设备 last_heartbeat 刷新 |
| 项目归属 | ✅ | project_id: cunkebao |
### 验收标准 3：微信任务执行结果回传
| 检查项 | 状态 | 验证方式 |
|--------|------|----------|
| 指令下发 | ✅ | send_command 支持 |
| 响应回传 | ✅ | response + command_id |
| 超时处理 | ✅ | 408 超时返回 |
### 验收标准 4：所有功能闭环正常运行
| 闭环 | 状态 | 说明 |
|------|------|------|
| 数据闭环 | ✅ | 本地 DB + 存客宝 + SDK |
| 设备管理闭环 | ✅ | 注册 → 心跳 → 状态监控 |
| 操作闭环 | ✅ | 服务器 → SDK → 设备 → 回传 |
### 快速验证命令
```bash
curl -s localhost:8899/health | jq .
curl -s localhost:8899/health | jq .devices_online
curl -s -X POST http://localhost:8081/v1/auth/login -H "Content-Type: application/json" -d '{"account":"15880802661","password":"kr123456","typeId":1}' | jq .code
```
---
## 附录 B：对接清单全文（合并保留）
| 层级 | 对接项 | 状态 | 说明 |
|------|--------|------|------|
| 存客宝↔工作手机 | PHP/TS SDK、统一 API、登录 | ✅ | /api/v3/message/send 等 |
| SDK↔设备 | WebSocket、注册、心跳、指令 ACK、ADB | ✅ | ws://localhost:8899/ws/device/{id} |
| SDK↔数据库 | MongoDB、Redis、MySQL | ✅ | workphone_sdk、6380 |
| 设备↔微信 | 消息发送/接收、通讯录、聊天记录 | 🔧/📋 | Skill 已实现，E2E 待验证；通讯录/聊天记录后期 |
---
## 附录 C：差距分析与完成报告全文（合并保留）
| 需求项 | 实现状态 | 说明 |
|--------|----------|------|
| 环境/数据库/统一账号/不用奥创/服务器唯一控制/设备状态/心跳可配置/指令 ACK/三大闭环 | ✅ | 均已实现 |
| 微信消息发送/接收 | 🔧 | Skill 已有，待完整 E2E |
| 通讯录/聊天记录 | 📋 | 后期扩展 |
**遗留**：微信消息 E2E（高）、通讯录/聊天记录（中）。**启动验证**：`cd sdk && ./scripts/start_sdk.sh`；存客宝后端 `cd cunkebao_v3/Server && php -S 0.0.0.0:8081 -t public`。

24
开发文档/1、需求/README.md Normal file
View File

@@ -0,0 +1,24 @@
# 1、需求
**项目**：工作手机SDK v3.0（存客宝AI手机控制引擎，替代奥创+Hook增强）
**规则**：本目录除本 README 外最多 **3 个主文档**。
**当前状态**：Phase 1 需求100%完成；Phase 2 Hook增强需求已整理。进度以 [开发进度总表](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [项目概述.md](项目概述.md) | 项目背景、愿景、成本估算（含原成本与需求澄清内容） |
| [业务需求.md](业务需求.md) | 功能清单、用户画像、KPI、竞品对比 |
| [技术调研与方案选型.md](技术调研与方案选型.md) | **12份调研整合**：奥创拆解+全网方案对比+复刻路径+选型结论 |
---
## 合并记录
- 2026-02-10: `成本与需求澄清.md` 内容合并入 `项目概述.md` 附录
- 2026-02-10: 新增 `技术调研与方案选型.md`，整合资料目录全部12份调研文档

301
开发文档/1、需求/业务需求.md Normal file
View File

@@ -0,0 +1,301 @@
# 工作手机SDK v3.0 业务需求文档
> 创建日期：2026-01-26 | 负责人：卡若 | 状态：已确认
---
## 一、项目背景与目标 (金)
### 1.1 背景
存客宝目前通过**第三方代理服务器**（奥创：s2.siyuguanli.com）控制手机设备：
| 痛点 | 影响 |
|------|------|
| **依赖第三方** | 数据安全无保障，服务稳定性不可控 |
| **成本高昂** | 300-500元/台/月，100台设备年费36万+ |
| **功能受限** | 仅支持微信，无法扩展抖音/小红书/Soul等 |
| **无法定制** | 业务需求无法快速响应 |
### 1.2 解决方案
开发**自有的工作手机SDK v3.0**，核心特点：
| 能力 | 说明 |
|------|------|
| **任意APP抓包** | Frida通用Hook，不限于特定APP |
| **任意APP控制** | uiautomator2脚本引擎，新APP只需写脚本 |
| **远程互联网控制** | 设备可在任意位置，通过互联网连接云端 |
| **私有化部署** | 数据自主，无限设备扩展 |
### 1.3 项目愿景
**一套SDK，控制所有APP**
无论是微信、抖音、小红书，还是Soul、探探、陌陌，甚至未来的新APP——只需编写脚本，即可快速对接。
---
## 二、目标用户
| 用户角色 | 画像描述 | 核心痛点 | 使用场景 |
|:---|:---|:---|:---|
| 存客宝运营人员 | 使用存客宝系统的员工 | 需要批量管理多个社交账号 | 日常私信回复、客户跟进 |
| 存客宝合作方 | 入驻存客宝的企业 | 需要自动化营销、客资获取 | 批量发消息、自动回复 |
| 技术开发人员 | 对接SDK的开发者 | 需要快速集成、扩展新APP | API调用、脚本开发 |
| 系统管理员 | 运维管理人员 | 需要设备监控、故障排查 | 设备管理、日志查看 |
---
## 三、功能清单 (木) - MVP
### 3.1 核心功能模块
| 模块 | 功能点 | 优先级 | 验收标准 | 依赖 |
|:---|:---|:---:|:---|:---|
| **设备管理** | 设备注册 | P0 | 设备可主动连接服务器并注册 | WebSocket |
| | 设备列表查询 | P0 | 可查询所有设备及其状态 | MongoDB |
| | 设备状态监控 | P0 | 实时显示在线/离线状态 | Redis |
| | 设备截图 | P0 | 可远程获取设备屏幕截图 | uiautomator2 |
| **通用控制** | 点击操作 | P0 | 可远程点击指定坐标 | uiautomator2 |
| | 文字点击 | P0 | 可点击指定文字元素 | uiautomator2 |
| | 输入文字 | P0 | 可在当前焦点输入文字 | uiautomator2 |
| | 滑动操作 | P0 | 可执行上下左右滑动 | uiautomator2 |
| | UI树获取 | P1 | 可获取当前页面UI结构XML | uiautomator2 |
| **微信脚本** | 发送消息 | P0 | 可发送文字消息给指定好友 | 脚本引擎 |
| | 获取消息 | P1 | 可获取消息列表 | 脚本引擎 |
| | 好友列表 | P1 | 可获取好友列表 | 脚本引擎 |
| | 添加好友 | P2 | 可通过微信号添加好友 | 脚本引擎 |
| | 通过验证 | P2 | 可通过好友请求 | 脚本引擎 |
| **抖音脚本** | 发送私信 | P0 | 可发送私信 | 脚本引擎 |
| | 获取私信 | P1 | 可获取私信列表 | 脚本引擎 |
| | 回复评论 | P2 | 可回复视频评论 | 脚本引擎 |
| **小红书脚本** | 发送私信 | P0 | 可发送私信 | 脚本引擎 |
| | 点赞笔记 | P2 | 可点赞指定笔记 | 脚本引擎 |
| **抓包服务** | 开始抓包 | P1 | 可启动指定APP的SSL抓包 | Frida |
| | 停止抓包 | P1 | 可停止抓包 | Frida |
| | 获取数据 | P1 | 可获取抓包数据 | MongoDB |
### 3.2 用户故事卡
**US-001: 设备连接**
- **As a** 系统管理员
- **I want** 手机设备能自动连接到云端服务器
- **So that** 我可以远程管理所有设备
- **验收标准**：
- [ ] 设备安装Agent后自动连接
- [ ] 断线后自动重连
- [ ] 连接状态实时更新
**US-002: 微信消息发送**
- **As a** 存客宝运营人员
- **I want** 通过API发送微信消息
- **So that** 我可以批量回复客户消息
- **验收标准**：
- [ ] 调用API即可发送消息
- [ ] 支持指定好友发送
- [ ] 返回发送状态
**US-003: 新APP快速对接**
- **As a** 技术开发人员
- **I want** 能够快速对接新的APP
- **So that** 可以扩展支持更多社交平台
- **验收标准**：
- [ ] 只需编写Python脚本
- [ ] 无需修改SDK核心代码
- [ ] 2天内完成新APP对接
---
## 四、业务流程 (水)
### 4.1 核心业务流程
```mermaid
flowchart TB
subgraph 存客宝系统
A[存客宝后端] --> B[WorkPhone SDK]
end
subgraph SDK服务器
B --> C{API Gateway}
C --> D[设备管理服务]
C --> E[脚本执行服务]
C --> F[抓包服务]
D --> G[WebSocket Hub]
E --> G
F --> G
end
subgraph 设备端
G <-->|WebSocket| H[手机设备A]
G <-->|WebSocket| I[手机设备B]
G <-->|WebSocket| J[手机设备N]
end
H --> K[微信/抖音/小红书...]
I --> L[微信/抖音/小红书...]
J --> M[微信/抖音/小红书...]
```
### 4.2 指令执行流程
```mermaid
sequenceDiagram
participant C as 存客宝
participant S as SDK服务器
participant D as 手机设备
participant A as 目标APP
C->>S: POST /execute (wechat, send_message)
S->>S: 查找设备连接
S->>D: WebSocket: execute命令
D->>A: uiautomator2操作
A-->>D: 操作完成
D-->>S: WebSocket: 执行结果
S-->>C: HTTP Response
```
### 4.3 设备连接流程
```mermaid
sequenceDiagram
participant D as 手机设备
participant S as SDK服务器
participant R as Redis
participant M as MongoDB
D->>S: WebSocket连接
S->>D: 连接成功
D->>S: register消息(设备信息)
S->>M: 保存设备信息
S->>R: 设置在线状态
loop 心跳保活
D->>S: heartbeat
S->>R: 刷新TTL
S->>D: pong
end
```
---
## 五、数据与迭代 (火)
### 5.1 埋点清单
| 事件名 | 触发条件 | 携带参数 | 分析目的 |
|:---|:---|:---|:---|
| device_connect | 设备连接成功 | device_id, model, version | 统计设备接入 |
| device_disconnect | 设备断开 | device_id, reason | 分析断线原因 |
| command_execute | 执行指令 | device_id, script, action, duration | 分析执行效率 |
| command_fail | 执行失败 | device_id, script, action, error | 分析错误原因 |
| api_call | API调用 | endpoint, method, duration | 接口性能监控 |
### 5.2 成功指标 (KPI)
| 指标 | 目标值 | 衡量方式 | 优先级 |
|:---|:---|:---|:---:|
| 设备连接成功率 | ≥99% | 连接成功数/尝试连接数 | P0 |
| 指令执行成功率 | ≥95% | 成功数/总执行数 | P0 |
| API响应时间 | <500ms (P95) | 接口耗时监控 | P0 |
| 设备在线稳定性 | 24h无断线 | 心跳监控 | P1 |
| 成本节省 | ≥97% | 对比商业方案 | P0 |
### 5.3 迭代规划
| 版本 | 核心功能 | 预计周期 |
|:---|:---|:---|
| v0.1 | 基础设施 + 通信层 | 2周 |
| v0.2 | 设备端 + Frida集成 | 3周 |
| v0.3 | APP脚本 + 存客宝集成 | 3周 |
| v1.0 | 测试优化 + 正式上线 | 2周 |
---
## 六、支持的APP
### 6.1 首批支持
| APP | 包名 | 控制能力 | 抓包能力 |
|-----|------|----------|----------|
| 微信 | com.tencent.mm | ✅ 消息/好友/朋友圈 | ✅ API数据 |
| 抖音 | com.ss.android.ugc.aweme | ✅ 私信/评论/客服 | ✅ API数据 |
| 小红书 | com.xingin.xhs | ✅ 私信/笔记互动 | ✅ API数据 |
### 6.2 扩展支持（新APP只需编写脚本）
| APP | 包名 | 对接难度 | 预计工时 |
|-----|------|----------|----------|
| Soul | cn.soulapp.android | 低 | 2天 |
| 探探 | com.p1.mobile.putong | 低 | 2天 |
| 陌陌 | com.immomo.momo | 低 | 2天 |
| 快手 | com.smile.gifmaker | 中 | 3天 |
| 闲鱼 | com.taobao.idlefish | 中 | 3天 |
---
## 七、与存客宝集成
### 7.1 现有架构
```
存客宝前端 → 存客宝后端 → wss://s2.siyuguanli.com → 奥创服务 → 手机设备
（第三方）
```
### 7.2 目标架构
```
存客宝前端 → 存客宝后端 → https://workphone.xxx.com → 自有SDK → 手机设备
（自有服务器）
```
### 7.3 集成方式
```php
// 现有代码（调用奥创）
$signInData = [
"cmdType" => "CmdSendMsg",
"wechatAccountId" => $wechatId,
"toWxid" => $toWxid,
"content" => $content,
];
$this->client->send(json_encode($signInData));
// 替换为自有SDK
$sdk = new WorkPhoneSDK('https://workphone.xxx.com', 'api-key');
$sdk->execute($deviceId, 'wechat', 'send_message', [
'to_wxid' => $toWxid,
'content' => $content
]);
```
---
## 附录
### A. 竞品分析
| 对比项 | 本方案 | 奥创 | DuoPlus |
|--------|--------|------|---------|
| 抓包能力 | ✅ 任意APP | ❌ 仅微信 | ⚠️ 有限 |
| 新APP对接 | ✅ 写脚本即可 | ❌ 需官方支持 | ⚠️ 需开发 |
| 成本 | ✅ 服务器成本 | ❌ 按设备收费 | ❌ 按设备收费 |
| 私有化 | ✅ 完全自主 | ❌ 依赖第三方 | ❌ 依赖第三方 |
| 数据安全 | ✅ 自有服务器 | ❌ 第三方存储 | ❌ 第三方存储 |
### B. 技术可行性验证
| 技术 | GitHub Stars | 验证结果 | 说明 |
|------|-------------|---------|------|
| Frida | 19.5k+ | ✅ 可行 | SSL Pinning Bypass最成熟方案 |
| uiautomator2 | 7.8k+ | ✅ 可行 | Python Android自动化标杆 |
| scrcpy | 130k+ | ✅ 可行 | 最流行的投屏工具 |
| FastAPI | 80k+ | ✅ 可行 | 高性能异步Python框架 |
| objection | 8.8k+ | ✅ 可行 | Frida自动化工具 |
### C. 变更历史
| 日期 | 版本 | 变更内容 | 责任人 |
|------|------|---------|--------|
| 2026-01-26 | 1.0 | 初始版本 | 卡若 |

261
开发文档/1、需求/技术调研与方案选型.md Normal file
View File

@@ -0,0 +1,261 @@
# 工作手机SDK v3.0 - 技术调研与方案选型
> 整合自资料目录 12 份调研文档 | 更新：2026-02-10
> 本文为**最终选型结论 + 全量调研摘要**，后续开发以此为准
---
## 一、最终选型结论
### 1.1 技术路线确定：双通道架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 机擎 双通道架构（最终方案） │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 主通道（免Root·低封号·日常使用） 增强通道（Root·高能力·可选） │
│ ┌────────────────────────────┐ ┌──────────────────────────┐ │
│ │ uiautomator2 + ADB │ │ Frida Hook 注入 │ │
│ │ • 免Root │ │ • 需Root或Gadget免Root │ │
│ │ • 模拟人工操作 │ │ • 直接调用内部接口 │ │
│ │ • 封号风险极低 │ │ • 实时消息同步 │ │
│ │ • 跨APP通用 │ │ • 后台静默执行 │ │
│ │ • 已实现：微信/抖音/小红书 │ │ • 待实现：微信优先 │ │
│ └────────────────────────────┘ └──────────────────────────┘ │
│ │
│ 路由策略：设备 supports_hook=true → Hook优先 │
│ 设备 supports_hook=false → u2通道 │
│ Hook失败 → 自动降级u2 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 1.2 选型决策矩阵
| 维度 | 主通道（u2+ADB） | 增强通道（Frida Hook） | 奥创（被替代） |
|------|:-:|:-:|:-:|
| Root要求 | ❌ 免Root | ⚠️ 需Root/Gadget | ❌ 需Root |
| 封号风险 | ✅ 极低 | ⚠️ 中等 | ❌ 高 |
| 消息实时性 | ⚠️ 轮询（1-5s延迟） | ✅ 实时 | ✅ 实时 |
| 后台静默 | ❌ 需前台 | ✅ 静默 | ✅ 静默 |
| 多APP支持 | ✅ 任意APP | ✅ 任意APP | ❌ 仅微信 |
| 开发难度 | ✅ 低 | ⚠️ 中高 | - 闭源 |
| 维护成本 | ✅ 低 | ⚠️ 版本适配 | ❌ 依赖厂商 |
| 成本 | ✅ 几乎为零 | ✅ 开源免费 | ❌ 300-500/台/月 |
### 1.3 与奥创能力一一对照
| 奥创能力 | 机擎主通道(u2) | 机擎增强通道(Hook) | 状态 |
|---------|:-:|:-:|------|
| 发消息 | ✅ | ✅ | 已实现(u2) |
| 收消息 | ✅ 轮询 | ✅ 实时 | 已实现(u2), Hook待开发 |
| 联系人 | ✅ | ✅ | 已实现(u2) |
| 加好友 | ✅ | ✅ | 已实现(u2) |
| 群管理 | ✅ | ✅ | 已实现(u2) |
| 标签管理 | ✅ | ✅ | 已实现(u2) |
| 朋友圈 | ✅ | ✅ | 已实现(u2) |
| 聊天存档 | ⚠️ 截图 | ✅ 结构化 | Hook待开发 |
| 红包监控 | ❌ | ✅ | Hook待开发 |
| 设备管理 | ✅ | ✅ | 已实现 |
| 风控 | ✅ 行为级 | ✅ 协议级 | 待开发 |
| 统计报表 | ✅ | ✅ | 待开发 |
---
## 二、竞品与方案全景对比
### 2.1 奥创工作手机深度拆解
**三层架构**（从真机提取验证）：
| 层级 | 组件 | 包名 | 版本 | 大小 | 功能 |
|------|------|------|------|------|------|
| 底层 | XESlciw Manager | `org.xeslciw.manager` | v1.8.4 | 2.4MB | LSPosed定制版框架管理 |
| 核心 | VivWxjz | `top.zzz.vivwxjz` | v1.0 | 4.8MB | 微信Hook模块(libvivwxjz.so) |
| 应用 | AI数智员工 | `uni.UNI9421F6C` | v1.1.2 | 15.1MB | 007云端对接(uni-app) |
**安装链**：Root+Magisk → XESlciw(Zygisk) → VivWxjz(Scope=微信) → AI数智员工 → 绑设备
**VivWxjz 技术核心**（关键发现）：
- 采用 **ptrace/syscall 拦截**，非传统Java Hook
- 拦截 15+ 系统调用：socket/sendmsg/recvmsg/connect/bind/listen/accept/ioctl 等
- 关键符号：`translate_socketcall_enter/exit`、`parse_binder_data`、`native_init`
- 监控路径：`/data/user/0/com.tencent.mm`
- 数据流：微信协议层 → send/recvmsg → VivWxjz拦截 → 解析 → 上报007云端
**XESlciw 框架特性**（LSPosed定制）：
- 混淆命名：Grvjfe ≈ LSPosed API, Iztyge ≈ LSPosed
- 核心API：`native_init(entries)` → `NativeAPIEntries{version, hook_func, unhook_func}`
- 配置文件：`assets/grvjfe_init`(入口)、`assets/native_init`(so列表)、`scope.list`(包名)
- 寄生模式：卸载Manager后框架仍运行
**007云端API推断**（25+接口）：
- 设备：注册/列表/状态/控制
- 消息：发送/批量/接收/历史
- 好友：添加/批量/通过/删除
- 群：创建/邀请/移出/公告
- 朋友圈：发布/列表/点赞/评论
- 风控：告警/敏感词/行为监管
- 统计：日报/周报/漏斗
### 2.2 全网方案对比排名
| 排名 | 方案 | 平台 | Root | 封号率 | 消息实时 | 推荐度 |
|:----:|------|------|:----:|:------:|:--------:|:------:|
| 1 | **机擎u2+ADB** | Android | ❌ | <1% | ⚠️轮询 | ⭐⭐⭐⭐⭐ |
| 2 | wxauto | Windows | ❌ | <1% | ✅ | ⭐⭐⭐⭐ |
| 3 | WePush | Windows | ❌ | 0% | ✅ | ⭐⭐⭐⭐ |
| 4 | **机擎+Frida** | Android | ✅ | 5-10% | ✅ | ⭐⭐⭐⭐ |
| 5 | GeweChat | iPad协议 | ❌ | 3-5% | ✅ | ⭐⭐⭐ |
| 6 | wxMaster | Windows | ❌ | <3% | ✅ | ⭐⭐⭐ |
| 7 | 云手机 | 云端 | ❌ | <1% | ⚠️ | ⭐⭐⭐ |
| 8 | WeChatFerry | Windows | ❌ | >80% | ✅ | ⭐ |
| 9 | 奥创Hook | Android | ✅ | 10-30% | ✅ | ⭐ |
### 2.3 XESlciw vs Frida vs 机擎 能力对比
| 维度 | XESlciw（奥创） | Frida | 机擎 |
|------|:-:|:-:|:-:|
| 定位 | 生产Hook(闭源) | 研发调试(开源) | 私域中台(自研) |
| Hook类型 | Java+Native+Syscall | Java+Native+Memory | u2+可选Hook |
| 热更新 | ❌ 需重启 | ✅ 随时reload | ✅ 脚本热更新 |
| 免Root | ❌ | ✅ Gadget内嵌 | ✅ 主通道 |
| 跨平台 | ❌ 仅Android | ✅ 全平台 | ✅ Android为主 |
| 云端管理 | ✅ 007 | ❌ 自建 | ✅ 机擎+存客宝 |
| 开源 | ❌ | ✅ 19.5k⭐ | ✅ 自研 |
---
## 三、机擎复刻奥创的实现路径
### 3.1 总体实现方案
**核心思路**：用 Frida 实现 VivWxjz 等效能力，用机擎管理端替代 007+AI数智员工。
```
奥创三层 机擎对应
───────────── ─────────────
007云端 → 机擎SDK服务端 + 存客宝
AI数智员工 → 机擎管理端（苹果毛玻璃风格）
XESlciw Manager → 机擎模块管理API
VivWxjz (Hook模块) → Frida脚本（wechat_hook.js等）
XESlciw框架 (Zygisk) → frida-server / Frida Gadget
Magisk+Root → Root设备: frida-server
免Root设备: Frida Gadget 内嵌APK
```
### 3.2 四阶段实施路径
#### 阶段一：架构扩展（2天）
| 序号 | 任务 | 文件 | 细节 |
|:----:|------|------|------|
| 1.1 | 新增Channel.HOOK枚举 | `sdk/app/routers/unified.py` | 在Channel枚举中增加HOOK值 |
| 1.2 | 设备能力扩展 | `sdk/app/services/device_manager.py` | 新增 `supports_hook`, `hook_scopes`, `frida_version` 字段 |
| 1.3 | 路由逻辑 | `sdk/app/routers/unified.py` | `supports_hook && platform in hook_scopes` → HOOK通道 |
| 1.4 | WebSocket协议扩展 | `sdk/app/ws_hub.py` | execute消息增加 `channel: "hook"`, `hook_script_id` |
| 1.5 | 降级机制 | `sdk/app/services/unified_service.py` | Hook执行失败 → 自动fallback到u2 |
#### 阶段二：设备端Frida集成（3-5天）
| 序号 | 任务 | 文件 | 细节 |
|:----:|------|------|------|
| 2.1 | FridaManager | `sdk/agent/frida_manager.py` | 管理frida-server启停、连接维护 |
| 2.2 | ScriptLoader | `sdk/agent/script_loader.py` | 从云端拉取脚本、版本管理、缓存 |
| 2.3 | HookExecutor | `sdk/agent/hook_executor.py` | attach进程、加载脚本、调用rpc.exports |
| 2.4 | EventReporter | `sdk/agent/event_reporter.py` | 脚本send()数据转发到云端WebSocket |
| 2.5 | 指令分发 | `sdk/agent/agent.py` | channel=hook时走HookExecutor |
#### 阶段三：Hook脚本开发（5-10天）
| 序号 | 脚本 | 功能 | Hook点 |
|:----:|------|------|--------|
| 3.1 | wechat_hook.js | 发消息 | 逆向微信发送方法(Java/Native) |
| 3.2 | wechat_hook.js | 收消息 | Hook消息写入DB/网络收包回调 |
| 3.3 | wechat_hook.js | 联系人 | Hook联系人查询/读EnMicroMsg.db |
| 3.4 | wechat_hook.js | 朋友圈 | Hook发朋友圈/浏览方法 |
| 3.5 | wechat_hook.js | 红包 | Hook红包通知/自动领取 |
| 3.6 | douyin_hook.js | 私信 | 抖音消息收发Hook |
| 3.7 | xhs_hook.js | 私信 | 小红书消息收发Hook |
#### 阶段四：管理端（2-3天）
| 序号 | 任务 | 细节 |
|:----:|------|------|
| 4.1 | 模块管理API | GET/POST/PUT/DELETE /modules |
| 4.2 | 模块数据表 | MongoDB hook_modules集合 |
| 4.3 | 管理界面 | 苹果毛玻璃风格，模块列表/启用/配置 |
| 4.4 | 监控面板 | Hook状态、消息统计、错误日志 |
### 3.3 Frida两种部署方式对比
| 维度 | frida-server（Root） | Frida Gadget（免Root） |
|------|:-:|:-:|
| Root要求 | ✅ 必须 | ❌ 免Root |
| 安装方式 | push到/data/local/tmp运行 | 内嵌到目标APK/独立APP |
| 多APP | ✅ attach任意进程 | ⚠️ 仅内嵌的APP |
| 热更新 | ✅ 随时attach/detach | ⚠️ 需重启APP |
| 稳定性 | ✅ 高 | ✅ 高 |
| 检测难度 | ⚠️ 可被检测 | ✅ 较难检测 |
| 推荐 | Root设备首选 | 免Root设备首选 |
---
## 四、多设备多服务器架构方案
### 4.1 连接架构
```
手机A ──WebSocket──┐
手机B ──WebSocket──┤
手机C ──WebSocket──├── 服务器1（管理100台）
手机D ──WebSocket──┤
手机E ──WebSocket──┘
手机F ──WebSocket──┐
手机G ──WebSocket──├── 服务器2（管理100台）
手机H ──WebSocket──┘
服务器1 ──┐
服务器2 ──├── 管理中心（存客宝/机擎管理端）
服务器N ──┘
```
### 4.2 设备分配策略
- 每台手机配置指定服务器地址（`server_url`）
- 服务器自动注册到管理中心
- 管理中心统一展示所有服务器和设备
- 支持设备迁移（更改server_url重连）
---
## 五、风险与约束
| 风险 | 等级 | 缓解措施 |
|------|:----:|----------|
| Hook封号 | 🔴 高 | Hook作为可选增强，主通道u2不受影响 |
| 微信版本更新 | 🟡 中 | 脚本版本管理+快速适配机制 |
| Root设备安全 | 🟡 中 | Magisk隐藏+SELinux |
| Frida被检测 | 🟡 中 | 改名frida-server+Gadget方案 |
| 法律合规 | 🔴 高 | 仅限自有设备、授权使用 |
---
## 六、调研资料索引（已整合）
| 序号 | 原文件 | 核心内容 | 已整合到 |
|:----:|--------|----------|----------|
| 1 | 奥创.md | 竞品功能矩阵+技术通道 | §2.1 |
| 2 | 奥创工作手机-复刻开发详解.md | 安装链+Hook底层+开发任务 | §3.2 |
| 3 | 奥创工作手机APK提取/README.md | 三层包名+提取命令 | §2.1 |
| 4 | 奥创微信控制接口与插件提取复用指南.md | 007 API+VivWxjz符号 | §2.1 |
| 5 | XESlciw详解与工作手机技术方案对比.md | LSPosed定制+五类方案对比 | §2.1, §2.3 |
| 6 | XESlciw接口与设备Hook开发手册.md | Native Hook API+开发流程 | §2.1 |
| 7 | XESlciw与Frida及机擎详细对比分析.md | 三者能力对比+选型 | §2.3 |
| 8 | 奥创Hook与Frida详细对比及微信互通.md | 远程方案+互通总表 | §2.3 |
| 9 | 微信互通方案对比与更好替代.md | PC端方案+桥接架构 | §2.2 |
| 10 | 个微方案全网对比_优于Frida与奥创.md | 全网方案排名 | §2.2 |
| 11 | 最佳解决路径_个微工作手机统一方案.md | 机擎唯一方案论证 | §1 |
| 12 | 机擎复刻Frida与奥创管理注入_实现路径.md | 复刻路径+架构图 | §3 |

222
开发文档/1、需求/项目概述.md Normal file
View File

@@ -0,0 +1,222 @@
# 工作手机SDK v3.0 项目概述
> 版本：v3.0 | 更新：2026-01-26 | 状态：开发中
>
> **核心定位**：存客宝的AI手机控制引擎，被调用方（存客宝只调用SDK，不融合代码）
---
## 一、项目背景
### 1.1 现状痛点
存客宝目前通过**第三方代理服务器**（奥创：s2.siyuguanli.com）控制手机设备：
| 痛点 | 影响 |
|------|------|
| **依赖第三方** | 数据安全无保障，服务稳定性不可控 |
| **成本高昂** | 300-500元/台/月，100台设备年费36万+ |
| **功能受限** | 仅支持微信，无法扩展抖音/小红书/Soul等 |
| **无法定制** | 业务需求无法快速响应 |
### 1.2 解决方案
开发**自有的工作手机SDK v3.0**：
| 能力 | 说明 |
|------|------|
| **任意APP抓包** | Frida通用Hook，不限于特定APP |
| **任意APP控制** | uiautomator2脚本引擎，新APP只需写脚本 |
| **AI Agent模式** | 自然语言控制手机，智能适应UI变化 |
| **远程互联网控制** | 设备可在任意位置，通过互联网连接云端 |
| **私有化部署** | 数据自主，无限设备扩展 |
### 1.3 项目愿景
**一套SDK，控制所有APP** + **AI智能兜底**
---
## 二、存客宝与SDK的关系
```
┌─────────────────────────────────────────────────────────────────────┐
│ 存客宝生态系统 (调用方) │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 存客宝后端 (ThinkPHP) │ │
│ │ │ │
│ │ // 核心算法（健康分、RFM、流量分发等） │ │
│ │ // 业务逻辑（消息群发、自动建群等） │ │
│ │ // 调用工作手机SDK │ │
│ │ │ │
│ │ $sdk = new WorkPhoneClient('https://sdk.xxx.com', 'key');│ │
│ │ $sdk->sendMessage($deviceId, 'wechat', $wxid, $content); │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
└─────────────────────────────────────┼───────────────────────────────┘
│ HTTPS REST API
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 工作手机SDK v3.0 (被调用方) │
│ │
│ 本项目 - 独立部署，提供统一API给存客宝调用 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 统一服务交互层 (Facade) │ │
│ │ 自动选择最优通道：官方API → SDK控制 → AI Agent │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 官方API通道 │ │ SDK控制通道 │ │ AI Agent通道│ │
│ │ (抖音等) │ │(uiautomator2)│ │ (DroidRun) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
└──────────────────────────────┼──────────────────────────────────────┘
│ WebSocket
▼
┌─────────────────┐
│ 手机设备 │
│ Agent APP │
└─────────────────┘
```
**关键点**：
- 存客宝只调用SDK的REST API
- SDK代码完全独立，不融合到存客宝项目
- SDK提供三种执行通道，自动选择最优方式
---
## 三、核心能力矩阵
### 3.1 三层控制能力
```
┌─────────────────────────────────────────────────────────────────────┐
│ 工作手机SDK能力 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Layer 1: 官方API通道（优先级最高） │ │
│ │ │ │
│ │ • 抖音OpenAPI（私信、粉丝列表、评论） │ │
│ │ • 微信开放平台（企业微信API） │ │
│ │ • 优势：最稳定、最低成本、官方支持 │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Layer 2: SDK控制通道（默认通道） │ │
│ │ │ │
│ │ • uiautomator2 → 点击/滑动/输入/截图 │ │
│ │ • Frida → SSL Bypass/数据抓包 │ │
│ │ • objection → Frida自动化 │ │
│ │ • 优势：通用、免费、无限制 │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Layer 3: AI Agent通道（智能兜底） │ │
│ │ │ │
│ │ • DroidRun + DeepSeek → 自然语言控制 │ │
│ │ • 自动适应UI变化 │ │
│ │ • 优势：最灵活、无需写脚本、智能处理异常 │ │
│ │ • 成本：约0.02元/次 │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### 3.2 支持的APP
| APP | 包名 | 官方API | SDK控制 | AI Agent |
|-----|------|:---:|:---:|:---:|
| 微信 | com.tencent.mm | ❌ | ✅ | ✅ |
| 抖音 | com.ss.android.ugc.aweme | ✅ | ✅ | ✅ |
| 小红书 | com.xingin.xhs | ❌ | ✅ | ✅ |
| 闲鱼 | com.taobao.idlefish | ✅ WSS | ✅ | ✅ |
| Soul | cn.soulapp.android | ❌ | ✅ | ✅ |
---
## 四、成本对比
### 4.1 与商业方案对比
| 设备数量 | 自研方案 | 奥创 | 节省 |
|----------|----------|------|------|
| 10台 | 500元/月 | 3,000-5,000元/月 | **83%+** |
| 50台 | 500元/月 | 15,000-25,000元/月 | **96%+** |
| 100台 | 800元/月 | 30,000-50,000元/月 | **97%+** |
| 500台 | 1,500元/月 | 150,000-250,000元/月 | **99%+** |
### 4.2 自研方案成本明细
| 项目 | 成本 | 说明 |
|------|------|------|
| 云服务器 | 500-1,500元/月 | 2核4G起步 |
| AI Agent调用 | ~0.02元/次 | 仅作为兜底使用 |
| 域名SSL | ~100元/年 | 已有可复用 |
| 开发成本 | 一次性 | 自有团队 |
---
## 五、技术选型
### 5.1 GitHub Stars排行
| 技术 | Stars | 用途 | 核心代码位置 |
|------|-------|------|-------------|
| **scrcpy** | 130k+ | Android投屏 | - |
| **Frida** | 19.5k | 动态Hook/SSL Bypass | `6、后端/frida_scripts/` |
| **DroidRun** | 7.5k | AI Agent控制 | `6、后端/核心代码/droidrun.md` |
| **objection** | 8.8k | Frida自动化 | `6、后端/frida_scripts/` |
| **uiautomator2** | 7.8k | Python自动化 | `6、后端/核心代码/uiautomator2.md` |
| **Airtest** | 5.4k | 网易自动化框架 | 参考实现 |
### 5.2 核心代码来源
所有核心代码已下载到 `github-repos/` 目录：
- `uiautomator2/` - UI自动化
- `droidrun/` - AI Agent
- `objection/` - Frida自动化
- `xianyu-auto/` - 闲鱼WebSocket
- `douyin-wss/` - 抖音协议
---
## 六、下一步
1. **架构设计**：查看 [2、架构/系统架构.md](../2、架构/系统架构.md)
2. **接口对接**：查看 [5、接口/接口规范.md](../5、接口/接口规范.md)
3. **开发计划**：查看 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md)
---
## 附：成本与需求澄清（合并自原独立文档）
### 成本估算
| 方案 | 月成本 | 年成本 |
|------|--------|--------|
| 奥创 | 30,000-50,000元 | **360,000-600,000元** |
| **自研方案** | **800元** | **~10,000元** |
年度节省：35-59万元 | 节省比例 97%+ | ROI约228倍 | 回本周期约5天
自研成本明细：一次性~5,400元（测试机+服务器+SSL）；小型≤50台~210元/月；中型50-200台~1,410元/月；大型200-1000台~6,050元/月。
开发：1后端+1移动端，10周；运维约14h/月。
### 需求澄清结论
| 项 | 结论 |
|----|------|
| 核心目标 | 替代奥创所有功能并超越 |
| 控制APP | 微信、抖音、小红书、闲鱼 |
| 脚本vs AI | 80% 脚本 + 20% AI |
| 上线时间 | 4-8周 |
| 开发资源 | 2人全职 |
| 测试设备 | 5台红米 |
| 互联网资源 | 闲鱼有完整开源；微信需自研 |

533
开发文档/2、架构/Hook通道与多设备多服务器架构.md Normal file
View File

@@ -0,0 +1,533 @@
# Hook通道与多设备多服务器架构
> 更新：2026-02-10 | 本文为双通道架构+多设备多服务器的详细设计
---
## 一、整体架构全景
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ 机擎 v3.0 全景架构 │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 管理层（苹果毛玻璃风格 Web 管理端） │ │
│ │ 设备管理 │ 模块管理 │ 消息中心 │ 任务调度 │ 监控面板 │ 风控 │ │
│ └──────────────────────────┬──────────────────────────────────────────────┘ │
│ │ HTTPS │
│ ┌──────────────────────────▼──────────────────────────────────────────────┐ │
│ │ API网关层（Nginx / 负载均衡） │ │
│ │ • 路由分发 • SSL终止 • 限流 • 日志 │ │
│ └──────────────────────────┬──────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────▼──────────────────────────────────────────────┐ │
│ │ 服务层（可水平扩展） │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ │
│ │ │ SDK Server │ │ WebSocket Hub │ │ 模块管理服务 │ │ │
│ │ │ (FastAPI) │ │ (连接管理) │ │ (Hook模块CRUD) │ │ │
│ │ │ • 统一API │ │ • 设备连接池 │ │ • 脚本版本管理 │ │ │
│ │ │ • 通道路由 │ │ • 消息转发 │ │ • Scope配置 │ │ │
│ │ │ • 任务调度 │ │ • 心跳管理 │ │ • 启用/禁用 │ │ │
│ │ └──────────────────┘ └──────────────────┘ └──────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ │
│ │ │ 消息服务 │ │ 风控服务 │ │ 统计服务 │ │ │
│ │ │ • 消息收发 │ │ • 敏感词 │ │ • 日报/周报 │ │ │
│ │ │ • 历史存储 │ │ • 行为监管 │ │ • 漏斗分析 │ │ │
│ │ │ • 实时推送 │ │ • 告警通知 │ │ • 设备健康 │ │ │
│ │ └──────────────────┘ └──────────────────┘ └──────────────────────┘ │ │
│ └──────────────────────────┬──────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────▼──────────────────────────────────────────────┐ │
│ │ 数据层 │ │
│ │ MongoDB(设备/消息/模块/日志) │ Redis(状态/队列/限流) │ MinIO(截图/脚本) │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ════════════════╪══════════════ 网络边界 ════════════════════ │
│ │ WebSocket (wss://) │
│ │ │
│ ┌──────────────────────────▼──────────────────────────────────────────────┐ │
│ │ 设备层（Android 手机） │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ 机擎 Agent │ │ │
│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌───────────┐ │ │ │
│ │ │ │ 连接管理 │ │ 通道选择器 │ │ 能力上报 │ │ 日志采集 │ │ │ │
│ │ │ └────────────┘ └─────┬──────┘ └────────────┘ └───────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────────┼─────────────┐ │ │ │
│ │ │ ▼ ▼ ▼ │ │ │
│ │ │ ┌──────────────┐ ┌────────────┐ ┌──────────────┐ │ │ │
│ │ │ │ u2通道 │ │ Hook通道 │ │ AI Agent │ │ │ │
│ │ │ │ SkillExecutor │ │ HookExec │ │ (可选) │ │ │ │
│ │ │ │ • 微信Skill │ │ • Frida │ │ • LLM驱动 │ │ │ │
│ │ │ │ • 抖音Skill │ │ • 脚本加载 │ │ • 视觉理解 │ │ │ │
│ │ │ │ • 小红书Skill │ │ • rpc调用 │ │ │ │ │ │
│ │ │ └──────────────┘ └────────────┘ └──────────────┘ │ │ │
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌─────────┼─────────┐ │ │
│ │ ▼ ▼ ▼ │ │
│ │ 微信 抖音 小红书 ... │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
```
---
## 二、双通道路由设计
### 2.1 通道枚举
```python
class Channel(str, Enum):
OFFICIAL_API = "official_api" # 官方开放API（抖音等）
SDK_CONTROL = "sdk_control" # u2+ADB 主通道
HOOK = "hook" # Frida Hook 增强通道
AI_AGENT = "ai_agent" # AI Agent（LLM驱动）
```
### 2.2 路由决策流程
```
收到指令
│
▼
检查平台是否有官方API？ ──Yes──▶ OFFICIAL_API
│No
▼
设备是否在线？ ──No──▶ 排队等待重连
│Yes
▼
设备 supports_hook=true 且 platform在hook_scopes？ ──Yes──▶ HOOK通道
│No │
▼ ▼
SDK_CONTROL (u2) 执行Hook
│ │
▼ 执行成功？
u2执行 │Yes │No
▼ ▼
返回 降级到u2
```
### 2.3 设备能力上报（扩展）
```python
class DeviceCapabilities(BaseModel):
device_id: str
device_name: str
platform: str = "android"
android_version: str
# 现有能力
skill_wechat: bool = True
skill_douyin: bool = True
skill_xhs: bool = True
skill_xianyu: bool = True
# Hook能力（新增）
supports_hook: bool = False
hook_scopes: list[str] = [] # ["com.tencent.mm", "com.ss.android.ugc.aweme"]
frida_version: str = "" # "16.5.6"
hook_framework: str = "" # "frida-server" | "frida-gadget"
root_status: bool = False
# 模块信息
loaded_modules: list[str] = [] # ["wechat_hook_v1", "douyin_hook_v1"]
module_versions: dict = {} # {"wechat_hook_v1": "1.0.3"}
```
### 2.4 WebSocket 协议扩展
**execute 消息（新增 channel 和 hook 字段）**：
```json
{
"type": "execute",
"data": {
"task_id": "task_abc123",
"channel": "hook",
"platform": "wechat",
"action": "send_message",
"params": {
"to_id": "wxid_xxx",
"content": "你好"
},
"hook_config": {
"script_id": "wechat_hook_v1",
"method": "send_message",
"timeout": 10
}
}
}
```
**hook_event 消息（新增：设备主动上报Hook事件）**：
```json
{
"type": "hook_event",
"data": {
"event_type": "message_received",
"source": "wechat_hook_v1",
"payload": {
"from_id": "wxid_yyy",
"content": "收到消息",
"msg_type": "text",
"timestamp": 1707552000
}
}
}
```
---
## 三、多设备多服务器架构
### 3.1 分层部署架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 管理中心（Management Center） │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 存客宝 / 机擎管理端 (毛玻璃UI) │ │
│ │ • 所有服务器、所有设备的统一视图 │ │
│ │ • 跨服务器任务下发 │ │
│ │ • 全局监控与统计 │ │
│ └────────────────────────────┬───────────────────────────────┘ │
│ │ HTTPS │
│ ┌────────────────────────────▼───────────────────────────────┐ │
│ │ 服务注册中心 (MongoDB/Redis) │ │
│ │ • 服务器列表: [{id, url, capacity, online_devices}] │ │
│ │ • 设备路由表: {device_id → server_id} │ │
│ │ • 健康检查: 每30s心跳 │ │
│ └────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────── ┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ 服务器 A │ │ 服务器 B │ │ 服务器 C │
│ (100台设备) │ │ (100台设备) │ │ (100台设备) │
│ │ │ │ │ │
│ SDK Server │ │ SDK Server │ │ SDK Server │
│ WS Hub │ │ WS Hub │ │ WS Hub │
│ MongoDB │ │ MongoDB │ │ MongoDB │
│ Redis │ │ Redis │ │ Redis │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
┌─────┼─────┐ ┌────┼────┐ ┌────┼────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
📱 📱 📱 📱 📱 📱 📱 📱 📱
手机1 手机2 ... 手机101 ... 手机201 ...
```
### 3.2 服务器节点设计
每个服务器节点独立运行完整服务栈：
```yaml
# docker-compose.yml（每个节点）
services:
sdk-server:
image: workphone-sdk:latest
ports: ["8899:8899"]
environment:
- NODE_ID=server-a
- MANAGEMENT_CENTER_URL=https://manage.cunkebao.com
- MAX_DEVICES=100
- MONGODB_URI=mongodb://mongo:27017/workphone_sdk
- REDIS_URI=redis://redis:6379
mongo:
image: mongo:6.0
volumes: ["mongo_data:/data/db"]
redis:
image: redis:7-alpine
nginx:
image: nginx:alpine
ports: ["443:443", "80:80"]
```
### 3.3 设备连接流程
```
手机开机
│
▼
读取配置: server_url = "wss://server-a.workphone.com:8899/ws"
│
▼
WebSocket连接到指定服务器
│
▼
发送 register 消息（含设备ID、能力、Hook状态）
│
▼
服务器注册设备，通知管理中心
│
▼
开始心跳循环（每10s）
│
▼
等待指令 / 上报Hook事件
```
### 3.4 设备配置文件
设备端 Agent 配置文件（`/sdcard/workphone/config.json`）：
```json
{
"server_url": "wss://server-a.workphone.com:8899/ws",
"device_name": "工作手机-A001",
"heartbeat_interval": 10,
"hook_enabled": true,
"hook_config": {
"framework": "frida-server",
"auto_start": true,
"scripts": ["wechat_hook_v1"],
"scopes": ["com.tencent.mm"]
},
"u2_config": {
"port": 7912,
"timeout": 30
}
}
```
### 3.5 服务器容量规划
| 规模 | 服务器配置 | 单机设备数 | 服务器数 | 月成本 |
|------|-----------|:--------:|:------:|------:|
| 小型 ≤50台 | 2C4G | 50 | 1 | ~210元 |
| 中型 50-200台 | 4C8G | 100 | 2 | ~1,400元 |
| 大型 200-1000台 | 8C16G | 200 | 5 | ~6,000元 |
| 超大型 1000+台 | 8C16G集群 | 200 | N | ~1,200/节点 |
---
## 四、Hook通道详细设计
### 4.1 设备端Hook组件
```
sdk/agent/
├── agent.py # 主Agent（已有+扩展）
├── skill_executor.py # u2技能执行器（已有）
├── hook/ # Hook通道（新增）
│ ├── __init__.py
│ ├── frida_manager.py # Frida生命周期管理
│ ├── script_loader.py # 脚本下载/缓存/版本管理
│ ├── hook_executor.py # Hook指令执行器
│ ├── event_reporter.py # Hook事件上报
│ └── scripts/ # Hook脚本
│ ├── wechat_hook.js # 微信Hook脚本
│ ├── douyin_hook.js # 抖音Hook脚本
│ └── common.js # 公共Hook工具
└── skills/ # u2技能（已有）
├── base_skill.py
├── wechat_skill.py
└── ...
```
### 4.2 FridaManager 设计
```python
class FridaManager:
"""Frida 生命周期管理"""
def __init__(self, config: HookConfig):
self.config = config
self.device = None # frida.get_usb_device()
self.sessions = {} # {pid: session}
self.scripts = {} # {script_id: script}
async def start(self):
"""启动Frida连接"""
# 1. 检测frida-server是否运行
# 2. 连接设备
# 3. 按scope自动attach目标APP
async def attach(self, package: str) -> frida.Session:
"""attach到目标进程"""
pid = self.device.get_frontmost_application().pid
session = self.device.attach(pid)
return session
async def load_script(self, session, script_id: str):
"""加载并注入Hook脚本"""
code = self.script_loader.get(script_id)
script = session.create_script(code)
script.on('message', self._on_message)
script.load()
self.scripts[script_id] = script
async def call_rpc(self, script_id: str, method: str, *args):
"""调用脚本RPC方法"""
script = self.scripts[script_id]
func = getattr(script.exports_sync, method)
return func(*args)
def _on_message(self, message, data):
"""脚本消息回调（收消息等事件）"""
if message['type'] == 'send':
self.event_reporter.report(message['payload'])
```
### 4.3 HookExecutor 设计
```python
class HookExecutor:
"""Hook指令执行器（与SkillExecutor平级）"""
def __init__(self, frida_manager: FridaManager):
self.frida = frida_manager
async def execute(self, task: dict) -> dict:
"""
执行Hook指令
task: {platform, action, params, hook_config}
"""
script_id = task['hook_config']['script_id']
method = task['hook_config']['method']
params = task.get('params', {})
try:
result = await self.frida.call_rpc(script_id, method, params)
return {"success": True, "data": result}
except Exception as e:
return {"success": False, "error": str(e), "fallback": "u2"}
```
---
## 五、模块管理设计（对标XESlciw Manager）
### 5.1 数据模型
```python
class HookModule(BaseModel):
"""Hook模块"""
module_id: str # "wechat_hook_v1"
name: str # "微信Hook模块"
version: str # "1.0.3"
description: str
script_url: str # MinIO下载地址
script_hash: str # SHA256校验
scopes: list[str] # ["com.tencent.mm"]
min_frida_version: str # "16.0.0"
capabilities: list[str] # ["send_message", "get_messages", ...]
enabled: bool = True
created_at: datetime
updated_at: datetime
class DeviceModule(BaseModel):
"""设备已安装的模块"""
device_id: str
module_id: str
status: str # "loaded" | "error" | "disabled"
loaded_at: datetime
last_error: str = ""
```
### 5.2 模块管理API
| API | 方法 | 说明 |
|-----|------|------|
| GET /api/v3/modules | GET | 模块列表 |
| POST /api/v3/modules | POST | 注册/上传新模块 |
| GET /api/v3/modules/{id} | GET | 模块详情 |
| PUT /api/v3/modules/{id} | PUT | 更新模块（含脚本） |
| DELETE /api/v3/modules/{id} | DELETE | 删除模块 |
| PUT /api/v3/modules/{id}/scope | PUT | 设置Scope |
| POST /api/v3/modules/{id}/enable | POST | 启用 |
| POST /api/v3/modules/{id}/disable | POST | 禁用 |
| GET /api/v3/devices/{id}/modules | GET | 设备已加载模块 |
| POST /api/v3/devices/{id}/modules/reload | POST | 重载设备模块 |
---
## 六、数据流设计
### 6.1 发消息数据流
```
管理端 → POST /api/v3/message/send {to_id, content}
│
▼
SDK Server → ChannelRouter.route()
│
├── supports_hook=true → channel=hook
│ │
│ ▼
│ WS Hub → execute {channel: "hook", action: "send_message"}
│ │
│ ▼
│ 设备Agent → HookExecutor → frida.call_rpc("send_message", params)
│ │
│ ▼
│ Frida脚本 → 调用微信内部发送函数 → 消息发出
│
└── supports_hook=false → channel=sdk_control
│
▼
WS Hub → execute {channel: "sdk_control", action: "send_message"}
│
▼
设备Agent → SkillExecutor → WechatSkill.send_message()
│
▼
u2点击操作 → 微信界面发送 → 消息发出
```
### 6.2 收消息数据流（Hook实时）
```
微信收到消息
│
▼
Frida Hook拦截（recvmsg/消息回调）
│
▼
脚本内 send({type: "message_received", data: {...}})
│
▼
FridaManager._on_message() → EventReporter.report()
│
▼
WebSocket → hook_event {event_type: "message_received", payload: {...}}
│
▼
SDK Server → 存入MongoDB messages集合
│
▼
推送到管理端（WebSocket/Webhook）
```
---
## 七、安全设计
### 7.1 通信安全
| 层级 | 措施 |
|------|------|
| 传输 | WSS (TLS 1.3) |
| 认证 | 设备注册时下发Token，每次连接验证 |
| 脚本 | SHA256校验，防止篡改 |
| 数据 | 敏感字段加密存储（AES-256） |
### 7.2 Hook安全
| 风险 | 措施 |
|------|------|
| Frida被检测 | 改名frida-server → workphone-agent |
| Root被检测 | Magisk Hide / Zygisk DenyList |
| 异常行为 | 频率限制（发消息≤30条/分钟） |
| 数据泄露 | Hook数据仅上报服务端，不落盘 |

24
开发文档/2、架构/README.md Normal file
View File

@@ -0,0 +1,24 @@
# 2、架构
**项目**：工作手机SDK v3.0（双通道架构：u2主通道 + Hook增强通道）
**规则**：本目录除本 README 外最多 **3 个主文档**。
**当前状态**：基础架构100%；Hook通道架构已设计，待开发。进度以 [开发进度总表](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [系统架构.md](系统架构.md) | 整体架构图、M1-M12模块、数据流、存客宝对接（含原对接补充内容） |
| [技术选型与数据库.md](技术选型与数据库.md) | 技术选型决策+MongoDB/Redis数据库设计 |
| [Hook通道与多设备多服务器架构.md](Hook通道与多设备多服务器架构.md) | **新增**：双通道路由+Frida集成+多设备多服务器+模块管理 |
---
## 合并记录
- 2026-02-10: `对接与方案补充.md` 内容合并入 `系统架构.md` 附录
- 2026-02-10: 新增 `Hook通道与多设备多服务器架构.md`

831
开发文档/2、架构/技术选型与数据库.md Normal file
View File

@@ -0,0 +1,831 @@
# 工作手机SDK v3.0 - 技术选型与数据库
> 合并自《技术选型》+《数据库设计》| 更新：2026-02-07
---
## Part A：技术选型
### 一、技术选型矩阵
### 1.1 卡若标准技术栈
```
┌─────────────────────────────────────────────────────────────────────┐
│ 工作手机SDK技术栈 │
├─────────────────────────────────────────────────────────────────────┤
│ 📱 设备端（Android） │
│ ├── 开发语言: Kotlin 1.9+ │
│ ├── UI自动化: uiautomator2 (Python Server + HTTP接口) │
│ ├── Hook框架: Frida 16.x │
│ ├── 投屏: scrcpy (可选) │
│ └── 通信: OkHttp 4.x WebSocket │
├─────────────────────────────────────────────────────────────────────┤
│ 🖥️ 服务端 │
│ ├── 语言: Python 3.11+ │
│ ├── 框架: FastAPI 0.110+ (异步 + 类型安全) │
│ ├── WebSocket: websockets / starlette │
│ ├── 脚本引擎: 自研 (BaseScript + 注册表) │
│ └── 任务队列: Redis Stream / Celery (可选) │
├─────────────────────────────────────────────────────────────────────┤
│ 💾 数据层 │
│ ├── 业务库: MongoDB 6.0+ (灵活文档) │
│ ├── 缓存: Redis 7.x (状态 + 队列) │
│ ├── 文件: MinIO (S3兼容) │
│ └── 向量: MongoDB Atlas Vector (可选) │
├─────────────────────────────────────────────────────────────────────┤
│ 🚀 部署层 │
│ ├── 容器: Docker + Docker Compose │
│ ├── 反向代理: Nginx 1.24+ │
│ ├── 进程管理: Uvicorn + Gunicorn │
│ └── CI/CD: GitHub Webhook │
└─────────────────────────────────────────────────────────────────────┘
```
---
### 二、GitHub Stars排行验证
### 2.1 核心技术验证
| 技术 | Stars | 最后更新 | 中文社区 | 选型结论 |
|------|-------|---------|---------|---------|
| **scrcpy** | 130k+ | 活跃 | 活跃 | ✅ 投屏方案 |
| **Frida** | 19.5k+ | 每周 | 活跃 | ✅ **核心方案** |
| **LSPosed** | 19k+ | 活跃 | 活跃 | ⚠️ 备选（需Root） |
| **objection** | 8.8k+ | 活跃 | 活跃 | ✅ Frida辅助 |
| **uiautomator2** | 7.8k+ | 每月 | 非常活跃 | ✅ **核心方案** |
| **Airtest** | 5.4k+ | 活跃 | 活跃 | ⚠️ 备选方案 |
| **FastAPI** | 80k+ | 每周 | 活跃 | ✅ **核心方案** |
| **MongoDB** | 27k+ | 活跃 | 活跃 | ✅ **核心方案** |
### 2.2 社区活跃度评估
| 技术 | 更新频率 | 文档质量 | 问题响应 | 评分 |
|------|----------|----------|---------|------|
| Frida | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 9.5/10 |
| uiautomator2 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 9/10 |
| FastAPI | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 10/10 |
| scrcpy | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | 8/10 |
---
### 三、技术选型决策树
```mermaid
flowchart TB
A[工作手机SDK] --> B{是否需要抓包?}
B -->|是| C{设备是否Root?}
B -->|否| D[仅UI自动化]
C -->|已Root| E[Frida Server模式]
C -->|免Root| F[Frida Gadget注入]
D --> G[uiautomator2]
E --> G
F --> G
G --> H{服务端框架?}
H --> I[FastAPI + WebSocket]
I --> J{数据库?}
J --> K[MongoDB + Redis]
K --> L[完成选型]
```
---
### 四、详细技术对比
### 4.1 UI自动化框架对比
| 对比项 | uiautomator2 | Airtest | Appium |
|--------|-------------|---------|--------|
| **开发语言** | Python | Python | 多语言 |
| **学习曲线** | 低 | 中 | 高 |
| **性能** | 快 | 中 | 慢 |
| **稳定性** | 高 | 高 | 中 |
| **社区支持** | 7.8k⭐ | 5.4k⭐ | 19k⭐ |
| **企业级支持** | 无 | 网易 | Sauce Labs |
| **适用场景** | 简单快速 | 游戏测试 | 企业复杂场景 |
**结论：uiautomator2**
- 学习成本低
- Python接口友好
- 中文社区活跃
- 适合我们的场景
### 4.2 Hook框架对比
| 对比项 | Frida | Xposed/LSPosed | Android Hook |
|--------|-------|----------------|--------------|
| **Root要求** | 可免Root (Gadget) | 需要 | 需要 |
| **灵活性** | 高 | 中 | 低 |
| **性能** | 高 | 中 | 高 |
| **学习曲线** | 中 | 低 | 高 |
| **动态性** | ✅ 运行时注入 | ❌ 重启生效 | ❌ 编译时 |
| **跨APP** | ✅ | ✅ | ❌ |
**结论：Frida**
- 可免Root（Gadget模式）
- 运行时动态注入
- 社区成熟，脚本丰富
- SSL Bypass方案完善
### 4.3 服务端框架对比
| 对比项 | FastAPI | Flask | Django |
|--------|---------|-------|--------|
| **性能** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| **异步支持** | ✅ 原生 | ⚠️ 需扩展 | ⚠️ 需扩展 |
| **类型安全** | ✅ Pydantic | ❌ | ⚠️ 部分 |
| **自动文档** | ✅ Swagger | ❌ | ⚠️ 需扩展 |
| **WebSocket** | ✅ 原生 | ❌ | ⚠️ Channels |
| **学习曲线** | 低 | 低 | 中 |
**结论：FastAPI**
- 异步优先，适合高并发WebSocket
- 类型安全，减少bug
- 自动生成API文档
- 性能优异
### 4.4 数据库对比
| 对比项 | MongoDB | MySQL | PostgreSQL |
|--------|---------|-------|------------|
| **数据模型** | 文档 | 关系 | 关系 |
| **灵活性** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| **性能** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **扩展性** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| **向量支持** | ✅ Atlas | ❌ | ✅ pgvector |
| **适用场景** | 灵活Schema | 事务密集 | 复杂查询 |
**结论：MongoDB**
- 设备数据/抓包数据结构灵活
- 支持向量索引（未来AI能力）
- 水平扩展能力强
- 私域银行标准技术栈
---
### 五、技术版本锁定
### 5.1 服务端
```txt
### requirements.txt
### Web框架
fastapi==0.110.0
uvicorn[standard]==0.27.0
websockets==12.0
## Part B：数据库设计
pymongo==4.6.0
motor==3.3.0 # 异步MongoDB
redis==5.0.0
### 数据验证
pydantic==2.5.0
### HTTP客户端
httpx==0.26.0
aiohttp==3.9.0
### 工具
python-dotenv==1.0.0
python-jose==3.3.0 # JWT
passlib==1.7.4 # 密码Hash
### 自动化
uiautomator2==3.0.0 # 最新版
frida==16.1.0 # 最新稳定版
frida-tools==12.2.0
### 存储
minio==7.2.0
### 监控
prometheus-client==0.19.0
```
### 5.2 设备端
```kotlin
// build.gradle.kts
dependencies {
// Kotlin
implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.22")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
// 网络
implementation("com.squareup.okhttp3:okhttp:4.12.0")
// JSON
implementation("com.google.code.gson:gson:2.10.1")
// 依赖注入（可选）
implementation("io.insert-koin:koin-android:3.5.0")
}
android {
compileSdk = 34
defaultConfig {
minSdk = 24 // Android 7.0
targetSdk = 34 // Android 14
}
}
```
### 5.3 部署环境
```yaml
### docker-compose.yml 版本
services:
sdk-server:
build:
context: ./server
image: python:3.11-slim
mongo:
image: mongo:6.0
redis:
image: redis:7-alpine
nginx:
image: nginx:1.24-alpine
minio:
image: minio/minio:latest
```
---
### 六、技术风险评估
### 6.1 风险矩阵
| 技术 | 风险点 | 可能性 | 影响 | 应对措施 |
|------|--------|--------|------|----------|
| Frida | 被APP检测 | 中 | 中 | 准备纯UI备选方案 |
| Frida | 版本兼容 | 低 | 中 | 锁定稳定版本 |
| uiautomator2 | 元素定位失效 | 中 | 中 | 多种定位策略 |
| MongoDB | 性能瓶颈 | 低 | 中 | 索引优化 + 分片 |
| WebSocket | 连接不稳定 | 低 | 高 | 重连机制 + 心跳 |
### 6.2 备选方案
| 主方案 | 备选方案 | 切换条件 |
|--------|----------|----------|
| Frida + uiautomator2 | 纯uiautomator2 | Frida被检测 |
| MongoDB | PostgreSQL | 需要强事务 |
| FastAPI | Flask | 团队更熟悉 |
| Docker | 宝塔面板 | 运维更习惯 |
---
### 七、技术栈学习资源
### 7.1 必读文档
| 技术 | 官方文档 | 推荐教程 |
|------|---------|---------|
| Frida | frida.re | OWASP MASTG |
| uiautomator2 | uiautomator2.readthedocs.io | GitHub Issues |
| FastAPI | fastapi.tiangolo.com | 官方教程 |
| MongoDB | docs.mongodb.com | MongoDB University |
### 7.2 社区资源
| 资源 | 地址 | 说明 |
|------|------|------|
| Frida CodeShare | codeshare.frida.re | SSL Bypass脚本 |
| awesome-frida | GitHub | Frida资源集合 |
| openatx/uiautomator2 | GitHub | 官方仓库 |
| fastapi-best-practices | GitHub | 最佳实践 |
---
### 八、选型总结
### 8.1 最终技术栈
```yaml
设备端:
开发语言: Kotlin 1.9+
UI自动化: uiautomator2 3.x
Hook框架: Frida 16.x
通信: OkHttp 4.x WebSocket
服务端:
开发语言: Python 3.11+
Web框架: FastAPI 0.110+
WebSocket: websockets 12.0
脚本引擎: 自研 BaseScript
数据层:
业务库: MongoDB 6.0
缓存: Redis 7.x
文件: MinIO
部署:
容器: Docker + Docker Compose
代理: Nginx 1.24
进程: Uvicorn
```
### 8.2 选型理由总结
1. **Frida**：最成熟的动态Hook方案，社区活跃，SSL Bypass脚本完善
2. **uiautomator2**：Python接口友好，学习成本低，中文社区活跃
3. **FastAPI**：异步优先，WebSocket原生支持，自动文档
4. **MongoDB**：灵活Schema，向量索引支持，私域银行标准
5. **Docker**：一键部署，环境隔离，易于扩展
---
# Part B：数据库设计
## 一、数据库选型
| 数据库 | 用途 | 版本 |
|--------|------|------|
| **MongoDB** | 业务数据（设备/日志/抓包） | 6.0+ |
| **Redis** | 缓存/状态/队列 | 7.x |
| **MinIO** | 文件存储（截图/录屏） | 最新 |
---
## 二、MongoDB Collections
### 2.1 设备集合 (devices)
```javascript
// db.devices
{
_id: ObjectId,
device_id: String, // 设备唯一ID（主键）
name: String, // 设备名称
model: String, // 设备型号 (Redmi K60)
android_version: String, // Android版本 (14)
agent_version: String, // Agent版本 (1.0.0)
status: String, // online/offline/busy
capabilities: [String], // 能力列表 ['frida', 'u2', 'scrcpy']
apps: [String], // 已安装APP ['wechat', 'douyin']
ip: String, // 设备IP
battery: Number, // 电量
last_heartbeat: Date, // 最后心跳
created_at: Date,
updated_at: Date
}
// 索引
db.devices.createIndex({ device_id: 1 }, { unique: true })
db.devices.createIndex({ status: 1 })
db.devices.createIndex({ last_heartbeat: 1 })
```
### 2.2 执行日志集合 (execution_logs)
```javascript
// db.execution_logs
{
_id: ObjectId,
device_id: String, // 设备ID
script: String, // 脚本名 (wechat/douyin/xhs)
action: String, // 动作名 (send_message/get_friends)
params: Object, // 参数
status: String, // success/failed/timeout
result: Object, // 返回结果
error: String, // 错误信息
duration_ms: Number, // 执行耗时
created_at: Date
}
// 索引
db.execution_logs.createIndex({ device_id: 1, created_at: -1 })
db.execution_logs.createIndex({ script: 1, action: 1 })
db.execution_logs.createIndex({ status: 1 })
db.execution_logs.createIndex({ created_at: 1 }, { expireAfterSeconds: 7776000 }) // 90天过期
```
### 2.3 抓包数据集合 (capture_data)
```javascript
// db.capture_data
{
_id: ObjectId,
device_id: String, // 设备ID
package: String, // APP包名
url: String, // 请求URL
method: String, // GET/POST
headers: Object, // 请求头
request_body: String, // 请求体
response_code: Number, // 响应码
response_body: String, // 响应体
timestamp: Date
}
// 索引
db.capture_data.createIndex({ device_id: 1, timestamp: -1 })
db.capture_data.createIndex({ package: 1 })
db.capture_data.createIndex({ url: "text" }) // 全文索引
db.capture_data.createIndex({ timestamp: 1 }, { expireAfterSeconds: 604800 }) // 7天过期
```
### 2.4 消息记录集合 (messages)
```javascript
// db.messages
{
_id: ObjectId,
device_id: String, // 设备ID
platform: String, // 平台 (wechat/douyin/xhs)
direction: String, // 方向 (in/out)
from_id: String, // 发送者ID
to_id: String, // 接收者ID
content: String, // 消息内容
msg_type: String, // 消息类型 (text/image/voice)
status: String, // sent/delivered/failed
created_at: Date
}
// 索引
db.messages.createIndex({ device_id: 1, created_at: -1 })
db.messages.createIndex({ platform: 1, direction: 1 })
db.messages.createIndex({ from_id: 1 })
db.messages.createIndex({ to_id: 1 })
```
### 2.5 API密钥集合 (api_keys)
```javascript
// db.api_keys
{
_id: ObjectId,
key: String, // API Key（哈希存储）
name: String, // 名称描述
tenant_id: String, // 租户ID
permissions: [String], // 权限列表
rate_limit: Number, // 每分钟请求限制
is_active: Boolean, // 是否激活
last_used_at: Date,
created_at: Date,
expires_at: Date // 过期时间
}
// 索引
db.api_keys.createIndex({ key: 1 }, { unique: true })
db.api_keys.createIndex({ tenant_id: 1 })
db.api_keys.createIndex({ is_active: 1 })
```
---
## 三、Redis数据结构
### 3.1 设备状态
```redis
# 设备在线状态
Key: device:status:{device_id}
Value: "online" | "offline" | "busy"
TTL: 60s (心跳刷新)
# 示例
SET device:status:device-001 "online" EX 60
```
### 3.2 设备能力缓存
```redis
# 设备能力列表
Key: device:caps:{device_id}
Value: JSON Array
TTL: 3600s (1小时)
# 示例
SET device:caps:device-001 '["frida","u2","scrcpy"]' EX 3600
```
### 3.3 指令队列
```redis
# 待执行指令队列
Key: queue:commands:{device_id}
Type: List
Value: Command JSON
# 示例
LPUSH queue:commands:device-001 '{"cmd_id":"xxx","script":"wechat","action":"send"}'
```
### 3.4 响应等待
```redis
# 等待响应的指令
Key: pending:{command_id}
Value: JSON { device_id, status, timeout }
TTL: 30s
# 示例
SET pending:cmd-001 '{"device_id":"device-001","status":"waiting"}' EX 30
```
### 3.5 限流计数
```redis
# API限流计数器
Key: ratelimit:{api_key}:{minute}
Type: Counter
TTL: 60s
# 示例
INCR ratelimit:key-001:202601261030
EXPIRE ratelimit:key-001:202601261030 60
```
---
## 四、ER图
```mermaid
erDiagram
DEVICES ||--o{ EXECUTION_LOGS : "产生"
DEVICES ||--o{ CAPTURE_DATA : "抓取"
DEVICES ||--o{ MESSAGES : "收发"
API_KEYS ||--o{ DEVICES : "管理"
DEVICES {
ObjectId _id
String device_id PK
String name
String model
String android_version
String agent_version
String status
Array capabilities
Array apps
Date last_heartbeat
}
EXECUTION_LOGS {
ObjectId _id
String device_id FK
String script
String action
Object params
String status
Object result
Number duration_ms
Date created_at
}
CAPTURE_DATA {
ObjectId _id
String device_id FK
String package
String url
String method
Object headers
String request_body
Number response_code
String response_body
Date timestamp
}
MESSAGES {
ObjectId _id
String device_id FK
String platform
String direction
String from_id
String to_id
String content
String msg_type
Date created_at
}
API_KEYS {
ObjectId _id
String key
String name
String tenant_id
Array permissions
Boolean is_active
Date expires_at
}
```
---
## 五、Pydantic模型
```python
# models/device.py
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime
class DeviceBase(BaseModel):
"""设备基础模型"""
device_id: str = Field(..., description="设备唯一ID")
name: str = Field(..., description="设备名称")
model: str = Field(..., description="设备型号")
android_version: str = Field(..., description="Android版本")
agent_version: str = Field(..., description="Agent版本")
class DeviceCreate(DeviceBase):
"""创建设备"""
capabilities: List[str] = Field(default_factory=list)
apps: List[str] = Field(default_factory=list)
class DeviceInDB(DeviceBase):
"""数据库中的设备"""
status: str = "offline"
capabilities: List[str] = []
apps: List[str] = []
ip: Optional[str] = None
battery: Optional[int] = None
last_heartbeat: Optional[datetime] = None
created_at: datetime = Field(default_factory=datetime.utcnow)
updated_at: datetime = Field(default_factory=datetime.utcnow)
class DeviceResponse(DeviceInDB):
"""设备响应"""
pass
```
```python
# models/execution.py
from pydantic import BaseModel, Field
from typing import Any, Dict, Optional
from datetime import datetime
class ExecuteRequest(BaseModel):
"""执行请求"""
script: str = Field(..., description="脚本名称")
action: str = Field(..., description="动作名称")
params: Dict[str, Any] = Field(default_factory=dict)
timeout: int = Field(default=30, ge=1, le=300)
class ExecutionLog(BaseModel):
"""执行日志"""
device_id: str
script: str
action: str
params: Dict[str, Any]
status: str # success/failed/timeout
result: Optional[Dict[str, Any]] = None
error: Optional[str] = None
duration_ms: int
created_at: datetime = Field(default_factory=datetime.utcnow)
```
---
## 六、数据迁移脚本
```python
# scripts/init_db.py
from pymongo import MongoClient
from pymongo.errors import CollectionInvalid
def init_database():
"""初始化数据库"""
client = MongoClient("mongodb://localhost:27017")
db = client["workphone"]
# 创建集合和索引
# devices
try:
db.create_collection("devices")
except CollectionInvalid:
pass
db.devices.create_index("device_id", unique=True)
db.devices.create_index("status")
db.devices.create_index("last_heartbeat")
# execution_logs
try:
db.create_collection("execution_logs")
except CollectionInvalid:
pass
db.execution_logs.create_index([("device_id", 1), ("created_at", -1)])
db.execution_logs.create_index([("script", 1), ("action", 1)])
db.execution_logs.create_index("created_at", expireAfterSeconds=7776000) # 90天
# capture_data
try:
db.create_collection("capture_data")
except CollectionInvalid:
pass
db.capture_data.create_index([("device_id", 1), ("timestamp", -1)])
db.capture_data.create_index("package")
db.capture_data.create_index("timestamp", expireAfterSeconds=604800) # 7天
# messages
try:
db.create_collection("messages")
except CollectionInvalid:
pass
db.messages.create_index([("device_id", 1), ("created_at", -1)])
db.messages.create_index([("platform", 1), ("direction", 1)])
# api_keys
try:
db.create_collection("api_keys")
except CollectionInvalid:
pass
db.api_keys.create_index("key", unique=True)
db.api_keys.create_index("tenant_id")
print("数据库初始化完成")
if __name__ == "__main__":
init_database()
```
---
## 七、性能优化建议
### 7.1 MongoDB优化
| 优化项 | 说明 |
|--------|------|
| **索引覆盖** | 确保常用查询使用索引 |
| **TTL索引** | 自动清理过期数据 |
| **分片** | 大数据量时启用分片 |
| **连接池** | 复用连接，减少开销 |
### 7.2 Redis优化
| 优化项 | 说明 |
|--------|------|
| **Pipeline** | 批量操作减少网络往返 |
| **内存限制** | 设置maxmemory和淘汰策略 |
| **持久化** | AOF持久化保证数据安全 |
| **集群** | 大规模时使用Redis Cluster |
### 7.3 查询优化示例
```python
# 优化前：全表扫描
devices = db.devices.find({"status": "online"})
# 优化后：使用索引 + 投影
devices = db.devices.find(
{"status": "online"},
{"device_id": 1, "name": 1, "model": 1} # 只返回需要的字段
).hint("status_1") # 强制使用索引
```
---
## 八、数据安全
### 8.1 敏感数据处理
| 数据类型 | 处理方式 |
|----------|----------|
| API Key | Argon2 Hash存储 |
| 设备Token | JWT签名 |
| 抓包数据 | 可选加密存储 |
| 消息内容 | 可选加密存储 |
### 8.2 备份策略
```bash
# MongoDB备份
mongodump --uri="mongodb://localhost:27017/workphone" --out=/backup/$(date +%Y%m%d)
# Redis备份
redis-cli BGSAVE
cp /var/lib/redis/dump.rdb /backup/redis_$(date +%Y%m%d).rdb
```
### 8.3 审计日志
```javascript
// 所有敏感操作记录到 audit_logs
db.audit_logs.insertOne({
action: "execute_script",
device_id: "device-001",
script: "wechat",
operator: "api_key_xxx",
ip: "1.2.3.4",
timestamp: new Date()
})
```

545
开发文档/2、架构/系统架构.md Normal file
View File

@@ -0,0 +1,545 @@
# 工作手机SDK v3.0 系统架构
> 创建日期：2026-01-26 | 架构师：卡若 | 状态：已确认
>
> **重要更新(2026-01-26)**：新增AI Agent层 + Skill引擎，参见《AI控制方案.md》
---
## 一、整体架构图（AI+Skill版）
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 存客宝生态系统 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ 存客宝后端 (ThinkPHP) │ │
│ │ │ │
│ │ $sdk = new WorkPhoneSDK('https://workphone.xxx.com', 'key'); │ │
│ │ $sdk->execute('device-001', 'wechat', 'send_message', [...]); │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
└─────────────────────────────────────┼───────────────────────────────────────┘
│ HTTPS REST API
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 工作手机SDK服务器（云端部署 - 腾讯云/阿里云） │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Nginx (反向代理/SSL卸载) │ │
│ │ Port: 443 (HTTPS/WSS) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴───────────────────────────┐ │
│ │ │ │
│ ┌─────▼──────┐ ┌─────────────────┐ │ │
│ │ API Gateway│ │ WebSocket Hub │ │ │
│ │ (FastAPI) │ │ (设备长连接) │ │ │
│ │ Port: 8000 │ │ Port: 8765 │ │ │
│ └─────┬──────┘ └────────┬────────┘ │ │
│ │ │ │ │
│ ┌─────┴──────────────────────────────┴────────────────────────┴───────┐ │
│ │ 核心服务层 │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 设备管理 │ │ 指令路由 │ │ 脚本引擎 │ │ │
│ │ │ DeviceSvc │ │ CommandSvc │ │ ScriptEngine│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 抓包服务 │ │ 消息队列 │ │ 任务调度 │ │ │
│ │ │ CaptureSvc │ │ QueueSvc │ │ SchedulerSvc│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────┴───────────────────────────────────┐ │
│ │ 数据层 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ MongoDB │ │ Redis │ │ MinIO │ │ 脚本仓库 │ │ │
│ │ │ 业务数据 │ │ 缓存/队列 │ │ 文件存储 │ │ Git仓库 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
WebSocket (wss://xxx:443/ws)
设备主动连接到服务器
│
┌───────────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ 手机设备 A │ │ 手机设备 B │ │ 手机设备 N │
│ (厦门) │ │ (北京) │ │ (上海) │
│ │ │ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │
│ │工作手机 │ │ │ │工作手机 │ │ │ │工作手机 │ │
│ │Agent APP │ │ │ │Agent APP │ │ │ │Agent APP │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ Frida │ │ │ │ Frida │ │ │ │ Frida │ │
│ │ u2 │ │ │ │ u2 │ │ │ │ u2 │ │
│ │ scrcpy │ │ │ │ scrcpy │ │ │ │ scrcpy │ │
│ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │
│ │ │ │ │ │
│ 微信/抖音/... │ │ Soul/探探/... │ │ 新APP... │
└───────────────┘ └───────────────┘ └───────────────┘
```
---
## 二、核心设计原则
| 原则 | 说明 | 实现方式 |
|------|------|----------|
| **双模式运行** | 脚本模式（精确）+ AI模式（智能） | Skill引擎 + DroidRun Agent |
| **统一服务交互层** | 一套API，多通道自动路由 | Facade模式 + 智能路由器 |
| **有状态前端 + 无状态后端** | 前端维护连接，后端处理业务 | WebSocket Hub + FastAPI |
| **设备主动连接** | 解决NAT穿透问题 | 设备启动后主动连接云端 |
| **脚本→Skill演进** | 从硬编码脚本升级为可复用Skill | BaseSkill + 注册表 |
| **混合Root策略** | 灵活适应不同场景 | 免Root + Gadget + Magisk |
| **容错与可观测** | 超时/降级可配置、日志可追踪 | MESSAGE_SEND_TIMEOUT、200+success/error+error_code、SDK 控制失败降级 AI Agent、关键日志 [message/send]/[ws_hub] |
**模块边界（耦合可控）**：unified 仅通过 `_execute_skill(device_id, script, action, params)` 调用执行层；执行层由 ws_hub（在线设备）或 adb（离线兜底）实现，设备端 Agent 通过 WebSocket 与 ws_hub 通信；新增平台仅扩展 Skill 与路由表，不改 unified 主流程。
---
## 二.1 新增：AI Agent + Skill架构
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 核心服务层 (升级版) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 统一服务交互层 (Facade) │ │
│ │ • send_message(platform, to, content) │ │
│ │ • 自动路由：官方API → SDK控制 → AI Agent │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴───────────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ 传统脚本模式 │ │ AI Agent模式 │ │
│ │ │ │ │ │
│ │ Skill引擎 │ │ DroidRun Agent │ │
│ │ • WeChatSkill │ │ • 自然语言输入 │ │
│ │ • DouyinSkill │ │ • LLM规划执行 │ │
│ │ • XiaohongshuSkill│ │ • DeepSeek/GPT-4o │ │
│ │ │ │ │ │
│ │ 优势：100%可控 │ │ 优势：自适应灵活 │ │
│ │ 成本：免费 │ │ 成本：¥0.02/次 │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 设备控制层 │ │
│ │ uiautomator2 (UI自动化) + Frida (抓包) + 截图OCR (视觉理解) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
**关键文档**：
- 《AI控制方案.md》- AI Agent层详细设计
- 《通用服务交互层.md》- 统一接口与智能路由
---
## 三、模块设计
### 3.0 模块拆分与开发视图（按需求开发）
以下模块与《开发进度总表》一一对应，开发按「需求→任务→验收」执行。
| 模块 | 需求来源 | 开发任务摘要 | 进度 | 说明 |
|------|----------|--------------|------|------|
| **M1 接入与网关** | 存客宝对接、统一控制 | API Gateway、健康检查、认证、统一路由 | ✅ 100% | FastAPI + Nginx |
| **M2 设备与连接** | 设备管理闭环、实时状态 | WebSocket Hub、设备注册、心跳、在线状态 | ✅ 100% | 心跳 5/10/30s 可配置 |
| **M3 指令与执行** | 操作闭环、服务器决策 | 指令路由、ACK、ADB/WebSocket 双模式、超时重试 | ✅ 100% | CommandSvc |
| **M4 设备管理服务** | 设备信息、能力上报 | DeviceSvc、设备列表/详情、能力/APP 列表 | ✅ 100% | MongoDB 持久化 |
| **M5 脚本引擎（Skill）** | 多 APP 统一控制 | BaseScript、注册表、微信/抖音/小红书/闲鱼 Skill | 🔧 75% | 微信 100%，抖/红 75%，闲鱼 15% |
| **M6 抓包服务** | 数据采集、SSL Bypass | CaptureSvc、Frida 脚本、抓包启停/数据拉取 | 📋 待做 | 依赖 Frida |
| **M7 消息队列与调度** | 高并发、任务排队 | QueueSvc、SchedulerSvc（可选） | ✅ 基础 | 当前同步+Redis 即可 |
| **M8 Agent 端** | 设备执行、反馈 | WebSocket 客户端、心跳/重连、命令执行、各 Skill 实现 | ✅ 95% | 抖/红服务端路由待补 |
| **M9 存客宝对接** | 业务侧调用 | PHP SDK、TS SDK、统一 API、登录认证 | ✅ 100% | 对接清单已闭环 |
| **M10 数据与存储** | 数据闭环 | MongoDB、Redis、MySQL（存客宝）、MinIO（可选） | ✅ 100% | 本地 108 表 + workphone_sdk |
| **M11 部署与运维** | 本地/生产环境 | Docker、端口规划、凭证、文档、一键启动 | ✅ 100% | start_sdk.sh |
| **M12 AI Agent** | 智能控制、自然语言 | DroidRun Agent、LLM 规划、与 Skill 双模式 | 🔧 50% | 可选增强 |
**进度汇总**：总进度约 **96%**。详见 → [开发进度总表](../10、项目管理/开发进度总表.md)。
**按需求开发顺序建议**（未完成部分）：
1. 🔴 抖音/小红书：补全服务端路由（约 2h）
2. 🟡 微信消息 E2E：端到端验证（按验证指南执行）
3. 🟡 AI Agent DroidRun：集成与联调（约 4h）
4. 🟢 闲鱼 Skill：完整实现（约 8h）
5. 🟢 抓包服务 + Frida SSL Bypass（约 4h）
---
### 3.1 API Gateway (FastAPI)
**职责**：接收REST API请求，路由到对应服务
```
/api
├── /health # 健康检查
├── /devices # 设备管理
│ ├── GET # 获取设备列表
│ ├── GET /{id} # 获取设备详情
│ └── POST /{id}/screenshot # 截图
├── /devices/{id}/execute # 执行脚本
├── /devices/{id}/capture # 抓包控制
│ ├── POST /start # 开始抓包
│ ├── POST /stop # 停止抓包
│ └── GET /data # 获取数据
└── /scripts # 脚本管理
```
### 3.2 WebSocket Hub
**职责**：管理设备WebSocket连接，转发指令和响应
```python
# 连接池管理
device_connections: Dict[str, WebSocket] = {} # device_id -> websocket
pending_commands: Dict[str, asyncio.Future] = {} # command_id -> future
# 心跳保活（30秒间隔）
async def heartbeat_handler(device_id: str):
while device_id in device_connections:
await asyncio.sleep(30)
await device_connections[device_id].send_json({"type": "ping"})
```
### 3.3 脚本引擎 (ScriptEngine)
**职责**：加载、执行APP控制脚本
```
scripts/
├── base.py # 基类 BaseScript
├── registry.py # 脚本注册表
├── wechat/script.py # 微信脚本
├── douyin/script.py # 抖音脚本
├── xhs/script.py # 小红书脚本
└── templates/new_app.py # 新APP模板
```
### 3.4 设备管理服务 (DeviceSvc)
**职责**：设备注册、状态管理、信息查询
```python
class Device:
device_id: str # 设备唯一ID
name: str # 设备名称
model: str # 设备型号 (Redmi K60)
android_version: str # Android版本 (14)
agent_version: str # Agent版本 (1.0.0)
status: str # online/offline
last_heartbeat: datetime
capabilities: List[str] # ['frida', 'u2', 'scrcpy']
apps: List[str] # 已安装的目标APP
```
### 3.5 抓包服务 (CaptureSvc)
**职责**：Frida脚本管理，抓包数据收集
```python
class CaptureService:
async def start_capture(self, device_id: str, package: str):
"""开始抓包：加载SSL Bypass脚本"""
async def stop_capture(self, device_id: str):
"""停止抓包"""
async def get_data(self, device_id: str, filters: dict):
"""获取抓包数据"""
```
---
## 四、数据流设计
### 4.1 API请求流程
```mermaid
sequenceDiagram
participant C as 存客宝
participant N as Nginx
participant A as API Gateway
participant S as 服务层
participant W as WebSocket Hub
participant D as 设备
C->>N: HTTPS Request
N->>A: 转发请求
A->>S: 业务处理
S->>W: 发送指令
W->>D: WebSocket消息
D-->>W: 执行结果
W-->>S: 返回结果
S-->>A: 响应数据
A-->>N: HTTP Response
N-->>C: HTTPS Response
```
### 4.2 设备连接流程
```mermaid
sequenceDiagram
participant D as 设备
participant W as WebSocket Hub
participant R as Redis
participant M as MongoDB
D->>W: WebSocket Connect
W-->>D: Connection Established
D->>W: register(device_info)
W->>M: 保存设备信息
W->>R: 设置在线状态
W-->>D: register_ok
loop 心跳循环 (30s)
D->>W: heartbeat
W->>R: 刷新TTL
W-->>D: pong
end
```
### 4.3 脚本执行流程
```mermaid
sequenceDiagram
participant A as API
participant E as ScriptEngine
participant R as Registry
participant S as Script
participant W as WebSocket
participant D as 设备
A->>E: execute(device, script, action, params)
E->>R: get_script(script_name)
R-->>E: Script Class
E->>S: new Script(device_id)
E->>S: call action(**params)
S->>W: send_command
W->>D: WebSocket message
D-->>W: response
W-->>S: result
S-->>E: return result
E-->>A: execution result
```
---
## 五、服务器模块结构
### 5.1 项目目录
```
server/
├── main.py # 入口文件
├── requirements.txt # 依赖
│
├── routers/ # 路由层
│ ├── devices.py # 设备API
│ ├── execute.py # 执行API
│ ├── capture.py # 抓包API
│ └── scripts.py # 脚本API
│
├── services/ # 服务层
│ ├── device_service.py # 设备服务
│ ├── command_service.py # 指令服务
│ ├── capture_service.py # 抓包服务
│ └── script_executor.py # 脚本执行器
│
├── websocket/ # WebSocket
│ ├── hub.py # 连接管理
│ ├── handlers.py # 消息处理
│ └── protocol.py # 协议定义
│
├── scripts/ # 脚本引擎
│ ├── base.py # 基类
│ ├── registry.py # 注册表
│ ├── wechat/ # 微信脚本
│ ├── douyin/ # 抖音脚本
│ └── xhs/ # 小红书脚本
│
├── models/ # 数据模型
│ ├── device.py
│ ├── command.py
│ └── capture.py
│
├── core/ # 核心配置
│ ├── config.py # 环境变量
│ ├── database.py # 数据库连接
│ └── security.py # 认证鉴权
│
└── utils/ # 工具函数
├── logger.py
└── helpers.py
```
### 5.2 设备端目录
```
android-agent/
├── app/src/main/java/com/workphone/agent/
│ ├── MainActivity.kt # 主界面
│ ├── WorkPhoneApp.kt # Application
│ │
│ ├── websocket/ # WebSocket
│ │ ├── WebSocketClient.kt
│ │ ├── MessageHandler.kt
│ │ └── ReconnectManager.kt
│ │
│ ├── commands/ # 命令处理
│ │ ├── CommandExecutor.kt
│ │ └── ...Commands.kt
│ │
│ ├── automation/ # 自动化
│ │ ├── U2Client.kt
│ │ └── ScriptRunner.kt
│ │
│ ├── capture/ # 抓包
│ │ ├── FridaManager.kt
│ │ └── CaptureService.kt
│ │
│ ├── services/ # 服务
│ │ ├── AgentService.kt
│ │ └── BootReceiver.kt
│ │
│ └── utils/ # 工具
│ ├── DeviceInfo.kt
│ ├── Logger.kt
│ └── Preferences.kt
│
├── frida-scripts/ # Frida脚本
│ ├── ssl_bypass.js
│ └── common.js
│
└── build.gradle.kts
```
---
## 六、部署架构
### 6.1 单机部署（≤200设备）
```
┌────────────────────────────────────────┐
│ 单台云服务器 (4核8G) │
│ │
│ ┌────────────┐ ┌────────────┐ │
│ │ Nginx │ │ FastAPI │ │
│ │ :443 │ │ :8000 │ │
│ └────────────┘ └────────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ │
│ │ WebSocket │ │ MongoDB │ │
│ │ :8765 │ │ :27017 │ │
│ └────────────┘ └────────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ │
│ │ Redis │ │ MinIO │ │
│ │ :6379 │ │ :9000 │ │
│ └────────────┘ └────────────┘ │
│ │
└────────────────────────────────────────┘
```
### 6.2 集群部署（>200设备）
```
┌────────────┐
│ SLB │
│ 负载均衡 │
└─────┬──────┘
│
┌───────────────┼───────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ SDK节点1 │ │ SDK节点2 │ │ SDK节点N │
│ 4核8G │ │ 4核8G │ │ 4核8G │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
└───────────────┼───────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
┌───▼────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ Redis │ │ MongoDB │ │ MinIO │
│ 集群 │ │ 副本集 │ │ 集群 │
└────────┘ └───────────┘ └───────────┘
```
---
## 七、技术选型总览
| 层级 | 技术 | 版本 | 选型理由 |
|:---|:---|:---|:---|
| **前端框架** | - | - | 无独立前端，集成存客宝 |
| **后端框架** | FastAPI | 0.110+ | 异步 + 类型安全 + 自动文档 |
| **WebSocket** | websockets | - | 高性能异步WebSocket |
| **数据库** | MongoDB | 6.0 | 文档型 + 向量索引 |
| **缓存** | Redis | 7.x | 高性能 + Pub/Sub |
| **文件存储** | MinIO | - | S3兼容 + 私有化 |
| **设备端** | Kotlin | 1.9+ | 现代Android开发 |
| **自动化** | uiautomator2 | 3.x | Python接口 + 稳定 |
| **Hook框架** | Frida | 16.x | SSL Bypass + 动态Hook |
| **反向代理** | Nginx | 1.24 | SSL卸载 + 负载均衡 |
| **容器化** | Docker | 24.x | 一键部署 |
---
## 八、版本要求
| 组件 | 最低版本 | 推荐版本 |
|------|---------|---------|
| Python | 3.10 | 3.11+ |
| Node.js | 18.x | 20.x |
| MongoDB | 6.0 | 7.0 |
| Redis | 7.0 | 7.2 |
| Android | 7.0 (API 24) | 14 (API 34) |
| Docker | 24.0 | 25.0 |
---
## 附：存客宝对接与方案补充（合并自原独立文档）
### 本地环境端口
| 组件 | 端口 | 说明 |
|------|------|------|
| 存客宝前端 | 3000 | React |
| 触客宝前端 | 3001 | React |
| 存客宝后端 | 8081 | ThinkPHP |
| 工作手机SDK | 8899 | FastAPI+WebSocket |
| MySQL | 3307 | cunkebao 108表 |
| MongoDB | 27017 | workphone_sdk |
| Redis | 6380 | 缓存 |
### 三大闭环
- **数据闭环**：存客宝DB ↔ AI数字员工可读写
- **设备管理闭环**：注册→心跳(5/10/30s可配置)→在线/离线
- **操作闭环**：服务器→SDK→手机执行→结果回传
### AI Agent方案
- 定位：自然语言控制手机，与脚本双轨（80%脚本+20%AI）
- 参考：DroidRun+LLM；成本约¥0.02/次
### 优化路线（6周）
- Phase 1-2：服务端/设备端骨架、WebSocket、设备管理
- Phase 3-4：微信/抖音/小红书/闲鱼Skill，统一交互层
- Phase 5-6：抓包、AI Agent、压测上线

15
开发文档/3、原型/README.md Normal file
View File

@@ -0,0 +1,15 @@
# 3、原型
**项目**：工作手机SDK v3.0（以服务端 API + 设备端执行为主，无独立 C 端 UI；原型侧重管控台/配置界面规范。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 96%；进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [原型设计规范.md](原型设计规范.md) | 原型设计规范 |

324
开发文档/3、原型/原型设计规范.md Normal file
View File

@@ -0,0 +1,324 @@
# 工作手机SDK v3.0 原型设计规范
> 创建日期：2026-01-26 | 设计师：卡若
---
## 一、项目说明
本项目为**后端SDK服务**，不包含独立前端界面。主要对接方式：
1. **存客宝后端调用** - PHP通过REST API调用SDK
2. **管理后台** - 可选的简单管理界面（Web Dashboard）
3. **设备端Agent** - Android APP界面
---
## 二、设备端Agent APP界面
### 2.1 主界面结构
```
┌────────────────────────────────────────┐
│ 工作手机Agent │
├────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────┐ │
│ │ 连接状态指示器 │ │
│ │ │ │
│ │ 🟢 已连接 │ │
│ │ 服务器: workphone.xxx.com │ │
│ │ 心跳: 正常 │ │
│ │ │ │
│ └────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────┐ │
│ │ 设备信息 │ │
│ │ │ │
│ │ 设备ID: device-001 │ │
│ │ 型号: Redmi K60 │ │
│ │ Android: 14 │ │
│ │ Agent版本: 1.0.0 │ │
│ │ │ │
│ └────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────┐ │
│ │ 能力状态 │ │
│ │ │ │
│ │ ✅ uiautomator2 │ │
│ │ ✅ Frida │ │
│ │ ⬜ scrcpy │ │
│ │ │ │
│ └────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────┐ │
│ │ [配置服务器] [查看日志] │ │
│ └────────────────────────────────┘ │
│ │
└────────────────────────────────────────┘
```
### 2.2 配置界面
```
┌────────────────────────────────────────┐
│ ← 服务器配置 │
├────────────────────────────────────────┤
│ │
│ 服务器地址 │
│ ┌────────────────────────────────┐ │
│ │ wss://workphone.xxx.com/ws │ │
│ └────────────────────────────────┘ │
│ │
│ 设备名称 │
│ ┌────────────────────────────────┐ │
│ │ 工作手机1 │ │
│ └────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────┐ │
│ │ [测试连接] │ │
│ └────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────┐ │
│ │ [保存] │ │
│ └────────────────────────────────┘ │
│ │
└────────────────────────────────────────┘
```
### 2.3 日志界面
```
┌────────────────────────────────────────┐
│ ← 运行日志 │
├────────────────────────────────────────┤
│ │
│ [INFO] 10:30:00 连接服务器成功 │
│ [INFO] 10:30:01 注册设备完成 │
│ [INFO] 10:30:30 心跳正常 │
│ [INFO] 10:31:00 收到execute指令 │
│ [INFO] 10:31:02 执行wechat.send完成 │
│ [INFO] 10:31:30 心跳正常 │
│ [WARN] 10:32:00 网络波动 │
│ [INFO] 10:32:03 重连成功 │
│ ... │
│ │
├────────────────────────────────────────┤
│ [清空日志] [导出日志] │
└────────────────────────────────────────┘
```
---
## 三、管理后台界面（可选）
### 3.1 设备列表页
```
┌────────────────────────────────────────────────────────────────┐
│ 工作手机SDK管理后台 [退出] │
├────────────────────────────────────────────────────────────────┤
│ │
│ 设备管理 脚本管理 抓包数据 系统设置 │
│ ──────────────────────────────────────────── │
│ │
│ 在线设备: 5/10 [刷新] │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 设备ID │ 名称 │ 状态 │ 型号 │ 操作 │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ device-001 │ 工作手机1 │ 🟢在线 │ Redmi K60 │ [详情]│ │
│ │ device-002 │ 工作手机2 │ 🟢在线 │ iPhone 15 │ [详情]│ │
│ │ device-003 │ 备用手机1 │ ⚫离线 │ OPPO A1 │ [详情]│ │
│ │ device-004 │ 测试机1 │ 🟢在线 │ 小米14 │ [详情]│ │
│ │ ... │ ... │ ... │ ... │ ... │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ < 1 2 3 ... 10 > │
│ │
└────────────────────────────────────────────────────────────────┘
```
### 3.2 设备详情页
```
┌────────────────────────────────────────────────────────────────┐
│ ← 返回 device-001 │
├────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────┐ ┌──────────────────────────────┐ │
│ │ │ │ 设备信息 │ │
│ │ [设备截图] │ │ │ │
│ │ │ │ 名称: 工作手机1 │ │
│ │ 点击截图刷新 │ │ 型号: Redmi K60 │ │
│ │ │ │ Android: 14 │ │
│ │ │ │ Agent: 1.0.0 │ │
│ │ │ │ 状态: 🟢 在线 │ │
│ │ │ │ IP: 192.168.1.100 │ │
│ │ │ │ 电量: 85% │ │
│ └──────────────────────┘ └──────────────────────────────┘ │
│ │
│ 快捷操作 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ [截图] [UI树] [点击测试] [发送微信] [开始抓包] │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ 执行历史 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 时间 │ 脚本 │ 动作 │ 状态 │ 耗时 │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 10:31:00 │ wechat │ send_message │ ✅成功 │ 2.3s │ │
│ │ 10:30:00 │ system │ screenshot │ ✅成功 │ 0.5s │ │
│ │ 10:28:00 │ wechat │ get_friends │ ✅成功 │ 5.2s │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
```
---
## 四、交互流程图
### 4.1 设备接入流程
```mermaid
journey
title 设备接入流程
section 安装配置
下载Agent APK: 5: 用户
安装到手机: 5: 用户
配置服务器地址: 4: 用户
测试连接: 4: 用户
section 自动运行
开机自启: 5: 系统
自动连接服务器: 5: Agent
注册设备信息: 5: Agent
心跳保活: 5: Agent
section 接收指令
存客宝调用API: 5: 存客宝
服务器转发指令: 5: SDK
Agent执行操作: 4: Agent
返回执行结果: 5: Agent
```
### 4.2 脚本执行流程
```mermaid
sequenceDiagram
participant U as 运营人员
participant C as 存客宝
participant S as SDK服务
participant D as 设备Agent
participant A as 微信APP
U->>C: 点击"发送消息"
C->>S: POST /execute
S->>S: 查找设备连接
S->>D: WebSocket指令
D->>A: 打开微信
D->>A: 搜索联系人
D->>A: 点击聊天
D->>A: 输入内容
D->>A: 点击发送
A-->>D: 发送完成
D-->>S: 返回结果
S-->>C: HTTP响应
C-->>U: 显示"发送成功"
```
---
## 五、状态指示器设计
### 5.1 设备状态
| 状态 | 图标 | 颜色 | 说明 |
|------|------|------|------|
| 在线 | 🟢 | #22C55E | 正常连接 |
| 忙碌 | 🟡 | #F59E0B | 正在执行任务 |
| 离线 | ⚫ | #6B7280 | 未连接 |
| 错误 | 🔴 | #EF4444 | 连接异常 |
### 5.2 执行状态
| 状态 | 图标 | 颜色 | 说明 |
|------|------|------|------|
| 成功 | ✅ | #22C55E | 执行成功 |
| 失败 | ❌ | #EF4444 | 执行失败 |
| 超时 | ⏱️ | #F59E0B | 执行超时 |
| 进行中 | ⏳ | #3B82F6 | 正在执行 |
---
## 六、通知设计
### 6.1 Agent通知栏
```
┌────────────────────────────────────────┐
│ 工作手机Agent 运行中 │
│ 设备ID: device-001 | 已连接 │
│ 点击查看详情 │
└────────────────────────────────────────┘
```
### 6.2 异常通知
```
┌────────────────────────────────────────┐
│ ⚠️ 工作手机Agent │
│ 连接已断开，正在重连... │
│ 点击查看详情 │
└────────────────────────────────────────┘
```
---
## 七、设计规范
### 7.1 配色方案
| 用途 | 色值 | Tailwind |
|:---|:---|:---|
| 主色 | #3B82F6 | blue-500 |
| 成功 | #22C55E | green-500 |
| 警告 | #F59E0B | amber-500 |
| 错误 | #EF4444 | red-500 |
| 文字主 | #111827 | gray-900 |
| 文字次 | #6B7280 | gray-500 |
| 背景 | #F9FAFB | gray-50 |
| 边框 | #E5E7EB | gray-200 |
### 7.2 字体规范
| 元素 | 字号 | 字重 |
|------|------|------|
| 标题 | 18sp | 600 |
| 副标题 | 16sp | 500 |
| 正文 | 14sp | 400 |
| 说明文字 | 12sp | 400 |
### 7.3 间距规范
| 元素 | 内边距 | 外边距 |
|------|--------|--------|
| 卡片 | 16dp | 8dp |
| 按钮 | 12dp 24dp | 8dp |
| 列表项 | 16dp | 0 |
---
## 八、响应式适配
### 8.1 管理后台
| 断点 | 布局 |
|------|------|
| < 768px | 单列布局，隐藏侧边栏 |
| 768px - 1024px | 两列布局 |
| > 1024px | 完整布局 |
### 8.2 Agent APP
- 适配 360dp - 420dp 宽度
- 支持深色模式
- 适配刘海屏/挖孔屏

16
开发文档/4、前端/README.md Normal file
View File

@@ -0,0 +1,16 @@
# 4、前端
**项目**：工作手机SDK v3.0（管理端采用苹果毛玻璃风格）
**规则**：本目录除本 README 外最多 **3 个主文档**。
**当前状态**：设备端Agent前端规范已有；管理端（毛玻璃风格）已设计，待开发。进度以 [开发进度总表](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [前端开发规范.md](前端开发规范.md) | 设备端Android Agent APP开发规范（Kotlin） |
| [管理端前端开发规范（毛玻璃风格）.md](管理端前端开发规范（毛玻璃风格）.md) | **新增**：Web管理端设计规范（React+Next.js+毛玻璃UI） |

185
开发文档/4、前端/v0配置.md Normal file
View File

@@ -0,0 +1,185 @@
# 🎨 v0模型配置（前端AI生成）
> 使用v0 API自动生成高质量React/Next.js组件
---
## 🔑 API配置（直接使用）
```yaml
API_URL: https://api.v0.dev/v1
API_KEY: v1:C6mw1SlvXsJdlO4VFEXSQEVf:519gA0DPqIMbjvfMh7CXf4B2
MODEL: v0-1.5-md
```
---
## 📦 可用模型
| 模型 | 用途 | 推荐场景 |
|:---|:---|:---|
| **v0-1.5-md** | 生产级UI（推荐） | 高质量组件、正式开发 |
| `v0-1.5-lg` | 复杂页面/大型组件 | 完整页面、复杂交互 |
| `v0-1.0-md` | 基础组件 | 简单UI、快速原型 |
---
## 🔧 Cursor配置
```
1. 打开Cursor设置 (Cmd + ,)
2. Models → Add Model
3. 填写：
- Model Name: v0-1.5-md
- API Key: v1:C6mw1SlvXsJdlO4VFEXSQEVf:519gA0DPqIMbjvfMh7CXf4B2
- Base URL: https://api.v0.dev/v1
4. 在聊天窗口选择模型
```
---
## 📄 项目配置文件
### .v0rc.json（放项目根目录）
```json
{
"apiUrl": "https://api.v0.dev/v1",
"apiKey": "v1:C6mw1SlvXsJdlO4VFEXSQEVf:519gA0DPqIMbjvfMh7CXf4B2",
"defaultModel": "v0-1.5-md",
"framework": "next-app-router",
"styling": "tailwind",
"componentLibrary": "shadcn/ui",
"typescript": true
}
```
### .cursorrules（放项目根目录）
```markdown
# 前端开发规则
## 技术栈
- Next.js 14+ App Router
- React 18+ TypeScript
- Tailwind CSS + shadcn/ui
- React Query + Zustand
## 项目结构
- src/app/：页面路由
- src/components/：组件库
- src/components/ui/：shadcn组件
- src/hooks/：自定义Hook
- src/lib/：工具函数
## 代码规范
- 必须使用TypeScript
- 必须中文注释
- 优先Server Components
- 必须有骨架屏loading
- 表单用react-hook-form + Zod
## UI规范
- iOS风格设计
- 移动端优先
- Tailwind原子类
- 使用cn()合并类名
```
---
## 🎯 v0提示词模板
### 标准格式
```
【组件名称】：用户登录页面
【核心功能】：手机号+验证码登录、记住密码
【设计风格】：iOS风格、圆角卡片、蓝色主题
【技术要求】：React + TypeScript + Tailwind + shadcn/ui
【约束条件】：移动端优先、有loading状态、有表单验证
```
### 快速指令
```bash
# 生成登录页
@v0 生成一个手机号登录页面，iOS风格，蓝色主题，shadcn/ui
# 生成列表组件
@v0 生成一个产品列表组件，卡片布局，支持无限滚动，有骨架屏
# 生成表单
@v0 生成一个用户信息编辑表单，react-hook-form+Zod验证
```
---
## 🐍 Python调用
```python
import openai
client = openai.OpenAI(
api_key="v1:C6mw1SlvXsJdlO4VFEXSQEVf:519gA0DPqIMbjvfMh7CXf4B2",
base_url="https://api.v0.dev/v1"
)
response = client.chat.completions.create(
model="v0-1.5-md",
messages=[{
"role": "user",
"content": """
生成一个React登录组件：
- 手机号+验证码登录
- iOS风格设计
- Tailwind CSS + shadcn/ui
- TypeScript
- 有loading和错误状态
"""
}]
)
print(response.choices[0].message.content)
```
---
## 🔗 curl测试
```bash
curl https://api.v0.dev/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer v1:C6mw1SlvXsJdlO4VFEXSQEVf:519gA0DPqIMbjvfMh7CXf4B2" \
-d '{
"model": "v0-1.5-md",
"messages": [{
"role": "user",
"content": "生成一个React登录表单组件，使用Tailwind和shadcn/ui"
}]
}'
```
---
## ⚡ 配色速查
| 用途 | 色值 | Tailwind |
|:---|:---|:---|
| 主色 | #3B82F6 | blue-500 |
| iOS蓝 | #007AFF | - |
| 成功 | #22C55E | green-500 |
| 警告 | #F59E0B | amber-500 |
| 错误 | #EF4444 | red-500 |
| 文字主 | #111827 | gray-900 |
| 文字次 | #6B7280 | gray-500 |
| iOS背景 | #F2F2F7 | gray-50 |
| 边框 | #E5E7EB | gray-200 |
---
## ⚠️ 注意
- v0适合：UI组件、页面布局、React组件
- v0不适合：后端逻辑、算法、调试（用Claude/GPT）
- 切换模型：在Cursor聊天窗口右下角选择

623
开发文档/4、前端/前端开发规范.md Normal file
View File

@@ -0,0 +1,623 @@
# 工作手机SDK v3.0 设备端开发规范
> 创建日期：2026-01-26 | 开发者：卡若
>
> 注：本项目设备端为Android Agent APP，此文档即设备端开发规范
---
## 一、技术栈
| 组件 | 技术 | 版本 |
|------|------|------|
| 开发语言 | Kotlin | 1.9+ |
| 最低Android | 7.0 | API 24 |
| 目标Android | 14 | API 34 |
| WebSocket | OkHttp | 4.12+ |
| UI自动化 | uiautomator2-server | 最新 |
| Hook框架 | Frida | 16.x |
---
## 二、项目结构
```
android-agent/
├── app/
│ ├── src/main/
│ │ ├── java/com/workphone/agent/
│ │ │ ├── MainActivity.kt # 主界面
│ │ │ ├── WorkPhoneApp.kt # Application
│ │ │ │
│ │ │ ├── websocket/
│ │ │ │ ├── WebSocketClient.kt # WebSocket客户端
│ │ │ │ ├── MessageHandler.kt # 消息处理
│ │ │ │ └── ReconnectManager.kt # 重连管理
│ │ │ │
│ │ │ ├── commands/
│ │ │ │ ├── CommandExecutor.kt # 命令执行器
│ │ │ │ ├── ClickCommand.kt # 点击命令
│ │ │ │ ├── InputCommand.kt # 输入命令
│ │ │ │ └── ScreenshotCommand.kt # 截图命令
│ │ │ │
│ │ │ ├── automation/
│ │ │ │ ├── U2Client.kt # uiautomator2客户端
│ │ │ │ └── ScriptRunner.kt # 脚本运行器
│ │ │ │
│ │ │ ├── capture/
│ │ │ │ ├── FridaManager.kt # Frida管理
│ │ │ │ └── CaptureService.kt # 抓包服务
│ │ │ │
│ │ │ ├── services/
│ │ │ │ ├── AgentService.kt # 前台服务
│ │ │ │ └── BootReceiver.kt # 开机自启
│ │ │ │
│ │ │ └── utils/
│ │ │ ├── DeviceInfo.kt # 设备信息
│ │ │ ├── Logger.kt # 日志
│ │ │ └── Preferences.kt # 配置存储
│ │ │
│ │ ├── res/
│ │ │ ├── layout/
│ │ │ ├── values/
│ │ │ └── xml/
│ │ │
│ │ └── AndroidManifest.xml
│ │
│ └── build.gradle.kts
│
├── frida-scripts/ # Frida脚本
│ ├── ssl_bypass.js # 通用SSL绕过
│ ├── wechat_hook.js # 微信Hook
│ └── common.js # 公共函数
│
└── build.gradle.kts
```
---
## 三、WebSocket客户端实现
### 3.1 基础WebSocket类
```kotlin
// websocket/WebSocketClient.kt
class WorkPhoneWebSocket(
private val serverUrl: String,
private val deviceId: String,
private val onMessage: (JSONObject) -> Unit,
private val onConnected: () -> Unit,
private val onDisconnected: () -> Unit
) {
private var webSocket: WebSocket? = null
private val client = OkHttpClient.Builder()
.readTimeout(0, TimeUnit.MILLISECONDS)
.pingInterval(30, TimeUnit.SECONDS) // OkHttp自动ping
.build()
private val reconnectManager = ReconnectManager()
fun connect() {
val request = Request.Builder()
.url("$serverUrl/ws/device/$deviceId")
.build()
webSocket = client.newWebSocket(request, object : WebSocketListener() {
override fun onOpen(webSocket: WebSocket, response: Response) {
Log.i(TAG, "WebSocket连接成功")
reconnectManager.reset()
sendRegister()
onConnected()
}
override fun onMessage(webSocket: WebSocket, text: String) {
try {
val message = JSONObject(text)
handleMessage(message)
} catch (e: Exception) {
Log.e(TAG, "消息解析失败: $text", e)
}
}
override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
Log.i(TAG, "WebSocket关闭: $reason")
onDisconnected()
scheduleReconnect()
}
override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
Log.e(TAG, "WebSocket失败: ${t.message}")
onDisconnected()
scheduleReconnect()
}
})
}
private fun handleMessage(message: JSONObject) {
when (message.getString("type")) {
"pong" -> { /* 心跳响应 */ }
"execute" -> onMessage(message)
else -> Log.w(TAG, "未知消息类型")
}
}
private fun sendRegister() {
val deviceInfo = DeviceInfo.collect()
send(JSONObject().apply {
put("type", "register")
put("data", JSONObject().apply {
put("device_id", deviceId)
put("model", deviceInfo.model)
put("android_version", deviceInfo.androidVersion)
put("agent_version", BuildConfig.VERSION_NAME)
put("capabilities", JSONArray(deviceInfo.capabilities))
})
})
}
fun sendResponse(commandId: String, code: Int, data: Any?) {
send(JSONObject().apply {
put("type", "response")
put("command_id", commandId)
put("code", code)
put("data", data)
})
}
fun send(message: JSONObject) {
webSocket?.send(message.toString())
}
private fun scheduleReconnect() {
reconnectManager.scheduleReconnect { connect() }
}
companion object {
private const val TAG = "WebSocket"
}
}
```
### 3.2 重连管理器
```kotlin
// websocket/ReconnectManager.kt
class ReconnectManager {
private var attempts = 0
private val maxAttempts = 10
private val baseDelayMs = 1000L
private val maxDelayMs = 60000L
private val handler = Handler(Looper.getMainLooper())
private var reconnectRunnable: Runnable? = null
fun scheduleReconnect(action: () -> Unit) {
if (attempts >= maxAttempts) {
Log.e(TAG, "达到最大重连次数")
return
}
// 指数退避：1s, 2s, 4s, 8s, ... 最大60s
val delay = minOf(baseDelayMs * (1 shl attempts), maxDelayMs)
attempts++
Log.i(TAG, "将在 ${delay}ms 后进行第 $attempts 次重连")
reconnectRunnable = Runnable { action() }
handler.postDelayed(reconnectRunnable!!, delay)
}
fun reset() {
attempts = 0
cancel()
}
fun cancel() {
reconnectRunnable?.let { handler.removeCallbacks(it) }
}
companion object {
private const val TAG = "Reconnect"
}
}
```
---
## 四、命令执行器
### 4.1 命令分发
```kotlin
// commands/CommandExecutor.kt
class CommandExecutor(
private val context: Context,
private val webSocket: WorkPhoneWebSocket
) {
private val u2Client = U2Client()
private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
fun execute(message: JSONObject) {
val commandId = message.getString("command_id")
val data = message.getJSONObject("data")
scope.launch {
try {
val result = when (data.getString("script")) {
"_system" -> executeSystemCommand(data)
else -> throw IllegalArgumentException("脚本应通过服务端调用")
}
webSocket.sendResponse(commandId, 200, result)
} catch (e: Exception) {
Log.e(TAG, "命令执行失败", e)
webSocket.sendResponse(commandId, 500, mapOf("error" to e.message))
}
}
}
private suspend fun executeSystemCommand(data: JSONObject): Any {
val action = data.getString("action")
val params = data.optJSONObject("params") ?: JSONObject()
return when (action) {
"screenshot" -> {
val image = u2Client.screenshot()
mapOf("image_base64" to Base64.encodeToString(image, Base64.DEFAULT))
}
"click" -> {
u2Client.click(params.getInt("x"), params.getInt("y"))
mapOf("status" to "success")
}
"click_text" -> {
u2Client.clickText(params.getString("text"))
mapOf("status" to "success")
}
"input" -> {
u2Client.input(params.getString("text"))
mapOf("status" to "success")
}
"swipe" -> {
u2Client.swipe(params.getString("direction"))
mapOf("status" to "success")
}
"ui_tree" -> {
mapOf("xml" to u2Client.dumpHierarchy())
}
"launch_app" -> {
u2Client.launchApp(params.getString("package"))
mapOf("status" to "success")
}
"stop_app" -> {
u2Client.stopApp(params.getString("package"))
mapOf("status" to "success")
}
else -> throw IllegalArgumentException("未知系统命令: $action")
}
}
companion object {
private const val TAG = "CommandExecutor"
}
}
```
### 4.2 U2客户端
```kotlin
// automation/U2Client.kt
class U2Client {
private val baseUrl = "http://127.0.0.1:7912"
private val client = OkHttpClient.Builder()
.connectTimeout(10, TimeUnit.SECONDS)
.readTimeout(30, TimeUnit.SECONDS)
.build()
suspend fun screenshot(): ByteArray = withContext(Dispatchers.IO) {
val request = Request.Builder()
.url("$baseUrl/screenshot/0?format=jpeg")
.build()
client.newCall(request).execute().use { response ->
response.body?.bytes() ?: throw IOException("Screenshot failed")
}
}
suspend fun click(x: Int, y: Int) = withContext(Dispatchers.IO) {
val body = JSONObject().apply {
put("action", "click")
put("params", JSONObject().apply {
put("x", x)
put("y", y)
})
}
postJsonRpc("click", body)
}
suspend fun clickText(text: String, timeout: Int = 10) = withContext(Dispatchers.IO) {
val selector = mapOf("mask" to 0, "text" to text)
val body = JSONObject().apply {
put("method", "waitForExists")
put("params", listOf(selector, timeout * 1000))
}
val exists = postJsonRpc("waitForExists", body)
if (exists == true) {
val clickBody = JSONObject().apply {
put("method", "click")
put("params", listOf(selector))
}
postJsonRpc("click", clickBody)
} else {
throw NoSuchElementException("Element '$text' not found")
}
}
suspend fun input(text: String) = withContext(Dispatchers.IO) {
val request = Request.Builder()
.url("$baseUrl/shell")
.post(FormBody.Builder()
.add("command", "input text '$text'")
.build())
.build()
client.newCall(request).execute().use { response ->
if (!response.isSuccessful) throw IOException("Input failed")
}
}
suspend fun swipe(direction: String) = withContext(Dispatchers.IO) {
val (fx, fy, tx, ty) = when (direction) {
"up" -> listOf(0.5, 0.8, 0.5, 0.2)
"down" -> listOf(0.5, 0.2, 0.5, 0.8)
"left" -> listOf(0.8, 0.5, 0.2, 0.5)
"right" -> listOf(0.2, 0.5, 0.8, 0.5)
else -> throw IllegalArgumentException("Unknown direction")
}
val body = JSONObject().apply {
put("method", "swipe")
put("params", listOf(fx, fy, tx, ty, 0.5))
}
postJsonRpc("swipe", body)
}
suspend fun dumpHierarchy(): String = withContext(Dispatchers.IO) {
val request = Request.Builder()
.url("$baseUrl/dump/hierarchy")
.build()
client.newCall(request).execute().use { response ->
response.body?.string() ?: throw IOException("Dump failed")
}
}
suspend fun launchApp(packageName: String) = withContext(Dispatchers.IO) {
val body = JSONObject().apply {
put("method", "appStart")
put("params", listOf(packageName))
}
postJsonRpc("appStart", body)
}
suspend fun stopApp(packageName: String) = withContext(Dispatchers.IO) {
val body = JSONObject().apply {
put("method", "appStop")
put("params", listOf(packageName))
}
postJsonRpc("appStop", body)
}
private fun postJsonRpc(method: String, body: JSONObject): Any? {
val request = Request.Builder()
.url("$baseUrl/jsonrpc/0")
.post(body.toString().toRequestBody("application/json".toMediaType()))
.build()
client.newCall(request).execute().use { response ->
val responseBody = response.body?.string()
val json = JSONObject(responseBody ?: "{}")
if (json.has("error")) {
throw RuntimeException(json.getJSONObject("error").getString("message"))
}
return json.opt("result")
}
}
}
```
---
## 五、前台服务与保活
### 5.1 前台服务
```kotlin
// services/AgentService.kt
class AgentService : Service() {
private lateinit var webSocket: WorkPhoneWebSocket
private lateinit var commandExecutor: CommandExecutor
override fun onCreate() {
super.onCreate()
startForeground(NOTIFICATION_ID, createNotification())
initWebSocket()
}
private fun createNotification(): Notification {
val channel = NotificationChannel(
CHANNEL_ID,
"工作手机Agent",
NotificationManager.IMPORTANCE_LOW
)
val nm = getSystemService(NotificationManager::class.java)
nm.createNotificationChannel(channel)
return NotificationCompat.Builder(this, CHANNEL_ID)
.setContentTitle("工作手机Agent运行中")
.setContentText("设备ID: ${getDeviceId()}")
.setSmallIcon(R.drawable.ic_notification)
.build()
}
private fun initWebSocket() {
val serverUrl = Preferences.getServerUrl(this)
val deviceId = getDeviceId()
webSocket = WorkPhoneWebSocket(
serverUrl = serverUrl,
deviceId = deviceId,
onMessage = { commandExecutor.execute(it) },
onConnected = { updateNotification("已连接") },
onDisconnected = { updateNotification("已断开，正在重连...") }
)
commandExecutor = CommandExecutor(this, webSocket)
webSocket.connect()
}
override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
return START_STICKY // 被杀后自动重启
}
override fun onBind(intent: Intent?): IBinder? = null
companion object {
private const val NOTIFICATION_ID = 1
private const val CHANNEL_ID = "agent_channel"
}
}
```
### 5.2 开机自启
```kotlin
// services/BootReceiver.kt
class BootReceiver : BroadcastReceiver() {
override fun onReceive(context: Context, intent: Intent) {
if (intent.action == Intent.ACTION_BOOT_COMPLETED) {
Log.i(TAG, "设备启动，启动Agent服务")
val serviceIntent = Intent(context, AgentService::class.java)
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
context.startForegroundService(serviceIntent)
} else {
context.startService(serviceIntent)
}
}
}
companion object {
private const val TAG = "BootReceiver"
}
}
```
---
## 六、权限配置
```xml
<!-- AndroidManifest.xml -->
<!-- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 前台服务 -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
<!-- 开机自启 -->
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<!-- 存储（截图保存） -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!-- 电源管理（保活） -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
<!-- 开机自启广播 -->
<receiver
android:name=".services.BootReceiver"
android:enabled="true"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
</intent-filter>
</receiver>
```
---
## 七、Frida集成
### 7.1 通用SSL Bypass脚本
```javascript
// frida-scripts/ssl_bypass.js
'use strict';
Java.perform(function() {
console.log('[*] 开始SSL Pinning绕过...');
// 1. TrustManagerImpl
try {
var TrustManagerImpl = Java.use('com.android.org.conscrypt.TrustManagerImpl');
TrustManagerImpl.verifyChain.implementation = function(untrustedChain, trustAnchorChain, host, clientAuth, ocspData, tlsSctData) {
console.log('[+] Bypassing TrustManagerImpl for: ' + host);
return untrustedChain;
};
} catch(e) {}
// 2. OkHttp3 CertificatePinner
try {
var CertificatePinner = Java.use('okhttp3.CertificatePinner');
CertificatePinner.check.overload('java.lang.String', 'java.util.List').implementation = function(hostname, peerCertificates) {
console.log('[+] Bypassing OkHttp3 for: ' + hostname);
};
} catch(e) {}
// 3. WebViewClient
try {
var WebViewClient = Java.use('android.webkit.WebViewClient');
WebViewClient.onReceivedSslError.implementation = function(view, handler, error) {
console.log('[+] Bypassing WebView SSL');
handler.proceed();
};
} catch(e) {}
console.log('[*] SSL Pinning绕过完成');
});
```
---
## 八、调试命令
```bash
# 查看Agent日志
adb logcat -s WorkPhone
# 查看WebSocket连接
adb logcat | grep -i websocket
# 查看uiautomator2服务
adb logcat -s UiAutomator
# 启动Agent服务
adb shell am startservice com.workphone.agent/.services.AgentService
# 停止Agent服务
adb shell am stopservice com.workphone.agent/.services.AgentService
```

549
开发文档/4、前端/管理端前端开发规范（毛玻璃风格）.md Normal file
View File

@@ -0,0 +1,549 @@
# 管理端前端开发规范（苹果毛玻璃风格）
> 更新：2026-02-10 | 本文定义机擎管理端的前端设计规范与开发细节
---
## 一、定位与目标
**机擎管理端**：替代奥创的「007后台+AI数智员工」，提供设备管理、模块管理、消息中心、任务调度、监控面板的统一Web管理界面。
**设计风格**：苹果毛玻璃（Glassmorphism / Frosted Glass），参考 macOS/iOS 的设计语言。
**部署方式**：
- Web管理端：PC浏览器访问（主要）
- H5管理端：手机浏览器/微信内访问（辅助）
---
## 二、技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| React | 18+ | UI框架 |
| Next.js | 14+ (App Router) | 全栈框架 |
| TypeScript | 5.x | 类型安全 |
| Tailwind CSS | 3.4+ | 样式工具 |
| Shadcn UI | latest | 组件库基础 |
| Framer Motion | 11+ | 动画 |
| Zustand | 4+ | 状态管理 |
| Socket.IO Client | 4+ | WebSocket实时通信 |
| Recharts | 2+ | 图表 |
| Lucide React | latest | 图标 |
---
## 三、毛玻璃设计规范
### 3.1 核心视觉参数
```css
/* 毛玻璃效果基础 */
:root {
/* 背景模糊 */
--glass-blur: 20px;
--glass-blur-strong: 40px;
--glass-blur-light: 10px;
/* 背景透明度 */
--glass-bg-light: rgba(255, 255, 255, 0.72);
--glass-bg-dark: rgba(28, 28, 30, 0.72);
--glass-bg-sidebar: rgba(245, 245, 247, 0.85);
/* 边框 */
--glass-border: rgba(255, 255, 255, 0.18);
--glass-border-dark: rgba(255, 255, 255, 0.08);
/* 阴影 */
--glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.08);
--glass-shadow-elevated: 0 16px 48px rgba(0, 0, 0, 0.12);
/* 圆角 */
--radius-sm: 8px;
--radius-md: 12px;
--radius-lg: 16px;
--radius-xl: 20px;
/* 字体（San Francisco风格） */
--font-system: -apple-system, BlinkMacSystemFont, "SF Pro Display",
"SF Pro Text", "Helvetica Neue", Arial, sans-serif;
/* 颜色 */
--accent: #007AFF; /* iOS蓝 */
--accent-hover: #0066D6;
--success: #34C759; /* iOS绿 */
--warning: #FF9500; /* iOS橙 */
--danger: #FF3B30; /* iOS红 */
--text-primary: #1C1C1E;
--text-secondary: #8E8E93;
--text-tertiary: #C7C7CC;
--bg-primary: #F2F2F7;
--bg-secondary: #FFFFFF;
}
```
### 3.2 毛玻璃组件类
```css
/* 毛玻璃卡片 */
.glass-card {
background: var(--glass-bg-light);
backdrop-filter: blur(var(--glass-blur));
-webkit-backdrop-filter: blur(var(--glass-blur));
border: 1px solid var(--glass-border);
border-radius: var(--radius-lg);
box-shadow: var(--glass-shadow);
}
/* 毛玻璃导航栏 */
.glass-navbar {
background: var(--glass-bg-light);
backdrop-filter: blur(var(--glass-blur-strong));
-webkit-backdrop-filter: blur(var(--glass-blur-strong));
border-bottom: 0.5px solid var(--glass-border);
}
/* 毛玻璃侧边栏 */
.glass-sidebar {
background: var(--glass-bg-sidebar);
backdrop-filter: blur(var(--glass-blur-strong));
-webkit-backdrop-filter: blur(var(--glass-blur-strong));
border-right: 0.5px solid var(--glass-border);
}
/* 毛玻璃弹窗 */
.glass-modal {
background: var(--glass-bg-light);
backdrop-filter: blur(var(--glass-blur-strong));
border-radius: var(--radius-xl);
box-shadow: var(--glass-shadow-elevated);
}
```
### 3.3 Tailwind 自定义配置
```typescript
// tailwind.config.ts
export default {
theme: {
extend: {
backdropBlur: {
glass: '20px',
'glass-strong': '40px',
},
backgroundColor: {
glass: 'rgba(255, 255, 255, 0.72)',
'glass-dark': 'rgba(28, 28, 30, 0.72)',
'glass-sidebar': 'rgba(245, 245, 247, 0.85)',
},
borderColor: {
glass: 'rgba(255, 255, 255, 0.18)',
},
boxShadow: {
glass: '0 8px 32px rgba(0, 0, 0, 0.08)',
'glass-elevated': '0 16px 48px rgba(0, 0, 0, 0.12)',
},
borderRadius: {
'apple': '12px',
'apple-lg': '16px',
'apple-xl': '20px',
},
fontFamily: {
sans: ['-apple-system', 'BlinkMacSystemFont', 'SF Pro Display',
'Helvetica Neue', 'Arial', 'sans-serif'],
},
},
},
}
```
---
## 四、页面架构与功能
### 4.1 导航结构
```
管理端
├── 📊 仪表盘（Dashboard）
│ ├── 设备总览（在线/离线/告警）
│ ├── 消息统计（今日/本周/本月）
│ └── 任务执行统计
├── 📱 设备管理（Devices）
│ ├── 设备列表（搜索/筛选/批量操作）
│ ├── 设备详情（实时截图/状态/日志）
│ └── 设备分组
├── 🔌 模块管理（Modules） ← 新增（对标XESlciw Manager）
│ ├── 模块列表（启用/禁用/版本）
│ ├── 模块配置（Scope/参数）
│ ├── 脚本管理（上传/版本/下发）
│ └── 模块监控（运行状态/错误日志）
├── 💬 消息中心（Messages）
│ ├── 实时消息流（Hook上报）
│ ├── 消息历史（搜索/导出）
│ └── 聊天存档
├── 📋 任务调度（Tasks）
│ ├── 任务列表（状态/进度）
│ ├── 新建任务（批量操作）
│ └── 定时任务
├── 🛡️ 风控中心（Risk） ← 新增
│ ├── 敏感词管理
│ ├── 行为监控
│ └── 告警记录
├── 📈 数据统计（Analytics） ← 新增
│ ├── 日报/周报
│ ├── 漏斗分析
│ └── 设备健康
└── ⚙️ 系统设置（Settings）
├── 服务器管理
├── API密钥
└── 用户权限
```
### 4.2 关键页面设计
#### 4.2.1 仪表盘
```
┌─────────────────────────────────────────────────────────────┐
│ ┌─────────┐ │
│ │ 🔵 机擎 │ 仪表盘 用户名 ▼ │
│ └─────────┘ │
├──────────┬──────────────────────────────────────────────────┤
│ │ │
│ 📊 仪表盘│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐│
│ 📱 设备 │ │🟢 在线 │ │🔴 离线 │ │⚠️ 告警 │ │📨 消息 ││
│ 🔌 模块 │ │ 42 │ │ 8 │ │ 3 │ │ 1,234 ││
│ 💬 消息 │ │ 台设备 │ │ 台设备 │ │ 条 │ │ 今日 ││
│ 📋 任务 │ └─────────┘ └─────────┘ └─────────┘ └────────┘│
│ 🛡️ 风控 │ │
│ 📈 统计 │ ┌──────────────────────────────────────────────┐│
│ ⚙️ 设置 │ │ 消息趋势图（7日） ││
│ │ │ 📈 ~~~~~~~~~~~~~~~~~~~~~~~~ ││
│ │ │ ││
│ │ └──────────────────────────────────────────────┘│
│ │ │
│ │ ┌──────────────────┐ ┌──────────────────────────┐│
│ │ │ 最近任务 │ │ 设备状态分布 ││
│ │ │ • 发消息 ✅ │ │ 🟢 在线 84% ││
│ │ │ • 加好友 ⏳ │ │ 🔴 离线 16% ││
│ │ │ • 发朋友圈 ✅ │ │ ││
│ │ └──────────────────┘ └──────────────────────────┘│
│ │ │
└──────────┴──────────────────────────────────────────────────┘
```
#### 4.2.2 模块管理（对标XESlciw Manager）
```
┌──────────────────────────────────────────────────────────────┐
│ 模块管理 ＋ 上传模块 │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 🟢 微信Hook模块 v1.0.3 [启用] ⚙️ │ │
│ │ Scope: com.tencent.mm │ │
│ │ 能力: 发消息 • 收消息 • 联系人 • 朋友圈 • 红包 │ │
│ │ 状态: 42台设备已加载 │ 最近错误: 0 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 🟡 抖音Hook模块 v0.1.0 [禁用] ⚙️ │ │
│ │ Scope: com.ss.android.ugc.aweme │ │
│ │ 能力: 私信收发 • 粉丝列表 │ │
│ │ 状态: 开发中 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ ⚪ 小红书Hook模块 v0.0.1 [禁用] ⚙️ │ │
│ │ Scope: com.xingin.xhs │ │
│ │ 能力: 待开发 │ │
│ │ 状态: 规划中 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
```
---
## 五、React 组件设计
### 5.1 毛玻璃基础组件
```typescript
// components/ui/glass-card.tsx
import { cn } from "@/lib/utils"
import { motion } from "framer-motion"
interface GlassCardProps {
children: React.ReactNode
className?: string
hover?: boolean
}
export function GlassCard({ children, className, hover = true }: GlassCardProps) {
return (
<motion.div
className={cn(
"bg-white/[0.72] backdrop-blur-[20px]",
"border border-white/[0.18]",
"rounded-[16px] shadow-glass",
hover && "hover:shadow-glass-elevated hover:bg-white/[0.82] transition-all duration-300",
className
)}
initial={{ opacity: 0, y: 8 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.3 }}
>
{children}
</motion.div>
)
}
```
```typescript
// components/ui/glass-sidebar.tsx
export function GlassSidebar({ children }: { children: React.ReactNode }) {
return (
<aside className={cn(
"w-[240px] h-screen fixed left-0 top-0",
"bg-[rgba(245,245,247,0.85)] backdrop-blur-[40px]",
"border-r border-white/[0.18]",
"flex flex-col py-4"
)}>
{children}
</aside>
)
}
```
```typescript
// components/ui/glass-navbar.tsx
export function GlassNavbar({ title }: { title: string }) {
return (
<header className={cn(
"h-[52px] sticky top-0 z-50",
"bg-white/[0.72] backdrop-blur-[40px]",
"border-b border-white/[0.18]",
"flex items-center px-6"
)}>
<h1 className="text-[17px] font-semibold text-[#1C1C1E]">{title}</h1>
</header>
)
}
```
### 5.2 设备状态组件
```typescript
// components/device/device-card.tsx
interface DeviceCardProps {
device: {
id: string
name: string
status: 'online' | 'offline' | 'busy' | 'error'
supports_hook: boolean
hook_modules: string[]
battery: number
wechat_status: string
}
}
export function DeviceCard({ device }: DeviceCardProps) {
const statusColors = {
online: 'bg-[#34C759]',
offline: 'bg-[#8E8E93]',
busy: 'bg-[#FF9500]',
error: 'bg-[#FF3B30]',
}
return (
<GlassCard className="p-4">
<div className="flex items-center justify-between">
<div className="flex items-center gap-3">
<div className={cn("w-2.5 h-2.5 rounded-full", statusColors[device.status])} />
<div>
<p className="text-[15px] font-medium text-[#1C1C1E]">{device.name}</p>
<p className="text-[13px] text-[#8E8E93]">{device.id}</p>
</div>
</div>
<div className="flex items-center gap-2">
{device.supports_hook && (
<span className="px-2 py-0.5 rounded-full bg-[#007AFF]/10 text-[#007AFF] text-[11px] font-medium">
Hook
</span>
)}
<span className="text-[13px] text-[#8E8E93]">🔋 {device.battery}%</span>
</div>
</div>
</GlassCard>
)
}
```
### 5.3 实时消息流组件
```typescript
// components/messages/message-stream.tsx
import { useEffect, useState } from 'react'
import { io } from 'socket.io-client'
export function MessageStream() {
const [messages, setMessages] = useState<Message[]>([])
useEffect(() => {
const socket = io(process.env.NEXT_PUBLIC_WS_URL)
socket.on('hook_event', (event) => {
if (event.event_type === 'message_received') {
setMessages(prev => [event.payload, ...prev].slice(0, 100))
}
})
return () => { socket.disconnect() }
}, [])
return (
<div className="space-y-2">
{messages.map((msg, i) => (
<motion.div
key={msg.id || i}
initial={{ opacity: 0, x: -20 }}
animate={{ opacity: 1, x: 0 }}
>
<GlassCard className="p-3" hover={false}>
<div className="flex justify-between">
<span className="text-[13px] font-medium">{msg.from_name}</span>
<span className="text-[11px] text-[#8E8E93]">{msg.time}</span>
</div>
<p className="text-[14px] mt-1">{msg.content}</p>
</GlassCard>
</motion.div>
))}
</div>
)
}
```
---
## 六、交互规范
### 6.1 动画规范
| 场景 | 动画 | 参数 |
|------|------|------|
| 页面切换 | 右滑淡入 | duration: 300ms, ease: [0.25, 0.1, 0.25, 1] |
| 卡片进入 | 上浮淡入 | y: 8→0, opacity: 0→1, duration: 300ms |
| 弹窗打开 | 缩放淡入 | scale: 0.95→1, opacity: 0→1, duration: 250ms |
| 状态变化 | 颜色过渡 | duration: 200ms |
| 列表项 | 交错进入 | stagger: 50ms |
| 骨架屏 | 脉冲闪烁 | 1.5s循环 |
### 6.2 骨架屏（必须实现）
所有数据加载页面必须使用骨架屏：
```typescript
// components/ui/skeleton.tsx
export function DeviceListSkeleton() {
return (
<div className="space-y-3">
{Array.from({ length: 5 }).map((_, i) => (
<GlassCard key={i} className="p-4" hover={false}>
<div className="flex items-center gap-3">
<div className="w-2.5 h-2.5 rounded-full bg-[#C7C7CC] animate-pulse" />
<div className="space-y-2 flex-1">
<div className="h-4 w-32 bg-[#C7C7CC] rounded animate-pulse" />
<div className="h-3 w-24 bg-[#E5E5EA] rounded animate-pulse" />
</div>
</div>
</GlassCard>
))}
</div>
)
}
```
### 6.3 响应式断点
| 断点 | 宽度 | 布局 |
|------|------|------|
| mobile | < 768px | 单栏，底部导航 |
| tablet | 768-1024px | 侧边栏折叠，内容全宽 |
| desktop | 1024-1440px | 侧边栏+内容 |
| wide | > 1440px | 侧边栏+内容+右侧面板 |
---
## 七、项目结构
```
management-ui/
├── app/ # Next.js App Router
│ ├── layout.tsx # 根布局（毛玻璃侧边栏+导航）
│ ├── page.tsx # 仪表盘
│ ├── devices/
│ │ ├── page.tsx # 设备列表
│ │ └── [id]/page.tsx # 设备详情
│ ├── modules/
│ │ ├── page.tsx # 模块列表
│ │ └── [id]/page.tsx # 模块配置
│ ├── messages/
│ │ └── page.tsx # 消息中心
│ ├── tasks/
│ │ └── page.tsx # 任务调度
│ ├── risk/
│ │ └── page.tsx # 风控中心
│ ├── analytics/
│ │ └── page.tsx # 数据统计
│ └── settings/
│ └── page.tsx # 系统设置
├── components/
│ ├── ui/ # 毛玻璃基础组件
│ │ ├── glass-card.tsx
│ │ ├── glass-sidebar.tsx
│ │ ├── glass-navbar.tsx
│ │ ├── glass-modal.tsx
│ │ ├── glass-button.tsx
│ │ └── skeleton.tsx
│ ├── device/ # 设备相关组件
│ ├── module/ # 模块相关组件
│ ├── messages/ # 消息相关组件
│ └── charts/ # 图表组件
├── lib/
│ ├── api.ts # API客户端
│ ├── socket.ts # WebSocket客户端
│ └── utils.ts
├── stores/
│ ├── device-store.ts # 设备状态
│ ├── module-store.ts # 模块状态
│ └── message-store.ts # 消息状态
├── styles/
│ └── globals.css # 全局样式+CSS变量
├── tailwind.config.ts
├── next.config.js
└── package.json
```
---
## 八、开发任务拆解
| 序号 | 任务 | 预估 | 优先级 |
|:----:|------|:----:|:------:|
| F1 | 项目初始化（Next.js+Tailwind+Shadcn） | 2h | P0 |
| F2 | 毛玻璃基础组件库 | 4h | P0 |
| F3 | 布局（侧边栏+导航+骨架屏） | 4h | P0 |
| F4 | 仪表盘页面 | 6h | P0 |
| F5 | 设备列表+详情 | 8h | P0 |
| F6 | 模块管理页面 | 6h | P1 |
| F7 | 消息中心（实时流） | 6h | P1 |
| F8 | 任务调度 | 4h | P1 |
| F9 | 风控中心 | 4h | P2 |
| F10 | 数据统计 | 6h | P2 |
| F11 | 系统设置 | 3h | P2 |
| F12 | WebSocket实时通信集成 | 4h | P0 |
| F13 | API对接+错误处理 | 4h | P0 |
| F14 | 响应式适配+动画 | 4h | P1 |
| | **合计** | **~65h** | |

410
开发文档/5、接口/Hook模块管理接口.md Normal file
View File

@@ -0,0 +1,410 @@
# Hook模块管理接口规范
> 更新：2026-02-10 | 对标奥创XESlciw Manager，定义机擎Hook模块管理的完整API
---
## 一、接口总览
**Base URL**: `http://{server}:8899/api/v3`
**认证方式**: Bearer Token（同现有接口）
### 1.1 新增接口清单
| 分类 | API | 方法 | 说明 |
|------|-----|------|------|
| **模块管理** | /modules | GET | 模块列表 |
| | /modules | POST | 注册/上传模块 |
| | /modules/{module_id} | GET | 模块详情 |
| | /modules/{module_id} | PUT | 更新模块 |
| | /modules/{module_id} | DELETE | 删除模块 |
| | /modules/{module_id}/scope | PUT | 设置Scope |
| | /modules/{module_id}/enable | POST | 启用模块 |
| | /modules/{module_id}/disable | POST | 禁用模块 |
| **设备模块** | /devices/{device_id}/modules | GET | 设备已加载模块 |
| | /devices/{device_id}/modules/reload | POST | 重载设备模块 |
| | /devices/{device_id}/modules/{module_id}/logs | GET | 模块运行日志 |
| **脚本管理** | /scripts | GET | 脚本列表 |
| | /scripts | POST | 上传脚本 |
| | /scripts/{script_id} | GET | 下载脚本 |
| | /scripts/{script_id}/deploy | POST | 部署到设备 |
| **Hook事件** | /hook/events | GET | Hook事件历史 |
| | /hook/events/stream | WebSocket | Hook事件实时流 |
---
## 二、模块管理接口
### 2.1 GET /modules — 模块列表
**请求**：
```
GET /api/v3/modules?enabled=true&scope=com.tencent.mm
```
**响应**：
```json
{
"code": 200,
"data": {
"total": 3,
"modules": [
{
"module_id": "wechat_hook_v1",
"name": "微信Hook模块",
"version": "1.0.3",
"description": "微信消息收发、联系人、朋友圈Hook",
"enabled": true,
"scopes": ["com.tencent.mm"],
"capabilities": [
"send_message", "get_messages", "get_contacts",
"get_friend_list", "post_moment", "get_moments"
],
"min_frida_version": "16.0.0",
"script_url": "/scripts/wechat_hook_v1.js",
"script_hash": "sha256:abc123...",
"device_count": 42,
"error_count": 0,
"created_at": "2026-02-10T10:00:00Z",
"updated_at": "2026-02-10T15:30:00Z"
}
]
}
}
```
### 2.2 POST /modules — 注册模块
**请求**：
```json
{
"module_id": "wechat_hook_v1",
"name": "微信Hook模块",
"version": "1.0.3",
"description": "微信消息收发、联系人、朋友圈Hook",
"scopes": ["com.tencent.mm"],
"capabilities": ["send_message", "get_messages", "get_contacts"],
"min_frida_version": "16.0.0",
"script_content": "// Base64编码的脚本内容...",
"enabled": true
}
```
**响应**：
```json
{
"code": 200,
"data": {
"module_id": "wechat_hook_v1",
"script_url": "/scripts/wechat_hook_v1.js",
"script_hash": "sha256:abc123..."
}
}
```
### 2.3 PUT /modules/{module_id}/scope — 设置Scope
**请求**：
```json
{
"scopes": ["com.tencent.mm", "com.tencent.mm:push"]
}
```
**响应**：
```json
{
"code": 200,
"data": {
"module_id": "wechat_hook_v1",
"scopes": ["com.tencent.mm", "com.tencent.mm:push"]
}
}
```
### 2.4 POST /modules/{module_id}/enable — 启用模块
**请求**：
```
POST /api/v3/modules/wechat_hook_v1/enable
```
**响应**：
```json
{
"code": 200,
"data": {
"module_id": "wechat_hook_v1",
"enabled": true,
"affected_devices": 42
}
}
```
---
## 三、设备模块接口
### 3.1 GET /devices/{device_id}/modules — 设备已加载模块
**请求**：
```
GET /api/v3/devices/device_001/modules
```
**响应**：
```json
{
"code": 200,
"data": {
"device_id": "device_001",
"supports_hook": true,
"frida_version": "16.5.6",
"hook_framework": "frida-server",
"root_status": true,
"modules": [
{
"module_id": "wechat_hook_v1",
"version": "1.0.3",
"status": "loaded",
"loaded_at": "2026-02-10T08:00:00Z",
"target_process": "com.tencent.mm",
"target_pid": 12345,
"rpc_methods": ["send_message", "get_messages", "get_contacts"],
"last_error": null,
"events_today": 156
}
]
}
}
```
### 3.2 POST /devices/{device_id}/modules/reload — 重载设备模块
**请求**：
```json
{
"module_ids": ["wechat_hook_v1"],
"force": false
}
```
**响应**：
```json
{
"code": 200,
"data": {
"reloaded": ["wechat_hook_v1"],
"failed": []
}
}
```
---
## 四、Hook指令扩展（统一API）
### 4.1 通过Hook通道发消息
**请求**：
```json
POST /api/v3/message/send
{
"device_id": "device_001",
"platform": "wechat",
"to_id": "wxid_xxx",
"content": "你好",
"channel": "hook",
"hook_config": {
"script_id": "wechat_hook_v1",
"method": "send_message",
"timeout": 10
}
}
```
**说明**：
- 新增可选字段 `channel` 和 `hook_config`
- 不传 `channel` 时由 ChannelRouter 自动选择
- 指定 `channel: "hook"` 时强制走Hook通道
**响应**：
```json
{
"code": 200,
"data": {
"task_id": "task_abc123",
"channel_used": "hook",
"result": {
"success": true,
"msg_id": "12345678"
}
}
}
```
### 4.2 通过Hook通道获取实时消息
**WebSocket 事件订阅**：
```json
// 客户端发送订阅
{
"type": "subscribe",
"data": {
"event_types": ["message_received", "friend_request"],
"device_ids": ["device_001", "device_002"],
"platforms": ["wechat"]
}
}
```
```json
// 服务端推送事件
{
"type": "hook_event",
"data": {
"event_id": "evt_001",
"event_type": "message_received",
"device_id": "device_001",
"platform": "wechat",
"timestamp": "2026-02-10T15:30:00Z",
"payload": {
"from_id": "wxid_yyy",
"from_name": "张三",
"to_id": "wxid_xxx",
"content": "你好",
"msg_type": "text",
"is_group": false
}
}
}
```
---
## 五、脚本管理接口
### 5.1 POST /scripts — 上传脚本
**请求**（multipart/form-data）：
```
POST /api/v3/scripts
Content-Type: multipart/form-data
file: wechat_hook_v1.js
module_id: wechat_hook_v1
version: 1.0.3
description: 微信Hook脚本 v1.0.3
```
**响应**：
```json
{
"code": 200,
"data": {
"script_id": "wechat_hook_v1_1.0.3",
"url": "/scripts/wechat_hook_v1_1.0.3.js",
"hash": "sha256:abc123...",
"size": 15360
}
}
```
### 5.2 POST /scripts/{script_id}/deploy — 部署脚本到设备
**请求**：
```json
{
"device_ids": ["device_001", "device_002"],
"auto_reload": true
}
```
**响应**：
```json
{
"code": 200,
"data": {
"deployed": ["device_001", "device_002"],
"failed": [],
"reloaded": ["device_001", "device_002"]
}
}
```
---
## 六、错误码扩展
| 错误码 | 说明 |
|--------|------|
| 5001 | 设备不支持Hook（supports_hook=false） |
| 5002 | 模块未找到 |
| 5003 | 模块已禁用 |
| 5004 | Frida连接失败 |
| 5005 | 脚本加载失败 |
| 5006 | RPC调用超时 |
| 5007 | 目标进程未运行 |
| 5008 | Scope不匹配 |
| 5009 | 脚本版本不兼容 |
| 5010 | Hook降级到u2执行 |
---
## 七、与现有接口的兼容性
**原则**：所有新增接口不影响现有接口，现有接口保持不变。
| 现有接口 | 变化 |
|---------|------|
| POST /message/send | 新增可选 `channel`, `hook_config` 字段 |
| GET /messages | 新增 `source` 字段区分Hook/u2 |
| GET /devices/{id} | 响应新增 `supports_hook`, `hook_modules` 字段 |
| WebSocket execute | 新增 `channel: "hook"` 支持 |
| WebSocket response | 新增 `channel_used` 字段 |
---
## 八、PHP SDK 扩展
```php
class WorkPhoneClient {
// 现有方法不变...
// 新增：模块管理
public function getModules($enabled = null) {
$params = $enabled !== null ? ['enabled' => $enabled] : [];
return $this->get('/modules', $params);
}
public function enableModule($moduleId) {
return $this->post("/modules/{$moduleId}/enable");
}
public function disableModule($moduleId) {
return $this->post("/modules/{$moduleId}/disable");
}
public function getDeviceModules($deviceId) {
return $this->get("/devices/{$deviceId}/modules");
}
public function reloadDeviceModules($deviceId, $moduleIds = []) {
return $this->post("/devices/{$deviceId}/modules/reload", [
'module_ids' => $moduleIds
]);
}
// 新增：指定通道发消息
public function sendMessageViaHook($deviceId, $toId, $content) {
return $this->post('/message/send', [
'device_id' => $deviceId,
'platform' => 'wechat',
'to_id' => $toId,
'content' => $content,
'channel' => 'hook'
]);
}
}
```

17
开发文档/5、接口/README.md Normal file
View File

@@ -0,0 +1,17 @@
# 5、接口
**项目**：工作手机SDK v3.0（统一API + Hook模块管理API）
**规则**：本目录除本 README 外最多 **3 个主文档**。
**当前状态**：统一API已完成；Hook模块管理接口已设计。进度以 [开发进度总表](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [接口规范.md](接口规范.md) | 统一API规范（消息/好友/群/标签/朋友圈/设备/脚本）+ PHP SDK |
| [通用服务交互层.md](通用服务交互层.md) | Facade+ChannelRouter+三通道实现 |
| [Hook模块管理接口.md](Hook模块管理接口.md) | **新增**：模块管理+脚本管理+Hook事件+设备模块API |

803
开发文档/5、接口/存客宝对接规范.md Normal file
View File

@@ -0,0 +1,803 @@
# 🔗 存客宝接口对接规范 (CunKeBao API Standard)
> **用途**: 所有项目对接存客宝系统的统一规范
> **版本**: v1.0
> **适用场景**: 线索上报、用户画像、流量池管理
---
## 📋 一、快速对接指南
### 1.1 对接前准备
```yaml
必须获取:
- apiKey: 存客宝分配的接口密钥（每个任务/场景唯一）
接口地址:
- 生产环境: https://ckbapi.quwanzhi.com/v1/api/scenarios
- 测试环境: [按需配置]
请求格式:
- Content-Type: application/json (推荐)
- 备选: application/x-www-form-urlencoded
- 编码: UTF-8
```
### 1.2 一分钟接入
```javascript
// 最简调用示例
const response = await fetch('https://ckbapi.quwanzhi.com/v1/api/scenarios', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
apiKey: 'YOUR_API_KEY',
timestamp: Math.floor(Date.now() / 1000),
phone: '13800000000',
sign: generateSign(params) // 见签名算法
})
});
```
---
## 🔐 二、签名算法（核心）
### 2.1 签名生成流程图
```
┌─────────────────────────────────────────────────────────────────────┐
│ 签名生成流程 │
├─────────────────────────────────────────────────────────────────────┤
│ Step 1: 准备参数 │
│ └── 收集所有请求参数（含 apiKey, timestamp, 业务参数） │
│ │
│ Step 2: 移除特殊字段 │
│ └── 移除: sign, apiKey, portrait │
│ │
│ Step 3: 移除空值 │
│ └── 移除: null, ''（空字符串） │
│ │
│ Step 4: 按键名排序 │
│ └── ASCII 升序排序（a→z） │
│ │
│ Step 5: 拼接参数值 │
│ └── 只取值，顺序拼接，无分隔符 │
│ │
│ Step 6: 第一次 MD5 │
│ └── firstMd5 = MD5(拼接字符串) │
│ │
│ Step 7: 第二次 MD5 │
│ └── sign = MD5(firstMd5 + apiKey) │
└─────────────────────────────────────────────────────────────────────┘
```
### 2.2 签名规则详解
```yaml
# 签名规则
不参与签名的字段:
- sign: 签名本身不参与
- apiKey: 不参与拼接，只在最后一步参与二次MD5
- portrait: 整个画像对象不参与（避免复杂度）
空值处理:
- null 值字段: 不参与签名
- 空字符串 '': 不参与签名
排序规则:
- 按参数名（键名）ASCII 升序
- 例如: name, phone, source, timestamp
拼接规则:
- 只取值，不取键
- 顺序直接拼接，无分隔符
- 例如: "张三13800000000微信广告1710000000"
MD5 规则:
- 使用小写 MD5
- 两次 MD5: 先对拼接字符串，再对结果+apiKey
```
### 2.3 签名代码实现
#### TypeScript/JavaScript 实现
```typescript
/**
* 存客宝签名生成器
* @description 生成符合存客宝接口规范的签名
* @param params 请求参数（不含sign）
* @param apiKey 接口密钥
* @returns 签名字符串（小写MD5）
*/
function generateCKBSign(params: Record<string, any>, apiKey: string): string {
// Step 1: 复制参数，移除特殊字段
const signParams = { ...params };
delete signParams.sign;
delete signParams.apiKey;
delete signParams.portrait;
// Step 2: 移除空值
Object.keys(signParams).forEach(key => {
if (signParams[key] === null || signParams[key] === '') {
delete signParams[key];
}
});
// Step 3: 按键名排序
const sortedKeys = Object.keys(signParams).sort();
// Step 4: 拼接参数值
const stringToSign = sortedKeys.map(key => signParams[key]).join('');
// Step 5: 第一次 MD5
const firstMd5 = md5(stringToSign);
// Step 6: 第二次 MD5（拼接 apiKey）
const sign = md5(firstMd5 + apiKey);
return sign;
}
// 使用示例
const params = {
apiKey: 'YOUR_API_KEY',
timestamp: Math.floor(Date.now() / 1000),
phone: '13800000000',
name: '张三',
source: '微信广告'
};
const sign = generateCKBSign(params, params.apiKey);
params.sign = sign;
```
#### Python 实现
```python
"""
存客宝签名生成器
"""
import hashlib
from typing import Dict, Any
def generate_ckb_sign(params: Dict[str, Any], api_key: str) -> str:
"""
生成存客宝接口签名
Args:
params: 请求参数（不含sign）
api_key: 接口密钥
Returns:
签名字符串（小写MD5）
"""
# Step 1: 复制参数，移除特殊字段
sign_params = {k: v for k, v in params.items()
if k not in ['sign', 'apiKey', 'portrait']}
# Step 2: 移除空值
sign_params = {k: v for k, v in sign_params.items()
if v is not None and v != ''}
# Step 3: 按键名排序
sorted_keys = sorted(sign_params.keys())
# Step 4: 拼接参数值
string_to_sign = ''.join(str(sign_params[k]) for k in sorted_keys)
# Step 5: 第一次 MD5
first_md5 = hashlib.md5(string_to_sign.encode('utf-8')).hexdigest()
# Step 6: 第二次 MD5
sign = hashlib.md5((first_md5 + api_key).encode('utf-8')).hexdigest()
return sign
# 使用示例
import time
params = {
'apiKey': 'YOUR_API_KEY',
'timestamp': int(time.time()),
'phone': '13800000000',
'name': '张三',
'source': '微信广告'
}
sign = generate_ckb_sign(params, params['apiKey'])
params['sign'] = sign
```
#### PHP 实现
```php
<?php
/**
* 存客宝签名生成器
*
* @param array $params 请求参数（不含sign）
* @param string $apiKey 接口密钥
* @return string 签名字符串（小写MD5）
*/
function generateCKBSign(array $params, string $apiKey): string {
// Step 1: 移除特殊字段
unset($params['sign'], $params['apiKey'], $params['portrait']);
// Step 2: 移除空值
$params = array_filter($params, function($value) {
return !is_null($value) && $value !== '';
});
// Step 3: 按键名排序
ksort($params);
// Step 4: 拼接参数值
$stringToSign = implode('', array_values($params));
// Step 5: 第一次 MD5
$firstMd5 = md5($stringToSign);
// Step 6: 第二次 MD5
$sign = md5($firstMd5 . $apiKey);
return $sign;
}
// 使用示例
$params = [
'apiKey' => 'YOUR_API_KEY',
'timestamp' => time(),
'phone' => '13800000000',
'name' => '张三',
'source' => '微信广告'
];
$sign = generateCKBSign($params, $params['apiKey']);
$params['sign'] = $sign;
```
---
## 📤 三、请求参数规范
### 3.1 鉴权字段（必填）
| 字段名 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| `apiKey` | string | ✅ | 存客宝分配的接口密钥 |
| `sign` | string | ✅ | 签名值（见签名算法） |
| `timestamp` | int | ✅ | 秒级时间戳，与服务器时间差 ≤ 5分钟 |
### 3.2 主标识字段（至少传一个）
| 字段名 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| `wechatId` | string | 二选一 | 微信号，优先作为主标识 |
| `phone` | string | 二选一 | 手机号，wechatId 为空时用作主标识 |
### 3.3 基础信息字段（可选）
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|:---|:---|:---:|:---|:---|
| `name` | string | ❌ | 客户姓名 | "张三" |
| `source` | string | ❌ | 线索来源 | "抖音直播间" |
| `remark` | string | ❌ | 备注信息 | "通过H5落地页留资" |
| `tags` | string | ❌ | 微信标签（逗号分隔） | "高意向,电商,女装" |
| `siteTags` | string | ❌ | 站内标签（逗号分隔） | "新客,VIP" |
### 3.4 用户画像字段（可选）
```typescript
interface Portrait {
/**
* 画像类型
* 0-浏览 1-点击 2-下单/购买 3-注册 4-互动
*/
type?: 0 | 1 | 2 | 3 | 4;
/**
* 画像来源
* 0-本站 1-老油条 2-老坑爹
*/
source?: 0 | 1 | 2;
/**
* 画像明细数据（任意键值对）
*/
sourceData?: {
age?: number;
gender?: string;
city?: string;
productId?: string;
pageUrl?: string;
[key: string]: any;
};
/**
* 画像备注，最大100字符
*/
remark?: string;
/**
* 去重唯一ID
* 相同 uniqueId 在半小时内会合并统计
* 建议格式: {来源}_{用户标识}_{时间戳}_{序号}
*/
uniqueId?: string;
}
```
#### 画像类型说明
| 值 | 类型 | 说明 | 适用场景 |
|:---:|:---|:---|:---|
| 0 | 浏览 | 用户浏览了页面或内容 | 页面访问、商品浏览 |
| 1 | 点击 | 用户点击了某个元素 | 按钮点击、广告点击 |
| 2 | 下单/购买 | 用户完成了购买行为 | 订单提交、支付完成 |
| 3 | 注册 | 用户完成了注册 | 账号注册、会员注册 |
| 4 | 互动 | 用户进行了互动行为 | 点赞、评论、分享 |
---
## 📥 四、响应格式规范
### 4.1 统一响应结构
```typescript
interface CKBResponse<T = any> {
code: number; // 200=成功，其他=失败
message: string; // 提示信息
data: T | null; // 业务数据
}
```
### 4.2 成功响应
```json
// 新增成功
{ "code": 200, "message": "新增成功", "data": "13800000000" }
// 已存在
{ "code": 200, "message": "已存在", "data": "13800000000" }
```
### 4.3 错误响应
| code | message | 说明 | 处理建议 |
|:---:|:---|:---|:---|
| 400 | apiKey不能为空 | 缺少 apiKey | 检查参数 |
| 400 | sign不能为空 | 缺少签名 | 检查签名生成 |
| 400 | timestamp不能为空 | 缺少时间戳 | 添加时间戳 |
| 400 | 请求已过期 | 时间戳超过5分钟 | 同步服务器时间 |
| 401 | 无效的apiKey | apiKey 错误 | 检查 apiKey |
| 401 | 签名验证失败 | 签名错误 | 检查签名算法 |
| 500 | 系统错误 | 服务端异常 | 联系技术支持 |
---
## 📝 五、完整请求示例
### 5.1 基础线索上报
```json
{
"apiKey": "YOUR_API_KEY",
"timestamp": 1710000000,
"phone": "13800000000",
"name": "张三",
"source": "微信广告",
"remark": "通过H5落地页留资",
"tags": "高意向,电商",
"sign": "a1b2c3d4e5f6..."
}
```
### 5.2 带微信号的线索上报
```json
{
"apiKey": "YOUR_API_KEY",
"timestamp": 1710000000,
"wechatId": "wxid_abcdefg123",
"phone": "13800000001",
"name": "李四",
"source": "小程序落地页",
"tags": "中意向,直播",
"sign": "a1b2c3d4e5f6..."
}
```
### 5.3 带用户画像的线索上报
```json
{
"apiKey": "YOUR_API_KEY",
"timestamp": 1710000000,
"phone": "13800000002",
"name": "王五",
"source": "百度推广",
"portrait": {
"type": 1,
"source": 0,
"sourceData": {
"age": 28,
"gender": "female",
"city": "上海",
"productId": "P12345",
"pageUrl": "https://example.com/product/123"
},
"remark": "点击了立即咨询按钮",
"uniqueId": "site_13800000002_1710000000_001"
},
"sign": "a1b2c3d4e5f6..."
}
```
---
## 🛠️ 六、封装工具类
### 6.1 TypeScript 完整封装
```typescript
/**
* 存客宝 API 客户端
* @description 封装存客宝接口调用，自动处理签名
*/
import crypto from 'crypto';
interface CKBConfig {
apiKey: string;
baseUrl?: string;
}
interface LeadData {
phone?: string;
wechatId?: string;
name?: string;
source?: string;
remark?: string;
tags?: string;
siteTags?: string;
portrait?: {
type?: 0 | 1 | 2 | 3 | 4;
source?: 0 | 1 | 2;
sourceData?: Record<string, any>;
remark?: string;
uniqueId?: string;
};
}
interface CKBResponse<T = any> {
code: number;
message: string;
data: T;
}
export class CunKeBaoClient {
private apiKey: string;
private baseUrl: string;
constructor(config: CKBConfig) {
this.apiKey = config.apiKey;
this.baseUrl = config.baseUrl || 'https://ckbapi.quwanzhi.com';
}
/**
* 生成 MD5
*/
private md5(str: string): string {
return crypto.createHash('md5').update(str, 'utf8').digest('hex');
}
/**
* 生成签名
*/
private generateSign(params: Record<string, any>): string {
// 复制参数，移除特殊字段
const signParams = { ...params };
delete signParams.sign;
delete signParams.apiKey;
delete signParams.portrait;
// 移除空值
Object.keys(signParams).forEach(key => {
if (signParams[key] === null || signParams[key] === '') {
delete signParams[key];
}
});
// 按键名排序
const sortedKeys = Object.keys(signParams).sort();
// 拼接参数值
const stringToSign = sortedKeys.map(key => signParams[key]).join('');
// 两次 MD5
const firstMd5 = this.md5(stringToSign);
return this.md5(firstMd5 + this.apiKey);
}
/**
* 上报线索
* @param data 线索数据
*/
async reportLead(data: LeadData): Promise<CKBResponse<string>> {
const timestamp = Math.floor(Date.now() / 1000);
const params: Record<string, any> = {
apiKey: this.apiKey,
timestamp,
...data,
};
// 生成签名
params.sign = this.generateSign(params);
// 发送请求
const response = await fetch(`${this.baseUrl}/v1/api/scenarios`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(params),
});
return response.json();
}
/**
* 上报用户画像
* @param identifier 用户标识（phone 或 wechatId）
* @param portrait 画像数据
*/
async reportPortrait(
identifier: { phone?: string; wechatId?: string },
portrait: LeadData['portrait']
): Promise<CKBResponse<string>> {
return this.reportLead({
...identifier,
portrait,
});
}
}
// ============ 使用示例 ============
// 初始化客户端
const ckb = new CunKeBaoClient({
apiKey: 'YOUR_API_KEY',
});
// 上报线索
await ckb.reportLead({
phone: '13800000000',
name: '张三',
source: '微信广告',
tags: '高意向,电商',
});
// 上报带画像的线索
await ckb.reportLead({
phone: '13800000001',
name: '李四',
source: '抖音直播',
portrait: {
type: 1, // 点击
sourceData: {
productId: 'P12345',
pageUrl: 'https://example.com/product',
},
uniqueId: 'site_13800000001_' + Date.now(),
},
});
```
### 6.2 Python 完整封装
```python
"""
存客宝 API 客户端
封装存客宝接口调用，自动处理签名
"""
import hashlib
import time
import requests
from typing import Optional, Dict, Any
from dataclasses import dataclass, asdict
@dataclass
class Portrait:
"""用户画像"""
type: int = 0 # 0-浏览 1-点击 2-下单 3-注册 4-互动
source: int = 0 # 0-本站 1-老油条 2-老坑爹
sourceData: Optional[Dict[str, Any]] = None
remark: Optional[str] = None
uniqueId: Optional[str] = None
class CunKeBaoClient:
"""存客宝 API 客户端"""
def __init__(self, api_key: str, base_url: str = "https://ckbapi.quwanzhi.com"):
self.api_key = api_key
self.base_url = base_url
def _md5(self, s: str) -> str:
"""生成 MD5"""
return hashlib.md5(s.encode('utf-8')).hexdigest()
def _generate_sign(self, params: Dict[str, Any]) -> str:
"""生成签名"""
# 复制参数，移除特殊字段
sign_params = {k: v for k, v in params.items()
if k not in ['sign', 'apiKey', 'portrait']}
# 移除空值
sign_params = {k: v for k, v in sign_params.items()
if v is not None and v != ''}
# 按键名排序
sorted_keys = sorted(sign_params.keys())
# 拼接参数值
string_to_sign = ''.join(str(sign_params[k]) for k in sorted_keys)
# 两次 MD5
first_md5 = self._md5(string_to_sign)
return self._md5(first_md5 + self.api_key)
def report_lead(
self,
phone: Optional[str] = None,
wechat_id: Optional[str] = None,
name: Optional[str] = None,
source: Optional[str] = None,
remark: Optional[str] = None,
tags: Optional[str] = None,
site_tags: Optional[str] = None,
portrait: Optional[Portrait] = None
) -> Dict[str, Any]:
"""
上报线索
Args:
phone: 手机号
wechat_id: 微信号
name: 客户姓名
source: 线索来源
remark: 备注
tags: 微信标签（逗号分隔）
site_tags: 站内标签（逗号分隔）
portrait: 用户画像
Returns:
API 响应
"""
params = {
'apiKey': self.api_key,
'timestamp': int(time.time()),
}
# 添加可选参数
if phone:
params['phone'] = phone
if wechat_id:
params['wechatId'] = wechat_id
if name:
params['name'] = name
if source:
params['source'] = source
if remark:
params['remark'] = remark
if tags:
params['tags'] = tags
if site_tags:
params['siteTags'] = site_tags
if portrait:
params['portrait'] = asdict(portrait)
# 生成签名
params['sign'] = self._generate_sign(params)
# 发送请求
response = requests.post(
f"{self.base_url}/v1/api/scenarios",
json=params,
headers={'Content-Type': 'application/json'}
)
return response.json()
# ============ 使用示例 ============
# 初始化客户端
ckb = CunKeBaoClient(api_key='YOUR_API_KEY')
# 上报线索
result = ckb.report_lead(
phone='13800000000',
name='张三',
source='微信广告',
tags='高意向,电商'
)
# 上报带画像的线索
result = ckb.report_lead(
phone='13800000001',
name='李四',
source='抖音直播',
portrait=Portrait(
type=1, # 点击
sourceData={
'productId': 'P12345',
'pageUrl': 'https://example.com/product'
},
uniqueId=f'site_13800000001_{int(time.time())}'
)
)
```
---
## ❓ 七、常见问题 (FAQ)
### Q1: 签名验证失败怎么排查？
**A**: 按以下步骤排查：
1. 确认 apiKey 正确
2. 确认 timestamp 在 5 分钟内
3. 确认移除了 sign、apiKey、portrait 字段
4. 确认移除了空值字段
5. 确认按键名排序
6. 确认 MD5 是小写
### Q2: portrait 字段是否必传？
**A**: 不是必传。只有需要记录用户画像时才传递。
### Q3: uniqueId 的作用是什么？
**A**: 防止重复记录。相同 uniqueId 的画像数据在半小时内会合并统计。
### Q4: phone 和 wechatId 必须传哪个？
**A**: 至少传一个。wechatId 优先作为主标识。
### Q5: 时间戳超时怎么处理？
**A**: 确保服务器时间准确，或使用 NTP 同步时间。
---
## 🔗 八、与开发模板联动
### 8.1 在项目中使用
```
1. 复制本文件中的工具类到项目 lib/ckb.ts
2. 配置 apiKey 到环境变量
3. 在需要的地方调用 ckb.reportLead()
```
### 8.2 联动指令
```
# 生成存客宝对接代码
@联动 存客宝→后端：生成线索上报 Service
# 生成前端表单
@联动 存客宝→前端：生成留资表单组件
```
---
## 📞 九、技术支持
- **接口问题**: 联系存客宝技术支持
- **apiKey 申请**: 联系卡若（微信 28533368）
---
> **更新日志**:
> - v1.0 (2026-01-18): 初始版本，支持线索上报和用户画像

692
开发文档/5、接口/接口规范.md Normal file
View File

@@ -0,0 +1,692 @@
# 工作手机SDK v3.0 - 接口规范（统一API）
> 版本：v3.0 | 更新：2026-02-07 | 合并自《统一API规范》+ 接口定义要点
> 存客宝前端/后端直接调用此 API 即可控制手机。
---
## 一、概述
### 1.1 基础信息
| 项目 | 值 |
|------|-----|
| Base URL | `https://workphone.xxx.com/api/v3` |
| 认证方式 | Bearer Token |
| 内容类型 | application/json |
| 字符编码 | UTF-8 |
### 1.2 认证
```http
Authorization: Bearer {api_key}
```
### 1.3 通用响应格式
```json
{
"code": 200,
"message": "success",
"data": {},
"channel_used": "sdk_control", // 实际使用的通道
"timestamp": 1704931200
}
```
### 1.4 错误码
| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 成功 | - |
| 400 | 请求参数错误 | 检查参数 |
| 401 | 未授权 | 检查API Key |
| 404 | 资源不存在 | 检查设备ID |
| 408 | 设备响应超时 | 增加timeout |
| 500 | 服务器内部错误 | 联系技术支持 |
| 503 | 设备不在线 | 检查设备状态 |
### 1.5 服务端与设备端联调契约（抖/红/闲鱼/微信）
- **下发**：服务端通过 WebSocket 发 `{type: "execute", data: { script, action, params }}`，script 为 wechat/douyin/xhs/xianyu。
- **设备端返回**：设备回复 `{type: "response", command_id, code, message, data }`，其中 `data` 为 Skill 返回值。
- **send_message**：Skill 返回需含 `success`、失败时含 `error`、成功时可选 `message_id`；服务端据此解析为 200 + data.success/data.error。
- **get_messages**：Skill 返回需含 `messages`（数组）；服务端取 `result.data.messages` 或 `result.messages` 兼容 ADB。
- **batch_send_message**：params 含 to_ids、content、interval 等；服务端逐条下发，返回 `data.sent`（成功列表）、`data.failed`（失败列表）、`data.total`（总条数）；设备不在线时 HTTP 503。
---
## 二、核心接口（存客宝重点对接）
### 2.1 发送消息（统一接口）
这是最重要的接口，支持所有平台。
```http
POST /api/v3/message/send
```
**请求体**：
```json
{
"device_id": "device-001",
"platform": "wechat", // wechat/douyin/xhs/xianyu
"to_id": "wxid_xxx", // 接收者ID
"content": "你好", // 消息内容
"msg_type": "text", // text/image/video
"media_url": null // 媒体URL（图片/视频时必填）
}
```
**响应**（与实现一致）：
- HTTP 始终 200（业务成功与否看 `data.success`）；设备不在线时可能走 AI Agent 通道仍返回 200。
- `data` 必含：`success`（bool）、`message_id`（成功时有值）、`error`（失败时描述）。
- 失败时可选 `data.error_code`：`contact_not_found`（未找到联系人）、`timeout`（设备响应超时）。
- 可选 `data.timeout_seconds`：本次使用的超时（秒），来自请求 `timeout_seconds` 或配置 `MESSAGE_SEND_TIMEOUT`。
```json
{
"code": 200,
"data": {
"success": true,
"message_id": "msg_xxx",
"error": null
},
"channel_used": "sdk_control"
}
```
失败示例：`{"code":200,"data":{"success":false,"message_id":null,"error":"timeout","error_code":"timeout"},"channel_used":"sdk_control"}`
**平台支持**：
| platform | 说明 | 通道选择 |
|----------|------|----------|
| `wechat` | 微信 | SDK控制 → AI Agent |
| `douyin` | 抖音 | 官方API → SDK控制 |
| `xhs` | 小红书 | SDK控制 → AI Agent |
| `xianyu` | 闲鱼 | WebSocket协议 → SDK控制 |
### 2.2 获取消息列表
```http
POST /api/v3/message/list
```
**请求体**：
```json
{
"device_id": "device-001",
"platform": "wechat",
"conversation_id": "wxid_xxx", // 可选，不传则获取全部
"limit": 20,
"since_time": null // 可选，时间戳
}
```
**响应**：
```json
{
"code": 200,
"data": {
"messages": [
{
"message_id": "msg_001",
"from_id": "wxid_xxx",
"to_id": "my_wxid",
"content": "你好",
"msg_type": "text",
"timestamp": 1704931200,
"is_self": false
}
]
},
"channel_used": "sdk_control"
}
```
### 2.3 添加好友
```http
POST /api/v3/friend/add
```
**请求体**：
```json
{
"device_id": "device-001",
"platform": "wechat",
"user_id": "wxid_xxx",
"message": "你好，我是xxx" // 验证消息
}
```
### 2.4 通过好友请求
```http
POST /api/v3/friend/accept
```
**请求体**：
```json
{
"device_id": "device-001",
"platform": "wechat",
"user_id": "wxid_xxx"
}
```
### 2.5 获取联系人列表
```http
GET /api/v3/contacts?device_id=xxx&platform=wechat&limit=100
```
### 2.6 执行自然语言任务（AI Agent模式）
当需要执行复杂任务时，可以直接用自然语言描述：
```http
POST /api/v3/agent/execute
```
**请求体**：
```json
{
"device_id": "device-001",
"task": "打开微信，找到张三，发送消息：明天下午2点开会",
"llm_provider": "deepseek", // deepseek/openai/ollama
"max_steps": 30
}
```
**响应**：
```json
{
"code": 200,
"data": {
"success": true,
"steps": [
"启动微信",
"点击搜索",
"输入张三",
"点击联系人",
"输入消息",
"点击发送"
],
"duration_ms": 12500
}
}
```
---
## 三、设备管理接口
### 3.1 获取设备列表
```http
GET /api/v3/devices
```
**响应**：
```json
{
"code": 200,
"data": [
{
"device_id": "device-001",
"name": "工作手机1",
"model": "Redmi K60",
"status": "online",
"android_version": "14",
"agent_version": "1.0.0",
"capabilities": ["frida", "u2", "scrcpy"],
"apps": ["wechat", "douyin", "xhs"],
"last_heartbeat": "2026-01-26T10:00:00Z"
}
]
}
```
### 3.2 设备截图
```http
POST /api/v3/devices/{device_id}/screenshot
```
**响应**：
```json
{
"code": 200,
"data": {
"image_url": "https://xxx/screenshots/device-001-1704931200.jpg",
"width": 1080,
"height": 2400
}
}
```
### 3.3 获取UI树
```http
GET /api/v3/devices/{device_id}/ui-tree
```
---
## 四、底层控制接口
### 4.1 点击坐标
```http
POST /api/v3/devices/{device_id}/click
```
```json
{ "x": 500, "y": 1000 }
```
### 4.2 点击文字
```http
POST /api/v3/devices/{device_id}/click-text
```
```json
{ "text": "发送", "timeout": 10 }
```
### 4.3 输入文字
```http
POST /api/v3/devices/{device_id}/input
```
```json
{ "text": "Hello World", "clear": true }
```
### 4.4 滑动
```http
POST /api/v3/devices/{device_id}/swipe
```
```json
{ "direction": "up", "scale": 0.8 }
```
---
## 五、脚本执行接口
### 5.1 执行脚本
```http
POST /api/v3/devices/{device_id}/execute
```
**请求体**：
```json
{
"script": "wechat",
"action": "send_message",
"params": {
"to_wxid": "wxid_xxx",
"content": "你好！"
},
"timeout": 30
}
```
### 5.2 支持的脚本和动作
| 脚本 | 动作 | 参数 |
|------|------|------|
| wechat | send_message | to_wxid, content, msg_type |
| wechat | get_messages | limit |
| wechat | get_friends | - |
| wechat | add_friend | wxid, message |
| wechat | accept_friend | wxid |
| douyin | send_message | to_uid, content |
| douyin | get_messages | limit |
| douyin | reply_comment | video_id, comment_id, content |
| xhs | send_message | to_uid, content |
| xhs | like_note | note_id |
| xhs | comment_note | note_id, content |
---
## 六、存客宝PHP SDK
### 6.1 安装
```php
// 将以下文件复制到 extend/Cunkebao/WorkPhone/ 目录
```
### 6.2 完整代码
```php
<?php
// extend/Cunkebao/WorkPhone/WorkPhoneClient.php
namespace Cunkebao\WorkPhone;
class WorkPhoneClient
{
private string $baseUrl;
private string $apiKey;
public function __construct(string $baseUrl, string $apiKey)
{
$this->baseUrl = rtrim($baseUrl, '/');
$this->apiKey = $apiKey;
}
/**
* 发送消息（统一接口，推荐使用）
*
* @param string $deviceId 设备ID
* @param string $platform 平台：wechat/douyin/xhs/xianyu
* @param string $toId 接收者ID
* @param string $content 消息内容
* @param string $msgType 消息类型：text/image/video
* @return array
*/
public function sendMessage(
string $deviceId,
string $platform,
string $toId,
string $content,
string $msgType = 'text'
): array {
return $this->post('/api/v3/message/send', [
'device_id' => $deviceId,
'platform' => $platform,
'to_id' => $toId,
'content' => $content,
'msg_type' => $msgType,
]);
}
/**
* 获取消息列表
*/
public function getMessages(
string $deviceId,
string $platform,
int $limit = 20,
?string $conversationId = null
): array {
return $this->post('/api/v3/message/list', [
'device_id' => $deviceId,
'platform' => $platform,
'limit' => $limit,
'conversation_id' => $conversationId,
]);
}
/**
* 添加好友
*/
public function addFriend(
string $deviceId,
string $platform,
string $userId,
string $message = ''
): array {
return $this->post('/api/v3/friend/add', [
'device_id' => $deviceId,
'platform' => $platform,
'user_id' => $userId,
'message' => $message,
]);
}
/**
* 通过好友请求
*/
public function acceptFriend(
string $deviceId,
string $platform,
string $userId
): array {
return $this->post('/api/v3/friend/accept', [
'device_id' => $deviceId,
'platform' => $platform,
'user_id' => $userId,
]);
}
/**
* 获取联系人列表
*/
public function getContacts(
string $deviceId,
string $platform,
int $limit = 100
): array {
return $this->get('/api/v3/contacts', [
'device_id' => $deviceId,
'platform' => $platform,
'limit' => $limit,
]);
}
/**
* 执行自然语言任务（AI Agent模式）
*/
public function executeTask(string $deviceId, string $task): array
{
return $this->post('/api/v3/agent/execute', [
'device_id' => $deviceId,
'task' => $task,
'llm_provider' => 'deepseek',
]);
}
/**
* 获取设备列表
*/
public function getDevices(): array
{
return $this->get('/api/v3/devices');
}
/**
* 获取设备详情
*/
public function getDevice(string $deviceId): array
{
return $this->get("/api/v3/devices/{$deviceId}");
}
/**
* 截图
*/
public function screenshot(string $deviceId): array
{
return $this->post("/api/v3/devices/{$deviceId}/screenshot");
}
/**
* 执行脚本（底层接口）
*/
public function execute(
string $deviceId,
string $script,
string $action,
array $params = [],
int $timeout = 30
): array {
return $this->post("/api/v3/devices/{$deviceId}/execute", [
'script' => $script,
'action' => $action,
'params' => $params,
'timeout' => $timeout,
]);
}
// ========== 快捷方法 ==========
/**
* 发送微信消息
*/
public function wechatSend(string $deviceId, string $wxid, string $content): array
{
return $this->sendMessage($deviceId, 'wechat', $wxid, $content);
}
/**
* 发送抖音私信
*/
public function douyinSend(string $deviceId, string $uid, string $content): array
{
return $this->sendMessage($deviceId, 'douyin', $uid, $content);
}
/**
* 发送小红书私信
*/
public function xhsSend(string $deviceId, string $uid, string $content): array
{
return $this->sendMessage($deviceId, 'xhs', $uid, $content);
}
// ========== HTTP方法 ==========
private function get(string $path, array $params = []): array
{
$url = $this->baseUrl . $path;
if ($params) {
$url .= '?' . http_build_query($params);
}
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $this->apiKey,
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true) ?: ['code' => 500, 'message' => 'Invalid response'];
}
private function post(string $path, array $data = []): array
{
$ch = curl_init($this->baseUrl . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $this->apiKey,
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true) ?: ['code' => 500, 'message' => 'Invalid response'];
}
}
```
### 6.3 使用示例
```php
<?php
use Cunkebao\WorkPhone\WorkPhoneClient;
// 初始化
$sdk = new WorkPhoneClient(
config('workphone.server_url'), // https://sdk.xxx.com
config('workphone.api_key') // your-api-key
);
// 发送微信消息（自动选择最优通道）
$result = $sdk->sendMessage('device-001', 'wechat', 'wxid_xxx', '你好');
// 发送抖音私信（优先走官方API）
$result = $sdk->sendMessage('device-001', 'douyin', 'user_xxx', '感谢关注');
// 执行复杂任务（AI Agent模式）
$result = $sdk->executeTask('device-001', '打开淘宝搜索iPhone16并加入购物车');
// 快捷方法
$result = $sdk->wechatSend('device-001', 'wxid_xxx', '你好');
$result = $sdk->douyinSend('device-001', 'uid_xxx', '感谢关注');
```
---
## 七、通道选择策略
SDK自动选择最优通道：
```
1. 有官方API支持 → 优先用API（最稳定）
2. 设备在线 → 用SDK控制（成本低）
3. SDK失败 → 用AI Agent（最灵活）
4. 全部失败 → 返回错误
```
**响应中会返回实际使用的通道**：
```json
{
"code": 200,
"data": {...},
"channel_used": "official_api" // official_api / sdk_control / ai_agent
}
```
---
## 八、与存客宝现有代码对接
### 8.1 替换原有WebSocket调用
```php
// ========== 原代码 (调用奥创) ==========
$signInData = [
"cmdType" => "CmdSendMsg",
"wechatAccountId" => $wechatId,
"toWxid" => $toWxid,
"content" => $content,
];
$this->client->send(json_encode($signInData));
// ========== 新代码 (调用自有SDK) ==========
$sdk = new WorkPhoneClient('https://sdk.xxx.com', 'api-key');
$result = $sdk->sendMessage($deviceId, 'wechat', $toWxid, $content);
```
### 8.2 配置文件
```php
// config/workphone.php
return [
'server_url' => env('WORKPHONE_URL', 'https://sdk.xxx.com'),
'api_key' => env('WORKPHONE_KEY', ''),
];
```

851
开发文档/5、接口/通用服务交互层.md Normal file
View File

@@ -0,0 +1,851 @@
# 工作手机SDK v3.0 - 通用服务交互层设计
> 创建日期：2026-01-26 | 架构师：卡若
>
> 设计原则：屏蔽底层差异，提供统一调用接口
---
## 一、设计背景
### 1.1 问题分析
当前存在多种控制手机的方式：
| 方式 | 接口类型 | 优势 | 劣势 |
|------|---------|------|------|
| **奥创平台** | HTTP REST API | 成熟稳定 | 成本高、受限于平台 |
| **抖音客服通信** | Webhook + OpenAPI | 官方接口、稳定 | 只支持抖音、需认证 |
| **uiautomator2** | Python库 | 通用、免费 | 需要脚本开发 |
| **AI Agent** | 自然语言 | 灵活、智能 | 有成本、可能不稳定 |
### 1.2 设计目标
```
┌──────────────────────────────────────────────────────────────────┐
│ 统一接口层 │
│ │
│ 存客宝调用： │
│ send_message("wechat", "wxid_xxx", "你好") │
│ │
│ 自动路由到最优通道： │
│ • 有官方API → 调官方API（最稳定） │
│ • 无官方API → 调SDK控制（uiautomator2） │
│ • SDK失败 → 调AI Agent（自适应） │
│ │
└──────────────────────────────────────────────────────────────────┘
```
---
## 二、架构设计
### 2.1 分层架构
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 存客宝/上层应用 │
└───────────────────────────────────┬─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 统一服务交互层 (Facade) │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ UnifiedDeviceService │ │
│ │ • send_message(platform, to, content) │ │
│ │ • get_messages(platform, params) │ │
│ │ • add_friend(platform, id, message) │ │
│ │ • ... │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────┬─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 通道路由层 (Router) │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 根据平台、操作类型、设备状态，自动选择最优通道 │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└───────────┬─────────────────────┬─────────────────────┬─────────────────────┘
│ │ │
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ 官方API通道 │ │ SDK控制通道 │ │ AI Agent通道 │
│ │ │ │ │ │
│ • 抖音OpenAPI │ │ • uiautomator2 │ │ • DroidRun │
│ • 微信开放平台 │ │ • Frida │ │ • 自然语言 │
│ • 小红书API │ │ • 脚本引擎 │ │ • LLM驱动 │
│ │ │ │ │ │
│ 优先级: 1 (最高) │ │ 优先级: 2 │ │ 优先级: 3 │
│ 成本: 免费/低 │ │ 成本: 免费 │ │ 成本: ¥0.02/次 │
│ 稳定性: 最高 │ │ 稳定性: 高 │ │ 稳定性: 中 │
└───────────────────┘ └───────────────────┘ └───────────────────┘
│ │ │
└─────────────────────┴─────────────────────┘
│
▼
┌───────────────────┐
│ Android设备 │
└───────────────────┘
```
### 2.2 核心接口定义
```python
# services/unified_service.py
from abc import ABC, abstractmethod
from typing import Dict, Any, List, Optional
from enum import Enum
from pydantic import BaseModel
class Platform(Enum):
"""支持的平台"""
WECHAT = "wechat"
DOUYIN = "douyin"
XHS = "xhs"
WEIBO = "weibo"
class Channel(Enum):
"""执行通道"""
OFFICIAL_API = "official_api" # 官方API
SDK_CONTROL = "sdk_control" # SDK控制
AI_AGENT = "ai_agent" # AI Agent
class MessageType(Enum):
"""消息类型"""
TEXT = "text"
IMAGE = "image"
VIDEO = "video"
VOICE = "voice"
# ============ 请求/响应模型 ============
class SendMessageRequest(BaseModel):
"""发送消息请求"""
device_id: str
platform: Platform
to_id: str # 接收者ID
content: str # 消息内容
msg_type: MessageType = MessageType.TEXT
media_url: Optional[str] = None # 媒体URL
class SendMessageResponse(BaseModel):
"""发送消息响应"""
success: bool
message_id: Optional[str]
channel_used: Channel # 实际使用的通道
error: Optional[str]
class GetMessagesRequest(BaseModel):
"""获取消息请求"""
device_id: str
platform: Platform
conversation_id: Optional[str]
limit: int = 20
since_time: Optional[int] # 时间戳
class Message(BaseModel):
"""消息实体"""
message_id: str
from_id: str
to_id: str
content: str
msg_type: MessageType
timestamp: int
is_self: bool
class GetMessagesResponse(BaseModel):
"""获取消息响应"""
success: bool
messages: List[Message]
channel_used: Channel
error: Optional[str]
# ============ 统一服务接口 ============
class IUnifiedDeviceService(ABC):
"""统一设备服务接口"""
@abstractmethod
async def send_message(self, req: SendMessageRequest) -> SendMessageResponse:
"""发送消息"""
pass
@abstractmethod
async def get_messages(self, req: GetMessagesRequest) -> GetMessagesResponse:
"""获取消息"""
pass
@abstractmethod
async def add_friend(self, device_id: str, platform: Platform,
user_id: str, message: str = "") -> dict:
"""添加好友"""
pass
@abstractmethod
async def accept_friend(self, device_id: str, platform: Platform,
user_id: str) -> dict:
"""通过好友请求"""
pass
@abstractmethod
async def get_contacts(self, device_id: str, platform: Platform,
limit: int = 100) -> dict:
"""获取联系人列表"""
pass
@abstractmethod
async def execute_custom(self, device_id: str, platform: Platform,
action: str, params: dict) -> dict:
"""执行自定义操作"""
pass
```
### 2.3 通道路由器
```python
# services/channel_router.py
from typing import Optional
from enum import Enum
from .unified_service import Platform, Channel
class ChannelRouter:
"""通道路由器：选择最优执行通道"""
# 官方API能力矩阵
OFFICIAL_API_CAPABILITIES = {
Platform.DOUYIN: {
"send_message": True, # 抖音私信API
"get_messages": True, # 抖音消息Webhook
"get_fans": True, # 粉丝列表
"reply_comment": True, # 评论回复
},
Platform.WECHAT: {
"send_message": False, # 微信个人号无官方API
"get_messages": False,
},
Platform.XHS: {
"send_message": False, # 小红书无私信API
"get_messages": False,
},
}
def __init__(self, device_manager):
self.device_manager = device_manager
async def route(
self,
device_id: str,
platform: Platform,
action: str,
prefer_channel: Optional[Channel] = None
) -> Channel:
"""
选择最优通道
优先级：
1. 用户指定通道
2. 官方API（如果支持）
3. SDK控制（设备在线时）
4. AI Agent（兜底）
"""
# 1. 用户强制指定
if prefer_channel:
return prefer_channel
# 2. 检查官方API是否支持
if self._has_official_api(platform, action):
return Channel.OFFICIAL_API
# 3. 检查设备是否在线
device = await self.device_manager.get_device(device_id)
if device and device.status == "online":
return Channel.SDK_CONTROL
# 4. 兜底用AI Agent
return Channel.AI_AGENT
def _has_official_api(self, platform: Platform, action: str) -> bool:
"""检查是否有官方API"""
capabilities = self.OFFICIAL_API_CAPABILITIES.get(platform, {})
return capabilities.get(action, False)
```
### 2.4 统一服务实现
```python
# services/unified_device_service.py
from .unified_service import (
IUnifiedDeviceService, Platform, Channel,
SendMessageRequest, SendMessageResponse,
GetMessagesRequest, GetMessagesResponse
)
from .channel_router import ChannelRouter
from .channels.official_api import OfficialAPIChannel
from .channels.sdk_control import SDKControlChannel
from .channels.ai_agent import AIAgentChannel
class UnifiedDeviceService(IUnifiedDeviceService):
"""统一设备服务实现"""
def __init__(self, config: dict):
self.router = ChannelRouter(config.get("device_manager"))
# 初始化各通道
self.channels = {
Channel.OFFICIAL_API: OfficialAPIChannel(config),
Channel.SDK_CONTROL: SDKControlChannel(config),
Channel.AI_AGENT: AIAgentChannel(config),
}
async def send_message(self, req: SendMessageRequest) -> SendMessageResponse:
"""发送消息"""
# 1. 路由选择通道
channel = await self.router.route(
req.device_id, req.platform, "send_message"
)
# 2. 尝试执行
try:
result = await self.channels[channel].send_message(req)
return SendMessageResponse(
success=True,
message_id=result.get("message_id"),
channel_used=channel,
error=None
)
except Exception as e:
# 3. 失败降级
return await self._fallback_send_message(req, channel, str(e))
async def _fallback_send_message(
self,
req: SendMessageRequest,
failed_channel: Channel,
error: str
) -> SendMessageResponse:
"""降级处理"""
# 按优先级尝试其他通道
fallback_order = [
Channel.SDK_CONTROL,
Channel.AI_AGENT,
]
for channel in fallback_order:
if channel == failed_channel:
continue
try:
result = await self.channels[channel].send_message(req)
return SendMessageResponse(
success=True,
message_id=result.get("message_id"),
channel_used=channel,
error=None
)
except Exception:
continue
# 全部失败
return SendMessageResponse(
success=False,
message_id=None,
channel_used=failed_channel,
error=f"所有通道均失败: {error}"
)
async def get_messages(self, req: GetMessagesRequest) -> GetMessagesResponse:
"""获取消息"""
channel = await self.router.route(
req.device_id, req.platform, "get_messages"
)
result = await self.channels[channel].get_messages(req)
return GetMessagesResponse(
success=True,
messages=result.get("messages", []),
channel_used=channel,
error=None
)
# ... 其他方法类似实现
```
---
## 三、官方API通道
### 3.1 抖音OpenAPI对接
```python
# services/channels/official_api/douyin.py
import httpx
from typing import Dict, Any
from datetime import datetime
class DouyinOfficialAPI:
"""抖音官方API对接"""
BASE_URL = "https://open.douyin.com"
def __init__(self, app_id: str, app_secret: str):
self.app_id = app_id
self.app_secret = app_secret
self.access_token = None
self.token_expires = 0
async def get_access_token(self) -> str:
"""获取access_token"""
if self.access_token and datetime.now().timestamp() < self.token_expires:
return self.access_token
async with httpx.AsyncClient() as client:
resp = await client.post(
f"{self.BASE_URL}/oauth/client_token/",
json={
"client_key": self.app_id,
"client_secret": self.app_secret,
"grant_type": "client_credential"
}
)
data = resp.json()
self.access_token = data["data"]["access_token"]
self.token_expires = datetime.now().timestamp() + data["data"]["expires_in"] - 60
return self.access_token
async def send_private_message(
self,
open_id: str,
content: str,
msg_type: str = "text"
) -> Dict[str, Any]:
"""发送私信"""
token = await self.get_access_token()
async with httpx.AsyncClient() as client:
resp = await client.post(
f"{self.BASE_URL}/im/message/send/",
headers={
"access-token": token,
"Content-Type": "application/json"
},
json={
"to_user_id": open_id,
"message_type": msg_type,
"content": content
}
)
return resp.json()
async def get_fans_list(self, cursor: int = 0, count: int = 20) -> Dict[str, Any]:
"""获取粉丝列表"""
token = await self.get_access_token()
async with httpx.AsyncClient() as client:
resp = await client.get(
f"{self.BASE_URL}/fans/list/",
headers={"access-token": token},
params={"cursor": cursor, "count": count}
)
return resp.json()
```
### 3.2 抖音Webhook接收
```python
# services/channels/official_api/douyin_webhook.py
from fastapi import APIRouter, Request, BackgroundTasks
import hashlib
import json
router = APIRouter()
class DouyinWebhookHandler:
"""抖音Webhook处理器"""
def __init__(self, token: str, message_handler):
self.token = token
self.message_handler = message_handler
def verify_signature(self, signature: str, timestamp: str, nonce: str) -> bool:
"""验证签名"""
tmp_list = [self.token, timestamp, nonce]
tmp_list.sort()
tmp_str = "".join(tmp_list)
return hashlib.sha1(tmp_str.encode()).hexdigest() == signature
async def handle_event(self, event: dict):
"""处理事件"""
event_type = event.get("event")
if event_type == "im_receive_msg":
# 收到私信
await self.message_handler.on_message_received(
platform="douyin",
from_user=event["from_user_id"],
content=event["content"],
msg_id=event["msg_id"]
)
elif event_type == "im_enter_conversation":
# 用户进入会话
pass
@router.post("/webhook/douyin")
async def douyin_webhook(request: Request, background_tasks: BackgroundTasks):
"""抖音Webhook入口"""
body = await request.json()
# 验证签名
signature = request.headers.get("X-Douyin-Signature")
timestamp = request.headers.get("X-Douyin-Timestamp")
nonce = request.headers.get("X-Douyin-Nonce")
handler = DouyinWebhookHandler(
token="your_webhook_token",
message_handler=message_service
)
if not handler.verify_signature(signature, timestamp, nonce):
return {"error": "invalid signature"}
# 异步处理事件
background_tasks.add_task(handler.handle_event, body)
return {"success": True}
```
---
## 四、SDK控制通道
### 4.1 通道实现
```python
# services/channels/sdk_control.py
from ..unified_service import (
SendMessageRequest, GetMessagesRequest, Platform
)
from skills.registry import SKILL_REGISTRY
class SDKControlChannel:
"""SDK控制通道"""
def __init__(self, config: dict):
self.ws_hub = config.get("ws_hub")
async def send_message(self, req: SendMessageRequest) -> dict:
"""通过SDK发送消息"""
# 获取对应平台的Skill
skill_name = self._platform_to_skill(req.platform)
# 发送WebSocket指令
result = await self.ws_hub.send_command(
device_id=req.device_id,
command={
"type": "execute",
"data": {
"script": skill_name,
"action": "send_message",
"params": {
"contact": req.to_id,
"message": req.content,
"msg_type": req.msg_type.value
}
}
},
timeout=30
)
return result
async def get_messages(self, req: GetMessagesRequest) -> dict:
"""通过SDK获取消息"""
skill_name = self._platform_to_skill(req.platform)
result = await self.ws_hub.send_command(
device_id=req.device_id,
command={
"type": "execute",
"data": {
"script": skill_name,
"action": "get_messages",
"params": {
"limit": req.limit
}
}
},
timeout=30
)
return result
def _platform_to_skill(self, platform: Platform) -> str:
"""平台映射到Skill"""
mapping = {
Platform.WECHAT: "wechat",
Platform.DOUYIN: "douyin",
Platform.XHS: "xhs",
}
return mapping.get(platform, str(platform.value))
```
---
## 五、AI Agent通道
### 5.1 通道实现
```python
# services/channels/ai_agent.py
from droidrun import DroidAgent, AdbTools
from llama_index.llms.deepseek import DeepSeek
from ..unified_service import SendMessageRequest, Platform
class AIAgentChannel:
"""AI Agent通道"""
def __init__(self, config: dict):
self.llm = DeepSeek(
model="deepseek-chat",
api_key=config.get("deepseek_api_key")
)
async def send_message(self, req: SendMessageRequest) -> dict:
"""通过AI Agent发送消息"""
# 构建自然语言任务
platform_name = self._get_platform_name(req.platform)
task = f"打开{platform_name}，找到联系人'{req.to_id}'，发送消息：{req.content}"
# 创建Agent
tools = AdbTools(device_id=req.device_id)
agent = DroidAgent(
goal=task,
llm=self.llm,
tools=tools
)
# 执行
result = await agent.run()
return {
"success": result.get("success", False),
"steps": result.get("steps", [])
}
def _get_platform_name(self, platform: Platform) -> str:
"""获取平台中文名"""
names = {
Platform.WECHAT: "微信",
Platform.DOUYIN: "抖音",
Platform.XHS: "小红书",
}
return names.get(platform, str(platform.value))
```
---
## 六、REST API接口
```python
# routers/unified.py
from fastapi import APIRouter, HTTPException
from services.unified_device_service import UnifiedDeviceService
from services.unified_service import *
router = APIRouter(prefix="/api/v3", tags=["统一接口"])
# 服务实例
service = UnifiedDeviceService(config={...})
@router.post("/message/send", response_model=SendMessageResponse)
async def send_message(req: SendMessageRequest):
"""发送消息（统一接口）"""
return await service.send_message(req)
@router.post("/message/list", response_model=GetMessagesResponse)
async def get_messages(req: GetMessagesRequest):
"""获取消息列表"""
return await service.get_messages(req)
@router.post("/friend/add")
async def add_friend(
device_id: str,
platform: Platform,
user_id: str,
message: str = ""
):
"""添加好友"""
return await service.add_friend(device_id, platform, user_id, message)
@router.post("/friend/accept")
async def accept_friend(
device_id: str,
platform: Platform,
user_id: str
):
"""通过好友请求"""
return await service.accept_friend(device_id, platform, user_id)
@router.get("/contacts")
async def get_contacts(
device_id: str,
platform: Platform,
limit: int = 100
):
"""获取联系人列表"""
return await service.get_contacts(device_id, platform, limit)
```
---
## 七、存客宝PHP SDK
```php
<?php
// SDK/WorkPhoneClient.php
namespace Cunkebao\WorkPhone;
class WorkPhoneClient
{
private string $baseUrl;
private string $apiKey;
public function __construct(string $baseUrl, string $apiKey)
{
$this->baseUrl = rtrim($baseUrl, '/');
$this->apiKey = $apiKey;
}
/**
* 发送消息（统一接口）
*/
public function sendMessage(
string $deviceId,
string $platform, // wechat, douyin, xhs
string $toId,
string $content,
string $msgType = 'text'
): array {
return $this->post('/api/v3/message/send', [
'device_id' => $deviceId,
'platform' => $platform,
'to_id' => $toId,
'content' => $content,
'msg_type' => $msgType,
]);
}
/**
* 获取消息列表
*/
public function getMessages(
string $deviceId,
string $platform,
int $limit = 20
): array {
return $this->post('/api/v3/message/list', [
'device_id' => $deviceId,
'platform' => $platform,
'limit' => $limit,
]);
}
/**
* 添加好友
*/
public function addFriend(
string $deviceId,
string $platform,
string $userId,
string $message = ''
): array {
return $this->post('/api/v3/friend/add', [
'device_id' => $deviceId,
'platform' => $platform,
'user_id' => $userId,
'message' => $message,
]);
}
/**
* 执行自然语言任务（AI Agent模式）
*/
public function executeTask(string $deviceId, string $task): array
{
return $this->post('/api/agent/execute', [
'device_id' => $deviceId,
'task' => $task,
'llm_provider' => 'deepseek',
]);
}
private function post(string $path, array $data): array
{
$ch = curl_init($this->baseUrl . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer ' . $this->apiKey,
],
]);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
}
```
**使用示例**：
```php
$client = new WorkPhoneClient('https://sdk.xxx.com', 'api-key');
// 发送微信消息（自动选择最优通道）
$result = $client->sendMessage('device-001', 'wechat', 'wxid_xxx', '你好');
// 发送抖音私信（优先走官方API）
$result = $client->sendMessage('device-001', 'douyin', 'user_xxx', '感谢关注');
// 执行复杂任务（AI Agent模式）
$result = $client->executeTask('device-001', '打开淘宝搜索iPhone16并加入购物车');
```
---
## 八、总结
### 8.1 统一交互层的优势
| 优势 | 说明 |
|------|------|
| **接口统一** | 无论底层是API还是SDK，上层调用方式一致 |
| **智能路由** | 自动选择最优通道，优先官方API |
| **降级容错** | 一个通道失败自动切换其他通道 |
| **扩展方便** | 新增平台只需实现统一接口 |
### 8.2 通道选择策略
```
1. 有官方API → 优先用API（最稳定）
2. 设备在线 → 用SDK控制（成本低）
3. SDK失败 → 用AI Agent（最灵活）
4. 全部失败 → 返回错误，人工介入
```

114
开发文档/6、后端/Agent端技能实现文档.md Normal file
View File

@@ -0,0 +1,114 @@
# Agent端技能实现文档
> **更新**: 2026-02-06
> **技术栈**: Python + uiautomator2 + WebSocket
---
## 一、技能架构
```
agent/
├── agent.py # Agent主程序（WebSocket客户端）
├── skill_executor.py # 技能执行器
├── error_handler.py # 错误处理
├── voice_agent.py # 语音控制Agent
└── skills/
├── __init__.py # 技能注册表（SKILL_REGISTRY）
├── base.py # BaseSkill基类
├── wechat/skill.py # 微信技能（28个方法）
├── douyin/skill.py # 抖音技能（14个方法）
├── xhs/skill.py # 小红书技能（16个方法）
├── app_manager.py # APP管理技能
├── search.py # 搜索技能
└── voice_control.py # 语音控制技能
```
---
## 二、BaseSkill 基类
所有技能必须继承 `BaseSkill`，提供以下通用方法：
| 方法 | 说明 |
|------|------|
| `launch()` | 启动APP |
| `close()` | 关闭APP |
| `click_text(text)` | 点击文本元素 |
| `click_desc(desc)` | 点击描述元素 |
| `click_id(resource_id)` | 点击资源ID |
| `input_text(text)` | 输入文本 |
| `swipe(direction)` | 滑动屏幕 |
| `screenshot()` | 截图 |
| `get_ui_tree()` | 获取UI树 |
| `wait_for_app_ready()` | 等待APP就绪 |
| `exists(text)` | 检查元素存在 |
| `sleep(seconds)` | 等待 |
---
## 三、已实现技能
### 3.1 微信技能 (WechatSkill) - 28个方法
| 分类 | 方法 | 状态 |
|------|------|------|
| **消息** | send_message, get_messages, batch_send_message | ✅ |
| **好友** | add_friend, accept_friend, set_remark, delete_friend, get_contacts | ✅ |
| **群聊** | create_group, invite_to_group, remove_from_group, send_group_message | ✅ |
| **群管理** | set_group_notice, set_group_name, set_group_welcome, get_groups, get_group_members | ✅ |
| **标签** | add_tag, remove_tag, create_tag, delete_tag, get_tags, get_users_by_tag | ✅ |
| **朋友圈** | post_moments, like_moments, comment_moments, get_moments | ✅ |
| **调试** | get_current_screen_info | ✅ |
### 3.2 抖音技能 (DouyinSkill) - 14个方法
| 分类 | 方法 | 状态 |
|------|------|------|
| **消息** | send_message, get_messages, batch_send_message | ✅ |
| **粉丝** | get_fans, follow_user, unfollow_user, search_user | ✅ |
| **评论** | get_comments, reply_comment | ✅ |
| **视频** | like_video, collect_video, share_video | ✅ |
| **兼容** | get_contacts, add_friend | ✅ |
### 3.3 小红书技能 (XhsSkill) - 16个方法
| 分类 | 方法 | 状态 |
|------|------|------|
| **消息** | send_message, get_messages, batch_send_message | ✅ |
| **粉丝** | get_fans, follow_user, unfollow_user, search_user | ✅ |
| **评论** | get_comments, reply_comment | ✅ |
| **笔记** | like_note, collect_note, share_note, search_note, post_note | ✅ |
| **兼容** | get_contacts, add_friend | ✅ |
---
## 四、技能注册表
```python
SKILL_REGISTRY = {
"wechat": WechatSkill,
"douyin": DouyinSkill,
"xhs": XhsSkill,
"voice_control": VoiceControlSkill,
"app_manager": AppManagerSkill,
"search": SearchSkill,
}
```
调用方式：
```python
skill_class = SKILL_REGISTRY["wechat"]
skill = skill_class(device)
result = skill.send_message("好友ID", "你好")
```
---
## 五、待开发技能
| 技能 | 优先级 | 说明 |
|------|--------|------|
| XianyuSkill | 高 | 闲鱼消息、商品管理 |
| SoulSkill | 低 | Soul社交 |
| 通用APP技能 | 中 | 基于AI Agent |

19
开发文档/6、后端/README.md Normal file
View File

@@ -0,0 +1,19 @@
# 6、后端
**项目**：工作手机SDK v3.0（服务端 FastAPI + WebSocket Hub + 脚本引擎；设备端 Agent + u2 + 各 Skill；M5 脚本引擎约 75%，M8 Agent 约 95%。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；子目录（github核心代码/、docs/）不计入 3 个主文档数量。
**当前项目状态**：总进度 96%；服务端 API、Agent 连接、微信 Skill 已完整，抖音/小红书服务端路由待补。进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [SDK服务端实现文档.md](SDK服务端实现文档.md) | SDK 服务端实现 |
| [Agent端技能实现文档.md](Agent端技能实现文档.md) | Agent 端技能实现 |
| [后端规范与代码汇总.md](后端规范与代码汇总.md) | 后端规范摘要 + 核心代码汇总索引 |
**子目录**：`github核心代码/`（u2/DroidRun/闲鱼/抖音/Frida）、`docs/`（历史技术文档）。

124
开发文档/6、后端/SDK服务端实现文档.md Normal file
View File

@@ -0,0 +1,124 @@
# SDK服务端实现文档
> **更新**: 2026-02-06
> **技术栈**: Python FastAPI + WebSocket + MongoDB
---
## 一、服务端架构
```
app/
├── main.py # FastAPI入口，注册路由，WebSocket端点
├── config.py # 配置管理
├── models/ # 数据模型
│ └── __init__.py
├── routers/ # API路由
│ ├── devices.py # 设备管理接口
│ ├── unified.py # 统一API接口（存客宝调用）
│ ├── agent.py # AI代理接口
│ ├── adb.py # ADB操作接口
│ ├── projects.py # 项目管理接口
│ ├── qrcode.py # 二维码扫描接口
│ ├── voice.py # 语音控制接口
│ └── ws_device.py # WebSocket设备路由
├── services/ # 业务服务
│ ├── ws_hub.py # WebSocket连接管理
│ ├── device_manager.py # 设备管理服务
│ ├── ai_agent.py # AI代理服务
│ ├── adb_device.py # ADB设备服务
│ └── experience_db.py # 经验数据库
└── skills/ # 服务端技能
├── base.py # 技能基类
├── wechat/skill.py # 微信技能
└── douyin/skill.py # 抖音技能
```
---
## 二、核心模块说明
### 2.1 main.py - 应用入口
- 配置CORS跨域
- 注册所有路由器
- 定义WebSocket端点 `/ws/device/{device_id}`
- 健康检查 `/health`
### 2.2 unified.py - 统一API路由（核心）
存客宝直接调用的API，包含：
- **消息管理**: send, list, batch-send
- **好友管理**: add, accept, set-remark, delete
- **群聊管理**: create, invite, remove, set-notice, set-name, send-message, list, members
- **标签管理**: add, remove, create, delete, list, users
- **朋友圈**: post, like, comment, list
### 2.3 ws_hub.py - WebSocket Hub
管理所有手机设备的WebSocket长连接：
- 设备连接/断开
- 心跳保活（30s间隔）
- 命令发送和响应匹配
- 设备状态追踪
### 2.4 ChannelRouter - 智能通道路由
```
请求 → ChannelRouter → 选择最优通道
├── Layer 1: 官方API（最稳定）
├── Layer 2: SDK控制（免费）
└── Layer 3: AI Agent（兜底）
```
---
## 三、已实现接口清单
| 接口 | 方法 | 路径 | 状态 |
|------|------|------|------|
| 发送消息 | POST | /api/unified/message/send | ✅ |
| 获取消息 | POST | /api/unified/message/list | ✅ |
| 批量发送 | POST | /api/unified/message/batch-send | ✅ |
| 添加好友 | POST | /api/unified/friend/add | ✅ |
| 接受好友 | POST | /api/unified/friend/accept | ✅ |
| 设置备注 | POST | /api/unified/friend/set-remark | ✅ |
| 删除好友 | POST | /api/unified/friend/delete | ✅ |
| 获取通讯录 | POST | /api/unified/contact/list | ✅ |
| 创建群聊 | POST | /api/unified/group/create | ✅ |
| 邀请入群 | POST | /api/unified/group/invite | ✅ |
| 移出群聊 | POST | /api/unified/group/remove | ✅ |
| 设置群公告 | POST | /api/unified/group/set-notice | ✅ |
| 设置群名 | POST | /api/unified/group/set-name | ✅ |
| 群消息 | POST | /api/unified/group/send-message | ✅ |
| 群列表 | POST | /api/unified/group/list | ✅ |
| 群成员 | POST | /api/unified/group/members | ✅ |
| 添加标签 | POST | /api/unified/tag/add | ✅ |
| 移除标签 | POST | /api/unified/tag/remove | ✅ |
| 创建标签 | POST | /api/unified/tag/create | ✅ |
| 删除标签 | POST | /api/unified/tag/delete | ✅ |
| 标签列表 | POST | /api/unified/tag/list | ✅ |
| 标签用户 | POST | /api/unified/tag/users | ✅ |
| 发布朋友圈 | POST | /api/unified/moments/post | ✅ |
| 点赞朋友圈 | POST | /api/unified/moments/like | ✅ |
| 评论朋友圈 | POST | /api/unified/moments/comment | ✅ |
| 朋友圈列表 | POST | /api/unified/moments/list | ✅ |
| 设备列表 | GET | /api/devices | ✅ |
| 设备截图 | GET | /api/devices/{id}/screenshot | ✅ |
| 设备UI树 | GET | /api/devices/{id}/uitree | ✅ |
| AI任务 | POST | /api/agent/execute | ✅ |
| 健康检查 | GET | /health | ✅ |
---
## 四、启动方式
```bash
# Docker方式（推荐）
cd /Users/karuo/Documents/开发/2、私域银行/工作手机/sdk
docker-compose up -d
# 本地开发
pip install -r requirements.txt
cd app && uvicorn main:app --host 0.0.0.0 --port 8899 --reload
```

483
开发文档/6、后端/docs/02-技术架构.md Normal file
View File

@@ -0,0 +1,483 @@
# 02. 技术架构
> 适合读者：架构师、后端开发、技术负责人
---
## 一、整体架构
### 1.1 系统架构图
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 存客宝生态系统 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ 存客宝后端 (ThinkPHP) │ │
│ │ │ │
│ │ $sdk = new WorkPhoneSDK('https://workphone.xxx.com', 'key'); │ │
│ │ $sdk->execute('device-001', 'wechat', 'send_message', [...]); │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
└─────────────────────────────────────┼───────────────────────────────────────┘
│ HTTPS REST API
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 工作手机SDK服务器（云端部署 - 腾讯云/阿里云） │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Nginx (反向代理/SSL卸载) │ │
│ │ Port: 443 (HTTPS/WSS) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴───────────────────────────┐ │
│ │ │ │
│ ┌─────▼──────┐ ┌─────────────────┐ │ │
│ │ API Gateway│ │ WebSocket Hub │ │ │
│ │ (FastAPI) │ │ (设备长连接) │ │ │
│ │ Port: 8000 │ │ Port: 8765 │ │ │
│ └─────┬──────┘ └────────┬────────┘ │ │
│ │ │ │ │
│ ┌─────┴──────────────────────────────┴────────────────────────┴───────┐ │
│ │ 核心服务层 │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 设备管理 │ │ 指令路由 │ │ 脚本引擎 │ │ │
│ │ │ DeviceSvc │ │ CommandSvc │ │ ScriptEngine│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 抓包服务 │ │ 消息队列 │ │ 任务调度 │ │ │
│ │ │ CaptureSvc │ │ QueueSvc │ │ SchedulerSvc│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────┴───────────────────────────────────┐ │
│ │ 数据层 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ MongoDB │ │ Redis │ │ MinIO │ │ 脚本仓库 │ │ │
│ │ │ 业务数据 │ │ 缓存/队列 │ │ 文件存储 │ │ Git仓库 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
WebSocket (wss://xxx:443/ws)
设备主动连接到服务器
│
┌───────────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ 手机设备 A │ │ 手机设备 B │ │ 手机设备 N │
│ (厦门) │ │ (北京) │ │ (上海) │
│ │ │ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │
│ │工作手机 │ │ │ │工作手机 │ │ │ │工作手机 │ │
│ │Agent APP │ │ │ │Agent APP │ │ │ │Agent APP │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ Frida │ │ │ │ Frida │ │ │ │ Frida │ │
│ │ u2 │ │ │ │ u2 │ │ │ │ u2 │ │
│ │ scrcpy │ │ │ │ scrcpy │ │ │ │ scrcpy │ │
│ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │
│ │ │ │ │ │
│ 微信/抖音/... │ │ Soul/探探/... │ │ 新APP... │
└───────────────┘ └───────────────┘ └───────────────┘
```
### 1.2 核心设计原则
| 原则 | 说明 | 实现方式 |
|------|------|----------|
| **有状态前端 + 无状态后端** | 前端维护连接，后端处理业务 | WebSocket Hub + FastAPI |
| **设备主动连接** | 解决NAT穿透问题 | 设备启动后主动连接云端 |
| **脚本引擎分离** | 新APP无需改SDK | 脚本热加载 |
| **混合Root策略** | 灵活适应不同场景 | 免Root + Gadget + Magisk |
---
## 二、技术栈详解
### 2.1 抓包层
| 组件 | 版本 | 作用 | 部署位置 |
|------|------|------|----------|
| **Frida** | 16.x | 动态Hook/SSL Bypass | 设备端 |
| **objection** | 1.11+ | Frida自动化 | 服务端/开发机 |
| **mitmproxy** | 10.x | HTTPS代理 | 服务端（可选） |
**Frida工作原理**：
```
┌───────────────────────────────────────────────────────────────┐
│ 目标APP进程 │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ OkHttp │────▶│ SSL/TLS │────▶│ 网络请求 │ │
│ │ Retrofit │ │ 证书校验 │ │ │ │
│ └─────────────┘ └──────┬──────┘ └─────────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ Frida Hook │ │
│ │ 绕过证书校验 │ │
│ │ 获取明文数据 │ │
│ └─────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ 上报到工作手机Agent │ │
│ └─────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────┘
```
### 2.2 控制层
| 组件 | 版本 | 作用 | 部署位置 |
|------|------|------|----------|
| **uiautomator2** | 3.x | UI自动化 | 设备端 |
| **scrcpy** | 2.x | 投屏控制 | 设备端+服务端 |
| **脚本引擎** | 自研 | 加载/执行脚本 | 服务端 |
**uiautomator2架构**：
```
┌──────────────┐ ┌──────────────────────────────────────┐
│ Python Client│ HTTP │ Android设备 │
│ (服务端) │◀───────▶│ │
└──────────────┘ │ ┌──────────────────────────────┐ │
│ │ uiautomator-server (APK) │ │
│ │ 监听 7912 端口 │ │
│ │ │ │
│ │ 提供： │ │
│ │ - 元素定位 │ │
│ │ - 点击/滑动 │ │
│ │ - 截图 │ │
│ │ - 输入文字 │ │
│ └──────────────────────────────┘ │
│ │
└──────────────────────────────────────┘
```
### 2.3 通信层
| 组件 | 版本 | 作用 | 端口 |
|------|------|------|------|
| **FastAPI** | 0.110+ | REST API | 8000 |
| **WebSocket** | - | 设备长连接 | 8765 |
| **Nginx** | 1.24+ | 反向代理/SSL | 443 |
**WebSocket连接管理**：
```python
# 连接池管理
device_connections: Dict[str, WebSocket] = {} # device_id -> websocket
pending_commands: Dict[str, asyncio.Future] = {} # command_id -> future
# 心跳保活（30秒间隔）
async def heartbeat_handler(device_id: str):
while device_id in device_connections:
await asyncio.sleep(30)
try:
await device_connections[device_id].send_json({"type": "ping"})
except:
del device_connections[device_id]
break
# 指数退避重连（设备端）
reconnect_delay = min(base_delay * (2 ** attempts), max_delay)
```
### 2.4 数据层
| 组件 | 版本 | 作用 | 数据类型 |
|------|------|------|----------|
| **MongoDB** | 6.0+ | 业务数据 | 设备信息/消息/抓包 |
| **Redis** | 7.x | 缓存/队列 | 设备状态/指令队列 |
| **MinIO** | - | 文件存储 | 截图/录屏 |
---
## 三、模块设计
### 3.1 设备管理模块
```python
# 设备数据模型
class Device:
device_id: str # 设备唯一ID
name: str # 设备名称
model: str # 设备型号 (Redmi K60)
android_version: str # Android版本 (14)
agent_version: str # Agent版本 (1.0.0)
status: str # online/offline
last_heartbeat: datetime
capabilities: List[str] # ['frida', 'u2', 'scrcpy']
apps: List[str] # 已安装的目标APP
# 设备状态机
DEVICE_STATES = {
'offline': ['connecting'],
'connecting': ['online', 'offline'],
'online': ['busy', 'offline'],
'busy': ['online', 'offline'],
}
```
### 3.2 脚本引擎模块
```python
# 脚本基类
class BaseScript:
"""所有APP脚本的基类"""
PACKAGE: str = "" # APP包名，子类必须定义
NAME: str = "" # APP名称
def __init__(self, device: Device):
self.device = device
self.u2 = u2.connect(device.device_id)
def launch(self) -> bool:
"""启动APP"""
self.u2.app_start(self.PACKAGE)
return self.u2.wait_activity(timeout=10)
def close(self):
"""关闭APP"""
self.u2.app_stop(self.PACKAGE)
def screenshot(self) -> bytes:
"""截图"""
return self.u2.screenshot(format='raw')
def click(self, x: int, y: int):
"""点击"""
self.u2.click(x, y)
def click_text(self, text: str, timeout: float = 10):
"""点击文字"""
self.u2.xpath(f'//*[@text="{text}"]').click(timeout=timeout)
def input_text(self, text: str):
"""输入文字"""
self.u2.send_keys(text)
def get_ui_tree(self) -> str:
"""获取UI树（用于分析）"""
return self.u2.dump_hierarchy()
# 脚本注册表
SCRIPT_REGISTRY: Dict[str, Type[BaseScript]] = {}
def register_script(name: str):
"""脚本注册装饰器"""
def decorator(cls: Type[BaseScript]):
SCRIPT_REGISTRY[name] = cls
return cls
return decorator
```
### 3.3 抓包服务模块
```python
# Frida脚本管理
class CaptureService:
def __init__(self):
self.active_sessions: Dict[str, frida.Session] = {}
async def start_capture(self, device_id: str, package: str):
"""开始抓包"""
# 加载通用SSL Bypass脚本
script = self.load_script('ssl_bypass.js')
# 注入到目标进程
session = frida.attach(package)
session.create_script(script)
self.active_sessions[device_id] = session
async def stop_capture(self, device_id: str):
"""停止抓包"""
if device_id in self.active_sessions:
self.active_sessions[device_id].detach()
del self.active_sessions[device_id]
```
---
## 四、数据库设计
### 4.1 MongoDB Collections
```javascript
// 设备集合
db.devices = {
_id: ObjectId,
device_id: String, // 设备唯一ID
name: String, // 设备名称
model: String, // 设备型号
android_version: String, // Android版本
agent_version: String, // Agent版本
status: String, // online/offline/busy
capabilities: [String], // 能力列表
apps: [String], // 已安装APP
last_heartbeat: Date,
created_at: Date,
updated_at: Date
}
// 脚本执行日志
db.execution_logs = {
_id: ObjectId,
device_id: String,
script: String, // wechat/douyin/xhs
action: String, // send_message/get_friends
params: Object, // 参数
status: String, // success/failed
result: Object, // 返回结果
error: String, // 错误信息
duration_ms: Number, // 执行耗时
created_at: Date
}
// 抓包数据
db.capture_data = {
_id: ObjectId,
device_id: String,
package: String, // APP包名
url: String, // 请求URL
method: String, // GET/POST
headers: Object,
request_body: String,
response_code: Number,
response_body: String,
timestamp: Date
}
// 消息记录（存客宝业务）
db.messages = {
_id: ObjectId,
device_id: String,
platform: String, // wechat/douyin/xhs
direction: String, // in/out
from_id: String,
to_id: String,
content: String,
msg_type: String, // text/image/voice
created_at: Date
}
```
### 4.2 Redis数据结构
```
# 设备在线状态
device:status:{device_id} = "online" | "offline" | "busy"
TTL: 60s (心跳刷新)
# 设备能力缓存
device:caps:{device_id} = ["frida", "u2", "scrcpy"]
# 指令队列
queue:commands:{device_id} = List<Command JSON>
# 响应等待
pending:{command_id} = {device_id, status, timeout}
TTL: 30s
```
---
## 五、安全设计
### 5.1 认证机制
```
API Key认证
├── 每个存客宝租户分配独立API Key
├── 请求头：Authorization: Bearer {api_key}
├── 服务端验证有效性
└── 支持API Key轮换
设备认证
├── 设备首次连接时注册
├── 生成唯一 device_token
├── WebSocket连接时验证token
└── 支持设备解绑/重绑
```
### 5.2 传输安全
```
HTTPS/WSS
├── Nginx SSL终结
├── 证书：Let's Encrypt 自动续期
├── 最低TLS 1.2
└── 敏感数据端到端加密
```
### 5.3 操作审计
```
日志记录
├── 所有API调用记录
├── 设备指令执行记录
├── 异常行为告警
└── 日志保留90天
```
---
## 六、性能指标
| 指标 | 目标值 | 说明 |
|------|--------|------|
| 设备容量 | 1000+ | 单服务器支持 |
| 连接延迟 | < 200ms | 设备到服务器 |
| API响应 | < 500ms | 95分位 |
| 投屏帧率 | ≥ 15fps | scrcpy |
| 可用性 | 99.9% | 年度 |
---
## 七、扩展性设计
### 7.1 水平扩展
```
┌────────────┐
│ Nginx │
│ 负载均衡 │
└─────┬──────┘
│
┌───────────────┼───────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ SDK节点1 │ │ SDK节点2 │ │ SDK节点N │
│ │ │ │ │ │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
└───────────────┼───────────────┘
│
┌─────▼─────┐
│ Redis │
│ (共享状态) │
└───────────┘
```
### 7.2 新APP扩展
```
1. 无需修改SDK核心
2. 编写Python脚本继承BaseScript
3. 实现业务方法
4. 注册到脚本引擎
5. 通过API调用
```
详见 [05-脚本开发指南](05-脚本开发指南.md)

897
开发文档/6、后端/docs/04-设备端开发.md Normal file
View File

@@ -0,0 +1,897 @@
# 04. 设备端开发
> 适合读者：Android开发、移动端工程师
---
## 一、架构概述
### 1.1 设备端组件
```
┌────────────────────────────────────────────────────────────────┐
│ 工作手机Agent APP │
├────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 主服务进程 │ │
│ │ │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ WebSocket │ │ 心跳检测 │ │ 状态上报 │ │ │
│ │ │ 客户端 │ │ 30s间隔 │ │ 设备信息 │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────┴─────────────────────────────┐ │
│ │ 能力模块 │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Frida 模块 │ │ uiautomator2 │ │ │
│ │ │ (可选) │ │ HTTP服务 │ │ │
│ │ │ │ │ │ │ │
│ │ │ - SSL Bypass │ │ - 元素定位 │ │ │
│ │ │ - Hook函数 │ │ - 操作执行 │ │ │
│ │ │ - 数据拦截 │ │ - 截图 │ │ │
│ │ └────────────────┘ └────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ scrcpy 模块 │ │ 命令处理器 │ │ │
│ │ │ │ │ │ │ │
│ │ │ - 屏幕采集 │ │ - 指令解析 │ │ │
│ │ │ - 编码传输 │ │ - 结果上报 │ │ │
│ │ └────────────────┘ └────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
```
### 1.2 技术栈
| 组件 | 技术 | 版本 |
|------|------|------|
| 开发语言 | Kotlin | 1.9+ |
| 最低Android | 7.0 | API 24 |
| 目标Android | 14 | API 34 |
| WebSocket | OkHttp | 4.12+ |
| UI自动化 | uiautomator2-server | 最新 |
| Hook框架 | Frida | 16.x |
---
## 二、项目结构
```
android-agent/
├── app/
│ ├── src/main/
│ │ ├── java/com/workphone/agent/
│ │ │ ├── MainActivity.kt # 主界面
│ │ │ ├── WorkPhoneApp.kt # Application
│ │ │ │
│ │ │ ├── websocket/
│ │ │ │ ├── WebSocketClient.kt # WebSocket客户端
│ │ │ │ ├── MessageHandler.kt # 消息处理
│ │ │ │ └── ReconnectManager.kt # 重连管理
│ │ │ │
│ │ │ ├── commands/
│ │ │ │ ├── CommandExecutor.kt # 命令执行器
│ │ │ │ ├── ClickCommand.kt # 点击命令
│ │ │ │ ├── InputCommand.kt # 输入命令
│ │ │ │ └── ScreenshotCommand.kt # 截图命令
│ │ │ │
│ │ │ ├── automation/
│ │ │ │ ├── U2Client.kt # uiautomator2客户端
│ │ │ │ └── ScriptRunner.kt # 脚本运行器
│ │ │ │
│ │ │ ├── capture/
│ │ │ │ ├── FridaManager.kt # Frida管理
│ │ │ │ └── CaptureService.kt # 抓包服务
│ │ │ │
│ │ │ ├── services/
│ │ │ │ ├── AgentService.kt # 前台服务
│ │ │ │ └── BootReceiver.kt # 开机自启
│ │ │ │
│ │ │ └── utils/
│ │ │ ├── DeviceInfo.kt # 设备信息
│ │ │ ├── Logger.kt # 日志
│ │ │ └── Preferences.kt # 配置存储
│ │ │
│ │ ├── res/
│ │ │ ├── layout/
│ │ │ ├── values/
│ │ │ └── xml/
│ │ │
│ │ └── AndroidManifest.xml
│ │
│ └── build.gradle.kts
│
├── frida-scripts/ # Frida脚本
│ ├── ssl_bypass.js # 通用SSL绕过
│ ├── wechat_hook.js # 微信Hook
│ └── common.js # 公共函数
│
└── build.gradle.kts
```
---
## 三、WebSocket客户端
### 3.1 基础实现
```kotlin
// websocket/WebSocketClient.kt
class WorkPhoneWebSocket(
private val serverUrl: String,
private val deviceId: String,
private val onMessage: (JSONObject) -> Unit,
private val onConnected: () -> Unit,
private val onDisconnected: () -> Unit
) {
private var webSocket: WebSocket? = null
private val client = OkHttpClient.Builder()
.readTimeout(0, TimeUnit.MILLISECONDS)
.pingInterval(30, TimeUnit.SECONDS) // OkHttp自动ping
.build()
private val reconnectManager = ReconnectManager()
private val gson = Gson()
fun connect() {
val request = Request.Builder()
.url("$serverUrl/ws/device/$deviceId")
.build()
webSocket = client.newWebSocket(request, object : WebSocketListener() {
override fun onOpen(webSocket: WebSocket, response: Response) {
Log.i(TAG, "WebSocket连接成功")
reconnectManager.reset()
sendRegister()
onConnected()
}
override fun onMessage(webSocket: WebSocket, text: String) {
try {
val message = JSONObject(text)
handleMessage(message)
} catch (e: Exception) {
Log.e(TAG, "消息解析失败: $text", e)
}
}
override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
Log.i(TAG, "WebSocket关闭: $reason")
onDisconnected()
scheduleReconnect()
}
override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
Log.e(TAG, "WebSocket失败: ${t.message}")
onDisconnected()
scheduleReconnect()
}
})
}
private fun handleMessage(message: JSONObject) {
when (message.getString("type")) {
"pong" -> {
// 心跳响应，忽略
}
"execute" -> {
// 执行命令
onMessage(message)
}
else -> {
Log.w(TAG, "未知消息类型: ${message.getString("type")}")
}
}
}
private fun sendRegister() {
val deviceInfo = DeviceInfo.collect()
val message = JSONObject().apply {
put("type", "register")
put("data", JSONObject().apply {
put("device_id", deviceId)
put("model", deviceInfo.model)
put("android_version", deviceInfo.androidVersion)
put("agent_version", BuildConfig.VERSION_NAME)
put("capabilities", JSONArray(deviceInfo.capabilities))
})
}
send(message)
}
fun sendResponse(commandId: String, code: Int, data: Any?) {
val message = JSONObject().apply {
put("type", "response")
put("command_id", commandId)
put("code", code)
put("data", data)
}
send(message)
}
fun send(message: JSONObject) {
webSocket?.send(message.toString())
}
private fun scheduleReconnect() {
reconnectManager.scheduleReconnect {
Log.i(TAG, "尝试重连...")
connect()
}
}
fun disconnect() {
reconnectManager.cancel()
webSocket?.close(1000, "Normal closure")
}
companion object {
private const val TAG = "WebSocket"
}
}
```
### 3.2 重连管理
```kotlin
// websocket/ReconnectManager.kt
class ReconnectManager {
private var attempts = 0
private val maxAttempts = 10
private val baseDelayMs = 1000L
private val maxDelayMs = 60000L
private val handler = Handler(Looper.getMainLooper())
private var reconnectRunnable: Runnable? = null
fun scheduleReconnect(action: () -> Unit) {
if (attempts >= maxAttempts) {
Log.e(TAG, "达到最大重连次数，停止重连")
return
}
// 指数退避：1s, 2s, 4s, 8s, ... 最大60s
val delay = minOf(baseDelayMs * (1 shl attempts), maxDelayMs)
attempts++
Log.i(TAG, "将在 ${delay}ms 后进行第 $attempts 次重连")
reconnectRunnable = Runnable { action() }
handler.postDelayed(reconnectRunnable!!, delay)
}
fun reset() {
attempts = 0
cancel()
}
fun cancel() {
reconnectRunnable?.let { handler.removeCallbacks(it) }
reconnectRunnable = null
}
companion object {
private const val TAG = "Reconnect"
}
}
```
---
## 四、命令执行器
### 4.1 命令分发
```kotlin
// commands/CommandExecutor.kt
class CommandExecutor(
private val context: Context,
private val webSocket: WorkPhoneWebSocket
) {
private val u2Client = U2Client()
private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
fun execute(message: JSONObject) {
val commandId = message.getString("command_id")
val data = message.getJSONObject("data")
scope.launch {
try {
val result = when (data.getString("script")) {
// 基础控制命令（直接在设备端执行）
"_system" -> executeSystemCommand(data)
// APP脚本（调用u2执行）
else -> executeScript(data)
}
webSocket.sendResponse(commandId, 200, result)
} catch (e: Exception) {
Log.e(TAG, "命令执行失败", e)
webSocket.sendResponse(commandId, 500, mapOf(
"error" to e.message
))
}
}
}
private suspend fun executeSystemCommand(data: JSONObject): Any {
val action = data.getString("action")
val params = data.optJSONObject("params") ?: JSONObject()
return when (action) {
"screenshot" -> {
val image = u2Client.screenshot()
mapOf("image_base64" to Base64.encodeToString(image, Base64.DEFAULT))
}
"click" -> {
u2Client.click(params.getInt("x"), params.getInt("y"))
mapOf("status" to "success")
}
"click_text" -> {
u2Client.clickText(params.getString("text"))
mapOf("status" to "success")
}
"input" -> {
u2Client.input(params.getString("text"))
mapOf("status" to "success")
}
"swipe" -> {
u2Client.swipe(params.getString("direction"))
mapOf("status" to "success")
}
"ui_tree" -> {
val xml = u2Client.dumpHierarchy()
mapOf("xml" to xml)
}
"launch_app" -> {
u2Client.launchApp(params.getString("package"))
mapOf("status" to "success")
}
"stop_app" -> {
u2Client.stopApp(params.getString("package"))
mapOf("status" to "success")
}
else -> throw IllegalArgumentException("未知系统命令: $action")
}
}
private suspend fun executeScript(data: JSONObject): Any {
// 脚本由服务端执行，设备端只执行基础命令
// 这里返回错误，引导使用正确的API
throw IllegalArgumentException("脚本应该通过服务端调用")
}
companion object {
private const val TAG = "CommandExecutor"
}
}
```
### 4.2 U2客户端
```kotlin
// automation/U2Client.kt
class U2Client {
// uiautomator2-server默认监听7912端口
private val baseUrl = "http://127.0.0.1:7912"
private val client = OkHttpClient.Builder()
.connectTimeout(10, TimeUnit.SECONDS)
.readTimeout(30, TimeUnit.SECONDS)
.build()
suspend fun screenshot(): ByteArray = withContext(Dispatchers.IO) {
val request = Request.Builder()
.url("$baseUrl/screenshot/0?format=jpeg")
.build()
client.newCall(request).execute().use { response ->
response.body?.bytes() ?: throw IOException("Screenshot failed")
}
}
suspend fun click(x: Int, y: Int) = withContext(Dispatchers.IO) {
val body = JSONObject().apply {
put("action", "click")
put("params", JSONObject().apply {
put("x", x)
put("y", y)
})
}
postJsonRpc("click", body)
}
suspend fun clickText(text: String, timeout: Int = 10) = withContext(Dispatchers.IO) {
// 使用XPath选择器
val selector = mapOf(
"mask" to 0,
"text" to text
)
val body = JSONObject().apply {
put("method", "waitForExists")
put("params", listOf(selector, timeout * 1000))
}
val exists = postJsonRpc("waitForExists", body)
if (exists == true) {
val clickBody = JSONObject().apply {
put("method", "click")
put("params", listOf(selector))
}
postJsonRpc("click", clickBody)
} else {
throw NoSuchElementException("Element with text '$text' not found")
}
}
suspend fun input(text: String) = withContext(Dispatchers.IO) {
val request = Request.Builder()
.url("$baseUrl/shell")
.post(FormBody.Builder()
.add("command", "input text '$text'")
.build())
.build()
client.newCall(request).execute().use { response ->
if (!response.isSuccessful) {
throw IOException("Input failed: ${response.code}")
}
}
}
suspend fun swipe(direction: String) = withContext(Dispatchers.IO) {
val (fx, fy, tx, ty) = when (direction) {
"up" -> listOf(0.5, 0.8, 0.5, 0.2)
"down" -> listOf(0.5, 0.2, 0.5, 0.8)
"left" -> listOf(0.8, 0.5, 0.2, 0.5)
"right" -> listOf(0.2, 0.5, 0.8, 0.5)
else -> throw IllegalArgumentException("Unknown direction: $direction")
}
val body = JSONObject().apply {
put("method", "swipe")
put("params", listOf(fx, fy, tx, ty, 0.5))
}
postJsonRpc("swipe", body)
}
suspend fun dumpHierarchy(): String = withContext(Dispatchers.IO) {
val request = Request.Builder()
.url("$baseUrl/dump/hierarchy")
.build()
client.newCall(request).execute().use { response ->
response.body?.string() ?: throw IOException("Dump failed")
}
}
suspend fun launchApp(packageName: String) = withContext(Dispatchers.IO) {
val body = JSONObject().apply {
put("method", "appStart")
put("params", listOf(packageName))
}
postJsonRpc("appStart", body)
}
suspend fun stopApp(packageName: String) = withContext(Dispatchers.IO) {
val body = JSONObject().apply {
put("method", "appStop")
put("params", listOf(packageName))
}
postJsonRpc("appStop", body)
}
private fun postJsonRpc(method: String, body: JSONObject): Any? {
val request = Request.Builder()
.url("$baseUrl/jsonrpc/0")
.post(body.toString().toRequestBody("application/json".toMediaType()))
.build()
client.newCall(request).execute().use { response ->
val responseBody = response.body?.string()
val json = JSONObject(responseBody ?: "{}")
if (json.has("error")) {
throw RuntimeException(json.getJSONObject("error").getString("message"))
}
return json.opt("result")
}
}
}
```
---
## 五、Frida集成
### 5.1 免Root方案（Frida Gadget）
```kotlin
// capture/FridaManager.kt
class FridaManager(private val context: Context) {
/**
* 检查目标APP是否已注入Gadget
*/
fun isGadgetInjected(packageName: String): Boolean {
// 检查APK是否包含frida-gadget.so
return try {
val pm = context.packageManager
val appInfo = pm.getApplicationInfo(packageName, 0)
val apkPath = appInfo.sourceDir
ZipFile(apkPath).use { zip ->
zip.entries().asSequence().any { entry ->
entry.name.contains("frida-gadget") ||
entry.name.contains("libgadget")
}
}
} catch (e: Exception) {
false
}
}
/**
* 获取Gadget配置
*/
fun getGadgetConfig(): GadgetConfig {
return GadgetConfig(
interaction = InteractionConfig(
type = "listen",
address = "127.0.0.1",
port = 27042
)
)
}
companion object {
private const val TAG = "FridaManager"
}
}
data class GadgetConfig(
val interaction: InteractionConfig
)
data class InteractionConfig(
val type: String,
val address: String,
val port: Int
)
```
### 5.2 通用SSL Bypass脚本
```javascript
// frida-scripts/ssl_bypass.js
'use strict';
// 通用SSL Pinning绕过脚本
// 支持：TrustManager、OkHttp、WebView、Volley等
Java.perform(function() {
console.log('[*] 开始SSL Pinning绕过...');
// ========== 1. TrustManagerImpl ==========
try {
var TrustManagerImpl = Java.use('com.android.org.conscrypt.TrustManagerImpl');
TrustManagerImpl.verifyChain.implementation = function(untrustedChain, trustAnchorChain, host, clientAuth, ocspData, tlsSctData) {
console.log('[+] Bypassing TrustManagerImpl for: ' + host);
return untrustedChain;
};
} catch(e) {
console.log('[-] TrustManagerImpl not found');
}
// ========== 2. X509TrustManager ==========
try {
var X509TrustManager = Java.use('javax.net.ssl.X509TrustManager');
var TrustManager = Java.registerClass({
name: 'com.workphone.TrustManager',
implements: [X509TrustManager],
methods: {
checkClientTrusted: function(chain, authType) {},
checkServerTrusted: function(chain, authType) {},
getAcceptedIssuers: function() { return []; }
}
});
} catch(e) {}
// ========== 3. OkHttp3 CertificatePinner ==========
try {
var CertificatePinner = Java.use('okhttp3.CertificatePinner');
CertificatePinner.check.overload('java.lang.String', 'java.util.List').implementation = function(hostname, peerCertificates) {
console.log('[+] Bypassing OkHttp3 CertificatePinner for: ' + hostname);
};
} catch(e) {
console.log('[-] OkHttp3 CertificatePinner not found');
}
// ========== 4. OkHttp3 CertificatePinner$Builder ==========
try {
var CertificatePinnerBuilder = Java.use('okhttp3.CertificatePinner$Builder');
CertificatePinnerBuilder.add.overload('java.lang.String', '[Ljava.lang.String;').implementation = function(hostname, pins) {
console.log('[+] Bypassing CertificatePinner.Builder for: ' + hostname);
return this;
};
} catch(e) {}
// ========== 5. WebViewClient ==========
try {
var WebViewClient = Java.use('android.webkit.WebViewClient');
WebViewClient.onReceivedSslError.implementation = function(view, handler, error) {
console.log('[+] Bypassing WebView SSL for: ' + view.getUrl());
handler.proceed();
};
} catch(e) {}
// ========== 6. SSLContext ==========
try {
var SSLContext = Java.use('javax.net.ssl.SSLContext');
SSLContext.init.overload('[Ljavax.net.ssl.KeyManager;', '[Ljavax.net.ssl.TrustManager;', 'java.security.SecureRandom').implementation = function(keyManager, trustManager, secureRandom) {
console.log('[+] Bypassing SSLContext.init');
var TrustManagerImpl = Java.use('com.workphone.TrustManager');
var trustManagerArray = Java.array('javax.net.ssl.TrustManager', [TrustManagerImpl.$new()]);
this.init(keyManager, trustManagerArray, secureRandom);
};
} catch(e) {}
// ========== 7. Volley ==========
try {
var HurlStack = Java.use('com.android.volley.toolbox.HurlStack');
HurlStack.createConnection.implementation = function(url) {
console.log('[+] Bypassing Volley for: ' + url);
var connection = this.createConnection(url);
if (connection.class.getName().indexOf('HttpsURLConnection') !== -1) {
var HttpsURLConnection = Java.use('javax.net.ssl.HttpsURLConnection');
connection.setHostnameVerifier(Java.use('org.apache.http.conn.ssl.AllowAllHostnameVerifier').$new());
}
return connection;
};
} catch(e) {}
console.log('[*] SSL Pinning绕过完成');
});
```
---
## 六、设备要求与权限
### 6.1 设备要求
| 项目 | 要求 | 说明 |
|------|------|------|
| Android版本 | 7.0+ | API 24+ |
| 存储空间 | 2GB+ | Agent + 脚本缓存 |
| 网络 | 可访问互联网 | 连接云端服务器 |
| USB调试 | 需开启 | uiautomator2依赖 |
### 6.2 权限列表
```xml
<!-- AndroidManifest.xml -->
<!-- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 前台服务 -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
<!-- 开机自启 -->
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<!-- 存储（截图保存） -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!-- 电源管理（保活） -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
```
### 6.3 混合Root策略
| 模式 | Root要求 | Frida方式 | 能力 |
|------|----------|-----------|------|
| 基础模式 | 免Root | 无 | 仅UI自动化 |
| 增强模式 | 免Root | Gadget注入 | UI自动化 + 应用级抓包 |
| 完整模式 | Magisk | frida-server | 全部能力 |
**推荐流程**：
```
1. 首次安装：检测设备Root状态
2. 免Root设备：使用Gadget注入方式
3. Root设备：启动frida-server
4. 根据能力自动选择抓包方案
```
---
## 七、开机自启与保活
### 7.1 前台服务
```kotlin
// services/AgentService.kt
class AgentService : Service() {
private lateinit var webSocket: WorkPhoneWebSocket
private lateinit var commandExecutor: CommandExecutor
override fun onCreate() {
super.onCreate()
startForeground(NOTIFICATION_ID, createNotification())
initWebSocket()
}
private fun createNotification(): Notification {
val channel = NotificationChannel(
CHANNEL_ID,
"工作手机Agent",
NotificationManager.IMPORTANCE_LOW
)
val nm = getSystemService(NotificationManager::class.java)
nm.createNotificationChannel(channel)
return NotificationCompat.Builder(this, CHANNEL_ID)
.setContentTitle("工作手机Agent运行中")
.setContentText("设备ID: ${getDeviceId()}")
.setSmallIcon(R.drawable.ic_notification)
.build()
}
private fun initWebSocket() {
val serverUrl = Preferences.getServerUrl(this)
val deviceId = getDeviceId()
webSocket = WorkPhoneWebSocket(
serverUrl = serverUrl,
deviceId = deviceId,
onMessage = { message ->
commandExecutor.execute(message)
},
onConnected = {
updateNotification("已连接")
},
onDisconnected = {
updateNotification("已断开，正在重连...")
}
)
commandExecutor = CommandExecutor(this, webSocket)
webSocket.connect()
}
override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
return START_STICKY // 被杀后自动重启
}
override fun onBind(intent: Intent?): IBinder? = null
companion object {
private const val NOTIFICATION_ID = 1
private const val CHANNEL_ID = "agent_channel"
}
}
```
### 7.2 开机广播
```kotlin
// services/BootReceiver.kt
class BootReceiver : BroadcastReceiver() {
override fun onReceive(context: Context, intent: Intent) {
if (intent.action == Intent.ACTION_BOOT_COMPLETED) {
Log.i(TAG, "设备启动，启动Agent服务")
val serviceIntent = Intent(context, AgentService::class.java)
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
context.startForegroundService(serviceIntent)
} else {
context.startService(serviceIntent)
}
}
}
companion object {
private const val TAG = "BootReceiver"
}
}
```
```xml
<!-- AndroidManifest.xml -->
<receiver
android:name=".services.BootReceiver"
android:enabled="true"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
</intent-filter>
</receiver>
```
---
## 八、调试与日志
### 8.1 日志系统
```kotlin
// utils/Logger.kt
object Logger {
private const val TAG = "WorkPhone"
private var logLevel = Log.DEBUG
fun d(message: String) {
if (logLevel <= Log.DEBUG) {
Log.d(TAG, message)
}
}
fun i(message: String) {
if (logLevel <= Log.INFO) {
Log.i(TAG, message)
}
}
fun w(message: String) {
if (logLevel <= Log.WARN) {
Log.w(TAG, message)
}
}
fun e(message: String, throwable: Throwable? = null) {
if (logLevel <= Log.ERROR) {
Log.e(TAG, message, throwable)
}
}
}
```
### 8.2 ADB调试命令
```bash
# 查看Agent日志
adb logcat -s WorkPhone
# 查看WebSocket连接
adb logcat | grep -i websocket
# 查看uiautomator2服务
adb logcat -s UiAutomator
# 启动Agent服务
adb shell am startservice com.workphone.agent/.services.AgentService
# 停止Agent服务
adb shell am stopservice com.workphone.agent/.services.AgentService
```

953
开发文档/6、后端/docs/05-脚本开发指南.md Normal file
View File

@@ -0,0 +1,953 @@
# 05. 脚本开发指南
> 适合读者：自动化开发、脚本工程师、扩展开发者
---
## 一、概述
### 1.1 脚本引擎架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 脚本引擎 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 脚本注册表 │ │
│ │ │ │
│ │ wechat → WeChatScript │ │
│ │ douyin → DouyinScript │ │
│ │ xhs → XhsScript │ │
│ │ soul → SoulScript (新APP) │ │
│ │ ... │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────▼──────────────────────────────┐ │
│ │ 脚本执行器 │ │
│ │ │ │
│ │ 1. 解析请求 → 2. 查找脚本 → 3. 调用方法 → 4. 返回结果 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────▼──────────────────────────────┐ │
│ │ BaseScript │ │
│ │ │ │
│ │ 提供通用能力：launch/close/click/input/screenshot │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 1.2 脚本目录结构
```
server/scripts/
├── __init__.py
├── base.py # 基类 BaseScript
├── registry.py # 脚本注册表
│
├── wechat/ # 微信脚本
│ ├── __init__.py
│ └── script.py
│
├── douyin/ # 抖音脚本
│ ├── __init__.py
│ └── script.py
│
├── xhs/ # 小红书脚本
│ ├── __init__.py
│ └── script.py
│
└── templates/ # 脚本模板
└── new_app.py
```
---
## 二、BaseScript 基类
### 2.1 完整定义
```python
# scripts/base.py
import uiautomator2 as u2
import time
from typing import Any, Dict, Optional
from abc import ABC, abstractmethod
class BaseScript(ABC):
"""
所有APP脚本的基类
子类必须定义：
- PACKAGE: APP包名
- NAME: APP名称
"""
PACKAGE: str = "" # 子类必须覆盖
NAME: str = "" # 子类必须覆盖
def __init__(self, device_id: str):
"""
初始化脚本
Args:
device_id: 设备ID
"""
self.device_id = device_id
self.d = u2.connect(device_id)
self.d.implicitly_wait(10.0) # 默认等待10秒
# ========== 基础操作 ==========
def launch(self, wait_activity: Optional[str] = None) -> bool:
"""
启动APP
Args:
wait_activity: 等待的Activity名称
Returns:
是否启动成功
"""
self.d.app_start(self.PACKAGE)
if wait_activity:
return self.d.wait_activity(wait_activity, timeout=10)
time.sleep(2) # 默认等待2秒
return True
def close(self):
"""关闭APP"""
self.d.app_stop(self.PACKAGE)
def is_running(self) -> bool:
"""检查APP是否在前台"""
current = self.d.app_current()
return current.get('package') == self.PACKAGE
def ensure_foreground(self):
"""确保APP在前台"""
if not self.is_running():
self.launch()
# ========== 屏幕操作 ==========
def screenshot(self) -> bytes:
"""截图"""
return self.d.screenshot(format='raw')
def click(self, x: int, y: int):
"""点击坐标"""
self.d.click(x, y)
def click_text(self, text: str, timeout: float = 10) -> bool:
"""
点击文字
Args:
text: 要点击的文字
timeout: 超时时间
Returns:
是否点击成功
"""
try:
self.d.xpath(f'//*[@text="{text}"]').click(timeout=timeout)
return True
except Exception:
return False
def click_resource_id(self, resource_id: str, timeout: float = 10) -> bool:
"""
点击资源ID
Args:
resource_id: 资源ID（如 com.xxx:id/btn_send）
timeout: 超时时间
"""
try:
self.d(resourceId=resource_id).click(timeout=timeout)
return True
except Exception:
return False
def long_click(self, x: int, y: int, duration: float = 1.0):
"""长按"""
self.d.long_click(x, y, duration=duration)
def swipe(self, direction: str, scale: float = 0.8):
"""
滑动
Args:
direction: up/down/left/right
scale: 滑动距离比例
"""
self.d.swipe_ext(direction, scale=scale)
def swipe_to_find(self, text: str, max_swipes: int = 5) -> bool:
"""
滑动查找文字
Args:
text: 要查找的文字
max_swipes: 最大滑动次数
Returns:
是否找到
"""
for _ in range(max_swipes):
if self.d.xpath(f'//*[@text="{text}"]').exists:
return True
self.swipe('up')
time.sleep(0.5)
return False
# ========== 输入操作 ==========
def input_text(self, text: str, clear: bool = False):
"""
输入文字
Args:
text: 要输入的文字
clear: 是否先清空
"""
if clear:
self.d.clear_text()
self.d.send_keys(text)
def clear_input(self):
"""清空输入框"""
self.d.clear_text()
# ========== 元素查找 ==========
def exists(self, text: str) -> bool:
"""检查文字是否存在"""
return self.d.xpath(f'//*[@text="{text}"]').exists
def wait_text(self, text: str, timeout: float = 10) -> bool:
"""
等待文字出现
Args:
text: 要等待的文字
timeout: 超时时间
Returns:
是否出现
"""
try:
self.d.xpath(f'//*[@text="{text}"]').wait(timeout=timeout)
return True
except Exception:
return False
def wait_gone(self, text: str, timeout: float = 10) -> bool:
"""
等待文字消失
Args:
text: 要等待消失的文字
timeout: 超时时间
"""
try:
self.d.xpath(f'//*[@text="{text}"]').wait_gone(timeout=timeout)
return True
except Exception:
return False
def get_text(self, resource_id: str) -> Optional[str]:
"""
获取元素文字
Args:
resource_id: 资源ID
Returns:
元素文字，不存在返回None
"""
try:
return self.d(resourceId=resource_id).get_text()
except Exception:
return None
def get_ui_tree(self) -> str:
"""获取UI树XML"""
return self.d.dump_hierarchy()
# ========== 辅助方法 ==========
def sleep(self, seconds: float):
"""等待"""
time.sleep(seconds)
def back(self):
"""返回键"""
self.d.press('back')
def home(self):
"""Home键"""
self.d.press('home')
def log(self, message: str):
"""记录日志"""
print(f"[{self.NAME}] {message}")
```
---
## 三、脚本注册表
### 3.1 注册机制
```python
# scripts/registry.py
from typing import Dict, Type, Callable
from .base import BaseScript
# 脚本注册表
SCRIPT_REGISTRY: Dict[str, Type[BaseScript]] = {}
def register_script(name: str):
"""
脚本注册装饰器
Usage:
@register_script('wechat')
class WeChatScript(BaseScript):
...
"""
def decorator(cls: Type[BaseScript]):
if name in SCRIPT_REGISTRY:
raise ValueError(f"脚本名称 '{name}' 已存在")
SCRIPT_REGISTRY[name] = cls
return cls
return decorator
def get_script(name: str) -> Type[BaseScript]:
"""获取脚本类"""
if name not in SCRIPT_REGISTRY:
raise ValueError(f"脚本 '{name}' 不存在")
return SCRIPT_REGISTRY[name]
def list_scripts() -> list:
"""列出所有已注册脚本"""
result = []
for name, cls in SCRIPT_REGISTRY.items():
result.append({
'name': name,
'package': cls.PACKAGE,
'display_name': cls.NAME,
'actions': [m for m in dir(cls) if not m.startswith('_') and callable(getattr(cls, m))]
})
return result
```
### 3.2 脚本执行器
```python
# scripts/executor.py
import asyncio
from typing import Any, Dict
from .registry import get_script
class ScriptExecutor:
"""脚本执行器"""
async def execute(
self,
device_id: str,
script_name: str,
action: str,
params: Dict[str, Any],
timeout: float = 30
) -> Dict[str, Any]:
"""
执行脚本
Args:
device_id: 设备ID
script_name: 脚本名称
action: 动作名称
params: 动作参数
timeout: 超时时间
Returns:
执行结果
"""
# 获取脚本类
script_cls = get_script(script_name)
# 创建脚本实例
script = script_cls(device_id)
# 获取动作方法
if not hasattr(script, action):
raise ValueError(f"脚本 '{script_name}' 没有动作 '{action}'")
method = getattr(script, action)
if not callable(method):
raise ValueError(f"'{action}' 不是可调用的方法")
# 执行动作（带超时）
try:
result = await asyncio.wait_for(
asyncio.to_thread(method, **params),
timeout=timeout
)
return {
'status': 'success',
'result': result
}
except asyncio.TimeoutError:
return {
'status': 'timeout',
'error': f'执行超时（{timeout}秒）'
}
except Exception as e:
return {
'status': 'error',
'error': str(e)
}
# 全局执行器实例
executor = ScriptExecutor()
```
---
## 四、微信脚本示例
### 4.1 完整实现
```python
# scripts/wechat/script.py
from ..base import BaseScript
from ..registry import register_script
from typing import List, Dict, Any, Optional
import time
@register_script('wechat')
class WeChatScript(BaseScript):
"""微信控制脚本"""
PACKAGE = "com.tencent.mm"
NAME = "微信"
# UI元素资源ID（需要根据微信版本调整）
RES_SEARCH = "com.tencent.mm:id/f55"
RES_INPUT = "com.tencent.mm:id/chatting_content_et"
RES_SEND = "com.tencent.mm:id/anv"
def send_message(self, to_wxid: str, content: str, msg_type: str = 'text') -> Dict[str, Any]:
"""
发送消息
Args:
to_wxid: 目标微信ID或备注名
content: 消息内容
msg_type: 消息类型（text/image）
Returns:
发送结果
"""
self.log(f"发送消息到 {to_wxid}: {content[:20]}...")
# 1. 确保微信在前台
self.ensure_foreground()
self.sleep(1)
# 2. 点击搜索
if not self.click_text("搜索"):
# 尝试点击搜索图标
self.click_resource_id(self.RES_SEARCH)
self.sleep(0.5)
# 3. 输入联系人
self.input_text(to_wxid)
self.sleep(1)
# 4. 点击搜索结果
if not self.click_text(to_wxid):
return {'status': 'failed', 'error': '未找到联系人'}
self.sleep(1)
# 5. 输入消息
self.click_resource_id(self.RES_INPUT)
self.input_text(content)
# 6. 发送
if not self.click_resource_id(self.RES_SEND):
self.click_text("发送")
self.log("消息发送成功")
return {'status': 'success'}
def get_messages(self, limit: int = 20) -> Dict[str, Any]:
"""
获取消息列表
Args:
limit: 获取数量
Returns:
消息列表
"""
self.log(f"获取最近 {limit} 条消息")
# 1. 确保在微信首页
self.ensure_foreground()
self.click_text("微信") # 点击微信标签
self.sleep(1)
# 2. 获取UI树分析
ui_tree = self.get_ui_tree()
# 3. 解析消息（这里需要根据实际UI结构解析）
# 简化示例，实际需要解析XML
messages = []
return {
'status': 'success',
'messages': messages,
'count': len(messages)
}
def get_friends(self) -> Dict[str, Any]:
"""获取好友列表"""
self.log("获取好友列表")
# 1. 进入通讯录
self.ensure_foreground()
self.click_text("通讯录")
self.sleep(1)
# 2. 滚动获取好友
friends = []
for i in range(10): # 最多滚动10次
ui_tree = self.get_ui_tree()
# 解析好友列表...
self.swipe('up')
self.sleep(0.5)
return {
'status': 'success',
'friends': friends,
'count': len(friends)
}
def add_friend(self, wxid: str, message: str = "") -> Dict[str, Any]:
"""
添加好友
Args:
wxid: 微信ID
message: 验证消息
"""
self.log(f"添加好友: {wxid}")
# 1. 进入添加好友页面
self.ensure_foreground()
self.click_text("通讯录")
self.sleep(0.5)
self.click_text("新的朋友")
self.sleep(0.5)
# 2. 点击搜索
self.click_text("添加朋友")
self.sleep(0.5)
# 3. 输入微信ID
self.click_text("微信号/手机号")
self.input_text(wxid)
self.sleep(1)
# 4. 搜索
self.click_text("搜索")
self.sleep(2)
# 5. 添加
if self.exists("添加到通讯录"):
self.click_text("添加到通讯录")
self.sleep(0.5)
if message:
self.input_text(message)
self.click_text("发送")
return {'status': 'success'}
else:
return {'status': 'failed', 'error': '用户不存在或不可添加'}
def accept_friend(self, wxid: str) -> Dict[str, Any]:
"""
通过好友请求
Args:
wxid: 请求者微信ID
"""
self.log(f"通过好友请求: {wxid}")
# 1. 进入新的朋友
self.ensure_foreground()
self.click_text("通讯录")
self.sleep(0.5)
self.click_text("新的朋友")
self.sleep(1)
# 2. 查找并通过
if self.swipe_to_find(wxid):
# 点击请求项
self.click_text(wxid)
self.sleep(0.5)
if self.click_text("通过验证"):
return {'status': 'success'}
return {'status': 'failed', 'error': '未找到好友请求'}
```
---
## 五、新APP对接指南
### 5.1 对接流程
```
Step 1: 分析APP
├── 获取UI树：GET /api/devices/{id}/ui-tree
├── 分析界面元素
└── 记录关键元素的定位方式
Step 2: 创建脚本
├── 创建脚本目录：scripts/{app_name}/
├── 继承BaseScript
└── 实现业务方法
Step 3: 注册脚本
├── 使用@register_script装饰器
└── 添加到__init__.py
Step 4: 测试验证
├── 单元测试
└── API测试
```
### 5.2 脚本模板
```python
# scripts/templates/new_app.py
"""
新APP脚本模板
使用方法：
1. 复制此文件到 scripts/{app_name}/script.py
2. 修改 PACKAGE 和 NAME
3. 实现业务方法
4. 注册脚本
"""
from ..base import BaseScript
from ..registry import register_script
from typing import Dict, Any
@register_script('new_app') # 修改为实际脚本名
class NewAppScript(BaseScript):
"""新APP控制脚本"""
# ========== 必须修改 ==========
PACKAGE = "com.example.newapp" # APP包名
NAME = "新APP" # APP名称
# ========== 可选：UI元素定位 ==========
# 根据UI分析结果填写
RES_INPUT = "com.example:id/input"
RES_SEND = "com.example:id/send"
# ========== 业务方法 ==========
def send_message(self, to_id: str, content: str) -> Dict[str, Any]:
"""
发送消息
Args:
to_id: 目标用户ID
content: 消息内容
Returns:
执行结果
"""
self.log(f"发送消息到 {to_id}")
# 1. 确保APP在前台
self.ensure_foreground()
self.sleep(1)
# 2. 进入消息页面（根据实际UI修改）
self.click_text("消息")
self.sleep(0.5)
# 3. 搜索联系人
self.click_text("搜索")
self.input_text(to_id)
self.sleep(1)
# 4. 点击联系人
if not self.click_text(to_id):
return {'status': 'failed', 'error': '未找到联系人'}
self.sleep(0.5)
# 5. 输入消息
self.click_resource_id(self.RES_INPUT)
self.input_text(content)
# 6. 发送
self.click_resource_id(self.RES_SEND)
return {'status': 'success'}
def get_messages(self, limit: int = 20) -> Dict[str, Any]:
"""获取消息列表"""
self.log(f"获取最近 {limit} 条消息")
# 实现获取消息逻辑
messages = []
return {
'status': 'success',
'messages': messages
}
# 根据需要添加更多方法...
```
### 5.3 Soul脚本示例
```python
# scripts/soul/script.py
from ..base import BaseScript
from ..registry import register_script
from typing import Dict, Any
@register_script('soul')
class SoulScript(BaseScript):
"""Soul APP控制脚本"""
PACKAGE = "cn.soulapp.android"
NAME = "Soul"
def send_message(self, to_id: str, content: str) -> Dict[str, Any]:
"""发送私信"""
self.log(f"发送消息到 {to_id}")
self.ensure_foreground()
self.sleep(1)
# 进入消息页
self.click_text("消息")
self.sleep(0.5)
# 搜索联系人
# Soul的搜索可能在不同位置，需要根据实际UI调整
self.click(540, 200) # 假设搜索框位置
self.input_text(to_id)
self.sleep(1)
# 点击联系人进入聊天
self.click_text(to_id)
self.sleep(0.5)
# 输入并发送
self.click(540, 1200) # 假设输入框位置
self.input_text(content)
self.click_text("发送")
return {'status': 'success'}
def match_soul(self) -> Dict[str, Any]:
"""灵魂匹配"""
self.log("开始灵魂匹配")
self.ensure_foreground()
# 进入广场
self.click_text("广场")
self.sleep(1)
# 点击匹配
if self.click_text("灵魂匹配"):
self.sleep(3) # 等待匹配结果
return {'status': 'success'}
return {'status': 'failed', 'error': '未找到匹配入口'}
```
---
## 六、最佳实践
### 6.1 元素定位策略
| 方法 | 优先级 | 说明 |
|------|--------|------|
| `resourceId` | ⭐⭐⭐ | 最稳定，但需要反编译获取 |
| `text` | ⭐⭐ | 简单直观，但多语言可能变化 |
| `className + index` | ⭐⭐ | 布局变化时可能失效 |
| `xpath` | ⭐ | 灵活但慢，最后手段 |
| `坐标` | ⚠️ | 不同分辨率会失效，尽量避免 |
### 6.2 稳定性建议
```python
# 1. 添加重试机制
def click_with_retry(self, text: str, max_retries: int = 3) -> bool:
for i in range(max_retries):
if self.click_text(text, timeout=5):
return True
self.log(f"点击失败，重试 {i+1}/{max_retries}")
self.sleep(1)
return False
# 2. 添加前置检查
def send_message(self, to_id: str, content: str):
# 检查APP是否安装
if not self.is_app_installed():
return {'status': 'failed', 'error': 'APP未安装'}
# 检查是否登录
if not self.is_logged_in():
return {'status': 'failed', 'error': '未登录'}
# 执行发送...
# 3. 添加异常处理
def safe_execute(self, action_func, *args, **kwargs):
try:
return action_func(*args, **kwargs)
except Exception as e:
self.screenshot() # 保存截图用于调试
self.log(f"执行失败: {e}")
return {'status': 'error', 'error': str(e)}
# 4. 使用显式等待而非sleep
def wait_for_element(self, text: str, timeout: float = 10) -> bool:
"""等待元素出现（替代sleep）"""
start = time.time()
while time.time() - start < timeout:
if self.exists(text):
return True
time.sleep(0.5)
return False
```
### 6.3 调试技巧
```python
# 1. 获取当前页面UI树
def debug_dump(self):
"""调试：打印当前UI结构"""
xml = self.get_ui_tree()
with open(f'/tmp/{self.NAME}_{int(time.time())}.xml', 'w') as f:
f.write(xml)
self.log("UI结构已保存")
# 2. 截图保存
def debug_screenshot(self, name: str = ''):
"""调试：保存截图"""
image = self.screenshot()
filename = f'/tmp/{self.NAME}_{name}_{int(time.time())}.jpg'
with open(filename, 'wb') as f:
f.write(image)
self.log(f"截图已保存: {filename}")
# 3. 交互式探索
def explore(self):
"""交互式探索APP"""
self.launch()
while True:
cmd = input("输入命令 (dump/click x,y/text xxx/quit): ")
if cmd == 'quit':
break
elif cmd == 'dump':
self.debug_dump()
elif cmd.startswith('click '):
x, y = map(int, cmd[6:].split(','))
self.click(x, y)
elif cmd.startswith('text '):
self.click_text(cmd[5:])
```
---
## 七、测试
### 7.1 单元测试
```python
# tests/test_wechat.py
import pytest
from scripts.wechat.script import WeChatScript
class TestWeChatScript:
@pytest.fixture
def script(self, mocker):
# Mock uiautomator2
mock_d = mocker.MagicMock()
mocker.patch('uiautomator2.connect', return_value=mock_d)
return WeChatScript('test-device')
def test_launch(self, script):
result = script.launch()
assert result == True
script.d.app_start.assert_called_once_with('com.tencent.mm')
def test_send_message(self, script):
# Mock UI操作
script.d.xpath.return_value.click.return_value = True
script.d.return_value.click.return_value = True
result = script.send_message('test_user', 'Hello')
assert result['status'] == 'success'
```
### 7.2 集成测试
```python
# tests/test_integration.py
import pytest
from scripts.executor import executor
@pytest.mark.integration
class TestScriptExecution:
@pytest.fixture
def device_id(self):
return 'real-device-001' # 真实设备ID
@pytest.mark.asyncio
async def test_wechat_send(self, device_id):
result = await executor.execute(
device_id=device_id,
script_name='wechat',
action='send_message',
params={
'to_wxid': 'test_contact',
'content': '自动化测试消息'
},
timeout=60
)
assert result['status'] == 'success'
```

769
开发文档/6、后端/docs/06-部署运维.md Normal file
View File

@@ -0,0 +1,769 @@
# 06. 部署运维
> 适合读者：运维工程师、DevOps、系统管理员
---
## 一、部署架构
### 1.1 生产环境架构
```
┌─────────────────────────────┐
│ 负载均衡 │
│ (阿里云SLB/腾讯云CLB) │
└──────────────┬──────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ SDK节点1 │ │ SDK节点2 │ │ SDK节点N │
│ │ │ │ │ │
│ FastAPI │ │ FastAPI │ │ FastAPI │
│ WebSocket │ │ WebSocket │ │ WebSocket │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────────┼───────────────────┘
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
┌──────▼──────┐ ┌───────▼───────┐ ┌───────▼───────┐
│ Redis │ │ MongoDB │ │ MinIO │
│ (主从集群) │ │ (副本集) │ │ (分布式) │
└─────────────┘ └───────────────┘ └───────────────┘
```
### 1.2 服务器配置建议
| 规模 | SDK节点 | Redis | MongoDB | MinIO | 总成本/月 |
|------|---------|-------|---------|-------|-----------|
| 小型 (≤50设备) | 1×2C4G | 1×1C2G | 1×2C4G | 1×2C4G | ~500元 |
| 中型 (≤200设备) | 2×4C8G | 1×2C4G | 1×4C8G | 1×4C8G | ~1500元 |
| 大型 (≤1000设备) | 4×8C16G | 集群3节点 | 副本集3节点 | 集群4节点 | ~5000元 |
---
## 二、Docker部署
### 2.1 目录结构
```
workphone-sdk/
├── docker-compose.yml # Docker编排
├── docker-compose.prod.yml # 生产环境覆盖
├── .env # 环境变量
├── .env.example # 环境变量示例
│
├── server/ # SDK服务端
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── main.py
│ └── ...
│
├── nginx/ # Nginx配置
│ ├── nginx.conf
│ └── ssl/
│ ├── cert.pem
│ └── key.pem
│
├── scripts/ # 运维脚本
│ ├── backup.sh
│ ├── restore.sh
│ └── health_check.sh
│
└── data/ # 数据目录（git忽略）
├── mongo/
├── redis/
└── minio/
```
### 2.2 docker-compose.yml
```yaml
# docker-compose.yml
version: '3.8'
services:
# SDK API服务
sdk-server:
build:
context: ./server
dockerfile: Dockerfile
ports:
- "8000:8000"
environment:
- MONGODB_URI=${MONGODB_URI:-mongodb://mongo:27017/workphone}
- REDIS_URI=${REDIS_URI:-redis://redis:6379}
- MINIO_ENDPOINT=${MINIO_ENDPOINT:-minio:9000}
- MINIO_ACCESS_KEY=${MINIO_ACCESS_KEY:-admin}
- MINIO_SECRET_KEY=${MINIO_SECRET_KEY:-password}
- API_KEY_SECRET=${API_KEY_SECRET}
- LOG_LEVEL=${LOG_LEVEL:-INFO}
depends_on:
- mongo
- redis
- minio
restart: always
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/api/health"]
interval: 30s
timeout: 10s
retries: 3
deploy:
resources:
limits:
cpus: '2'
memory: 4G
# WebSocket服务
websocket-hub:
build:
context: ./server
dockerfile: Dockerfile.websocket
ports:
- "8765:8765"
environment:
- REDIS_URI=${REDIS_URI:-redis://redis:6379}
depends_on:
- redis
restart: always
deploy:
resources:
limits:
cpus: '1'
memory: 2G
# Nginx反向代理
nginx:
image: nginx:1.24-alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./nginx/ssl:/etc/nginx/ssl:ro
depends_on:
- sdk-server
- websocket-hub
restart: always
# MongoDB
mongo:
image: mongo:6.0
ports:
- "27017:27017"
environment:
- MONGO_INITDB_ROOT_USERNAME=${MONGO_ROOT_USER:-root}
- MONGO_INITDB_ROOT_PASSWORD=${MONGO_ROOT_PASSWORD}
volumes:
- ./data/mongo:/data/db
restart: always
command: mongod --wiredTigerCacheSizeGB 1
# Redis
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- ./data/redis:/data
restart: always
command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru
# MinIO文件存储
minio:
image: minio/minio:latest
ports:
- "9000:9000"
- "9001:9001"
environment:
- MINIO_ROOT_USER=${MINIO_ACCESS_KEY:-admin}
- MINIO_ROOT_PASSWORD=${MINIO_SECRET_KEY:-password}
volumes:
- ./data/minio:/data
command: server /data --console-address ":9001"
restart: always
volumes:
mongo_data:
redis_data:
minio_data:
```
### 2.3 Dockerfile
```dockerfile
# server/Dockerfile
FROM python:3.11-slim
WORKDIR /app
# 安装系统依赖
RUN apt-get update && apt-get install -y \
curl \
&& rm -rf /var/lib/apt/lists/*
# 安装Python依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# 复制代码
COPY . .
# 暴露端口
EXPOSE 8000
# 启动命令
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]
```
### 2.4 Nginx配置
```nginx
# nginx/nginx.conf
worker_processes auto;
events {
worker_connections 10000;
use epoll;
}
http {
include mime.types;
default_type application/octet-stream;
# 日志格式
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for" '
'rt=$request_time uct="$upstream_connect_time" '
'uht="$upstream_header_time" urt="$upstream_response_time"';
access_log /var/log/nginx/access.log main;
error_log /var/log/nginx/error.log warn;
# 性能优化
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
# Gzip压缩
gzip on;
gzip_types text/plain application/json application/xml;
# 上游服务
upstream sdk_api {
server sdk-server:8000;
keepalive 32;
}
upstream sdk_websocket {
server websocket-hub:8765;
}
# HTTP重定向到HTTPS
server {
listen 80;
server_name workphone.xxx.com;
return 301 https://$host$request_uri;
}
# HTTPS服务
server {
listen 443 ssl http2;
server_name workphone.xxx.com;
# SSL证书
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers on;
# REST API
location /api/ {
proxy_pass http://sdk_api;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 30s;
proxy_read_timeout 60s;
}
# WebSocket
location /ws/ {
proxy_pass http://sdk_websocket;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
# 健康检查
location /health {
access_log off;
return 200 'OK';
add_header Content-Type text/plain;
}
}
}
```
### 2.5 部署命令
```bash
# 1. 准备环境变量
cp .env.example .env
vim .env # 编辑配置
# 2. 创建数据目录
mkdir -p data/{mongo,redis,minio}
# 3. 准备SSL证书
mkdir -p nginx/ssl
# 复制证书到 nginx/ssl/cert.pem 和 nginx/ssl/key.pem
# 4. 构建镜像
docker-compose build
# 5. 启动服务
docker-compose up -d
# 6. 查看日志
docker-compose logs -f
# 7. 检查状态
docker-compose ps
# 8. 测试API
curl https://workphone.xxx.com/api/health
```
---
## 三、环境变量
### 3.1 配置示例
```bash
# .env
# ========== 基础配置 ==========
LOG_LEVEL=INFO
ENVIRONMENT=production
# ========== API密钥 ==========
API_KEY_SECRET=your-super-secret-key-change-me
# ========== MongoDB ==========
MONGODB_URI=mongodb://root:password@mongo:27017/workphone?authSource=admin
MONGO_ROOT_USER=root
MONGO_ROOT_PASSWORD=your-mongo-password
# ========== Redis ==========
REDIS_URI=redis://redis:6379
# ========== MinIO ==========
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=admin
MINIO_SECRET_KEY=your-minio-password
# ========== 域名 ==========
DOMAIN=workphone.xxx.com
```
---
## 四、监控告警
### 4.1 健康检查
```python
# server/api/health.py
from fastapi import APIRouter
from datetime import datetime
import redis
import pymongo
router = APIRouter()
@router.get("/api/health")
async def health_check():
"""健康检查接口"""
checks = {}
# 检查MongoDB
try:
client = pymongo.MongoClient(MONGODB_URI, serverSelectionTimeoutMS=2000)
client.admin.command('ping')
checks['mongodb'] = 'ok'
except Exception as e:
checks['mongodb'] = f'error: {str(e)}'
# 检查Redis
try:
r = redis.from_url(REDIS_URI)
r.ping()
checks['redis'] = 'ok'
except Exception as e:
checks['redis'] = f'error: {str(e)}'
# 总体状态
all_ok = all(v == 'ok' for v in checks.values())
return {
'status': 'healthy' if all_ok else 'unhealthy',
'timestamp': datetime.now().isoformat(),
'checks': checks
}
@router.get("/api/metrics")
async def metrics():
"""监控指标"""
return {
'devices': {
'online': len(device_connections),
'total': await db.devices.count_documents({})
},
'commands': {
'pending': len(pending_commands),
'today': await db.execution_logs.count_documents({
'created_at': {'$gte': today_start}
})
},
'uptime': get_uptime()
}
```
### 4.2 Prometheus指标
```python
# server/metrics.py
from prometheus_client import Counter, Gauge, Histogram, generate_latest
from fastapi import Response
# 定义指标
DEVICES_ONLINE = Gauge('workphone_devices_online', 'Online devices count')
COMMANDS_TOTAL = Counter('workphone_commands_total', 'Total commands', ['script', 'action', 'status'])
COMMAND_DURATION = Histogram('workphone_command_duration_seconds', 'Command duration', ['script', 'action'])
WEBSOCKET_CONNECTIONS = Gauge('workphone_websocket_connections', 'WebSocket connections')
@app.get("/metrics")
async def metrics():
"""Prometheus指标端点"""
return Response(
content=generate_latest(),
media_type="text/plain"
)
```
### 4.3 日志聚合
```yaml
# docker-compose.prod.yml (日志收集扩展)
services:
# Loki日志收集
loki:
image: grafana/loki:2.9.0
ports:
- "3100:3100"
volumes:
- ./loki-config.yaml:/etc/loki/local-config.yaml
command: -config.file=/etc/loki/local-config.yaml
# Promtail日志代理
promtail:
image: grafana/promtail:2.9.0
volumes:
- /var/log:/var/log:ro
- ./promtail-config.yaml:/etc/promtail/config.yaml
command: -config.file=/etc/promtail/config.yaml
# Grafana可视化
grafana:
image: grafana/grafana:10.0.0
ports:
- "3000:3000"
volumes:
- grafana_data:/var/lib/grafana
environment:
- GF_SECURITY_ADMIN_PASSWORD=admin
volumes:
grafana_data:
```
---
## 五、备份恢复
### 5.1 备份脚本
```bash
#!/bin/bash
# scripts/backup.sh
set -e
BACKUP_DIR="/backup/workphone"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_PATH="${BACKUP_DIR}/${DATE}"
mkdir -p ${BACKUP_PATH}
echo "开始备份 ${DATE}"
# 备份MongoDB
echo "备份MongoDB..."
docker exec workphone-mongo mongodump \
--uri="mongodb://root:${MONGO_ROOT_PASSWORD}@localhost:27017" \
--out=/tmp/mongodump
docker cp workphone-mongo:/tmp/mongodump ${BACKUP_PATH}/mongodb
# 备份Redis
echo "备份Redis..."
docker exec workphone-redis redis-cli BGSAVE
sleep 5
docker cp workphone-redis:/data/dump.rdb ${BACKUP_PATH}/redis.rdb
# 备份MinIO
echo "备份MinIO..."
docker cp workphone-minio:/data ${BACKUP_PATH}/minio
# 备份配置
echo "备份配置..."
cp .env ${BACKUP_PATH}/
cp -r nginx ${BACKUP_PATH}/
# 压缩
echo "压缩备份..."
cd ${BACKUP_DIR}
tar -czf ${DATE}.tar.gz ${DATE}
rm -rf ${DATE}
# 清理旧备份（保留7天）
find ${BACKUP_DIR} -name "*.tar.gz" -mtime +7 -delete
echo "备份完成: ${BACKUP_DIR}/${DATE}.tar.gz"
```
### 5.2 恢复脚本
```bash
#!/bin/bash
# scripts/restore.sh
set -e
if [ -z "$1" ]; then
echo "用法: ./restore.sh <backup_file.tar.gz>"
exit 1
fi
BACKUP_FILE=$1
RESTORE_DIR="/tmp/restore_$(date +%s)"
echo "开始恢复..."
# 解压
mkdir -p ${RESTORE_DIR}
tar -xzf ${BACKUP_FILE} -C ${RESTORE_DIR}
BACKUP_PATH=$(ls ${RESTORE_DIR})
# 停止服务
docker-compose stop sdk-server websocket-hub
# 恢复MongoDB
echo "恢复MongoDB..."
docker cp ${RESTORE_DIR}/${BACKUP_PATH}/mongodb workphone-mongo:/tmp/mongodump
docker exec workphone-mongo mongorestore \
--uri="mongodb://root:${MONGO_ROOT_PASSWORD}@localhost:27017" \
--drop /tmp/mongodump
# 恢复Redis
echo "恢复Redis..."
docker-compose stop redis
docker cp ${RESTORE_DIR}/${BACKUP_PATH}/redis.rdb workphone-redis:/data/dump.rdb
docker-compose start redis
# 启动服务
docker-compose start sdk-server websocket-hub
# 清理
rm -rf ${RESTORE_DIR}
echo "恢复完成"
```
### 5.3 定时备份
```bash
# /etc/cron.d/workphone-backup
# 每天凌晨2点备份
0 2 * * * root /opt/workphone-sdk/scripts/backup.sh >> /var/log/workphone-backup.log 2>&1
```
---
## 六、扩容指南
### 6.1 垂直扩容
```bash
# 修改docker-compose.yml中的资源限制
deploy:
resources:
limits:
cpus: '4' # 增加CPU
memory: 8G # 增加内存
```
### 6.2 水平扩容
```yaml
# docker-compose.prod.yml
services:
sdk-server:
deploy:
replicas: 3 # 启动3个实例
```
```bash
# 扩容到5个实例
docker-compose up -d --scale sdk-server=5
```
### 6.3 Redis集群
```yaml
# redis-cluster.yml
services:
redis-master:
image: redis:7-alpine
command: redis-server --appendonly yes
redis-slave-1:
image: redis:7-alpine
command: redis-server --slaveof redis-master 6379
redis-slave-2:
image: redis:7-alpine
command: redis-server --slaveof redis-master 6379
redis-sentinel-1:
image: redis:7-alpine
command: redis-sentinel /etc/redis/sentinel.conf
```
---
## 七、故障排查
### 7.1 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 设备连接不上 | WebSocket端口未开放 | 检查防火墙/安全组 |
| API超时 | 服务过载 | 扩容/优化代码 |
| 数据库连接失败 | 连接数耗尽 | 增加连接池/检查连接泄漏 |
| 内存不足 | 数据积累 | 清理历史数据/扩容 |
### 7.2 排查命令
```bash
# 查看服务状态
docker-compose ps
# 查看服务日志
docker-compose logs -f sdk-server
# 查看资源使用
docker stats
# 进入容器调试
docker exec -it workphone-sdk-server bash
# 查看网络连接
docker exec workphone-sdk-server netstat -nltp
# 查看MongoDB连接
docker exec workphone-mongo mongosh --eval "db.serverStatus().connections"
# 查看Redis状态
docker exec workphone-redis redis-cli INFO
```
### 7.3 性能分析
```bash
# 查看慢查询（MongoDB）
docker exec workphone-mongo mongosh --eval "db.system.profile.find().sort({millis:-1}).limit(10)"
# 查看Redis慢日志
docker exec workphone-redis redis-cli SLOWLOG GET 10
# 分析API性能
curl -w "@curl-format.txt" -o /dev/null -s https://workphone.xxx.com/api/devices
```
---
## 八、安全加固
### 8.1 网络安全
```bash
# 只允许指定IP访问
ufw allow from 存客宝服务器IP to any port 443
# 禁止直接访问内部端口
ufw deny 8000
ufw deny 8765
ufw deny 27017
ufw deny 6379
```
### 8.2 SSL配置检查
```bash
# 检查SSL配置
curl -I https://workphone.xxx.com
# SSL Labs测试
https://www.ssllabs.com/ssltest/analyze.html?d=workphone.xxx.com
```
### 8.3 日志审计
```python
# 记录所有API调用
@app.middleware("http")
async def audit_log(request: Request, call_next):
start = time.time()
response = await call_next(request)
duration = time.time() - start
logger.info(
f"API调用: {request.method} {request.url.path} "
f"IP={request.client.host} "
f"Duration={duration:.3f}s "
f"Status={response.status_code}"
)
return response
```

741
开发文档/6、后端/docs/07-设备端Hook开发指南.md Normal file
View File

@@ -0,0 +1,741 @@
# 07-设备端Hook开发指南
> 更新：2026-02-10 | 设备端Frida集成与Hook通道的完整开发指南
---
## 一、概述
**目标**：在机擎设备端Agent中集成Frida，实现Hook通道，使设备具备：
1. 启动/管理 frida-server 或 Frida Gadget
2. 根据服务端指令 attach 目标APP
3. 加载/执行 Hook 脚本（rpc.exports 调用）
4. 将 Hook 事件实时上报服务端
**与现有Agent的关系**：Hook通道是与u2通道平级的新增通道，二者并行工作。
```
Agent 主循环
│
├── WebSocket连接管理（已有）
├── 能力上报（扩展Hook能力）
├── 心跳管理（已有）
│
├── u2通道（已有）
│ └── SkillExecutor → WechatSkill / DouyinSkill / ...
│
└── Hook通道（新增）
├── FridaManager（生命周期）
├── ScriptLoader（脚本管理）
├── HookExecutor（指令执行）
└── EventReporter（事件上报）
```
---
## 二、环境准备
### 2.1 设备要求
| 要求 | frida-server(Root) | Frida Gadget(免Root) |
|------|:-:|:-:|
| Android版本 | 7.0+ | 7.0+ |
| Root | ✅ 必须（Magisk推荐） | ❌ 不需要 |
| 存储空间 | ≥50MB | ≥50MB |
| 网络 | 连接服务器 | 连接服务器 |
| SELinux | Permissive | Enforcing OK |
### 2.2 Frida安装（Root方案）
```bash
# 1. 下载frida-server（匹配设备架构）
FRIDA_VERSION="16.5.6"
ARCH="arm64" # arm64 / arm / x86_64 / x86
wget https://github.com/frida/frida/releases/download/${FRIDA_VERSION}/frida-server-${FRIDA_VERSION}-android-${ARCH}.xz
xz -d frida-server-*.xz
# 2. 推送到设备
adb push frida-server-* /data/local/tmp/frida-server
adb shell "chmod 755 /data/local/tmp/frida-server"
# 3. 启动（Root权限）
adb shell "su -c '/data/local/tmp/frida-server -l 0.0.0.0:27042 &'"
# 4. 验证
adb shell "su -c '/data/local/tmp/frida-server --version'"
# 输出: 16.5.6
# 5. 安全：改名防检测
adb shell "su -c 'cp /data/local/tmp/frida-server /data/local/tmp/wp-agent'"
adb shell "su -c '/data/local/tmp/wp-agent -l 0.0.0.0:27042 &'"
```
### 2.3 Frida Gadget方案（免Root）
```bash
# 1. 下载Gadget
wget https://github.com/frida/frida/releases/download/${FRIDA_VERSION}/frida-gadget-${FRIDA_VERSION}-android-${ARCH}.so.xz
xz -d frida-gadget-*.so.xz
# 2. 重打包目标APK（以微信为例）
# 使用 apktool / objection 注入
objection patchapk -s com.tencent.mm.apk -a arm64 --gadget-version ${FRIDA_VERSION}
# 3. 安装重打包的APK
adb install com.tencent.mm.objection.apk
# 4. 启动APP后自动加载Gadget
# Gadget会在APP启动时自动初始化
```
---
## 三、Agent端代码结构
### 3.1 目录结构
```
sdk/agent/
├── agent.py # 主Agent（已有，需扩展）
├── skill_executor.py # u2技能执行器（已有）
├── error_handler.py # 错误处理（已有）
├── hook/ # Hook通道（新增，整个目录）
│ ├── __init__.py
│ ├── frida_manager.py # Frida生命周期管理
│ ├── script_loader.py # 脚本下载/缓存/版本
│ ├── hook_executor.py # Hook指令执行
│ ├── event_reporter.py # 事件上报
│ ├── config.py # Hook配置
│ └── scripts/ # 内置Hook脚本
│ ├── wechat_hook.js # 微信Hook
│ ├── douyin_hook.js # 抖音Hook
│ └── common.js # 公共工具函数
└── skills/ # u2技能（已有）
```
### 3.2 Hook配置
```python
# sdk/agent/hook/config.py
from pydantic import BaseModel
from typing import Optional
class HookConfig(BaseModel):
enabled: bool = False
framework: str = "frida-server" # "frida-server" | "frida-gadget"
frida_server_path: str = "/data/local/tmp/wp-agent"
frida_server_port: int = 27042
auto_start: bool = True
scripts_dir: str = "/sdcard/workphone/scripts"
scripts_cache_dir: str = "/data/local/tmp/wp-scripts"
default_scopes: list[str] = ["com.tencent.mm"]
reconnect_interval: int = 5 # Frida断连重连间隔(秒)
max_reconnect_attempts: int = 10
script_load_timeout: int = 30 # 脚本加载超时(秒)
rpc_call_timeout: int = 10 # RPC调用超时(秒)
```
### 3.3 FridaManager 完整实现
```python
# sdk/agent/hook/frida_manager.py
import frida
import asyncio
import logging
import subprocess
from typing import Optional, Dict, Callable
logger = logging.getLogger("hook.frida_manager")
class FridaManager:
"""Frida 生命周期管理器"""
def __init__(self, config: HookConfig, on_event: Callable):
self.config = config
self.on_event = on_event
self.device: Optional[frida.core.Device] = None
self.sessions: Dict[str, frida.core.Session] = {}
self.scripts: Dict[str, frida.core.Script] = {}
self._running = False
async def start(self):
"""启动Frida连接"""
if self.config.framework == "frida-server":
await self._ensure_frida_server()
try:
self.device = frida.get_usb_device(timeout=10)
self._running = True
logger.info(f"Frida连接成功: {self.device.name}")
except Exception as e:
logger.error(f"Frida连接失败: {e}")
raise
async def stop(self):
"""停止所有Hook"""
self._running = False
for script_id, script in self.scripts.items():
try:
script.unload()
except:
pass
for pkg, session in self.sessions.items():
try:
session.detach()
except:
pass
self.scripts.clear()
self.sessions.clear()
logger.info("Frida已停止")
async def _ensure_frida_server(self):
"""确保frida-server正在运行"""
result = subprocess.run(
["adb", "shell", "su", "-c",
f"ls {self.config.frida_server_path}"],
capture_output=True, text=True
)
if result.returncode != 0:
raise FileNotFoundError(
f"frida-server不存在: {self.config.frida_server_path}")
# 检查是否已运行
result = subprocess.run(
["adb", "shell", "su", "-c", "pidof wp-agent"],
capture_output=True, text=True
)
if not result.stdout.strip():
# 启动frida-server
subprocess.Popen(
["adb", "shell", "su", "-c",
f"{self.config.frida_server_path} "
f"-l 0.0.0.0:{self.config.frida_server_port} &"],
)
await asyncio.sleep(2)
logger.info("frida-server已启动")
async def attach(self, package: str) -> frida.core.Session:
"""attach到目标进程"""
if package in self.sessions:
return self.sessions[package]
try:
pid = self.device.get_process(package).pid
session = self.device.attach(pid)
session.on('detached',
lambda reason: self._on_detached(package, reason))
self.sessions[package] = session
logger.info(f"已attach: {package} (PID={pid})")
return session
except frida.ProcessNotFoundError:
logger.error(f"进程未运行: {package}")
raise
async def load_script(self, package: str, script_id: str,
script_code: str) -> frida.core.Script:
"""加载Hook脚本"""
session = await self.attach(package)
script = session.create_script(script_code)
script.on('message',
lambda msg, data: self._on_message(script_id, msg, data))
script.load()
self.scripts[script_id] = script
logger.info(f"脚本已加载: {script_id} -> {package}")
return script
async def call_rpc(self, script_id: str, method: str,
*args) -> any:
"""调用脚本RPC方法"""
if script_id not in self.scripts:
raise KeyError(f"脚本未加载: {script_id}")
script = self.scripts[script_id]
func = getattr(script.exports_sync, method)
result = await asyncio.wait_for(
asyncio.get_event_loop().run_in_executor(
None, func, *args
),
timeout=self.config.rpc_call_timeout
)
return result
async def unload_script(self, script_id: str):
"""卸载脚本"""
if script_id in self.scripts:
self.scripts[script_id].unload()
del self.scripts[script_id]
logger.info(f"脚本已卸载: {script_id}")
def _on_message(self, script_id: str, message: dict, data):
"""脚本消息回调"""
if message['type'] == 'send':
payload = message['payload']
payload['_script_id'] = script_id
self.on_event(payload)
elif message['type'] == 'error':
logger.error(f"脚本错误 [{script_id}]: {message}")
def _on_detached(self, package: str, reason: str):
"""进程detach回调"""
logger.warning(f"进程detached: {package}, 原因: {reason}")
if package in self.sessions:
del self.sessions[package]
if reason == 'process-terminated' and self._running:
asyncio.create_task(self._try_reattach(package))
async def _try_reattach(self, package: str):
"""尝试重新attach"""
for i in range(self.config.max_reconnect_attempts):
await asyncio.sleep(self.config.reconnect_interval)
try:
await self.attach(package)
# 重新加载之前的脚本
for sid, script in list(self.scripts.items()):
if not script.is_destroyed:
continue
# 需要ScriptLoader协助重新加载
logger.info(f"重新attach成功: {package}")
return
except Exception as e:
logger.warning(f"重新attach失败 ({i+1}): {e}")
logger.error(f"重新attach放弃: {package}")
def get_status(self) -> dict:
"""获取Frida状态"""
return {
"running": self._running,
"device": self.device.name if self.device else None,
"sessions": {
pkg: {"pid": s.pid if hasattr(s, 'pid') else None}
for pkg, s in self.sessions.items()
},
"scripts": list(self.scripts.keys()),
"framework": self.config.framework
}
```
### 3.4 ScriptLoader 实现
```python
# sdk/agent/hook/script_loader.py
import os
import hashlib
import aiohttp
import logging
from typing import Optional
logger = logging.getLogger("hook.script_loader")
class ScriptLoader:
"""Hook脚本管理器：下载、缓存、版本管理"""
def __init__(self, config: HookConfig, server_url: str):
self.config = config
self.server_url = server_url
self.cache: dict[str, str] = {} # {script_id: code}
self.versions: dict[str, str] = {} # {script_id: version}
async def get_script(self, script_id: str) -> str:
"""获取脚本代码（优先缓存）"""
# 本地缓存
if script_id in self.cache:
return self.cache[script_id]
# 本地文件
local_path = os.path.join(
self.config.scripts_cache_dir, f"{script_id}.js")
if os.path.exists(local_path):
with open(local_path, 'r') as f:
code = f.read()
self.cache[script_id] = code
return code
# 内置脚本
builtin_path = os.path.join(
os.path.dirname(__file__), 'scripts', f"{script_id}.js")
if os.path.exists(builtin_path):
with open(builtin_path, 'r') as f:
code = f.read()
self.cache[script_id] = code
return code
# 从服务端下载
return await self.download_script(script_id)
async def download_script(self, script_id: str) -> str:
"""从服务端下载脚本"""
url = f"{self.server_url}/api/v3/scripts/{script_id}"
async with aiohttp.ClientSession() as session:
async with session.get(url) as resp:
if resp.status != 200:
raise FileNotFoundError(
f"脚本下载失败: {script_id}, status={resp.status}")
data = await resp.json()
code = data['data']['content']
# 校验Hash
expected_hash = data['data'].get('hash', '')
if expected_hash:
actual_hash = hashlib.sha256(
code.encode()).hexdigest()
if actual_hash != expected_hash.replace('sha256:', ''):
raise ValueError(f"脚本Hash不匹配: {script_id}")
# 缓存到本地
self._save_cache(script_id, code)
return code
async def check_updates(self) -> list[str]:
"""检查脚本更新"""
url = f"{self.server_url}/api/v3/scripts?check_update=true"
async with aiohttp.ClientSession() as session:
async with session.get(url) as resp:
data = await resp.json()
updates = []
for script in data['data']['scripts']:
sid = script['script_id']
ver = script['version']
if self.versions.get(sid) != ver:
updates.append(sid)
return updates
def _save_cache(self, script_id: str, code: str):
"""保存到本地缓存"""
os.makedirs(self.config.scripts_cache_dir, exist_ok=True)
path = os.path.join(
self.config.scripts_cache_dir, f"{script_id}.js")
with open(path, 'w') as f:
f.write(code)
self.cache[script_id] = code
logger.info(f"脚本已缓存: {script_id}")
```
### 3.5 HookExecutor 实现
```python
# sdk/agent/hook/hook_executor.py
import logging
from typing import Optional
logger = logging.getLogger("hook.executor")
class HookExecutor:
"""Hook指令执行器"""
def __init__(self, frida_manager, script_loader):
self.frida = frida_manager
self.scripts = script_loader
async def execute(self, task: dict) -> dict:
"""
执行Hook指令
task格式:
{
"platform": "wechat",
"action": "send_message",
"params": {"to_id": "wxid_xxx", "content": "hello"},
"hook_config": {
"script_id": "wechat_hook_v1",
"method": "send_message",
"timeout": 10
}
}
"""
hook_config = task.get('hook_config', {})
script_id = hook_config.get('script_id',
self._default_script(task['platform']))
method = hook_config.get('method', task['action'])
params = task.get('params', {})
# 确保脚本已加载
await self._ensure_script_loaded(script_id, task['platform'])
try:
result = await self.frida.call_rpc(
script_id, method, params)
return {
"success": True,
"channel": "hook",
"data": result
}
except Exception as e:
logger.error(f"Hook执行失败: {e}")
return {
"success": False,
"channel": "hook",
"error": str(e),
"fallback": "u2"
}
async def _ensure_script_loaded(self, script_id: str,
platform: str):
"""确保脚本已加载到目标进程"""
if script_id in self.frida.scripts:
return
package = self._platform_to_package(platform)
code = await self.scripts.get_script(script_id)
await self.frida.load_script(package, script_id, code)
def _default_script(self, platform: str) -> str:
"""平台默认脚本ID"""
mapping = {
"wechat": "wechat_hook",
"douyin": "douyin_hook",
"xhs": "xhs_hook",
"xianyu": "xianyu_hook",
}
return mapping.get(platform, f"{platform}_hook")
def _platform_to_package(self, platform: str) -> str:
"""平台到包名映射"""
mapping = {
"wechat": "com.tencent.mm",
"douyin": "com.ss.android.ugc.aweme",
"xhs": "com.xingin.xhs",
"xianyu": "com.taobao.idlefish",
"soul": "cn.soulapp.android",
}
return mapping.get(platform, platform)
```
### 3.6 EventReporter 实现
```python
# sdk/agent/hook/event_reporter.py
import json
import asyncio
import logging
from datetime import datetime
from collections import deque
logger = logging.getLogger("hook.event_reporter")
class EventReporter:
"""Hook事件上报器"""
def __init__(self, ws_client, device_id: str):
self.ws = ws_client
self.device_id = device_id
self.queue = deque(maxlen=1000)
self._running = False
async def start(self):
"""启动事件上报循环"""
self._running = True
asyncio.create_task(self._flush_loop())
async def stop(self):
self._running = False
def report(self, payload: dict):
"""接收Frida脚本上报的事件"""
event = {
"type": "hook_event",
"data": {
"device_id": self.device_id,
"event_type": payload.get('type', 'unknown'),
"source": payload.get('_script_id', ''),
"timestamp": datetime.utcnow().isoformat(),
"payload": {
k: v for k, v in payload.items()
if not k.startswith('_')
}
}
}
self.queue.append(event)
async def _flush_loop(self):
"""批量上报循环"""
while self._running:
if self.queue:
batch = []
while self.queue and len(batch) < 50:
batch.append(self.queue.popleft())
for event in batch:
try:
await self.ws.send(json.dumps(event))
except Exception as e:
logger.error(f"事件上报失败: {e}")
self.queue.appendleft(event)
break
await asyncio.sleep(0.1)
```
### 3.7 Agent主文件扩展
```python
# sdk/agent/agent.py 中需要扩展的部分
class WorkPhoneAgent:
def __init__(self, config):
self.config = config
# 已有
self.skill_executor = SkillExecutor(...)
# 新增Hook通道
self.hook_config = HookConfig(**config.get('hook', {}))
if self.hook_config.enabled:
self.event_reporter = EventReporter(self.ws, config['device_id'])
self.frida_manager = FridaManager(
self.hook_config,
on_event=self.event_reporter.report
)
self.script_loader = ScriptLoader(
self.hook_config, config['server_url']
)
self.hook_executor = HookExecutor(
self.frida_manager, self.script_loader
)
async def _handle_execute(self, data: dict):
"""处理execute指令（扩展通道选择）"""
channel = data.get('channel', 'sdk_control')
if channel == 'hook' and self.hook_config.enabled:
result = await self.hook_executor.execute(data)
# Hook失败且需要降级
if not result['success'] and result.get('fallback') == 'u2':
logger.warning("Hook执行失败，降级到u2")
result = await self.skill_executor.execute(data)
result['channel'] = 'u2_fallback'
else:
result = await self.skill_executor.execute(data)
# 返回结果
await self.ws.send(json.dumps({
"type": "response",
"data": {
"task_id": data['task_id'],
"channel_used": result.get('channel', channel),
**result
}
}))
def _get_capabilities(self) -> dict:
"""能力上报（扩展Hook能力）"""
caps = {
"skill_wechat": True,
"skill_douyin": True,
"skill_xhs": True,
"skill_xianyu": True,
}
if self.hook_config.enabled:
caps.update({
"supports_hook": True,
"hook_scopes": self.hook_config.default_scopes,
"frida_version": frida.__version__,
"hook_framework": self.hook_config.framework,
"loaded_modules": list(
self.frida_manager.scripts.keys()) if hasattr(
self, 'frida_manager') else [],
})
return caps
```
---
## 四、开发任务清单
| 序号 | 任务 | 文件 | 预估 | 优先级 | 依赖 |
|:----:|------|------|:----:|:------:|:----:|
| H1 | 创建hook/目录结构 | sdk/agent/hook/ | 0.5h | P0 | - |
| H2 | HookConfig配置 | hook/config.py | 0.5h | P0 | - |
| H3 | FridaManager核心 | hook/frida_manager.py | 4h | P0 | H1,H2 |
| H4 | ScriptLoader | hook/script_loader.py | 3h | P0 | H1 |
| H5 | HookExecutor | hook/hook_executor.py | 2h | P0 | H3,H4 |
| H6 | EventReporter | hook/event_reporter.py | 2h | P0 | H1 |
| H7 | Agent扩展（通道选择） | agent.py | 2h | P0 | H3-H6 |
| H8 | 能力上报扩展 | agent.py | 1h | P0 | H7 |
| H9 | 微信Hook脚本 | hook/scripts/wechat_hook.js | 8h | P1 | H3 |
| H10 | frida-server安装脚本 | scripts/install_frida.sh | 2h | P0 | - |
| H11 | 单元测试 | tests/test_hook*.py | 4h | P1 | H3-H7 |
| H12 | 集成测试 | tests/test_hook_e2e.py | 4h | P2 | H9 |
| | **合计** | | **~33h** | | |
---
## 五、测试方法
### 5.1 Frida连接测试
```bash
# 1. 确认frida-server运行
adb shell "su -c 'pidof wp-agent'"
# 2. Python测试连接
python3 -c "
import frida
device = frida.get_usb_device()
print(f'设备: {device.name}')
for proc in device.enumerate_processes()[:5]:
print(f' {proc.pid}: {proc.name}')
"
# 3. 测试attach微信
python3 -c "
import frida
device = frida.get_usb_device()
session = device.attach('com.tencent.mm')
print(f'已attach微信, PID={session.pid}')
session.detach()
"
```
### 5.2 脚本加载测试
```python
# tests/test_hook_basic.py
import frida
device = frida.get_usb_device()
session = device.attach("com.tencent.mm")
script = session.create_script("""
rpc.exports = {
ping: function() {
return "pong from wechat process";
},
getProcessInfo: function() {
return {
pid: Process.id,
arch: Process.arch,
platform: Process.platform,
modules: Process.enumerateModules().length
};
}
};
""")
script.load()
print(script.exports_sync.ping())
print(script.exports_sync.get_process_info())
script.unload()
session.detach()
```
---
## 六、常见问题
| 问题 | 原因 | 解决 |
|------|------|------|
| frida.ServerNotRunningError | frida-server未启动 | `adb shell "su -c '/data/local/tmp/wp-agent &'"` |
| frida.ProcessNotFoundError | 目标APP未运行 | 先启动APP再attach |
| frida.PermissionDeniedError | 无Root权限 | 确认Magisk已授权 |
| Script destroyed | 目标进程被杀 | EventReporter标记+重新attach |
| RPC调用超时 | 脚本方法阻塞 | 增加timeout或异步调用 |
| Frida被微信检测 | 进程名/端口特征 | 改名+改端口 |

689
开发文档/6、后端/docs/08-微信Hook脚本开发.md Normal file
View File

@@ -0,0 +1,689 @@
# 08-微信Hook脚本开发
> 更新：2026-02-10 | 微信Frida Hook脚本的完整开发指南
> 参考：VivWxjz Syscall拦截思路 + Frida Java/Native Hook
---
## 一、概述
**目标**：用 Frida 脚本实现与 VivWxjz 等效的微信控制能力。
**实现方式对比**：
| 方式 | 说明 | 难度 | 稳定性 | 推荐 |
|------|------|:----:|:------:|:----:|
| Java层Hook | Hook微信Java方法 | ⭐⭐ | ⚠️ 版本敏感 | 首选 |
| Native层Hook | Hook so库函数 | ⭐⭐⭐ | ✅ 较稳定 | 进阶 |
| Syscall拦截 | Hook系统调用 | ⭐⭐⭐⭐ | ✅ 版本无关 | 参考VivWxjz |
| DB读取 | 读EnMicroMsg.db | ⭐ | ✅ 稳定 | 辅助 |
---
## 二、脚本结构
### 2.1 标准模板
```javascript
// wechat_hook.js — 微信Hook主脚本
'use strict';
// ========== 配置 ==========
const CONFIG = {
WECHAT_PACKAGE: 'com.tencent.mm',
DB_PATH: '/data/user/0/com.tencent.mm/MicroMsg',
LOG_LEVEL: 'info', // debug | info | warn | error
};
// ========== 工具函数 ==========
function log(level, tag, msg) {
if (['debug', 'info', 'warn', 'error'].indexOf(level) >=
['debug', 'info', 'warn', 'error'].indexOf(CONFIG.LOG_LEVEL)) {
send({ type: 'log', level: level, tag: tag, message: msg });
}
}
function jstring(str) {
return Java.use('java.lang.String').$new(str);
}
// ========== RPC接口（暴露给主机调用） ==========
rpc.exports = {
// 发送文本消息
sendMessage: function(params) {
return new Promise(function(resolve, reject) {
Java.perform(function() {
try {
var result = sendTextMessage(params.to_id, params.content);
resolve({ success: true, data: result });
} catch(e) {
reject({ success: false, error: e.message });
}
});
});
},
// 获取联系人列表
getContacts: function(params) {
return new Promise(function(resolve, reject) {
Java.perform(function() {
try {
var contacts = getContactList(params.limit || 100);
resolve({ success: true, data: contacts });
} catch(e) {
reject({ success: false, error: e.message });
}
});
});
},
// 获取最近消息
getMessages: function(params) {
return new Promise(function(resolve, reject) {
Java.perform(function() {
try {
var messages = getRecentMessages(
params.contact_id, params.limit || 20);
resolve({ success: true, data: messages });
} catch(e) {
reject({ success: false, error: e.message });
}
});
});
},
// 添加好友
addFriend: function(params) {
return new Promise(function(resolve, reject) {
Java.perform(function() {
try {
var result = addFriendByWxId(
params.wxid, params.message || '');
resolve({ success: true, data: result });
} catch(e) {
reject({ success: false, error: e.message });
}
});
});
},
// 发朋友圈
postMoment: function(params) {
return new Promise(function(resolve, reject) {
Java.perform(function() {
try {
var result = postTimelineMoment(
params.content, params.images || []);
resolve({ success: true, data: result });
} catch(e) {
reject({ success: false, error: e.message });
}
});
});
},
// Ping测试
ping: function() {
return "pong from wechat hook";
},
// 获取进程信息
getProcessInfo: function() {
return {
pid: Process.id,
arch: Process.arch,
modules: Process.enumerateModules().length,
wechat_version: getWechatVersion()
};
}
};
// ========== 实时消息监听（自动上报） ==========
Java.perform(function() {
hookMessageReceiver();
hookFriendRequest();
log('info', 'init', '微信Hook脚本已加载');
});
```
### 2.2 RPC方法完整清单
| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `sendMessage` | `{to_id, content}` | `{success, msg_id}` | 发文本消息 |
| `sendImage` | `{to_id, image_path}` | `{success, msg_id}` | 发图片 |
| `sendFile` | `{to_id, file_path}` | `{success, msg_id}` | 发文件 |
| `getContacts` | `{limit}` | `[{wxid, nickname, ...}]` | 联系人列表 |
| `getMessages` | `{contact_id, limit}` | `[{from, content, ...}]` | 消息记录 |
| `addFriend` | `{wxid, message}` | `{success}` | 添加好友 |
| `acceptFriend` | `{encryptusername}` | `{success}` | 通过好友 |
| `postMoment` | `{content, images}` | `{success, snsid}` | 发朋友圈 |
| `getMoments` | `{limit}` | `[{snsid, content, ...}]` | 朋友圈列表 |
| `likeMoment` | `{snsid}` | `{success}` | 点赞 |
| `getGroupMembers` | `{chatroom_id}` | `[{wxid, nickname}]` | 群成员 |
| `createGroup` | `{wxids, name}` | `{chatroom_id}` | 建群 |
| `ping` | 无 | `"pong"` | 连通测试 |
| `getProcessInfo` | 无 | `{pid, arch, version}` | 进程信息 |
---
## 三、Java层Hook实现
### 3.1 发送消息
```javascript
function sendTextMessage(toUser, content) {
var result = null;
Java.perform(function() {
// 微信发消息的关键类（需根据版本调整类名）
// 思路：找到消息发送的Manager/Service类
// 方式1：Hook消息发送入口
Java.choose('com.tencent.mm.modelmulti.g', {
onMatch: function(instance) {
// 调用发消息方法
log('info', 'send', '找到消息管理器实例');
},
onComplete: function() {}
});
// 方式2：通过ContentProvider/Intent
var Intent = Java.use('android.content.Intent');
var ComponentName = Java.use('android.content.ComponentName');
// 方式3：通过微信内部SDK
// 需要逆向找到具体的发送类和方法名
// 以下为示例框架：
try {
// 查找消息发送相关类
var classes = [
'com.tencent.mm.plugin.messenger.foundation.a.l',
'com.tencent.mm.modelmulti.g',
'com.tencent.mm.sdk.platformtools.MMLog'
];
for (var i = 0; i < classes.length; i++) {
try {
var cls = Java.use(classes[i]);
log('debug', 'send', '找到类: ' + classes[i]);
} catch(e) {
// 类不存在，继续尝试
}
}
result = { msg_id: Date.now().toString(), status: 'sent' };
} catch(e) {
log('error', 'send', '发消息失败: ' + e.message);
throw e;
}
});
return result;
}
```
### 3.2 消息接收监听
```javascript
function hookMessageReceiver() {
// Hook消息入库方法
// 当新消息被插入数据库时触发
try {
// 微信消息存储相关类（需逆向确认）
var SQLiteDatabase = Java.use('android.database.sqlite.SQLiteDatabase');
// Hook insert方法，监控消息表写入
SQLiteDatabase.insert.overload(
'java.lang.String',
'java.lang.String',
'android.content.ContentValues'
).implementation = function(table, nullColumnHack, values) {
var result = this.insert(table, nullColumnHack, values);
// 过滤消息表
if (table === 'message' || table === 'rconversation') {
try {
var msgContent = values.getAsString(jstring('content'));
var talker = values.getAsString(jstring('talker'));
var type = values.getAsInteger(jstring('type'));
if (msgContent && talker) {
send({
type: 'message_received',
from_id: talker ? talker.toString() : '',
content: msgContent ? msgContent.toString() : '',
msg_type: type ? type.intValue() : 0,
timestamp: Date.now()
});
}
} catch(e) {
// 非消息表，忽略
}
}
return result;
};
log('info', 'receiver', '消息接收Hook已启用');
} catch(e) {
log('error', 'receiver', '消息接收Hook失败: ' + e.message);
// 备选方案：Hook ContentResolver
hookContentResolver();
}
}
function hookContentResolver() {
var ContentResolver = Java.use('android.content.ContentResolver');
ContentResolver.insert.overload(
'android.net.Uri',
'android.content.ContentValues'
).implementation = function(uri, values) {
var result = this.insert(uri, values);
var uriStr = uri.toString();
if (uriStr.indexOf('message') !== -1) {
log('debug', 'cr', '检测到消息写入: ' + uriStr);
}
return result;
};
}
```
### 3.3 联系人获取
```javascript
function getContactList(limit) {
var contacts = [];
Java.perform(function() {
try {
// 方式1：通过数据库查询
var SQLiteDatabase = Java.use('android.database.sqlite.SQLiteDatabase');
// 找到微信的数据库实例
Java.choose('android.database.sqlite.SQLiteDatabase', {
onMatch: function(db) {
try {
var path = db.getPath();
if (path && path.toString().indexOf('MicroMsg') !== -1
&& path.toString().indexOf('EnMicroMsg') !== -1) {
var cursor = db.rawQuery(
'SELECT username, nickname, conRemark, type ' +
'FROM rcontact WHERE type != 0 AND type != 4 ' +
'LIMIT ?',
[limit.toString()]
);
while (cursor.moveToNext()) {
contacts.push({
wxid: cursor.getString(0),
nickname: cursor.getString(1),
remark: cursor.getString(2),
type: cursor.getInt(3)
});
}
cursor.close();
log('info', 'contacts',
'获取联系人: ' + contacts.length + '个');
}
} catch(e) {
// 不是目标数据库
}
},
onComplete: function() {}
});
} catch(e) {
log('error', 'contacts', '获取联系人失败: ' + e.message);
throw e;
}
});
return contacts;
}
```
### 3.4 好友请求监听
```javascript
function hookFriendRequest() {
try {
// Hook好友请求通知
// 需要逆向找到好友请求处理类
// 备选：监控数据库fmessage_conversation表
var SQLiteDatabase = Java.use('android.database.sqlite.SQLiteDatabase');
SQLiteDatabase.insert.overload(
'java.lang.String',
'java.lang.String',
'android.content.ContentValues'
).implementation = function(table, nullColumnHack, values) {
var result = this.insert(table, nullColumnHack, values);
if (table === 'fmessage_conversation') {
try {
var encryptUser = values.getAsString(
jstring('encryptusername'));
var nickname = values.getAsString(jstring('nickname'));
var message = values.getAsString(jstring('message'));
send({
type: 'friend_request',
encrypt_username: encryptUser ?
encryptUser.toString() : '',
nickname: nickname ? nickname.toString() : '',
message: message ? message.toString() : '',
timestamp: Date.now()
});
} catch(e) {}
}
return result;
};
log('info', 'friend', '好友请求Hook已启用');
} catch(e) {
log('warn', 'friend', '好友请求Hook失败: ' + e.message);
}
}
```
---
## 四、Native层Hook（Syscall拦截）
### 4.1 参考VivWxjz的思路
VivWxjz 在 Syscall 层拦截，对微信版本依赖极小：
```javascript
// syscall_hook.js — Syscall级别拦截（参考VivWxjz）
// 拦截sendmsg系统调用
Interceptor.attach(Module.findExportByName('libc.so', 'sendmsg'), {
onEnter: function(args) {
var fd = args[0].toInt32();
var msg = args[1];
// 读取msghdr结构
var msg_name = msg.readPointer();
var msg_namelen = msg.add(Process.pointerSize).readU32();
var msg_iov = msg.add(Process.pointerSize * 2).readPointer();
var msg_iovlen = msg.add(Process.pointerSize * 3).readU32();
if (msg_iovlen > 0) {
var iov_base = msg_iov.readPointer();
var iov_len = msg_iov.add(Process.pointerSize).readU64();
if (iov_len > 0 && iov_len < 65536) {
try {
var data = iov_base.readByteArray(
Math.min(iov_len, 4096));
// 解析微信协议数据
this.send_data = data;
this.fd = fd;
} catch(e) {}
}
}
},
onLeave: function(retval) {
if (this.send_data) {
send({
type: 'network_send',
fd: this.fd,
data_size: this.send_data.byteLength,
timestamp: Date.now()
}, this.send_data);
}
}
});
// 拦截recvmsg系统调用
Interceptor.attach(Module.findExportByName('libc.so', 'recvmsg'), {
onEnter: function(args) {
this.fd = args[0].toInt32();
this.msg = args[1];
},
onLeave: function(retval) {
var bytesReceived = retval.toInt32();
if (bytesReceived > 0 && this.msg) {
try {
var msg_iov = this.msg.add(Process.pointerSize * 2)
.readPointer();
var iov_base = msg_iov.readPointer();
var data = iov_base.readByteArray(
Math.min(bytesReceived, 4096));
send({
type: 'network_recv',
fd: this.fd,
data_size: bytesReceived,
timestamp: Date.now()
}, data);
} catch(e) {}
}
}
});
```
### 4.2 SSL Bypass（配合Hook使用）
```javascript
// ssl_bypass.js — 绕过SSL Pinning（已在现有docs中）
Java.perform(function() {
// 方式1: TrustManager绕过
var TrustManagerImpl = Java.use(
'com.android.org.conscrypt.TrustManagerImpl');
TrustManagerImpl.verifyChain.implementation = function() {
return arguments[0];
};
// 方式2: OkHttp CertificatePinner
try {
var CertPinner = Java.use('okhttp3.CertificatePinner');
CertPinner.check.overload('java.lang.String', 'java.util.List')
.implementation = function() {};
} catch(e) {}
// 方式3: WebViewClient
try {
var WebViewClient = Java.use('android.webkit.WebViewClient');
WebViewClient.onReceivedSslError.implementation = function(
view, handler, error) {
handler.proceed();
};
} catch(e) {}
});
```
---
## 五、工具函数库
```javascript
// common.js — 公共工具函数
function getWechatVersion() {
try {
var context = Java.use('android.app.ActivityThread')
.currentApplication().getApplicationContext();
var pm = context.getPackageManager();
var info = pm.getPackageInfo('com.tencent.mm', 0);
return info.versionName.value;
} catch(e) {
return 'unknown';
}
}
function findWechatDB() {
var dbPath = null;
Java.choose('android.database.sqlite.SQLiteDatabase', {
onMatch: function(db) {
var path = db.getPath();
if (path && path.toString().indexOf('EnMicroMsg') !== -1) {
dbPath = path.toString();
}
},
onComplete: function() {}
});
return dbPath;
}
function enumClasses(keyword) {
var matches = [];
Java.enumerateLoadedClasses({
onMatch: function(name) {
if (name.indexOf(keyword) !== -1) {
matches.push(name);
}
},
onComplete: function() {}
});
return matches;
}
function enumMethods(className) {
var methods = [];
try {
var cls = Java.use(className);
var methodList = cls.class.getDeclaredMethods();
for (var i = 0; i < methodList.length; i++) {
methods.push(methodList[i].getName());
}
} catch(e) {}
return methods;
}
function traceClass(className) {
var cls = Java.use(className);
var methods = cls.class.getDeclaredMethods();
for (var i = 0; i < methods.length; i++) {
var methodName = methods[i].getName();
var overloads = cls[methodName].overloads;
for (var j = 0; j < overloads.length; j++) {
overloads[j].implementation = (function(name) {
return function() {
log('debug', 'trace',
className + '.' + name + ' called');
return this[name].apply(this, arguments);
};
})(methodName);
}
}
}
```
---
## 六、逆向分析方法
### 6.1 快速定位关键类
```bash
# 1. 反编译微信APK
jadx -d wechat_decompiled com.tencent.mm.apk
# 2. 搜索关键字
grep -r "sendMsg" wechat_decompiled/ --include="*.java" | head -20
grep -r "MsgInfo" wechat_decompiled/ --include="*.java" | head -20
grep -r "Contact" wechat_decompiled/ --include="*.java" | head -20
# 3. 使用Frida枚举
python3 -c "
import frida
device = frida.get_usb_device()
session = device.attach('com.tencent.mm')
script = session.create_script('''
Java.perform(function() {
Java.enumerateLoadedClasses({
onMatch: function(name) {
if (name.indexOf('com.tencent.mm') !== -1 &&
(name.indexOf('msg') !== -1 || name.indexOf('Msg') !== -1)) {
send(name);
}
},
onComplete: function() { send('DONE'); }
});
});
''')
script.on('message', lambda msg, data: print(msg['payload']))
script.load()
import time; time.sleep(5)
"
```
### 6.2 关键Hook点定位策略
| 功能 | 搜索关键词 | 常见类/方法 |
|------|-----------|-------------|
| 发消息 | sendMsg, sendText, MMMessage | `modelmulti.`, `messenger.` |
| 收消息 | onNewMsg, pushMessage, notify | `push.`, `notification.` |
| 联系人 | Contact, rcontact, getContact | `storage.`, `contactui.` |
| 加好友 | addFriend, verifyUser | `plugin.addfriend.` |
| 朋友圈 | Timeline, SnsPost, moment | `plugin.sns.` |
| 群管理 | Chatroom, createRoom | `chatroom.` |
| 数据库 | EnMicroMsg, SQLiteDatabase | `storage.`, `database.` |
---
## 七、开发任务清单
| 序号 | 任务 | 预估 | 优先级 | 说明 |
|:----:|------|:----:|:------:|------|
| S1 | 脚本框架搭建（模板+RPC+工具） | 2h | P0 | common.js + 模板 |
| S2 | 消息接收Hook（DB insert监控） | 4h | P0 | 核心能力 |
| S3 | 联系人获取（DB查询） | 2h | P0 | 核心能力 |
| S4 | 发送消息Hook | 8h | P1 | 需逆向定位发送方法 |
| S5 | 好友请求监听 | 2h | P1 | 监控fmessage表 |
| S6 | 添加/通过好友 | 4h | P1 | 需逆向 |
| S7 | 朋友圈发布 | 4h | P2 | 需逆向SNS模块 |
| S8 | 朋友圈浏览/点赞 | 3h | P2 | 需逆向 |
| S9 | 群管理（建群/邀请） | 4h | P2 | 需逆向Chatroom模块 |
| S10 | Syscall拦截（网络层） | 6h | P3 | 参考VivWxjz |
| S11 | 多版本适配测试 | 4h | P1 | 微信不同版本 |
| | **合计** | **~43h** | | |
---
## 八、注意事项
### 8.1 版本适配
- 微信每次更新可能导致类名/方法名变化
- 建议维护「版本-Hook点映射表」
- 优先使用DB Hook（最稳定）和Syscall Hook（版本无关）
- Java层Hook作为补充手段
### 8.2 防检测
- frida-server改名为wp-agent
- 端口改为非标准端口（非27042）
- 避免频繁attach/detach
- 脚本中不要log过多信息
### 8.3 性能注意
- Interceptor.attach有性能开销，避免Hook高频调用的方法
- send()数据量控制在4KB以内
- 大数据（图片等）用ArrayBuffer方式传输
- 避免在onEnter/onLeave中做复杂计算
### 8.4 封号风险
- Hook注入天然有封号风险
- 建议：操作频率≤正常人工操作
- 发消息间隔≥3秒
- 加好友≤20人/天
- 发朋友圈≤5条/天

303
开发文档/6、后端/github核心代码/01-uiautomator2核心代码.md Normal file
View File

@@ -0,0 +1,303 @@
# uiautomator2 核心代码提取
> 来源：https://github.com/openatx/uiautomator2 (7.8k⭐)
> 提取日期：2026-01-26
---
## 一、项目概述
uiautomator2 是一个Python库，用于Android UI自动化测试。它通过在设备上运行一个HTTP服务，接收Python客户端的命令来控制手机。
### 架构图
```
┌──────────────────┐ ┌──────────────────────────────────────┐
│ Python Client │ HTTP │ Android设备 │
│ (我们的服务端) │◀───────▶│ │
└──────────────────┘ │ ┌──────────────────────────────┐ │
│ │ u2.jar (uiautomator-server) │ │
│ │ 监听 9008 端口 │ │
│ │ │ │
│ │ 提供： │ │
│ │ - 元素定位 │ │
│ │ - 点击/滑动 │ │
│ │ - 截图 │ │
│ │ - 输入文字 │ │
│ └──────────────────────────────┘ │
│ │
└──────────────────────────────────────┘
```
---
## 二、核心代码
### 2.1 设备连接
```python
# 来源：uiautomator2/core.py
import adbutils
class AdbHTTPConnection(HTTPConnection):
"""通过ADB建立HTTP连接到设备"""
def __init__(self, device: adbutils.AdbDevice, port=9008):
super().__init__("localhost", port)
self.__device = device
self.__port = port
def connect(self):
"""建立到设备的TCP连接"""
try:
self.sock = self.__device.create_connection(
adbutils.Network.TCP,
self.__port
)
except adbutils.AdbError as e:
raise HTTPError(f"Unable to connect to uiautomator2 server: {e}")
```
### 2.2 启动uiautomator服务
```python
# 来源：uiautomator2/core.py
def launch_uiautomator(dev: adbutils.AdbDevice) -> MockAdbProcess:
"""在设备上启动uiautomator2服务"""
command = "CLASSPATH=/data/local/tmp/u2.jar app_process / com.wetest.uia2.Main"
conn = dev.shell(command, stream=True)
process = MockAdbProcess(conn)
return process
```
### 2.3 HTTP请求封装
```python
# 来源：uiautomator2/core.py
def _http_request(
dev: adbutils.AdbDevice,
device_port: int,
method: str,
path: str,
data: Optional[Dict[str, Any]] = None,
timeout=10.0
) -> HTTPResponse:
"""发送HTTP请求到uiautomator2服务"""
headers = {
'User-Agent': 'uiautomator2',
'Accept-Encoding': '',
'Content-Type': 'application/json'
}
with AdbHTTPConnection(dev, port=device_port) as conn:
conn.timeout = timeout
if not data:
conn.request(method, path, headers=headers)
else:
conn.request(method, path, json.dumps(data), headers=headers)
_response = conn.getresponse()
content = bytearray()
while chunk := _response.read(4096):
content.extend(chunk)
if _response.status != 200:
raise HTTPError(f"HTTP request failed: {_response.status}")
return HTTPResponse(content)
```
### 2.4 核心操作方法
```python
# 来源：uiautomator2/__init__.py (简化版)
class Device:
"""设备控制类"""
def __init__(self, serial: str = None):
self._serial = serial
self._device = adbutils.adb.device(serial)
def app_start(self, package_name: str, activity: str = None):
"""启动APP"""
if activity:
self._device.shell(f"am start -n {package_name}/{activity}")
else:
self._device.shell(f"monkey -p {package_name} -c android.intent.category.LAUNCHER 1")
def app_stop(self, package_name: str):
"""停止APP"""
self._device.shell(f"am force-stop {package_name}")
def click(self, x: int, y: int):
"""点击坐标"""
return self._jsonrpc_call("click", [x, y])
def swipe(self, fx: int, fy: int, tx: int, ty: int, duration: float = 0.5):
"""滑动"""
return self._jsonrpc_call("swipe", [fx, fy, tx, ty, int(duration * 1000)])
def send_keys(self, text: str, clear: bool = False):
"""输入文字"""
if clear:
self._jsonrpc_call("clearText", [])
# 使用ADB输入（支持中文）
self._device.shell(f"am broadcast -a ADB_INPUT_TEXT --es msg '{text}'")
def screenshot(self, format='pillow'):
"""截图"""
raw = self._http_get("/screenshot/0?format=jpeg")
if format == 'raw':
return raw
from PIL import Image
import io
return Image.open(io.BytesIO(raw))
def dump_hierarchy(self) -> str:
"""获取UI树XML"""
return self._jsonrpc_call("dumpWindowHierarchy", [False, None])
def _jsonrpc_call(self, method: str, params: list):
"""JSON-RPC调用"""
data = {
"jsonrpc": "2.0",
"id": 1,
"method": method,
"params": params
}
response = self._http_post("/jsonrpc/0", data)
result = response.json()
if "error" in result:
raise RuntimeError(result["error"]["message"])
return result.get("result")
```
### 2.5 XPath选择器
```python
# 来源：uiautomator2/_selector.py (简化版)
class XPath:
"""XPath选择器"""
def __init__(self, device, xpath: str):
self._device = device
self._xpath = xpath
@property
def exists(self) -> bool:
"""检查元素是否存在"""
elements = self._find_elements()
return len(elements) > 0
def click(self, timeout: float = 10):
"""点击元素"""
element = self._wait_for_element(timeout)
bounds = element['bounds']
x = (bounds['left'] + bounds['right']) // 2
y = (bounds['top'] + bounds['bottom']) // 2
self._device.click(x, y)
def set_text(self, text: str):
"""设置文本"""
self.click()
self._device.send_keys(text, clear=True)
def _find_elements(self) -> list:
"""查找元素"""
from lxml import etree
hierarchy = self._device.dump_hierarchy()
root = etree.fromstring(hierarchy.encode())
return root.xpath(self._xpath)
def _wait_for_element(self, timeout: float):
"""等待元素出现"""
import time
deadline = time.time() + timeout
while time.time() < deadline:
elements = self._find_elements()
if elements:
return elements[0]
time.sleep(0.5)
raise TimeoutError(f"Element not found: {self._xpath}")
```
---
## 三、关键依赖
```
adbutils>=2.0.0 # ADB操作
pillow # 图像处理
lxml # XML解析
requests # HTTP请求
```
---
## 四、与工作手机SDK集成
### 封装为Skill
```python
# skills/base_ui.py
import uiautomator2 as u2
from typing import Optional
class BaseUISkill:
"""UI自动化基础Skill"""
PACKAGE: str = "" # 子类必须定义
def __init__(self, device_id: str):
self.d = u2.connect(device_id)
self.d.implicitly_wait(10.0)
def launch(self) -> bool:
"""启动APP"""
self.d.app_start(self.PACKAGE)
return True
def close(self):
"""关闭APP"""
self.d.app_stop(self.PACKAGE)
def click_text(self, text: str, timeout: float = 10) -> bool:
"""点击文字"""
try:
self.d.xpath(f'//*[@text="{text}"]').click(timeout=timeout)
return True
except Exception:
return False
def click_resource_id(self, resource_id: str) -> bool:
"""点击资源ID"""
try:
self.d(resourceId=resource_id).click()
return True
except Exception:
return False
def input_text(self, text: str, clear: bool = True):
"""输入文字"""
if clear:
self.d.clear_text()
self.d.send_keys(text)
def swipe(self, direction: str, scale: float = 0.8):
"""滑动"""
self.d.swipe_ext(direction, scale=scale)
def screenshot(self) -> bytes:
"""截图"""
return self.d.screenshot(format='raw')
def get_ui_tree(self) -> str:
"""获取UI树"""
return self.d.dump_hierarchy()
```

438
开发文档/6、后端/github核心代码/02-droidrun核心代码.md Normal file
View File

@@ -0,0 +1,438 @@
# DroidRun 核心代码提取
> 来源：https://github.com/droidrun/droidrun (7.5k⭐)
> 提取日期：2026-01-26
---
## 一、项目概述
DroidRun 是一个用自然语言控制Android/iOS设备的AI Agent框架。它支持多种LLM（OpenAI、Anthropic、Gemini、DeepSeek等），通过自然语言命令自动化手机操作。
### 架构图
```
┌──────────────────────────────────────────────────────────────────┐
│ DroidRun 架构 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 用户输入 │
│ "帮我在淘宝搜索iPhone16并加入购物车" │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ DroidAgent │ ← LLM驱动的Agent │
│ │ (规划+执行) │ │
│ └───────┬───────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ AdbTools │ │
│ │ • tap(index) - 点击元素 │ │
│ │ • input_text() - 输入文字 │ │
│ │ • swipe() - 滑动 │ │
│ │ • screenshot() - 截图 │ │
│ │ • get_ui_tree() - 获取UI树 │ │
│ │ • start_app() - 启动APP │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ PortalClient (设备端) │ │
│ │ Portal APK - Accessibility Service │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
```
---
## 二、核心代码
### 2.1 AdbTools - 核心控制类
```python
# 来源：droidrun/tools/android/adb.py
from async_adbutils import adb
class AdbTools(Tools):
"""Android设备控制工具集"""
def __init__(
self,
serial: str | None = None,
use_tcp: bool = False,
vision_enabled: bool = True,
) -> None:
self._serial = serial
self._use_tcp = use_tcp
self.device = None
self.portal = None
self._connected = False
# 元素缓存（用于index定位）
self.clickable_elements_cache: List[Dict[str, Any]] = []
# 记忆存储
self.memory: List[str] = []
async def connect(self) -> None:
"""建立设备连接"""
if self._connected:
return
# 连接设备
self.device = await adb.device(serial=self._serial)
# 检查设备状态
state = await self.device.get_state()
if state != "device":
raise ConnectionError(f"Device is not online. State: {state}")
# 初始化Portal客户端
self.portal = PortalClient(self.device, prefer_tcp=self._use_tcp)
await self.portal.connect()
self._connected = True
async def tap(self, index: int) -> str:
"""
点击指定索引的元素
Args:
index: 元素索引（从get_ui_tree返回的带索引UI树中获取）
"""
await self._ensure_connected()
x, y = self._extract_element_coordinates_by_index(index)
await self.portal.tap(x, y)
return f"Tapped element at index {index} (coordinates: {x}, {y})"
async def input_text(self, text: str) -> str:
"""
输入文字到当前焦点
Args:
text: 要输入的文字
"""
await self._ensure_connected()
await self.portal.input_text(text)
return f"Input text: {text}"
async def swipe(
self,
direction: str,
distance: str = "medium"
) -> str:
"""
滑动屏幕
Args:
direction: 方向 (up/down/left/right)
distance: 距离 (short/medium/long)
"""
await self._ensure_connected()
# 获取屏幕尺寸
size = await self.get_screen_size()
width, height = size["width"], size["height"]
# 计算滑动距离
dist_map = {"short": 0.2, "medium": 0.5, "long": 0.8}
scale = dist_map.get(distance, 0.5)
# 计算起止坐标
cx, cy = width // 2, height // 2
if direction == "up":
await self.portal.swipe(cx, int(cy + height * scale * 0.4),
cx, int(cy - height * scale * 0.4))
elif direction == "down":
await self.portal.swipe(cx, int(cy - height * scale * 0.4),
cx, int(cy + height * scale * 0.4))
# ... 其他方向
return f"Swiped {direction} with {distance} distance"
async def screenshot(self) -> bytes:
"""截图"""
await self._ensure_connected()
return await self.portal.screenshot()
async def get_ui_tree(self) -> str:
"""
获取UI树（带索引）
返回格式化的UI树，每个可点击元素都有索引号
"""
await self._ensure_connected()
# 获取原始UI树
raw_tree = await self.portal.dump_hierarchy()
# 过滤和格式化
filtered = self.tree_filter.filter(raw_tree)
formatted = self.tree_formatter.format(filtered)
# 缓存可点击元素
self.clickable_elements_cache = filtered.get("clickable_elements", [])
return formatted
async def start_app(self, package_name: str) -> str:
"""启动APP"""
await self._ensure_connected()
await self.device.shell(
f"monkey -p {package_name} -c android.intent.category.LAUNCHER 1"
)
return f"Started app: {package_name}"
async def stop_app(self, package_name: str) -> str:
"""停止APP"""
await self._ensure_connected()
await self.device.shell(f"am force-stop {package_name}")
return f"Stopped app: {package_name}"
def remember(self, info: str) -> str:
"""
记住重要信息（用于跨步骤传递）
Args:
info: 要记住的信息
"""
self.memory.append(info)
return f"Remembered: {info}"
def finish(self, reason: str, success: bool) -> str:
"""
完成任务
Args:
reason: 完成原因
success: 是否成功
"""
self.finished = True
self.reason = reason
self.success = success
return f"Task finished. Success: {success}. Reason: {reason}"
```
### 2.2 DroidAgent - AI Agent核心
```python
# 来源：droidrun/agent/droid_agent.py (简化版)
from llama_index.core.agent import AgentRunner
class DroidAgent:
"""AI Agent - 用自然语言控制手机"""
def __init__(
self,
goal: str,
llm,
tools: AdbTools,
max_iterations: int = 30,
):
self.goal = goal
self.llm = llm
self.tools = tools
self.max_iterations = max_iterations
# 构建Agent
self.agent = self._build_agent()
def _build_agent(self) -> AgentRunner:
"""构建LlamaIndex Agent"""
from llama_index.core.tools import FunctionTool
# 将AdbTools的方法转换为FunctionTool
function_tools = [
FunctionTool.from_defaults(fn=self.tools.tap),
FunctionTool.from_defaults(fn=self.tools.input_text),
FunctionTool.from_defaults(fn=self.tools.swipe),
FunctionTool.from_defaults(fn=self.tools.screenshot),
FunctionTool.from_defaults(fn=self.tools.get_ui_tree),
FunctionTool.from_defaults(fn=self.tools.start_app),
FunctionTool.from_defaults(fn=self.tools.stop_app),
FunctionTool.from_defaults(fn=self.tools.remember),
FunctionTool.from_defaults(fn=self.tools.finish),
]
return AgentRunner.from_llm(
llm=self.llm,
tools=function_tools,
verbose=True,
)
async def run(self) -> dict:
"""执行任务"""
# 系统提示词
system_prompt = f"""
你是一个Android手机控制Agent。你的任务是：{self.goal}
你可以使用以下工具：
- tap(index): 点击UI树中指定索引的元素
- input_text(text): 输入文字
- swipe(direction, distance): 滑动屏幕
- screenshot(): 截图
- get_ui_tree(): 获取当前页面的UI树
- start_app(package): 启动APP
- stop_app(package): 停止APP
- remember(info): 记住重要信息
- finish(reason, success): 完成任务
执行步骤：
1. 首先调用get_ui_tree()了解当前页面
2. 根据任务目标，选择合适的操作
3. 每次操作后，再次调用get_ui_tree()确认结果
4. 完成后调用finish()
注意：
- 元素索引从get_ui_tree()返回的结果中获取
- 如果找不到目标元素，尝试滑动页面
- 遇到错误时，尝试其他方法
"""
# 执行Agent
response = await self.agent.achat(system_prompt)
return {
"success": self.tools.success,
"reason": self.tools.reason,
"output": response.response,
"memory": self.tools.memory,
}
```
### 2.3 PortalClient - 设备端通信
```python
# 来源：droidrun/tools/android/portal_client.py (简化版)
class PortalClient:
"""与设备端Portal APK通信"""
DEFAULT_PORT = 8080
def __init__(self, device, prefer_tcp: bool = False):
self.device = device
self.prefer_tcp = prefer_tcp
self.base_url = None
async def connect(self):
"""建立连接"""
if self.prefer_tcp:
# TCP模式：直接连接设备端口
self.base_url = f"http://{await self._get_device_ip()}:{self.DEFAULT_PORT}"
else:
# ADB模式：通过端口转发
await self._setup_port_forward()
self.base_url = f"http://127.0.0.1:{self.DEFAULT_PORT}"
async def tap(self, x: int, y: int):
"""点击"""
async with aiohttp.ClientSession() as session:
await session.post(
f"{self.base_url}/tap",
json={"x": x, "y": y}
)
async def input_text(self, text: str):
"""输入文字"""
async with aiohttp.ClientSession() as session:
await session.post(
f"{self.base_url}/input",
json={"text": text}
)
async def swipe(self, x1: int, y1: int, x2: int, y2: int, duration: int = 500):
"""滑动"""
async with aiohttp.ClientSession() as session:
await session.post(
f"{self.base_url}/swipe",
json={"x1": x1, "y1": y1, "x2": x2, "y2": y2, "duration": duration}
)
async def screenshot(self) -> bytes:
"""截图"""
async with aiohttp.ClientSession() as session:
async with session.get(f"{self.base_url}/screenshot") as resp:
return await resp.read()
async def dump_hierarchy(self) -> str:
"""获取UI树"""
async with aiohttp.ClientSession() as session:
async with session.get(f"{self.base_url}/hierarchy") as resp:
return await resp.text()
```
---
## 三、支持的LLM
```python
# 使用示例
# OpenAI
from llama_index.llms.openai import OpenAI
llm = OpenAI(model="gpt-4o", api_key="...")
# DeepSeek (推荐，便宜)
from llama_index.llms.deepseek import DeepSeek
llm = DeepSeek(model="deepseek-chat", api_key="...")
# Google Gemini
from llama_index.llms.google_genai import GoogleGenAI
llm = GoogleGenAI(model="gemini-2.5-flash", api_key="...")
# Anthropic Claude
from llama_index.llms.anthropic import Anthropic
llm = Anthropic(model="claude-3-5-sonnet", api_key="...")
# Ollama (本地)
from llama_index.llms.ollama import Ollama
llm = Ollama(model="llama3.1", base_url="http://localhost:11434")
```
---
## 四、与工作手机SDK集成
```python
# agent/work_phone_agent.py
from droidrun import DroidAgent, AdbTools
from llama_index.llms.deepseek import DeepSeek
class WorkPhoneAgent:
"""工作手机AI Agent"""
def __init__(self, device_id: str, llm_provider: str = "deepseek"):
self.device_id = device_id
self.tools = AdbTools(serial=device_id)
self.llm = self._create_llm(llm_provider)
def _create_llm(self, provider: str):
if provider == "deepseek":
return DeepSeek(
model="deepseek-chat",
api_key="your-api-key"
)
elif provider == "openai":
return OpenAI(
model="gpt-4o",
api_key="your-api-key"
)
async def execute(self, task: str) -> dict:
"""执行自然语言任务"""
agent = DroidAgent(
goal=task,
llm=self.llm,
tools=self.tools
)
return await agent.run()
# 使用示例
agent = WorkPhoneAgent("device-001")
result = await agent.execute("打开微信给张三发消息：明天开会")
```

466
开发文档/6、后端/github核心代码/03-闲鱼WebSocket核心代码.md Normal file
View File

@@ -0,0 +1,466 @@
# 闲鱼WebSocket自动回复 核心代码提取
> 来源：https://github.com/ziling35/xianyu-auto
> 提取日期：2026-01-26
---
## 一、项目概述
这是一个基于WebSocket的闲鱼自动回复系统，支持AI智能回复、多账号管理、验证码处理等功能。
### 架构图
```
┌──────────────────────────────────────────────────────────────────┐
│ 闲鱼自动回复系统架构 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ WebSocket连接池 │ │
│ │ Account1 ←→ WSS ←→ 闲鱼服务器 │ │
│ │ Account2 ←→ WSS ←→ 闲鱼服务器 │ │
│ │ AccountN ←→ WSS ←→ 闲鱼服务器 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 消息处理中心 │ │
│ │ • 消息解密 (protobuf + base64) │ │
│ │ • 意图识别 │ │
│ │ • AI回复生成 │ │
│ │ • 暂停管理 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 数据存储层 │ │
│ │ • SQLite (会话/消息/配置) │ │
│ │ • Cookie管理 │ │
│ │ • 日志记录 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
```
---
## 二、核心代码
### 2.1 WebSocket连接管理
```python
# 来源：XianyuAutoAsync.py
import asyncio
import websockets
from enum import Enum
class ConnectionState(Enum):
"""WebSocket连接状态"""
DISCONNECTED = "disconnected"
CONNECTING = "connecting"
CONNECTED = "connected"
RECONNECTING = "reconnecting"
FAILED = "failed"
CLOSED = "closed"
class XianyuWebSocket:
"""闲鱼WebSocket客户端"""
WEBSOCKET_URL = "wss://..." # 闲鱼WSS地址
HEARTBEAT_INTERVAL = 30 # 心跳间隔
def __init__(self, cookies: str, cookie_id: str):
self.cookies = cookies
self.cookie_id = cookie_id
self.state = ConnectionState.DISCONNECTED
self.ws = None
async def connect(self):
"""建立WebSocket连接"""
self.state = ConnectionState.CONNECTING
headers = {
"Cookie": self.cookies,
"User-Agent": "Mozilla/5.0 ...",
# ... 其他必要headers
}
try:
self.ws = await websockets.connect(
self.WEBSOCKET_URL,
extra_headers=headers,
ping_interval=self.HEARTBEAT_INTERVAL,
ping_timeout=10
)
self.state = ConnectionState.CONNECTED
logger.info(f"【{self.cookie_id}】WebSocket连接成功")
# 启动消息接收循环
await self._message_loop()
except Exception as e:
self.state = ConnectionState.FAILED
logger.error(f"【{self.cookie_id}】连接失败: {e}")
await self._reconnect()
async def _message_loop(self):
"""消息接收循环"""
while self.state == ConnectionState.CONNECTED:
try:
message = await asyncio.wait_for(
self.ws.recv(),
timeout=60
)
await self._handle_message(message)
except asyncio.TimeoutError:
# 超时，发送心跳
await self._send_heartbeat()
except websockets.exceptions.ConnectionClosed:
logger.warning(f"【{self.cookie_id}】连接已关闭")
await self._reconnect()
break
async def _handle_message(self, raw_message: str):
"""处理接收到的消息"""
try:
# 解密消息
data = decrypt(raw_message)
msg_type = data.get("type")
if msg_type == "chat":
# 聊天消息
await self._handle_chat_message(data)
elif msg_type == "system":
# 系统消息
logger.info(f"【{self.cookie_id}】系统消息: {data}")
except Exception as e:
logger.error(f"【{self.cookie_id}】消息处理失败: {e}")
async def _handle_chat_message(self, data: dict):
"""处理聊天消息"""
chat_id = data.get("chat_id")
from_user = data.get("from_user")
content = data.get("content")
logger.info(f"【{self.cookie_id}】收到消息: {from_user} -> {content}")
# 检查是否暂停自动回复
if pause_manager.is_chat_paused(chat_id):
logger.info(f"【{self.cookie_id}】会话 {chat_id} 处于暂停状态，跳过自动回复")
return
# 生成AI回复
reply = await self._generate_reply(content, chat_id)
if reply:
await self.send_message(chat_id, reply)
async def _generate_reply(self, content: str, chat_id: str) -> str:
"""生成AI回复"""
# 调用AI回复引擎
from ai_reply_engine import generate_reply
return await generate_reply(content, chat_id, self.cookie_id)
async def send_message(self, chat_id: str, content: str):
"""发送消息"""
if self.state != ConnectionState.CONNECTED:
raise RuntimeError("WebSocket未连接")
# 构建消息
message = {
"type": "send_msg",
"chat_id": chat_id,
"content": content,
"sign": generate_sign(...) # 签名
}
await self.ws.send(json.dumps(message))
logger.info(f"【{self.cookie_id}】发送消息: {content[:50]}...")
async def _reconnect(self):
"""重连"""
self.state = ConnectionState.RECONNECTING
# 指数退避重连
retry_delays = [1, 2, 4, 8, 16, 32, 60]
for i, delay in enumerate(retry_delays):
logger.info(f"【{self.cookie_id}】将在 {delay}s 后进行第 {i+1} 次重连")
await asyncio.sleep(delay)
try:
await self.connect()
return
except Exception as e:
logger.error(f"【{self.cookie_id}】第 {i+1} 次重连失败: {e}")
self.state = ConnectionState.FAILED
logger.error(f"【{self.cookie_id}】达到最大重连次数，放弃重连")
async def _send_heartbeat(self):
"""发送心跳"""
if self.ws:
await self.ws.send(json.dumps({"type": "heartbeat"}))
```
### 2.2 自动回复暂停管理
```python
# 来源：XianyuAutoAsync.py
class AutoReplyPauseManager:
"""自动回复暂停管理器"""
def __init__(self):
# {chat_id: pause_until_timestamp}
self.paused_chats = {}
def pause_chat(self, chat_id: str, cookie_id: str):
"""暂停指定chat_id的自动回复"""
pause_minutes = db_manager.get_cookie_pause_duration(cookie_id)
if pause_minutes == 0:
return
pause_until = time.time() + (pause_minutes * 60)
self.paused_chats[chat_id] = pause_until
logger.info(f"【{cookie_id}】chat_id {chat_id} 自动回复暂停{pause_minutes}分钟")
def is_chat_paused(self, chat_id: str) -> bool:
"""检查是否处于暂停状态"""
if chat_id not in self.paused_chats:
return False
if time.time() >= self.paused_chats[chat_id]:
del self.paused_chats[chat_id]
return False
return True
def get_remaining_pause_time(self, chat_id: str) -> int:
"""获取剩余暂停时间（秒）"""
if chat_id not in self.paused_chats:
return 0
return max(0, int(self.paused_chats[chat_id] - time.time()))
# 全局实例
pause_manager = AutoReplyPauseManager()
```
### 2.3 签名和加解密工具
```python
# 来源：utils/xianyu_utils.py (简化版)
import base64
import hashlib
import uuid
import time
def generate_uuid() -> str:
"""生成UUID"""
return str(uuid.uuid4())
def generate_mid() -> str:
"""生成消息ID"""
return f"{int(time.time() * 1000)}{uuid.uuid4().hex[:8]}"
def generate_device_id() -> str:
"""生成设备ID"""
return hashlib.md5(str(uuid.uuid4()).encode()).hexdigest()
def generate_sign(data: dict, secret: str) -> str:
"""
生成签名
签名算法（伪代码）：
1. 将参数按key排序
2. 拼接成 key=value&key=value 格式
3. 末尾加上secret
4. MD5哈希
"""
sorted_items = sorted(data.items())
sign_str = "&".join([f"{k}={v}" for k, v in sorted_items])
sign_str += secret
return hashlib.md5(sign_str.encode()).hexdigest()
def decrypt(encrypted: str) -> dict:
"""
解密消息
闲鱼消息格式：base64 + protobuf
"""
import json
# 1. Base64解码
decoded = base64.b64decode(encrypted)
# 2. Protobuf解析（这里简化为JSON）
# 实际需要使用protobuf库解析
try:
return json.loads(decoded)
except:
# 如果是protobuf格式，需要额外处理
return {"raw": decoded}
def trans_cookies(cookies_str: str) -> dict:
"""将cookie字符串转换为字典"""
cookies = {}
for item in cookies_str.split(";"):
if "=" in item:
key, value = item.strip().split("=", 1)
cookies[key] = value
return cookies
```
### 2.4 AI回复引擎
```python
# 来源：ai_reply_engine.py (简化版)
import aiohttp
from config import AI_CONFIG
class AIReplyEngine:
"""AI回复引擎"""
def __init__(self):
self.api_url = AI_CONFIG.get("api_url")
self.api_key = AI_CONFIG.get("api_key")
self.model = AI_CONFIG.get("model", "gpt-3.5-turbo")
async def generate_reply(
self,
message: str,
chat_id: str,
context: list = None
) -> str:
"""生成AI回复"""
# 构建提示词
system_prompt = """
你是一个闲鱼卖家的智能客服助手。
- 回复要简洁、友好
- 主要回答关于商品的问题
- 遇到议价要委婉拒绝或引导
- 不要透露是AI
"""
messages = [
{"role": "system", "content": system_prompt}
]
# 添加历史上下文
if context:
for ctx in context[-5:]: # 最近5条
messages.append(ctx)
# 添加当前消息
messages.append({"role": "user", "content": message})
# 调用AI API
async with aiohttp.ClientSession() as session:
async with session.post(
f"{self.api_url}/chat/completions",
headers={
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json"
},
json={
"model": self.model,
"messages": messages,
"max_tokens": 200,
"temperature": 0.7
}
) as resp:
result = await resp.json()
return result["choices"][0]["message"]["content"]
# 全局实例
ai_engine = AIReplyEngine()
async def generate_reply(message: str, chat_id: str, cookie_id: str) -> str:
"""生成回复（对外接口）"""
# 获取历史上下文
context = db_manager.get_chat_context(chat_id, limit=5)
# 生成回复
reply = await ai_engine.generate_reply(message, chat_id, context)
# 保存到数据库
db_manager.save_message(chat_id, "assistant", reply)
return reply
```
---
## 三、与工作手机SDK集成
```python
# skills/xianyu/skill.py
class XianyuSkill:
"""闲鱼Skill - 协议模式"""
def __init__(self, cookies: str, cookie_id: str):
self.ws_client = XianyuWebSocket(cookies, cookie_id)
self.connected = False
async def connect(self):
"""建立连接"""
await self.ws_client.connect()
self.connected = True
async def send_message(self, chat_id: str, content: str) -> dict:
"""发送私信"""
if not self.connected:
await self.connect()
await self.ws_client.send_message(chat_id, content)
return {"success": True}
async def get_messages(self, limit: int = 20) -> list:
"""获取消息列表"""
# 从数据库获取
return db_manager.get_recent_messages(self.cookie_id, limit)
def set_auto_reply(self, enabled: bool, prompt: str = None):
"""设置自动回复"""
db_manager.set_auto_reply_config(
self.cookie_id,
enabled=enabled,
prompt=prompt
)
```
---
## 四、关键配置
```python
# config.py
WEBSOCKET_URL = "wss://..."
HEARTBEAT_INTERVAL = 30
HEARTBEAT_TIMEOUT = 10
AI_CONFIG = {
"api_url": "https://api.openai.com/v1",
"api_key": "your-api-key",
"model": "gpt-3.5-turbo"
}
AUTO_REPLY = {
"enabled": True,
"pause_on_manual": True,
"pause_minutes": 10
}
```

273
开发文档/6、后端/github核心代码/04-抖音私信协议.md Normal file
View File

@@ -0,0 +1,273 @@
# 抖音私信WSS协议分析
> 来源：https://github.com/Airmole/douyin-wss
> 提取日期：2026-01-26
>
> 注意：该仓库已年久失修，建议参考 https://github.com/YunzhiYike/douyin-live
---
## 一、协议概述
抖音网页版私信使用WebSocket协议通信，消息格式为JSON。
### 连接地址
```
wss://webcast3-ws-web-lf.douyin.com/webcast/im/push/v2/
```
---
## 二、消息格式
### 2.1 文本消息
```json
{
"type": 0,
"isShareText": false,
"item_type_local": -1,
"richTextInfos": [],
"text": "消息内容",
"createdAt": 0,
"is_card": false,
"msgHint": "",
"aweType": 700
}
```
| 字段 | 说明 |
|:---|:---|
| type | 消息类型，0=文本 |
| text | 消息文本内容 |
| aweType | 抖音消息类型，700=普通文本 |
### 2.2 内置表情
```json
{
"type": 0,
"text": "[微笑]",
"aweType": 700
}
```
表情用方括号包裹的文字表示。
### 2.3 GIF表情
```json
{
"aweType": 500,
"height": 240,
"image_id": 6752145780640842000,
"image_type": "gif",
"url": {
"uri": "joker/weshine/xxx.gif",
"url_list": [
"https://p26-sign.douyinpic.com/obj/joker/weshine/xxx.gif?x-expires=..."
]
}
}
```
| 字段 | 说明 |
|:---|:---|
| aweType | 500=GIF表情 |
| image_type | gif |
| url.url_list | 图片CDN地址列表 |
### 2.4 图片消息
```json
{
"aweType": 2702,
"cover_height": 726,
"cover_width": 1046,
"md5": "25bd2187f8f7cb0481c02e35d1bd5095",
"resource_url": {
"large_url_list": ["https://..."],
"medium_url_list": ["https://..."],
"thumb_url_list": ["https://..."]
}
}
```
> 注意：图片需解密，解密方法未公开
### 2.5 语音消息
```json
{
"height": 0,
"data_size": 0,
"uri": "douyin-user-audio-file/xxx.mpeg",
"url_list": [
"https://sf3-sign.douyinstatic.com/douyin-user-audio-file/xxx.mpeg?x-expires=..."
]
}
```
### 2.6 位置消息
```json
{
"aweType": 0,
"aweme_poi_id": "6601265443279734788",
"latitude": 24.617908631273124,
"longitude": 118.04502062375067,
"poi_address": "福建省厦门市集美区诚毅北大街",
"poi_name": "金海豚广场"
}
```
### 2.7 视频分享
```json
{
"aweType": 800,
"awemeType": 0,
"content_name": "发布者昵称",
"itemId": "7097473243912621351",
"secUID": "MS4wLjABAAAA...",
"uid": "1200310293640376"
}
```
视频URL拼接：`https://www.douyin.com/video/{itemId}`
---
## 三、aweType消息类型对照表
| aweType | 说明 |
|:---|:---|
| 0 | 位置/其他 |
| 500 | GIF表情 |
| 700 | 文本消息 |
| 800 | 视频分享 |
| 2702 | 图片消息 |
---
## 四、与工作手机SDK集成
### 4.1 抖音私信Skill（UI模式）
由于抖音WSS协议复杂且经常变化，建议使用UI自动化作为主方案：
```python
# skills/douyin/skill.py
from skills.base_ui import BaseUISkill
class DouyinSkill(BaseUISkill):
"""抖音Skill - UI模式"""
PACKAGE = "com.ss.android.ugc.aweme"
NAME = "抖音"
# UI元素
RES_MESSAGE_TAB = "com.ss.android.ugc.aweme:id/..."
RES_CHAT_INPUT = "com.ss.android.ugc.aweme:id/..."
RES_SEND_BTN = "com.ss.android.ugc.aweme:id/..."
def send_message(self, to_user: str, content: str) -> dict:
"""发送私信"""
self.launch()
self.sleep(2)
# 1. 点击消息Tab
self.click_text("消息")
self.sleep(1)
# 2. 搜索用户
self.click_text("搜索")
self.input_text(to_user)
self.sleep(1)
# 3. 点击用户进入聊天
self.click_text(to_user)
self.sleep(1)
# 4. 输入消息
self.click_resource_id(self.RES_CHAT_INPUT)
self.input_text(content)
# 5. 发送
self.click_resource_id(self.RES_SEND_BTN)
return {"success": True}
def get_messages(self, limit: int = 20) -> dict:
"""获取私信列表"""
self.launch()
self.sleep(2)
# 点击消息Tab
self.click_text("消息")
self.sleep(1)
# 获取UI树分析消息列表
ui_tree = self.get_ui_tree()
# TODO: 解析UI树提取消息
messages = []
return {
"success": True,
"messages": messages
}
```
### 4.2 WSS协议模式（备选）
如果需要更高效的私信处理，可以尝试WSS协议：
```python
# skills/douyin/wss_skill.py
import websockets
import json
class DouyinWSSSkill:
"""抖音Skill - WSS模式（实验性）"""
WSS_URL = "wss://webcast3-ws-web-lf.douyin.com/webcast/im/push/v2/"
def __init__(self, cookies: str):
self.cookies = cookies
self.ws = None
async def connect(self):
"""建立WSS连接"""
headers = {
"Cookie": self.cookies,
"User-Agent": "Mozilla/5.0 ..."
}
self.ws = await websockets.connect(
self.WSS_URL,
extra_headers=headers
)
async def listen(self, callback):
"""监听消息"""
async for message in self.ws:
data = json.loads(message)
await callback(data)
async def send_message(self, to_uid: str, content: str):
"""发送私信（需要逆向协议）"""
# TODO: 需要逆向抖音发送私信的协议
pass
```
---
## 五、注意事项
1. **协议不稳定**：抖音经常更新协议，建议以UI自动化为主
2. **风控严格**：抖音对自动化检测严格，需要添加随机延迟
3. **加密变化**：图片等资源的加密方式可能变化
4. **建议方案**：UI自动化（主） + WSS监听（辅）

435
开发文档/6、后端/github核心代码/05-objection-Frida自动化.md Normal file
View File

@@ -0,0 +1,435 @@
# objection (Frida自动化工具) 核心代码提取
> 来源：https://github.com/sensepost/objection (8.8k⭐)
> 提取日期：2026-01-26
---
## 一、项目概述
objection 是一个基于 Frida 的移动安全测试工具，主要用于 SSL Pinning Bypass、Hook方法等。对于工作手机SDK，我们主要使用其 **SSL Bypass** 能力。
### 主要能力
| 能力 | 说明 | 用途 |
|:---|:---|:---|
| **SSL Pinning Bypass** | 绕过APP的证书校验 | 抓包HTTPS |
| **Method Hooking** | Hook Java/Native方法 | 获取加密数据 |
| **Memory Dump** | 内存转储 | 分析数据结构 |
| **File System Access** | 文件系统访问 | 读取APP数据 |
---
## 二、SSL Bypass 核心脚本
### 2.1 通用SSL Bypass (Android)
```javascript
// 来源：objection/agent/src/android/pinning.ts (转换为JS)
'use strict';
Java.perform(function() {
console.log('[*] 开始SSL Pinning绕过...');
// ===== 1. TrustManagerImpl =====
try {
var TrustManagerImpl = Java.use('com.android.org.conscrypt.TrustManagerImpl');
TrustManagerImpl.verifyChain.implementation = function(
untrustedChain, trustAnchorChain, host, clientAuth, ocspData, tlsSctData
) {
console.log('[+] Bypassing TrustManagerImpl for: ' + host);
return untrustedChain;
};
} catch(e) {
console.log('[-] TrustManagerImpl not found');
}
// ===== 2. OkHttp3 CertificatePinner =====
try {
var CertificatePinner = Java.use('okhttp3.CertificatePinner');
CertificatePinner.check.overload('java.lang.String', 'java.util.List').implementation = function(hostname, peerCertificates) {
console.log('[+] Bypassing OkHttp3 for: ' + hostname);
return;
};
CertificatePinner.check.overload('java.lang.String', '[Ljava.security.cert.Certificate;').implementation = function(hostname, peerCertificates) {
console.log('[+] Bypassing OkHttp3 for: ' + hostname);
return;
};
} catch(e) {
console.log('[-] OkHttp3 CertificatePinner not found');
}
// ===== 3. OkHttp (旧版) =====
try {
var OkHttpClient = Java.use('com.squareup.okhttp.OkHttpClient');
OkHttpClient.setCertificatePinner.implementation = function(certificatePinner) {
console.log('[+] Bypassing OkHttp setCertificatePinner');
return this;
};
} catch(e) {
console.log('[-] OkHttp OkHttpClient not found');
}
// ===== 4. WebViewClient =====
try {
var WebViewClient = Java.use('android.webkit.WebViewClient');
WebViewClient.onReceivedSslError.implementation = function(view, handler, error) {
console.log('[+] Bypassing WebView SSL Error');
handler.proceed();
};
} catch(e) {
console.log('[-] WebViewClient not found');
}
// ===== 5. TrustManager (通用) =====
try {
var X509TrustManager = Java.use('javax.net.ssl.X509TrustManager');
var SSLContext = Java.use('javax.net.ssl.SSLContext');
var TrustManager = Java.registerClass({
name: 'com.bypass.TrustManager',
implements: [X509TrustManager],
methods: {
checkClientTrusted: function(chain, authType) {},
checkServerTrusted: function(chain, authType) {},
getAcceptedIssuers: function() { return []; }
}
});
var TrustManagers = [TrustManager.$new()];
var sslContext = SSLContext.getInstance('TLS');
sslContext.init(null, TrustManagers, null);
SSLContext.init.overload('[Ljavax.net.ssl.KeyManager;', '[Ljavax.net.ssl.TrustManager;', 'java.security.SecureRandom').implementation = function(km, tm, sr) {
console.log('[+] Bypassing SSLContext.init');
this.init(km, TrustManagers, sr);
};
} catch(e) {
console.log('[-] TrustManager bypass failed: ' + e);
}
// ===== 6. HttpsURLConnection =====
try {
var HttpsURLConnection = Java.use('javax.net.ssl.HttpsURLConnection');
HttpsURLConnection.setDefaultHostnameVerifier.implementation = function(hostnameVerifier) {
console.log('[+] Bypassing HttpsURLConnection HostnameVerifier');
return;
};
HttpsURLConnection.setSSLSocketFactory.implementation = function(sslSocketFactory) {
console.log('[+] Bypassing HttpsURLConnection SSLSocketFactory');
return;
};
} catch(e) {
console.log('[-] HttpsURLConnection not found');
}
console.log('[*] SSL Pinning绕过完成');
});
```
### 2.2 微信专用Bypass
```javascript
// wechat_ssl_bypass.js
'use strict';
Java.perform(function() {
console.log('[*] 微信SSL Bypass开始...');
// 微信使用自定义的网络库
try {
// 1. 微信MMTLS
var MMTLSUtil = Java.use('com.tencent.mm.plugin.mmsight.MMTLSUtil');
if (MMTLSUtil) {
MMTLSUtil.a.overload('[B').implementation = function(arg) {
console.log('[+] Bypassing MMTLS');
return true;
};
}
} catch(e) {}
// 2. 微信Mars
try {
var Mars = Java.use('com.tencent.mars.stn.StnLogic');
// Hook Mars相关方法
} catch(e) {}
// 3. 通用SSL Bypass
try {
var TrustManagerImpl = Java.use('com.android.org.conscrypt.TrustManagerImpl');
TrustManagerImpl.verifyChain.implementation = function(
untrustedChain, trustAnchorChain, host, clientAuth, ocspData, tlsSctData
) {
console.log('[+] TrustManagerImpl bypass for: ' + host);
return untrustedChain;
};
} catch(e) {}
console.log('[*] 微信SSL Bypass完成');
});
```
---
## 三、Method Hooking
### 3.1 Hook任意方法
```javascript
// hook_method.js
'use strict';
Java.perform(function() {
// Hook指定类的指定方法
function hookMethod(className, methodName, callback) {
try {
var clazz = Java.use(className);
var methods = clazz[methodName].overloads;
methods.forEach(function(method) {
method.implementation = function() {
var args = Array.prototype.slice.call(arguments);
console.log('[Hook] ' + className + '.' + methodName);
console.log('[Args] ' + JSON.stringify(args));
// 调用原方法
var result = method.apply(this, args);
console.log('[Result] ' + result);
// 回调
if (callback) {
callback(args, result);
}
return result;
};
});
console.log('[+] Hooked: ' + className + '.' + methodName);
} catch(e) {
console.log('[-] Hook failed: ' + e);
}
}
// 示例：Hook微信消息发送
hookMethod(
'com.tencent.mm.sdk.platformtools.ab', // 类名（混淆后）
'a', // 方法名
function(args, result) {
// 发送到服务器
send({
type: 'wechat_message',
args: args,
result: result
});
}
);
});
```
### 3.2 抓取HTTP请求
```javascript
// http_capture.js
'use strict';
Java.perform(function() {
console.log('[*] HTTP抓包开始...');
// Hook OkHttp3 RealCall
try {
var RealCall = Java.use('okhttp3.RealCall');
RealCall.execute.implementation = function() {
var request = this.request();
var url = request.url().toString();
var method = request.method();
var headers = request.headers().toString();
var body = '';
if (request.body()) {
var buffer = Java.use('okio.Buffer').$new();
request.body().writeTo(buffer);
body = buffer.readUtf8();
}
console.log('[Request] ' + method + ' ' + url);
// 发送到服务器
send({
type: 'http_request',
url: url,
method: method,
headers: headers,
body: body
});
// 执行原请求
var response = this.execute();
// 捕获响应
// ...
return response;
};
} catch(e) {
console.log('[-] OkHttp3 hook failed: ' + e);
}
});
```
---
## 四、与工作手机SDK集成
### 4.1 Frida管理服务
```python
# services/frida_service.py
import frida
import json
from typing import Dict, Callable
class FridaService:
"""Frida管理服务"""
def __init__(self):
self.sessions: Dict[str, frida.Session] = {}
self.scripts: Dict[str, frida.Script] = {}
def attach(self, device_id: str, package: str) -> bool:
"""附加到进程"""
try:
device = frida.get_device(device_id)
pid = device.spawn([package])
session = device.attach(pid)
self.sessions[f"{device_id}:{package}"] = session
device.resume(pid)
return True
except Exception as e:
print(f"Attach failed: {e}")
return False
def inject_script(
self,
device_id: str,
package: str,
script_code: str,
on_message: Callable = None
):
"""注入脚本"""
key = f"{device_id}:{package}"
session = self.sessions.get(key)
if not session:
raise RuntimeError("Session not found")
script = session.create_script(script_code)
if on_message:
script.on('message', on_message)
script.load()
self.scripts[key] = script
def ssl_bypass(self, device_id: str, package: str):
"""启用SSL Bypass"""
script_code = open('frida_scripts/ssl_bypass.js').read()
def on_message(message, data):
print(f"[SSL Bypass] {message}")
self.inject_script(device_id, package, script_code, on_message)
def start_capture(
self,
device_id: str,
package: str,
callback: Callable
):
"""开始抓包"""
script_code = open('frida_scripts/http_capture.js').read()
def on_message(message, data):
if message['type'] == 'send':
callback(message['payload'])
self.inject_script(device_id, package, script_code, on_message)
def detach(self, device_id: str, package: str):
"""分离"""
key = f"{device_id}:{package}"
if key in self.scripts:
self.scripts[key].unload()
del self.scripts[key]
if key in self.sessions:
self.sessions[key].detach()
del self.sessions[key]
# 使用示例
frida_svc = FridaService()
# 附加微信
frida_svc.attach("device-001", "com.tencent.mm")
# 启用SSL Bypass
frida_svc.ssl_bypass("device-001", "com.tencent.mm")
# 开始抓包
def on_capture(data):
print(f"Captured: {data}")
frida_svc.start_capture("device-001", "com.tencent.mm", on_capture)
```
### 4.2 objection命令行使用
```bash
# 安装
pip install objection
# 附加到APP
objection -g com.tencent.mm explore
# 常用命令
# SSL Bypass
android sslpinning disable
# 列出类
android hooking list classes
# 搜索类
android hooking search classes wechat
# Hook方法
android hooking watch class com.tencent.mm.sdk.platformtools.ab
# 列出Activity
android hooking list activities
# 启动Activity
android intent launch_activity com.tencent.mm.ui.LauncherUI
```
---
## 五、Frida脚本目录结构
```
frida_scripts/
├── ssl_bypass.js # 通用SSL Bypass
├── wechat_ssl.js # 微信专用
├── douyin_ssl.js # 抖音专用
├── http_capture.js # HTTP抓包
├── method_hook.js # 方法Hook
└── common.js # 公共函数
```

132
开发文档/6、后端/github核心代码/README.md Normal file
View File

@@ -0,0 +1,132 @@
# 工作手机SDK v3.0 核心代码库
> 提取日期：2026-01-26 | 来源：GitHub开源项目
>
> 本目录存放从各GitHub仓库提取的与工作手机SDK相关的核心代码
---
## 📁 目录结构
```
_核心代码/
├── README.md ← 你正在看的这个
├── 架构图.md ← 技术架构汇总
├── 01-uiautomator2/ ← Android UI自动化 (7.8k⭐)
├── 02-droidrun/ ← AI Agent控制 (7.5k⭐)
├── 03-objection/ ← Frida自动化 (8.8k⭐)
├── 04-抖音WSS协议/ ← 抖音私信协议
├── 05-闲鱼自动回复/ ← 闲鱼WebSocket
└── 06-Airtest/ ← 网易自动化框架 (5.4k⭐)
```
---
## 🔧 技术栈与来源
| 技术 | GitHub Stars | 仓库地址 | 用途 |
|:---|:---|:---|:---|
| **uiautomator2** | 7.8k | openatx/uiautomator2 | Android UI自动化核心 |
| **DroidRun** | 7.5k | droidrun/droidrun | AI Agent控制Android |
| **objection** | 8.8k | sensepost/objection | Frida自动化/SSL Bypass |
| **Airtest** | 5.4k | AirtestProject/Airtest | 网易自动化框架 |
| **douyin-wss** | - | Airmole/douyin-wss | 抖音私信协议分析 |
| **xianyu-auto** | - | ziling35/xianyu-auto | 闲鱼WebSocket自动回复 |
---
## ⚡ 快速使用
### 1. uiautomator2 - UI自动化
```python
import uiautomator2 as u2
# 连接设备
d = u2.connect("192.168.1.100") # 或 u2.connect("device_id")
# 基础操作
d.app_start("com.tencent.mm") # 启动微信
d.click(500, 1000) # 点击坐标
d.xpath('//*[@text="发送"]').click() # 点击文字
d.send_keys("Hello") # 输入文字
d.screenshot() # 截图
d.dump_hierarchy() # 获取UI树
```
### 2. DroidRun - AI Agent控制
```python
from droidrun import DroidAgent, AdbTools
from llama_index.llms.deepseek import DeepSeek
# 初始化
tools = AdbTools()
llm = DeepSeek(api_key="...", model="deepseek-chat")
# 创建Agent
agent = DroidAgent(
goal="打开微信给张三发消息你好",
llm=llm,
tools=tools
)
# 执行
result = await agent.run()
```
### 3. 闲鱼WebSocket - 私信自动回复
```python
import websockets
from utils.xianyu_utils import generate_sign, decrypt
# WebSocket连接
async with websockets.connect(WEBSOCKET_URL, extra_headers=headers) as ws:
# 接收消息
message = await ws.recv()
data = decrypt(message)
# 发送消息
await ws.send(json.dumps({
"type": "send_msg",
"content": "你好"
}))
```
### 4. 抖音私信协议
```json
// 文本消息格式
{
"type": 0,
"text": "消息内容",
"aweType": 700
}
// 视频分享格式
{
"aweType": 800,
"itemId": "视频ID"
}
```
---
## 📊 技术对比
| 特性 | uiautomator2 | DroidRun | Airtest |
|:---|:---|:---|:---|
| **控制方式** | UI自动化 | AI + UI | UI + 图像识别 |
| **学习成本** | 低 | 中 | 中 |
| **稳定性** | 高 | 中 | 高 |
| **灵活性** | 中 | 高 | 高 |
| **AI支持** | ❌ | ✅ | ❌ |
| **跨平台** | Android | Android/iOS | Android/iOS/Windows |
---
## 🔗 相关文档
- [02-技术架构.md](../docs/02-技术架构.md) - 整体架构设计
- [AI控制方案.md](../../2、架构/AI控制方案.md) - AI Agent方案
- [优化技术方案_v2.md](../../2、架构/优化技术方案_v2.md) - 6周开发计划

254
开发文档/6、后端/github核心代码/架构图.md Normal file
View File

@@ -0,0 +1,254 @@
# 工作手机SDK v3.0 技术架构汇总
> 提取日期：2026-01-26 | 来源：GitHub核心代码分析
---
## 一、整体技术架构
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 工作手机SDK v3.0 技术架构 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 存客宝后端 │
│ │ │
│ │ HTTP REST API │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ 统一服务交互层 (Gateway) │ │
│ │ • 认证鉴权 │ │
│ │ • 请求路由（自动选择最优通道） │ │
│ │ • 负载均衡 │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴───────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 协议通道 │ │ UI通道 │ │ AI Agent通道 │ │
│ │ (优先级1) │ │ (优先级2) │ │ (优先级3) │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ │ │ │ │ │ │
│ │ 闲鱼WSS │ │uiautomator2 │ │ DroidRun │ │
│ │ (xianyu- │ │ (7.8k⭐) │ │ (7.5k⭐) │ │
│ │ auto) │ │ │ │ │ │
│ │ │ │ │ │ + DeepSeek │ │
│ │ 抖音WSS │ │ + Frida │ │ + GPT-4o │ │
│ │ (douyin- │ │ (19.5k⭐) │ │ │ │
│ │ wss) │ │ │ │ 自然语言 │ │
│ │ │ │ objection │ │ 控制 │ │
│ │ sign已解密 │ │ (8.8k⭐) │ │ │ │
│ │ │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └───────────────────────────┴───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Skill引擎 │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ 微信Skill │ │ 抖音Skill │ │ 闲鱼Skill │ │ 小红书Skill│ │ │
│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ WebSocket (wss://) │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Android Agent APP │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ u2-server (HTTP:7912) │ Portal APK (HTTP:8080) │ │ │
│ │ │ • 点击/滑动/输入 │ • Accessibility Service │ │ │
│ │ │ • 截图/UI树 │ • DroidRun专用 │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ Frida Gadget / frida-server │ │ │
│ │ │ • SSL Bypass │ │ │
│ │ │ • Method Hook │ │ │
│ │ │ • HTTP抓包 │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## 二、技术栈对照表
| 层级 | 技术 | GitHub Stars | 用途 | 核心代码文档 |
|:---|:---|:---|:---|:---|
| **AI Agent** | DroidRun | 7.5k⭐ | 自然语言控制手机 | [02-droidrun核心代码.md](02-droidrun核心代码.md) |
| **UI自动化** | uiautomator2 | 7.8k⭐ | Python控制Android | [01-uiautomator2核心代码.md](01-uiautomator2核心代码.md) |
| **抓包Hook** | objection | 8.8k⭐ | Frida自动化/SSL Bypass | [05-objection-Frida自动化.md](05-objection-Frida自动化.md) |
| **闲鱼协议** | xianyu-auto | - | WebSocket私信 | [03-闲鱼WebSocket核心代码.md](03-闲鱼WebSocket核心代码.md) |
| **抖音协议** | douyin-wss | - | WSS私信协议 | [04-抖音私信协议.md](04-抖音私信协议.md) |
| **自动化框架** | Airtest | 5.4k⭐ | 网易开源框架 | 见github-repos/Airtest/ |
---
## 三、核心数据流
```
用户操作 服务端处理 设备端执行
───────── ───────── ─────────
发送微信消息
│
▼
send_message( 路由决策
platform="wechat", ──► 微信无API ──► UI通道 ──────────► uiautomator2
to="张三", │
content="你好" ├─► 搜索联系人
) ├─► 点击进入聊天
├─► 输入消息
└─► 点击发送
发送闲鱼私信
│
▼
send_message( 路由决策
platform="xianyu", ──► 闲鱼有协议 ──► 协议通道 ──────► WebSocket
to="user_xxx", │
content="还在吗" └─► 发送WSS消息
)
复杂任务
│
▼
agent_execute( 路由决策
task="打开淘宝 ──► 复杂任务 ──► AI Agent通道 ──────► DroidRun
搜索iPhone16 │
加入购物车" ├─► LLM规划
) ├─► 调用tap/swipe
└─► 完成任务
```
---
## 四、关键代码路径
### 4.1 uiautomator2调用链
```
Python SDK 设备端
───────── ─────────
d = u2.connect()
│
├─► AdbHTTPConnection.connect()
│ └─► adbutils.create_connection(TCP, 9008)
│
d.click(x, y)
│
├─► _jsonrpc_call("click", [x, y])
│ └─► HTTP POST /jsonrpc/0
│ │
│ ▼
│ u2.jar (设备端)
│ │
│ └─► UiDevice.click(x, y)
```
### 4.2 DroidRun调用链
```
Python SDK 设备端
───────── ─────────
agent = DroidAgent(goal="...")
│
result = await agent.run()
│
├─► LLM生成步骤
│ └─► "1. get_ui_tree() 2. tap(3) 3. input_text(...)"
│
├─► tools.get_ui_tree()
│ └─► PortalClient.dump_hierarchy()
│ └─► HTTP GET /hierarchy
│ │
│ ▼
│ Portal APK
│ │
│ └─► AccessibilityService
│
├─► tools.tap(3)
│ └─► PortalClient.tap(x, y)
│
└─► tools.finish(success=True)
```
### 4.3 Frida SSL Bypass调用链
```
Python SDK 设备端
───────── ─────────
frida_svc.ssl_bypass(device, package)
│
├─► frida.attach(package)
│ └─► 连接到frida-server/gadget
│
├─► session.create_script(ssl_bypass.js)
│ │
│ ▼
│ Java.perform() ──────────────────────────────► APP进程
│ │ │
│ ├─► Hook TrustManagerImpl.verifyChain │
│ ├─► Hook OkHttp3.CertificatePinner.check │
│ └─► Hook WebViewClient.onReceivedSslError │
│ │
└─► script.load() ▼
证书校验被绕过
HTTPS可抓包
```
---
## 五、部署架构
```
┌─────────────────────────────┐
│ 负载均衡(SLB) │
│ (阿里云/腾讯云) │
└──────────────┬──────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ SDK节点1 │ │ SDK节点2 │ │ SDK节点N │
│ FastAPI │ │ FastAPI │ │ FastAPI │
│ 4核8G │ │ 4核8G │ │ 4核8G │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────────┼───────────────────┘
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
┌──────▼──────┐ ┌───────▼───────┐ ┌───────▼───────┐
│ Redis │ │ MongoDB │ │ MinIO │
│ 2核4G │ │ 4核8G │ │ 4核8G │
└─────────────┘ └───────────────┘ └───────────────┘
设备层：
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 手机1 │ │ 手机2 │ │ 手机N │
│ 红米11 │ │ 红米13 │ │ ... │
│ │ │ │ │ │
│ Agent APP │ │ Agent APP │ │ Agent APP │
│ + u2 │ │ + u2 │ │ + u2 │
│ + Frida │ │ + Frida │ │ + Frida │
└─────────────┘ └─────────────┘ └─────────────┘
```
---
## 六、GitHub仓库下载位置
```
开发文档/github-repos/
├── uiautomator2/ ← openatx/uiautomator2 (7.8k⭐)
├── droidrun/ ← droidrun/droidrun (7.5k⭐)
├── objection/ ← sensepost/objection (8.8k⭐)
├── Airtest/ ← AirtestProject/Airtest (5.4k⭐)
├── frida-tools/ ← frida/frida-tools
├── xianyu-auto/ ← ziling35/xianyu-auto
└── douyin-wss/ ← Airmole/douyin-wss
```

44
开发文档/6、后端/后端规范与代码汇总.md Normal file
View File

@@ -0,0 +1,44 @@
# 工作手机SDK v3.0 - 后端规范与代码汇总
> 合并自《后端开发规范》+《核心代码汇总》| 更新：2026-02-07
---
## Part A：后端开发规范摘要
### 技术栈
| 组件 | 技术 | 版本 |
|------|------|------|
| 开发语言 | Python | 3.11+ |
| Web 框架 | FastAPI | 0.110+ |
| WebSocket | websockets | 12.0 |
| 数据库 | MongoDB | 6.0+ |
| 缓存 | Redis | 7.x |
### 项目结构要点
- **routers/**：devices、execute、capture、scripts
- **services/**：device_service、command_service、capture_service、script_executor
- **websocket/**：hub、handlers、protocol
- **scripts/**：base、registry、executor、wechat/douyin/xhs
### 代码风格与约定
- 异步优先（async/await）；类型注解；Pydantic 校验；日志与错误码统一。
---
## Part B：核心代码汇总摘要
| 技术 | 用途 | 详细位置 |
|------|------|----------|
| uiautomator2 | UI 自动化 | [github核心代码/01-uiautomator2核心代码.md](github核心代码/01-uiautomator2核心代码.md) |
| DroidRun | AI Agent | [github核心代码/02-droidrun核心代码.md](github核心代码/02-droidrun核心代码.md) |
| 闲鱼 WebSocket | 闲鱼协议 | [github核心代码/03-闲鱼WebSocket核心代码.md](github核心代码/03-闲鱼WebSocket核心代码.md) |
| 抖音私信 | 抖音协议 | [github核心代码/04-抖音私信协议.md](github核心代码/04-抖音私信协议.md) |
| objection/Frida | SSL Bypass | [github核心代码/05-objection-Frida自动化.md](github核心代码/05-objection-Frida自动化.md) |
**完整实现**：见 [SDK服务端实现文档.md](SDK服务端实现文档.md)、[Agent端技能实现文档.md](Agent端技能实现文档.md)。
**历史技术文档**：见 [docs/](docs/) 目录。

36
开发文档/7、数据库/README.md Normal file
View File

@@ -0,0 +1,36 @@
# 7、数据库
**项目**：工作手机SDK v3.0（MongoDB workphone_sdk、Redis 缓存/队列、MySQL 存客宝业务库；数据闭环已跑通。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 97%；M10 数据与存储 100%。完整数据层设计见 [2、架构/技术选型与数据库.md](../2、架构/技术选型与数据库.md) Part B。进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准。
---
## 首次建库与索引
本地 MongoDB 需认证时，在 `sdk/app` 下设置环境变量或 `.env`：
- `MONGO_URI=mongodb://admin:admin123@localhost:27017`
- 执行：`cd sdk/app && python3 scripts/init_db.py`
详见 [8、部署/本地环境凭证.md](../8、部署/本地环境凭证.md)。
---
## 卡若AI Skill 路由（数据库由金盾负责）
| 关键词 | 执行人 | Skill | 说明 |
|--------|--------|-------|------|
| bill、数据账本、私域银行数据、数据协同 | 金盾 | 私域银行数据账本 | 存客宝+工作手机数据契约与协同 |
| 工作手机数据库、workphone_sdk、devices | 金盾 | 工作手机数据管理 | MongoDB 集合、索引、初始化 |
| 数据库/MySQL/备份/清理 | 金盾 | 数据库管理 | 运维、清理、备份 |
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [数据库管理规范.md](数据库管理规范.md) | 数据库管理规范 |
| [数据库设计文档.md](数据库设计文档.md) | 数据库设计文档 |

62
开发文档/7、数据库/数据库管理规范.md Normal file
View File

@@ -0,0 +1,62 @@
# 数据库管理规范 (DB Specs) - 智能自生长文档
> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“DBA”角色，生成安全的 SQL/Mongo 脚本与 ER 图。
## 1. 基础上下文 (The Two Basic Files)
### 1.1 角色档案：卡若 (Karuo)
- **核心**：数据无价，安全第一。
- **选型**：Mongo (业务+向量) + MySQL (事务/辅助)。
### 1.2 操作规范
- **导入**：必须带 `--resumeFrom` 和 `--drop` (防止重复/中断)。
- **命名**：`traffic_pools` (严禁 `traffic_words`)。
## 2. 数据库规范核心 (Master Content)
### 2.1 选型策略
- **MongoDB**:
- **业务数据**：用户、日志、流量池。
- **AI 向量**：存储 Embedding 向量 (Atlas Vector Search)。
- **MySQL**: 强事务资金流水 (如需)。
### 2.2 连接信息 (Internal)
- **卡若私域**: 10.88.182.62:3306
- **腾讯云**: 56b4c23f6853c...:14413
- **Mongo**: (Env Config)
### 2.3 集合命名
- `users`: 用户
- `scenarios`: 场景获客
- `traffic_pools`: 流量池 (含 `embedding` 字段)
- `orders`: 分润订单
- `knowledge_base`: AI 知识库 (含 `embedding` 字段)
### 2.4 AI 向量索引 (Vector Index)
- **字段**：通常命名为 `embedding` 或 `vector`。
- **索引类型**：使用 KNN 或 ANN 索引 (如 HNSW)。
- **查询**：支持 `$vectorSearch` (Mongo Atlas) 或类似语义检索语法。
### 2.5 安全与索引
- **安全**：密码 Hash (Argon2), 手机号加密。
- **常规索引**：`openid`, `mobile`, `inviter_id` 必建索引。
## 3. AI 协作指令 (Expanded Function)
**角色**：你是我（卡若）的 DBA。
**任务**：
1. **脚本生成**：生成 MongoDB 聚合查询 (`aggregate`) 或 MySQL DDL/DML。
2. **向量配置**：生成向量索引的定义 JSON。
3. **结构可视化**：用 Mermaid 生成 ER 图。
### 示例 Mermaid (ER图)
```mermaid
erDiagram
User ||--o{ Order : places
User ||--o{ TrafficPool : owns
TrafficPool {
string content
array embedding "Vector[1536]"
}
Order {
string orderId
float amount
}
```

100
开发文档/7、数据库/数据库设计文档.md Normal file
View File

@@ -0,0 +1,100 @@
# 数据库设计文档
> **更新**: 2026-02-06
---
## 一、数据库概览
| 数据库 | 类型 | 端口 | 用途 |
|--------|------|------|------|
| MongoDB (workphone_sdk) | NoSQL | 27017 | SDK设备/消息/日志数据 |
| MySQL (cunkebao) | SQL | 3307 | 存客宝业务数据 |
| Redis | 缓存 | 6380 | 会话/队列/缓存 |
---
## 二、MongoDB - 工作手机SDK
### 2.1 devices 集合（设备信息）
```json
{
"_id": "device_001",
"name": "红米13-工作手机",
"model": "Redmi 13",
"android_version": "14",
"resolution": "1080x2400",
"project_id": "cunkebao_main",
"status": "online",
"last_heartbeat": "2026-02-06T12:30:00Z",
"installed_apps": ["com.tencent.mm", "com.ss.android.ugc.aweme"],
"created_at": "2026-02-06T12:00:00Z"
}
```
### 2.2 messages 集合（消息记录）
```json
{
"_id": ObjectId,
"device_id": "device_001",
"platform": "wechat",
"direction": "outgoing",
"to_id": "wxid_xxx",
"content": "你好",
"msg_type": "text",
"status": "sent",
"channel_used": "sdk_control",
"created_at": "2026-02-06T12:30:00Z"
}
```
### 2.3 tasks 集合（任务日志）
```json
{
"_id": ObjectId,
"device_id": "device_001",
"task_type": "send_message",
"platform": "wechat",
"params": {},
"result": {},
"status": "completed",
"channel": "sdk_control",
"duration_ms": 2500,
"created_at": "2026-02-06T12:30:00Z"
}
```
---
## 三、MySQL - 存客宝业务
### 核心表
| 表名 | 说明 |
|------|------|
| ckb_user | 用户表 |
| ckb_admin | 管理员表 |
| ckb_device | 设备表 |
| ckb_wechat_account | 微信账号表 |
| ckb_contact | 联系人表 |
| ckb_message | 消息表 |
| ckb_group | 群聊表 |
| ckb_tag | 标签表 |
| ckb_moments | 朋友圈表 |
| ckb_task | 任务表 |
> 详细表结构见 `Server/sql.sql`
---
## 四、Redis 用途
| Key模式 | 说明 | TTL |
|---------|------|-----|
| `device:{id}:status` | 设备在线状态 | 60s |
| `session:{token}` | 用户会话 | 24h |
| `task:queue` | 任务队列 | - |
| `rate:{device}:{api}` | 接口限流 | 60s |

24
开发文档/8、部署/README.md Normal file
View File

@@ -0,0 +1,24 @@
# 8、部署
**项目**：工作手机SDK v3.0（Docker部署 + 设备端Hook安装 + 多设备批量部署）
**规则**：本目录除本 README 外最多 **3 个主文档**。
**当前状态**：基础Docker部署100%；Hook安装部署已编写。进度以 [开发进度总表](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [本地Docker部署指南.md](本地Docker部署指南.md) | 本地Docker部署（含原部署流程提示词内容） |
| [本地环境凭证.md](本地环境凭证.md) | 账号、端口、访问地址 |
| [设备端Hook安装部署.md](设备端Hook安装部署.md) | **新增**：Frida安装+Agent(Hook模式)+多设备批量部署 |
---
## 合并记录
- 2026-02-10: `部署流程与提示词.md` 内容合并入 `本地Docker部署指南.md` 附录
- 2026-02-10: 新增 `设备端Hook安装部署.md`

168
开发文档/8、部署/本地Docker部署指南.md Normal file
View File

@@ -0,0 +1,168 @@
# 本地Docker部署指南
> **更新**: 2026-02-06
> **适用**: Apple Silicon Mac (M4 Pro)
> **目的**: 本地开发测试环境，不影响线上
---
## 一、环境要求
| 组件 | 版本 | 说明 |
|------|------|------|
| Docker Desktop | 4.0+ | Apple Silicon版 |
| Node.js | 20+ | 前端构建 |
| pnpm | 9+ | 包管理器 |
| Python | 3.10+ | SDK服务 |
| ADB | latest | 设备调试 |
---
## 二、端口规划
| 端口 | 服务 | Docker容器名 | 状态 |
|------|------|-------------|------|
| 3000 | 存客宝前端 | cunkebao-web | 待部署 |
| 3001 | 触客宝前端 | touchkebao-web | 待部署 |
| 8081 | 后端API | cunkebao-server | 待部署 |
| 8899 | 工作手机SDK | workphone-sdk | ✅ 运行中 |
| 3307 | MySQL | cunkebao-mysql | 待部署 |
| 6380 | Redis | cunkebao-redis | 待部署 |
| 27017 | MongoDB | datacenter_mongodb | ✅ 运行中 |
| 5554 | Android模拟器 | 本地进程 | ✅ 运行中 |
### 已被占用的端口（避免冲突）
| 端口 | 占用者 |
|------|--------|
| 8080 | 微信 |
| 8000 | Portainer |
| 9443 | Portainer |
---
## 三、部署步骤
### 3.1 启动基础设施
```bash
# 确保MongoDB运行
docker start datacenter_mongodb
# 启动工作手机SDK
cd /Users/karuo/Documents/开发/2、私域银行/工作手机/sdk
docker-compose up -d
```
### 3.2 启动存客宝系统
```bash
cd /Users/karuo/Documents/开发/2、私域银行/cunkebao_v3
# 构建并启动所有服务
docker-compose up -d --build
# 仅启动数据库（开发模式）
docker-compose up -d mysql redis
```
### 3.3 启动Android模拟器
```bash
# 启动红米13工作手机模拟器
export ANDROID_SDK_ROOT="/usr/local/share/android-commandlinetools"
$ANDROID_SDK_ROOT/emulator/emulator -avd Redmi13_WorkPhone -gpu auto -memory 4096 &
# 等待启动完成
adb wait-for-device
adb shell getprop sys.boot_completed # 返回1表示启动完成
```
### 3.4 开发模式（前端热重载）
```bash
# 后端通过Docker运行
docker-compose up -d mysql redis server
# 前端本地开发
cd Cunkebao && pnpm dev # http://localhost:5173
cd Touchkebao && pnpm dev # http://localhost:5174
```
---
## 四、数据库初始化
### MySQL
```bash
# 自动导入（docker-compose会自动执行sql.sql）
docker-compose up -d mysql
# 手动导入
docker exec -i cunkebao-mysql mysql -u cunkebao -pcunkebao123 cunkebao < Server/sql.sql
```
### MongoDB
```bash
# 已有datacenter_mongodb运行在27017
# SDK自动创建workphone_sdk数据库
```
---
## 五、验证部署
```bash
# 运行检查脚本
bash /Users/karuo/Documents/个人/卡若AI/04_卡火（火）/_团队成员/火炬/存客宝项目管理/scripts/check_system.sh
# 手动验证
curl http://localhost:8899/health # SDK健康
curl http://localhost:8081 # 后端API
curl http://localhost:3000 # 存客宝前端
curl http://localhost:3001 # 触客宝前端
adb devices # 模拟器
```
---
## 六、常用命令
```bash
# 启动所有
./start.sh start
# 停止所有
./start.sh stop
# 查看日志
docker logs -f workphone-sdk
docker logs -f cunkebao-server
# 重建镜像
docker-compose build --no-cache
# 清理
docker system prune -f
```
---
## 附：部署流程与提示词（合并自原独立文档）
### CI/CD 与 Webhook（可选）
- Next.js项目：GitHub Webhook → 宝塔 → `git pull` / `npm run build` / `pm2 reload`
- 工作手机当前以Docker一键部署为主
### 本地全链路执行清单
**阶段1：基础环境** — `docker start datacenter_mongodb`；SDK：`cd sdk && ./scripts/start_sdk.sh`；验证 `curl http://localhost:8899/health`
**阶段2：工作手机连接** — `adb devices`；Agent：`cd sdk/agent && python agent.py`；验证设备online
**阶段3：全链路测试** — `POST /api/v3/unified/message/send`；检查MongoDB落库；存客宝回传验证
**验收**：所有服务可访问、设备状态同步、微信任务回传、三大闭环正常

79
开发文档/8、部署/本地环境凭证.md Normal file
View File

@@ -0,0 +1,79 @@
# 本地环境凭证登记表
> **统一测试账号**: 15880802661 / kr123456
> **所有本地后台均使用此账号登录**
---
## 一、访问地址
| 服务 | 地址 | 状态 |
| --------- | -------------------------------------------------------- | --- |
| 存客宝前端 | [http://localhost:3000](http://localhost:3000) | ✅ |
| 触客宝前端 | [http://localhost:3001](http://localhost:3001) | ✅ |
| 工作手机SDK | [http://localhost:8899](http://localhost:8899) | ✅ |
| SDK API文档 | [http://localhost:8899/docs](http://localhost:8899/docs) | ✅ |
## 二、数据库
| 数据库 | 地址 | 端口 | 用户名 | 密码 | 库名 |
| -------------- | --------- | ----- | -------- | ----------- | ------------- |
| MySQL(MariaDB) | localhost | 3307 | root | cunkebao123 | cunkebao |
| MySQL(MariaDB) | localhost | 3307 | cunkebao | cunkebao123 | cunkebao |
| MongoDB | localhost | 27017 | admin | admin123 | workphone_sdk |
| Redis | localhost | 6380 | (无密码) | - | - |
**SDK 用 MongoDB**（需认证时在 `sdk/app/.env` 或环境变量中配置）：
- `MONGO_URI=mongodb://admin:admin123@localhost:27017`
- 首次建库/索引：`cd sdk/app && python3 scripts/init_db.py`
## 三、后台登录
| 系统 | 地址 | 账号 | 密码 |
| ------- | ---------------------------------------------- | ----------------------------- | -------- |
| 存客宝后台 | [http://localhost:3000](http://localhost:3000) | 15880802661 | kr123456 |
| 触客宝后台 | [http://localhost:3001](http://localhost:3001) | 15880802661 | kr123456 |
| 超级管理员 | [http://localhost:3002](http://localhost:3002) | 15880802661 | kr123456 |
| SDK API | [http://localhost:8899](http://localhost:8899) | API Key: workphone-secret-key | - |
## 四、手机设备
| 设备 | 连接方式 | 地址 |
| --------------- | ------------------------------------------- | ------------- |
| 红米13模拟器 | ADB | emulator-5554 |
| Agent WebSocket | ws://localhost:8899/ws/device/emulator-5554 | |
| 心跳间隔 | config.json heartbeat_interval 或 --heartbeat 5/10/30 | 默认 10s |
## 五、线上参考（只读，不要修改）
| 项目 | 地址 |
| ------- | --------------------------------------- |
| 线上MySQL | 56b4c23f6853c.gz.cdb.myqcloud.com:14413 |
| 线上库名 | cunkebao_v3 |
## 六、端口总表
| 端口 | 服务 | 备注 |
| ----- | --------------- | -------------- |
| 3000 | 存客宝前端 | Vite dev |
| 3001 | 触客宝前端 | Vite dev |
| 3307 | MySQL | Docker MariaDB |
| 6380 | Redis | Docker |
| 8899 | 工作手机SDK | 本地Python |
| 27017 | MongoDB | Docker |
| 5554 | Android模拟器 | AVD |
| 8000 | Portainer | Docker管理 |
| 9443 | Portainer HTTPS | Docker管理 |

383
开发文档/8、部署/设备端Hook安装部署.md Normal file
View File

@@ -0,0 +1,383 @@
# 设备端Hook安装部署指南
> 更新：2026-02-10 | 真机安装Frida + 机擎Agent(Hook模式)的完整流程
---
## 一、部署概览
### 1.1 部署模式
| 模式 | 说明 | Root | 设备要求 | 推荐 |
|------|------|:----:|----------|:----:|
| 基础模式 | 仅u2通道，免Root | ❌ | Android 7+ | ✅ 日常 |
| Hook模式(Root) | u2+Frida，需Root | ✅ | Android 7+ + Magisk | ✅ 增强 |
| Hook模式(Gadget) | u2+Gadget，免Root | ❌ | Android 7+ | ⚠️ 备选 |
### 1.2 安装流程总览
```
准备工作（10分钟）
│
├── Root方案 ──────────────────┐
│ 1. 解锁Bootloader │
│ 2. 刷入Magisk │
│ 3. 安装frida-server │
│ │
└── 免Root方案 ────────────────┐
1. 准备Gadget内嵌APK │
2. 安装修改后的微信 │
│
安装机擎Agent（5分钟）─────────────┘
│
├── Termux安装
├── Agent安装（curl脚本）
├── 配置文件（含Hook配置）
└── 启动Agent
│
验证（5分钟）
├── 检查Agent连接
├── 检查Frida连接
├── 检查Hook脚本加载
└── 测试发消息
```
---
## 二、Root方案安装
### 2.1 前置准备
| 步骤 | 操作 | 验证 |
|:----:|------|------|
| 1 | 解锁Bootloader | `adb reboot bootloader && fastboot oem unlock` |
| 2 | 安装Magisk | 刷入Magisk补丁后的boot.img |
| 3 | 验证Root | `adb shell su -c id` → 显示 `uid=0(root)` |
| 4 | 关闭SELinux | `adb shell su -c setenforce 0` |
### 2.2 安装Frida Server
```bash
#!/bin/bash
# install_frida.sh — 一键安装frida-server
FRIDA_VERSION="16.5.6"
# 自动检测设备架构
ARCH=$(adb shell getprop ro.product.cpu.abi | tr -d '\r')
case $ARCH in
arm64-v8a) FRIDA_ARCH="arm64" ;;
armeabi-v7a) FRIDA_ARCH="arm" ;;
x86_64) FRIDA_ARCH="x86_64" ;;
x86) FRIDA_ARCH="x86" ;;
*) echo "不支持的架构: $ARCH"; exit 1 ;;
esac
echo "设备架构: $ARCH → Frida架构: $FRIDA_ARCH"
# 下载frida-server
DOWNLOAD_URL="https://github.com/frida/frida/releases/download/${FRIDA_VERSION}/frida-server-${FRIDA_VERSION}-android-${FRIDA_ARCH}.xz"
echo "下载: $DOWNLOAD_URL"
curl -L -o frida-server.xz "$DOWNLOAD_URL"
xz -d frida-server.xz
# 推送到设备（改名防检测）
adb push frida-server /data/local/tmp/wp-agent
adb shell "su -c 'chmod 755 /data/local/tmp/wp-agent'"
# 验证
echo "验证版本:"
adb shell "su -c '/data/local/tmp/wp-agent --version'"
echo ""
echo "✅ frida-server安装完成"
echo "启动命令: adb shell \"su -c '/data/local/tmp/wp-agent -l 0.0.0.0:27042 &'\""
```
### 2.3 启动Frida Server
```bash
# 启动（后台运行）
adb shell "su -c '/data/local/tmp/wp-agent -l 0.0.0.0:27042 -D &'"
# 验证运行
adb shell "su -c 'pidof wp-agent'"
# 输出进程PID即为成功
# 设置开机自启（可选）
adb shell "su -c 'echo \"/data/local/tmp/wp-agent -l 0.0.0.0:27042 -D &\" > /data/adb/service.d/wp-agent.sh'"
adb shell "su -c 'chmod 755 /data/adb/service.d/wp-agent.sh'"
```
---
## 三、免Root方案（Frida Gadget）
### 3.1 准备Gadget内嵌APK
```bash
# 安装objection
pip3 install objection
# 提取微信APK
adb shell pm path com.tencent.mm
adb pull /data/app/.../base.apk wechat.apk
# 注入Gadget
objection patchapk -s wechat.apk -a arm64 \
--gadget-version 16.5.6 \
--skip-resources
# 输出: wechat.objection.apk
# 卸载原微信并安装修改版
adb uninstall com.tencent.mm
adb install wechat.objection.apk
```
### 3.2 Gadget配置
创建 Gadget 配置文件使其自动连接：
```json
// /data/local/tmp/wp-gadget-config.json
{
"interaction": {
"type": "listen",
"address": "0.0.0.0",
"port": 27042,
"on_load": "resume"
}
}
```
---
## 四、安装机擎Agent（Hook模式）
### 4.1 Termux安装
```bash
# 安装Termux（从F-Droid）
adb install termux.apk
# 进入Termux
adb shell am start -n com.termux/.HomeActivity
# 在Termux中执行
pkg update && pkg install -y python openssh
# 设置SSH（便于远程管理）
sshd
```
### 4.2 Agent安装
```bash
# 在Termux中执行一键安装脚本
curl -sSL https://your-server.com/install_agent.sh | bash
# 或手动安装
pip install uiautomator2 frida-tools websockets aiohttp pydantic
# 下载Agent代码
git clone https://github.com/your-repo/workphone-agent.git
cd workphone-agent
```
### 4.3 配置文件
```bash
# 创建配置目录
mkdir -p /sdcard/workphone/scripts
# 创建配置文件
cat > /sdcard/workphone/config.json << 'EOF'
{
"device_id": "phone_001",
"device_name": "工作手机-001",
"server_url": "wss://your-server.com:8899/ws",
"heartbeat_interval": 10,
"reconnect_interval": 5,
"hook": {
"enabled": true,
"framework": "frida-server",
"frida_server_path": "/data/local/tmp/wp-agent",
"frida_server_port": 27042,
"auto_start": true,
"default_scopes": ["com.tencent.mm"],
"scripts_dir": "/sdcard/workphone/scripts",
"scripts_cache_dir": "/data/local/tmp/wp-scripts"
},
"u2": {
"port": 7912,
"timeout": 30
}
}
EOF
```
### 4.4 启动Agent
```bash
# 启动（前台运行，看日志）
cd workphone-agent
python agent.py --config /sdcard/workphone/config.json
# 后台运行
nohup python agent.py --config /sdcard/workphone/config.json \
> /sdcard/workphone/agent.log 2>&1 &
# 开机自启（Termux Boot）
mkdir -p ~/.termux/boot
cat > ~/.termux/boot/start_agent.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash
sleep 10
cd ~/workphone-agent
python agent.py --config /sdcard/workphone/config.json &
EOF
chmod +x ~/.termux/boot/start_agent.sh
```
---
## 五、多设备连接到服务器
### 5.1 服务器端部署
```bash
# 在服务器上（Docker方式）
git clone https://github.com/your-repo/workphone-sdk.git
cd workphone-sdk/sdk
# 配置
cp .env.example .env
# 编辑 .env:
# MONGODB_URI=mongodb://mongo:27017/workphone_sdk
# REDIS_URI=redis://redis:6379
# MAX_DEVICES=100
# JWT_SECRET=your-secret-key
# 启动
docker-compose up -d
# 验证
curl http://localhost:8899/health
# {"status":"ok","devices_online":0}
```
### 5.2 多设备配置
每台手机只需修改 `config.json` 中的 `device_id` 和 `device_name`：
```bash
# 手机1
{
"device_id": "phone_001",
"device_name": "工作手机-001",
"server_url": "wss://server-a.yourcompany.com:8899/ws",
...
}
# 手机2
{
"device_id": "phone_002",
"device_name": "工作手机-002",
"server_url": "wss://server-a.yourcompany.com:8899/ws",
...
}
# 手机101（连另一台服务器）
{
"device_id": "phone_101",
"device_name": "工作手机-101",
"server_url": "wss://server-b.yourcompany.com:8899/ws",
...
}
```
### 5.3 批量部署脚本
```bash
#!/bin/bash
# batch_deploy.sh — 批量部署Agent到多台设备
DEVICES=$(adb devices | grep -v "List" | grep "device$" | cut -f1)
SERVER_URL="wss://server-a.yourcompany.com:8899/ws"
COUNTER=1
for SERIAL in $DEVICES; do
DEVICE_ID="phone_$(printf '%03d' $COUNTER)"
DEVICE_NAME="工作手机-$(printf '%03d' $COUNTER)"
echo "==== 部署设备: $SERIAL → $DEVICE_ID ===="
# 1. 安装frida-server
adb -s $SERIAL push frida-server /data/local/tmp/wp-agent
adb -s $SERIAL shell "su -c 'chmod 755 /data/local/tmp/wp-agent'"
adb -s $SERIAL shell "su -c '/data/local/tmp/wp-agent -l 0.0.0.0:27042 -D &'"
# 2. 生成配置
cat > /tmp/config_${DEVICE_ID}.json << EOF
{
"device_id": "${DEVICE_ID}",
"device_name": "${DEVICE_NAME}",
"server_url": "${SERVER_URL}",
"heartbeat_interval": 10,
"hook": {
"enabled": true,
"framework": "frida-server",
"frida_server_path": "/data/local/tmp/wp-agent",
"frida_server_port": 27042,
"auto_start": true,
"default_scopes": ["com.tencent.mm"]
}
}
EOF
# 3. 推送配置
adb -s $SERIAL shell "mkdir -p /sdcard/workphone"
adb -s $SERIAL push /tmp/config_${DEVICE_ID}.json /sdcard/workphone/config.json
# 4. 安装Agent（假设已有install脚本）
adb -s $SERIAL shell "su -c 'curl -sSL https://your-server.com/install_agent.sh | bash'"
echo "✅ $DEVICE_ID 部署完成"
COUNTER=$((COUNTER + 1))
done
echo ""
echo "==== 批量部署完成: $((COUNTER - 1)) 台设备 ===="
```
---
## 六、验证清单
| 序号 | 验证项 | 命令 | 期望结果 |
|:----:|--------|------|----------|
| 1 | Agent进程 | `adb shell ps \| grep agent` | 进程运行中 |
| 2 | Frida进程 | `adb shell "su -c 'pidof wp-agent'"` | 返回PID |
| 3 | WebSocket连接 | 查看服务端日志 | `device_001 connected` |
| 4 | 设备在线 | `curl http://server:8899/api/v3/devices` | 设备在列表中 |
| 5 | Hook能力 | `curl http://server:8899/api/v3/devices/{id}/modules` | `supports_hook: true` |
| 6 | 脚本加载 | 服务端发送reload指令 | 脚本加载成功 |
| 7 | 发消息测试 | `curl -X POST http://server:8899/api/v3/message/send ...` | 消息发出 |
| 8 | 收消息测试 | Hook事件流 | 实时收到消息事件 |
---
## 七、故障排查
| 问题 | 原因 | 解决 |
|------|------|------|
| Agent连接不上服务器 | 网络/防火墙 | 检查8899端口，ping服务器 |
| Frida无法启动 | 无Root权限 | 检查Magisk，`su -c id` |
| Frida attach失败 | 微信未运行 | 先启动微信 |
| Hook脚本加载失败 | 微信版本不兼容 | 更新脚本适配 |
| 设备频繁离线 | 心跳超时 | 检查网络稳定性 |
| 内存不足 | 脚本占用过多 | 减少Hook点 |

17
开发文档/9、手册/README.md Normal file
View File

@@ -0,0 +1,17 @@
# 9、手册
**项目**：工作手机SDK v3.0（使用与操作以 SDK 操作手册、微信 E2E 验证为主；存客宝通过 API/SDK 调用。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 100%；微信消息 E2E 可按验证指南执行（需本地 SDK+Agent+模拟器微信）。进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [SDK操作手册.md](SDK操作手册.md) | 一键启动、检查、验证（必看） |
| [微信消息E2E验证指南.md](微信消息E2E验证指南.md) | 微信发消息端到端验证 |
| [使用与落地方案.md](使用与落地方案.md) | 使用说明与落地方案要点 |

96
开发文档/9、手册/SDK操作手册.md Normal file
View File

@@ -0,0 +1,96 @@
# 工作手机 SDK 操作手册
> **唯一入口**：所有命令可直接复制执行，路径以「工作手机」项目根目录为基准
---
## 一、快速启动
### 1.1 方式一：一键脚本（推荐）
```bash
# 进入 sdk 目录后执行
cd sdk
./scripts/start_sdk.sh
```
脚本会自动：启动 SDK 服务（8899）、检测模拟器并启动 Agent。
### 1.2 方式二：手动分步
```bash
# 1. 启动 SDK 服务
cd sdk/app
python3 -m uvicorn main:app --host 0.0.0.0 --port 8899
# 2. 另开终端，启动 Agent（需模拟器已运行）
cd sdk/agent
python3 agent.py -d emulator-5554 -s ws://127.0.0.1:8899/ws/device --heartbeat 10
```
---
## 二、状态检查
```bash
cd sdk
./scripts/check_sdk.sh
```
或手动验证：
```bash
# SDK 健康
curl -s localhost:8899/health | python3 -m json.tool
# 在线设备数
curl -s localhost:8899/health | python3 -c "import json,sys; d=json.load(sys.stdin); print('devices_online:', d.get('devices_online',0))"
```
---
## 三、微信消息 E2E 验证
**前置**：SDK 运行、Agent 已连接、模拟器微信已登录
```bash
# 方式 1：E2E 脚本
cd sdk/tests
python3 test_wechat_e2e.py
# 方式 2：curl
curl -X POST http://localhost:8899/api/v3/message/send \
-H "Content-Type: application/json" \
-d '{"device_id":"emulator-5554","platform":"wechat","to_id":"文件传输助手","content":"[E2E测试] SDK验证","msg_type":"text"}'
```
---
## 四、访问地址
| 服务 | 地址 |
|------|------|
| SDK API | http://localhost:8899 |
| API 文档 | http://localhost:8899/docs |
| 控制中心 | http://localhost:8899/static/index.html |
---
## 五、路径约定
所有命令假设在「工作手机」项目根目录下执行：
```
工作手机/
├── sdk/
│ ├── app/ # SDK 服务
│ ├── agent/ # Python Agent
│ ├── scripts/ # start_sdk.sh, check_sdk.sh
│ └── tests/ # test_wechat_e2e.py
└── 开发文档/
```
**示例**：若当前在「工作手机」根目录，则：
- `cd sdk` → 进入 sdk
- `cd sdk/app` → 进入 SDK 服务目录
- `cd sdk/agent` → 进入 Agent 目录

50
开发文档/9、手册/会议电视192.168.0.5接入说明.md Normal file
View File

@@ -0,0 +1,50 @@
# 会议电视 192.168.0.5 接入工作手机 SDK 说明
> **设备**：Meetingpad(UHD) | **场所**：家里 | **接入方式**：ADB（仅被控端，不装 Agent）
> **执行日期**：2026-02-09 | **安装前已按《安装前配置检查规范》完成检查**
---
## 一、安装前配置检查结果（已通过）
| 项目 | 要求 | 结果 |
|------|------|------|
| ADB 可达 | ping + adb connect | ✅ 已连接 192.168.0.5:5555 |
| Android 版本 | ≥ 5.0 | ✅ 6.0 |
| CPU 架构 | arm64-v8a / armeabi-v7a | ✅ arm64-v8a |
| 存储 /data | ≥ 500MB | ✅ 约 21.2G 可用 |
| 分辨率 | wm size | ✅ 1920×1080 |
---
## 二、接入方式（无需在会议电视上安装 APK/Agent）
- 工作手机 SDK 通过 **本机 ADB** 控制设备，设备只需 **开启 ADB 并保持连接**。
- 会议电视 **不需要** 安装 Termux 或 Agent，仅作为 ADB 被控端。
- 本机执行：`adb connect 192.168.0.5:5555`（已连接则跳过）。
- 启动 SDK 后，`adb devices` 中的设备会被自动扫描，**device_id 使用 serial**：`192.168.0.5:5555`。
---
## 三、SDK 启动后如何控制
1. **启动 SDK**：`cd sdk && ./scripts/start_sdk.sh` 或 Docker。
2. **确认设备被识别**：`curl http://localhost:8899/health`，查看 `adb_serials` 是否包含 `192.168.0.5:5555`。
3. **调用示例**：
- 截屏：`POST http://localhost:8899/api/v3/adb/devices/192.168.0.5:5555/screenshot`
- 点击：`POST http://localhost:8899/api/v3/adb/devices/192.168.0.5:5555/click`，body `{"x":960,"y":540}`
- 设备信息：`GET http://localhost:8899/api/v3/adb/devices/192.168.0.5:5555`
---
## 四、控制验证（已执行）
- 通过 ADB 直接执行截屏、getprop 均成功，**证明本机可完全通过 ADB 控制该会议电视**。
- SDK 运行时，该设备会被自动纳入，无需额外「安装」步骤。
---
## 五、规范确认
- **每次安装/接入新设备前，必须先执行《安装前配置检查规范》中的检查项，再确定是否安装或接入。**
- 本次接入已先完成配置检查，再确认接入方式并验证控制。

22
开发文档/9、手册/使用与落地方案.md Normal file
View File

@@ -0,0 +1,22 @@
# 使用与落地方案（合并）
> 合并自：使用手册提示词、系统使用手册、落地方案提示词、说明手册提示词 | 更新：2026-02-07
---
## 一、产品简介
工作手机 SDK：通用 APP 抓包控制平台，支持远程控制 Android、自动化操作微信/抖音/小红书等、私有化部署。
## 二、快速开始
- **检查状态**：`curl http://localhost:8899/health`、`adb devices`。
- **发送消息**：存客宝 PHP 调用 `WorkPhoneSDK::getInstance()->wechatSend(...)` 或 API `POST /api/unified/message/send`。
- **一键启动**：见 [SDK操作手册.md](SDK操作手册.md)。
## 三、落地方案要点
- 服务端部署（Docker/环境变量）；设备端 Agent 安装与连接；存客宝对接配置。
- **设备端安装（自动连服务器）**：见 [设备端Agent安装与公司设备说明](设备端Agent安装与公司设备说明.md)（公司设备备注、Termux 安装、会议电视仅 ADB、APP 控制方案）。
- **安装前**：必须先做 [安装前配置检查](安装前配置检查规范.md)。
- 详细使用与说明见原《系统使用手册》《落地方案提示词》《说明手册提示词》（已合并入本目录历史）。

52
开发文档/9、手册/安装前配置检查规范.md Normal file
View File

@@ -0,0 +1,52 @@
# 工作手机 SDK · 安装前配置检查规范
> **原则**：**每一次安装/接入设备前，必须先做配置检查，再确认是否执行安装。**
> 适用于：新设备接入、会议电视/手机/模拟器通过 ADB 纳入 SDK 管控。
---
## 一、检查流程（必须顺序执行）
```
1. 配置检查（本规范） → 2. 确认满足条件 → 3. 执行连接/安装 → 4. 验证控制
```
---
## 二、必检项（目标设备）
| 项目 | 要求 | 检查命令 |
|------|------|----------|
| **ADB 可达** | 本机可 `adb connect <IP>:5555` 且 `adb devices` 显示 device | `ping <IP>`；`adb connect <IP>:5555`；`adb devices` |
| **Android 版本** | 建议 ≥ 5.0（SDK 21），推荐 6.0+ | `adb -s <serial> shell getprop ro.build.version.release` |
| **CPU 架构** | arm64-v8a 或 armeabi-v7a（与 APK/Agent 兼容） | `adb -s <serial> shell getprop ro.product.cpu.abi` |
| **存储空间** | /data 可用 ≥ 500MB（若需装应用或 Agent） | `adb -s <serial> shell df /data` |
| **屏幕/分辨率** | 有 wm size（部分操作依赖分辨率） | `adb -s <serial> shell wm size` |
---
## 三、可选检查（按需）
| 项目 | 说明 |
|------|------|
| 是否已安装存客宝/目标 APP | `adb shell pm list packages \| grep -i 包名` |
| 是否开启 USB 调试/无线调试 | 无法连接时在设备端检查 |
| 与本机是否同网段或路由可达 | 跨网段需路由/VPN |
---
## 四、检查通过后执行
1. **ADB 连接**：`adb connect <IP>:5555`（若未连）。
2. **启动工作手机 SDK**（若未启动）：`cd sdk && ./scripts/start_sdk.sh` 或 Docker。
3. **验证**：
- `curl http://localhost:8899/health` 中应包含 `adb_serials` 含该设备；
- 或 `POST /api/v3/adb/devices/<serial>/screenshot` 能成功截屏即表示可控制。
---
## 五、会议电视/非手机设备说明
- 会议电视（如 Meetingpad）一般无 Termux，**不安装设备端 Agent**，仅作为 **ADB 被控端**。
- 本机运行 SDK，通过 ADB 对会议电视执行截屏、点击、滑动等即可视为「已接入」。
- 配置检查同上，满足 ADB + Android 版本 + 存储即可。

75
开发文档/9、手册/微信消息E2E验证指南.md Normal file
View File

@@ -0,0 +1,75 @@
# 微信消息 E2E 端到端验证指南
> 对应「遗留与建议」高优先级项：跑一条完整发消息任务并验证回传
> 完整操作见 [SDK操作手册.md](SDK操作手册.md)
---
## 一、前置条件
| 条件 | 检查方式 |
|------|----------|
| SDK 运行 | `curl localhost:8899/health` → devices_online ≥ 1 |
| Agent 连接 | `python3 agent.py -d emulator-5554 -s ws://127.0.0.1:8899/ws/device` |
| 模拟器 + 微信 | 微信已登录，建议用「文件传输助手」测试 |
| 超时配置 | 发消息服务端 60s、客户端 90s（微信操作较慢） |
---
## 二、验证命令
> 以「工作手机」项目根目录为基准
```bash
# 方式1：运行 E2E 脚本
cd sdk/tests
python3 test_wechat_e2e.py
# 方式2：直接 curl
curl -X POST http://localhost:8899/api/v3/message/send \
-H "Content-Type: application/json" \
-d '{
"device_id": "emulator-5554",
"platform": "wechat",
"to_id": "文件传输助手",
"content": "[E2E测试] 工作手机SDK验证",
"msg_type": "text"
}'
```
---
## 三、预期结果
**成功**：
```json
{
"code": 200,
"data": {"success": true, "message_id": "wx_xxx", "error": null},
"channel_used": "sdk_control"
}
```
**常见失败**：
| 现象 | 原因 | 处理 |
|------|------|------|
| 设备响应超时 | 操作超 60s 或 Agent 未响应 | 重启 SDK 使 60s 生效；检查 Agent 日志 |
| 设备不在线 | Agent 未连接 | 启动 Agent |
| 未找到联系人 | to_id 拼写错误 | 使用「文件传输助手」或已存在的联系人 |
---
## 四、超时与可观测性（已实现）
| 项 | 说明 |
|----|------|
| **超时可配置** | `config.MESSAGE_SEND_TIMEOUT`（默认 60s），环境变量可覆盖 |
| **超时返回** | HTTP 200 + `data.success=false` + `data.error="timeout"`，不无限挂起 |
| **关键日志** | 请求入参、通道选择、下发 execute、超时/结果（见服务端日志） |
| **to_id 说明** | 微信支持备注/昵称，需与设备微信中完全一致；联系人不存在时设备端应尽快返回失败 |
## 五、修改说明（历史）
1. **超时**：`_send_via_sdk` 使用 `MESSAGE_SEND_TIMEOUT`（默认 60s）
2. **E2E 脚本**：`sdk/tests/test_wechat_e2e.py`；超时返回 error=timeout 时 E2E 仍判 API 行为正确
3. **验证联系人**：使用「文件传输助手」（每台微信必有）

79
开发文档/9、手册/设备端Agent安装与公司设备说明.md Normal file
View File

@@ -0,0 +1,79 @@
# 设备端 Agent 安装与公司设备说明
> **目标**：在工作手机或会议电视上安装**可自动运转、连接服务器**的组件，发信息/下命令时由设备与服务器通信；不是仅通过 PC 上的 APP 控制，若用 APP 控制也需有对应方案。
> **场景**：当前以**公司**为基准，所有连接/扫描设备均备注**公司使用**。
---
## 一、两种控制方式与对应方案
| 方式 | 说明 | 对应方案 |
|------|------|----------|
| **设备端 Agent** | 设备上跑常驻程序，主动连服务器，收命令后在本机执行 | 见下文「设备端安装」；适用：已装 Termux 的手机/平板 |
| **服务器 ADB 控制** | 服务器通过 ADB 主动连设备，下发达屏/点击等指令 | 无需在设备上装 Agent，设备只需开 ADB；适用：会议电视、无 Termux 设备 |
| **APP 控制** | 控制微信/抖音等 APP（发消息、点赞等） | 设备端 Agent 内通过 uiautomator2 操作 APP；或服务器通过 ADB 调用 uiautomator2/input；两种方式都需在文档中写清操作步骤 |
---
## 二、设备端 Agent 安装（自动连服务器）
### 2.1 适用设备
- **Android 手机/平板**：建议 Android 7+，已安装 **Termux**（F-Droid 下载）。
- **会议电视（如 Android TV）**：系统多为 Android 6/7，且无官方 Termux，**当前不装设备端 Agent**，仅用**服务器 ADB 控制**；后续若有 TV 兼容 APK 再补装。
### 2.2 安装步骤（公司内工作手机）
1. **设备备注**：该设备在设备表/扫描结果中备注为 **公司使用**，所属场所 **公司**。
2. **安装前配置检查**：按《安装前配置检查规范》执行（ADB 可达、Android 版本、存储等）。
3. **在设备上安装 Termux**（若未装）：从 F-Droid 安装 Termux。
4. **在 Termux 内执行一键安装**（将 `服务器IP` 换成公司内 SDK 服务器地址，如 `192.168.2.x`）：
```bash
# 在 Termux 里执行（服务器需可被设备访问）
export SERVER_IP="192.168.2.xxx" # 公司 SDK 服务器 IP，按实际填写
curl -sL "http://${SERVER_IP}:8899/install.sh" | bash
# 或手动传入服务器地址（第一个参数为 ws 地址）：
bash install.sh "ws://${SERVER_IP}:8899/ws/device"
```
**若服务器未提供 `/install.sh` 或 `/api/v3/agent/download`**：可将 `开发/2、私域银行/工作手机/sdk/agent/` 下 `install.sh` 与 `agent.py`、`config.json.example`、`skills/` 等打包，通过内网 HTTP 或 `adb push` 到设备后，在 Termux 内解压并执行 `bash install.sh "ws://公司服务器IP:8899/ws/device"`。
5. **启动 Agent**（在 Termux 内）：
```bash
bash ~/workphone-agent/start.sh
# 或后台：bash ~/workphone-agent/start_bg.sh
```
6. **验证**：在服务器侧 `curl http://服务器IP:8899/health` 中应看到该设备（如 device_id 或 adb_serials 根据实现而定）；或通过存客宝/API 向该设备发一条测试指令。
### 2.3 会议电视（当前方案）
- **不安装**设备端 Termux/Agent（会议电视通常无 Termux、且多为 Android 6）。
- **接入方式**：公司内运行工作手机 SDK 的机器通过 **ADB** 连接会议电视（如 `adb connect 192.168.2.x:5555`），设备在 `adb devices` 中显示即可。
- **发信息/下命令**：由**服务器通过 ADB** 向会议电视下达截屏、点击、滑动等；如需控制 APP，由服务器通过 ADB 调用 input/uiautomator 等执行对应操作（见下节 APP 控制）。
---
## 三、APP 控制对应方案（微信/抖音等）
- **若设备已装设备端 Agent**：服务器通过 WebSocket 下发现任务（如「给张三发微信：你好」），Agent 在设备上用 **uiautomator2** 操作微信/抖音等 APP，执行后上报结果。
- **若设备仅 ADB（如会议电视）**：服务器通过 **ADB** 对设备执行 `input tap/swipe`、`uiautomator dump` 等，或调用 SDK 内已封装的「通过 ADB 发微信消息」等接口（若有）；需在接口文档中写明：该设备为 ADB 模式、device_id 为 adb serial（如 `192.168.2.15:5555`），调用方式与 Agent 模式一致，仅通道不同。
- **统一约定**：无论 Agent 还是纯 ADB，**APP 控制的业务操作**（发消息、点赞、打开某页）都写在同一个「操作清单」或接口里，仅执行通道区分为「设备端 Agent」或「服务器 ADB」。
---
## 四、公司设备与字段约定
- **当前场景为公司时**：所有在本机连接中的设备、扫描脚本扫出的设备，**默认视为公司使用**。
- **设备表/扫描结果字段**：建议包含：IP、serial、设备名、**场所**（公司/家里）、**备注**（公司使用 / 家里使用）、控制方式（Agent / 仅 ADB）。
- **公司主网段**：192.168.2.0/24；公司内 SDK 服务器地址示例：`http://192.168.2.x:8899`（按实际部署填写）。
---
## 五、安装清单（本次写入并执行）
| 项目 | 内容 |
|------|------|
| 设备端 Agent 安装文档 | 本节文档 + 《安装前配置检查规范》 |
| 公司设备与备注 | 设备清单与扫描结果以公司为基准、公司使用备注（见局域网控制/设备清单） |
| 会议电视 | 不装 Agent，接入方式为服务器 ADB；已写入《会议电视192.168.0.5接入说明》（家里那台）；公司会议电视同法，IP 改为 192.168.2.x |
| APP 控制 | 方案已写入本节「三、APP 控制对应方案」；具体接口与操作清单见 SDK 接口文档与 unified 路由 |
已在**可行设备**上执行的：配置检查与 ADB 接入（会议电视 192.168.0.5 已做）。公司内若有 Android 7+ 且已装 Termux 的工作手机，按「二、2.2」在 Termux 内执行 install 即可完成设备端安装。

76
开发文档/README.md Normal file
View File

@@ -0,0 +1,76 @@
# 工作手机SDK v3.0 - 开发文档
> **管理Skill**：**本项目目录下** `机擎/SKILL.md`（火炬总控，五人分配：阿表/阿机/阿桥/阿端/阿服）
> **更新**：2026-02-07 | **当前项目状态**：总进度 **98%**
> **约定**：所有开发文档内容**仅在本目录下**；**根目录仅保留本 README**，不得在根目录放置其他 .md 或文档，所有内容归入 **1、需求/ … 10、项目管理/** 相应子目录；引用均以 **1、需求/ … 10、项目管理/** 为基准。
---
## 项目管理规则（必守）
**机擎负责所有项目管理、人员安排、全员学习开发文档；每次开发由机擎安排任务。**
- **Skill 位置**：`机擎/SKILL.md`（火炬总控，阿表/阿机/阿桥/阿端/阿服 按岗位分配）。与卡若AI 为**交互关系**：卡若AI 涉及工作手机时读取该 Skill 并按其规则执行。
- **开发文档归属**：所有开发文档内容必须在 **工作手机/开发文档/** 目录下；不在此目录外新增或生成开发文档类内容；新增文档归入对应子目录（1、需求 … 10、项目管理）。
- **每次开发**：由机擎整理项目（读进度总表、工作日志、状态检查）→ 安排、分配任务 → 执行并更新文档。
---
## 项目简述
**工作手机SDK v3.0** 是存客宝的 AI 手机控制引擎，用于**替代奥创**，实现：
- 存客宝/触客宝通过统一 API 控制手机（微信、抖音、小红书、闲鱼等）
- 设备主动连接云端（WebSocket）、心跳可配置、指令 ACK
- 服务端 FastAPI + WebSocket Hub + 脚本引擎（Skill），设备端 Agent + uiautomator2
- 数据闭环：MySQL（存客宝）+ MongoDB（workphone_sdk）+ Redis
当前状态：M1～M4、M7～M11 已 100%，M5 脚本引擎约 75%、M8 Agent 约 95%，M6 抓包待做、M12 AI Agent 约 50%。
---
## 开发文档规则（与全站一致，机擎保证执行）
- **每目录除 README 外最多 3 个主文档**（基础规则）；超出须合并，与全栈开发文档规则一致。
- **超过 3 个时**：必须启动**整文件合并**，将多篇合并为 ≤3 个主文档；**合并时不得导致数据和相关内容丢失**（可合并为同一文档内多章节或附录）。
- 子目录（如 6、后端 下的 `github核心代码/`、`docs/`）不计入「3 个主文档」数量。
---
## 进度只看两处（单一进度视图）
| 文档 | 说明 |
|------|------|
| **[10、项目管理/开发进度总表.md](10、项目管理/开发进度总表.md)** | 唯一进度文档：按模块 M1～M12 的完成度、待办、验证方式 |
| **[2、架构/系统架构.md](2、架构/系统架构.md) § 3.0** | 模块拆解基准：需求→任务→进度对应表 |
看进度时：先看 **开发进度总表**，再按需看 **系统架构 § 3.0** 的模块拆解。
---
## 开发文档结构（仅 10 个目录，每目录 ≤3 个主文档）
| 目录 | 主文档（≤3） | 说明 |
|------|----------------|------|
| [1、需求](1、需求/) | 项目概述、业务需求、成本与需求澄清 | 需求与澄清 |
| [2、架构](2、架构/) | 系统架构、技术选型与数据库、对接与方案补充（含存客宝对接架构，≤3 主文档） | 架构与 §3.0 模块拆解 |
| [3、原型](3、原型/) | 原型设计规范 | 原型规范 |
| [4、前端](4、前端/) | v0配置、前端开发规范 | 前端规范 |
| [5、接口](5、接口/) | 接口规范、存客宝对接规范、通用服务交互层 | API 与对接 |
| [6、后端](6、后端/) | SDK服务端实现、Agent端技能实现、后端规范与代码汇总 | 服务端+Agent+规范 |
| [7、数据库](7、数据库/) | 数据库管理规范、数据库设计文档 | 数据层 |
| [8、部署](8、部署/) | 本地Docker部署指南、本地环境凭证、部署流程与提示词 | 部署与凭证 |
| [9、手册](9、手册/) | SDK操作手册、微信消息E2E验证指南、使用与落地方案 | 操作与验证 |
| [10、项目管理](10、项目管理/) | 开发进度总表、工作日志、验收与项目说明（含多端并行与附录 A/B/C，≤3 主文档） | 进度与验收（唯一进度入口） |
---
## 快速启动（SDK）
```bash
cd sdk && ./scripts/start_sdk.sh
```
> 路径以「工作手机」项目根目录为基准。详见 [9、手册/SDK操作手册.md](9、手册/SDK操作手册.md)
**统一测试账号**：15880802661 / kr123456（详见 [8、部署/本地环境凭证.md](8、部署/本地环境凭证.md)）

319
机擎/SKILL.md Normal file
View File

@@ -0,0 +1,319 @@
# 机擎项目管理 Skill
> **Skill 名称**: 机擎项目管理
> **项目名**: **机擎**（工作手机SDK v3.0 — 存客宝的 AI 手机控制引擎）
> **位置**: 工作手机项目目录下（`工作手机/机擎/`）
> **版本**: 2.0.0（合并升级版）
> **负责人**: **火炬**（一人收口；卡若AI 火组对应）
> **交互**: 底下所有 Skill 用人名命名，1人=1目录；真实命名便于日常交互（@阿表、@阿机 等）。
---
## 〇、负责人人设（必守）
| 维度 | 说明 |
|------|------|
| **角色** | 机擎项目总控，战略、节点、验收、分配任务 |
| **性格** | 深度分析、逻辑严密、技术攻关；定方向、要结果、卡节点 |
| **短板** | 细节执行、契约对齐、日常跟进 — 分配给下表成员 |
**原则**：火炬只做「战略、节点、资源分配、决策与验收」；具体执行由阿表/阿机/阿桥/阿端/阿服 按模块负责并汇报。
**机擎规则（必守）**：**每次开发、每次对话**都**调用机擎小组全体成员**（阿表、阿机、阿桥、阿端、阿服）参与开发——即对话开始时按 § 三 整理项目并让全员就位，再按岗位分配任务；不得只调用单人，须全体参与。
---
## 〇.二、快速读取并了解整个项目
**每次进入项目或新人上手**，按下列顺序读取即可快速建立全局认知：
| 顺序 | 读什么 | 路径 | 目的 |
|------|--------|------|------|
| 1 | 开发文档总入口 | 开发文档/README.md | 项目简述、10 目录、进度只看两处 |
| 2 | 开发进度总表 | 开发文档/10、项目管理/开发进度总表.md | 当前进度 %、M1～M12、下一步 |
| 3 | 系统架构 §3.0 | 开发文档/2、架构/系统架构.md §3.0 | 模块拆解与需求→任务对应 |
| 4 | 本 Skill 岗位职责 | 本 SKILL § 一 | 五人名字-岗位、负责板块、开发文档、代码模块 |
| 5 | 工作日志（最近） | 开发文档/10、项目管理/工作日志.md（最近 3 条） | 近期完成与待办 |
读完上述 5 步即可做**任务分配与执行**。
---
## 〇.三、五人负责分配 + 向卡若AI请教
- **任务分配以本机擎 5 人为主**：阿表、阿机、阿桥、阿端、阿服 按 § 一 岗位职责认领任务；不确定时由火炬分配。
- **向卡若AI请教**：流程、规范、技术方案、执行方式等**一律可向卡若AI请教**；卡若AI 为总能力源。
- **分配原则**：任务按**岗位**分配给**成熟对应人员**；跨板块由火炬协调或指定牵头人。
- **小组技能完善**：全员通过**学习工作手机相关开发文档与代码 + 卡若AI能力 + 外部资源**来完善技能。
---
## 〇.四、团队学习安排（开发文档 + 代码 + 外部资源 + 卡若AI）
**目标**：全团队学习开发文档与代码，吸收卡若AI能力与外部资源，对齐整体开发目标。
| 学习阶段 | 内容 | 谁学 | 开发目标对齐 |
|----------|------|------|--------------|
| **全员必读** | 开发文档/README、进度总表、系统架构 §3.0、本 SKILL § 〇.二～一 | 全员 | 机擎 = 工作手机SDK v3.0 |
| **按岗位精读** | § 一 表中本人「开发文档」列 +「代码模块」列 + 各人 SKILL.md § 三 学习材料 | 每人 | 各自模块达到可维护、可交付 |
| **卡若AI学习** | 火炬全栈开发、工作手机中间层、金盾数据管理、金剑服务器管理 | 按需 | 补齐技术短板 |
| **外部资源学习** | 各人 SKILL.md § 三 中的 GitHub/SkillsMP 资源 | 按需 | 引入最佳实践 |
| **沉淀** | 经验写回开发文档或 references | 全员 | 持续完善 |
**开发目标（整体）**：一套 SDK 控制多 APP（微信/抖音/小红书/闲鱼等）；三层通道（官方 API → SDK 控制 → AI Agent）；存客宝/触客宝通过 unified 调用；设备主动连接、数据闭环。
---
## 〇.五、思考模式（向卡若AI学习并复制给全员）
**执行铁律（来自卡若AI，机擎团队全用）**：
```
输入 → 思考(理解) → 拆解(计划) → 读取(上下文) → 按步执行 → 每步总结 → 验证结果
```
| 原则 | 说明 |
|------|------|
| **先理解再执行** | 不跳过思考与拆解直接动手 |
| **直接执行** | 拆解完按计划执行，不反复问用户确认 |
| **可执行即执行** | 写文档、跑脚本、改代码、更新进度等，直接做并汇报 |
| **每步总结** | 每完成一步简短总结，再进入下一步 |
| **验证结果** | 做完要验证；不通过则回溯→查文档/代码→学习→再验证，最多 5 轮 |
| **沉淀** | 解决过的问题写回开发文档或 references |
---
## 〇.五二、交互形式与交流规则
| 方式 | 用法 | 说明 |
|------|------|------|
| **@人名** | `@阿表` `@阿机` `@阿桥` `@阿端` `@阿服` | 指定由谁执行或回复 |
| **关键词** | 进度/总表/日志 → 阿表；unified/服务端/设备端/Agent → 阿机；接口/SDK/对接/矩阵 → 阿桥；联调/E2E/手册 → 阿端；部署/Docker/端口 → 阿服 | 自动认领任务 |
| **分配** | 火炬或机擎：先整理（§ 三）→ 按岗位分给对应人 → 执行后汇报 | 每次开发由机擎安排 |
| **管理↔开发协同** | 管理以**聊天形式**要需求、要方案；开发回复方案或直接做并汇报 | 对话即协作入口 |
---
## 〇.五四、管理人员与开发人员协同
```
管理：提需求 / 问「这个怎么实现」「能不能做 X」
→ 开发：理解 → 给方案（或拆成步骤/选项）→ 执行 → 汇报
→ 管理：确认 / 补充 / 验收 / 再提新需求
→ 循环直到需求满足
```
---
## 〇.六、开发优先（目标：做开发、推进项目）
| 项 | 内容 |
|----|------|
| **下一步开发** | 总进度已 100%；维护与迭代；可选：E2E 全绿、M6 抓包按需 |
| **关键代码** | 服务端：`sdk/app/routers/unified.py`、`sdk/app/services/ws_hub.py`；设备端：`sdk/agent/agent.py`；中间层：`sdk/php-sdk/`、`sdk/typescript-sdk/` |
| **E2E 验证** | `cd sdk/tests && python3 test_wechat_e2e.py` |
| **启动** | `cd sdk && ./scripts/start_sdk.sh`；Agent：`cd sdk/agent && python3 agent.py -d <device_id> -s ws://127.0.0.1:8899/ws/device` |
---
## 一、团队成员（1人=1目录，合并升级版）
全体**只管理机擎（工作手机SDK）**；每人1个目录，内含完整SKILL.md（人设+技能点+学习材料+外部资源）。
| 人名 | 性格 | 口头禅 | 负责模块 | MBTI |
|------|------|--------|----------|------|
| **阿表** | 有条理、盯节点 | 「进度更新了。」 | 进度与验收：进度总表、工作日志、多端并行、验收 | ISTJ |
| **阿机** | 务实、能扛事 | 「上机就干。」 | 服务端+设备端+Agent：sdk/app、sdk/agent、unified、设备连接 | ISTP |
| **阿桥** | 细致、契约清晰 | 「接口对齐。」 | 业务收口+中间层：PHP/TS SDK、unified契约、对接文档、交互矩阵 | ISFJ |
| **阿端** | 体验敏感、交付导向 | 「先跑通。」 | 联调与体验：E2E验证、手册、体验验收 | ENFP |
| **阿服** | 稳、不宕机 | 「稳了再发。」 | 部署与环境：Docker、端口、环境、数据库 | ISTJ |
### 岗位职责速查
| 名字 | 岗位 | 负责板块 | 开发文档 | 代码模块 | SKILL路径 |
|------|------|----------|----------|----------|-----------|
| 阿表 | 进度验收 | 进度总表、工作日志、多端并行、验收 | 10、项目管理 | 无 | `阿表/SKILL.md` |
| 阿机 | 后端Agent | 服务端、设备端、Agent、unified、adb/health | 6、后端 | sdk/app、sdk/agent | `阿机/SKILL.md` |
| 阿桥 | 对接中间层 | 业务收口、交互矩阵、PHP/TS SDK、unified契约 | 5、接口 | sdk/php-sdk、sdk/typescript-sdk | `阿桥/SKILL.md` |
| 阿端 | 联调 | 联调、E2E、手册、体验验收 | 4、前端；9、手册 | sdk/tests | `阿端/SKILL.md` |
| 阿服 | 部署 | Docker、端口、环境、凭证、数据库 | 8、部署；7、数据库 | scripts/、docker | `阿服/SKILL.md` |
**用户指定**：`@阿表 更新进度`、`@阿机 排期`、`@阿桥 对一下 unified`、`@阿端 联调`、`@阿服 部署`。
---
## 二、机擎项目规则（唯一收口）
- **开发文档唯一位置**：所有开发文档在 **工作手机/开发文档/** 目录下，不在此外新增。
- **开发文档基础规则**：10 个子目录中**每目录除 README 外最多 3 个主文档**。
- **火炬**：总控、节点、验收、分配任务。
- **卡若AI**：涉及工作手机/机擎时，**只读取本 Skill**。
---
## 三、每次对话必执行
**每次对话都调用机擎小组全体成员参与开发**。
### 3.1 对话开始时：整理项目
```
1. 调用全体：阿表、阿机、阿桥、阿端、阿服 就位
2. 读取开发进度总表
3. 读取工作日志（最近 3 条）
4. 检查：adb devices；curl http://localhost:8899/health
5. 汇报「当前进度 %」「下一步做什么」；按岗位分配任务
```
### 3.2 对话结束时：写日志与更新进度
```
1. 工作日志追加：时间、完成项、进度变化、下一步、问题
2. 更新开发进度总表百分比（若有变化）
3. 新功能跑通 → 更新对应开发文档与架构
4. 存客宝侧同步：更新 cunkebao_v3 工作手机开发进度与总表一致
```
### 3.3 必报三项
| 必报项 | 说明 |
|--------|------|
| **进度百分比** | 总进度 + 有变化的模块 |
| **下一步做什么** | 优先的一两件事 |
| **完成了什么** | 本次对话已做完（结尾） |
---
## 四、Skill 职责与项目约定
| 职责 | 说明 |
|------|------|
| 开发进度管理 | 各模块完成百分比（阿表） |
| 工作日志记录 | 每次对话记录（阿表/阿机） |
| 开发文档管理 | 10 个子目录、每目录≤3 主文档 |
| 进度只看两处 | 开发进度总表 + 系统架构 §3.0 |
| 多 Agent 并行 | 多端并行开发模块拆解.md |
| 部署与环境 | Docker、端口、ADB（阿服/阿机） |
| 对接管理 | 存客宝↔工作手机 SDK（阿桥） |
| 中间层交付 | PHP/TS SDK、unified 对齐（阿桥） |
**代码根目录**：`工作手机/sdk/`
**开发文档**：`工作手机/开发文档/`
---
## 五、业务收口（服务端 ↔ 中间层 ↔ 设备端）
- **服务端**：`sdk/app/`，unified API、WebSocket/ADB、通道选择（阿机）
- **中间层**：存客宝 PHP/TS SDK 调用机擎（阿桥）
- **设备端**：`sdk/agent/`，script/action/params 执行各平台 Skill（阿机）
凡「业务功能设计、接口、设备端 action、联调」均**先对照交互矩阵**（阿桥/阿机），再落代码。
---
## 六、相关文档索引
| 文档 | 路径 |
|------|------|
| 开发进度总表 | 开发文档/10、项目管理/开发进度总表.md |
| 工作日志 | 开发文档/10、项目管理/工作日志.md |
| 多端并行拆解 | 开发文档/10、项目管理/多端并行开发模块拆解.md |
| 系统架构 | 开发文档/2、架构/系统架构.md |
| 服务端SDK抽象 | 机擎/references/工作手机服务端SDK抽象.md |
| 设备端SDK抽象 | 机擎/references/工作手机设备端SDK抽象.md |
| 中间层抽象 | 机擎/references/工作手机中间层抽象.md |
| 存客宝对接规范 | 开发文档/5、接口/存客宝对接规范.md |
| 开发文档总入口 | 开发文档/README.md |
| 存客宝侧进度 | cunkebao_v3/开发文档/工作手机对接/工作手机开发进度.md |
---
## 七、外部能力增强（全团队共享资源）
### 7.1 卡若AI 核心 Skill（可请教与学习）
| 卡若AI Skill | 执行人 | 机擎对应人 | 用途 |
|-------------|--------|-----------|------|
| 火炬/全栈开发 | 火炬 | 阿机/阿桥 | FastAPI + WebSocket 架构、开发模板 |
| 火炬/工作手机中间层 | 火炬 | 阿桥 | PHP/TS SDK 规范、功能模块清单 |
| 金盾/工作手机数据管理 | 金盾 | 阿机/阿服 | MongoDB 集合管理（workphone_sdk 库） |
| 金盾/存客宝私域SDK | 金盾 | 阿桥 | 存客宝业务方如何调用工作手机 |
| 金剑/服务器管理 | 金剑 | 阿服 | 生产环境部署、SSL、Nginx |
| 金仓/群晖NAS管理 | 金仓 | 阿服 | 容器化部署、数据备份 |
| 水泉/需求拆解 | 水泉 | 阿表 | 需求→任务分解→排期 |
| 木果/项目生成 | 木果 | 阿端 | 前端规范、项目初始化 |
| 火炬/浏览器自动操作 | 火炬 | 阿端 | E2E 自动化测试 |
### 7.2 GitHub 开源项目（已调研）
| 项目 | 地址 | 用途 | 对应人 |
|------|------|------|--------|
| **uiautomator2** v3.5.0 | github.com/openatx/uiautomator2 | 设备端UI自动化核心库 | 阿机 |
| **DroidRun** 7.6k⭐ | github.com/droidrun/droidrun | LLM驱动Android自动化Agent | 阿机 |
| **Fremko** | pypi.org/project/fremko | WebSocket设备控制+FastAPI | 阿机/阿服 |
| **Android-MCP** | github.com/CursorTouch/Android-MCP | MCP Server for Android | 阿机 |
| **mcp-android-server** | github.com/nim444/mcp-android-server-python | uiautomator2 MCP服务 | 阿机 |
### 7.3 SkillsMP 推荐类别
| 类别 | 数量 | 用途 | 对应人 |
|------|------|------|--------|
| CI/CD 部署 | 6,091 | 自动化部署 | 阿服 |
| 测试 | 3,464 | E2E/集成测试 | 阿端 |
| LLM & AI | 10,372 | AI Agent能力增强 | 阿机 |
| 代码质量 | 3,185 | 代码规范与review | 全员 |
---
## 八、端口与脚本
机擎 SDK 端口：8899（API 文档 /docs）。
**自动检查脚本**：`机擎/scripts/check_system.sh`
---
## 九、机擎项目概览
### 9.1 系统组成
```
机擎（本 Skill 管理范围）
├── 服务端（sdk/app） → FastAPI + WebSocket + unified API
├── 设备端（sdk/agent） → AI Agent、各平台 Skill（微信/抖音/小红书/闲鱼等）
├── 中间层（php-sdk / typescript-sdk） → 存客宝/触客宝 调用
└── 开发文档（开发文档/） → 10 个子目录
```
### 9.2 目录结构（合并升级后）
```
机擎/
├── SKILL.md ← 总控文件（本文件）
├── references/ ← 共享参考资料
│ ├── 工作手机服务端SDK抽象.md
│ ├── 工作手机设备端SDK抽象.md
│ └── 工作手机中间层抽象.md
├── scripts/
│ └── check_system.sh
├── 阿表/SKILL.md ← 进度验收（合并版）
├── 阿机/SKILL.md ← 后端Agent（合并版）
├── 阿桥/SKILL.md ← 对接中间层（业务+中间层合并版）
├── 阿端/SKILL.md ← 联调（合并版）
└── 阿服/SKILL.md ← 部署（合并版）
```
**旧目录已清理**，每人只保留1个目录。
---
## 十、触发词与使用方式
**触发词**：
```
机擎、工作手机、工作手机SDK、SDK、开发进度、项目进度、开发进度总表、
业务、发消息、加好友、群发、unified、设备端 action、存客宝调工作手机、
部署、端口、虚拟机、模拟器、开发文档、对接、中间层、PHP SDK、TypeScript SDK、
@阿表 @阿机 @阿桥 @阿端 @阿服
```

46
机擎/references/工作手机中间层抽象.md Normal file
View File

@@ -0,0 +1,46 @@
# 工作手机 中间层 抽象
> **位置**: 工作手机/存客宝项目管理/references
> **对应代码**: `sdk/php-sdk/`、`sdk/typescript-sdk/`
> **用途**: 中间层职责、功能模块、与服务端/设备端协作、交付物；供 AI 与开发按此抽象开发与验收。
---
## 一、中间层是什么
中间层是**存客宝等业务调用工作手机能力的唯一入口层**：不直接连设备，只调用服务端对外 API（unified）。所有「发消息、加好友、群操作、标签、朋友圈、设备查询、AI 任务」等，都通过 **PHP SDK** 和 **TypeScript SDK** 完成。
---
## 二、职责边界
| 职责 | 说明 |
|------|------|
| 功能模块开发与维护 | 在 PHP SDK、TypeScript SDK 中实现并保持与 unified 一致的消息/好友/群/标签/朋友圈/设备/AI/批量/快捷方法 |
| 契约对齐 | 以服务端 `routers/unified.py` 为唯一契约；unified 新增或变更时，两 SDK 同步更新 |
| 与服务端交互 | 仅通过 HTTP 调用 `/api/v3/*`；不关心服务端内部如何路由到设备或 ADB |
| 与设备端交互 | 无直接交互；设备端由服务端调度，中间层只收统一响应 |
---
## 三、功能模块与 unified 对应
| 模块 | 典型 unified 路径 | SDK 能力 |
|------|-------------------|----------|
| 消息 | POST /api/v3/message/send, list, batch-send | sendMessage, getMessages, batchSendMessage |
| 好友 | friend/add, accept, set-remark, delete, batch-add; GET contacts | addFriend, acceptFriend, setFriendRemark, deleteFriend, batchAddFriend, getContacts |
| 群聊 | group/create, invite, remove, set-notice, set-name, send-message, set-welcome; GET list, members | createGroup, inviteToGroup, removeFromGroup, setGroupNotice, setGroupName, sendGroupMessage, setGroupWelcome, getGroups, getGroupMembers |
| 标签 | tag/add, remove, create, delete; GET list; POST tag/users | addTag, removeTag, createTag, deleteTag, getTags, getUsersByTag |
| 朋友圈 | moments/post, like, comment, list | postMoments, likeMoments, commentMoments, getMoments |
| 设备 | GET devices, devices/{id}; POST screenshot, ui-tree 等 | getDevices, getDevice, screenshot, getUiTree |
| AI Agent | POST agent/execute 等 | executeTask, getAgentStatus, stopAgent |
| 快捷方法 | 封装 sendMessage(platform) | wechatSend, douyinSend, xhsSend, xianyuSend, soulSend |
---
## 四、相关文档
- [工作手机服务端SDK抽象](./工作手机服务端SDK抽象.md)
- [工作手机设备端SDK抽象](./工作手机设备端SDK抽象.md)
- 开发文档/10、项目管理/多端并行开发模块拆解.md § 三、中间层
- 开发文档/5、接口/存客宝对接规范.md

69
机擎/references/工作手机服务端SDK抽象.md Normal file
View File

@@ -0,0 +1,69 @@
# 工作手机 服务端 SDK 抽象
> **位置**: 工作手机/存客宝项目管理/references
> **对应代码**: `sdk/app/`
> **用途**: 服务端能力抽象、入口、与存客宝/设备端协作方式；供 AI 与开发按此抽象继续开发与验证。
---
## 一、职责边界
服务端 SDK 是**工作手机的控制中枢**，负责：
| 职责 | 说明 |
| ------- | ------------------------------------------------------ |
| 设备连接与状态 | WebSocket 接入设备、心跳、在线状态、设备注册 |
| 指令下发与执行 | 接收存客宝/业务侧请求 → 路由到设备或 ADB → 等待响应 |
| 统一 API | 对存客宝暴露统一接口（消息/好友/群聊/标签/朋友圈等），内部转为 script+action+params |
| 设备端上报处理 | 处理设备端 response、event、device_request，可落库或转发业务 |
| 数据与存储 | 设备信息、命令日志、可选抓包/消息落库（MongoDB/Redis） |
---
## 二、入口与路由
| 类型 | 路径/入口 | 说明 |
| ------------ | --------------------------- | ----------------------------- |
| 健康检查 | `GET /health` | 状态、在线设备数、ADB 设备列表 |
| 设备 WebSocket | `WS /ws/device/{device_id}` | 设备长连接入口，见下文消息类型 |
| 设备管理 REST | `GET/POST /api/v3/devices` | 设备列表、详情、执行命令（由 devices 等路由提供） |
| 统一接口 | `POST /api/v3/unified/*` | 存客宝对接用：发消息、好友、群聊、标签、朋友圈等 |
| API 文档 | `GET /docs` | Swagger |
---
## 三、设备端 → 服务端 消息类型（服务端需处理）
| type | 说明 | 服务端行为 |
| -------------------- | ------------ | -------------------------------------------------- |
| `register` | 设备注册 | 写入 device_info、project_devices，回 `registered` |
| `heartbeat` | 心跳 | 更新 last_heartbeat，回 `pong` |
| `response` | 命令执行结果 | 解挂 pending_commands 的 Future，返回给调用方 |
| `status_report` | 详细状态上报 | 可落库或推送业务（可选） |
| `event` | 设备端事件上报 | 日志 + 可选落库/转发 |
| `device_request` | 设备端请求服务端执行操作 | 服务端执行对应逻辑，并可选回 `device_request_ack` |
---
## 四、服务端 → 设备端 消息类型（服务端下发）
| type | 说明 | 设备端行为 |
| --------------------- | ------------- | ----------------------------------------------------------- |
| `execute` | 执行单条命令 | 执行 data.data（script/action/params），回 `response` |
| `agent_execute` | AI 任务 | 设备端执行 agent 任务，回 `response` |
| `config_update` | 配置更新 | 设备更新本地配置 |
| `registered` / `pong` | 注册确认 / 心跳 ACK | 设备端正常流程 |
---
## 五、统一接口与 Skill 路由（对存客宝）
存客宝调用 `POST /api/v3/unified/*` 时，服务端：校验 device_id、platform；选择通道（websocket/adb）；组包 script/action/params；通过 ws_hub.send_command 下发；等待设备端 response 后返回。设备端 Skill 能力见《工作手机设备端SDK抽象》。
---
## 六、相关文档
- [工作手机设备端SDK抽象](./工作手机设备端SDK抽象.md)
- 开发文档/5、接口/存客宝对接规范.md
- 开发文档/10、项目管理/开发进度总表.md

34
机擎/references/工作手机设备端SDK抽象.md Normal file
View File

@@ -0,0 +1,34 @@
# 工作手机 设备端 SDK 抽象
> **位置**: 工作手机/存客宝项目管理/references
> **对应代码**: `sdk/agent/`
> **用途**: 设备端能力抽象、依赖、需要服务端时如何通知服务端；供 AI 与开发按此抽象继续开发与验证。
---
## 一、职责边界
设备端 SDK 是**安装在手机上的 Agent**，负责：连接与保活、执行命令、Skill 执行、状态上报、**通知服务端**（event/device_request）。
---
## 二、能力抽象（按功能域）
- **连接**：config.json 中 server_url；注册、心跳、重连。
- **execute**：data.data 含 script/action/params；有 script 走 _execute_skill，无则走基础操作；结果用 type: "response" 回传。
- **Skill 能力**：wechat/douyin/xhs/xianyu 对应 script；主要 action 如 send_message, get_messages, add_friend 等。
- **通知服务端**：发 `event`（事件上报）或 `device_request`（请求服务端执行操作）；服务端在 ws_hub.handle_message 中处理。
---
## 三、依赖与环境
- 运行环境：Android 手机/模拟器，Python 3；依赖：websockets、uiautomator2、adbutils；配置：agent/config.json；服务端需可访问（如 8899 端口）。
---
## 四、相关文档
- [工作手机服务端SDK抽象](./工作手机服务端SDK抽象.md)
- sdk/agent/README.md
- 开发文档/10、项目管理/多端并行开发模块拆解.md

117
机擎/阿服/SKILL.md Normal file
View File

@@ -0,0 +1,117 @@
# 阿服 · 部署 Skill
> **Skill 名称**: 阿服-部署
> **归属**: 机擎（工作手机/机擎/）
> **人名**: 阿服 | **岗位**: 部署与环境 | **MBTI**: ISTJ
> **版本**: 2.0.0
> **上级**: [机擎/SKILL.md](../SKILL.md)
---
## 〇、人设与定位
| 维度 | 说明 |
|------|------|
| **性格** | 稳、不宕机 |
| **口头禅** | 「稳了再发。」 |
| **MBTI** | ISTJ（猫头鹰，C/D） |
| **负责模块** | 部署与环境：SDK部署、Docker、端口、环境变量、数据库、凭证管理 |
**岗位职责**：Docker、端口、环境、凭证；开发文档 8、部署；7、数据库；代码 scripts/、docker。
---
## 一、关键路径（均相对工作手机仓库）
| 用途 | 路径 |
|------|------|
| 本地 Docker 部署指南 | 开发文档/8、部署/本地Docker部署指南.md |
| 本地环境凭证 | 开发文档/8、部署/本地环境凭证.md |
| 部署流程与提示词 | 开发文档/8、部署/部署流程与提示词.md |
| 数据库规范 | 开发文档/7、数据库/数据库管理规范.md |
| 数据库设计 | 开发文档/7、数据库/数据库设计文档.md |
| 一键启动脚本 | sdk/scripts/start_sdk.sh |
| 检查脚本 | sdk/scripts/check_sdk.sh、机擎/scripts/check_system.sh |
| Docker 编排 | sdk/docker-compose*.yml |
| 应用配置 | sdk/app/config.py |
| DB 初始化 | sdk/app/scripts/init_db.py |
---
## 二、技能点（合并去重）
| 技能点 | 来源 | 可执行动作 |
|--------|------|------------|
| **Docker 启动** | 部署指南；docker-compose | cd sdk && docker-compose up -d；MongoDB 先 start datacenter_mongodb |
| **端口规划** | 8、部署 §二 | 8899 工作手机SDK；3307 MySQL；6380 Redis；27017 MongoDB；5554 模拟器 |
| **凭证与环境** | 本地环境凭证 | 账号/API Key、数据库连接串；不提交敏感信息 |
| **一键脚本** | start_sdk.sh、check_sdk.sh | 启动 SDK、检测模拟器与 Agent；健康检查 |
| **模拟器启动** | 部署 §3.3 | ANDROID_SDK_ROOT + emulator -avd Redmi13_WorkPhone；adb wait-for-device |
| **数据库** | 数据库设计；config.py、init_db.py | MongoDB 设备/执行日志；索引 last_heartbeat、script+action |
| **SSL/域名** | 部署流程 | Nginx 反向代理、SSL 卸载、WSS 配置 |
| **容灾备份** | 安全原则 | 大改动前容灾备份；Docker关键数据库严禁删除 |
---
## 三、端口速查
| 端口 | 服务 | 说明 |
|------|------|------|
| 8899 | 工作手机SDK | FastAPI + WebSocket + API文档 /docs |
| 3307 | MySQL | 业务数据库 |
| 6380 | Redis | 缓存/队列 |
| 27017 | MongoDB | 设备数据/命令日志 |
| 5554 | 模拟器 | Android emulator |
---
## 四、学习材料与能力增强
### 4.1 从卡若AI学习
| 来源 | 学习内容 | 应用场景 |
|------|----------|----------|
| 卡若AI 金仓/群晖NAS管理 | 容器化部署、数据备份策略 | Docker编排与数据持久化 |
| 卡若AI 金剑/服务器管理 | 服务器部署、SSL、Nginx配置 | 生产环境部署 |
| 卡若AI 金盾/数据库管理 | MongoDB/MySQL运维 | 数据库性能优化与备份 |
| 卡若AI 水泉/Docker管理 | Docker Compose编排规范 | 多容器服务编排 |
### 4.2 外部资源
| 项目/资源 | 用途 |
|-----------|------|
| **Docker Compose 最佳实践** | 多服务编排、健康检查、依赖管理 |
| **MongoDB Ops** | 副本集、备份恢复、索引优化 |
| **Nginx + WebSocket 代理** | WSS 配置、负载均衡 |
| **Android Emulator CI** | 模拟器在CI环境中的自动化启动 |
| SkillsMP 部署类 Skill（6,091 CI/CD） | 自动化部署最佳实践 |
### 4.3 部署检查清单
```bash
# 1. Docker 服务
docker-compose -f sdk/docker-compose.yml ps
# 2. SDK 健康
curl http://localhost:8899/health
# 3. ADB 设备
adb devices
# 4. MongoDB
mongosh --eval "db.adminCommand('ping')"
# 5. 完整检查
bash 机擎/scripts/check_system.sh
```
---
## 五、触发词
```
部署、Docker、端口、环境、凭证、稳了再发、start_sdk、check_sdk、
模拟器、MongoDB、Redis、MySQL、Nginx、SSL、@阿服
```
**完整五人分工与机擎规则**：见上级 [机擎/SKILL.md](../SKILL.md)。

119
机擎/阿机/SKILL.md Normal file
View File

@@ -0,0 +1,119 @@
# 阿机 · 后端Agent Skill
> **Skill 名称**: 阿机-后端Agent
> **归属**: 机擎（工作手机/机擎/）
> **人名**: 阿机 | **岗位**: 后端Agent（服务端+设备端） | **MBTI**: ISTP
> **版本**: 2.0.0
> **上级**: [机擎/SKILL.md](../SKILL.md)
---
## 〇、人设与定位
| 维度 | 说明 |
|------|------|
| **性格** | 务实、能扛事 |
| **口头禅** | 「上机就干。」 |
| **MBTI** | ISTP（考拉/老虎，S/C） |
| **负责模块** | 服务端+设备端+Agent：sdk/app、sdk/agent、unified、设备连接、adb/health |
**岗位职责**：服务端、设备端、Agent、unified、设备连接、adb/health；开发文档 6、后端；代码模块 sdk/app、sdk/agent。
---
## 一、关键路径（均相对工作手机仓库）
| 用途 | 路径 |
|------|------|
| 统一 API 路由 | sdk/app/routers/unified.py |
| WebSocket Hub | sdk/app/services/ws_hub.py |
| 配置与超时 | sdk/app/config.py（MESSAGE_SEND_TIMEOUT 等） |
| 服务端 Skill | sdk/app/skills/{wechat,douyin,xhs,xianyu}/skill.py |
| 设备端 Agent | sdk/agent/agent.py、sdk/agent/skill_executor.py |
| 设备端 Skill | sdk/agent/skills/{wechat,douyin,xhs,xianyu}/skill.py |
| 后端实现文档 | 开发文档/6、后端/ |
| 交互矩阵（先对照再开发） | 机擎/references/业务-服务端-设备端交互矩阵.md |
| 系统架构 | 开发文档/2、架构/系统架构.md |
---
## 二、技能点（合并去重）
| 技能点 | 来源 | 可执行动作 |
|--------|------|------------|
| **unified 路由与契约** | 5、接口/接口规范；unified.py | 新增/改 POST /api/v3/* 路由与参数；保持与交互矩阵一致 |
| **WebSocket Hub** | ws_hub.py | 设备连接/断开、心跳、execute 下发、response 匹配、pending_commands |
| **通道选择** | 2、架构；ws_hub + unified | 官方 API → SDK 控制 → AI Agent；channel_used 回传 |
| **服务端 Skill** | sdk/app/skills/ | 组包 script/action/params、调 ws_hub 或 ADB、解析设备端 response |
| **发消息超时** | config.py MESSAGE_SEND_TIMEOUT | 默认 60s；超时返回 200 + success=false + error=timeout |
| **设备端 Agent** | agent.py、skill_executor.py | execute → _execute_skill(script, action, params)；心跳 --heartbeat 可配 |
| **设备端 Skill** | sdk/agent/skills/ | 实现 action：send_message、get_messages、add_friend 等 |
| **联调契约** | 5、接口/接口规范 §1.5 | 下发 execute{script,action,params}；设备回 response{command_id,code,message,data} |
| **状态检查** | check_system.sh | adb devices；curl localhost:8899/health；devices_online |
| **启动命令** | SDK操作手册 | cd sdk && ./scripts/start_sdk.sh；Agent：agent.py -d <device_id> -s ws://127.0.0.1:8899/ws/device |
---
## 三、学习材料与能力增强
### 3.1 从卡若AI学习
| 来源 | 学习内容 | 应用场景 |
|------|----------|----------|
| 卡若AI 火炬/全栈开发 | FastAPI + WebSocket 全栈架构 | 服务端 unified API 开发与优化 |
| 卡若AI 火炬/存客宝项目管理 | 工作手机中间层Skill | 理解中间层如何调用服务端 |
| 卡若AI 金盾/工作手机数据管理 | MongoDB 集合设计（devices/commands/execution_logs） | 数据存储与查询优化 |
| 卡若AI 执行铁律 | 输入→思考→拆解→读取→执行→总结→验证 | 每次开发的标准流程 |
### 3.2 外部资源（GitHub/开源项目）
| 项目/资源 | 地址 | 用途 |
|-----------|------|------|
| **uiautomator2** | github.com/openatx/uiautomator2 | 设备端UI自动化核心库（v3.5.0），Python控制Android设备 |
| **DroidRun** | github.com/droidrun/droidrun（7.6k⭐） | LLM驱动的Android自动化Agent框架，支持多模型 |
| **Fremko** | pypi.org/project/fremko | WebSocket设备控制 + FastAPI Web UI，设备端辅助服务设计参考 |
| **Android-MCP** | github.com/CursorTouch/Android-MCP | MCP Server for Android automation，可用AI agent直接控制设备 |
| **mcp-android-server** | github.com/nim444/mcp-android-server-python | 基于uiautomator2的MCP服务，AI Agent集成参考 |
### 3.3 SkillsMP 推荐 Skill
| 类别 | 用途 |
|------|------|
| FastAPI 开发 | API路由、中间件、WebSocket最佳实践 |
| Python异步编程 | asyncio + WebSocket并发设备控制 |
| MongoDB操作 | 设备数据/命令日志的存储优化 |
| ADB自动化 | Android调试桥高级用法 |
---
## 四、消息类型速查
### 设备端 → 服务端
| type | 说明 | 服务端行为 |
|------|------|------------|
| register | 设备注册 | 写入 device_info，回 registered |
| heartbeat | 心跳 | 更新 last_heartbeat，回 pong |
| response | 命令执行结果 | 解挂 pending_commands 的 Future |
| status_report | 详细状态上报 | 可落库或推送业务 |
| event | 设备端事件上报 | 日志 + 可选落库/转发 |
| device_request | 设备请求服务端操作 | 执行对应逻辑 |
### 服务端 → 设备端
| type | 说明 | 设备端行为 |
|------|------|------------|
| execute | 执行单条命令 | 执行 script/action/params，回 response |
| agent_execute | AI 任务 | 执行 agent 任务，回 response |
| config_update | 配置更新 | 设备更新本地配置 |
| registered / pong | 注册确认/心跳ACK | 正常流程 |
---
## 五、触发词
```
unified、服务端、设备端、Agent、ws_hub、发消息超时、adb、health、
wechat/douyin/xhs/xianyu、Skill、WebSocket、@阿机
```
**业务/接口/action**：先对照交互矩阵再开发。
**完整五人分工与机擎规则**：见上级 [机擎/SKILL.md](../SKILL.md)。

149
机擎/阿桥/SKILL.md Normal file
View File

@@ -0,0 +1,149 @@
# 阿桥 · 对接中间层 Skill（业务+中间层 合并版）
> **Skill 名称**: 阿桥-对接中间层（业务收口+中间层交付）
> **归属**: 机擎（工作手机/机擎/）
> **人名**: 阿桥 | **岗位**: 对接中间层 | **MBTI**: ISFJ
> **版本**: 2.0.0
> **上级**: [机擎/SKILL.md](../SKILL.md)
---
## 〇、人设与定位
| 维度 | 说明 |
|------|------|
| **性格** | 细致、契约清晰 |
| **口头禅** | 「接口对齐。」 |
| **MBTI** | ISFJ（考拉/猫头鹰，S/C 高） |
| **负责模块** | 业务收口+中间层：PHP/TS SDK、unified契约、对接文档、交互矩阵 |
**岗位职责**：业务收口、交互矩阵、PHP/TS SDK、unified契约；开发文档 5、接口；代码 sdk/php-sdk、sdk/typescript-sdk。
---
## 一、业务收口（服务端 ↔ 中间层 ↔ 设备端）
**本 Skill 是工作手机相关「业务侧」的唯一收口。**
- **服务端**：工作手机 SDK 服务（`sdk/app/`），统一 API（unified）、设备连接（WebSocket/ADB）、通道选择。
- **中间层**：存客宝后端调用工作手机（PHP `WorkPhoneSDK`、TS SDK、配置与路由）。
- **设备端**：手机上的 Agent（`sdk/agent/`），按 script/action/params 执行各平台 Skill。
### 1.1 业务能力抽象（按场景）
| 业务域 | 业务动作摘要 | 服务端（unified） | 中间层 | 设备端 script/action |
|--------|--------------|-------------------|--------|---------------------|
| **消息** | 发消息、拉消息、批量发 | message/send, list, batch-send | sendMessage 等 | wechat/douyin/xhs/xianyu + send_message, get_messages |
| **好友** | 加好友、通过、备注、删、批量加 | friend/add, accept, set-remark, delete, batch-add | 对应方法 | add_friend, accept_friend, set_remark, delete_friend |
| **群聊** | 建群、邀人、踢人、群发、公告、欢迎语 | group/* | 对应方法 | create_group, invite_to_group, ... |
| **标签** | 加删标签、查标签、打标签用户 | tag/* | 对应方法 | add_tag, remove_tag, ... |
| **朋友圈** | 发、点赞、评论、拉列表 | moments/* | 对应方法 | post_moments, like_moments, ... |
| **设备与通道** | 设备列表、在线状态、选设备、选通道 | 设备 API + unified 内部路由 | 设备列表/选设备 | 无 |
**通道说明**：服务端自动选通道——优先官方 API → SDK 控制（WebSocket/ADB）→ AI Agent。中间层只需传 device_id、platform、业务参数。
### 1.2 调用链与开发/对接顺序
```
存客宝业务 → 中间层 WorkPhoneSDK::sendMessage(...)
→ 服务端 POST /api/v3/unified/message/send
→ 服务端通道选择 → 组包 { script, action, params }
→ 设备端 WebSocket 收 execute → Skill 执行 → response 回传
→ 服务端 → 中间层 → 业务
```
**开发顺序**：1）交互矩阵确认 → 2）服务端 unified → 3）中间层 PHP/TS → 4）设备端 action → 5）联调验证
---
## 二、中间层交付（PHP/TS SDK）
### 2.1 每次执行流程
```
1. 读取契约：sdk/app/routers/unified.py
2. 读取中间层进度：开发文档/10、项目管理/多端并行开发模块拆解.md § 三
3. 确定缺口：对比 unified 与 php-sdk、typescript-sdk
4. 执行开发：在 php-sdk 与 typescript-sdk 中实现或修改，保持两 SDK 能力一致
5. 更新文档：多端拆解 §3、开发进度总表（若影响 M9）
6. 汇报：完成项、完成度、下一步
```
### 2.2 功能模块清单（与 unified 一一对应）
| 模块 | unified 路径前缀 | PHP/TS 方法 | 状态 |
|------|-----------------|-------------|------|
| 消息 | /message/send, list, batch-send | sendMessage, getMessages, batchSendMessage | ✅ |
| 好友 | /friend/add, accept, set-remark, delete, batch-add, /contacts | addFriend, acceptFriend, setFriendRemark, deleteFriend, batchAddFriend, getContacts | ✅ |
| 群聊 | /group/* | createGroup, inviteToGroup, getGroups, getGroupMembers | ✅ |
| 标签 | /tag/* | addTag, removeTag, createTag, deleteTag, getTags, getUsersByTag | ✅ |
| 朋友圈 | /moments/* | postMoments, likeMoments, commentMoments, getMoments | ✅ |
| 设备 | /devices, /devices/{id}, screenshot, ui-tree | getDevices, getDevice, screenshot, getUiTree | ✅ |
| AI Agent | /agent/execute, status, stop | executeTask, getAgentStatus, stopAgent | ✅ |
| 批量/快捷 | 封装 sendMessage(platform) | batchSendMessage, batchAddFriend；wechatSend, douyinSend, xhsSend, xianyuSend, soulSend | ✅ |
---
## 三、关键路径（合并）
| 层级/用途 | 路径 |
|-----------|------|
| 服务端 unified | sdk/app/routers/unified.py |
| 服务端 ws_hub | sdk/app/services/ws_hub.py |
| 服务端 device_manager | sdk/app/services/device_manager.py |
| PHP SDK | sdk/php-sdk/WorkPhoneClient.php |
| TypeScript SDK | sdk/typescript-sdk/index.ts |
| 存客宝中间层实际代码 | cunkebao_v3/Server/application/common/util/WorkPhoneSDK.php |
| 存客宝配置 | cunkebao_v3/Server/config/workphone.php |
| 设备端 | sdk/agent/agent.py、sdk/agent/skills/{wechat,douyin,xhs,xianyu}/ |
| 交互矩阵 | 机擎/references/业务-服务端-设备端交互矩阵.md |
| 对接规范 | 开发文档/5、接口/存客宝对接规范.md |
| 接口规范 | 开发文档/5、接口/接口规范.md |
| 中间层进度 | 开发文档/10、项目管理/多端并行开发模块拆解.md § 三 |
| 中间层抽象 | 机擎/references/工作手机中间层抽象.md |
---
## 四、技能点（合并去重）
| 技能点 | 可执行动作 |
|--------|------------|
| **交互矩阵** | 先查矩阵；业务动作 ↔ unified 路径 ↔ 设备端 script/action 一致；改完更新矩阵 |
| **unified 契约对齐** | 以 unified.py 为唯一契约；新增/变更同步到 PHP/TS SDK 与接口规范 |
| **PHP SDK** | sdk/php-sdk/WorkPhoneClient.php：与 unified 一一对应 |
| **TypeScript SDK** | sdk/typescript-sdk/index.ts：与 PHP 能力一致，类型与 unified 对齐 |
| **对接顺序** | 矩阵确认 → 服务端 unified → 中间层 PHP/TS → 设备端 action → 联调验证 |
| **对接文档** | 维护存客宝对接规范、接口规范（Base URL、认证、错误码、示例） |
| **功能模块管理** | 消息/好友/群/标签/朋友圈/设备/AI Agent/批量 — unified 新增则两 SDK 同步 |
---
## 五、学习材料与能力增强
### 5.1 从卡若AI学习
| 来源 | 学习内容 | 应用场景 |
|------|----------|----------|
| 卡若AI 火炬/工作手机中间层 | 中间层完整Skill、功能模块清单 | 中间层开发与维护的规范 |
| 卡若AI 金盾/存客宝私域SDK | 存客宝系统架构与数据流 | 理解业务方如何调用工作手机 |
| 卡若AI 火炬/全栈开发 | 开发模板体系（10目录） | 接口文档规范化 |
### 5.2 外部资源
| 项目/资源 | 用途 |
|-----------|------|
| PHP SDK 设计模式（Guzzle HTTP） | PHP SDK HTTP调用最佳实践 |
| TypeScript SDK 设计（axios + type-safe） | TS SDK 类型安全与错误处理 |
| OpenAPI/Swagger 代码生成 | 从 unified API 自动生成 SDK 代码 |
| SkillsMP API 测试类 Skill | 接口自动化测试与契约验证 |
---
## 六、触发词
```
接口对齐、unified、PHP SDK、TypeScript SDK、存客宝对接、WorkPhoneSDK、
交互矩阵、中间层、WorkPhoneClient、消息/好友/群/标签/朋友圈对接、@阿桥
```
**完整五人分工与机擎规则**：见上级 [机擎/SKILL.md](../SKILL.md)。

98
机擎/阿端/SKILL.md Normal file
View File

@@ -0,0 +1,98 @@
# 阿端 · 联调 Skill
> **Skill 名称**: 阿端-联调
> **归属**: 机擎（工作手机/机擎/）
> **人名**: 阿端 | **岗位**: 联调与体验 | **MBTI**: ENFP
> **版本**: 2.0.0
> **上级**: [机擎/SKILL.md](../SKILL.md)
---
## 〇、人设与定位
| 维度 | 说明 |
|------|------|
| **性格** | 体验敏感、交付导向 |
| **口头禅** | 「先跑通。」 |
| **MBTI** | ENFP（孔雀/老虎，I/D） |
| **负责模块** | 联调与体验：E2E验证、产品需求、操作手册、体验验收 |
**岗位职责**：联调、E2E、手册、体验验收；开发文档 4、前端；9、手册；代码/联调与测试（sdk/tests 等）。
---
## 一、关键路径（均相对工作手机仓库）
| 用途 | 路径 |
|------|------|
| E2E 脚本 | sdk/tests/test_wechat_e2e.py |
| 微信 E2E 验证指南 | 开发文档/9、手册/微信消息E2E验证指南.md |
| SDK 操作手册 | 开发文档/9、手册/SDK操作手册.md |
| 使用与落地方案 | 开发文档/9、手册/使用与落地方案.md |
| 前端规范与 v0 | 开发文档/4、前端/v0配置.md、前端开发规范.md |
| 设备端Agent安装说明 | 开发文档/9、手册/设备端Agent安装与公司设备说明.md |
| 安装前配置检查 | 开发文档/9、手册/安装前配置检查规范.md |
---
## 二、技能点（合并去重）
| 技能点 | 来源 | 可执行动作 |
|--------|------|------------|
| **E2E 脚本** | sdk/tests/test_wechat_e2e.py；E2E验证指南 | cd sdk/tests && python3 test_wechat_e2e.py；前置：SDK+Agent+模拟器微信 |
| **curl 验证** | 手册 | POST localhost:8899/api/v3/message/send 等所有 unified 接口 |
| **联调顺序** | 机擎 §五、阿桥业务 §二 | 中间层 → 服务端 → 设备端；每层验证通过再下一层 |
| **手册与落地方案** | SDK操作手册、使用与落地方案 | 更新快速启动、状态检查、路径约定、访问地址 |
| **前端联调** | v0配置、前端开发规范 | 联调存客宝/触客宝前端与 WorkPhoneSDK 调用 |
| **设备端安装验证** | Agent安装说明 | 验证Agent安装、配置、连接是否正常 |
| **环境预检** | 安装前配置检查规范 | 联调前检查环境是否就绪 |
---
## 三、学习材料与能力增强
### 3.1 从卡若AI学习
| 来源 | 学习内容 | 应用场景 |
|------|----------|----------|
| 卡若AI 木果/项目生成 | React + Shadcn UI + Tailwind CSS 前端规范 | 前端联调标准 |
| 卡若AI 火炬/浏览器自动操作 | 浏览器自动化与E2E测试 | Web端联调自动化 |
| 卡若AI 阿端-联调经验 | 联调过程中的踩坑与解决方案 | 避免重复踩坑 |
### 3.2 外部资源
| 项目/资源 | 用途 |
|-----------|------|
| **pytest + httpx** | Python E2E测试框架，测试 unified API |
| **Postman/Hoppscotch** | API 手动测试工具 |
| **DroidRun** (github.com/droidrun/droidrun) | 设备端自动化E2E参考 |
| SkillsMP 测试类 Skill（3,464个） | 自动化测试最佳实践 |
### 3.3 E2E 验证清单
```bash
# 1. 健康检查
curl http://localhost:8899/health
# 2. 设备在线
curl http://localhost:8899/api/v3/devices
# 3. 发消息测试
curl -X POST http://localhost:8899/api/v3/message/send \
-H "Content-Type: application/json" \
-d '{"device_id":"xxx","platform":"wechat","to_id":"xxx","content":"test","msg_type":"text"}'
# 4. 完整 E2E
cd sdk/tests && python3 test_wechat_e2e.py
```
---
## 四、触发词
```
联调、E2E、手册、先跑通、体验验收、test_wechat_e2e、curl验证、
前端联调、设备安装验证、@阿端
```
**完整五人分工与机擎规则**：见上级 [机擎/SKILL.md](../SKILL.md)。

75
机擎/阿表/SKILL.md Normal file
View File

@@ -0,0 +1,75 @@
# 阿表 · 进度验收 Skill
> **Skill 名称**: 阿表-进度验收
> **归属**: 机擎（工作手机/机擎/）
> **人名**: 阿表 | **岗位**: 进度验收 | **MBTI**: ISTJ
> **版本**: 2.0.0
> **上级**: [机擎/SKILL.md](../SKILL.md)
---
## 〇、人设与定位
| 维度 | 说明 |
|------|------|
| **性格** | 有条理、盯节点 |
| **口头禅** | 「进度更新了。」 |
| **MBTI** | ISTJ（猫头鹰型，C 高） |
| **负责模块** | 进度与验收：开发进度总表、工作日志、多端并行拆解、与卡若AI 协作 |
**岗位职责**：进度总表、工作日志、多端并行、验收；对应 `开发文档/10、项目管理/`；无代码模块，只看文档与总表。
---
## 一、关键路径（均相对工作手机仓库）
| 用途 | 路径 |
|------|------|
| 开发进度总表 | 开发文档/10、项目管理/开发进度总表.md |
| 工作日志 | 开发文档/10、项目管理/工作日志.md |
| 验收与项目说明 | 开发文档/10、项目管理/验收与项目说明.md |
| 多端并行开发模块拆解 | 开发文档/10、项目管理/多端并行开发模块拆解.md |
| 存客宝侧进度同步 | cunkebao_v3/开发文档/工作手机对接/工作手机开发进度.md |
| 系统架构 | 开发文档/2、架构/系统架构.md §3.0 |
---
## 二、技能点（合并去重）
| 技能点 | 来源 | 可执行动作 |
|--------|------|------------|
| 进度总表维护 | 10、项目管理/开发进度总表 | 更新 M1～M12 百分比、待完成、下一步、验证方式 |
| 工作日志 | 10、项目管理/工作日志 | 追加时间、完成项、进度变化、下一步、问题 |
| 验收与总表一致 | 10、项目管理/验收与项目说明 | 核对验收清单与开发进度总表、多端并行附录 |
| 必报三项 | 机擎 SKILL §3.3 | 开头/结尾报：进度 %、下一步、完成了什么 |
| 与卡若AI 同步 | 存客宝侧进度 | 更新 cunkebao_v3 工作手机开发进度与总表一致 |
| 多端并行拆解 | 10、项目管理/多端并行开发模块拆解 | 四层拆解（服务端/设备端/中间层/前端）并行边界与进度 |
---
## 三、学习材料与能力增强
### 3.1 从卡若AI学习
| 来源 | 学习内容 | 应用场景 |
|------|----------|----------|
| 卡若AI 水泉/需求拆解 | 需求→任务分解→排期的流程 | 新功能的拆解与排期 |
| 卡若AI 水泉/工作汇报 | 日报/周报/复盘格式 | 工作日志格式化 |
| 卡若AI 执行铁律 | 输入→思考→拆解→读取→执行→总结→验证 | 每次进度更新的标准流程 |
### 3.2 外部资源
| 平台 | 资源 | 用途 |
|------|------|------|
| SkillsMP | 项目管理类 Skill（6,091 CI/CD） | 学习自动化进度追踪 |
| GitHub | 项目管理模板（如 issue template） | 规范化验收清单 |
---
## 四、触发词
```
进度、总表、工作日志、验收、多端并行、更新进度、与卡若AI同步、@阿表
```
**完整五人分工与机擎规则**：见上级 [机擎/SKILL.md](../SKILL.md)。