Agent 工具调用该怎么留痕？Shield KYA 的本地审计与云端策略边界
编码 Agent 能读文件、执行命令、调用 MCP 工具，效率提高的同时，也让“它刚才做了什么”变成一个实际的安全问题。Shield KYA（Know Your Agent）提供一套面向编码 Agent 的调用留痕和策略检查工具：本地记录工具活动，并可通过策略路径返回允许、待人工审核或拒绝的决策。它值得关注的不是“装上就能拦住一切”，而是把本地可见性与真正的策略执行拆开说明。
先分清观察与强制执行
项目 README 将 KYA 描述为 CLI 与本地 MCP gate。kya start 会初始化 .kya/，尝试为检测到的编码宿主接入 MCP，并打开本地活动报告。支持情况取决于宿主的配置格式及加载方式；部分宿主需要重新启动或新建会话才能加载 MCP。通过本地 hook 记录的决策也不等于每次调用都被强制阻止：默认情况下，ALLOW 和 REQUIRE_APPROVE 作为记录继续放行，只有本地拒绝规则会直接阻断。
更重要的边界是策略决策路径。README 说明真正的策略评估、人工审批在 Shield 的托管 workspace/control plane 上执行；本地 hooks 采用 fail-open 设计。因此，不能把本地报告误解成离线防火墙，也不能仅凭“已接入 hook”就认为所有危险调用都会等待人工批准。项目强调：未经过评估路径的 Agent 调用不会自动进入策略判断。采用前要确认团队的威胁模型、网络要求和托管服务边界是否合适。
安装后先验证接入
项目以 npm 包 @shield-agent/kya 发布，README 标明 MIT 许可证，要求 Node.js 22 或更高版本（24 为推荐版本）。官方提供的快速开始命令是：
npm i -g @shield-agent/kya@latest && kya start
Linux 上若全局 npm 目录权限不足，README 建议不要使用 sudo，而是用一次性运行方式：
npx @shield-agent/kya@latest start
随后按项目文档检查活动报告是否出现当前会话，以及 Agent 宿主是否成功加载 MCP。不要只看安装命令退出码：关闭并重新打开宿主或新建会话后，再执行一项无副作用的工具调用，确认记录链路工作。接入前备份项目已有的 MCP 配置；README 表示 kya start 会合并其支持的配置，而不是覆盖无法解析的宿主配置，但团队仍应在自己的环境中验证变更。
用策略决策替代“看起来安全”
KYA 可在策略路径上对工具请求进行评估，并表达 Allow、Review 或 Deny。Review 需要人处理，不代表 Agent 已自动暂停在任何本地 hook 上；具体阻断行为取决于调用是否经过 MCP gate 或托管策略面。因而，集成时应选择一条明确路径：让工具调用经过评估，观察拒绝和待审决策如何传递，再测试拒绝时下游写操作确实不会执行。README 也说明，wrap 默认是 observe 模式；需要在待审时返回特定退出码，可按文档使用 --hold 或 KYA_HOLD=1，而不是想当然地把所有包装模式当作强制门禁。
可把部署拆成三步：先在测试仓库启用记录，检查调用覆盖率；再针对删除、凭据读取等高风险操作测试拒绝路径；最后才将策略接入关键工作流。避免把真实密钥放进示例命令或日志，并为审批人制定超时、拒绝和紧急恢复流程。审计记录能帮助追溯，但不能替代最小权限、备份和代码审查。
适用场景与限制
它适合希望集中查看编码 Agent 活动、并探索统一策略决策的团队。需要留意的是，KYA 并非网络扫描器；本地 hook 的默认行为不是全面阻断，而托管策略面涉及外部服务。若环境要求完全离线，或组织不接受工作流依赖云端策略，应先验证哪些功能能在本地工作，并考虑其他控制方案。还要评估记录内容的敏感性、保留期限和访问权限，避免审计面板本身成为源码或凭据泄露的新入口。
核心判断可以归结为：先问“哪些调用会被看见”，再问“哪些调用会被阻止”。Shield KYA 把这两件事放在同一工具中，但两者的实现路径和保证并不相同。用无害操作验证接入、用故意触发的测试验证拒绝，再依据团队的风险要求决定是否引入托管策略，这比把安装成功等同于安全更可靠。