BioDiscoveryAgent 完整教學

Repository: https://github.com/snap-stanford/BioDiscoveryAgent Stars: 113 | Forks: 26 | Language: Python | License: MIT 最後更新: 2026-07-12 | 論文: arXiv:2405.17631

1. 專案概覽 (Project Overview)

1.1 這是什麼

BioDiscoveryAgent 是一個由 大型語言模型 (LLM; Large Language Model) 驅動的 AI 代理人 (AI agent; 人工智慧代理人)，用途是自動設計 基因擾動實驗 (genetic perturbation experiment; 基因擾動實驗)。簡單講，它要回答的問題是：

「在一個有上萬個基因的細胞系統裡，如果我只能做幾輪、每輪只能測試一小批基因的濕實驗 (wet-lab experiment; 濕實驗)，該怎麼選基因，才能最快找到真正會影響某個生物表型 (phenotype; 表型) 的『命中基因 (hit gene; 命中基因)』？」

這件事在濕實驗室裡的專有名詞叫 CRISPR 篩選 (CRISPR screen; CRISPR 基因篩選)——用 CRISPR 系統對成千上萬個基因逐一「敲掉」或「激活」，看哪些基因的變化會顯著影響某個可測量的表型（例如細胞分泌的 IFN-γ 濃度、IL-2 濃度、細胞存活率等）。全基因組篩選 (genome-wide screen; 全基因組篩選) 一次要測試近 2 萬個基因，成本極高、耗時極長。BioDiscoveryAgent 的目標是把這個過程變成一個 閉環實驗設計 (closed-loop experimental design; 閉環實驗設計)：AI 先根據先驗知識挑一批候選基因 → 「虛擬做實驗」拿到（模擬的）結果 → 根據結果反思、調整策略 → 再挑下一批基因，反覆迭代，用遠低於全基因組篩選的預算，逼近全篩選才能找到的命中基因集合。

1.2 研究團隊與動機

本專案由 Stanford SNAP 實驗室 (Stanford Network Analysis Project; 史丹佛網路分析計畫)——Jure Leskovec 教授團隊——與 Percy Liang（Stanford CRFM/HELM 團隊）、Alexander Marson（免疫學/CRISPR 篩選專家，UCSF/Gladstone）合作完成，一作為 Yusuf Roohani。這個組合很關鍵：SNAP 提供圖與 AI agent 方法論，CRFM 提供 LLM 評測基礎設施（HELM），Marson 實驗室提供真實的免疫學 CRISPR 篩選資料集（IFNG、IL2 等出自其發表的篩選論文）。

動機在論文標題就講得很白：“An AI Agent for Designing Genetic Perturbation Experiments”——用 LLM 取代（或輔助）人類專家「憑經驗、憑文獻直覺挑基因」的角色，因為：

1. LLM（如 Claude、GPT-4）已經在預訓練中吸收了大量生物學文獻知識，天生具備「像資深研究員一樣聯想相關基因」的能力。
2. 傳統的主動學習 (active learning; 主動學習) 方法需要先有一些標記資料才能訓練代理模型；LLM agent 可以在零筆或極少筆歷史資料的情況下，靠先驗知識做出合理的第一輪猜測（這叫 冷啟動 (cold start; 冷啟動) 優勢）。
3. 把文獻檢索、基因資料庫查詢、基因相似度計算等「工具」交給 agent 自主決定何時呼叫，模擬人類科學家「查資料、想一想、再下判斷」的完整流程。

1.3 解決的問題與重要性

• 問題本質：這是一個典型的 組合優化 + 序列決策 (sequential decision making; 序列決策) 問題——在巨大的離散搜尋空間（~2 萬基因，或基因兩兩配對時是 C(2萬,2) 量級）中，用有限輪次的「查詢-回饋」找到高價值子集。
• 為什麼重要：CRISPR 篩選是現代藥物標靶發現 (drug target discovery; 藥物標靶發現) 的核心方法之一；每一輪濕實驗可能花費數週和數萬美元。如果 AI agent 能把「找到 80% 命中基因所需的實驗輪數」從 10 輪降到 5 輪，對整個藥物研發 pipeline 的時間與成本節省是實質的。這與 AIKT 系統中 L19 tu-plan-generator（藥物開發計畫生成）所服務的場景高度相關——都是「用電腦運算縮短濕實驗迭代週期」。

