docs: 建立工作手机专有名词解释文档

2026-07-29 23:27:43 +08:00
parent 337957adf5
commit 9189cd9d46
4 changed files with 160 additions and 0 deletions
--- a/开发文档/00、简洁入口/02、技术与接口.md
+++ b/开发文档/00、简洁入口/02、技术与接口.md
@@ -21,3 +21,5 @@
 - API新增先改“API全量接口目录”和OpenAPI，不另建“新版接口文档”。
 - 微信动作统一回写“微信全功能矩阵”；批次实测放验收区。
 - 架构变化统一回写“系统架构”；专项图作为附件，不再形成平行总架构。
+
+- [专有名词解释](../2、架构/01-总览/专有名词解释.md)
--- a/开发文档/2、架构/01-总览/专有名词解释.md
+++ b/开发文档/2、架构/01-总览/专有名词解释.md
@@ -0,0 +1,129 @@
+---
+tags:
+  - 工作手机
+  - 架构
+  - 术语
+  - 接口
+  - 微信
+doc-type: 术语解释
+layer: 2、架构/01-总览
+parent: [[系统架构]]
+related:
+  - "[[../../5、接口/03-Hook与微信/微信174动作能力矩阵]]"
+  - "[[../05-规范/微信风控统计与执行台账]]"
+---
+
+# 工作手机专有名词解释
+
+> 本文是开发、产品、测试和运营共同使用的术语表。第一次出现的英文缩写保留英文，后续统一使用本文定义。
+
+## 一、产品与系统
+
+| 名词 | 全称/来源 | 白话解释 | 在本项目中的作用 |
+|---|---|---|---|
+| 工作手机 | Work Phone | 用于统一管理微信和业务动作的手机系统 | 产品主体 |
+| SDK | Software Development Kit，软件开发工具包 | 给其他系统调用的一组代码、接口和工具 | 对外提供工作手机能力 |
+| API | Application Programming Interface，应用程序接口 | 系统之间约定好的调用地址和参数 | 例如发送消息、读取联系人 |
+| BFF | Backend for Frontend，前端专用后端 | 为某个前端或业务端整理数据的后端层 | 连接管理后台和SDK |
+| Agent | 设备代理程序 | 安装在手机上的常驻小程序，负责接收指令 | 连接服务器与手机 |
+| APK | Android Package，安卓安装包 | Android应用的安装文件 | 工作手机设备端安装包 |
+| 控制面 | Control Plane | 管理设备、任务、配置和状态的部分 | 不直接执行微信动作 |
+| 数据面 | Data Plane | 真正执行消息、好友、朋友圈动作的部分 | 通过Agent和Hook执行 |
+| 真源 | Source of Truth | 发生冲突时优先采用的唯一资料 | 需求、接口矩阵、验收证据各有真源 |
+
+## 二、设备与通信
+
+| 名词 | 全称/来源 | 白话解释 | 在本项目中的作用 |
+|---|---|---|---|
+| WS / WebSocket | WebSocket | 服务器和手机之间的长连接 | 默认设备通信通道 |
+| WSS | WebSocket Secure | 加密的WebSocket | 生产环境设备回连通道 |
+| WS-first | WebSocket First | 优先走WebSocket，不自动切换其他通道 | 当前微信控制默认策略 |
+| ADB | Android Debug Bridge | Android调试命令工具 | 仅用于安装、诊断等运维，不作为微信业务通道 |
+| u2 | UIAutomator2 | 通过Android界面控件执行操作的工具 | 相机、系统界面等特殊动作的补充通道 |
+| 无线通道 | Wireless Channel | 不依赖USB线的设备连接方式 | 手机通过局域网/WSS连接服务器 |
+| device_id | Device Identifier | 设备唯一标识 | 每条任务、回执和风控记录绑定设备 |
+| serial | Device Serial | Android设备序列号 | 安装和诊断时识别设备 |
+| 心跳 | Heartbeat | 手机定期告诉服务器“我还在线” | 判断设备在线和连接稳定性 |
+| 设备窗口 | Device Window | 某一时段允许指定任务使用设备 | 防止多个任务同时写入同一微信 |
+
+## 三、Hook与微信执行链路
+
+| 名词 | 全称/来源 | 白话解释 | 在本项目中的作用 |
+|---|---|---|---|
+| Hook | Hook / 钩子 | 在程序运行时拦截或调用目标函数 | 连接微信内部能力 |
+| Frida | Frida Dynamic Instrumentation Toolkit | 运行时注入和调用程序内部函数的工具 | 执行微信内部RPC动作 |
+| Frida RPC | Frida Remote Procedure Call | 通过网络调用手机内Hook函数 | 发送消息、读数据库、发朋友圈 |
+| RPC | Remote Procedure Call，远程过程调用 | 像调用本地函数一样调用远程函数 | API到手机内部函数的桥梁 |
+| Hook脚本 | Hook Script | 注入微信进程的JavaScript脚本 | 暴露`getProfile`、`sendMessage`等动作 |
+| Hook附着 | Hook Attach | Hook脚本已经连接到微信进程 | 写接口执行前的必要条件 |
+| Hook镜像 | Hook Mirror | 同一Hook脚本在不同目录的运行副本 | Agent、APK assets和发布包需保持一致 |
+| rpc.exports | RPC Exports | Hook脚本对外暴露的函数列表 | Action映射的最终执行对象 |
+| Action | 动作名 | 产品层统一使用的业务动作名称 | 如`send_message`、`get_contacts` |
+| ACTION_TO_RPC | Action-to-RPC映射 | 把业务动作映射到Hook函数 | 如`send_message → sendMessage` |
+| companion | Companion Module | 需要设备端辅助模块才能执行的动作 | 无模块时返回能力不可用 |
+| capability | Capability | 某个设备或通道具备的能力 | 判断动作是否可执行 |
+
+## 四、接口请求与回执
+
+| 名词 | 全称/来源 | 白话解释 | 在本项目中的作用 |
+|---|---|---|---|
+| request | 请求 | 调用接口时提交的参数 | 包含设备、动作和业务数据 |
+| response | 响应 | 接口返回给调用方的结果 | 包含状态、数据和证据 |
+| trace_id | Trace Identifier | 一次请求的全链路追踪编号 | 串起API、Agent、Hook和回读 |
+| idempotency_key | 幂等键 | 防止同一请求被重复执行的唯一键 | 重试时复用，同键不同参数拒绝 |
+| dry_run | 演练模式 | 只检查参数和门禁，不执行真实写入 | 批量任务和资金动作的第一步 |
+| confirm | 确认标记 | 表示调用方确认执行真实写入 | 与`dry_run=false`一起打开写入门 |
+| raw_rpc_receipt | 原始RPC回执 | Hook函数返回的原始结果 | 防止中间层改写真实失败 |
+| readback | 业务回读 | 写入后重新读取微信数据验证结果 | 判断是否真正成功 |
+| verified | 已验证 | 回读结果与请求目标一致 | 写接口成功的必要条件 |
+| channel_used | 实际通道 | 本次请求真正使用的通信路径 | 例如`websocket`、`frida_rpc` |
+| error_code | 错误码 | 机器可识别的失败原因 | 例如`device_offline`、`rate_limited` |
+| retry_after_seconds | 建议重试秒数 | 告诉调用方多久后再试 | 频控和冷却任务续跑依据 |
+| HTTP | Hypertext Transfer Protocol | 浏览器和服务器常用的请求协议 | API状态码和接口通信基础 |
+| JSON | JavaScript Object Notation | 接口常用的数据格式 | 保存请求、回执和验收证据 |
+
+## 五、风控与验收
+
+| 名词 | 全称/来源 | 白话解释 | 在本项目中的作用 |
+|---|---|---|---|
+| 风控 | Risk Control | 识别高风险动作并限制执行 | 降低频控、封禁和误操作风险 |
+| RiskSentinel | Risk Sentinel | 风险哨兵 | 统计设备动作量、连续失败和冷却状态 |
+| anti_ban_guard | Anti-ban Guard | 服务端动作前风控守卫 | 在写操作前判断是否允许继续 |
+| rate_limiter | Rate Limiter | 限流器 | 控制动作频率、间隔和冷却 |
+| batch_pacing | Batch Pacing | 批量节奏控制 | 给批量动作增加间隔、抖动和停批规则 |
+| jitter | 抖动 | 在基础等待时间上增加小范围随机变化 | 避免固定节奏 |
+| silent_throttle | 静默限流 | 表面成功但业务没有真正送达或落库 | 识别假成功并立即停批 |
+| stop_on_risk | 遇险停批 | 发现风险后停止剩余批次 | 批量接口默认开启 |
+| cooldown | 冷却 | 风险触发后暂停一段时间 | 防止连续重试扩大风险 |
+| 四证据 | Four Evidence | HTTP结果、追踪号、原始RPC、业务回读 | 写入成功的完整证明链 |
+| 真机验收 | Real-device Acceptance | 在真实手机和真实微信上验证 | 区分代码通过和实际可用 |
+| P0/P1/P2 | Priority 0/1/2 | 验收优先级 | P0是主链，P1是重要扩展，P2是增强项 |
+| PASS | 通过 | 满足验收标准 | 必须有对应证据 |
+| BLOCKED | 被环境阻断 | 条件不足暂时无法完成验证 | 例如设备离线、Hook未附着 |
+| capability_unavailable | 能力不可用 | 当前通道或模块没有该能力 | 不代表接口代码一定不存在 |
+
+## 六、数据库与文件
+
+| 名词 | 全称/来源 | 白话解释 | 在本项目中的作用 |
+|---|---|---|---|
+| MongoDB | Mongo Database | 文档型数据库 | 存控制面、任务和统计数据 |
+| WCDB | WeChat Database | 微信使用的数据库封装 | 读取消息、联系人等业务数据 |
+| SQLite | SQLite Database | 轻量级关系数据库 | 微信底层数据存储基础之一 |
+| rcontact | 微信联系人表 | 微信联系人数据表 | 判断好友关系和读取备注 |
+| SNS | Social Networking Service | 微信朋友圈数据域 | 朋友圈发布、读取和回读 |
+| IIFE | Immediately Invoked Function Expression | 打包后立即执行的JavaScript形式 | Hook发布和Android assets使用 |
+| SHA-256 | Secure Hash Algorithm 256 | 文件内容指纹 | 检查Hook三份副本是否一致 |
+
+## 七、统一写法
+
+- 第一次出现写：`软件开发工具包（SDK）`，后续写`SDK`。
+- “Hook没好”统一写为：`Hook未附着`或`hook_unavailable`。
+- “接口成功”只有在`verified=true`和业务回读通过时成立。
+- “代码有了”不等于“真机可用”；必须区分`已映射`、`契约通过`、`历史真机通过`、`当前可调用`。
+- 所有新增专有名词先补本文，再进入需求、接口或验收文档。
+
+## 八、更新记录
+
+| 日期 | 更新内容 |
+|---|---|
+| 2026-07-29 | 建立工作手机SDK、Hook、Frida、RPC、风控、验收和数据字段统一术语表。 |
--- a/开发文档/README.md
+++ b/开发文档/README.md
@@ -22,6 +22,7 @@

 - [工作手机完整使用手册](9、手册/工作手机·五图总览与使用手册.md)
 - [系统架构](2、架构/01-总览/系统架构.md)
