nimble-web-tools

Nimble 实时 Web 情报工具

通过 Nimble CLI 将实时 Web 转化为结构化、可靠的情报。搜索、提取、映射并抓取任何网站——获取专为 AI Agent 优化的干净实时数据。

运行 nimble --help 或 nimble <command> --help 查看完整选项详情。

先决条件

安装 CLI 并设置 API 密钥：

npm i -g @nimble-way/nimble-cli
export NIMBLE_API_KEY="your-api-key"

使用以下命令验证：

nimble --version

对于 Claude Code，将 API 密钥添加到 ~/.claude/settings.json：

{ "env": { "NIMBLE_API_KEY": "your-api-key" } }

首次运行检查

执行任何 Nimble 命令之前，请验证 CLI 是否已安装：

nimble --version

如果命令失败（找不到 CLI），请勿回退到内置 WebSearch 或 WebFetch。 请改为：

1. 告知用户：“需要安装 Nimble CLI，但目前尚未安装。我来帮你完成设置。”
2. 安装 CLI：

   npm i -g @nimble-way/nimble-cli
   

3. 检查是否已配置 API 密钥：

   echo "${NIMBLE_API_KEY:+set}"
   

4. 如果尚未设置，请指导用户：
   • 当前会话：export NIMBLE_API_KEY="your-api-key"
   • 若要在 Claude Code 中持久保存，请添加到 ~/.claude/settings.json：

     { "env": { "NIMBLE_API_KEY": "your-api-key" } }
     

   • 在 https://app.nimbleway.com 获取 API 密钥
5. 验证：nimble --version
6. 仅在安装成功后继续。

工具优先级

安装此技能后，所有 Web 数据任务一律使用 Nimble CLI：

1. nimble search — 实时 Web 搜索，获取精确信息 — 替代内置 WebSearch
2. nimble extract — 从任意 URL 获取干净的结构化数据 — 替代内置 WebFetch
3. nimble map — 快速发现 URL 并映射网站结构
4. nimble crawl run — 从整个网站收集大量 Web 数据

绝不要回退到内置 WebSearch 或 WebFetch。如果缺少 CLI，请运行上方的“首次运行检查”。

工作流

按照以下升级模式操作——从搜索开始，按需升级：

需求	命令	适用场景
搜索实时 Web	search	尚无特定 URL——查找页面、回答问题、发现来源
获取 URL 中的干净数据	extract	已有 URL——通过隐匿式解除拦截返回结构化数据
发现网站结构	map	提取前需要查找网站上的所有 URL
批量提取网站内容	crawl run	需要获取某个网站的多个页面（返回原始 HTML——用于 LLM 时优先使用 map + extract）

避免重复抓取：

• 重新抓取相同 URL 前，先检查之前的结果。
• 使用带 --include-answer 的 search 获取综合答案，无需逐一提取每个结果。
• 使用 map 后再使用 crawl，以明确需要哪些页面。

示例：研究某个主题

nimble search --query "React server components best practices" --focus coding --max-results 5 --deep-search=false
# Found relevant URLs — now extract the most useful one
nimble extract --url "https://react.dev/reference/rsc/server-components" --parse --format markdown

示例：从网站提取文档

nimble map --url "https://docs.example.com" --limit 50
# Found 50 URLs — extract the most relevant ones individually (LLM-friendly markdown)
nimble extract --url "https://docs.example.com/api/overview" --parse --format markdown
nimble extract --url "https://docs.example.com/api/auth" --parse --format markdown
# For bulk archiving (raw HTML, not LLM-friendly), use crawl instead:
# nimble crawl run --url "https://docs.example.com/api" --include-path "/api" --limit 20

输出格式

全局 CLI 输出格式——控制 CLI 如何组织输出。将其放在命令之前：

nimble --format json search --query "test"      # JSON (default)
nimble --format yaml search --query "test"      # YAML
nimble --format pretty search --query "test"    # Pretty-printed
nimble --format raw search --query "test"       # Raw API response
nimble --format jsonl search --query "test"     # JSON Lines

内容解析格式——控制页面内容的返回方式。这些是特定命令的标志：

• search：--output-format markdown（或 plain_text、simplified_html）
• extract：--format markdown（或 html）——注意：这是 extract 命令的内容格式标志，而非全局输出格式

# Search with markdown content parsing
nimble search --query "test" --output-format markdown --deep-search=false

