ToolUniverse 教學文件：用 1000+ 科學工具打造 AI 科學家

Repository: mims-harvard/ToolUniverse Stars: 1554 · Forks: 235 · License: Apache-2.0 · Language: Python 論文: Democratizing AI Scientists using ToolUniverse (arXiv:2509.23426, 2025) 官網: https://aiscientist.tools · 文件: https://zitniklab.hms.harvard.edu/ToolUniverse/

目錄

1. 專案概述
2. 核心架構
3. 安裝與設定
4. 基本使用
5. 進階功能與應用場景
6. AIKT 整合分析與策略
7. 效能、限制與替代方案
8. 總結與建議

1. 專案概述 (Project Overview)

1.1 一句話說明

ToolUniverse 是由哈佛醫學院 Marinka Zitnik 實驗室（Zitnik Lab, MIMS — Machine Intelligence for Manufacturing and Science）打造的一個「科學工具超市」：它把 1000 多個機器學習模型 (machine learning model; 機器學習模型)、資料庫 API、以及科學計算套件，全部包裝成統一格式的「工具 (tool; 工具)」，讓任何大型語言模型 (large language model; LLM; 大型語言模型) 都能像使用手機 App 一樣，直接呼叫這些科學能力。

1.2 用比喻理解這個專案在解決什麼問題

想像你是一位藥物研發人員，桌上攤開了 20 個瀏覽器分頁：PubChem 查化合物結構、ChEMBL 查生物活性、ClinicalTrials.gov 查臨床試驗、FDA FAERS 查不良反應報告、UniProt 查蛋白質序列、AlphaFold 查結構預測……每個網站介面不同、查詢語法不同、回傳格式不同。你要花大量時間「翻譯」自己的問題成每個資料庫看得懂的查詢語言，再把結果手動拼裝成一份完整報告。

ToolUniverse 做的事情，很像機場的「萬國轉接頭 (universal adapter; 萬國轉接頭)」——你不需要為每個國家（資料庫）帶不同插頭，轉接頭統一介面之後，插上就能用。對 AI 而言，ToolUniverse 就是這個轉接頭：它把 UniProt、ChEMBL、FDA、ClinicalTrials.gov、AlphaFold 等上千個「插座」全部轉換成同一種「插頭」——AI-Tool Interaction Protocol (AI-工具互動協議)。LLM 只需要學會這一種協議，就能操作所有工具，不用為每個資料庫寫一次專屬的 API 整合程式碼。

再換一個比喻：傳統做法是每個 AI 助理都要自己「學一次」怎麼查 PubMed、怎麼查 ChEMBL、怎麼跑 AlphaFold——像每個新員工都要重新自己摸索公司內部 20 套不同系統怎麼操作。ToolUniverse 相當於幫全公司建了一套「統一 SSO 入口 + 標準化操作手冊」，任何新員工（任何 LLM）上線第一天就能直接用同一套邏輯操作所有系統，不用重新學習。

1.3 解決的核心問題

科學研究的知識散落在數千個異質資料來源中，每個來源有自己的：

• API 格式（REST、GraphQL、SOAP、檔案下載）
• 認證機制（API Key、OAuth、免費開放）
• 資料結構（JSON、XML、FASTA、PDB、CSV）
• 查詢語言（各自的參數命名慣例）

在 LLM 興起之前，這種碎片化問題靠「人類專家」硬記與手動整合來彌補。LLM 出現後，理論上 AI 可以自動查詢科學資料庫、設計實驗、驗證假說，達成「AI 科學家 (AI scientist; AI 科學家)」的願景——但現實中每接一個新資料庫，工程師都要手寫一次整合程式碼（parsing、錯誤處理、rate limit 管理），這個「整合稅」讓 AI 科學家系統的開發速度遠遠跟不上科學資料庫的增長速度。

ToolUniverse 用「標準化協議 + 開放貢獻機制」來解決這個問題：任何人都能用固定的 JSON schema 描述一個新工具，加進 ToolUniverse 的工具庫，所有下游的 AI 助理立刻就能用上這個新工具，不需要重新部署或修改 Agent 邏輯。

1.4 在生物醫學 AI 領域的重要性與地位

ToolUniverse 目前串接的工具已超過 2200 個（官方文件標示「1000+」為對外行銷數字，實際本地資料檔案盤點約 2201 個工具、跨 520 個工具定義檔），涵蓋範圍極廣：

• 藥物與化學：PubChem、ChEMBL、BindingDB、DrugBank 風格資料、ADMET 預測 (ADMET; 吸收/分布/代謝/排除/毒性)
• 基因體與蛋白質：UniProt、NCBI Gene、Ensembl、AlphaFold、AlphaMissense、AlphaGenome
• 臨床與法規：ClinicalTrials.gov、FDA FAERS (不良反應報告系統)、OMIM、ClinVar
• 文獻與知識：PubMed、bioRxiv、medRxiv、arXiv、Europe PMC、Semantic Scholar
• 單細胞與空間體學：CELLxGene Census、CellMarker
• 結構生物學：RCSB PDB、AlphaFold、ClusPro（蛋白質對接）
• AI 推理輔助工具：23 個 Agentic Tools（例如 HypothesisGenerator、ExperimentalDesignScorer），本身即是呼叫 LLM 的「工具化 Agent」

這個規模讓 ToolUniverse 在「Scientific AI Agents (科學 AI 代理人)」這個新興分類中，成為目前生態系最完整、社群動能最強的基礎設施型專案之一（1554 星、235 分支、活躍發布節奏）。它不是單一功能的工具，而是「工具的工具」——是其他 AI 科學家系統的地基層。

1.5 相關發表論文與引用

主論文：

1Gao, S., Zhu, R., Sui, P., Kong, Z., Aldogom, S., Huang, Y., Noori, A.,
2Shamji, R., Parvataneni, K., Tsiligkaridis, T., Zitnik, M. (2025).
3Democratizing AI Scientists using ToolUniverse.
4arXiv:2509.23426 [cs.AI]

衍生 / 相關專案（同一實驗室生態系，直接建立在 ToolUniverse 之上）：

• TxAgent（論文，GitHub）：治療推理 AI 代理人 (therapeutic reasoning agent; 治療推理代理人)，利用 ToolUniverse 的工具生態系解決複雜的用藥決策問題，是 ToolUniverse 概念最早的落地驗證。
• Medea（論文，GitHub）：多體學 AI 代理人 (omics AI agent; 體學 AI 代理人)，整合 ToolUniverse 工具做跨癌症/自體免疫疾病的治療靶點識別與藥物反應預測。

1.6 在 mims-harvard 實驗室生態系中的角色

Zitnik Lab 的研究主軸是「用圖神經網路與基礎模型解決精準醫療問題」，過去累積了大量針對特定任務的模型（如藥物交互作用預測、疾病網路分析）。ToolUniverse 的角色是把這些「單點模型」升級成「可被 LLM 呼叫的通用工具」——它是實驗室從「發論文型模型」轉向「可組合系統型基礎設施」的關鍵一步。TxAgent 與 Medea 兩個下游專案，證明了 ToolUniverse 不是自我封閉的展示品，而是被實際重複使用的共享基礎設施。

1.7 專案定位圖

