ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apipython/netCard.md

@@ -0,0 +1,219 @@
+# 卡密模块 (NetCard)
+
+卡密模块提供了卡密验证、备注设置以及键值对存储功能，用于管理网络卡密相关的操作。
+
+## 功能概览
+
+- **卡密验证**: 验证卡密的有效性
+- **备注管理**: 设置和管理卡密备注信息
+- **云变量存储**: 提供键值对形式的数据存储和读取功能
+
+## 注意事项
+
+1. **卡密安全**: 卡密信息应当妥善保管，避免在日志中明文输出
+2. **API 调用顺序**: 验证卡密后，其他 api 才能调用
+
+## API 参考
+
+### 卡密验证
+
+#### verify - 验证卡密
+
+```python
+def verify(cardNo: str) -> bool
+```
+
+**参数说明：**
+
+| 参数名   | 类型 | 是否必填 | 默认值 | 描述                 |
+| -------- | ---- | -------- | ------ | -------------------- |
+| `cardNo` | str  | 是       |        | 需要验证的卡密字符串 |
+
+**返回值：**
+
+| 类型   | 描述                                            |
+| ------ | ----------------------------------------------- |
+| `bool` | 验证结果，True 表示验证成功，False 表示验证失败 |
+
+**示例 1：**
+
+```python
+from kuaijs import netcard, logger
+import sys
+
+# 验证卡密
+cardNo = "ABC123456789"
+isValid = netcard.verify(cardNo)
+
+if isValid:
+    logger.info("卡密验证成功")
+else:
+    logger.error("卡密验证失败")
+    # 注意卡密验证失败退出程序
+    sys.exit(0)
+```
+
+**示例 2：**
+
+```python
+from kuaijs import netcard, logger, config
+import sys
+
+# 验证卡密 从配置中获取卡密
+cardNo = config.get("cardNo")
+isValid = netcard.verify(cardNo)
+
+if isValid:
+    logger.info("卡密验证成功")
+else:
+    logger.error("卡密验证失败")
+    # 注意卡密验证失败退出程序
+    sys.exit(0)
+```
+
+### 获取卡密信息
+
+#### getCardInfo - 获取卡密信息
+
+```python
+from typing import TypedDict, Optional
+
+class CardInfo(TypedDict):
+    cardNo: str
+    batchCard: str
+    remark: str
+    activeTime: int
+    expireTime: int
+
+def getCardInfo() -> Optional[CardInfo]
+```
+
+**返回值：**
+
+| 类型       | 描述                                 |
+| ---------- | ------------------------------------ |
+| `CardInfo` | 卡密信息对象，包含卡密及备注和时间等 |
+
+`CardInfo` 字段：
+
+- `cardNo`: 卡密号码
+- `batchCard`: 批量码
+- `remark`: 备注
+- `activeTime`: 激活时间
+- `expireTime`: 过期时间
+
+**示例：**
+
+```python
+from kuaijs import netcard, logger
+
+# 获取卡密信息
+cardInfo = netcard.getCardInfo()
+if cardInfo:
+    logger.info(f"卡密信息: {cardInfo}")
+```
+
+### 备注管理
+
+#### setCardRemark - 设置卡密备注
+
+```python
+def setCardRemark(remark: str) -> bool
+```
+
+**参数说明：**
+
+| 参数名   | 类型 | 是否必填 | 默认值 | 描述           |
+| -------- | ---- | -------- | ------ | -------------- |
+| `remark` | str  | 是       |        | 备注信息字符串 |
+
+**返回值：**
+
+| 类型   | 描述                                            |
+| ------ | ----------------------------------------------- |
+| `bool` | 设置结果，True 表示设置成功，False 表示设置失败 |
+
+**示例：**
+
+```python
+from kuaijs import netcard, logger
+
+# 设置卡密备注
+remark = "测试用户卡密"
+success = netcard.setCardRemark(remark)
+
+if success:
+    logger.info("备注设置成功")
+else:
+    logger.error("备注设置失败")
+```
+
+### 云变量
+
+#### setValue - 设置键值对
+
+```python
+def setValue(key: str, value: str) -> str
+```
+
+**参数说明：**
+
+| 参数名  | 类型 | 是否必填 | 默认值 | 描述       |
+| ------- | ---- | -------- | ------ | ---------- |
+| `key`   | str  | 是       |        | 存储的键名 |
+| `value` | str  | 是       |        | 存储的值   |
+
+**返回值：**
+
+| 类型  | 描述                                          |
+| ----- | --------------------------------------------- |
+| `str` | 成功时返回设置的 value 值，失败时返回空字符串 |
+
+**示例：**
+
+```python
+from kuaijs import netcard, logger
+
+# 设置键值对
+key = "userConfig"
+value = "enableNotification"
+result = netcard.setValue(key, value)
+
+if result == value:
+    logger.info(f"成功设置 {key}: {value}")
+else:
+    logger.error("设置失败")
+```
+
+#### getValue - 获取键值对
+
+```python
+def getValue(key: str) -> str
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述         |
+| ------ | ---- | -------- | ------ | ------------ |
+| `key`  | str  | 是       |        | 要获取的键名 |
+
+**返回值：**
+
+| 类型  | 描述                                             |
+| ----- | ------------------------------------------------ |
+| `str` | 成功时返回对应的值，失败或键不存在时返回空字符串 |
+
+**示例：**
+
+```python
+from kuaijs import netcard, logger
+
+# 获取键值对
+key = "userConfig"
+value = netcard.getValue(key)
+
+if value:
+    logger.info(f"获取到配置: {key} = {value}")
+else:
+    logger.warn(f"配置 {key} 不存在或获取失败")
+```

package/docs/apipython/node.md

@@ -0,0 +1,331 @@
+# 节点模块 (Node)
+
+节点模块提供了强大的 UI 元素访问和操作功能，可以通过各种条件选择和操作界面元素。
+
+**注意事项**
+
+- 此模块仅支持 快点 Agent 模式使用
+
+## 类型定义
+
+```python
+from typing import List, Literal, Optional, TypedDict, Union
+
+class NodeBounds:
+    x: int
+    y: int
+    width: int
+    height: int
+    centerX: int
+    centerY: int
+
+class NodeInfo:
+    id: str
+    identifier: str
+    label: str
+    type: str
+    value: str
+    placeholderValue: str
+    title: str
+    visible: bool
+    enabled: bool
+    bounds: NodeBounds
+    depth: int
+    index: int
+    parentId: str
+    childCount: int
+
+    def clickCenter(self) -> bool: ...
+    def clickRandom(self) -> bool: ...
+    def hittable(self) -> bool: ...
+    def parent(self) -> Optional["NodeInfo"]: ...
+    def child(self, index: int) -> Optional["NodeInfo"]: ...
+    def allChildren(self) -> List["NodeInfo"]: ...
+    def siblings(self) -> List["NodeInfo"]: ...
+    def previousSiblings(self) -> List["NodeInfo"]: ...
+    def nextSiblings(self) -> List["NodeInfo"]: ...
+
+class NodeSelectorOptions(TypedDict, total=False):
+    maxDepth: int  # 最大层级深度，默认 50
+```
+
+## 节点选择器 (NodeSelector)
+
+节点选择器是访问 UI 元素的核心工具，提供了灵活的筛选和查找机制。
+
+### 创建节点选择器
+
+#### `createNodeSelector` - 创建节点选择器
+
+创建一个新的节点选择器实例。
+
+```python
+def createNodeSelector(params: Optional[NodeSelectorOptions] = None) -> NodeSelector
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                  |
+| ---------- | ---- | -------- | ------ | --------------------- |
+| `maxDepth` | int  | 否       | 50     | 最大层级深度，默认 50 |
+
+**返回值：** `NodeSelector`
+
+**示例：**
+
+```python
+from kuaijs import node
+
+# 创建选择器
+selector = node.createNodeSelector({
+    "maxDepth": 20  # 最大20层深度
+})
+```
+
+### 选择器方法
+
+#### 获取节点
+
+```python
+# 获取当前页面的 XML 字符串
+def xml(timeout: int = 5000) -> Optional[str]
+
+# 获取多个节点
+def getNodeInfo(timeout: int = 5000) -> List[NodeInfo]
+
+# 获取单个节点
+def getOneNodeInfo(timeout: int = 5000) -> Optional[NodeInfo]
+
+# 加载节点数据（通常内部自动调用）
+def loadNode(timeout: int = 5000) -> NodeSelector
+
+# 清除所有选择条件
+def clearSelector() -> NodeSelector
+```
+
+**示例：**
+
+```python
+from kuaijs import node
+
+selector = node.createNodeSelector()
+
+# 获取所有匹配的节点
+all_nodes = selector.getNodeInfo(5000)
+print(f"找到 {len(all_nodes)} 个节点")
+
+# 获取第一个匹配的节点
+first_node = selector.getOneNodeInfo(3000)
+if first_node:
+    print(f"节点标签: {first_node.label}")
+```
+
+#### 条件筛选
+
+##### 文本相关
+
+```python
+# 精确匹配标签
+def label(text: str) -> NodeSelector
+
+# 标签模糊匹配
+def labelMatch(pattern: str) -> NodeSelector
+
+# 精确匹配名称
+def title(text: str) -> NodeSelector
+
+# 名称模糊匹配
+def titleMatch(pattern: str) -> NodeSelector
+
+# 精确匹配标识符
+def identifier(text: str) -> NodeSelector
+
+# 标识符模糊匹配
+def identifierMatch(pattern: str) -> NodeSelector
+
+# 精确匹配值
+def value(text: str) -> NodeSelector
+
+# 值模糊匹配
+def valueMatch(pattern: str) -> NodeSelector
+```
+
+**示例：**
+
+```python
+# 查找标签为"确定"的按钮
+confirm_button = selector.label("确定").getOneNodeInfo(3000)
+
+# 查找包含"登录"的元素
+login_elements = selector.labelMatch(".*登录.*").getNodeInfo(3000)
+
+# 查找名称包含"button"的元素
+buttons = selector.titleMatch("button").getNodeInfo(3000)
+
+# 查找值为"submit"的元素
+submit_element = selector.value("submit").getOneNodeInfo(2000)
+
+# 通过标识符查找
+el_by_id = selector.identifier("login_btn").getOneNodeInfo(2000)
+fuzzy = selector.identifierMatch("^login_.*").getNodeInfo(3000)
+```
+
+##### 类型与属性
+
+```python
+# 精确匹配类型
+def type(type_title: str) -> NodeSelector
+
+# 类型模糊匹配
+def typeMatch(pattern: str) -> NodeSelector
+
+# 启用状态
+def enabled(flag: bool) -> NodeSelector
+
+# 可见性
+def visible(flag: bool) -> NodeSelector
+```
+
+**示例：**
+
+```python
+from kuaijs import node
+
+selector = node.createNodeSelector()
+
+# 查找所有按钮
+all_buttons = selector.type("XCUIElementTypeButton").getNodeInfo(3000)
+
+# 查找所有文本框
+text_fields = selector.typeMatch("XCUIElementTypeTextField").getNodeInfo(3000)
+
+# 查找启用的元素
+enabled_elements = selector.enabled(True).getNodeInfo(3000)
+```
+
+##### 位置与结构
+
+```python
+# 索引位置
+def index(idx: int) -> NodeSelector
+
+# 层级深度
+def depth(d: int) -> NodeSelector
+
+# 子节点数量（支持表达式，如 ">0"）
+def childCount(expr: Union[int, str]) -> NodeSelector
+
+# 边界范围
+def bounds(x: int, y: int, width: int, height: int) -> NodeSelector
+
+# XPath 路径
+def xpath(path: str) -> NodeSelector
+```
+
+**说明：** `*_match` 支持正则/模糊匹配；`childCount` 支持表达式（如 `>0`）。
+
+**示例：**
+
+```python
+from kuaijs import node
+
+selector = node.createNodeSelector()
+
+# 查找第一个元素
+first_element = selector.index(0).getOneNodeInfo(2000)
+
+# 查找特定深度的元素
+level3_elements = selector.depth(3).getNodeInfo(3000)
+
+# 查找有子节点的元素
+parent_elements = selector.childCount(">0").getNodeInfo(3000)
+
+# 查找特定区域的元素
+region_elements = selector.bounds(100, 100, 200, 50).getNodeInfo(3000)
+
+# 使用 XPath 查找
+xpath_elements = selector.xpath("//*[@title='快点JS']").getNodeInfo(3000)
+```
+
+## 节点操作
+
+`NodeSelector` 查找得到的 `NodeInfo` 支持直接调用操作方法（点击、无障碍手势等）。
+
+### 点击操作
+
+```python
+# 点击节点中心
+def clickCenter() -> bool
+
+# 随机点击节点区域
+def clickRandom() -> bool
+
+# 节点是否可接收事件（用于判断是否显示在屏幕上）
+def hittable() -> bool
+```
+
+**示例：**
+
+```python
+from kuaijs import node
+
+selector = node.createNodeSelector()
+
+# 查找并点击确定按钮
+confirm_btn = selector.label("确定").type("XCUIElementTypeButton").getOneNodeInfo(3000)
+
+if confirm_btn:
+    print(f"是否可接收事件: {confirm_btn.hittable()}")
+
+    clicked = confirm_btn.clickCenter()
+    if clicked:
+        print("成功点击确定按钮")
+
+    # 随机点击避免检测
+    confirm_btn.clickRandom()
+```
+
+### 节点导航
+
+```python
+# 获取父节点
+def parent() -> Optional[NodeInfo]
+
+# 获取指定索引的子节点
+def child(index: int) -> Optional[NodeInfo]
+
+# 获取所有子节点
+def allChildren() -> List[NodeInfo]
+
+# 获取兄弟节点
+def siblings() -> List[NodeInfo]
+
+# 获取前面的兄弟节点
+def previousSiblings() -> List[NodeInfo]
+
+# 获取后面的兄弟节点
+def nextSiblings() -> List[NodeInfo]
+```
+
+**示例：**
+
+```python
+from kuaijs import node
+
+selector = node.createNodeSelector()
+
+# 查找输入框并获取其父容器
+text_field = selector.type("XCUIElementTypeTextField").getOneNodeInfo(3000)
+
+if text_field:
+    container = text_field.parent()
+    if container:
+        print(f"容器类型: {container.type}")
+
+        # 获取容器的所有子元素
+        children = container.allChildren()
+        print(f"容器包含 {len(children)} 个子元素")
+
+        # 查找同级的按钮
+        sibling_buttons = [n for n in children if n.type == "XCUIElementTypeButton"]
+```

