migrate-to-parallel

迁移到 Parallel

端到端替换提供方边界。将成功的 HTTP 响应视为中点，而非完成：迁移请求构造、响应使用方、依赖项、配置、测试和运维行为。

将 <skill-root> 解析为包含此 SKILL.md 的目录。无论当前工作目录为何，都从该目录解析所有随附的参考资料和脚本。扫描器仅使用 Python 标准库。如果无法使用 Python 3.9 或更高版本，请使用工具提供的文件搜索工具进行等效的代码库搜索，并说明未运行随附的扫描。

加载合适的参考资料

1. 如果代码库中包含 Exa，请阅读 references/exa.md。
2. 如果代码库中包含 Tavily，请阅读 references/tavily.md。
3. 如果代码库中包含 Perplexity Search、Sonar、Agent API 网页工具或 Perplexity 搜索封装，请阅读 references/perplexity.md。
4. 如果代码库中包含 Firecrawl Search、Scrape、Batch Scrape、Extract、Agent、Research Index、Crawl、Map、Parse、Browser、Interact、Monitor 或 MCP 用法，请阅读 references/firecrawl.md。
5. 如果任何调用可能路由到 Search，或需要迁移查询、筛选条件、新鲜度、模式或结果列表，请阅读 references/parallel-search.md。
6. 如果任何调用可能路由到 Extract、Chat、Task 或实体发现，或需要迁移流式传输、结构化输出或引用，请阅读 references/parallel-products.md。
7. 如果查询是动态生成的、提供方以模型工具形式暴露、提供方响应类型会传播到多个模块，或应用需要完整内容或综合答案，请阅读 references/integration-patterns.md。
8. 对于检测到但上述参考资料未涵盖的任何 SDK、封装、参数或响应字段，请查阅当前官方文档。不要猜测提供方的行为。

保持这些不变量

• 除非用户明确授权更改，否则保持调用方可见的行为不变。
• 绝不悄悄丢弃筛选条件、内容字段、合成答案、图像、安全控制或基于评分的决策。
• 绝不输出 API 密钥或机密值。仅检查密钥是否存在。
• 不要仅仅为了生成 search_queries 而暗中添加 LLM 调用。
• 不要仅仅因为任意用户提示词符合 API 长度限制，就将其视为关键词查询。
• 将网络研究意图、硬性筛选条件、处理程序策略和答案合成指令保留在各自独立的契约中。
• 省略的提供商参数也会影响行为：省略 Parallel 设置前，先检查其默认值。
• 不要通过兼容性垫片重建整个旧版提供商 SDK。只规范化应用实际使用的契约。
• 除非用户明确要求，否则不要从外部密钥管理器或提供商控制面板中删除凭据。删除过时的代码引用，并更新已签入的模板。
• 将模式映射视为起点。使用应用的真实查询验证延迟、质量和输出行为。
• 如果必需行为没有受支持的 Parallel 等效功能，也没有范围内的替代方案，请在进行破坏性编辑前停止。报告确切的缺口以及所需的最小决策。
• 如果 Perplexity 的边界需要 embeddings，请停止；它们不能由 Parallel Search 替代。根据实际使用的契约，通过 Parallel 的通用索引使用 Search、Chat 或 Task 来处理 finance_search；仅当硬性市场数据覆盖范围、新鲜度或原始结果要求仍未得到保留时才停止。除非用户明确扩大迁移范围，否则应将 Agent API 的模型路由、沙箱、MCP 和现有自定义函数能力分开处理。
• 如果 Firecrawl 的边界需要完整爬取或 URL 映射、本地／私有文件解析、浏览器操作或会话、屏幕截图或其他丰富的抓取格式、更改追踪，或没有经批准替代方案的 Firecrawl 专属隐私／安全控制，请停止。Search 和 Extract 无法重现这些契约。
• 遵循仓库本地的说明，例如 AGENTS.md、CLAUDE.md 和 CONTRIBUTING.md。保留无关的工作，绝不重置或丢弃用户更改。
• 完成安全的仓库本地迁移工作，不要在盘点或制定计划后就停止。除非用户提出要求，否则不要提交、推送、更改托管密钥或修改提供商账户。

1. 清点实际迁移范围