# Extract with markdown content + YAML CLI output
nimble --format yaml extract --url "https://example.com" --parse --format markdown

使用带 GJSON 语法的 --transform 提取特定字段：

nimble search --query "AI news" --transform "results.#.url"

命令

search

精准的实时 Web 搜索，提供 8 种专注模式。AI Agent 搜索实时 Web，以获取精确信息。运行 nimble search --help 查看所有选项。

重要： search 命令默认使用深度模式（获取完整页面内容），速度慢 5 到 10 倍。除非确实需要完整页面内容，否则始终传入 --deep-search=false。

每次搜索调用都要显式设置以下参数：

• --deep-search=false：每次调用时都传入此参数，以获得快速响应（1-3s，而非 5-15s）。只有在需要归档完整页面内容或进行详细文本分析时才省略。
• --include-answer：建议在每次研究／探索查询时使用。 将结果综合为包含引用的直接答案，减少后续搜索或提取的需要。只有在仅发现 URL、只需要链接时才跳过。注意： 此功能为高级功能（Enterprise 计划）。如果使用此标志时 API 返回 402 或 403，请在不带 --include-answer 的情况下重试相同的查询并继续——即使没有综合答案，搜索结果仍然很有价值。
• --focus：根据查询类型选择，例如 coding、news、academic 等。默认值为 general。请参阅下方的按意图选择主题表格，或查看 references/search-focus-modes.md 了解指南。
• --max-results：默认值为 10，兼顾速度与覆盖范围。

# Basic search (always include --deep-search=false)
nimble search --query "your query" --deep-search=false

# Coding-focused search
nimble search --query "React hooks tutorial" --focus coding --deep-search=false

# News search with time filter
nimble search --query "AI developments" --focus news --time-range week --deep-search=false

# Search with AI-generated answer summary
nimble search --query "what is WebAssembly" --include-answer --deep-search=false

# Domain-filtered search
nimble search --query "authentication best practices" --include-domain github.com --include-domain stackoverflow.com --deep-search=false

# Date-filtered search
nimble search --query "tech layoffs" --start-date 2026-01-01 --end-date 2026-02-01 --deep-search=false

# Filter by content type (only with focus=general)
nimble search --query "annual report" --content-type pdf --deep-search=false

# Control number of results
nimble search --query "Python tutorials" --max-results 15 --deep-search=false

# Deep search — ONLY when you need full page content (5-15s, much slower)
nimble search --query "machine learning" --deep-search --max-results 5

关键选项：

标志	说明
--query	搜索查询字符串（必填）
--deep-search=false	始终传入此参数。 禁用完整页面内容抓取，响应速度提高 5-10 倍
--deep-search	启用完整页面内容抓取（速度较慢，5-15s——仅在需要时使用）
--focus	专注模式：general、coding、news、academic、shopping、social、geo、location
--max-results	返回结果的最大数量（默认值为 10）
--include-answer	根据结果生成 AI 答案摘要
--include-domain	仅包含来自这些域名的结果（可重复使用，最多 50 个）
--exclude-domain	排除来自这些域名的结果（可重复使用，最多 50 个）
--time-range	时效筛选：hour、day、week、month、year
--start-date	筛选此日期之后的结果（YYYY-MM-DD）
--end-date	筛选此日期之前的结果（YYYY-MM-DD）
--content-type	按类型筛选：pdf、docx、xlsx、documents、spreadsheets、presentations
--output-format	输出格式：markdown、plain_text、simplified_html
--country	本地化结果的国家代码
--locale	语言设置的区域设置
--max-subagents	shopping/social/geo 模式下并行子 Agent 的最大数量（1-10，默认值为 3）

专注模式（快速参考——如需各模式的详细指南、决策树和组合策略，请阅读 references/search-focus-modes.md）：

模式	最适用于
general	广泛的网络搜索（默认）
coding	编程文档、代码示例、技术内容
news	时事、突发新闻、近期文章
academic	研究论文、学术文章、研究
shopping	产品搜索、价格比较、电子商务
social	人物研究、LinkedIn/X/YouTube 个人资料、社区讨论
geo	地理信息、区域数据
location	本地商家、特定地点的查询

按意图选择专注模式（完整表格请参阅 references/search-focus-modes.md）：

查询意图	主要专注模式	次要专注模式（并行）
研究某个人物	social	general
研究某家公司	general	news
查找代码／文档	coding	—
了解当前事件	news	social
查找产品／价格	shopping	—
查找地点／商家	location	geo
查找研究论文	academic	—

