# FR-133 交接紀錄（LOG）

> append-only：每棒追加一個 block，寫完不改。要更正舊 block，在新 block 的「推翻了什麼」寫明。現況看 `FR-133-STATE.md`。

## 第 1 棒 — 2026-10-09 — 首腦（設計定案、開卡、派工、驗收）

**commits**：BE `a2aa7d9dd`（design 定案）… `df999ed90`（T-R 白名單），全部已 push `feature/FR-133`；FE `9e4e5d18`／`6d2d4e56`／`7d1f64a0`；jedi-python-package `6d815fec`／`e6574acf`／`9a943a54`；evidence-agent `2dea7c8`／`a26464c`／`7e6e1e3`。本 block 所在的文件 commit 未 push。

**18 張卡**（卡號／做什麼／commit／驗收結論／打折處）

- CM-2601 母案（D1–D10）／—／未收／—
- CM-2602 T-A1 jedi-log `log_events` 開關與 `capture_exception`（1.3.4）／jedi `6d815fec`／合格，突變有牙齒／無
- CM-2603 T-A2 後端預設不送 ClientError、worker 與 socketio 補送／BE `1f45680c6`／合格，四項驗收過／用本機 envelope 接收器代替站台；socketio 沒實打
- CM-2604 T-B0 DEV 實跑十項／BE `a5bd492b2`／合格，D1、D2 成立／無
- CM-2605 T-B1 compose 加站台、前門 `/bugsink/`／BE `4fadd8add`、FE `9e4e5d18`／合格／本機 arm64 無產品 image，只起 db／bugsink／fe 三支，後端送件用替身容器
- CM-2606 T-B2 包收 image（釘 digest）與烙印密碼檔／BE `333e5c22d`／腳本層合格／`build_bundle.sh` 全流程未在 188 跑（轉 T-R）
- CM-2607 T-B3 安裝器首裝建站、升級補站／BE `1631d4f27`／合格／Linux 容器只載入函式、只起 db 與站台，真機 root 安裝未跑
- CM-2608 T-B4 `bugsink-vacuum`／`bugsink-set-password`／BE `ace6a5f1a`／合格／harness 載入子命令，`guidantai status` 未實跑
- CM-2609 T-C1 轉送端點與設定端點／BE `98cc3c934`、FE `6d2d4e56`／合格，DEV 實打五項／無
- CM-2610 T-C2 前端登入後接回／FE `7d1f64a0`／合格，headless 實跑／兩組 DSN 以環境變數暫時指向本機站台
- CM-2611 T-D 診斷包改打 Bugsink 讀取 API／BE `16fd0f110`／合格／無
- CM-2612 T-V 端到端驗收／—／待派／—
- CM-2613 T-E 文件／—／待派／—
- CM-2614 T-C1b 轉送端點收使用者與 Agent 兩種身分／BE `5dc3dd6cb`／合格，含偽造 typ 401／臨時三專案站台與不帶排程的後端
- CM-2615 T-C3 Agent 錯誤回報、註冊與心跳回應帶設定／BE `2795930fb`、Agent `2dea7c8`／合格／本機 compose 站台、Agent 跑原始碼非 image
- CM-2616 T-C4 沙箱只通站台的網段／BE `ca6b743de`、jedi `e6574acf`／合格，隔離實測／redis 與 seaweedfs 用替身、沒跑真機安裝
- CM-2617 T-B3b 三專案三組 DSN、診斷包撈三專案／BE `aa084603f`／合格／fetcher 用假 HTTP 層、install.sh 未完整跑
- CM-2618 T-A3 jedi-log 遮罩補 Bearer 值（1.3.5）／jedi `9a943a54`／合格，突變有牙齒／站台手測延到 190
- CM-2619 T-R 發版、釘版、出包、部署 190／BE `fdec6b758`、`df999ed90`，Agent `a26464c`、`7e6e1e3`／進行中，卡在 Nexus npm 快取／—

**決策**

- D1 自動建專案走 `bugsink-manage shell` 的 ORM，DSN 從庫讀。
- D2 站台走 443 子路徑（B0 實證可行，不開 8443）。
- D3 PolyForm Shield 授權可接受，不過法務。
- D4 前端錯誤經後端轉送端點，DSN 登入後才給。
- D5 管理員帳號固定、密碼全客戶一組、build 時烙印。
- D6 共用 `guidant-db` 另開 `bugsink` 庫與獨立帳號。
- D7 每專案保留 1 萬筆、不設天數。
- D8 告警第一版不做。
- D9 接入規範：內網 Python 行程直連並只准走 jedi-log 的 init；外網客戶端經同一支轉送端點，身分沿用既有認證，DSN 附在拿到身分的同一回應。
- D10 三個專案：guidant-ai／guidant-ai-fe／guidant-agent。
- 沙箱接入：多一個 internal 網段只含沙箱與站台，DSN 從 `.env` 拿，不碰 guidant.env。
- 發版流程拿掉 e2e 回歸 gate（決策者裁，`387035254`）。

