---
title: "網址型 Profile 存成檔案並同步給 Agent — 設計文件 v1.1 (FR-174)"
brand: "Guidant AI · **FR-174** 設計 v1.1"
eyebrow: "FR-174 · 設計文件 v1.1 · 2026-11-02 · 實作中異動"
h1: "設計 v1.1：實作中異動"
subtitle: "對照 v1.0（design.md，2026-11-01 定稿）；v1.0 決策 D1～D10 不變"
lede: "🔴 **這份只記 v1.0 定稿後、實作期間對設計本身做的改動。** 決策 D1～D10 的方向一條都沒有推翻；改的是拆卡範圍與一個卡上的筆誤。v1.0 原文保留在 [design.md](design.md) 不動。現況（實際版號、行為）不在這裡，看結案後的 FINAL-SPEC。"
chips: [
  {text: "v1.0 → v1.1", kind: accent},
  {text: "D1～D10 不變", kind: ok},
  {text: "拆卡 7 → 9 張", kind: warn},
  {text: "2026-11-02 合回主線", kind: ok},
]
footer: "FR-174 設計文件 v1.1 · 2026-11-02 · v1.0 見 design.md"
---

## 版本 {#versions nav="版本"}

| 版本 | 日期 | 檔案 | 內容 |
|---|---|---|---|
| v1.0 | 2026-11-01 | [design.md](design.md) | 定稿：決策 D1～D10、Profile 一生流程圖、套件改法、7 張卡 4 批 |
| **v1.1** | 2026-11-02 | 本頁 | 補開 E-1、A-2 兩張卡（批 4），H-1 挪批 5、Z-1 挪批 6；工具代號更正 |

> v1.0 的拆卡表在 2026-11-02 開卡當天就已就地改成 9 張 6 批（同一個 commit 裡改了 design.md 與 cards.py）。本頁補記這次改動的理由，讓兩版的差異有地方查。

---

## 1. 為什麼有 v1.1 {#why nav="為什麼"}

v1.0 定稿時，FR-171 還在進行中。FR-171 結案合回主線後，FR-174 要接著跑 H-1（在 DEV 走通、驗 Agent 下拉），檢查放行條件時查到兩個 v1.0 沒料到的擋點：

1. **套件分支落後主線**：FR-174 的套件工作坊分支是從 FR-171 的預發版 b1 長出來的。FR-171 結案後，主線已經是套件正式版。兩邊合併時，`jedi-detection/pyproject.toml` 的版號會衝突：174 已長到 1.8.0b2，171 發了 1.7.3。不先對齊，H-1 起的服務會用舊套件配新的主線程式碼。
2. **Agent 的 Profile 快取路徑寫死**：`profile_cache.CACHE_ROOT` 寫死成 `/data/content/cache`，這是 Docker 容器裡的路徑。在 Mac 本機直接跑 Agent 會寫不進去（Read-only file system），Profile 同步全部失敗，H-1 要驗的下拉一定是空的。

兩件都要在 H-1 之前做完，所以補開兩張卡，排在 H-1 前面。

---

## 2. 拆卡異動 {#cards nav="拆卡異動"}

### 2.1 補開（掛 174 母卡 CM-3422）

| 卡 | 批 | Repo | 做什麼 |
|---|---|---|---|
| **E-1** CM-3434 | 4 | jedi-packages | 把主線合進 174 套件分支，解 `jedi-detection/pyproject.toml` 版號衝突（版號取 174 的 1.8.0b2，相依下限取 171 的 `>=1.12.0`）；開發環境 `.venv-fr174` 的兩支通訊套件換成正式版 |
| **A-2** CM-3435 | 4 | agent | Profile 快取路徑改讀環境變數 `AGENT_CONTENT_CACHE_DIR`，預設值不變（容器行為不受影響）；本機啟動腳本補一行 |

### 2.2 挪批

| 卡 | v1.0 | v1.1 | 為什麼 |
|---|---|---|---|
| H-1 CM-3426 | 批 3 | **批 5** | 要等 E-1、A-2 做完。批 1～3 已驗收通過，新卡不能插進已完成的批次，否則工作坊會以為批 3 還沒做完 |
| Z-1 CM-3429 | 批 4 | **批 6** | 跟著往後挪 |

### 2.3 總數

| | v1.0 | v1.1 |
|---|---|---|
| 卡數 | 7 張 4 批 | 9 張 6 批 |

---

## 3. 與 v1.0 決策的關係 {#decisions nav="決策"}

決策 D1～D10 全部照 v1.0 執行，沒有推翻。

| 項目 | v1.0 | v1.1 | 說明 |
|---|---|---|---|
| 套件版號（D9） | 1.8.0b1 → 1.8.0b2 → 1.8.0 | 同 | 照計畫 |
| 套件分支基底（D9） | 以 FR-171 的 `ws-CM-3379` 為基底 | 改從 `feature/FR-172` 長 | FR-171 批 1 的套件先被合回 `feature/FR-172`，174 套件卡可以照工作坊預設的主線開，不用手動指定基底 |
| 工具代號 | 卡上寫 `cinc_auditor` | 實際是 `inspec` | 開卡時筆誤。Agent 的工具表、主控台與前端都用 `inspec`；查詢下拉要帶 `tool=inspec` |
| 下載檔名 | 從網址推得的原始檔名 | 推不出時用 `<版本 uid>-v1.tar.gz` | v1.0 已寫了這條後備規則；實際 GitHub 封存檔推不出原名，後備規則生效 |

---

## 4. 實作中踩到、影響後續案的事 {#lessons nav="影響後續"}

- **工作坊在派卡前先撞衝突**：E-1 卡要解的版號衝突，工作坊在派卡前自動同步主線時就先撞到，停在合併一半。輔助首腦照卡上裁示解掉後，工作坊才派這張卡。
- **共用 `.venv` 又被改**：Z-1 小弟在卡工作區跑 `poetry update`，卡工作區的 `.venv` 連到主資料夾那一份，主資料夾的 detection 被升到 1.8.0，比主資料夾當時的釘版 1.7.3 新。174 合回主線後兩邊才對齊。
- **DEV 儲存換新容器**：188 的 SeaweedFS 換成新容器，裡面是空的，舊檔都不在。dev-sec 兩支是重新下載所以沒受影響；TWGCB 九支基準在 DEV 下載會 404，跟本案無關。

沿革細節見 [handoff/FR-174-STATE.md](handoff/FR-174-STATE.md) 與 git log。