# AScript-Framework

**Repository Path**: wzos/ascript-framework

## Basic Information

- **Project Name**: AScript-Framework
- **Description**: 基于AScript的插件，快速中文精简编程脚本的框架，小白不懂编程也可以快速上手。本框架专为简化脚本编写而设计，提供了一系列易用的图文识别和设备控制功能。兼容（Android & iOS）
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AScript 中文简易框架

面向挂机自动化的精简 Python 框架：**图文识别 + 链式动作与稳态判据 + 生命周期引擎 + 任务调度 + 设备/应用控制**，同时支持 **Android & iOS**。用极为精简的中文 API，把「识别—点击—等待画面落定—再识别」这类易卡、易误判的循环，收敛成一行链式表达。

## 关于 AScript（运行环境）

本框架运行在 **AScript** 之上。AScript 是一款 Android/iOS 端的自动化脚本引擎（类似按键精灵 / Auto.js），提供截图、OCR、找图找色、点击滑动、Shell 等底层能力，并通过 Python SDK `ascript` 对外暴露。

因此本框架**不是可独立 pip 安装的库**，而是**基于 `ascript` 的设备端插件**：它在原生 API 之上收敛出更高阶的中文链式接口，并补齐稳态判据、生命周期托管、定时熄屏挂机等实战能力。

- **运行前提**：在设备上安装 AScript APP 并编写/运行脚本，本框架作为其插件加载。
- **依赖**：运行期依赖设备端 `ascript` SDK（无需 `pip install`）。
- **权限**：物理熄屏功能需 Shizuku / ADB shell 权限。
- **跨平台**：Android 与 iOS 均支持，`仅安卓` 标注的能力在 iOS 自动跳过并优雅降级。

## 加载方式

**作为 AScript 插件（推荐，经插件库分发）**
```python
from ascript.android import plug
plug.load("AScript中文简易框架:1.0")
from AScript中文简易框架 import *      # 一次性引入全部对外 API
```

**作为源码（clone 本仓库后直接引用）**
```python
from ascript_framework.工具封装 import 找字, 找图, 点, 等, 自动化引擎
```
> `工具封装.py` 是唯一对外出口，业务只应从它导入。

## 3 分钟上手

```python
# 等到「开始游戏」出现 → 点击 → 确认它消失（即真正进入），全程链式
if 找字("开始游戏").等点消():
    等(2)
    找图("res/img/结算.png").等显().点()

# 点进去但不关心元素是否消失、只关心「页面变没变」（整页跳转场景）
找字("下一步").等点变()

# 读取屏幕上的数字（如体力值）
体力 = 找字("体力").取数()
```

## 核心概念

1. **识别入口 → 链对象**：`找字(文本, 区域)`、`找图(模板, 区域)` 各识别一次，返回 `文字链` / `图片链`。链对象可直接 `if` 判断是否命中。
2. **链式动作**：链上可续接 `.等显()` `.点()` `.滑动()` `.等()`，命中才执行、未命中自动跳过，无需层层 `if`。
3. **稳态判据（本框架的关键）**：以「区域帧差 + 画面归于静止」为核心，避免动画/回弹/转场导致的误点与漏判：
   - `等消()`：点击后等目标真正消失（静止后比对基准；静止不了则按区域重识别定论）。
   - `点变()`：点击后等判据区发生变化（确认点击生效，适合整页跳转）。
   - 复合动作 `等点消` / `等点变` / `等点`：把「等到出现」与「点击 + 落定判断」一步串起，内置最多 2 次点击重试。
4. **生命周期引擎**：`自动化引擎` 统一托管「定时唤醒或立即执行 → 准备设备环境（分辨率/熄屏/常亮） → 打开应用 → 执行业务 → 异常捕获 → 统一收尾还原」，业务只写任务函数。
5. **集中配置**：阈值、置信度、时长、稳态超时、缓冲节拍等全部收敛于 `默认配置`，可按项目覆盖。

## API 清单

### 图文识别
| 函数 | 说明 |
|---|---|
| `截图一帧(区域=None)` | 全屏或区域截图（区域直采更快） |
| `裁剪图片(截屏, 区域)` | 对已有帧局部裁剪复用 |
| `计算截图特征(截屏)` | 图像哈希，极速判断画面是否变化 |
| `比色(颜色特征, 相似度=0.9, ...)` | 多点比色，返回是否匹配 |
| `比色多组(颜色列表, ...)` | 多组比色，返回命中组索引（无则 -1） |
| `查找文字(文本="", 区域=None, 置信度=…)` | 单次 OCR，返回结果字典或 None |
| `查找所有文字(区域=None, ...)` | 全量 OCR，返回文字列表 |
| `模板匹配(模板, 区域=None, ...)` | 单模板匹配，返回 (x,y) 或 None |
| `识别图片多模板单结果(模板列表, ...)` | 多模板取首个命中「名称」 |
| `识别图片多模板多结果(模板列表, ...)` | 多模板取全部命中 |
| `Ocr` / `FindImages` | 原生 OCR / 找图类（高级用法直调） |