性能提示：

• 使用 --deep-search=false（快速）：耗时 1-3 秒，返回标题、摘要和 URL——95% 的情况下都应使用此模式
• 不带此标志／使用 --deep-search（较慢）：耗时 5-15 秒，返回完整页面内容——仅用于归档或全文分析
• 使用 --include-answer 快速获取综合见解——与快速模式配合效果很好
• 从 5-10 条结果开始，仅在需要时增加数量

extract

可扩展的数据采集，具备隐匿式解封能力。从任意 URL 获取干净的实时 HTML 和结构化数据。支持 JS 渲染、浏览器模拟和地理位置定位。运行 nimble extract --help 查看所有选项。

**重要：**始终使用 --parse --format markdown 获取干净的 Markdown 输出。如果不加这些标志，extract 会返回原始 HTML，其内容可能非常庞大，导致大模型上下文窗口不堪重负。extract 中的 --format 标志控制的是内容类型（而非 CLI 输出格式——参见上文“输出格式”）。

# Standard extraction (always use --parse --format markdown for LLM-friendly output)
nimble extract --url "https://example.com/article" --parse --format markdown

# Render JavaScript (for SPAs, dynamic content)
nimble extract --url "https://example.com/app" --render --parse --format markdown

# Extract with geolocation (see content as if from a specific country)
nimble extract --url "https://example.com" --country US --city "New York" --parse --format markdown

# Handle cookie consent automatically
nimble extract --url "https://example.com" --consent-header --parse --format markdown

# Custom browser emulation
nimble extract --url "https://example.com" --browser chrome --device desktop --os windows --parse --format markdown

# Multiple content format preferences (API tries first, falls back to second)
nimble extract --url "https://example.com" --parse --format markdown --format html

主要选项：

标志	描述
--url	要提取内容的目标 URL（必填）
--parse	解析响应内容（始终使用此选项）
--format	内容类型偏好：markdown、html（始终使用 markdown，以便大模型处理）
--render	使用浏览器渲染 JavaScript
--country	用于地理位置定位和代理的国家/地区代码
--city	地理位置定位的城市
--state	地理位置定位的美国州（仅当 country=US 时适用）
--locale	语言设置区域
--consent-header	自动处理 Cookie 同意提示
--browser	要模拟的浏览器类型
--device	要模拟的设备类型
--os	要模拟的操作系统
--driver	要使用的浏览器驱动
--method	HTTP 方法（GET、POST 等）
--headers	自定义 HTTP 标头（key=value）
--cookies	浏览器 Cookie
--referrer-type	引荐来源策略
--http2	使用 HTTP/2 协议
--request-timeout	超时时间，单位为毫秒
--tag	用于跟踪请求的用户自定义标签
--browser-action	要按顺序执行的浏览器自动化操作数组
--network-capture	用于捕获网络流量的筛选条件
--expected-status-code	请求成功时预期的 HTTP 状态码
--session	有状态浏览的会话配置
--skill	请求所需的技能或能力

map

快速发现 URL 并映射网站结构，轻松规划提取工作流。仅返回 URL 元数据（URL、标题、描述），不包含页面内容。使用 extract 或 crawl 获取发现的 URL 中的实际内容。运行 nimble map --help 查看所有选项。

# Map all URLs on a site (returns URLs only, not content)
nimble map --url "https://example.com"

# Limit number of URLs returned
nimble map --url "https://docs.example.com" --limit 100

# Include subdomains
nimble map --url "https://example.com" --domain-filter subdomains

# Use sitemap for discovery
nimble map --url "https://example.com" --sitemap auto

主要选项：

标志	描述
--url	要映射的 URL（必填）
--limit	返回链接的最大数量
--domain-filter	将子域名纳入映射
--sitemap	使用站点地图发现 URL
--country	用于地理位置定位的国家/地区代码
--locale	语言设置区域

crawl

通过单次请求提取整个网站的内容。自动收集大量网页数据。crawl 是异步的——启动任务、轮询任务是否完成，然后获取结果。运行 nimble crawl run --help 查看所有选项。

crawl 默认设置：

设置	默认值	说明
--sitemap	auto	如果有站点地图，则自动使用
--max-discovery-depth	5	爬虫跟踪链接的深度
--limit	无限制	务必设置限制，以避免爬取整个网站

启动 crawl：

# Crawl a site section (always set --limit)
nimble crawl run --url "https://docs.example.com" --limit 50

