跳轉到

Guidant AI v1.19.0 Release Note

項目 內容
版本 1.19.0（功能版號；主軸＝後端模組化全案 FR-069——40 個模組抽成 25 支可獨立安裝的 jedi- 套件、主專案收整淨刪 38,000+ 行、對外契約零漂移；並列＝檢測 Agent 安裝形態改版 FR-073（Agent 1.0.0）*＋ 兩套安裝教學影片 FR-072／FR-074 ＋ 一則資安修補：移除 guidant credentials 明文密碼子命令）
發布日期 2026-09-03
上一版本 1.18.0（2026-08-29）
涵蓋區間 2026-08-29 ~ 2026-09-03（fe56ab6a..c1fb2397，BE 225 commits：refactor 52／fix 17／chore 12／feat 10／test 3／docs 125；jedi monorepo 同期整條 feature/FR-069→FR-069.5；FE 5 commits；evidence-agent FR-073 整案）
涵蓋需求 FR-069 模組化抽取全案（母卡 CM-1435，子卡 CM-1436～CM-1516 約 80 張）：四階段抽取＋2.5 身分族合併＋第三階段完全體插件＋第四階段核心抽取＋FR-069.5 收整（shim 清退 310 支／存量紅測試 94→0／readmodel 重整／身分表直連 port 化 13 支／四類歸位／技術債五連清）；FR-073 檢測 Agent 安裝形態比照主產品（CM-1534，Agent 0.2.32→1.0.0）；FR-072 console 安裝教學影片套件（CM-1517）；FR-074 檢測工具整合教學影片（CM-1535，六章 28 段）；CM-1511 排程掃描開始時間顯示修正；CM-1533 Agent installer heredoc 反引號 cosmetic 錯誤；資安修補：移除 guidant credentials（2026-09-03 決策者裁示）
規模 jedi-* 套件終態 26 支（現役 25＋退役 10 已刪）；本 arc 發版 27 支次（最終批九支：common 0.0.34／issue 0.0.19／participant 0.0.2／detection 0.0.3／flow-engine 0.0.37／system-menu 0.0.13／compliance-audit 0.0.3／survey 0.1.3／task-platform 0.1.2）；DB migration 5 支（1 支 envs=*＋4 支 dev 專屬）；主專案守衛測試 80 綠／全量 pytest 2155 綠
適用部署 188 STG ＋ 189 POC（安裝版 docker stack，install.sh --upgrade）；190 已以本版 beta（1.19.0b1）＋POC 真資料實測升級路徑通過
部署性質 含 1 支 envs=* DB migration（2026-08-30-fr069-12-project-ext-converge：project ext 四欄收回主表，自帶對帳守衛不一致即 rollback；已於 DEV／190 POC 快照／STG 三處真資料實測通過）。另 4 支 dev 專屬（drop 舊延伸表／死欄／軟參照）不隨 init image migrate 套 STG/POC（依環境鐵律，見 §5）。FE image 有異動必重 build（CM-1511 排程時間顯示＋i18n）。BE image 必重 build（主專案 pin 九支新版套件）。不走正式簽章（維持 --skip-prod-key-check，PROD 鑰待 FR-062 待辦）。檢測 Agent 隨本版出 1.0.0（安裝形態改變，見 §2.3）

0. 發版前回歸 gate

本版未執行 site-regression 自動 Core gate，理由與 v1.16.0～v1.18.0 同：落地版 stack 形態的 E2E 套件尚未補齊。放行依據：

  • 機器驗證（CM-1509 收口棒）：全量 pytest 2155 passed／9 skipped；守衛 80 綠；D5 對外契約凍結面機器 diff 零漂移（231 個 error code 字串值＋424 條 URL 逐字比對重構前後）；url_map 598 條 method+path 零差異；mini arc-review 兩條 finding 修畢。
  • 190 真資料驗收（CM-1516）：以 POC（189）2026-09-02 快照還原＋補套本版 migration → 部署 1.19.0b1 → 決策者以真資料整輪手測通過；兩套教學影片（FR-072／FR-074）亦在 190 上以本版錄製完成。
  • 安裝包實裝：guidant-ai-1.19.0b1.tar.gz 於 190 首裝＋同版 --upgrade --force 兩條路徑皆通；Agent 0.2.32→1.0.0 首裝、升級、遷移三條路徑於 190 實測（CM-1534）。

