---
title: "AI 守門調整手冊 (FR-122)"
brand: "Guidant AI · **FR-122** AI 閘道與檔案沙箱"
eyebrow: "FR-122 · 維運手冊 · 隨產品交付"
h1: "AI 守門怎麼調：改哪個檔、改完怎麼生效、改壞怎麼救"
lede: "給客戶端維運人員。AI 助理、AI 儀表板、證據自動分類送給 AI 前後的守門規則與 AI 指示都在主機一個目錄裡，**放寬或收緊不必重裝、不必換版**：改檔、重啟兩個服務即生效。"
chips: [
  {text: "不用重 build", kind: ok},
  {text: "升級不蓋客戶改動", kind: ok},
  {text: "改壞會擋啟動並指出檔案行號", kind: plain}
]
---
# AI 守門調整手冊

> **適用對象**：客戶端的系統維運人員（能登入主機、執行 `docker compose` 的人）。
> **本文用途**：說明 AI 功能（AI 助理、AI 儀表板、證據自動分類）送給 AI 之前與之後的「守門」怎麼運作，以及現場要放寬或收緊時**改哪個檔、哪一段、改完怎麼生效、怎麼確認**。改這些都不必重裝、不必換版。
> **不在本文範圍**：AI 金鑰與額度設定（在系統畫面「系統設定分組 › AI 用量」與 AI 設定頁操作）、證據分類的判斷標準（在後台「AI 分類設定」調整，見第三節最後）。

**變更紀錄**

| 日期 | 內容 |
|------|------|
| 2026-09-30 | 首版：守門規則與三段 prompt 的位置、常見調整食譜、升級時的保留與合併、改壞了怎麼救 |

---

## 一、先懂三件事

**① 所有 AI 呼叫都經過同一道閘門。** 使用者在 AI 助理打的字、儀表板的需求、分類時讀到的證據內容，都先過閘門檢查才送給 AI；AI 的回答回來時也再檢查一次。

**② 閘門的行為全部寫在主機上的一個目錄裡**：

```
/srv/guidant-ai/ai-gateway-rules/
├── gateway_rules.yaml          守門規則：什麼要遮、什麼要標記、什麼要擋
├── presidio_recognizers.yaml   自訂的機敏資料格式（身分證字號、AWS 金鑰…）
└── prompts.yaml                各功能給 AI 的固定指示（角色、判斷方式）
```

> 資料目錄若安裝時改過（不是 `/srv/guidant-ai`），以 `sudo guidantai status` 顯示的資料目錄為準，下文一律以 `/srv/guidant-ai` 舉例。

**③ 改完一定要重啟兩個服務才生效**（用 `restart` 就夠，這個目錄不是 `start` 才會讀的設定檔）：

```bash
sudo guidantai restart guidant-api
sudo guidantai restart guidant-worker
```

每一行會等該服務健康檢查通過才結束。兩個都要重啟：`guidant-api` 管 AI 助理與儀表板，`guidant-worker` 管證據自動分類。只重啟一個，另一邊還是舊規則。

> 改檔前先備份一份：`sudo cp -a /srv/guidant-ai/ai-gateway-rules /srv/guidant-ai/ai-gateway-rules.bak-$(date +%F)`。

---

## 二、守門規則怎麼讀（gateway_rules.yaml）

檔案裡的 `rules:` 底下一條一條規則，每條長這樣：

```yaml
  - id: offtopic-bot          # 規則名稱，會出現在 AI 呼叫紀錄裡，全檔不可重複
    feature: ai-bot           # 套用在哪個功能
    detector: offtopic        # 用哪一種偵測方式
    action: block             # 命中後怎麼處置
    params: {...}             # 這種偵測方式的細部設定
```

**feature（功能）**

| 值 | 代表 |
|----|------|
| `ai-bot` | AI 助理 |
| `ai-dashboard.*` | AI 儀表板（挑資料來源＋設計圖表兩步都套） |
| `classification` | 證據自動分類 |
| `"*"` | 全部功能 |

**action（處置）**——對應 AI 呼叫紀錄頁「處置」欄的顯示：

| 值 | 畫面顯示 | 效果 |
|----|---------|------|
| `redact` | 遮蔽後送出 | 命中的那一段換成「[已遮蔽]」再送給 AI，使用者照常拿到回答 |
| `flag` | 標記 | 照常送出，只在紀錄上留一筆，事後可查 |
| `block` | 阻擋 | 不送出，使用者看到一句說明 |

