狀態：✅ 全案收口（2026-09-03，母卡 CM-1517 Done）｜建立日期：2026-09-02｜無前作｜無獨立討論稿——設計討論在對話中完成
| 日期 | 變更 | 對應 |
|---|---|---|
| 2026-09-02 | 初版設計定案，D1–D6 全數拍板（含 2026-09-02 spike 驗證結果） | FR-072 母案 |
| 2026-09-03 | 全案收口:12 子卡+母卡全 Done。六支影片+完整版交付(④以 Agent 1.0.0 重錄);install-test 已接線未實跑(出貨前先試跑,build README 已標)。衍生:FR-073(Agent 安裝形態)、FR-074(檢測工具影片) | CM-1517 收口 |
| 2026-09-02 | 影片系列 5→6 支（增⑥日常維運 CLI，CM-1532）；查證確認安裝/CLI/license/精靈全段已實作可實錄（B3 依賴解除）；步驟細節回寫 B 段各卡 | CM-1524~1532 |
| 2026-09-02 | 錄影標準帳號定為 guidantai（user 拍板）：190 上新建、ssh 免密＋docker group＋sudo NOPASSWD 已實測；所有錄影與 install-test 一律走此帳號，spike 當時用的 jedi 停用於本案 |
CM-1521 / CM-1522 |
training 套件（Cucumber + Playwright + overlay 字幕），只能錄 web UI。ssh guidantai@192.168.50.190，Playwright 開 localhost:7681 打指令、疊 overlay、錄影出片，全鏈可行。window.term，走 xterm buffer API（term.buffer.active.getLine(i).translateToString(true)）可讀全畫面文字——等待/斷言靠它。clean。整件事分三段做：A 先把「用瀏覽器錄 terminal」的地基蓋好 → B 用地基錄出五支安裝教學影片 → C 同一組腳本翻面當自動化安裝測試，掛進出包驗收。
| 階段 | 做什麼（白話） | 產出 | 完成怎麼判定（決策者檢查法） |
|---|---|---|---|
| A 錄影地基 | 讓既有的 Cucumber 錄影套件學會操作 terminal：新的 step（「在終端機執行…」「等待終端機出現…」）、ttyd 起停、190 主機的檢查點探測與重置 | console steps + ConsoleTerminal 封裝 + ttyd fixture + 檢查點腳本 + 撰寫指南 | 跑一次示範場景，打開產出的 mp4 看：terminal 畫面清楚、指令有打出來、overlay 說明字卡有疊上去 |
| B 五支影片 | 照安裝流程順序寫五支 feature 檔並逐支出片：①系統需求 ②主產品安裝 ③License 申請匯入 ④Agent 安裝 ⑤首次登入 | 5 支獨立 mp4 + 1 支合併版 | 逐支打開 mp4 從頭看到尾：步驟看得懂、畫面上沒有任何密碼/金鑰/license 內容（對照 §4.4 檢查清單逐項打勾） |
| C 安裝測試 | 同一組 feature 關掉字卡、加上硬斷言（ssh 直查服務真的起來了），變成「乾淨機實裝驗收」，掛進出包流程 | @install-test 執行模式 + 出包驗收文件指標 | 對一個安裝包跑一次 @install-test：包好的過、故意弄壞的包（如抽掉一顆 image）要紅 |
順序 A → B → C；B3（License 影片）依賴 license 流程文件定稿。
| # | 決策 | 定案 |
|---|---|---|
| D1 | 錄影引擎 | ttyd + Playwright（方案 B），非 VHS / asciinema。理由：overlay 說明系統（training-helper.js 8 種效果）是 DOM 注入，ttyd 把 terminal 變網頁後零改動繼承；且是唯一能 web + console 混排的方案。VHS 排除：無 overlay 能力，說明插入只能後製或 echo 土法。asciinema 排除：偏人工實錄，不適合正式管線。 |
| D2 | BDD 同軌 | console 走既有 Cucumber 套件，不另起爐灶。混排場景（如首次登入：瀏覽器＋terminal 同片）必須同一 world；overlay / SKIP_OVERLAYS / preview / 錄影管線全繼承；feature 檔雙用途（training mode＝錄影、test mode＝安裝測試）。 |
| D3 | 分段錄製 | 5 檢查點狀態機 clean → bundle-uploaded → installed → licensed → agent-ready，每段影片＝兩檢查點之間。每支 feature 開頭跑不入鏡的 ssh 前置檢查（190 狀態不符檢查點直接 fail，不會錄出錯誤前提的片）。重錄第 N 段＝把 190 回到檢查點 N-1：VM snapshot 優先，不可行則替補腳本用 SKIP_OVERLAYS 全速重放前段指令。合併走既有 merge-phase-videos.sh 模式加 install 章節清單，各段亦保留獨立成片。 |
| D4 | 敏感內容三層防線 | ①分鏡設計讓敏感值不上畫面（首選）：私鑰/license/token/API key 一律禁 cat，只准 ls / 指紋（ssh-keygen -lf）/ .sample 佔位符檔；密碼走 read -s 或免密；敏感 env 走「以隱藏方式載入環境變數」step（畫面只見 source 指令）。②overlay 區域遮罩：從 window.term buffer + cell 尺寸算行座標蓋色塊，留給預期外輸出。③後製 ffmpeg 打碼：事故補救，不當常規。紀律：feature 檔是版控檔案，禁真值（「憑證不入版控」延伸＝「憑證不入影片」）；出片前過敏感內容檢查清單（§4.4）。 |
| D5 | 自動化安裝測試 | 同一組 feature 加 @install-test 模式＝關 overlay＋硬斷言（畫面文字之外，ssh 直查 exit code / 服務狀態）＋環境重置，掛進出包驗收當 release gate。呼應 T-6.6 教訓（驗收環境打折掩蓋真缺口——乾淨機實裝才能抓到「第三方 image 沒進包」類問題）。 |
| D6 | skill / 文件落點 | canonical 在 test repo（console-recording-guide.md + test repo CLAUDE.md 補段），BE repo 只在 build 文件加指標。暫不開 .claude/skills 條目，流程跑穩後再升格。 |
Mac 端一機包辦錄影管線，190 零安裝（只被 ssh 進去操作）：
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
subgraph MAC["Mac（錄影主機）"]
CUKE["Cucumber feature
（training 套件）"] --> PW["Playwright
（開 localhost:7681
打字 / overlay / 錄影）"]
PW --> TTYD["ttyd -p 7681 -W
包 ssh 指令"]
PW --> MP4["mp4 出片
（既有錄影管線）"]
end
TTYD -- "ssh guidantai@192.168.50.190" --> TARGET["190 錄影目標機
（guidant-ai-e2e，零安裝）"]
PW -. "window.term buffer API
讀畫面文字（等待/斷言）" .-> TTYD
| 元件 | 內容 |
|---|---|
training/steps/console/console.steps.js |
六個 step：終端機已連線到安裝目標主機／主機狀態符合檢查點「」／在終端機執行「」／等待終端機出現「」逾時「」秒／確認上一個指令成功／以隱藏方式載入環境變數「」 |
training/pages/console/ConsoleTerminal.js |
封裝 window.term buffer 讀取（term.buffer.active.getLine(i).translateToString(true)）、打字、開場 clear |
| ttyd 起停 fixture | Before/After hook 或外部腳本：起 ttyd -p 7681 -W ssh guidantai@192.168.50.190，場景結束關閉 |
| 檢查點定義＋探測 | ssh 查 /srv/guidant-ai、docker ps、license 狀態等，對應 §4.3 五檢查點 |
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
stateDiagram-v2
[*] --> clean : 190 全清（2026-09-02 已達成）
clean --> bundle_uploaded : 影片②前段（傳包）
bundle_uploaded --> installed : 影片②（install.sh → 服務起）
installed --> licensed : 影片③（License 申請匯入）
licensed --> agent_ready : 影片④（Agent 安裝）
agent_ready --> [*] : 影片⑤（首次登入，不再改機器狀態）
note right of clean
重錄第 N 段＝回到檢查點 N-1：
VM snapshot 優先；
不可行則替補腳本
SKIP_OVERLAYS 全速重放前段指令
end note
merge-phase-videos.sh 模式加 install 章節清單，各段亦保留獨立成片。| 層 | 手段 | 定位 |
|---|---|---|
| ① 分鏡設計 | 敏感值不上畫面：私鑰/license/token/API key 禁 cat，只准 ls／指紋（ssh-keygen -lf）／.sample 佔位符檔；密碼走 read -s 或免密；敏感 env 走「以隱藏方式載入環境變數」step（畫面只見 source 指令） |
首選，設計時就解決 |
| ② overlay 區域遮罩 | 從 window.term buffer + cell 尺寸算行座標蓋色塊 |
留給預期外輸出 |
| ③ 後製 ffmpeg 打碼 | 逐幀打碼 | 事故補救，不當常規 |
紀律：
.env 或部署文件」。| 坑 | 對策 |
|---|---|
| xterm canvas 渲染，DOM 無文字 | 走 window.term buffer API 讀畫面 |
| ssh 開場有 Ubuntu motd 雜訊 | 錄影開始前先 clear |
ttyd --once 一連線即退場 |
正式 fixture 不用 --once，用 After hook 關 |
| 「確認上一個指令成功」兩模式語意不同 | training mode 靜默（不打斷錄影）、install-test mode 硬斷言 |
查證來源：docs/user-manual/onprem/ 02/03/04 章＋189 實機盤點（1.18.0 bundle --help 實測）。
| # | 影片 | 內容 | 卡 |
|---|---|---|---|
| ① | 系統基本需求 | sha256sum -c 驗包＋sudo ./install.sh --check-only（只驗不動） |
CM-1524 |
| ② | 主產品安裝 | tar 解包 → sudo ./install.sh（互動只問主機名/資料目錄/port 三題，不問密碼）→ 八步自動 → 印站台網址＋一次性設定碼＋機器碼 |
CM-1525 |
| ③ | License 申請與匯入 | 機器碼（精靈第 3 步／保底 sudo guidant fingerprint）＋開通序號 → 原廠回 .license → 登入後「License 開通」頁上傳開通；線上路徑輸序號直接開通 |
CM-1526 |
| ④ | Agent 安裝 | 檢測 Agent 安裝＋guidant agent-check 確認對接 |
CM-1527 |
| ⑤ | 首次登入 | web + console 混排：開站 → 貼一次性設定碼 → 自建管理員（帳號名禁用 admin）→ 顯示機器碼 |
CM-1528 |
| ⑥ | 日常維運指令 | guidant status/logs/restart/credentials/stop/start 高頻示範；rotate-credentials/uninstall 只講不跑；credentials 輸出含真密碼依 D4 遮罩 |
CM-1532 |
順序 A → B → C；B3 依賴 license 流程文件定稿（2026-09-02 查證：license 流程已實作走通，依賴解除）。
| # | 子任務 | 驗收 |
|---|---|---|
| A1 | console steps + ConsoleTerminal + ttyd fixture | 重跑 spike 等價場景出片 |
| A2 | 檢查點定義＋重置機制 | clean 重置腳本實跑一次＋各檢查點探測函式 |
| A3 | console-recording-guide.md + test repo CLAUDE.md 補段 | 含 D4 三層防線、金鑰紀律表、出片前檢查清單 |
| # | 子任務 | 驗收 |
|---|---|---|
| B1–B5、B7 | 六支 feature（①系統需求 ②主產品安裝 ③License ④Agent ⑤首次登入 ⑥日常維運） | 每支獨立出片＋敏感內容檢查過 |
| B6 | 合併出片（六支） | merge 清單＋全系列檢視 |
| # | 子任務 | 驗收 |
|---|---|---|
| C1 | @install-test 模式（關 overlay＋硬斷言＋重置串接） | 對安裝包實跑一次全綠 |
| C2 | 掛進出包驗收流程（BE build 文件加指標） | 出包 SOP 文件含 install-test 步驟 |
@install-test 模式對一個安裝包實跑：正常包全綠；缺件包（如抽掉第三方 image）確實變紅。