Guidant AI v1.22.0 Release Note¶
| 項目 | 內容 |
|---|---|
| 版本 | 1.22.0（功能版號；主軸＝AI 閘道與檔案沙箱——小幫手、儀表板、證據分類三支 AI 功能全部走同一道守門，證據檔改在沙箱裡拆，另加 AI 用量紀錄與額度管理） |
| 發布日期 | 2026-09-30 |
| 上一版本 | 1.21.0（2026-09-28） |
| 涵蓋區間 | 2026-09-28 ~ 2026-09-30（BE 712fb5b64..354ba4039，105 commits：docs 64／feat 23／fix 7／chore 6／test 2／build 2／merge 1；FE 50bda00..HEAD 28 commits：feat 15／fix 10／style 2） |
| 涵蓋需求 | FR-122 AI 閘道與檔案沙箱（三階段：共用守門、沙箱拆檔與背景工作、用量紀錄與額度） |
| 規模 | jedi-* 套件新增 1 支（jedi-ai-gateway 0.1.0）、升版 5 支；主線 DB migration 新增 6 支（結構類 3 支、資料類 3 支，全部已進出貨基線）；新服務 2 個（guidant-worker、guidant-sandbox），退役 1 個（guidant-classifier） |
| 適用部署 | 先上 190 e2e 測試機驗升級，放行後依序 188 STG → 189 POC（install.sh --upgrade） |
| 部署性質 | 服務組成有變：多兩個容器、少一個容器；正式模式缺 AI 金鑰加密鑰或守門模型檔會拒絕啟動。主機記憶體建議 16 GB 起 |
0. 發版前回歸 gate¶
比照 v1.21.0，本版不跑 site-regression 自動回歸（出版前回歸測試重整仍在排隊）。把關方式：每張 FR-122 卡由 runner 實跑驗證＋首腦開檔抽查；決策者在 DEV 逐項手測守門（遮機敏、擋私鑰、擋索取密碼、擋下 SQL、離題、疑似注入）、額度黃條與用量頁；六支 jedi 套件改吃 Nexus 新版後跑各自測試。第 7.1 節列的三條容器項要在 STG 驗。
1. 概述¶
v1.21.0 之後這版只做一件事：把系統裡所有呼叫 AI 模型的地方收到同一道閘道後面。
- 送出去之前：遮掉機敏資料、擋私鑰與「幫我拿密碼」「幫我下 SQL」這類請求、離題問題回固定說明、疑似注入攻擊的內容打上警告。
- 證據檔不再由後端直接打開，改交給一個沒有 AI 金鑰、連不到外網的沙箱容器拆檔，拆完的文字才進閘道。
- 每一次 AI 呼叫都留紀錄，管理員看得到誰、什麼時候、用了多少；可以對租戶與個人設美金上限與每分鐘次數。
2. 使用者可見變更¶
標「操作會變」的是使用者畫面或流程會有感的地方，升級後要特別看。
2.1 三支 AI 功能共用同一道守門¶
- 遮機敏：送給模型前，內容裡的機敏資料會被換成代稱再送出。
- 直接擋下：內容含私鑰（PEM）、要求系統交出密碼或憑證、要求代為下 SQL 指令，一律不送出，回固定說明。操作會變：以前模型可能照答的這類問題，現在會被擋並告知原因。
- 離題：跟合規稽核無關的問題回固定說明，不耗用額度。
- 疑似注入：內容看起來在指揮模型「忽略前面的指示」之類的，會標出警告；「標記」級照送不擋（純紀錄），「擋下」級不送。
2.2 小幫手¶
- 定位改為合規稽核助理：合規領域知識（ISO 27001、NIST、個資法等）可以直接答，不必侷限於系統操作說明；ISO 27001 未指明版本時預設 2022 版。
- 操作會變：與合規無關的閒聊會回固定說明。
2.3 AI 儀表板¶
- 產生前先判斷意圖：只有「看資料」類問題會產生儀表板；要求做操作（改資料、刪東西）或與系統無關的問題會被擋下，並說明原因。操作會變：以前會產生奇怪結果的問法，現在直接收到說明。
2.4 證據自動分類¶
- 證據檔改由沙箱拆檔：檔案裡藏字（白底白字、極小字）或疑似注入攻擊的，分類結果改成「待人工審」不自動套用；含私鑰的檔案直接擋。
- 審閱頁改版：改為「一條待辦線」版面，由上而下依序處理；新增「已人工確認」狀態。操作會變：審閱頁版面與操作位置都不同。
- 分類工作改到背景工作服務跑（見 2.6），前端送出後會看到排隊中→處理中→完成。
2.5 新頁面：AI 用量、AI 額度¶
- AI 用量（系統設定群組）：列出每一次 AI 呼叫（誰、哪個功能、時間、token 數、估計費用、守門結果），可匯出 xlsx；另有用量彙總。紀錄不存問答原文，只存雜湊與字數（租戶「完整保留」開關尚未做）。需要
ai-call-log.read權限。 - AI 額度：設定租戶與每人的美金上限（日／月）、每人每分鐘次數；平台管理員可替租戶設上限。用到 80% 時畫面出現黃色提示條，超過上限的呼叫會被擋下。需要
ai-quota.read／ai-quota.update權限，ai-quota.update預設只授予管理員角色。 - 升級時兩個頁面的權限依既有角色自動補上（見第 4 節）。
2.6 關於頁¶
- 新增「Built with Llama」標示（守門模型用到 Llama 系列）。
3. Breaking Changes（落地版部署面）¶
- 新服務
guidant-worker：背景工作服務，證據分類在這裡跑。沒起來的話分類單會一直停在「排隊中」且不報錯。 - 新服務
guidant-sandbox：純拆檔、沒有 AI 金鑰、不出外網，取代guidant-classifier（升級後舊容器移除）。 - 正式模式啟動檢查：缺
AI_PROVIDER_ENCRYPTION_KEY或守門模型檔，後端拒絕啟動（開發模式只警告）。 - 守門規則與 prompt 可現場調整：隨 image 出貨一份預設，主機上
/srv/guidant-ai/ai-gateway-rules/可覆寫，升級不會蓋掉現場改過的檔。調整方式見 FR-122 站「AI 守門調整手冊」。 - 記憶體建議 16 GB 起（守門模型常駐）。
- 出包流程多一步相依弱點掃描：建置時掃第三方相依的已知弱點。
4. DB Migration¶
主線（scripts/sql/manifest.tsv 新增 6 列）¶
| 檔案 | 類別 | 內容 |
|---|---|---|
2026-09-28-fr114-fr093-backfill-verify-and-unmark.sql |
結構 | FR-114 延續：驗 23 支關鍵物件存在，缺的撤銷假登記讓套件那輪補套（從 1.19.0 直升的機器缺欄位實例） |
2026-09-28-fr122-background-jobs.sql |
結構 | 新表 public.background_jobs：背景工作佇列，RLS 前綴比對＋超管放行 |
2026-09-28-fr122-ai-call-log.sql |
結構 | 新表 public.ai_call_log：AI 呼叫紀錄，預設只存雜湊與字數，RLS 同上 |
2026-09-29-fr122-ai-call-log-page.sql |
資料 | 能力點 ai-call-log.read＋授予＋選單一列 |
2026-09-29-fr122-ai-quota-page.sql |
資料 | 能力點 ai-quota.read／ai-quota.update＋授予＋選單一列 |
2026-09-29-fr122-ai-usage-menu-rename.sql |
資料 | 選單「AI 呼叫紀錄」改名「AI 用量」 |
資料類三支皆冪等。
出貨基線¶
三支結構類已併入 scripts/init/02-schema.sql 並在 99-stamp.sql 蓋章；資料類走 seed 階段。升級既有客戶：install.sh --upgrade 的 migrate 模式會套這幾支，只加新表、新權限與新選單，不動舊資料。
5. 相依套件版本¶
| 套件 | v1.21.0 | 本版 |
|---|---|---|
| jedi-ai-gateway | — | 0.1.0（新，裝 [gateway] extras） |
| jedi-evidence-classification | 1.4.1 | 1.5.0 |
| jedi-ai-bot | 1.3.1 | 1.4.0 |
| jedi-ai-dashboard | 1.4.1 | 1.5.0 |
| jedi-license-runtime | 1.1.2 | 1.1.3 |
| jedi-remote-agent | 1.2.2 | 1.2.3 |
第三方：cryptography 上限放寬到 <51.0（鎖 50.0.1）、weasyprint 70.x。其餘 15 支 jedi 套件不變。檢測 Agent 不變（1.1.0）。
6. 部署順序¶
- 188 build 機：BE／FE／套件四個 clone
git pull到本版 commit，跑scripts/build/build_all.sh --all（會多出 worker 與 sandbox 兩顆 image），再build_bundle.sh --skip-prod-key-check封包（PROD 簽章鑰仍未建，同 v1.21.0 第 8 節）。 - 190 測試機從 1.21.0
install.sh --upgrade，驗九服務變十服務、guidant-classifier已移除、分類單能從排隊走到完成、第 7.1 節三條。 - 放行後 STG（188） → POC（189）。POC 等同 production，務必 STG 驗過再上。
- 升級前確認主機記憶體；升級腳本會自動備份資料庫並印出還原指令。
7. 已知限制與 follow-up（不擋本版）¶
7.1 待 STG 驗的容器項¶
- 沙箱容器的環境變數與
curl對外連線確認（應連不出去、沒有金鑰）。 - 分類進行中重啟 api 容器，背景工作能否接續。
- 升級後舊
classifier-jobs目錄是否清空。
7.2 其他¶
- 守門「標記」級照送不擋，僅留紀錄。
- AI 用量紀錄不存原文；租戶「完整保留」開關尚未做（設計 D5）。
- jedi-license-runtime 16 個測試為舊債（契約測試寫死 migration 數、暫存庫缺宿主表），非本版造成。
- v1.21.0 第 7 節所列項目仍有效。
8. 相關文件¶
- FR-122 全案：
docs/features/FR-122-2609-ai-gateway-and-sandbox/（design.md設計、ai-guard-tuning-guide.md守門調整手冊、handoff/FR-122-STATE.md現況） - 出貨基線同步規則：
scripts/init/README.md