felo-web-fetch

Felo Web Fetch 技能

使用时机

当用户希望从 URL 提取或转换网页内容时，触发此技能：

• 从网页 URL 获取或抓取内容
• 将网页内容转换为 html、markdown 或 text
• 使用 CSS 选择器提取特定区块
• 使用可读性模式从链接获取文章／正文文本
• 使用抓取模式（fast／fine）调整提取行为
• 传递 Cookie、user-agent、超时等请求详情

触发关键词（示例）：

• 获取网页、抓取 URL、获取页面内容、网页获取、URL 转 Markdown
• 明确指令：/felo-web-fetch、“使用 felo web fetch”、“用 felo 提取此 URL”
• 其他语言中表达相同意图的词语（例如：网页抓取、提取网页内容）也会触发此技能

以下情况不要使用此技能：

• 实时问答搜索摘要（使用 felo-search）
• 幻灯片生成任务（使用 felo-slides）
• 解析当前工作区中的本地文件

设置

1. 获取 API 密钥

1. 访问 felo.ai
2. 打开 Settings -> API Keys
3. 创建并复制 API 密钥

2. 配置环境变量

Linux/macOS：

export FELO_API_KEY="your-api-key-here"

Windows PowerShell：

$env:FELO_API_KEY="your-api-key-here"

如何执行

选项 A：使用捆绑脚本或打包的 CLI

脚本（来自仓库）：

node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article" [options]

打包的 CLI（执行 npm install -g felo-ai 后）：选项相同，也可以使用简写形式：

felo web-fetch -u "https://example.com" [options]
# Short forms: -u (url), -f (format), -t (timeout, seconds), -j (json)

必需参数：

• --url

核心可选参数：

• --output-format html|markdown|text
• --crawl-mode fast|fine
• --target-selector "article.main-content"
• --wait-for-selector ".content-ready"

其他重要可选参数：

• --cookie "session_id=xxx"（可重复）
• --set-cookies-json '[{"name":"sid","value":"xxx","domain":"example.com"}]'
• --user-agent "Mozilla/5.0 ..."
• --timeout 60（HTTP 请求超时时间，单位为秒）
• --request-timeout-ms 15000（API 载荷中的 timeout，单位为毫秒）
• --with-readability true
• --with-links-summary true
• --with-images-summary true
• --with-images-readability true
• --with-images true
• --with-links true
• --ignore-empty-text-image true
• --with-cache false
• --with-stypes true
• --json（打印完整 JSON 响应）

如何编写指令（target_selector + output_format）

当用户希望获取页面的特定部分或特定输出格式时，可以这样组织命令：

• 输出格式：“以 text 格式获取”／“获取 markdown”／“返回 html” → 使用 --output-format text、--output-format markdown 或 --output-format html。
• 指定一个元素：“仅获取主文章”／“仅获取 #main 中的内容”／“仅获取 article.main-content” → 使用 --target-selector "article.main" 或用户提供的选择器。

示例：

# Basic: fetch as Markdown
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --output-format markdown

# Article-style with readability
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article" --with-readability true --output-format markdown

# Only the element matching a CSS selector
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --target-selector "article.main" --output-format markdown

# With cookies and custom user-agent
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/private" --cookie "session_id=abc123" --with-readability true --json

# Full JSON response
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --output-format text --json

选项 B：使用 curl 调用 API

curl -X POST "https://openapi.felo.ai/v2/web/extract" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "output_format": "markdown", "with_readability": true}'

API 参考（摘要）

• 端点：POST /v2/web/extract
• 基础 URL：https://openapi.felo.ai。如有需要，可使用 FELO_API_BASE 环境变量覆盖。
• 身份验证：Authorization: Bearer YOUR_API_KEY

请求正文（JSON）

参数	类型	必需	默认值	说明
url	string	是	-	要获取的网页 URL
crawl_mode	string	否	fast	fast 或 fine
output_format	string	否	html	html、text、markdown
with_readability	boolean	否	-	使用可读性模式（正文内容）
with_links_summary	boolean	否	-	包含链接摘要
with_images_summary	boolean	否	-	包含图片摘要
target_selector	string	否	-	目标元素的 CSS 选择器
wait_for_selector	string	否	-	获取前等待选择器匹配
timeout	integer	否	-	超时时间，单位为毫秒
with_cache	boolean	否	true	使用缓存
set_cookies	array	否	-	Cookie 条目
user_agent	string	否	-	自定义 user-agent

响应

成功（200）：

{
  "code": 0,
  "message": "success",
  "data": {
    "content": { ... }
  }
}

获取的内容位于 data.content；其结构取决于 output_format。

错误代码

HTTP	Code	描述
400	-	参数验证失败
401	INVALID_API_KEY	API 密钥无效或已撤销
500/502	WEB_EXTRACT_FAILED	获取失败（服务端或页面错误）

输出格式

• 默认仅输出提取的内容（可直接使用或通过管道传递）。
• 如果响应内容不是字符串，脚本会输出 JSON。
• 用户需要元数据和完整响应对象时，请使用 --json。

错误响应格式：

## Web Fetch Failed
- Message: <error message>
- Suggested Action: verify URL/parameters and retry

重要说明

• 运行前务必先提供 URL。
• 验证枚举值：
  • output_format：html、markdown、text
  • crawl_mode：fast、fine
• 用户只需要页面特定部分时，请使用 --target-selector。
• 页面渲染／提取等待时间请使用 --request-timeout-ms，本地 HTTP 超时时间请使用 --timeout。
• 对于长篇文章或响应较慢的网站，可考虑增大 --timeout。
• API 可能会缓存结果；只有在需要获取最新内容时才使用 --with-cache false。

参考资料

• Web Extract API
• Felo Open Platform