zn-gate 1.14.0 新功能：Antigravity 和 ZCode desktop app 支持、Gemini CLI 与 GitHub Copilot CLI 钩子、更多 Codex CLI 检查、保管库和 Team 修复以及 MCP 配置扫描

版本发布John Silver30 分钟阅读

在 npm 上此版本以 1.14.1 发布，即 1.14.0 加上针对 Windows 的修复（见安全更新日志）。zn-gate 1.14.0 新增面向 Google Antigravity 和 ZCode desktop app 的钩子（它们现在是受支持的智能体），以及面向 Gemini CLI 和 GitHub Copilot CLI 的实验性钩子，并为 Codex CLI 增加了更多检查。它还能发现 MCP 服务器配置中以明文写入的密钥和密码，加固了保险库和 zn Team，补上了 Python 工具防护的一个缺口，并为用框架构建智能体的开发者新增了示例。zn-gate 仍然无需账户，默认不发送任何内容。请用 npm install -g zn-gate@1.14.1 和 pip install -U zn-gate 更新。

zn-gate 1.14 新功能概览，在 npm 上发布为 1.14.1。官方支持 Antigravity 和 ZCode desktop app。Claude Code 会检查网页抓取、MCP 工具和 shell 命令的输出。Scan 可发现 MCP 配置中以明文写入的密钥和密码。Windows 加固。

zn-gate 现在保护哪些新的智能体？

又有四个智能体获得了执行前钩子。Antigravity 和 ZCode desktop app 与 Claude Code、Codex CLI、Cursor 和 OpenCode 一同成为受支持的智能体，共六个。Gemini CLI 和 Copilot CLI 是实验性的，单独列出。

npx -y zn-gate hooks install gemini
npx -y zn-gate hooks install antigravity
npx -y zn-gate hooks install zcode
npx -y zn-gate hooks install copilot

加上 --project 可只为当前项目设置钩子（ZCode 除外，它会忽略项目钩子）。不加时，钩子会放在你的用户设置中。

  • Gemini CLI： 钩子会阻止智能体按路径读取或写入机密文件，以及运行处理机密的 shell 命令。它还会保护 Gemini CLI 自己的设置文件，不让智能体修改。Gemini CLI 的钩子无法请求确认，因此 zn-gate 会阻止它会拒绝的内容以及它会询问的内容，并给出原因和批准方法。其他所有情况适用 Gemini CLI 自己的批准机制。
  • Google Antigravity： 钩子的作用相同，并保护它自己的钩子文件。当文件夹中存在明文的 .env 或密钥文件时，对整个文件夹的搜索会请求确认。Antigravity 的钩子无法改写工具输出，因此在那里匹配到的行和命令输出不会被隐藏。Antigravity 指南列出了该钩子不覆盖的内容，包括 Antigravity 没有说明钩子失败时会发生什么。
  • ZCode 桌面应用： zn hooks install zcode（或 npx -y zn-gate init）会添加在每次工具调用之前和每个提示词之前运行的钩子。它会阻止读取和写入机密文件、处理机密的 shell 命令、会发送机密的 MCP 调用，以及包含机密的提示词，并且智能体无法编辑 ZCode 自己的配置文件。它无法从工具返回的内容中移除机密（输出中包含机密时，zn 会添加提示），ZCode 会忽略项目的钩子，而且当 Node.js 丢失时，zn 的启动器会阻止调用，因此请把它当作第一层防护。ZCode 的文档没有说明钩子失败时会发生什么；在我们使用 Linux 上的 ZCode 桌面应用 3.16.3 的测试中，失败的钩子（退出码不是 2、崩溃或超时）会让调用照常运行，只有退出码 2 或 deny 响应才会拦截调用。已在 Linux x64 上的官方 ZCode 桌面应用 3.16.3 上完成端到端测试（2026 年 10 月）。同样的检查也在 Windows x64 上通过（Windows Server 2022，相同的应用版本，2026 年 10 月），分别以管理员和标准用户身份，通过该应用自带的智能体完成；Windows 应用窗口本身未被操作。macOS 未测试。在 Windows 上，zn-gate check 现在能识别 zn hooks install zcode 写入的钩子。已有适用于 Linux 的 ZCode 插件构建；其安装步骤将随其插件仓库一同发布。详情：ZCode 页面。
  • GitHub Copilot CLI： 钩子会阻止智能体按路径读取或写入机密文件，以及运行处理机密的 shell 命令，会替换读取类和 shell 类工具结果中的机密值，并保护 Copilot 自己的钩子和设置文件，不让智能体修改。Copilot CLI 的钩子无法阻止已输入的提示词，且钩子超时时 Copilot 会放行该调用，因此为钩子设置了 15 秒超时的 zn 会在 11 秒时自行拦截该调用。

