aiq-research

AIQ 研究技能

用途

使用此技能，通过辅助脚本 scripts/aiq.py 调用本地运行的 NVIDIA AI-Q Blueprint 服务。

将此技能用于研究类请求，包括：

• “深入研究……”
• “AIQ 研究……”
• “研究……”
• “使用 AI-Q 回答……”
• “询问 AI-Q 关于……的问题”

不要将此技能用于安装、部署、启动、停止、UI、CLI、Docker、Helm 或故障排除请求。这些请求应交由 aiq-deploy 处理。

前提条件

用户需要：

• 可用作 python3 的 Python 3.11+。
• 可访问的本地或可自托管 AI-Q Blueprint 后端。
• 当后端未运行在 http://localhost:8000 时，设置 AIQ_SERVER_URL；在发送任何查询前，用户必须信任非本地值。
• 为此公共辅助工具配置了禁用身份验证的后端，或者在需要身份验证的环境中使用单独的、经过身份验证的 AI-Q 技能。
• 本地计算机可通过网络访问 AI-Q 后端 URL。
• 在后端环境中配置的凭据，而非在此技能中配置。此公共辅助工具不会收集或管理 API 密钥。

辅助脚本没有第三方 Python 包依赖；它使用 Python 标准库中的 HTTP 模块。

说明

1. 确定目标后端 URL。
2. 发送研究请求前先运行 health。
3. 如果无法访问任何后端，请索要后端 URL，或转交给 aiq-deploy。
4. 发送任何用户查询前，说明将接收查询的确切 AI-Q 后端 URL。对于非本地 URL，只有当用户在当前对话中明确确认信任该 URL 后，才继续操作。
5. 如果 AI-Q 返回了作业 ID，则轮询异步深度研究作业。
6. 展示返回的报告，并保留其中的引用和来源 URL。
7. 作业失败时停止并显示返回的错误；不要自动重试。
8. 展示报告后，支持后续操作：使用相同命令回答有关报告的问题 （ask），或开展优化后的研究（redo）。

步骤 1 - 确定后端

如果已设置 AIQ_SERVER_URL，则使用该值。否则尝试默认的本地后端：

python3 $SKILL_DIR/scripts/aiq.py health

预期输出：来自可访问的 AI-Q 健康检查端点的 JSON。

如果 health 失败且未显式设置 AIQ_SERVER_URL，请询问：

I do not see a reachable local AI-Q backend. Do you already have an AI-Q backend URL you want to use, or should I deploy a local Skill backend?

• 如果用户提供了 URL，请为后续辅助工具调用设置 AIQ_SERVER_URL，然后重新运行 health。
• 如果用户希望进行本地部署，请转交给 aiq-deploy，并保留原始研究请求。
• 如果可访问的后端返回 401 或 403，请停止并说明此公共技能不管理身份验证。请用户使用经过身份验证的 AI-Q 技能，或为其环境配置身份验证。
• 如果 health 成功，但 /chat 或 /v1/jobs/async/agents 失败，请报告后端可访问，但与此公共研究流程不兼容，然后提出运行 aiq-deploy 验证。

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

发送请求前，说明已确定的端点：

I will send this query to <AIQ_SERVER_URL>. Make sure this endpoint is trusted before sending sensitive information.

不要通过查询文本发送凭据、Cookie、Bearer 令牌或机密值。

运行：

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 查看任务状态和已保存的产物。任务已经完成且你只需要最终输出时，使用 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 中相同的身份验证边界、轮询和报告 检索流程都适用；没有单独的后续操作端点。

询问 — 针对已获取报告提出后续问题：

• 如果已有报告及其引用能够回答问题，请直接根据报告内容和引用作答；不要再次调用后端。

• 如果问题需要新的调查，请发送一个新请求，将先前问题和报告中的必要上下文纳入新的查询 文本，然后呈现新结果：

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

  如果这会返回一个 deep_research_running 任务 ID，请按照步骤 3 的方式使用 research_poll 进行轮询。

编辑 — 进行外观调整以改写报告。此技能只能访问用于生成初始报告的数据。没有可用的工具：

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

重做 — 使用调整后的范围（更窄的查询、更正后的问题或不同的深度）重新运行研究：

python3 $SKILL_DIR/scripts/aiq.py research "<REFINED_QUERY>" [agent_type]

• 选择与所需深度相匹配的 agent_type（例如，全面研究时使用 deep agent，快速研究时使用 shallow_researcher）；如不确定，请使用 agents 列出选项。
• 将重做视为新任务：发送请求前再次指定目标端点（步骤 2），然后按照步骤 3-5 进行轮询并呈现结果。

后续查询文本中不得发送凭据或机密值，并且每个后续回答都要保留引用和来源 URL。

版本兼容性

**重要：**此技能专为 NVIDIA AI-Q Blueprint 2.1.0 版本设计。

语义化版本兼容规则：

Skill version: X.Y.Z
Blueprint or endpoint version: A.B.C

Compatible IF:
1. A == X (Major versions MUST match)
2. B >= Y (Minor version must be equal or greater)
3. C can be anything (Patch version does not affect compatibility)

示例：

