trafilatura

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trafilatura

CLI skill for trafilatura: extract main article text and metadata from URLs, piped HTML, or local files. Follow the stdout-first protocol before any batch writes.

Scope: Single-page extraction, metadata JSON, piped/local HTML, bounded URL discovery (

--list

), and user-approved batch processing. NOT for: multi-source research (

research

), PDF/tables (

docling

), raw page fetch (

fetch

fetcher

), video hosts (

yt-dlp

), or paywall bypass.

用于trafilatura的CLI技能：从URL、管道HTML或本地文件中提取主要文章文本和元数据。在进行任何批量写入之前，请遵循标准输出优先协议。

**适用范围：**单页提取、元数据JSON输出、管道/本地HTML处理、有限范围的URL发现（

--list

参数）以及用户批准的批量处理。**不适用场景：**多源研究（

research

工具）、PDF/表格处理（

docling

工具）、原始页面抓取（

fetch

fetcher

工具）、视频平台处理（

yt-dlp

工具）或绕过付费墙。

Canonical Vocabulary

标准术语表

Term	Meaning	NOT
extract	Single URL → clean text via CLI	full crawl harvest
metadata	JSON output with `with_metadata`	bare URL probe only
pipe	Stdin or local `.html` file as input	download from URL
discover	`--feed` / `--sitemap` / `--crawl` / `--probe` with `--list`	bulk download
batch	`-i` link list → output directory	silent mass scrape
local	`--input-dir` reprocess saved HTML	live fetch
archived	`--archived` Internet Archive fallback	paywall bypass
precision	`--precision` — less noise	default when content missing
recall	`--recall` — more text	default when noise high
doctor	Preflight JSON for binary and version	live URL smoke

术语	含义	不包含
extract	单个URL → 通过CLI提取干净文本	全站点爬取收获
metadata	使用 `with_metadata` 参数输出JSON格式元数据	仅探测裸URL
pipe	以标准输入或本地 `.html` 文件作为输入	从URL下载内容
discover	结合 `--list` 参数使用 `--feed` / `--sitemap` / `--crawl` / `--probe`	批量下载
batch	通过 `-i` 参数传入链接列表 → 输出到指定目录	静默大规模爬取
local	使用 `--input-dir` 参数重新处理已保存的HTML	实时抓取
archived	使用 `--archived` 参数调用Internet Archive作为备用源	绕过付费墙
precision	使用 `--precision` 参数 — 减少冗余内容	内容缺失时的默认模式
recall	使用 `--recall` 参数 — 获取更多文本	冗余内容较多时的默认模式
doctor	预检查二进制文件和版本的JSON输出	实时URL可用性探测

Dispatch

命令调度

`$ARGUMENTS`	Mode	Action
`doctor` / `preflight`	Doctor	Run `scripts/doctor.py --format json`
`extract <url>` / bare `https://…`	Extract	Stdout-first via `extract_url.py`
`metadata <url>`	Metadata	`extract_url.py` with `--with-metadata --format json`
`pipe <file>` / stdin HTML	Pipe	`trafilatura` on file or stdin
`discover feed <url>`	Discover	`list_urls.py --mode feed` ( `--list` only)
`discover sitemap <url>`	Discover	`list_urls.py --mode sitemap`
`discover crawl <url>`	Discover	`list_urls.py --mode crawl`
`discover probe <url>`	Discover	`list_urls.py --mode probe`
`batch <listfile>`	Batch	Approval gate → `-i` + `-o` under user dir
`local <input-dir>`	Local	Approval gate → `--input-dir` + `-o`
`archived <url>`	Archived	`extract_url.py --archived` after normal fetch fails
Natural language: "main text", "clean article", "extract from URL"	Auto	Map to extract (stdout-first)
(empty)	Help	Gallery + protocol + references

