# Webextract

> Use when a URL or online PDF needs ingestion-ready rendered content, or when host-native URL reading failed because JavaScript/PDF rendering is required; only use it for those cases, not routine web discovery or reading.

- Skill: `zimoliao/webextract` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zimoliao/webextract`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zimoliao/webextract/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: zimoliao (https://skillmd.com/u/zimoliao)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zimoliao/webextract

---


# WebExtract - 网页内容提取

**当前 Agent 原生能力优先，但必须先做能力检查**：按页面读取能力和输出契约路由，不按 Agent 品牌路由。若当前会话实际提供网页搜索和页面读取能力，就由当前使用的 Agent 原生能力完成普通检索、来源核验和阅读。只有该能力无法读取需要 JavaScript/PDF 渲染的页面，或任务明确需要可入库、可复现的渲染后 Markdown 时，才调用本 skill。

通过 qt-web-extractor 提取网页内容并转换为 Markdown。优先使用 MCP 方式连接
本机或远端 extractor；HTTP `/extract` 方式保留为兼容 fallback。

## 服务地址

默认 HTTP 服务运行在 `http://127.0.0.1:8766`。推荐 MCP endpoint 为
`http://127.0.0.1:8766/mcp`。

推荐通过 `config.yaml` 配置 MCP：

```yaml
webextract:
  transport: mcp
  mcp_url: http://127.0.0.1:8766/mcp
  api_key: your_key
  mcp_tool: fetch_url
```

HTTP 兼容配置：

```yaml
webextract:
  transport: http
  base_url: http://127.0.0.1:8766
  api_key: your_key
```

## 功能特性

- 提取完全渲染的网页内容（支持 JavaScript 和 SPA）
- 自动转换为干净的 Markdown 格式
- 支持 PDF 文本提取
- 支持 JSON 格式输出

## 使用方法

### 基本用法

```bash
scholaraio webextract <URL>
```

### PDF 提取模式

```bash
scholaraio webextract <PDF_URL> --pdf
```

### 全文与预览模式

```bash
# 默认只显示预览，避免长页面直接刷满终端
scholaraio webextract <URL>

# 查看全文
scholaraio webextract <URL> --full

# 自定义预览长度
scholaraio webextract <URL> --max-chars 1200
```

### 环境变量

- `WEBEXTRACT_URL` - 自定义服务地址（默认: http://127.0.0.1:8766）
- `WEBEXTRACT_API_KEY` - API 认证密钥（如服务配置了认证）
- `WEBEXTRACT_TRANSPORT` - `mcp` 或 `http`
- `WEBEXTRACT_MCP_URL` / `QT_WEB_EXTRACTOR_MCP_URL` - MCP endpoint
- `QT_WEB_EXTRACTOR_API_KEY` - qt-web-extractor API 认证密钥别名

## 与 Agent 协作

当 agent 需要提取网页内容进行分析时：

1. 普通网页发现、来源核验和阅读优先使用当前 Agent 原生网页能力
2. 只有原生读取失败，或需要生成可入库的渲染后 Markdown 时，才确认 `webextract.transport: mcp` 或远端 MCP endpoint 已配置
3. 使用 `scholaraio webextract <URL>` 提取网页内容
4. 将提取的 Markdown 交给 `ingest-link` 工作流或用于需要完整渲染正文的分析

## 注意事项

- MCP 模式下，确保 qt-web-extractor 的 `/mcp` endpoint 可访问；这样可以使用远端
  `fetch_url`，不需要每台机器都安装 Qt WebEngine 环境
- HTTP fallback 下，确保 qt-web-extractor 服务已在本地或远端 8766 端口运行
- 如果服务返回错误且没有正文，CLI 会直接报错退出，而不是显示“提取成功”
- 对于需要登录或特殊认证的页面，可能需要额外配置
- 大量提取时建议分批进行，避免过载