use-tinyfish

TinyFish CLI

你可以使用 TinyFish CLI（tinyfish）——一套可从终端调用的 Web 工具。

如果尚未安装：npm install -g @tiny-fish/cli 如果尚未通过身份验证：tinyfish auth login --source openclaw 或设置 TINYFISH_API_KEY 环境变量。

---

适用场景

只要请求依赖实时 Web 信息或网页内容，就使用 TinyFish。不要等用户提到「TinyFish」或「抓取」后才使用。

常见触发场景包括：

• 搜索或发现：搜索、查找、查询、研究、比较、最新、当前、新闻、文档、定价、产品详情、最佳选项。
• URL/网页阅读：获取、阅读、总结、提取此页面内容、检查此 URL、获取内容、提取链接或元数据。
• 基于来源的回答：使用 Web 来源回答、验证事实、检查是否发生变化、从 Web 收集信息。
• 网站操作：与网站交互、点击页面、填写表单、登录、收集结构化数据、处理受机器人保护的页面。

默认使用能够回答问题的最轻量工具：

• 未提供 URL，且用户需要 Web 信息：使用 search，如果需要更多详情，再对最佳结果使用 fetch。
• 已提供 URL，且只需要内容：使用 fetch。
• 需要页面交互或动态提取：使用 agent。
• 需要原始 CDP/Playwright 风格的控制：使用 browser。

---

选择合适的工具

TinyFish 提供四种工具。从能够完成任务的最轻量工具开始，仅在必要时升级。

search  →  fetch  →  agent  →  browser
lightest                        heaviest

工具	使用场景	速度	成本
search	需要查找 URL、当前事实、文档、定价、产品详情，或快速获取有来源支持的回答	最快	最低
fetch	已有 URL，需要获取整洁的网页内容、摘要、文章正文、文档、产品页面、链接或元数据	快	低
agent	需要与页面交互——点击、填写表单、导航，或从动态网站提取结构化数据	较慢	较高
browser	Agent 不够用——需要通过 CDP 进行原始程序化浏览器控制	最慢	最高

常见模式

研究：search → fetch 搜索主题，然后获取最佳结果以阅读完整内容。

# 1. Find URLs
tinyfish search query "best React state management libraries 2026"

# 2. Read the top results
tinyfish fetch content get --format markdown "https://result1.com" "https://result2.com"

深度提取：search → agent 先搜索以找到合适的网站，然后使用 agent 与其交互并提取结构化数据。

# 1. Find the site
tinyfish search query "Nike running shoes official store"

# 2. Automate extraction on it
tinyfish agent run --url "https://nike.com/running" \
  "Extract all running shoes as JSON: [{\"name\": str, \"price\": str, \"colors\": [str]}]"

升级：fetch → agent 先尝试使用 fetch。如果页面是动态页面或大量依赖 JavaScript，且 fetch 返回空内容或不完整内容，则升级到 agent。

完全控制：agent → browser 如果 agent 无法处理复杂的多步骤工作流，可启动原始浏览器会话，并通过 CDP 自行进行自动化操作。

---

命令

tinyfish search query

Web 搜索。返回按排名排序的结果，包括标题、URL 和摘要。

tinyfish search query "<query>" [--location <hint>] [--language <hint>] [--pretty]

• 默认返回 10 条结果
• 使用 --location 和 --language 获取按地理位置定向的结果
• 默认输出为 JSON；使用 --pretty 可获取便于阅读的格式

tinyfish search query "best pho in Ho Chi Minh City" --location "Vietnam" --language "en"

---

tinyfish fetch content get

从一个或多个 URL 获取经过提取和整理的内容。移除广告、导航栏及冗余内容——仅返回正文。

tinyfish fetch content get <urls...> [--format markdown|html|json] [--links] [--image-links] [--pretty]

