@isdk/web-fetcher 0.2.0 → 0.2.2

package/README.action.cn.md

@@ -80,21 +80,21 @@ export class FillAction extends FetchAction {
 
 #### `goto`
 
-导航到新的 URL。
+将浏览器导航至指定 URL。
 
 * **`id`**: `goto`
 * **`params`**:
   * `url` (string): 要导航到的 URL。
-  * ...其他导航选项，如 `waitUntil`, `timeout`，这些选项会传递给引擎。
+  * ...其他导航选项，如 **`waitUntil`**, **`timeout`**，这些选项会传递给引擎。
 * **`returns`**: `response`
 
 #### `click`
 
-点击一个由选择器指定的元素。
+点击由 **`selector`** (CSS 选择器) 指定的元素。
 
 * **`id`**: `click`
 * **`params`**:
-  * `selector` (string): 用于标识要点击元素的 CSS 选择器或 XPath。
+  * **`selector`** (string): 用于标识要点击元素的 CSS 选择器。
 * **`returns`**: `none`
 
 #### `fill`
@@ -103,9 +103,14 @@ export class FillAction extends FetchAction {
 
 * **`id`**: `fill`
 * **`params`**:
-  * `selector` (string): 输入元素的选择器。
+  * **`selector`** (string): 输入元素的选择器。
   * `value` (string): 要填入元素中的文本。
-* **`returns`**: `none`
+* **`returns`**: `response`
+
+> **注意**：返回内容的具体行为在不同引擎之间存在差异。
+>
+> * **`cheerio`**：此引擎直接操作其内部的 HTML 表示，因此返回的内容会包含填充的值。
+> * **`playwright`**：此引擎返回的是页面的渲染后 HTML (类似于 `document.documentElement.outerHTML`)。然而，当 `page.fill()` 更新输入框时，它修改的是该输入框元素的内部 `value` 属性。这个属性不总会被序列化为 HTML 源代码中的 `value` 特性。因此，调用 `page.content()` 所返回的 HTML 中将**不会**看到填充的值。
 
 #### `submit`
 
@@ -113,28 +118,31 @@ export class FillAction extends FetchAction {
 
 * **`id`**: `submit`
 * **`params`**:
-  * `selector` (string, optional): 表单元素的选择器。
+  * **`selector`** (string, optional): 表单元素的选择器。
 * **`returns`**: `none`
 
 #### `waitFor`
 
-暂停执行以等待特定条件满足。
+暂停执行，以等待一个或多个条件的满足。
+
+在 `browser` 模式下，如果提供了多个条件，它们将按顺序依次等待。例如，它会先等待选择器出现，然后等待网络空闲，最后再等待指定的毫秒数。
 
 * **`id`**: `waitFor`
-* **`params`**: 一个指定等待条件的对象 (例如 `ms`, `selector`, `networkIdle`)。
+* **`params`**: 一个指定等待条件的对象，可包含以下一个或多个键：
+  * **`ms`** (number): 等待指定的毫秒数。两个引擎都支持。
+  * **`selector`** (string): 等待匹配的选择器出现在页面中。仅 `browser` 模式支持。
+  * **`networkIdle`** (boolean): 等待直到网络空闲（即，在一段时间内没有新的网络请求）。仅 `browser` 模式支持。
 * **`returns`**: `none`
 
 #### `pause`
 
-暂停 Action 脚本的执行，以允许用户手动介入（例如，解决验证码）。
-
-此 Action **必须**在 `fetchWeb` 的选项中提供一个 `onPause` 回调处理器。当此 Action 被触发时，它会调用 `onPause` 处理器并等待其执行完成。
+暂停 Action 脚本的执行，以允许用户手动介入（例如，解决验证码）。此 Action **必须**在 **`fetchWeb`** 的选项中提供一个 **`onPause`** 回调处理器。当此 Action 被触发时，它会调用 **`onPause`** 处理器并等待其执行完成。
 
 * **`id`**: `pause`
 * **`params`**:
-  * `selector` (string, optional): 如果提供，仅当匹配此选择器的元素存在时，Action 才会暂停。
-  * `attribute` (string, optional): 与 `selector` 配合使用。如果提供，仅当元素存在且拥有该指定属性时，Action 才会暂停。
-  * `message` (string, optional): 一个将传递给 `onPause` 处理器的消息，可用于向用户显示提示信息。
+  * **`selector`** (string, optional): 如果提供，仅当匹配此选择器的元素存在时，Action 才会暂停。
+  * **`attribute`** (string, optional): 与 **`selector`** 配合使用。如果提供，仅当元素存在且拥有该指定属性时，Action 才会暂停。
+  * **`message`** (string, optional): 一个将传递给 **`onPause`** 处理器的消息，可用于向用户显示提示信息。
 * **`returns`**: `none`
 
 **示例：在 Google 搜索中处理 CAPTCHA**
@@ -193,10 +201,10 @@ await fetchWeb({
 
 #### `extract`
 
-使用一个强大且声明式的 Schema 从当前页面中提取结构化数据。这是进行数据采集的核心 Action。
+使用一个强大且声明式的 **`ExtractSchema`** 从当前页面中提取结构化数据。这是进行数据采集的核心 Action。
 
 * **`id`**: `extract`
-* **`params`**: 一个 `ExtractSchema` 对象, 用于定义提取规则。
+* **`params`**: 一个 **`ExtractSchema`** 对象, 用于定义提取规则。
 * **`returns`**: `any` (提取出的数据)
 
 ##### 提取 Schema 详解
@@ -205,7 +213,7 @@ await fetchWeb({
 
 ###### 1. 提取单个值
 
-最基础的提取,可以指定 `selector` (CSS 选择器), `attribute` (要提取的属性名), 以及 `type` (string, number, boolean, html)。
+最基础的提取，可以指定 **`selector`** (CSS 选择器), **`attribute`** (要提取的属性名), 以及 **`type`** (string, number, boolean, html)。
 
 ```json
 {
@@ -221,7 +229,7 @@ await fetchWeb({
 
 ###### 2. 提取对象
 
-通过 `type: 'object'` 和 `properties` 字段来定义一个结构化对象。
+通过 **`type: 'object'`** 和 **`properties`** 字段来定义一个结构化对象。
 
 ```json
 {
@@ -239,7 +247,7 @@ await fetchWeb({
 
 ###### 3. 提取数组 (便捷用法)
 
-通过 `type: 'array'` 来提取一个列表。为了让最常见的操作更简单,我们提供了一些便捷用法。
+通过 **`type: 'array'`** 来提取一个列表。为了让最常见的操作更简单，我们提供了一些便捷用法。
 
 * **提取文本数组 (默认行为)**: 当您想提取一个文本列表时,只需提供选择器,省略 `items` 即可。这是最常见的用法。
 
@@ -263,7 +271,7 @@ await fetchWeb({
 
     > 上例将返回一个包含所有 `<li>` 标签文本的数组, 如 `["tech", "news"]`。
 
-* **提取属性数组 (快捷方式)**: 当您只想提取一个属性列表(例如所有链接的 `href`)时,也无需嵌套 `items`。直接在 `array` 定义中声明 `attribute` 即可。
+* **提取属性数组 (快捷方式)**: 当您只想提取一个属性列表(例如所有链接的 **`href`**)时，也无需嵌套 `items`。直接在 `array` 定义中声明 **`attribute`** 即可。
 
     ```json
 
@@ -289,10 +297,10 @@ await fetchWeb({
 
 ###### 4. 精确筛选: `has` 和 `exclude`
 
-您可以在任何包含 `selector` 的 Schema 中使用 `has` 和 `exclude` 字段来精确控制元素的选择。
+您可以在任何包含 **`selector`** 的 Schema 中使用 **`has`** 和 **`exclude`** 字段来精确控制元素的选择。
 
-* `has`: 一个 CSS 选择器,用于确保所选元素**必须包含**匹配此选择器的后代元素。
-* `exclude`: 一个 CSS 选择器,用于从结果中**排除**匹配此选择器的元素。
+* **`has`**: 一个 CSS 选择器，用于确保所选元素**必须包含**匹配此选择器的后代元素。
+* **`exclude`**: 一个 CSS 选择器，用于从结果中**排除**匹配此选择器的元素。
 
 **完整示例: 提取包含图片且未被标记为"草稿"的文章链接**
 

package/README.action.md

@@ -94,7 +94,7 @@ Clicks on an element specified by a selector.
 
 * **`id`**: `click`
 * **`params`**:
-  * `selector` (string): A CSS selector or XPath to identify the element to click.
+  * `selector` (string): A CSS selector to identify the element to click.
 * **`returns`**: `none`
 
 #### `fill`
@@ -105,7 +105,12 @@ Fills an input field with a specified value.
 * **`params`**:
   * `selector` (string): A selector for the input element.
   * `value` (string): The text to fill into the element.
-* **`returns`**: `none`
+* **`returns`**: `response`
+
+> **Note**: The behavior of the returned content differs between engines.
+>
+> * **`cheerio`**: This engine directly manipulates its internal HTML representation, so the returned content will include the filled value.
+> * **`playwright`**: This engine returns the rendered HTML of the page (similar to `document.documentElement.outerHTML`). However, when `page.fill()` updates an input, it changes the input's internal `value` property. This property is not always serialized back to the `value` attribute in the HTML source. As a result, the filled value will **not** be visible in the HTML returned by `page.content()`.
 
 #### `submit`
 
@@ -118,10 +123,15 @@ Submits a form.
 
 #### `waitFor`
 
-Pauses execution to wait for a specific condition to be met.
+Pauses execution to wait for one or more conditions to be met.
+
+In `browser` mode, if multiple conditions are provided, they are awaited sequentially. For example, it will first wait for the selector to appear, then wait for the network to be idle, and finally wait for the specified duration.
 
 * **`id`**: `waitFor`
-* **`params`**: An object specifying the wait condition (e.g., `ms`, `selector`, `networkIdle`).
+* **`params`**: An object specifying the wait condition, which can contain one or more of the following keys:
+  * **`ms`** (number): Waits for the specified number of milliseconds. Supported by both engines.
+  * **`selector`** (string): Waits for an element matching the selector to appear on the page. Supported only in `browser` mode.
+  * **`networkIdle`** (boolean): Waits until the network is idle (i.e., no new network requests for a period of time). Supported only in `browser` mode.
 * **`returns`**: `none`
 
 #### `pause`

package/README.cn.md

@@ -1,9 +1,16 @@
 # 🕸️ @isdk/web-fetcher
 
+[![npm version](https://img.shields.io/npm/v/%40isdk%2Fweb-fetcher)](https://www.npmjs.com/package/@isdk/web-fetcher)
+[![npm downloads](https://img.shields.io/npm/dw/%40isdk%2Fweb-fetcher)](https://www.npmjs.com/package/@isdk/web-fetcher)
+[![License](https://img.shields.io/github/license/isdk/web-fetcher.js)](https://github.com/isdk/web-fetcher.js/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Types%20included-3178C6?logo=typescript)](https://www.typescriptlang.org/)
+[![GitHub Stars](https://img.shields.io/github/stars/isdk/web-fetcher.js?logo=github)](https://github.com/isdk/web-fetcher.js)
+![antibot](https://img.shields.io/badge/antibot-optional-orange)
+
 [English](./README.md) | 简体中文
 
-> 一个功能强大且灵活的 Web 抓取与浏览器自动化库。
-> 它采用双引擎架构（HTTP 和浏览器）和声明式动作系统，是 AI 代理和复杂数据抓取任务的理想选择。
+> 一个面向AI的网页自动化库，它将复杂的网页交互简化为声明式JSON动作脚本。一次编写，你的脚本即可在快速的 **`http`** 模式（用于静态内容）或完整的 **`browser`** 模式（用于动态站点）下运行。可选的 **`antibot`** 标志有助于绕过检测机制。该库专为有针对性的、面向任务的数据提取而设计（例如，从页面Y获取数据X），而非用于构建全站爬虫。
 
 ---
 
@@ -137,6 +144,7 @@ searchGoogle('gemini');
 * `fill`: 用指定的值填充一个输入字段。
 * `submit`: 提交一个表单。
 * `waitFor`: 暂停执行以等待特定条件（例如，超时、选择器出现或网络空闲）。
+* `pause`: 暂停执行以进行手动干预（例如，解决验证码）。
 * `getContent`: 获取当前页面状态的完整内容（HTML、文本等）。
 * `extract`: 使用富有表现力的声明式 Schema,可轻松提取页面中的任意结构化数据。
 

package/README.hackernews.md

@@ -0,0 +1,52 @@
+### **Title:**
+
+`Show HN: I built a declarative web automation library for AI agents`
+
+---
+
+### **First Comment (Final Masterpiece Version):**
+
+GitHub: https://github.com/isdk/web-fetcher.js
+
+Hey HN,
+
+I’ve been building some AI agents lately and ran into a fundamental problem: LLMs are great at generating structured data like JSON, but they are terrible at writing the brittle, procedural JavaScript needed for web automation (`await page.click(...)`, `await page.waitFor(...)`, etc.).
+
+This led me to build `@isdk/web-fetcher`, a library designed around a few core principles to solve this mismatch.
+
+* **Declarative JSON Actions for AI:** Instead of code, you define tasks in a simple JSON "plan." This is a format an LLM can easily generate and reason about, making it a much more natural interface for an agent.
+
+* **A Unified, Dual-Engine API:** It has a fast `http` engine (using Cheerio) and a full `browser` engine (using Playwright). The key was to design a single API (with actions like `extract`, `fill`, etc.) that works across both, allowing the library to execute your plan in the most efficient way.
+
+* **Simple but Powerful Anti-Bot Evasion:** In `browser` mode, you just add `antibot: true`. Under the hood, this does more than just rotate user-agents; it meticulously equips the browser with a more convincing, human-like fingerprint—modifying TLS signatures, ordering headers correctly, and patching navigator properties to evade common commercial bot detectors. It's a complex problem solved with a single switch.
+
+To avoid reinventing the core crawling infrastructure, the library is built on top of the excellent `crawlee` library. My work was to design and implement this declarative, AI-friendly layer on top.
+
+Here’s an example of what a browser-based plan with the anti-bot flag looks like:
+
+```typescript
+// Define a plan to access a site with strong bot detection
+const plan = {
+  url: 'https://some-protected-site.com',
+  engine: 'browser',
+  antibot: true, // Just flip this switch for enhanced evasion
+  actions: [
+    { id: 'fill', params: { selector: '#search-input', value: 'Hacker News' } },
+    { id: 'click', params: { selector: '#search-button' } },
+    { id: 'waitFor', params: { selector: '#results' } },
+    {
+      id: 'extract',
+      params: {"type": "array", "selector": "#results a", "attribute": "href"},
+      storeAs: 'searchResults',
+    },
+  ]
+};
+
+const { result, outputs } = await fetchWeb(plan);
+console.log('Search finalUrl:', result?.finalUrl);
+console.log('Outputs searchResults:', outputs.searchResults);
+```
+
+The project is new, and I believe this declarative approach is a more robust path forward for building capable AI agents that can interact with the web. I'd love to hear the community's thoughts and critiques on this design.
+
+Thanks

package/README.md

@@ -1,9 +1,16 @@
 # 🕸️ @isdk/web-fetcher
 
+[![npm version](https://img.shields.io/npm/v/%40isdk%2Fweb-fetcher)](https://www.npmjs.com/package/@isdk/web-fetcher)
+[![npm downloads](https://img.shields.io/npm/dw/%40isdk%2Fweb-fetcher)](https://www.npmjs.com/package/@isdk/web-fetcher)
+[![License](https://img.shields.io/github/license/isdk/web-fetcher.js)](https://github.com/isdk/web-fetcher.js/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Types%20included-3178C6?logo=typescript)](https://www.typescriptlang.org/)
+[![GitHub Stars](https://img.shields.io/github/stars/isdk/web-fetcher.js?logo=github)](https://github.com/isdk/web-fetcher.js)
+![antibot](https://img.shields.io/badge/antibot-optional-orange)
+
 English | [简体中文](./README.cn.md)
 
-> A powerful and flexible web fetching and browser automation library.
-> It features a dual-engine architecture (HTTP and Browser) and a declarative action system, making it perfect for AI agents and complex data scraping tasks.
+> An AI-friendly web automation library that simplifies complex web interactions into a declarative JSON action script. Write your script once and run it in either a fast **`http`** mode for static content or a full **`browser`** mode for dynamic sites. An optional **`antibot`** flag helps bypass detection mechanisms. The library is designed for targeted, task-oriented data extraction (e.g., get X from page Y), not for building whole-site crawlers.
 
 ---
 
@@ -137,6 +144,7 @@ Here are the essential built-in actions:
 * `fill`: Fills an input field with a specified value.
 * `submit`: Submits a form.
 * `waitFor`: Pauses execution to wait for a specific condition (e.g., a timeout, a selector to appear, or network to be idle).
+* `pause`: Pauses execution for manual intervention (e.g., solving a CAPTCHA).
 * `getContent`: Retrieves the full content (HTML, text, etc.) of the current page state.
 * `extract`: Extracts any structured data from the page with ease using an expressive, declarative schema.
 

package/README.reddit.md

@@ -0,0 +1,248 @@
+### 推荐的 Reddit 频道 (Subreddits)
+
+根据项目特点,最适合发布此帖子的社区是:
+
+1.  **r/webscraping**: 这是最直接相关的社区。这里的用户会非常欣赏其双引擎架构和反机器人侦测功能。
+2.  **r/javascript**: 这是一个庞大的 JavaScript 开发者社区。由于这是一个 npm 库,在这里发布可以获得广泛的关注。
+3.  **r/ArtificialIntelligence**: 鉴于该库明确为 AI 代理设计,这个社区的成员会对“声明式 JSON 工作流”等特性特别感兴趣,因为这使得 AI 可以轻松生成和执行自己的自动化脚本。
+4.  **r/programming**: 一个更广泛的编程社区,适合分享技术含量高的新项目。
+
+---
+
+### Reddit 帖子草稿
+
+**标题:** 我为 AI 代理构建了一个 Web 自动化库,它拥有双引擎(快速 HTTP + 完整浏览器)和声明式操作!
+
+**正文:**
+
+大家好,
+
+我非常激动地想和大家分享我最近一直在开发的一个项目: **`@isdk/web-fetcher`**。
+
+在构建需要与 web 交互的 AI 代理或复杂的 web scraper 时,我们常常需要编写脆弱、命令式的代码来处理导航、点击和数据提取。这个过程不仅繁琐,而且难以维护。
+
+`@isdk/web-fetcher` 就是为了解决这个问题而生的。它是一个功能强大且灵活的 web 抓取和浏览器自动化库,其核心是为 AI 应用和高级数据抓取任务而设计的。
+
+---
+
+#### 🤔 为什么要造这个轮子?
+
+你可能会想:“为什么不直接用 `fetch` 或者 Playwright 呢?”
+
+*   **`fetch` 的局限**: `fetch` API 非常适合请求 API 或获取静态 HTML,但对于现代的、由 JavaScript 动态渲染内容的网站(比如单页应用 SPA)就无能为力了。你拿到手的只是一堆不含实际内容的模板代码。
+*   **Playwright 不够“开箱即用”**: 虽然 Playwright 很强大,但直接使用它意味着你需要自己处理很多额外的工作。比如:
+    *   **反爬虫措施**: 很多网站有 Cloudflare 等反机器人机制,需要复杂的策略来绕过。
+    *   **登录与会话**: 获取某些内容前必须登录,你需要手动管理登录流程和会话状态。
+    *   **代码冗余**: 大量的配置和重复的交互逻辑代码会迅速膨胀。
+
+`@isdk/web-fetcher` 在这些工具之上构建了一个更高层次的抽象,旨在提供一个既强大又易于使用的统一接口,让你可以专注于业务逻辑,而不是底层的实现细节。
+
+---
+
+#### ✨ 核心功能:
+
+*   **⚙️ 双引擎架构**: 你可以根据任务需求选择合适的引擎。使用 **`http` 模式** (基于 Cheerio) 在静态网站上实现闪电般的速度,或者切换到 **`browser` 模式** (基于 Playwright) 来处理需要完整 JavaScript 执行的动态网站。
+*   **📜 声明式操作脚本**: 你可以用简单、可读的 JSON 格式定义复杂的多步骤工作流(如登录、填写表单、点击按钮)。这使得 AI 代理可以动态生成自己的自动化脚本。
+*   **📊 强大的数据提取**: 通过一个直观且富有表现力的声明式 Schema,可以轻松提取从简单文本到复杂嵌套对象的各种结构化数据。
+*   **🛡️ 反机器人侦测**: 在 `browser` 模式下,一个可选的 `antibot` 标志可以帮助你绕过像 Cloudflare 这样的常见反机器人措施。
+*   **🧩 可扩展**: 你可以轻松创建自定义的、高级别的“复合”操作来封装可复用的业务逻辑(例如,一个 `login` 动作)。
+
+---
+
+#### 🚀 快速上手
+
+下面是一个简单的例子,展示了如何抓取一个网页并提取其标题:
+
+```typescript
+import { fetchWeb } from '@isdk/web-fetcher';
+
+async function getTitle(url: string) {
+  const { outputs } = await fetchWeb({
+    url,
+    actions: [
+      {
+        id: 'extract',
+        params: {
+          // 提取 <title> 标签的文本内容
+          selector: 'title',
+        },
+        // 将结果存储在 outputs 对象的 'pageTitle' 键下
+        storeAs: 'pageTitle',
+      },
+    ],
+  });
+
+  console.log('Page Title:', outputs.pageTitle);
+}
+
+getTitle('https://www.google.com');
+```
+
+---
+
+#### 🤖 高级用法: 多步骤表单提交
+
+这个例子演示了如何使用 `browser` 引擎在 Google 上执行搜索。
+
+```typescript
+import { fetchWeb } from '@isdk/web-fetcher';
+
+async function searchGoogle(query: string) {
+  const { result } = await fetchWeb({
+    url: 'https://www.google.com',
+    engine: 'browser', // 使用完整的浏览器引擎进行交互
+    actions: [
+      // 初始导航由 url 选项处理
+      { id: 'fill', params: { selector: 'textarea[name=q]', value: query } },
+      { id: 'submit', params: { selector: 'form' } },
+      { id: 'waitFor', params: { selector: '#search' } }, // 等待搜索结果容器出现
+    ]
+  });
+
+  console.log('搜索结果 URL:', result?.finalUrl);
+}
+
+searchGoogle('gemini');
+```
+
+---
+
+#### 🌱 项目状态与未来展望
+
+这个项目刚刚出炉,我们已经搭建好了一个坚实且高度可扩展的核心架构,并提供了上述所有基本功能。
+
+当然,它还有一些待完善的地方。我们接下来的一个重要目标是实现更智能的抓取策略,比如 **能够根据目标网站的特点自动选择最佳的抓取方式** (例如,自动从 `http` 模式升级到 `browser` 模式)。
+
+---
+
+这个项目是开源的,你可以在 NPM 和 GitHub 上找到它。
+
+*   **NPM:** `npm install @isdk/web-fetcher`
+*   **GitHub:** [链接到你的 GitHub 仓库]
+
+欢迎大家试用并提出宝贵的反馈!我很想听听你们的想法。
+
+
+------------------------------
+
+
+好的，这是一个非常重要的信息！透露你使用了像 `crawlee` 这样成熟的库作为底层，可以极大地增强你项目的可信度。这表明你没有“重复造轮子”，而是在一个坚实的基础上构建了一个更高层次的抽象。这在技术社区里是一个非常积极的信号。
+
+我会将这一点巧妙地融入帖子中，让它成为一个加分项。
+
+---
+
+这是更新后的版本，它强调了你的库是如何站在巨人肩膀上的：
+
+### **Title: I built a web automation library for AI agents so they can browse the web like a human, not a bot.**
+
+Hey everyone,
+
+Ever tried to make an AI agent *actually use* a website? You quickly run into a wall of pain.
+
+You're not trying to crawl an entire domain like a traditional scraper. You want your agent to perform a specific task: log in, find a price, fill out a form, and get the result. But this means writing brittle, imperative code (`page.waitForSelector()`, `page.click()`, `page.evaluate()`, repeat) that breaks the moment a UI element changes.
+
+I've been building AI agents and got deeply frustrated by this. So, I created a solution: **`@isdk/web-fetcher`**.
+
+It’s a library designed to give agents a "browser on a leash"—a way to perform targeted, human-like actions on the web without the messy implementation details.
+
+---
+
+### 🤔 "Why not just use Playwright or Crawlee?"
+
+Great question, and the answer gets to the heart of this project. I'm a huge fan of not reinventing the wheel, which is why **this library uses the incredible `crawlee` library under the hood.**
+
+*   **The Low-Level Tools (`fetch`, Playwright):** `fetch` is for static content, and Playwright is a fantastic browser control tool. But using it directly is like being given a box of engine parts and told to build a car.
+*   **The Powerful Framework (`crawlee`):** `crawlee` is a massive step up. It solves huge problems like request queuing, proxy management, and browser pooling. It's the robust engine and chassis for our car.
+*   **The Missing Piece (My Library):** Even with `crawlee`, you often still need to write *imperative, procedural code* to define *what* happens on the page. Your agent's logic gets mixed up with `page.click()` and `page.fill()`.
+
+`@isdk/web-fetcher` is the final layer: **the simple, declarative dashboard for the car.** It sits on top of `crawlee`'s power and provides a JSON-based instruction set. This allows an AI to easily generate a "plan" of what to do, without worrying about the implementation.
+
+So, it's not a replacement; it's an abstraction layer specifically for **agent-driven automation**.
+
+---
+
+### ✨ Core Features: What Makes It Different?
+
+*   **⚙️ Dual-Engine Architecture (via Crawlee):** Choose your weapon. Use the blazing-fast **`http` mode** for simple sites, or the full-featured **`browser` mode** for complex, interactive web apps.
+*   **📜 Declarative Action Scripts:** This is the key for AI. Instead of code, you define multi-step tasks (log in, search, extract) in simple JSON. **This means an AI agent can dynamically generate its own automation plans.**
+*   **📊 Clean, Declarative Data Extraction:** Define the data you want with a simple schema. No more wrestling with DOM traversal in your application code.
+*   **🛡️ Built-in Anti-Bot Evasion:** By leveraging `crawlee`'s capabilities, a simple `antibot: true` flag helps navigate common bot detection hurdles like Cloudflare.
+*   **🧩 Extensible by Design:** Bundle complex sequences into your own high-level actions. For example, create a single, reusable `loginToGitHub` action that encapsulates the entire login flow.
+
+---
+
+### 🚀 Quick Start: Grab a Page Title
+
+Here’s how simple it is. The library handles the engine choice and execution.
+
+```typescript
+import { fetchWeb } from '@isdk/web-fetcher';
+
+async function getTitle(url: string) {
+  const { outputs } = await fetchWeb({
+    url,
+    actions: [
+      {
+        id: 'extract',
+        params: {
+          // Tell it to grab the text from the <title> tag
+          selector: 'title',
+        },
+        // Store the result under the 'pageTitle' key
+        storeAs: 'pageTitle',
+      },
+    ],
+  });
+
+  console.log('Page Title:', outputs.pageTitle);
+}
+
+getTitle('https://news.ycombinator.com');
+```
+
+---
+
+### 🤖 Advanced Example: A Human-like Task (Google Search)
+
+This shows how an agent could perform a search. Notice we're just *describing* the steps.
+
+```typescript
+import { fetchWeb } from '@isdk/web-fetcher';
+
+async function searchGoogle(query: string) {
+  const { result } = await fetchWeb({
+    url: 'https://www.google.com',
+    engine: 'browser', // We need a real browser for this
+    actions: [
+      // Step 1: Fill the search bar
+      { id: 'fill', params: { selector: 'textarea[name=q]', value: query } },
+      // Step 2: Submit the form (like pressing Enter)
+      { id: 'submit', params: { selector: 'form' } },
+      // Step 3: Wait for search results to appear
+      { id: 'waitFor', params: { selector: '#search' } },
+    ]
+  });
+
+  console.log('Search Results URL:', result?.finalUrl);
+}
+
+searchGoogle('Gemini vs. GPT-4');
+```
+
+---
+
+### 🌱 Project Status & The Road Ahead
+
+This project is fresh out of the oven. The core architecture is solid, and the features above are ready to use.
+
+My next big goal is to make it even smarter. I want to implement a strategy where it can **automatically upgrade from `http` to `browser` mode** if it detects that a simple request isn't enough to get the job done.
+
+---
+
+The project is open source and I'd be thrilled for you to check it out, give it a spin, and share your feedback.
+
+*   **NPM:** `npm install @isdk/web-fetcher`
+*   **GitHub:** [https://github.com/isdk/web-fetcher.js](https://github.com/isdk/web-fetcher.js)
+
+I’m really excited to hear what you think and what you might build with it. Thanks for reading

package/README.v2ex.md

@@ -0,0 +1,109 @@
+非常好！这个补充说明是项目的核心亮点之一，必须在帖子里清晰地强调出来。这正是区分你的库和简单封装的关键所在：**提供一个跨引擎的、统一的抽象层**。
+
+我会将这一点融入到 V2EX 帖子中，让技术用户一眼就能看出这个设计的精妙之处。
+
+---
+
+这是更新后的 V2EX 帖子最终版：
+
+#### **标题 (推荐):**
+
+`[自荐] 做了一个为 AI 代理设计的 Web 自动化库：统一 API 驱动双引擎，让 AI 像人一样浏览网页。`
+
+*(这个标题直接点出了“统一 API”和“双引擎”两个核心技术点)*
+
+---
+
+#### **正文:**
+
+大家好，
+
+最近一直在折腾 AI Agent，发现让 Agent 可靠地与 Web 交互是个大难题，现有工具要么太底层，要么不够灵活。所以动手撸了一个轮子： **`@isdk/web-fetcher`**，想和大家分享一下，也希望能得到一些反馈。
+
+* **GitHub:** `https://github.com/isdk/web-fetcher.js`
+* **NPM:** `npm install @isdk/web-fetcher`
+
+
+#### 解决了什么痛点？
+
+你可能会问，为啥不用 `fetch` 或 Playwright/Crawlee？
+
+* `fetch` 拿不到 JS 动态渲染的内容，对现代网页基本没用。
+* Playwright 虽然强大，但需要写大量命令式的过程代码 (`await page.click(...)` 等)，不仅繁琐，而且 AI (比如 LLM) 很难直接生成这种复杂的逻辑。
+
+我不想重复造轮子，所以**底层用了`Crawlee` 库**来处理。
+
+我的目标是在 `Crawlee` 之上构建一个跨引擎一致性：抽象/模拟 HTTP 与 Browser 的共有行为，**声明式的“意图层”**，让 AI 可以通过生成简单的 JSON 来“指挥”浏览器完成任务，而不是去写具体的执行代码。
+
+#### 核心功能
+
+* **⚙️ 双引擎架构**: 你可以选择 `http` 模式（基于 Cheerio）来极速抓取静态内容，也可以用 `browser` 模式（基于 Playwright）来处理复杂的动态网页。
+* **✨ 统一的操作模型 (核心设计)**: 这是最关键的一点。**我抽象了 `http` 和 `browser` 模式下的共性行为**。无论底层用哪个引擎，你都使用同一套 `actions` API。比如 `extract` (提取数据) 这个操作，在 `http` 模式下它会通过 Cheerio 解析静态 HTML，在 `browser` 模式下它会操作浏览器渲染后的 DOM。**你只需要学习一套 API，库在内部完成了适配和翻译**。
+* **📜 声明式操作脚本**: 基于统一的模型，你可以用 JSON 定义一个多步骤任务流（登录、填表、点击），AI 生成这个 JSON 的成本远低于生成 JS 代码。
+* **📊 强大的数据提取**: 同样是声明式的 Schema，轻松从页面提取结构化数据。
+* **🛡️ 内置反爬**: `browser` 模式下开启 `antibot: true`，能处理一些常见的 Cloudflare 挑战。
+* **🧩 易于扩展**: 可以自己封装常用的操作，比如把“登录知乎”封装成一个 `loginToZhihu` 的自定义动作。
+
+---
+
+#### 快速上手：提取个标题
+
+注意，下面的代码不关心目标 URL 是静态还是动态的，`extract` 操作在两种模式下都有效。
+
+```typescript
+import { fetchWeb } from '@isdk/web-fetcher';
+
+async function getTitle(url: string) {
+  const { outputs } = await fetchWeb({
+    url,
+    actions: [
+      {
+        id: 'extract',
+        params: {
+          selector: 'title', // 提取 <title> 标签内容
+        },
+        storeAs: 'pageTitle', // 结果存到 outputs.pageTitle
+      },
+    ],
+  });
+
+  console.log('页面标题:', outputs.pageTitle);
+}
+
+getTitle('https://www.v2ex.com');
+```
+
+#### 进阶玩法：多步表单提交 (Google 搜索)
+
+这个例子展示了如何用 JSON 指挥浏览器执行一系列动作。
+
+```typescript
+import { fetchWeb } from '@isdk/web-fetcher';
+
+async function searchGoogle(query: string) {
+  const { result } = await fetchWeb({
+    url: 'https://www.google.com',
+    engine: 'browser', // 显式指定需要浏览器环境
+    actions: [
+      // 步骤 1: 找到输入框并填入内容
+      { id: 'fill', params: { selector: 'textarea[name=q]', value: query } },
+      // 步骤 2: 提交表单
+      { id: 'submit', params: { selector: 'form' } },
+      // 步骤 3: 等待搜索结果容器加载出来
+      { id: 'waitFor', params: { selector: '#search' } },
+    ]
+  });
+
+  console.log('搜索结果页 URL:', result?.finalUrl);
+}
+
+searchGoogle('V2EX');
+```
+
+---
+
+#### 项目状态
+
+项目刚起步，核心架构已经搭好。下一步计划是实现更智能的抓取策略（比如发现 http 模式拿不到内容时，自动升级到 browser 模式）。
+
+项目是开源的，欢迎大家试用、Star、提 Issue，或者狠狠地拍砖！感谢。