research-assistant 0.1.1 → 0.2.0

package/README-ZH.md

@@ -66,6 +66,7 @@ research-assistant locate <md_path> "<q>"      # 锚点式相关性扫描
 
 # 管理
 research-assistant setup                       # 配置 + 安装 skill/agent
+research-assistant config fields               # 查看各 provider 需填的配置字段
 research-assistant doctor [--show-config]      # 连通性诊断
 research-assistant skills status               # 受管 skill/agent 新鲜度
 ```

package/README.md

@@ -73,6 +73,7 @@ research-assistant locate <md_path> "<q>"      # anchor-based relevance scan
 
 # Management
 research-assistant setup                       # configure + install skill/agent
+research-assistant config fields               # show each provider's required config fields
 research-assistant doctor [--show-config]      # connectivity diagnostics
 research-assistant skills status               # managed skill/agent freshness
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "research-assistant",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Search/research sub-agent + concurrent search/fetch/locate CLI atomic tools for AI agents (Exa, Tavily, Firecrawl, Context7, OpenAI-compatible).",
   "license": "MIT",
   "homepage": "https://github.com/arsonist-g/research-assistant-cli#readme",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "research-assistant"
-version = "0.1.1"
+version = "0.2.0"
 description = "Search/research sub-agent + a set of concurrent search/fetch/locate CLI atomic tools for AI agents."
 readme = "README.md"
 requires-python = ">=3.10"

package/src/research_assistant/assets/skills/research-assistant/SKILL.md

@@ -76,7 +76,7 @@ tier genuinely cannot return the content.
 | Tier | Tool | Strength | Use when |
 |------|------|----------|----------|
 | 1. API | `exa`, `tavily` | Structured search APIs; clean JSON, no rendering. `tavily extract` returns ready markdown, `tavily map`/`crawl` cover a whole site; `exa` adds `similar`, `contents`, `answer`, and async `research`. Fast and cheap. | Simple or public pages; search with snippets; fast fetch of a known URL; site map or crawl. |
-| 2. Firecrawl | `firecrawl` | Residential or home-bandwidth infrastructure; `scrape` and `search` are **keyless**, the other endpoints (`map`, `crawl`, `extract`, `interact`, `agent`, `monitor`, `parse`) need a key. More likely than Tier 1 to succeed on lightly protected pages, and the only tier with site-wide crawl and structured extraction. | A page refuses raw HTTP but shows no hard Cloudflare challenge. Batch scrape many URLs, crawl a whole site, or extract structured data with a schema. |
+| 2. Firecrawl | `firecrawl` | Residential or home-bandwidth infrastructure; `scrape`/`search`/`interact`/`parse` are **keyless**, the other endpoints (`map`, `crawl`, `extract`, `agent`, `monitor`) need a key. More likely than Tier 1 to succeed on lightly protected pages, and the only tier with site-wide crawl and structured extraction. | A page refuses raw HTTP but shows no hard Cloudflare challenge. Batch scrape many URLs, crawl a whole site, or extract structured data with a schema. |
 | 3. Browser | `fetch`, `browser` | Drives the user's real Edge/Chromium, same engine as the daily browser so login cookies stay valid. `fetch` auto-escalates: normal API, then a headed browser with Cloudflare auto-detect (no challenge means solve returns instantly). `browser` is the direct browser platform when you already know you want the browser: `browser fetch` (headed + CF auto-detect, skips the API) and `browser search` (headless search engine: Bing CN/intl, Google). | Everything above failed; or the page is behind Cloudflare, needs JS, or needs login cookies; or you want a browser search engine directly. |
 
 Notes:
@@ -157,29 +157,32 @@ and accept `--async-submit` to return the job id immediately instead of waiting.
 
 ```sh
 # Tier 1: structured search APIs. Clean JSON, fastest, cheapest. Start here for simple or public pages.
-research-assistant exa search "<query>" [--num-results N] [--type auto|keyword|neural|fast] [--text] [--highlights] [--category CAT] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--include-domains D ...] [--exclude-domains D ...]
-research-assistant exa similar <url> [--num-results N]              # pages semantically similar to a URL
+research-assistant exa search "<query>" [--num-results N (1-100)] [--type auto|keyword|neural|fast] [--text] [--highlights] [--category CAT] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--include-domains D ...] [--exclude-domains D ...]
+research-assistant exa similar <url> [--num-results N (1-100)]              # pages semantically similar to a URL ("more like this")
 research-assistant exa contents <id>... [--text] [--highlights]     # fetch body for Exa IDs or URLs