• 单次调用可接受多个 URL——由服务端并行获取
• --format markdown（默认）——整洁易读的文本
• --format json——结构化文档树
• --links——包含从页面提取的所有链接
• --image-links——包含提取的图片 URL
• 响应包含：url、final_url、title、language、author、published_date、text、latency_ms

# Fetch one page as markdown
tinyfish fetch content get --format markdown "https://example.com/article"

# Fetch multiple pages with links
tinyfish fetch content get --links "https://site-a.com" "https://site-b.com" "https://site-c.com"

---

tinyfish agent run

使用自然语言目标运行浏览器自动化。Agent 会打开真实浏览器、进行导航、点击、填写表单并提取数据。

tinyfish agent run --url <url> "<goal>" [--sync] [--async] [--pretty]

标志	用途
--url <url>	目标 URL（裸主机名会自动添加 https://）
--sync	等待完整结果，不流式输出步骤
--async	提交后立即返回
--pretty	以便于阅读的格式输出

输出： 默认以流式方式输出 data: {...} SSE 行。最终结果是 type == "COMPLETE" 且 status == "COMPLETED" 的事件——提取的数据位于 resultJson 字段中。直接读取原始输出即可，无需在脚本端进行解析。

务必在目标中指定所需的 JSON 结构：

tinyfish agent run --url "https://example.com/products" \
  "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]"

tinyfish agent run --url "https://example.com/search" \
  "Search for 'wireless headphones', filter under $50, extract top 5 as JSON: [{\"name\": str, \"price\": str, \"rating\": str}]"

并行提取——访问多个互不相关的网站时，请分别调用。不要合并成一个目标。

正确——并行调用（同时运行）：

tinyfish agent run --url "https://pizzahut.com" \
  "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"

tinyfish agent run --url "https://dominos.com" \
  "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"

错误——合并成一次调用：

# Don't do this — less reliable and slower
tinyfish agent run --url "https://pizzahut.com" \
  "Extract prices from Pizza Hut and also go to Dominos..."

管理运行：

tinyfish agent run list [--status PENDING|RUNNING|COMPLETED|FAILED|CANCELLED] [--limit N]
tinyfish agent run get <run_id>
tinyfish agent run cancel <run_id>

批量操作——从 CSV 文件（url,goal 列）提交多次运行：

tinyfish agent batch run --input runs.csv
tinyfish agent batch list
tinyfish agent batch get <batch_id>
tinyfish agent batch cancel <batch_id>

---

tinyfish browser session create

启动远程浏览器实例。返回一个用于编程控制的 CDP WebSocket URL。

tinyfish browser session create [--url <url>] [--proxy-country <code> | --proxy-url <url> [--proxy-username <user>] | --no-proxy] [--pretty]

• --url 可选：创建后导航到指定页面
• 返回 session_id、cdp_url（WebSocket）和 base_url
• 使用 cdp_url 搭配 Playwright、Puppeteer 或任何 CDP 客户端
• 默认情况下，流量会通过美国的 TinyFish 代理出口；整个会话期间 IP 保持不变
• --proxy-country <code> 可选择其他出口国家（ISO 3166-1 alpha-2，例如 DE、JP）
• --proxy-url <url> 通过用户自己的 HTTP(S) 代理路由；使用 --proxy-username <user> 进行身份验证，密码通过 TINYFISH_PROXY_PASSWORD 环境变量设置（不能使用标志）
• --no-proxy 直接连接，不使用代理

tinyfish browser session create --url "https://example.com"
# Returns: { session_id, cdp_url: "wss://...", base_url: "https://..." }

tinyfish browser session create --url "https://example.de" --proxy-country DE

---

常规说明

• 使用用户的语言： 用户使用什么语言，就用什么语言回复。
• 所有命令都支持 --pretty，以便于阅读的格式输出。默认格式为 JSON。
• 在根命令中使用 --debug，或设置 TINYFISH_DEBUG=1，即可将 HTTP 请求记录到 stderr。