ax

Name: ax
Author: akillness

github.com/akillness数据与数据库5360 次安装4 天前更新

代码仓库

关于 ax

ax 是面向 AI Agent 的网页抓取与提取命令行工具，可发现页面结构并提取结构化数据。它提供预算控制和缓存探测，适合构建可重复的网页数据处理任务。

主要功能

01获取网页并返回响应元数据
02概览页面结构并定位文本
03按 CSS 选择器提取多字段数据
04筛选行并输出 JSON 或 TSV
05按令牌预算限制结果

适用场景

01查看网页结构后选择提取目标
02从商品列表抽取名称与价格
03提取文档并转换为 Markdown
04定期检查 JSON API 状态

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/akillness/jeo-skills --skill ax

安装后在 Claude Code 中输入/ax确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md

references/

agent-patterns.md

cli-flags.md

installation.md

scripts/

scaffold-integration.sh

setup.sh

详细介绍

ax — AI 时代用于网页抓取与提取的 Curl

版本 1.0.0
Yusuke Bebé 与贡献者
AI 驱动的抓取、发现与提取框架

概述

ax 是一款专为 AI Agent 打造的命令行工具，可抓取网页、发现网页结构并提取结构化数据——用一个确定性强、节省 Token 的命令，取代经典的 curl → parse → regex 循环。

何时使用 ax

需要 Agent 抓取网页并提取结构化数据
希望发现网页结构（--outline），而不输出原始 HTML
使用 CSS 选择器提取包含多个字段的行（--row、--table）
需要符合 Token 预算的输出（设有上限，可控制预算）
正在构建可重复执行的网页抓取 Agent 任务
厌倦了在 Agent 代码中使用 curl | grep | awk 管道

何时不应使用 ax

目标网站需要客户端 JavaScript 渲染（请改用 Playwright 或 Puppeteer）
需要实时浏览器自动化或多步交互
内容需要身份验证，且无法通过请求头解决（请改用直接调用 API）
需要无头浏览器进行视觉测试

快速开始

安装 ax

# System-wide install (via shell script)
curl -fsSL https://ax.yusuke.run/install | sh

# Or via Homebrew (macOS/Linux)
brew install yusukebe/tap/ax

# Or via npm (if Node.js available)
npm install -g ax-cli

基本用法

# Fetch and show full response
ax https://api.example.com/users

# Discover page structure
ax https://example.com --outline

# Extract rows with custom selectors
ax https://example.com '.item' --row 'title=a, href=a@href'

# Read docs as markdown
ax https://docs.example.com --md --budget 800

# Extract table to JSON
ax https://example.com 'table' --table --json

集成到 Agent 工作流

# Run with agent context (shows optimized flags for LLMs)
ax agent-context

# Use in agentic script
ITEMS=$(ax https://shop.example.com '.product' \
  --row 'name=h2, price=.price' \
  --where 'price < 100' \
  --json)

核心概念

1. 抓取模式 — 提供完整上下文的实时数据

命令： ax <url>

返回 JSON 格式的响应：{ status, ok, ms, headers, body }。不会静默失败。

每次请求都是实时的（默认不使用缓存）
即使响应体为空，也会生成完整报告
JSON 响应会自动解析
使用 --body 可像传统 curl 一样通过标准输出管道传递数据
延迟通常为 100ms 以上；使用 --no-check 可跳过 SSL 验证（仅限开发环境）

ax https://api.github.com/repos/yusukebe/ax
# Output:
# {
#   "status": 200,
#   "ok": true,
#   "ms": 142,
#   "headers": { "content-type": "application/json", ... },
#   "body": { "name": "ax", "stars": 450, ... }
# }

2. 解析模式 — 发现缓存的 HTML

标志： --outline、--locate、--md

抓取 URL 时，HTML 会缓存在本地（约 2 分钟），以便后续快速探查。

--outline：显示重复出现的 DOM 结构（输出中不包含原始标记）
--locate 'text'：查找包含给定文本的 CSS 选择器
--md：将 HTML 渲染为易读的 Markdown
每次命中缓存时都会在标准错误中提示
--fresh 强制重新抓取；--no-cache 完全禁用磁盘缓存

