AI Skills
aiq-research

aiq-research

热门

当需要通过可访问的 NVIDIA AI-Q Blueprint 后端执行深度调研（deep research）或 AI-Q 调研任务时使用此 Skill。

2750Star
320Fork
更新于 2026/8/1
获取 Skill源代码

相关 Skills

agent-reviewer7.1万planning-with-files4.7万planning-and-task-breakdown7.7万
SKILL.md
只读
名称
aiq-research
描述

当需要通过可访问的 NVIDIA AI-Q Blueprint 后端执行深度调研（deep research）或 AI-Q 调研任务时使用此 Skill。

AIQ Research Skill

技能用途

使用此 Skill，可以通过位于 scripts/aiq.py 的辅助脚本调用本地运行的 NVIDIA AI-Q Blueprint 服务器。

适用于处理调研类的请求，包括：

  • “针对……做深度调研”
  • “AIQ 调研……”
  • “调研/研究……”
  • “用 AI-Q 回答……”
  • “向 AI-Q 询问关于……的内容”

请勿将此 Skill 用于安装、部署、启动、停止、UI、CLI、Docker、Helm 或排障等请求，此类需求请使用 aiq-deploy。

前提条件

用户需具备以下条件：

  • 可通过 python3 命令调用的 Python 3.11+ 环境。
  • 一个可访问的本地或自托管 AI-Q Blueprint 后端。
  • 当后端未运行在 http://localhost:8000 时，需设置 AIQ_SERVER_URL；在发送任何查询之前，非本地 URL 必须先经用户确认信任。
  • 后端需针对此公共辅助脚本配置为禁用身份验证；若处于带鉴权的环境中，请使用专门的带鉴权 AI-Q Skill。
  • 本地机器到 AI-Q 后端 URL 的网络连通性。
  • 凭据需在后端环境中配置，而非在此 Skill 中配置。本公共辅助脚本不会收集或管理 API Key。

该辅助脚本没有任何第三方 Python 包依赖，直接使用 Python 标准库中的 HTTP 模块。

操作指南

  1. 解析目标后端 URL。
  2. 在发送调研请求之前，先运行 health 进行健康检查。
  3. 如果没有任何可访问的后端，向用户询问后端 URL，或转交给 aiq-deploy 处理。
  4. 在发送任何用户查询之前，明确说明接收请求的 AI-Q 后端 URL。对于非本地 URL，只有当用户在当前对话中明确确认信任该 URL 后方可继续。
  5. 当 AI-Q 返回任务 ID（job ID）时，轮询异步深度调研任务的状态。
  6. 展示返回的报告，并保持引用（citations）和来源 URL 完整无损。
  7. 任务失败时停止执行并展示返回的错误信息，不要自动重试。
  8. 报告展示完成后，支持后续跟进：通过相同命令回答针对报告的问题（ask），或执行更精细的重新调研（redo）。

步骤 1 - 解析后端

若已设置 AIQ_SERVER_URL，则直接使用；否则尝试默认的本地后端：

python3 $SKILL_DIR/scripts/aiq.py health

预期输出：可访问的 AI-Q 健康检查端点返回的 JSON 数据。

如果 health 检查失败且未明确设置 AIQ_SERVER_URL，请提示用户：

未检测到可访问的本地 AI-Q 后端。您是否有想要使用的 AI-Q 后端 URL？或者需要我部署一个本地 Skill 后端？
  • 若用户提供了 URL，请为后续辅助脚本调用设置 AIQ_SERVER_URL 并重新运行 health。
  • 若用户需要本地部署，转交给 aiq-deploy 并保留原始的调研请求。
  • 若可访问的后端返回 401 或 403，停止运行并解释本公共 Skill 不管理身份验证。请用户使用带鉴权功能的 AI-Q Skill，或为其环境配置鉴权。
  • 若 health 成功但 /chat 或 /v1/jobs/async/agents 失败，汇报后端虽可访问但与此公共调研流程不兼容，然后建议运行 aiq-deploy 校验。

步骤 2 - 发送路由后的调研请求

