策略引擎

策略引擎

Gemini CLI 包含一个强大的策略引擎，它提供了对工具执行细粒度的控制。它允许用户和管理员定义规则，以决定是否允许、拒绝或需要用户确认工具调用。

快速开始

要创建您的第一个策略：

1. 创建策略目录（如果它不存在）：

   mkdir -p ~/.gemini/policies

2. 创建一个新的策略文件（例如，~/.gemini/policies/my-rules.toml）。您可以使用任何以 .toml 结尾的文件名；该目录中的所有此类文件将被加载并组合：

   [[rule]]
   toolName = "run_shell_command"
   commandPrefix = "git status"
   decision = "allow"
   priority = 100

3. 运行一个触发策略的命令（例如，请求 Gemini CLI git status）。现在工具将自动执行，无需确认提示。

核心概念

策略引擎基于一组规则运行。每条规则都是条件和结果的组合。当大型语言模型想要执行一个工具时，策略引擎评估所有规则，以找到与工具调用匹配的优先级最高的规则。

规则主要由以下组成部分构成：

• 条件：工具调用必须满足的，使规则适用的标准。这可以包括工具的名称、提供给它的参数，或当前的审批模式。
• 决策：如果规则匹配，要执行的动作（允许、拒绝或请求用户确认）。
• 优先级：决定规则优先顺序的数字。数字越高，优先级越高。

例如，这条规则将在执行任何 git 命令前请求用户确认。

[[rule]]
toolName = "run_shell_command"
commandPrefix = "git "
decision = "ask_user"
priority = 100

条件

条件是工具调用必须满足的，使规则适用的标准。主要条件是工具的名称和其参数。

工具名称

规则中的 toolName 必须与被调用的工具的名称相匹配。

通配符：对于模型托管协议（MCP）服务器，您可以使用通配符。一个 toolName 的 my-server__* 将匹配 my-server MCP 中的任何工具。

参数模式

如果指定了 argsPattern，工具的参数会被转换成一个稳定的 JSON 字符串，然后与提供的正则表达式进行测试。如果参数与模式不匹配，则该规则不适用。

决策

规则可以实施的三个可能决策如下：

• allow：工具调用在无用户交互的情况下自动执行。
• deny：工具调用被阻止且不执行。
• ask_user：提示用户批准或拒绝工具调用。（在非交互模式下，这被视为 deny。）

优先级系统和层级

策略引擎使用复杂的优先级系统来解决当单个工具调用匹配多个规则时的冲突。核心原则很简单：优先级最高的规则胜出。

为了提供一个清晰的层次结构，策略被组织成三个层级。每个层级都有一个指定的数字，该数字构成了最终优先级计算的基础。

层级	基础	描述
默认	1	随 Gemini CLI 一起提供的内置策略。
用户	2	用户定义的自定义策略。
管理员	3	由管理员管理的策略（例如，在企业环境中）。

在 TOML 策略文件中，您可以分配一个从 0 到 999 的优先级值。引擎使用以下公式将其转换为最终优先级：

final_priority = tier_base + (toml_priority / 1000)

这个系统保证了：

管理员策略始终覆盖用户和默认策略。 用户策略始终覆盖默认策略。 您仍然可以在单个层级内对规则进行排序，以实现细粒度的控制。

例如：

• 默认策略文件中的 priority: 50 规则变为 1.050。
• 用户策略文件中的 priority: 100 规则变为 2.100。
• 管理员策略文件中的 priority: 20 规则变为 3.020。

审批模式

审批模式允许策略引擎根据命令行界面的操作模式应用不同的规则集。一条规则可以与一个或多个模式相关联（例如，yolo，autoEdit）。只有当命令行界面运行在其指定模式之一时，该规则才会生效。如果规则没有指定模式，则它始终有效。

规则匹配

当工具调用发生时，引擎会检查所有活动的规则，从最高优先级开始。第一个匹配的规则决定了结果。

