AI agent 工具调用的审计流水与拦截闸门。查看每个编码 agent 做了什么，并按策略检查每一次工具调用。所有工具调用都会记录在本地实时仪表盘上，并可与 Agent Trust Baseline 对照检查。开源客户端仅提供建议且采用 fail open 模式（出错时放行调用），只有一份很小的 never-list 中的危险调用会被始终拒绝。真正的拦截与人工审批运行在托管工作区的 MCP 策略路径上（即 Shield Agent 云服务）。一条命令。基于 MIT 协议永久免费。

npm i -g @shield-agent/kya@latest && kya start

需要 Node.js 22+（推荐 24）。重启一次 Cursor / Claude Code / Codex，让 MCP 加载。托管控制台：shield-agent.com。

Shield「Know Your Agent」路径的 CLI 与本地 MCP 闸门。

先向 Shield 询问的 agent 会得到 Allow、Review 或 Deny：你注册 agent、包装工具（或让它走 MCP 闸门或托管平面），Review 会等待人工处理。本地 hook 只记录并拦截 never-list（见 Hook 拦截）。真正的强制执行在托管端。本包不会扫描你的网络。从不调用 evaluate 的 agent 会有意保持不可见。

npx @shield-agent/kya@latest --help npx @shield-agent/kya@latest --version

--version、-v、-V 和 kya version 会在一行内打印已安装包的版本并以 0 退出。它们只读取本地包：不联网、不显示横幅、不读配置。

需要 Node.js 22+（engines.node: >=22）；推荐 24 系列。Node 20 和 21 不受支持但可以运行：CLI 会打印一行警告。Node 18 及更早版本不受支持，部分功能在其上会出问题（HTTP serve-mcp、gateway OTLP 接收器）。低于 22 时，CLI 会主动提出为你安装 Node 24（通过 volta / fnm / nvm / brew）、重新安装自身并完成该命令。如果你拒绝，它只打印警告并继续。kya hook 从不警告或提示。

它适用于任何支持 MCP 或 OpenAPI 的宿主。垂直包是可选的。Shield 是唯一的策略决策点（唯一决定 Allow 或 Deny 的地方）。本闸门绝不会自动批准不可逆的副作用（无法撤销的更改）。

如果 KYA_API_KEY 为空且指向需认证的平面，网络命令会以非零码退出。eval-tool、wrap 和 invoke 在 ALLOW 时以 0 退出，在 REQUIRE_APPROVE 时以 4 退出，在 DENY 或未知时以 1 退出，因此像 eval-tool && write 这样的命令行无法跳过闸门。wrap 默认以 observe 模式运行，因此在 REQUIRE_APPROVE 时也会以 0 退出。设置 KYA_HOLD=1 或传入 --hold 可获得 4。

--offline 可在没有付费云的情况下运行示例 evaluate（便于演示 DENY 和 REQUIRE_APPROVE）。创建 agent 本身就是一个工具：离线时，kya.agent.register 会返回 REQUIRE_APPROVE。Allow、break-glass 和 approve 铸造模式（即创建审批的模式）位于控制平面上。

npm i -g @shield-agent/kya@latest && kya start

在你的项目目录中运行。（若从本仓库克隆，./scripts/install-local.sh 可替代 npm install。）

更多安装方式（同一包；npm 仍是参考路径）：

Homebrew。Homebrew 7 可能会要求你信任第三方 tap：先运行 brew tap The-Pixel-Boys/tap。

该 formula 不安装语义搜索运行时。在你选择启用前，搜索保持词法匹配（见自然语言搜索）。

brew install The-Pixel-Boys/tap/shield-kya

Scoop（尚未在 Windows 上验证）

scoop bucket add The-Pixel-Boys https://github.com/The-Pixel-Boys/scoop-bucket.git scoop install shield-kya

Claude Code 用户还可安装该插件；GitHub Copilot CLI 用户可安装 Copilot CLI 插件（安装前请先阅读其第一段）；code CLI 用户可安装 Codex 插件；Gemini CLI 用户可安装 Gemini CLI 扩展。Cline 用户：npm install -g @shield-agent/kya@latest，然后按 llms-install.md 操作。该文件是专为 Cline 跟随而写的；仅凭该文件运行的 Cline 流程尚未测试。

它会初始化 .kya/、配置本地 MCP（.mcp.json、mcp.json、.cursor/mcp.json → kya serve-mcp --stdio），还会为检测到的每个已安装宿主配置用户级配置（/.claude.json、/.kimi-code/、/.grok/、/.cursor/ 等），并打开实时活动报告。报告在后台运行，因此你能拿回终端。kya stop 可停止它。kya receipt --open 可重新打开。Cursor、Kiro、Qwen、Amp、Droid、Cline 和 Grok 可实时接入该服务器，无需重启（Kimi：只需新建会话）。Claude Code、Codex、OpenCode、Gemini、Copilot CLI 和 Kilo CLI 会在下次启动时加载。claude --resume 可保留你的对话。

kya start --no-open # 仅配置 kya start --force # 重写 MCP 块

Receipt 变更预览（截断 + 脱敏）：写入操作默认开启

KYA_DIFF_PREVIEW=0 可禁用

每个宿主一条命令

kya start 覆盖 Claude Code、Cursor 以及任何读取 .mcp.json 的宿主。它还会自动配置检测到的每个已安装宿主的用户级配置。对于其余宿主，kya connect 会直接写入宿主自己的配置方言：

kya connect claude # ~/.claude.json（仅合并 mcpServers） kya connect grok # ~/.grok/config.toml（追加 [mcp_servers.shield-kya]） kya connect opencode # ~/.config/opencode/opencode.json kya connect qwen # ~/.qwen/settings.json kya connect amp # ~/.config/amp/settings.json kya connect qwen --project # 项目作用域而非全局 kya connect kiro --force # 覆盖已有的 shield-kya 条目

Connect 采用合并方式。它绝不会重写无法解析的宿主配置，并保留你的其他服务器和键。支持的宿主：claude、codex、grok、opencode、kilo、kiro、qwen、kimi、mastracode、amp、copilot、cursor。每个都会以 KYA_OFFLINE=1 配置 serve-mcp --stdio，使闸门以无密钥（无 API key）方式启动。当你指向需认证的平面时，在宿主 env 中设置 KYA_API_KEY。

没有 connect 目标的宿主仍然可用：kya wrap --offline -- <agent command> 会把同样的 evaluate 闸门置于任何 CLI 之前。带验证步骤和故障排查的逐宿主配方见 docs/hosts/。

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）