编辑前，记录当前分支和工作区状态。从目标仓库运行随附的扫描器：

python3 <skill-root>/scripts/scan_provider_usage.py .

使用 --format json 获取机器可读的输出。扫描器会有意跳过依赖项／生成文件目录、二进制文件、无法读取的文件以及过大的文件；仅凭字段名称无法识别与提供商无关的使用方。请将扫描结果作为清点辅助，而非完整性证明。检查结果，然后追踪每个提供商响应的使用方。还要检查：

• 软件包清单和锁文件；
• 直接 REST 端点和认证标头；
• SDK 客户端、异步客户端、封装层和模型工具定义；
• 环境变量架构、示例、部署配置和文档；
• 请求构建器、重试、超时、缓存、可观测性和错误处理；
• 用于渲染、排序、阈值、引用或模型上下文的响应字段；
• Firecrawl 爬取、批处理、提取、浏览器、交互、Webhook 和任务生命周期相关的使用方；
• 测试、模拟对象、固定数据和快照。

可行时，在编辑前运行现有的专项测试。记录当前已覆盖的行为、已有的失败，以及必须手动验证的行为。

编辑前，为每个提供商调用点填写一行决策记录：

调用点	提供商产品	使用的行为	Parallel 对应路线	语义差异	操作
path:line	Search、Scrape、Agent 等	调用方依赖的输入、输出、生命周期和策略	如有，填写对应的具体产品路径	该路线无法保留的任何内容	migrate、retain 或 block

修改调用前，必须且只能选择一种操作：

• 仅当拟采用的路线保留了调用契约，或用户已批准所列差异时，选择 migrate；
• 当调用位于迁移范围之外，或这是保留不受支持功能的最小安全方案时，选择 retain；
• 当未获得用户决策就无法完成所要求的范围时，选择 block。指出所需的最小决策，并继续处理任何独立的 migrate 行。

不要仅为移除某个提供商导入，就改用功能更广泛的 Parallel 产品。结果形状看似合理，并不能证明来源范围、支出控制、模型行为、生命周期或隐私策略仍然等效。

2. 选择迁移边界

编辑前，请同时考虑以下两种设计：

• 直接替换： 适用于提供商调用数量少、彼此接近，且提供商专属的响应类型不会传播到其他地方的情况。逐个替换调用及其使用方，并确保原子性。
• 应用自有的数据模块： 适用于调用分散、需要多个 Parallel 产品，或提供商字段会传播到应用其他部分的情况。将请求构建、响应规范化、重试和遥测封装在一个小型、面向调用方的接口之后。应将其设计为隐藏提供商细节的深层模块；不要添加仅透传数据的封装层。

优先选择能将未来搜索提供商变更限制在局部，并尽量减少对无关调用方修改的设计。如果应用会公开旧提供商的原始响应，则要么通过规范化器仅保留有文档说明的应用契约，要么同时更新所有使用方。

3. 有目的地迁移请求

围绕以下事实构建每个 Parallel Search API 请求：

• search_queries 为必填项。至少提供一个非空的关键词查询；如果调用流程能够提供多个查询，则使用两到三个不同的关键词查询。
• objective 为可选项，但建议提供。在其中填写完整、自成一体的网络研究目标，而不是整段用户对话或答案格式说明。
• 对于直接 REST 调用，请使用 https://api.parallel.ai/v1/search、x-api-key 和 PARALLEL_API_KEY。
• 对于 Python 和 TypeScript，请使用官方的 parallel-web 包；除非检测到的框架包含当前由 Parallel 提供、且能保留所需契约的一方集成。

翻译每项旧版输入前，先进行分类：

• 完整的网络研究目标、上下文或宽松的来源／时效性偏好 → objective；
• 简洁的检索探查 → search_queries；
• 仅允许或绝不允许的来源限制 → advanced_settings.source_policy；
• 答案格式、综合指令、结构化输出或流式传输 → 现有综合层、Chat API 或 Task API；
• 延迟、结果数量、缓存和摘录控制 → 由应用自行决定并明确测试的策略。