如果满足规则的所有条件，则规则与工具调用匹配：

1. 工具名称：规则中的 toolName 必须与被调用的工具名称相匹配。
   • 通配符：对于模型托管协议（MCP）服务器，可以使用通配符。一个 toolName 为 my-server__* 的规则将匹配来自任何 my-server MCP 的工具。
2. 参数模式：如果指定了 argsPattern，则工具的参数会被转换成一个稳定的JSON字符串，然后该字符串会与提供的正则表达式进行测试。如果参数与模式不匹配，则该规则不适用。

配置

策略在 .toml 文件中定义。命令行界面从默认、用户目录（如果配置了）和管理员目录加载这些文件。

TOML 规则架构

以下是 TOML 策略规则中可用的字段细分：

[[rule]]
# A unique name for the tool, or an array of names.
toolName = "run_shell_command"

# (Optional) The name of an MCP server. Can be combined with toolName
# to form a composite name like "mcpName__toolName".
mcpName = "my-custom-server"

# (Optional) A regex to match against the tool's arguments.
argsPattern = '"command":"(git|npm)'

# (Optional) A string or array of strings that a shell command must start with.
# This is syntactic sugar for `toolName = "run_shell_command"` and an `argsPattern`.
commandPrefix = "git "

# (Optional) A regex to match against the entire shell command.
# This is also syntactic sugar for `toolName = "run_shell_command"`.
# Note: This pattern is tested against the JSON representation of the arguments (e.g., `{"command":"<your_command>"}`), so anchors like `^` or `$` will apply to the full JSON string, not just the command text.
# You cannot use commandPrefix and commandRegex in the same rule.
commandRegex = "^git (commit|push)"

# The decision to take. Must be "allow", "deny", or "ask_user".
decision = "ask_user"

# The priority of the rule, from 0 to 999.
priority = 10

# (Optional) An array of approval modes where this rule is active.
modes = ["autoEdit"]

使用数组（列表）

为了将同一规则应用于多个工具或命令前缀，您可以提供字符串数组给 toolName 和 commandPrefix 字段。

示例：

这个单一规则将同时应用于 write_file 和 replace 工具。

[[rule]]
toolName = ["write_file", "replace"]
decision = "ask_user"
priority = 10

run_shell_command 的特殊语法

为了简化对 run_shell_command 编写策略，您可以使用 commandPrefix 或 commandRegex，而不是更复杂的 argsPattern。

• commandPrefix：如果 command 参数以给定字符串开头，则匹配。
• commandRegex：如果 command 参数与给定的正则表达式匹配，则匹配。

示例：

这条规则将在执行任何 git 命令之前要求用户确认。

[[rule]]
toolName = "run_shell_command"
commandPrefix = "git "
decision = "ask_user"
priority = 100

对 MCP 工具的特殊语法

您可以使用 mcpName 字段或通配符模式创建针对来自模型托管协议（MCP）服务器的工具的规则。

1. 使用 mcpName

要针对特定服务器上的特定工具，结合使用 mcpName 和 toolName。

# Allows the `search` tool on the `my-jira-server` MCP
[[rule]]
mcpName = "my-jira-server"
toolName = "search"
decision = "allow"
priority = 200

2. 使用通配符

要创建适用于特定 MCP 服务器上所有工具的规则，只需指定 mcpName。

# Denies all tools from the `untrusted-server` MCP
[[rule]]
mcpName = "untrusted-server"
decision = "deny"
priority = 500

默认策略

Gemini CLI 附带一组默认策略，以提供开箱即用的安全体验。

• 只读工具（如 read_file, glob）通常允许。
• 代理委派（如 delegate_to_agent）允许（子代理操作会单独检查）。
• 写入工具（如 write_file, run_shell_command）默认为**ask_user**。
• 在**yolo**模式下，一个高优先级规则允许所有工具。
• 在**autoEdit**模式下，规则允许某些写入操作在不提示的情况下发生。