kepil

Kepil

AI Agent 的问责层。 为每个 Agent 配备护照，让每项操作都经过同一道关口，并保留一份事后无法篡改的日志。

53% 的组织曾遇到 AI Agent 超出预期权限的情况。 48% 的生产环境 Agent 完全没有监控。只有 22% 的组织将 Agent 视为拥有独立身份的实体。 —— Cloud Security Alliance，《State of AI Agent Security》，2026 年

Kepil 补上了其他 78% 缺少的部分：身份、授权、执行、证据，以及没人能做到的那一环：撤销。

pip install kepil
python -m kepil.admin        # http://localhost:7317

俄语版：README.ru.md

---

功能

护照。 每个 Agent 版本都有一张不可变的卡片：由谁构建、由谁运行、它能做什么、它绝不会做什么、风险等级、自主等级、限制，以及何时应重新审查风险。每个新版本都有一张新卡片；旧卡片会永久保留。

授权。 针对单项任务的机器可读授权书：允许的操作、允许访问的系统、支出限额、有效期限，以及哪些类型的操作必须由人工确认。未明确允许的操作一律拒绝。

关口。 Agent 接触外部世界的唯一入口。每项操作都会在调用模型之前依据授权进行检查。默认拒绝：检查中出现任何错误都意味着拒绝，绝不会放行。

日志。 只追加的 JSONL，每条记录都包含前一条记录的哈希。任何人都可以使用独立实现检测记录是否被编辑或删除：

npx proofbyte-agent-trace verify data/journal.jsonl

撤销。 日志是一张操作图，每种职业都会声明其补偿操作。Kepil 沿着这张图反向追溯，并在遇到无法撤销的第一步时如实停止。Agent 平台会记录发生了什么；而 Kepil 会将其恢复。

手机确认。 不可逆操作会发送到 Telegram，并附有两个按钮——批准或退回——让问责不再意味着必须守在笔记本电脑前。

无人回应的卡片不会悄无声息地消失。 阻止操作保护的是操作，而不是阅读者：没人打开的卡片看起来和一分钟前发出的卡片一模一样。因此，等待设有截止时间（默认 4 小时）。逾期卡片会再次送达，附上相同的按钮和等待时长，并在面板中标记。可以推迟处理，但必须说明理由，且最迟只能推迟 72 小时。推迟操作会作为人工决策写入日志，时间一到，卡片就会再次出现。MCP 不支持推迟处理：Agent 无法让自己的卡片静音。

在任何 MCP 客户端中使用

Kepil 自带 MCP 服务，因此编辑器、助手或其他 Agent 都可以通过它进行操作——而每项操作仍会经过同一道关口，并写入同一份日志。

{
  "mcpServers": {
    "kepil": { "command": "python", "args": ["-m", "kepil.mcp"] }
  }
}

提供七种工具：列出职业、创建订单、运行步骤、读取订单状态、查看等待人工处理的事项、验证日志、读取 Agent 护照。

特意不提供一种工具：确认。 如果模型可以批准不可逆操作，人工就会退出整个流程，整个设计也就失去了意义。确认卡片会发送给真人——通过面板或 Telegram——任何 MCP 客户端都无法点击确认按钮。我们通过测试确保了这一点。

守护现有自动化

Kepil 提供小型 JSON API，因此 n8n 工作流、Make 场景或你自己的脚本都可以在执行操作前请求许可：

curl -X POST http://localhost:7317/api/check   -H "Authorization: Bearer $KEPIL_API_TOKEN"   -H "Content-Type: application/json"   -d '{"order_id":"ord-0042","action":"send:message","system":"whatsapp.local"}'

{ "decision": "await_human", "allowed": false, "needs_human": true,
  "reason": "необратимое действие: требуется подтверждение человека" }

许可结果会记录在日志中，因此之后你可以说明自动化执行或未执行某项操作的依据。n8n 提供了现成节点：n8n-nodes-kepil。

必须设置令牌才能启用 API（在面板 → Settings 中设置，或使用 KEPIL_API_TOKEN）。绑定到 localhost 的面板受绑定地址保护；程序化接口则不受此保护，因此默认禁用。

此处的 Agent 从不完全自主

AgentPassport 拒绝使用一种人类无法再取消决策的自主性类别来构造。这是刻意设定的架构限制，并非缺失的功能——参见 ADR-0002。无论职业定义如何声明，门控机制都会执行同一规则。

职业：行为作为数据，而非代码

Agent 的工作是一份 JSON 描述：有序步骤、边界、限制、不可逆操作模式、回滚规则。添加一种新工作类型意味着添加一个文件，或在面板中填写一份表单。危险部分仍保留在代码中并接受测试。

项目自带五种职业：入站线索、流程自动化、簿记文档、AI 采用审计、公共采购材料包。

诚实止步的撤销