**detector（偵測方式）**，共四種：

| 值 | 在找什麼 | 主要設定 |
|----|---------|---------|
| `format` | 固定格式的文字：私鑰、身分證字號、要求列出密碼、直接貼 SQL／指令 | `pattern`（比對的樣式）、`reply`（擋下時回給使用者的話） |
| `presidio` | 常見個資：信用卡、email、電話、IP、AWS 金鑰、身分證字號 | `entities`（要找哪幾類）、`min_score`（多像才算，0～1） |
| `prompt_guard` | 企圖操控 AI 的輸入（「忽略以上指示…」這類） | 門檻在檔案最上方 `thresholds.prompt_guard` |
| `offtopic` | 與本系統無關的閒聊（寫詩、天氣、股票…），**只用在 AI 助理** | `allow_topics`、`offtopic_patterns`、`reply` |

> 本檔最上方另有 `scan_segments` 與 `counts_rate` 兩段，分別決定「每個功能檢查哪些內容」與「哪些呼叫計入每分鐘次數」，屬於系統對接設定，**不要改**。

---

## 三、常見調整食譜

每一條的格式都是：**改哪裡 → 重啟（第一節③）→ 怎麼確認**。確認一律到系統畫面 **「系統設定分組 › AI 用量」→「呼叫明細」**，找你剛才那一筆，看「處置」欄；點該列可看「守門命中」是哪條規則。

### 食譜 1：AI 助理要多放行一類主題

**情境**：使用者問「個資法第幾條規定…」被回「我只能回答 Guidant AI 的操作與合規稽核相關問題」。

AI 助理的擋有兩層，要先分清楚是哪一層擋的：

- 回覆**正好是**「我只能回答 Guidant AI 的操作與合規稽核相關問題。」→ 是**閘門**擋的（離題規則），AI 根本沒收到。改 `gateway_rules.yaml`。
- 回覆是 AI 自己寫的一段婉拒（每次措辭不同）→ 是 **AI 依角色設定婉拒**。改 `prompts.yaml`（見食譜 5）。

**閘門擋的改法**：打開 `gateway_rules.yaml`，找 `id: offtopic-bot`，在 `allow_topics` 加上主題關鍵字：

```yaml
      allow_topics: [合規, 稽核, 控制, 證據, 風險, SSP, 問卷, 專案, 框架, 報表, 任務, 權限,
                     Guidant, ISO, NIST, CMMC, 資安, 政策, 程序, 帳號, 登入, 上傳, 匯入, 匯出, 儀表板,
                     個資, GDPR]
```

規則是：**句子裡只要出現任何一個 allow_topics 的字，就不算離題**。加字只會放行，不會多擋。

**確認**：重啟後再問一次，不再是上面那句固定的回覆，改由 AI 回答；呼叫明細「狀態」為「成功」、「處置」為「放行」。

> 放行只代表**問題送得到 AI**。AI 還是會依 `prompts.yaml` 的角色設定決定要不要答——主題不在角色範圍內的話，它會自己婉拒（每次措辭不同）。兩層都要放寬，才會真的得到答案，另一層見食譜 5。

### 食譜 2：AI 助理要多擋一類問題

**情境**：不希望 AI 助理回答「推薦投資標的」這類問題。

在 `offtopic-bot` 的 `offtopic_patterns` 加一行樣式：

```yaml
      offtopic_patterns:
        - ...（原有的保留）
        - "(投資|理財).{0,10}(標的|建議|推薦)"
```

樣式寫法：`(A|B)` 表示 A 或 B；`.{0,10}` 表示中間可夾 0～10 個任意字（避免換個說法就繞過）。

> ⚠️ **只有「命中樣式」且「沒提到 allow_topics 任何字」才會擋**。所以「資安投資建議」不會被擋（提到「資安」）。這是刻意的：寧可漏擋閒聊，也不要誤擋正事。

**確認**：問「推薦投資標的」→ 回罐頭訊息；呼叫明細「處置」為「阻擋」，守門命中 `offtopic-bot`。

### 食譜 3：某功能不要遮 email

**情境**：AI 儀表板要依寄件者 email 做統計，但 email 被遮成「[已遮蔽]」。