### 图文动作（链式）
- 入口：`找图(模板, 区域=None, 置信度=…, 缩放范围=…)` → `图片链`；`找字(文本或区域, 区域=None, 置信度=…)` → `文字链`
- 原子动作：`点(坐标, y=None, 时长=None, 抖动=True)`、`滑动(x1,y1,x2,y2,时长)`、`等(秒数)`
- 链方法（图片链/文字链通用）：
  - `等显(超时=None, 识别频率=None)`：等目标出现
  - `.点(...) / .滑动(...) / .等(秒数)`：命中才执行
  - `等消(变化超时=None)`：等目标消失（返回可判真伪的 `等消结果`）
  - `等点(...) / 点消(...) / 等点消(...) / 点变(判据区=None, 变化超时=None) / 等点变(...)`：复合动作，支持 `if` 与链式续接
  - `命中坐标`：命中元素坐标（文字为全屏绝对中心，图片为识别帧局部坐标）
  - `取数()`（文字链）：从识别文本抽取纯数字，无则 None

### 系统应用
| 函数 | 说明 |
|---|---|
| `获取资源(路径)` / `R` | 取图片等资源 |
| `获取工程名()` | 当前工程名 |
| `打开应用(包名, 超时时间=5)` | 安卓先校验包名已安装（未安装直接失败），再启动并轮询前台校验，最多重试 3 次，返回是否成功 |
| `停止应用(包名)` | 关闭应用 |
| `数据缓存.保存数据/读取数据/清除数据` | 键值持久化（跨重启） |
| `退出脚本(提示)` / `重启脚本(延迟毫秒)` | 脚本生命周期 |
| `定时执行(执行时间, 任务标识)` | 分段 reboot + 补执行窗口到点调度；同一目标窗口内补跑次数受 `补跑上限` 限制 |
| `关闭定时自动重启()` | 任务结束关闭异常自动重启 |

### 系统设备（多数为 `仅安卓`，iOS 自动跳过）
`唤醒屏幕 / 关闭屏幕 / 按电源键 / 按主页键 / 按返回键`｜`获取亮度 / 设置亮度`｜`获取音量 / 设置音量`｜`启动模拟息屏(透明度) / 取消模拟息屏(画板)`｜`隐藏悬浮球 / 显示悬浮球`｜`开启熄屏() / 熄屏还原()`（物理断显挂机，需 Shizuku）｜`保持屏幕常亮 / 取消屏幕常亮`｜`获取屏幕信息 / 修改分辨率(宽,高,dpi)`｜`播报语音 / 弹出吐司 / 弹出提示 / 弹窗确认`｜`执行Shell(命令)`｜`剪切板写入文本(文本)`

### 脚本引擎
```python
自动化引擎(任务名称)\
    .配置应用(包名)\
    .配置定时(True, (9, 30))\        # 单点或 [(时,分), ...]
    # .配置立即执行()\               # 二选一：不排定时，准备环境后跑一轮即收尾退出
    # .配置失败重跑(1)\              # 任务异常自动重启重跑次数（默认关闭）
    .配置分辨率(宽, 高, dpi, 原始=…)\ # 运行分辨率，结束自动还原
    .挂载主任务(任务函数)\
    # .挂载收尾任务(收尾函数, 名称="收尾任务", 就地重试=1)\   # 主任务正常结束后同进程跑的附加段，收尾函数入参=主任务返回值
    .启动()
退出引擎(提示)                        # 业务侧主动触发统一收尾
```

立即执行模式不进入调度循环、不写定时缓存，退出收尾时额外关闭宿主自动重跑（`auto_run` / `stop_re_run`），适合调试单批：进程结束后不会被复活再跑一轮。

失败重跑（`配置失败重跑`）：任务抛出异常时（`退出引擎` 与分辨率重启除外），引擎按上限计数（同任务 2 小时内），未超限写“因更新重启”标记并 3 秒后重启重跑；超限则放弃本批（定时批次标记完成，避免窗口补跑）。