**教訓**

- 遮罩只看欄位名不夠：A3 的缺口是 C4 runner 實送事件後撈站台原文才抓到（`auth_header` 變數值是 `Bearer <密鑰>`）。根因是 jedi-common 的 Bearer 規則只掛在 log 出口那支。驗收斷言要寫「整個事件找不到原始值」。
- B0 證實設計預告的 ALLOWED_HOSTS 陷阱：內網 Host 回 400 而 SDK 不報錯；換網址後舊對外 DSN 失效——直接決定了「網址相關設定每次重寫」。
- FR-132 三次出包的 Nuitka 漏收坑，Agent 出 image 時要再驗：Agent 出包已整包收 `sentry_sdk`，但「編譯後實送一次」仍要在 190 做。
- Agent 1.4.0 之後 188 沒跑過完整 build，smoke 第 4 項紅是 1.4.0 的未授權拒探測守門造成，不是本案。長時間沒出包的元件，第一次出包要預期撞到前版累積的問題。
- Nexus npm-proxy 的套件資訊快取 24 小時，鎖到剛發的 npm 版本會讓 pipeline 紅；同一批套件可能部分刷到、部分沒有。

**推翻了什麼**

- design.md 初版的 nginx 安全標頭寫死補兩個（T-B1 實測會送出兩份同名標頭，改「上游沒帶才補」）。
- 初版設定端點回 release（T-C1 改由前端用 build 時烙的 `VITE_APP_RELEASE`）。
- 初版只建一個專案、轉送端點只收使用者（D9／D10 後改三專案、雙身分）。
- 初版 Agent 設定只在註冊回應附帶（T-C3 實作時加心跳，因升版 Agent 不重註冊）。
- 初版安裝器「缺了才補」涵蓋網址（B0 後改網址相關每次重寫）。
- 以上已併進 design.md v2。

**留給下一棒**：決策者裁 Nexus 快取後，T-R 續跑到 190 升級與 Agent 升級；之後派 T-V。

---

## 第 2 棒 — 2026-10-10 — 首腦（T-R 收尾、缺口開卡、第二輪發版、驗收、收尾）

**commits**：BE `478db0876`（CI verify 改 pull 目前分支）、`e5a0a9ef9`／`0bc75fd88`（補開 A4／B5／G1／T-R2 卡）、`a614be494`（B5）、`b19358521`（T-R2 釘版）、`aba953f67`（預設全收）；jedi-python-package `95ffe840`（jedi-log 1.3.6）、`be05c2e4`（classifier 1.6.5）；evidence-agent `4b088a4`（Agent 1.4.2）。四個 repo 的 `feature/FR-133` 已併回 main 並 push（BE 範圍 `84e293101..aba953f67`）；本 block 所在的收尾文件 commit 未 push。

**本棒的卡**（卡號／做什麼／commit／驗收結論／打折處）

- CM-2619 T-R 發版、出包、部署 190，後續追加上 STG／POC 與四台 Agent／BE `fdec6b758`、`df999ed90`、`478db0876`，Agent `a26464c`、`7e6e1e3`／合格／A3 遮罩用本機 jedi-log 送 190 驗、不是沙箱真實失敗路徑；Agent 回報改在 190 真環境驗、沒對 DEV 驗
- CM-2620 A4 遮罩補無名位置參數，三份一起改／jedi `95ffe840`、`be05c2e4`，Agent `4b088a4`／合格，三份突變都有牙齒，首腦自行 probe 無洩漏／DEV 全收打錯密碼那條沒在 DEV 做（改在 T-R2 的 188／189 做）；分類器測試跑在暫存 venv，套件版本不保證與容器鎖定相同
- CM-2621 B5 升級保留現場補的允許主機名／BE `a614be494`／合格，T-R2 在 190 真機驗過網域仍在／debian 容器只載入函式
- CM-2622 G1 Agent 1.1.0 直升的儲存憑證缺口／—／決策者裁暫緩／—
- CM-2623 T-R2 第二輪發版、三環境、四台 Agent／BE `b19358521`（安裝包以 `aba953f67` 出）、Agent `4b088a4`／合格／190 留手動兩行關閉全收，「沒設就預設全收」只在 188 驗到；189 有手動兩行 =true
- CM-2612 T-V 端到端／—／決策者裁以 T-R／T-R2 三環境實跑代替，改 Done／乾淨機首裝未驗
- CM-2613 T-E 文件／—／收尾時由另一支 agent 處理／—

**決策**

