parallel-deep-research

深度研究

研究主题：$ARGUMENTS

文本输出和上下文串联需要 parallel-cli ≥ 0.3.0。如果缺少已记录的命令或选项，请检查 parallel-cli --version 和该命令的 --help，然后按照 Setup 中针对安装方式的升级指南操作。API、身份验证和输入错误并不能证明 CLI 版本较旧。

何时使用（而非 parallel-web-search）

仅当用户明确要求进行深度／全面研究时，才使用此技能。根据处理器和任务，这可能需要几分钟，成本也高于快速搜索。对于常规的“研究 X”请求、快速查询或事实核查，请改用 parallel-web-search。

第 1 步：开始研究

在持久目录中选择一个描述性输出基名（例如 reports/ai-chip-market-2026）。将返回的运行 ID 加入其中以确保唯一，然后在第 2 步中使用此基名作为 -o "$FILENAME"。保存前检查是否已有 .json 和 .md 文件。

parallel-cli research run "$ARGUMENTS" --processor pro-fast --text --no-wait --json

--text 标志会告知 API 在任务完成时返回 Markdown 报告（含行内引用），而不是默认的结构化 JSON。对于叙述式／报告式请求（大多数用户所说的“深度研究”都属于此类），请使用该标志。如果用户明确要求结构化 JSON 输出，则省略 --text。

使用 --text 时可选：传入 --text-description "Keep under 1500 words, focus on M&A activity"，以调整篇幅、格式或重点。

如果这是后续请求，且你有之前任务返回的 interaction_id，请添加上下文串联。Enrichment 的 taskgroup_id 和 Search／Extract 的 session_id 都不是 Task 的交互 ID。异步 enrichment 不会返回新的交互 ID；请保留之前的 Task ID。Zero Data Retention（ZDR）账户不支持上下文串联，因此请省略该功能，并明确提供所需上下文。

parallel-cli research run "$ARGUMENTS" --processor lite-fast --text --no-wait --json --previous-interaction-id "$INTERACTION_ID"

这会复用之前 Task 的上下文。对于重点明确的后续请求，可以使用较轻量的处理器（lite-fast 或 base-fast）；应根据新问题的深度选择，而不要假设所有后续请求都很简单。

始终使用 --no-wait，将任务创建与有时限的轮询分开。立即保存返回的 ID。如果创建过程被中断或响应丢失，在确认第一个任务是否已创建之前，不要提交替代任务。

探索性研究默认使用 pro-fast。运行 parallel-cli research processors，查看已安装 CLI 的处理器列表和延迟估算值；这些数值并非截止时间。只有在用户明确要求且不超出其批准的预算时，才选择 ultra 等级。请查看当前定价，不要引用固定的成本倍数。

解析 JSON 输出，保存 run_id、interaction_id 和 result_url。立即告知用户：

• 深度研究已启动
• 所选处理器的预计延迟（如有）
• 可用于跟踪进度的监控网址

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

步骤 2：轮询结果

parallel-cli research poll "$RUN_ID" -o "$FILENAME" --timeout 60

重要提示：

• 每次轮询都应设置时限；--timeout 60 可在等待期间提供进度更新。
• 轮询大型报告时避免使用 --json。-o 标志会将完整结果保存到文件。
• 使用 -o "$FILENAME" 时：
  • 始终会写入 $FILENAME.json（元数据 + 依据）
  • 仅当返回文本输出时才会写入 $FILENAME.md，通常通过 --text 请求文本输出；自动架构结果可以仅保存为 JSON。
  • 对于文本输出，JSON 会将 output.content_file 设为相对于已保存 JSON 文件的路径，而不是重复包含报告正文。
• 如果输出中有执行摘要，请分享该摘要。某些成功的输出没有摘要；不要臆造摘要，也不要将缺少摘要视为失败。
• 如果输出文件已存在，除非明确指定 --force，否则不会覆盖。优先使用新的文件名；仅在确实需要覆盖这些文件时才使用 --force。
• 请读取实际打印出的路径。写入出错时，CLI 可能会退回到系统临时目录，且写入内容可能不完整。重试前请检查这两个位置。将最终报告从临时存储复制到预期的持久存储位置后，再告知用户文件已持久保存。

如果轮询超时或中断

退出码 5 表示超时；中断也只会结束本地等待，不一定代表服务端任务已结束。检查已保存的任务：

parallel-cli research status "$RUN_ID" --json

仅当任务处于待处理或运行中状态时，才继续轮询同一任务；对于已完成的任务，获取其输出；对于失败、取消或 action_required 状态，准确报告状态。CLI 的轮询循环可能无法识别 action_required，因此不要无限轮询该状态。切勿仅因本地等待结束就重新创建任务。

回复格式

步骤 1 之后： 分享用于跟踪进度的监控 URL。

步骤 2 之后：

1. 如果输出中有执行摘要，请分享该摘要；否则说明结果已保存，并仅在需要时根据已检查的输出提供简要摘要。
2. 告知用户生成的文件路径：
   • 实际的 .md 路径（如果存在文本报告）
   • 实际的 .json 路径，其中包含元数据和依据（以及 JSON 输出的结构化内容）
3. 分享 interaction_id，并告知用户可以提出基于此研究的后续问题（例如“深入探讨 X”或“将其与 Y 进行比较”）。

任务完成后，请链接已保存的文件，而不要重复分享监控 URL。

避免将整份报告加载到上下文中。回答摘要或后续问题时，只阅读相关部分，并引用返回的来源。

请记住 interaction_id： 如果账户支持上下文串联，可在相关研究或补充信息的后续请求中使用它。

设置

如果找不到 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；对于结果不明确的创建操作，不要自动重试。