zn-gate check 会报告这些钩子，并在 Gemini CLI、Copilot CLI 或 ZCode 关闭了钩子时发出警告。各个智能体的设置请见安装。

流程图。编程智能体（Claude Code、Codex CLI、Cursor、OpenCode、Antigravity 或 ZCode desktop app；Gemini CLI 和 Copilot CLI 为实验性）会将每次工具调用经过你机器上的 zn-gate 钩子。钩子负责决定。放行：其他所有调用照常运行。拦截：读取和写入机密文件，以及处理机密的 shell 命令。隐藏：工具输出中的机密会在模型读取之前被替换。模型拿不到任何机密值。钩子能改变什么取决于智能体：Antigravity 和 ZCode 的钩子无法改写工具输出。

Codex CLI 有什么新变化？

更新后请再次运行 zn-gate hooks install codex，然后在 Codex 中用 /hooks 查看已更改的钩子。

  • zn-gate 现在会在 MCP 工具调用执行前检查它们，与 Cursor 上已有的做法一致。
  • 当它的检查会拒绝某次调用时，它会用拒绝来回应 Codex 的权限请求，因此对于被 zn-gate 阻止的调用，不会显示“批准”按钮。它从不回答“允许”。
  • 它会审查模型的最终回答。当回答中含有机密值，或含有它在本次会话中此前未见过的 __ZN_ 占位符时，它会提醒你。提醒显示给你，而不是给模型。若想让 Codex 要求模型重写这样的回答，请在 ~/.zn/config.json 的 hooks 下设置 "stopReview": "block"。
  • 可选设置 hooks.replaceToolOutputOnSecret 会把含有真实机密的工具结果替换为一段简短文字，只说明机密的类型，绝不包含其值。默认关闭。
  • 当存在其他工具的 PreToolUse 或 PermissionRequest 钩子时，zn-gate check 会报告 Codex 没有得到完整保护，因为 Codex 会同时运行这些钩子，其中一个可能在 zn-gate 检查之后改动命令。它还会报告被设置为后台运行或在 config.toml 中被关闭的 zn 钩子。
  • zn-gate hooks install codex 还会添加 SessionStart 和 SubagentStart 钩子。它们为模型添加一条简短提醒，从不阻止任何操作。设置方法见 Codex 指南。

scan 现在能发现什么？

zn-gate scan 和 zn audit 会查找 MCP 服务器配置（.mcp.json、.cursor/mcp.json、.vscode/mcp.json、.codex/config.toml、claude_desktop_config.json 等）中以明文写入的密钥和密码。它们会检查名为 API 密钥、令牌或密码的字段下的值、Authorization 请求头、args 中凭据参数后面的值，以及服务器 URL 中的密钥。${NAME} 这类引用不会被报告。报告会显示类型、存放该值的名称、文件和行号，绝不显示值本身，并说明如何把它移到保险库或环境变量中。

npx -y zn-gate scan --include-home

--include-home 还会检查你自己的 MCP 配置（Claude Desktop、Claude Code、Cursor、Codex、Gemini、Antigravity、OpenCode 和 Amazon Q）。scan 现在会列出它不读取的文件夹及原因，而不是悄悄跳过；当没有可扫描的内容时会提示 “No files were scanned”，空结果不再看起来像是干净的；会跟随你作为扫描目标给出的链接；并会读取 .vscode/mcp.json。参见扫描指南。

有安全修复吗？