package/docs/apipython/overview.md

@@ -0,0 +1,66 @@
+# Python API 使用教程
+
+- `快点JS` 在 Python 环境中提供与 JS API 对齐的模块，模块名与 JS 保持一致。
+
+- 导入方式：
+
+```python
+from kuaijs import action, hid, image, appleocr, paddleocr, yolo, system, device, file, mysql, netcard, ime, media, hotupdate, tomatoocr, tts, ui, utils, node, pip, logger
+```
+
+## 下载资源
+
+- 官方网盘下载：[链接](https://pan.kuai.js.cn/#/_/%E5%BF%AB%E7%82%B9JS)
+
+## nodejs 环境
+
+`快点JS` 开发工具基于 nodejs 环境，因此需要先安装 nodejs 环境。
+
+## python 环境
+
+`快点JS` - Python 基于 Python3.14 版本，因此需要先安装 Python3.14 环境。
+
+自行安装：`pip install kuaijs-ios` 以获取代码提示
+
+## IDE 配置
+
+### Visual Studio Code
+
+`快点JS` 使用 Visual Studio Code 作为主要开发工具，并安装以下扩展：
+
+#### 必需扩展
+
+- **`快点JS开发工具`** - 提供 `快点JS` 相关功能，如创建项目、代码补全、图色工具、节点查找、打包软件包 等
+
+#### 安装步骤
+
+1. 打开 Visual Studio Code
+2. 点击左侧扩展图标（或使用快捷键 `Ctrl+Shift+X`）
+3. 在搜索框中输入 `快点JS开发工具`
+   <img src="/img/DevPlugin.jpg" width="800" alt="安装快点JS开发工具">
+4. 点击安装按钮安装扩展
+5. 安装完成后，重新启动 Visual Studio Code
+
+## 创建项目
+
+- 参照[创建 JS 项目](../quick/createProject.md)创建项目
+
+- 创建项目时选择 `Python` 作为项目类型
+
+## 标准库
+
+Python 的标准库大部分都是支持的.
+
+multiprocessing: ios 的沙盒模式限制.不能多次开辟进程.
+
+## 第三方库
+
+除了标准库外,我们也增加了一些常用的第三方库
+
+```
+"numpy==2.5.0",
+"opencv-python==4.14.0"
+"requests",
+"websockets",
+"PyMySQL"
+```