自動化 gate 待落地版 E2E 套件補齊後於後續版本恢復。

1. 概述

v1.18.0 把系統設定頁補到客戶自己改得動。v1.19.0 做的是看不見的那一層：後端從一個 40 模組的單體，拆成 25 支可獨立安裝的 jedi-* 套件——每支自帶路由、DI 容器與 migration（插件契約 D6），主專案縮成產品本體四類（報表櫃檯／接線盤／組裝根／業務加工）。這是為了讓「別的產品也用得到」的能力可以被複用，也讓主專案體積減半（淨刪 38,000+ 行）。

對使用者而言，這版幾乎沒有可見變化——error code、URL、回應形狀全程凍結，前端與既有部署無感；唯一可見的是排程掃描「開始時間」顯示修正（§3.1）。對部署者而言，有兩件事要知道：檢測 Agent 的安裝形態改了（§2.3，Agent 1.0.0），以及guidant credentials 指令被移除了（§3.2，資安修補）。

另外兩支教學影片套件（console 安裝流程六段、檢測工具整合六章 28 段）隨本版錄製完成，成品在 test repo reports/training-videos/。

2. 重點變更

2.1 後端模組化全案（FR-069，母卡 CM-1435）

四階段抽取＋收整，工程帳詳見 docs/features/FR-069-2608-jedi-module-extraction/handoff/2026-09-01-FR069-SUMMARY.md。對部署面的意義：

  • 主專案 poetry install 即可跑，零本地 path 依賴（九支套件最終版已上 Nexus）。
  • 對外契約 D5 凍結：231 error code 值／424 URL／blueprint 名機器 diff 零漂移。
  • 收整帳：shim 清退 310 支、存量紅測試 94→0、tests/ 整合套件退役 25,015 行（裸跑 pytest 假紅根治）、13 支身分表直連改名冊 port、孤兒清理排程（daily 03:10 UTC）、DI deepcopy 與 logging import 副作用雙病根修除、出貨依賴衛生（測試框架不再進產物）。

2.2 排程掃描開始時間（CM-1511，jedi-detection 0.0.3 ＋ FE 5548cd2）

見 §3.1。

2.3 檢測 Agent 安裝形態比照主產品（FR-073／CM-1534，Agent 0.2.32 → 1.0.0）

這是本版對部署者影響最大的一項。 舊形態「解壓目錄＝安裝目錄」——.env（含註冊 token 與儲存憑證）、compose、憑證、profile 全留在客戶家目錄的解壓資料夾，裝完畫面要印「請勿刪除」；換版走新目錄首裝會撞固定 container_name 靜默失敗（CM-1533 實證：新版建不出、installer fallback 把失敗讀成成功、憑證消失後雲端 409 拒新註冊）。

本版改為與主產品相同的三分離：

項目 舊（0.2.x） 新（1.0.0）
安裝目錄 解壓目錄（家目錄下） /srv/guidant-ai-agent（固定系統路徑）
設定 同上 .env /etc/guidant-ai-agent/（安裝紀錄）＋資料目錄 .env
log 解壓目錄 /var/log/guidant-ai-agent/
CLI 指回解壓目錄 /usr/local/bin/guidant-agent-compose 指固定路徑
解壓目錄 🔴 不可刪 用完可刪
升級 新目錄首裝（會撞名） 偵測既有安裝 → 沿用 .env／憑證／volume → 換 image；compose project name 固定
舊形態遷移 — install.sh 偵測家目錄舊安裝 → 搬進固定目錄
fallback 判定 「容器都在跑」即成功 補「容器 image tag == 本次要裝 tag」

