Policy 模型

Policy 是 Huoban 的印坊规矩：它把一次 AI 工作中哪些行为允许、哪些行为拒绝、哪些行为必须审批，变成可版本化、可审查、可复用的规则对象。它不是安全系统本身，也不是 runtime 拦截器。Policy 声明行为边界；validator 校验对象结构，runtime、MCP server、agent runner 或审查工具解释规则，并采取继续、拒绝或创建 Checkpoint 等实现侧动作。本页属于核心概念，解释 Policy 的设计边界和使用模型；字段级定义、必填项和 schema 约束见 Policy 规范。

声明行为边界

Policy 用 allow、deny、requireApproval 表达一次 AI 工作的行为边界。

匹配协议语义

规则匹配 capabilities、sideEffects 和 trustLevels，不是匹配工具私有命令。

保守处理 unknown

未声明副作用推荐进入 requireApproval，严格场景可以直接 deny。

触发 Checkpoint

requireApproval 表示不能自动继续，应进入一次具体的 Checkpoint 决策边界。

Policy 不是安全系统

Policy 的第一性职责是把行为边界对象化，而不是提供完整安全执行环境。

对象	职责	不承担
`Profile`	提供判断语境、团队偏好、架构原则和风险信号。	不直接授权写文件、发布远端、访问密钥或花钱。
`Policy`	声明 capability、side effect、trust level 下的 allow / deny / requireApproval。	不执行阻断，不保存审批结果，不记录实际副作用。
`Checkpoint`	承载一次具体审批或判断请求。	不定义长期规则。
`Run`	记录本次使用哪些 Policy，以及实际观察到哪些副作用。	不重新定义 Policy 规则。
`Trust`	记录对象来源、审查状态、信任等级和 sandbox 要求。	不自动授予危险行为权限。

一句话：Policy 是印坊规矩；它不决定文章写什么，也不替代校对，只声明哪些印刷动作可以做、哪些动作必须请示、哪些动作不能碰。

与 Profile 的边界

Profile 告诉 AI 在什么语境下判断，Policy 告诉系统什么行为被允许。

内容	归属
这个项目偏好小改动。	`Profile`
发布远端变更必须审批。	`Policy`
团队要求先写设计说明。	`Profile`
访问 secret 必须拒绝或审批。	`Policy`
架构上避免跨层依赖。	`Profile`
未声明 side effect 默认 requireApproval。	`Policy`

Profile 可以提供风险信号或 policyDerivationNotes，但不能直接授权副作用。由 Profile 派生出的 Policy 必须作为独立对象审查后使用。

与 Checkpoint 的边界

Policy 声明规则，Checkpoint 承载事件。

# Policy spec fragment
rules:
  - effect: requireApproval
    when:
      sideEffects:
        - publishRemote
        - accessSecret

effect=requireApproval 表示匹配到这些行为时不能自动继续；实现应创建或要求一个 Checkpoint。Checkpoint 的 approve、requestChanges、reject 只是这一次 run 的决策结果，不会改变 Policy 本身。

与 Run 的边界

Policy 是规则对象，Run 是执行事实对象。

# Run spec fragment
policyRefs:
  - name: safe-defaults

# Run status fragment
observedSideEffects:
  - type: writeFile
    path: examples/generated/idea-to-spec-review-dry-run.yaml

边界是：

Run.spec.policyRefs 声明本次执行采用的 Policy。
Run.status.observedSideEffects 记录实际观察到的副作用。
Policy 不保存 observed side effects。
Run 不复制 Policy 规则。

Run.spec.snapshot.policyRefHash 散列本次 policyRefs 列表，但不散列被引用 Policy 的完整内容。内容级不可变性仍需 generation、外部内容寻址存储或实现声明的额外证据。

与 Preflight 的边界

Preflight 检查并记录“当前环境是否具备执行条件”，Policy 判断“即使具备条件，这个行为是否允许”。

问题	负责结构
Skill / Adapter 能否解析、程序是否存在、MCP tool 是否可发现？	`Requirement` + `Preflight`
`networkAccess`、`sendMessage`、`publishRemote` 是否允许？	`Policy`
需要审批时，这一次允许哪些决策动作？	`Checkpoint`

当前 reference Preflight 只解析 Policy 引用，不执行 Policy.spec.rules。PreflightReady=True 不是授权；实现不能因为依赖已就绪而跳过 Policy、Trust 或 Checkpoint。

与 Trust 的边界

Trust 回答这个对象来自哪里、是否经过审查、需要什么 sandbox；Policy 回答在这个信任等级下哪些行为允许、拒绝或需要审批。

情况	Policy 可以怎样处理
`trustLevels` 包含 `unknown`	对写文件、执行命令、访问网络等副作用 `requireApproval` 或 `deny`。
对象来源经过 review	仍按 side effect 和 capability 检查规则。
sandbox 要求未知	当前 Policy 不能直接匹配 sandbox 状态；实现可以基于 Trust / sandbox 信息创建 Checkpoint，或等待未来扩展 Policy matcher。

高 trust 不等于自动允许危险行为。低 trust 可以让 Policy 更保守，但不由 Trust 单独决定行为。