-research-assistant exa answer "<question>" [--text]                 # LLM answer grounded in Exa results
-research-assistant exa research "<instructions>" [--model exa-research|exa-research-pro] [--output-schema JSON | --infer-schema] [--poll-timeout N] [--async-submit]   # async in-depth research
-
-research-assistant tavily search "<query>" [--depth ultra-fast|fast|basic|advanced] [--max-results N] [--topic general|news|finance] [--time-range day|week|month|year] [--include-answer basic|true|advanced] [--country C] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--chunks-per-source N] [--include-raw-content markdown|text] [--include-images] [--include-domains D ...] [--exclude-domains D ...] [--auto-parameters]
-research-assistant tavily extract <url>... [--extract-depth basic|advanced] [--format markdown|text]   # ready markdown, no rendering
-research-assistant tavily map <url> [--max-depth N] [--max-breadth N] [--limit N] [--select-paths REGEX ...] [--instructions TEXT] [--timeout N]   # list a site's reachable URLs
-research-assistant tavily crawl <url> [--max-depth N] [--limit N] [--instructions TEXT] [--extract-depth basic|advanced] [--no-external] [--timeout N]   # recursive crawl, markdown per page
-
-# Tier 2: Firecrawl. Residential bandwidth. scrape and search are keyless; the rest need a key.
+research-assistant exa answer "<question>" [--text]                 # LLM answer grounded in Exa results (treat as a lead; verify with fetch)
+research-assistant exa research "<instructions>" [--model exa-research|exa-research-pro] [--output-schema JSON | --infer-schema] [--poll-timeout N] [--async-submit]   # async in-depth research; --infer-schema lets the model pick fields, --output-schema pins a rigid shape
+
+research-assistant tavily search "<query>" [--depth ultra-fast|fast|basic|advanced] [--max-results N] [--topic general|news|finance] [--time-range day|week|month|year] [--include-answer basic|true|advanced] [--country C] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--chunks-per-source N (1-3, advanced)] [--include-raw-content markdown|text] [--include-images] [--include-domains D ...] [--exclude-domains D ...] [--auto-parameters]
+research-assistant tavily extract <url>... [--extract-depth basic|advanced] [--format markdown|text]   # ready markdown, no rendering (fastest fetch of known URLs)
+research-assistant tavily map <url> [--max-depth N (1-5)] [--max-breadth N (1-500)] [--limit N] [--select-paths REGEX ...] [--instructions TEXT] [--timeout N (10-150)]   # list a site's reachable URLs (sitemap-aware, returns URLs only)
+research-assistant tavily crawl <url> [--max-depth N (1-5)] [--limit N] [--instructions TEXT] [--extract-depth basic|advanced] [--no-external] [--timeout N (10-150)]   # recursive crawl, markdown per page (depth-bounded)
+
+# Tier 2: Firecrawl. Residential bandwidth. scrape/search/interact/parse are keyless; map/crawl/extract/agent/monitor need a key.
+# Keyless commands default to auto: try keyless first, fall back to your key on rate-limit/IP failure
+# (a keyed call bills credits, so keyless-first saves them). --use-key skips keyless (needs api_key);
+# --keyless forces keyless (no fallback).
 # Keyless endpoints are sensitive to IP quality: residential/home IPs work; datacenter IPs may
 # hit 403 ("IP looks suspicious") and need a home-bandwidth proxy.
-research-assistant firecrawl scrape <url>... [--format markdown|html] [--only-main-content] [--wait-for MS]   # batch markdown, keyless
-research-assistant firecrawl search "<query>" [--limit N] [--sources web|news] [--scrape]                      # keyless; --scrape returns full markdown per result
-research-assistant firecrawl map <url> [--limit N] [--include-subdomains]                                      # needs key
-research-assistant firecrawl crawl <url> [--limit N] [--max-depth N] [--include-paths REGEX ...] [--allow-subdomains] [--prompt TEXT] [--poll-timeout N] [--async-submit]   # async recursive crawl
-research-assistant firecrawl extract <url>... [--prompt TEXT | --schema JSON] [--enable-web-search] [--agent] [--poll-timeout N] [--async-submit]   # LLM structured extraction, async
-research-assistant firecrawl interact "<prompt>" [--scrape-id ID | --url URL] [--code TEXT --language node|python|bash] [--timeout S] [--stop]   # live browser session bound to a scrape
-research-assistant firecrawl agent "<prompt>" [--model spark-1-mini|spark-1-pro] [--urls U ...] [--schema JSON] [--max-credits N] [--strict] [--poll-timeout N] [--async-submit]   # autonomous extraction
-research-assistant firecrawl monitor                                                                       # list active crawl jobs
-research-assistant firecrawl parse <file> [--format markdown|html|json ...] [--pdf-mode fast|auto|ocr] [--max-pages N]   # parse a local document
+research-assistant firecrawl scrape <url>... [--format markdown|html] [--only-main-content] [--wait-for MS]   # keyless; single or batch URL → markdown/html (auto: keyless first, falls back to key)
+research-assistant firecrawl search "<query>" [--limit N (1-100)] [--sources web|news] [--scrape]   # keyless; web search; --scrape returns full markdown per result (bills more credits)
+research-assistant firecrawl map <url> [--limit N] [--include-subdomains]   # needs key; discover all reachable URLs of a site (sitemap + link crawl), URLs only; no page content
+research-assistant firecrawl crawl <url> [--limit N] [--max-depth N] [--include-paths REGEX ...] [--allow-subdomains] [--prompt TEXT] [--poll-timeout N] [--async-submit]   # needs key; async recursive crawl following links, markdown per page; --prompt lets an LLM generate crawl options
+research-assistant firecrawl extract <url>... [--prompt TEXT | --schema JSON] [--enable-web-search] [--agent] [--poll-timeout N] [--async-submit]   # needs key; LLM pulls structured data from URLs by --prompt (free-form) or --schema (rigid shape); --agent navigates pages first; async
+research-assistant firecrawl interact "<prompt>" [--scrape-id ID | --url URL] [--code TEXT --language node|python|bash] [--timeout S (1-300)] [--stop]   # keyless; live browser session bound to a scrape: run a prompt or code in the already-loaded page
+research-assistant firecrawl agent "<prompt>" [--model spark-1-mini|spark-1-pro] [--urls U ...] [--schema JSON] [--max-credits N] [--strict] [--poll-timeout N] [--async-submit]   # needs key; autonomous agent: give a goal, it browses sites and extracts the data (spark model); async, bills credits
+research-assistant firecrawl monitor   # needs key; list your team's currently active crawl jobs
+research-assistant firecrawl parse <file> [--format markdown|html|json ...] [--pdf-mode fast|auto|ocr] [--max-pages N (1-10000)]   # keyless; upload a local PDF/DOCX/HTML → markdown/json (no URL needed)
 
 # Tier 3: real browser. fetch auto-escalates (normal API, then headed browser with CF auto-detect).
 research-assistant fetch <url> [<url>...] [--concurrency N] [--login|--no-login] [--no-browser] [--output PATH]
