项目概述

AgentQL 由 tinyfish-io 团队开发，旨在解决传统网页自动化和爬虫技术中的核心痛点：UI 变化导致的脚本失效问题。传统的网页抓取方案通常依赖固定的 DOM 选择器，一旦网站更新界面结构，爬虫脚本就会中断。AgentQL 采用自然语言理解的方式定位页面元素，即使网页布局发生变化，只要语义内容保持一致，查询仍然有效。资料来源：README.md

该项目的设计理念是让 AI 代理能够像人类用户一样理解和使用网页，通过智能定位器（Smart Locator）和数据查询 API 实现网页元素的自动发现与数据提取。资料来源：examples/python/first_steps/main.py:1-20

核心功能特性

自然语言选择器

AgentQL 的核心优势在于使用自然语言描述来定位页面元素。开发者无需编写复杂的 CSS 选择器或 XPath，只需用人类可读的查询语句描述所需元素，系统即可自动识别匹配的 DOM 节点。资料来源：README.md

这种设计带来了三个显著优势：

• 跨站点兼容性：相同的查询可以用于结构相似但具体实现不同的网站
• UI 变化自愈能力：页面结构改变时，只要语义内容保留，查询依然有效
• 降低学习成本：非前端专业的开发者也能轻松编写网页交互脚本

结构化数据输出

AgentQL 支持在查询中定义期望的数据结构，系统会自动将提取的数据映射到预定义的格式中。通过查询语言可以指定字段类型转换，例如将价格字符串转换为整数。资料来源：examples/python/first_steps/main.py:28-35

示例查询展示了如何提取产品列表数据：

{
    price_currency
    products[] {
        name
        price(integer)
    }
}

此查询会返回包含货币类型、产品名称数组和整数类型价格的数据结构。资料来源：examples/python/first_steps/main.py:28-35

转换与提取能力

除了基本的数据提取，AgentQL 还支持在查询过程中对数据进行即时转换处理。开发者可以在查询语句中指定数据类型转换规则，实现数据清洗和格式统一。资料来源：README.md

SDK 工具矩阵

AgentQL 提供多语言 SDK 支持，涵盖主流开发环境：

资料来源：README.md

Playwright 集成

AgentQL 与 Playwright 深度集成，为 Python 和 JavaScript 提供统一的操作接口。通过 agentql.wrap() 方法可以将 Playwright 的 Page 对象包装为支持自然语言查询的增强版本。资料来源：examples/python/first_steps/main.py:50-52

page = agentql.wrap(browser.new_page())

集成架构允许开发者同时使用 Playwright 的底层控制能力和 AgentQL 的智能查询功能。资料来源：examples/python/first_steps/main.py:1-15

API 方法体系

AgentQL 提供两类核心查询方法：

资料来源：examples/python/first_steps/main.py:56-70

使用模式与示例

列表数据查询

列表查询是 AgentQL 最常见的应用场景之一，适用于商品列表、搜索结果、表格数据等需要批量提取的场景。资料来源：examples/python/list_query_usage/README.md

该模式的工作流程如下：

1. 定义查询语句，指定列表字段结构
2. 调用 query_data() 方法执行查询
3. 处理返回的结构化数组数据

分页数据采集

AgentQL 支持跨页数据采集场景。典型实现包括导航到分页页面、执行查询、点击下一页、重复采集的循环逻辑。资料来源：examples/js/collect-paginated-news-headlines/README.md

// JavaScript 分页采集示例结构
const headlines = [];
for (let page = 0; page < totalPages; page++) {
    const data = await page.queryData(NEWS_QUERY);
    headlines.push(...data.headlines);
    await page.click('.next-button');
}

表单自动填写

通过 AgentQL 的元素定位能力，可以自动化完成表单填写和提交操作。查询语句精确定位各个输入框和按钮，Playwright API 执行实际的交互动作。资料来源：examples/js/submit-form/README.md

此模式常用于：

• 用户注册自动化
• 登录流程处理
• 在线调查问卷填写
• 多步骤向导表单

情感分析集成

AgentQL 可与外部 AI 模型集成，实现更高级的数据处理能力。典型架构是将 AgentQL 用于评论数据提取，随后将结果发送给 OpenAI 等大语言模型进行情感分析。资料来源：examples/python/perform_sentiment_analysis/README.md

# 数据提取 + 情感分析流程
comments = page.query_data(COMMENTS_QUERY)
sentiment = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": f"Analyze: {comments}"}]
)

系统架构

AgentQL 的整体架构可分为四个层次：

graph TD
    A[用户查询层] --> B[AgentQL 查询引擎]
    B --> C[智能定位器]
    C --> D[Playwright 浏览器控制]
    B --> E[数据提取器]
    E --> F[结构化输出]
    
    G[LLM 集成层] --> B
    H[REST API 层] --> B

典型应用场景

电商数据采集

AgentQL 可用于从电商网站提取商品信息、价格、库存状态等数据。由于其跨站点兼容性，同一套查询语句经过适当调整后可应用于多个电商平台。资料来源：examples/python/first_steps/main.py:1-100

社交媒体监控

结合分页采集功能，AgentQL 能够监控社交媒体平台上的帖子、评论和用户互动数据。与情感分析模型结合，可构建舆情监控系统。资料来源：examples/js/collect-youtube-comments/README.md

AI Agent 网页交互

AgentQL 的设计初衷是让 AI Agent 能够自主操作网页。通过自然语言指令，Agent 可以搜索信息、填写表单、点击按钮，执行复杂的网页任务序列。资料来源：README.md

框架集成

AgentQL 提供与主流 Agent 框架和自动化工具的集成能力：

资料来源：README.md

Cloudflare Workers 环境

社区反馈表明，有用户尝试在 Cloudflare 的 Browser Rendering 环境中使用 AgentQL JavaScript SDK。该环境基于 Playwright 构建，但由于边缘计算的特殊限制，可能需要额外的适配工作。资料来源：AgentQL (JS) x Cloudflare's Browser Rendering #128

社区与资源

示例代码库

项目中包含了丰富的示例代码，涵盖 Python 和 JavaScript 两大生态：

资料来源：examples/examples.md

调试工具

官方提供了 AgentQL Debugger Chrome 扩展程序，允许开发者在浏览器中实时测试和调试查询语句。该工具对于理解查询匹配逻辑和优化查询性能非常有帮助。资料来源：examples/python/list_query_usage/README.md

文档资源

技术优势分析

与传统网页抓取方案相比，AgentQL 具有以下技术优势：

已知限制与注意事项

元素定位精度

