ms-vite-plugin 1.4.38 → 1.4.40

package/docs/api/dotocr.md

@@ -0,0 +1,160 @@
+# 点阵 OCR 模块（dotOcr）
+
+`dotOcr` 使用图色工具生成的固定像素点阵字库识别文字。字库保存在项目的 `res/fonts` 目录，使用方式与 YOLO 模型一致：先加载资源取得字库 ID，再复用该 ID 进行识别，使用完毕后释放。
+
+点阵模板按照制作时的原始像素尺寸匹配，不会自动缩放到其他分辨率。目标文字的字号、缩放比例或像素形状发生变化时，应制作对应的字库特征。
+
+## 功能概览
+
+- **字库管理**：加载、缓存和释放项目字库
+- **文字识别**：返回按阅读顺序排列的识别结果数组
+- **文本查找**：先识别再按行定位目标串，返回命中位置的绝对坐标
+- **多源输入**：支持 `"screen"`、图片文件路径、URL 或 imageId
+- **绝对坐标**：裁剪区域内的结果会映射回原图或全屏坐标
+
+## 数据类型
+
+### OCRChar
+
+```typescript
+interface OCRChar {
+  text: string;
+  confidence: number;
+  x: number;
+  y: number;
+  ex: number;
+  ey: number;
+  width: number;
+  height: number;
+  centerX: number;
+  centerY: number;
+}
+```
+
+| 字段名               | 类型   | 描述                                   |
+| -------------------- | ------ | -------------------------------------- |
+| `OCRChar.text`       | string | 识别文本；查找结果中为命中的目标字符串 |
+| `confidence`         | number | 置信度，范围为 0-1                     |
+| `x`, `y`             | number | 结果区域左上角绝对坐标                 |
+| `ex`, `ey`           | number | 结果区域右下角绝对坐标                 |
+| `width`, `height`    | number | 结果区域宽度和高度                     |
+| `centerX`, `centerY` | number | 结果区域中心点绝对坐标                 |
+
+## API 参考
+
+### 字库管理
+
+#### loadFont - 加载并缓存字库
+
+```typescript
+function loadFont(fontPath: string): string | null;
+```
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                                                        |
+| ---------- | ------ | -------- | ------ | --------------------------------------------------------------------------- |
+| `fontPath` | string | 是       |        | 资源路径，运行时会自动处理 `res` 目录解析；常见写法如 `/fonts/default.json` |
+
+**返回值：**加载成功返回 `fontId`，失败返回 `null`。加载后的字库 ID 会复用到后续识别与释放流程。
+
+```javascript
+const fontId = dotOcr.loadFont("/fonts/default.json");
+if (!fontId) throw new Error("字库加载失败");
+```
+
+建议在脚本初始化时加载一次并保存 `fontId`，后续识别时复用，不要每次识别都重新加载。
+
+### 文字识别
+
+#### recognizeAbs - 识别文字并返回绝对坐标
+
+```typescript
+function recognizeAbs(
+  fontId: string,
+  input: string,
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  confidenceThreshold?: number,
+): OCRChar[];
+```
+
+| 参数名                | 类型   | 是否必填 | 默认值 | 描述                                                                                         |
+| --------------------- | ------ | -------- | ------ | -------------------------------------------------------------------------------------------- |
+| `fontId`              | string | 是       |        | `loadFont` 返回的字库 ID                                                                     |
+| `input`               | string | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                                        |
+| `x`, `y`              | number | 否       | 0      | 裁剪区域左上角坐标                                                                           |
+| `ex`, `ey`            | number | 否       | 0      | 裁剪区域右下角坐标；`ex` 或 `ey` 为 0 时分别使用图像宽度或高度                               |
+| `confidenceThreshold` | number | 否       | 0.8    | 相似度下限；`<=0` 时按 `0.8`；低于阈值的字符会被过滤；`>0.95` 时要求模板与图像像素完全一致 |
+
+**返回值：**`OCRChar[]`。按行从上到下、同一行从左到右排列。颜色按字库各字自带的前景色/偏色匹配，无需额外传色。
+
+```javascript
+const chars = dotOcr.recognizeAbs(fontId, "screen", 100, 200, 600, 280, 0.8);
+console.log(chars[0]?.text, chars[0]?.x, chars[0]?.width);
+```
+
+### 文本查找
+
+#### findTextAbs - 查找指定字符串并返回绝对坐标
+
+```typescript
+function findTextAbs(
+  fontId: string,
+  input: string,
+  targetTexts: string[],
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  confidenceThreshold?: number,
+  exactMatch?: boolean,
+): OCRChar[];
+```
+
+| 参数名                | 类型     | 是否必填 | 默认值 | 描述                                                                  |
+| --------------------- | -------- | -------- | ------ | --------------------------------------------------------------------- |
+| `fontId`              | string   | 是       |        | `loadFont` 返回的字库 ID                                              |
+| `input`               | string   | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                 |
+| `targetTexts`         | string[] | 是       |        | 要查找的字符串数组，例如 `["商店", "背包"]`                           |
+| `x`, `y`              | number   | 否       | 0      | 裁剪区域左上角坐标                                                    |
+| `ex`, `ey`            | number   | 否       | 0      | 裁剪区域右下角坐标；`ex` 或 `ey` 为 0 时分别使用图像宽度或高度        |
+| `confidenceThreshold` | number   | 否       | 0.8    | 单字符识别相似度下限；语义同 `recognizeAbs`                           |
+| `exactMatch`          | boolean  | 否       | false  | `false` 为行内子串包含匹配；`true` 要求某一整行文本完全等于目标字符串 |
+
+**返回值：**命中结果数组。每个目标最多返回一次命中（最先匹配到的行）；每项的 `text` 是目标字符串。
+
+```javascript
+const hits = dotOcr.findTextAbs(
+  fontId,
+  "screen",
+  ["商店", "背包"],
+  100,
+  200,
+  600,
+  280,
+  0.8,
+  false,
+);
+if (hits.length > 0) action.click(hits[0].centerX, hits[0].centerY);
+```
+
+### 资源管理
+
+#### free - 释放指定字库
+
+```typescript
+function free(fontId: string): void;
+```
+
+#### freeAll - 释放全部点阵字库
+
+```typescript
+function freeAll(): void;
+```
+
+```javascript
+dotOcr.free(fontId);
+// 或在需要清理全部已加载的点阵字库时：
+dotOcr.freeAll();
+```