有。

  • 钩子在失败时阻止： 当安装时所用的 Node.js 消失（切换或卸载 nvm、升级）或钩子崩溃时，Claude Code、Codex、Cursor 和 Gemini CLI 的钩子不再让工具调用不经检查就运行，而是阻止该调用。在 Claude Code 和 Codex 中，钩子超时时也会阻止。请再次运行 zn hooks install <agent> 来更新已有的安装；zn-gate check 现在会报告 Node.js 或启动脚本已不存在的钩子。对于 Claude Code 插件，请运行 claude plugin update zn-gate@usezn 并开启新会话；它需要 Claude Code 2.1.295 或更高版本。Codex 没有相关设置，因此它的钩子会在 Codex 的时间限制前几秒自行给出拒绝。
  • Python 工具防护： 嵌套超过约八层的工具参数或结果此前不经检查就被放行，因此藏在这么深处的值会绕过所有规则。现在它们会以 “nested too deeply to check” 为由被阻止。它影响 Python 包 1.13.1 及更早版本。请用 pip install -U zn-gate 更新。
  • scan 输出： zn-gate scan 会把文件名和文件夹名中的控制字符显示为转义形式（例如 \x1b），因此仓库中的名称无法写入终端控制序列。两个包都已覆盖。
  • 钩子： 格式错误的文件名和文本（例如不成对的 Unicode 代理字符）会被拒绝，而不是在某些 Windows 系统上让钩子中断。保护 zn 密钥模块的规则在其名称于命令内部拼接而成时也能识别。
  • 实验性网关： 加密的审计记录与自己的 id 和命名空间绑定；使用错误的密码短语时审计日志拒绝打开；默认的来源检查只接受回环来源；上传的策略在保存前会先验证。
  • 审计报告： zn audit 会隐藏更多凭据参数后面的值，例如 --passphrase、--bearer 和 --jwt。
  • ZCode 安装： zn hooks install zcode 和 uninstall 是原子操作。安装会在改动配置之前保存 hooks.enabled 原来的值，并最后写入 config.json，因此中途失败的安装不会再让你自己的钩子被打开却没有记录可用于撤销。启动器有自己的期限，比 ZCode 的钩子超时短两秒，因此启动时卡住的钩子会被阻止，而不是让调用继续运行。
  • 项目级钩子： 针对 Claude Code、Codex CLI、Cursor、Gemini CLI 和 Copilot CLI 的项目级安装（zn hooks install <agent> --project）过去会写入一条裸的 zn hook <agent> 命令。在 zn 或 Node.js 无法启动的地方（例如在另一台机器上），该命令会失败，智能体会不经检查就执行调用。现在项目级钩子运行在启动保护程序中，当 zn 或 Node.js 缺失或钩子失败时会阻止调用（对于无法阻止的事件则只发出警告）。该保护程序只信任来自 PATH 中绝对路径条目的 zn 和 Node.js，适用于所有 sh（包括 macOS 上的 sh），并且在 Windows 上有 PowerShell 形式。zn-gate check 会将项目文件中裸的 zn hook <agent> 报告为未受保护，将与 zn 所写内容不同的保护程序报告为已修改。请在该项目中再次运行 zn hooks install <agent> --project 来替换它。
  • 钩子启动器： 启动器脚本绝不会运行在相对 PATH 条目（例如 .）中找到的程序，因此放在项目文件夹中的程序永远不会被运行，并且它们会在每次调用后删除自己的私有文件。在 Windows 上，zn.cmd 不能再启动当前文件夹中的 node.exe 或 node.bat。如果你试用过 1.14.0 候选版本，请再次运行 zn hooks install（并在每个带有项目钩子的项目中运行 zn hooks install --project），以便它写入的钩子获得这些修复。
  • 插件钩子： Claude Code、Codex 和 ZCode 的 zn-gate 插件钩子只会从项目之外的绝对 PATH 条目或常见安装文件夹中启动 Node.js；ZCode 插件则通过完整路径 /bin/sh 启动其钩子，因此项目中的 node 或 sh（其 bin/ 或 node_modules/.bin）永远不会取而代之被运行。Cursor 插件已不再提供：请使用 zn hooks install cursor，如果您已在 Cursor 中添加了该插件，请在 Cursor 中将其移除（Customize）。该插件不再添加 MCP 服务器：如需 secrets 服务器，请使用 zn hooks install claude-code。zn-gate check 会把不以这种方式启动的插件钩子报告为未受保护。在 Windows 上的 Claude Code 中，插件需要 Git Bash；没有它的话，请使用 zn hooks install claude-code。用 claude plugin update zn-gate@usezn 更新插件，并在 ZCode 中重新安装 ZCode 插件（设置，插件）。
  • 插件文件夹： 钩子现在会像保护钩子设置一样保护智能体的插件文件夹和插件状态：在 Claude Code、Codex、Cursor、ZCode 和 Antigravity 中，智能体不能再写入、删除或移动已安装插件的文件或已安装插件的列表，因此被提示词注入的智能体无法修改插件的钩子脚本来跳过 zn 的检查。项目自己的 .gemini/ 和 .claude/plugins/ 文件夹仍然可以写入。
  • 钩子输出： 如果钩子无法将完整的答复写给智能体（例如因为智能体关闭了管道），过去它会像正常完成一样退出，因此拦截结果可能丢失。现在写入失败会使钩子失败，并且启动器只有在钩子确认已写完整个答复时才接受该钩子；否则它们会阻止该操作，对于无法阻止的事件则发出警告。
  • 钩子时间限制： 输入永不结束或检查永不完成的钩子，现在会在智能体自身的时间限制之前阻止调用，而不是让智能体得不到任何答复（那会使调用得以运行）。Gemini CLI 和 Copilot CLI 在钩子超时时会放行调用（zn 将它们的钩子超时设为 15 秒），它们会在 11 秒时得到拦截。检查期间收到 SIGTERM、SIGHUP 或 SIGINT 时，同样会以拦截作答。
  • 无法询问的智能体： Codex CLI、Cursor、OpenCode 和 Gemini CLI 无法显示提问，过去 zn 会丢弃它想要询问的内容（写入指令文件、MCP 调用中的个人数据、对含有明文 .env 的文件夹进行搜索），因此调用会被执行。现在 zn 会阻止此类调用，并且原因会说明被扣留的内容以及如何批准。Claude Code、Copilot CLI、Antigravity 和 ZCode 仍会询问。现在，无法读取的工具调用在所有智能体中都会被阻止。
  • 不可见标记： 规则在匹配文本时现在会忽略从左到右标记、从右到左标记和阿拉伯字母标记、蒙古语元音分隔符以及韩文填充字符，因此这些字符不再能拆分触发短语。对大部分由不可见字符组成的工具输出的检查也会统计这些字符。正常的阿拉伯语和希伯来语文本不会被拦截。
  • 超大的工具输出： 超大的工具事件不再未经检查就进入 Claude Code、Codex 或 Copilot CLI 中的模型。钩子现在会扣下过大而无法检查的工具后事件的输出，插件启动器读取事件时会在 32 MiB 处停止。
  • zn-gate init： 它不再把从环境中读取的密钥或令牌（ZN_API_KEY、ZN_JWT_SECRET、ZN_MCP_WS_TOKEN、ZN_DB_KEY）写入 zn.json，并且在 Linux 和 macOS 上创建的文件仅所有者可读。
  • 实验性网关审计： 每条审计记录都带有已认证调用方的命名空间，因此租户不会再看到命名空间恰好匹配的其他租户的调用。审计日志默认只存储元数据，神经层也不再保留调用的参数。升级网关会清除早期版本遗留在向量记忆文件中的文本，并清除审计日志中旧的相邻文本，同时压缩数据库，使这些文本不会留在空闲页中。事件流、SIEM 导出和 webhook 告警从不携带请求负载，并且在启动时会拒绝作为链接或对其他用户开放的 data/ref.key。
  • MCP 调用和网络请求： Claude Code 现在会在 MCP 工具调用执行前检查它们，与其他智能体此前的做法一致：参数中的机密值或占位符会被阻止，个人数据会请你批准该调用（请再次运行 zn hooks install claude-code 来更新已有的安装）。在智能体执行网络请求（curl、wget、Invoke-WebRequest、内联的 python -c 或 node -e、WebFetch，或带有 URL 或请求头的 MCP 调用）之前，钩子会检查其请求头、查询字符串和请求体中是否含有个人数据和明文机密，并在执行前询问你。对 localhost 的请求会被跳过，可通过 ~/.zn/config.json 中的 hooks.egressCheck 和 hooks.egressAllowHosts 调整。
  • 工具输出中的指令： 在 Claude Code 中，网页抓取、MCP 工具和 shell 命令的输出会用本地规则检查。当规则标记出读起来像指令的文本时，会提示智能体把它当作数据并告诉你。该功能默认开启且从不阻止；hooks.checkToolOutputInstructions: false 可将其关闭。新规则还会标记页面、MCP 结果或文件中的这类文本：要求智能体识别其用户，或把用户的姓名、邮箱或 API 密钥放进请求头、URL、Cookie 或表单字段。它们默认只是提示，在严格模式下会阻止。
  • 命令规则： 破坏性命令规则和受保护文件规则现在会像 shell 那样解读命令。被反斜杠拆开的单词、花括号列表（c{u,}rl ... | sh）、带引号、printf 和 here-string 形式的 Base64 载荷、紧贴前一个单词的重定向、NTFS 备用数据流（.aws\credentials::$DATA），以及上传参数中 @ 之后的主目录路径，都会像普通写法一样被识别。当主目录名中的重音字符以另一种 Unicode 形式书写时（如在 macOS 上），zn 自己的文件夹同样保持受保护。Node.js 包和 Python 包给出相同的判定。
  • 破坏性命令： 智能体钩子现在默认拒绝递归删除主目录、文件系统根目录或系统文件夹，以及向磁盘设备写入。智能体会被告知先请你确认。另外四条规则（通过管道交给 shell 的下载、对根目录或系统文件夹执行 chmod -R 或 chown -R、fork 炸弹，以及写入 shell 启动文件的下载）默认关闭；可在 ~/.zn/config.json 中用 hooks.blockDestructiveCommands 开启。它只读取命令文本，不是沙箱。
  • MCP shield： 它现在会完整检查最大 32 MB 的工具结果（此前对更大的结果只检查开头和结尾），并检查服务器发送的通知和请求、资源和提示词的内容，以及工具模式中的每一个字符串。过深或过大而无法检查的工具模式会被替换为一条提示，而不是不经检查就通过。主要由不可见字符组成的工具输出，在 Claude Code、Copilot 和 OpenCode 中不再让机密漏过。在 SDK 中，超过 4 MB 的工具结果现在默认被阻止；ZN_ALLOW_TRUNCATED=1 可允许。
  • 机密脱敏： 跨多行拆分的机密、在工具输出中用作属性名的机密、OpenPGP 私钥、嵌套在 LangChain 结果中的机密，以及更多形式的连接 URL，现在都会被脱敏，npm 包和 Python 包都是如此。现在有一项测试会用两个包对随机生成的假密钥文本进行脱敏，只要任一个包在输出中留下密钥，测试就会失败。
  • 更多 Python 防护检查： 它现在会读取 dataclass、pydantic 模型和其他对象内部的字符串，阻止无法完整读取的参数（例如生成器，因为检查它会把它用尽），解码没有 = 填充的 Base64，并检查和遮蔽工具抛出的错误消息，因为智能体框架会把该消息发送给模型。LangChain 集成支持 langchain-core 1.3.3 及更高版本；更早的版本存在已知的高危公告。
  • 审计、保险库和网关： 审计日志的加密使用由操作系统提供种子的随机数生成器生成每个 nonce，已有的加密记录会在审计保险库首次用其密钥打开时升级。保险库错误不再引用解密后的文本。zn audit 不再把凭据参数后面的值显示为 npx MCP 服务器的包名。zn-gate init --revert 只恢复配置旁最新的一份备份，并跳过属于链接或位于其他文件夹的备份，因此仓库无法再把恢复操作重定向到你自己的 MCP 配置上。实验性网关更新了 rustls-webpki、webpki-root-certs 和 wasmtime（RUSTSEC-2026-0378、-0379、-0382 和 -0383）。
  • 指令文件： 在智能体写入保存其记忆和长期指令的文件（MEMORY.md、AGENTS.md、CLAUDE.md、.cursorrules 等）之前，智能体钩子会先询问你，因为智能体会在之后的会话中读取这些文件。严格模式下会拒绝写入，hooks.agentInstructionWrites: "off" 可关闭该询问。读取这些文件从不被阻止。无法询问的智能体（Codex CLI、Gemini CLI、OpenCode 以及 Cursor 的文件工具）沿用各自的审批规则。
  • 更多命令写法： 通过管道交给 shell 或 Invoke-Expression 的下载，如果使用 ANSI-C 引用（$'...'）或在单词内使用 PowerShell 反引号转义，现在也会被识别。仅被打印的文本，例如 echo $'curl ... | sh'，仍然允许。