社区反馈表明，在某些复杂页面结构中，查询可能返回语义相近但非目标的元素。例如，页面中包含多个视觉相似的 <span> 元素时，查询可能解析到错误的目标。资料来源：querying element resolved as useless span #121

建议在使用 get_by_prompt() 方法后验证返回元素是否正确：

element = page.get_by_prompt("提交按钮")
if element:
    element.click()

边缘环境限制

JavaScript SDK 在 Cloudflare Workers 等边缘计算环境中使用时，由于 Node.js API 的部分限制，可能需要额外的配置或替代方案。资料来源：AgentQL (JS) x Cloudflare's Browser Rendering #128

快速开始指南

安装步骤

Python SDK 安装：

pip install agentql

JavaScript SDK 安装：

npm install agentql

基础使用流程

1. 导入并初始化：使用 agentql.wrap() 包装 Playwright Page 对象
2. 编写查询语句：使用 GraphQL 风格的查询定义目标和数据结构
3. 执行查询：调用 query_elements()、query_data() 或 get_by_prompt()
4. 交互操作：使用返回的定位器执行点击、输入等操作
5. 数据处理：解析返回的结构化数据

资料来源：examples/python/first_steps/main.py:50-85

发展趋势

AgentQL 正在扩展其生态系统的覆盖范围，包括与更多 AI Agent 框架的深度集成、MCP（Model Context Protocol）服务器的完善，以及针对企业级用例的功能增强。资料来源：Monetize AgentQL with run.pay #153

项目团队也在积极听取社区反馈，持续优化查询解析算法以提高定位精度，并为复杂应用场景提供更多最佳实践指南。

概述

AgentQL 是一个用于从网页中提取数据和自动化网页交互的工具套件，通过自然语言查询语言连接 LLMs 和 AI Agents 与整个互联网。该项目提供 Python SDK 和 JavaScript SDK，可与 Playwright 无缝集成，支持跨网站兼容性、结构化输出、自然语言选择器以及 UI 变化自愈能力。

本文档将帮助用户在 5 分钟内快速上手 AgentQL，完成从安装到运行第一个脚本的全流程。

概述

AgentQL Python SDK 是连接 LLM 和 AI Agent 与网页的核心工具库。该 SDK 通过扩展 Playwright 的 Page 对象，提供了一套声明式的查询语言和 API，使开发者能够以自然、灵活的方式从网页中提取数据并与之交互。

Python SDK 的核心价值在于：

• 自然语言选择器：使用类似 GraphQL 的查询语言定位页面元素
• 结构化输出：查询结果直接映射为 Python 字典数据结构
• 跨站点兼容：同一查询可适用于具有相似结构的多个网站
• UI 变化适应性：查询具有自愈能力，能应对页面结构的微小变化

资料来源：README.md

核心概念与架构

SDK 在整体架构中的位置

graph TD
    A[开发者代码] --> B[AgentQL Python SDK]
    B --> C[Playwright API]
    C --> D[浏览器实例]
    D --> E[目标网页]
    
    F[AgentQL 查询语言] --> B
    G[自然语言提示] --> B

AgentQL Python SDK 建立在 Playwright 之上，通过 wrap() 方法将标准的 Playwright Page 对象转换为增强版对象，从而获得 AgentQL 特有的查询能力。

资料来源：examples/python/first_steps/main.py:16-17

安装与基础配置

环境要求

安装步骤

pip install agentql
playwright install chromium

基础导入

import agentql
from agentql.ext.playwright.sync_api import Page
from playwright.sync_api import sync_playwright

资料来源：examples/python/first_steps/main.py:1-10

核心 API

1. 包装 Page 对象

使用 agentql.wrap() 将 Playwright Page 对象转换为支持 AgentQL API 的对象：

page = agentql.wrap(browser.new_page())

这是使用所有 AgentQL 特性的前提条件。包装后的 page 对象保留了 Playwright 的所有原生方法，同时新增了 AgentQL 特有的查询方法。

资料来源：examples/python/first_steps/main.py:33-34

2. 查询数据 (query_data)

query_data() 方法是 SDK 最核心的功能，用于从页面中提取结构化数据：

data = page.query_data(PRODUCT_DATA_QUERY)

查询语法示例：

{
    price_currency
    products[] {
        name
        price(integer)
    }
}

查询结果直接返回 Python 字典：

{
    'price_currency': '$',
    'products': [
        {'name': 'Bulbasaur', 'price': 5},
        {'name': 'Charmander', 'price': 6}
    ]
}

特点说明：

• 使用 [] 语法表示数组/列表
• 可以指定数据类型转换如 (integer)
• 支持嵌套对象结构

资料来源：examples/python/first_steps/main.py:25-35

3. 查询元素 (query_elements)

query_elements() 用于定位 DOM 元素，返回元素对象后可使用 Playwright API 进行交互：

response = page.query_elements(SEARCH_BOX_QUERY)
response.search_product_box.type(search_key_word, delay=200)

此方法返回的是一个包含查询字段的响应对象，每个字段对应一个可交互的 Playwright 元素。

资料来源：examples/python/first_steps/main.py:63-67

4. 自然语言提示定位 (get_by_prompt)

get_by_prompt() 是 AgentQL 的独特功能，允许使用自然语言描述来定位元素：

qwilfish_page_btn = page.get_by_prompt("Button to display Qwilfish page")
qwilfish_page_btn.click()

这种方法特别适合定位难以用传统选择器描述的按钮或链接。底层由 LLM 驱动，能够理解语义化的描述。

资料来源：examples/python/first_steps/main.py:79-83

同步与异步 API

同步版本

适用于简单的脚本和批量处理场景：

from playwright.sync_api import sync_playwright

with sync_playwright() as playwright:
    browser = playwright.chromium.launch(headless=True)
    page = agentql.wrap(browser.new_page())
    page.goto(URL)
    data = page.query_data(QUERY)

资料来源：examples/python/list_query_usage/main.py:1-19

异步版本

适用于高性能并发场景：

from playwright.async_api import async_playwright

async with async_playwright() as p:
    browser = await p.chromium.launch(headless=True)
    page = await agentql.wrap_async(browser.new_page())
    await page.goto(URL)
    data = await page.query_data(QUERY)

异步 API 使用 agentql.wrap_async() 进行包装，并通过 await 处理所有操作。

资料来源：examples/python/news-aggregator/main.py:1-35

并发执行模式

异步版本支持高效的多标签页并发抓取：

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        context = await browser.new_context()
        await asyncio.gather(
            *(fetch_data(context, url) for url in WEBSITE_URLS)
        )

async def fetch_data(context, session_url):
    page = await agentql.wrap_async(context.new_page())
    await page.goto(session_url)
    data = await page.query_data(QUERY)