flowchart TB
    subgraph SG_DATA["原始科學資料來源層"]
        DB1["PubMed / bioRxiv
文獻資料庫"]
        DB2["UniProt / AlphaFold
蛋白質資料庫"]
        DB3["ChEMBL / PubChem
化學資料庫"]
        DB4["ClinicalTrials.gov / FAERS
臨床法規資料庫"]
        DB5["CELLxGene / GEO
體學資料庫"]
    end

    subgraph SG_TU["ToolUniverse 工具標準化層"]
        PROTO["AI_Tool_Protocol
統一互動協議"]
        REG["Tool_Registry
2200+ 工具註冊表"]
        CACHE["Result_Cache
雙層快取系統"]
        PROTO --> REG
        REG --> CACHE
    end

    subgraph SG_ACCESS["存取介面層"]
        MCP["MCP_Server
對話式 AI 客戶端"]
        CLI["tu CLI
終端機介面"]
        SDK["Python SDK
程式化呼叫"]
    end

    subgraph SG_AGENT["下游 AI 科學家應用層"]
        TXAGENT["TxAgent
治療推理代理人"]
        MEDEA["Medea
體學 AI 代理人"]
        GENERIC["Claude / GPT / Gemini
通用助理"]
    end

    DB1 --> PROTO
    DB2 --> PROTO
    DB3 --> PROTO
    DB4 --> PROTO
    DB5 --> PROTO

    CACHE --> MCP
    CACHE --> CLI
    CACHE --> SDK

    MCP --> GENERIC
    SDK --> TXAGENT
    SDK --> MEDEA
    CLI --> GENERIC

    style SG_DATA fill:#E0F2FE,color:#0F172A
    style SG_TU fill:#DBEAFE,color:#0F172A
    style SG_ACCESS fill:#FEF3C7,color:#0F172A
    style SG_AGENT fill:#DCFCE7,color:#0F172A

這張圖說明了 ToolUniverse 的「中間層」定位：它不產生原始科學資料，也不是最終使用者看到的聊天介面；它是連接兩端的標準化轉譯層。這個定位非常關鍵，稍後在第 6 章分析與 AIKT 的關係時會反覆用到這個概念。

1.8 名稱背後的設計哲學

「Democratizing AI Scientists (讓 AI 科學家普及化)」這個副標題揭示了核心動機：目前只有大型實驗室（有充足工程資源整合各種資料庫 API）才能打造功能完整的 AI 科學家系統。ToolUniverse 想讓一個沒有龐大工程團隊的實驗室，也能透過「一行 MCP 設定」擁有和大型實驗室相同等級的工具存取能力——這是一種基礎設施民主化 (infrastructure democratization; 基礎設施民主化) 的嘗試。

1.9 社群動能與專案健康度指標

單看 1554 顆星、235 個分支，數字本身意義有限，需要放進脈絡裡解讀：

• Fork/Star 比偏高（235/1554 ≈ 15%）：一般開源工具的 fork/star 比多落在 5-8% 之間，偏高的比例通常代表使用者不只是「收藏觀望」，而是真的把程式碼拉下來改、拉下來接進自己的系統——這符合 ToolUniverse「被當作基礎設施使用」而非「被當作展示型 repo 收藏」的定位。
• 多語言社群支援：文件站提供語言切換（language_switcher.js/.css），加上獨立的 WeChat 社群連結，顯示團隊有意識地經營中文開發者社群，這點對台灣/中文使用者而言是額外的友善訊號。
• 多客戶端支援廣度：文件目錄下 building_ai_scientists/ 底下逐一列出 Cursor、Claude Desktop、Claude Code、Windsurf、Codex CLI、Gemini CLI、Cline、Trae、OpenCode、Antigravity、Qwen Code 等十餘種客戶端的專屬設定教學，顯示團隊把「降低任何一種主流 AI 工具的接入門檻」當作核心產品目標，而不是只服務單一生態系。
• Slack + LinkedIn + X（Twitter）多管道社群：README 明確列出這些連結，加上主要作者 Shanghua Gao 的個人求職狀態也寫在 README 裡（“currently on the job market”），透露這是一個仍由核心少數個人強力驅動、社群仍在早期成長階段的專案，而非已完全制度化、去個人依賴的大型基金會專案。這對長期依賴風險評估是一個值得記錄的觀察點——核心維護者的個人狀態變化，理論上可能影響專案未來的維護節奏。

1.10 專案採用門檻的「三層漸進式設計」

值得特別點出的一個產品設計選擇：ToolUniverse 沒有強迫所有使用者走同一條安裝路徑，而是依「使用者的技術背景」分成三層，門檻由低到高依序是「不寫程式的研究者（MCP 聊天模式）」「熟悉終端機但不寫程式的使用者（CLI 模式）」「工程師/資料科學家（Python SDK 模式）」。這種漸進式門檻設計，讓一個完全不寫程式的濕實驗室研究者，也能透過 Claude Desktop 之類的聊天介面用到跟資深工程師一樣完整的工具能力——這正是「Democratizing（普及化）」這個詞在產品設計層面的具體落實，而不只是行銷口號。

2. 核心架構 (Core Architecture)

2.1 整體系統架構

ToolUniverse 的架構可以拆成四層：資料層（工具定義 + 工具實作）、核心引擎層（註冊、發現、執行、快取）、存取介面層（MCP / CLI / SDK）、以及擴充機制（本地新增工具 / 遠端註冊工具）。

flowchart TB
    subgraph SG_DEF["工具定義層 tooluniverse/data/*.json"]
        JSON1["每個工具一份 JSON schema
name/description/parameters/type"]
    end

    subgraph SG_IMPL["工具實作層 tooluniverse/*_tool.py"]
        IMPL1["BaseTool 子類別
633+ 個 _tool.py 檔案"]
        RESTTOOL["BaseRESTTool
REST API 共用邏輯"]
        AGENTTOOL["AgenticTool
呼叫 LLM 的工具"]
        IMPL1 --> RESTTOOL
        IMPL1 --> AGENTTOOL
    end

    subgraph SG_CORE["核心引擎 ToolUniverse class"]
        REGISTRY["ToolRegistry
載入與索引所有工具"]
        EXEC["execute_function.py
統一執行入口"]
        FINDER_KW["tool_finder_keyword
關鍵字搜尋"]
        FINDER_EMB["tool_finder_embedding
語意向量搜尋"]
        FINDER_LLM["tool_finder_llm
LLM 判斷相關工具"]
        REGISTRY --> EXEC
        REGISTRY --> FINDER_KW
        REGISTRY --> FINDER_EMB
        REGISTRY --> FINDER_LLM
    end

    subgraph SG_CACHE["快取系統 cache/"]
        MEMCACHE["memory_cache
記憶體 LRU"]
        SQLCACHE["sqlite_backend
持久化 SQLite"]
        MEMCACHE --> SQLCACHE
    end

    subgraph SG_IFACE["存取介面"]
        SMCP["smcp_server.py
MCP stdio/http server"]
        CLIMOD["cli.py
tu 命令列 9 子命令"]
        PYSDK["Python 直接匯入
from tooluniverse import ToolUniverse"]
    end

    JSON1 --> REGISTRY
    IMPL1 --> REGISTRY
    EXEC --> MEMCACHE
    EXEC --> SQLCACHE

    REGISTRY --> SMCP
    REGISTRY --> CLIMOD
    REGISTRY --> PYSDK

    style SG_DEF fill:#FEF9C3,color:#0F172A
    style SG_IMPL fill:#FDE68A,color:#0F172A
    style SG_CORE fill:#BFDBFE,color:#0F172A
    style SG_CACHE fill:#FBCFE8,color:#0F172A
    style SG_IFACE fill:#BBF7D0,color:#0F172A

關鍵設計決策：資料與實作分離。 每個工具由兩個檔案組成——一份 *_tools.json（描述工具的名稱、參數、說明，給 LLM 讀的「工具說明書」）和一份對應的 *_tool.py（實際執行邏輯，繼承 BaseTool 或 BaseRESTTool）。這種分離讓「工具的介面規格」與「工具的實作細節」互相獨立——想幫某個工具改善 LLM 看到的說明文字，不需要動到程式碼；想換底層 API 供應商，不需要動到 LLM 看到的介面。這正是典型的「介面與實作解耦」設計。

一份真實的工具定義大致長這樣（簡化示意，用來說明 schema 結構，而非某個工具的逐字原文）：

 1{
 2  "name": "FAERS_count_reactions_by_drug",
 3  "type": "FAERSTool",
 4  "description": "Count reported adverse reactions for a given drug from the FDA Adverse Event Reporting System (FAERS).",
 5  "parameter": {
 6    "type": "object",
 7    "properties": {
 8      "drug_name": {
 9        "type": "string",
10        "description": "Generic or brand name of the drug to query."
11      },
12      "limit": {
13        "type": "integer",
14        "description": "Maximum number of top reaction types to return.",
15        "default": 10
16      }
17    },
18    "required": ["drug_name"]
19  },
20  "category": "drug_safety"
21}

這份 JSON 本身就是 LLM 決定「要不要用這個工具、怎麼填參數」的唯一依據——LLM 從來不需要讀 Python 原始碼，也解釋了為什麼「寫好的工具說明文字品質」對整個系統的可用性影響很大：說明寫得含糊，LLM 就容易選錯工具或填錯參數，這也是為什麼 compose_scripts/tool_description_optimizer.py 這個工具本身存在的理由——用另一個 LLM 反覆檢查、優化每個工具描述的清晰度，形成一種「工具描述的自我改善迴圈」。

2.2 資料流向：一次工具呼叫的生命週期

以「查詢阿斯匹靈的不良反應報告」為例，展示一次完整的請求—回應循環：

sequenceDiagram
    participant User as 使用者/AI 助理
    participant MCP as MCP Server
    participant Reg as Tool Registry
    participant Cache as 快取系統
    participant Tool as FAERS_tool 實作
    participant API as FDA FAERS API

    User->>MCP: 問題："aspirin 有哪些嚴重不良反應？"
    MCP->>Reg: find_tools("drug adverse event")
    Reg-->>MCP: 回傳候選工具清單
[FAERS_count_reactions_by_drug, ...]
    MCP->>Reg: get_tool_info(工具名稱)
    Reg-->>MCP: 回傳參數 schema
    MCP->>User: 展示可用工具與所需參數
    User->>MCP: execute_tool("FAERS_count_reactions_by_drug",
{"drug_name":"aspirin"})
    MCP->>Cache: 查詢快取（依參數 fingerprint）
    alt 快取命中
        Cache-->>MCP: 回傳先前結果（毫秒級）
    else 快取未命中
        MCP->>Tool: 呼叫工具實作
        Tool->>API: 發送 REST 請求
        API-->>Tool: 回傳原始 JSON
        Tool->>Tool: 解析/正規化資料
        Tool-->>Cache: 寫入快取（含 fingerprint）
        Tool-->>MCP: 回傳結構化結果
    end
    MCP-->>User: 呈現最終答案

這裡有兩個值得注意的設計：

1. 兩階段呼叫（先找工具，再執行工具）：LLM 不是盲目呼叫工具，而是先透過 find_tools / grep_tools 縮小候選範圍，再透過 get_tool_info 確認參數格式，最後才 execute_tool。這種「先探索、再執行」的模式，正是為了應付底下要講的「Compact Mode」設計。

2. 指紋化快取 (fingerprinting cache; 指紋化快取)：同樣的工具名稱 + 同樣的參數，會被計算成一個唯一指紋，查詢結果快取起來。這對藥物研發這類「反覆查詢同一批化合物/基因」的工作流特別有效——第二次查詢幾乎是瞬間回應，也讓離線環境（沒有網路）依然能重播過去查過的結果，這對「可重現性 (reproducibility; 可重現性)」的科學研究非常重要。

2.3 關鍵演算法與方法論

2.3.1 Compact Mode（緊湊模式）——解決 Context Window 爆炸問題

這是 ToolUniverse 最重要的工程創新之一。假設要把 2200 個工具的完整 schema 全部塞進 LLM 的 system prompt，以每個工具平均 150-300 tokens 估算，光是工具說明就要吃掉 33 萬到 66 萬 tokens——這遠超過任何商用 LLM 的 context window，而且會讓每次對話的成本暴增、回應速度暴跌。

Compact Mode 的解法：不把 2200 個工具都攤開，而是只暴露 5 個「元工具 (meta-tool; 元工具)」：

LLM 的推理循環變成：「先用 find_tools 縮小到 5-10 個候選 → 用 get_tool_info 確認參數 → 用 execute_tool 執行」，而不是「一次看完所有 2200 個工具再決定」。官方文件宣稱這能節省約 99% 的 context window 用量——換算下來大約是「把一本百科全書變成一個搜尋引擎」的差別：你不需要背下整本百科全書的目錄，只需要知道怎麼查詢索引。

flowchart LR
    subgraph SG_BEFORE["未使用 Compact Mode"]
        ALL2200["2200+ 個工具 schema
全部塞進 prompt
≈ 40-60 萬 tokens"]
    end

    subgraph SG_AFTER["使用 Compact Mode"]
        FIVE["5 個元工具
≈ 1-2 千 tokens"]
        FIVE -->|find_tools| CANDIDATES["候選 5-10 個工具"]
        CANDIDATES -->|get_tool_info| DETAIL["取得詳細參數"]
        DETAIL -->|execute_tool| RESULT["執行並取得結果"]
    end

    style SG_BEFORE fill:#FEE2E2,color:#0F172A
    style SG_AFTER fill:#DCFCE7,color:#0F172A

2.3.2 三種工具發現機制

ToolUniverse 提供三種互補的「找工具」策略，各有取捨：

• 關鍵字搜尋（tool_finder_keyword）：對工具名稱、描述做字串/正則比對。速度最快、零成本（不需呼叫任何模型），但要求使用者輸入的詞彙要接近工具實際命名。
• 語意向量搜尋（tool_finder_embedding）：把所有工具描述轉成向量，用 embedding 相似度找最接近的工具。能處理「我想查一下這個藥有沒有致癌風險」這種不直接包含工具名稱關鍵字的自然語言問題，但需要先建置向量索引、且需要 embedding 模型資源。
• LLM 判斷（tool_finder_llm）：直接請一個 LLM 讀完候選工具描述後判斷哪些最相關。彈性最高（能理解複雜的多步驟需求），但成本最高、延遲最大，通常作為前兩者篩選後的最後把關。

三者的取捨呈現典型的「速度/成本 vs. 理解深度」光譜，ToolUniverse 讓使用者/客戶端自行選擇要用哪一種（或組合使用）。

2.3.3 工具組合（Tool Composition）——把工具串成工作流

除了單一工具呼叫，ToolUniverse 在 compose_scripts/ 目錄下提供「組合腳本 (compose script; 組合腳本)」，把多個原子工具串成固定的工作流，例如：

• comprehensive_drug_discovery.py：串接化合物檢索 → 靶點比對 → ADMET 預測 → 文獻佐證，形成一條完整的藥物發現初篩流程
• drug_safety_analyzer.py：串接不良反應資料庫 + 交互作用檢查 + 臨床文獻搜尋
• multi_agent_literature_search.py：多個 Agent 分工搜尋不同資料庫的文獻，最後彙整摘要

這種設計讓「常見的多步驟科學任務」被封裝成一個可重複呼叫的高階工具，而不需要每次都讓 LLM 重新規劃步驟順序——類似把常用的一連串 Excel 操作錄製成巨集 (macro; 巨集)，之後一鍵重播。

2.4 內部元件互動關係

flowchart TB
    CORE["ToolUniverse 主類別
(src/tooluniverse/__init__.py)"]

    CORE --> LOADER["工具載入器
掃描 data/*.json"]
    CORE --> REGISTRY2["ToolRegistry
依名稱/分類索引"]
    CORE --> EXECUTOR["execute_function
依 type 派發到對應 *_tool.py"]
    CORE --> FINDERS["三種 Finder
keyword/embedding/llm"]
    CORE --> HOOKS["output_hook / extended_hooks
結果後處理與驗證"]

    EXECUTOR --> CACHE2["Result Cache
memory + sqlite"]
    EXECUTOR --> ASYNCBASE["async_base
長任務進度追蹤"]
    ASYNCBASE --> TASKMGR["task_manager /
task_progress"]

    HOOKS --> LOGGING["logging_config
統一輸出到 stderr"]

    LOADER -.->|懶載入優化| LAZY["_lazy_registry_static
build_optimizer 產生"]

    style CORE fill:#BFDBFE,color:#0F172A
    style CACHE2 fill:#FBCFE8,color:#0F172A
    style LAZY fill:#FEF9C3,color:#0F172A

懶載入優化 (lazy loading optimization; 懶載入優化) 是另一個值得注意的效能設計：與其在啟動時真的把 2200 個工具的 Python 模組全部 import 進記憶體（會拖慢啟動速度），ToolUniverse 用 build_optimizer.py 預先產生一份靜態的 _lazy_registry_static.py，只記錄「工具名稱 → 該去哪個模組載入」的對照表，真正需要執行某個工具時才動態 import 該模組。這讓啟動速度大幅提升，同時保留了 2200+ 工具全部可用的完整性。

2.5 非同步任務（Async Operations）處理長時間運算

不是所有科學計算都能秒回——蛋白質對接模擬、分子動力學模擬可能要跑幾分鐘到幾小時。ToolUniverse 用 async_base.py + task_manager.py + task_progress.py 三個模組實作了「非同步工具」機制：

1. 呼叫長任務工具時，立刻回傳一個 task ID，不阻塞主流程
2. LLM/使用者可以用另一個工具查詢該 task ID 的進度
3. 任務完成後，結果存入快取，之後查詢直接拿到最終結果
4. 支援平行執行多個長任務（例如同時對接 50 個候選化合物）

這個設計避免了「LLM 對話被一個要跑 10 分鐘的模擬卡死」的窘境，也讓平行篩選（screening）類任務可以真正發揮平行運算的效益。

2.6 工具基底類別設計：BaseTool / BaseRESTTool / AgenticTool

理解 ToolUniverse 如何讓「新增一個工具」的成本降到最低，要看它的類別繼承設計：

flowchart TB
    BASE["BaseTool
(base_tool.py)
定義 run()/validate()/schema 介面"]
    BASE --> REST["BaseRESTTool
(base_rest_tool.py)
共用 HTTP 請求/重試/逾時邏輯"]
    BASE --> AGENT2["AgenticTool
(agentic_tool.py)
共用 LLM 呼叫/prompt 組裝邏輯"]
    REST --> CONCRETE1["UniProt_tool.py
PubMed_tool.py
ChEMBL_tool.py
...約 600 個具體實作"]
    AGENT2 --> CONCRETE2["ScientificTextSummarizer
HypothesisGenerator
...23 個 Agentic Tools"]

    style BASE fill:#BFDBFE,color:#0F172A
    style REST fill:#FDE68A,color:#0F172A
    style AGENT2 fill:#FCE7F3,color:#0F172A

這種「兩層繼承」設計的好處是：絕大多數新工具只是「換一個 REST endpoint、換一組參數」，因此只需要繼承 BaseRESTTool 並填入該資料庫的 endpoint 與參數對映邏輯，共用的請求重試 (retry; 重試)、逾時 (timeout; 逾時)、錯誤攔截邏輯完全不用重寫。這也是為什麼這個專案能在相對短時間內把工具數量堆疊到 2200+——邊際成本被壓得很低，加一個工具往往只需要新增一份 JSON schema + 一小段 Python，而不是從零實作一整套 HTTP 客戶端邏輯。

2.7 錯誤處理與驗證機制

exceptions.py 定義了統一的例外階層，讓所有工具的錯誤回應遵循一致的格式，這對 LLM 判讀錯誤原因、決定要不要重試或改用其他工具非常重要。常見錯誤分類包括：

• 參數驗證錯誤：呼叫時缺少必填參數，或型別不符（例如把字串傳進整數欄位），在真正發出外部 API 請求前就被攔截，避免浪費一次外部呼叫額度
• 認證錯誤：缺少對應的 API Key 時，錯誤訊息直接指出「請設定哪個環境變數」，而不是回傳一個難以判讀的 401 原始錯誤
• 上游服務錯誤：外部資料庫本身回應逾時/服務中斷，會被正規化成統一格式，並保留原始錯誤供除錯
• 速率限制錯誤：偵測到 429（Too Many Requests）時的退避重試 (exponential backoff; 指數退避) 邏輯，避免因為短時間內大量呼叫而被上游資料庫封鎖

server_security.py 則額外處理 MCP Server 模式下的存取控制邏輯，例如限制哪些工具可以被暴露、避免惡意輸入注入到底層工具呼叫中。

2.8 品質保證：自動化健檢機制

.github/workflows/weekly-tool-healthcheck.yml 這個持續整合 (continuous integration; CI) 工作流，會定期實際呼叫抽樣的工具，確認它們是否還能正常回應——這對一個依賴 2200+ 個外部第三方服務的專案而言是必要的維運手段，因為任何一個上游資料庫改版都可能讓對應工具悄悄失效而沒有人發現。健檢結果會回饋到 .github/known_failing_categories.txt，讓維護者與使用者都能提前知道「目前哪些工具類別已知不穩定」，而不是等使用者踩雷才發現。這個機制某種程度上補足了「聚合大量第三方 API」這種架構天生的脆弱性——單一工具的故障不會被無限期忽略。

3. 安裝與設定 (Installation & Setup)

3.1 前置需求

依 AIKT 全域工具鏈鐵律，本文件示範一律使用 uv / uvx，不使用裸 pip 作為主要安裝方式。

3.2 三種存取模式，先決定要走哪一條路

ToolUniverse 官方明確區分三種使用情境，安裝方式各不相同：

flowchart TB
    START["我要怎麼用 ToolUniverse？"] --> Q1{"我只想用聊天
問問題，不寫程式？"}
    Q1 -->|是| MODE_MCP["模式 A：MCP Server
接進 Claude/Cursor/Codex 等
對話式 AI 客戶端"]
    Q1 -->|否| Q2{"我想在終端機
快速測試/腳本化？"}
    Q2 -->|是| MODE_CLI["模式 B：tu CLI
uvx --from tooluniverse tu ..."]
    Q2 -->|否| MODE_SDK["模式 C：Python SDK
uv pip install tooluniverse"]

    style MODE_MCP fill:#DBEAFE,color:#0F172A
    style MODE_CLI fill:#DCFCE7,color:#0F172A
    style MODE_SDK fill:#FEF3C7,color:#0F172A

3.3 安裝方法一：MCP Server（給對話式 AI 客戶端用，最推薦）

步驟 1：安裝 uv（唯一前置依賴，之後 uv/uvx 會自動管理 Python 版本與虛擬環境）

1curl -LsSf https://astral.sh/uv/install.sh | sh
2uv --version   # 驗證安裝成功

步驟 2：把以下設定貼進你的 AI 客戶端 MCP 設定檔

1{
2  "mcpServers": {
3    "tooluniverse": {
4      "command": "uvx",
5      "args": ["--refresh", "tooluniverse"],
6      "env": { "PYTHONIOENCODING": "utf-8" }
7    }
8  }
9}

常見客戶端的設定檔位置（以 Claude Code / Claude Desktop 為主的機器最常用到）：

步驟 3：重啟客戶端，確認 tooluniverse 出現在已連接的 MCP server 清單中。

3.4 安裝方法二：tu CLI（終端機直接用）

不需要先安裝，uvx 會自動下載並快取套件：

1# 免安裝直接跑（第一次約 30 秒下載，之後瞬間啟動）
2uvx --from tooluniverse tu status
3
4# 或想要更短命令，直接裝成全域工具
5uv tool install tooluniverse
6tu status

3.5 安裝方法三：Python SDK（給要寫程式整合的人）

1uv pip install tooluniverse

驗證安裝：

1from tooluniverse import ToolUniverse
2
3tu = ToolUniverse()
4tu.load_tools()
5print(f"已載入 {len(tu.all_tool_dict)} 個工具")

3.6 開發模式安裝（要改原始碼、貢獻新工具）

1git clone https://github.com/mims-harvard/ToolUniverse.git
2cd ToolUniverse
3uv pip install -e ".[dev]"

pyproject.toml 定義的 dev extras 會一併裝好 pytest、pytest-cov、ruff、pre-commit 等測試與品質工具，符合貢獻程式碼前先跑測試的慣例。

3.7 環境設定：API Key

多數核心工具（PubMed、UniProt、PubChem 等）不需要 API Key 即可使用；但部分資料庫（NCBI、NVIDIA NIM、BioGRID、DisGeNET、OMIM 等）需要各自申請免費或學術用 API Key 才能解鎖對應工具。

依 AIKT 全域安全規範，機密一律放環境變數，不寫進程式碼：

1# 複製範本
2cp .env.template .env
3
4# 編輯 .env，填入你需要的 Key（不是每個都必填）
5# NCBI_API_KEY=xxxxx        # 提升 PubMed 查詢速率上限
6# NVIDIA_API_KEY=nvapi-xxx  # 解鎖 AlphaFold2/DiffDock 等 16 個 NIM 工具
7# BIOGRID_API_KEY=xxxxx     # 解鎖蛋白質交互作用查詢
8# OPENAI_API_KEY=xxxxx      # Agentic Tools（呼叫 LLM 的工具）需要

沒填的 Key 對應的工具會在呼叫時明確報錯提示「缺少哪個環境變數」，其餘工具不受影響——這是一個對「漸進式設定」友善的設計，不會因為缺一個 Key 就整套系統罷工。

3.8 驗證安裝是否成功

 1# 檢查版本與工具總數
 2tu status
 3
 4# 應該看到類似輸出：
 5# ToolUniverse v1.3.1
 6# Total tools loaded: 2201
 7# Top categories: ...
 8
 9# 搜尋測試：找跟「蛋白質結構」相關的工具
10tu find "protein structure analysis"
11
12# 執行測試：跑一個不需要 API Key 的工具
13tu run PubMed_search_articles '{"query": "CRISPR gene editing", "max_results": 3}'

若三個指令都能正常輸出結果（不報錯），代表安裝與環境設定完成。

3.9 常見安裝問題排解

依 AIKT 全域規範，遇到同一個安裝錯誤嘗試兩次仍未解決時，應停下來換一個排解方向或直接詢問使用者，而不是反覆用同一種方式重試。

4. 基本使用 (Basic Usage)

4.1 心智模型：把 ToolUniverse 想成「圖書館 + 圖書館員」

在動手之前，先建立一個心智模型：ToolUniverse 本身像一座藏書 2200 本的圖書館，find_tools/grep_tools 是圖書館員幫你找書，get_tool_info 是翻開書的目錄看章節安排，execute_tool 才是真正打開書、讀出你要的內容。整個互動流程永遠是「找 → 看規格 → 執行」三步驟，不管走 CLI、SDK 還是聊天，邏輯都一樣。

4.2 快速入門：CLI 五分鐘上手

情境：你想知道某個藥物（以 metformin 二甲雙胍為例）有沒有已知的嚴重不良反應。

1# 第一步：搜尋跟「藥物安全」相關的工具（不需要知道確切工具名稱）
2tu find "drug safety adverse events"

輸出範例（簡化）：

11. FAERS_count_reactions_by_drug   — Count adverse event reactions reported for a drug
22. FAERS_count_death_related_by_drug — Count death-related reports for a drug
33. DrugSafety_check_interactions   — Check known drug-drug interactions

1# 第二步：看第一個工具需要什麼參數
2tu info FAERS_count_reactions_by_drug

輸出範例：

 1{
 2  "name": "FAERS_count_reactions_by_drug",
 3  "description": "Count reported adverse reactions for a given drug from FDA FAERS.",
 4  "parameters": {
 5    "type": "object",
 6    "properties": {
 7      "drug_name": {"type": "string", "description": "Generic or brand drug name"},
 8      "limit": {"type": "integer", "description": "Max number of reaction types to return"}
 9    },
10    "required": ["drug_name"]
11  }
12}

1# 第三步：實際執行
2tu run FAERS_count_reactions_by_drug '{"drug_name": "metformin", "limit": 10}'

輸出範例（簡化的 JSON）：

1{
2  "drug_name": "metformin",
3  "top_reactions": [
4    {"reaction": "Lactic acidosis", "count": 1842},
5    {"reaction": "Nausea", "count": 973},
6    {"reaction": "Diarrhoea", "count": 861}
7  ],
8  "total_reports": 15420
9}

三個指令、三十秒內，就完成了原本要開瀏覽器、找到 FAERS 公開查詢介面、手動輸入查詢條件、再自己統計排序的工作。

4.3 從零開始的完整工作流範例：文獻 + 化合物 + 安全性

假設任務是：「幫我快速了解 metformin 這個藥的基本化學資訊、近期相關文獻、以及安全性顧慮」——這是一個典型「新藥/舊藥快速摸底」的研究情境。

 1# 步驟 1：查化學結構與基本資訊
 2tu run PubChem_get_compound_by_name '{"name": "metformin"}'
 3
 4# 步驟 2：查最近三年的相關文獻
 5tu run PubMed_search_articles '{"query": "metformin cancer prevention", "max_results": 5, "sort": "date"}'
 6
 7# 步驟 3：查不良反應概況（延續 4.2 的結果）
 8tu run FAERS_count_reactions_by_drug '{"drug_name": "metformin", "limit": 5}'
 9
10# 步驟 4：查是否有已知的藥物交互作用
11tu run DrugSafety_check_interactions '{"drug_name": "metformin"}'

在對話式 AI 客戶端（MCP 模式）中，你完全不需要自己拆解成這四個指令——只要問「幫我摸底一下 metformin 這個藥」，LLM 會自動透過 find_tools 找到這四類工具、依序呼叫、再把結果整理成一份摘要報告。CLI 範例的價值在於：讓你理解 AI 背後實際在做什麼，方便除錯與驗證結果的可信度。

4.4 Python SDK 三種呼叫模式

ToolUniverse 的 Python SDK 提供三種呼叫風格，適合不同的整合場景。

模式 1：直接匯入（有型別提示、IDE 自動完成）——最適合寫固定、可預期的分析腳本：

1from tooluniverse.tools import UniProt_get_entry_by_accession
2
3result = UniProt_get_entry_by_accession(accession="P12345")
4print(result["sequence"])

模式 2：屬性存取（不用逐一 import，適合互動式探索）——最適合 Jupyter Notebook 探索階段：

1from tooluniverse import ToolUniverse
2
3tu = ToolUniverse()
4tu.load_tools()
5
6result = tu.tools.UniProt_get_entry_by_accession(accession="P12345")
7print(result["organism"])

模式 3：JSON 動態呼叫（適合管線化、工具名稱是變數的情境）——最適合把 ToolUniverse 嵌進更大的自動化管線，因為工具名稱可以是設定檔裡讀出來的字串：

 1from tooluniverse import ToolUniverse
 2
 3tu = ToolUniverse()
 4tu.load_tools()
 5
 6tool_calls = [
 7    {"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}},
 8    {"name": "PubMed_search_articles", "arguments": {"query": "BRCA1 mutation", "max_results": 5}},
 9]
10
11for call in tool_calls:
12    result = tu.run(call)
13    print(call["name"], "->", type(result))

4.5 輸入/輸出格式慣例

理解 ToolUniverse 的輸入輸出格式對除錯很重要：

這個「stdout 純淨、log 走 stderr」的設計，跟 AIKT 全域 shell 規範中「錯誤訊息寫到 stderr」的原則不謀而合，代表這是成熟 CLI 工具的共通慣例。

4.6 真實生物醫學場景範例：三個常見任務的最短路徑

場景 A：確認某基因變異是否已知致病

1tu find "genetic variant pathogenicity"
2tu run ClinVar_get_variant_by_id '{"variant_id": "rs121913529"}'

場景 B：快速找某疾病的臨床試驗現況

1tu find "clinical trials disease"
2tu run ClinicalTrials_search '{"condition": "pancreatic cancer", "status": "recruiting", "limit": 10}'

場景 C：確認某蛋白質是否已有解析結構

1tu find "protein 3D structure"
2tu run PDB_search_by_protein '{"protein_name": "EGFR"}'
3tu run AlphaFold_get_prediction '{"uniprot_id": "P00533"}'

以上三個場景共用同一套三步驟節奏（find → 確認參數 → run），這正是 ToolUniverse 設計上刻意追求的「一致性」：不管背後是哪一個資料庫，使用者的操作心智負擔都不會隨著工具數量增加而變重。

5. 進階功能與應用場景 (Advanced Features & Use Cases)

5.1 進階配置選項

5.1.1 精細控制 Compact Mode 的工具白名單

大型部署場景中，可能不想讓 AI 有權存取全部 2200+ 個工具（例如出於成本或安全考量，只想開放化學相關工具）。ToolUniverse 支援在啟動 MCP Server 時限定工具子集：

 1{
 2  "mcpServers": {
 3    "tooluniverse-chem-only": {
 4      "command": "uvx",
 5      "args": [
 6        "--refresh", "tooluniverse",
 7        "--include-categories", "chemistry,admet,pubchem"
 8      ],
 9      "env": { "PYTHONIOENCODING": "utf-8" }
10    }
11  }
12}

這種「白名單縮限」對機構內部部署特別重要——例如只想讓某個內部助理碰化學資料庫、不碰臨床病人資料相關工具，降低誤用/資料外洩風險面。

5.1.2 快取策略調校

雙層快取（記憶體 LRU + SQLite 持久化）可依情境調整：

1from tooluniverse import ToolUniverse
2
3tu = ToolUniverse(
4    cache_enabled=True,
5    cache_ttl_seconds=86400,       # 快取 24 小時後過期
6    cache_backend="sqlite",        # 持久化到磁碟，跨 session 保留
7)

對於「同一批候選化合物要反覆分析好幾天」的藥物發現專案，把 TTL 拉長甚至設為永久，能大幅降低對外部 API 的重複請求量，同時確保結果可重現（同一輸入永遠得到同一份已快取的輸出，不受外部資料庫當下狀態波動影響）。

5.1.3 自訂 Tool Finder 策略

視情境切換三種 Finder 的優先序：

1result = tu.find_tools(
2    query="find drugs that target EGFR",
3    strategy="embedding",      # "keyword" | "embedding" | "llm"
4    top_k=8,
5)

對成本敏感的批次任務用 keyword；對模糊自然語言查詢用 embedding；對需要深度推理才能判斷相關性的複雜需求，才動用 llm（成本最高）。

5.2 實際應用案例

案例一：藥物重定位（Drug Repurposing）初篩管線

場景：想知道現有已上市藥物中，有沒有可能對某個罕見疾病靶點有效。

 1from tooluniverse import ToolUniverse
 2
 3tu = ToolUniverse()
 4tu.load_tools()
 5
 6target_gene = "SOD1"  # 例：與漸凍症相關的靶點
 7
 8# 1. 找出已知與該靶點結合的化合物
 9binders = tu.run({
10    "name": "BindingDB_get_ligands_by_target",
11    "arguments": {"target_gene": target_gene, "limit": 20}
12})
13
14# 2. 對每個候選化合物查詢是否已上市、目前核准適應症
15approved_candidates = []
16for compound in binders.get("ligands", []):
17    info = tu.run({
18        "name": "PubChem_get_compound_by_name",
19        "arguments": {"name": compound["name"]}
20    })
21    approval = tu.run({
22        "name": "ClinicalTrials_search",
23        "arguments": {"intervention": compound["name"], "status": "completed"}
24    })
25    if approval.get("total_count", 0) > 0:
26        approved_candidates.append(compound["name"])
27
28print(f"找到 {len(approved_candidates)} 個可能重定位的已核准藥物候選")

這個範例示範了 ToolUniverse 最典型的價值：把「靶點 → 已知結合分子 → 上市狀態確認」這條原本要在三個不同網站手動查詢比對的流程，壓縮成一段十幾行的可重複執行程式碼。

案例二：用 Agentic Tools 做文獻自動摘要與假說產生

ToolUniverse 內建 23 個「Agentic Tools」——本質上是包裝了 LLM 呼叫的工具，可以和一般資料庫工具混用：

 1# 先用一般工具搜文獻
 2papers = tu.run({
 3    "name": "PubMed_search_articles",
 4    "arguments": {"query": "long COVID biomarkers", "max_results": 15}
 5})
 6
 7# 再用 Agentic Tool 做摘要整合（需要設定 OPENAI_API_KEY 或等效 LLM Key）
 8summary = tu.run({
 9    "name": "ScientificTextSummarizer",
10    "arguments": {"documents": [p["abstract"] for p in papers["articles"]]}
11})
12
13# 用另一個 Agentic Tool 從摘要中產生可測試假說
14hypotheses = tu.run({
15    "name": "HypothesisGenerator",
16    "arguments": {"context": summary["summary_text"], "domain": "immunology"}
17})
18
19for h in hypotheses["hypotheses"]:
20    print("-", h)

這種「一般工具查資料、Agentic Tool 做推理」的混用模式，正是 ToolUniverse 宣稱能支援「實驗設計 (experimental design; 實驗設計)」這類更高階科學任務的關鍵——它不是純粹的資料檢索系統，而是把資料檢索與 LLM 推理封裝在同一套介面下，讓兩者可以自由交錯串接。

案例三：非同步長任務——批次蛋白質結構預測

 1# 送出多個蛋白質序列做結構預測（長任務，立即回傳 task_id）
 2task_ids = []
 3sequences = {"protein_A": "MKT...", "protein_B": "MVL..."}
 4
 5for name, seq in sequences.items():
 6    result = tu.run({
 7        "name": "AlphaFold_predict_structure_async",
 8        "arguments": {"sequence": seq}
 9    })
10    task_ids.append((name, result["task_id"]))
11
12# 輪詢所有任務進度
13import time
14pending = dict(task_ids)
15while pending:
16    for name, tid in list(pending.items()):
17        status = tu.run({"name": "check_task_progress", "arguments": {"task_id": tid}})
18        if status["state"] == "completed":
19            print(f"{name} 完成，結構已存入快取")
20            del pending[name]
21    if pending:
22        time.sleep(30)

案例四：網路藥理學（Network Pharmacology）多靶點交互分析

場景：許多疾病（如癌症、代謝症候群）並非單一靶點驅動，而是牽涉一組相互作用的基因/蛋白質網路。這個範例示範如何用 ToolUniverse 串接蛋白質交互作用資料庫與通路資料庫，建立一個可供下游網路分析（如 NetworkX）使用的資料集。

 1from tooluniverse import ToolUniverse
 2
 3tu = ToolUniverse()
 4tu.load_tools()
 5
 6seed_genes = ["TP53", "MDM2", "CDKN1A"]  # 已知與該疾病相關的種子基因
 7edges = []
 8
 9for gene in seed_genes:
10    # 1. 查詢該基因的直接交互作用夥伴（需要 BIOGRID_API_KEY）
11    interactions = tu.run({
12        "name": "BioGRID_get_interactions",
13        "arguments": {"gene_symbol": gene, "limit": 15}
14    })
15    for partner in interactions.get("interactors", []):
16        edges.append((gene, partner["symbol"]))
17
18    # 2. 查詢該基因參與的通路
19    pathways = tu.run({
20        "name": "Reactome_get_pathways_by_gene",
21        "arguments": {"gene_symbol": gene}
22    })
23    print(f"{gene} 參與 {len(pathways.get('pathways', []))} 條已知通路")
24
25print(f"共建立 {len(edges)} 條交互作用邊，可交給 networkx 建圖分析中心性/模組")

這個範例產生的 edges 列表可以直接餵給 networkx.Graph() 做進一步的中心性 (centrality; 中心性) 或社群偵測 (community detection; 社群偵測) 分析，展示了 ToolUniverse 作為「上游資料供應」與其他 Python 科學計算生態系（NetworkX、scikit-learn 等）自然銜接的能力——它不試圖取代這些分析工具，只負責把原始資料整理成乾淨的結構化格式。

5.3 與其他工具/函式庫的整合

5.3.1 與 MCP 生態系整合

因為 ToolUniverse 本身就是一個標準 MCP Server，它天然能被任何支援 MCP 協議的客戶端使用——不只是聊天助理，也包括其他 Agent 框架（如 LangGraph、CrewAI 等）如果支援 MCP client，也能把 ToolUniverse 當成一個工具供應商掛載進去。

5.3.2 與 smolagents 整合

pyproject.toml 定義了 smolagents extras，代表官方支援直接把 ToolUniverse 的工具接進 Hugging Face 的 smolagents 框架：

1uv pip install "tooluniverse[smolagents]"

1from smolagents import CodeAgent
2from tooluniverse.smolagents_bridge import get_smolagents_tools
3
4tools = get_smolagents_tools(categories=["chemistry", "genomics"])
5agent = CodeAgent(tools=tools, model=my_llm_model)
6agent.run("Find compounds similar to imatinib and check their known targets.")

5.3.3 與程式碼執行器整合

ToolUniverse 內建 python_code_executor 與 python_script_runner 兩個工具，讓 LLM 在需要「自己寫一段程式碼做資料處理」時（例如對查回來的一批基因表現量資料做統計檢定），可以直接在受控環境內執行 Python，不需要跳出 ToolUniverse 生態系去另外接一個 code interpreter。

5.4 效能優化建議

1. 善用 Compact Mode，不要關掉它：即使是程式化呼叫（SDK 模式），如果工具數量龐大，仍建議透過 find_tools 先縮小範圍，而不是一次列出全部工具清單塞進自己的 prompt。
2. 依任務性質選 Finder 策略：批次腳本化任務用 keyword（零延遲零成本）；互動式探索用 embedding；只有真正模糊、需要語境理解的查詢才用 llm 策略。
3. 拉長快取 TTL 應對可重現性需求：科學分析經常需要「同一份輸入，任何時候重跑都要得到一樣的結果」，善用 SQLite 持久化快取而非只靠記憶體 LRU。
4. 善用 tu build 產生型別化 Python 包裝：對於會長期維護的分析管線，先跑 tu build --output ./my_tools 產生具型別提示的 Python 模組，比每次都用字串拼 JSON 呼叫更不容易出參數型別的低級錯誤。
5. 平行化非同步長任務：善用 async_base 機制平行送出多個長任務（如批次結構預測），而不是序列等待每個任務跑完才送下一個。

6. AIKT 整合分析與策略 (AIKT Integration & Strategy)

6.1 整合架構圖

flowchart TB
    subgraph SG_AIKT["AIKT 27 Layer 系統"]
        L1_3["L1-L3
知識擷取
ai-save/gh-save/autofetch"]
        L9_10["L9-L10
文獻搜尋
paper-search/paper-qa-lite"]
        L18_19["L18-L19
研究管線
research-pipeline-v2/tu-plan-generator"]
        L4_6["L4-L6
知識組織
graphify/NotebookLM/GitNexus"]
    end

    subgraph SG_TOOLU["ToolUniverse"]
        TU_MCP["MCP Server
2200+ 科學工具"]
        TU_DATA["科學資料層
PubMed/UniProt/ChEMBL/
ClinicalTrials/FAERS..."]
        TU_AGENT["23 Agentic Tools
假說生成/文獻摘要"]
    end

    L9_10 -.->|功能重疊
紅海| TU_DATA
    L18_19 -->|互補整合
藍海機會| TU_MCP
    L18_19 -->|藍海機會| TU_AGENT
    TU_MCP -->|原始科學數據輸出| L1_3
    L1_3 -->|轉存為 inbox md| L4_6
    L4_6 -->|知識圖譜索引| L11_13
    TU_AGENT -.->|部分重疊
假說生成| L18_19

    style SG_AIKT fill:#DBEAFE,color:#0F172A
    style SG_TOOLU fill:#DCFCE7,color:#0F172A

6.2 紅海分析 (Red Ocean Analysis)

紅海分析的目標是誠實指出：ToolUniverse 有哪些能力，會讓 AIKT 現有的某些 Layer 顯得多餘或處於劣勢。

6.2.1 重疊功能逐項比較

6.2.2 市場定位衝突

嚴格來說，兩者的市場定位其實不衝突——ToolUniverse 定位是「科學資料/計算的統一存取層」，AIKT 定位是「知識工作流編排系統」。真正的重疊只發生在一個狹窄地帶：當 AIKT 某個 Layer 本身也試圖直接呼叫外部科學/學術 API 時（如 paper-search 直連 PubMed API），這時 AIKT 就從「編排者」的角色，滑落到跟 ToolUniverse 搶「資料存取層」這個 ToolUniverse 已經做得更完整、更多人維護的地盤。

紅海警訊：如果 AIKT 未來新增 Layer 的方向是「再接一個科學資料庫的 API 整合」（例如接 ChEMBL、接 ClinicalTrials.gov），這件事 ToolUniverse 已經用一個標準化協議做了 2200 次，AIKT 自建等於重新發明一個規模小 2000 倍的輪子。這是本分析要提出的最明確警訊：AIKT 不應該再自建任何「單一科學資料庫 API 整合」的新 Layer，而應該優先評估直接接 ToolUniverse。

6.3 藍海策略 (Blue Ocean Strategy)

6.3.1 此 repo 未滿足的需求

ToolUniverse 明確聲明自己「不做」的事情，剛好是 AIKT 的核心強項：

1. 不做知識沉澱與長期記憶：ToolUniverse 每次查詢是無狀態的（stateless），查完就丟，不會像 AIKT 的 inbox/ + graphify 知識圖譜一樣把查詢結果永久化、建立跨查詢的知識關聯。
2. 不做專業文件產出：ToolUniverse 回傳的是結構化 JSON，不會自動生成一份排版精美、附圖表的 PDF 報告——這正是 kami / quarkdown 的強項。
3. 不做多輪迭代的研究策略調整：ToolUniverse 的 Agentic Tools 是單次呼叫，不會像 research-pipeline-v2 一樣做「三輪迭代收斂」的研究策略優化。
4. 不做跨會議/跨專案的情報整合：ToolUniverse 不知道你上週開會討論了什麼、公司內部有哪些既有研究——這些是 company-intel、meeting-intel 的地盤。

6.3.2 創造新價值的整合機會

真正的藍海機會，不是「AIKT 去做 ToolUniverse 已經做的事」，而是「讓 ToolUniverse 的原始科學數據，流進 AIKT 已經建好的知識沉澱與交付管線」。具體來說：

flowchart LR
    Q["研究問題"] --> TU["ToolUniverse
查 2200+ 科學工具
取得原始數據"]
    TU --> SAVE["ai-save (L1)
把查詢結果轉存為
inbox/ 標準 md"]
    SAVE --> GRAPH["graphify (L4)
建立知識圖譜索引
跨查詢關聯"]
    GRAPH --> PLAN["tu-plan-generator (L19)
組裝成 pre-IND
藥物開發計畫"]
    PLAN --> KAMI["kami (L11)
排版成專業 PDF"]

    style TU fill:#DCFCE7,color:#0F172A
    style SAVE fill:#DBEAFE,color:#0F172A
    style GRAPH fill:#FEF3C7,color:#0F172A
    style PLAN fill:#FCE7F3,color:#0F172A
    style KAMI fill:#E0E7FF,color:#0F172A

這條管線讓 ToolUniverse 從「一次性查詢工具」升級為「AIKT 知識庫的活水源頭」——每次用 ToolUniverse 查到的數據，不再是查完就丟，而是自動變成 AIKT 可長期檢索、可組裝進交付物的知識資產。這正是 ToolUniverse 自身完全沒有、也不打算做的能力（見 §6.3.1 第一點），因此不構成競爭，而是純粹的價值疊加。

6.3.3 互補的 AIKT 層級

6.3.4 具體差異化策略

1. AIKT 不重做資料存取層，改當「ToolUniverse 的知識治理層」：明確把「查科學資料庫」這件事的底層實作交給 ToolUniverse，AIKT 專注在「查完之後怎麼永久化、怎麼組裝成交付物、怎麼守住機密邊界」。這是最高槓桿的差異化——用最少的自建成本，換最大的能力擴充。
2. 針對 tu-plan-generator 做深度整合，而非泛用整合：這是 AIKT 現有 Layer 中與 ToolUniverse 場景重疊度最高、互補價值也最高的一個，應該優先設計標準化的「ToolUniverse 查詢結果 → pre-IND 文件段落」轉換樣板。
3. 把「機密邊界」做成差異化賣點，而非弱點：ToolUniverse 是通用開源工具，沒有企業內部治理概念。AIKT 若能把「哪些 ToolUniverse 查詢結果允許進 Discord / 允許進 git / 哪些必須留在 chmod 700 目錄」這套規則做扎實，就是 ToolUniverse 完全無法提供、但企業用戶高度需要的價值。
4. 不要在 L9 paper-search 上跟 ToolUniverse 硬碰硬：既有 paper-search 若功能被 ToolUniverse 的文獻工具覆蓋，應評估「retire 或降級為輕量客製化層，底層改接 ToolUniverse」，把維護資源省下來投入真正差異化的 Layer。

6.3.5 具體場景演練：tu-plan-generator 呼叫 ToolUniverse 的完整互動

用一個具體場景把 §6.3.3、§6.3.4 的抽象建議落地：使用者觸發 tu: 產生 XX 化合物的 pre-IND 安全性章節，理想中的整合互動應該長這樣：

sequenceDiagram
    participant User as 使用者
    participant TUGEN as tu-plan-generator (L19)
    participant TU as ToolUniverse MCP
    participant SAVE as ai-save (L1)
    participant GRAPH as graphify (L4)
    participant KAMI as kami (L11)

    User->>TUGEN: tu: 產生 compound-X 的 pre-IND 安全性章節
    TUGEN->>TU: find_tools("drug safety adverse event ADMET")
    TU-->>TUGEN: 候選工具清單
    TUGEN->>TU: execute_tool(FAERS_count_reactions_by_drug, ...)
    TUGEN->>TU: execute_tool(ADMETai_predict_toxicity, ...)
    TU-->>TUGEN: 結構化 JSON 結果
    TUGEN->>SAVE: 轉存查詢結果為 inbox/ md（附時間戳與來源）
    SAVE->>GRAPH: 觸發 graphify update，建立與既有知識的關聯
    TUGEN->>TUGEN: 組裝安全性章節草稿（引用 ToolUniverse 數據）
    TUGEN->>KAMI: 排版成 pre-IND 文件格式
    KAMI-->>User: 交付專業 PDF 章節

這個場景演練清楚展示了「垂直分工」而非「水平競爭」的關係：ToolUniverse 只負責中間的資料查詢環節，前面的意圖理解、後面的知識沉澱與專業排版全部是 AIKT 既有 Layer 的既有強項，完全不需要重造。

6.4 推薦整合方案

第一階段（低成本驗證，1-2 週）：

• 在 AIKT 新增一個輕量「tu-bridge」腳本（可歸類為現有 L1 ai-save 的一個子模式，不需要開新 Layer），呼叫 uvx --from tooluniverse tu run <tool> <args> --raw，把 JSON 輸出轉存為標準 inbox md（帶上 frontmatter 標明資料來源與查詢時間戳）。
• 先驗證 3-5 個高頻使用場景（文獻搜尋、藥物安全查詢、基因變異查詢），確認轉存格式與 graphify 索引相容。

第二階段（深度整合，配合 tu-plan-generator 迭代）：

• 在 tu-plan-generator 的計畫生成邏輯中，明確定義哪些段落（如「安全性風險評估」「已知交互作用」）應該自動觸發 ToolUniverse 查詢並嵌入結果，而非要求使用者手動貼資料。

第三階段（評估既有 Layer 去留）：

• 針對 L9 paper-search，評估是否將底層文獻查詢邏輯改接 ToolUniverse 的 PubMed/bioRxiv/arXiv 工具，同時保留 paper-search 現有的 AIKT 客製化輸出格式作為上層包裝，降低雙重維護成本。

不建議的整合方向：

• 不建議把 ToolUniverse 整個包裝成一個新的獨立 AIKT Layer（例如「L28 tooluniverse」）。ToolUniverse 更適合以「被多個既有 Layer 呼叫的共用底層能力」的形式存在，而不是又一個獨立入口——這樣才不會製造「使用者該用哪一個 Layer 查科學資料」的選擇困擾，也符合 AIKT 全域規範「消除特殊情況優先於增加例外分支」的簡化原則。

6.5 風險與需要使用者決策的開放問題

誠實列出這份分析尚無法自行下判斷、必須交由使用者決策的項目（依 AIKT 全域規範「無法確認時明確指出缺口，不把推測寫成事實」）：

2. API Key 的集中管理：若深度整合，NCBI/NVIDIA/BioGRID/DisGeNET 等多個 API Key 應該放在 AIKT 現有的 .env 集中管理，還是讓 ToolUniverse 用自己的 .env.template 獨立管理？兩者都可行，但涉及 AIKT 現有機密管理慣例是否要擴充覆蓋範圍。
3. 成本控制：Agentic Tools 呼叫 LLM 需要額外的 API 額度消耗，若 tu-plan-generator 等 Layer 頻繁觸發，需要先估算大概的呼叫頻率與對應的月費影響，避免整合後才發現成本超出預期。
4. 既有 paper-search 的實際重疊程度：§6.2 的紅海分析是基於官方文件描述的功能比較，尚未實測 paper-search 目前串接的具體資料庫清單與 ToolUniverse 文獻工具是否 100% 重疊——建議在真正決定 retire/降級 paper-search 之前，先做一次逐項核對，而不是僅憑本文件的定性判斷就執行。

7. 效能、限制與替代方案 (Performance, Limitations & Alternatives)

7.1 效能數據與觀察

• 工具規模：本地程式碼盤點約 633 個 _tool.py 實作檔案，對應約 520 個工具定義 JSON 檔案，總計約 2201 個可呼叫工具（官方對外文案標示「1000+」，屬保守行銷數字，實際規模已超過此數）。
• Context 節省：官方宣稱 Compact Mode 能節省約 99% 的 context window 用量（從攤開全部工具 schema，縮減到只暴露 5 個元工具）。
• 快取加速：官方文件宣稱「兩層快取」能達到 10 倍加速（重複查詢情境）；一次性、每次都是新查詢條件的場景則無法從快取受益。
• 啟動速度：懶載入機制（_lazy_registry_static.py）讓啟動時不需要 import 全部 2200 個工具模組，官方 CLI 另外用 TOOLUNIVERSE_LIGHT_IMPORT 環境變數跳過 MCP/fastmcp 等重量級 import，宣稱單次 CLI 呼叫可省約 480ms。
• 版本活躍度：pyproject.toml 顯示版本號 1.3.1，配合 GitHub Actions 中的 weekly-tool-healthcheck.yml（每週自動健檢所有工具是否還能正常呼叫）、auto-release.yml（自動發版），顯示這是一個持續有人維護、對「工具會不會悄悄壞掉」有系統性防範的專案，而不是發布後就無人問津的展示型 repo。

7.2 已知限制

1. 工具品質不一致：2200+ 個工具是社群/團隊持續累積的成果，各工具背後對接的第三方 API 穩定性、文件完整度、回應速度天差地別——查 PubMed 這種成熟大型資料庫通常很順，查一些小眾/冷門資料庫的工具可能較常遇到上游服務不穩定的狀況（.github/known_failing_categories.txt 這個檔案的存在本身就說明官方也已知有一部分工具類別會週期性失敗）。
2. 依賴外部服務可用性：多數工具是薄封裝在第三方公開 API 上，ToolUniverse 本身不擁有底層資料，任何一個上游資料庫改版/停機/調整 rate limit，都可能直接影響對應工具的可用性，這是所有「聚合型」工具庫的通病，非 ToolUniverse 獨有。
3. 部分工具需要付費/申請制 API Key：如 DisGeNET、OMIM 需要學術審核，NVIDIA NIM 工具需另外的 GPU 額度，並非「裝完就全部工具都能用」，需要使用者依需求逐步申請。
4. 重度依賴套件相對繁重：pyproject.toml 列出的依賴包含 playwright、faiss-cpu、markitdown[all] 等相對重量級套件，全裝下來的環境體積不小，對只想用少數幾個工具的使用者而言略顯「殺雞用牛刀」。
5. Agentic Tools 品質依賴所接的 LLM：假說生成、文獻摘要類工具的產出品質，本質上受限於使用者自己設定的 LLM API（OPENAI_API_KEY 等），ToolUniverse 本身不提供品質保底。
6. 不是真正的「AI 科學家」，而是科學家的工具箱：專案命名容易讓人誤以為裝了就能自動做科學研究，但實際上決策、假說驗證、實驗設計的最終判斷仍需要人類專家或另一層 Agent 邏輯（如 TxAgent）來編排——ToolUniverse 提供的是「能力」，不是「智慧」。
7. 中文文件雖有涵蓋但深度有限：雖然有語言切換機制與 WeChat 社群，核心技術文件（API Reference、工具 schema 說明）主要仍是英文為主，中文使用者在深入除錯時仍需要能讀英文技術文件。
8. 本地端資源消耗隨載入工具數量增加：即使有懶載入優化，若使用情境需要同時大量使用不同類別工具（例如同時做基因體 + 化學 + 臨床試驗查詢），記憶體與磁碟快取占用會隨之增加，長期運行的伺服器模式需要留意資源監控。

7.3 與同類工具比較

7.4 何時使用 vs. 何時不使用

適合使用 ToolUniverse 的情境：

• 需要一次串接大量異質科學資料庫，且不想為每個資料庫分別寫整合程式碼
• 使用對話式 AI 助理（Claude/Cursor/Codex 等）做研究輔助，希望它能查真實科學資料，而不是憑訓練記憶瞎猜
• 需要建立可重現、可快取的科學查詢管線
• 需要平行處理多個長時間科學計算任務（結構預測、對接模擬）

不適合/需謹慎使用的情境：

• 需要對單一資料庫做非常深度、涵蓋所有進階查詢參數的整合（此時直接用該資料庫官方 SDK 可能更完整）
• 極度隱私敏感的資料查詢（病人層級資料），需要先確認每個涉及的第三方工具是否符合機構的資料治理與法規要求
• 資源受限環境（極輕量裝置、極嚴格的網路出口管控），因為多數工具依賴對外連線
• 已有穩定、經過驗證的自建整合，且切換成本高於維持現狀的收益時，不必為了「用新東西」而貿然置換

8. 總結與建議 (Summary & Recommendations)

8.1 關鍵要點回顧

1. ToolUniverse 是一個把 2200+ 個科學資料庫/模型/API 統一包裝成標準化「工具」的基礎設施專案，核心貢獻是 AI-Tool Interaction Protocol 這個標準化互動協議。
2. 最重要的工程創新是 Compact Mode——用 5 個元工具取代直接攤開 2200+ 個工具 schema，解決了「工具數量增長 vs. context window 有限」的根本矛盾，這個思路值得任何要接大量工具的 Agent 系統借鏡。
3. 三種工具發現策略（keyword/embedding/llm）與雙層快取系統，展現了在「速度、成本、理解深度」之間做權衡設計的成熟度。
4. TxAgent 與 Medea 兩個下游應用證明 ToolUniverse 不是自我展示的玩具，而是被真實重複使用的共享基礎設施。
5. 對 AIKT 而言，ToolUniverse 定位是「科學資料存取層」，AIKT 定位是「知識工作流編排層」——兩者的正確關係是垂直互補，不是水平競爭。唯一的紅海地帶是 AIKT 若持續自建單一科學資料庫的 API 整合，這條路線應立即停止，改為評估直接接 ToolUniverse。

8.2 最佳使用場景

• 藥物研發初篩階段的多資料庫快速摸底（化學結構 + 文獻 + 安全性 + 臨床試驗現況一次查完）
• 精準醫療場景中，對特定基因變異快速查詢致病性、已知治療關聯
• 建立需要長期可重現、可稽核的科學查詢管線（受惠於其快取指紋機制）
• 任何已經在用 Claude/Cursor/Codex 等 MCP 相容客戶端的研究團隊，想低成本擴充「AI 助理能查真實科學資料」的能力
• 需要用 Agentic Tools（假說生成、實驗設計評分）輔助研究早期發想階段，但仍保留人類專家做最終判斷的工作流
• 教學/訓練情境：讓學生/新進研究人員透過自然語言就能操作原本需要熟悉一大堆資料庫查詢語法才能上手的科學資源，降低入門門檻

8.3 不建議依賴 ToolUniverse 的情境（風險提醒彙整）

彙整第 7 章的限制分析，以下情境建議謹慎評估後才決定是否採用：

• 法規遞交等對數據來源可追溯性要求極高的正式文件（如真正送交 FDA 的 IND/NDA 文件），第三方聚合工具查回的數據仍需回溯確認原始資料庫版本與查詢時間，不能只憑 ToolUniverse 回傳結果直接引用而不做二次核實
• 涉及病患層級隱私資料的查詢，需要先由機構的資料治理/法務部門確認是否符合 HIPAA 或當地個資法規要求，不應假設「開源工具＝合規」
• 對回應時間有嚴格 SLA 要求的生產環境服務，因為底層仍依賴多個第三方 API 的可用性，難以保證端對端的服務等級協議

8.4 未來發展方向觀察

從 GitHub Actions 工作流（weekly-tool-healthcheck.yml、auto-release.yml、publish-mcp-registry.yml、sync-api-keys.yml）可以看出專案正朝著「工業化維運」方向發展——不只持續加新工具，也建立了自動健檢、自動發版、MCP Registry 上架、API Key 自動同步等維運機制，代表團隊已經意識到「工具規模一旦破千，最大挑戰不是新增工具而是維持既有工具不悄悄壞掉」。這對評估是否長期依賴這個專案的團隊是正面訊號——顯示背後有制度化的品質保證流程，而非單純堆規模。

對 AIKT 而言，建議的下一步不是等一份完整規格文件，而是先做本文件 §6.4 第一階段建議的低成本驗證（tu-bridge 轉存腳本），用實際跑過 3-5 個查詢場景的結果，決定是否值得投入第二階段的深度整合——這符合 AIKT 全域「先問這是真問題還是想像的、有沒有更簡單的方法」的任務處理原則。