三條路徑（首裝／升級／舊形態遷移）於 190 實測通過；同時順手修掉 install.sh usage heredoc 內第二處裸反引號（與 CM-1533 同款 bug）。部署文件 docs/user-manual/agent/03-install.md／07-upgrade.md 已同步。

2.4 兩套教學影片（FR-072／FR-074）

  • FR-072 console 安裝教學六段（傳包→安裝→License→Agent→首次登入→維運）＋完整版 21:29，ttyd＋Playwright 錄製管線落地 test repo（training/），reset-190.sh 檢查點重置腳本可重放。
  • FR-074 檢測工具整合教學六章 28 段 75:42（＋2x 版），涵蓋七支檢測工具從設定到取證。

成品在 test repo reports/training-videos/；影片④已以 Agent 1.0.0 重錄、影片⑥已以移除 credentials 後的 CLI 重錄。

3. 重要修補

3.1 排程掃描「開始時間」顯示的是建單時刻（CM-1511）

排程單的執行詳情把 started_at（發動/建單時間）標成「開始時間」，排 09:20 顯示 09:18，看起來像提早開掃或存錯時間。資料層無 bug（agent_tasks.scheduled_at 正確、agent 也確實等到時間才領單）。修法 A（BE）：mark_running() 轉 running 時把 started_at 覆寫為實際開掃時刻；修法 B（FE）：排程中顯示「排定開始時間」、開掃後才標「開始時間」。順帶補一個從未生效的顯示：執行紀錄列的「排程於 X 開始」——序列化器從未宣告 scheduled_at，該欄位靜默被丟，上線以來沒亮過。

3.2 🔴 資安修補：移除 guidant credentials 子命令（BE e8d04ba5）

sudo guidant credentials／--export 會把資料庫、Redis、物件儲存的明文密碼印在畫面上。決策者 2026-09-03 裁示：這不該是交付給客戶的功能——客戶只需知道設定檔在哪；原廠人員需要查看時走內部維運文件。本版整支移除（CLI 函式、dispatcher、help、installer 完成畫面的引導文字）；rotate-credentials 保留（輪換不印值，完成畫面改指設定檔位置）。使用手冊 §4.5 改寫。密碼在客戶機上的長期存放與存取邊界另案討論（與 FR-070 同族）。

升級注意：既有客戶 --upgrade 後 /usr/local/bin/guidant 即為新版；若客戶的 SOP 文件引用過 credentials 指令需同步更新。

3.3 Agent installer「start: command not found」（CM-1533，Agent 0.2.32）

.env heredoc 內裸反引號被 shell 當命令替換，純 cosmetic（安裝結果正確），已跳脫。1.0.0 又抓到 usage heredoc 第二處同款。

3.4 建置鏈對預發版號的四處不相容（beta 出包首例，皆已修）

1.19.0b1 是本產品第一次出預發版，踩到：Nuitka --product-version 不收 PEP 440 字尾（截數字段餵）、BE/FE 版號守門字面比對（PEP 440 b1 vs semver -beta.1 正規化後比）、修正時 \1 寫成 \x01 控制字元、FE image tag 雙格式（暫以 docker tag 別名過，正式版不受影響；tag 格式統一記帳待修）。另 bundle 腳本的 PROD 公鑰路徑仍指 FR-069 前的主專案位置（common/license/public_keys.py，已搬進 jedi-license-runtime）——skip 模式不讀該檔故本版未擋，正式簽章上線前必修。

4. Breaking Changes

  • 對外 API：無（D5 凍結面機器 diff 零漂移）。
  • 內部：舊 import 路徑（api/auth、domain/flow_control、domain/participant、domain/evidence_classification 等）已刪除，二次開發改用 jedi-* 套件路徑；pytest 裸跑已可用（不再需要 python -m）。
  • 檢測 Agent 1.0.0 安裝形態改變（§2.3）：舊形態已裝客戶由新 install.sh 偵測遷移；agent 包版號脫離 0.x。
  • guidant credentials 子命令移除（§3.2）。