@@ -218,6 +221,7 @@ research-assistant locate <md_path> "<query>" [--top N] [--scope lines|paragraph
 
 ```sh
 research-assistant setup [--non-interactive | --config-inline TOML] [--provider TYPE[,k=v,...]] ... [--proxy URL] [--browser-channel msedge|chrome] [--daemon-port N] [--install-skills claude,codex,...]   # configure providers/proxy/browser; --install-skills writes the skill+agent files
+research-assistant config fields                                         # each provider's config fields (api_key/model required, default base_url, keyless tier, notes); read-only
 research-assistant doctor [--show-config] [--target <name>]              # connectivity diagnostics; --show-config prints config (masked), --target checks one provider or builtin
 research-assistant skills status [--targets claude,codex,...] [--skills-root PATH]   # managed skill/agent freshness
 research-assistant skills update [--targets claude,codex,...] [--skills-root PATH]   # refresh managed files

package/src/research_assistant/cli.py

@@ -80,8 +80,9 @@ def _build_parser(config: Any) -> argparse.ArgumentParser:
     from .commands import setup as setup_cmd
     from .commands import skills as skills_cmd
     from .commands import doctor as doctor_cmd
+    from .commands import config as config_cmd
 
-    for cmd in (fetch_cmd, locate_cmd, search_cmd, ask_cmd, setup_cmd, skills_cmd, doctor_cmd):
+    for cmd in (fetch_cmd, locate_cmd, search_cmd, ask_cmd, config_cmd, setup_cmd, skills_cmd, doctor_cmd):
         cmd.register(subs)
 
     return parser

package/src/research_assistant/commands/_provider_meta.py

@@ -0,0 +1,80 @@
+"""provider 配置元数据（setup 交互式 + config fields 共享，单源）。
+
+集中描述每个 provider type 在 config.toml 里该填什么：是否必填 api_key / model、
+base_url 默认值、免 key 层说明、配置提示。setup 的 _PROVIDER_TYPES 从此派生，避免两处漂移。
+
+字段：
+    type         config.toml 的 type 键
+    label        人类可读名
+    needs_model  是否必填 model
+    default_base base_url 默认值（空=用户必填）
+    api_key      "required" | "optional"
+    keyless      免 key 层说明（空=无免 key 层）
+    notes        配置提示
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ProviderMeta:
+    type: str
+    label: str
+    needs_model: bool
+    default_base: str
+    api_key: str  # "required" | "optional"
+    keyless: str = ""
+    notes: str = ""
+
+
+# 顺序即展示顺序（LLM 主干 → 搜索 API → 文档 → firecrawl）。
+PROVIDER_META: dict[str, ProviderMeta] = {
+    "openai_compat": ProviderMeta(
+        type="openai_compat",
+        label="OpenAI-compatible (drives ask)",
+        needs_model=True,
+        default_base="https://api.openai.com/v1",
+        api_key="required",
+        notes="base_url defaults to OpenAI (with /v1/). For a compatible gateway, set its URL including /v1/. Pick a model with built-in web search.",
+    ),
+    "locate": ProviderMeta(
+        type="locate",
+        label="locate model (small OpenAI-compatible model for long-doc locate)",
+        needs_model=True,
+        default_base="https://api.openai.com/v1",
+        api_key="required",
+        notes="Reuses the OpenAI-compatible protocol; a cheap small model is enough. base_url defaults to OpenAI; a gateway URL must include /v1/.",
+    ),
+    "exa": ProviderMeta(
+        type="exa",
+        label="Exa (structured search API)",
+        needs_model=False,
+        default_base="https://api.exa.ai",
+        api_key="required",
+    ),
+    "tavily": ProviderMeta(
+        type="tavily",
+        label="Tavily (search + extract + map + crawl)",
+        needs_model=False,
+        default_base="https://api.tavily.com",
+        api_key="required",
+    ),
+    "firecrawl": ProviderMeta(
+        type="firecrawl",
+        label="Firecrawl (keyless scrape/search/interact/parse; map/crawl/extract/agent/monitor need key)",
+        needs_model=False,
+        default_base="https://api.firecrawl.dev/v2",
+        api_key="optional",
+        keyless="scrape/search/interact/parse are keyless (IP-rate-limited); map/crawl/extract/agent/monitor need a key.",
+        notes="Keyless commands default to auto (keyless first, fall back to key on rate-limit/IP failure). Configure a key to unlock map/crawl/extract/agent/monitor.",
+    ),
+    "context7": ProviderMeta(
+        type="context7",
+        label="Context7 (library/framework/SDK/CLI/cloud docs)",
+        needs_model=False,
+        default_base="https://context7.com",
+        api_key="required",
+    ),
+}

package/src/research_assistant/commands/config.py

@@ -0,0 +1,47 @@
+"""config 命令：配置相关的只读查询。
+
+    research-assistant config fields   # 打印各 provider 配置字段表（只读，不连网，不动配置）
+
+未来可扩展更多子命令（如 config show 打印当前值，与 doctor --show-config 区分）。
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from ..config import Config
+from ._provider_meta import PROVIDER_META
+
+NAME = "config"
+ALIASES: list[str] = []
+HELP = "Read-only configuration queries (provider field reference)."
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(NAME, help=HELP, description=HELP)
+    sub = p.add_subparsers(dest="subcommand", required=True, metavar="<fields>")
+    f = sub.add_parser(
+        "fields",
+        help="Print each provider type's config fields (api_key/model required, default base_url, keyless tier, notes).",
+    )
+    f.set_defaults(_handler=run_fields)
+
+
+async def run_fields(args: argparse.Namespace, config: Config) -> dict[str, Any]:
+    """各 provider 配置字段表（{provider_type: fields}）。只读：不读 config.toml，不连网。
+
+    返回 dict-of-dict 而非 list，使 markdown 渲染走普通 dict 路径（每字段 200 字符宽），
+    notes 不被 list 的 80 字符截断。
+    """
+    out: dict[str, Any] = {}
+    for ptype, m in PROVIDER_META.items():
+        out[m.type] = {
+            "label": m.label,
+            "api_key": m.api_key,
+            "model": "required" if m.needs_model else "n/a",
+            "default_base_url": m.default_base or "(set by user)",
+            "keyless": m.keyless or "-",
+            "notes": m.notes or "-",
+        }
+    return out

package/src/research_assistant/commands/setup.py

@@ -18,19 +18,16 @@ from ..config import Config, ProviderConfig, load, save
 from ..errors import ArgsError, ResearchAssistantError
 from .. import targets as targets_mod
 from .. import installer
+from ._provider_meta import PROVIDER_META
 
 NAME = "setup"
 ALIASES: list[str] = ["init"]
 HELP = "Configure providers/proxy/browser and optionally install managed skill/agent."
 
-# 已知 provider 类型 + 是否需要 model
+# 已知 provider 类型 + 是否需要 model（从共享元数据派生，单源；setup 只用 needs_model/label/default_base）
 _PROVIDER_TYPES: dict[str, dict[str, Any]] = {
-    "openai_compat": {"needs_model": True, "label": "OpenAI-compatible (search/LLM)", "default_base": ""},
-    "locate": {"needs_model": True, "label": "locate 模型 (openai 兼容小模型)", "default_base": ""},
-    "exa": {"needs_model": False, "label": "Exa", "default_base": "https://api.exa.ai"},
-    "tavily": {"needs_model": False, "label": "Tavily", "default_base": "https://api.tavily.com"},
-    "firecrawl": {"needs_model": False, "label": "Firecrawl", "default_base": "https://api.firecrawl.dev/v2"},
-    "context7": {"needs_model": False, "label": "Context7", "default_base": "https://context7.com"},
+    t: {"needs_model": m.needs_model, "label": m.label, "default_base": m.default_base}
+    for t, m in PROVIDER_META.items()
 }
 
 

package/src/research_assistant/providers/browser.py

@@ -51,7 +51,7 @@ class BrowserProvider(Provider):
                         help="Search engine (default bing-intl; intl avoids CN-sensitive-word filtering).",
                     ),
                     ArgSpec(["--limit"], type=int, default=10, help="Min results to collect (default 10)."),
-                    ArgSpec(["--max-pages"], type=int, default=10, help="Max pages to paginate (default 10)."),
+                    ArgSpec(["--max-pages"], type=int, default=10, help="Max pages to paginate (default 10; engine may offer fewer)."),
                 ],
                 handler=self.search,
             ),

package/src/research_assistant/providers/exa.py

@@ -87,7 +87,7 @@ class ExaProvider(Provider):
                 help="Search the web with Exa (auto/keyword/neural/fast).",
                 args=[
                     ArgSpec(["query"], kind="positional", help="Search query."),
-                    ArgSpec(["--num-results"], type=int, default=10, help="Number of results (default 10)."),
+                    ArgSpec(["--num-results"], type=int, default=10, help="Number of results (1-100, default 10)."),
                     ArgSpec(
                         ["--type"],
                         choices=["auto", "keyword", "neural", "fast"],
@@ -124,7 +124,7 @@ class ExaProvider(Provider):
                 help="Find pages similar to a URL.",
                 args=[
                     ArgSpec(["url"], kind="positional", help="Source URL."),
-                    ArgSpec(["--num-results"], type=int, default=10, help="Number of results."),
+                    ArgSpec(["--num-results"], type=int, default=10, help="Number of results (1-100)."),
                 ],
                 handler=self.similar,
             ),

package/src/research_assistant/providers/firecrawl.py

@@ -49,12 +49,26 @@ from .registry import register
 DEFAULT_BASE_URL = "https://api.firecrawl.dev/v2"
 
 
+def _keyless_flags() -> list[ArgSpec]:
+    """keyless 命令（scrape/search/interact/parse）共享的 key 策略 flags。
+
+    默认 auto：配了 key 先走免 key，失败（限流/IP/suspicious）再带 key 重试一次。
+    --use-key 强制带 key（跳过免 key）；--keyless 强制免 key（失败不 fallback）。二者互斥。
+    """
+    return [
+        ArgSpec(["--use-key"], action="store_true",
+                help="Force the keyed tier; skip the keyless attempt (needs api_key)."),
+        ArgSpec(["--keyless"], action="store_true",
+                help="Force the keyless tier; do not fall back to key on failure."),
+    ]
+
+
 @register
 class FirecrawlProvider(Provider):
     type = "firecrawl"
     command = "firecrawl"
     aliases = ["fc"]
-    help = "Firecrawl scrape / search / map (scrape+search work keyless; map needs a key)."
+    help = "Firecrawl scrape/search/interact/parse (keyless) + map/crawl/extract/agent/monitor (need key)."
 
     def capabilities(self) -> list[Capability]:
         return [
@@ -66,7 +80,7 @@ class FirecrawlProvider(Provider):
                     ArgSpec(["--format"], choices=["markdown", "html"], default="markdown", help="Output format."),
                     ArgSpec(["--only-main-content"], action="store_true", help="Drop nav/footer boilerplate."),
                     ArgSpec(["--wait-for"], type=int, metavar="MS", help="Wait N ms before scraping."),
-                ],
+                ] + _keyless_flags(),
                 handler=self.scrape,
             ),
             Capability(
@@ -74,10 +88,10 @@ class FirecrawlProvider(Provider):
                 help="Web search (keyless); with --scrape returns full markdown per result.",
                 args=[
                     ArgSpec(["query"], kind="positional", help="Search query."),
-                    ArgSpec(["--limit"], type=int, default=10, help="Max results."),
+                    ArgSpec(["--limit"], type=int, default=10, help="Max results (1-100)."),
                     ArgSpec(["--sources"], nargs="+", choices=["web", "news"], help="Result sources."),
-                    ArgSpec(["--scrape"], action="store_true", help="Scrape full content for each result (needs key on keyless tier)."),
-                ],
+                    ArgSpec(["--scrape"], action="store_true", help="Scrape full content for each result."),
+                ] + _keyless_flags(),
                 handler=self.search,
             ),
             Capability(
@@ -124,7 +138,7 @@ class FirecrawlProvider(Provider):
             ),
             Capability(
                 name="interact",
-                help="Run a prompt or code in a live browser session bound to a scrape (needs a key).",
+                help="Run a prompt or code in a live browser session bound to a scrape (keyless).",
                 args=[
                     ArgSpec(["prompt"], kind="positional", nargs="?", metavar="TEXT",
                             help="AI prompt to run in the browser session (mode 1; exclusive with --code)."),
@@ -140,7 +154,7 @@ class FirecrawlProvider(Provider):
                             help="Execution timeout seconds (1-300, default 30)."),
                     ArgSpec(["--stop"], action="store_true",
                             help="Stop and tear down the session (requires --scrape-id)."),
-                ],
+                ] + _keyless_flags(),
                 handler=self.interact,
             ),
             Capability(
@@ -174,7 +188,7 @@ class FirecrawlProvider(Provider):
             ),
             Capability(
                 name="parse",
-                help="Upload a local document (.pdf/.docx/.html/...) and parse to markdown/json (needs a key).",
+                help="Upload a local document (.pdf/.docx/.html/...) and parse to markdown/json (keyless).",
                 args=[
                     ArgSpec(["file"], kind="positional", metavar="PATH",
                             help="Local file path (.html/.htm/.pdf/.docx/.doc/.odt/.rtf/.xlsx/.xls)."),
@@ -194,7 +208,7 @@ class FirecrawlProvider(Provider):
                             help="PDF parser mode (sets options.parsers[0].mode)."),
                     ArgSpec(["--max-pages"], type=int, metavar="N",
                             help="Max PDF pages to parse (1-10000, needs --pdf-mode)."),
-                ],
+                ] + _keyless_flags(),
                 handler=self.parse,
             ),
         ]
@@ -224,14 +238,106 @@ class FirecrawlProvider(Provider):
             msg = data.get("error") or "firecrawl 返回 success:false"
             raise ProviderError(f"firecrawl {endpoint}: {msg}", provider="firecrawl", details=data)
 
-    async def _scrape_one(self, client: Any, url: str, fmt: str, args: Any) -> dict[str, Any]:
+    def _require_keyed(self, cfg: ProviderConfig, endpoint: str) -> None:
+        """keyed 命令（map/crawl/extract/agent/monitor）必须配 key，否则前置失败，不发请求。"""
+        if not cfg.api_key:
+            from ..errors import ArgsError
+            raise ArgsError(
+                f"firecrawl {endpoint}: 此命令需要 api_key（免 key 层仅支持 scrape/search/interact/parse）",
+                provider="firecrawl",
+            )
+
+    def _resolve_mode(self, args: Any, cfg: ProviderConfig) -> str:
+        """解析 keyless 命令的 key 模式：keyless | use_key | auto。"""
+        from ..errors import ArgsError
+        if getattr(args, "keyless", False) and getattr(args, "use_key", False):
+            raise ArgsError("firecrawl: --keyless 与 --use-key 互斥", provider="firecrawl")
+        if getattr(args, "keyless", False):
+            return "keyless"
+        if getattr(args, "use_key", False):
+            if not cfg.api_key:
+                raise ArgsError("firecrawl: --use-key 需要 api_key，但未配置", provider="firecrawl")
+            return "use_key"
+        return "auto"  # 默认：有 key 先免 key 失败再带 key，无 key 只免 key
+
+    @staticmethod
+    def _is_keyless_retryable(err: Exception) -> bool:
+        """免 key 失败是否值得带 key 重试（限流/IP/suspicious/quota 类；网络错误不算）。"""
+        from ..errors import ProviderError
+        if not isinstance(err, ProviderError):
+            return False
+        details = getattr(err, "details", None) or {}
+        status = details.get("status_code")
+        if status in (403, 429):
+            return True
+        msg = (getattr(err, "message", "") or "").lower()
+        keywords = ("rate limit", "ratelimit", "too many", "suspicious", "quota", "limit reached", "ip ")
+        return any(k in msg for k in keywords)
+
+    async def _do_request(
+        self, client: Any, method: str, path: str, *,
+        json_body: Any = None, files: Any = None,
+        headers: dict[str, str] | None, endpoint: str,
+    ) -> dict[str, Any]:
+        """单次 firecrawl 请求（JSON 或 multipart），按 headers 决定是否带 key；统一 _check。"""
+        if files is not None:
+            import httpx
+            from ..errors import NetworkError, wrap_provider_http_error
+            try:
+                resp = await client.request(method, path, files=files, headers=headers)
+            except httpx.HTTPError as e:
+                raise wrap_provider_http_error("firecrawl", e) from e
+            if resp.status_code >= 400:
+                raise http_mod.handle_http_error("firecrawl", httpx.HTTPStatusError(
+                    f"firecrawl HTTP {resp.status_code}", request=resp.request, response=resp
+                ))
+            try:
+                data = resp.json()
+            except ValueError as e:
+                raise NetworkError(f"firecrawl: 响应非 JSON ({e})", provider="firecrawl") from e
+        else:
+            data = await http_mod.request_json(
+                client, method, path, provider="firecrawl", json_body=json_body, headers=headers
+            )
+        self._check(data, endpoint=endpoint)
+        return data
+
+    async def _request_keyless(
+        self, client: Any, method: str, path: str, *,
+        cfg: ProviderConfig, mode: str,
+        json_body: Any = None, files: Any = None, endpoint: str,
+    ) -> dict[str, Any]:
+        """keyless 命令请求调度：按 mode 决定是否带 key；auto 下免 key 失败（可重试）带 key 重试一次。
+
+        - keyless：永不带 key，失败即抛。
+        - use_key：必带 key（无 key 在 _resolve_mode 已挡）。
+        - auto：先免 key；失败且可重试（限流/IP/suspicious）且有 key → 带 key 重试一次。
+        """
+        from ..errors import ProviderError
+        key_headers = {"Authorization": f"Bearer {cfg.api_key}"} if cfg.api_key else None
+
+        if mode == "use_key":
+            return await self._do_request(client, method, path, json_body=json_body, files=files,
+                                          headers=key_headers, endpoint=endpoint)
+
+        # keyless 或 auto：先免 key
+        try:
+            return await self._do_request(client, method, path, json_body=json_body, files=files,
+                                          headers=None, endpoint=endpoint)
+        except ProviderError as e:
+            if mode == "keyless" or not cfg.api_key or not self._is_keyless_retryable(e):
+                raise
+            # auto + 有 key + 可重试：带 key 再来一次
+            return await self._do_request(client, method, path, json_body=json_body, files=files,
+                                          headers=key_headers, endpoint=endpoint)
+
+    async def _scrape_one(self, client: Any, url: str, fmt: str, args: Any, cfg: ProviderConfig, mode: str) -> dict[str, Any]:
         body: dict[str, Any] = {"url": url, "formats": [fmt]}
         if getattr(args, "only_main_content", False):
             body["onlyMainContent"] = True
         if getattr(args, "wait_for", None):
             body["waitFor"] = args.wait_for
-        data = await http_mod.request_json(client, "POST", "scrape", provider="firecrawl", json_body=body)
-        self._check(data, endpoint="scrape")
+        data = await self._request_keyless(client, "POST", "scrape", cfg=cfg, mode=mode, json_body=body, endpoint="scrape")
         inner = data.get("data") or {}
         out: dict[str, Any] = {}
         if fmt == "markdown":
@@ -246,21 +352,22 @@ class FirecrawlProvider(Provider):
 
     async def scrape(self, args: Any) -> dict[str, Any]:
         cfg = self._cfg()
+        mode = self._resolve_mode(args, cfg)
         urls = args.urls
         async with http_mod.make_client(
             proxy_url=resolve_proxy(self.config.proxy.url),
             timeout=cfg.timeout,
             base_url=cfg.base_url,
-            headers=self._headers(cfg),
         ) as client:
             if len(urls) == 1:
-                return {"data": await self._scrape_one(client, urls[0], args.format, args)}
+                return {"data": await self._scrape_one(client, urls[0], args.format, args, cfg, mode)}
             # 批量并发
-            items = await asyncio.gather(*[self._scrape_one(client, u, args.format, args) for u in urls])
+            items = await asyncio.gather(*[self._scrape_one(client, u, args.format, args, cfg, mode) for u in urls])
             return {"results": [{"url": u, "data": d} for u, d in zip(urls, items)]}
 
     async def search(self, args: Any) -> dict[str, Any]:
         cfg = self._cfg()
+        mode = self._resolve_mode(args, cfg)
         body: dict[str, Any] = {"query": args.query, "limit": args.limit}
         if args.scrape:
             body["scrapeOptions"] = {"formats": [{"type": "markdown"}]}
@@ -270,10 +377,8 @@ class FirecrawlProvider(Provider):
             proxy_url=resolve_proxy(self.config.proxy.url),
             timeout=cfg.timeout,
             base_url=cfg.base_url,
-            headers=self._headers(cfg),
         ) as client:
-            data = await http_mod.request_json(client, "POST", "search", provider="firecrawl", json_body=body)
-        self._check(data, endpoint="search")
+            data = await self._request_keyless(client, "POST", "search", cfg=cfg, mode=mode, json_body=body, endpoint="search")
         out: dict[str, Any] = {}
         if args.scrape:
             arr = data.get("data") or []
@@ -293,6 +398,7 @@ class FirecrawlProvider(Provider):
 
     async def map(self, args: Any) -> dict[str, Any]:
         cfg = self._cfg()
+        self._require_keyed(cfg, "map")
         body: dict[str, Any] = {"url": args.url, "limit": args.limit}
         if args.include_subdomains:
             body["includeSubdomains"] = True
@@ -323,6 +429,7 @@ class FirecrawlProvider(Provider):
 
     async def crawl(self, args: Any) -> dict[str, Any]:
         cfg = self._cfg()
+        self._require_keyed(cfg, "crawl")
         body: dict[str, Any] = {
             "url": args.url,
             "limit": args.limit,
@@ -376,6 +483,7 @@ class FirecrawlProvider(Provider):
         from ..errors import ArgsError
 
         cfg = self._cfg()
+        self._require_keyed(cfg, "extract")
         body: dict[str, Any] = {"urls": args.urls}
         if args.prompt:
             body["prompt"] = args.prompt
@@ -418,6 +526,7 @@ class FirecrawlProvider(Provider):
         from ..errors import ArgsError, ProviderError
 
         cfg = self._cfg()
+        mode = self._resolve_mode(args, cfg)
         # --stop：配合 --scrape-id，DELETE 会话
         if args.stop:
             if not args.scrape_id:
@@ -426,12 +535,11 @@ class FirecrawlProvider(Provider):
                 proxy_url=resolve_proxy(self.config.proxy.url),
                 timeout=cfg.timeout,
                 base_url=cfg.base_url,
-                headers=self._headers(cfg),
             ) as client:
-                data = await http_mod.request_json(
-                    client, "DELETE", f"scrape/{args.scrape_id}/interact", provider="firecrawl"
+                await self._request_keyless(
+                    client, "DELETE", f"scrape/{args.scrape_id}/interact",
+                    cfg=cfg, mode=mode, endpoint="interact",
                 )
-            self._check(data, endpoint="interact")
             return {"stopped": True, "scrapeId": args.scrape_id}
 
         # 模式校验：prompt 与 --code 二选一
@@ -444,7 +552,6 @@ class FirecrawlProvider(Provider):
             proxy_url=resolve_proxy(self.config.proxy.url),
             timeout=cfg.timeout,
             base_url=cfg.base_url,
-            headers=self._headers(cfg),
         ) as client:
             # 解析会话句柄：--scrape-id 优先；否则用 --url 发起 scrape 拿 metadata.scrapeId
             scrape_id = args.scrape_id
@@ -453,11 +560,10 @@ class FirecrawlProvider(Provider):
                     raise ArgsError(
                         "firecrawl interact: 需要 --scrape-id 或 --url（用于新建会话）", provider="firecrawl"
                     )
-                seed = await http_mod.request_json(
-                    client, "POST", "scrape", provider="firecrawl",
-                    json_body={"url": args.url, "formats": ["markdown"]},
+                seed = await self._request_keyless(
+                    client, "POST", "scrape", cfg=cfg, mode=mode,
+                    json_body={"url": args.url, "formats": ["markdown"]}, endpoint="scrape",
                 )
-                self._check(seed, endpoint="scrape")
                 seed_inner = seed.get("data") or {}
                 meta = seed_inner.get("metadata") or {}
                 scrape_id = meta.get("scrapeId")
@@ -474,10 +580,10 @@ class FirecrawlProvider(Provider):
             else:
                 body = {"prompt": args.prompt}
 
-            data = await http_mod.request_json(
-                client, "POST", f"scrape/{scrape_id}/interact", provider="firecrawl", json_body=body
+            data = await self._request_keyless(
+                client, "POST", f"scrape/{scrape_id}/interact",
+                cfg=cfg, mode=mode, json_body=body, endpoint="interact",
             )
-        self._check(data, endpoint="interact")
 
         # 透传会话句柄 + 执行结果（prompt→output，code→stdout/result/stderr/exitCode/killed）
         out: dict[str, Any] = {"scrapeId": scrape_id}
@@ -492,6 +598,7 @@ class FirecrawlProvider(Provider):
         from ..errors import ArgsError
 
         cfg = self._cfg()
+        self._require_keyed(cfg, "agent")
         body: dict[str, Any] = {"prompt": args.prompt, "model": args.model}
         if args.urls:
             body["urls"] = args.urls
@@ -538,6 +645,7 @@ class FirecrawlProvider(Provider):
         OpenAPI 的 required 误写为 data，实际响应字段是 crawls，两个字段都兼容。
         """
         cfg = self._cfg()
+        self._require_keyed(cfg, "monitor")
         async with http_mod.make_client(
             proxy_url=resolve_proxy(self.config.proxy.url),
             timeout=cfg.timeout,
@@ -558,18 +666,17 @@ class FirecrawlProvider(Provider):
         }
 
     async def parse(self, args: Any) -> dict[str, Any]:
-        """上传本地文件解析（POST /v2/parse，multipart/form-data）。
+        """上传本地文件解析（POST /v2/parse，multipart/form-data，keyless）。
 
-        request_json 只支持 JSON body；parse 需要 multipart 文件上传，这里直接用 client.request，
-        复用 handle_http_error / wrap_provider_http_error 保持与其他 handler 一致的错误映射。
+        走 _request_keyless 的 multipart 分支（_do_request files=...），享受与 scrape 等一致的
+        key 策略（auto/keyless/use_key）与错误映射。
         """
         from pathlib import Path
 
-        import httpx
-
-        from ..errors import ArgsError, NetworkError, wrap_provider_http_error
+        from ..errors import ArgsError
 
         cfg = self._cfg()
+        mode = self._resolve_mode(args, cfg)
         path = Path(args.file)
         if not path.is_file():
             raise ArgsError(f"firecrawl parse: 文件不存在: {args.file}", provider="firecrawl")
@@ -610,24 +717,10 @@ class FirecrawlProvider(Provider):
             proxy_url=resolve_proxy(self.config.proxy.url),
             timeout=cfg.timeout,
             base_url=cfg.base_url,
-            headers=self._headers(cfg),
         ) as client:
-            try:
-                resp = await client.request("POST", "parse", files=files)
-            except httpx.HTTPError as e:
-                raise wrap_provider_http_error("firecrawl", e) from e
-            if resp.status_code >= 400:
-                raise http_mod.handle_http_error(
-                    "firecrawl",
-                    httpx.HTTPStatusError(
-                        f"firecrawl HTTP {resp.status_code}", request=resp.request, response=resp
-                    ),
-                )
-            try:
-                data = resp.json()
-            except ValueError as e:
-                raise NetworkError(f"firecrawl: 响应非 JSON ({e})", provider="firecrawl") from e
-        self._check(data, endpoint="parse")
+            data = await self._request_keyless(
+                client, "POST", "parse", cfg=cfg, mode=mode, files=files, endpoint="parse",
+            )
 
         # ScrapeResponse 结构：markdown 映射到 content（对齐 api-contract §2.1）
         inner = data.get("data") or {}