open-policy-agent/gatekeeper: 🐊 Policy Controller for Kubernetes 开源的门禁框架
门禁系统计划文档
本文档从“解释性材料”重构为“计划文档”,用于指导门禁系统的下一阶段落地。
1. 目标
把当前分散在 policy、gate、hook、CI、output-guard 里的规则与执行链,收敛成一套可对标行业标准的门禁系统:
Context Builder → Policy Engine → Decision → Enforcement → Observability最终要求:
有规则
有注册
有路由
有执行
有拦截
有审计2. 现状
当前系统已经具备以下能力:
- 文档层 policy:
instructions.md、hard-gates.md、defaults.md、annotated.md - 注册层:
gate-registry.json - 行为门禁:
check-ai-behavior.mjs - 任务编译链:
tools/task-pipeline/* - 本地 hook:
githooks/pre-commit - CI 门禁:
.github/workflows/contract-guard.yml - 输出门禁:
output-guard
当前缺口主要在:
Context Builder没有单独分层Decisionschema 不统一Runtime Enforcement还不够完整Observability还没有系统化
3. 目标架构
┌──────────────────────────┐
│ Client / Input │
│ (code / request / prompt)│
└────────────┬─────────────┘
↓
┌──────────────────────────────────────┐
│ Pipeline / Entry Layer │
│ (CI / Gateway / Agent / CLI / Hook) │
└────────────┬─────────────────────────┘
↓
┌──────────────────────────────────────┐
│ Context Builder Layer │
│ (extract / normalize / enrich input) │
└────────────┬─────────────────────────┘
↓
┌──────────────────────────────────────┐
│ Policy Engine Layer │
│ (OPA / Rego / rules / constraints) │
└────────────┬─────────────────────────┘
↓
┌──────────────────────────────────────┐
│ Decision Layer │
│ (allow / deny / review / score) │
└────────────┬─────────────────────────┘
↓
┌──────────────────────────────────────┐
│ Enforcement / Runtime Hook │
│ (block / retry / fallback / reject) │
└────────────┬─────────────────────────┘
↓
┌──────────────────────────────────────┐
│ Execution Layer │
│ (deploy / API call / AI output) │
└────────────┬─────────────────────────┘
↓
┌──────────────────────────────────────┐
│ Observability / Feedback │
│ (logs / audit / metrics / tracing) │
└──────────────────────────────────────┘4. 现有系统映射
4.1 已有层
Policy Layer
├── .codex/policy/*
├── gate-registry.json
└── unified-gates/config/execution-gates.json
Gate Layer
├── guards/ai-behavior/core/check-ai-behavior.mjs
├── guards/ai-behavior/core/check-frontend-design-closeout.mjs
└── unified-gates/gates/*
Pipeline Layer
├── githooks/pre-commit
├── .github/workflows/contract-guard.yml
└── output-guard4.2 缺失层
Context Builder
├── 输入解析从 gate 中拆出
└── 形成可复用 JSON context
Unified Decision
├── 统一 decision schema
└── 统一 allow / review / block 输出
Runtime Enforcement
├── 输出前强制拦截
├── 提交前强制拦截
└── CI 失败即阻断
Observability
├── gate decision log
├── audit trail
└── 命中统计5. 生命周期门禁链
change requested
↓
project contract / behavior policy
↓
plan gate
↓
pre-commit gate
↓
git commit
↓
pre-push gate
↓
git push
↓
post-push gate
↓
CI / workflow verdict
↓
pre-deploy gate
↓
deploy decision对应到 unified-gates/config/execution-gates.json 的顺序是:
pre_commit → pre_push → post_push → pre_deploy6. 门禁树状图
C:\Users\ASUS-KL
├── .codex [全局控制面 / canonical policy root]
│ ├── instructions.md
│ ├── MEMORY.md
│ ├── orchestrator\
│ ├── policy\
│ │ ├── index.md
│ │ ├── hard-gates.md
│ │ ├── defaults.md
│ │ ├── annotated.md
│ │ ├── gate-registry.json
│ │ └── remote-execution-anti-drift.md
│ ├── rules\
│ ├── automations\
│ │ ├── gateway.ps1
│ │ ├── set-contractguard-gateway-root.ps1
│ │ ├── toggle-contractguard-gateway.ps1
│ │ └── get-contractguard-gateway-status.ps1
│ └── gateway.ps1
│
├── ContractGuard [可复用门禁 / 规则系统 / 执行器仓]
│ ├── README.md
│ ├── project.json
│ ├── docs\
│ ├── templates\project-contract\
│ ├── tools\
│ │ ├── validate-project-contract.mjs
│ │ └── task-pipeline\
│ ├── guards\
│ │ └── ai-behavior\
│ │ ├── core\
│ │ │ ├── check-ai-behavior.mjs
│ │ │ └── check-frontend-design-closeout.mjs
│ │ ├── hooks\
│ │ │ ├── invoke-plan-gate.ps1
│ │ │ └── invoke-diff-gate.ps1
│ │ └── policy\
│ │ └── ai-behavior-guard.json
│ ├── unified-gates\
│ │ ├── README.md
│ │ ├── config\
│ │ │ └── execution-gates.json
│ │ ├── gates\
│ │ │ ├── pre-commit.mjs
│ │ │ ├── pre-push.mjs
│ │ │ ├── post-push.mjs
│ │ │ ├── pre-deploy.mjs
│ │ │ ├── verify-gate.mjs
│ │ │ ├── deploy-decision-check.mjs
│ │ │ ├── architecture-boundary-gate.mjs
│ │ │ └── self-verification-handoff-gate.mjs
│ │ ├── kernel\
│ │ └── tools\
│ ├── githooks\
│ │ └── pre-commit
│ ├── .github\
│ │ └── workflows\
│ │ └── contract-guard.yml
│ └── scripts\
│ └── install-git-hooks.mjs
│
├── Atramenti-Console [消费方 / 接入方 / 运行壳]
│ └── codex\
│ ├── plugins\obsidian\data\docs\blog\门禁系统.md
│ ├── mcps\output-guard\
│ │ ├── start.cmd
│ │ └── README.md
│ ├── guards\ai-behavior\
│ │ └── core\check-ai-behavior.mjs
│ └── PROJECT-CONTEXT.md
│
└── 门禁执行链
├── 文档层
│ ├── instructions.md
│ ├── hard-gates.md
│ ├── defaults.md
│ ├── annotated.md
│ └── remote-execution-anti-drift.md
├── 注册层
│ └── gate-registry.json
├── 执行层
│ ├── check-ai-behavior.mjs
│ ├── pre-commit.mjs
│ ├── pre-push.mjs
│ ├── post-push.mjs
│ ├── pre-deploy.mjs
│ ├── verify-gate.mjs
│ ├── deploy-decision-check.mjs
│ └── architecture-boundary-gate.mjs
├── 接入层
│ ├── githooks\
│ ├── .github\workflows\
│ ├── output-guard\
│ └── gateway.ps1
└── 决策层
├── allow
├── review
└── block7. 门禁类型分层图
gate-registry.json
├── hard gates
│ ├── GATE-FORMAT-001 [enforced]
│ ├── GATE-PROGRESS-001 [enforced]
│ ├── GATE-PLAN-001 [enforced]
│ ├── GATE-VERIFY-001 [enforced]
│ ├── GATE-DEPLOY-001 [enforced]
│ ├── GATE-LIVE-001 [enforced]
│ └── GATE-ARCH-001 [enforced]
├── advisory hard gates
│ ├── GATE-FIDELITY-001
│ ├── GATE-DOC-001
│ ├── GATE-README-001
│ ├── GATE-RUNTIME-003
│ ├── GATE-RUNTIME-004
│ ├── GATE-RUNTIME-005
│ └── GATE-RUNTIME-006
└── default gates
├── DEFAULT-MEMORY-001
├── DEFAULT-DOC-004
└── ...8. 迁移蓝图
Phase 0: 冻结现状
先记录当前所有 gate 的:
- 名称
- 入口
- 输入
- 输出
- 是否 enforced
Phase 1: 统一 Decision Schema
所有 gate 输出统一成:
{
"decision": "allow | review | block",
"gateId": "GATE-PROGRESS-001",
"reason": "missing [ACTION]",
"violations": [
{
"code": "MISSING_TAG",
"severity": "block",
"detail": "missing [ACTION]"
}
]
}Phase 2: 拆 Context Builder
把输入解析从 gate 内部拆出去,形成可复用上下文构建层。
Phase 3: 引入 OPA
优先只迁移 GATE-PROGRESS-001,先证明策略引擎可替换、可接管。
Phase 4: 加 Policy Adapter
新增统一调用层,把 JSON context 转成统一 decision。
Phase 5: 让 registry 变成路由表
让 gate-registry.json 不只是说明,而是能驱动执行链。
Phase 6: 实现 output-guard wrapper
让输出强制经过拦截器,再决定 allow / review / block。
Phase 7: 接入 Codex / Atramenti-Console
把 wrapper 接进现有输出链和 UI/console 路径。
Phase 8: 迁移其他 gate
按低风险到高风险迁移:
GATE-FORMAT-001
GATE-PROGRESS-001
GATE-PLAN-001
GATE-VERIFY-001
GATE-DEPLOY-001
GATE-ARCH-001Phase 9: 补 Observability
新增 gate decision 日志、审计日志和命中统计。
9. 执行级计划
下面这部分是把上面的 Phase 直接落到可执行颗粒度。原则是:
- 每个阶段都能独立交付
- 每个阶段都能独立验证
- 每个阶段失败时可以保留现状,不影响前一阶段
Milestone 1: 统一决策格式
目标:所有 gate 输出统一到一个 decision schema。
任务:
- 新建
schemas/decision.schema.json - 修改
guards/ai-behavior/core/check-ai-behavior.mjs - 修改
guards/ai-behavior/core/check-frontend-design-closeout.mjs - 为输出格式门禁补自测
文件:
E:\My Project\ContractGuard\schemas\decision.schema.jsonE:\My Project\ContractGuard\guards\ai-behavior\core\check-ai-behavior.mjsE:\My Project\ContractGuard\guards\ai-behavior\core\check-frontend-design-closeout.mjsE:\My Project\ContractGuard\tests\
验证:
- 所有 gate 返回同一组字段
allow / review / block的语义一致- 自测覆盖缺 tag、乱序、空输出三类情况
风险控制:
- 先保留旧输出兼容层
- 不一次性改所有 gate
Milestone 2: 拆 Context Builder
目标:把输入解析从 gate 逻辑中剥离出来。
任务:
- 新建
guards/context/ - 提取输出文本、标签、来源、上下文元数据
- 让 gate 只消费标准化 context
文件:
E:\My Project\ContractGuard\guards\context\build-output-context.mjsE:\My Project\ContractGuard\guards\context\build-diff-context.mjsE:\My Project\ContractGuard\guards\context\build-frontend-closeout-context.mjs
验证:
- context 结构稳定
- 同一输入总能生成同一输出
- gate 不再直接解析原始字符串
风险控制:
- 先做输出门禁的 context builder
- diff / frontend context 后续再拆
Milestone 3: 接入 OPA
目标:只让一个 gate 先接 OPA,证明链路可用。
优先级:
- 先做
GATE-PROGRESS-001 - 不要一开始迁移全部 gate
任务:
- 新建
policies/rego/progress.rego - 新建
guards/policy-engine/opa-adapter.mjs - 让
check-ai-behavior.mjs通过 adapter 调 OPA
文件:
E:\My Project\ContractGuard\policies\rego\progress.regoE:\My Project\ContractGuard\guards\policy-engine\opa-adapter.mjsE:\My Project\ContractGuard\guards\ai-behavior\core\check-ai-behavior.mjs
验证:
- 同一 context 在 JS 规则和 OPA 规则下输出一致
- OPA 失败时能 fallback 到 JS 规则或明确 block
- 规则文件变更后能独立测试
风险控制:
- 保留 JS fallback
- OPA 只负责判断,不负责上下文拼装
Milestone 4: 统一 registry 路由
目标:让 gate registry 从说明文档变成执行路由。
任务:
- 给每个 enforced gate 加上执行器路径
- 给 registry 增加
engine、contextBuilder、policy字段 - 明确每个 gate 的默认 fallback 行为
文件:
C:\Users\ASUS-KL\.codex\policy\gate-registry.jsonC:\Users\ASUS-KL\.codex\policy\policy-map.json
验证:
- registry 能反查每个 gate 的执行入口
- enforced gate 都能定位到真实文件
- advisory gate 保持不阻断
风险控制:
- 不删除旧字段
- 只做增量扩展
Milestone 5: output-guard runtime enforcement
目标:让输出门禁真正“拦得住”。
任务:
- 新建
guards/runtime/output-guard.mjs - 在 output-guard 层接 registry
- 把 gate verdict 转成 runtime block / review / allow
文件:
E:\My Project\ContractGuard\guards\runtime\output-guard.mjsE:\My Project\Atramenti-Console\codex\mcps\output-guard\start.cmdE:\My Project\Atramenti-Console\codex\mcps\output-guard\README.md
验证:
- 缺
[ACTION]时直接 block - 合规输出允许通过
- 运行时日志能记录每次决策
风险控制:
- 先只接输出门禁
- 不把所有 gate 一次性塞进 runtime wrapper
Milestone 6: 接入 Codex / Console
目标:把门禁接到实际使用链路。
任务:
- 确保
Atramenti-Console的 output-guard 走统一 gate - 确保
Codex/Claude共享同一套 policy core - 补入口文档和接线说明
文件:
E:\My Project\Atramenti-Console\codex\PROJECT-CONTEXT.mdE:\My Project\Atramenti-Console\codex\mcps\output-guard\start.cmdE:\My Project\Atramenti-Console\codex\mcps\output-guard\README.md
验证:
- 真实调用链经过 gate
- 触发 block 时不会继续输出
- 文档和 machine-readable 配置一致
风险控制:
- 先在单一入口验证
- 再扩展到其他入口
Milestone 7: 生命周期门禁齐备
目标:把 pre-commit / pre-push / post-push / pre-deploy 真正做成一条链。
任务:
- 维护
unified-gates/config/execution-gates.json - 完成
pre-push.mjs - 完成
post-push.mjs - 完成
pre-deploy.mjs
文件:
E:\My Project\ContractGuard\unified-gates\config\execution-gates.jsonE:\My Project\ContractGuard\unified-gates\gates\pre-commit.mjsE:\My Project\ContractGuard\unified-gates\gates\pre-push.mjsE:\My Project\ContractGuard\unified-gates\gates\post-push.mjsE:\My Project\ContractGuard\unified-gates\gates\pre-deploy.mjs
验证:
- 四个阶段顺序正确
- 每个阶段都有明确 on_failure 行为
- 失败阶段不会继续向后执行
风险控制:
- 先让 pre-commit 稳定
- 再补 push / deploy
Milestone 8: Observability
目标:让门禁有审计、可回放、可统计。
任务:
- 新增 gate decision log
- 记录命中规则、输入摘要、决策结果
- 形成最小 audit trail
文件:
E:\My Project\ContractGuard\logs\E:\My Project\ContractGuard\unified-gates\logs\
验证:
- 每次 block 都有可读原因
- 每次 allow 也有记录
- 后续可统计失败最多的 gate
风险控制:
- 先写 JSONL
- 不先做复杂可视化
Milestone 9: 回归测试与验收
目标:确保迁移后系统行为不漂移。
任务:
- 追加 gate 回归测试
- 追加 OPA fallback 测试
- 追加 runtime block 测试
文件:
E:\My Project\ContractGuard\tests\E:\My Project\ContractGuard\unified-gates\tests\
验证:
- 每个 milestone 都有对应测试
- 本地和 CI 结果一致
- 回归时可精确定位失败阶段
风险控制:
- 每次只推进一个 milestone
- 不在同一轮做大规模重构
10. 交付物
decision.schema.jsoncontext builder目录opa-adapteroutput-guard wrappergate decision audit log- 更新后的 registry / workflow / hook 文档
11. 完成标准
以下结果同时满足时,认为该计划完成:
- 本地提交前会拦
- 推送前会拦
- 推送后能检查 CI/CD
- 部署前有独立决策
- 所有 gate 输出统一 schema
- 所有决策可审计
12. 备注
这篇文档的定位已经从“门禁科普”变成“门禁计划”,后续新增内容优先写进:
- 目标
- 现状
- 迁移阶段
- 交付物
- 完成标准
原来的说明性正文如果继续保留,可以作为附录,但不再是主结构。
🧠 一句话本质
门禁系统 = 请求入口 + 规则判断 + 决策放行/拒绝🧱 一、传统门禁(现实世界)
结构
人
↓
门禁设备(刷卡/人脸)
↓
控制器
↓
数据库(权限)
↓
门锁对应逻辑
刷卡
→ 验证身份
→ 查权限
→ 决定开门 or 拒绝👉 核心:
身份 + 权限 + 决策🌐 二、互联网“门禁系统”(标准架构)
你现在用的所有网站,其实都有门禁。
结构图
Client(浏览器)
↓
Gateway / API入口
↓
认证(Authentication)
↓
权限判断(Authorization)
↓
业务服务拆开讲
🟢 1. 入口(Gateway)
Nginx / API Gateway作用:
接收所有请求🟡 2. 身份认证(Authentication)
你是谁?方式:
token / session / cookie / apiKey🟠 3. 权限控制(Authorization)
你能不能做这件事?比如:
普通用户 ❌ 不能调 admin API
VIP ✔ 可以用更强模型🔴 4. 决策
通过 → 继续执行
拒绝 → 返回 403 / 401🧠 三、经典门禁模型(你必须知道)
🥇 RBAC(最常见)
Role-Based Access Control结构:
用户 → 角色 → 权限例子:
user → 普通用户 → 只能用基础功能
admin → 管理员 → 可以所有操作🥈 ABAC(高级)
Attribute-Based Access Control不是看角色,而是:
属性 + 条件例子:
时间 < 22:00
IP 在白名单
请求频率 < 限制👉 你现在的 AI 系统其实更像 ABAC
🔥 四、你现在系统里的“门禁”
你其实已经在做一个门禁系统了,只是你没意识到👇
你的结构
Client(Next.js)
↓
Node Gateway(你写的)
↓
Key Pool
↓
AI实际发生的“门禁判断”
比如一个请求进来:
请求进入(Node 5101)
↓
判断:
- 用哪个 key?
- 是否超限?
- 是否允许?
↓
决定:
- 放行(调用AI)
- 拒绝(返回错误)👉 这就是:
AI 访问控制系统(门禁)🧱 五、你可以这样升级你的门禁(非常关键)
🟢 1. 身份层
API Key / 用户ID / Token🟡 2. 限流层
每个 key:
- 每分钟多少请求
- 并发多少🟠 3. 权限层
不同用户:
- 能用哪些模型
- 上下文长度限制🔴 4. 风险控制
异常请求 → 拒绝
连续失败 → 熔断🔵 5. 审计(你现在没有)
谁调用了什么
用了多少 token🧠 六、工业级门禁架构(你未来会做到)
Client
↓
API Gateway(入口)
↓
Auth(身份认证)
↓
Policy Engine(权限规则)
↓
Rate Limiter(限流)
↓
Service(业务)
↓
Audit Log(日志)🧠 七、你现在在哪个阶段
你现在已经:
✔ 有 Gateway(Node)
✔ 有资源池(key pool)
✔ 有简单调度但还缺:
❌ 明确认证(谁在用)
❌ 权限系统
❌ 限流系统
❌ 审计日志🔥 八、最关键一句话
你现在不是在“调用 AI”
👉 你在做一个“AI门禁系统”🚀 如果你继续往上走
下一步就是:
✔ 用户系统
✔ API key管理
✔ 限流(Redis)
✔ 权限策略
✔ 计费系统如果你愿意,我可以帮你把你现在这套:
AI Gateway + Key Pool升级成一个完整的:
👉 “带门禁的 AI 平台架构图”包括:
✔ 用户体系
✔ 权限
✔ 限流
✔ 计费
✔ 日志你只要说:
门禁升级我给你一版真正“能商用”的结构。
在没有清楚原理的情况下的优化是灾难
“截获每次模 型输出”的运行时拦截器。
你一直以为这条门禁是 runtime 强制,但其实它只是 flow 内强制
low 内强制 = 本流程内强制执行、不可跳过、不可绕过。
[WHY] 你现在缺的是一个真正执行器:之前记录里已经确认 GATE-FORMAT-001 / GATE-PROGRESS-001 没有绑定 enforcedBy,check-ai-behavior.mjs 也没有校验 [STEP]/[WHY]/[ACTION]/[RESULT]。
先把话说直:
你现在这套已经不是“有没有门禁”,而是门禁分层没理清。我给你一个当今工程里最标准、也最清晰的一版模型。
🧠 一、现代门禁系统 = 5 层模块
不是一坨东西,而是分层的👇
① Policy 层(规则定义)
👉 定义“什么是对/错”
包括:
-
hard-gates.md
-
instructions.md
-
gate-registry.json
特点:
-
可读
-
可讨论
-
❌ 不执行
② Mapping 层(规则 → 执行器绑定)
👉 定义“谁来执行这些规则”
包括:
-
policy-map.json
-
MASTER-CONTROL.json
特点:
-
把 rule → script / gate
-
决定执行入口
-
❗ 很容易漏(你现在的问题就在这)
③ Gate 层(执行器)
👉 真正“判断是否通过”的代码
包括:
-
check-ai-behavior.mjs
-
check-frontend-design-closeout.mjs
-
你刚加的 check-progress-format.mjs
特点:
-
可执行
-
有 PASS / BLOCK
-
是唯一有“强制性”的层
④ Orchestrator 层(调度执行)
👉 决定“什么时候跑 gate”
包括:
-
CLI / agent / workflow
-
/verify / /gsd-ui-phase
-
CI pipeline
特点:
-
控制执行时机
-
❗ 不同路径执行不同 gate
⑤ Runtime Hook(最关键)
👉 拦截“每一次输出 / 每一次提交”
包括:
-
PR CI
-
response validator
-
pre-send hook
特点:
-
真正实现“强制”
-
❗ 你现在缺的就是这层(对话场景)
🧩 二、完整流程图(标准版)
我给你一个“工业级正确结构”👇
┌──────────────┐
│ Policy │
│ (rules/spec) │
└──────┬───────┘
↓
┌──────────────┐
│ Mapping │
│ (bind rules) │
└──────┬───────┘
↓
┌──────────────┐
│ Gates │
│ (executors) │
└──────┬───────┘
↓
┌──────────────────┐
│ Orchestrator │
│ (when to run) │
└──────┬───────────┘
↓
┌──────────────────────┐
│ Runtime Hook │
│ (BLOCK / ALLOW) │
└─────────┬────────────┘
↓
┌──────────────┐
│ Final Action │
│ (reply/merge)│
└──────────────┘🔥 三、你当前系统的问题(精准定位)
你现在是这样👇
Policy ✔
Mapping ⚠️(部分)
Gate ✔
Orchestrator ✔(部分 flow)
Runtime Hook ❌(缺)具体断点
❌ 1. Mapping 没接完整
-
FORMAT / PROGRESS 没有 enforcedBy
-
没挂到执行器
❌ 2. Runtime Hook 不存在
-
对话输出没有 validator
-
assistant 可以直接绕过
❌ 3. Orchestrator 不统一
-
flow 里有 gate
-
普通对话没有
🧠 四、三种“强制等级”(这是关键认知)
Level 1:文档级(你原来很多规则)
写在 md 里 → 靠人遵守👉 ❌ 不强制
Level 2:流程级(你之前“感觉强制”的)
进入 workflow → 自动跑 gate👉 ⚠️ 半强制
Level 3:运行时级(真正强制)
任何输出 → 必须经过 gate → 不通过就拦👉 ✅ 真强制
🧩 五、不同场景的门禁流程(对比)
1️⃣ 前端 CI(你已经做对了)
code → lint → screenshot → gate → BLOCK👉 ✔ 完整闭环
2️⃣ AI 对话(你现在的问题)
prompt → assistant → 输出👉 ❌ 没 gate
3️⃣ AI + gate(正确形态)
prompt
↓
assistant draft
↓
gate check (format / behavior)
↓
PASS → 输出
BLOCK → 拦截 / 重写🎯 六、真正标准的“门禁系统定义”
一句话总结:
门禁系统 = 规则 + 执行器 + 拦截点
缺任何一个都不叫门禁。
🪓 七、你现在最关键的一刀
不是再加规则,而是:
👉 把 Gate 接到 Runtime Hook
💬 最后一句话(非常重要)
你现在的问题不是:
“门禁有哪些模块”
而是:
❗ 你的系统停在“能判断”,但还没到“能阻止”
如果你要,我下一步可以直接帮你画你这套系统的当前 vs 目标架构图(带具体文件路径),甚至给你一版:
👉 “一键把所有 gate 接到 runtime”的最小实现
那才是真正完成这套系统。