ax https://news.example.com --outline
# Output:
# main
#   article (×12)
#     h2.headline (×1)
#     p.summary (×1)
#     a.read-more (×1)

3. 提取模式 — 结构化数据行

标志： --row、--table、--where

通过一条命令提取包含多个字段的行；使用安全的表达式语言进行筛选。

# Custom row format
ax https://shop.example.com '.item' \
  --row 'name=h2, price=.price, rating=.stars' \
  --where 'price > 50'

# Table extraction (auto-detects <table>)
ax https://data.example.com --table --json

# Output format: TSV by default (header once), --json for JSON array

--row 'field1=selector, field2=selector@attr'：定义字段和 CSS 选择器
@attr：提取属性（例如 a@href）；默认提取 .textContent
--where 'expr'：筛选行；使用安全的表达式语言（不执行代码）
--json：输出 JSON 而非 TSV
--limit 50：限制结果行数（默认值为 50）

4. Token 预算控制 — 优化 AI 上下文

标志： --budget <tokens>

结果会按照大模型上下文窗口的要求调整格式：

默认将输出限制为约 50 行（会在标准错误中提示）
--budget 800 将输出限制在约 800 个估算 Token 内
结果始终包含行数或截断提示
TSV 格式更节省 Token；JSON 更灵活，适合结构化解析

ax https://catalog.example.com '.product' \
  --row 'name=h2, price=.price' \
  --budget 500
# If 200 rows match, shows first ~40 to fit token budget
# stderr: "Truncated to 40 of 200 rows (token budget: 500)"

Agent 使用模式

模式 1：发现网页结构（零代码，按需提问）

Agent 不知道网页结构 → 使用 --outline，让 Agent 提问：

ax https://docs.example.com --outline
# Agent reads structure, asks targeted follow-up
# ax https://docs.example.com 'h2' --md --budget 300

模式 2：批量提取数据行

Agent 需要从重复结构中提取表格数据：

ax https://items.example.com '.item' \
  --row 'title=h2, url=a@href, price=.price' \
  --json

# Output: JSON array of objects, agent iterates
# Use in script: `jq '.[] | select(.price < 50)' | ...`

模式 3：提取 Markdown 文档

Agent 需要易读的文档：

ax https://guide.example.com/intro --md --budget 2000
# Returns markdown-formatted text, preserves headers, links, structure

模式 4：实时 API 监控

Agent 反复检查 JSON API 端点：

# No cache (live every time)
ax https://api.status.example.com/incident-count

模式 5：筛选与转换

Agent 提取并筛选数据行，然后传递给下游：

ax https://store.example.com '.sale-item' \
  --row 'name=h2, old_price=.old-price, discount=.discount' \
  --where 'discount > 30' \
  --json | jq '.[] | {name, savings: (.old_price * .discount / 100)}'

与 Agent 技能集成

与 `deep-agents-core` 集成

在自定义 Agent 工具中使用 ax：

from deep_agents import tool

@tool("scrape_page")
async def scrape_page(url: str, selector: str = None, extract_mode: str = "outline"):
    """Fetch and parse web pages with ax."""
    cmd = f"ax {url}"
    if extract_mode == "outline":
        cmd += " --outline"
    elif extract_mode == "rows" and selector:
        cmd += f" '{selector}' --row 'content=*' --json"
    
    result = await run_shell(cmd)
    return result

与 `react-grab` 集成

在定位 React 元素之前，使用 ax 提取 HTML 结构：

# Get page outline to understand React component tree
ax https://app.example.com --outline

# Then use react-grab to capture specific component
react-grab --selector '.user-card'

与 `research` 集成（并行发现）

并发对多个 URL 运行 ax：

# Wrapper script: parallel-discover.sh
for url in $(cat urls.txt); do
  ax "$url" --outline --budget 300 &
done | wait

常见任务

任务：提取页面中的所有链接

ax https://example.com --row 'text=a, href=a@href' --json

任务：查找特定章节

ax https://docs.example.com --locate 'Installation' --md

任务：监控 API 端点