保险库和 zn Team 有什么变化？

  • 参数中的机密标记（破坏性变更）： zn run 和智能体钩子不再填入写在命令参数中的机密标记，因为参数会显示在进程列表和命令行日志中。请为该程序存储机密（zn secret set PGPASSWORD --command psql），然后运行 zn run --secrets PGPASSWORD -- psql "postgres://user@db/app"，由 psql 自行读取该变量。你的 shell 加载的环境文件（被遮蔽的 .env）中的标记仍会被填入。secrets_http_request 现在只发送以 proxy 模式存储的机密：如果某个 API 需要，请用 zn secret allow NAME --mode proxy 更改机密的模式。
  • 批准跟随值： 首次使用批准现在属于其所针对的值。删除机密会删除它的批准，替换值则会再次询问。1.13.x 及更早版本保存的批准没有 id，不再有效，因此更新后，每个机密在命令首次使用时会再询问一次。
  • 短值： 保险库不再接受少于 8 个字符的新机密，因为这样的值无法与普通文本区分。旧版本存储的短值仍可继续使用。
  • 谁可以请求值： 遮蔽现在在保险库守护进程内部运行，每个对值的请求都必须指明目的地或用途，由守护进程根据其持有的内容进行核对。没有上下文的请求会被拒绝并写入审计日志。能够与守护进程通信的程序，仍可在与之匹配的上下文中按名称请求已存储的机密：威胁模型说明了这能阻止什么、不能阻止什么。
  • Windows 和不安全的脚本： 保险库会为其文件夹、会话密钥和守护进程管道设置明确的仅所有者权限，如果无法验证这些权限则不会启动。zn run 拒绝把机密值交给他人可写的脚本，或位于他人可写文件夹中的脚本。
  • 重置和清除： zn vault reset 会保留一份加密备份并告知其位置。新的 zn vault purge 会永久删除保险库：它会列出每个文件，要求你确认（AI 智能体不能确认），并检查是否没有任何残留。zn-gate uninstall 现在也会删除备份和令牌映射。
  • 审计日志检查： 解锁后的保管库现在会在 zn vault log 显示、zn vault log export --otlp 导出或 zn team sync 上传整个审计日志之前，以及在向其追加内容之前，先检查整个审计日志（每条记录的签名、链以及它记住的最后一条记录）。此前只比较最后一条记录。保管库还会在解锁之前和每次写入之前，按序列号和签名将日志与它记住的最后一条记录进行比较，并且审计记录在写入时会刷新到磁盘。如果检查失败，日志不会被显示、导出或上传，保管库会存储一条在锁定和解锁之后仍然保留的警告，并且在你于自己的终端中用 zn vault verify --acknowledge 接受该日志之前，zn vault verify 会一直失败。限制：保管库处于锁定状态时，zn vault log 和 zn vault log export --otlp 无法检查链，并会如实说明；恢复较旧的 secrets.age（无论是否连同其较旧的 audit.jsonl）不会被检测到；如果保管库进程被终止，自其上次保存以来写入的记录（最多一分钟）可能会在没有通知的情况下被截断。当保管库在非正常关闭后解锁并接管尚未设置检查点的审计记录时，它会写入一条 warn 记录，因此每次崩溃都会显示在 zn vault log 中。
  • zn Team 策略： zn team sync 会拒绝版本相同但内容不同的第二份已签名策略，在你离开团队之前开始的同步也不能再应用其响应。当新的策略版本放宽某项限制时，zn team status 会列出变化的内容，审计日志会记录下来，Claude Code 也会提示一次。
  • zn Team 加入和离开： zn team join 不再上传你加入之前写入的审计记录；--include-history 可以添加它们，仅限首次加入时。当策略未被应用时，zn team join 和 zn team sync 以退出码 1 退出，zn team leave 会先通知服务器并说明其回复。当无法读取本地审计日志时，zn team join 也会停止，且不会发送任何内容。
  • 团队检测器： 当 ~/.zn/team.json 或策略副本被删除或编辑时，组织的自定义检测器不再丢失：zn team sync 和 zn team status 会从保险库中将其恢复。

