yusukebe/ax

# ax **AI 时代的 curl：抓取、发现、提取。一个命令搞定。** ax 是编程智能体应该使用的工具，而不是将 `curl` 的输出通过管道传递给一次性的解析脚本。它能抓取页面，帮助智能体理解其结构，并提取结构化数据 —— 在本地确定性地运行，输出专为上下文窗口设计。 ``` ax https://api.example.com/users # curl parity — but never silent ax https://example.com --outline # discover the page's structure ax https://example.com '.item' --row 'title=a, href=a@href' ax https://docs.example.com/guide --md --budget 800 # read docs as markdown ``` ## 缘由 编程智能体不断重复着一个网络循环：**抓取 → 理解 → 提取**。如今，这意味着使用 `curl`（在响应体为空时_什么也不_打印），在上下文窗口中肉眼检查原始 HTML（消耗数千个 token），以及编写基于 HTML 的正则表达式脚本，一旦 HTML 结构发生细微变化这些脚本就会失效。 ax 用一个命令取代了整个循环： - **抓取，绝不静默** — 为每个请求返回 `{status, ok, ms, headers, body}`。空响应体和错误状态码依然会生成完整报告。JSON 响应体会被自动解析。抓取模式从不缓存 —— 每个请求都是实时的。（`--body` 提供经典的管道体验：仅在标准输出打印响应体。） - **发现，而非全盘倾倒** — `--outline` 展示页面的重复结构；`--locate 'text'` 回答“哪个选择器包含了这个内容？” —— 原始 HTML 绝不会进入上下文窗口。解析模式的 URL 会被缓存约 2 分钟，因此探测几乎是零成本的（每次命中都会在 stderr 中通知；`--fresh` 强制重新抓取，`--no-cache` 绝不触碰磁盘）。 - **结构化提取** — `--row 'title=a, href=a@href'` 通过一次调用提取多字段行；`--table` 将 `` 转换为带键的行数据；`--where` 使用安全的表达式语言进行过滤。 - **设计上极其节省 token** — 结果上限为 50 条，并在 stderr 中附带说明（绝不静默截断），`--budget ` 根据估算的 token 数量限制输出，行数据默认采用表头只输出一次的 TSV 格式（使用 `--json` 输出 JSON 格式）。 ## 安装 ``` curl -fsSL https://ax.yusuke.run/install | sh ``` 教导你的智能体使用：`npx skills add yusukebe/ax` —— 或者让它运行 `ax agent-context`。 ## 为什么不用 htmlq / curl / Firecrawl？ **htmlq 只是一个选择器；而 ax 是整个循环。** htmlq 仅覆盖一个步骤（CSS 选择器 → 文本）且无法抓取内容，因此每次使用都必须与 curl 结合。多字段提取意味着要运行它 N 次并手动进行 zip 组合 —— 这正是智能体放弃并开始编写 Python 代码的临界点。ax 在一个二进制程序中完成了抓取 + 发现 + 结构化行数据 + 表格处理 + 过滤，并输出专为智能体设计的内容。 **curl 是静默的。** 一个状态码为 200 的空响应体什么也不会打印；智能体不得不加上 `-i`、`-w` 重新运行，不断猜测。ax 则始终会进行报告。 **Firecrawl 及类似工具通过按量计费的云 API 返回 markdown 文本块。** ax 是本地化、确定性、无需 API 密钥的，并且返回的是_结构_（行数据、表格），而不仅仅是纯文本。（对于 JavaScript 密集的 SPA，你仍然需要浏览器工具 —— 但对于其他所有场景，ax 是更快捷的路径。） | | 一次性 Python 脚本 | curl + htmlq | ax | | ---------------------------------------------- | :--------------: | :----------: | :-: | | 附带完整报告的抓取（状态/Headers/ms） | △ _需自行编写_ | ✗ | ✓ | | 结构发现（`--outline` / `--locate`） | ✗ | ✗ | ✓ | | CSS 选择器提取 | △ _需依赖 bs4_ | ✓ | ✓ | | 一次调用提取多字段行（`--row`） | △ _需自行编写_ | ✗ | ✓ | | `` → 带键行数据 | △ _需自行编写_ | ✗ | ✓ | | 标签结构漂移后更易于修复选择器 | ✗ _（正则表达式）_ | ✓ | ✓ | | 页面 → 易读的 markdown（`--md`） | ✗ | ✗ | ✓ | | 针对优化的 token 输出（上限截断, `--budget`, 提示备注） | ✗ | ✗ | ✓ | | 每个任务无需编写代码 | ✗ | ✓ | ✓ | （△ = 有可能实现，但智能体每次都必须编写并调试代码 —— 而这种编写成本正是 ax 试图解决的核心痛点。） ## 测量数据 基于真实的无头 Claude Code 会话，在执行相同任务时，对比使用与不使用 ax 的情况 —— 结果经过评分，每次运行中双方得出的答案均正确： | 任务 (Opus 4.8, 智能体已掌握 ax 用法) | 不使用 ax | 使用 ax | | ------------------------------------------ | ------------ | ----------------------- | | 包含标签结构漂移的两个页面（会导致正则失效） | $0.458 | **$0.150 (−67%)** | | 从 60 个条目的目录中进行干净提取 | $0.296 · 24s | **$0.104 · 14s (−65%)** | | 实时网站，含干扰标签（3 次的中位数） | $0.248 | **$0.191 (−23%)** | | 标签结构漂移，智能体首次使用 ax | $0.664 | **$0.282 (−58%)** | 完整的方法论 —— 包括 ax _失败_的运行记录 —— 详见 [bench/RESULTS.md](bench/RESULTS.md)。 ## 完整的标志参考 运行 `ax --help`，或运行 `ax agent-context` 获取面向智能体的操作指南（同时也通过 [ax.yusuke.run/llms.txt](https://ax.yusuke.run/llms.txt) 提供）。 ## 构建基于 [Bun](https://bun.sh)（通过 `bun build --compile` 生成的单文件二进制程序）和 [linkedom](https://github.com/WebReflection/linkedom)（用于标准 DOM 解析 —— 唯一的运行时依赖）。