在发送请求之前，说明解析出的端点：

将把此查询发送至 <AIQ_SERVER_URL>。在发送敏感信息之前，请确保该端点可信。

请勿通过查询文本发送凭据、Cookie、Bearer Token 或任何敏感密钥。

运行：

python3 $SKILL_DIR/scripts/aiq.py chat "<USER_QUESTION>"

预期输出：

  • 浅层回答或直接解答时，返回普通的 JSON 响应。
  • 对于异步深度调研，返回包含 {"status": "deep_research_running", "job_id": "<JOB_ID>"} 的结构化 JSON。

如果响应为普通 JSON，立即展示结果。在没有 job_id 的情况下无需强制轮询。

步骤 3 - 轮询异步任务

如果响应中包含 deep_research_running，提取出 job_id 并使用相同的脚本绝对路径进行轮询：

python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

预期输出：任务成功完成时的最终报告 JSON。

如果运行时支持非阻塞或后台执行机制，请优先使用。若所选执行方式需要提升权限，需先向用户说明原因并取得明确授权。同时告知用户深度调研正在后台运行中。

步骤 4 - 中断后恢复

如果轮询中断，任务会在服务端继续运行。可通过以下命令恢复：

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

使用 status 查看任务状态和已保存的产物（artifacts）。当任务已完成且只需最终输出时，使用 report。使用 research_poll 继续等待任务完成。

最终报告可能会将生成的产物（图表、CSV 等）引用为 artifact://<id> 格式的链接。若要将其落地为本地文件，可运行 python3 $SKILL_DIR/scripts/aiq.py artifacts <JOB_ID> --download-dir ./aiq-artifacts；该命令会下载各个产物并输出本地路径。请注意，报告本身不会直接包含 base64 编码的图片数据。

若要生成自包含且易于分享的报告，可运行 python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID> --out-dir ./my-report。它会生成 report.md 以及 artifacts/ 目录，并将每个 artifact://<id> 链接重写为对应的本地文件路径。这样一来，无需运行后端，报告（包含所有图表）即可在任意 Markdown 查看器中渲染展示。

步骤 5 - 展示报告

当 research_poll 成功完成时，获取并展示完整的报告。务必保持引用和来源 URL 完整无损。
如果任务状态为 failed、failure 或 cancelled，显示状态响应中的错误信息，并询问用户是否希望缩小查询范围或更换方法重试。

步骤 6 - 后续跟进：提问、修改或重做报告

报告展示完成后，用户通常希望深入探讨或调整范围。
直接复用现有的后端流程——步骤 1 至 5 中的鉴权边界、轮询和报告获取逻辑同样适用；无需调用单独的跟进端点。

Ask（追问）——针对已有报告提出后续问题：

  • 对于可根据已掌握报告直接解答的问题，直接利用其中的内容和引用回答，无需再次调用后端。

  • 对于需要重新调查的问题，发送一个新请求，将先前问题和报告中的必要上下文带入新的查询文本中，然后展示新结果：

    python3 $SKILL_DIR/scripts/aiq.py chat "<FOLLOW_UP_QUESTION> (context: <PRIOR_TOPIC>)"

    如果该请求返回了 deep_research_running 的任务 ID，严格按照步骤 3 使用 research_poll 进行轮询。

Edit（修改）——对报告进行润色或格式调整。此 Skill 仅能访问生成初始报告时的数据，无法使用额外工具：

python3 $SKILL_DIR/scripts/aiq.py report_edit <JOB_ID> "<EDIT_INSTRUCTIONS>"

Redo（重做）——调整范围后重新执行调研（缩小查询范围、修正问题或更改研究深度）：

python3 $SKILL_DIR/scripts/aiq.py research "<REFINED_QUERY>" [agent_type]
  • 根据所需深度选择 agent_type（例如选择深度 Agent 进行全面分析，或选择 shallow_researcher 进行快速调研）；若不确定可用选项，使用 agents 命令列出。
  • 将重做视为新任务：在发送前再次说明目标端点（步骤 2），然后按照步骤 3 至 5 进行轮询与展示。

