整合 Scout
Scout 提供 FactVerse 網頁、平台 MCP 與 REST API 三種存取方式。網頁適合人工調查與審閱；MCP 適合在 AI 用戶端中呼叫受治理的 Scout 工具；REST API 適合應用整合與自動化。
選擇整合方式
| 方式 | 適用情境 | 驗證方式 |
|---|---|---|
| FactVerse 網頁 | 建立任務、審閱證據、核准與發布 | 平台使用者登入 |
| 平台 MCP | 讓外部 AI 用戶端讀取任務並呼叫授權工具 | 平台 MCP 憑證與 X-API-Key |
| REST API | 將 Scout 操作連接到業務系統或自動化程式 | 部署環境提供的平台憑證 |
所有方式共用同一租戶、任務、權限與稽核紀錄。精確請求欄位以目前環境傳回的工具定義或 API 說明為準。
前提條件與輸入
- FactVerse 主機位址與目標租戶
- 已啟用的 Scout 與平台 MCP 能力
- 綁定有效帳號、用途與最小權限的平台憑證
- 業務問題、設備或資料集範圍
- 由授權服務取得的任務與資源識別資訊
先使用唯讀存取列出能力與任務，確認用戶端連接到預期租戶。
連接 MCP 用戶端
使用支援遠端 MCP Streamable HTTP 並可設定請求標頭的用戶端。Scout 端點為：
https://your-factverse-host/mcp/scout/
- 請租戶管理員簽發平台 MCP 憑證。首次驗證建議使用
READ用途與scout.read範圍。 - 在用戶端中加入遠端 MCP 服務；私有部署填寫客戶環境的平台位址。
- 在受保護設定中加入請求標頭
X-API-Key，值為平台 MCP 憑證。 - 連接後重新整理工具清單，依序呼叫
scout_capabilities、scout_mission_list與scout_mission_get。 - 核對傳回的任務、設備、來源選項與租戶資訊。
| 工具 | 用途 |
|---|---|
scout_capabilities | 查看可用流程、業務目標與授權來源選項 |
scout_mission_list | 分頁列出目前租戶的 Scout 任務 |
scout_mission_get | 查看所選任務的階段、阻塞項目、下一步與證據參照 |
工具輸入以用戶端顯示的定義為準。任務清單為空表示目前查詢範圍沒有可見任務，可回到網頁建立任務或請管理員檢查權限。
指派憑證用途
| 工作責任 | 憑證用途 | Scout 權限範圍 |
|---|---|---|
| 查看任務與證據 | READ | scout.read |
| 建立任務、調查與驗證 | OPERATOR | scout.read、scout.write |
| 審閱發布證據 | APPROVER | scout.read、scout.approve |
| 套用已核准發布或執行支援的復原 | DEPLOYER | scout.read、scout.deploy |
平台還會檢查帳號狀態及相關資料、MDM、模型與 DFS 權限。對需要職責分離的發布流程，應為核准者與發布操作員分別設定存取。
範例：調查設備訊號
可以向 AI 用戶端提出：
檢查這台馬達最近一週的振動、溫度與電池資料。確認實際設備、X/Y/Z 方向、量測類型與單位，先列出依據和待確認問題，再提出配對建議。
- 呼叫
scout_capabilities查看可用流程與業務目標。 - 使用
scout_mission_list找到任務，再用scout_mission_get查看範圍與目前階段。 - 依工具定義調查已授權來源，查看候選依據。
- 補充設備手冊、安裝紀錄或欄位負責人確認。
- 在相應角色下完成候選審閱、驗證、核准與發布。
- 檢查指定時間範圍的實際讀值與應用結果。
範例：審閱業務資料交付
依已發布業務目標檢查這批授權資料。識別資料集，提出欄位含義與身分鍵建議，檢查重複紀錄與關係，並列出需要業務審閱者確認的定義。
使用能力介面選擇業務目標與授權來源，依任務流程完成盤點、剖析、欄位與 MDM 決策、試執行、核准與發布。週期性交付先與目前生效版本比較，詳見後續批次交付。
REST API 端點
以下路徑相對於 FactVerse 主機。資源識別資訊應來自目前租戶的授權回應。
| 方法與路徑 | 用途 |
|---|---|
GET /api/v1/scout/missions | 列出任務 |
GET /api/v1/scout/missions/{missionId} | 讀取任務 |
POST /api/v1/scout/missions/{missionId}/discovery | 啟動探索 |
GET /api/v1/scout/missions/{missionId}/semantic-model-proposals/options | 取得模型草稿、設備、屬性與相容類別選項 |
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals | 提交模型提案供審閱 |
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals/{id}/review | 記錄模型提案決策 |
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals/{id}/apply-to-draft | 將已核准提案套用到模型草稿 |
POST /api/v1/scout/missions/{missionId}/semantic-execution/dry-runs | 驗證模型與參照發布計畫 |
模型相關介面還需要相應的模型、MDM 與 DFS 權限。草稿變更套用後，繼續使用獨立的發布核准與執行流程。
處理重試與錯誤
要求 Idempotency-Key 的介面，應為同一邏輯請求與相同內容重複使用同一識別資訊。逾時後先讀取操作狀態，再重試服務明確支援的等冪動作。
| 回應 | 處理方式 |
|---|---|
| 401 | 更新或恢復平台驗證 |
| 403 | 檢查租戶、模組、動作與相關資料權限 |
| 404 | 使用目前租戶傳回的資源識別資訊重新查詢 |
| 409 | 讀取最新版本，重新驗證並審閱 |
| 429 | 依回應要求退避 |
| 逾時或服務錯誤 | 查詢現有操作狀態，保留請求關聯資訊 |
輪換用戶端憑證
- 簽發綁定適當帳號、用途與權限的新憑證。
- 使用
scout_capabilities和scout_mission_list驗證唯讀存取。 - 更新用戶端受保護的
X-API-Key設定並重新連接。 - 撤銷舊憑證，確認新舊憑證的存取結果符合預期。
- 記錄憑證標籤、負責人、用途與輪換日期。
平台 MCP 憑證與模型提供商憑證分別管理。發現憑證洩漏或人員離職時，應依客戶安全流程及時撤銷存取。