parallel-findall

FindAll：实体发现

查找：$ARGUMENTS

完整的 FindAll 需要 parallel-cli ≥ 0.3.0；可选的 entity-search 路径需要 ≥ 0.6.0。如果缺少文档中提到的命令或选项，请通过此 CLI 使用的安装方式进行更新，然后重试。请参阅 https://docs.parallel.ai/integrations/cli。

何时使用此技能

当需要根据描述获取结构化实体列表时，使用 FindAll。对于网页或快速解答，请使用 parallel-web-search；对于叙述性分析，请使用 parallel-deep-research；对于为用户已有的列表添加字段，请使用 parallel-data-enrichment。

默认使用全面的异步 findall run。它支持匹配条件、排除项、丰富处理、证据，以及公司和个人以外的实体类型。“查找所有”并不保证覆盖互联网上的全部内容。

只有在用户明确需要快速或粗略的公司或个人列表，并接受未经逐项核实的结果时，才使用同步的 entity-search 路径。不要仅仅因为它支持该实体类型就选择它。它不支持排除项、生成器选择、丰富处理，也不提供 FindAll 条件和丰富处理引用。

步骤 1：启动并保留运行记录

为保存的 JSON 文件选择一个未使用过且能描述本次运行的 $FILENAME。将用户目标作为一个带引号的参数传入，不进行 shell 求值。

parallel-cli findall run "$ARGUMENTS" --no-wait --json -o "/tmp/$FILENAME-create.json"

默认生成器为 core，匹配上限为 10。如需匹配最多 50 个实体，请使用 -n 50；允许的上限为 5–1000。除非用户要求其他权衡，否则使用 core。pro 会搜索更大的范围，但速度更慢、成本更高；只有在用户明确要求粗略扫描时，才使用速度更快、质量较低的 base。请根据可用证据抽查批次、年份和地理范围等具体说法，尤其是在使用 base 时。

如需排除项：

parallel-cli findall run "$ARGUMENTS" --no-wait --json \
    --exclude '[{"name":"Google","url":"google.com"},{"name":"OpenAI","url":"openai.com"}]' \
    -o "/tmp/$FILENAME-create.json"

如果目标需要澄清，parallel-cli findall ingest "$ARGUMENTS" --json 可以预览推断出的实体类型、条件和建议的丰富字段。这会调用 API；并非离线或免费的测试。如果推断出的条件与用户意图不同，请先完善目标，再创建运行。

立即记录返回的 findall_id，以及目标、生成器、匹配上限和排除项。报告运行已启动；只有在实际返回监控 URL 时才提供该 URL。不要推断 URL 或保证完成时间。如果创建响应丢失，请先查找现有任务，再重新提交。

步骤 2：明确添加所需字段

--no-wait 会接收输入并创建运行，但不会应用建议的丰富字段。所需输出字段（例如 CEO 姓名或员工人数）需要单独提交丰富处理请求；仅在目标中提及这些字段并不足够。

parallel-cli findall enrich "$FINDALL_ID" \
    '{"type":"object","properties":{"ceo":{"type":"string","description":"CEO name"},"employee_count":{"type":"number","description":"Number of employees"}}}' \
    -p core --json

请使用描述用户所需字段的 JSON Schema 对象，而非完整的 ingest 信封。请将提交的确切 schema 和 processor 与运行 ID 一并保存在本地；如果使用了多个请求，也要全部保留。不要依赖 schema 摘要在之后重建它们。丰富处理会添加非布尔型输出数据，不会更改匹配条件。

运行进行中或完成后，都可以添加丰富处理。已进入终态的运行可以重新排队，以处理这些字段。创建运行、接受丰富处理请求和结果填充是彼此独立的结果。不要仅凭丰富处理响应或一次已完成的轮询，就声称字段已就绪。

步骤 3：检查状态并获取结果

parallel-cli findall status "$FINDALL_ID" --json
parallel-cli findall poll "$FINDALL_ID" -o "/tmp/$FILENAME.json" --timeout 60
parallel-cli findall result "$FINDALL_ID" -o "/tmp/$FILENAME-snapshot.json"

使用有界等待。超时（退出码 5）或中断表示本地等待耗尽，并不代表取消。只要任务仍处于活动状态，就应在用户的等待时限内检查状态并使用相同 ID 恢复；不要提交另一次运行。共享轮询器无法识别兼容状态 action_required。如果出现该状态、failed、cancelled 或未完成且不活动的状态，请停止自动等待，并报告该状态以及需要人工处理的已保存 ID。