`$ARGUMENTS`	模式	操作
`doctor` / `preflight`	诊断模式	执行 `scripts/doctor.py --format json`
`extract <url>` / 直接传入 `https://…`	提取模式	通过 `extract_url.py` 优先输出到标准输出
`metadata <url>`	元数据模式	执行 `extract_url.py` 并添加 `--with-metadata --format json` 参数
`pipe <file>` / 标准输入HTML	管道模式	对文件或标准输入的HTML执行 `trafilatura` 命令
`discover feed <url>`	发现模式	执行 `list_urls.py --mode feed` （仅返回链接列表）
`discover sitemap <url>`	发现模式	执行 `list_urls.py --mode sitemap`
`discover crawl <url>`	发现模式	执行 `list_urls.py --mode crawl`
`discover probe <url>`	发现模式	执行 `list_urls.py --mode probe`
`batch <listfile>`	批量模式	需确认权限 → 使用 `-i` 和 `-o` 参数输出到用户目录
`local <input-dir>`	本地模式	需确认权限 → 使用 `--input-dir` 和 `-o` 参数
`archived <url>`	归档模式	常规抓取失败后执行 `extract_url.py --archived`
自然语言指令："main text"、"clean article"、"extract from URL"	自动模式	映射到提取模式（优先输出到标准输出）
(空参数)	帮助模式	展示示例、协议及参考文档

Auto-Detection Heuristic

自动检测规则

URL + "sitemap", "feed", "crawl", "list URLs" → Discover (
```
--list
```
only).
URL + "metadata", "title", "author", "date" → Metadata.
Path to
```
.html
```
or "pipe", "stdin", "local file" → Pipe.
Path to URL list file or "batch" → Batch (approval gate).
Directory of saved HTML → Local (approval gate).
"Archive", "wayback", "link rot" after failed fetch → Archived.
Bare URL or "extract", "clean", "article text" → Extract.
Ambiguous → ask: extract, metadata, discover list, or batch?

URL + "sitemap"、"feed"、"crawl"、"list URLs" → 发现模式（仅返回链接列表）。
URL + "metadata"、"title"、"author"、"date" → 元数据模式。
```
.html
```
文件路径或包含"pipe"、"stdin"、"local file" → 管道模式。
URL列表文件路径或包含"batch" → 批量模式（需确认权限）。
已保存HTML的目录路径 → 本地模式（需确认权限）。
抓取失败后出现"Archive"、"wayback"、"link rot" → 归档模式。
裸URL或包含"extract"、"clean"、"article text" → 提取模式。
指令模糊时 → 询问用户：提取、元数据、发现链接列表还是批量处理？

Stdout-First Protocol

标准输出优先协议

Run stages in order. Do not skip doctor after CLI errors. Do not batch-write until single-URL needs are met or the user explicitly approves bulk scope.

按顺序执行步骤。CLI报错后请勿跳过诊断步骤。在满足单URL需求或用户明确批准批量范围之前，请勿执行批量写入。

Stage 1 — Doctor (once per session or after errors)

步骤1 — 诊断（每次会话或报错后执行一次）

bash

uv run python scripts/doctor.py --format json

Stop on

ok: false

or any check with

status: fail

(missing

trafilatura

binary).

bash

uv run python scripts/doctor.py --format json

若返回

ok: false

或任何检查项

status: fail

（如缺少

trafilatura

二进制文件），则停止操作。

Stage 2 — Extract (preferred for single URLs)

步骤2 — 提取（单URL优先选择）

bash

uv run python scripts/extract_url.py --url 'https://…' --format json

Markdown (default readable):

bash

uv run python scripts/extract_url.py --url 'https://…' --output-format markdown

From probe JSON, report:

url

title

date

(if metadata),

text_length

, and format. Load references/output-formats.md when choosing formats.

bash

uv run python scripts/extract_url.py --url 'https://…' --format json

输出Markdown格式（默认易读）：

bash

uv run python scripts/extract_url.py --url 'https://…' --output-format markdown