1.4 在 snap-stanford 生態系中的定位

SNAP 實驗室的開源專案大致分三類：（a）圖神經網路 / 圖表示學習核心方法（如 PyG 前身、GraphSAGE）、（b）生物醫學圖譜應用（如 PrimeKG、TxGNN）、（c）LLM agent 應用（本專案、STORM 等）。BioDiscoveryAgent 屬於第三類，是 SNAP 把「圖 + 生物知識」的傳統強項，與新一代 LLM agent 範式結合的代表作之一——它大量呼叫 Reactome（生物通路資料庫，本質是圖結構）、基因共表現網路等「圖式知識」作為 agent 的外部工具。

2. 核心架構 (Core Architecture)

2.1 系統資料流

flowchart TB
    A["研究問題 Prompt
(task_prompts/*.json)"] --> B["Research Assistant
(research_assistant.py)"]
    B --> C{"LLM 決策
Claude / GPT-4"}
    C -->|"1. Reflection"| D["反思前一輪結果"]
    C -->|"2. Research Plan"| E["更新研究計畫"]
    C -->|"3. 工具呼叫 (可選)"| F["工具層 tools.py"]
    C -->|"4. Solution"| G["提出下一批候選基因"]

    F --> F1["get_lit_review
(文獻檢索)"]
    F --> F2["gene.py 工具集
(OpenTargets/Reactome/KEGG)"]
    F --> F3["get_similar_genes
(achilles.csv 相似基因)"]
    F --> F4["critique
(AI 自我批評)"]
    F -->|"工具回傳結果"| C

    G --> H["模擬濕實驗
(datasets/ground_truth_*.csv)"]
    H --> I["回傳表型量測值
(measurement)"]
    I --> B
    B -->|"steps 次迭代後"| J["sampled_genes_N.npy
累積候選基因清單"]
    J --> K["analyze.py
計算 hit rate"]

2.2 關鍵模組說明

2.3 設計哲學與技術選擇分析

(1) Prompt 即架構 (Prompt-as-Architecture)。 這個專案沒有訓練任何神經網路，整個「智能」都封裝在 research_assistant.py 頂部那一串 initial_prompt_* 字串模板裡。每種變體（基礎版 / 帶基因搜尋版 / 帶通路搜尋版 / 帶 RNA 表現版 / 基因對版）對應一個不同的 prompt 模板，強制 LLM 用固定格式回答（1. Reflection / 2. Research Plan / 3. Solution）。這是典型的 ReAct 風格 agent (Reasoning + Acting; 推理與行動交錯)：先讓模型「說出思考過程」，再抽取其中結構化的「行動」部分（要測試的基因清單、或要呼叫的工具）。

好處：完全不需要 fine-tune，換一個更強的 LLM（例如把 --model claude-v1 換成 claude-3-5-sonnet-20240620）馬上就能提升效果，因為所有生物學知識都來自 LLM 的預訓練，而非資料集學習。

代價：高度依賴 prompt 格式的穩定輸出——tools.py 裡 parse_action_input() 用正則表達式硬解析 LLM 輸出，模型稍微「不聽話」就會解析失敗（程式碼裡看得到大量被註解掉的舊版 JSON 解析嘗試，顯示作者們也踩過這個坑）。

(2) 工具可插拔、實驗可組合。 --lit_review、--critique、--reactome、--gene_search 這些 CLI flag 各自獨立開關，對應論文中的消融實驗 (ablation study; 消融實驗)——用來回答「文獻檢索工具到底有沒有幫助？」「AI 自我批評機制有沒有用？」這類問題。這種「先把 baseline 跑通，再逐一疊加工具做 A/B」的設計，是做 agent 研究時值得學習的模式。

(3) 離線模擬濕實驗，而非真的连線機器人實驗室。 這點很多人會誤解——BioDiscoveryAgent 目前不是直接控制機器人做 CRISPR 篩選，而是拿「已經做過的篩選」的完整結果當作模擬環境：agent 猜的基因如果剛好落在資料集裡，就回傳真實量到的表型值；如果沒被猜到，該基因當輪就沒有資料回饋。這是做閉環實驗設計研究常見的「retrospective simulation（回溯模擬）」手法，允許在沒有真實濕實驗室的情況下,大量重複跑迭代實驗來評估 agent 策略優劣。

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

3.1 環境需求

• Python：3.10（README 建議版本；3 系列皆可但建議 3.10）
• GPU：非必要——所有運算是 API 呼叫 + CSV/文字處理，CPU 即可跑
• 磁碟空間：至少 300MB 可用空間（achilles.csv 基因特徵檔案，若使用 --gene_search True 會自動從 Figshare 下載）
• API 金鑰：Claude API（必要，agent 骨幹模型預設用 Claude）；如需跑 OpenAI 版本則另需 OpenAI API key

依照本機 CLAUDE.md 規範，Python 套件安裝優先使用 uv；以下指令保留專案原生 pip 寫法對照，實務操作建議改用 uv pip install 或建立 uv venv。

3.2 完整安裝步驟

 1# 1. clone 專案
 2git clone https://github.com/snap-stanford/BioDiscoveryAgent.git
 3cd BioDiscoveryAgent
 4
 5# 2. 建立隔離環境（依全域規範用 uv，取代原生 pip 安裝）
 6uv venv --python 3.10
 7source .venv/bin/activate
 8
 9# 3. 安裝相依套件（requirements.txt 是專案給的清單）
10uv pip install -r requirements.txt
11
12# 4. 設定 API 金鑰（專案採用「讀取本地文字檔」的方式，非環境變數）
13echo "sk-ant-你的金鑰" > claude_api_key.txt
14# 若要跑 OpenAI 版本，格式是 "organization:api_key"
15echo "org-xxxx:sk-xxxx" > openai_api_key.txt

安全提醒（依全域安全規範）：claude_api_key.txt / openai_api_key.txt 屬於機密檔案，務必加進 .gitignore，切勿提交進版本控制或貼到對話/文件中。專案本身的 .gitignore 未必涵蓋這兩個檔名，建議手動確認：

1echo -e "claude_api_key.txt\nopenai_api_key.txt\ncrfm_api_key.txt" >> .gitignore

3.3 資料集下載與準備

專案內建 5 個現成資料集，皆已附在 datasets/ 目錄，不需另外下載：

若使用 --gene_search True，程式會自動偵測指定目錄下有無 achilles.csv，沒有的話會從 Figshare 自動下載（DepMap Achilles 基因依賴性資料，約需 300MB 空間）：

1python research_assistant.py --task perturb-genes-brief --model claude-3-5-sonnet-20240620 \
2  --run_name test --data_name IFNG --steps 5 --num_genes 128 \
3  --log_dir sonnet_sim --gene_search True --csv_path ./cache/

若要用自己的篩選資料，README 指向 data/ 目錄下的範例（data/schmidt.py、data/screen.py），需自行準備 ground truth CSV 與對應的 task_prompts/*.json（描述任務背景與量測方式）。

3.4 常見問題排解

4. 核心概念詳解 (Key Concepts)

4.1 什麼是「閉環實驗設計」？——用釣魚打比方

想像一座巨大的湖（代表 2 萬個基因），湖裡藏著幾十條特別大的魚（代表真正會影響表型的「命中基因」），但你只能撒有限次數的網，每次網只能撒在有限範圍（一次挑 128 個基因這種規模）。

• 傳統作法（隨機篩選/全篩選）：把整座湖都撒一遍網——保證抓到所有大魚，但成本極高（等於做全基因組篩選）。
• 主動學習作法：先撒幾網，看哪裡撈到魚比較多，用統計模型推測「魚可能聚集」的區域，下一網往那邊撒。
• BioDiscoveryAgent 的作法：找一位「有經驗的漁夫（LLM）」，他雖然沒撒過這座湖的網，但看過很多其他湖的釣魚紀錄（訓練語料裡的生物學文獻），能一開始就合理猜測「這種魚通常在水草多的地方」（即：這種表型通常與哪些已知的生物通路/基因家族有關），撒完網看結果後，還會「反思」調整下一網的策略。

這整個「撒網 → 看結果 → 反思調整 → 再撒網」的過程，就是閉環 (closed-loop)：模型的輸出直接影響下一輪的輸入，形成一個回饋迴圈，而不是一次性預測。

4.2 概念關係圖

flowchart LR
    subgraph sg1["先驗知識來源"]
        P1["LLM 預訓練知識"]
        P2["文獻檢索工具"]
        P3["基因資料庫
(Reactome/KEGG/OpenTargets)"]
        P4["基因表現相似度
(Achilles/RNA-seq)"]
    end

    subgraph sg2["Agent 決策核心"]
        D1["Reflection 反思"]
        D2["Research Plan 計畫更新"]
        D3["Solution 候選基因清單"]
    end

    subgraph sg3["回饋訊號"]
        R1["模擬濕實驗
(ground truth 查表)"]
        R2["Hit / No-hit 結果"]
    end

    P1 --> D1
    P2 --> D1
    P3 --> D1
    P4 --> D1
    D1 --> D2 --> D3
    D3 --> R1 --> R2
    R2 -->|"下一輪 prompt 上下文"| D1

4.3 為什麼要有「多種 prompt 模板」？

research_assistant.py 裡有 initial_prompt（基礎版）、initial_prompt_gene_search（加基因相似度搜尋步驟）、initial_prompt_topk（加相關基因搜尋）、initial_prompt_rna（加組織表現搜尋）、initial_prompt_pathways（加 Reactome 通路搜尋）、initial_prompt_pairs（基因對版本）。這不是重複程式碼，而是每種工具對應一套獨立的輸出格式規範——因為 LLM 是「照格式解析」而非「語意理解後抽取」，工具越多、要求 LLM 額外輸出的欄位就越多（例如要求它先講「Gene Search: <基因名>」再講「Solution」），這是 prompt engineering 中常見的「顯式格式約束優於隱式期待」的做法。

4.4 「基因對 (gene pair)」任務的特殊性

initial_prompt_pairs 與 initial_prompt_pairs_norman 處理的是基因交互作用篩選 (genetic interaction screen; 基因交互作用篩選)——不只測單一基因，而是測「兩個基因同時擾動」的組合效應（例如 Norman et al. 資料集）。這類任務的搜尋空間是 C(n,2) 量級，比單基因篩選大一個數量級以上，因此 prompt 裡直接把候選基因池限縮到一個固定小清單（如 89 個基因），把「從全基因組挑」簡化成「從已知相關的小清單挑組合」——這是把搜尋空間預先用生物學先驗知識壓縮的典型手法。

4.5 Hit Rate 是怎麼算的（直覺解釋）

analyze.py 的邏輯很直接：拿 agent 每輪累積猜過的基因清單（sampled_genes_{round}.npy），和資料集內事先算好的「真正命中基因清單」（topmovers_{dataset}.npy，通常是效應量排名前 N 的基因）取交集：

1命中率 = |Agent 猜過的基因 ∩ 真正命中基因| / |真正命中基因|

如果做「必要基因 (essential gene; 必要基因)」過濾（--essential 1），還會先把兩邊都排除掉 CEGv2.txt 裡列出的「不管做什麼實驗都會有反應的管家基因」，避免這些「太容易猜中」的基因灌水命中率。

5. 使用方式與程式碼範例 (Usage & Code Examples)

5.1 基礎用法：跑一個 5 輪的閉環實驗

1# 用 Claude-3.5-Sonnet 在 IFNG 資料集上跑 5 輪迭代，每輪選 128 個基因
2python research_assistant.py \
3  --task perturb-genes-brief \
4  --model claude-3-5-sonnet-20240620 \
5  --run_name test \
6  --data_name IFNG \
7  --steps 5 \
8  --num_genes 128 \
9  --log_dir sonnet

跑完後，觀察每輪的候選基因是否累積收斂，並用 analyze.py 計算命中率：

1python analyze.py --model sonnet --dataset IFNG --rounds 5

輸出範例（示意）：

1Model: sonnet, Data: IFNG, mean: 0.42, std: 0.03

代表在 5 輪迭代（總計 640 個候選基因）內，找到了資料集真正命中基因清單中約 42% 的命中基因。

5.2 進階用法：開啟全部工具（對照論文完整版設定）

 1python research_assistant.py \
 2  --task perturb-genes-brief \
 3  --model claude-3-5-sonnet-20240620 \
 4  --run_name test \
 5  --data_name IFNG \
 6  --steps 5 \
 7  --num_genes 128 \
 8  --log_dir sonnet_all \
 9  --lit_review True \
10  --critique True \
11  --reactome True

三個 flag 各自的作用：

• --lit_review True：agent 每輪可呼叫 get_lit_review.py，查詢與目前候選基因相關的既有文獻摘要，模擬「先查文獻再下判斷」。
• --critique True：讓 agent 對自己提出的候選清單做一輪「AI 自我批評 (self-critique)」，類似 reflexion 機制，過濾掉明顯不合理的基因。
• --reactome True：允許 agent 呼叫 gene.py 中的 get_gene_to_reactome_pathways()，查詢某基因參與的生物通路，再反向找出同通路的其他候選基因。

5.3 使用相似基因搜尋工具（需下載 Achilles 特徵資料）

 1python research_assistant.py \
 2  --task perturb-genes-brief \
 3  --model claude-3-5-sonnet-20240620 \
 4  --run_name test \
 5  --data_name IFNG \
 6  --steps 5 \
 7  --num_genes 128 \
 8  --log_dir sonnet_sim \
 9  --gene_search True \
10  --csv_path /data/achilles_cache/

5.4 程式碼範例：手動呼叫 gene.py 的基因知識工具（獨立於 agent 使用）

即使不透過完整的 agent 迴圈，gene.py 裡的工具函式也可以單獨當作生物資料庫查詢工具使用，這對想把 BioDiscoveryAgent 的「工具層」抽出來做其他用途的人很有參考價值：

 1# 範例：獨立呼叫 gene.py 的工具函式，查詢單一基因的知識
 2from gene import (
 3    get_gene_info_from_opentarget,
 4    get_gene_to_reactome_pathways,
 5    get_gene_pLI,
 6)
 7
 8gene_name = "IFNGR1"
 9
10# 1. 查詢 OpenTargets 對此基因的整體註解
11info = get_gene_info_from_opentarget(gene_name)
12print(f"[OpenTargets] {gene_name}: {info[:200]}...")
13
14# 2. 查詢此基因參與的 Reactome 生物通路
15pathways = get_gene_to_reactome_pathways(gene_name)
16print(f"[Reactome pathways] {gene_name}: {pathways}")
17
18# 3. 查詢此基因的 pLI 分數（loss-of-function 不耐受機率，數值越接近 1
19#    代表此基因功能喪失突變越不被自然選擇容忍，暗示其重要性）
20pli = get_gene_pLI(gene_name)
21print(f"[pLI score] {gene_name}: {pli}")

5.5 程式碼範例：解析 agent 對話歷史，抽取每輪候選基因清單

tools.py 中的 parse_action_input() 是核心解析函式，理解它有助於除錯「LLM 輸出格式跑掉」的問題：

 1import re
 2
 3def parse_action_input(s, entries):
 4    """
 5    從 LLM 回應文字中，用正則表達式抽出結構化欄位。
 6    entries 例如 ["content"]，代表要抽取 {"content": ...} 這個結構。
 7    """
 8    s = s.split("{")[1].split("}")[0].strip()
 9    pattern = ""
10    for e in entries:
11        pattern += f'"{e}":([\\s\\S]*),\\s*'
12    pattern = pattern[:-4]
13    result = re.search(pattern, s, re.MULTILINE)
14    if result is None:
15        raise Exception("Invalid: " + s)
16    return [r.strip().strip('"') for r in result.groups()]
17
18# 示範：假設某工具呼叫的 action input 長這樣
19sample = 'Action Input: {"gene_name": "TNFRSF9"}'
20print(parse_action_input(sample, ["gene_name"]))
21# 輸出: ['TNFRSF9']

5.6 程式碼範例：自行實作一個簡化版「命中率追蹤」腳本

如果想在每輪迭代當下就即時看到命中率變化（而非跑完全部輪數才用 analyze.py 事後分析），可以這樣寫：

 1import numpy as np
 2
 3def running_hit_rate(sampled_genes_by_round: list[list[str]], topmovers: list[str],
 4                      essential_genes: set[str] | None = None) -> list[float]:
 5    """
 6    輸入：每一輪新增的候選基因清單（list of list），與真正命中基因清單
 7    輸出：累積到第 i 輪為止的命中率序列
 8    """
 9    topmovers_set = set(topmovers)
10    if essential_genes:
11        topmovers_set -= essential_genes
12
13    cumulative = set()
14    rates = []
15    for round_genes in sampled_genes_by_round:
16        cumulative.update(round_genes)
17        effective = cumulative - essential_genes if essential_genes else cumulative
18        hit_rate = len(effective & topmovers_set) / max(len(topmovers_set), 1)
19        rates.append(hit_rate)
20    return rates
21
22# 使用範例
23rounds = [
24    ["TNFRSF9", "ZAP70", "LHX6"],       # 第 1 輪候選
25    ["CD27", "EBF2", "IFNGR2"],          # 第 2 輪候選
26    ["CD3E", "PLCG1", "GRAP2"],          # 第 3 輪候選
27]
28topmovers = ["ZAP70", "IFNGR2", "PLCG1", "CD247", "LCK"]
29
30print(running_hit_rate(rounds, topmovers))
31# 輸出範例: [0.2, 0.4, 0.6]  — 命中率隨輪數遞增

6. 進階應用場景 (Advanced Use Cases)

6.1 真實世界應用案例

1. 免疫治療標靶篩選：IFNG、IL2 資料集本身就是 T 細胞活化相關的免疫學篩選，agent 可用來輔助設計 CAR-T 細胞工程改造中「該敲除哪些基因來增強效果」的實驗優先順序。
2. 藥物標靶驗證的前導篩選：在正式做昂貴的全基因組 CRISPR 篩選前，先用 agent 快速產生一份「高信心候選基因清單」，作為小規模驗證性篩選 (validation screen; 驗證性篩選) 的基因池，降低前期成本。
3. 基因交互作用網路建構：利用 initial_prompt_pairs 模式，探索特定通路內基因兩兩組合的協同/拮抗效應，輔助建構通路內的功能性交互作用圖。

6.2 與其他 snap-stanford 工具的整合可能

• 與 PrimeKG / TxGNN 整合：BioDiscoveryAgent 目前呼叫的是 Reactome、OpenTargets 等外部 API；若替換或補充成 SNAP 自家的生物醫學知識圖譜（PrimeKG），可能提供更一致、更豐富的基因-疾病-藥物關聯資訊，減少多個外部 API 呼叫的延遲與速率限制問題。
• 與圖神經網路方法互補：可以把 agent 產生的候選基因序列，餵給傳統的圖神經網路主動學習模型做交叉驗證，比較「LLM 先驗知識驅動」與「圖結構驅動」兩種策略的命中率差異，這正是論文消融實驗想回答的問題延伸。

6.3 效能調校與最佳實踐

• 模型選擇：--model 直接決定 agent 上限，實務上優先選用指令遵循能力強、格式穩定輸出的模型（避免 parse_action_input 頻繁解析失敗），這與 AIKT 全域規範「模型分級」思路一致——推理密集的科學決策任務用最強模型。
• --num_genes 與 --steps 的權衡：增大單輪候選數（num_genes）能提高單輪命中率，但也更接近全篩選、失去「省成本」的意義；增加輪數（steps）能讓 agent 有更多反思機會收斂，但會拉長總對話上下文長度，增加 token 成本與解析失敗風險——需要依實際實驗預算做網格搜尋。
• 工具開關的邊際效益評估：--lit_review / --critique / --reactome / --gene_search 各自增加 API 呼叫次數與延遲，建議先跑基礎版本建立 baseline 命中率，再逐一開啟工具比較邊際提升，避免無謂疊加所有工具卻拖慢實驗又未必提升效果。

7. 與 AIKT 的關聯分析 (AIKT Integration Analysis)

7.1 此專案可作為 AIKT 的資料來源或分析工具嗎？

可以，而且有兩個明確的切入點：

1. 作為研究資料來源：BioDiscoveryAgent 本身是一篇 arXiv 論文 + 開源程式碼的組合，天生適合被 L9 paper-search（跨資料庫學術搜尋）與 L12 gh-tutorial-qd（GitHub repo → 教學全套）這兩層收錄——事實上，本教學文件本身就是 L12 產出的一個實例。
2. 作為方法論參考：其「LLM agent + 可插拔工具 + 多輪迭代反思」的架構模式，與 AIKT 自身「Agent 編排：平行 subagent 派工」的設計哲學高度相似，可作為未來設計 L18 research-pipeline-v2（多輪迭代研究 pipeline）內部「工具呼叫決策邏輯」的參考範本。

7.2 AIKT 哪些 Layer 可以包裝或編排此專案？

flowchart TB
    subgraph sg1["AIKT 知識擷取層"]
        L2["L2 ai-gh-save
收錄 repo 為知識庫條目"]
        L9["L9 paper-search
收錄 arXiv:2405.17631"]
    end

    subgraph sg2["AIKT 教學產出層"]
        L12["L12 gh-tutorial-qd
(本文件產出路徑)"]
        L15["L15 paper-tutorial
論文精讀教學"]
    end

    subgraph sg3["AIKT 研究/藥物層"]
        L18["L18 research-pipeline-v2
多輪迭代研究框架"]
        L19["L19 tu-plan-generator
藥物開發計畫生成"]
    end

    subgraph sg4["AIKT 治理層"]
        L28["L28 aikt-governance
模型調度/派工判準"]
    end

    L2 --> L12
    L9 --> L15
    BDA["BioDiscoveryAgent
(閉環基因篩選 agent)"] -.收錄.-> L2
    BDA -.論文精讀.-> L9
    BDA -.方法論參考.-> L18
    BDA -.篩選結果.->|"作為候選標靶輸入"| L19
    L18 -.借鏡多工具反思迴圈設計.-> L28

• L2 ai-gh-save / L9 paper-search：直接把此 repo 與其論文收錄進知識庫，供未來查詢「LLM agent 做實驗設計」相關主題時召回。
• L12 gh-tutorial-qd：如本文件，把程式碼架構轉譯為繁中教學，降低團隊內部理解生物資訊 + LLM agent 交叉領域專案的門檻。
• L18 research-pipeline-v2：BioDiscoveryAgent 的「多輪迭代 + 反思 + 工具調用」正是 research-pipeline-v2 「三輪迭代研究」精神的具體案例，可作為 pipeline 設計時「如何讓每輪迭代吸收上一輪回饋」的參考實作。
• L19 tu-plan-generator：若使用者在做藥物標靶探索時，BioDiscoveryAgent 篩出的候選基因清單可以作為 tu-plan-generator 生成藥物開發計畫時的候選標靶輸入來源之一（例如將命中基因清單餵入 ChEMBL 查詢，看是否已有對應化合物）。

7.3 潛在整合場景與價值

• 場景一：文獻+程式碼雙軌收錄。當使用者輸入 gh: https://github.com/snap-stanford/BioDiscoveryAgent 時，L2 收錄程式碼結構；同時若使用者另外提供 arXiv 連結，L9/L10（paper-search + paper-qa-lite）可對論文本身做深度問答，兩者在 AIKT 知識圖譜（L4 graphify）中應建立交叉連結，讓「查詢某個基因篩選方法」時能同時召回論文論述與程式碼實作細節。
• 場景二：作為 L18 pipeline 設計的『他山之石』。BioDiscoveryAgent 的 prompt 模板設計（強制輸出 Reflection/Plan/Solution 三段式）示範了「用嚴格輸出格式約束 LLM 行為」的實務技巧，這可以直接應用在 AIKT 內部任何需要多輪 LLM 決策迴圈的場景（例如 research-pipeline-v2 的每輪迭代 prompt 設計）。
• 場景三：治理層的模型調度借鏡。BioDiscoveryAgent 的 --model flag 讓使用者自由切換 Claude / GPT-4，並在 LLM.py 中對兩種 API 做統一封裝——這與 L28 aikt-governance 的「模型分級調度」理念一致：把「決策邏輯」與「底層模型選擇」解耦，才能在模型迭代升級時保持系統穩定。

8. 優缺點與生態系定位 (Strengths, Limitations & Ecosystem Position)

8.1 核心優勢與創新點

• 零訓練成本啟動：不需要任何監督式訓練，直接用預訓練 LLM 的先驗知識做冷啟動決策，這在生物醫學領域「標記資料稀缺」的常見痛點下特別有價值。
• 工具可插拔、易於消融分析：--lit_review / --critique / --reactome / --gene_search 的獨立開關設計，讓研究者能清楚量化每個工具模組的邊際貢獻，這是很好的實驗設計典範。
• 忠實模擬真實濕實驗的閉環迭代結構：使用真實已發表的 CRISPR 篩選資料做回溯模擬,結果具有可信度，且方法論可以無痛遷移到「真正串接機器人濕實驗室」的場景（把 ground truth 查表換成真實實驗回饋 API 即可）。
• 多資料集覆蓋不同生物系統：五個資料集涵蓋不同的免疫/腺苷訊息通路情境，驗證了方法的泛化能力，而非只在單一資料集上調參過擬合。

8.2 目前限制與改進空間

• 高度依賴 LLM 輸出格式穩定性：parse_action_input() 用正則表達式硬解析，模型格式稍有偏差就會拋出例外，缺乏更 robust 的容錯重試機制（例如用 structured output / function calling API 取代純文字正則解析）。
• 僅限離線回溯模擬，尚未串接真實濕實驗室：目前所有「實驗結果」都來自事先跑好的資料集，agent 尚未在真正的機器人自動化實驗室閉環中被驗證過（這是論文明確點出的未來工作方向）。
• 金鑰管理方式偏舊：直接讀取本地明文檔案（claude_api_key.txt）而非環境變數，不符合現代密鑰管理最佳實踐，使用時務必自行加強 .gitignore 防護。
• 程式碼可讀性有進步空間：tools.py 中留有大量被註解掉的舊版解析邏輯（JSON 解析嘗試），顯示程式碼是研究原型 (research prototype; 研究原型) 性質，尚未經過工程化重構，直接用於生產環境前建議先做程式碼清理與錯誤處理強化。
• 基因對任務的搜尋空間仍需人工預先限縮：initial_prompt_pairs 需要研究者事先給定一個小型候選基因清單，而非讓 agent 從全基因組自由組合，某種程度上仍依賴人類專家的先驗篩選。

8.3 與同領域工具的比較

8.4 適用場景建議

• 適合：預算有限、需要快速產生「高信心候選基因清單」的前導性篩選規劃；需要可解釋推理過程（給實驗室 PI 審閱決策邏輯）的場景；已有既定生物學文獻基礎、想驗證 LLM 能否複現專家直覺的研究性課題。
• 不適合：已具備充分歷史篩選資料、更適合用嚴謹統計主動學習方法的場景（此時傳統貝氏優化可能更穩定精確）；需要嚴格因果推斷保證的正式法規申報用途（LLM 推理過程不具備統計顯著性保證，僅能作為實驗設計輔助而非最終決策依據）。

附錄：快速指令備忘

 1# 基礎跑法
 2python research_assistant.py --task perturb-genes-brief --model claude-3-5-sonnet-20240620 \
 3  --run_name test --data_name IFNG --steps 5 --num_genes 128 --log_dir sonnet
 4
 5# 全工具跑法
 6python research_assistant.py --task perturb-genes-brief --model claude-3-5-sonnet-20240620 \
 7  --run_name test --data_name IFNG --steps 5 --num_genes 128 --log_dir sonnet_all \
 8  --lit_review True --critique True --reactome True
 9
10# 計算命中率
11python analyze.py --model sonnet --dataset IFNG --rounds 5