ax https://api.example.com/status | jq '.body | select(.status == "ok")'

任务：提取表格并转换为 CSV

ax https://data.example.com 'table.report' --table --json | \
  jq -r '.[] | [.col1, .col2, .col3] | @csv'

任务：由 Agent 驱动的发现流程

# Step 1: Outline (cheap, informs next step)
ax https://site.example.com --outline

# Step 2: Extract (targeted, uses agent's observations)
ax https://site.example.com '.observed-selector' --row 'field=selector' --json

最佳实践

1. 始终从 `--outline` 开始

编写选择器之前，先使用 --outline 了解页面结构。虽然会消耗令牌，但能省去无数次解析迭代。

# Right: Agent learns structure first
ax https://example.com --outline

# Then: Targeted extraction
ax https://example.com '.item' --row 'name=h2'

# Wrong: Guessing selectors and failing
ax https://example.com 'div.product-card' --row 'price=.cost'  # Oops, wrong selector

2. 使用 `--where` 进行客户端筛选

不要提取所有行后再在 Agent 代码中筛选——应在源头筛选：

# Right: Server-side filter
ax https://shop.example.com '.item' \
  --row 'name=h2, price=.price' \
  --where 'price > 50 && price < 200'

# Wasteful: Extract all, filter in agent
ax https://shop.example.com '.item' --row 'name=h2, price=.price' --json
# Agent: "if row.price > 50 and row.price < 200: ..."

3. 遵守速率限制和 Robots.txt

自动抓取前先检查 robots.txt
在请求之间设置合理的延迟（如果可用，使用 --delay <ms>）
尽可能在 User-Agent 标头中标明你的 Agent 身份
谨慎使用 --no-cache；利用缓存命中来减轻负载

4. 为大型数据集预留令牌预算

数据集规模未知时，务必限制结果数量：

# Right: Safe upper bound
ax https://catalog.example.com '.item' --budget 500

# Risky: No limit, may blow context window
ax https://catalog.example.com '.item' --json

5. 处理空响应和错误响应

ax 从不会静默失败——始终会输出响应元数据：

ax https://down.example.com
# Output:
# {
#   "status": 503,
#   "ok": false,
#   "ms": 1200,
#   "headers": { "retry-after": "60" },
#   "body": ""
# }

Agent 应在解析正文前检查 ok 标志和 status。

性能与基准测试

成本节省（真实 Opus 4.8 会话）

任务	不使用 ax	使用 ax	节省
两页标记漂移	$0.458	$0.150	−67%
提取 60 项目录	$0.296 (24s)	$0.104 (14s)	−65%
含有干扰内容的实时网站	$0.248	$0.191	−23%
标记漂移（首次使用）	$0.664	$0.282	−58%

完整方法请参阅 ax 仓库中的 bench/RESULTS.md。

为什么更快、更省？

**令牌效率：**结构化输出 + 预算上限 = 每次请求使用更少令牌
**无需原始 HTML：**与输出完整标记相比，--outline 消耗的令牌少得多
**更少重试：**确定性提取意味着无需“没成功，再试一次”
**原生 CLI：**无需 Agent 在任务过程中编写和调试 shell 脚本

故障排除

问题：“Empty body”或“selector found 0 matches”

**原因：**选择器与页面结构不匹配，或内容由客户端渲染。

解决方法：

运行 ax <url> --outline 验证结构
使用 ax <url> --locate 'visible text' 查找正确的选择器
如果 outline 后仍为空，内容可能由 JS 渲染 → 改用 Playwright

问题：受到速率限制或被拦截

**原因：**请求过多或缺少 User-Agent。

解决方法：

启用缓存：ax <url>（fetch 模式下默认启用缓存）
在脚本的请求之间使用 --delay <ms>
检查 robots.txt 并遵守 crawl-delay
添加 User-Agent 标头：ax <url> -H 'User-Agent: MyAgent/1.0'

问题：“Truncated to N of M rows”

**原因：**结果超出令牌预算。

解决方法：

如果关键数据被截断，请增加 --budget
或缩小 --where 筛选范围，减少返回的行数
或拆分为多个较小的查询