- G1 暫緩。理由：產品未出貨，不存在客戶端 1.1.0 Agent；內部四台已升完。被排除的：修升級子命令轉呼叫新包 install.sh——投入大、目前無受益者。出貨後若有跨版升級需求再開。
- 產品預設改全收（`aba953f67`）：4xx 使用者失誤與 ERROR log 行預設都送站台。理由：UAT 期間要看到使用者在哪裡撞牆。前提是 jedi-log ≥1.3.6 已補位置參數遮罩。被排除的：維持設計初版「預設只收程式錯誤」——看不到使用者被擋在哪。
- 三套件發兩輪（jedi-log 1.3.5→1.3.6、classifier 1.6.4→1.6.5、Agent 1.4.1→1.4.2）。被排除的：等下一版一起發——全收已開，位置參數漏洞不能等。
- 不進版：主專案版號不動、不寫 release note、不切 spec 快照，image tag 仍是 1.26.0 加新 commit。
- 決策者親手或當場裁示的環境動作：190 停舊 Sentry self-hosted 與獨立 bugsink、guidant.env 註解舊 DSN；Nexus npm-proxy 清快取；GitLab 變數改 14 字、取消 Protect；188 兩個 clone 切 `feature/FR-133`；STG／POC 當天上版；四台 Agent 升級；189 開全收並解鎖 blsadmin。
- 發版流程不跑 e2e 回歸 gate（`387035254`，第 1 棒已記，本棒沿用）。

**教訓**

- 遮罩第二次盲點是決策者在 190 開全收時親眼看到的：`@transaction` 包裝層的 `args` 是 `(self, username, password, …)`，遮罩只認欄位名與 Bearer 樣式。兩次盲點（Bearer 值、位置參數）都不是測試抓到，是實送事件後看站台原文抓到。驗收要有「真 SDK 收到的事件」這一層。
- 遮罩有三份複製品（jedi-log、Agent、分類器容器），A4 runner 改完兩份才自己發現第三份。改遮罩前先 grep 三處。
- Nexus npm-proxy 對套件資訊快取 24 小時，剛發的 npm 版本會讓 build-fe 紅，同批套件可能部分刷到部分沒有；清法是 invalidate-cache API。
- 新加的第三方 image 要先在 188 `docker pull`，否則 package 紅；B 系列卡沒寫這步。
- GitLab masked 變數勾 Protect，在 feature 分支讀到空值。
- Agent `guidant-agent-compose upgrade` 跑的是機器上舊版的升級程式；1.1.0 直升時新版才有的步驟不會執行。
- Agent 升級不清 `/tmp` 暫存解包，.166 的 `/tmp` 是記憶體盤，第三次升級塞滿，錯誤訊息誤導成「檔案損毀」。
- 在 jedi 子目錄跑 `poetry run` 會解析到 BE 的 venv，跑出假紅；改用 `PYTHONPATH=. python3 -m pytest`。
- `guidantai restart` 不重讀 env_file，改設定後要用 `start`。
- 長時間沒出包的元件（Agent 1.4.0 之後）第一次出包會撞到前版累積的問題（smoke 第 4 項）。

**首腦違規自檢**

- A1：runner 回寫「決策者明示後發版」，決策者始終沒回答有無下令；首腦按「有」處理，沒再追。
- T-R 期間決策者直接與 runner 互動裁示多項（清快取、GitLab 變數、切 clone、STG／POC 上版），首腦是事後驗收，不是事前派工。

**推翻了什麼**

- design.md D9 之後的「過濾預設只收程式錯誤」改為預設全收（`aba953f67`），開關仍在、設 false 回到只收程式錯誤。
- 第 1 棒 STATE §5 推測「GitLab 變數推測已設」：實際有設但勾了 Protect、只有 11 字，feature 分支讀到空。
- 第 1 棒留給下一棒「之後派 T-V」：T-V 不另跑，以三環境實跑代替。

**三環境最終狀態**

- 190（e2e）、188（STG）、189（POC）：api／worker／socketio 都在 1.26.0＋`aba953f67`，sandbox evidence-classifier 1.6.5，bugsink 2.6.1 healthy，三專案在。
- 四台 Agent（.166／.122／.167／.121）都在 1.4.2，雲端登記 1.4.2。190 本機的 Agent 容器仍是 1.4.1（2026-10-10 實查）。
- 190 guidant.env 留有手動 `ERROR_TRACKING_CAPTURE_CLIENT_ERRORS=false` 與 `ERROR_TRACKING_LOG_EVENTS=true`；189 guidant.env 有手動兩行 =true；188 是純預設。
- 188、189、.166 有 reboot-required 旗標未重開。

- 收尾中補做：190 本機 Agent 1.4.1→1.4.2（包從 188 scp、sha256 OK、`guidant-agent-compose upgrade`、healthy、release 行確認）。T-E（CM-2613）9d0849644 完成並收 Done。

- 收尾後追加 T-M1（CM-2624）：遮罩三份複製品收斂成零相依套件 jedi-masking 0.1.0，三邊改薄殼（jedi-log 1.3.7／分類器 1.6.6／Agent 1.4.3），首腦比對新舊行為一致；程式已推 main、未發版，併下次進版。

**留給下一棒**：arc 收尾完成，等決策者決定進版時機（version-bump skill）；進版時先發 jedi-masking 再依序發三邊。

---