result 返回的是快照，不能证明任务已完成。应同时读取 status 和 is_active。富化完成后，检查每个匹配候选项的 output 是否包含所有请求字段。如果字段缺失，应在有界等待时限内获取更多结果快照，即使首次轮询显示任务已完成也是如此。报告缺失、为 null 或失败的值，不要凭空编造；如果等待时限已到，则返回部分结果和可用于恢复的 ID。匹配集为空并不能证明富化成功。

对于大型结果集，避免使用 --json；-o 会保留完整 JSON。这些命令可能覆盖所选文件，因此请使用属于本次运行的路径。保留原始候选列表和状态。/tmp 是临时目录；需要时，请将请求的交付文件复制到用户的持久位置。

展示匹配项和依据

只将 match_status: "matched" 的候选项列为匹配项。在原始文件中保留已生成、未匹配和已丢弃的候选项。检查明显的查询回显占位内容和缺乏依据的条目，不要将每个候选项都视为一个实体。

结合实体背景审查 URL。LinkedIn 个人资料可以合理地用于识别人物，YC 或 Crunchbase 个人资料也可以用于识别公司。不要仅仅因为实体不拥有该域名就丢弃这些 URL。标记缺失或无法验证的 URL，并利用现有依据消除不确定性。

事实性陈述应以条件和富化依据为准，并附上其来源 URL。实体的主 URL 与支持性引用可以不同。除非主 URL 或个人资料 URL 能支持相关说法，否则不要将其标注为某项属性的依据。

首先说明所展示的匹配实体数量，注明排除项或尚未解决的条目，并使用表格或列表列出名称、URL 和请求字段。包括已保存的原始结果路径、运行 ID、当前状态以及任何未完成的字段。结果稀少或噪声较多时，可以建议调整目标或生成器；不要自动创建替代的付费运行。

获取更多匹配项

只有在用户请求更多匹配项时才扩展：

parallel-cli findall schema "$FINDALL_ID" --json
parallel-cli findall extend "$FINDALL_ID" 50 --json

50 是增加量，不是新的总数。检查已知的创建上限或当前架构，包括之前的扩展，以确保最终总数不超过 1000。预览运行无法扩展。只有终止原因是 match_limit_met 的已完成运行才符合扩展条件；CLI 中的 status/result 不包含该原因，因此无法证明运行符合条件。对于用户明确请求且不超过上限的扩展，让 API 验证是否符合条件；如果被拒绝，应显示拒绝信息，不要自动创建新的运行。

保留更新后的上限，并轮询相同 ID 以获取新结果。重新检查请求的富化字段；如果必须重新应用现有富化，则在用户授权范围内使用原先保留的请求负载和处理器。

快速实体搜索

仅在用户明确要求快速获取粗略列表，且实体类型为 companies 或 people 时使用。此操作是同步的，返回 entity_set_id 和按排名排列的 entities，而非 findall_id 或经过验证的候选项。

parallel-cli findall entity-search "$ARGUMENTS" -t companies -n 10 -o "/tmp/$FILENAME.json"

-n 的限制范围为 5–1000，默认值为 10。根据用户的请求选择相应的限制值。此路径应避免使用限制过严的条件：列表后部的相关性可能会降低。如果需要逐项条件检查或信息补充，请使用完整的 FindAll。

保留有效的目录／个人资料链接，并检查空 URL 或与查询内容相同的名称。将这些内容作为未经验证的线索呈现，并引用指向相应实体的链接；不要声称它们具有不存在的 FindAll 依据或验证。报告已保存的路径和返回的数量。切勿将 entity_set_id 传递给 FindAll 的 poll/status/result/enrich/extend。如果用户之后需要这些功能，请说明需要单独运行完整搜索，并保留原有的快速搜索结果。

设置

需要安装并完成身份验证的 parallel-cli。检查 parallel-cli --version 和 parallel-cli auth --json；即使 authenticated 为 false，身份验证命令也可能成功退出。缺少二进制文件、不支持的命令／选项以及身份验证失败，分别需要采取不同的解决方法：安装、通过现有安装方式升级，或在终端中登录。请参阅 https://docs.parallel.ai/integrations/cli。身份验证失败时，停止受影响的请求；不要在聊天中索要机密信息，也不要为了绕过受阻的设置而更改账户策略。