NCATS ARAX 是做什麼的？
將 ARAX 用作受約束的知識圖譜查詢服務。提交經過審核的 CURIEs 與明確的 Biolink 型別，保留精確的 TRAPI 交換，檢視查詢邊緣繫結與 provenance，並將每個回傳的路徑視為後續驗證的候選項目。
在構建查詢前，請先閱讀 query-contract.md。在解讀儲存的產出、警告、provenance 或部分結果時，請閱讀 output-schema.md。
安全邊界
- 僅使用公開、非敏感的研究問題。即使要求
store=false，ARAX 狀態設施仍可能暴露查詢與呼叫者中繼資料。 - 請勿提交病患資訊、機密研究問題、未發表的化合物計畫或專有目標假說。
- 請勿將回傳的路徑呈現為經過驗證的機制或臨床建議。
- 將零結果報告為「未在這些限制下回傳」，絕不能作為不存在關係的證據。
- 將位置描述為未經分數計算的回應順序，絕不能視為排名。
- 重要的候選項目需另外透過文獻與權威資料庫進行驗證。
工作流程
- 先對自由文字進行正規化，然後審閱並報告建議的 CURIE 與類別。
- 選擇型別的單跳查詢，或兩端點均固定的恰好雙跳查詢。
- 除非使用者明確指定二至五個提供者，否則使用預設的 RTX-KG2 查詢。
- 確認生物醫學查詢是公開的，並選擇一個新的或空的輸出目錄。
- 執行一次客戶端。在失敗或得到空結果後，不得暗中更改提供者選擇或擴展順序。
- 檢視
summary.json以取得受邊界限制的繫結與 provenance，並檢視response.json以取得精確的 TRAPI payload。 - 在 ARAX 之外驗證科學上重要的路徑。
預檢
在不進行生物醫學查詢的情況下檢查生產 OpenAPI：
python skills/ncats-arax/scripts/arax_client.py preflight
客戶端會驗證服務是否標示為 ARAX、是否暴露 /query 端點，以及是否報告支援的 TRAPI 版本。非生產端點或未測試的 TRAPI 系列需要明確的覆寫；任何覆寫都不會改變固定的查詢形狀或操作。
實體正規化
正規化僅供審閱，絕不觸發圖譜查詢：
python skills/ncats-arax/scripts/arax_client.py normalize "primary myelofibrosis" \
--expected-category biolink:Disease \
--max-synonyms 10 \
--acknowledge-public-query \
--output-dir outputs/normalize-myelofibrosis
在使用 CURIE 前，請審閱規範識別碼、名稱、類別與同義詞預覽。無論查詢結果如何，均需報告所有 CURIEs 與類別。類別警告或零結果是應整理識別碼的緣故，而非自動串接至 /query。
單跳查詢
至少固定一個端點，並為兩個節點指定型別：
python skills/ncats-arax/scripts/arax_client.py one-hop \
--subject-id CHEBI:31690 \
--subject-category biolink:SmallMolecule \
--predicate biolink:affects \
--object-id NCBIGene:25 \
--object-category biolink:Gene \
--qualifier biolink:object_aspect_qualifier=activity_or_abundance \
--qualifier biolink:object_direction_qualifier=decreased \
--acknowledge-public-query \
--output-dir outputs/imatinib-abl1
查詢模式是預設值，並將擴展固定為 infores:rtx-kg2。預設回傳 20 筆結果。使用 --result-limit N 可要求 1-50 筆結果；50 是兩種模式中的硬上限。
端點固定的雙跳查詢
使用恰好一個有型別、未固定的中間節點：
python skills/ncats-arax/scripts/arax_client.py two-hop \
--subject-id CHEBI:66901 \
--subject-category biolink:SmallMolecule \
--predicate-1 biolink:affects \
--intermediate-category biolink:Gene \
--predicate-2 biolink:associated_with \
--object-id MONDO:0009061 \
--object-category biolink:Disease \
--qualifier-1 biolink:object_aspect_qualifier=activity_or_abundance \
--qualifier-1 biolink:object_direction_qualifier=increased \
--expand-order right-first \
--acknowledge-public-query \
--output-dir outputs/ivacaftor-cystic-fibrosis
先右擴展是預設值。如果空結果值得再嘗試一次，請明確使用 --expand-order left-first 執行新的查詢，並保持各次執行分開。
選定提供者的聯合查詢
聯合是明確的，且接受二至五個命名提供者：
python skills/ncats-arax/scripts/arax_client.py one-hop \
--subject-id CHEBI:31690 \
--subject-category biolink:SmallMolecule \
--predicate biolink:affects \
--object-id NCBIGene:25 \
--object-category biolink:Gene \
--mode federated \
--kp infores:rtx-kg2 \
--kp infores:molepro \
--acknowledge-public-query \
--output-dir outputs/federated-imatinib-abl1
聯合查詢預設使用硬上限 50 筆結果。提供者錯誤可能與有用的結果共存；此類執行會以退出碼 7 結束，保留其產出並標記為部分結果。
檢視已儲存的 Provenance
在不使用網路的情況下重建受邊界限制的摘要：
python skills/ncats-arax/scripts/arax_client.py summarize \
--request outputs/ivacaftor-cystic-fibrosis/request.json \
--response outputs/ivacaftor-cystic-fibrosis/response.json \
--format text
檢視器僅接受與即時指令所產生之相同受約束的查詢形狀與固定操作。使用 --format json 可取得標準輸出的正規化檢視。
解讀結果
- 跟隨每個分析的查詢邊緣繫結；請勿總結每個知識圖譜邊緣。
- 保留 ARAX 回傳的物理邊緣主詞、謂詞、受詞與修飾詞值。回傳的謂詞或修飾詞面向可能比查詢約束更具體。
- 檢視所有來源物件，包括 primary、aggregator、supporting-data、upstream-resource 與 source-record URL 欄位。
- 將
publication_availability: not_returned視為遺失的中繼資料，而非不存在文獻的證據。 - 將缺少的輔助圖譜參考與提供者失敗視為明確的警告。
- 每當受邊界限制的摘要省略細節，或服務回應是部分、不熟悉或科學上令人驚訝時，請查閱原始回應。
故意排除的功能
客戶端不具備原始查詢、工作流程、操作、疊加、排序、推論、鏈路預測、Pathfinder、ARS、批次處理、所有提供者、三跳、快取、守護程式、SDK、MCP 或自然語言轉 TRAPI 的表面。請勿透過此技能以直接 HTTP 呼叫繞過這些限制。