Policy engine
Gemini CLI policy engine 的用途：細粒度控制工具執行、替代簡單 allowed tools、適合團隊和企業治理。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Policy engine | 策略引擎 | 用規則統一管控 Agent 行為。 |
| 規則 | rule | 允許 / 攔截 / 確認的策略。 |
| 優先順序 | precedence | 多條策略的生效順序。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用 Gemini CLI 的策略引擎統一管控允許/攔截哪些操作。
你是 Gemini CLI 策略引擎顧問。
【角色】
Gemini CLI 策略引擎顧問，按最小夠用、安全合規優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 想允許 / 攔截哪些操作：___
- 高危操作有哪些：___
- 個人還是團隊統一：___
- 風險偏好：___
- 經驗水平：___
【工作流程】
1. 把需求轉成策略規則
2. 處理規則優先順序
3. 高危操作預設攔截或確認
4. 給測試規則的方式
5. 給落地
【輸出規範】
▌一、策略規則
▌二、優先順序處理
▌三、高危預設攔截
▌四、測試 + 落地
【硬約束】
- 高危操作預設攔截或確認
- 規則先測試再生效
- 團隊策略變更可審計
- 不要替我臆測情況或編造不存在的設定，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述Policy engine 用來更細粒度地控制工具能否執行、在什麼條件下執行。官方 CLI cheatsheet 裡也提示 --allowed-tools 已 deprecated，建議使用 policy engine。
許可權邊界要寫進 policy，不要只寫進 prompt。Prompt 是建議，policy 是執行前攔截。
它的核心不是“開或關某個工具”，而是按規則決定工具呼叫應該 allow、deny 還是 ask_user。規則寫在 TOML 檔案中，可以匹配工具名、引數、互動模式和優先順序。
Policy 的價值在於執行前攔截。尤其是 shell、MCP 寫工具、subagent 和自動化任務，越不能靠“模型會聽話”來控制。規則要能被負例測試觸發。
適合控制
- 哪些工具可用。
- 哪些命令需要確認。
- 哪些目錄禁止寫。
- 哪些 MCP server 可以用。
- 團隊預設安全策略。
基本規則
最常見的規則結構包含四個欄位：
toolName：匹配工具名，例如run_shell_command。commandPrefix或argsPattern：匹配命令或引數。decision：allow、deny或ask_user。priority：數字越大優先順序越高。
例如高風險 shell 字首應當直接 deny；常見但有副作用的 git、npm、pnpm、docker 命令可以先設為 ask_user。
決策含義
allow：工具直接執行，不再詢問。ask_user：讓使用者確認；headless 場景裡通常等同於 deny。deny：阻斷工具呼叫。對於全域 deny，工具還會從模型可見工具列表中排除，這比只靠 prompt 要可靠。
優先順序與層級
Policy engine 有 Default、Extension、Workspace、User、Admin 等層級。官方文件特別說明：Workspace tier 目前不可用，專案級 .gemini/policies 不會生效，應使用 User 或 Admin policies。
團隊環境裡，Admin policy 應該壓過個人設定；個人本機可以用 ~/.gemini/policies/*.toml 做預設保護。
使用建議
個人專案可以先用預設確認；團隊專案應該把 policy 寫清楚，避免每個人用不同的許可權模型。
不要只靠“請不要刪除檔案”這種 prompt 管許可權。真正的許可權邊界應該進入 policy：危險 shell 字首、未知 MCP 寫操作、生產目錄寫入、部署和刪除命令都應明確規則。
| 風險 | 建議 decision |
|---|---|
git status、rg、只讀診斷 | allow 或預設確認 |
npm install、docker、遷移命令 | ask_user |
rm -rf、生產目錄寫入 | deny |
| 未知 MCP 寫操作 | ask_user 或 deny |
| headless 中需要人工確認的動作 | deny |
驗收方式
寫完 policy 後要主動觸發測試：讓 Gemini CLI 嘗試一個應該被攔截的命令，確認它被 deny 或 ask_user；再測試一個應該允許的只讀命令，確認沒有誤傷。否則 policy 只是“看起來安全”。
還要做反向測試：確認高優先順序 deny 不會被低優先順序 allow 覆蓋，確認 headless 中 ask_user 不會變成靜默允許。團隊環境裡，每次改 policy 都應該留下測試用例和預期結果。
企業環境還應把 policy 版本化，避免各機器漂移。
如果一個動作在互動模式下是 ask_user，在無互動 headless 場景裡要按不可確認處理。自動化任務不應該依賴人工彈出視窗；需要人工確認的動作要在 CI 之前拆成審批步驟。
最小上線組合
個人專案可以從三條規則開始：允許只讀診斷，詢問安裝依賴和 Git 寫操作，拒絕刪除、部署和生產目錄寫入。團隊專案再補 MCP allowlist、subagent 限制和 Admin policy。
Policy 不需要一次寫成“大而全”。先覆蓋最危險的誤操作，再用記錄和失敗案例補規則，反而更容易維護。
接下來去哪
Enterprise config
團隊和企業要把 policy 放進統一設定與管理路徑。
MCP 設定
MCP 寫工具也要受 policy 和最小許可權控制。
Sandbox
policy 管許可權，sandbox 管執行環境，兩者配合使用。