+- [专有名词解释](2、架构/01-总览/专有名词解释.md)
 - [统一API目录](5、接口/01-规范与统一层/工作手机API全量接口目录.md)
 - [全产品设计与原型](3、原型/工作手机全产品设计_20260722/产品总方案.md)
 - [可点击高保真原型](3、原型/工作手机全产品设计_20260722/可浏览高保真原型.html)
--- a/开发文档/功能迭代记录.md
+++ b/开发文档/功能迭代记录.md
@@ -1,5 +1,12 @@
 # 工作手机功能迭代记录

+## 2026-07-29｜建立工作手机专有名词解释文档
+
+- 新建 `开发文档/2、架构/01-总览/专有名词解释.md`。
+- 覆盖产品系统、设备通信、Hook/Frida、接口回执、风控验收、数据库文件六类术语。
+- 统一 SDK、Hook、RPC、Agent、trace_id、readback、RiskSentinel 等词的写法和判定口径。
+
+
 ## 2026-07-29｜微信风控统一统计台账

 - 新建 `开发文档/2、架构/05-规范/微信风控统计与执行台账.md`，作为微信风控唯一统计入口。
@@ -1572,3 +1579,24 @@ flowchart LR
 - 通过单好友改名接口将“爱赛车的阿猫”备注改为`阿猫｜估值36.09`。
 - Frida写入成功，独立好友详情接口回读一致。
 - 证据：`开发文档/5、接口/03-Hook与微信/20260729_阿猫好友备注命令行实测.md`。