package/docs/api/file.md

@@ -47,50 +47,6 @@ logi(`文档目录: ${documentsDir}`);
 logi(`临时目录: ${tempDir}`);
 ```
 
-#### getDataDir - 获取应用数据目录路径。
-
-```typescript
-function getDataDir(): string;
-```
-
-**返回值:**
-
-| 类型     | 描述             |
-| -------- | ---------------- |
-| `string` | 应用数据目录路径 |
-
-**示例:**
-
-```javascript
-const dataDir = file.getDataDir();
-logi(`数据目录: ${dataDir}`);
-```
-
-#### getDataFile - 获取应用数据文件的完整路径。
-
-```typescript
-function getDataFile(file: string): string;
-```
-
-**参数:**
-
-| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
-| ------ | ------ | -------- | ------ | ------------ |
-| `file` | string | 是       | -      | 文件名或路径 |
-
-**返回值:**
-
-| 类型     | 描述         |
-| -------- | ------------ |
-| `string` | 文件完整路径 |
-
-**示例:**
-
-```javascript
-const configPath = file.getDataFile("config.json");
-logi(`配置文件路径: ${configPath}`);
-```
-
 #### mkdirs - 创建目录（支持递归创建）。
 
 ```typescript
@@ -328,6 +284,54 @@ if (config) {
 }
 ```
 
+#### getResFile - 获取 `res` 资源的本地文件路径。
+
+适用于需要真实文件路径的场景（如模型文件、音视频）。用完后应调用 `cleanupResFile`。
+
+```typescript
+function getResFile(fileName: string): string | null;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                  |
+| ---------- | ------ | -------- | ------ | --------------------- |
+| `fileName` | string | 是       | -      | 相对 `res` 目录的路径 |
+
+**返回值:**
+
+| 类型           | 描述                                      |
+| -------------- | ----------------------------------------- |
+| `string\|null` | 本地文件绝对路径；失败或不存在时返回 null |
+
+**示例:**
+
+```javascript
+const path = file.getResFile("model.bin");
+if (path) {
+  // 使用 path ...
+  file.cleanupResFile(path);
+}
+```
+
+#### cleanupResFile - 清理由 `getResFile` 得到的本地文件。
+
+```typescript
+function cleanupResFile(path: string): void;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                      |
+| ------ | ------ | -------- | ------ | ------------------------- |
+| `path` | string | 是       | -      | `getResFile` 返回的文件路径 |
+
+**示例:**
+
+```javascript
+file.cleanupResFile(path);
+```
+
 #### writeFile - 写入文件内容（覆盖原有内容）。
 
 ```typescript