parallel-findall

FindAll：实体发现

查找：$ARGUMENTS

需要 parallel-cli ≥ 0.6.0（findall entity-search 命令在 0.6.0 中添加；更广泛的 findall 命令在 0.3.0 中添加）。如果出现 no such command 或类似错误，请告知用户运行 parallel-cli update（如果通过 pipx 安装，则运行 pipx upgrade parallel-web-tools），然后重试。

何时使用此技能

当用户想要一个与描述匹配的结构化实体列表，而不是网页或叙述性答案时，使用 FindAll。

用户要求…	使用
“查找所有X…” / “列出每一个Y…”	parallel-findall（此技能）
网页结果 / 快速答案 / 当前信息	parallel-web-search
叙述性报告 / 分析 / “研究X”	parallel-deep-research
为已有列表添加字段	parallel-data-enrichment

如果用户已有列表，只想添加字段，则此技能不适用——应使用 parallel-data-enrichment。

FindAll 有两条路径：全面的异步 findall run（步骤 1-2）和快速的同步 entity-search（最后一部分）。

• entity-search — 非常快（几秒钟），仅支持人物或公司搜索。支持的查询参数更有限。优化了召回率而非精确度；结果未单独验证。
• findall run — 提供全面覆盖、复杂的匹配条件、排除、丰富、引用或除人物/公司之外的类型。

如果不明确，询问用户偏好并提供默认选项。记住实体搜索的限制：仅限公司/人物，无排除/生成器/丰富功能，且 entity_set_id 不能与 enrich/extend 一起使用（如果需要，通过 findall run 重新运行）。

仅当用户明确表示想要一个快速、一次性的列表时，才切换到 entity-search。entity-search 的限制也更严格：它仅支持 companies 或 people 实体类型，无排除，无生成器选择，无丰富功能，返回的 entity_set_id 不能与 findall enrich/extend 一起使用。如果从那里开始，用户后来要求丰富或扩展，则必须通过 findall run 重新运行。

步骤 1：启动运行

parallel-cli findall run "$ARGUMENTS" --no-wait --json

默认值：生成器 core，匹配限制 10。除非用户有理由升级，否则坚持使用 core：

• -g pro — 最彻底的生成器（更慢，成本更高）。当用户要求“全面”覆盖或在 core 上匹配稀疏时使用
• -g base — 最快，但质量明显较低。通常返回查询回显实体（例如，目录页面、字面查询字符串）、没有 URL 的条目或类别占位符。仅当用户明确要求快速扫描并接受噪音时使用；否则优先使用 core
• -n 50 — 最多返回 50 个匹配实体（允许 5-1000）

如果用户想要排除已知实体（例如，“查找竞争对手，但不包括 Google 或 OpenAI”）：

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

提示——如果目标不明确，先预览模式：parallel-cli findall ingest "$ARGUMENTS" --json 显示 API 推断的实体类型和匹配条件，以便在付费运行前优化措辞。

解析 JSON 输出以提取 findall_id 和任何监控 URL。告知用户：

• FindAll 运行已启动
• 大致节奏（core 几分钟，pro 更长）
• 他们可以在运行期间继续工作

步骤 2：轮询结果

选择一个描述性文件名（例如，series-a-ai-2026、charlotte-roofers）。使用小写字母和连字符，无空格。

parallel-cli findall poll "$FINDALL_ID" -o "/tmp/$FILENAME.json" --timeout 540

重要：

• 使用 --timeout 540（9 分钟）以保持在工具执行限制内
• 对于大型结果集，不要传递 --json——它会淹没上下文。-o 将完整结果保存到磁盘

如果轮询超时

重新运行相同的 parallel-cli findall poll 命令以继续等待。服务器端运行不受影响。

响应格式

在呈现匹配结果之前，过滤掉明显的噪音：

• 删除 url 为空/缺失的条目
• 删除 name 回应用户查询的条目（例如，字面“YC W25 批次开发者工具公司”）——这些是搜索结果占位符，不是真实实体
• 删除 url 是第三方目录或个人资料页面而非实体自身域名的条目。URL 应该是实体自身拥有的东西（其产品网站、文档或营销网站）

如果过滤移除了相当一部分匹配结果，请告知用户，并建议使用 -g pro 或更高的 -n 重新运行。

对 -g base 的结果进行合理性检查。 base 生成器可能幻觉出分类属性（例如，将 YC S22 公司返回为 YC W25 匹配）。上述过滤规则仅捕获 URL/名称形状，而非事实正确性。如果用户的查询具有可证伪的属性（特定批次、年份、地理位置等），请对照源 URL 抽查保留的条目，并标记任何不符合的条目。如果多个保留条目未通过抽查或噪音过滤移除了匹配集的相当一部分（例如，≥40%），建议使用 -g core（或更高）重新运行——两者都表明 base 对此查询无法产生可靠结果。

将剩余的（真实）实体以 Markdown 表格或列表形式呈现。先显示数量，然后列出每个实体及其名称、URL 和一行描述（如果有）。为每个实体引用其源 URL。

告知用户：

• 匹配了多少实体（以及有多少被过滤为噪音，如果有）
• 完整结果路径（/tmp/$FILENAME.json）
• 他们可以：

  • 为这些结果添加字段，例如：

    parallel-cli findall enrich $FINDALL_ID '{"properties":{"ceo":{"type":"string"},"employee_count":{"type":"number"}}}'
    

    模式是一个 JSON Schema 风格的对象，包含 properties，将字段名称映射到 {type, description?}。

  • 获取更多匹配：parallel-cli findall extend $FINDALL_ID 50

快速实体搜索

仅当用户明确表示想要一个快速/粗略/预览列表时才使用此路径——不要仅仅因为实体类型恰好是 companies 或 people 就选择它。

同步调用。无需轮询，无需 findall_id。选择一个描述性的 $FILENAME（小写，连字符，无空格），如步骤 2 所示。

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

标志：

• -t companies|people — 实体类型（必需）。端点仅支持这两种；对于其他类型，使用 findall run
• -n 5..1000 — 匹配限制（默认 10）。尽可能请求比用户需要的更多（例如 -n 100），并在过滤后选择——结果已排序但未单独验证，低限制可能遗漏相关实体
• 对于大型结果集，不要传递 --json——它会淹没上下文。-o 将完整结果保存到磁盘

在此路径上避免高度限制性的目标：API 会填充到限制，因此相关性在尾部下降。将核心标准保留在目标中，并在下游过滤其余部分，或使用 findall run。

响应格式：

{ "entity_set_id": "entity_set_…", "entities": [ {"name": "...", "url": "...", "description": "..."},
… ] }

与完整路径不同，entity-search 返回的 url 通常是目录/个人资料链接——这是预期的，不是噪音。不要删除它们；仅过滤掉 url 为空或 name 回应用户查询的条目。

将保留的实体以 Markdown 表格或列表形式呈现，先显示数量，并为每个实体引用其源 URL。告知用户：

• 返回了多少实体（以及有多少被过滤为噪音）
• 如果使用了 -o，则提供完整结果路径（/tmp/$FILENAME.json）

设置

需要 parallel-cli（已安装并认证）。如果 parallel-cli --version 失败，或后续命令因认证错误失败，请告知用户查看 https://docs.parallel.ai/integrations/cli 并停止。