@lizychy0329/pi-ax

v0.0.6

Published

2 months ago

ax integration for pi: structured web extraction via CSS selectors and HTTP API calls

0High
0Medium
0Low

lizychy0329

pi-package pi-extension pi-skill web extraction scraping ax

hero

pi-ax

ax 集成包 for pi — 结构化网页提取，无需写任何解析脚本。

ax is a Rust CLI built for fast, token-cheap web extraction. This package wraps it as a pi extension — giving your agent a web_extract tool with 7 operation modes, plus a skill that tells the agent when to use it vs fetch_content.

项目简介与技术栈

| 项目 | 说明 | |---|---| | ax CLI | Rust — 底层提取引擎，支持 7 种模式、CSS 选择器、TSV 输出、URL 缓存 | | web_extract 工具 | TypeScript — 将 ax CLI 封装为 pi 结构化参数工具，注册为 web_extract | | SKILL | Markdown — 指导 agent 何时用 ax、何时用 fetch_content | | 自动安装 | 首次使用时自动检测环境，缺失则从 ax 官方下载二进制到 ~/.pi/agent/bin/（无需 sudo） | | 测试 | Vitest — 33 单元测试 + 7 集成测试，覆盖全部 mode 分支和可选参数 |

架构

pi Agent (LLM)
    │
    ├── web_extract 工具 ─── buildAxArgs(params) ─── spawnSync("ax", args)
    │         │                              │
    │         └── TypeBox schema             └── Rust ax CLI (7 modes)
    │
    └── SKILL ─── 决策指南：何时 ax、何时 fetch_content

快速开始

安装

# 从 npm 安装（推荐）
pi install npm:@lizychy0329/pi-ax

# 或从 GitHub 安装
pi install git:github.com/lizyChy0329/pi-ax

安装后，pi 会自动：

检测 ax 是否已安装
若未安装，自动下载 ax 二进制到 ~/.pi/agent/bin/（无需 sudo）
注册 web_extract 工具和 ax skill

第一个请求

告诉 agent：

"提取 https://github.com 页面上所有导航链接的标题"

agent 会自动调用：

{
  "url": "https://github.com",
  "mode": "extract",
  "selector": "a[href]",
  "fields": "title=@innerText"
}

本地开发

git clone https://github.com/lizyChy0329/pi-ax
cd pi-ax
npm install

# 运行测试
npm test

# 临时加载（开发模式）
pi -e ./src/index.ts

为什么需要他？

不用写解析脚本：过去要从 HTML 提取数据得写正则或 DOM 解析，现在只要一个 web_extract 调用
Token 便宜：默认 TSV 输出，约为 JSON 的 1/3 token
7 种模式，一个工具：HTTP 报告、结构发现、文本定位、结构化提取、表格提取、Markdown 转换、原始解析
自动安装：不用手动装 ax，缺失时自动从官网下载
Skill 决策：告诉 agent 什么场景用 ax、什么场景用 fetch_content，避免工具选择混乱

能做什么？不能做什么？

tools-compare

✅ web_extract 能做

| 模式 | 场景 | 示例 | |---|---|---| | fetch | REST API 调用、HTTP 调试 | fetch(url, method="POST", body='{"a":1}') | | outline | 页面结构发现（提取前先探查） | outline(url) → tag.class 模式计数 | | locate | 找某段文本的 CSS 选择器 | locate(url, query="Pricing") → .nav-pricing | | extract | 结构化行提取（列表、卡片、搜索结果） | extract(selector=".card", fields="title=a, href=a@href") | | table | HTML <table> → 键值行 | table(selector="table") → 列名来自 <th> | | markdown | 文档页 → 可读 Markdown（支持 token 预算） | markdown(url, budget=800) | | parse | 原始页面内容（带 ~2min URL 缓存） | parse(url, fresh=true) 绕过缓存 |

❌ 不该用 web_extract

| 场景 | 改用 | |---|---| | YouTube 视频内容 | fetch_content | | PDF 文档 | fetch_content | | GitHub 仓库分析 | fetch_content | | 纯文章阅读（无需 CSS 选择器） | fetch_content |

工作流：从未知页面提取数据

workflow

步骤 1：发现结构 → web_extract mode: outline

$ ax https://example.com --outline
 210  path
  90  li
  82  a.Link
  37  li.item

步骤 2：定位选择器 → web_extract mode: locate

$ ax https://example.com --locate "Pricing"
→ .nav-pricing

步骤 3：结构化提取 → web_extract mode: extract

{ "url": "https://example.com", "mode": "extract",
  "selector": ".item", "fields": "name=a, price=.price" }

步骤 4：分页继续 → envelope: true + offset

{ "url": "https://example.com", "mode": "extract",
  "selector": ".item", "fields": "name=a",
  "limit": 20, "envelope": true }

Aim for ≤3 tool calls. The 2-minute URL cache makes repeated probes free.

常见陷阱

<a> 自身做 row selector：字段 a 在 <a> 内找不到子元素 → 空。用父容器作 row selector。
HTTPS→HTTP 跳转：百度等站点强制降级，直接用 http://。
单行压缩 HTML：--outline 效果差，用 --fresh 或 Python 格式化。

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme