aiq-research

AIQ Research Skill

用途

使用此 Skill 透過 scripts/aiq.py 輔助指令碼來呼叫本機運行的 NVIDIA AI-Q Blueprint 伺服器。

當收到研究類型的需求時請使用此 Skill，包括：

• "deep research on ..."（針對……進行深度研究）
• "AIQ research ..."（AIQ 研究……）
• "research ..."（研究……）
• "use AI-Q to answer ..."（使用 AI-Q 回答……）
• "ask AI-Q about ..."（詢問 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 金鑰。

此輔助指令碼不依賴任何第三方 Python 套件，僅使用 Python 標準庫的 HTTP 模組。

執行說明

1. 確定目標後端 URL。
2. 傳送研究請求前先執行 health 檢查。
3. 若無法連線至任何後端，請詢問後端 URL 或轉交給 aiq-deploy。
4. 傳送任何使用者查詢前，明確說明將接收查詢的 AI-Q 後端 URL。若為非本機 URL，僅在使用者的當前對話中明確確認信任該 URL 後才可繼續執行。
5. 當 AI-Q 回傳 Job ID 時，輪詢非同步深度研究任務。
6. 展示回傳的報告，並完整保留引用出處與來源 URL。
7. 若任務失敗請停止執行並顯示回傳的錯誤訊息，切勿自動重試。
8. 展示報告後，支援後續操作：解答針對報告的提問（ask），或使用相同命令執行進一步的精細研究（redo）。

步驟 1 - 確定後端 URL

若有設定 AIQ_SERVER_URL 則直接使用，否則嘗試預設的本機後端：

python3 $SKILL_DIR/scripts/aiq.py health

預期輸出：來自可連線 AI-Q health 端點的 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，請停止執行並解釋此公開 Skill 不管理身份驗證。請使用者使用支援身份驗證的 AI-Q Skill，或為其環境設定身份驗證。
• 若 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 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 檢查任務狀態及儲存的產物。當任務已經完成且僅需要最終輸出時使用 report。使用 research_poll 繼續等待任務完成。

最終報告可能會以 artifact://<id> 連結的形式引用生成的產物（圖表、CSV 等）。若要將其實體化為本機檔案，請執行 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 的 Job 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（例如：使用 deep 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（次版本號必須大於或等於）
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；可能回傳即時內容或深度研究的 Job 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 金鑰、Bearer Token、Cookie 或基本驗證憑證。
• 後端憑證應儲存於 AI-Q 部署環境中，而非此 Skill 或命令範例內。
• 使用者的查詢內文會傳送至所設定的 AIQ_SERVER_URL。傳送敏感或機密資訊前，請務必確認該端點值得信任。
• 若後端使用私有資料源，請將回傳的報告視為潛在敏感資訊處理。
• 請勿截斷回傳報告中的引用出處或來源 URL。

限制

• 此 Skill 需要已在運行的 AI-Q 後端；它本身不負責部署後端。
• 此公開輔助工具不管理身份驗證 Token。