还有哪些新功能？

  • Node.js 包拥有与 Python 包相同的工具防护：checkToolCall 和 guardTool。它还附带 TypeScript 类型。
  • 忘记保险库密码短语时，可以用 zn vault reset。它只在你自己的终端中运行，要求你输入确认短语，并会先把旧保险库保存到备份文件夹。
  • zn team managed-config 会显示管理员通过设备管理部署的托管设置，使钩子在每台开发机器上运行。它不写入任何内容。
  • 当钩子阻止某个操作或隐藏机密时，zn-gate evidence 现在会把它显示为一个事件（绝不包含值、命令、路径或提示词文本）。
  • 面向 CrewAI、LlamaIndex、OpenAI Agents SDK、Pydantic AI、Google ADK 和 Haystack 的可运行示例。每个示例都会在模型读取之前检查工具的输出，使用虚构的页面在本地运行，不需要 API 密钥。参见框架。
  • 命令行参考列出了每个 zn-gate 命令，升级指南说明了每次更新后该做什么。
  • 每个版本现在都包含 npm 包和 Python 包的软件物料清单。
  • 当 zn-gate scan 的结果没有覆盖它本应读取的每个文件时，它不再以 0 退出。如果没有读取任何文件，或者跳过了某个文件或文件夹（2 MiB 或更大、无法读取、不是常规文件），它会以 3 退出。发现问题时仍以 1 退出，只有部分文件被跳过时，--allow-partial 会保持退出码 0。运行 zn-gate scan 的 CI 任务可能会遇到这个新的退出码。
  • 在 Node.js 22.1 及更高版本上，钩子启动更快；Python 包现已声明支持 Python 3.14。钩子还只在需要时才加载用于运行其他程序的代码；检查没有隐藏字符的超大工具输出时也更快。
  • scrubber 能识别更多粘贴机密的方式：反引号中的值、从日志复制的带转义引号的 JSON、setx NAME value、PowerShell 赋值以及 NAME=value 命令。
  • zn-gate uninstall 一步移除 zn-gate。它会列出找到的内容（Claude Code 插件、zn 为各智能体设置的钩子，以及由 init --wrap-mcp 包装的 MCP 服务器），请你在自己的终端中确认，然后移除它们并运行 zn-gate check。只有在你另外确认时才会删除保险库，--dry-run 只显示列表而不做任何更改。智能体不能替你运行它：与其他会更改你的设置的命令一样，它需要你在自己的终端中运行。参见移除 zn-gate。
  • 适用于 pre-commit 框架的钩子：zn-gate-scan 会在每次提交前对你的仓库运行 zn-gate scan，zn-audit 会运行 zn audit。它们需要 Node.js 18 或更高版本。
  • zn audit 现在会读取智能体通过另一个文件加载的指令文件（CLAUDE.md 中的 @path 导入和 opencode.json 的 instructions 路径），找出名称仅大小写不同的智能体文件，报告无法读取的智能体文件，并在找不到某个智能体可读内容时显示 “not checked” 而不是 “No findings”。它的误报也更少：诸如 Bash(git status:*) 这样限定范围的 Claude Code 权限、诸如把 .env.example 复制为 .env 这样的常规设置步骤，以及 SKILL.md 中的文档，不再被报告为风险。
  • zn-gate check 和 zn-gate status 能识别托管安装（Claude Code 的托管设置、Cursor 的企业级钩子和 Codex 的 requirements.toml）并指出文件名。当你的 Node.js 已停止维护（18 和 20）或低于其版本线的已修补版本时，它们还会发出警告，但不会阻止。Claude Code 插件现在需要 Node.js 20.19 或更高版本；zn-gate 和 zn 的钩子仍可在 Node.js 18 及更高版本上运行。
  • 在 Python 中，guarded_tool 现在默认会扫描工具输出中的提示词注入（传入 check_result=False 可保留旧行为），把被阻止的目标命名为 tool:<name>，并且也适用于异步工具。新的原生钩子覆盖 Google ADK、OpenAI Agents SDK 和 Pydantic AI，包括这些框架自带的工具，例如 MCP 服务器。该包附带类型信息（py.typed）。
  • 更多可运行的示例：AG2、DSPy、LangChain.js、Mastra、OpenAI Agents SDK（JavaScript）、Vercel AI SDK、smolagents 和 Semantic Kernel。
  • 保险库、钥匙串和 connect 的错误信息现在用通俗的话说明发生了什么以及下一步该做什么。技术细节只在设置 ZN_VERBOSE=1 或 DEBUG=zn 时显示；DEBUG=* 不再开启它。zn unlock 和 zn vault status 会以你的本地时间显示保险库何时锁定，Python 包中的 zn-gate -v 会打印版本号。zn 的本地 MCP 服务器支持最高 2025-11-25 的协议版本，其工具描述会说明何时调用它们。npm 包变小了：下载约 1.0 MB，而不是 1.6 MB。
  • zn audit 会报告含有连续 40 个或更多空行、其后还有文本的指令文件（新规则 ZNA021，中等），因为审阅者看不到这些文本。本地规则也会把一长串空行当作一个空行来读取，因此填充之后的文本会与它前面的文本一起被检查。zn audit 不再把仅仅讨论 curl | sh 风险的文本，或技能备注中的 <system-or-project> 这类占位符标记出来。

