Skip to content

Commit e4a3020

Browse files
author
Ven
committed
docs: 添加开发文档体系
1 parent 6597b1e commit e4a3020

File tree

10 files changed

+473
-0
lines changed

10 files changed

+473
-0
lines changed

‎docs/development/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# 开发文档
2+
3+
本目录为 Assists 项目的**开发文档**，面向开源贡献者与集成开发者。
4+
5+
## 文档结构
6+
7+
| 文档 | 说明 |
8+
|------|------|
9+
| [快速开始](getting-started.md) | 环境准备与首次运行 |
10+
| [安装指南](installation.md) | 依赖与构建安装 |
11+
| [配置说明](configuration.md) | 运行时与构建配置 |
12+
| [架构设计](architecture.md) | 模块划分与设计说明 |
13+
| [API 参考](api/README.md) | 接口与能力说明 |
14+
| [开发指南](guides/README.md) | 专题教程与最佳实践 |
15+
| [贡献指南](contributing.md) | 如何参与贡献 |
16+
| [更新日志](changelog.md) | 版本变更记录 |
17+
| [常见问题](faq.md) | FAQ |
18+
19+
## 相关资源
20+
21+
- 能力列表：根目录 [WEB_CAPABILITIES.md](../WEB_CAPABILITIES.md)、[NATIVE_CAPABILITIES.md](../NATIVE_CAPABILITIES.md)
22+
- 付费/商业扩展文档：[付费开发文档](../paid-development/README.md)

‎docs/development/api/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# API 参考
2+
3+
本目录为 Assists 的 **API 参考** 索引，便于按模块或能力查阅。
4+
5+
## 文档索引
6+
7+
- **Web 能力**：根目录 [WEB_CAPABILITIES.md](../../WEB_CAPABILITIES.md) — 通过 `assistsx` / `assistsxAsync` 等调用的方法列表与约定
8+
- **Native 能力**：根目录 [NATIVE_CAPABILITIES.md](../../NATIVE_CAPABILITIES.md) — 原生侧接口说明（如有）
9+
10+
## 约定说明
11+
12+
- **请求**：通常为 JSON，包含 `method`、`arguments`、`node`/`nodes`、`callbackId` 等
13+
- **响应**：JSON 包含 `code`（0 表示成功）、`data`、`message`、`callbackId`
14+
- **节点**：多数接口支持在根节点或指定 `node`（含 `nodeId`）上操作
15+
16+
后续可按子模块在此目录下新增独立 API 文档（如 `web-bridge.md`、`node-api.md` 等）。