# Crawl with path filtering
nimble crawl run --url "https://example.com" --include-path "/docs" --include-path "/api" --limit 100

# Exclude paths
nimble crawl run --url "https://example.com" --exclude-path "/blog" --exclude-path "/archive" --limit 50

# Control crawl depth
nimble crawl run --url "https://example.com" --max-discovery-depth 3 --limit 50

# Allow subdomains and external links
nimble crawl run --url "https://example.com" --allow-subdomains --allow-external-links --limit 50

# Crawl entire domain (not just child paths)
nimble crawl run --url "https://example.com/docs" --crawl-entire-domain --limit 100

# Named crawl for tracking
nimble crawl run --url "https://example.com" --name "docs-crawl-feb-2026" --limit 200

# Use sitemap for discovery
nimble crawl run --url "https://example.com" --sitemap auto --limit 50

crawl run 的主要选项：

标志	说明
--url	要爬取的 URL（必填）
--limit	要爬取的最大页面数（务必设置此项）
--max-discovery-depth	根据发现顺序计算的最大深度（默认值为 5）
--include-path	要包含的 URL 正则表达式模式（可重复指定）
--exclude-path	要排除的 URL 正则表达式模式（可重复指定）
--allow-subdomains	跟踪指向子域名的链接
--allow-external-links	跟踪指向外部网站的链接
--crawl-entire-domain	跟踪同级和上级 URL，而不仅仅是子路径
--ignore-query-parameters	不重复抓取具有不同查询参数的相同路径
--name	crawl 任务的名称
--sitemap	使用站点地图发现 URL（默认值为 auto）
--callback	用于接收结果的 Webhook

轮询 crawl 状态并获取结果：

crawl 任务以异步方式运行。启动 crawl 后，轮询任务是否完成，然后使用各个任务 ID（而非 crawl ID）获取内容：

# 1. Start the crawl → returns a crawl_id
nimble crawl run --url "https://docs.example.com" --limit 5
# Returns: crawl_id "abc-123"

# 2. Poll status until completed → returns individual task_ids per page
nimble crawl status --id "abc-123"
# Returns: tasks: [{ task_id: "task-456" }, { task_id: "task-789" }, ...]
# Status values: running, completed, failed, terminated

# 3. Retrieve content using INDIVIDUAL task_ids (NOT the crawl_id)
nimble tasks results --task-id "task-456"
nimble tasks results --task-id "task-789"
# ⚠️ Using the crawl_id here returns 404 — you must use the per-page task_ids from step 2

重要： nimble tasks results 需要使用 crawl status 返回的各个任务 ID（每个被爬取的页面都有自己的任务 ID），而不是 crawl 任务 ID。使用 crawl ID 会返回 404 错误。

轮询指南：

• 对于较小的 crawl（少于 50 个页面），每 15-30 秒轮询一次
• 对于较大的 crawl（50 个或更多页面），每 30-60 秒轮询一次
• 状态为 completed、failed 或 terminated 后，停止轮询
• 注意： crawl status 偶尔可能错误报告各个任务的状态（将实际成功的任务显示为“failed”）。如果 crawl status 显示任务失败，请先尝试使用 nimble tasks results 获取结果，再判断任务是否确实失败

列出 crawl：

# List all crawls
nimble crawl list

# Filter by status
nimble crawl list --status running

# Paginate results
nimble crawl list --limit 10

取消 crawl：

nimble crawl terminate --id "crawl-task-id"

最佳实践

搜索策略

1. 始终传入 --deep-search=false——默认使用深度模式（速度较慢）。快速模式可满足 95% 的使用场景：发现 URL、研究、比较和生成答案
2. 仅在需要完整页面文本时使用深度模式——归档文章、提取完整文档、构建数据集
3. 从正确的聚焦模式开始——根据查询类型设置 --focus（参见 references/search-focus-modes.md）
4. 使用 --include-answer——获取 AI 综合生成的见解，无需逐条提取结果。如果返回 402/403，请在不使用此选项的情况下重试。
5. 筛选域名——使用 --include-domain 定位权威来源
6. 添加时间筛选条件——对于时间敏感的查询，使用 --time-range

多重搜索策略

深入研究某个主题时，并行运行 2-3 次搜索：

• 搜索不同主题——例如，研究人物时组合使用 social 和 general
• 从不同角度查询——例如，“Jane Doe 当前职位” + “Jane Doe 职业经历” + “Jane Doe 出版物”

