@isdk/web-fetcher 0.2.12 → 0.3.1

package/README.action.cn.md

@@ -90,6 +90,8 @@ export class FillAction extends FetchAction {
   * ...其他导航选项，如 **`waitUntil`**, **`timeout`**，这些选项会传递给引擎。
 * **`returns`**: `response`
 
+> **注意**：此 Action 可以在单个会话脚本中多次调用。引擎确保每次导航都已完成且其对应的 Action 循环已稳定，然后再处理序列中的下一个 Action。
+
 #### `click`
 
 点击由 **`selector`** (CSS 选择器) 指定的元素。
@@ -123,6 +125,41 @@ export class FillAction extends FetchAction {
   * **`selector`** (string, optional): 表单元素的选择器。
 * **`returns`**: `none`
 
+#### `trim`
+
+从 DOM 中移除特定元素以在提取前清理页面。这会对当前会话的页面状态进行持久修改。
+
+* **`id`**: `trim`
+* **`params`**:
+  * **`selectors`** (string | string[], optional): 一个或多个要移除元素的 CSS 选择器。
+  * **`presets`** (string | string[], optional): 预定义的移除元素组。支持的预设：
+    * `scripts`: 移除所有 `<script>` 标签。
+    * `styles`: 移除所有 `<style>` 和 `<link rel="stylesheet">` 标签。
+    * `svgs`: 移除所有 `<svg>` 元素。
+    * `images`: 移除 `<img>`, `<picture>` 和 `<canvas>` 元素。
+    * `comments`: 移除 HTML 注释。
+    * `hidden`: 移除带有 `hidden` 属性或内联 `display:none` 的元素。在 **browser** 模式下，它还会检测并移除通过外部 CSS（如样式表中的 `display: none` 或 `visibility: hidden`）隐藏的元素。
+    * `all`: 包含上述所有预设。
+* **`returns`**: `none`
+
+**示例：在提取前清理页面**
+
+```json
+{
+  "actions": [
+    { "action": "goto", "params": { "url": "https://example.com" } },
+    {
+      "action": "trim",
+      "params": {
+        "selectors": ["#ad-banner", ".popup"],
+        "presets": ["scripts", "styles", "comments"]
+      }
+    },
+    { "action": "extract", "params": { "schema": { "content": "#main-content" } } }
+  ]
+}
+```
+
 #### `waitFor`
 
 暂停执行，以等待一个或多个条件的满足。
@@ -208,199 +245,110 @@ await fetchWeb({
 * **`params`**: (无)
 * **`returns`**: `response`
 
-#### `extract`
-
-使用一个强大且声明式的 **`ExtractSchema`** 从当前页面中提取结构化数据。这是进行数据采集的核心 Action。
-
-* **`id`**: `extract`
-* **`params`**: 一个 **`ExtractSchema`** 对象, 用于定义提取规则。
-* **`returns`**: `any` (提取出的数据)
-
-##### 提取 Schema 详解
-
-`params` 对象本身就是一个 Schema, 用于描述您想提取的数据结构。
-
-###### 1. 提取单个值
-
-最基础的提取，可以指定 **`selector`** (CSS 选择器), **`attribute`** (要提取的属性名), **`type`** (string, number, boolean, html), 以及 **`mode`** (text, innerText)。
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "selector": "h1.main-title",
-    "type": "string",
-    "mode": "innerText"
-  }
-}
-```
-
-> **提取模式 (Extraction Modes):**
->
-> * **`text`** (默认): 提取元素的 `textContent`。
-> * **`innerText`**: 提取渲染后的文本，尊重 CSS 样式并处理换行。
-> * **`html`**: 返回元素的 `innerHTML`。
-> * **`outerHTML`**: 返回包含标签自身的完整 HTML。对于保留元素结构非常有用。
-> 上例将使用 `innerText` 模式提取 class 为 `main-title` 的 `<h1>` 标签的文本内容。
-
-###### 2. 提取对象
-
-通过 **`type: 'object'`** 和 **`properties`** 字段来定义一个结构化对象。
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "object",
-    "selector": ".author-bio",
-    "properties": {
-      "name": { "selector": ".author-name" },
-      "email": { "selector": "a.email", "attribute": "href" }
-    }
-  }
-}
-```
-
-###### 3. 提取数组 (便捷用法)
+#### `mouseMove`
 
-通过 **`type: 'array'`** 来提取一个列表。为了让最常见的操作更简单，我们提供了一些便捷用法。
+将鼠标指针移动到指定的坐标或元素。在 `browser` 模式下，它使用 **贝塞尔曲线 (Bézier curve)** 来模拟真实人类的非线性移动轨迹，并带有轻微的抖动以增加真实感。
 
-* **提取文本数组 (默认行为)**: 当您想提取一个文本列表时,只需提供选择器,省略 `items` 即可。这是最常见的用法。
+* **`id`**: `mouseMove`
+* **`params`**:
+  * `x` (number, 可选): 绝对 X 坐标。
+  * `y` (number, 可选): 绝对 Y 坐标。
+  * `selector` (string, 可选): CSS 选择器。如果提供，鼠标将移动到该元素的中心。
+  * `steps` (number, 可选): 轨迹的中间步数（默认：`-1`）。设置为 `-1` 可根据距离动态计算步数（模拟自然移动速度）。
+* **`returns`**: `none`
 
-    ```json
-    {
-      "id": "extract",
-      "params": {
-        "type": "array",
-        "selector": ".tags li"
-      }
-    }
-    ```
+#### `mouseClick`
 
-    > 上例将返回一个包含所有 `<li>` 标签文本的数组, 如 `["tech", "news"]`。
+在当前位置或指定坐标触发鼠标点击。如果提供了 `selector`，光标会先平滑地移动到目标元素（使用动态步数），然后再执行点击。
 
-* **提取属性数组 (快捷方式)**: 当您只想提取一个属性列表(例如所有链接的 **`href`**)时，也无需嵌套 `items`。直接在 `array` 定义中声明 **`attribute`** 即可。
+* **`id`**: `mouseClick`
+* **`params`**:
+  * `x` (number, 可选): 点击的绝对 X 坐标。
+  * `y` (number, 可选): 点击的绝对 Y 坐标。
+  * `selector` (string, 可选): CSS 选择器。如果提供，鼠标会先移动到该元素。
+  * `button` (string, 可选): 使用的鼠标按键 (`left`, `right`, 或 `middle`)。默认为 `left`。
+  * `clickCount` (number, 可选): 点击次数（例如：2 表示双击）。默认为 1。
+  * `delay` (number, 可选): mousedown 和 mouseup 之间的延迟（毫秒）。
+* **`returns`**: `none`
 
-    ```json
+#### `keyboardType`
 
-    {
-      "id": "extract",
-      "params": {
-        "type": "array",
-        "selector": ".gallery img",
-        "attribute": "src"
-      }
-    }
-    ```
+模拟真人在当前获得焦点的元素中输入文本。
 
-    > 上例将返回一个包含所有 `<img>` 标签 `src` 属性的数组。
+* **`id`**: `keyboardType`
+* **`params`**:
+  * `text` (string): 要输入的文本。
+  * `delay` (number, 可选): 按键之间的延迟（毫秒，默认：100）。
+* **`returns`**: `none`
 
-* **数组提取模式**: 在提取数组时，引擎支持不同的模式来处理各种 DOM 结构。
+#### `keyboardPress`
 
-  * **`nested`** (默认): `selector` 匹配每个项目的包裹元素。
-  * **`columnar`** (原 Zip 策略): `selector` 指向**容器**，`items` 中的字段是平行的列，按索引缝合在一起。
-  * **`segmented`**: `selector` 指向**容器**，项目通过“锚点”字段进行分段提取。
+模拟按下单个按键或组合键（例如：`Enter`, `Control+A`）。
 
-###### 4. 列对齐模式 (Columnar Mode，原 Zip 策略)
+* **`id`**: `keyboardPress`
+* **`params`**:
+  * `key` (string): 按键名称（例如：`Enter`, `Tab`, `Backspace`, `ArrowUp`）。
+  * `delay` (number, 可选): 按键后的延迟（毫秒）。
+* **`returns`**: `none`
 
-当 `selector` 指向一个**容器**（如结果列表）且项目数据以平行的独立列散落在其中时使用。
+#### `evaluate`
 
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#search-results",
-    "mode": "columnar",
-    "items": {
-      "title": { "selector": ".item-title" },
-      "link": { "selector": "a.item-link", "attribute": "href" }
-    }
-  }
-}
-```
+在页面上下文中执行 JavaScript 函数或表达式。这是一个强大的 Action，用于执行内置 Action 未涵盖的自定义逻辑。
 
-> **启发式自动检测:** 如果省略了 `mode`，且 `selector` 恰好只匹配到一个元素，同时 `items` 中包含选择器，引擎会自动使用 **columnar** 模式。
+* **`id`**: `evaluate`
+* **`params`**:
+  * **`fn`** (string | function): 要执行的函数或表达式。
+  * **`args`** (any, 可选): 传递给函数的单个参数。如需传递多个参数，请使用数组或对象。
+* **`returns`**: `any` (执行结果)
 
-**Columnar 配置参数:**
+> **💡 跨引擎兼容性**:
+>
+> * **`browser`**: 直接在浏览器中运行。
+> * **`http`**: 在 Node.js 中运行，并提供模拟环境（提供 `window`, `document` 和 `$`）。
+    * **`args`**: `any` - 传递给函数的单个参数。如需传递多个值，请使用数组或对象。
 
-* **`strict`** (boolean, 默认: `true`): 如果为 `true`，当不同字段匹配到的数量不一致时将抛出错误。
-* **`inference`** (boolean, 默认: `false`): 如果为 `true`，当字段数量不匹配时，尝试通过 DOM 树自动寻找“包裹元素”来修复错位的列表。
+**核心特性：**
 
-###### 5. 分段扫描模式 (Segmented Mode)
+- **自动导航检测**：如果代码修改了 `window.location.href` 或调用了 `assign()`/`replace()`，引擎会自动触发并等待导航完成。
+- **增强型 Mock DOM (HTTP 模式)**：支持常用的 DOM 方法，如 `querySelector`, `querySelectorAll`, `getElementById`, `getElementsByClassName`，以及 `document.body` 和 `document.title` 等属性。
+- **沙箱安全**：在 HTTP 模式下使用 `util-ex` 的 `newFunction`，防止全局状态污染。
 
-适用于完全“平铺”且没有包裹元素的结构。它使用第一个字段（或指定的 `anchor`）作为锚点来对容器内容进行分段。
+**示例 (数组参数)：**
 
 ```json
 {
-  "id": "extract",
+  "action": "evaluate",
   "params": {
-    "type": "array",
-    "selector": "#flat-container",
-    "mode": { "type": "segmented", "anchor": "title" },
-    "items": {
-      "title": { "selector": "h3" },
-      "desc": { "selector": "p" }
-    }
+    "fn": "([a, b]) => a + b",
+    "args": [1, 2]
   }
 }
 ```
 
-> 在此模式下，每当引擎发现一个 `h3`，就会开启一个新项目。随后找到的 `p` 标签（直到下一个 `h3` 出现前）都归属于该项目。
-
-###### 6. 隐式对象提取 (最简语法)
-
-为了让对象提取更简单，你可以省略 `type: 'object'` 和 `properties`。如果 schema 对象包含非保留关键字（如 `selector`, `attribute`, `type` 等）的键，它将被视为对象 schema，其中的键作为属性名。
+**示例 (导航)：**
 
 ```json
 {
-  "id": "extract",
+  "action": "evaluate",
   "params": {
-    "selector": ".author-bio",
-    "name": { "selector": ".author-name" },
-    "email": { "selector": "a.email", "attribute": "href" }
+    "fn": "() => { window.location.href = '/new-page'; }"
   }
 }
 ```
 
-> 这等同于示例 2，但更简洁。
-
-###### 6. 精确筛选: `has` 和 `exclude`
-
-您可以在任何包含 **`selector`** 的 Schema 中使用 **`has`** 和 **`exclude`** 字段来精确控制元素的选择。
-
-* **`has`**: 一个 CSS 选择器，用于确保所选元素**必须包含**匹配此选择器的后代元素。
-* **`exclude`**: 一个 CSS 选择器，用于从结果中**排除**匹配此选择器的元素。
+#### `extract`
 
-**完整示例: 提取包含图片且未被标记为"草稿"的文章链接**
+使用强大且声明式的 **`ExtractSchema`** 从页面中提取结构化数据。
 
-```json
-{
-  "actions": [
-    { "id": "goto", "params": { "url": "https://example.com/articles" } },
-    {
-      "id": "extract",
-      "params": {
-        "type": "array",
-        "selector": "div.article-card",
-        "has": "img.cover-image",
-        "exclude": ".draft",
-        "items": {
-          "selector": "a.title-link",
-          "attribute": "href"
-        }
-      }
-    }
-  ]
-}
-```
+* **`id`**: `extract`
+* **`params`**: 一个 **`ExtractSchema`** 对象。
+* **`returns`**: 提取出的结构化数据。
 
-> 上述 `extract` Action 会:
+> **📚 详细手册**: 由于 `extract` 功能非常丰富（包含数组模式、作用域控制、锚点跳转等），我们准备了专门的详细文档：
 >
-> 1. 找到所有 `div.article-card` 元素。
-> 2. 筛选出其中必须包含 `<img class="cover-image">` 的元素。
-> 3. 再从结果中排除掉自身带有 `.draft` 类的元素。
-> 4. 对于最终剩下的每个 `div.article-card`, 找到其后代 `a.title-link` 并提取 `href` 属性。
+> 👉 **[点击查看 Extract 操作详解](./README.action.extract.cn.md)**
+
+---
 
 ### 通过“组合”构建高级语义 Action
 
@@ -545,3 +493,97 @@ await fetchWeb({
 * `protected onAfterExec?()`: 在 `onExecute` 执行后调用。
 
 对于需要管理复杂状态或资源的 Action，可以实现这些钩子。通常，对于组合式 Action，直接在 `onExecute` 中编写逻辑已经足够。
+
+---
+
+## 💎 7. Action 返回类型与状态管理 (进阶)
+
+在 `@isdk/web-fetcher` 中，Action 的 `static returnType` 不仅仅是一个类型提示。它定义了框架如何管理 **Session 状态** 以及如何在执行后自动同步数据。
+
+### 7.1 返回类型详解
+
+#### 🟢 `response` (页面响应)
+
+* **定义**: 包含 HTTP 状态码、响应头、正文和 Cookie 的 `FetchResponse` 对象。
+* **用途**: 将最新的页面内容和状态同步到会话中。
+* **用法**: 适用于执行导航、刷新或获取当前页面快照的动作。
+* **系统行为**: 框架在 `afterExec` 阶段会自动将此结果更新到 `context.lastResponse`。后续动作可以通过上下文访问它。
+* **典型 Action**: `goto`, `getContent`, `fill`（在某些引擎中）。
+* **示例**:
+
+  ```typescript
+  export class MyNavigateAction extends FetchAction {
+    static override id = 'myGoto';
+    static override returnType = 'response' as const;
+
+    async onExecute(context, options) {
+      // 返回 FetchResponse 的逻辑
+      return await this.delegateToEngine(context, 'goto', options.params.url);
+    }
+  }
+  ```
+
+#### 🟡 `any` (通用数据 - 默认)
+
+* **定义**: 任何可序列化的数据结构（对象、数组、字符串等）。
+* **用途**: 业务数据提取的主要机制。
+* **用法**: 当你的动作产生处理后的业务数据（而不是代表整个页面或系统状态）时使用。
+* **系统行为**: 如果 Action 配置包含 `storeAs: "key"`，框架会自动将 `result` 保存到 `context.outputs["key"]` 中。如果目标键已包含一个对象且新结果也是一个对象，它们将被合并（浅合并）而不是覆盖。这允许通过多个 `extract` 动作将数据累积到同一个输出键中。
+* **典型 Action**: `extract`。
+* **示例**:
+
+  ```typescript
+  static override returnType = 'any' as const;
+  async onExecute(context, options) {
+    return { title: 'Hello', price: 99 }; // 如果设置了 storeAs，则保存到 outputs
+  }
+  ```
+
+#### ⚪ `none` (无返回)
+
+* **定义**: `void`。
+* **用途**: 纯交互或副作用，不输出数据。
+* **用法**: 执行 UI 交互或时间控制的动作。
+* **典型 Action**: `click`, `submit`, `pause`, `trim`, `waitFor`。
+* **示例**:
+
+  ```typescript
+  static override returnType = 'none' as const;
+  async onExecute(context, options) {
+    await this.delegateToEngine(context, 'click', options.params.selector);
+    // 不需要返回值
+  }
+  ```
+
+#### 🔵 `outputs` (累积结果)
+
+* **定义**: 整个 `context.outputs` 记录 (`Record<string, any>`)。
+* **用途**: 获取当前会话期间提取并存储的所有数据。
+* **用法**: 通常用作链条末尾的“总结”动作或用于调试。
+* **典型 Action**: 自定义数据总结动作。
+
+#### 🟣 `context` (会话快照)
+
+* **定义**: 完整的 `FetchContext` 对象。
+* **用途**: 元编程和深度调试。
+* **用法**: 允许调用者检查当前的会话配置（超时、代理、请求头）和内部引擎元数据。
+
+---
+
+### 7.2 结果包装机制 (`FetchActionResult`)
+
+`onExecute` 返回的每个值都会被 `FetchAction.execute` 方法自动包装成 `FetchActionResult` 对象。这确保了所有动作之间一致的错误处理和元数据追踪。
+
+**`FetchActionResult` 的结构**:
+
+* `status`: `Success` (成功), `Failed` (失败), 或 `Skipped` (跳过)。
+* `returnType`: 匹配 Action 的 `static returnType`。
+* `result`: `onExecute` 返回的原始数据。
+* `error`: 如果动作失败，捕获到的错误对象。
+* `meta`: 诊断信息，包括执行时间、引擎类型和重试次数。
+
+### 7.3 开发者最佳实践
+
+1. **为导航选择 `response`**: 对于跳转到新 URL 的动作，务必使用 `response`，以确保会话的“当前页面”保持同步。
+2. **利用 `any` + `storeAs`**: 对于数据提取，将数据作为 `any` 返回，并让用户通过 JSON 脚本中的 `storeAs` 决定存储键。
+3. **明确使用 `none`**: 使用 `none` 可以清晰地表明该动作用于其副作用（如点击或等待），使工作流更易于理解。

package/README.action.extract.cn.md

@@ -0,0 +1,263 @@
+# 🔍 Extract 操作深度指南 (The Data Surgeon's Manual)
+
+[English](./README.action.extract.md) | 简体中文
+
+`extract` 是 `@isdk/web-fetcher` 的灵魂。它不只是一个“抓取器”，更像是一个**智能转换器**，能把杂乱无章的 HTML 变成你想要的精美 JSON。
+
+---
+
+## ⚡ 1. 快速开始：简写魔法 (Shorthand Magic)
+
+**场景**：结构简单的标准网页。当你只想快点看到结果，不想写长长的 JSON 配置时。
+
+```json
+{
+  "action": "extract",
+  "params": {
+    "title": "h1",               // 把 h1 里的文字抓出来存为 'title'
+    "link": { "selector": "a.main", "attribute": "href" }, // 精确提取链接属性
+    "tags": { "type": "array", "selector": ".tag-item" }   // 一口气抓下一组标签
+  }
+}
+```
+
+---
+
+## 📄 2. 提取基本值：手术镊子 (The Tweezers)
+
+**场景**：处理网页上具体的某一个数据点，如价格、标题或 ID。
+
+### 镊子参数解析 (Value Properties)
+
+* **`selector`**: CSS 选择器，告诉镊子要去哪里夹东西。
+* **`type`**: 自动类型转换。支持 `string`, `number` (自动剔除货币符号、单位，只留数字), `boolean`, `html`。
+* **`mode`**: 提取的模式。
+  * `innerText`: **(强烈推荐使用)** 就像人眼观察一样，它只取网页上可见的文字，并自动处理换行，过滤掉隐藏的 HTML 噪音。
+  * `text`: 原始文本内容，对应源码里的 `textContent`，包含隐藏字符。
+  * `outerHTML`: 抓取包含标签自身的完整 HTML 代码。
+* **`attribute`**: 如果你要抓的不是文字，而是属性（如 `href`, `src`），就在这里指定属性名。
+* **`depth`**: 向上回溯。匹配到元素后，先向上跳 N 层父节点再提取（比如你想抓一个按钮的父容器上的 ID）。
+
+**示例**：
+
+```json
+{
+  "selector": ".price-tag",
+  "type": "number",       // 自动把 "￥99.00" 转换成数字 99
+  "mode": "innerText",    // 确保拿到的是干净的文字
+  "attribute": "data-v",  // 提取 data-v 属性
+  "depth": 1              // 抓取该元素父节点的属性
+}
+```
+
+---
+
+## 📦 3. 提取对象：便当盒 (The Bento Box)
+
+**场景**：当你需要把多个相关的字段（如用户的“姓名”、“头像”、“简介”）打包在一起，形成一个完整的结构时。
+
+### 便当盒参数解析 (Object Properties)
+
+* **`type: "object"`**: 明确告诉引擎，这是一个需要打包的对象。
+* **`selector`**: **对象的根容器**。这非常重要！内部所有属性的 `selector` 都会相对于这个容器查找。如果你把容器定在 `.user-card`，内部写 `img` 就会只抓这张卡片里的图。
+* **`properties`**: **核心配置**。在这里定义你想要的 JSON 键名（Key）和对应的提取规则。
+* **`required`**: 如果你认为某个字段是“灵魂”，抓不到它这个对象就没意义，请设为 `true`。此时若提取失败，整个对象会返回 `null`。
+* **`depth`**: 用于触发“向上探索”逻辑的深度（详见进阶章节）。
+
+**示例：打包用户信息**
+
+```json
+{
+  "type": "object",
+  "selector": ".user-card",
+  "properties": {
+    "name": { "selector": ".username", "required": true },
+    "bio": ".user-description",
+    "avatar": { "selector": "img.avatar", "attribute": "src" }
+  }
+}
+```
+
+> **💡 透明盒子 (隐式对象)**：如果你省略 `type: "object"` 且不写 `selector`，这个盒子就成了“透明的”。如果内部所有字段都抓不到结果，整个盒子会自动消失。在过滤列表中的广告或空项时非常神奇。
+
+---
+
+## 📑 4. 提取数组：分拣模式 (The Sorting Machines)
+
+**场景**：处理成排出现的数据，如搜索结果列表、新闻瀑布流、或一组分类标签。
+
+### 分拣机参数解析 (Array Properties)
+
+* **`type: "array"`**: 明确声明你要提取的是一个列表。
+* **`selector`**: **扫描范围**。在默认模式下，它匹配每一个项目的“外壳”；在平铺模式下，它匹配整个大的列表容器。
+* **`items`**: **每一项的图纸**。注意，数组里用的是 `items` 而不是 `properties`。它定义了每一行数据长什么样。
+* **`mode`**: 决定分拣机的工作模式。
+  * `"nested"`: (默认) 每一个项目都有自己的“格子”（容器）。
+  * `"columnar"`: 数据按列排布，没有行容器（像 Excel 表格）。
+  * `"segmented"`: 数据完全平铺，通过“锚点”来切分段落。
+* **`limit`**: 限制抓取的最大条数，防止数据量过大。
+* **`inference`**: 启发式推断。当列表结构不规范时，开启它可以让引擎自动尝试修正错位。
+
+### 4.1 Nested (蛋托模式)：最稳定、首选
+
+**场景**：每个项目都被包裹在 `<li>` 或 `.item` 这种容器里。这是最稳、性能最好的选择。
+
+```json
+{
+  "type": "array",
+  "selector": ".product-list .item", // 匹配每一个产品的外壳
+  "items": {
+    "name": "h3",
+    "price": ".price"
+  }
+}
+```
+
+### 4.2 Columnar (列对齐模式)：处理表格类平铺
+
+**场景**：数据像表格一样。左边一列是标题，右边一列是价格，但它们没有共同的父节点包裹。
+**广播功能 (Broadcasting)**：如果某个字段在每一项里都一样（如列表的分类），你只需在总容器提取一次，它会自动“广播”给每一行。
+
+```json
+{
+  "type": "array",
+  "selector": "#table-container",
+  "mode": "columnar",
+  "items": {
+    "name": ".title-cols",
+    "date": "" // selector 为空，自动广播总容器里的日期信息
+  }
+}
+```
+
+### 4.3 Segmented (切割模式)：处理无序平铺
+
+**场景**：页面结构极其糟糕，所有内容都是兄弟节点并排，只能靠某个标志（如 `h2` 标题）来区分段落。
+
+```json
+{
+  "type": "array",
+  "selector": ".content-body",
+  "mode": { "type": "segmented", "anchor": "h2" }, // 看到 h2 就切一刀
+  "items": {
+    "section_title": "h2",
+    "text": "p"
+  }
+}
+```
+
+---
+
+## 🛡️ 5. 质量控制：过滤器与筛子 (Filters & Sieves)
+
+**场景**：抓取时混入了广告、缺货提示或者不需要的垃圾项。
+
+* **`has`**：**精华过滤器**。只有包含特定子元素时才抓取。例如：`"has": ".promo-tag"` 表示只有带优惠标签的商品我才要。
+* **`exclude`**：**垃圾剔除器**。排除匹配的元素。例如：`"exclude": ".is-advertisement"`。
+* **`strict`**：**强迫症模式**。一旦发现必填项缺失，直接报错停机，而不是默默返回 `null`。
+
+---
+
+## 🧠 6. 核心进阶：边界与作用域控制 (Boundary Mastery)
+
+这是处理那些没有 ID、没有类名、结构平铺的烂网页的“手术刀”。
+
+### 6.1 顺序切片：解决“双胞胎标签”定位难题
+
+* **痛点**：网页上一排 `<span>` 或 `p`，长得一模一样。你用同一个选择器去抓，每次都只能抓到第一个。
+* **解决方案**：`relativeTo: "previous"` (相对于上一个)。
+* **原理解析**：引擎会像“读书”一样记住上次读到了哪。当第一个字段提取完后，引擎会夹个“书签”。提取下一个字段时，引擎会**从书签之后**开始找。
+* **关键点**：由于这是按顺序寻找，建议显式设置 `order: ["name", "job"]` 来确保引擎不会因为 JSON 键名的乱序而导致书签位置错乱，虽然大多数js引擎是按照对象keys的声明顺序来排序的。
+* **示例场景**：
+
+    ```html
+    <p>姓名</p> <span>张三</span>
+    <p>职位</p> <span>经理</span>
+    ```
+
+* **配置示例**：
+
+    ```json
+    {
+      "relativeTo": "previous",
+      "order": ["k1", "v1", "k2", "v2"], // 强制顺序，防止书签错位
+      "properties": {
+        "k1": "p",    // 抓到第一个 p (姓名)
+        "v1": "span", // 从 k1 之后找，抓到张三
+        "k2": "p",    // 从 v1 之后找，抓到第二个 p (职位)
+        "v2": "span"  // 从 k2 之后找，抓到经理
+      }
+    }
+    ```
+
+### 6.2 分段隔离与 LCA：筑起“逻辑围墙”
+
+* **痛点**：平铺结构中提取列表，如果没有墙，Item 1 的搜索可能会越界抓到 Item 2 的内容。
+* **解决方案**：使用 `mode: "segmented"` 配合 `anchor`。
+* **原理解析**：引擎计算两个锚点之间的“最小公共祖先 (LCA)”，并逻辑上筑起围墙，确保搜索范围死死锁在 Item 内部。
+* **示例场景**：
+
+    ```html
+    <h2 class="title">文章1</h2>
+    <p class="summary">摘要1</p>
+    <h2 class="title">文章2</h2>
+    <p class="summary">摘要2</p>
+    ```
+
+* **配置示例**：
+
+    ```json
+    {
+      "type": "array",
+      "mode": { "type": "segmented", "anchor": "h2.title" }, // 以 h2 为墙
+      "items": {
+        "title": "h2",
+        "desc": "p"
+      }
+    }
+    ```
+
+### 6.3 向上探索 (Bubble-up)：给提取一次“后悔药”
+
+* **痛点**：作用域定在卡片内部，但关键数据（如卡片 ID）在卡片外面的父容器上。
+* **解决方案**：设置 `depth` (向上回退层数) 并配合 `required`。
+* **原理解析**：
+    1. 引擎在当前范围内找必填项，没找到。
+    2. 它会根据 `depth: 1` 自动把视野“向后退一步”，退到父节点。
+    3. 在更大的视野里重新扫描，从而找齐那些“由于视野太窄而漏掉”的数据。
+* **示例场景**：
+
+    ```html
+    <div class="wrapper" data-id="ID_001">
+      <div class="content-box">
+        <h3 class="title">产品名称</h3>
+      </div>
+    </div>
+    ```
+
+* **配置示例**：
+
+    ```json
+    {
+      "selector": ".content-box", // 初始视角太窄
+      "depth": 1,                 // 允许退后一级
+      "properties": {
+        "product_id": {
+          "selector": "..",        // ".." 代表向上找父节点
+          "attribute": "data-id",
+          "required": true         // 没找到 ID 就触发向上回溯
+        },
+        "name": "h3"
+      }
+    }
+    ```
+
+---
+
+## 💡 7. 最佳实践提示
+
+1. **容器优先**：只要 HTML 里有 `.item` 这种包裹容器，永远优先选择默认的 `Nested` 模式，这是性能和稳定性最好的选择。
+2. **innerText 推荐作为首选**：在 90% 的场景下，它都比 `text` 好用，因为它拿到的数据最干净，且能自动处理换行。
+3. **遇到平铺找锚点**：当你看到一堆兄弟节点并排且没有外壳包裹时，第一时间就该想到 `segmented` + `anchor` 的组合。
+4. **善用 required 过滤空数据**：如果你抓到一个列表，有些项是空的（比如预留位），给核心字段加上 `required: true`，那些空项就会自动变成 `null`，方便你在代码里过滤。
+5. **调试必备：先看 Scope**：如果抓不到数据，先检查是不是 `selector` 写得太死，或者尝试把 `depth` 调大一点。