‎docs/development/architecture.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# 架构设计
2+
3+
本文档描述 Assists 自动化框架的整体架构、模块划分与依赖关系。该框架基于 **Android 无障碍服务**封装，提供节点查找、操作、浮窗、截图、输入法、Web 桥接等能力，并围绕 Web 自动化与日志分析形成完整开发生态。
4+
5+
---
6+
7+
## 一、概述
8+
9+
Assists 是一套**基于 Android 无障碍服务**封装的自动化框架，目标是通过统一的 API 与多种增强能力，支持在设备上完成 UI 自动化、脚本控制与 Web 端动态编排。核心特点包括：
10+
11+
- **基础层**：封装系统无障碍服务与能力增强 API，提供浮窗管理（添加/删除/显示/隐藏/缩放/移动）
12+
- **增强层**：自定义输入法、屏幕截图、OpenCV 图像识别，弥补无障碍在部分场景的不足
13+
- **桥接层**：WebView + JS 通道，使 Web 端可直接调用 Native 能力，实现「写 Web 即写自动化」
14+
- **应用层**：Web 自动化运行平台 AssistsX、assistsx-js 步骤器、日志分析系统（**仅限付费用户使用**），支撑开发调试与问题定位
15+
16+
---
17+
18+
## 二、模块总览与依赖关系
19+
20+
### 2.1 模块依赖图（Mermaid）
21+
22+
```mermaid
23+
flowchart TB
24+
subgraph 应用与生态
25+
AssistsX[AssistsX 应用<br/>Web 自动化运行平台 + 节点分析服务]
26+
AssistsX_JS[assistsx-js<br/>Web 端 API + 步骤器]
27+
LogSystem[日志分析系统<br/>⚠️ 仅限付费用户]
28+
end
29+
30+
subgraph 桥接层
31+
AssistsWeb[assists-web<br/>WebView 原生↔JS 通道]
32+
end
33+
34+
subgraph 增强层
35+
AssistsIme[assists-ime<br/>自定义输入法]
36+
AssistsMp[assists-mp<br/>屏幕录制/截图]
37+
AssistsOpcv[assists-opcv<br/>OpenCV 图像识别]
38+
end
39+
40+
subgraph 基础层
41+
Assists[assists<br/>无障碍 + 浮窗 + API]
42+
end
43+
44+
AssistsX --> AssistsWeb
45+
AssistsX_JS -.->|调用| AssistsWeb
46+
AssistsWeb --> Assists
47+
AssistsWeb --> AssistsMp
48+
AssistsWeb --> AssistsIme
49+
AssistsMp --> Assists
50+
AssistsOpcv --> Assists
51+
AssistsIme --> Assists
52+
LogSystem -.->|提交日志/节点| Assists
53+
```
54+
55+
### 2.2 模块一览表
56+
57+
| 模块 | 类型 | 职责 | 依赖 |
58+
|------|------|------|------|
59+
| **assists** | Library | 无障碍服务封装、能力增强 API、浮窗管理 | 无（基础） |
60+
| **assists-ime** | Library | 自定义输入法，用于「仅输入法可触发搜索」等场景 | assists |
61+
| **assists-mp** | Library | 屏幕录制与截图，整屏/节点截图，弥补无障碍无法直接截图的场景 | assists |
62+
| **assists-opcv** | Library | OpenCV 封装，当前以模板匹配做屏幕识别增强 | assists |
63+
| **assists-web** | Library | WebView 桥接，原生与 JS 双向通道，暴露 assists 能力给 Web | assists, assists-mp, assists-ime |
64+
| **AssistsX** | App | Web 自动化运行平台，安装于手机，开发者专注 Web 开发自动化；支持节点分析工具（局域网浏览器访问，分析当前页面节点） | assists-web（及底层库） |
65+
| **assistsx-js** | JS 库 | Web 端 API 封装 + 步骤器，便于开发与维护大型自动化 | 通过 assists-web 注入的接口调用 |
66+
| **日志分析系统** | 系统能力 | 测试提交日志与页面节点信息，供开发分析、精准定位多设备/多界面 Bug。**⚠️ 仅限付费用户使用** | 与 assists 能力配合 |
67+
68+
---
69+
70+
## 三、各模块说明
71+
72+
### 3.1 assists（基础框架）
73+
74+
- **定位**：整个框架的基础库，所有增强与桥接均基于此构建。
75+
- **核心能力**：
76+
- **无障碍服务封装**：连接系统 AccessibilityService，提供节点树获取、查找（按 id/text/class 等）、点击、长按、输入、滚动等标准能力。
77+
- **能力增强 API**：在系统无障碍之上做封装与扩展，便于上层统一调用。
78+
- **浮窗管理**：浮窗的添加、删除、显示、隐藏，以及浮窗的**缩放、移动**，可快速实现悬浮控制面板、小窗等 UI。
79+
- **依赖**：仅依赖 Android SDK 与通用工具库，不依赖其他 Assists 子模块。
80+
- **发布**：Maven 产物为 `assists-base`（如 `com.github.ven-coder:assists:assists-base`）。
81+
82+
### 3.2 assists-ime（自定义输入法）
83+
84+
- **定位**：为 assists 提供输入法维度的增强，主要解决「页面无搜索按钮、仅能通过输入法触发搜索」等场景。
85+
- **主要作用**：在搜索框获得焦点后，通过自定义输入法的「搜索/提交」等动作触发搜索，供 assists 自动化流程调用。
86+
- **依赖**：依赖 **assists**，作为 assists 的扩展能力被使用；**assists-web** 也依赖 assists-ime，以便在 Web 自动化中调用该能力。
87+
88+
### 3.3 assists-mp（屏幕录制与截图）
89+
90+
- **定位**：屏幕内容截图与录制库，用于增强 assists 在「图像」维度的能力。
91+
- **核心能力**：
92+
- **整屏截图**：对整个屏幕进行截图，弥补无障碍服务无法直接截取屏幕画面的限制。
93+
- **指定节点区域截图**：结合 assists 的节点信息（如 bounds），对指定控件区域截图，便于做局部识别或上报。
94+
- **使用场景**：当无障碍无法直接拿到屏幕像素（如部分游戏、视频、安全界面）时，作为补充方案；也可为模板匹配、OCR 等提供图像输入。
95+
- **依赖**：依赖 **assists**；**assists-web** 依赖 assists-mp，从而在 Web 端可调用截图相关 API。
96+
97+
### 3.4 assists-opcv（OpenCV 图像识别）
98+
99+
- **定位**：集成并封装 OpenCV，增强**图片处理与识别**能力，当前主要用作屏幕识别的补充手段。
100+
- **当前实现**：以**模板匹配**为主，在屏幕或截图上做模板匹配，用于辅助定位目标区域，增强 assists 的「找控件/找区域」能力。
101+
- **建议**：更复杂的识别需求（如复杂 OCR、多目标、鲁棒性要求高）建议评估其他方案（如 ML Kit、自研模型等），本库可作为轻量增强与尝试入口。
102+
- **依赖**：依赖 **assists**，与 assists、assists-mp 配合使用（例如对 assists-mp 的截图做模板匹配）。
103+
104+
### 3.5 assists-web（WebView 桥接）
105+
106+
- **定位**：封装 WebView，建立**原生与 JS 的双向通道**，使 Web 页面可直接调用 assists 的无障碍及增强能力，实现「用 Web + JS 写自动化」。
107+
- **核心能力**：
108+
- 向 WebView 注入约定对象，前端通过 JSON 调用指定 method。
109+
- 支持在同一个 App 内加载本地或远程 Web 页面，动态编写、更新自动化逻辑，无需重新发版。
110+
- **依赖**：**assists**（核心）、**assists-mp**（截图）、**assists-ime**（输入法触发搜索等）
111+
- **与 assistsx-js 的关系**：assists-web 提供「能力注入与协议」，assistsx-js 在 Web 端封装成易用 API 并实现步骤器，二者配合完成完整的 Web 自动化开发体验。
112+
113+
---
114+
115+
## 四、Web 自动化生态
116+
117+
### 4.1 assistsx-js（Web 端 API + 步骤器）
118+
119+
- **定位**：面向 Web 自动化开发的 **JavaScript 库**，运行在加载了 assists-web 的 WebView 页面中。
120+
- **作用**：
121+
- **API 封装**：将 assists-web 注入的原始接口封装成更易用的 API，开发时直接调用即可驱动 assists 完成查找、点击、输入等操作。
122+
- **步骤器**：提供步骤编排与维护能力，便于**开发与维护大型自动化程序**（步骤拆分、复用、错误处理等）。
123+
- **使用方式**：在 Web 自动化页面中集成 assistsx-js，通过其 API 调用底层 assists 能力；无需关心底层 JSON 协议细节。
124+
- **推荐**：使用 **Web 实现自动化** 可带来**调试快、动态更新**等优势，适合作为主要自动化开发方式。
125+
126+
### 4.2 AssistsX（Web 自动化运行平台）
127+
128+
- **定位**：基于 **assists-web** 实现的 **Android 应用**，即「Web 自动化运行平台」。
129+
- **作用**：安装在手机上后，开发者只需专注于**使用 Web 技术开发自动化**，无需单独开发、安装自己的 App；AssistsX 负责提供 WebView 环境、注入 assists 能力、加载并执行用户的 Web 自动化页面。
130+
- **节点分析工具**：AssistsX 支持**节点分析服务**能力。开启后，可在**局域网**内通过**浏览器**访问该服务，实时查看与分析当前手机界面上的**页面节点**（节点树、属性等），便于编写或调试自动化脚本时快速定位控件。
131+
- **下载**：[AssistsX](https://www.pgyer.com/SqGaCx8C)（版本等信息以页面为准）。
132+
- **关系**：AssistsX App → 依赖 assists-web → 依赖 assists / assists-mp / assists-ime；Web 端再配合 assistsx-js 使用，形成「手机端运行环境 + Web 端开发与步骤编排」的闭环。
133+
134+
---
135+
136+
## 五、日志分析系统
137+
138+
> **⚠️ 仅限付费用户使用**
139+
> 日志分析系统为付费/商业扩展功能，仅对已获得相应许可的付费用户使用。
140+
141+
- **定位**：面向**测试与开发协作**的支撑能力，用于解决「出现 Bug 时缺少日志与页面节点信息、在不同设备/界面上难以复现与定位」的痛点。
142+
- **主要能力**：
143+
- **测试人员**：可提交**运行日志**与**当前页面的节点信息**（如节点树、控件属性、截图等），便于开发还原现场。
144+
- **开发人员**：基于提交的日志与节点信息分析页面结构，快速精准定位问题，减少「无法复现」「设备差异」带来的排查成本。
145+
- **与框架关系**：与 **assists** 能力配合（如通过 assists 获取节点树、通过 assists-mp 获取截图），可集成在 AssistsX 或自研 App 中，作为自动化测试与问题排查的配套功能。
146+
147+
---
148+
149+
## 六、架构层次与类图（模块级）
150+
151+
以下用 Mermaid 的 `classDiagram` 从「模块/包」视角描述各部分的职责与关系（非具体 Java/Kotlin 类）。
152+
153+
```mermaid
154+
classDiagram
155+
direction TB
156+
class Assists {
157+
+无障碍服务封装
158+
+节点查找/操作 API
159+
+浮窗管理(增删显隐/缩放/移动)
160+
}
161+
162+
class AssistsIme {
163+
+自定义输入法
164+
+触发搜索等动作
165+
}
166+
167+
class AssistsMp {
168+
+整屏截图
169+
+指定节点区域截图
170+
}
171+
172+
class AssistsOpcv {
173+
+OpenCV 封装
174+
+模板匹配(屏幕识别)
175+
}
176+
177+
class AssistsWeb {
178+
+WebView 桥接
179+
+注入 assistsx / assistsxAsync
180+
+原生与 JS 双向通道
181+
}
182+
183+
class AssistsX_JS {
184+
+Web 端 API 封装
185+
+步骤器
186+
}
187+
188+
class AssistsX_App {
189+
+Web 自动化运行平台
190+
+安装即用
191+
+节点分析服务(局域网浏览器访问)
192+
}
193+
194+
class LogSystem {
195+
<<仅限付费用户>>
196+
+提交日志与节点信息
197+
+开发分析/定位 Bug
198+
}
199+
200+
Assists <|-- AssistsIme : 基于
201+
Assists <|-- AssistsMp : 基于
202+
Assists <|-- AssistsOpcv : 基于
203+
AssistsWeb --> Assists : 调用
204+
AssistsWeb --> AssistsMp : 调用
205+
AssistsWeb --> AssistsIme : 调用
206+
AssistsX_JS ..> AssistsWeb : 通过注入接口调用
207+
AssistsX_App --> AssistsWeb : 集成
208+
LogSystem ..> Assists : 使用节点/能力
209+
```
210+
211+
---
212+
213+
## 七、数据流与调用关系简图
214+
215+
```mermaid
216+
flowchart LR
217+
subgraph Web
218+
JS[assistsx-js / 自定义 JS]
219+
end
220+
221+
subgraph App
222+
WV[WebView + assists-web]
223+
AS[assists]
224+
IM[assists-ime]
225+
MP[assists-mp]
226+
OC[assists-opcv]
227+
end
228+
229+
JS -->|JSON 调用| WV
230+
WV -->|节点/操作| AS
231+
WV -->|截图| MP
232+
WV -->|输入法搜索| IM
233+
AS -->|截图区域/节点| MP
234+
OC -->|图像识别| AS
235+
AS -->|无障碍| System[系统无障碍服务]
236+
```

‎docs/development/changelog.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# 更新日志
2+
3+
本文档记录 Assists 各版本的变更，格式参考 [Keep a Changelog](https://keepachangelog.com/)。
4+
5+
## [Unreleased]
6+
7+
### Added
8+
9+
- （待发布的新增内容）
10+
11+
### Changed
12+
13+
- （待发布的变更）
14+
15+
### Fixed
16+
17+
- （待发布的修复）
18+
19+
### Removed
20+
21+
- （待发布的移除项）
22+
23+
---
24+
25+
## 版本说明
26+
27+
- **Added**：新功能
28+
- **Changed**：行为或 API 变更
29+
- **Fixed**：Bug 修复
30+
- **Removed**：移除的功能或废弃项
31+
- **Security**：安全相关更新（如有）
32+
33+
版本号与日期在发布时填写。

‎docs/development/configuration.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# 配置说明
2+
3+
本文档描述 Assists 的构建与运行时配置方式。
4+
5+
## 构建配置
6+
7+
- **Gradle**：根目录 `build.gradle`、`settings.gradle`，各模块 `build.gradle`
8+
- **局部配置**：`local.properties`（SDK 路径等，不提交版本库）
9+
- **环境变量**：如需通过环境变量控制构建，可在 `build.gradle` 中读取 `System.getenv()`
10+
11+
## 运行时配置
12+
13+
- 应用级配置：根据项目实际使用方式（如 `BuildConfig`、配置文件、远程配置）在对应模块中维护
14+
- 权限与组件：见 `AndroidManifest.xml` 及各模块说明
15+
16+
## 扩展与定制
17+
18+
若项目支持通过配置文件或 BuildConfig 开关功能，可在此补充具体字段与含义。

‎docs/development/contributing.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# 贡献指南
2+
3+
感谢你对 Assists 的关注与贡献。本文档说明如何参与开发与提交流程。
4+
5+
## 行为准则
6+
7+
- 尊重他人，理性讨论
8+
- 贡献代码与文档需符合项目现有风格与规范
9+
10+
## 如何贡献
11+
12+
1. **Fork 并克隆**本仓库，在本地创建分支（如 `feature/xxx`、`fix/xxx`）
13+
2. **开发与自测**：确保通过现有测试，必要时补充用例
14+
3. **文档**：若新增或变更对外能力，请同步更新 [WEB_CAPABILITIES](../../WEB_CAPABILITIES.md) 或相关文档
15+
4. **提交**：Commit 信息清晰（建议中文，如：`feat: 添加 xxx 能力`），然后发起 Pull Request
16+
5. **Review**：维护者会进行代码与文档审查，根据反馈修改后再合并
17+
18+
## 代码与文档规范
19+
20+
- 代码注释使用中文
21+
- 对外字符串（如日志、错误信息）可保持英文，便于排查
22+
- 新增 API 或配置请在对应文档中说明用途与示例
23+
24+
## 问题与建议
25+
26+
- Bug 与功能建议请通过 Issue 提交，尽量提供复现步骤与环境信息
27+
- 安全相关问题请通过私下渠道联系维护者

‎docs/development/faq.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# 常见问题
2+
3+
本文档汇总开发与使用过程中的常见问题与解决办法。
4+
5+
## 构建与环境
6+
7+
**Q：Gradle 同步失败或依赖下载超时？**
8+
A：检查网络与代理，必要时配置 Gradle/ Maven 镜像；确认 JDK 与 Android SDK 版本符合 [安装指南](installation.md)。
9+
10+
**Q：编译报错找不到 SDK 或 NDK？**
11+
A：在 `local.properties` 中配置 `sdk.dir`（及 `ndk.dir` 如需要），或使用 Android Studio 的 SDK Manager 安装对应组件。
12+
13+
## 运行与调试
14+
15+
**Q：WebView 中调用 `assistsx` 无响应？**
16+
A：确认 WebView 已注入接口、页面已加载完成，以及请求 JSON 格式符合 [WEB_CAPABILITIES](../../WEB_CAPABILITIES.md) 中的约定；可查看 Logcat 中相关 TAG 的日志。
17+
18+
**Q：节点查找返回空或报错？**
19+
A：确认无障碍/所需权限已开启，当前界面已有对应节点，且传入的 `filterText`/`filterDes`/`filterClass` 等条件与真实节点一致；注意部分厂商对无障碍或节点信息的限制。
20+
21+
## 文档与 API
22+
23+
**Q：能力列表在哪里？**
24+
A：Web 端能力见 [WEB_CAPABILITIES.md](../../WEB_CAPABILITIES.md)，Native 能力见 [NATIVE_CAPABILITIES.md](../../NATIVE_CAPABILITIES.md)；开发文档入口为 [开发文档 README](README.md)。
25+
26+
**Q：如何参与贡献？**
27+
A：请阅读 [贡献指南](contributing.md)，按分支、开发、测试、文档、PR 流程参与。
28+
29+
---
30+
31+
如有未覆盖的问题，欢迎提 Issue 或补充到本文档。

0 commit comments

Comments
 (0)