资料来源：examples/python/news-aggregator/main.py:19-37

常见使用场景

场景一：电商数据采集

从电商网站提取产品列表和价格信息：

URL = "https://scrapeme.live/shop"

QUERY = """
{
    products[] {
        name
        price(integer)
    }
}
"""

page.goto(URL)
response = page.query_data(QUERY)

with open("product_data.csv", "w") as f:
    f.write("Name, Price\n")
    for product in response["products"]:
        f.write(f"{product['name']},{product['price']}\n")

资料来源：examples/python/list_query_usage/main.py:1-33

场景二：价格比较

从不同电商平台获取同一商品的价格进行比较：

PRODUCT_INFO_QUERY = """
{
    nintendo_switch_price
}
"""

page.goto(NINTENDO_URL)
nintendo_price = page.query_data(PRODUCT_INFO_QUERY)
print("Price at Nintendo:", nintendo_price["nintendo_switch_price"])

page.goto(TARGET_URL)
target_price = page.query_data(PRODUCT_INFO_QUERY)
print("Price at Target:", target_price["nintendo_switch_price"])

资料来源：examples/python/compare_product_prices/main.py:1-45

场景三：本地商家信息采集

QUERY = """
{
    listings[] {
        name
        rating
        description
        order_link
        take_out_link
        address
        hours
    }
}
"""

page.goto(URL)
response = page.query_data(QUERY)

with open("map_data.csv", "w") as f:
    f.write("Name, Rating, Description, Order Link, Take Out Link, Address, Hours\n")
    for listing in response["listings"]:
        f.write(f"{listing['name']},{listing['rating']},...")

资料来源：examples/python/maps_scraper/main.py:1-45

场景四：分页数据采集

QUERY = """
{
    items[] {
        published_date
        entry
        author
        outlet
        url
    }
}
"""

for page_num in range(num_pages):
    page.goto(f"{BASE_URL}?page={page_num}")
    data = page.query_data(QUERY)
    all_items.extend(data["items"])

资料来源：examples/python/news-aggregator/main.py:10-25

查询语言详解

AgentQL 查询语法特点

类型转换

支持的类型转换包括：

• integer：转换为整数
• float：转换为浮点数
• string：确保为字符串

语义提示

通过括号内的提示文本帮助 LLM 理解查询意图：

{
    search_product_box
    published_date(convert to XX/XX/XXXX format)
}

资料来源：examples/python/news-aggregator/main.py:10-25

已知限制与常见问题

元素定位不准确

社区反馈中提到了元素被解析为无用的 span 而非预期元素的问题：

Issue #121: 使用 AgentQL 查询时，元素被解析为无用的 span 而非预期的目标元素

这通常发生在页面结构复杂或元素语义不明确时。解决方案包括：

1. 使用更具体的自然语言提示
2. 结合 Playwright 原生选择器进行二次筛选
3. 使用 query_elements() 获取元素后再通过 Playwright API 精确定位

Cloudflare 边缘环境兼容

Issue #128 报告了在 Cloudflare Workers 边缘环境中使用 SDK 时遇到的问题：

Cloudflare 的 Browser Rendering 支持 Playwright，但在边缘环境中存在某些 Node.js API 兼容性问题

对于边缘计算场景，建议使用标准环境部署。

数据模型

常见响应结构

# 单对象查询
{
    "field1": "value1",
    "field2": "value2"
}

# 列表查询
{
    "items": [
        {"name": "Item 1", "price": 100},
        {"name": "Item 2", "price": 200}
    ]
}

文件输出模型

常见的数据持久化模式：

CSV_FILE_PATH = "output.csv"

with open(CSV_FILE_PATH, "w", encoding="utf-8") as file:
    file.write("Header1, Header2, Header3\n")
    for item in data["items"]:
        file.write(f"{item['field1']},{item['field2']},{item['field3']}\n")

资料来源：examples/python/news-aggregator/main_sync.py:45-58

最佳实践

1. 选择合适的 API 版本

2. 错误处理

try:
    page.goto(URL, timeout=30000)
    data = page.query_data(QUERY)
except Exception as e:
    log.error(f"Failed to fetch data: {e}")
    return None

3. 性能优化

• 使用浏览器上下文复用减少启动开销
• 并发执行多个页面操作
• 设置合理的超时时间

4. 查询优化

• 使用具体的字段名称而非通配符
• 避免过度嵌套的查询结构
• 利用类型转换减少后处理需求

总结

AgentQL Python SDK 通过简洁直观的 API 设计，将复杂的网页交互和数据提取任务简化为声明式的查询操作。无论是简单的单页采集还是复杂的多源数据聚合，开发者都能利用这套工具高效完成任务。SDK 与 Playwright 的深度整合确保了良好的浏览器控制能力，而 AgentQL 查询语言则为跨站点兼容性和 UI 变化适应性提供了技术保障。

概述

JavaScript SDK 是 AgentQL 为 Node.js 环境提供的官方开发工具包，使开发者能够在 JavaScript/TypeScript 项目中使用 AgentQL 的自然语言查询能力来自动化网页操作和数据提取。该 SDK 与 Playwright 无缝集成，继承了 Playwright 的全部浏览器控制功能，同时通过 AgentQL 查询语言增强了元素定位和数据提取的智能化程度。

核心功能

安装与配置

环境要求

• Node.js 14.17.0 或更高版本
• npm、yarn 或 pnpm 包管理器

安装步骤

npm install agentql playwright

依赖配置

JavaScript SDK 的 package.json 中定义了核心依赖：

{
  "dependencies": {
    "agentql": "latest",
    "openai": "^4.70.1",
    "playwright": "^1.48.2",
    "playwright-dompath": "^0.0.7"
  }
}

资料来源：examples/js/package.json:13-17

全局配置

在使用 SDK 之前，需要通过 configure() 函数进行初始化：

const { wrap, configure } = require('agentql');

// 配置 API 密钥
configure({
  apiKey: process.env.AGENTQL_API_KEY,
});

configure() 函数接受以下参数：

核心 API

wrap() 函数

wrap() 是 JavaScript SDK 的核心函数，用于将 Playwright 的 Page 对象转换为支持 AgentQL 查询的增强对象。

const { wrap } = require('agentql');
const { chromium } = require('playwright');

const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();

// 将普通 Page 对象包装为 AgentQL Page 对象
const wrappedPage = await wrap(page);

资料来源：examples/js/get-by-prompt/main.js:1-11

queryData() 方法

queryData() 方法允许使用 AgentQL 查询语言从页面中提取结构化数据。