从探测JSON中报告：

url

、

title

、

date

（若包含元数据）、

text_length

及输出格式。选择格式时可参考references/output-formats.md。

Stage 3 — Discover (list only by default)

步骤3 — 发现（默认仅返回链接列表）

bash

uv run python scripts/list_urls.py --mode sitemap --url 'https://…' --format json

Present

url_count

and a sample of URLs. Do not chain into batch download without explicit user approval.

bash

uv run python scripts/list_urls.py --mode sitemap --url 'https://…' --format json

展示

url_count

及URL示例。未经用户明确批准，请勿自动链式执行批量下载。

Stage 4 — Batch / local (explicit approval required)

步骤4 — 批量/本地处理（需明确批准）

Before running:

Confirm URL count or directory scope.
Confirm output directory (default:
```
$HOME/Downloads/trafilatura/output/
```
).
Confirm politeness acknowledgment — see references/politeness-and-ethics.md.

bash

mkdir -p "$HOME/Downloads/trafilatura/output"
trafilatura -i list.txt -o "$HOME/Downloads/trafilatura/output/" --markdown --backup-dir "$HOME/Downloads/trafilatura/html-backup/"

执行前需确认：

URL数量或目录范围。
输出目录（默认：
```
$HOME/Downloads/trafilatura/output/
```
）。
确认遵守礼貌规则 — 参考references/politeness-and-ethics.md。

bash

mkdir -p "$HOME/Downloads/trafilatura/output"
trafilatura -i list.txt -o "$HOME/Downloads/trafilatura/output/" --markdown --backup-dir "$HOME/Downloads/trafilatura/html-backup/"

Stage 5 — Escalation (missing or blocked content)

步骤5 — 问题升级（内容缺失或被拦截）

Retry with
```
--recall
```
(CLI) or
```
--recall
```
flag on
```
extract_url.py
```
.

If download blocked:

wget -qO- 'URL' | trafilatura

curl -sL 'URL' | trafilatura

If unavailable:

extract_url.py --archived

trafilatura --archived -u 'URL'

If still empty: note JS-rendered page limitation — no in-tool browser automation. See references/troubleshooting.md.

使用
```
--recall
```
参数重试（CLI或
```
extract_url.py
```
添加
```
--recall
```
标志）。

若下载被拦截：

wget -qO- 'URL' | trafilatura

或

curl -sL 'URL' | trafilatura

。

若内容不可用：

extract_url.py --archived

或

trafilatura --archived -u 'URL'

。

若仍为空：说明存在JS渲染页面限制 — 工具内无浏览器自动化功能。参考references/troubleshooting.md。

MCP fallback (no Bash)

MCP备用方案（无Bash环境）

When doctor fails because the harness has no shell, use MCPHub

trafilatura

→

fetch_and_extract

. Document degraded path. See references/mcp-fallback.md.

若因环境无Shell导致诊断失败，使用MCPHub的

trafilatura

→

fetch_and_extract

。记录降级路径。参考references/mcp-fallback.md。

Mode Details

模式详情

Extract

提取模式

Use bundled
```
extract_url.py
```
(wraps
```
trafilatura -u
```
).
Read-only regarding repo tree; stdout or JSON envelope only.
Default output: markdown for human summary; json when structured metadata is needed.

使用内置的
```
extract_url.py
```
（封装
```
trafilatura -u
```
命令）。
仅读取仓库目录；仅输出到标准输出或JSON包。
默认输出：Markdown格式（供人工阅读）；需要结构化元数据时输出JSON格式。

Metadata

元数据模式

bash

uv run python scripts/extract_url.py --url 'https://…' --output-format json --with-metadata

bash

uv run python scripts/extract_url.py --url 'https://…' --output-format json --with-metadata

Pipe

管道模式

bash

trafilatura --markdown < page.html
cat page.html | trafilatura --json --no-tables

bash

trafilatura --markdown < page.html
cat page.html | trafilatura --json --no-tables