收尾任务（`挂载收尾任务`）：重跑单位与主任务不同——主任务重跑是**进程级**（重启脚本后从头再跑），收尾任务只在**同进程内就地重调本段**：返回 False（本段自判未完成且零副作用）才重试，段内抛异常则位置不明、可能已执行过半，只留证放弃不重试。两者都不写失败重跑计数、不重启脚本、不还原定时环境；达上限只打 `×`（由错误取证自动整屏留证）后放弃本段，主批次仍按正常完成收尾。只捕 `Exception`，`退出引擎` 等主动退出照常穿透。收尾函数的入参即主任务的返回值（同进程原样传递，供收尾段消费批次判定，不必走数据缓存落盘）；收尾函数必须声明一个形参接收它，用不上也得占位。适用于“失败不值得整批重来”的收尾工作（如微信小程序领取）；不挂载时行为与旧版一致。

引擎不再直接干预悬浮球： hide 已收口到 `打开应用()` 的成功分支（打印启动成功后、返回前），拉起应用会连带把球复位显形，因此启动即即时摁回，业务侧无需散落调用。隐藏只对当前进程生效，APP 重启后仍会复位显形（原生 `FloatWindow` 仅 `hide`/`show`/`add_menu`，无永久关闭接口，也无尺寸参数可调小；实机验证 `dim` 全透明虽可隐形，但 APP 启动即按默认参数复位、难以保持）。

### 任务调度器
最小堆定时调度，支持「到点执行」与「帧差阻断（画面变化才识别、命中才回调）」两种模式：
`添加任务(名称, 执行函数=… , 间隔秒数=…)` 或 `添加任务(名称, 识别区域=…, 识别条件=…, 回调函数=…, 间隔秒数=…)`｜`移除任务 / 暂停任务 / 恢复任务`｜`执行一轮()`｜`启动后台调度(轮询间隔) / 停止后台调度()`

### 配置项（默认值，可按项目覆盖）
`文字识别阈值 / 图像置信度 / 区域缩放范围 / AScript宿主包名 / 抖动半径 / 点击时长 / 触点时长抖动比例 / 启用触点时长抖动 / 抖动时长最小值·最大值 / 滑动时长 / 等待秒数 / 变化超时 / 变化探测间隔 / 点前等待 / 点后等待 / 图片等待时间·识别频率 / 文字等待时间·识别频率 / 设备播报默认消息·次数 / 补跑上限`

## 完整示例：每天定时挂机领资源

```python
from ascript.android import plug
plug.load("AScript中文简易框架:1.0")
from AScript中文简易框架 import *


def 领取任务():
    # 进入活动页
    if not 找字("活动中心").等点():
        退出引擎("未找到入口，本轮跳过")
    # 点击签到并确认按钮消失（真正签到成功）
    找字("签到").等点消()
    # 循环领取多个奖励图标
    for _ in range(3):
        if not 找图("res/img/领取按钮.png").等点消(超时=2):
            break
    播报语音("资源领取完成")


自动化引擎("每日领资源")\
    .配置应用("com.example.game")\
    .配置定时(True, [(9, 30), (21, 0)])\   # 每天 9:30 与 21:00 各一轮
    .挂载主任务(领取任务)\
    .启动()
```

## 目录结构

```
ascript_framework/
├── 工具封装.py          # 唯一对外出口（聚合导出全部 API）
├── 核心组件/
│   ├── 图文识别.py      # OCR / 找图 / 比色 / 帧差特征
│   ├── 图文动作.py      # 链式动作与稳态判据（等显/等消/点消/点变/等点变）
│   ├── 系统设备.py      # 屏幕/物理熄屏/音量/弹窗/分辨率（Android & iOS）
│   ├── 系统应用.py      # 应用启停 / 数据缓存 / 脚本生命周期 / 定时
│   ├── 脚本引擎.py      # 自动化引擎：生命周期与统一收尾
│   ├── 任务调度.py      # 最小堆调度器（到点执行 / 帧差阻断）
│   └── 配置参数.pyi     # 默认配置（阈值 / 时长 / 缓冲节拍）
└── 打包发布/            # AST 合并 → 混淆 → 打包 .asplug 插件
```

## 打包为插件

`打包发布/打包程序.py` 的 `打包插件()` 会把框架合并为单一模块并打成 `发布产物/<插件名>.asplug`（zip），上传到 AScript 插件库后即可被 `plug.load` 加载。

## 许可

MIT License（作者 wangos），详见 [LICENSE](LICENSE)。物理熄屏内嵌 dex 为自研工具（反射公开 AOSP 接口，借鉴 scrcpy 思路、未复制其代码），需 Shizuku/ADB 权限。