找 `id: pii-redact-dashboard`，從 `entities` 拿掉 `EMAIL_ADDRESS`：

```yaml
  - id: pii-redact-dashboard
    feature: ai-dashboard.*
    detector: presidio
    action: redact
    params:
      entities: [CREDIT_CARD, PHONE_NUMBER, IP_ADDRESS, AWS_ACCESS_KEY, TW_NATIONAL_ID]
```

AI 助理那邊是 `pii-redact-bot`，要調就改那一條；兩條互不影響。

> ⚠️ 不遮就代表這類資料會原樣送到 AI 供應商。改之前請確認貴單位的資料外送政策允許。

**確認**：呼叫明細點該筆 →「守門命中」不再出現 `EMAIL_ADDRESS`。

### 食譜 4：「標記」那一級要改成直接擋／直接放行

以「企圖操控 AI」為例，檔案最上方：

```yaml
thresholds:
  prompt_guard: {flag: 0.8, block: 0.95}
```

每句輸入會得到一個 0～1 的分數，越高越像操控。**分數 ≥ flag 記為「標記」、≥ block 直接「阻擋」**。

| 想要 | 改法 |
|------|------|
| 更嚴：多擋一些 | 調低 `block`，例如 `0.9` |
| 更鬆：少記一些標記 | 調高 `flag`，例如 `0.9` |
| 某條規則整條改成直接擋 | 把該條的 `action: flag` 改成 `action: block` |
| 某條規則整條不要擋、只記錄 | 把該條的 `action: block` 改成 `action: flag` |

> 證據自動分類那條（`injection-classification`）有 `never_block: true`，分數再高也只標記——證據檔本來就常含「忽略」「指示」這類字，擋了會讓整批分類失敗。**不建議拿掉**。

**確認**：呼叫明細「處置」欄從「標記」變「阻擋」（或反之）。

### 食譜 5：AI 回答太保守或太寬

改 `prompts.yaml`。每段上方都有註解說明它管什麼、改了會怎樣，**動手前先讀那段註解**。

| 功能 | 位置 | 管什麼 |
|------|------|--------|
| AI 助理 | `ai-bot:` → `role:` | 角色設定：哪些主題要完整回答、哪些要婉拒 |
| AI 儀表板 | `ai-dashboard:` → `select:` | 判斷使用者是要看資料、要執行操作、還是無關，並挑一個資料來源 |
| 證據分類 | `classification:` → `persona:`／`guidance:` | 最後一道退路，**平常不生效**（見下方說明） |

**例：AI 助理對「個資法」一律婉拒（不是閘門擋的）**——在 `role:` 那段範圍清單加上去：

```yaml
  role: |-
    你是 Guidant AI 的合規稽核助理。你的服務範圍包括：①本系統的操作說明；②資安合規領域知識——ISO 27001、NIST、CMMC、SSP、個資法、控制項、證據、風險評估等框架與名詞解釋、稽核實務問答。…（其餘不動）
```

**寫法規則**：

- `role: |-` 下一行起、**比 `role:` 多縮排兩格**的內容，就是整段文字（可以換行）。縮排少了會被當成下一個設定，整個檔就壞了。
- 不要用 Tab，一律空白。
- 某段整段刪掉或留空 → 該功能自動改用系統內建的同一段文字，不會壞。
- 儀表板那段最後一行「只返回 JSON…」的欄位名與三個 intent 值是系統對接格式，**不可改**。

**關於證據分類**：分類給 AI 的角色與判斷標準，以後台「**AI 分類設定**」為準（出廠附一筆「出廠通用設定」）。`prompts.yaml` 的 `classification` 只在後台設定讀取失敗時頂上。**要調分類，請改後台的分類設定**。

**確認**：重啟後在 AI 助理問同一句，看回答是否符合預期。AI 回答本身有隨機性，請多問兩三次再判斷。

### 食譜 6：加一種自家機敏格式（例如員工編號）

**情境**：員工編號格式是 `EMP` 加 6 位數字（`EMP123456`），不希望送給 AI。

在 `gateway_rules.yaml` 的 `rules:` 底下新增一條（放在「小幫手」那一區即可）：

```yaml
  - id: employee-id-bot
    feature: ai-bot
    detector: format
    action: redact
    params:
      entity: EMPLOYEE_ID
      pattern: "(?<![A-Za-z0-9])EMP\\d{6}(?![A-Za-z0-9])"
```

