第27章 Omnigent 的上下文感知策略
上下文感知策略（Contextual Policies）
策略控制你的 Omnigent 能做什么、不能做什么。它会拦截每一个动作（工具调用、LLM 请求、文件操作），并实时决定是放行、请求批准，还是拒绝。
为什么是“上下文感知”？
大多数 agent 框架只提供静态规则：允许这个工具、禁止那个工具。Omnigent 的策略不同，它们是有状态且动态的：每条策略在整个会话期间维护自己的状态，并根据目前发生的情况做出决策。
正是这一点，让静态系统根本无法表达的策略成为可能：
- 成本预算。跟踪每一轮对话的累计 LLM 花费。花费到 $3 时警告，到 $5 时禁止使用昂贵模型。策略会记住你已经花了多少。 - 速率限制。统计一段时间内的工具调用次数，超过阈值后拒绝。这个计数在整个会话中持续存在，而不是按请求计算。 - 风险评分。根据敏感操作（访问凭据、修改生产数据）累积风险分数。一旦分数超过阈值，就升级为人工审批。 - 模型路由。根据对话上下文将任务分类为简单或复杂，把简单任务从昂贵模型上分流出去。
每次策略评估都会收到完整的会话上下文：累计成本、工具调用历史、数据分类标签，以及你自定义的状态。这使得 Omnigent 的策略系统比单个 coding agent 内置的静态安全控制从根本上更强大。
可以强制执行的内容
例如：限制花费上限、在破坏性操作前要求批准、限制对仓库或服务的访问、屏蔽 PII，或进行模型路由。完整列表见 Builtin Policies。
策略如何工作
每条策略返回三种决策之一：
Decision — What happens ALLOW — 动作继续执行。 ASK — 动作暂停，直到用户批准或拒绝。 DENY — 动作被阻止，并返回错误信息。
策略按顺序检查，第一条返回决策的策略生效。无意见（None）则传递给下一条策略。
可用策略
Omnigent 为常见的防护需求提供了内置策略（成本预算、审批门禁、访问控制、PII 屏蔽、模型路由）。你也可以用 Python 编写自己的自定义策略，并在服务器上注册使其可用：
# server config (config.yaml) policy_modules: - myorg.policies
用该文件启动服务器：
omnigent server -c config.yaml
-c 是 --config 的缩写。这样你的自定义策略就会与内置策略一起被识别。如何编写和注册自定义策略，见 Custom Policies。
三个层级
要应用一条策略，你需要选择一个（内置或自定义），并在三个层级之一添加。每个层级的作用域和优先级不同：
Level — Who — Scope — How to add — Priority Session — 最终用户 — 仅当前会话，不持久化 — 直接告诉你的 Omnigent，或使用 UI 设置面板 — 第一 Omnigent config — 开发者 — 使用该 Omnigent 的每个会话 — Omnigent YAML 中的 policies 块 — 第二 Server-wide — 管理员 — 服务器上的所有 agent 和会话 — Settings 页面、服务器配置 YAML 或 REST API — 最后
管理员可以设置全公司的成本上限，开发者可以限制 Omnigent 能写入哪些仓库，最终用户可以添加额外的审批门禁。三个层级同时生效。
添加策略
Session 层级：直接让 Omnigent 处理（推荐）
添加策略最简单的方式就是直接告诉你的 Omnigent，用自然语言描述你想要什么：
You: 加一条策略，运行任何 shell 命令前先问我。
You: 把这个会话的 LLM 花费限制在 $5 以内。
You: 屏蔽除 myorg/frontend 之外的所有 GitHub 仓库访问。
你的 Omnigent 会从可用注册表（内置策略以及服务器上注册的自定义策略）中挑选合适的策略，配置参数，然后请求你的批准。批准后，策略立即在当前会话的下一轮生效。
你也可以在 Web UI 的设置面板中浏览和切换策略，无需在聊天中输入任何内容。
Omnigent config 层级：在 YAML 中声明
对于应该始终生效的策略，在 Omnigent 配置的 policies 块中声明。每次 Omnigent 启动时它们都会生效。
policies: approve_file_ops: type: function handler: omnigent.policies.builtins.safety.ask_on_os_tools rate_limit: type: function handler: omnigent.policies.builtins.safety.max_tool_calls_per_session factory_params: limit: 50
这里的 rate_limit 限制单个会话能进行的工具调用总次数（本例为 50），防止 agent 陷入死循环、产生意外成本。达到上限后，会话剩余部分的所有工具调用都会被拒绝。
无参数的策略只需 handler。可配置的策略需加上 factory_params。多条策略按声明顺序评估。
Server-wide 层级：服务器配置
服务器级策略适用于你部署的服务器上的所有会话。把它们添加到一个配置文件中，并用 -c 传入（--config 是完整形式）：
policies: session_cost_guard: type: function function: path: omnigent.policies.builtins.cost.cost_budget arguments: ask_thresholds_usd: [1.0] max_cost_usd: 5.0 user_daily_cost_guard: type: function function: path: omnigent.policies.builtins.cost.user_daily_cost_budget arguments: ask_thresholds_usd: [10.0, 25.0] max_cost_usd: 50.0
omnigent server -c config.yaml
服务器级策略使用 function: {path, arguments} 格式（而非 handler / factory_params）。修改配置后需重启服务器。
管理员也可以不碰配置文件，直接在 /settings/policies 的 Settings 页面管理服务器级策略。更改立即生效，无需重启服务器。
服务器级策略也可以在运行时通过 REST API 管理：
Method — Endpoint — Description POST — /v1/policies — 创建策略 GET — /v1/policies — 列出所有策略 PATCH — /v1/policies/{id} — 更新策略 DELETE — /v1/policies/{id} — 删除策略