转到其他技能

需求	技能	原因
复杂的页面交互、多步骤流程	使用 Playwright 的 `deep-agents-core`	需要浏览器自动化
提取后检查 React 组件	`react-grab`	将 ax 发现与元素捕获相结合
并行抓取多个网站	`research`（多 Agent）	编排并发 ax 调用
优化令牌预算	`react-best-practices`	调整输出结构以适配 LLM 上下文
验证提取标记的无障碍性	`accessible-markup`	根据 WCAG 验证抓取的内容

对比：ax 与其他方案

特性	curl	htmlq	Firecrawl	ax
获取 URL	✓	✗	✓	✓
发现结构（`--outline`）	✗	✗	△	✓
多字段提取	✗	△（N 次运行）	✓	✓
Markdown 提取（`--md`）	✗	✗	✓	✓
Token 预算输出	✗	✗	✗	✓
每项任务无需编写代码	✗	△（管道操作繁琐）	✓	✓
缓存解析（免费探测）	✗	✗	✗	✓
安全过滤（`--where`）	✗	✗	△	✓

参考资料

官方网站： https://ax.yusuke.run
GitHub： https://github.com/yusukebe/ax
Agent 上下文和标志： ax agent-context（另见 https://ax.yusuke.run/llms.txt）
基准测试： https://github.com/yusukebe/ax/blob/main/bench/RESULTS.md
构建技术： Bun（单文件二进制文件）+ linkedom（DOM 解析）

路由简报（供 Agent 响应时使用）

从 Agent 任务中调用 ax 时请参考：

ax（获取、发现、提取）→ 当 Agent 需要网页数据且不需要无头浏览器时使用。使用 ax <url> --outline 免费发现结构，然后使用 ax <url> 'selector' --row 提取数据。内置 Token 预算和安全过滤。需要交互时转至 Playwright；需要并行编排多个 URL 时转至 research 技能。

许可证

ax 为开源软件（许可证信息请查看仓库）。支持多种安装方式（shell 脚本、Homebrew、npm）。

最后更新： 2026 年 7 月——反映 ax v1.1+ 的功能

支持 Markdown

登录后评论

基本信息

作者: akillness
仓库: akillness/jeo-skills
分类: 数据与数据库
安装次数: 60
GitHub Stars: 53

报告问题

ax

关于 ax

主要功能

适用场景

安装

包含的文件

详细介绍

ax — AI 时代用于网页抓取与提取的 Curl

概述

何时使用 ax

何时不应使用 ax

快速开始

安装 ax

基本用法

集成到 Agent 工作流

核心概念

1. 抓取模式 — 提供完整上下文的实时数据

2. 解析模式 — 发现缓存的 HTML

3. 提取模式 — 结构化数据行

4. Token 预算控制 — 优化 AI 上下文

Agent 使用模式

模式 1：发现网页结构（零代码，按需提问）

模式 2：批量提取数据行

模式 3：提取 Markdown 文档

模式 4：实时 API 监控

模式 5：筛选与转换

与 Agent 技能集成

与 deep-agents-core 集成

与 react-grab 集成

与 research 集成（并行发现）

常见任务

任务：提取页面中的所有链接

任务：查找特定章节

任务：监控 API 端点

任务：提取表格并转换为 CSV

任务：由 Agent 驱动的发现流程

最佳实践

1. 始终从 --outline 开始

2. 使用 --where 进行客户端筛选

3. 遵守速率限制和 Robots.txt

4. 为大型数据集预留令牌预算

5. 处理空响应和错误响应

性能与基准测试

成本节省（真实 Opus 4.8 会话）

为什么更快、更省？

故障排除

问题：“Empty body”或“selector found 0 matches”

问题：受到速率限制或被拦截

问题：“Truncated to N of M rows”

转到其他技能

对比：ax 与其他方案

参考资料

路由简报（供 Agent 响应时使用）

许可证

评论

与 `deep-agents-core` 集成

与 `react-grab` 集成

与 `research` 集成（并行发现）

1. 始终从 `--outline` 开始

2. 使用 `--where` 进行客户端筛选