TinyFish CLI

您可使用 TinyFish CLI（tinyfish）—— 一套可通过终端调用的 Web 工具集。

如尚未安装： npm install -g @tiny-fish/cli
如尚未认证：运行 tinyfish auth login --source openclaw，或设置环境变量 TINYFISH_API_KEY。

此技能应触发的时机

只要用户请求依赖实时 Web 信息或网页内容，即应启用 TinyFish。无需等待用户明确提及 “TinyFish” 或 “scrape” 等关键词。

典型触发场景包括：

• 搜索与发现：搜索、查找、查询、调研、对比、最新、当前、新闻、文档、定价、产品详情、最佳选项等。
• URL/页面读取：获取、阅读、摘要、从该页面提取、检查该 URL、获取页面内容、拉取链接或元数据等。
• 信源支撑型回答：基于 Web 信源作答、验证事实、确认某项内容是否更新、从 Web 收集信息等。
• 网站交互类任务：与网站互动、逐页点击浏览、填写表单、登录、采集结构化数据、处理防爬保护页面等。

默认优先选用能满足需求的最轻量级工具：

• 未提供 URL，但需 Web 信息 → 先用 search；若需更详细内容，再对最优结果调用 fetch。
• 已提供 URL，且仅需页面内容 → 直接用 fetch。
• 需页面交互或动态内容提取 → 使用 agent。
• 需原始 CDP / Playwright 风格的底层浏览器控制 → 使用 browser。

如何选择合适工具

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

search  →  fetch  →  agent  →  browser
轻量级                        重量级

常见使用模式

调研流程：search → fetch
先搜索目标主题，再对最优结果调用 fetch，以读取其完整内容。

# 1. 查找相关 URL
tinyfish search query "best React state management libraries 2026"

# 2. 获取前几条结果的全文内容
tinyfish fetch content get --format markdown "https://result1.com" "https://result2.com"

深度提取：search → agent
先搜索定位目标站点，再使用 agent 与其交互并提取结构化数据。

# 1. 定位目标网站
tinyfish search query "Nike running shoes official store"

# 2. 在该站点上自动化执行提取
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 "" [--location ] [--language ] [--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  [--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

# 以 Markdown 格式获取单个页面
tinyfish fetch content get --format markdown "https://example.com/article"

# 并行获取多个页面，并附带所有链接
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  "" [--sync] [--async] [--pretty]

输出说明： 默认以 Server-Sent Events（SSE）格式流式输出 data: {...} 行。最终结果对应事件中 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}]"

❌ 不推荐方式（单一合并调用）：

# 请勿如此操作 —— 可靠性更低且执行更慢
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 
tinyfish agent run cancel 

批量操作 —— 可通过 CSV 文件（含 url,goal 两列）一次性提交多个任务：

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

tinyfish browser session create

创建一个远程浏览器实例，返回可用于程序化控制的 CDP WebSocket 地址。

tinyfish browser session create [--url ] [--pretty]

• --url 参数可选，用于在会话创建后自动跳转至指定页面
• 返回字段包括：session_id、cdp_url（WebSocket 地址）和 base_url
• 可将 cdp_url 与 Playwright、Puppeteer 或任意兼容 CDP 的客户端配合使用

tinyfish browser session create --url "https://example.com"
# 返回示例：{ session_id, cdp_url: "wss://...", base_url: "https://..." }

通用说明

• 匹配用户语言：请使用用户输入所用的语言进行响应。
• 所有命令均支持 --pretty 参数以输出人类可读格式；默认输出为 JSON。
• 可在根命令上添加 --debug，或设置环境变量 TINYFISH_DEBUG=1，将 HTTP 请求日志输出至 stderr。