这比顺序搜索更快，覆盖范围也更广。提取前请按 URL 去重。

消除常见姓名的歧义

搜索常见姓名的人物时：

1. 在查询中加入有助于区分的信息：公司名称、职位、城市
2. 使用 --focus social——LinkedIn 结果会包含地点和当前公司信息，便于消除歧义
3. 交叉核对不同搜索的结果，确认目标人物无误

提取策略

1. 始终使用 --parse --format markdown — 返回整洁的 Markdown，而非原始 HTML，避免上下文窗口溢出
2. 先尝试不加 --render — 对静态页面来说速度更快
3. 对于 SPA，添加 --render — 在内容由 JavaScript 加载时使用
4. 设置地理位置 — 使用 --country 查看特定地区的内容

爬取策略

1. 供大模型使用时，优先选择 map + extract，而不是 crawl — crawl 结果会返回原始 HTML（每页 60-115KB），会占满大模型的上下文。要获得适合大模型使用的输出，请使用 map 发现 URL，然后对单个页面运行 extract --parse --format markdown
2. 仅在批量存档或数据管道中使用 crawl — 当你需要获取多个页面的原始内容，并会在大模型上下文之外进行后处理时使用
3. 始终设置 --limit — crawl 没有默认限制，因此始终指定限制，以避免爬取整个网站
4. 使用路径筛选器 — 使用 --include-path 和 --exclude-path 指定目标版块
5. 为爬取任务命名 — 使用 --name 便于跟踪
6. 使用单个任务 ID 获取结果 — crawl status 会返回每个页面对应的任务 ID；使用这些 ID（而不是爬取 ID）运行 nimble tasks results --task-id

常用方案

调查某个人

# Step 1: Run social + general in parallel for max coverage
nimble search --query "Jane Doe Head of Engineering" --focus social --deep-search=false --max-results 10 --include-answer
nimble search --query "Jane Doe Head of Engineering" --focus general --deep-search=false --max-results 10 --include-answer

# Step 2: Broaden with different query angles in parallel
nimble search --query "Jane Doe career history Acme Corp" --deep-search=false --include-answer
nimble search --query "Jane Doe publications blog articles" --deep-search=false --include-answer

# Step 3: Extract the most promising non-auth-walled URLs (skip LinkedIn — see Known Limitations)
nimble extract --url "https://www.companysite.com/team/jane-doe" --parse --format markdown

调查某家公司

# Step 1: Overview + recent news in parallel
nimble search --query "Acme Corp" --focus general --deep-search=false --include-answer
nimble search --query "Acme Corp" --focus news --time-range month --deep-search=false --include-answer

# Step 2: Extract company page
nimble extract --url "https://acme.com/about" --parse --format markdown

技术调研

# Step 1: Find docs and code examples
nimble search --query "React Server Components migration guide" --focus coding --deep-search=false --include-answer

# Step 2: Extract the most relevant doc
nimble extract --url "https://react.dev/reference/rsc/server-components" --parse --format markdown

错误处理

错误	解决方案
NIMBLE_API_KEY not set	设置环境变量：export NIMBLE_API_KEY="your-key"
401 Unauthorized	在 nimbleway.com 验证 API 密钥是否有效
402/403 with --include-answer	当前套餐不支持高级功能。移除 --include-answer，重试相同查询并继续
429 Too Many Requests	降低请求频率或升级 API 套餐
超时	确保已设置 --deep-search=false，减少 --max-results 的值，或增大 --request-timeout 的值
没有结果	尝试不同的 --focus，扩大查询范围，或移除域名筛选器

已知限制

网站	问题	解决方法
LinkedIn profiles	身份验证墙会阻止提取（返回重定向或 JS，状态码为 999）	改用 --focus social 搜索 — 它会通过子 Agent 直接返回 LinkedIn 数据。不要尝试 extract LinkedIn URL。
需要登录的网站	extract 返回登录页面而不是内容	无解决方法 — 请改用搜索摘要
复杂的 SPA	extract 返回空白或极少的 HTML	添加 --render 标志，在提取前执行 JavaScript
Crawl results	返回原始 HTML（每页 60-115KB），没有 Markdown 选项	对单个页面使用 map + extract --parse --format markdown，以获得适合大模型使用的输出
Crawl status	可能会将实际已成功的单个任务状态误报为“failed”	假定任务失败前，务必先尝试运行 nimble tasks results --task-id