const QUERY = `
{
    items[]
    {
        title
        url
        published_date(convert to XX/XX/XXXX format)
    }
}`;

const data = await wrappedPage.queryData(QUERY);
console.log(data.items);

资料来源：examples/js/news-aggregator/main.js:1-18

getByPrompt() 方法

getByPrompt() 通过自然语言描述定位页面元素，返回匹配的元素对象或 null。

// 获取登录按钮
const signUpBtn = await wrappedPage.getByPrompt('Sign up button');

// 点击按钮
if (signUpBtn) {
    await signUpBtn.click();
}

资料来源：examples/js/get-by-prompt/main.js:21-27

使用模式

基本查询模式

graph TD
    A[初始化浏览器] --> B[创建 Page 对象]
    B --> C[wrap 包装 Page]
    C --> D[定义 AgentQL 查询]
    D --> E[queryData 执行查询]
    E --> F[处理返回数据]

基础示例

const { wrap, configure } = require('agentql');
const { chromium } = require('playwright');

const URL = 'https://example.com';

async function main() {
    // 1. 配置 API
    configure({ apiKey: process.env.AGENTQL_API_KEY });
    
    // 2. 启动浏览器
    const browser = await chromium.launch({ headless: false });
    const page = await wrap(await browser.newPage());
    
    // 3. 导航到目标页面
    await page.goto(URL);
    
    // 4. 执行查询
    const QUERY = `{ headline title }`;
    const data = await page.queryData(QUERY);
    console.log(data);
    
    // 5. 关闭浏览器
    await browser.close();
}

main();

分页数据采集模式

对于需要遍历多页的场景：

const QUERY = `
{
    books[] {
        name
        price
        rating
    }
}`;

const books = [];
const browser = await chromium.launch({ headless: false });
const page = await wrap(await browser.newPage());

await page.goto(URL);

while (books.length < 50) {
    const response = await page.queryData(QUERY);
    books.push(...response.books);
    
    // 检查是否有下一页
    if (paginationInfo.hasNextPage) {
        await goToTheNextPage(page, URL);
    }
}

资料来源：examples/js/collect-paginated-ecommerce-data/main.js:1-26

价格筛选模式

async function searchProduct(page, product, minPrice, maxPrice) {
    // 使用 getByPrompt 定位搜索输入框
    const searchInput = await page.getByPrompt('the search input field');
    await searchInput.type(product, { delay: 200 });
    await searchInput.press('Enter');

    // 定位价格筛选输入框
    const minPriceInput = await page.getByPrompt('the min price input field');
    await minPriceInput.fill(String(minPrice));

    const maxPriceInput = await page.getByPrompt('the max price input field');
    await maxPriceInput.fill(String(maxPrice));
    await maxPriceInput.press('Enter');
    return true;
}

资料来源：examples/js/collect-pricing-data/main.js:16-33

数据提取与转换

AgentQL 查询语言支持在查询时直接进行数据转换：

const QUERY = `
{
    items[]
    {
        published_date(convert to XX/XX/XXXX format)
        entry(title or post if no title is available)
        author(person's name; return "n/a" if not available)
        outlet(the original platform it is posted on)
        url
    }
}`;

资料来源：examples/js/news-aggregator/main.js:8-15

查询语法参考

列表查询

使用 [] 语法声明列表类型：

{
    products[] {
        name
        price
    }
}

数据转换指令

在字段名后添加括号指定转换规则：

自然语言选择器

通过描述性语言定位元素：

高级用法

并发数据采集

利用 Playwright 的上下文功能实现多标签页并发：

async function fetchData(context, url) {
    const page = await wrap(await context.newPage());
    await page.goto(url);
    return await page.queryData(QUERY);
}

// 在同一浏览器上下文中打开多个标签页
await asyncio.gather(
    *(fetchData(context, url) for url in WEBSITE_URLS)
);

与 Playwright 原生 API 混用

包装后的 Page 对象仍可调用所有 Playwright 原生方法：

const wrappedPage = await wrap(page);

// AgentQL 方法
await wrappedPage.queryData(QUERY);

// Playwright 原生方法
await wrappedPage.waitForTimeout(10000);
await wrappedPage.screenshot({ path: 'screenshot.png' });

已知限制

Cloudflare 边缘环境

社区反馈表明，JavaScript SDK 在 Cloudflare Workers 等边缘环境中使用时存在兼容性问题。边缘环境对部分 Node.js API 有限制，而 SDK 依赖这些 API 进行正常工作。详情见 Issue #128。

元素定位准确性

某些情况下，查询结果可能返回无用的 span 元素而非预期的目标元素。社区已在 Issue #121 中报告了此问题，涉及特定网站如 CheckPoint Careers 页面。

相关资源

概述

AgentQL 浏览器调试器扩展（AgentQL Debugger Chrome Extension）是一款 Chrome 浏览器插件，旨在帮助开发者交互式地构建、测试和调试 AgentQL 查询语句。该扩展通过可视化的方式让用户在浏览器中直接编写和验证查询语句，显著降低了学习和使用 AgentQL 的门槛。

核心功能

资料来源：examples/python/list_query_usage/README.md:14

工作原理

架构流程

graph TD
    A[用户访问网页] --> B[激活调试器扩展]
    B --> C[编写 AgentQL 查询]
    C --> D[扩展执行查询]
    D --> E[Playwright 渲染页面]
    E --> F[LLM 解析查询意图]
    F --> G[返回匹配元素]
    G --> H[展示查询结果]
    H --> I{结果是否满意?}
    I -->|是| J[复制查询到代码]
    I -->|否| C

查询执行流程

当用户在调试器扩展中执行查询时，系统会经历以下步骤：

1. 页面加载 - Playwright 加载目标网页
2. 查询解析 - LLM 解析 AgentQL 查询语句
3. 元素定位 - 根据查询语义定位页面 DOM 元素
4. 数据提取 - 提取匹配元素的数据
5. 结果展示 - 在扩展界面中展示提取结果

资料来源：examples/python/first_steps/main.py:25-30

安装指南

系统要求

安装步骤

1. 访问 AgentQL Chrome 扩展安装页面
2. 点击"添加到 Chrome"按钮
3. 在弹出对话框中确认安装
4. 安装完成后，扩展图标将出现在浏览器工具栏

资料来源：examples/js/list-query-usage/README.md:15-17

使用方法

基本工作流程

graph LR
    A[打开目标网页] --> B[点击扩展图标]
    B --> C[输入查询语句]
    C --> D[点击执行]
    D --> E[查看结果]
    E --> F[调整查询]
    F --> C

查询编写示例

以下是一个典型的查询编写流程：

步骤 1：定位搜索框

{
    search_product_box
}

