将 Exa/Tavily/Perplexity/Firecr…

当你需要把 Exa、Tavily、Perplexity 或 Firecrawl 的 SDK/REST 调用、依赖、配置、测试与文档整体替换为 Parallel 产品，同时保留调用方可见行为时使用。

适用场景

解决思路

1. 把 `<skill-root>` 解析为包含该 `SKILL.md` 的目录，并始终从该目录解析所有随附参考与脚本，无论当前工作目录是什么；扫描器只用 Python 标准库，若没有 Python 3.9+，改用宿主文件搜索工具做等价仓库搜索并声明未运行随附扫描。
2. 按仓库内容加载对应参考：含 Exa 读 references/exa.md；含 Tavily 读 references/tavily.md；含 Perplexity Search、Sonar、Agent API web tools 或 Perplexity 搜索封装读 references/perplexity.md；含 Firecrawl Search、Scrape、Batch Scrape、Extract、Agent、Research Index、Crawl、Map、Parse、Browser、Interact、Monitor 或 MCP 读 references/firecrawl.md；任何可能路由到 Search 或需要迁移 query、filter、freshness、mode、结果列表时读 references/parallel-search.md；任何可能路由到 Extract、Chat、Task 或实体发现，或需要 streaming、结构化输出、引用时读 references/parallel-products.md；查询动态生成、provider 作为模型工具暴露、provider 响应类型泄漏到多个模块，或应用需要全文/合成答案时读 references/integration-patterns.md；对参考未覆盖的 SDK、封装、参数或响应字段，打开当前官方文档，不要猜测 provider 行为。
3. 保持这些不变量：除非用户明确授权，保留调用方可见行为；绝不静默丢弃 filter、内容字段、合成答案、图片、安全控制或基于分数的决策；绝不打印 API key 或密钥值，只检查 key 是否存在；不要仅为制造 `search_queries` 而添加隐藏 LLM 调用；不要仅因用户 prompt 符合 API 长度限制就把它当作关键词查询；把网页研究意图、硬过滤、handler 策略和答案合成指令保留在各自独立契约中；把省略的 provider 参数也视为行为，省略 Parallel 设置前先检查其默认值；不要在兼容 shim 后重建整个旧 provider SDK，只规范化应用实际使用的契约；除非用户明确要求，不要从外部密钥管理器或 provider 控制台移除凭据，但要移除过时代码引用并更新已检入模板；把 mode 映射当作起点，用应用真实查询验证延迟、质量和输出行为；当必需行为没有受支持的 Parallel 等价物且没有范围内替代时，在破坏性编辑前停止，报告确切缺口和所需的最小决策；当 Perplexity 边界需要 embeddings 时停止，它们不是 Parallel Search 替代；按消费契约通过 Search、Chat 或 Task 将 `finance_search` 路由到 Parallel 通用索引，仅当硬性市场数据覆盖、时效或原始结果要求仍未保留时停止；除非用户明确扩大迁移范围，保持 Agent API 模型路由、sandbox、MCP 和现有自定义函数能力分离；当 Firecrawl 边界需要完整爬取或 URL 映射、本地/私有文件解析、浏览器动作或会话、截图或其他丰富抓取格式、变更跟踪，或 Firecrawl 专有隐私/安全控制且无批准替代时停止，Search 和 Extract 不能复现这些契约；遵循仓库本地指令如 `AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING.md`，保留无关工作，绝不重置或丢弃用户更改；完成安全的仓库本地迁移工作，不要在盘点或计划后停止；除非用户要求，不要 commit、push、更改托管密钥或改动 provider 账号。
4. 盘点真实迁移面：编辑前记录当前分支和工作树状态；从目标仓库运行随附扫描器 `python3 <skill-root>/scripts/scan_provider_usage.py .`，需要机器可读输出时加 `--format json`；注意扫描器会跳过依赖/生成目录、二进制、不可读和超大文件，且无法仅凭字段名识别 provider 中立消费者，把它当作盘点辅助而非完整性证明；检查结果后追踪每个 provider 响应到其消费者；同时检查 package manifests 和 lockfiles、直接 REST 端点和 auth headers、SDK 客户端/异步客户端/封装/模型工具定义、环境 schema/示例/部署配置/文档、请求构造器/重试/超时/缓存/可观测性/错误处理、用于渲染/排序/阈值/引用/模型上下文的响应字段、Firecrawl crawl/batch/extract/browser/interaction/webhook/job-lifecycle 消费者、测试/mock/fixture/snapshot。
5. 可行时在编辑前运行现有聚焦测试，记录当前覆盖的行为、既有失败和必须手动验证的行为。
6. 编辑前为每个 provider 调用点写决策行：`Call site`（`path:line`）、`Provider product`（Search、Scrape、Agent 等）、`Consumed behavior`（调用方依赖的输入、输出、生命周期和策略）、`Parallel route`（确切产品路径，若有）、`Semantic gap`（该路由无法保留的内容）、`Action`（`migrate`、`retain` 或 `block`）；改调用前只选一个动作：仅当提议路由保留消费契约或用户已批准指定差异时用 `migrate`；当调用在迁移边界外或是保留不支持能力的最小安全方式时用 `retain`；当请求边界无法在没有用户决策下完成时用 `block`，指出最小决策并继续任何独立的 `migrate` 行；不要仅为消除 provider import 而使用更宽的 Parallel 产品，合理的结果形状不是源范围、花费控制、模型行为、生命周期或隐私策略仍等价的证据。
7. 选择迁移边界：编辑前考虑两种设计——直接替换（provider 调用少、集中且 provider 专有响应类型不外泄时，原子替换每个调用及其消费者）和应用自有网页数据模块（调用分散、需要多个 Parallel 产品或 provider 字段泄漏进应用时，把请求构造、响应规范化、重试和遥测放在一个小的面向调用方接口后，做成隐藏 provider 细节的深模块，不要加透传包装）；优先选择能本地化未来搜索 provider 变更并最小化无关调用方编辑的设计；若应用发布旧 provider 原始响应，要么通过 normalizer 只保留文档化的应用契约，要么一起更新所有消费者。
8. 有意迁移请求：每个 Parallel Search API 请求围绕这些事实构造——`search_queries` 必填，至少提供一个非空关键词查询，调用流能提供时用两到三个多样关键词查询；`objective` 可选但推荐，把自包含网页研究目标放这里，而不是整个用户对话或答案格式指令；直接 REST 调用用 `https://api.parallel.ai/v1/search`、`x-api-key` 和 `PARALLEL_API_KEY`；Python 和 TypeScript 都用官方 `parallel-web` 包，除非检测到的框架有保留所需契约的当前一方 Parallel 集成。
9. 翻译前分类每个旧输入：完整网页研究目标、上下文或软来源/时效偏好 → `objective`；简洁检索探针 → `search_queries`；必须仅用或绝不使用的来源限制 → `advanced_settings.source_policy`；答案格式、合成指令、结构化输出或 streaming → 现有合成层、Chat API 或 Task API；延迟、结果数、缓存和摘录控制 → 应用自有策略，显式选择并测试。
10. 静态调用写明确 objective 和两到三个关键词探针；模型工具用 references/integration-patterns.md 中的精确三查询 schema；单查询直接调用回退仅用于已是关键词风格的旧值且必须评估；不要静默截断意图、编造关键词变体、添加隐藏 planner 或把硬过滤移入散文。
11. 分类后才应用 provider 映射；只保留实现真实产品需求的设置，不必要的 `advanced_settings` 会降低质量。
12. 发送前按 Parallel V1 契约验证运行时值，特别注意查询数量/长度、objective 长度、合计 200 域名限制、日期规范化和支持的位置代码；不要隐式沿用旧 provider 的数值范围。
13. 迁移响应行为：把每个消费者更新到 Parallel 响应形状；Search API 返回带 `url`、可选 `title`、可选 `publish_date` 和 `excerpts` 数组的排序 `results`，不返回旧 provider 的相关性分数、生成答案、图片字段、响应时间或整页正文。
14. 保留字段语义而非仅字段名：仅日期的 `publish_date` 不能恢复旧时间戳的时分精度，`search_id` 不是会话标识符，SKU 使用计数不是 provider credits 或美元成本；仅当应用契约定义了转换时才规范化，否则把契约变更显式化。
15. 显式路由非搜索行为：LLM 上下文或简洁证据直接用 Search API excerpts；从已知结果 URL 获取全文用 Extract API，复用 Search API `session_id`；有依据的答案用 Chat API 或应用现有模型；异步多步研究或结构化合成用 Task API；同步人员或公司发现用 Entity Search。
16. 对 Firecrawl，选路由前先分类产品：Search 通常映射到 Search；公共 URL markdown 或全文可映射到 Extract；结构化多页研究仅当 Task 保留所需源范围、花费策略、质量选择和生命周期时才映射到 Task；确切已知 URL 的结构化提取更适合 Extract 加应用自有模型/解析器；Research Index、Crawl、Map、Parse uploads、Browser、Interact、Monitor、截图和其他丰富抓取行为不是 Search 字段映射；遵循 references/firecrawl.md 并保留独立能力直到批准明确替代。
17. 不要用看似合理的常量填充缺失字段；移除过时消费者、重新设计应用契约或使用合适的 Parallel API。
18. 替换依赖和配置：只添加所选路由需要的 SDK——Search、Extract 或 Task 用 `parallel-web`；Chat 用 `openai`，除非应用已有兼容客户端；直接 REST 是更简单的现有模式时不加 SDK；仅当没有 `retain` 行仍依赖旧 provider 包时才移除它，然后用仓库包管理器重新生成 lockfile；只在 `migrate` 行内替换 provider import、客户端初始化、端点和 headers；保留共享 provider 设置直到 retained 调用有自己的明确边界；把 `PARALLEL_API_KEY` 加入已检入环境模板、验证 schema、安装脚本、部署 manifest、示例和文档；仅当没有 retained 运行时能力仍需要旧 key 时才从这些表面移除；在 Parallel SDK 支持处保留现有超时、重试、取消和日志行为，否则在应用边界实现并测试；保持错误消息 provider 中立，除非 provider 名称有助于操作员行动；绝不在日志、报告、补丁或 fixture 中暴露或改写真实密钥值。
19. 验证行为而非仅语法：为以下内容添加或更新测试——请求构造（含 `search_queries`、mode、filters、dates 和 location）；apex 域名、子域名、scheme、路径、通配符、冲突列表和 provider 专有上限的 source-policy 规范化；查询设计行为（静态请求、直接单查询兼容路径和模型工具 schema）；省略的旧默认值、双域名列表和任何已批准语义变更；动态查询和域名列表的目标上限验证；响应解析和 excerpt 拼接；空结果、缺失可选 title/date、warnings 和 errors；任何保留应用自有契约的 normalizer；使用时的全文、合成或实体路由；移除分数阈值或 provider 专有字段。
20. 保留仓库测试执行契约：若其聚焦测试此前 stub 了 provider 包并在未安装该 SDK 下运行，也要 stub 替代 SDK 或把 import 保持在注入边界后；在等价干净环境中重跑完全相同的迁移前测试命令，依赖环境包的通过不是仓库仍自包含的证据。
21. 然后按顺序运行：1) 窄迁移测试；2) 仓库的 formatter、type checker、lint、build 和更广测试（视情况）；3) 完全移除该 provider 时运行 `python3 <skill-root>/scripts/scan_provider_usage.py . --provider <legacy-provider> --fail-on-legacy`；4) 当批准的非搜索 Perplexity 或 Firecrawl 用法保留时，不带 `--fail-on-legacy` 运行 provider 扫描，分类每个发现，然后只扫描已迁移根或用窄 `--exclude` 路径隔离 retained 模块，绝不排除混合搜索/非搜索边界；5) 独立大小写不敏感搜索 `exa`、`tavily`、`perplexity`、`sonar-`、`firecrawl`、赋给 `sonar` 的确切 `model`、路由的 `perplexity/sonar` 模型 ID、包名、端点和 key 名，若 skill 安装在目标仓库内则排除 `<skill-root>`；6) 审查最终 diff 是否有意外行为变更、泄漏值、无关编辑和过时 lockfile；7) 仅当本任务明确授权 provider 调用且 `PARALLEL_API_KEY` 已可用时做实时冒烟测试，不打印它。
22. 环境凭据本身不授权付费网络调用；获授权时用小的非敏感合成查询并检查 `warnings`、结果排序、excerpts 和错误行为；仅当用户批准把代表性生产查询发给两个 provider，或现有仓库测试策略已允许该确切比较时才比较；不要要求用户粘贴密钥。
23. 完成门：仅当所有适用陈述为真时结束——迁移边界内无旧 provider 运行时依赖、import、端点、auth header、key 引用、工具定义、fixture 或过时设置说明；该边界外的任何 Perplexity 模型路由、embeddings、sandbox、MCP 或自定义函数能力保持完整或被列为明确 blocker；任何已迁移 `finance_search` 路径通过经评估的 Parallel 路由并在需要时通过应用自有 normalizer 保留消费的最终答案或 `finance_results` 契约，未解决的硬性覆盖或时效要求是明确 blocker；该边界外的任何 Firecrawl crawl、map、file-parse、browser、interaction、rich-format、change-tracking、security/privacy、MCP 或异步 job 能力保持完整或被列为明确 blocker；每个盘点调用都有记录的 `migrate`、`retain` 或 `block` 决策，且没有 `block` 行被当作缺口已解决而编辑；Firecrawl 确切 URL 约束、每次运行 credit 上限、`spark-1-*` 模型选择和同步/异步行为被保留或仅经明确批准更改，域名 allow-list、省略预算或猜测的 Task processor 不满足此门；每个使用的请求特性和响应字段都有已实现的 Parallel 路径或明确批准的行为变更；查询构造保留研究目标、使用关键词形检索探针并遵循适用的直接调用或模型工具契约；source-policy 迁移保留预期 URL 范围，不支持的路径或通配符行为被显式实现或记录为已批准缺口；测试和静态检查通过，或无关既有失败被有证据地识别；provider 被完全移除时 provider 专有旧扫描通过，否则每个剩余发现属于已批准隔离的非搜索边界且每个识别响应已追踪到其下游消费者；实时调用在明确授权且凭据可用时通过，否则清楚说明缺失的实时验证；最终报告命名迁移边界、重要语义选择、验证命令和仍留给操作员的外部密钥清理。

适用边界 · 注意事项

• 当所需行为没有受支持的 Parallel 等价物且没有范围内替代时（如 Perplexity embeddings、Firecrawl 完整爬取/URL 映射/本地文件解析/浏览器会话/截图/变更跟踪等），不要继续破坏性编辑，应停止并报告缺口。
• 当 Perplexity 边界存在硬性市场数据覆盖、时效或原始结果要求且无法通过 Parallel 通用索引保留时，不要强行迁移。
• 当用户未明确授权付费网络调用或未提供 `PARALLEL_API_KEY` 时，不要执行实时冒烟测试或把生产查询发送给两个 provider。