请勿在后续查询文本中发送凭据或密钥信息，并在每次跟进回答中保持引用和来源 URL 完整。

版本兼容性

重要提示： 本 Skill 专为 NVIDIA AI-Q Blueprint 2.1.0 版本设计。

语义化版本（Semantic Versioning）兼容性规则：

Skill 版本: X.Y.Z
Blueprint 或端点版本: A.B.C

满足以下条件即兼容：
1. A == X (主版本号必须一致)
2. B >= Y (次版本号必须大于或等于 Skill 的次版本号)
3. C 可以为任意值 (修订号不影响兼容性)

示例：

  • Skill 版本 2.1.0 兼容 Blueprint 版本 2.1.0。
  • Skill 版本 2.1.0 兼容 Blueprint 版本 2.2.0。
  • Skill 版本 2.1.0 兼容 Blueprint 版本 2.1.5。
  • Skill 版本 2.1.0 不兼容 Blueprint 版本 3.0.0。
  • Skill 版本 2.1.0 不兼容 Blueprint 版本 2.0.0。

若您的 Blueprint 版本不兼容：

  1. 检查是否有与您的 Blueprint 版本相匹配的最新 Skill 版本。
  2. 使用与本 Skill 兼容的 Blueprint 版本。
  3. 仅在用户明确接受兼容性风险的情况下谨慎继续；因为 API 路由或响应数据结构可能已发生改变。

可用脚本

脚本 用途 参数
scripts/aiq.py health 检查配置的服务器是否正常响应 无
scripts/aiq.py chat POST /chat；可能返回内联输出或深度调研任务 ID <query>
scripts/aiq.py agents 列出可用的异步 Agent 类型 无
scripts/aiq.py submit 提交一个显式异步任务 <query> [agent_type]
scripts/aiq.py research 提交异步任务、进行轮询并打印最终报告 JSON <query> [agent_type]
scripts/aiq.py research_poll 恢复对已有异步任务的轮询 <job_id>
scripts/aiq.py status 获取任务状态及 /state 产物 <job_id>
scripts/aiq.py state 仅获取事件存储（event-store）产物 <job_id>
scripts/aiq.py report 获取最终报告；配合 --out-dir DIR 可导出包含本地文件链接重写的便携式 report.md + artifacts/ 目录 <job_id> [--out-dir DIR]
scripts/aiq.py report_edit 对已完成的报告进行外观润色与修改 <job_id> <edit_instructions>
scripts/aiq.py artifacts 列出持久化产物；配合 --download-dir DIR 可下载产物并打印本地路径 <job_id> [--download-dir DIR]
scripts/aiq.py stream 实时流式接收任务的 SSE 事件 <job_id>
scripts/aiq.py cancel 取消正在运行的任务 <job_id>

当宿主环境支持 run_script() 辅助函数时，通过 scripts/aiq.py 及上述参数进行调用。否则，运行等效的 Shell 命令，例如 python3 $SKILL_DIR/scripts/aiq.py health。

环境变量

变量名 是否必填 默认值 描述
AIQ_SERVER_URL 否 http://localhost:8000 本地或自托管 AI-Q 服务器的 Base URL

安全最佳实践

  • 请勿在 AIQ_SERVER_URL 中填入 API Key、Bearer Token、Cookie 或 HTTP 基本身份验证（Basic-Auth）凭据。
  • 请将后端凭据存储在 AI-Q 部署环境中，而不是存放在本 Skill 或命令示例中。
  • 用户的查询文本会被发送至配置的 AIQ_SERVER_URL。在发送敏感或机密信息之前，请确认该端点是否可信。
  • 若后端使用了私有数据源，请将返回的报告视为潜在敏感数据。
  • 请勿截断或删减返回报告中的引用信息或来源 URL。

局限性与限制

  • 本 Skill 要求已有正在运行的 AI-Q 后端；Skill 本身不负责部署后端。
  • 此公共辅助脚本不负责管理身份验证 Token。