5. DB Migration

檔 envs 說明 STG/POC 處置
2026-08-30-fr069-12-project-ext-converge.sql * project ext 四欄（module_frame_id／living_ssp_id／owner_id／deleted_at）收回主表＋回填＋對帳守衛 init image migrate 模式套用（STG 已於 2026-09-02 build 前置套過）
2026-08-30-fr069-17-drop-users-topt-secret.sql dev 刪拼錯的死欄位 不套（環境專屬）
2026-08-31-fr069-cm1474-drop-assessment-plan-extensions.sql dev 孤兒表退役 不套
2026-08-31-fr069-cm1474-drop-project-extensions.sql dev 舊延伸表 drop（雙寫已拔） 不套（STG/POC 保留舊表作安全網，drop 另裁）
2026-08-31-fr069-cm1490-soft-ref-job-execution-bindings.sql dev 四條 CASCADE 外鍵改軟參照 不套

帶舊資料升級路徑已於 190 以 POC 真實快照實測（兩支對帳守衛在真資料上全過）。出貨基線庫已收斂 fr069-12（dc0c7789，init 產物 regenerate）。

6. 相依套件版本（本版 pin）

jedi-common 0.0.34／jedi-issue 0.0.19／jedi-participant 0.0.2／jedi-detection 0.0.3／jedi-flow-engine 0.0.37／jedi-system-menu 0.0.13／jedi-compliance-audit 0.0.3／jedi-survey 0.1.3／jedi-task-platform 0.1.2（其餘 16 支未變）。完整 25 支對照見 docs/claude/jedi-packages.md 現役套件總表。檢測 Agent 1.0.0。

7. 部署順序

  1. 188 build 機 git pull 到 tag v1.19.0 並親驗 HEAD → build_all.sh --all → build_bundle.sh --skip-prod-key-check（PROD 鑰未進 image，維持內部簽章形態）→ 開包驗 commit。
  2. STG（188 stack）：install.sh --upgrade（init image migrate 模式套 fr069-12；STG 已預先套過會 skip）→ 六服務健康 → 抽驗專案列表／參與者姓名／檢測任務。
  3. 決策者放行 → POC（189）同上。POC 等同 production，放行前不動。
  4. Agent 1.0.0 包隨版交付；已裝 0.2.x 的客戶走新 install.sh 遷移路徑。

8. 已知 follow-up

  • FR-070 AI／Google Drive 憑證 DB 化與功能開通（admin tenant 限定）——Phase 0，含「密碼怎麼藏」設計討論。
  • FR-071 客戶端診斷包（Support Bundle）——Phase 0。
  • bundle 腳本 PROD 公鑰路徑指套件（正式簽章前必修）；FE image tag 預發格式統一。
  • jedi-survey 套件既有 48 紅（陳年測試債）；jedi-flow-engine 架構測試檔 27 個遮蔽函式。
  • Nexus 四支舊殼（jedi-auth／login／mfa／captcha）下架——決策者裁暫不動。
  • site-regression 接 190 跑最新版；FR-072 C 段（@install-test 出包驗收 gate）未啟動。

9. 相關文件索引

  • FR-069：docs/features/FR-069-2608-jedi-module-extraction/（design／boundary-map／extraction-sop／handoff/2026-09-01-FR069-SUMMARY.md／fr069-STATE.md）；review docs/review/2026-09-01-fr069-review.md
  • FR-073：docs/features/FR-073-2609-agent-install-layout/design.md
  • FR-072／FR-074：test repo training/＋docs/features/FR-072-*/、FR-074-*/
  • 架構手冊（族譜 26 支終態／主專案四類／D6 六條）：docs/features/architecture-handbook/
  • 使用手冊異動：docs/user-manual/onprem/04-operations.md §4.5、docs/user-manual/agent/03-install.md、07-upgrade.md、docs/spec-site/current/user-manual/detection-tools-guide.md（排程時間常見問題）