ControlKeel

ControlKeel

将团队的工作方式转化为 AI Agent 可执行的记忆。——@arya_minus

**ControlKeel 是面向日常治理工程的 Agent 控制平面。**它通过观察、发现问题和评估，学习你的意图规则、审查偏好和交付习惯，并将它们转化为类型化记忆、策略检查和证明包。CK 位于你的编码 Agent 与生产环境之间，充当可移植的“公司大脑”：对比预期交付与实际交付，并将 Agent 的原始意图转化为经过策略验证的任务。

如果你现在正在使用 AI Agent，很可能有一个 *.md 文件告诉它该如何行动。但规则／规格文件只是对模型作出的承诺。**ControlKeel 会强制验证输出。**除了发现 Bug，CK 还解决“未知的未知”问题：无需在每次会话中都重新解释你的领域知识。

产品循环

1. 捕获意图和策略——范围、风险、预算、领域包和人工偏好都会成为 CK 状态。
2. 验证 Agent 输出——确定性检查和可选的建议性审查会在高风险工作进入 main 之前生成发现。
3. 只在需要时设门禁——当意图、风险或策略有要求时，由人工批准高影响操作。
4. 持久化证据——发现、审查、证明、记忆、成本和任务结果在切换主机后仍然保留。
5. 通过评估改进——跟踪记录和反复出现的失败会成为针对特定测试套件和对象的有限回归证据。

运行原则很简单：把 token 花在探索上，而非重复探索上。 反复出现的行为会经过人工把关的确定性晋级流程； 当其回归证据通过后，检查、API、CLI 或工作流就会处理已知情况，而 Agent 只需处理例外情况和真正的新不确定性。

ControlKeel 将你的领域知识从“原始”意图和“束之高阁”的文档转化为一个能够记忆、执行和不断演进的活系统。

快速开始

通过 Agent 一行完成设置

将以下内容复制并粘贴到你的 Agent 中（OpenCode、Codex、Claude 或其他受支持的主机）：

Set up ControlKeel for this repository. Read and follow https://raw.githubusercontent.com/aryaminus/controlkeel/main/README.md, https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/getting-started.md, https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/support-matrix.md, and https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/agent-integrations.md. Install ControlKeel if missing, run `controlkeel setup`, detect this agent host, attach the strongest supported path with `controlkeel attach <host>`, then run `controlkeel attach doctor`, `controlkeel provider doctor`, `controlkeel status`, `controlkeel findings`, and the host-native MCP check. If CK is available only as MCP, call `ck_attach` for this host. Apply only safe local fixes and redact secrets from logs. Pause and ask before continuing if the host needs workspace trust, manual provider configuration, a restart after attach/plugin changes, or a plan-review approval that cannot auto-wait. Ensure the project is trusted and restart the host after attach/plugin changes.

安装 CLI

安装 CLI：

brew tap aryaminus/controlkeel && brew install controlkeel
# or
npm i -g @aryaminus/controlkeel
# or
curl -fsSL https://github.com/aryaminus/controlkeel/releases/latest/download/install.sh | sh

Windows PowerShell：

irm https://github.com/aryaminus/controlkeel/releases/latest/download/install.ps1 | iex

首次治理运行：

controlkeel
controlkeel setup
controlkeel attach opencode   # project scope by default; use another supported host as needed
controlkeel attach doctor
controlkeel provider doctor
controlkeel status
controlkeel findings

从你想要治理的代码仓库运行设置并进行关联。项目范围只会在该代码仓库内写入主机文件。--scope user 只会针对明确支持用户范围的目标，将主机级文件写入你的用户配置中；它不会将项目绑定或证明状态变成全局状态。

如需完整的首次运行流程，请参阅 docs/getting-started.md。如需了解主机支持情况，请参阅 docs/support-matrix.md 和 docs/agent-integrations.md。

基于基准测试的证据

ControlKeel 内含持久化的基准测试引擎。目前面向用户的证据仅限于下方列出的测试套件、对象和评分定义；完整表格、注意事项、JSON 导出和 Agent 主机协议的权威参考文档为 docs/benchmarks.md。

已验证的启用与未启用 CK 基线对比（host_comparison_v1，12 个高风险场景）

已使用 ControlKeel 0.3.45 验证：

• 高风险测试套件 host_comparison_v1：null_policy_baseline 捕获 0/12；controlkeel_validate 捕获 12/12，拦截 9/12，并命中预期规则 9/12；中位确定性验证时间为 52 ms，0 个提供方令牌。
• 配对的良性测试套件 benign_baseline_v1：controlkeel_validate 的捕获数为 0/10，拦截数为 0/10，FPR 为 0.000；中位确定性验证时间为 42 ms，0 个提供方令牌。

请准确解读这些数字：确定性扫描器证据并不等同于基于模型的 Agent 主机证据。复现命令以及 OpenCode/Copilot/Claude/Codex 对比协议见 docs/benchmarks.md。

当前提供的功能

• 本地治理： CLI、完整的本地 stdio MCP 工具集、项目绑定、主机挂接/导出包、扫描器验证、发现项、审查、证明包、预算和类型化记忆。
• 主机与运行时支持： 对受支持主机的原生挂接、面向无头/外循环系统的运行时导出、范围更窄的 OAuth 托管 MCP 工具集、精简版 A2A，以及回退验证/代理路径。
• 团队/项目运营： 组织成员资格、邀请、工作区 GitHub 仓库绑定、服务账户、Webhook、工作区工具策略和策略集 API。
• 云端证据路径： 可选加入的云端遥测、工作区密钥、云端运行包、运行时回调，以及配置前保持休眠状态的发现项、审查、摘要和记忆记录双向同步。
• 可观测性闭环： 时间线、记忆质量、成本、趋势、问题集群、评估候选项、基准测试草案/历史记录和晋级建议。

文档导航

• docs/README.md — 按任务划分的文档导航
• docs/getting-started.md — 从安装到发现首个问题
• docs/support-matrix.md — 主机/协议权威清单
• docs/agent-integrations.md — 集成机制与支持层级
• docs/benchmarks.md — 基准测试评分、元数据和声明规范
• docs/observability-feedback-loop.md — 本地证据到回归的闭环
• docs/control-plane-claim-matrix.md — 治理、记忆、云端同步和人工关卡的 README 声明到测试映射表
• docs/api-reference.md 和 docs/cli-reference.md — 与代码一致的接口
• docs/packages.md — 软件包与分发目录
• docs/self-hosting.md — 自托管部署指南

开发

mix setup
mix phx.server
mix test
mix precommit

Phoenix + Ecto，使用 SQLite。HTTP 请求使用 Req。单二进制文件通过 Burrito 和 GitHub Releases 发布。