parallel-data-enrichment

資料擴充

擴充：$ARGUMENTS

開始之前

告知使用者擴充可能需要數分鐘，視資料列數與要求的欄位數量而定。

選擇性：建議輸出欄位

如果使用者只給模糊意圖（例如「擴充這些公司，給我有用的資訊」），且你不確定要新增哪些欄位，可在啟動執行前先呼叫 API 取得建議：

parallel-cli enrich suggest "找出 CEO 與近期募資資訊" --json

回應為一個封裝物件：{title, processor, enriched_columns, warnings}。請只取出 enriched_columns 陣列（而非整個封裝），並將其作為 --enriched-columns 的值傳入 enrich run，取代 --intent——這兩個旗標是互斥的指定方式，不可同時使用。如果 suggest 有回傳 processor，請在 run 呼叫中明確透過 --processor 傳入（這是針對該資料結構的最佳化建議）。如果使用者已經指定了想要的欄位，則跳過本節。

enrich suggest 需要 parallel-cli ≥ 0.3.0。如果指令錯誤訊息類似 no such command / No such command / unknown command，請不要放棄——跳過建議步驟，直接進入步驟 1 使用 --intent，完成執行，並在最終回應中提示 parallel-cli update（或 pipx upgrade parallel-web-tools），讓使用者下次能使用此功能。

步驟 1：啟動擴充

使用以下其中一種指令模式（請替換為使用者的實際資料）：

內嵌資料：

parallel-cli enrich run --data '[{"company": "Google"}, {"company": "Microsoft"}]' --intent "CEO 名稱與成立年份" --target "output.csv" --no-wait --json

CSV 檔案：

parallel-cli enrich run --source-type csv --source "input.csv" --target "output.csv" --source-columns '[{"name": "company", "description": "公司名稱"}]' --intent "CEO 名稱與成立年份" --no-wait --json

如果這是接續前次研究任務，且你有該任務的 interaction_id，可加入上下文串接：

parallel-cli enrich run --data '...' --intent "..." --target "output.csv" --no-wait --json --previous-interaction-id "$INTERACTION_ID"

擴充將會帶著前次研究的完整上下文執行——因此你可以擴充先前發現的實體，而無需重複已找到的資訊。請注意：擴充本身不會產生新的 interaction_id，所以你無法再從擴充結果繼續串接下一輪。

重要： 務必加上 --no-wait，讓指令立即回傳而不阻塞。

解析 --json 輸出，取出 taskgroup_id 和 url。輸出格式為 {taskgroup_id, url, num_runs}——沒有 interaction_id 欄位，請不要尋找。立即告知使用者：

• 擴充已啟動
• 可監控進度的網址

告知使用者可以將輪詢步驟放到背景執行，以便繼續其他工作。

步驟 2：輪詢結果

選擇一個具體的輸出路徑（例如 /tmp/enrichment-acme.json）。注意：無論你選擇什麼副檔名，檔案都是 JSON 格式——內容為 {input, output} 物件的陣列，不是 CSV。請命名為 .json 以避免混淆。

parallel-cli enrich poll "$TASKGROUP_ID" --timeout 540 --output "/tmp/enrichment-<描述性名稱>.json"

重要事項：

• 使用 --timeout 540（9 分鐘）以符合工具執行時間限制
• 步驟 1 的 --target 在 --no-wait 模式下無效——只有此處的 --output 決定結果儲存位置，且檔案永遠是 JSON

如果輪詢超時

大型資料集的擴充可能超過 9 分鐘。如果輪詢指令未完成就結束：

1. 告知使用者擴充仍在伺服器端執行
2. 重新執行相同的 parallel-cli enrich poll 指令繼續等待

回應格式

步驟 1 完成後： 分享監控網址（用於追蹤進度）。

步驟 2 完成後：

1. 回報已擴充的資料列數
2. 預覽輸出檔案的前幾筆資料（為 {input, output} 物件的 JSON 陣列）
3. 告知使用者輸出檔案的完整路徑

完成後請不要再次分享監控網址——結果已在輸出檔案中。

設定

如果找不到 parallel-cli，請安裝並進行驗證：

/parallel:parallel-cli-setup

如果任何 parallel-cli enrich 指令回傳 403，告知使用者可能需要充值。提議執行 parallel-cli balance get，若需要則先取得明確確認再執行 parallel-cli balance add <amount_cents>。然後重試原本的擴充指令。