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-search 的限制：僅限公司/人物，無排除條件/生成器/擴充功能，且 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 batch companies in developer tools」）——這些是搜尋結果的佔位符，不是真實實體
• 刪除 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 並停止。