还修复了什么？

  • 因含机密而被拦截的提示词，现在在文本显示了凭据名称时会指出该名称，例如 DB_PASSWORD。值绝不会显示。
  • 当密码很短时，zn env shadow 会把整个连接 URL 移到保险库。
  • 在以 PowerShell 为 shell 的 Windows 上，OpenCode 能正确包装带有 __ZN_NAME__ 标记的命令。
  • 多个程序同时写入时，证据日志不再丢失记录，Windows 上也是如此。
  • --help 现在可用于 zn unlock、zn lock、zn vault 和 zn team。对于 zn hooks、zn secret 和 zn env，请对子命令使用：zn hooks install --help、zn secret set --help 和 zn env shadow --help。
  • 缓慢或卡住的 MCP 服务器不再拖慢你的其他服务器，已失效的 WebSocket 服务器会被重新连接。
  • 含有多个 Base64 管道（echo ... | base64 -d）的命令，现在会逐个管道检查。此前只解码第一个，因此无害的第一个管道可能掩盖后面管道中被拦截的命令。超过 16 个管道，或解码后的数据超过 128 KiB，会被拦截。
  • 当缺少 Node.js 或钩子无法启动时，Antigravity 钩子现在会给出修复步骤：安装 zn-gate，然后再次运行 zn hooks install antigravity。此前 Antigravity 得不到可用的回应。
  • MCP shield 现在会像检查值一样检查服务器结构化内容中的键，因此放在键里的指令不会再到达智能体。
  • Antigravity：钩子现在会像文档所说的那样阻止写入含有明文机密的 .env 文件，并在对含有此类文件的文件夹进行递归 shell 搜索（grep -r、rg）之前询问。在 Windows 上它现在可以启动了：钩子命令不再依赖引号（Antigravity 不使用引号），因此含空格的 Node.js 路径不会再使它失效。请再次运行 zn hooks install antigravity 来替换已有的钩子。
  • 实验性网关：已被拒绝的操作不会再被批准，一次批准只能使用一次，封禁会持续到过期。待处理的批准默认 15 分钟后过期，超过 1 MiB 的 WebSocket 消息默认会关闭连接。使用 AWS KMS 时，它会在重启之间沿用同一个数据密钥，并且在无法获取 KMS 密钥时拒绝启动（除非你允许回退）。它的 scrubber 现在在 JSON 成员、Authorization 请求头，以及紧跟在被拒绝候选项之后的卡号上，与 Node.js 的结果一致。
  • zn-gate scan 现在会在两个包中读取 test、tests 和 __tests__ 文件夹，因为其中的测试数据可能含有真实机密，并且两个包跳过相同的文件夹。Python 扫描会像 Node.js 扫描一样列出它无法读取的文件夹，当所扫描的文件夹是通过链接访问时，路径也保持整洁。