对于静态调用，明确编写一个目标和两到三个关键词探查。对于模型工具，请使用 references/integration-patterns.md 中恰好包含三个查询的架构。仅当旧版值本身已采用关键词形式时，才可使用单查询直接调用回退方案，并且必须经过评估。不要默默截断意图、臆造关键词变体、添加隐藏规划器，也不要将硬性筛选条件移入描述文本。

只有完成上述分类后，才应用提供商映射。仅保留能实现实际产品需求的设置；不必要的 advanced_settings 可能会降低质量。

发送前，根据 Parallel V1 契约验证运行时值。尤其要注意查询数量／长度、目标长度、合计 200 个域名的限制、日期规范化，以及受支持的位置代码。不要默认沿用旧提供商的数值范围。

4. 迁移响应行为

更新所有使用方，使其适配 Parallel 响应结构。Search API 会返回按相关性排序的 results，其中包含 url、可选的 title、可选的 publish_date 和 excerpts 数组。它不会返回旧提供商的相关性评分、生成的答案、图片字段、响应时间或完整页面正文。

保留字段语义，而不只是字段名称。仅包含日期的 publish_date 无法恢复旧时间戳的时分秒精度；search_id 不是会话标识符；SKU 用量计数也不是提供商额度或美元成本。只有在应用契约定义了转换方式时才进行规范化；否则应明确说明契约变更。

明确路由非搜索行为：

• 直接使用 Search API 摘录作为大模型上下文或简明证据。
• 对已知结果 URL 的完整内容使用 Extract API，并复用 Search API 的 session_id。
• 使用 Chat API 或应用现有模型生成有依据的答案。
• 使用 Task API 进行异步多步骤研究或结构化综合。
• 使用 Entity Search 同步查找人员或公司。

对于 Firecrawl，请先判定产品类型，再选择路由。Search 通常映射到 Search；公开 URL 的 Markdown 或完整内容可能映射到 Extract；只有在 Task 能保留所需来源范围、支出策略、质量选项和生命周期时，结构化的多页研究才映射到 Task。对于已知 URL 的精确结构化提取，优先选择 Extract 加由应用管理的模型／解析器。Research Index、Crawl、Map、Parse 上传、Browser、Interact、Monitor、屏幕截图及其他丰富的抓取行为，都不是 Search 字段映射。请遵循 references/firecrawl.md，并保留独立能力，直到明确批准替代方案。

不要用看似合理的常量填充缺失字段。移除过时的使用方、重新设计应用契约，或使用相应的 Parallel API。

5. 替换依赖项和配置

• 仅添加所选路由所需的 SDK：Search、Extract 或 Task 使用 parallel-web；Chat 使用 openai，除非应用已有兼容客户端；如果直接 REST 更符合现有模式，则无需 SDK。
• 只有在没有任何 retain 行仍依赖旧提供商包时，才移除该包，然后使用仓库的包管理器重新生成锁文件。
• 仅在 migrate 行中替换提供商导入、客户端初始化、端点和请求头。在保留的调用有各自明确边界之前，保留共享的提供商配置。
• 将 PARALLEL_API_KEY 添加到已检入版本控制的环境模板、验证模式、设置脚本、部署清单、示例和文档中。只有在没有保留的运行时能力仍需要旧密钥时，才从这些位置移除旧密钥。
• 如果 Parallel SDK 支持，则保留现有的超时、重试、取消和日志记录行为；否则，应在应用边界处实现这些行为并进行测试。
• 除非提供商名称有助于操作人员采取行动，否则错误消息应与提供商无关。

绝不要在日志、报告、补丁或测试样例中暴露或改写真实密钥值。

6. 验证行为，而不只是语法

为以下内容添加或更新测试：

• 请求构造，包括 search_queries、模式、筛选条件、日期和位置；
• 来源策略规范化，涵盖顶级域名、子域名、方案、路径、通配符、冲突列表和特定提供商的限制；
• 查询设计行为：静态请求、直接单查询兼容路径和模型工具模式；
• 省略旧版默认值、双域名列表以及任何获批的语义变更；
• 动态查询和域名列表的目标数量限制验证；
• 响应解析和摘要拼接；
• 空结果、缺少可选标题／日期、警告和错误；
• 任何用于保留应用自有契约的规范化器；
• 使用到的全文、综合或实体路由；
• 移除分数阈值或特定提供商字段。