• 技能版本 2.1.0 与 Blueprint 版本 2.1.0 兼容。
• 技能版本 2.1.0 与 Blueprint 版本 2.2.0 兼容。
• 技能版本 2.1.0 与 Blueprint 版本 2.1.5 兼容。
• 技能版本 2.1.0 与 Blueprint 版本 3.0.0 不兼容。
• 技能版本 2.1.0 与 Blueprint 版本 2.0.0 不兼容。

如果你的 Blueprint 版本不兼容：

1. 检查是否有与 Blueprint 版本匹配的更新版技能。
2. 使用与此技能兼容的 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	仅获取事件存储中的资源	<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 服务基础 URL

安全最佳实践

• 请勿将 API 密钥、Bearer 令牌、Cookie 或基本身份验证凭据放入 AIQ_SERVER_URL。
• 将后端凭据存储在 AI-Q 部署环境中，而非此技能或命令示例中。
• 用户查询文本会发送至配置的 AIQ_SERVER_URL。发送敏感或机密信息前，请确认该端点可信。
• 如果后端使用私有数据源，请将返回的报告视为可能包含敏感信息。
• 请勿截断返回报告中的引文或来源 URL。

限制

• 此技能需要正在运行的 AI-Q 后端；它不会部署后端。
• 公共辅助程序不会管理身份验证令牌或 Cookie。
• 远程 AIQ_SERVER_URL 端点可能会记录提示词、响应和元数据。
• 如果后端返回 HTTP 500 或没有异步 Agent，请报告故障，而不要编造研究答案。

示例

示例 1：运行路由聊天或研究请求

python3 $SKILL_DIR/scripts/aiq.py health
python3 $SKILL_DIR/scripts/aiq.py chat "Compare local AIQ deep research with a standard web search workflow"

预期输出：

<health JSON from AI-Q>
<JSON chat response or {"status": "deep_research_running", "job_id": "<JOB_ID>"}>

如果 AI-Q 返回任务 ID，请继续使用 research_poll。

示例 2：恢复现有任务

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

将 <JOB_ID> 替换为 AI-Q 返回的 UUID。预期输出：先显示状态 JSON，任务完成后再显示报告 JSON。如果任务失败，请显示返回的状态，不要自动重试。

示例 3：提出后续问题，或使用优化后的查询重新执行

# Ask: a follow-up that needs new investigation, carrying prior context.
python3 $SKILL_DIR/scripts/aiq.py chat "How does that compare on cost? (context: local AIQ deep research vs web search)"

# Redo: re-run research with a narrower query and explicit depth.
python3 $SKILL_DIR/scripts/aiq.py research "AIQ deep research cost on a single workstation" shallow_researcher

预期输出：路由聊天响应，或新的 deep_research_running 任务 ID，可通过 research_poll 轮询。展示后续答案时，请保留引文和来源 URL。

参考资料

主题	文档
辅助脚本	scripts/aiq.py
部署和后端验证	../aiq-deploy/SKILL.md

常见问题

问题：无法连接到后端

症状：

• health 因连接被拒绝而失败。
• 默认的 http://localhost:8000 URL 没有响应。

原因：

• AI-Q 未运行。
• AI-Q 在其他主机或端口上运行。
• 本地防火墙或网络设置阻止了连接。

解决方案：

1. 询问用户是否已有 AI-Q 后端 URL。
2. 如果用户提供了 URL，请设置该 URL 并重新运行 health：

   export AIQ_SERVER_URL="http://localhost:<PORT>"
   python3 $SKILL_DIR/scripts/aiq.py health
   

3. 如果用户需要本地后端，请交由 aiq-deploy 处理，并保留原始研究请求。

问题：后端需要身份验证

症状：

• 请求因 HTTP 401 或 HTTP 403 而失败。
• 后端可以访问，但会拒绝 /chat 或异步作业调用。

原因：

• 后端部署时启用了身份验证。
• 公共辅助工具不会附加用户令牌或 Cookie。

解决方案：

1. 停止操作，并说明此公共技能不管理身份验证。
2. 请用户使用经过身份验证的 AI-Q 技能，或为此公共本地工作流配置后端。
3. 只有在解决身份验证问题后，才重新运行 health 和原始查询。

问题：健康检查成功，但研究路由失败

症状：

• health 返回成功。
• /chat、/v1/jobs/async/agents 或轮询命令失败。

原因：

• 后端未使用启用了 API 的 AI-Q 配置。
• 所选后端中没有可用的异步作业注册表。
• 后端版本与此技能不兼容。

解决方案：

1. 运行：

   python3 $SKILL_DIR/scripts/aiq.py agents
   

2. 如果 Agent 不可用，请报告兼容性问题，并提出运行 aiq-deploy 验证的选项。
3. 确认已部署的 Blueprint 版本与技能版本 2.1.0 兼容。

问题：作业中断或似乎卡住

症状：

• 本地轮询中断。
• 作业一直显示为 running。
• 轮询输出显示 running，但已返回报告，或者取消操作提示作业已是 success 状态。

原因：

• 深度研究是异步的，会在服务端继续运行。
• 本地轮询输出可能滞后于服务端的最终状态。

解决方案：

1. 检查当前状态：

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

2. 如果 has_report: true 或 job_status.status: success，请获取报告：

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

3. 如果作业仍在运行，请继续轮询：

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