步骤 2：提取产品数据

{
    price_currency
    products[] {
        name
        price(integer)
    }
}

步骤 3：使用自然语言选择器

NATURAL_LANGUAGE_PROMPT = "Button to display Qwilfish page"

资料来源：examples/python/first_steps/main.py:20-42

在示例项目中的应用

所有 AgentQL 示例项目都推荐使用调试器扩展来优化查询。以下是常见的使用场景：

#### 分页数据采集

{
    items(might be articles, posts, tweets)[]{
        published_date(convert to XX/XX/XXXX format)
        entry(title or post if no title is available)
        author(person's name; return "n/a" if not available)
        outlet(the original platform it is posted on)
        url
    }
}

资料来源：examples/python/news-aggregator/README.md:21-31

#### 列表项查询

{
    items_list[] {
        item_name
        item_description
        item_price
    }
}

资料来源：examples/python/list_query_usage/README.md:18-24

最佳实践

查询优化建议

常见问题处理

#### 查询元素定位不准确

当遇到查询结果与预期不符时（如元素被解析为无用的 span），建议：

1. 使用更具体的自然语言描述
2. 检查页面结构是否动态加载
3. 尝试使用属性选择器而非内容选择器

资料来源：github.com/tinyfish-io/agentql/issues/121

与 IDE 工作流集成

调试器扩展的最佳实践是与代码编辑器形成完整的工作流：

graph LR
    A[浏览器调试器] --> B[优化查询]
    B --> C[复制到 IDE]
    C --> D[编写脚本]
    D --> E[运行测试]
    E --> F{是否需要调整?}
    F -->|是| A
    F -->|否| G[完成]

进阶用法

自然语言选择器

AgentQL 支持使用自然语言描述来定位元素，这使得查询编写更加直观：

# 示例：定位特定按钮
NATURAL_LANGUAGE_PROMPT = "显示 Qwilfish 页面的按钮"

这种方式的优点：

• 跨站点兼容性 - 相同的自然语言描述在不同网站也能工作
• 自愈能力 - 页面结构变化时查询仍能正确执行
• 意图导向 - 基于内容意图而非 DOM 结构

资料来源：examples/python/first_steps/main.py:44-45

数据转换与提取

在查询中可以直接进行数据转换：

{
    products[] {
        name
        price(integer)          # 转换为整数
        published_date(format: "XX/XX/XXXX")  # 格式化日期
    }
}

相关资源

与其他工具的配合

与 Playwright 的协同

调试器扩展与 Playwright SDK 紧密配合：

# 使用调试器验证后的查询
page = agentql.wrap(browser.new_page())
page.goto(URL)

# 使用扩展中测试过的查询
data = page.query_data(QUERY)

资料来源：examples/python/first_steps/main.py:47-52

与 Cloudflare Browser Rendering 的兼容

社区反馈表明，在 Cloudflare Workers 环境中使用调试器扩展时需要注意：

• Edge 环境对某些 Node.js API 支持有限
• 可能需要调整查询以适应无头浏览器环境

资料来源：github.com/tinyfish-io/agentql/issues/128

概述

Python 示例代码集是 AgentQL 项目的重要组成部分，提供了使用 Python SDK 进行网页数据提取、自动化测试和浏览器交互的实战示例。这些示例代码覆盖了从基础入门到高级应用的多种场景，帮助开发者快速掌握 AgentQL 的核心功能。

AgentQL Python SDK 与 Playwright 无缝集成，提供了 agentql.wrap() 方法来扩展 Playwright 的 Page 对象，使其具备智能定位和数据查询能力。开发者可以通过自然语言查询定位页面元素，定义结构化数据输出，并在查询中应用数据转换。

核心功能模块

基础查询功能

AgentQL 的核心是 query_elements() 和 query_data() 两个方法。前者用于定位 DOM 元素，返回可交互的 Playwright 元素对象；后者用于提取结构化数据，支持嵌套对象和数组提取。

# 导入 AgentQL 扩展
import agentql
from agentql.ext.playwright.sync_api import Page
from playwright.sync_api import sync_playwright

# 包装浏览器页面对象
page = agentql.wrap(browser.new_page())

# 使用 AgentQL 查询定位元素
SEARCH_BOX_QUERY = """
{
    search_product_box
}
"""

response = page.query_elements(SEARCH_BOX_QUERY)
response.search_product_box.type("fish", delay=200)

# 提取结构化数据
PRODUCT_DATA_QUERY = """
{
    price_currency
    products[] {
        name
        price(integer)
    }
}
"""

data = page.query_data(PRODUCT_DATA_QUERY)

资料来源：examples/python/first_steps/main.py:1-42

自然语言定位器

AgentQL 提供了 get_by_prompt() 方法，允许开发者使用自然语言描述来定位页面元素。这种方式比传统的 CSS 选择器或 XPath 更加直观，特别适合定位那些结构可能变化但语义保持一致的元素。

# 使用自然语言提示定位元素
NATURAL_LANGUAGE_PROMPT = "Button to display Qwilfish page"
qwilfish_page_btn = page.get_by_prompt(NATURAL_LANGUAGE_PROMPT)

资料来源：examples/python/first_steps/main.py:47-52

示例代码分类

新闻聚合器

新闻聚合器示例展示了如何从多个新闻网站并发抓取数据并将结果保存为 CSV 文件。该示例提供了异步和同步两种实现方式。

#### 异步实现

异步版本使用 asyncio.gather() 并发处理多个 URL，显著提高数据采集效率。

import agentql
from playwright.async_api import async_playwright

WEBSITE_URLS = [
    "https://duckduckgo.com/?q=agents+for+the+web&t=h_&iar=news&ia=news",
]

async def main():
    async with async_playwright() as p:
        async with await p.chromium.launch(headless=True) as browser:
            async with await browser.new_context() as context:
                await asyncio.gather(
                    *(fetch_data(context, url) for url in WEBSITE_URLS)
                )

资料来源：examples/python/news-aggregator/main.py:10-23

#### 同步实现

同步版本按顺序处理 URL，适合需要严格控制请求顺序的场景。

import agentql
from playwright.sync_api import sync_playwright

def main():
    with sync_playwright() as p:
        with p.chromium.launch(headless=True) as browser:
            context = browser.new_context()
            for url in WEBSITE_URLS:
                fetch_data(context, url)

资料来源：examples/python/news-aggregator/main_sync.py:16-24

分页数据采集

分页数据采集示例演示了如何遍历多个分页页面收集数据，适用于 HackerNews、电商列表等场景。

该示例通过循环翻页并累积数据，直到达到指定页数或页面不再包含目标元素。

async def fetch_data(context, query, num_pages):
    page = await agentql.wrap_async(context.new_page())
    all_data = []
    
    for page_num in range(num_pages):
        data = await page.query_data(query)
        all_data.extend(data.get("items", []))
        await page.click("next_button_selector")
        await page.wait_for_load_state("networkidle")

资料来源：examples/python/collect_paginated_news_headlines/README.md:1-25

列表项查询

列表项查询示例展示了如何从页面中提取重复出现的数据结构，如产品列表、新闻条目等。通过在查询中使用 [] 语法，AgentQL 可以自动识别并提取数组类型的数据。

LIST_QUERY = """
{
    items[] {
        title
        url
        author
    }
}
"""

data = page.query_data(LIST_QUERY)
# data["items"] 是一个包含所有列表项的数组

资料来源：examples/python/list_query_usage/README.md:1-20

电商数据采集

电商数据采集示例专门针对电商网站的商品列表和分页结构进行了优化，支持提取商品名称、价格、库存等关键信息。

ECOMMERCE_QUERY = """
{
    products[] {
        name
        price(integer)
        availability
        category
    }
    pagination {
        current_page
        total_pages
        next_button
    }
}
"""

资料来源：examples/python/collect_paginated_ecommerce_listing_data/README.md:1-25

现有浏览器复用

AgentQL 支持连接到已打开的浏览器实例，这对于调试和手动操作场景特别有用。开发者可以通过 Chrome DevTools Protocol 地址连接到现有浏览器。

from playwright.sync_api import sync_playwright

# 启动带调试端口的浏览器
# google-chrome --remote-debugging-port=9222

browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
page = agentql.wrap(browser.new_page())

资料来源：examples/python/use_existing_browser/README.md:1-20

工作流程架构

graph TD
    A[启动浏览器] --> B[创建 Page 对象]
    B --> C[agentql.wrap 包装]
    C --> D[定义 AgentQL 查询]
    D --> E[query_elements 或 query_data]
    E --> F{查询类型}
    F -->|元素定位| G[返回 Playwright 元素]
    F -->|数据提取| H[返回结构化 JSON]
    G --> I[执行交互操作]
    H --> J[处理和存储数据]
    I --> K[继续导航或关闭]
    J --> K

数据提取流程

sequenceDiagram
    participant Dev as 开发者
    participant API as AgentQL API
    participant Page as Playwright Page
    participant Target as 目标网页
    
    Dev->>API: 定义 AgentQL 查询
    API->>Page: 发送查询请求
    Page->>Target: 加载页面 DOM
    Target-->>Page: 返回 DOM 结构
    Page->>API: 发送 DOM 数据
    API->>API: 解析并转换数据
    API-->>Dev: 返回结构化结果

常见使用模式

搜索和筛选流程

def search_and_collect(page, search_term, max_results):
    """执行搜索并收集结果"""
    # 定位搜索框
    search_box = page.query_elements('{ search_input }')
    
    # 输入搜索关键词
    search_box.type(search_term)
    page.keyboard.press("Enter")
    
    # 等待结果加载
    page.wait_for_load_state("networkidle")
    
    # 提取搜索结果
    results = page.query_data('''
    {
        search_results[] {
            title
            link
            snippet
        }
    }
    ''')
    
    return results["search_results"]

CSV 数据导出

import os

CSV_FILE_PATH = "output_data.csv"

def save_to_csv(data, fieldnames):
    """保存数据到 CSV 文件"""
    file_exists = os.path.exists(CSV_FILE_PATH)
    
    with open(CSV_FILE_PATH, "a", encoding="utf-8") as file:
        if not file_exists:
            file.write(" | ".join(fieldnames) + "\n")
        
        for item in data:
            clean_entry = str(item).replace("|", "")
            file.write(clean_entry + "\n")

资料来源：examples/python/news-aggregator/main.py:25-45

安装和配置

环境要求

安装步骤

1. 安装 AgentQL SDK：

pip install agentql

1. 安装浏览器驱动：

playwright install chromium

1. 验证安装：

python -c "import agentql; print(agentql.__version__)"

社区反馈与注意事项

根据社区反馈，在使用 AgentQL 进行元素查询时，需要注意以下几点：

• 元素定位问题：某些网站可能使用复杂的 DOM 结构，查询结果可能定位到无用的 span 元素而非预期元素。遇到此类问题时，可尝试使用更精确的自然语言描述或调整查询语句。
• 分页处理：对于动态加载的分页内容，需要在翻页后等待网络请求完成再进行数据提取。
• 并发控制：虽然支持异步并发操作，但建议控制并发数量以避免触发网站的反爬机制。

相关资源

• AgentQL 官方文档
• Python SDK 安装指南
• AgentQL 查询语言介绍
• Chrome 调试扩展
• Discord 社区支持

核心依赖环境

JavaScript 示例基于以下核心依赖构建：

资料来源：examples/js/package.json:10-15

SDK 核心 API

JavaScript SDK 提供两个主要导出函数：

const { wrap, configure } = require('agentql');

资料来源：examples/js/get-by-prompt/main.js:4-5

示例脚本分类

1. 按提示词定位元素

get-by-prompt 示例展示了如何使用自然语言提示词定位页面元素：

// 获取 "Sign up" 提示的按钮
const signUpBtn = await page.getByPrompt('Sign up button');
if (signUpBtn) {
  await signUpBtn.click();
}

此方法通过自然语言描述定位元素，无需编写 CSS 选择器或 XPath，适用于 UI 结构频繁变化的场景。

资料来源：examples/js/get-by-prompt/main.js:24-28

2. 数据查询与转换

collect-pricing-data 示例演示了复杂的数据查询与转换能力：

const QUERY = `
  {
      products[] {
          name
          model
          sku
          price(integer)  // 类型转换 transform
      }
  }`;
const pricingData = await page.queryData(QUERY);

AgentQL 查询语言支持以下特性：

• 列表提取：使用 [] 语法提取数组数据
• 类型转换：在字段后添加 (integer) 等类型指示器进行数据转换
• 嵌套结构：支持多层级数据结构查询

资料来源：examples/js/collect-pricing-data/main.js:9-17

3. 分页数据采集

分页采集是网页数据抓取中的常见需求，AgentQL 提供了两种实现模式：

#### 新闻分页采集

collect-paginated-news-headlines 使用 End 键滚动方式触发分页加载：

const paginationQuery = `
  {
      pagination {
          next_button
      }
  }`;

// 按 End 键滚动到页面底部加载下一页
await page.keyboard.press('End');

#### 电商分页采集

collect-paginated-ecommerce-data 采用类似模式，但针对电商页面结构优化：

graph TD
    A[打开商品列表页] --> B[执行数据查询]
    B --> C{判断是否有下一页}
    C -->|是| D[点击下一页按钮]
    C -->|否| E[保存数据]
    D --> B
    E --> F[结束采集]

两种模式的选择取决于目标网站的加载机制：

资料来源：examples/js/collect-paginated-news-headlines/main.js 资料来源：examples/js/collect-paginated-ecommerce-data/README.md

4. 新闻聚合器

news-aggregator 示例展示了多标签页并发数据采集能力：

const websiteUrls = [
  'https://bsky.app/search?q=agents+for+the+web',
  'https://dev.to/search?q=agents%20for%20the+web',
  'https://hn.algolia.com/?dateRange=last24h&query=agents',
  'https://duckduckgo.com/?q=agents+for+the+web&iar=news&ia=news',
];

// 并发处理多个 URL
await asyncio.gather(
  *(fetchData(context, url) for url in websiteUrls)
);

此模式在单一浏览器上下文中创建多个标签页，实现高效的并发数据采集。

资料来源：examples/js/news-aggregator/main.js:13-18

5. 情感分析集成

perform_sentiment_analysis 示例（位于 Python 示例中）展示了将 AgentQL 与 OpenAI GPT-3.5 结合的高级用法，通过提取页面数据后进行 AI 驱动的语义分析。

执行流程架构

graph TD
    A[配置 API Key] --> B[启动 Chromium 浏览器]
    B --> C[创建 Page 对象]
    C --> D[使用 wrap 包装页面]
    D --> E[导航到目标 URL]
    E --> F[执行 AgentQL 查询]
    F --> G[获取结构化数据]
    G --> H{处理完成?}
    H -->|否| F
    H -->|是| I[关闭浏览器]
    I --> J[数据后处理]

常见问题与社区反馈

Cloudflare Edge 环境兼容性

社区 Issue #128 讨论了 AgentQL JavaScript SDK 在 Cloudflare Workers 边缘环境中使用时的限制。由于边缘环境不支持部分 Node.js API，可能需要调整实现方式。

元素定位准确性

Issue #121 报告了某些网站中查询结果定位不准确的问题，建议使用 Chrome 扩展调试器调整查询语句以获得更精确的定位。

快速开始

1. 安装依赖：

npm install agentql playwright openai

1. 配置环境变量：

export AGENTQL_API_KEY="your-api-key"

1. 运行示例脚本：

node main.js

相关资源

• JavaScript SDK 安装文档
• AgentQL 查询语言参考
• Chrome 调试器扩展

功能概览

远程浏览器模式

工作原理

远程浏览器模式允许 AgentQL 通过 Chrome DevTools Protocol (CDP) 连接到已经运行的浏览器实例。这种方式避免了每次都启动新浏览器的开销，特别适用于需要复用复杂登录状态的场景。

graph TD
    A[启动浏览器<br/>--remote-debugging-port=9222] --> B[AgentQL 通过 CDP 连接]
    B --> C[获取已打开页面列表]
    C --> D[选择目标页面]
    D --> E[执行 AgentQL 查询]
    E --> F[提取数据]

Python 实现

from agentql.ext.playwright.sync_api import sync_playwright
import agentql

async def main():
    async with sync_playwright() as p:
        # 通过 CDP URL 连接到远程浏览器
        browser = await p.chromium.connect_over_cdp(
            "http://127.0.0.1:9222"
        )
        
        # 获取所有打开的页面
        contexts = browser.contexts
        if contexts:
            page = contexts[0].pages[0]
            wrapped_page = agentql.wrap(page)
            
            # 执行查询
            data = await wrapped_page.query_data(QUERY)

连接参数说明

现有浏览器模式

核心概念

现有浏览器模式使开发者能够直接操控用户已打开的浏览器页面。通过 AgentQL Debugger Chrome 扩展打开的页面可以作为数据源，无需重新导航和认证。

这种模式特别适用于以下场景：

• 用户已在浏览器中登录网站
• 需要从复杂单页应用中提取数据
• 需要复用已有的浏览器状态

graph LR
    A[用户在浏览器中<br/>打开目标页面] --> B[安装 AgentQL<br/>Chrome 扩展]
    B --> C[点击扩展图标<br/>启动调试模式]
    C --> D[运行 Python 脚本<br/>连接本地浏览器]
    D --> E[执行查询<br/>提取数据]

使用限制

现有浏览器模式依赖本地 Chrome 实例和特定的启动参数。脚本启动时会输出调试端点 URL，用户需要在终端中复制该 URL 并在浏览器中访问以建立连接。

资料来源：examples/python/use_existing_browser/main.py:1-20

隐身模式

功能特性

隐身模式通过隐藏常见的自动化特征来避免被网站检测。这些特征包括：

• 移除 webdriver 属性
• 修改 navigator 对象
• 模拟真实用户代理
• 禁用某些 JavaScript API 检测

启用方式

import agentql

with sync_playwright() as p:
    browser = await p.chromium.launch(
        headless=True,
        args=[
            "--disable-blink-features=AutomationControlled"
        ]
    )
    
    page = agentql.wrap(browser.new_page())
    # 隐身模式自动应用
    page.goto(url)

隐身模式集成在 AgentQL 的页面包装机制中，无需额外配置即可自动生效。这种设计确保了在进行大规模数据抓取时的隐蔽性。

会话持久化

工作流程

会话持久化功能允许开发者保存当前的浏览器状态（Cookie、Local Storage、会话数据）并在后续运行中恢复。这对于需要长期维护登录状态的自动化任务至关重要。

graph TD
    A[首次运行<br/>完整登录流程] --> B[保存会话状态]
    B --> C[存储到本地文件]
    C --> D[后续运行]
    D --> E[加载会话状态]
    E --> F[跳过登录<br/>直接访问目标页面]

实现示例

import json
import agentql
from pathlib import Path

STORAGE_STATE_PATH = Path(__file__).parent / "state.json"

def main():
    with sync_playwright() as p:
        context = p.chromium.launch_persistent_context(
            user_data_dir="./user_data_dir"
        )
        
        page = agentql.wrap(context.pages[0])
        page.goto("https://example.com")
        
        # 执行登录操作
        perform_login(page)
        
        # 保存状态
        state = context.storage_state()
        with open(STORAGE_STATE_PATH, 'w') as f:
            json.dump(state, f)

def load_session():
    with open(STORAGE_STATE_PATH) as f:
        state = json.load(f)
    return state

状态管理参数

社区相关讨论

已知问题与解决方案

远程浏览器在 Cloudflare 环境中的限制

社区 issue #128 讨论了 AgentQL JavaScript SDK 与 Cloudflare Browser Rendering 服务的集成问题。Cloudflare Workers 环境对某些 Node.js API 有限制，可能影响远程浏览器连接的稳定性。

元素定位不准确问题

issue #121 报告了某些网站（如 Checkpoint 招聘页面）上查询结果不准确的问题。元素可能被解析为无用的 span 标签而非预期的元素。这种情况下建议使用更精确的 AgentQL 查询或结合传统 CSS 选择器。

文档链接问题

issue #64 指出官方文档中的 Google Colab 示例链接指向了错误的目录。正确的路径应为 examples/run_script_online_in_google_colab。

最佳实践

浏览器资源管理

错误处理

from playwright.sync_api import Error as PlaywrightError

try:
    browser = p.chromium.connect_over_cdp(endpoint)
except PlaywrightError as e:
    logger.error(f"无法连接到远程浏览器: {e}")
    # 降级到本地浏览器启动
    browser = p.chromium.launch()

相关资源

• AgentQL 官方文档
• Playwright 浏览器连接指南
• Chrome DevTools Protocol 文档

概述

AgentQL 通过丰富的第三方集成生态系统，将 AI 代理与整个 Web 环境连接起来。项目的集成策略围绕核心自动化框架展开，同时支持与主流 AI 服务、代理框架和云平台的深度整合。

根据官方文档，AgentQL 的主要集成包括：

• Playwright - 底层浏览器自动化引擎
• LangChain - AI 代理框架
• Zapier - 工作流自动化平台
• MCP Server - 模型上下文协议服务器

资料来源：README.md

概述

Cloudflare 浏览器渲染集成是指将 AgentQL 与 Cloudflare Workers 平台上的 Browser Rendering 功能结合使用的技术方案。该集成允许开发者在 Cloudflare 的边缘计算环境中运行基于 Playwright 的浏览器自动化任务，并利用 AgentQL 的自然语言查询能力从网页中提取结构化数据。

根据社区反馈（Issue #128），这一集成面临一些边缘环境特有的技术挑战，需要开发者在使用时注意 Node.js 兼容性限制。

架构设计

整体架构

graph TD
    A[Cloudflare Worker] --> B[Browser Rendering API]
    B --> C[Playwright 实例]
    C --> D[AgentQL 查询引擎]
    D --> E[结构化数据输出]
    
    F[传统 Node.js 环境] --> G[完整 Playwright 支持]
    G --> H[AgentQL 完整功能]

集成层级

核心依赖配置

JavaScript SDK 依赖

在 examples/js/package.json 中定义了 AgentQL JavaScript SDK 的核心依赖：

{
  "dependencies": {
    "agentql": "latest",
    "openai": "^4.70.1",
    "playwright": "^1.48.2",
    "playwright-dompath": "^0.0.7"
  }
}

资料来源：examples/js/package.json:14-18

Python SDK 与 Playwright

Python 版本使用同步或异步 Playwright API：

import agentql
from agentql.ext.playwright.sync_api import Page
from playwright.sync_api import sync_playwright

资料来源：examples/python/first_steps/main.py:1-4

使用模式

同步查询模式

适用于传统的服务器端环境：

from agentql import wrap

page = wrap(browser.new_page())
data = page.query_data(QUERY)

异步查询模式

适用于高并发的边缘环境：

async with async_playwright() as p:
    page = await agentql.wrap_async(context.new_page())
    data = await page.query_data(QUERY)

资料来源：examples/python/news-aggregator/main.py:1-40

Cloudflare 边缘环境限制

Node.js 兼容性挑战

根据社区 Issue #128 的讨论，在 Cloudflare Workers 边缘环境中存在以下限制：

解决方案建议

1. 条件加载：使用特性检测加载不同模块
2. 轻量级替代：替换重型依赖为边缘兼容版本
3. 任务分片：将大型任务拆分为多个 Worker 调用
4. 数据预取：在传统环境预处理数据，减少边缘计算负担

Playwright 容器镜像

AgentQL 推荐的 Playwright 运行环境中使用以下容器镜像：

playwright:
  - tier: recommended
    alias: playwright-latest
    image: mcr.microsoft.com/playwright:v1.58.2-noble
    uri: mcr.microsoft.com/playwright:v1.58.2-noble@sha256:65cefd09a5e943921ecd3a6e5414c603db2eb161e9eb48f2e2ccc63486dc7dc0
    runtime_version: "1.58.2"
    base_os: Ubuntu 24.04 LTS (Noble Numbat)

资料来源：golden-images.yaml:1-20

常见查询模式

数据查询

DATA_QUERY = """
{
    price_currency
    products[] {
        name
        price(integer)
    }
}
"""

元素定位

SEARCH_BOX_QUERY = """
{
    search_product_box
}
"""

自然语言定位

NATURAL_LANGUAGE_PROMPT = "Button to display Qwilfish page"

资料来源：examples/python/first_steps/main.py:20-40

社区反馈与已知问题

Issue #128：AgentQL (JS) x Cloudflare's Browser Rendering

这是社区中关于此集成的主要讨论话题。核心问题是边缘环境与标准 Node.js 环境的差异导致部分功能不可用。

关键反馈点：

• Cloudflare Browser Rendering 支持 Playwright
• Edge 环境对某些 Node.js API 有特殊限制
• 需要测试和验证具体功能的兼容性

问题排查清单

• [ ] 验证 Playwright 版本兼容性
• [ ] 检查全局对象使用情况
• [ ] 测试原生模块依赖
• [ ] 评估执行时间限制
• [ ] 确认数据存储方案

相关资源

Pitfall Log / 踩坑日志

项目：tinyfish-io/agentql

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Dependency Dashboard。

1. 安装坑 · 来源证据：Dependency Dashboard

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Dependency Dashboard
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_761b694cc0e94100b46ba5683041137b | https://github.com/tinyfish-io/agentql/issues/114 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：Starlog published a deep-dive on tinyfish-io/agentql

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Starlog published a deep-dive on tinyfish-io/agentql
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_55a8aa1466634fb39e0b679f753270ec | https://github.com/tinyfish-io/agentql/issues/148 | 来源类型 github_issue 暴露的待验证使用条件。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:760722197 | https://github.com/tinyfish-io/agentql | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:760722197 | https://github.com/tinyfish-io/agentql | last_activity_observed missing

5. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:760722197 | https://github.com/tinyfish-io/agentql | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:760722197 | https://github.com/tinyfish-io/agentql | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:760722197 | https://github.com/tinyfish-io/agentql | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:760722197 | https://github.com/tinyfish-io/agentql | release_recency=unknown