- `id` 取一個全檔沒用過的名字。
- 要儀表板也遮，就再抄一條，`id` 改成 `employee-id-dashboard`、`feature` 改成 `ai-dashboard.*`。
- `pattern` 裡的反斜線要寫兩個（`\\d`）。`(?<![A-Za-z0-9])` 與 `(?![A-Za-z0-9])` 是「前後不能緊接英數字」，避免誤抓長字串中間的一段。
- 要直接擋而不是遮，把 `action` 改成 `block`，並在 `params` 加一行 `reply: "請勿輸入員工編號。"`。

**確認**：在 AI 助理輸入「EMP123456 的權限怎麼設」→ 呼叫明細「處置」為「遮蔽後送出」，守門命中 `employee-id-bot`／`EMPLOYEE_ID`。

---

## 四、升級時規則目錄怎麼處理

**升級不會蓋掉你改過的檔。** 升級程式（`install.sh --upgrade`）對這個目錄只做兩件事：

1. **把新版出廠原檔整份放到 `/srv/guidant-ai/ai-gateway-rules.default/`**（每次升級都換新）
2. **`ai-gateway-rules/` 裡缺哪個檔才補哪個**，已存在的一律不動

升級過程若印出：

```
以下規則檔與本版出廠版不同，已保留現場版本不覆蓋：prompts.yaml
```

代表你手上那份與新版出廠版不一樣——可能是你改過、也可能是新版出廠有調整、或兩者都有。**系統照樣用你那份**，但新版的調整不會自動進來。建議升級後比對一次：

```bash
cd /srv/guidant-ai
sudo diff ai-gateway-rules.default/prompts.yaml ai-gateway-rules/prompts.yaml
```

- 差異**全是你自己改的** → 不必動。
- 有**你沒改過、新版出廠多出來或改掉的段落** → 把那幾段抄進 `ai-gateway-rules/` 那份，然後重啟（第一節③）。

> 想整份回到新版出廠、放棄自己的修改：`sudo cp ai-gateway-rules.default/<檔名> ai-gateway-rules/<檔名>` 再重啟。

---

## 五、改壞了怎麼救

**症狀一：重啟後 `guidant-api` 或 `guidant-worker` 起不來。** 看 log：

```bash
sudo guidantai logs guidant-api       # 分類那邊換成 guidant-worker；Ctrl-C 離開
```

YAML 寫壞時會看到類似：

```
[FATAL] 啟動失敗：AI 相關必要設定缺 1 項
  - AI_GATEWAY_RULES_DIR 內的 prompts.yaml 格式錯誤：… 無法解析：while scanning a quoted scalar
  in "<unicode string>", line 2, column 9:
```

訊息會指出**哪個檔、第幾行**。最常見的原因：縮排少了兩格、引號沒關、用了 Tab、規則 `id` 重複。

**最快的救法——整份換回出廠版**：

```bash
cd /srv/guidant-ai
sudo cp ai-gateway-rules/<壞掉的檔名> ai-gateway-rules/<壞掉的檔名>.broken   # 留一份，方便事後找錯
sudo cp ai-gateway-rules.default/<壞掉的檔名> ai-gateway-rules/<壞掉的檔名>
sudo guidantai restart guidant-api
sudo guidantai restart guidant-worker
```

改動前有照第一節備份的話，也可以直接換回備份那份。

**症狀二：`ai-gateway-rules.default/` 也不見了**——可以從執行中的映像直接取出出廠版：

```bash
cd /srv/guidant-ai
VER=$(sed -n 's/^GUIDANT_VERSION=//p' .env)
CID=$(sudo docker create guidant-ai-be:$VER)
sudo docker cp $CID:/opt/guidant/ai-gateway-rules/. ai-gateway-rules.default/
sudo docker rm $CID
```

**症狀三：`prompts.yaml` 不小心刪掉了**——服務照常啟動、行為跟出廠一樣（自動改用系統內建文字），log 會多一行「找不到 prompts.yaml」的警告。要補回來照上面換回出廠版即可。

> ⚠️ **不要把 `ai-gateway-rules/` 整個目錄刪掉或清空**：服務會因為找不到 `gateway_rules.yaml` 起不來（它不會自動退回映像內建那份）。