parallel-data-enrichment

数据补全

补全：$ARGUMENTS

开始前

告知用户，具体耗时取决于行数和请求补全的字段，可能需要几分钟。

可选：建议输出列

如果用户的需求比较模糊（例如“为这些公司补充有用信息”），而你不确定要添加哪些列，请先向 API 请求建议，再启动任务：

parallel-cli enrich suggest "Find CEO and recent funding info" --json

响应是一个信封对象：{title, processor, enriched_columns, warnings}。仅提取 enriched_columns 数组（不要提取整个信封对象），并在 enrich run 中将其作为 --enriched-columns 的值，替代 --intent。这两个标志是指定补全内容的不同方式。如果 suggest 返回了 processor，请在 run 调用中通过 --processor 显式传入。如果用户已指定所需字段，请跳过本节。

enrich suggest 要求 parallel-cli ≥ 0.3.0。如果仅缺少此命令，请跳过可选的建议步骤，并在第 1 步中使用 --intent。请参考 Setup 中针对具体安装方式的升级说明。不要将认证、API 或无效输入错误归类为 CLI 版本过旧。基于意图的运行本身会请求建议；显式指定列时默认使用 core-fast，而意图可选择其他处理器，除非 --processor 覆盖该选择。

第 1 步：开始数据补全

使用以下其中一种命令格式（替换为用户的实际数据）：

对于内联数据：

parallel-cli enrich run --data '[{"company": "Google"}, {"company": "Microsoft"}]' --intent "CEO name and founding year" --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": "Company name"}]' --intent "CEO name and founding year" --no-wait --json

如果这是先前研究任务的后续操作，且你有其 interaction_id，请添加上下文链：

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

这会复用先前任务的上下文。零数据保留（ZDR）账户无法使用上下文链，因此请勿添加该标志，并明确提供所需上下文。数据补全不会返回新的 interaction_id；请保留先前的任务 ID，以便后续跟进。taskgroup_id 或 Search/Extract session_id 都不是任务交互 ID。

**重要：**务必添加 --no-wait，让命令立即返回，而不是阻塞等待。

立即保存 --json 输出中的 taskgroup_id、url 和 num_runs。其中没有 interaction_id 字段。如果创建过程被中断或响应丢失，请先检查任务组是否已创建，再提交另一次运行。随后立即告知用户：

• 数据补全已启动
• 可用于跟踪进度的监控 URL

任务组在服务端运行；之后可使用已保存的 ID 恢复轮询。

第 2 步：轮询结果

选择一个持久且专用于本次运行的输出路径（例如 enrichment-acme-tgrp-<id>.json）。轮询会覆盖输出文件，因此请先检查是否已有文件；除非有意替换，否则请使用新路径。无论扩展名是什么，输出内容始终为 JSON：包含 input 和 output 或 error 的行数组。异步轮询不包含依据或逐行交互 ID；不要编造引用或上下文 ID。

parallel-cli enrich poll "$TASKGROUP_ID" --timeout 60 --output "enrichment-<descriptive-name>-<group-id>.json"

重要事项：

• 限制轮询时长；使用 --timeout 60，以便在等待间隔中更新进度。
• 在 --no-wait 模式下，第 1 步中的 --target 不会生效。只有此处的 --output 决定结果保存位置，且文件始终为 JSON。
• 已完成的任务组仍可能包含失败的行。请分别统计包含 output 的行和包含 error 的行，并将总数与 num_runs 比较；空文件或不完整文件不代表整个输入已成功补全。

如果轮询超时或被中断

超时退出码 5 或中断会结束本地等待。在称任务仍在运行前，请先检查任务组状态：

parallel-cli enrich status "$TASKGROUP_ID" --json

检查 is_active、status_counts 和 num_runs。如果任务组仍处于活动状态，请继续对同一任务组进行轮询；如果已停止活动，则获取结果并报告失败或尚未解决的行。不要因超时而重新创建任务组，也不要自动重新运行失败的行。如果本地文件写入失败，可以使用相同的任务组 ID 和可写的输出路径重试。

如果用户请求 CSV

在本地将保存的 JSON 转换为单独的 CSV。保留所有原始输入列和行，包括重复行和失败行；将丰富数据字段与名称冲突的输入字段分开，并为失败项添加错误列。不要假定流式返回的行与原始输入顺序一致，也不要在行身份不明确时猜测如何关联。验证行数，并保持输入 CSV 不变。这是本地转换，不是通过异步轮询生成的 CSV；报告 JSON 和 CSV 的路径。

响应格式

**步骤 1 后：**分享监控 URL（用于跟踪进度）。

步骤 2 后：

1. 报告成功、失败和总行数，并指出任何缺失结果。
2. 预览几行成功结果；如果有失败项，也提供一个有代表性的失败示例，不要声称所有行都成功。
3. 告知用户输出文件的完整路径

完成后，链接到已保存的输出文件，不要重复监控 URL。

设置

如果找不到 parallel-cli，请安装并完成身份验证：

/parallel:parallel-cli-setup

如果缺少文档中提到的选项或命令，请确认安装方式并通过该方式升级：独立安装使用 parallel-cli update；pipx 使用 pipx upgrade parallel-web-tools；uv 使用 uv tool upgrade parallel-web-tools；Homebrew 使用 brew upgrade parallel-web/tap/parallel-cli；npm 使用 npm update -g parallel-web-cli。重试前，请在 Agent 的终端中重新检查版本和帮助信息。

对于身份验证或 API 错误，请检查返回的消息。403 可能表示权限、账户政策或计费问题；这并不能证明余额不足。相关时，请检查 parallel-cli auth --json 及其 authenticated 布尔值，但不要泄露凭据。只有明确与计费相关的错误才需要检查余额；添加资金需要明确确认。重用已保存的组 ID；不要自动重试结果不明确的创建操作。