适用于 Copilot CLI 的 zn-gate

为 GitHub Copilot CLI 安装 zn 的实验性钩子：阻止读取和写入密钥文件，以及处理密钥的 shell 命令，并替换工具结果中的密钥值。

查看 .md

对 Copilot CLI 的支持是实验性的。请把它当作第一道防线：它无法拦截你粘贴到提示词中的密钥，而且如果钩子太慢，Copilot 会让调用继续执行（见下面的“限制”）。

你需要 Node.js 18 或更高版本。在终端中逐行粘贴以下命令，每行后按回车：

npm install -g zn-gate
zn hooks install copilot

在 macOS 和 Linux 上，如果 npm install -g 因 EACCES 失败，请按照 npm 的指南修复权限错误操作。

无需管理员权限即可修复：

mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

如果使用 bash，请写入 ~/.bashrc 而不是 ~/.zshrc。

然后打开新的终端并运行 npx -y zn-gate init。使用 nvm 等 Node.js 版本管理器也可以避免该问题。

然后打开一个新的 Copilot CLI 会话。zn 会把它自己的文件 zn-gate.json 写入 ~/.copilot/hooks/（如果你设置了自定义的 Copilot 文件夹，则写入 $COPILOT_HOME/hooks/），并且只修改它在那里写入的内容。之后要更新？请参阅升级 zn-gate。

仅用于一个项目

在项目内运行 zn hooks install copilot --project。它会把 .github/hooks/zn-gate.json 写入该项目，而不是你的主目录。该钩子会从你的 PATH 运行 zn，所以每个在 Copilot CLI 中打开该项目的人都需要安装 zn-gate，否则钩子无法启动。在运行仓库中的钩子之前，Copilot 还会要求每个人先信任该文件夹。

你将获得的保护

  • zn 会在每次工具调用运行之前检查它。
  • 按文件路径，阻止读取和写入密钥文件，例如含值的 .env 文件。
  • 处理密钥的 shell 命令会被阻止。对于使用 __ZN_<NAME>__ 标记的命令，zn 会阻止它，并告诉模型应改用的确切 zn run -- ... 命令行。
  • 智能体无法编辑 Copilot 自己的钩子文件和设置文件。
  • 读取类工具或 shell 工具运行之后，zn 会在模型看到成功的结果之前，替换其中的密钥值。
  • 当某项检查需要你来决定时，zn 会请你确认。在没有人能回答的地方，即 Copilot 的云端智能体和自动驾驶模式中，Copilot 会把这个提问变成拦截。
  • zn 从不替你批准调用。当它没有异议时，由 Copilot 自己的权限规则决定。

限制

  • 粘贴到手动输入的提示词中的密钥不会被拦截。 Copilot 不允许钩子拦截手动输入的提示词。
  • 钩子耗时过长时，Copilot 会让调用继续执行。 Copilot 默认等待 30 秒，zn 为其钩子设置的是 15 秒。当 zn 自身的检查在 11 秒时仍未完成，它也会以拦截作为响应。
  • Copilot 自己的日志会保留原始输出。 你机器上的会话日志（events.jsonl）保存的是 zn 替换任何内容之前的工具输出。zn 清理的是发送给模型的内容，而不是这个文件。
  • 机器级策略钩子同样会运行。 Copilot 还会从 /etc/github-copilot/policy.d 加载钩子文件，zn 看不到这些文件。
  • 有些工具可能不会被检查。 zn 不一定能识别某个 MCP 工具，所以它的调用可能不会被检查，它的输出也不会被清理。
  • 设置可以关闭这些钩子。 在 zn 的文件中，或在仓库的 .github/copilot/settings.json 或 settings.local.json 中设置 "disableAllHooks": true，都会将它们关闭。zn-gate check 会报告。
  • 尚未在 Windows 上测试。
  • zn 是用 Copilot CLI 1.0.98 和一个脚本化的模型检查的，并非覆盖所有版本。

检查是否正常工作

在新的终端中运行 zn-gate check。应显示 Copilot CLI (experimental) 的 OK。输出含义。

在 Windows PowerShell 中，如果 npm 提示 "running scripts is disabled on this system"，请改用 npm.cmd 和 zn.cmd：参见安装。

如何移除

在你自己的终端中运行 zn hooks uninstall copilot（项目级安装请加上 --project）。