架构

zn-gate 的构成方式。围绕智能体每个动作的三个检查点，以及背后的原则。

查看 .md

zn-gate 是运行在你机器上的一个小型检查点，位于你的编程智能体与它读取、执行的一切内容之间。它只检查每个动作的三个时刻，其余时间不打扰你。本页说明它的结构和背后的原则。各个部分的详细说明见zn-gate 如何工作。

三个检查点

zn-gate 在你的机器上的三个检查点示意图。第 1 步：提示词或内容先经过 analyze_prompt，检查注入和粘贴的密钥，然后才到达智能体。第 2 步：智能体的工具调用先经过 check_tool_call，拦截有风险的参数并遮蔽密钥，然后才运行工具。第 3 步：工具输出先经过 check_tool_result，删除密钥并中和注入，然后才到达模型。
步骤 检查点 时机 作用
1 analyze_prompt 智能体处理提示词或内容之前 查找提示词注入、越狱以及粘贴在文本中的密钥
2 check_tool_call 工具运行之前 检查参数中的注入、外泄模式和敏感路径。被拦截的调用不会到达工具。参数中的密钥会被遮蔽
3 check_tool_result 工具运行之后、模型读取输出之前 删除密钥并中和间接提示词注入。带有注入的结果会被一条简短提示替换

每个检查点的答复是 allow 或 block，并给出做出决定的 rule 和 reason。同样的三项检查适用于 zn-gate 的每种配置方式：智能体钩子、MCP 服务器，或放在你其他 MCP 服务器前面的 zn-gate shield。各种配置及其覆盖范围见zn-gate 如何工作。

原则

  1. 依赖尽量少。 Python 包只使用标准库。npm 包只有一个运行时依赖 age-encryption（及其 @noble 和 @scure 库），用于加密密钥保险库。它按 package-lock.json 中固定的版本打包在包内，你的机器上不会编译任何东西。
  2. 优先本地且可预测。 检查在你的机器上用固定规则运行：模式匹配，加上对形近字符、零宽字符和编码文本的规范化。相同的输入得到相同的答案，每个答案都会指明所用规则。最近 2,048 条结果会被缓存，重复的文本只检查一次。实测耗时见性能页面。
  3. 可选的云端第二意见。 只有提示词分析可以询问云端分类器，而且只有在你开启之后：同时设置 ZN_API_KEY 和 ZN_CLOUD=1，或运行 zn-gate connect。ZN_LOCAL_ONLY=true 可再次关闭。本地规则已经拦截的文本永远不会发送，文本中的密钥会先在你的机器上删除再发送（个人数据不会被删除）。工具参数、工具输出和工具描述在任何设置下都不会离开你的机器。详情：哪些内容会离开你的机器。
  4. 可发现篡改的本地日志。 zn-gate shield 和各 SDK 记录的每个决定，都会追加到 ~/.zn/evidence.jsonl，并带有链接上一条记录的 SHA-256 哈希和已删除密钥的预览，绝不包含密钥本身。zn-gate evidence --verify 会检查这条链。它能发现意外或部分的修改，但无法防范能写入该文件的人，因为对方可以重新计算。参见证据。

这种结构不做什么

  • 它只是一道边界，不是你的整个安全模型。请为工具保持最小权限，并对影响重大的操作保留人工审核。
  • 检查点能看到什么，取决于 zn-gate 的配置方式和所用的智能体。单独的 MCP 服务器只能看到智能体主动发给它的调用。钩子还覆盖智能体的内置工具，覆盖程度取决于各个智能体允许什么。参见威胁模型。
  • 本地规则不是语义分类器：换一种说法的攻击可能会通过。