@isdk/web-fetcher 0.3.0 → 0.3.1

package/README.action.cn.md

@@ -245,6 +245,52 @@ await fetchWeb({
 * **`params`**: (无)
 * **`returns`**: `response`
 
+#### `mouseMove`
+
+将鼠标指针移动到指定的坐标或元素。在 `browser` 模式下，它使用 **贝塞尔曲线 (Bézier curve)** 来模拟真实人类的非线性移动轨迹，并带有轻微的抖动以增加真实感。
+
+* **`id`**: `mouseMove`
+* **`params`**:
+  * `x` (number, 可选): 绝对 X 坐标。
+  * `y` (number, 可选): 绝对 Y 坐标。
+  * `selector` (string, 可选): CSS 选择器。如果提供，鼠标将移动到该元素的中心。
+  * `steps` (number, 可选): 轨迹的中间步数（默认：`-1`）。设置为 `-1` 可根据距离动态计算步数（模拟自然移动速度）。
+* **`returns`**: `none`
+
+#### `mouseClick`
+
+在当前位置或指定坐标触发鼠标点击。如果提供了 `selector`，光标会先平滑地移动到目标元素（使用动态步数），然后再执行点击。
+
+* **`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`
+
+#### `keyboardType`
+
+模拟真人在当前获得焦点的元素中输入文本。
+
+* **`id`**: `keyboardType`
+* **`params`**:
+  * `text` (string): 要输入的文本。
+  * `delay` (number, 可选): 按键之间的延迟（毫秒，默认：100）。
+* **`returns`**: `none`
+
+#### `keyboardPress`
+
+模拟按下单个按键或组合键（例如：`Enter`, `Control+A`）。
+
+* **`id`**: `keyboardPress`
+* **`params`**:
+  * `key` (string): 按键名称（例如：`Enter`, `Tab`, `Backspace`, `ArrowUp`）。
+  * `delay` (number, 可选): 按键后的延迟（毫秒）。
+* **`returns`**: `none`
+
 #### `evaluate`
 
 在页面上下文中执行 JavaScript 函数或表达式。这是一个强大的 Action，用于执行内置 Action 未涵盖的自定义逻辑。
@@ -292,322 +338,17 @@ await fetchWeb({
 
 #### `extract`
 
-使用一个强大且声明式的 **`ExtractSchema`** 从当前页面中提取结构化数据。这是进行数据采集的核心 Action。
+使用强大且声明式的 **`ExtractSchema`** 从页面中提取结构化数据。
 
 * **`id`**: `extract`
-* **`params`**: 一个 **`ExtractSchema`** 对象, 用于定义提取规则。
-* **`returns`**: `any` (提取出的数据)
-
-##### 提取 Schema 详解
+* **`params`**: 一个 **`ExtractSchema`** 对象。
+* **`returns`**: 提取出的结构化数据。
 
-`params` 对象本身就是一个 Schema, 用于描述您想提取的数据结构。
-
-###### 1. 提取单个值
-
-最基础的提取，可以指定 **`selector`** (CSS 选择器), **`attribute`** (要提取的属性名), **`type`** (string, number, boolean, html), 以及 **`mode`** (text, innerText)。
-
-* **`depth`** (number, 可选): 在通过 `selector` 匹配到元素后, 向上回溯指定的 DOM 层级。最终回溯到的祖先元素将作为实际的值提取目标 (例如, 用于从父级包装容器中提取属性)。
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "selector": "h1.main-title",
-    "type": "string",
-    "mode": "innerText"
-  }
-}
-```
-
-> **提取模式 (Extraction Modes):**
+> **📚 详细手册**: 由于 `extract` 功能非常丰富（包含数组模式、作用域控制、锚点跳转等），我们准备了专门的详细文档：
 >
-> * **`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" }
-    }
-  }
-}
-```
-
-* **`depth`** (number, 可选): 启用“按需回溯 (Try-And-Bubble)”策略。如果在当前匹配的元素中缺少 `required` (必填) 字段，引擎会尝试向上回溯 DOM 树（最多 `depth` 层），寻找包含该必填字段的祖先元素。当选择器匹配的是后代元素（如内部 `span`），但数据位于父级容器时，此功能非常有用。
-
-**Object 进阶功能:**
-
-* **锚点跳转 (`anchor`)**: 指定该字段提取的起始参考点。
-  * **字段引用**: 引用同一对象中先前已提取的字段（使用其 DOM 元素）。
-  * **CSS 选择器**: 在当前对象作用域内即时查找锚点。
-  * **`depth`** (number, 可选): 使用锚点时，定义向上回溯多少层父节点来收集后续兄弟节点。
-    * **注意**: 如果省略，引擎默认会回溯到最大深度（直至对象根节点）以保持向后兼容。若要严格限制在锚点自身的兄弟节点内搜索，请设置 `depth: 0`。
-  * **效果**: 锚点生效后，该字段的搜索范围将变为锚点**之后**的兄弟节点（及其祖先节点，取决于 `depth`）。这允许在平铺结构中实现非线性的“跳转”提取。
-* **顺序消费 (`relativeTo: "previous"`)**:
-  * 配合 `order` 属性，使每个字段的搜索范围都从前一个字段的匹配位置之后开始。
-  * 这对于提取由多个相同标签组成的列表（如多个连续的 `<p>` 标签分别代表不同含义）至关重要。
-
-###### 3. 提取数组 (便捷用法)
-
-通过 **`type: 'array'`** 来提取一个列表。为了让最常见的操作更简单，我们提供了一些便捷用法。
-
-* **提取文本数组 (默认行为)**: 当您想提取一个文本列表时,只需提供选择器,省略 `items` 即可。这是最常见的用法。
-
-    ```json
-    {
-      "id": "extract",
-      "params": {
-        "type": "array",
-        "selector": ".tags li"
-      }
-    }
-    ```
-
-    > 上例将返回一个包含所有 `<li>` 标签文本的数组, 如 `["tech", "news"]`。
-
-* **提取属性数组 (快捷方式)**: 当您只想提取一个属性列表(例如所有链接的 **`href`**)时，也无需嵌套 `items`。直接在 `array` 定义中声明 **`attribute`** 即可。
-
-    ```json
-
-    {
-      "id": "extract",
-      "params": {
-        "type": "array",
-        "selector": ".gallery img",
-        "attribute": "src"
-      }
-    }
-    ```
-
-    > 上例将返回一个包含所有 `<img>` 标签 `src` 属性的数组。
-
-* **数组提取模式**: 在提取数组时，引擎支持不同的模式来处理各种 DOM 结构。
-
-  * **`nested`** (默认): `selector` 匹配每个项目的包裹元素。
-  * **`columnar`** (原 Zip 策略): `selector` 指向**容器**，`items` 中的字段是平行的列，按索引缝合在一起。
-  * **`segmented`**: `selector` 指向**容器**，项目通过“锚点”字段进行分段提取。
-
-###### 4. 列对齐模式 (Columnar Mode，原 Zip 策略)
-
-当 `selector` 指向一个**容器**（如结果列表）且项目数据以平行的独立列散落在其中时使用。此模式针对性能进行了深度优化，特别是在浏览器模式下，通过最小化 DOM 查询和 RPC 调用来提升速度。
-
-> **💡 广播与性能 (Broadcasting & Performance)**：如果某个属性匹配容器元素本身（例如省略 selector 或匹配容器自身的属性），其值将被**广播**到每一行。这不仅是一个功能，更是一项重大性能优化：该值仅被提取**一次**并在所有行中复用，避免了成千上万次冗余的引擎调用。
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#search-results",
-    "mode": "columnar",
-    "items": {
-      "title": { "selector": ".item-title" },
-      "link": { "selector": "a.item-link", "attribute": "href" }
-    }
-  }
-}
-```
-
-> **启发式自动检测:** 如果省略了 `mode`，且 `selector` 恰好只匹配到一个元素，同时 `items` 中包含选择器，引擎会自动使用 **columnar** 模式。
-
-**示例：列模式的广播行为 (Broadcasting)**
-
-当列表中的某些数据（如分类）位于容器上，而具体项目在容器内部时。
+> 👉 **[点击查看 Extract 操作详解](./README.action.extract.cn.md)**
 
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#book-category",
-    "mode": "columnar",
-    "items": {
-      "category": { "attribute": "data-category" },
-      "title": { "selector": ".book-title" }
-    }
-  }
-}
-```
-
-> 如果 `#book-category` 拥有 `data-category="Sci-Fi"` 属性并包含 3 本书，结果将返回 3 个项目，且每个项目都带有 `"category": "Sci-Fi"`。
-
-**Columnar 配置参数:**
-
-* **`strict`** (boolean, 默认: `true`): 如果为 `true`，当不同字段匹配到的数量不一致时将抛出错误。
-* **`inference`** (boolean, 默认: `false`): 如果为 `true`，当字段数量不匹配时，尝试通过 DOM 树自动寻找“包裹元素”来修复错位的列表。它使用经过优化的**祖先搜索算法**，在浏览器模式下比手动遍历快得多。
-* **性能备注**: 引擎会自动检测共享结构并预计算对齐方式，确保即使在复杂的 DOM 树中也能保持 O(N) 的性能。在浏览器模式下，通过预计算“广播”标志来最小化 IPC 往返开销。
-
-###### 5. 分段扫描模式 (Segmented Mode)
-
-适用于完全“平铺”且没有包裹元素的结构。它使用指定的 `anchor` 锚点来对容器内容进行分段。
-
-**核心特性：自动容器检测 (Bubble Up)**
-
-为了处理“看似平铺实则有细微容器”的结构，引擎引入了冒泡定位策略：
-
-- **智能冒泡**：当锚点深埋于嵌套结构中（如 `div.card > h3.title`），引擎会自动向上回溯，寻找在不包含相邻锚点的前提下最大的“安全容器”（如 `div.card`）。
-- **逻辑隔离**：如果找到安全容器，该容器将成为分段的作用域。这使您能够通过简单的相对选择器提取容器内的任何内容，即使它位于锚点的“上方”或深层。
-- **平铺回退**：如果锚点之间完全没有容器隔离，引擎将自动回退到传统的兄弟节点扫描模式。
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#flat-container",
-    "mode": { "type": "segmented", "anchor": "h3.item-title" },
-    "items": {
-      "title": { "selector": "h3" },
-      "desc": { "selector": "p" }
-    }
-  }
-}
-```
-
-**Segmented 配置参数:**
-
-* **`anchor`** (string):
-  * 可以是 `items` 中定义的**字段名**（如 `"title"`）。
-  * 也可以是直接的 **CSS 选择器**（如 `"h3.item-title"`）。
-  * 默认使用 `items` 中第一个字段的选择器。
-* **`depth`** (number, 可选): 从锚点向上寻找分段容器时的最大回溯层级。如果省略，它将尽可能向上冒泡，只要不与相邻分段冲突。
-* **`strict`** (boolean, 默认: `false`): 如果为 `true`，若未找到任何锚点元素，或任何项目违反了自身的 `required` 约束，将抛出错误。
-
-###### 5.1 进阶：处理重复标签 (relativeTo)
-
-当一个分段中包含多个完全相同的标签（例如连续多个 `<p>` 标签）分别代表不同字段时，可以使用 `relativeTo: "previous"` 按顺序“消耗”它们。
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#container",
-    "mode": {
-      "type": "segmented",
-      "anchor": ".item-start",
-      "relativeTo": "previous"
-    },
-    "items": {
-      "type": "object",
-      "order": ["id", "desc", "extra"],
-      "properties": {
-        "id": "h1",
-        "desc": "p",
-        "extra": "p"
-      }
-    }
-  }
-}
-```
-
-* **`relativeTo: "previous"`**: 找到 `id` (h1) 后，查找 `desc` 会从该 h1 之后开始。找到 `desc` (第一个 p) 后，查找 `extra` 会从该 p 之后开始，从而成功匹配到第二个 `<p>`。
-* **`order`**: 定义了消耗 DOM 的确切顺序。在使用 `relativeTo: "previous"` 时强烈建议显式指定。
-
-###### 6. 数据质量控制: `required` 和 `strict`
-
-- **`required`**: 将字段标记为必填。
-  - **Object 中**: 如果任何必填字段为 `null`，整个对象返回 `null`。
-  - **Array 中**: 缺失必填字段的项目会被自动跳过。
-  - **空值传播**: 对于没有 `selector` 的隐式对象，如果其所有子字段均为 `null`，则该对象本身被视为 `null`，从而触发父级的必填或跳过逻辑。
-- **`strict`**:
-  - `false` (默认): 静默跳过不完整数据。
-  - `true`: 任何必填项缺失或列模式对齐失败都将抛出错误。
-  - **继承性**: 在数组模式中设置 `strict` 会自动向下传递给所有嵌套子项。
-
-**示例：忽略缺少关键信息的项目**
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": ".product-list",
-    "mode": "columnar",
-    "items": {
-      "name": { "selector": ".title", "required": true },
-      "price": { "selector": ".price", "required": true },
-      "discount": ".promo"
-    }
-  }
-}
-```
-
-> 在此示例中，如果某个产品缺少 `name` 或 `price`，它将从结果数组中完全剔除。可选的 `discount` 字段缺失不会影响该项的保留。
-
-###### 7. 隐式对象提取 (最简语法)
-
-为了让对象提取更简单，你可以省略 `type: 'object'` 和 `properties`。如果 schema 对象包含非上下文定义关键字（如 `selector`, `has`, `exclude`, `required`, `strict`, `depth`）的键，它将被视为对象 schema，其中的键作为属性名。
-
-> **关键字冲突处理：** 您可以安全地抓取名为 `type` 的数据字段，只要它的值不是保留的 Schema 类型（如 `"string"`, `"object"`, `"array"` 等）。
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "selector": ".author-bio",
-    "name": ".author-name",
-    "type": ".author-rank",
-    "items": { "type": "array", "selector": "li" }
-  }
-}
-```
-
-> **隐式对象的核心特性：**
->
-> 1. **关键字处理**：常用的配置关键字如 `items`、`attribute` 或 `mode` **可以作为属性名**在隐式对象中使用。只有当显式存在 `type`（如 `array`）时，它们才会被视为配置项。同时，`required`、`strict` 和 `depth` 也会被当作上下文定义关键字处理。
-> 2. **字符串简写**：你可以直接使用字符串作为属性值（例如 `"email": "a.email"`），它会自动扩展为 `{ "selector": "a.email" }`。
-> 3. **上下文分离**：只有 `selector`、`has`、`exclude`、`required`、`strict` 和 `depth` 用于定义隐式对象的上下文及校验逻辑；所有其他键都被视为要提取的数据。
-> 4. **空值传递 (Null Propagation)**: 如果一个隐式对象没有 `selector`，且其所有的子属性提取结果均为 `null`，则该对象本身返回 `null`。这对于父对象的 `required` 校验或数组中的跳过逻辑至关重要。
-
-###### 8. 精确筛选: `has` 和 `exclude`
-
-您可以在任何包含 **`selector`** 的 Schema 中使用 **`has`** 和 **`exclude`** 字段来精确控制元素的选择。
-
-* **`has`**: 一个 CSS 选择器，用于确保所选元素**必须包含**匹配此选择器的后代元素。
-* **`exclude`**: 一个 CSS 选择器，用于从结果中**排除**匹配此选择器的元素。
-
-**完整示例: 提取包含图片且未被标记为"草稿"的文章链接**
-
-```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"
-        }
-      }
-    }
-  ]
-}
-```
-
-> 上述 `extract` Action 会:
->
-> 1. 找到所有 `div.article-card` 元素。
-> 2. 筛选出其中必须包含 `<img class="cover-image">` 的元素。
-> 3. 再从结果中排除掉自身带有 `.draft` 类的元素。
-> 4. 对于最终剩下的每个 `div.article-card`, 找到其后代 `a.title-link` 并提取 `href` 属性。
+---
 
 ### 通过“组合”构建高级语义 Action
 
@@ -787,7 +528,7 @@ await fetchWeb({
 * **定义**: 任何可序列化的数据结构（对象、数组、字符串等）。
 * **用途**: 业务数据提取的主要机制。
 * **用法**: 当你的动作产生处理后的业务数据（而不是代表整个页面或系统状态）时使用。
-* **系统行为**: 如果 Action 配置包含 `storeAs: "key"`，框架会自动将 `result` 保存到 `context.outputs["key"]` 中。
+* **系统行为**: 如果 Action 配置包含 `storeAs: "key"`，框架会自动将 `result` 保存到 `context.outputs["key"]` 中。如果目标键已包含一个对象且新结果也是一个对象，它们将被合并（浅合并）而不是覆盖。这允许通过多个 `extract` 动作将数据累积到同一个输出键中。
 * **典型 Action**: `extract`。
 * **示例**:
 

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` 调大一点。