每周一个版本

从 1.14 开始，zn-gate 按每周发布的节奏推出版本：每周一个较大的版本，而不是许多小版本。每个版本发布前几天会先发布一个候选版本（npm 的 next 标签和一个 PyPI 预发布版本），方便你提前试用。只有在出现高危或严重安全修复，或安装损坏时，我们才会在这个节奏之外发布。

我们的计划

  • 在智能体编辑它自己的记忆和指令文件（CLAUDE.md、AGENTS.md、skills）之前先询问。
  • 发现隐藏在 skills 和文档中 HTML 注释里的指令。
  • 在 macOS 上对 ZCode 进行端到端测试，并在 Windows 和 macOS 上对 Antigravity 进行端到端测试。
  • Rust 引擎采用与 Node 和 Python 包相同的命令规则。

常见问题

zn-gate 1.14.0 有哪些新功能？

面向 Google Antigravity 和 ZCode 桌面应用的钩子（它们现在是受支持的智能体），以及面向 Gemini CLI 和 GitHub Copilot CLI 的实验性钩子。更多 Codex CLI 检查（MCP 工具调用、权限请求和最终回答）。zn-gate scan 和 zn audit 能发现 MCP 服务器配置中以明文写入的密钥和密码。保险库和 zn Team 的修复：命令参数中的机密标记不再被填入，批准跟随其所针对的值，zn Team 的策略同步也更严格。修复了 Python 工具防护的一个问题：嵌套超过约八层的值此前不会被检查。Node.js 包新增工具防护和 TypeScript 类型，另有 zn vault reset、zn team managed-config，以及 CrewAI、LlamaIndex、OpenAI Agents SDK、Pydantic AI、Google ADK 和 Haystack 的示例。