Discover

发现模式

Modes:

feed

sitemap

crawl

probe

. Always

--list

via

list_urls.py

unless user explicitly requests harvest.

Optional filters:

--url-filter

--target-language

(requires

trafilatura[all]

). See references/discovery.md.

支持模式：

feed

、

sitemap

、

crawl

、

probe

。除非用户明确要求抓取，否则始终通过

list_urls.py

使用

--list

参数仅返回链接列表。

可选过滤参数：

--url-filter

、

--target-language

（需安装

trafilatura[all]

）。参考references/discovery.md。

Batch

批量模式

Parse list file (one URL per line).
Require approval before
```
-i
```
runs.
Recommend
```
--backup-dir
```
for HTML archival.
Never write into the agents repo.

解析列表文件（每行一个URL）。
执行
```
-i
```
命令前需获得批准。
推荐使用
```
--backup-dir
```
参数归档HTML文件。
禁止写入代理仓库目录。

Local

本地模式

```
--input-dir
```
for previously downloaded HTML.
Mirror structure with
```
--keep-dirs
```
when needed.
Approval gate same as batch.

使用
```
--input-dir
```
参数处理已下载的HTML文件。
必要时使用
```
--keep-dirs
```
参数保留目录结构。
批准流程与批量模式相同。

Archived

归档模式

Use when
```
fetch_url
```
equivalent returns nothing.
Slow; best for small URL sets.

当等效的
```
fetch_url
```
命令返回空内容时使用。
速度较慢；适合小批量URL。

Doctor

诊断模式

bash

uv run python scripts/doctor.py --format json

bash

uv run python scripts/doctor.py --format json

Help

帮助模式

Show dispatch table, stdout-first protocol, default paths, and reference index.

展示调度表、标准输出优先协议、默认路径及参考文档索引。

Gallery (Empty Arguments)

示例库（空参数）


/trafilatura doctor
/trafilatura extract https://example.org/article
/trafilatura metadata https://example.org/article
/trafilatura discover sitemap https://example.org
/trafilatura pipe saved-page.html
/trafilatura archived https://example.org/missing

#	Task	Example
1	Preflight	`/trafilatura doctor`
2	Extract article	`/trafilatura extract https://example.org/article`
3	Metadata JSON	`/trafilatura metadata https://example.org/article`
4	Discover sitemap	`/trafilatura discover sitemap https://example.org`
5	Pipe local HTML	`/trafilatura pipe saved-page.html`
6	Archived fallback	`/trafilatura archived https://example.org/missing`

Pick a number, a mode from the dispatch table, or paste a URL and say whether you need extract, metadata, or URL discovery.


/trafilatura doctor
/trafilatura extract https://example.org/article
/trafilatura metadata https://example.org/article
/trafilatura discover sitemap https://example.org
/trafilatura pipe saved-page.html
/trafilatura archived https://example.org/missing

序号	任务	示例
1	预检查	`/trafilatura doctor`
2	提取文章	`/trafilatura extract https://example.org/article`
3	输出元数据JSON	`/trafilatura metadata https://example.org/article`
4	发现站点地图链接	`/trafilatura discover sitemap https://example.org`
5	处理本地HTML管道	`/trafilatura pipe saved-page.html`
6	归档备用提取	`/trafilatura archived https://example.org/missing`

选择序号、调度表中的模式，或粘贴URL并说明需要提取、元数据还是URL发现功能。

Critical Rules

核心规则

Doctor before first extract in a session (or after CLI errors).
Stdout-first for single URLs — use
```
extract_url.py
```
before filesystem batch writes.
Discover list-only by default — present URL count; no auto bulk download.
Explicit approval for batch/local — confirm scope, output dir, politeness.
No paywall bypass coaching — see references/politeness-and-ethics.md.
Not Fetch MCP primary — article main-text extraction belongs here when trafilatura is appropriate.
Not research — multi-source synthesis uses
```
/research
```
.
Not docling — PDFs and table-heavy documents use docling MCP.
Not yt-dlp — video/audio hosts use
```
/yt-dlp
```
.
Report provenance — URL, format, title/date if present, text length in summary.