与 Skill / Adapter 的边界

Skill 和 Adapter 提供声明：能力、输入输出和 declared side effects。Policy 使用这些声明做规则匹配，但不把它们当作事实。

对象	表达内容
`Skill` / `Adapter`	声明 capability、输入输出和 declared side effects；`Adapter` 可引用 Trust，`Skill` 的信任信息由独立 `Trust` 对象描述。
`Policy`	基于 capability、side effect、trust level 判断 allow / deny / requireApproval。
`Run`	记录 observed side effects 和 condition。
`Checkpoint`	承载 requireApproval 后的一次具体判断请求。

如果 observed side effects 超出 declared side effects，应进入 Run.status.observedSideEffects 和 condition，例如 UndeclaredSideEffectObserved，并可能触发 Checkpoint。 Lifecycle Handler 的 provider 也遵守同一规则。stage 成功后上报通常声明 networkAccess、sendMessage；即使 handler 是 bestEffort 且 Preflight 可解析，实际投递仍不能绕过 Policy 和 Trust。

不是命令黑名单

Policy 不应该主要匹配 shell 命令或某个 runner 的私有字段。不要把规则中心写成：

# Not a Huoban Policy rule
deny:
  commands:
    - git push
    - rm -rf
    - curl

应该写协议层语义：

rules:
  - effect: requireApproval
    when:
      sideEffects:
        - publishRemote
        - accessSecret
  - effect: deny
    when:
      sideEffects:
        - modifyGitHistory

publishRemote、accessSecret、modifyGitHistory 是协议层副作用；git push、gh release、curl 只是不同工具对这些副作用的实现方式。

effect

v1alpha1 的 Policy 只有三种 effect。

effect	语义
`allow`	匹配时允许自动继续。
`deny`	匹配时拒绝继续。
`requireApproval`	匹配时必须进入审批边界。

告警、审计、沙箱、限流、隔离和升级处理属于未来扩展或实现侧行为，不是当前 rules[].effect 已经支持的字段值。

unknown side effect

defaults.unknownSideEffect 决定未声明副作用的默认处理方式。

值	语义
`allow`	未声明副作用也允许继续。
`deny`	未声明副作用直接拒绝。
`requireApproval`	未声明副作用必须进入审批边界。

v1alpha1 允许三种值，但开放生态的推荐默认是 requireApproval。未知副作用不能被当作安全行为；它至少应该进入审批边界，严格场景可以直接 deny。

标准治理对象

Policy 属于标准治理对象。最小实现可以先验证 Skill / Profile / Flow / Run / Checkpoint 链路，但公开生态、公司落地和可复盘执行必须引入 Policy。没有 Policy，Huoban 可以描述工作结构，却不能稳定表达副作用、审批和权限边界。

行业语言映射

用当前行业语言看，Policy 位于 policy-as-code、permission boundary、approval gate 和 agent safety 的交叉点。

行业概念	Huoban 表达
policy-as-code	规则进入声明式 `Policy` 对象，而不是散落在工具配置里。
permission boundary	行为边界以 side effect、capability 和 trust level 表达。
approval gate	`requireApproval` 触发 `Checkpoint`，但不是审批结果。
agent safety	行为边界可被不同 agent、tool、MCP server 和 runtime 共同解释。

Huoban 不把这些概念堆进一个安全大对象里，而是让 Policy 专注回答一个问题：在当前能力、副作用和信任条件下，这次 AI 工作是否可以继续。

结构示例

apiVersion: huoban.dev/v1alpha1
kind: Policy
metadata:
  name: safe-defaults
spec:
  defaults:
    unknownSideEffect: requireApproval
  rules:
    - effect: requireApproval
      when:
        sideEffects:
          - publishRemote
          - spendMoney
          - accessSecret
    - effect: deny
      when:
        sideEffects:
          - modifyGitHistory

这个示例来自 examples/policies/safe-defaults.yaml。它展示的是保守默认策略：未知副作用需要审批，远端发布、花钱和访问密钥需要审批，修改 Git 历史直接拒绝。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

声明行为边界

匹配协议语义

保守处理 unknown

触发 Checkpoint

Policy 不是安全系统

与 Profile 的边界

与 Checkpoint 的边界

与 Run 的边界

与 Preflight 的边界

与 Trust 的边界

与 Skill / Adapter 的边界

不是命令黑名单

effect

unknown side effect

标准治理对象

行业语言映射

结构示例

声明行为边界

匹配协议语义

保守处理 unknown

触发 Checkpoint

​Policy 不是安全系统

​与 Profile 的边界

​与 Checkpoint 的边界

​与 Run 的边界

​与 Preflight 的边界

​与 Trust 的边界

​与 Skill / Adapter 的边界

​不是命令黑名单

​effect

​unknown side effect

​标准治理对象

​行业语言映射

​结构示例

Policy 不是安全系统

与 Profile 的边界

与 Checkpoint 的边界

与 Run 的边界

与 Preflight 的边界

与 Trust 的边界

与 Skill / Adapter 的边界

不是命令黑名单

effect

unknown side effect

标准治理对象

行业语言映射

结构示例