如何更新到 zn-gate 1.14.0？

在 npm 上此版本以 1.14.1 发布：Node 包运行 npm install -g zn-gate@1.14.1，Python 包运行 pip install -U zn-gate。然后对你使用的每个智能体重新运行 npx -y zn-gate@1.14.1 hooks install <agent>（例如 hooks install codex）以添加新钩子；npx -y zn-gate@1.14.1 check 会告诉你哪些智能体需要这样做。如果你使用 Claude Code 插件，请运行 claude plugin update zn-gate@usezn 并开启新会话；它需要 Claude Code 2.1.295 或更高版本。

Antigravity 和 ZCode 桌面应用是否受支持，Gemini CLI 和 Copilot CLI 的钩子已经完善了吗？

Antigravity 和 ZCode 桌面应用是受支持的智能体，加上 Claude Code、Codex CLI、Cursor 和 OpenCode，共六个。它们的钩子会按路径阻止读取和写入机密文件，也会阻止处理机密的 shell 命令，但无法改写工具输出，因此在那里匹配到的行和命令输出不会被隐藏。粘贴到提示词中的机密在 Antigravity 中不会被拦截；ZCode 会拦截。ZCode 会忽略项目的钩子，因此没有项目级安装。已在 Linux x64 上的官方 ZCode 桌面应用 3.16.3 上完成端到端测试（2026 年 10 月）。同样的检查也在 Windows x64 上通过（Windows Server 2022，相同的应用版本，2026 年 10 月），分别以管理员和标准用户身份，通过该应用自带的智能体完成；Windows 应用窗口本身未被操作。macOS 未测试。Gemini CLI 和 Copilot CLI 的钩子是实验性的：Gemini CLI 的钩子无法请求确认，Copilot CLI 的钩子无法阻止已输入的提示词，且钩子超时时 Copilot 会放行该调用，因此为钩子设置了 15 秒超时的 zn 会在 11 秒时自行拦截该调用。zn-gate check 会报告每个钩子是否已就位。

保险库和 zn Team 方面我需要改动什么吗？

有两种情况需要。如果你通过 zn run 或智能体钩子运行的命令，其参数中带有 __ZN_DB_PASSWORD__ 这样的机密标记，它现在会被拒绝，因为参数会显示在进程列表和命令行日志中：请为该程序存储机密（zn secret set PGPASSWORD --command psql），并改为运行 zn run --secrets PGPASSWORD -- psql。另外，1.13.x 及更早版本保存的批准不再有效，因此更新后，每个机密在命令首次使用时 zn 会再询问一次。其他方面无需改动。

Python 工具防护的修复会影响我吗？

如果你对可能嵌套很深的参数或结果使用工具防护（guard、guarded_tool 或 check_tool_call），它会影响 Python 包 1.13.1 及更早版本。嵌套超过约八层的值此前不经检查就被放行。从 1.14.0 起，它们会以 “nested too deeply to check” 为由被阻止。请用 pip install -U zn-gate 更新。

使用 zn-gate 1.14.0 需要账户吗？

不需要。zn-gate 仍然无需账户，默认不发送任何内容。可选的云端检查在你运行 zn-gate connect 之前保持关闭。

完整的更改列表见 1.14.0 发布说明。zn-gate 采用 MIT 许可，在本地运行，无需账户：从 npx -y zn-gate scan --include-home 开始，或查看安装了解各个智能体的设置。

分享