每次会话首次提取前需执行诊断（或CLI报错后）。
单URL优先输出到标准输出 — 在执行文件系统批量写入前使用
```
extract_url.py
```
。
发现模式默认仅返回链接列表 — 展示URL数量；禁止自动批量下载。
批量/本地处理需明确批准 — 确认范围、输出目录及礼貌规则。
禁止指导绕过付费墙 — 参考references/politeness-and-ethics.md。
非Fetch MCP主工具 — 当trafilatura适用时，文章正文提取属于本工具范畴。
非研究工具 — 多源合成使用
```
/research
```
工具。
非docling工具 — PDF和表格密集型文档使用docling MCP工具。
非yt-dlp工具 — 视频/音频平台使用
```
/yt-dlp
```
工具。
报告来源信息 — 摘要中需包含URL、格式、标题/日期（若存在）及文本长度。

Troubleshooting

故障排除

See references/troubleshooting.md for precision/recall, archived fallback, wget/curl pipe, and JS-rendered pages.

关于精确/召回模式、归档备用方案、wget/curl管道及JS渲染页面的问题，请参考references/troubleshooting.md。

References

参考文档

File	Use when
output-formats.md	Choosing txt/json/markdown/xml formats
discovery.md	Feed, sitemap, crawl, url-filter
troubleshooting.md	Missing content, blocked downloads
politeness-and-ethics.md	Robots, rate limits, refusals
mcp-fallback.md	Shell-less harness / MCPHub path

文件	使用场景
output-formats.md	选择txt/json/markdown/xml输出格式时
discovery.md	处理Feed、站点地图、爬取、URL过滤时
troubleshooting.md	内容缺失、下载被拦截时
politeness-and-ethics.md	机器人协议、速率限制、拒绝规则相关
mcp-fallback.md	无Shell环境 / MCPHub路径相关

Scripts

脚本说明

Script	Purpose
`scripts/doctor.py`	JSON preflight: trafilatura binary and version
`scripts/extract_url.py`	Single-URL CLI wrapper with JSON envelope
`scripts/list_urls.py`	Discovery `--list` wrapper
`scripts/check.py`	Validate skill manifest and evals

脚本	用途
`scripts/doctor.py`	JSON格式预检查：trafilatura二进制文件及版本
`scripts/extract_url.py`	单URL CLI封装工具，输出JSON包
`scripts/list_urls.py`	发现模式的 `--list` 参数封装工具
`scripts/check.py`	验证技能清单及评估内容

Examples

示例命令

bash

undefined

bash

undefined

Preflight

预检查

uv run python scripts/doctor.py --format json

Extract (stdout-first)

提取（优先输出到标准输出）

uv run python scripts/extract_url.py --url 'https://github.blog/2019-03-29-leader-spotlight-erin-spiceland/' --output-format markdown

Metadata JSON

输出元数据JSON

uv run python scripts/extract_url.py --url 'https://example.org' --output-format json --with-metadata

Discover sitemap URLs (list only)

发现站点地图URL（仅返回列表）

uv run python scripts/list_urls.py --mode sitemap --url 'https://www.sitemaps.org/' --format json

Pipe local HTML

处理本地HTML管道

trafilatura --markdown < saved.html

Batch (after user approval)

批量处理（用户批准后）

trafilatura -i urls.txt -o "$HOME/Downloads/trafilatura/output/" --markdown --backup-dir "$HOME/Downloads/trafilatura/html-backup/"

undefined

trafilatura -i urls.txt -o "$HOME/Downloads/trafilatura/output/" --markdown --backup-dir "$HOME/Downloads/trafilatura/html-backup/"

undefined