订单的日志由一系列操作组成，每种职业都会为每项操作声明补偿操作，因此面板可以逐步回退：选定一个时间范围后，流程会从最后一项操作开始向前回退，并在遇到第一项无法撤销的操作时停止。按下按钮之前就会显示将要发生的情况，并指出流程会在哪一步停止——悄无声息地失败的撤销承诺，比完全没有撤销更糟。结果会记录为操作员的决策，这就是为什么 MCP 服务和 JSON API 都不能回滚任何内容：如果 Agent 撤销自己的操作，就等于冒用他人的名义签字。

面板

运行 python -m kepil.admin 会打开一个操作员控制台，包含订单、职业、Agent 通行证、计量面板（操作次数、令牌数、成本、替代的人力时间）、合规性生成器、带链验证和锚定功能的日志，以及设置。

状态以普通 JSON 文件的形式保存在 KEPIL_DATA 下（默认为 ./data）。没有数据库：你可以打开、读取这些文件，并将其附加到争议材料中。

确认往返才是日志的见证

哈希链可以证明留存记录彼此一致，却无法说明哪些记录被删掉了：截断第 3 条记录之后的日志，再用正确的 prev_hash 值重写后续所有内容，验证就会在更短的历史记录上显示 Integrity confirmed，而这段历史内部完全自洽。

设计中早已包含解决办法，只是尚未启用。确认卡片会离开写入进程，交给某个人处理，可以在面板中操作，也可以通过 Telegram 操作；这次往返就是在写入方之外生成的唯一凭证。因此，现在卡片会携带当前链头，返回的决策会引用其看到的链头，日志也会将其记录下来。

现在，重写日志前缀就必须与某条写入方无法触及的消息相矛盾。验证不再只是检查自洽性，而是成为另一方对日志在某个时刻具体状态的陈述。

chain against itself:  Integrity confirmed
witnessed head:        confirmation at record 0 refers to root sha256:a3d124b9…,
                       which is no longer in the chain: the history was cut or
                       rewritten (3 such confirmations)

最后一个见证链头之后写入的记录仍未受到保护。保证止步于此，并且明确说明了这一点。

这项改进源自一位读者 ANP2 Network，他在一条评论中同时描述了攻击方式和修复方案。

调查：安装本身能证明什么，以及人必须回答什么

合规调查是一份与法律规范对应的问题清单。有些答案已包含在安装中——护照中的风险和自主性等级、资料包中的文档完整性、日志中的确认和停止记录。其余问题则必须由人回答：训练数据的来源、模型的功能列表、保险合同。

面板会运行检查清单，并将每个项目分为三类：有安装中的证据支撑、存在缺口，或需要人工处理。在实际安装中，大约五分之一的项目可以自动完成。如果自动完成的比例高得多，检查清单就不完整。

有两点值得说明。解析器只返回事实——“未声明高自主性”“日志中有零次停止”——绝不判定是否合规；结论和签名仍由人负责。检查清单文件引用的是代码中声明的解析器名称，不包含任何可执行内容，否则，来自其他地方的 JSON 文件就可能成为在保存日志的机器上运行代码的途径。

完整性解析器会报告系统自身的弱点：如果链的根从未固定，或是在日志旁以未签名的方式固定，那么就没有外部见证者，整个历史记录都可能被改写。

8.2  needs a human   anchors exist, but 1 of 1 is unsigned and stored next to
                     the journal — there is no outside witness

合规资料包

各国的文档要求各不相同，且变化速度快于代码，因此文本存放在引擎之外。此处附带的通用资料包遵循国际惯例（ISO/IEC 42001，以及符合 EU AI Act 精神的记录保存要求）。司法辖区资料包——例如哈萨克斯坦的 AI Law No. 230-VIII 及其第 95/НҚ 号命令——以文件形式放入 $KEPIL_DATA/packs。

设计规则

• 零依赖。 核心仅使用 Python 3.11+ 标准库；一旦出现第三方导入，CI 就会使构建失败。这样可确保 Kepil 能在隔离网络边界内部安装，并让一个能看到每项操作的工具所面临的供应链攻击面保持为零。
• 绝不将值写入日志——只记录类型、计数和哈希。
• 验证器使用另一种语言独立实现。 只有其作者自己能验证的证明，不算证明。

相关项目

项目	作用
agent-trace	独立验证日志并生成证据资料包（MIT）
AI-Gateway	在你的应用与外部模型之间屏蔽 PII 和机密信息
AutoGov	发现影子自动化及其可访问的凭据

状态

Alpha，191 项测试。接口仍可能变更。本文内容不构成法律意见：在依赖生成的文档之前，请让你所在司法辖区的律师审阅。

许可证

AGPL-3.0-or-later。运行基于 Kepil 构建的网络服务，即有义务按照相同条款公开你自己的源代码，或购买商业许可证。请参阅 NOTICE.md。