保留仓库的测试执行约定。如果其针对性测试此前会对提供商包打桩，并且无需安装该 SDK 即可运行，那么也应对替代 SDK 打桩，或继续将导入限制在注入边界之后。在等效的干净环境中重新运行迁移前的确切测试命令；依赖环境中已有的软件包而通过，并不能证明仓库仍可独立运行。

然后按顺序运行：

1. 范围最窄的迁移测试；
2. 按需运行仓库的格式化工具、类型检查器、代码检查、构建和更广泛的测试；
3. 完全移除该提供商时，运行 python3 <skill-root>/scripts/scan_provider_usage.py . --provider <legacy-provider> --fail-on-legacy；
4. 获批的非搜索 Perplexity 或 Firecrawl 用法仍存在时，不带 --fail-on-legacy 运行提供商扫描，逐项归类所有发现，然后仅扫描已迁移的根目录，或对独立保留的模块使用范围狭窄的 --exclude 路径；绝不要排除同时包含搜索和非搜索功能的边界；
5. 独立进行不区分大小写的搜索，查找 exa、tavily、perplexity、sonar-、firecrawl、精确赋值为 sonar 的 model、路由后的 perplexity/sonar 模型 ID、软件包名称、端点和密钥名称；如果 <skill-root> 安装在目标仓库内，则将其排除；
6. 审查最终差异，检查是否存在非预期的行为变更、泄露的值、不相关的编辑和过时的锁文件；
7. 仅当明确授权本任务调用提供商，且 PARALLEL_API_KEY 已可用时，才运行在线冒烟测试；不得打印该密钥。

环境中存在凭据本身并不代表授权进行付费网络调用。获得授权后，使用小型、非敏感的合成查询，并检查 warnings、结果排序、摘要和错误行为。只有当用户批准将具有代表性的生产查询发送给两个提供商，或现有仓库测试策略已允许进行该项比较时，才进行比较。不要要求用户粘贴密钥。

完成门槛

仅当以下所有适用项均为真时，才算完成：

• 在迁移边界内，不再存在对旧提供方的运行时依赖、导入、端点、身份验证标头、密钥引用、工具定义、测试夹具或过时的设置说明。
• 该边界之外的任何 Perplexity 模型路由、嵌入、沙盒、MCP 或自定义函数能力，均保持完好，或被明确列为阻塞项。
• 任何已迁移的 finance_search 路径，均通过经过评估的 Parallel 路由保留所使用的最终答案或 finance_results 契约，并在需要时使用由应用程序管理的规范化器；尚未解决的硬性覆盖范围或时效性要求，均明确列为阻塞项。
• 该边界之外的任何 Firecrawl 抓取、地图、文件解析、浏览器、交互、丰富格式、变更跟踪、安全／隐私、MCP 或异步作业能力，均保持完好，或被明确列为阻塞项。
• 每个已盘点的调用都记录了 migrate、retain 或 block 决策，且没有任何 block 行被当作缺口已解决而修改。
• Firecrawl 的精确 URL 限制、每次运行的额度上限、spark-1-* 模型选择以及同步／异步行为，均予以保留；如需更改，必须获得明确批准。域名允许列表、未指定预算或臆测的 Task 处理器均不满足此门槛。
• 每项已使用的请求功能和响应字段，均有已实现的 Parallel 路径，或已获明确批准的行为变更。
• 查询构造保留研究目标，使用关键词形式的检索探针，并遵循适用的直接调用或模型工具契约。
• 来源策略迁移保留预期的 URL 范围；不受支持的路径或通配符行为，均已明确实现，或记录为经批准的缺口。
• 测试和静态检查均通过，或有证据表明失败与本次工作无关，且属于先前已存在的问题。
• 如果提供方已被完全移除，则通过针对该提供方的专用扫描。否则，所有剩余发现均属于经批准且隔离的非搜索边界，并且已追踪每项发现的响应在下游的所有使用方。
• 如果已明确授权实时调用且凭据可用，则实时调用通过；否则，必须清楚说明缺少实时验证。
• 最终报告列出迁移边界、重要的语义选择、验证命令，以及仍需操作员处理的任何外部密钥清理事项。