+
+## 2026-07-29｜手机工作台显示当前微信账号与好友数
+
+- **目标**：工作手机首页除“微信正在运行”外，明确显示当前挂载微信号、微信昵称和真实好友总数。
+- **界面**：`fragment_dashboard.xml` 新增“核心数据 · 当前微信”卡片，分别展示当前微信号、昵称、好友人数和数据来源状态。
+- **数据链路**：`DashboardFragment` 通过手机内 `AgentEngine.executeLocal` 调用 `get_profile` 与 `get_contacts`，固定走微信 Frida RPC；好友数读取数据库回执中的 `total_count`。
+- **性能**：账号数据独立30秒轮询，不跟随设备状态秒级刷新重复查询微信数据库；页面暂停时自动取消。
+- **通道收口**：`get_contacts` 加入严格 Frida 动作集合，Hook未挂载时明确显示等待状态，不转入无障碍页面操作。
+- **构建验证**：`./gradlew :app:assembleDebug` 成功；APK SHA-256：`fdd126556f2c552212040e6ade557ee60e2e2c341cb0e9a5335d1aca742843e2`。
+- **APK**：`sdk/android-app/app/build/outputs/apk/debug/app-debug.apk`。
+- **待验收**：通过下一次WSS安装窗口更新手机后，收集首页截图、当前wxid、好友总数和Hook回读四项一致证据。
+
+## 2026-07-29｜工作台微信核心数据真实回读修复与真机闭环
+
+- **现象**：手机真实运行页面只显示“微信 8.0.69 / 运行正常”，没有显示微信号和好友数。
+- **根因**：实际首页由 `MainActivity + WebView` 渲染，不是 `DashboardFragment`；同时原生桥接只接受外层 `channel_used=server/frida`，实际回执为外层 `frida_rpc`、内层 `_channel_used=server/frida`，导致真实资料被误判失败并清空。
+- **修复**：兼容两层Frida通道；只有真实 `get_profile/get_contacts` 成功才保存账号；空微信号清除旧值；好友数允许真实0；版本优先使用Frida回读、失败回退手机PackageManager；Web工作台同时显示昵称、微信号、版本和好友数。
+- **真实回读**：昵称`卡皮巴拉`；微信号`wxid_1ffyhf9fjw7y22`；好友总数`3`；微信版本`8.0.69`；Hook PID `14217`；通道`frida_rpc`；好友数据标记`实时回读`。
+- **无线安装**：设备`3c2d803e58f2c30a744234484c4e393e`；安装时间`2026-07-29 21:13:08`；新Agent PID `7705`；WSS自动回连成功。
+- **APK**：`sdk/android-app/app/build/outputs/apk/debug/app-debug.apk`；SHA-256 `e3cb9cd4c137dbaa9992c43ac98158d041c49c4d176a867a3992dbedcf331c73`。
+- **真机截图**：`开发文档/8、部署/05-测试验收/20260729_工作台微信核心数据_真机截图.png`。