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

chore: 不上传 资料/机擎/.cursor/开发文档/scripts 目录

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
卡若
2026-02-24 14:16:38 +08:00
parent 5281dec8a3
commit ef4c68c66c
82 changed files with 7 additions and 17748 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
.cursor/rules/workphone.mdc
View File

@@ -1,44 +0,0 @@
---
description: 工作手机项目规则 - 机擎小组全员参与、开发文档与代码约定
globs:
alwaysApply: true
---
# 工作手机项目 Cursor 规则
本规则适用于**工作手机**项目（工作手机SDK v3.0 — 存客宝的 AI 手机控制引擎）。在本项目内进行开发或对话时，必须遵守以下约定。
## 一、项目管理入口（必读）
- **机擎 Skill**：`机擎/SKILL.md` 为本项目**唯一项目管理入口**。
- **每次对话开始**：先读取 `机擎/SKILL.md`（至少 § 〇、〇.二、三、一），再按其中规则执行。
- **进度只看两处**：`开发文档/10、项目管理/开发进度总表.md`、`开发文档/2、架构/系统架构.md` §3.0。
## 二、机擎规则（必守）
- **每次开发、每次对话**都**调用机擎小组全体成员**（阿表、阿机、阿桥、阿端、阿服）参与——对话开始时按机擎 § 三 整理项目、全员就位，再按岗位分配任务；不得只调用单人。
- **任务分配**：由火炬/机擎按 `机擎/SKILL.md` § 一 岗位职责分配；关键词可自动认领（进度→阿表，unified/服务端/设备端→阿机，接口/SDK/对接→阿桥，联调/E2E→阿端，部署/Docker→阿服）。
- **能力增强**：每人SKILL.md内含学习材料（卡若AI Skill + GitHub开源项目 + SkillsMP），遇到不会的先查对应学习材料，再向卡若AI请教。
- **管理与开发协同**：**管理的人**可以**以聊天形式**向**开发的人**要需求、要方案；开发侧理解→给方案或直接做→汇报；协同闭环（需求↔方案↔开发），详见机擎 § 〇.五四。
- **执行流程**：`输入 → 思考(理解) → 拆解(计划) → 读取(机擎SKILL+开发文档) → 按步执行 → 每步总结 → 验证结果`（与卡若AI 一致）。
## 三、开发文档与代码约定
- **开发文档唯一位置**：所有开发文档内容必须在 **开发文档/** 目录下；不在此目录外新增开发文档；新增文档归入 1、需求 … 10、项目管理 对应子目录。
- **每目录最多 3 个主文档**：开发文档下每子目录除 README 外最多 3 个主文档；超过须合并，合并时不得丢失数据。
- **代码根目录**：`sdk/`（服务端 `sdk/app/`，设备端 `sdk/agent/`，中间层 `sdk/php-sdk/`、`sdk/typescript-sdk/`）。
## 四、五人岗位与路径速查（1人=1目录，合并升级版 v2.0）
| 人名 | 岗位 | SKILL路径 | 开发文档 | 代码模块 |
|------|------|-----------|----------|----------|
| 阿表 | 进度验收 | 机擎/阿表/SKILL.md | 10、项目管理 | 无 |
| 阿机 | 后端Agent | 机擎/阿机/SKILL.md | 6、后端 | sdk/app、sdk/agent |
| 阿桥 | 对接中间层 | 机擎/阿桥/SKILL.md | 5、接口 | sdk/php-sdk、sdk/typescript-sdk |
| 阿端 | 联调 | 机擎/阿端/SKILL.md | 4、前端；9、手册 | sdk/tests/ |
| 阿服 | 部署 | 机擎/阿服/SKILL.md | 8、部署；7、数据库 | sdk/scripts/、docker |
## 五、对话结束时
- 若有进度或文档变更：更新 `开发文档/10、项目管理/工作日志.md`、必要时更新 `开发进度总表.md`。
- 汇报：完成了什么、当前进度 %、下一步做什么。

7
.gitignore vendored
View File

@@ -1,5 +1,12 @@
# 工作手机项目 .gitignore
.DS_Store
# 不上传的目录
资料/
机擎/
.cursor/
开发文档/
scripts/
*.py[cod]
__pycache__/
.idea/

18
scripts/sync_to_gitea_github.sh
View File

@@ -1,18 +0,0 @@
#!/bin/bash
# ============================================
# 工作手机 SDK → Gitea + GitHub 双推
# 用法：在项目根目录执行 bash scripts/sync_to_gitea_github.sh
# ============================================
REPO_DIR="/Users/karuo/Documents/开发/2、私域银行/工作手机"
cd "$REPO_DIR" || exit 1
# 提交变更
git add -A
if git diff --cached --quiet; then
echo "无变更，跳过"
exit 0
fi
git commit -m "chore: $(date '+%Y-%m-%d %H:%M') 同步 | 工作手机 SDK 更新"
# 推送（github 优先，gitea 需先创建仓库）
git push github main 2>/dev/null && echo "✅ GitHub 推送成功" || echo "⚠️ GitHub 推送失败"
git push gitea main 2>/dev/null && echo "✅ Gitea 推送成功" || echo "⚠️ Gitea: 需先在 open.quwanzhi.com 创建 fnvtk/workphone-sdk 仓库"

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

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.0 MiB

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

@@ -1,19 +0,0 @@
# 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
View File

@@ -1,46 +0,0 @@
# 五方向学习与调查结论
> **来源**：用户要求安置五个问题方向，向卡若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 与本文档。

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

@@ -1,497 +0,0 @@
# 工作手机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 | 机擎复刻 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、继续开发、解决所有问题和验证"

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

@@ -1,63 +0,0 @@
# 工作手机SDK v3.0 - 开发进度总表
> **更新**: 2026-02-07 | **总进度**: 100%
> **唯一进度文档**，按 M1～M12 管理；详细架构见 [系统架构.md](../2、架构/系统架构.md) §3.0。
---
## 一、一眼看懂（每次对话必报）
| 项目 | 内容 |
|------|------|
| **当前进度** | **100%**（整体） |
| **下一步** | 维护与迭代；M6 抓包按需；E2E 全绿需本地「SDK+Agent+模拟器微信」后执行 test_wechat_e2e.py |
| **本次完成** | 抖/红/闲鱼与设备端联调契约（接口规范 §1.5）；AI Agent 设备端接 SkillExecutor（微信/抖音任务可执行）；验收与进度更新至 100% |
**进度条**：`██████████████████████` 100%
**待选**：M6 抓包（按需）、微信 E2E 全绿（需环境后跑 test_wechat_e2e.py）。
---
## 二、按模块进度（M1～M12）
| 模块 | 进度 | 说明 |
|------|------|------|
| M1 接入与网关 | ✅ 100% | 健康检查、统一 API |
| M2 设备与连接 | ✅ 100% | WebSocket、心跳、在线 |
| M3 指令与执行 | ✅ 100% | 指令路由、ADB/WS 双模式 |
| M4 设备管理 | ✅ 100% | 设备列表、MongoDB |
| M5 脚本引擎 | ✅ 100% | 微信/抖/红/闲鱼 Skill；联调契约已写；发消息超时可配置+timeout |
| M6 抓包 | 📋 按需 | Frida、按需排期 |
| M7 队列调度 | ✅ 基础 | 当前够用 |
| M8 设备端 Agent | ✅ 100% | 各 Skill、event/device_request |
| M9 存客宝对接 | ✅ 100% | PHP/TS SDK、统一 API |
| M10 数据与存储 | ✅ 100% | MongoDB、Redis、MySQL |
| M11 部署运维 | ✅ 100% | Docker、文档 |
| M12 AI Agent | ✅ 100% | 设备端 agent_execute 接 SkillExecutor（微信/抖音任务可执行） |
---
| 功能 | 验证 |
|------|------|
| SDK 启动、ADB、截图、点击、滑动、APP 控制 | curl :8899/health、adb devices |
| WebSocket Agent、心跳、统一发消息 | devices_online:1、双模式 |
| PHP/TS SDK、存客宝前端、触客宝前端 | localhost:3000/3001、WorkPhoneSDK |
| MongoDB、Redis、API 文档、安装脚本、对接文档 | 见 8、部署/本地环境凭证 |
---
## 四、待完成（优先级）
| 优先级 | 任务 |
|--------|------|
| ~~🔴 高~~ | ~~模拟器装微信 APK~~ 验收已达标，E2E 脚本已就绪 |
| ~~🟡 中~~ | ~~抖/红/闲鱼 联调 + E2E + AI Agent 联调~~ ✅ 契约已写、Agent 已接 SkillExecutor |
| 🟢 可选 | 微信 E2E 全绿：本地启动 SDK+Agent+模拟器微信后执行 `sdk/tests/test_wechat_e2e.py` |
| 🟢 低 | Frida 抓包（按需） |
---
## 五、凭证
- **账号**: 15880802661 **密码**: kr123456
- 详见 [本地环境凭证.md](../8、部署/本地环境凭证.md)

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

@@ -1,135 +0,0 @@
# 验收与项目说明（合并）
> 合并自：验收清单、对接清单、差距分析与完成报告、开发计划、项目管理说明与计划 | 更新：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`。

17
开发文档/1、需求/README.md
View File

@@ -1,17 +0,0 @@
# 1、需求
**项目**：工作手机SDK v3.0（存客宝的 AI 手机控制引擎，替代奥创，支持微信/抖音/小红书/闲鱼等多 APP 控制。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 96%；进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准，模块拆解见 [2、架构/系统架构.md](../2、架构/系统架构.md) §3.0。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [项目概述.md](项目概述.md) | 项目背景、愿景、与存客宝关系 |
| [业务需求.md](业务需求.md) | 功能清单、用户画像、MVP 范围 |
| [成本与需求澄清.md](成本与需求澄清.md) | 成本估算摘要 + 需求澄清结论 |

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

@@ -1,301 +0,0 @@
# 工作手机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 | 初始版本 | 卡若 |

63
开发文档/1、需求/成本与需求澄清.md
View File

@@ -1,63 +0,0 @@
# 工作手机SDK v3.0 - 成本与需求澄清
> 合并自《成本估算》+《需求澄清记录_20260126》| 更新：2026-02-07
---
## 一、成本估算摘要
### 1.1 与商业方案对比（100台设备）
| 方案 | 月成本 | 年成本 |
|------|--------|--------|
| 奥创 | 30,000-50,000元 | **360,000-600,000元** |
| **自研方案** | **800元** | **~10,000元** |
**年度节省：35-59万元 | 节省比例 97%+**
### 1.2 自研成本明细
| 类型 | 金额/规模 |
|------|-----------|
| 一次性投入 | ~5,400元（测试机+首月服务器+SSL） |
| 小型≤50台 | ~210元/月 |
| 中型50-200台 | ~1,410元/月 |
| 大型200-1000台 | ~6,050元/月 |
### 1.3 人力与ROI
- 开发：1后端+1移动端，10周；运维约14h/月。
- 回本周期：约5天（100台对比奥创）；3年ROI约228倍。
---
## 二、需求澄清结论
### 2.1 目标与边界
| 项 | 结论 |
|----|------|
| 核心目标 | 替代奥创所有功能并超越 |
| 控制APP | 微信、抖音、小红书、闲鱼 |
| 设备规模 | 无限量，按服务器性价比 |
| 使用方 | 存客宝内部 + 对外SaaS |
| 脚本 vs AI | 80% 脚本 + 20% AI |
### 2.2 奥创功能清单（需替代）
微信管理（聊天存档、话术库、客户标签、定时发圈等）、微信风控、设备管理、客户运营、私域营销、数据统计。
### 2.3 硬性约束
- **上线时间**：4-8周（第一阶段）
- **开发资源**：2人全职
- **核心指标**：稳定性
### 2.4 资源与风险
- 测试设备：5台（红米11/13）；设备离线：WebSocket重连；APP更新：自定义更新、团队维护。
- 互联网资源：闲鱼有完整开源方案；抖音有WSS/私信框架；微信/小红书需自研抓包+UI自动化。
---
**详见**：原《成本估算》全文已压缩如上；原《需求澄清记录》四轮问答与奥创功能清单已摘录。

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

@@ -1,193 +0,0 @@
# 工作手机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)

17
开发文档/2、架构/README.md
View File

@@ -1,17 +0,0 @@
# 2、架构
**项目**：工作手机SDK v3.0（FastAPI + WebSocket + 设备端 Agent，M1～M12 模块见系统架构 §3.0。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 96%；M1～M4、M7～M11 已 100%，M5/M8 约 75%～95%，M6 待做、M12 约 50%。进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [系统架构.md](系统架构.md) | 整体架构图、**§3.0 模块拆分与开发视图（M1～M12）**、数据流、部署 |
| [技术选型与数据库.md](技术选型与数据库.md) | 技术选型（Part A）+ 数据库设计（Part B） |
| [对接与方案补充.md](对接与方案补充.md) | 存客宝对接架构、AI 方案摘要、优化技术方案摘要 |

69
开发文档/2、架构/对接与方案补充.md
View File

@@ -1,69 +0,0 @@
# 存客宝对接与方案补充
> 合并自：存客宝工作手机对接架构 + AI控制方案摘要 + 优化技术方案摘要 | 更新：2026-02-07
---
## 一、存客宝 + 工作手机对接架构（本地环境）
### 1.1 总体架构
```
[ 服务器 & 控制层 API ] ← 存客宝 ThinkPHP / 控制中心 FastAPI
↓
[ 设备管理 & 心跳系统 ] ← WebSocket Hub、DeviceManager
↓
[ 工作手机 SDK ] ← Agent (Termux/模拟器) + uiautomator2
↓
[ 微信 & 手机系统 ] ← 安卓设备 / 模拟器
↓
[ 存客宝 & 本地数据库 ] ← MySQL + MongoDB + Redis
```
### 1.2 本地环境端口与组件
| 组件 | 端口 | 说明 |
|------|------|------|
| 存客宝前端 | 3000 | React |
| 触客宝前端 | 3001 | React |
| 存客宝后端 | 8081 | ThinkPHP |
| 工作手机 SDK | 8899 | FastAPI + WebSocket |
| MySQL | 3307 | cunkebao 108表 |
| MongoDB | 27017 | workphone_sdk |
| Redis | 6380 | 缓存 |
### 1.3 三大闭环
- **数据闭环**：存客宝 DB ↔ AI 数字员工可读写
- **设备管理闭环**：注册 → 心跳(5/10/30s 可配置) → 在线/离线
- **操作闭环**：服务器 → SDK → 手机执行 → 结果回传
### 1.4 通信机制（原存客宝工作手机对接架构）
- **心跳**：手机→服务器；间隔 5s/10s/30s 可配置；内容含设备 ID、微信状态、当前任务、电量/网络。
- **指令**：服务器→手机；队列执行、支持重试；ACK：command_id + response。
### 1.5 技术约束
不用奥创；工作手机 = SDK + 控制中心 API；服务器为唯一控制中心；设备状态实时反馈。
**操作入口**：[9、手册/SDK操作手册.md](../9、手册/SDK操作手册.md)
---
## 二、AI Agent 方案摘要
- **定位**：自然语言控制手机，与脚本模式双轨（80% 脚本 + 20% AI）。
- **参考**：DroidRun（Accessibility + LLM）、AppAgent（视觉 LLM）；本方案 u2 + Frida + 可选 LLM。
- **成本**：脚本免费；AI 约 ¥0.02/次，按需启用。
- 详见原《AI控制方案》全文（已合并入本目录历史）。
---
## 三、优化技术方案摘要（6 周）
- **路线**：协议优先 + UI 兜底；闲鱼用 XianYuApis，抖音 WSS+UI，微信/小红书 u2。
- **Phase 1-2**：服务端骨架、设备端骨架、WebSocket、设备管理 API。
- **Phase 3-4**：微信/抖音/小红书/闲鱼 Skill，统一服务交互层。
- **Phase 5-6**：抓包、AI Agent 集成、压测与上线。
- 详见原《优化技术方案_v2》全文（已合并入本目录历史）。

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

@@ -1,831 +0,0 @@
# 工作手机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()
})
```

512
开发文档/2、架构/系统架构.md
View File

@@ -1,512 +0,0 @@
# 工作手机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 |

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

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

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

@@ -1,324 +0,0 @@
# 工作手机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
View File

@@ -1,16 +0,0 @@
# 4、前端
**项目**：工作手机SDK v3.0（前端以存客宝/触客宝为主；本目录为前端规范与 v0 配置，供集成或扩展使用。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 96%；存客宝/触客宝前端已跑通（3000/3001）。进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [v0配置.md](v0配置.md) | v0 配置 |
| [前端开发规范.md](前端开发规范.md) | 前端开发规范 |

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

@@ -1,185 +0,0 @@
# 🎨 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
View File

@@ -1,623 +0,0 @@
# 工作手机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
```

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

@@ -1,17 +0,0 @@
# 5、接口
**项目**：工作手机SDK v3.0（统一 API 供存客宝调用：/api/v3/message/send 等；ADB/WebSocket 双模式，认证与错误码见接口规范。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 96%；PHP/TS SDK、统一 API、登录认证已闭环。进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [接口规范.md](接口规范.md) | 统一 API（存客宝/前端调用主入口） |
| [存客宝对接规范.md](存客宝对接规范.md) | 存客宝侧对接规范 |
| [通用服务交互层.md](通用服务交互层.md) | 统一服务交互层（Facade、路由） |

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

@@ -1,803 +0,0 @@
# 🔗 存客宝接口对接规范 (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
View File

@@ -1,692 +0,0 @@
# 工作手机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
View File

@@ -1,851 +0,0 @@
# 工作手机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
View File

@@ -1,114 +0,0 @@
# 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
View File

@@ -1,19 +0,0 @@
# 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
View File

@@ -1,124 +0,0 @@
# 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
View File

@@ -1,483 +0,0 @@
# 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
View File

@@ -1,897 +0,0 @@
# 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
View File

@@ -1,953 +0,0 @@
# 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
View File

@@ -1,769 +0,0 @@
# 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
```

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

@@ -1,303 +0,0 @@
# 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
View File

@@ -1,438 +0,0 @@
# 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
View File

@@ -1,466 +0,0 @@
# 闲鱼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
View File

@@ -1,273 +0,0 @@
# 抖音私信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
View File

@@ -1,435 +0,0 @@
# 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
View File

@@ -1,132 +0,0 @@
# 工作手机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
View File

@@ -1,254 +0,0 @@
# 工作手机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
View File

@@ -1,44 +0,0 @@
# 工作手机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
View File

@@ -1,36 +0,0 @@
# 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
View File

@@ -1,62 +0,0 @@
# 数据库管理规范 (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
View File

@@ -1,100 +0,0 @@
# 数据库设计文档
> **更新**: 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 |

19
开发文档/8、部署/README.md
View File

@@ -1,19 +0,0 @@
# 8、部署
**项目**：工作手机SDK v3.0（本地 Docker + 一键 start_sdk.sh；端口 8899、3307、6380、27017 等见本地环境凭证。）
**规则**：本目录除本 README 外最多 **3 个主文档**，与全站开发文档规则一致；超出须合并。
**当前项目状态**：总进度 100%；M11 部署与运维 100%。进度以 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md) 为准。
**跨环境一致性**：同一套通过环境变量控制——`MONGO_URI`、`REDIS_URL`、`MESSAGE_SEND_TIMEOUT`、`API_KEY` 等见 `sdk/app/.env.example`；首次建库执行 `cd sdk/app && python3 scripts/init_db.py`；端口与凭证见 [本地环境凭证.md](本地环境凭证.md)。
---
## 本目录主文档（≤3）
| 文档 | 说明 |
|------|------|
| [本地Docker部署指南.md](本地Docker部署指南.md) | 本地 Docker 部署 |
| [本地环境凭证.md](本地环境凭证.md) | 账号、端口、访问地址（必看） |
| [部署流程与提示词.md](部署流程与提示词.md) | CI/CD、Webhook、运维提示词 |

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

@@ -1,149 +0,0 @@
# 本地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
```

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

@@ -1,79 +0,0 @@
# 本地环境凭证登记表
> **统一测试账号**: 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管理 |

52
开发文档/8、部署/部署流程与提示词.md
View File

@@ -1,52 +0,0 @@
# 部署流程与提示词（合并）
> 合并自：Next.js 自动化部署、WEBHOOK 部署提示词、宝塔 Webhook 文档、项目程序提示词 | 更新：2026-02-07
---
## 一、工作手机 SDK 部署主入口
- **本地/生产**：以 [本地Docker部署指南.md](本地Docker部署指南.md) 为主。
- **环境凭证**：见 [本地环境凭证.md](本地环境凭证.md)。
---
## 二、CI/CD 与 Webhook（可选参考）
- **Next.js 项目**：GitHub Webhook → 宝塔面板 → `git pull` / `npm install` / `npm run build` / `pm2 reload`。
- **前提**：GitHub 仓库、宝塔（Nginx/Node/PM2/Git）、域名解析；Webhook 插件 + 标准脚本模板。
- **工作手机** 当前以 Docker 一键部署为主，Webhook 用于前端/Next 项目时可复用上述流程。
---
## 三、项目程序/运维提示词要点
- 部署架构：负载均衡 → 多 SDK 节点 → Redis/MongoDB/MinIO。
- 故障排查：权限、端口、日志、健康检查。
- 详细运维见原《项目程序提示词》与《基于 GitHub Webhook 与宝塔面板的自动化部署流程文档》（已合并入本目录历史）。
---
## 四、本地全链路执行清单
**目标**：存客宝 + 工作手机（SDK 控制微信）在本机完整跑通；账号 15880802661 / kr123456（仅测试环境）。
### 阶段 1：基础环境搭建
- **Docker/DB**：`docker start datacenter_mongodb`；存客宝需 MySQL+Redis 时 `cd cunkebao_v3 && docker-compose up -d mysql redis`。
- **SDK 服务**：`cd 工作手机/sdk && ./scripts/start_sdk.sh`，验证 `curl -s http://localhost:8899/health`。
- **存客宝**（可选）：`cd cunkebao_v3 && docker-compose up -d --build`；后端配置 `WORKPHONE_SDK_URL=http://localhost:8899`。
### 阶段 2：工作手机连接
- **ADB**：`adb devices`，模拟器或真机。
- **Agent**：`cd sdk/agent && python agent.py --device-id emulator-5554 --server ws://本机IP:8899/ws/device --heartbeat 10`；验证 `GET /api/v3/devices` 有设备且 `status: online`、`last_heartbeat` 更新。
- **微信**：设备安装微信并登录（测试账号同上）。
### 阶段 3：全链路测试
- **发消息**：`POST /api/v3/unified/message/send`，body：`device_id`、`platform: wechat`、`to_id`、`content`。期望 `code: 200`、`data.success: true`。
- **状态与日志**：设备注册与心跳落库 MongoDB `devices`；命令执行落库 `commands`；存客宝通过 WorkPhoneSDK 调 8899 验证回传。
**验收自检**：本机可访问所有服务；工作手机状态与服务器同步；微信任务执行结果回传；数据/设备管理/操作闭环正常。详见 [验收清单.md](../验收清单.md)。

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

@@ -1,17 +0,0 @@
# 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
View File

@@ -1,96 +0,0 @@
# 工作手机 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
View File

@@ -1,50 +0,0 @@
# 会议电视 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
View File

@@ -1,22 +0,0 @@
# 使用与落地方案（合并）
> 合并自：使用手册提示词、系统使用手册、落地方案提示词、说明手册提示词 | 更新：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
View File

@@ -1,52 +0,0 @@
# 工作手机 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
View File

@@ -1,75 +0,0 @@
# 微信消息 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
View File

@@ -1,79 +0,0 @@
# 设备端 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
View File

@@ -1,76 +0,0 @@
# 工作手机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
View File

@@ -1,319 +0,0 @@
# 机擎项目管理 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
View File

@@ -1,46 +0,0 @@
# 工作手机 中间层 抽象
> **位置**: 工作手机/存客宝项目管理/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
View File

@@ -1,69 +0,0 @@
# 工作手机 服务端 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
View File

@@ -1,34 +0,0 @@
# 工作手机 设备端 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

73
机擎/scripts/check_system.sh
View File

@@ -1,73 +0,0 @@
#!/bin/bash
# 存客宝项目 - 系统状态检查脚本
# 位置：工作手机/存客宝项目管理/scripts/
# 每次对话开始时执行
echo "=========================================="
echo " 存客宝私域银行系统 - 状态检查"
echo " 时间: $(date '+%Y-%m-%d %H:%M:%S')"
echo "=========================================="
echo ""
# 1. Docker服务检查
echo "--- Docker服务 ---"
for svc in workphone-sdk cunkebao-server cunkebao-web touchkebao-web cunkebao-mysql cunkebao-redis datacenter_mongodb; do
STATUS=$(docker inspect -f '{{.State.Status}}' $svc 2>/dev/null)
if [ "$STATUS" = "running" ]; then
echo " ✅ $svc: 运行中"
elif [ -n "$STATUS" ]; then
echo " ⏸ $svc: $STATUS"
else
echo " ❌ $svc: 未创建"
fi
done
echo ""
# 2. 健康检查
echo "--- 健康检查 ---"
SDK_HEALTH=$(curl -s http://localhost:8899/health 2>/dev/null)
if [ -n "$SDK_HEALTH" ]; then
echo " ✅ 工作手机SDK: $SDK_HEALTH"
else
echo " ❌ 工作手机SDK: 未响应"
fi
for port_name in "3000:存客宝前端" "3001:触客宝前端" "8080:后端API"; do
PORT=${port_name%%:*}
NAME=${port_name##*:}
if curl -s -o /dev/null -w "%{http_code}" http://localhost:$PORT 2>/dev/null | grep -q "200\|301\|302"; then
echo " ✅ $NAME (端口$PORT): 可访问"
else
echo " ⏸ $NAME (端口$PORT): 未启动"
fi
done
echo ""
# 3. ADB设备
echo "--- ADB设备 ---"
DEVICES=$(adb devices 2>/dev/null | grep -v "List" | grep "device" | wc -l | tr -d ' ')
echo " 在线设备数: $DEVICES"
adb devices 2>/dev/null | grep -v "List" | grep "device" | while read line; do
SERIAL=$(echo $line | awk '{print $1}')
MODEL=$(adb -s $SERIAL shell getprop ro.product.model 2>/dev/null | tr -d '\r')
VERSION=$(adb -s $SERIAL shell getprop ro.build.version.release 2>/dev/null | tr -d '\r')
echo " 📱 $SERIAL: $MODEL (Android $VERSION)"
done
echo ""
# 4. 端口占用检查
echo "--- 端口占用 ---"
for port in 3000 3001 3002 8080 8899 3307 6380 27017 5554 5555 6080; do
PID=$(lsof -ti :$port 2>/dev/null | head -1)
if [ -n "$PID" ]; then
PROC=$(ps -p $PID -o comm= 2>/dev/null)
echo " 端口 $port: 占用 (PID:$PID $PROC)"
else
echo " 端口 $port: 空闲"
fi
done
echo ""
echo "=========================================="
echo " 检查完毕"
echo "=========================================="

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

@@ -1,117 +0,0 @@
# 阿服 · 部署 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
View File

@@ -1,119 +0,0 @@
# 阿机 · 后端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
View File

@@ -1,149 +0,0 @@
# 阿桥 · 对接中间层 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
View File

@@ -1,98 +0,0 @@
# 阿端 · 联调 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
View File

@@ -1,75 +0,0 @@
# 阿表 · 进度验收 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)。

354
资料/XESlciw与Frida及机擎详细对比分析.md
View File

@@ -1,354 +0,0 @@
# XESlciw 与 Frida 及机擎（工作手机SDK）详细对比分析
> **创建**：2026-02-10 | **用途**：选型决策、功能对标、接口清单
> **相关文档**：《XESlciw接口与设备Hook开发手册》《XESlciw详解与技术方案对比》《系统架构》
---
## 一、三者概览
| 维度 | XESlciw | Frida | 机擎（工作手机SDK v3.0） |
|------|---------|-------|---------------------------|
| **本质** | LSPosed 系 Xposed 框架（奥创定制） | 动态插桩工具（脚本注入） | 私域工作手机控制中台 |
| **部署** | Magisk 模块，设备端常驻 | 设备端 frida-server/Gadget，或主机端 attach | 云端服务 + 设备端 Agent + ADB |
| **Root 要求** | 必须 Root + Magisk | 可选（Gadget 免 Root） | 免 Root 为主，可选 Root |
| **主要用途** | 微信/APP 深度 Hook、数据采集 | 逆向、抓包、调试、Hook | 消息发送、好友/群管理、朋友圈、自动化 |
| **语言** | Java + Native C/C++ | JavaScript + Python 绑定 | Python 服务端 + JS/TS SDK |
| **商业化** | 闭源、奥创专用 | 开源、GPL | 自研、存客宝生态 |
---
## 二、XESlciw 与 Frida 详细对比
### 2.1 架构对比
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ XESlciw 架构 │
├─────────────────────────────────────────────────────────────────────────────┤
│ Magisk → XESlciw 框架 → Scope 指定 APP → 模块 APK │
│ → assets/grvjfe_init (Java 入口) + assets/native_init (so) │
│ → native_init(entries) 返回 on_library_loaded │
│ → entries->hook_func(target, replace, backup) 做 Native Hook │
│ → 可选 Java IXposedHookLoadPackage 做 Java 层 Hook │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ Frida 架构 │
├─────────────────────────────────────────────────────────────────────────────┤
│ 主机 frida / 设备 frida-server / 内嵌 Gadget │
│ → 注入 V8/QJS 引擎 │
│ → JavaScript 脚本：Interceptor.attach / Java.perform / ... │
│ → 实时 attach/detach，无需重启 APP │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 2.2 能力对比
| 能力 | XESlciw | Frida | 说明 |
|------|:-------:|:-----:|------|
| **Java 方法 Hook** | ✅ 传统 Xposed API | ✅ Java.perform + Java.use | XESlciw 需 compileOnly Xposed API |
| **Native 函数 Hook** | ✅ 通过 entries->hook_func | ✅ Interceptor.attach | Frida 更灵活，可随时 attach |
| **Syscall 级 Hook** | ✅ VivWxjz 已实现 | ⚠️ 需自写 Native | XESlciw 现成，Frida 需 CModule 等 |
| **脚本热更新** | ❌ 需重装模块 | ✅ 随时重载脚本 | Frida 开发效率高 |
| **多进程支持** | ✅ Scope 指定包名 | ✅ spawn/attach 指定 | 都支持 |
| **跨平台** | ❌ 仅 Android | ✅ Android / iOS / Win / Linux / macOS | Frida 通用 |
| **免 Root** | ❌ 必须 Root | ✅ Gadget 嵌入 APK | Frida 有免 Root 方案 |
| **检测对抗** | 寄生模式、隐藏 Manager | 可配合反检测 | 都需额外手段 |
| **调试/逆向** | ❌ 偏生产 | ✅ 主力场景 | Frida 更适合研发调试 |
| **生产部署** | ✅ 奥创已验证 | ⚠️ 需自建运维 | XESlciw 为商业化产品配套 |
### 2.3 接口清单
#### 2.3.1 XESlciw / Grvjfe 接口
| 接口/配置 | 类型 | 说明 |
|-----------|------|------|
| `assets/grvjfe_init` | 配置 | Java 入口类 + lib 名（如 `top.zzz.vivwxjz.Main` + `libvivwxjz.so`） |
| `assets/native_init` | 配置 | 每行一个 so 库名，框架调用其 `native_init` |
| `native_init(entries)` | 函数 | 必须导出，返回 `NativeOnModuleLoaded` 回调 |
| `entries->version` | 字段 | API 版本 |
| `entries->hook_func(target, replace, backup)` | 函数 | Native Hook |
| `entries->unhook_func(target)` | 函数 | 取消 Hook |
| `on_library_loaded(name, handle)` | 回调 | 库加载时调用，可 dlsym + hook_func |
| `IXposedHookLoadPackage.handleLoadPackage(lpparam)` | Java | 包加载时设置 Hook |
| `META-INF/xposed/scope.list` | 配置 | 每行一个包名，指定生效 APP |
| `META-INF/xposed/module.prop` | 配置 | minApiVersion、targetApiVersion 等 |
#### 2.3.2 Frida JavaScript API（核心）
| 模块 | API | 说明 |
|------|-----|------|
| **Interceptor** | `Interceptor.attach(target, {onEnter, onLeave})` | Native 函数 Hook |
| | `Interceptor.replace(target, replacement)` | 替换函数实现 |
| **Java** | `Java.perform(fn)` | 在 Java 线程执行 |
| | `Java.use(className)` | 获取类，用于 hook 方法 |
| | `Java.choose(className, callbacks)` | 枚举已实例化对象 |
| | `Java.registerClass(spec)` | 动态注册类 |
| **Process** | `Process.id`、`Process.arch` | 进程信息 |
| | `Process.enumerateModules()` | 枚举模块 |
| | `Process.enumerateThreads()` | 枚举线程 |
| **Module** | `Module.findExportByName(module, export)` | 查找导出 |
| | `Module.load(name)` | 加载模块 |
| | `Module.findBaseAddress(name)` | 基址 |
| **Memory** | `Memory.alloc(size)` | 分配内存 |
| | `Memory.scan(address, size, pattern, callbacks)` | 扫描内存 |
| | `Memory.protect(address, size, protection)` | 修改权限 |
| **NativeFunction** | `new NativeFunction(addr, retType, argTypes)` | 调用 Native 函数 |
| **NativeCallback** | `new NativeCallback(fn, retType, argTypes)` | 创建 Native 回调 |
| **NativePointer** | `ptr(address)` | 指针封装 |
| | `readByteArray()`、`writeByteArray()` | 读写内存 |
| **Stalker** | `Stalker.follow(tid, callbacks)` | 指令级追踪 |
| **Socket** | `Socket.listen()`、`Socket.connect()` | 网络 |
| **File** | `File.readAllBytes()`、`File.writeAllBytes()` | 文件 |
| **RPC** | `rpc.exports = { fn() {} }` | 与主机通信 |
---
## 三、机擎（工作手机SDK）功能与接口
### 3.1 技术栈与通道
| 层级 | 技术 | 说明 |
|------|------|------|
| 设备控制 | uiautomator2 | UI 自动化（点击、滑动、输入） |
| 设备控制 | ADB | 离线兜底、Shell 执行 |
| 抓包（M6） | Frida | SSL Bypass、流量采集（待完善） |
| 连接 | WebSocket | 设备主动连云端，实时指令 |
| 智能 | AI Agent (DroidRun) | 自然语言 → 操作规划 |
### 3.2 统一 API 接口清单（HTTP）
**Base**: `https://workphone.xxx.com/api/v3`
**认证**: `Authorization: Bearer {api_key}`
#### 消息管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/message/send` | 发送消息（微信/抖音/小红书/闲鱼） |
| POST | `/message/list` | 获取消息列表 |
| POST | `/message/batch-send` | 批量发送 |
| POST | `/comment/reply` | 回复评论 |
#### 好友管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/friend/add` | 添加好友 |
| POST | `/friend/accept` | 接受好友 |
| POST | `/friend/set-remark` | 设置备注 |
| POST | `/friend/delete` | 删除好友 |
| POST | `/friend/batch-add` | 批量添加 |
| GET | `/contacts` | 获取联系人 |
#### 群聊管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/group/create` | 创建群 |
| POST | `/group/invite` | 邀请入群 |
| POST | `/group/remove` | 移出群 |
| POST | `/group/set-notice` | 设置群公告 |
| POST | `/group/set-name` | 设置群名称 |
| POST | `/group/send-message` | 发群消息 |
| POST | `/group/set-welcome` | 设置群欢迎语 |
| GET | `/group/list` | 群列表 |
| GET | `/group/members` | 群成员 |
#### 标签管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/tag/add` | 添加标签 |
| POST | `/tag/remove` | 移除标签 |
| POST | `/tag/create` | 创建标签 |
| POST | `/tag/delete` | 删除标签 |
| GET | `/tag/list` | 标签列表 |
| POST | `/tag/users` | 按标签取用户 |
#### 朋友圈管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/moments/post` | 发朋友圈 |
| POST | `/moments/like` | 点赞 |
| POST | `/moments/comment` | 评论 |
| POST | `/moments/list` | 朋友圈列表 |
#### 设备管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/devices` | 设备列表 |
| GET | `/devices/{id}` | 设备详情 |
| POST | `/devices/{id}/screenshot` | 截图 |
| POST | `/devices/{id}/click` | 点击 |
| POST | `/devices/{id}/click-text` | 按文本点击 |
| POST | `/devices/{id}/input` | 输入 |
| POST | `/devices/{id}/swipe` | 滑动 |
| GET | `/devices/{id}/ui-tree` | UI 树 |
| POST | `/devices/{id}/execute` | 执行自定义指令 |
#### 抓包（依赖 Frida）
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/capture/start` | 启动抓包 |
| POST | `/capture/stop` | 停止抓包 |
| GET | `/capture/status/{device_id}` | 抓包状态 |
| GET | `/capture/data/{device_id}` | 抓包数据 |
#### AI Agent
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/agent/execute` | 执行 Agent 指令 |
| GET | `/agent/status/{device_id}` | Agent 状态 |
| POST | `/agent/stop/{device_id}` | 停止 Agent |
| GET | `/ai/status` | AI 服务状态 |
| POST | `/ai/chat` | AI 对话 |
| POST | `/v1/chat/completions` | OpenAI 兼容接口 |
#### 其它
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v3/adb/*` | ADB 设备控制 |
| POST | `/api/v3/experience/*` | 经验库、快捷操作 |
| POST | `/qrcode/generate` | 二维码生成 |
### 3.3 WebSocket 协议（设备端 ↔ 服务端）
| 类型 | 方向 | 说明 |
|------|------|------|
| `connect` | 设备→服务端 | 设备注册、上报 device_id |
| `heartbeat` | 双向 | 心跳保活 |
| `execute` | 服务端→设备 | 下发 `{script, action, params}` |
| `response` | 设备→服务端 | 返回 `{command_id, code, message, data}` |
### 3.4 设备端 Skill 与通道路由
| 通道 | 条件 | 用途 |
|------|------|------|
| 官方 API | 抖音等有开放接口 | 直接调用 |
| SDK 控制 | 设备在线 | WebSocket → Skill 脚本 |
| ADB | 设备离线 | u2 + ADB shell |
| AI Agent | 兜底/智能 | 自然语言 → DroidRun |
---
## 四、三者功能合适度分析
### 4.1 机擎 vs XESlciw
| 机擎能力 | XESlciw 可替代/增强？ | 说明 |
|----------|------------------------|------|
| 发消息 | ⚠️ 可增强 | XESlciw 可 Hook 微信发送接口，避免 UI 操作，更快更稳 |
| 获取消息列表 | ⚠️ 可增强 | Hook 消息存储/网络层，直接读数据，不依赖 UI |
| 好友/群/标签 | ⚠️ 可增强 | 同理，Hook 比 UI 自动化更稳定 |
| 朋友圈 | ⚠️ 可增强 | Hook 发朋友圈接口 |
| 抓包 | ✅ 强项 | VivWxjz 已在 syscall 层抓包，机擎 M6 可参考 |
| 免 Root | ❌ 冲突 | XESlciw 必须 Root，机擎主打免 Root |
| 多 APP | ⚠️ 部分 | XESlciw 主要做微信，抖音/小红书需单独模块 |
| 云端中台 | ❌ 无关 | XESlciw 纯设备端，无云端概念 |
### 4.2 机擎 vs Frida
| 机擎能力 | Frida 可替代/增强？ | 说明 |
|----------|----------------------|------|
| 发消息 | ⚠️ 可增强 | Frida Hook 微信 Java/Native，同 XESlciw |
| 抓包 (M6) | ✅ 已规划 | 机擎抓包服务即基于 Frida，需完善 SSL Bypass |
| 设备控制 | ❌ 不替代 | u2/ADB 做 UI，Frida 做 Hook，互补 |
| 免 Root | ✅ 可兼容 | Frida Gadget 免 Root，与机擎策略一致 |
| 开发调试 | ✅ 强项 | Frida 热更新、脚本调试，研发效率高 |
| 生产部署 | ⚠️ 需自建 | 需 frida-server 或 Gadget 注入，运维成本 |
### 4.3 综合对标表
| 功能需求 | XESlciw | Frida | 机擎现状 | 建议 |
|----------|:-------:|:-----:|:--------:|------|
| 微信消息发送 | ✅ 强 | ✅ 可 | ✅ u2/ADB | Root 场景可引入 Hook 加速 |
| 微信消息拉取 | ✅ 强 | ✅ 可 | ✅ u2/ADB | Hook 可减少 UI 依赖 |
| 抖音/小红书 | ⚠️ 需自研模块 | ✅ 可 | ✅ Skill | Frida 更灵活 |
| 抓包/SSL Bypass | ✅ VivWxjz | ✅ 强 | 🔧 待做 | 用 Frida 实现 M6 |
| 免 Root 部署 | ❌ | ✅ | ✅ | 机擎保持免 Root 主线 |
| 云端统一 API | ❌ | ❌ | ✅ | 机擎独有 |
| AI 智能控制 | ❌ | ❌ | ✅ | 机擎独有 |
| 商业化闭环 | 奥创体系 | 开源工具 | 存客宝体系 | 各司其职 |
---
## 五、选型建议
### 5.1 按场景
| 场景 | 首选 | 备选 |
|------|------|------|
| 机擎主产品（免 Root） | u2 + ADB + AI Agent | - |
| 抓包服务 (M6) | Frida | 参考 VivWxjz 思路 |
| Root 设备极致性能 | XESlciw 类 Hook 或 Frida | 需自研/采购模块 |
| 逆向分析、协议研究 | Frida | - |
| 奥创生态复刻 | XESlciw + VivWxjz | - |
### 5.2 按开发阶段
| 阶段 | 建议 |
|------|------|
| 研发/调试 | Frida：热更新、脚本快迭代 |
| 生产部署（免 Root） | 机擎现有方案：u2 + WebSocket + ADB |
| 生产部署（Root） | 评估 XESlciw 类模块 或 Frida Gadget |
| 抓包功能补齐 | 优先 Frida，可借鉴 VivWxjz syscall 思路 |
### 5.3 机擎后续可做事项
1. **M6 抓包**：用 Frida 实现 SSL Bypass，与现有 capture 服务对接。
2. **Root 增强通道**：可选集成 Frida 或自研 Hook 模块，针对已 Root 设备提速。
3. **协议层能力**：若需深度协议（如直接调微信 C++ 接口），可参考 XESlciw/VivWxjz 的 syscall 方案，用 Frida 实现等效逻辑。
4. **保持主线**：免 Root + u2 + AI Agent 作为主通道，Hook 作为可选增强。
---
## 六、接口与功能速查总表
### XESlciw
| 类别 | 接口/配置 | 说明 |
|------|-----------|------|
| 入口 | `assets/grvjfe_init` | Java 类 + so 名 |
| 入口 | `assets/native_init` | so 名列表 |
| Native | `native_init(entries)` | 返回库加载回调 |
| Native | `entries->hook_func` | Hook 函数 |
| Java | `IXposedHookLoadPackage` | 包加载 Hook |
| 配置 | `scope.list` | 作用域包名 |
| 配置 | `module.prop` | 版本等 |
### Frida
| 类别 | 接口 | 说明 |
|------|------|------|
| Hook | `Interceptor.attach` | Native Hook |
| Hook | `Interceptor.replace` | 替换实现 |
| Java | `Java.perform` | 进入 Java 环境 |
| Java | `Java.use` | 获取类并 Hook |
| 内存 | `Memory.*` | 分配、扫描、权限 |
| 调用 | `NativeFunction` | 调 Native |
| 通信 | `rpc.exports` | 与主机交互 |
### 机擎
| 类别 | 接口 | 说明 |
|------|------|------|
| 消息 | `POST /message/send` 等 | 发消息、拉消息、批量 |
| 好友 | `POST /friend/*`、`GET /contacts` | 增删改查 |
| 群聊 | `POST /group/*`、`GET /group/list` 等 | 群管理 |
| 标签 | `POST /tag/*`、`GET /tag/list` | 标签管理 |
| 朋友圈 | `POST /moments/*` | 发、赞、评、列表 |
| 设备 | `GET /devices`、`POST /devices/{id}/*` | 设备控制、截图、点击等 |
| 抓包 | `POST /capture/start` 等 | 启停、状态、数据 |
| AI | `POST /agent/execute` 等 | Agent、聊天 |
| WS | `execute` / `response` | 实时指令与响应 |
---
## 七、参考资料
| 文档 | 路径 |
|------|------|
| XESlciw 接口与 Hook 手册 | `资料/XESlciw接口与设备Hook开发手册.md` |
| XESlciw 详解与技术方案对比 | `资料/XESlciw详解与工作手机技术方案对比.md` |
| 系统架构 | `开发文档/2、架构/系统架构.md` |
| 接口规范 | `开发文档/5、接口/接口规范.md` |
| Frida 官方文档 | https://frida.re/docs/javascript-api/ |
| LSPosed Native Hook | https://github.com/LSPosed/LSPosed/wiki/Native-Hook |

345
资料/XESlciw接口与设备Hook开发手册.md
View File

@@ -1,345 +0,0 @@
# XESlciw 接口与设备 Hook 开发手册
> **目标**：获取 XESlciw/Grvjfe 所有接口、对接方式、功能说明，支撑设备端 Hook 开发
> **来源**：真机 APK 逆向 + LSPosed 公开文档
> **更新**：2026-02-24
---
## 一、XESlciw 与 Grvjfe 命名对照
| XESlciw 内用名 | 对应 | 说明 |
|----------------|------|------|
| **Grvjfe** | LSPosed API | 框架提供的 Hook API |
| **Iztyge** | LSPosed | 框架本身（如 piskmyagk/Iztyge） |
| **XESlciw** | 奥创定制名 | 框架/Manager 的对外名称 |
---
## 二、模块入口与配置
### 2.1 入口声明方式（XESlciw 使用 legacy 风格）
| 类型 | LSPosed 标准 | XESlciw/Grvjfe |
|------|--------------|----------------|
| **Java 入口** | `META-INF/xposed/java_init.list` | `assets/xposed_init` 或 `assets/grvjfe_init` |
| **Native 入口** | `META-INF/xposed/native_init.list` | `assets/native_init` |
### 2.2 VivWxjz 模块的 grvjfe_init 格式
```
top.zzz.vivwxjz.Main
libvivwxjz.so
```
- 第一行：Java 入口类（或仅作加载触发）
- 第二行：Native 库名（不含 lib 前缀和 .so）
### 2.3 assets/native_init 格式
```
libvivwxjz.so
```
每行一个 so 库名，框架在模块加载时调用其中的 `native_init`。
---
## 三、Native Hook 接口（核心 API）
### 3.1 头文件定义（LSPosed Native Hook 标准）
```c
typedef int (*HookFunType)(void *func, void *replace, void **backup);
typedef int (*UnhookFunType)(void *func);
typedef void (*NativeOnModuleLoaded)(const char *name, void *handle);
typedef struct {
uint32_t version;
HookFunType hook_func;
UnhookFunType unhook_func;
} NativeAPIEntries;
typedef NativeOnModuleLoaded (*NativeInit)(const NativeAPIEntries *entries);
```
### 3.2 必须导出的入口函数
```c
extern "C" [[gnu::visibility("default")]] [[gnu::used]]
NativeOnModuleLoaded native_init(const NativeAPIEntries *entries);
```
| 参数 | 说明 |
|------|------|
| `entries` | 框架传入，含 `version`、`hook_func`、`unhook_func`，不可修改 |
| 返回值 | 库加载回调 `NativeOnModuleLoaded`，每次目标进程 `dlopen` 时调用 |
### 3.3 库加载回调
```c
void on_library_loaded(const char *name, void *handle);
```
| 参数 | 说明 |
|------|------|
| `name` | 库路径，如 `/data/app/xxx/lib/arm64/libxxx.so` |
| `handle` | `dlopen` 句柄，用于 `dlsym` 查找符号 |
### 3.4 Hook 函数用法
```c
// 保存 entries->hook_func 供后续使用
static HookFunType hook_func = nullptr;
// 在 native_init 中
hook_func = entries->hook_func;
// 在 on_library_loaded 中 Hook 目标函数
void *target = dlsym(handle, "target_function_name");
void *backup = nullptr;
hook_func(target, (void *)replacement_function, &backup);
```
### 3.5 libvivwxjz.so 导出符号（从 APK 提取）
| 符号 | 说明 |
|------|------|
| `JNI_OnLoad` | JNI 加载入口 |
| `on_library_loaded` | 库加载回调 |
| `native_init` | 框架调用的 Native 入口 |
| `initialize_extension` | 扩展初始化 |
| `kompat_callback` | 兼容回调 |
| `module_main` | 模块主逻辑 |
---
## 四、Java 入口接口（传统 Xposed 风格）
### 4.1 经典接口
| 接口 | 说明 |
|------|------|
| `IXposedHookLoadPackage` | 包加载时回调 |
| `handleLoadPackage(XC_LoadPackage.LoadPackageParam lpparam)` | 在此设置 Hook |
### 4.2 使用示例
```kotlin
class MainHook : IXposedHookLoadPackage {
override fun handleLoadPackage(lpparam: XC_LoadPackage.LoadPackageParam) {
if (lpparam.packageName == "com.tencent.mm") {
System.loadLibrary("vivwxjz") // 加载 Native Hook
}
}
}
```
### 4.3 现代 API（XESlciw 可能部分支持）
- 入口实现：`io.github.libxposed.api.XposedModule`
- 配置：`META-INF/xposed/module.prop`、`scope.list`
---
## 五、Scope 配置
### 5.1 作用
指定模块对哪些 APP 生效。
### 5.2 配置方式
| 方式 | 路径/位置 |
|------|------------|
| **现代** | `META-INF/xposed/scope.list`，每行一个包名 |
| **Manager 内** | 在 XESlciw Manager 中为模块选择作用域 |
### 5.3 微信 Scope 示例
```
com.tencent.mm
```
### 5.4 备份/恢复
- 备份：`Backup module list and scope lists`
- 恢复：`Restore module list and scope lists`
---
## 六、模块配置（module.prop）
### 6.1 标准字段（LSPosed 现代 API）
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `minApiVersion` | int | 是 | 最低 Grvjfe/Xposed API 版本 |
| `targetApiVersion` | int | 是 | 目标 API 版本 |
| `staticScope` | boolean | 否 | 是否禁止用户扩展 Scope |
### 6.2 版本校验（XESlciw 行为）
- 未指定版本：`This module does not specify the Grvjfe version it needs`
- 版本过低：`This module requires a newer Grvjfe version (%d)`
- 版本不兼容：`created for Grvjfe version %1$d, incompatible with version %2$d`
### 6.3 API 调用限制
- `Only module classloader can use Grvjfe API`：仅在模块 ClassLoader 内使用
- `Grvjfe module is not activated yet`：模块未激活
---
## 七、VivWxjz 技术要点（微信 Hook 参考）
### 7.1 技术路线
- **层**：Syscall 级（非 Java 方法 Hook）
- **监控**：`socket`、`connect`、`bind`、`sendmsg`、`recvmsg` 等
### 7.2 监控路径
```
/data/user/0/com.tencent.mm
/data/data/com.tencent.mm/cache/maps
```
### 7.3 相关符号（从 so 提取）
- `translate_socketcall_enter` / `translate_socketcall_exit`
- `parse_binder_data`
- `bind`、`connect`、`listen`、`socket`
### 7.4 模块结构
```
top.zzz.vivwxjz/
├── Main (Java 入口，触发 loadLibrary)
├── libvivwxjz.so (Native Hook)
├── assets/grvjfe_init
└── assets/native_init
```
---
## 八、自研 Hook 模块开发流程
### 8.1 环境
- Magisk + XESlciw（或 LSPosed）
- Android NDK
- 目标：如 `com.tencent.mm`
### 8.2 步骤
```
1. 创建 Android 模块工程
└── build.gradle: compileOnly Xposed API
2. 声明入口
├── assets/grvjfe_init 或 assets/xposed_init
│ └── 你的包名.Main
└── assets/native_init
└── libyour_hook.so
3. 实现 Java 入口（可选，用于 loadLibrary）
└── Main.kt: handleLoadPackage → System.loadLibrary("your_hook")
4. 实现 Native 入口
└── native_init(entries) → 返回 on_library_loaded
5. 实现库加载回调
└── on_library_loaded(name, handle)
└── 若 name 含目标 so → dlsym + hook_func
6. 配置 Scope
└── 在 Manager 中勾选 com.tencent.mm
7. 打包安装
└── 安装 APK → 在 XESlciw Manager 中启用
```
### 8.3 最小 Native 示例
```c
// native_hook.c
#include <dlfcn.h>
#include <string.h>
typedef int (*HookFunType)(void *func, void *replace, void **backup);
typedef void (*NativeOnModuleLoaded)(const char *name, void *handle);
typedef struct {
uint32_t version;
HookFunType hook_func;
void *unhook_func;
} NativeAPIEntries;
static HookFunType g_hook = NULL;
static void on_library_loaded(const char *name, void *handle) {
if (strstr(name, "libyour_target.so")) {
void *target = dlsym(handle, "target_func");
if (target) {
// g_hook(target, replacement, &backup);
}
}
}
extern "C" __attribute__((visibility("default"))) __attribute__((used))
NativeOnModuleLoaded native_init(const NativeAPIEntries *entries) {
g_hook = entries->hook_func;
return on_library_loaded;
}
```
---
## 九、对接清单速查
| 项目 | 值 |
|------|-----|
| 框架存储 | `/data/adb/xesd/` |
| Manager 包名 | `org.xeslciw.manager` |
| 寄生 Manager 备份 | `/data/adb/xesd/manager.apk` |
| Java 入口配置 | `assets/grvjfe_init` 或 `assets/xposed_init` |
| Native 入口配置 | `assets/native_init` |
| 必须导出函数 | `native_init` |
| 回调签名 | `void (*)(const char *name, void *handle)` |
| Hook 函数 | `entries->hook_func(void *target, void *replace, void **backup)` |
---
## 十、常见问题与约束
### 10.1 System Framework Hook 限制
> Modules that hook System Framework will not work. Please report to Iztyge developer.
对系统框架（如 `android.*`）的 Hook 可能失效，需向框架开发者反馈。
### 10.2 模块 ClassLoader 限制
> Only module classloader can use Grvjfe API
Xposed/Grvjfe API 只能在模块自身的 ClassLoader 内调用，不能通过反射从其他类调用。
### 10.3 寄生模式
> XESlciw now supports system parasitization to avoid detection. Uninstall manager after creating parasitic shortcut. Reinstall from /data/adb/xesd/manager.apk
创建寄生快捷方式后，可卸载 Manager，框架仍可运行。如需恢复 Manager，可从 `/data/adb/xesd/manager.apk` 安装。
---
## 十一、参考资料
| 资源 | 链接 |
|------|------|
| LSPosed | https://github.com/LSPosed/LSPosed |
| LSPosed Native Hook | https://github.com/LSPosed/LSPosed/wiki/Native-Hook |
| Modern Xposed API | https://github.com/LSPosed/LSPosed/wiki/Develop-Xposed-Modules-Using-Modern-Xposed-API |
| libxposed API | https://github.com/libxposed/api |
| XESlciw 详解 | `资料/XESlciw详解与工作手机技术方案对比.md` |
| 提取 APK | `资料/奥创工作手机APK提取/` |

294
资料/XESlciw详解与工作手机技术方案对比.md
View File

@@ -1,294 +0,0 @@
# XESlciw 详解与工作手机同类型技术方案对比
> **更新**：2026-02-24
> **来源**：奥创工作手机真机逆向 + 公开技术资料
---
## 一、XESlciw 详解
### 1.1 定义与定位
**XESlciw** 是奥创工作手机采用的 **LSPosed 类 Hook 框架**，用于在 Android 设备上注入微信等目标应用，实现聊天同步、消息收发、风控监控等能力。
| 维度 | 说明 |
|------|------|
| **本质** | LSPosed/Xposed 生态的定制 fork 或兼容实现 |
| **命名关系** | 代码中 `Iztyge`≈LSPosed、`Grvjfe`≈LSPosed API（混淆名） |
| **Manager 包名** | org.xeslciw.manager |
| **框架存储** | /data/adb/xesd/ |
| **寄生模式** | 支持卸载 Manager 后仍运行，降低被检测概率 |
### 1.2 技术架构
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ XESlciw 技术架构 │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 用户层：XESlciw Manager (org.xeslciw.manager) │ │
│ │ • 模块列表、Scope 配置、启用/禁用、寄生模式、版本检查 │ │
│ │ • 可独立卸载，框架仍可运行（寄生模式） │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────┴──────────────────────────────────────┐ │
│ │ 框架层：XESlciw Core (Zygisk/Riru 模块) │ │
│ │ • 注入 Zygote，接管 APP 进程启动 │ │
│ │ • 按 Scope 加载 Hook 模块 │ │
│ │ • 提供 Grvjfe API 给模块使用 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────┴──────────────────────────────────────┐ │
│ │ 模块层：VivWxjz 等 │ │
│ │ • 通过 assets/grvjfe_init 声明入口（Main + libxxx.so） │ │
│ │ • Scope 匹配时注入目标 APP（如 com.tencent.mm） │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 依赖：Magisk + Zygisk，需 Root │
└─────────────────────────────────────────────────────────────────────────────────┘
```
### 1.3 核心能力
| 能力 | 说明 |
|------|------|
| **Scope 作用域** | 为每个模块指定生效的 APP 包名，如仅对微信生效 |
| **模块版本校验** | Grvjfe 版本与模块声明版本需匹配，否则禁用 |
| **寄生模式** | 创建快捷方式后卸载 Manager，框架继续工作 |
| **System Framework 限制** | 对系统框架的 Hook 可能无效，需向 Iztyge 反馈 |
| **备份/恢复** | 支持备份/恢复模块列表与 Scope 配置 |
### 1.4 模块加载流程
```
Zygote 启动
│
▼
XESlciw 框架注入 (Zygisk)
│
▼
APP 进程 fork（如微信）
│
▼
检查已启用模块的 Scope
│
├── Scope 包含此 APP ? ──No──> 不加载
│
└── Yes
│
▼
加载模块 (assets/grvjfe_init)
│
├── top.zzz.vivwxjz.Main
└── libvivwxjz.so
│
▼
模块在目标进程内执行 Hook
```
### 1.5 与 LSPosed 的关系
| 对比项 | LSPosed | XESlciw |
|--------|---------|---------|
| 定位 | 通用 Xposed 框架 | 奥创工作手机专用 |
| 开源 | 是（GitHub） | 否，闭源 |
| Manager | LSPosed Manager | XESlciw Manager |
| API 命名 | LSPosed API | Grvjfe API（混淆） |
| 特色 | 通用模块生态 | 寄生模式、与 VivWxjz 深度适配 |
| 核心模块 | 无内置 | Tpyc、XESlciw 等内置/推荐 |
**结论**：XESlciw 是 LSPosed 的定制/兼容实现，面向工作手机场景做了封装和隐藏处理。
---
## 二、工作手机技术方案对比总览
### 2.1 五类方案概览
| 方案 | 代表 | Root | 实时性 | 数据完整性 | 合规风险 | 维护成本 |
|------|------|:----:|:------:|:----------:|:--------:|:--------:|
| **Hook 注入** | XESlciw/LSPosed | 需 | 高 | 高 | 高 | 高 |
| **无障碍** | AccessibilityService | 否 | 中 | 中 | 低 | 中 |
| **ADB+u2** | 机擎 SDK | 否 | 中 | 中 | 低 | 中 |
| **官方 API** | 企微开放平台 | 否 | 高 | 中 | 无 | 低 |
| **AI Agent** | DroidRun/机擎 M12 | 否 | 低 | 中 | 低 | 中 |
---
## 三、各方案详解与对比
### 3.1 方案一：Hook 注入（XESlciw / LSPosed / Frida / Xposed）
| 子方案 | 说明 | Root | 特点 |
|--------|------|:----:|------|
| **XESlciw** | 奥创采用的 LSPosed 类框架 | 需 | 闭源、寄生模式、与 VivWxjz 适配 |
| **LSPosed** | 主流 Xposed 框架，Zygisk | 需 | 开源、生态丰富 |
| **EdXposed** | 早期继任者 | 需 | 已停更 |
| **Xposed** | 经典框架 | 需 | 已停更，仅支持旧系统 |
| **Frida** | 动态插桩 | 需 | 跨平台、脚本化、无需刷机 |
**技术原理**：
```
Zygote/进程启动 → 框架注入 → 目标 APP 加载时执行 Hook
→ 拦截 Java 方法 / Native 函数 / Syscall
→ 读取/修改参数与返回值 → 上报云端或执行操作
```
**奥创/VivWxjz 特殊点**：除 Java Hook 外，还采用 **Syscall 级拦截**（socket/recvmsg/sendmsg），在协议层获取数据，对微信版本依赖更小。
**优劣势**：
| 优势 | 劣势 |
|------|------|
| 功能强、可调用内部接口 | 需 Root |
| 数据完整（DB、协议层） | 微信更新需适配 |
| 实时、可后台静默 | 合规与封号风险高 |
| 性能好、无 UI 延迟 | 技术门槛高 |
---
### 3.2 方案二：无障碍服务（AccessibilityService）
| 维度 | 说明 |
|------|------|
| Root | 不需要 |
| 原理 | 监听界面事件，获取 UI 树，执行 performAction |
| 能力 | 点击、输入、滑动、读 UI 文本 |
| 限制 | 无法直接读 DB、需界面在前台或可访问 |
**技术原理**：
```
注册 AccessibilityService
→ 监听 com.tencent.mm 窗口事件
→ getRootInActiveWindow() 获取 UI 树
→ 解析 text/resource-id 定位控件
→ performAction(ACTION_CLICK) 等模拟操作
```
**优劣势**：
| 优势 | 劣势 |
|------|------|
| 免 Root | 依赖 UI 结构，易受改版影响 |
| 开发简单 | 需前台或辅助界面 |
| 不改 APP | 无法获取协议/DB 级数据 |
| 相对合规 | 容易被风控检测 |
---
### 3.3 方案三：ADB + uiautomator2（机擎当前方案）
| 维度 | 说明 |
|------|------|
| Root | 不需要 |
| 原理 | ADB + u2 控制 UI，或 adb shell input |
| 能力 | 点击、输入、滑动、截图、dump UI 树 |
| 限制 | 需 USB/WiFi 连接或本地 Agent |
**技术原理**：
```
ADB 连接设备
→ u2.connect(serial) 或 adb shell input tap x y
→ d.click(text="发送") / d.input_text("内容")
→ 或 uiautomator dump 解析 XML 获取消息列表
```
**优劣势**：
| 优势 | 劣势 |
|------|------|
| 免 Root | 依赖 ADB/Agent 连接 |
| 跨 APP 通用 | 操作有延迟，依赖 UI |
| 工具链成熟 | 复杂逻辑需精细适配 |
| 合规风险低 | 无法协议级实时同步 |
---
### 3.4 方案四：官方 API（企微开放平台）
| 维度 | 说明 |
|------|------|
| Root | 不需要 |
| 适用 | 仅企业微信、公众号 |
| 能力 | 会话存档、客户联系、消息推送等 |
| 限制 | 需企业认证，个人微信不可用 |
**优劣势**：
| 优势 | 劣势 |
|------|------|
| 完全合规 | 仅限企微/公众号 |
| 稳定可靠 | 功能有限 |
| 无封号风险 | 个人微信无法使用 |
---
### 3.5 方案五：AI Agent（视觉 + 自动化）
| 维度 | 说明 |
|------|------|
| Root | 不需要 |
| 原理 | 截图 → 视觉模型理解 → 生成操作 → u2/ADB 执行 |
| 代表 | DroidRun、机擎 M12 |
| 特点 | 自然语言驱动，自适应 UI 变化 |
**优劣势**：
| 优势 | 劣势 |
|------|------|
| 灵活、少写选择器 | 需 LLM 调用，有成本 |
| 对 UI 改版不敏感 | 速度慢、准确率依赖模型 |
| 代表未来方向 | 技术仍在演进 |
---
## 四、能力矩阵对比（工作手机核心需求）
| 能力 | XESlciw Hook | 无障碍 | ADB+u2 | 官方API | AI Agent |
|------|:------------:|:------:|:------:|:-------:|:--------:|
| 发消息 | ✅ 内部调用 | ✅ 模拟 | ✅ 模拟 | ✅ 企微 | ✅ 模拟 |
| 收消息实时同步 | ✅ 协议/Syscall | ⚠️ 轮询 UI | ⚠️ 轮询 UI | ✅ 会话存档 | ⚠️ 轮询 |
| 联系人完整获取 | ✅ DB/Hook | ⚠️ UI 树 | ⚠️ UI 树 | ✅ API | ⚠️ UI |
| 红包/转账监控 | ✅ Hook | ❌ | ❌ | ⚠️ 部分 | ❌ |
| 朋友圈 | ✅ Hook | ⚠️ 复杂 | ⚠️ 复杂 | ❌ | ⚠️ 可行 |
| 后台静默 | ✅ | ❌ 需前台 | ❌ 需连接 | ✅ | ❌ |
| 免 Root | ❌ | ✅ | ✅ | ✅ | ✅ |
| 个人微信 | ✅ | ✅ | ✅ | ❌ | ✅ |
---
## 五、技术选型建议（机擎场景）
| 场景 | 推荐方案 | 理由 |
|------|----------|------|
| **商业化、通用设备** | ADB+u2（当前） | 免 Root、合规、易部署 |
| **内部/高管控** | Hook（LSPosed+Frida） | 能力最强，接受 Root |
| **企微专用** | 官方 API | 合规、稳定 |
| **增强实时同步** | 混合：u2 + 定时 UI 轮询 | 免 Root 下折中 |
| **长期演进** | AI Agent 增强 | 降低 UI 耦合，提升鲁棒性 |
---
## 六、XESlciw 与 LSPosed 对照
| 项目 | XESlciw | LSPosed |
|------|---------|---------|
| 开源 | 否 | 是 |
| 安装方式 | 奥创定制包 / data/adb/xesd | Magisk 模块 |
| Manager | org.xeslciw.manager | org.lsposed.manager |
| Scope | 有 | 有 |
| 寄生模式 | 有 | 无（官方） |
| 内置推荐模块 | Tpyc、XESlciw | 无 |
| 适用 | 奥创工作手机 | 通用模块生态 |
---
## 七、参考资料
- **XESlciw 接口与设备 Hook 开发手册**：`资料/XESlciw接口与设备Hook开发手册.md`
- 奥创官网：http://www.aochuang.cn/
- LSPosed：https://github.com/LSPosed/LSPosed
- LSPatch（免 Root）：https://github.com/LSPosed/LSPatch
- Frida：https://github.com/frida/frida
- 工作手机资料：`资料/奥创.md`、`资料/奥创工作手机-复刻开发详解.md`

213
资料/个微方案全网对比_优于Frida与奥创.md
View File

@@ -1,213 +0,0 @@
# 个微方案全网对比 — 比 Frida 和奥创更好的替代
> **目标**：全网搜索并对比比 Frida、奥创更优的个人微信自动化/互通方案
> **更新**：2026-02-10
---
## 一、结论速览：更好的方案
| 方案 | 优于 Frida/奥创的点 | 封号风险 | 推荐度 |
|------|---------------------|----------|--------|
| **wxauto** | 不注入、不 Hook，模拟真人操作 | 极低 | ⭐⭐⭐⭐⭐ |
| **WePush** | 基于 wxauto，模拟点击 + 消息队列，零封号宣传 | 极低 | ⭐⭐⭐⭐⭐ |
| **wxMaster** | 读本地数据库，不 Hook，HTTP API | 极低 | ⭐⭐⭐⭐ |
| **GeweChat** | iPad 协议，Docker 部署，免费 | 中 | ⭐⭐⭐⭐ |
| **RPA（影刀等）** | 模拟真人，日发 50 条以下风险极低 | 低 | ⭐⭐⭐⭐ |
| **机擎 u2/ADB** | 免 Root，不 Hook，云端远程 | 低 | ⭐⭐⭐⭐ |
| **云手机** | 多开托管，设备隔离，IP 轮换 | 低 | ⭐⭐⭐ |
| **Wechaty Web/Padlocal** | 多协议，但 Web 限制多，Padlocal 付费 | 视协议 | ⭐⭐⭐ |
| **omni-bot-sdk-oss** | 视觉 RPA + YOLO，微信 4.0 | 低 | ⭐⭐⭐ |
| **WeChatFerry** | 功能强，但封号率 >80%，不推荐 | 极高 | ⭐⭐ |
---
## 二、Frida / 奥创 的短板（为何要替代）
| 维度 | Frida | 奥创 |
|------|-------|------|
| **技术** | Hook 注入 | Hook 注入 |
| **封号风险** | 高 | 高 |
| **Root** | 需 Root（Gadget 可免） | 必须 Root |
| **部署** | 需自建、自写脚本 | 绑定 007 生态 |
| **维护** | 微信更新需适配 | 闭源，依赖厂商 |
**替代方向**：不 Hook、不注入，或使用协议模拟，降低封号与 Root 依赖。
---
## 三、更好方案详细对比
### 3.1 wxauto — 强烈推荐
| 项目 | 说明 |
|------|------|
| **原理** | Windows UIAutomation 官方 API，模拟真人点击/输入 |
| **安装** | `pip install wxauto` |
| **环境** | Windows 10/11 + PC 微信 |
| **封号** | 作者声明「不封号」，基于官方 API，不侵入 |
| **功能** | 发消息、收消息、添加好友、聊天记录、文件传输、@群友、引用 |
| **限制** | 无实时监听，需轮询窗口；支持微信 3.9.x，暂不支持 4.0+ |
| **GitHub** | cluic/wxauto，约 1.6k Star |
**优于 Frida/奥创**：零注入、零 Hook，封号风险极低，部署简单。
### 3.2 WePush — 强烈推荐
| 项目 | 说明 |
|------|------|
| **原理** | 基于 wxauto，模拟人工点击 + FastAPI + Redis 消息队列 |
| **GitHub** | friend-nicen/wepush |
| **特点** | 异步队列、随机间隔、需手动打开聊天窗口，降低批量特征 |
| **封号** | 宣传「零封号」，完全模拟人工 |
| **部署** | Windows + Redis + 微信客户端 |
**优于 Frida/奥创**：在 wxauto 基础上增加队列与节奏控制，更适合生产推送场景。
### 3.3 wxMaster — 推荐
| 项目 | 说明 |
|------|------|
| **原理** | 直接读微信本地数据库，不 Hook、不注入 |
| **接口** | HTTP API，默认 34567 端口，JSON 返回 |
| **功能** | 私聊/群聊消息、通讯录、群成员、历史消息、多账号 |
| **版本** | 微信 4.0.0.26 ~ 4.0.3.22 |
| **封号** | 读库方式，不修改数据，宣称不易封号 |
| **GitHub** | xz-soft/wxMaster |
**优于 Frida/奥创**：不注入进程，数据获取稳定，HTTP 接口易集成。
### 3.4 GeweChat — 推荐（iPad 协议）
| 项目 | 说明 |
|------|------|
| **原理** | 模拟微信 iPad 客户端协议，Docker 部署 API 服务 |
| **部署** | Docker，端口 2531（API）、2532（文件） |
| **功能** | 收发消息、群管理、联系人、朋友圈 |
| **限制** | 建议同省 IP，消息频率 ≤5 条/分钟 |
| **封号** | 中等，需控制频率与环境 |
| **GitHub** | 约 2.5k Star，持续维护 |
**优于 Frida/奥创**：无 Root、无手机端 Hook，服务器端部署，支持个微。
### 3.5 RPA（影刀、来也等）
| 项目 | 说明 |
|------|------|
| **原理** | 模拟真人点击、输入，与真人操作一致 |
| **封号** | 日发 50 条以下、随机间隔 8–15 秒，风险极低 |
| **限制** | 无法实时监听，需轮询；需 PC 端微信 |
| **建议** | 间隔 ≥5 秒，日操作 ≤200 条 |
**优于 Frida/奥创**：行为像真人，不易被风控识别。
### 3.6 机擎（u2/ADB）
| 项目 | 说明 |
|------|------|
| **原理** | uiautomator2 + ADB，模拟 UI 操作 |
| **设备** | Android 手机，无需 Root |
| **连接** | WebSocket 远程，设备主动连云端 |
| **功能** | 发消息、好友、群、朋友圈、标签等 |
**优于 Frida/奥创**：免 Root、免 Hook，支持远程与云端中台。
### 3.7 云手机（星界、川川、多多云等）
| 项目 | 说明 |
|------|------|
| **原理** | 云端安卓虚拟机，每台独立设备指纹 |
| **能力** | 多开、脚本托管、远程操作、24 小时挂机 |
| **防封** | 设备隔离、IP 轮换、资料差异化 |
| **适用** | 多账号营销、集中托管 |
**优于 Frida/奥创**：设备级隔离，无需 Root，可规模化部署。
### 3.8 Wechaty
| 项目 | 说明 |
|------|------|
| **Web 协议** | 免费，但 2017 年后注册账号可能无法登录网页版 |
| **Padlocal** | 付费，iPad 协议，本地网关 |
| **生态** | 多语言、多协议，社区活跃 |
**注意**：Web 协议限制多，Padlocal 需付费，综合性价比一般。
### 3.9 omni-bot-sdk-oss
| 项目 | 说明 |
|------|------|
| **原理** | 视觉 RPA + YOLO，解析微信 4.0 界面 |
| **能力** | 解析各类消息，发送文本/图片/文件 |
| **GitHub** | weixin-omni/omni-bot-sdk-oss |
**优于 Frida/奥创**：无 Hook，基于视觉，对 UI 改版有一定适应性。
### 3.10 WeChatFerry — 不推荐作为替代
| 项目 | 说明 |
|------|------|
| **原理** | PC 微信 DLL 注入 |
| **封号** | 实测 >80% 封号率 |
| **建议** | 仅技术研究，需虚拟机隔离 |
**结论**：功能强但风险极高，不作为「更好方案」推荐。
---
## 四、综合对比表（个微）
| 方案 | 不注入 | 免Root | 封号风险 | 远程 | 发消息 | 收消息 | 联系人 | 朋友圈 | 推荐场景 |
|------|:------:|:------:|:--------:|:----:|:------:|:------:|:------:|:------:|----------|
| **wxauto** | ✅ | ✅ | 极低 | PC 本地 | ✅ | ⚠️ 轮询 | ✅ | ⚠️ | 个人/小团队 |
| **WePush** | ✅ | ✅ | 极低 | ✅ API | ✅ | ⚠️ | ✅ | ⚠️ | 消息推送、客服 |
| **wxMaster** | ✅ | ✅ | 极低 | ✅ HTTP | ✅ | ✅ | ✅ | ⚠️ | 需读库、HTTP 集成 |
| **GeweChat** | ✅ | ✅ | 中 | ✅ Docker | ✅ | ✅ | ✅ | ✅ | 个微机器人、私域 |
| **RPA** | ✅ | ✅ | 低 | 视产品 | ✅ | ⚠️ | ✅ | ⚠️ | 定时任务、低频率 |
| **机擎** | ✅ | ✅ | 低 | ✅ | ✅ | ⚠️ UI | ✅ | ✅ | 工作手机、多端 |
| **云手机** | ✅ | ✅ | 低 | ✅ | ✅ | ✅ | ✅ | ✅ | 多开、托管 |
| **Wechaty** | ✅ | ✅ | 视协议 | ✅ | ✅ | ✅ | ✅ | ✅ | 多协议、生态 |
| **omni-bot** | ✅ | ✅ | 低 | 视部署 | ✅ | ✅ | ✅ | ⚠️ | 微信 4.0、视觉 RPA |
| **Frida** | ❌ | ⚠️ | 高 | ✅ | ✅ | ✅ | ✅ | ✅ | 逆向、自研 |
| **奥创** | ❌ | ❌ | 高 | ✅ | ✅ | ✅ | ✅ | ✅ | 工作手机、Root 场景 |
| **WeChatFerry** | ❌ | ✅ | 极高 | ✅ | ✅ | ✅ | ✅ | ✅ | 不推荐 |
---
## 五、选型建议
### 5.1 优先不 Hook、低封号
1. **wxauto** — 最简单，`pip install wxauto` 即用
2. **WePush** — 需要消息队列、推送服务时使用
3. **GeweChat** — 需要 Docker、协议级能力时使用
4. **机擎** — 需要 Android 工作手机、云端中台时使用
### 5.2 多账号、规模化
- **云手机** — 多开、托管、脚本
- **GeweChat** — 单服务多账号（注意频率）
### 5.3 必须用手机、免 Root
- **机擎 u2/ADB** — 不 Hook，云端远程
- **云手机** — 云端虚拟机
### 5.4 不推荐
- **WeChatFerry** — 封号率过高
- **Frida/奥创** — 在「更好方案」存在时，仅作技术研究或特殊场景
---
## 六、资源链接
| 方案 | 链接 |
|------|------|
| wxauto | https://docs.wxauto.org/ |
| WePush | https://github.com/friend-nicen/wepush |
| wxMaster | https://github.com/xz-soft/wxMaster |
| GeweChat | 搜索 GeweChat Docker |
| Wechaty | https://wechaty.gitbook.io/wechaty/ |
| 机擎 | 开发文档/2、架构/系统架构.md |
| 微信互通替代方案 | 资料/微信互通方案对比与更好替代.md |

604
资料/奥创.md
View File

@@ -1,604 +0,0 @@
# 奥创工作手机 — 技术分析与底层拆解
> **更新**: 2026-02-10
> **来源**: 奥创官网 + 007私域管理API + Teambition文档 + 全网技术调研 + GitHub开源项目
> **用途**: 为机擎（工作手机SDK v3.0）开发提供竞品分析与技术参考
**延伸阅读**：
- [XESlciw 详解与工作手机技术方案对比](XESlciw详解与工作手机技术方案对比.md)
- [奥创工作手机 复刻开发详解](奥创工作手机-复刻开发详解.md)
---
## 一、奥创产品概述
### 1.1 基本信息
| 项 | 说明 |
|----|------|
| **产品名** | 奥创云脑工作手机 |
| **开发商** | 奥创软件研究院 |
| **官网** | http://www.aochuang.cn/ |
| **定位** | 企业微信私域流量矩阵 + 移动营销风控留痕 |
| **API文档** | https://007.siyuguanli.com/api/swagger-ui/index.html （Swagger UI） |
| **产品文档** | https://thoughts.teambition.com/share/5e044d094700080013a8e8d9 （Teambition文档汇总） |
| **后台系统** | 007私域管理系统（007.siyuguanli.com） |
### 1.2 核心功能矩阵
| 功能域 | 具体功能 |
|--------|----------|
| **微信管理** | 聊天记录实时同步、联系人同步、红包/转账监控、多微信账号管理 |
| **手机监控** | 手机状态监控（通话/电量/信号）、录音同步、通讯录同步、通话记录同步、短信同步 |
| **营销自动化** | 批量加好友、批量群发、自动发朋友圈、定时消息、话术库、自动欢迎语 |
| **客户管理** | 客户标签、客户画像、客户分配、客户生命周期、流失预警 |
| **风险控制** | 敏感词风控、敏感行为监管（删好友/删记录/收红包等）、实时报警 |
| **数据安全** | 聊天记录留痕、双重加密云端存储、员工离职客户保护 |
| **云客服** | 多微信统一管理、无需扫码永远登录、消息批量精准推送、多平台兼容 |
| **统计报表** | 电话工作量、客户增长、财务统计、精准报表 |
### 1.3 适用行业
教育、电信、医美、服务、微商、旅游、金融、房产等
---
## 二、007私域管理系统 — API接口分析
### 2.1 API入口
```
Base URL: https://007.siyuguanli.com/api
文档格式: Swagger UI（OpenAPI 规范）
认证方式: 推测为 API Key / Token（待访问确认）
```
> **注意**：API文档页面（swagger-ui/index.html）在外网抓取时超时，需内网或VPN访问。建议在浏览器直接打开查看完整接口列表。
### 2.2 推测的API模块（基于奥创功能矩阵）
根据奥创的功能矩阵和行业通用的工作手机API设计，推测其API包含以下模块：
| API 模块 | 推测接口 | 说明 |
|----------|----------|------|
| **设备管理** | GET /devices, POST /devices/{id}/command | 设备列表、状态、远程命令 |
| **微信管理** | GET /wechat/contacts, GET /wechat/messages | 联系人、聊天记录同步 |
| **消息发送** | POST /message/send, POST /message/batch-send | 单发、群发消息 |
| **好友管理** | POST /friend/add, POST /friend/batch-add | 加好友、批量加好友 |
| **朋友圈** | POST /moments/post, GET /moments/list | 发朋友圈、拉列表 |
| **群管理** | POST /group/create, POST /group/invite | 建群、邀人 |
| **标签管理** | POST /tag/create, POST /tag/assign | 创建标签、打标签 |
| **风控** | GET /risk/alerts, POST /risk/keywords | 告警列表、敏感词配置 |
| **统计** | GET /stats/overview, GET /stats/workload | 总览、工作量统计 |
### 2.3 与机擎SDK的对标
| 奥创API（推测） | 机擎 unified API | 状态 |
|-----------------|------------------|------|
| 设备管理 | GET /api/v3/devices | ✅ 已实现 |
| 消息发送 | POST /api/v3/message/send | ✅ 已实现 |
| 批量发送 | POST /api/v3/message/batch-send | ✅ 已实现 |
| 好友管理 | POST /api/v3/friend/add | ✅ 已实现 |
| 群管理 | POST /api/v3/group/* | ✅ 已实现 |
| 标签管理 | POST /api/v3/tag/* | ✅ 已实现 |
| 朋友圈 | POST /api/v3/moments/* | ✅ 已实现 |
| AI Agent | POST /api/v3/agent/execute | ✅ 已实现（奥创无此功能） |
| 风控/敏感词 | — | ❌ 机擎暂未实现 |
| 统计报表 | — | ❌ 机擎暂未实现 |
---
## 三、底层技术拆解 — 工作手机手机访问技术
奥创类工作手机产品的底层技术，核心是**如何远程控制Android手机并获取/操作APP数据**。行业内主要有以下5种技术通道：
### 3.1 技术通道总览
```
┌─────────────────────────────────────────────────────────┐
│ 工作手机技术架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ 通道1 │ │ 通道2 │ │ 通道3 │ │
│ │ Hook注入 │ │ 无障碍服务 │ │ ADB控制 │ │
│ │ (Xposed/ │ │ (Accessi- │ │ (adb shell │ │
│ │ Frida/ │ │ bility │ │ + input │ │
│ │ LSPosed) │ │ Service) │ │ + uiauto) │ │
│ └──────┬──────┘ └──────┬──────┘ └─────┬──────┘ │
│ │ │ │ │
│ ┌──────┴──────┐ ┌──────┴──────┐ ┌─────┴──────┐ │
│ │ 通道4 │ │ 通道5 │ │ 通道+ │ │
│ │ 官方API │ │ AI Agent │ │ WebSocket │ │
│ │ (企微开放 │ │ (视觉理解 │ │ 远程通信 │ │
│ │ 平台) │ │ +自动化) │ │ (设备连接) │ │
│ └─────────────┘ └─────────────┘ └────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 云端控制服务器（API Gateway） │ │
│ │ FastAPI / Spring Boot + WebSocket Hub │ │
│ │ + 设备管理 + 指令路由 + 数据存储 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 数据层 │ │
│ │ MongoDB + Redis + MySQL + MinIO │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### 3.2 通道1：Hook注入（Xposed/Frida/LSPosed）
**这是奥创等传统工作手机的核心技术**，通过Hook框架直接注入微信进程，拦截和修改函数调用。
#### 技术原理
```
Zygote进程启动 → Xposed/LSPosed 替换 app_process
→ 微信启动时加载 Hook 模块
→ 拦截目标函数（发消息、收消息、加好友等）
→ 通过HTTP/WebSocket上报到云端服务器
→ 云端下发指令 → Hook模块执行对应操作
```
#### 核心框架
| 框架 | 说明 | Root要求 | 支持Android版本 | 状态 |
|------|------|----------|-----------------|------|
| **Xposed** | 最经典的Hook框架 | 需Root | ≤Android 8 | 已停更 |
| **EdXposed** | Xposed的继任者 | 需Root+Magisk | Android 8-10 | 已停更 |
| **LSPosed** | 当前主流（基于Magisk+Zygisk） | 需Root+Magisk v24+ | Android 8.1-15 | 2024停更，社区fork维护 |
| **Frida** | 动态插桩框架（跨平台） | 需Root | 全版本 | 活跃 |
| **VirtualXposed** | 免Root虚拟环境 | 不需Root | ≤Android 10 | 有限 |
#### Hook 能力范围
| 能力 | 说明 | 实现方式 |
|------|------|----------|
| **消息拦截** | 实时获取收发消息 | Hook微信消息处理函数 |
| **联系人获取** | 读取完整通讯录 | Hook微信数据库查询 |
| **消息发送** | 自动发消息/群发 | 调用微信内部发消息函数 |
| **红包监控** | 监控红包收发 | Hook红包相关类 |
| **朋友圈** | 发/读朋友圈 | Hook朋友圈相关函数 |
| **加好友** | 自动加/通过好友 | Hook好友请求函数 |
| **防撤回** | 拦截撤回操作 | Hook撤回方法 |
| **数据库访问** | 直接读写微信本地数据库 | Hook SQLite操作 |
#### 关键GitHub项目
| 项目 | Stars | 说明 |
|------|-------|------|
| [coder-pig/CPWechatXposed](https://github.com/coder-pig/CPWechatXposed) | 高 | Xposed Hook微信综合项目 |
| [546669204/wechatbot-xposed](https://github.com/546669204/wechatbot-xposed) | 198 | 基于Xposed的微信机器人 |
| [Dawnnnnnn/Hook_WeChat_FaaS_Xposed](https://github.com/dawnnnnnn/hook_wechat_faas_xposed) | 51 | Kotlin版微信云函数Hook |
| [suhy07/WechatHook](https://github.com/suhy07/wechathook) | — | Xposed Hook微信实验项目 |
| [AlienwareHe/wechat-robot](https://github.com/AlienwareHe/wechat-robot) | — | Xposed微信消息HTTP服务暴露 |
| [musi66/wework_robot](https://github.com/musi66/wework_robot) | — | 企业微信逆向Hook机器人 |
| [graysign/XMagicHooker](https://github.com/graysign/XMagicHooker) | — | Kotlin半开源企业微信插件框架 |
#### 优劣势
| 优势 | 劣势 |
|------|------|
| 功能最强大，可直接调用微信内部函数 | 需要Root权限 |
| 数据获取最完整（数据库级别） | 微信版本更新需重新适配 |
| 性能好，无UI操作延迟 | 被检测风险高，可能封号 |
| 可实现无UI操作（后台静默） | 技术门槛高（需逆向分析） |
---
### 3.3 通道2：无障碍服务（AccessibilityService）
**免Root方案**，通过Android系统的无障碍服务API获取UI树并模拟操作。
#### 技术原理
```
注册AccessibilityService → 监听微信窗口事件
→ 获取UI节点树（AccessibilityNodeInfo）
→ 通过 resource-id / text / content-desc 定位控件
→ 执行 performAction（点击/滑动/输入文字）
→ 通过HTTP/WebSocket上报操作结果到云端
```
#### 实现步骤
```java
// 1. 继承AccessibilityService
public class WechatAutoService extends AccessibilityService {
@Override
public void onAccessibilityEvent(AccessibilityEvent event) {
// 监听微信事件
if ("com.tencent.mm".equals(event.getPackageName())) {
AccessibilityNodeInfo root = getRootInActiveWindow();
// 遍历节点树，定位目标控件
// 执行自动化操作
}
}
}
// 2. 配置 accessibility_service_config.xml
// <accessibility-service
// android:packageNames="com.tencent.mm"
// android:accessibilityEventTypes="typeAllMask"
// android:canRetrieveWindowContent="true" />
```
#### 能力范围
| 能力 | 说明 | 实现难度 |
|------|------|----------|
| 自动发消息 | 模拟打字和发送按钮点击 | 中 |
| 自动加好友 | 模拟搜索、添加流程 | 中 |
| 发朋友圈 | 模拟朋友圈发布流程 | 高 |
| 读取消息 | 从UI节点获取文字内容 | 中 |
| 自动回复 | 监听新消息通知+自动回复 | 低 |
#### 优劣势
| 优势 | 劣势 |
|------|------|
| **不需Root** | 操作慢（需等UI渲染） |
| 开发简单 | 控件ID随版本变化，维护成本高 |
| 兼容性好 | 无法获取数据库级数据 |
| 不修改目标APP | 容易被检测 |
---
### 3.4 通道3：ADB控制（adb + uiautomator2）
**通过ADB调试桥+UI自动化框架远程控制设备**，这是机擎SDK当前采用的核心方案之一。
#### 技术原理
```
PC/服务器 ← ADB协议（USB/WiFi） → Android设备
→ adb shell input tap x y # 模拟点击
→ adb shell input text "hello" # 模拟输入
→ adb shell screencap # 截图
→ uiautomator2 控制 # UI自动化
→ scrcpy 投屏 # 实时画面
```
#### 核心工具链
| 工具 | 说明 | GitHub |
|------|------|--------|
| **uiautomator2** v3.5.0 | Python控制Android UI自动化 | github.com/openatx/uiautomator2（7.8k⭐） |
| **scrcpy** | 高性能Android投屏+控制 | github.com/Genymobile/scrcpy（115k⭐） |
| **minicap** | 快速截图（30-40FPS） | github.com/nicklockwood/minicap |
| **minitouch** | 远程触摸操作 | github.com/nicklockwood/minitouch |
| **adbutils** | Python ADB封装 | github.com/openatx/adbutils |
#### uiautomator2 核心能力
```python
import uiautomator2 as u2
# 连接设备
d = u2.connect("192.168.1.100") # WiFi连接
d = u2.connect("SERIAL_NO") # USB连接
# 应用管理
d.app_start("com.tencent.mm") # 启动微信
d.app_stop("com.tencent.mm") # 停止微信
# UI操作
d(text="微信").click() # 点击文字
d(resourceId="com.tencent.mm:id/input").set_text("Hello") # 输入
d.click(500, 800) # 坐标点击
d.swipe(500, 1500, 500, 500) # 滑动
# 截图与UI树
d.screenshot("screen.png")
d.dump_hierarchy() # 获取UI树（XML）
# XPath选择器
d.xpath('//node[@text="发送"]').click()
```
#### 优劣势
| 优势 | 劣势 |
|------|------|
| 不需Root | 依赖ADB连接（USB/WiFi） |
| 跨APP通用 | 操作有延迟（需等UI） |
| 工具链成熟（7.8k⭐） | 需要屏幕亮着才能操作 |
| 支持WiFi远程控制 | 复杂操作需精确定位 |
---
### 3.5 通道4：官方API（企业微信开放平台）
部分功能可通过企业微信/微信开放平台的官方API实现。
| 官方API | 能力 | 限制 |
|---------|------|------|
| 企微会话存档 | 聊天记录获取 | 需企业认证 |
| 企微客户联系 | 客户管理、标签 | 仅企业微信 |
| 企微消息推送 | 主动发消息 | 频率限制 |
| 微信公众号API | 粉丝管理、消息 | 仅公众号 |
#### 优劣势
| 优势 | 劣势 |
|------|------|
| 完全合规 | 仅限企业微信/公众号 |
| 稳定可靠 | 功能有限 |
| 无封号风险 | 需企业认证 |
---
### 3.6 通道5：AI Agent（视觉理解+自动化）
**最新技术方案**，通过AI视觉理解屏幕内容，结合自动化框架执行操作。机擎SDK的M12模块。
#### 核心项目
| 项目 | Stars | 说明 |
|------|-------|------|
| [DroidRun](https://github.com/droidrun/droidrun) | 7.6k | LLM驱动Android自动化Agent，支持多模型 |
| [Fremko](https://pypi.org/project/fremko) | — | WebSocket设备控制+FastAPI+LLM |
| [Android-MCP](https://github.com/CursorTouch/Android-MCP) | 217 | MCP Server for Android自动化 |
| [mcp-android-server](https://github.com/nim444/mcp-android-server-python) | — | uiautomator2 + MCP |
#### 技术原理
```
AI Agent 收到任务（如"发消息给张三"）
→ 截图 → AI视觉模型分析屏幕内容
→ 生成操作步骤（点击哪里、输入什么）
→ 通过 uiautomator2/ADB 执行操作
→ 再截图验证结果
→ 循环直到任务完成
```
#### 优劣势
| 优势 | 劣势 |
|------|------|
| 最灵活，自然语言驱动 | 成本高（需LLM调用） |
| 无需适配控件ID变化 | 速度慢（每步需AI推理） |
| 可处理未知场景 | 准确率不如精确定位 |
| 代表未来方向 | 技术尚在发展中 |
---
## 四、奥创底层技术推断
### 4.1 核心技术栈推断
基于奥创的功能特征（聊天记录实时同步、无需扫码登录、数据库级数据获取），推断奥创主要采用：
```
┌─────────────────────────────────────────────────────────┐
│ 奥创云脑技术架构（推断） │
├─────────────────────────────────────────────────────────┤
│ │
│ 手机端： │
│ ├── 定制ROM / Root + Magisk + LSPosed/Xposed │
│ ├── 微信Hook模块（拦截消息/联系人/红包/朋友圈） │
│ ├── 手机监控模块（通话/短信/GPS/录音） │
│ ├── Agent常驻服务（保活+心跳+指令接收） │
│ └── WebSocket/MQTT 长连接到云端 │
│ │
│ 云端： │
│ ├── API Gateway（Spring Boot / Java） │
│ ├── WebSocket Hub（设备连接管理） │
│ ├── 业务服务（消息/好友/群/朋友圈/风控/统计） │
│ ├── 数据库（MySQL + MongoDB + Redis） │
│ └── Web管理后台（007.siyuguanli.com） │
│ │
│ 管理端： │
│ ├── Web后台（React/Vue） │
│ ├── 云客服系统（多微信统一管理） │
│ └── Swagger API（对外开放接口） │
│ │
└─────────────────────────────────────────────────────────┘
```
### 4.2 关键推断依据
| 功能特征 | 推断技术 | 原因 |
|----------|----------|------|
| "聊天记录实时同步" | Hook + 数据库读取 | 无障碍/ADB无法实时获取完整聊天记录 |
| "无需扫码永远登录" | Hook微信登录模块 | 保持微信登录状态不过期 |
| "红包转账监控" | Hook微信支付函数 | 需要拦截内部函数才能获取金额等详情 |
| "敏感操作监控（删好友等）" | Hook微信操作函数 | 需要在操作发生时实时拦截 |
| "多微信账号" | 定制ROM/虚拟空间 | 需要系统级支持多开 |
| "后台自动报警" | 常驻Agent + WebSocket | 需要持续运行+实时通信 |
### 4.3 与机擎SDK技术对比
| 维度 | 奥创（推断） | 机擎SDK（当前） | 差异 |
|------|-------------|----------------|------|
| **主要通道** | Hook注入为主 | ADB + WebSocket + AI Agent | 机擎更合规 |
| **Root要求** | 需要Root | 不需要Root | 机擎门槛低 |
| **数据获取** | 数据库级（完整） | UI级（部分） | 奥创更完整 |
| **实时性** | 函数级实时 | 操作级实时 | 奥创更快 |
| **稳定性** | 依赖微信版本 | 不依赖内部API | 机擎更稳定 |
| **合规性** | 修改APP，风险高 | 不修改APP，合规 | 机擎更安全 |
| **封号风险** | 高 | 低 | 机擎更安全 |
| **扩展性** | 仅微信 | 微信/抖音/小红书/闲鱼等 | 机擎更广 |
| **AI能力** | 无 | AI Agent（M12） | 机擎领先 |
---
## 五、交互模型详解
### 5.1 奥创交互流程（推断）
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 管理后台 │ │ 云端服务器 │ │ 手机设备 │
│ (Web/007) │ │ (API+WS) │ │ (Hook Agent) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ 1.发送消息指令 │ │
│ ─────────────────> │ │
│ POST /message/send│ │
│ │ │
│ │ 2.WebSocket下发 │
│ │ ──────────────────> │
│ │ {action:send_msg} │
│ │ │
│ │ │ 3.Hook调用微信
│ │ │ 内部发消息函数
│ │ │
│ │ 4.执行结果回传 │
│ │ <────────────────── │
│ │ {success:true} │
│ │ │
│ 5.返回结果 │ │
│ <───────────────── │ │
│ {code:200} │ │
│ │ │
│ │ ===== 实时同步 === │
│ │ │
│ │ 6.新消息Hook拦截 │
│ │ <────────────────── │
│ │ {type:new_message} │
│ │ │
│ 7.推送新消息 │ │
│ <───────────────── │ │
│ WebSocket/SSE │ │
```
### 5.2 机擎SDK交互流程（当前）
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 存客宝/ │ │ 机擎SDK │ │ 手机设备 │
│ 触客宝 │ │ 服务端 │ │ (Agent) │
│ (PHP/TS) │ │ (FastAPI) │ │ (u2+ADB) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ 1.中间层调用 │ │
│ ─────────────────> │ │
│ WorkPhoneSDK │ │
│ ::sendMessage() │ │
│ │ │
│ │ 2.通道选择 │
│ │ 官方API→SDK→Agent │
│ │ │
│ │ 3.WebSocket下发 │
│ │ ──────────────────> │
│ │ execute{script, │
│ │ action,params} │
│ │ │
│ │ │ 4.u2模拟操作
│ │ │ 打开微信→找对话
│ │ │ →输入→发送
│ │ │
│ │ 5.response回传 │
│ │ <────────────────── │
│ │ {success,data} │
│ │ │
│ 6.返回结果 │ │
│ <───────────────── │ │
│ {success:true} │ │
```
### 5.3 两种模型的核心差异
| 维度 | 奥创（Hook模型） | 机擎（操作模型） |
|------|-----------------|------------------|
| 操作方式 | 调用APP内部函数 | 模拟用户UI操作 |
| 速度 | 毫秒级 | 秒级（需等UI） |
| 可见性 | 后台静默，用户无感 | 前台操作，屏幕可见 |
| 数据获取 | 数据库级完整数据 | UI级可见数据 |
| 维护成本 | 每次微信更新需适配 | 相对稳定 |
| 风险 | 高（修改进程） | 低（正常操作） |
---
## 六、关键GitHub资源汇总
### 6.1 工作手机/云控 综合方案
| 项目 | 地址 | Stars | 说明 |
|------|------|-------|------|
| gongzuoshouji | github.com/weixin2026/gongzuoshouji | 4 | 完整工作手机SDK（Java），含监控/营销/云客服 |
| 源雀SCRM | gitee.com/iyque/iYqueCode | — | 开源企微SCRM+AI，含会话存档/客户管理 |
| scrm-wecom-api | github.com/douyuxingchen/scrm-wecom-api | — | 企微API封装SDK |
| wecom-openapi | github.com/juzibot/wecom-openapi | — | 企微OpenAPI 3.x Swagger规范 |
### 6.2 Hook框架
| 项目 | 地址 | Stars | 说明 |
|------|------|-------|------|
| LSPosed | github.com/LSPosed/LSPosed | 高 | 当前主流Android Hook框架（2024停更） |
| Frida | github.com/frida/frida | 13k+ | 跨平台动态插桩框架 |
| Xposed | github.com/rovo89/Xposed | — | 经典Hook框架（已停更） |
### 6.3 微信自动化
| 项目 | 地址 | Stars | 说明 |
|------|------|-------|------|
| CPWechatXposed | github.com/coder-pig/CPWechatXposed | 高 | Xposed Hook微信综合项目 |
| wechatbot-xposed | github.com/546669204/wechatbot-xposed | 198 | Xposed微信机器人 |
| wechat-robot | github.com/AlienwareHe/wechat-robot | — | 微信消息HTTP服务暴露 |
| wework_robot | github.com/musi66/wework_robot | — | 企微逆向Hook |
| XMagicHooker | github.com/graysign/XMagicHooker | — | Kotlin企微插件框架 |
| WeChat-Chatbot | github.com/cnlhl/wechat-chatbot | — | Xposed微信自动回复 |
### 6.4 设备控制与自动化
| 项目 | 地址 | Stars | 说明 |
|------|------|-------|------|
| uiautomator2 | github.com/openatx/uiautomator2 | 7.8k | Python Android UI自动化 |
| scrcpy | github.com/Genymobile/scrcpy | 115k | Android投屏+控制 |
| DroidRun | github.com/droidrun/droidrun | 7.6k | LLM驱动Android Agent |
| Fremko | pypi.org/project/fremko | — | WebSocket+FastAPI设备控制 |
| Android-MCP | github.com/CursorTouch/Android-MCP | 217 | MCP Android自动化 |
### 6.5 个人微信SDK（第三方）
| 项目 | 地址 | 说明 |
|------|------|------|
| 个人微信SDK | gitee.com/tangjinjinwx/Public.WeChat.CRM.SDK/ | 微信CRM SDK开发 |
---
## 七、对机擎SDK的启示与建议
### 7.1 可借鉴的功能
| 奥创功能 | 机擎现状 | 建议 |
|----------|----------|------|
| **风控/敏感词** | 未实现 | 新增风控模块：敏感词库+行为监控+报警推送 |
| **统计报表** | 未实现 | 新增统计API：工作量/客户增长/转化率 |
| **聊天记录存档** | 部分（通过UI获取） | 增强消息存储：MongoDB落库+全量查询 |
| **云客服系统** | 未实现 | 存客宝前端集成多微信统一管理界面 |
| **话术库** | 未实现 | 新增话术管理API+快捷调用 |
### 7.2 技术路线建议
机擎当前的**ADB + WebSocket + AI Agent**路线更合规、更稳定，建议：
1. **保持当前路线**：不采用Hook方案，降低封号风险
2. **增强AI Agent**：用AI视觉理解替代Hook的数据获取能力
3. **补充官方API**：企微场景走官方API，个微场景走SDK控制
4. **优化操作速度**：通过缓存UI树、预加载等方式提升u2操作速度
5. **新增风控模块**：对标奥创的敏感词/行为监控能力
---
## 八、附录
### 8.1 原始链接
- 奥创API文档：https://007.siyuguanli.com/api/swagger-ui/index.html
- 奥创文档汇总：https://thoughts.teambition.com/share/5e044d094700080013a8e8d9
- 奥创官网：http://www.aochuang.cn/
### 8.2 相关资料
| 资料 | 说明 |
|------|------|
| 本文档 | 工作手机/资料/奥创.md |
| 机擎SDK架构 | 开发文档/2、架构/系统架构.md |
| 机擎进度 | 开发文档/10、项目管理/开发进度总表.md |
| 服务端SDK抽象 | 机擎/references/工作手机服务端SDK抽象.md |
| 设备端SDK抽象 | 机擎/references/工作手机设备端SDK抽象.md |

360
资料/奥创Hook与Frida详细对比及微信互通.md
View File

@@ -1,360 +0,0 @@
# 奥创 Hook 与 Frida 详细对比及微信互通
> **目标**：奥创 Hook vs Frida，**按远程方案对比**（不依赖 USB），并扩展市面微信私域/工作手机解决方案
> **更新**：2026-02-10
---
## 〇、远程方案总览（不依赖 USB）
| 方案 | 连接方式 | 是否远程 | USB 依赖 |
|------|----------|----------|----------|
| **奥创** | 设备连 007 云端（WiFi/4G），云端下发指令 | ✅ 天然远程 | ❌ 不需要 |
| **Frida 网络模式** | 主机 `-H 设备IP` 连 frida-server | ✅ 同一局域网/公网 | ❌ 不需要 |
| **Frida Gadget** | 脚本内嵌 APK，设备联网后主动连服务器 或 被动监听 | ✅ 可完全远程 | ❌ 不需要 |
| **机擎** | 设备 WebSocket 连 SDK 服务器 | ✅ 天然远程 | ❌ 不需要 |
---
## 一、可连接架构对比（远程场景）
### 1.1 奥创 Hook 可连接架构
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 奥创 Hook 可连接架构 │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 007 管理后台/API │
│ │ │
│ │ HTTPS / WebSocket（指令下发 + 数据上报） │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 007 云端 (007.siyuguanli.com) │ │
│ │ • API Gateway、WebSocket Hub、业务服务、数据库 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ 长连接（设备主动连 / 或推送） │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Android 设备 │ │
│ │ ├── AI数智员工 (uni.UNI9421F6C)：业务 App，接收指令、上报数据、登录 007 │ │
│ │ ├── VivWxjz (top.zzz.vivwxjz)：微信 Hook 模块，注入微信进程 │ │
│ │ └── XESlciw (org.xeslciw.manager)：框架，加载 VivWxjz 等模块 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Scope=com.tencent.mm 时注入 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 微信 (com.tencent.mm) │ │
│ │ • VivWxjz 在 syscall 层拦截 sendmsg/recvmsg，复制报文并上报 007 │ │
│ │ • 发消息：007 下指令 → AI数智员工/或直连 → VivWxjz 调微信内部接口或协议 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
**连接要点**：
| 环节 | 说明 |
|------|------|
| **云端↔设备** | 007 云端与设备通过 HTTPS/WebSocket 连接，设备需安装 AI数智员工 并登录 007 账号 |
| **设备↔微信** | 无直接「连接」概念，VivWxjz 作为 XESlciw 模块注入微信进程，在 syscall 层拦截网络与 Binder |
| **数据上报** | VivWxjz 将拦截到的消息/联系人等通过本地通道交给 AI数智员工，再上报 007 |
| **指令下发** | 007 下发发消息等指令 → 设备侧执行 → VivWxjz 调用微信内部接口或模拟协议完成发送 |
### 1.2 Frida 可连接架构（远程方案，不依赖 USB）
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Frida 远程可连接架构（无 USB） │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 远程服务器 / 控制端 (任意网络) │
│ │ │
│ │ 方式 A：frida -H 设备IP:27042 （frida-server 监听 0.0.0.0） │
│ │ 方式 B：Frida Gadget 内嵌 APK，设备主动连服务器 / 或监听等待 │
│ │ 方式 C：adb connect 设备IP（无线调试）后 frida 连接 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Android 设备（WiFi/4G 联网即可） │ │
│ │ ├── frida-server -l 0.0.0.0（监听所有网卡，支持远程连接） │ │
│ │ │ 或 Frida Gadget 内嵌微信/目标 APK，免 Root │ │
│ │ └── 注入 V8/QJS 引擎，执行 JavaScript 脚本 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ attach/spawn 指定进程（如 com.tencent.mm） │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 微信进程 (com.tencent.mm) │ │
│ │ • 脚本内 Java.perform / Interceptor.attach 等 Hook 微信 Java/Native │ │
│ │ • rpc.exports 暴露函数给远程主机，主机可主动调用 │ │
│ │ • send() 把数据推到远程主机 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
**Frida 远程连接三种方式**：
| 方式 | 前提 | 命令/配置 | 适用 |
|------|------|-----------|------|
| **frida-server 网络** | Root，设备与主机同网或可互通 | `frida-server -l 0.0.0.0`；主机 `frida -H 设备IP` | 局域网/公网转发 |
| **Frida Gadget 内嵌** | 反编译微信 APK，注入 frida-gadget.so，重打包 | `libfrida-gadget.config.so` 配置 `listen` 或 `connect` | 免 Root，可远程 |
| **无线 ADB + frida** | 设备开启无线调试 | `adb connect IP:端口` 后 `frida -U` | 同网段 |
**Gadget 远程配置示例**（设备主动连服务器）：
```json
{"interaction":{"type":"connect","address":"服务器IP:27042"}}
```
或监听模式（服务器连设备）：
```json
{"interaction":{"type":"listen","address":"0.0.0.0:27042"}}
```
**连接要点**：
| 环节 | 说明 |
|------|------|
| **主机↔设备** | 远程：`-H 设备IP` 或 Gadget 配置 connect/listen；**无需 USB** |
| **设备↔微信** | Frida 向微信进程注入脚本，连接即「附加到进程」 |
| **数据上报** | 脚本 `send(data)` → 远程主机 `on('message')` |
| **指令下发** | 远程主机 `script.exports.xxx()` 调用，在微信进程内执行 |
### 1.3 可连接性对照表（远程方案）
| 维度 | 奥创 Hook | Frida（远程） |
|------|-----------|---------------|
| **谁连谁** | 007 云端 ↔ 设备（AI数智员工） | 远程服务器 ↔ 设备（frida-server/Gadget） |
| **USB 依赖** | ❌ 不需要 | ❌ 不需要（网络/Gadget） |
| **设备端常驻** | AI数智员工 + XESlciw + VivWxjz | frida-server 或 Gadget |
| **网络要求** | 设备能连 007 云端即可 | 设备与服务器网络互通 |
| **指令下发** | 007 API/WebSocket → 设备 App → Hook | 远程主机 script.exports → 脚本执行 |
| **数据上报** | Hook 模块 → 007 云端 | 脚本 send() → 远程主机 |
| **多设备管理** | 007 后台统一管理 | 需自建：多设备多连接 |
| **免 Root** | ❌ | ✅ Gadget 内嵌可免 Root |
---
## 二、微信互通能力详细对比
### 2.1 登录与账号
| 能力 | 奥创 Hook | Frida |
|------|-----------|-------|
| **登录方式** | 用户在手机微信内正常登录（扫码/密码），无需额外接口 | 同左，微信自身登录 |
| **检测是否已登录** | 可由 VivWxjz 读进程/DB 或 007 侧记录设备绑定 | 脚本内 Java 查微信登录态类/DB |
| **获取当前账号信息** | 通过 Hook/Binder 获取 wxid、昵称等，上报 007 | Java.use 查相关类或 DB，send 到主机 |
| **多账号** | 多设备或多开，每设备/进程一个微信；007 按设备管理 | 多进程 attach 或多设备，主机侧区分 |
**结论**：二者都依赖「微信已在设备上登录」，不提供独立登录 API；账号信息获取均需自写 Hook/读库，奥创已集成在 VivWxjz，Frida 需自写脚本。
### 2.2 发消息
| 能力 | 奥创 Hook | Frida |
|------|-----------|-------|
| **实现方式** | VivWxjz 调微信内部发消息接口或组包发协议 | 脚本 Hook 发消息方法后调用原实现，或逆向找发送函数用 NativeFunction 调 |
| **接口形态** | 007 调用 API → 设备 → VivWxjz 执行 | 主机 script.exports.send_text(wxid, msg) 等 |
| **文本消息** | ✅ 支持 | ✅ 需自写 Hook/调用 |
| **图片/文件/卡片** | ✅ 支持（协议/内部接口） | ✅ 需自写 |
| **@群友** | ✅ 支持 | ✅ 需自写 |
| **延迟与稳定性** | 毫秒级，不依赖 UI | 同左，取决于脚本实现 |
| **版本适配** | 奥创随微信更新可能需发版 | 脚本可热更新，适配快 |
**结论**：发消息能力二者都能做；奥创开箱可用，Frida 需逆向+写脚本，但可热更新适配新版本。
### 2.3 收消息 / 消息同步
| 能力 | 奥创 Hook | Frida |
|------|-----------|-------|
| **实现方式** | VivWxjz 在 syscall 层拦截 recvmsg，复制报文解析后上报 007 | 脚本 Hook 微信收消息/写 DB 的 Java 或 Native 函数，在回调里 send 到主机 |
| **实时性** | 高（网络层拦截） | 高（取决于 Hook 点） |
| **历史消息** | 可读本地 DB 或协议拉取 | 可 Hook 读 DB 或查库 |
| **推送形态** | 007 云端 → 管理后台/API | 设备脚本 send → 主机 → 自建服务 |
**结论**：都能做实时收消息；奥创已做成产品（007 同步），Frida 需自建上报与存储。
### 2.4 联系人 / 群 / 标签
| 能力 | 奥创 Hook | Frida |
|------|-----------|-------|
| **联系人列表** | VivWxjz 通过 Binder/DB 或协议获取，上报 007 | Java.use 查联系人相关类或 EnMicroMsg.db |
| **群列表 / 群成员** | 同上 | 同上，需自写 |
| **标签** | 同上 | 同上 |
| **备注/昵称** | 支持 | 需自写 |
**结论**：奥创已集成；Frida 需自写 Hook/读库，能力等价。
### 2.5 朋友圈
| 能力 | 奥创 Hook | Frida |
|------|-----------|-------|
| **发朋友圈** | Hook 发朋友圈接口，007 下指令执行 | Hook 发朋友圈方法并调用 |
| **刷朋友圈/点赞/评论** | 可 Hook 相关接口 | 需自写 |
| **拉取朋友圈列表** | 协议或 DB | 需自写 |
**结论**：奥创产品化；Frida 均可实现，需开发量。
### 2.6 红包 / 转账监控
| 能力 | 奥创 Hook | Frida |
|------|-----------|-------|
| **监控** | VivWxjz 可 Hook 支付相关，上报 007 | Hook 支付/红包类方法，send 到主机 |
| **合规风险** | 高 | 高 |
**结论**：二者都能做，均存在合规与风控风险。
---
## 三、微信互通总表（奥创 vs Frida）
| 微信互通能力 | 奥创 Hook | Frida | 说明 |
|--------------|:---------:|:-----:|------|
| **登录** | 依赖手机微信已登录 | 同左 | 无独立登录 API |
| **是否已登录检测** | ✅ 可做 | ✅ 需自写 | 奥创已集成 |
| **当前账号信息** | ✅ 可做 | ✅ 需自写 | 同上 |
| **发文本消息** | ✅ | ✅ 需自写 | 奥创调内部/协议 |
| **发图片/文件** | ✅ | ✅ 需自写 | 同上 |
| **收消息实时同步** | ✅ syscall 拦截 | ✅ Hook 收消息/DB | 奥创已产品化 |
| **联系人/群/标签** | ✅ | ✅ 需自写 | 奥创已集成 |
| **朋友圈** | ✅ | ✅ 需自写 | 同上 |
| **红包/转账监控** | ✅ | ✅ 需自写 | 合规风险高 |
| **与云端/中台对接** | ✅ 007 现成 | ❌ 需自建 | 奥创闭环 |
| **脚本热更新** | ❌ 需重装模块 | ✅ | Frida 灵活 |
| **免 Root** | ❌ | ✅ Gadget | 仅 Frida |
| **多 APP（非微信）** | 需另写模块 | ✅ 同一套脚本思路 | Frida 通用 |
---
## 四、微信解封与自动化
### 4.1 官方解封途径（推荐）
| 类型 | 途径 | 说明 |
|------|------|------|
| **临时限制（7–30 天）** | 微信安全中心、腾讯客服小程序、95017 | 设备一致性 + 活体检测 + 好友辅助 |
| **好友辅助** | 微信团队 → 自助工具 → 解封/申诉辅助验证 | 辅助人需注册满 6 个月、实名、30 天内未辅助 |
| **永久封禁申诉** | 人工申诉 | 身份证、手持证件、支付凭证、聊天/朋友圈截图 |
**注意**：第三方自动化解封工具属非法，易被骗；频繁申诉会消耗次数（单账号最多 3 次）。
### 4.2 奥创 / Frida 与解封的关系
| 方案 | 能否自动化解封 | 说明 |
|------|----------------|------|
| **奥创** | ❌ 不提供 | 工作手机偏监控与营销，不解封 |
| **Frida** | ⚠️ 理论上可辅助 | 可 Hook 解封流程 UI 做自动化点击，但需好友配合、活体检测难绕过，**风险高且违规** |
| **市面产品** | 多数不提供 | 解封依赖官方审核，自动化空间有限 |
**结论**：解封应走官方通道；自动化解封不合规，不建议用 Hook 实现。
---
## 五、市面微信私域 / 工作手机解决方案扩展
### 5.1 方案总览
| 方案 | 类型 | 设备 | 远程 | Root | 适用 |
|------|------|------|:----:|:----:|------|
| **奥创** | Hook + 云端 | Android 手机 | ✅ | 需 | 个微工作手机 |
| **Frida 远程** | Hook | Android 手机 | ✅ | 可选(Gadget 免) | 自建、研发 |
| **机擎** | u2/ADB + 云端 | Android 手机 | ✅ | 否 | 个微工作手机 |
| **WeChatFerry** | 注入 PC 微信 | PC Windows | ✅ 可 | 否 | 个微，PC 场景 |
| **iPad 协议** | 模拟企微客户端 | 服务器 | ✅ | 否 | **仅企微** |
| **云手机** | 虚拟化 | 云端虚拟机 | ✅ | 否 | 多开、托管 |
| **无极私域/企云心服** | 合规监控 | 工作手机 | ✅ | 视产品 | 企微+个微管控 |
| **企微官方 API** | 官方 | 云端 | ✅ | 否 | **仅企微** |
### 5.2 各方案简述
#### 奥创（已详述）
- 007 云端 + VivWxjz Hook + AI数智员工，远程下发指令、实时同步消息
- 需 Root + Magisk，封号风险较高
#### Frida 远程
- frida-server 监听 `0.0.0.0` 或 Gadget 内嵌，主机 `-H 设备IP` 远程连接
- 微信互通需自写脚本，可热更新，可免 Root（Gadget）
#### 机擎
- 设备 WebSocket 连 SDK 服务器，u2/ADB 模拟操作，免 Root
- 已实现发消息、好友、群、朋友圈等，远程天然支持
#### WeChatFerry 远程部署
- PC 微信 + DLL 注入，可部署在 Windows 服务器，`--host 0.0.0.0` 暴露 API
- 支持登录检测、发消息、收消息、联系人、朋友圈；版本绑定（如 3.9.2.23）
- 注：项目曾停更，需关注社区 fork
#### iPad 协议（企微）
- 模拟企业微信 iPad 客户端，通过网页/私有协议与企微服务器通信
- 仅**企业微信**，不适用个人微信；支持会话、群、联系人、朋友圈、消息收发
- 单服务器可托管数百企微账号，私有化/云端均可
#### 云手机（星界、川川、多多云等）
- 云端安卓虚拟机，每台独立设备指纹，支持微信多开、脚本托管
- 远程操作、24 小时挂机，防封依赖 IP 轮换、资料差异化
- 适用多账号营销、工作手机集中托管
#### 无极私域 / 企云心服
- 企业级工作手机管理，场景化监控、客户资产保护、敏感行为预警
- 合规设计（工作时间、工作手机），支持个微+企微
#### 企微官方 API
- 会话存档、客户联系、消息推送等，完全合规
- 仅企业微信，需企业认证
### 5.3 综合对比（远程 + 微信互通 + 自动化）
| 能力 | 奥创 | Frida远程 | 机擎 | WeChatFerry | iPad协议 | 云手机 | 企微官方 |
|------|:----:|:---------:|:----:|:-----------:|:--------:|:------:|:--------:|
| **远程连接** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **不依赖 USB** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **登录微信** | 手机内登 | 同左 | 同左 | PC 扫码 | 企微登录 | 云端登 | 企微 |
| **发消息** | ✅ | ✅ 自写 | ✅ | ✅ | ✅ 企微 | ✅ | ✅ 企微 |
| **收消息同步** | ✅ | ✅ 自写 | ⚠️ UI | ✅ | ✅ | ✅ | ✅ |
| **联系人/群/朋友圈** | ✅ | ✅ 自写 | ✅ | ✅ | ✅ | ✅ | ✅ 企微 |
| **自动化操作** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ 脚本 | ✅ |
| **微信解封** | ❌ | ⚠️ risky | ❌ | ❌ | ❌ | ❌ | ❌ |
| **免 Root** | ❌ | ✅ Gadget | ✅ | ✅ | ✅ | ✅ | ✅ |
| **个人微信** | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
---
## 六、选型与落地建议
### 6.1 要远程 + 可连接 + 云端打通、快速用上微信互通
- **选奥创**：007 云端 ↔ 设备，天然远程；开箱可用，代价是 Root、封号风险较高。
- **选 Frida 远程**：服务器 `-H 设备IP` 或 Gadget 内嵌，自建云端；需自写脚本，可热更新。
### 6.2 要自建、可热更新、多 APP、免 Root
- **选 Frida + Gadget**：内嵌 APK，免 Root，远程连接；微信互通自写脚本，可扩展抖音等。
- **选机擎**：免 Root，WebSocket 远程，u2 自动化；已覆盖微信主要能力。
### 6.3 要微信互通但尽量少 Hook、降低风险
- **优先**：PC 方案（WeChatFerry / wxauto）远程部署 + 机擎桥接；
- **企微场景**：iPad 协议 或 企微官方 API；
- **多开/托管**：云手机；
- **仅 Root 且接受风险时**：奥创或 Frida Hook。
### 6.4 微信解封
- **一律走官方**：安全中心、客服、95017；勿用第三方自动化解封工具。
---
## 七、参考资料
| 文档 | 路径 |
|------|------|
| XESlciw 与 Frida 及机擎详细对比 | 资料/XESlciw与Frida及机擎详细对比分析.md |
| 奥创复刻与微信 Hook 拆解 | 资料/奥创工作手机-复刻开发详解.md |
| 微信互通更好替代方案 | 资料/微信互通方案对比与更好替代.md |
| XESlciw 接口与 Hook 手册 | 资料/XESlciw接口与设备Hook开发手册.md |
| 外部链接 | 说明 |
|----------|------|
| Frida Gadget | https://frida.re/docs/gadget/ |
| WeChatFerry | https://wechatferry.readthedocs.io/ |
| 企微开发文档 | https://developer.work.weixin.qq.com/ |

373
资料/奥创工作手机-复刻开发详解.md
View File

@@ -1,373 +0,0 @@
# 奥创工作手机 — 复刻开发详解
> **目标**：深度拆解安装顺序、底层功能、微信 Hook 流程，支撑机擎设备端功能开发
> **来源**：真机提取 APK 逆向分析 + 奥创资料
> **更新**：2026-02-24
---
## 一、安装顺序与依赖关系（完整流程）
### 1.1 安装流程图
```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ 奥创工作手机 安装顺序流程图 │
└─────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐
│ ① 设备准备 │
│ Android 11 │
│ 需 Root │
└──────┬───────┘
│
▼
┌──────────────┐ Magisk 刷入
│ ② 安装 Magisk│ ──────────────────────> Root 环境就绪
│ (v24+) │
└──────┬───────┘
│
▼
┌──────────────────────────────────┐
│ ③ 安装 XESlciw Manager │ org.xeslciw.manager v1.8.4
│ (LSPosed 类框架) │ → 仅为管理端 UI，框架需单独刷入
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ ④ 刷入 XESlciw 框架 │ 通过 Magisk 模块 或 /data/adb/xesd/
│ (Zygisk/Riru 注入) │ 框架注入 Zygote，接管 APP 进程启动
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ ⑤ 安装 微信 Hook 模块 │ top.zzz.vivwxjz v1.0
│ (VivWxjz) │ → 在 XESlciw Manager 中启用，选择 scope=微信
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ ⑥ Scope 配置 │ 将 VivWxjz 的作用域设为 com.tencent.mm
│ Module scope = 微信 │ → 微信进程启动时加载 Hook
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ ⑦ 安装 AI数智员工 │ uni.UNI9421F6C v1.1.2
│ (007 业务入口) │ → 登录 007 账号，对接云端
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ ⑧ 登录微信 + 绑定设备 │ 微信扫码/登录 → 007 云端绑定此设备
└──────────────────────────────────┘
```
### 1.2 依赖关系图
```
┌─────────────────┐
│ Magisk │
│ (Root 环境) │
└────────┬────────┘
│
┌──────────────┴──────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ XESlciw 框架 │ │ XESlciw Manager│
│ (Zygisk 注入) │◄──────────│ (管理 UI) │
└────────┬────────┘ └─────────────────┘
│
│ 加载模块 (scope 匹配时)
▼
┌─────────────────┐ ┌─────────────────┐
│ VivWxjz │ │ AI数智员工 │
│ 微信 Hook 模块 │ │ (业务 App) │
└────────┬────────┘ └────────┬────────┘
│ │
│ 注入 com.tencent.mm │ 对接 007.siyuguanli.com
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ 微信 │ │ 007 云端 │
│ com.tencent.mm │ │ API + WebSocket│
└─────────────────┘ └─────────────────┘
```
---
## 二、微信 Hook 模块 — 底层功能深度拆解
### 2.1 技术路线：Syscall 级拦截（非传统 Xposed Java Hook）
**关键发现**：VivWxjz 采用 **ptrace/syscall 拦截**，而非 Xposed 的 Java 方法 Hook。
| 维度 | 传统 Xposed | VivWxjz (奥创) |
|------|-------------|----------------|
| Hook 层 | Java 方法 | Linux Syscall |
| 拦截点 | 微信 .dex 内方法 | socket/connect/bind/recvmsg/sendmsg |
| 数据来源 | 方法参数/返回值 | 网络报文、Binder IPC |
| 微信版本 | 强依赖，需适配 | 相对稳定（协议层） |
### 2.2 微信相关 Syscall 与路径
```
拦截的 Syscall（从 strings 提取）:
├── socket / socketpair # 创建套接字
├── bind / connect / listen # 连接建立
├── send / sendto # 发送数据
├── sendmsg / sendmmsg # 消息发送
├── recvmsg / recvmmsg # 消息接收
├── sendfile / sendfile64 # 文件传输
├── mq_timedsend / mq_timedreceive # 消息队列
├── msgget / msgsnd / msgrcv / msgctl # System V 消息
└── parse_binder_data # Binder IPC 解析
```
**监控路径**：
- `/data/user/0/com.tencent.mm` — 微信数据目录
- `/data/data/com.tencent.mm/cache/maps` — 微信缓存/内存映射
### 2.3 模块加载入口
```
assets/grvjfe_init 内容:
top.zzz.vivwxjz.Main # Java 入口类
libvivwxjz.so # Native 实现
assets/native_init 内容:
(指向 libvivwxjz.so 的 JNI 加载)
```
### 2.4 微信消息流 — 推断的数据流
```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ 微信消息 收发 数据流（Syscall Hook 推断） │
└─────────────────────────────────────────────────────────────────────────────────────────┘
[用户发消息]
│
▼
微信 UI 输入 ──> 微信协议层 ──> send/sendmsg() ──> 腾讯服务器
│ │
│ │ ← VivWxjz 拦截
│ ▼
│ ┌──────────────┐
│ │ 复制报文内容 │
│ │ 解析协议 │
│ └──────┬───────┘
│ │
│ ▼
│ ┌──────────────┐
│ │ 上报 007 云端 │ (HTTP/WebSocket)
│ │ 或本地存储 │
│ └──────────────┘
[用户收消息]
腾讯服务器 ──> recv/recvmsg() ──> 微信协议层 ──> 微信 UI 展示
│
│ ← VivWxjz 拦截
▼
┌──────────────┐
│ 复制报文内容 │
│ 解析协议 │
└──────┬───────┘
│
▼
┌──────────────┐
│ 上报 007 云端 │
│ 实时同步 │
└──────────────┘
```
### 2.5 额外发现的进程路径
```
/data/data/io.github.vvb2060.mahoshojo/cache/maps
```
说明：可能同时监控「魔法少女」等工具，或为同一开发方的其他产品。
### 2.6 libvivwxjz.so 关键能力
| 能力 | 实现方式 | 说明 |
|------|----------|------|
| 网络拦截 | translate_socketcall_enter/exit | 拦截 socket 相关 syscall |
| Binder 解析 | parse_binder_data | 解析微信与系统的 Binder 通信 |
| 进程识别 | /data/user/0/com.tencent.mm | 通过路径判断目标进程 |
| 双架构 | arm64-v8a + armeabi-v7a | 支持 64/32 位 |
---
## 三、三层模块 — 功能清单与复刻对照
### 3.1 XESlciw Manager（框架管理端）
| 功能 | 说明 | 机擎复刻参考 |
|------|------|--------------|
| 模块列表 | 显示已安装 LSPosed 模块 | 若采用 Hook 路线，需类似模块管理 |
| Scope 配置 | 为每个模块指定生效 APP | 设备端需「按 APP 启用技能」的能力 |
| 模块启用/禁用 | 开关控制 | 可做「按设备/任务启用」 |
| 寄生模式 | 可卸载 Manager，框架仍运行 | 降低检测面 |
| 版本检查 | XESlciw 框架与 Manager 版本匹配 | 兼容性校验 |
### 3.2 VivWxjz（微信 Hook 模块）
| 功能 | 技术点 | 机擎复刻方向 |
|------|--------|--------------|
| 消息实时同步 | Syscall 拦截 send/recv | **方案 A**：Frida Hook 微信协议层<br>**方案 B**：保持 u2+ADB，做 UI 轮询 |
| 发消息 | 调用微信内部接口 或 模拟协议 | **方案 A**：逆向微信协议直接发包<br>**方案 B**：u2 模拟点击发送（当前） |
| 联系人 | Binder/DB 读取 | **方案 A**：Hook 或读 EnMicroMsg.db<br>**方案 B**：UI 树解析（当前） |
| 红包/转账监控 | Hook 支付相关 | 可选增强，合规风险高 |
### 3.3 AI数智员工（业务 App）
| 功能 | 说明 | 机擎复刻 |
|------|------|----------|
| 登录 | pages/login/index | 对接自有认证 |
| 聊天 | pages/chat/index | 可做成 Web 管理端或 H5 |
| 对接 007 | 007.siyuguanli.com API | 对接机擎 unified API |
| 网络超时 | request 60s, WebSocket 60s | 可复用 |
---
## 四、机擎设备端复刻 — 功能映射与开发建议
### 4.1 复刻路线选择
| 路线 | 优势 | 劣势 | 适用场景 |
|------|------|------|----------|
| **A. Hook 路线** | 实时、完整、可后台 | 需 Root、合规风险、维护成本高 | 内部/合规场景 |
| **B. u2+ADB 路线（当前）** | 免 Root、合规 | 非实时、依赖 UI、需亮屏 | 通用商业化 |
| **C. 混合** | 按设备能力选通道 | 实现复杂 | 多机型兼容 |
### 4.2 设备端功能模块拆解（可直接落任务）
```
机擎设备端 复刻清单
├── 1. 连接与注册
│ ├── WebSocket 长连 SDK 服务器
│ ├── 设备 ID / 项目 ID 上报
│ └── 心跳、重连、离线缓存
│
├── 2. 指令执行（已有）
│ ├── wechat.send_message
│ ├── wechat.get_messages（UI 树解析）
│ ├── wechat.get_contacts
│ └── screenshot / 其他 Skill
│
├── 3. 增强：实时同步（可选）
│ ├── 方案 B：定时截图+OCR 检测新消息
│ ├── 方案 A：Frida 注入微信读 DB（需 Root）
│ └── 事件上报：new_message, new_friend_request
│
├── 4. 增强：稳定性
│ ├── 微信版本检测与降级提示
│ ├── 操作失败重试（u2 易受 UI 变化影响）
│ └── 健康检查（微信是否在前台、是否卡死）
│
└── 5. 管理端（对标 AI数智员工）
├── 设备绑定 / 解绑
├── 任务下发与状态
└── 简单聊天/监控视图（Web 或 H5）
```
### 4.3 微信相关接口 — 与奥创能力对照
| 奥创能力 | 实现方式 | 机擎当前 | 增强建议 |
|----------|----------|----------|----------|
| 发消息 | Hook 调内部接口 | u2 模拟 | 优化 u2 流程，加超时与重试 |
| 收消息同步 | Syscall 拦截 | 无 | 定时 UI 拉取 或 Frida（需 Root） |
| 联系人 | Binder/DB | UI 树 | 可尝试读 DB（需 Root） |
| 群发 | 批量调用 | 支持 batch-send | 保持 |
| 朋友圈 | Hook | 未实现 | 低优先级 |
---
## 五、流程图汇总（Mermaid）
### 5.1 安装流程
```mermaid
flowchart TD
A[设备 Root + Magisk] --> B[安装 XESlciw Manager]
B --> C[刷入 XESlciw 框架]
C --> D[安装 VivWxjz 微信 Hook]
D --> E[Scope 设为 com.tencent.mm]
E --> F[安装 AI数智员工]
F --> G[登录 007 + 微信绑定]
```
### 5.2 运行时 — 发消息流程
```mermaid
sequenceDiagram
participant U as 007 管理端
participant C as 007 云端
participant A as AI数智员工
participant H as VivWxjz Hook
participant W as 微信
U->>C: POST 发消息
C->>A: 推送任务 / WebSocket
A->>H: 调用发消息（或云端直连设备）
H->>W: 调用内部接口 / 模拟协议
W->>H: 发送完成
H->>C: 上报结果
C->>U: 返回成功
```
### 5.3 运行时 — 收消息同步流程
```mermaid
sequenceDiagram
participant W as 微信
participant H as VivWxjz Hook
participant C as 007 云端
participant U as 管理端
W->>W: recvmsg 收到服务器消息
H->>H: 拦截 recvmsg
H->>H: 解析协议 / 复制数据
H->>C: HTTP/WS 上报新消息
C->>U: 推送给管理端
```
---
## 六、APK 与关键文件速查
| 包名 | APK 路径（设备） | 提取后文件名 |
|------|------------------|--------------|
| org.xeslciw.manager | /data/app/manager_sign/manager_sign.apk | org.xeslciw.manager_XESlciw_Manager_v1.8.4.apk |
| top.zzz.vivwxjz | /data/app/VivWxjz/VivWxjz.apk | top.zzz.vivwxjz_微信Hook模块_v1.0.apk |
| uni.UNI9421F6C | base.apk | uni.UNI9421F6C_AI数智员工_v1.1.2.apk |
| 关键 Native | 说明 |
|-------------|------|
| libvivwxjz.so | 主 Hook 逻辑，syscall 拦截 |
| libwechatnormsg.so | 微信消息相关（可能在主 so 内或依赖） |
---
## 七、复刻开发优先级建议
| 优先级 | 任务 | 预估 | 说明 |
|:------:|------|------|------|
| P0 | 完善 u2 发消息流程 | 2-4h | 成功率、超时、重试 |
| P0 | 设备 WebSocket 在线率 | 2h | 心跳、重连、状态同步 |
| P1 | 收消息同步（UI 轮询） | 4-8h | 定时拉 UI 树，解析新消息 |
| P1 | 管理端 H5 雏形 | 8h | 登录、设备列表、简单聊天 |
| P2 | Frida 注入方案调研 | 4h | 评估 Root 场景可行性 |
| P2 | 微信 DB 读取（需 Root） | 8h | EnMicroMsg.db 解密与查询 |
---
## 八、参考资料
- **XESlciw 详解与技术方案对比**：`资料/XESlciw详解与工作手机技术方案对比.md`
- 奥创官网：http://www.aochuang.cn/
- 007 后台：https://007.siyuguanli.com/
- 工作手机资料：`资料/奥创.md`
- 提取 APK：`资料/奥创工作手机APK提取/`

110
资料/奥创工作手机APK提取/README.md
View File

@@ -1,110 +0,0 @@
# 奥创工作手机 — 安装包提取与业务拆解
> **提取日期**: 2026-02-24
> **设备**: 788e3a0f0601 (Xiaomi Redmi 21121119SC)
> **来源**: 已安装奥创工作手机套件的真机提取
---
## 一、业务架构拆解
奥创工作手机在设备上采用 **三层架构**：
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 奥创工作手机 手机端业务架构 │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 应用层：AI数智员工 (uni.UNI9421F6C) │ │
│ │ • 管理界面、任务接收、数据展示 │ │
│ │ • uni-app + H5/WebView，对接 007 私域管理云端 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────┴──────────────────────────────────────┐ │
│ │ 核心层：微信 Hook 模块 (top.zzz.vivwxjz) │ │
│ │ • 注入微信进程，拦截消息/联系人/红包/朋友圈 │ │
│ │ • libvivwxjz.so + libwechatnormsg.so │ │
│ │ • 依赖 XESlciw 框架运行 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────┴──────────────────────────────────────┐ │
│ │ 底层：XESlciw 框架 (org.xeslciw.manager) │ │
│ │ • LSPosed 类 Hook 框架，需 Root + Magisk │ │
│ │ • 管理模块激活、寄生模式、版本更新 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
---
## 二、提取的安装包清单
| 序号 | 包名 | 文件名 | 大小 | 说明 |
|:----:|------|--------|------|------|
| 1 | org.xeslciw.manager | org.xeslciw.manager_XESlciw_Manager_v1.8.4.apk | 2.4 MB | XESlciw 框架管理端，LSPosed 类 |
| 2 | top.zzz.vivwxjz | top.zzz.vivwxjz_微信Hook模块_v1.0.apk | 4.8 MB | 微信 Hook 模块，需 XESlciw |
| 3 | uni.UNI9421F6C | uni.UNI9421F6C_AI数智员工_v1.1.2.apk | 15.1 MB | AI数智员工 v1.1.2，007 业务入口 |
---
## 三、安装顺序与依赖
```
1. Root 设备 (Magisk)
│
▼
2. 安装 XESlciw Manager (org.xeslciw.manager)
│ 在 Magisk 中刷入 XESlciw 框架
▼
3. 安装 微信 Hook 模块 (top.zzz.vivwxjz)
│ 在 XESlciw 中启用该模块
▼
4. 安装 AI数智员工 (uni.UNI9421F6C)
│ 配置 007 账号/服务器
▼
5. 登录微信，完成绑定
```
---
## 四、提取命令（供再次提取使用）
```bash
# 设备 Serial
DEVICE=788e3a0f0601
# 拉取 APK（需 ADB 连接）
adb -s $DEVICE pull $(adb -s $DEVICE shell pm path org.xeslciw.manager | cut -d: -f2) ./manager.apk
adb -s $DEVICE pull $(adb -s $DEVICE shell pm path top.zzz.vivwxjz | cut -d: -f2) ./vivwxjz.apk
adb -s $DEVICE pull $(adb -s $DEVICE shell pm path uni.UNI9421F6C | cut -d: -f2) ./ai_employee.apk
```
---
## 五、与奥创官网对应关系
| 官网产品 | 手机端对应 |
|----------|------------|
| 奥创云脑工作手机 | 整套三层架构 |
| 007 私域管理系统 | AI数智员工 App 对接云端 |
| 聊天记录实时同步 | 微信 Hook 模块 |
| 无需扫码永远登录 | Hook 微信登录模块 |
| 红包/转账监控 | Hook 支付函数 |
---
## 六、深度复刻开发
详见 → **[奥创工作手机-复刻开发详解.md](../奥创工作手机-复刻开发详解.md)**
包含：安装流程图、微信 Hook 底层拆解、Syscall 拦截原理、机擎设备端功能映射、开发优先级建议。
---
## 七、注意事项
- **合规**：仅用于自有设备备份与技术分析，请勿用于未授权场景。
- **版本**：提取自当前设备，其他设备/版本可能不同。
- **依赖**：微信 Hook 与 AI数智员工依赖 XESlciw 与 Root 环境。

BIN
资料/奥创工作手机APK提取/org.xeslciw.manager_XESlciw_Manager_v1.8.4.apk
View File

Binary file not shown.

BIN
资料/奥创工作手机APK提取/top.zzz.vivwxjz_微信Hook模块_v1.0.apk
View File

Binary file not shown.

BIN
资料/奥创工作手机APK提取/uni.UNI9421F6C_AI数智员工_v1.1.2.apk
View File

Binary file not shown.

330
资料/奥创微信控制接口与插件提取复用指南.md
View File

@@ -1,330 +0,0 @@
# 奥创微信控制 — 接口与插件完整提取与复用指南
> **目标**：提取奥创控制微信的全部接口、插件名称、底层能力，供机擎（工作手机SDK）复用
> **来源**：真机 APK 逆向 + 奥创资料 + 007 文档推断
> **更新**：2026-02-10
---
## 一、插件与包名完整清单
### 1.1 奥创三层架构（手机端）
| 层级 | 包名 | 显示名/别名 | 版本 | 说明 |
|------|------|-------------|------|------|
| **框架管理** | `org.xeslciw.manager` | XESlciw Manager | v1.8.4 | LSPosed 类框架管理端 |
| **微信 Hook** | `top.zzz.vivwxjz` | VivWxjz | v1.0 | 微信 Hook 模块，核心能力 |
| **业务入口** | `uni.UNI9421F6C` | AI数智员工 | v1.1.2 | 007 业务 App，uni-app |
### 1.2 关联组件
| 组件 | 包名/路径 | 说明 |
|------|-----------|------|
| 微信 | `com.tencent.mm` | 目标 APP，Scope 作用域 |
| 框架存储 | `/data/adb/xesd/` | XESlciw 框架与 Manager 备份 |
| Manager 备份 | `/data/adb/xesd/manager.apk` | 寄生模式下可从此恢复 |
| 可能关联 | `io.github.vvb2060.mahoshojo` | 魔法少女等工具（同开发方？） |
### 1.3 提取的 APK 文件
| 包名 | 文件名 | 路径 |
|------|--------|------|
| org.xeslciw.manager | org.xeslciw.manager_XESlciw_Manager_v1.8.4.apk | 资料/奥创工作手机APK提取/ |
| top.zzz.vivwxjz | top.zzz.vivwxjz_微信Hook模块_v1.0.apk | 资料/奥创工作手机APK提取/ |
| uni.UNI9421F6C | uni.UNI9421F6C_AI数智员工_v1.1.2.apk | 资料/奥创工作手机APK提取/ |
---
## 二、007 云端 API 接口（推断）
> 注：007 API 文档（https://007.siyuguanli.com/api/swagger-ui/index.html）需内网访问，以下根据奥创功能矩阵推断。
### 2.1 设备与连接
| 接口 | 方法 | 说明 | 机擎对应 |
|------|------|------|----------|
| 设备列表 | GET /devices | 在线设备 | GET /api/v3/devices |
| 设备详情 | GET /devices/{id} | 设备状态 | GET /api/v3/devices/{id} |
| 设备指令 | POST /devices/{id}/command | 下发指令 | WebSocket execute |
| 心跳/状态 | WebSocket | 实时连接 | ws_hub |
### 2.2 微信控制（核心）
| 接口 | 方法 | 说明 | 机擎对应 |
|------|------|------|----------|
| 发消息 | POST /message/send | 单发 | POST /api/v3/message/send |
| 批量发 | POST /message/batch-send | 群发 | POST /api/v3/message/batch-send |
| 消息列表 | GET /wechat/messages | 聊天记录 | POST /api/v3/message/list |
| 联系人 | GET /wechat/contacts | 联系人同步 | GET /api/v3/contacts |
| 加好友 | POST /friend/add | 添加好友 | POST /api/v3/friend/add |
| 批量加 | POST /friend/batch-add | 批量加 | POST /api/v3/friend/batch-add |
| 接受好友 | POST /friend/accept | 通过好友请求 | POST /api/v3/friend/accept |
| 设置备注 | POST /friend/set-remark | 备注 | POST /api/v3/friend/set-remark |
| 删除好友 | POST /friend/delete | 删除 | POST /api/v3/friend/delete |
| 创建群 | POST /group/create | 建群 | POST /api/v3/group/create |
| 邀请入群 | POST /group/invite | 邀人 | POST /api/v3/group/invite |
| 移出群 | POST /group/remove | 踢人 | POST /api/v3/group/remove |
| 群发消息 | POST /group/send-message | 群消息 | POST /api/v3/group/send-message |
| 群公告 | POST /group/set-notice | 公告 | POST /api/v3/group/set-notice |
| 群列表 | GET /group/list | 群列表 | GET /api/v3/group/list |
| 群成员 | GET /group/members | 成员 | GET /api/v3/group/members |
| 发朋友圈 | POST /moments/post | 发朋友圈 | POST /api/v3/moments/post |
| 朋友圈列表 | GET /moments/list | 拉朋友圈 | POST /api/v3/moments/list |
| 点赞朋友圈 | POST /moments/like | 点赞 | POST /api/v3/moments/like |
| 评论朋友圈 | POST /moments/comment | 评论 | POST /api/v3/moments/comment |
| 标签创建 | POST /tag/create | 创建标签 | POST /api/v3/tag/create |
| 标签分配 | POST /tag/assign | 打标签 | POST /api/v3/tag/add |
| 标签列表 | GET /tag/list | 标签列表 | GET /api/v3/tag/list |
### 2.3 风控与统计（奥创独有，机擎未实现）
| 接口 | 方法 | 说明 |
|------|------|------|
| 告警列表 | GET /risk/alerts | 敏感行为告警 |
| 敏感词配置 | POST /risk/keywords | 敏感词库 |
| 工作量统计 | GET /stats/workload | 电话/消息工作量 |
| 客户增长 | GET /stats/customer-growth | 客户统计 |
---
## 三、VivWxjz 微信 Hook 模块 — 底层接口
### 3.1 入口与配置
| 配置项 | 路径/值 | 说明 |
|--------|---------|------|
| Java 入口 | `assets/grvjfe_init` | 第一行：`top.zzz.vivwxjz.Main` |
| Native 库 | `assets/grvjfe_init` | 第二行：`libvivwxjz.so` |
| Native 入口 | `assets/native_init` | 内容：`libvivwxjz.so` |
| Scope | Manager 内配置 | 必填：`com.tencent.mm` |
### 3.2 libvivwxjz.so 导出符号
| 符号 | 说明 |
|------|------|
| `JNI_OnLoad` | JNI 加载 |
| `native_init` | XESlciw 调用的入口，返回 `on_library_loaded` |
| `on_library_loaded` | 库加载回调，在此做 Hook |
| `initialize_extension` | 扩展初始化 |
| `kompat_callback` | 兼容回调 |
| `module_main` | 模块主逻辑 |
### 3.3 Syscall 拦截点（从 so 提取）
| 类型 | 符号/接口 | 说明 |
|------|-----------|------|
| Socket 进入 | `translate_socketcall_enter` | 进入 socket 调用时拦截 |
| Socket 退出 | `translate_socketcall_exit` | 退出时处理 |
| Binder 解析 | `parse_binder_data` | 解析 Binder IPC |
| 系统调用 | `socket`、`connect`、`bind`、`listen` | 连接建立 |
| 系统调用 | `sendmsg`、`recvmsg`、`sendmmsg`、`recvmmsg` | 消息收发 |
| 系统调用 | `send`、`sendto`、`sendfile` | 数据发送 |
| 消息队列 | `mq_timedsend`、`mq_timedreceive` | 消息队列 |
| 系统 V 消息 | `msgget`、`msgsnd`、`msgrcv`、`msgctl` | System V 消息 |
### 3.4 监控路径
| 路径 | 说明 |
|------|------|
| `/data/user/0/com.tencent.mm` | 微信数据目录 |
| `/data/data/com.tencent.mm/cache/maps` | 微信缓存/内存映射 |
### 3.5 微信能力与实现方式（VivWxjz）
| 能力 | VivWxjz 实现 | 数据来源 |
|------|--------------|----------|
| 消息收发同步 | Syscall 拦截 sendmsg/recvmsg | 协议层报文 |
| 联系人 | Binder/DB 或协议解析 | parse_binder_data |
| 红包/转账 | 支付相关 Hook | 协议/内部函数 |
| 发消息 | 调用微信内部接口 或 模拟协议 | 需逆向确认 |
| 朋友圈 | Hook 相关函数 | 协议/内部接口 |
---
## 四、XESlciw 框架接口（开发 Hook 模块用）
### 4.1 Native API
| 接口 | 签名 | 说明 |
|------|------|------|
| `native_init` | `NativeOnModuleLoaded(entries)` | 必须导出 |
| `entries->version` | uint32_t | API 版本 |
| `entries->hook_func` | `(target, replace, backup) -> int` | Hook 函数 |
| `entries->unhook_func` | `(target) -> int` | 取消 Hook |
| `on_library_loaded` | `(name, handle) -> void` | 库加载回调 |
### 4.2 Java 入口（可选）
| 接口 | 说明 |
|------|------|
| `IXposedHookLoadPackage` | 包加载时回调 |
| `handleLoadPackage(lpparam)` | 在此 `System.loadLibrary("vivwxjz")` |
### 4.3 配置文件
| 文件 | 说明 |
|------|------|
| `META-INF/xposed/scope.list` | 每行一个包名 |
| `META-INF/xposed/module.prop` | minApiVersion、targetApiVersion |
| `assets/grvjfe_init` | Java 类 + lib 名 |
| `assets/native_init` | so 名列表 |
---
## 五、机擎复用映射表
### 5.1 接口级映射（机擎已实现）
| 奥创能力 | 007 推断接口 | 机擎 API | 实现方式 |
|----------|--------------|----------|----------|
| 发消息 | POST /message/send | POST /api/v3/message/send | u2 模拟 / WebSocket Skill |
| 批量发 | POST /message/batch-send | POST /api/v3/message/batch-send | 逐条 u2 |
| 消息列表 | GET /wechat/messages | POST /api/v3/message/list | UI 树解析 / Skill |
| 联系人 | GET /wechat/contacts | GET /api/v3/contacts | UI 树解析 |
| 加好友 | POST /friend/add | POST /api/v3/friend/add | Skill |
| 批量加 | POST /friend/batch-add | POST /api/v3/friend/batch-add | Skill |
| 接受好友 | POST /friend/accept | POST /api/v3/friend/accept | Skill |
| 设置备注 | POST /friend/set-remark | POST /api/v3/friend/set-remark | Skill |
| 删除好友 | POST /friend/delete | POST /api/v3/friend/delete | Skill |
| 创建群 | POST /group/create | POST /api/v3/group/create | Skill |
| 邀请入群 | POST /group/invite | POST /api/v3/group/invite | Skill |
| 群发消息 | POST /group/send-message | POST /api/v3/group/send-message | Skill |
| 群列表 | GET /group/list | GET /api/v3/group/list | Skill |
| 群成员 | GET /group/members | GET /api/v3/group/members | Skill |
| 发朋友圈 | POST /moments/post | POST /api/v3/moments/post | Skill |
| 朋友圈列表 | GET /moments/list | POST /api/v3/moments/list | Skill |
| 点赞/评论 | POST /moments/like, comment | POST /api/v3/moments/like, comment | Skill |
| 标签 | POST /tag/* | POST /api/v3/tag/* | Skill |
### 5.2 机擎 WechatSkill 方法 ↔ 奥创能力
| 机擎 Skill 方法 | 奥创对应能力 | 备注 |
|-----------------|--------------|------|
| send_message | 发消息 | 已实现 |
| get_messages | 消息同步 | UI 解析，非实时 |
| get_contacts | 联系人 | UI 解析 |
| add_friend | 加好友 | 已实现 |
| accept_friend | 接受好友 | 已实现 |
| batch_add_friend | 批量加好友 | 已实现 |
| set_remark | 设置备注 | 已实现 |
| delete_friend | 删除好友 | 已实现 |
| 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 | 朋友圈列表 | 已实现 |
| batch_send_message | 批量发 | 已实现 |
### 5.3 奥创有、机擎暂无
| 能力 | 说明 | 复用建议 |
|------|------|----------|
| 风控敏感词 | 敏感词库 + 告警 | 新增 M13 风控模块 |
| 工作量统计 | 电话/消息统计 | 新增统计 API |
| 实时消息同步 | Syscall 级拦截 | Frida 抓包 或 UI 轮询增强 |
| 红包/转账监控 | Hook 支付 | 合规风险高，慎用 |
| 后台静默操作 | 无 UI 调用内部接口 | 需 Root + Hook |
---
## 六、复用开发建议
### 6.1 直接复用（无需改架构）
- **接口设计**：机擎 unified API 已覆盖奥创主要能力，可按 007 风格做兼容层
- **Skill 方法**：WechatSkill 已实现全部核心动作，可直接对接
- **设备通道**：WebSocket + ADB 双模式，与 007 的云端→设备模式一致
### 6.2 增强复用（需开发）
| 增强项 | 参考来源 | 实现思路 |
|--------|----------|----------|
| 实时消息同步 | VivWxjz syscall 拦截 | Frida Hook sendmsg/recvmsg，或定时 UI 拉取 |
| 抓包/SSL Bypass | libvivwxjz.so | Frida 实现 M6 抓包服务 |
| 风控模块 | 007 /risk/* | 新增敏感词库、行为监控、告警 API |
| 统计报表 | 007 /stats/* | 新增工作量、客户增长等统计 API |
| Root 增强通道 | VivWxjz | 可选：Frida 或自研 Hook 模块，加速发消息 |
### 6.3 不推荐复用
| 项目 | 原因 |
|------|------|
| 直接使用 XESlciw/VivWxjz APK | 闭源、绑定奥创生态、合规风险 |
| 完全照搬 Syscall Hook | 需 Root、维护成本高、封号风险 |
| 红包/转账监控 | 合规与风控风险高 |
---
## 七、速查表
### 插件包名
```
org.xeslciw.manager # 框架管理
top.zzz.vivwxjz # 微信 Hook
uni.UNI9421F6C # AI 数智员工
com.tencent.mm # 微信（Scope）
```
### VivWxjz 关键符号
```
native_init
on_library_loaded
translate_socketcall_enter
translate_socketcall_exit
parse_binder_data
```
### 机擎 WebSocket 指令格式（与 007 类似）
```json
{
"type": "execute",
"data": {
"script": "wechat",
"action": "send_message",
"params": { "to_id": "xxx", "content": "hello" }
}
}
```
### 机擎 Skill action 清单（wechat）
```
send_message, get_messages, get_contacts
add_friend, accept_friend, batch_add_friend
set_remark, delete_friend
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
batch_send_message
```
---
## 八、参考资料
| 文档 | 路径 |
|------|------|
| 奥创技术分析 | 资料/奥创.md |
| 奥创复刻详解 | 资料/奥创工作手机-复刻开发详解.md |
| APK 提取 | 资料/奥创工作手机APK提取/README.md |
| XESlciw 接口手册 | 资料/XESlciw接口与设备Hook开发手册.md |
| XESlciw 详解 | 资料/XESlciw详解与工作手机技术方案对比.md |
| 机擎架构 | 开发文档/2、架构/系统架构.md |
| 机擎接口规范 | 开发文档/5、接口/接口规范.md |

237
资料/微信互通方案对比与更好替代.md
View File

@@ -1,237 +0,0 @@
# 微信互通方案对比 — 比奥创 Hook 更好的替代方案
> **目标**：列出比奥创 Hook 更优的解决方案，实现「直接登录微信 + 发消息」
> **更新**：2026-02-10
---
## 一、方案总览
| 方案 | 设备 | 登录方式 | Root/注入 | 封号风险 | 推荐度 |
|------|------|----------|-----------|----------|--------|
| **WeChatFerry** | PC | 扫码登录 PC 微信 | 注入 DLL | 低 | ⭐⭐⭐⭐⭐ |
| **wxauto** | PC | 扫码登录 PC 微信 | 无，仅 UI 自动化 | 极低 | ⭐⭐⭐⭐⭐ |
| **wxMaster** | PC | 扫码登录 PC 微信 | 无，读数据库 | 极低 | ⭐⭐⭐⭐ |
| **机擎 + PC 桥接** | PC+云端 | PC 微信登录 | 无/低 | 低 | ⭐⭐⭐⭐ |
| **企微官方 API** | 云端 | 企业认证 | 无 | 无 | ⭐⭐⭐⭐⭐（仅企微） |
| **奥创/VivWxjz** | Android | 手机微信 | 需 Root+Hook | 高 | ⭐⭐ |
| **机擎 u2/ADB** | Android | 手机微信 | 无 | 低 | ⭐⭐⭐ |
| **无障碍服务** | Android | 手机微信 | 无 | 低 | ⭐⭐⭐ |
---
## 二、强烈推荐：PC 端方案（最佳替代）
### 2.1 为什么 PC 端更好？
- **无需 Root**：不折腾手机
- **登录简单**：PC 微信扫码即可，与日常使用一致
- **封号风险更低**：多数方案不注入/不破解协议
- **功能完整**：发消息、收消息、联系人、朋友圈、数据库查询
- **易于集成**：HTTP/gRPC API，机擎可做「PC 桥接」统一接入
### 2.2 方案 A：WeChatFerry（wcferry）— 功能最强
| 项目 | 说明 |
|------|------|
| **安装** | `pip install wcferry` |
| **原理** | 注入 PC 微信进程，gRPC 通信 |
| **环境** | Windows + PC 微信 3.9.2.23（版本需匹配） |
| **文档** | https://wechatferry.readthedocs.io/ |
**核心能力**：
```
✅ 获取登录二维码
✅ 查询登录状态 is_login()
✅ 获取登录账号 get_user_info()
✅ 发送文本/图片/文件/卡片/XML/GIF
✅ @群友、拍一拍、转发
✅ 接收消息（实时监听）
✅ 获取联系人
✅ 查询数据库（聊天记录）
✅ 朋友圈消息
✅ 通过好友申请、添加/删除群成员
```
**快速示例**：
```python
from wcferry import Wcf
wcf = Wcf()
if wcf.is_login():
# 给某人发消息
wcf.send_text("你好", "wxid_xxx")
# 获取联系人
contacts = wcf.get_contacts()
```
**与机擎对接**：机擎服务端可部署「PC 桥接服务」——在 Windows 机器上跑 WeChatFerry，通过 gRPC/HTTP 暴露给机擎 unified API，实现「手机/PC 双通道」。
---
### 2.3 方案 B：wxauto — 不注入、声称不封号
| 项目 | 说明 |
|------|------|
| **安装** | `pip install wxauto` |
| **原理** | Windows UIAutomation API，模拟用户操作 |
| **环境** | Windows + PC 微信 |
| **文档** | https://docs.wxauto.org/ |
**特点**：
- 不侵入微信进程，不 Hook、不破解
- 作者声称「不封号」（需合规使用）
- Python 一行代码即可发消息
**快速示例**：
```python
from wxauto import WeChat
wx = WeChat()
wx.SendMsg('你好！', '文件传输助手') # 或联系人昵称
```
**能力**：发文字/图片/文件、@群友、引用消息、监听消息、获取聊天记录。
---
### 2.4 方案 C：wxMaster — HTTP API、多账号
| 项目 | 说明 |
|------|------|
| **地址** | https://github.com/xz-soft/wxMaster |
| **原理** | 读微信本地数据库，不 Hook |
| **接口** | HTTP GET，默认端口 34567，JSON 返回 |
| **环境** | Windows + 微信 4.0.x |
**特点**：
- 任何语言都能调（HTTP）
- 多账号（多开微信）
- 读数据库方式，不易封号
- 需微信 4.0.x 版本
---
## 三、机擎 + PC 桥接架构（推荐落地方式）
若你希望「统一用机擎 API，但底层用 PC 微信」：
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 存客宝 / 机擎 统一 API │
│ POST /api/v3/message/send 等 │
└─────────────────────────────────────────────────────────────────────────┘
│
┌──────────────┴──────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Android 设备 │ │ PC 桥接服务 │
│ (u2/ADB/Agent) │ │ (WeChatFerry / │
│ 手机微信 │ │ wxauto) │
└──────────────────┘ │ PC 微信 │
└──────────────────┘
```
**实现要点**：
1. 新增设备类型 `device_type: "pc_wechat"`，对应 PC 桥接
2. 桥接服务：在 Windows 上跑 WeChatFerry/wxauto，暴露 HTTP 或 WebSocket
3. 机擎路由：`platform=wechat` 且 `device_id` 指向 PC 桥接时，走桥接通道
4. 用户流程：在 Windows 登录 PC 微信 → 启动桥接服务 → 机擎即可发消息
---
## 四、官方合规方案：企业微信
| 项目 | 说明 |
|------|------|
| **适用** | 仅企业微信，不适用个人微信 |
| **能力** | 会话存档、客户联系、消息推送等 |
| **文档** | https://developer.work.weixin.qq.com/ |
| **限制** | 需企业认证、按员工购买许可 |
若场景是**企业微信**，优先用官方 API，无封号风险。
---
## 五、Android 端方案对比
### 5.1 奥创 vs 更好替代
| 维度 | 奥创 (VivWxjz) | 更好替代 |
|------|----------------|----------|
| ** Root** | 必须 | PC 方案免 Root |
| **封号** | 高（Hook 注入） | PC 方案更低 |
| **登录** | 手机微信 | PC 扫码更简单 |
| **功能** | 消息/联系人/朋友圈 | PC 方案同样完整 |
| **维护** | 微信更新需适配 | wxauto 等相对稳定 |
| **部署** | 每台手机 Root+刷机 | 一台 PC 可管多微信 |
### 5.2 若必须用 Android 手机
| 方案 | 说明 | 推荐 |
|------|------|------|
| **机擎 u2/ADB** | 免 Root，模拟点击 | ✅ 当前方案，保持 |
| **无障碍服务** | 免 Root，同 u2 思路 | ✅ 可作补充 |
| **奥创 Hook** | 需 Root，高封号风险 | ⚠️ 仅内部/合规场景 |
**结论**：Android 端优先保留机擎现有方案；若追求「登录简单 + 发消息稳定」，建议引入 **PC 桥接（WeChatFerry / wxauto）**。
---
## 六、快速选型指引
### 6.1 我要「直接登录微信并发消息」
| 场景 | 推荐方案 | 步骤 |
|------|----------|------|
| 可接受用 PC | **WeChatFerry** 或 **wxauto** | 1. 装 PC 微信 2. `pip install wcferry` 或 `wxauto` 3. 扫码登录 4. 代码发消息 |
| 必须用手机 | **机擎 Agent + u2** | 1. 手机连电脑/USB 2. 启动 Agent 3. 微信需已登录 4. API 发消息 |
| 企业微信 | **企微官方 API** | 1. 企业认证 2. 开通会话存档/客户联系 3. 调用官方接口 |
### 6.2 我要「比奥创更好」
- **更好的定义**：更少 Root、更低封号、更易登录、更稳维护
- **首选**：PC 端 **WeChatFerry** 或 **wxauto**，通过桥接接入机擎
- **次选**：继续用机擎 u2 方案，不做 Hook
- **不推荐**：继续走奥创 Hook，除非有特殊合规场景
---
## 七、实施建议
### 7.1 短期（1–2 周）
1. **验证 WeChatFerry**：在 Windows 上安装，完成登录、发消息、收消息测试
2. **设计 PC 桥接**：定义桥接 HTTP/gRPC 接口，与机擎 `message/send` 等对齐
3. **路由扩展**：在机擎增加 `pc_wechat` 通道，按 `device_id` 路由到桥接
### 7.2 中期（1 个月）
1. 开发并部署 PC 桥接服务
2. 存客宝/前端支持「PC 微信」设备类型
3. 编写部署文档：Windows 环境、微信版本、桥接启动方式
### 7.3 长期
1. 支持多 PC、多微信账号
2. 桥接服务高可用、断线重连
3. 视情况评估 wxauto 作为「不注入」备选通道
---
## 八、资源链接
| 方案 | 链接 |
|------|------|
| WeChatFerry | https://wechatferry.readthedocs.io/ |
| wxauto | https://docs.wxauto.org/ |
| wxMaster | https://github.com/xz-soft/wxMaster |
| 企微开发者 | https://developer.work.weixin.qq.com/ |
| 奥创分析 | 资料/奥创.md、奥创微信控制接口与插件提取复用指南.md |

BIN
资料/抖音客服通信接口文档(完整版)20240422.doc
View File

Binary file not shown.

146
资料/最佳解决路径_个微工作手机统一方案.md
View File

@@ -1,146 +0,0 @@
# 最佳解决路径 — 个微工作手机统一方案
> **结论**：用 **机擎（工作手机SDK）** 作为**唯一**方案，替代奥创，实现私域全功能、后端无感、多平台扩展
> **依据**：资料调研、市场调研、对话内容综合
> **更新**：2026-02-10
---
## 一、唯一推荐方案：机擎
**机擎 = 工作手机SDK v3.0 = 存客宝的 AI 手机控制引擎**
| 维度 | 说明 |
|------|------|
| **本质** | 统一云端中台 + 设备端 Agent + Skill 引擎 |
| **连接** | 设备 WebSocket 主动连云端，天然远程，不依赖 USB |
| **控制** | uiautomator2 + ADB，不 Hook、不注入 |
| ** Root** | 免 Root |
| **封号** | 低风险（模拟真人操作） |
---
## 二、为何选机擎（不选奥创/Frida/其他）
| 需求 | 奥创 | Frida | 其他（wxauto/云手机等） | 机擎 |
|------|------|-------|-------------------------|------|
| 替代奥创手机 | ✅ 同设备 | ✅ | 云手机可，wxauto 仅 PC | ✅ 同设备 |
| 个微全功能 | ✅ | 需自写 | wxauto 仅 PC；GeweChat 仅个微 | ✅ 已有 |
| 企微/Soul/闲鱼/抖音 | ❌ 仅个微 | 需逐一手写 | 无统一架构 | ✅ Skill 架构可扩展 |
| 后端无感运行 | ✅ | 需自建 | 视产品 | ✅ 云端服务，存客宝调 API |
| 简洁可维护 | 绑 007 | 复杂 | 分散 | ✅ 统一 API、Skill 注册表 |
| 免 Root | ❌ | Gadget 可 | 多数可 | ✅ |
| 低封号 | ❌ | ❌ | 视方案 | ✅ |
**结论**：机擎是**唯一**同时满足「手机端、个微、多平台扩展、后端无感、免 Root、低封号」的方案。
---
## 三、实施路径（替换奥创手机）
### 3.1 总体流程
```
卸载奥创 → 安装机擎 Agent → 配置连接 → 存客宝切 API → 扩展企微/Soul
```
### 3.2 具体步骤
| 步骤 | 操作 | 说明 |
|:----:|------|------|
| 1 | 备份奥创设备上的 007 配置与数据 | 若有重要配置可导出 |
| 2 | 卸载奥创组件 | 卸载 AI数智员工、VivWxjz、XESlciw Manager（可选恢复出厂或保留 Root） |
| 3 | 安装机擎 Agent | 将 agent 部署到手机（Python + u2），或打包为简易 Android 服务 |
| 4 | 配置 Agent | server_url=机擎 SDK 地址，device_id=设备编号 |
| 5 | 启动 Agent | 设备主动 WebSocket 连云端，上报能力 |
| 6 | 存客宝/触客宝 切换 API | 由 007 改为调用机擎 `POST /api/v3/message/send` 等 |
| 7 | 验证 | 发消息、拉联系人、朋友圈等 |
| 8 | 扩展 | 按需新增 WeworkSkill、SoulSkill |
### 3.3 后端无感运行
| 层级 | 说明 |
|------|------|
| **云端** | 机擎 SDK 部署在腾讯云/阿里云，7×24 运行 |
| **存客宝** | 调用 `WorkPhoneSDK::sendMessage()` 等，对业务无感 |
| **设备** | Agent 后台常驻，收到指令后执行 u2 操作 |
| **用户** | 业务侧仅调 API，不感知底层实现 |
---
## 四、平台支持与扩展
### 4.1 当前已支持
| 平台 | Skill | 能力 |
|------|-------|------|
| 个微 | wechat | 发消息、好友、群、标签、朋友圈 |
| 抖音 | douyin | 发消息、评论回复 |
| 小红书 | xhs | 发消息 |
| 闲鱼 | xianyu | 发消息 |
### 4.2 扩展计划（按需）
| 平台 | 新增 Skill | 实现方式 |
|------|------------|----------|
| 企微 | wework | 优先走企微官方 API；无 API 时用 u2 |
| Soul | soul | 新建 SoulSkill，u2 模拟操作 |
| 其他 | 按 APP 新建 Skill | 继承 BaseSkill，注册到 SKILL_REGISTRY |
扩展方式：在 `sdk/agent/skills/` 下新建目录，实现 `BaseSkill`，在 `__init__.py` 中注册；unified 路由表增加对应 platform。
---
## 五、与奥创能力对照
| 奥创能力 | 机擎实现 | 状态 |
|----------|----------|------|
| 发消息 | WechatSkill.send_message | ✅ |
| 收消息 | WechatSkill.get_messages（UI 解析） | ✅ |
| 联系人 | WechatSkill.get_contacts | ✅ |
| 好友/群/标签 | 对应 Skill 方法 | ✅ |
| 朋友圈 | WechatSkill.post_moments 等 | ✅ |
| 007 云端 | 机擎 SDK 服务端 | ✅ 替代 |
| 设备管理 | DeviceSvc、WebSocket Hub | ✅ |
| 实时同步 | UI 轮询或按需拉取 | ⚠️ 非 syscall 级，够用 |
| 红包/转账监控 | 暂未实现 | 可选，合规风险高 |
**差异**：机擎为 UI 自动化，非 Hook，操作会有界面反馈；换来的是免 Root、低封号、可扩展多平台。
---
## 六、部署清单
### 6.1 云端（机擎 SDK）
- 部署机擎 SDK（Docker 或直接运行）
- 配置 MongoDB、Redis
- 配置 Nginx + SSL
- 暴露 `https://workphone.xxx.com`
### 6.2 设备（原奥创手机）
- 卸载奥创
- 安装 Python 环境 + uiautomator2（或打包的 Agent）
- 配置 `server_url`、`device_id`
- 启动 Agent，保持 WebSocket 连接
### 6.3 业务侧（存客宝）
- 将 007 API 调用改为机擎 WorkPhoneSDK
- 设备 ID 映射（奥创 device_id → 机擎 device_id）
- 验证消息发送、好友管理、群管理、朋友圈等
---
## 七、总结
| 项目 | 内容 |
|------|------|
| **唯一方案** | 机擎（工作手机SDK v3.0） |
| **替换对象** | 奥创（007 + VivWxjz + AI数智员工） |
| **优势** | 免 Root、低封号、统一 API、可扩展个微/企微/Soul/闲鱼/抖音 |
| **运行方式** | 云端无感、设备 Agent 后台、存客宝调 API |
| **扩展方式** | 新增 Skill，注册到 SKILL_REGISTRY |
**下一步**：按 §3.2 执行替换步骤；企微、Soul 等按需扩展 Skill。

264
资料/机擎复刻Frida与奥创管理注入_实现路径.md
View File

@@ -1,264 +0,0 @@
# 机擎复刻 Frida 与奥创的管理与注入 — 可行性及实现路径
> **目标**：机擎在 SDK 与私域管理上，完全复刻 Frida、奥创的管理形式与注入能力
> **更新**：2026-02-10
---
## 一、结论：可以实现
在机擎现有架构上，通过增加 **Hook 通道**、**模块管理**、**Frida 集成**，可完整复刻 Frida 与奥创的「管理 + 注入」形态，并提取其能力。
| 能力 | 奥创/Frida | 机擎复刻 | 实现方式 |
|------|------------|----------|----------|
| 模块列表与启用 | XESlciw Manager / Frida 脚本 | ✅ 可做 | 新增模块管理 API + 设备端模块注册 |
| Scope 作用域 | 按 APP 指定生效 | ✅ 可做 | 设备能力 `scope: [com.tencent.mm, ...]` |
| Hook 注入 | VivWxjz / Frida attach | ✅ 可做 | 集成 Frida，设备运行 frida-server/Gadget |
| 实时消息同步 | Syscall 拦截 | ✅ 可做 | Frida Hook sendmsg/recvmsg 或 Java 层 |
| 发消息（内部调用） | 调微信内部接口 | ✅ 可做 | Frida 逆向找发送函数并调用 |
| 双通道路由 | — | ✅ 可做 | 设备 `supports_hook` 时走 Hook，否则走 u2 |
| 云端管理 | 007 后台 | ✅ 已有 | 机擎 SDK 服务端 + 存客宝 |
**前提**：设备需 Root（frida-server）或使用 Frida Gadget 内嵌 APK（可免 Root）。
---
## 二、复刻目标：奥创/Frida 的管理与注入形态
### 2.1 奥创管理形态
| 能力 | 说明 | 机擎复刻对应 |
|------|------|--------------|
| 模块列表 | 已安装 Xposed/LSPosed 模块 | 机擎「Hook 模块」列表 |
| Scope 配置 | 为每个模块指定生效 APP（如 com.tencent.mm） | 设备能力 `hook_scopes` |
| 模块启用/禁用 | 开关控制 | API `POST /modules/{id}/enable` |
| 寄生模式 | 卸载 Manager 后框架仍运行 | 可选：框架常驻，Manager 仅配置 |
| 版本校验 | 框架与模块版本匹配 | 设备上报 `hook_framework_version` |
### 2.2 Frida 注入形态
| 能力 | 说明 | 机擎复刻对应 |
|------|------|--------------|
| attach 目标进程 | 指定包名如 com.tencent.mm | 设备执行 `attach(com.tencent.mm)` |
| 脚本注入 | 加载 JS 脚本做 Hook | 云端下发脚本或脚本 ID，设备加载 |
| rpc.exports | 暴露函数给主机调用 | 设备通过 WebSocket 暴露 `script.exports.xxx()` |
| send() 上报 | 脚本内 send 数据到主机 | 设备转发到云端 |
| 热更新 | 随时重载脚本 | 云端下发新脚本，设备 reload |
### 2.3 能力提取（VivWxjz 等效）
| VivWxjz 能力 | 实现方式 | 机擎复刻 |
|--------------|----------|----------|
| 消息实时同步 | Syscall 拦截 recvmsg | Frida Hook 收消息相关 Java/Native |
| 发消息 | 调内部接口或协议 | Frida 逆向发消息函数并调用 |
| 联系人 | Binder/DB | Frida Hook 或读 EnMicroMsg.db |
| 朋友圈 | Hook 相关接口 | Frida Hook 发朋友圈方法 |
---
## 三、实现路径（分阶段）
### 阶段一：架构扩展（约 2 天）
#### 1.1 新增通道与设备能力
| 项 | 说明 |
|----|------|
| **Channel** | 在 `Channel` 枚举中增加 `HOOK` |
| **设备能力** | 上报 `supports_hook: true`、`hook_scopes: ["com.tencent.mm"]`、`frida_version` |
| **路由** | `ChannelRouter.route()` 在设备 `supports_hook` 且 platform 在 scope 内时返回 `Channel.HOOK` |
```python
# unified.py 扩展
class Channel(str, Enum):
OFFICIAL_API = "official_api"
SDK_CONTROL = "sdk_control"
AI_AGENT = "ai_agent"
HOOK = "hook" # 新增
# 路由逻辑
def route(platform, action, device_online, device_caps):
if device_caps.get("supports_hook") and platform in device_caps.get("hook_scopes", []):
return Channel.HOOK
# ... 原有逻辑
```
#### 1.2 模块管理 API（对标 XESlciw Manager）
| API | 方法 | 说明 |
|-----|------|------|
| GET /modules | GET | 模块列表（设备上报 + 云端配置） |
| POST /modules | POST | 注册/上传模块（脚本或 APK） |
| PUT /modules/{id}/scope | PUT | 设置 Scope |
| POST /modules/{id}/enable | POST | 启用 |
| POST /modules/{id}/disable | POST | 禁用 |
| GET /modules/{id}/status | GET | 状态 |
---
### 阶段二：设备端 Frida 集成（约 3–5 天）
#### 2.1 设备端架构
```
设备
├── 机擎 Agent（现有）
├── frida-server 或 Frida Gadget
├── Hook 脚本仓库（云端下发或本地缓存）
└── 脚本加载器（按 scope 注入目标 APP）
```
#### 2.2 设备端新增组件
| 组件 | 职责 |
|------|------|
| **FridaManager** | 启动 frida-server/Gadget，维护连接 |
| **ScriptLoader** | 根据 scope 加载脚本，attach 到目标进程 |
| **HookExecutor** | 执行 `script.exports.send_message()` 等，替代 u2 |
| **EventReporter** | 将脚本 `send()` 的数据转发到云端 WebSocket |
#### 2.3 指令协议扩展
设备收到的 `execute` 增加 `channel` 与 `hook_script_id`：
```json
{
"type": "execute",
"data": {
"channel": "hook",
"script": "wechat",
"action": "send_message",
"params": { "to_id": "xxx", "content": "hello" },
"hook_script_id": "wechat_hook_v1"
}
}
```
设备侧：若 `channel=hook`，则走 Frida 分支，调用对应 Hook 脚本的 `rpc.exports.send_message()`。
---
### 阶段三：Hook 脚本开发（提取 VivWxjz 能力）（约 5–10 天）
#### 3.1 微信 Hook 脚本（Frida JS）
参考 VivWxjz 的 syscall/Java Hook 思路，用 Frida 实现：
| 能力 | Hook 点（示例） | 说明 |
|------|-----------------|------|
| 发消息 | 逆向微信发消息方法 | Java.use 或 NativeFunction |
| 收消息 | Hook 消息写入 DB / 网络收包 | 在回调中 send 到主机 |
| 联系人 | Hook 联系人查询 / 读 DB | 解析后上报 |
| 朋友圈 | Hook 发朋友圈方法 | 调用原实现或内部接口 |
#### 3.2 脚本结构
```javascript
// wechat_hook.js
rpc.exports = {
send_message: function(to_id, content) { /* ... */ },
get_contacts: function(limit) { /* ... */ },
get_messages: function(limit) { /* ... */ }
};
// 收消息时自动 send 到主机
Java.perform(function() {
// Hook 收消息逻辑，在回调里 send(data)
});
```
#### 3.3 脚本存储与下发
- 脚本存于云端（MongoDB/文件/MinIO）
- 设备启动或模块启用时拉取
- 支持版本号，便于热更新
---
### 阶段四：私域管理端（对标 007）— 已有基础
| 功能 | 机擎现状 | 复刻说明 |
|------|----------|----------|
| 设备列表 | DeviceSvc | 已实现 |
| 设备详情 | GET /devices/{id} | 已实现 |
| 发消息 | POST /message/send | 已实现，路由到 Hook 即可 |
| 联系人 | GET /contacts | 已实现 |
| 模块管理 | — | 新增 §3.1 模块 API |
| 实时消息推送 | — | 设备 Hook 上报 → WebSocket → 存客宝 |
| 管理后台 | 存客宝/触客宝 | 已有，可增加模块管理页面 |
---
## 四、整体架构（复刻后）
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 机擎（复刻 Frida/奥创 形态） │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 存客宝 / 私域管理 │
│ │ │
│ │ POST /message/send 等 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 机擎 SDK 服务端 │ │
│ │ • 模块管理 API（对标 XESlciw Manager） │ │
│ │ • 通道路由：官方API / SDK(u2) / Hook / AI Agent │ │
│ │ • 设备管理、指令下发、数据接收 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ WebSocket（execute / response / event） │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 设备端 Agent │ │
│ │ ├── 通道选择：supports_hook ? Hook : u2 │ │
│ │ ├── Hook 通道：FridaManager + ScriptLoader + HookExecutor │ │
│ │ └── u2 通道：现有 Skill 执行 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Frida attach + script.exports │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 微信 / 抖音 / Soul / 闲鱼 等（目标 APP） │ │
│ │ • Frida 脚本注入，Hook 发消息/收消息/联系人 等 │ │
│ │ • rpc.exports 暴露给设备端，设备端再通过 WebSocket 暴露给云端 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
---
## 五、实施优先级
| 优先级 | 任务 | 预估 | 说明 |
|:------:|------|------|------|
| P0 | 架构扩展：Channel.HOOK、设备能力、路由 | 2 天 | 通道与能力基础 |
| P0 | 设备端 Frida 集成：FridaManager、ScriptLoader | 3 天 | 能 attach + 加载脚本 |
| P1 | 微信 Hook 脚本：send_message、get_messages、get_contacts | 5 天 | 提取 VivWxjz 核心能力 |
| P1 | 模块管理 API：列表、Scope、启用/禁用 | 2 天 | 对标 XESlciw Manager |
| P2 | 收消息实时上报 | 2 天 | 脚本 send → 设备 → 云端 |
| P2 | 私域管理前端：模块管理页面 | 2 天 | 可选 |
| P3 | 抖音/Soul/闲鱼 Hook 脚本 | 按需 | 每个 APP 独立脚本 |
---
## 六、约束与风险
| 项 | 说明 |
|----|------|
| **Root** | frida-server 需 Root；Gadget 内嵌可免 Root，但需重打包目标 APK |
| **封号** | Hook 注入有封号风险，需合规使用 |
| **版本适配** | 微信等 APP 更新后，Hook 点可能失效，需维护脚本 |
| **合规** | 仅限自有设备、授权场景，遵守相关法律法规 |
---
## 七、参考资料
| 文档 | 路径 |
|------|------|
| XESlciw 接口与 Hook 手册 | 资料/XESlciw接口与设备Hook开发手册.md |
| 奥创复刻与微信 Hook 拆解 | 资料/奥创工作手机-复刻开发详解.md |
| 奥创 Hook 与 Frida 对比 | 资料/奥创Hook与Frida详细对比及微信互通.md |
| 系统架构 | 开发文档/2、架构/系统架构.md |