shield-kya

@shield-agent/kya

**AI Agent 的审计轨迹与可追溯性。**查看每个编码 Agent 执行了什么，拦截有风险的调用，请求人工审批，并通过签名信任检查提供证明。每次工具调用都会记录在实时本地仪表板上，并可根据 Agent Trust Baseline 进行检查。本地 KYA 只发出警告，不会拦截，并且会以开放失败方式运行（发生错误时允许调用通过）。唯一例外是一份精简的禁止列表（始终拒绝的一小组危险调用）。真正的强制执行通过 MCP gate 路径和托管层（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 gate。

先向 Shield 请求的 Agent 会收到 Allow、Review 或 Deny：注册 Agent、包装工具（或通过 MCP gate 或托管层路由工具），Review 会等待人工处理。本地钩子只记录并拦截禁止列表中的调用（参见钩子拦截）。强制执行在托管端进行。此软件包不会扫描你的网络。刻意不调用 evaluate 的 Agent 会保持不可见。

操作指南：使用方法。

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

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

它适用于任何支持 MCP 或 OpenAPI 的宿主。垂直领域包为可选项。Shield 是唯一的策略决策点（唯一负责决定 Allow 或 Deny 的位置）。此 gate 绝不会自动批准不可逆的副作用（无法撤销的更改）。

如果 KYA_API_KEY 为空，而服务端要求身份验证，则网络命令会以非零状态码退出。eval-tool、wrap 和 invoke 在 ALLOW 时以 0 退出，在 REQUIRE_APPROVE 时以 4 退出，在 DENY 或状态未知时以 1 退出，因此类似 eval-tool && write 的命令不会绕过 gate。

--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 安装。）

其他安装方式（使用同一软件包；npm 仍是参考方式）：

# Homebrew. Homebrew 7 may ask you to trust a third-party tap: run `brew tap The-Pixel-Boys/tap` first.
# The formula installs about 270MB because of the optional semantic-search runtime.
brew install The-Pixel-Boys/tap/shield-kya

# Scoop (not yet verified on 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 插件（安装前请阅读其第一段）；Codex 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   # wire only
kya start --force     # rewrite MCP blocks
# Receipt change previews (clipped + redacted): on by default for writes
# KYA_DIFF_PREVIEW=0 to disable

每个宿主一条命令

kya start 适用于 Claude Code、Cursor 以及任何读取 .mcp.json 的宿主。它还会自动接入其检测到的所有已安装宿主的用户级配置。对于其他宿主，kya connect 会直接写入宿主专属的配置格式：

kya connect claude              # ~/.claude.json (merges mcpServers only)
kya connect grok                # ~/.grok/config.toml (appends [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      # project scope instead of global
kya connect kiro --force        # overwrite an existing shield-kya entry

Connect 会合并配置。对于无法解析的宿主配置，它绝不会重写，并会保留你的其他服务和键。支持的宿主：claude、grok、opencode、kilo、kiro、qwen、kimi、mastracode、amp、copilot、cursor。每个宿主都会接入 serve-mcp --stdio，并设置 KYA_OFFLINE=1，让网关无需密钥即可启动（无需 API 密钥）。若要连接经过身份验证的控制平面，请在宿主环境中设置 KYA_API_KEY。

没有 connect 目标的宿主也能使用：kya wrap --offline -- <agent command> 可在任何 CLI 前接入同一个评估网关。各宿主的操作指南（含验证步骤和故障排除）见 docs/hosts/。

Hook 拦截

kya start 还会在检测到的所有支持 hook 的已安装宿主中配置 PreToolUse hook：Claude Code（~/.claude/settings.json，仅合并）、Grok（~/.grok/hooks/shield-kya.json，由 kya 管理的文件）和 Kimi Code（~/.kimi-code/config.toml，追加 [[hooks]]）。之后，Agent 发出的每次工具调用都会先经过 kya hook：在本地进行评估（离线、不到一秒、无需网络），并写入全局记录（trail）。（如果你选择加入匿名使用统计，hook 还会每天最多启动一次分离运行的辅助程序；请参阅匿名使用统计（默认关闭，选择加入）。）

决策映射：本地永不允许列表中的 DENY 会阻止工具调用（退出码为 2，并返回包含 permissionDecision: "deny" 的 hookSpecificOutput deny JSON）。ALLOW 和 REQUIRE_APPROVE 会作为建议写入记录，调用则继续进行。手动配置时，可在 hook 命令中传入 --strict，以同时阻止 REQUIRE_APPROVE。

Hooks 采用故障时放行策略：任何 hook 错误或超时都会允许调用继续进行。Hooks 是提醒机制，并在本地执行永不允许列表规则，不是唯一的防护措施。策略强制执行仍通过 MCP kya.policy_evaluate 路径进行。Hooks 在新会话中生效；这三个宿主都会在会话开始时加载 hooks。

kya connect claude --hooks   # wire the PreToolUse hook by hand
kya connect grok --hooks
kya connect kimi --hooks

Claude Code 插件

此仓库也是一个名为 shield-kya 的 Claude Code 插件市场，其中包含一个插件 kya：

/plugin marketplace add The-Pixel-Boys/shield-kya
/plugin install kya@shield-kya

该插件采用建议模式，且故障时放行：它会将每次工具调用记录到本地记录（~/.kya/trail.jsonl），并且只会阻止永不允许列表中的少量项。如果 kya 缺失、崩溃或超时，工具调用会继续进行，且不会记录任何内容。它离线进行评估，因此没有 Hold，也不会进行审批。托管式强制执行通过 MCP gate 路径实现。

团队部署：将 extraKnownMarketplaces（shield-kya GitHub 源）和 enabledPlugins（"kya@shield-kya": true）提交到仓库的 .claude/settings.json，或者通过托管设置在整个组织范围内强制启用。详情和限制：docs/hosts/claude-plugin.md。

GitHub Copilot CLI 插件

先检查。 如果公开仓库中还没有 plugins/kya-copilot 文件夹（即发布该文件夹之前的每个版本），请勿在 Copilot CLI 中安装该插件：Copilot 随后会加载 Claude Code 插件，而 Copilot CLI 1.0.98 会因此拒绝每次工具调用（“Denied by preToolUse hook ... (hook errored)”）。如果你已经安装，请运行 copilot plugin uninstall kya@shield-kya，并使用 kya connect copilot（仅 MCP 服务，参阅更多宿主），直到某个版本发布该文件夹。

从发布该文件夹的版本开始：

copilot plugin marketplace add The-Pixel-Boys/shield-kya
copilot plugin install kya@shield-kya

Copilot 会优先读取 .plugin/marketplace.json，再读取 .claude-plugin/marketplace.json，因此 kya@shield-kya 会解析到 plugins/kya-copilot：一个 Agent Plugins v1 清单（plugin.json），hooks 位于 com.github.copilot/hooks/hooks.json，MCP 服务位于 mcp.json。Claude Code 和 Codex 仍会加载 plugins/kya，不会看到此文件夹。行为相同：采用建议模式，且故障时放行。Copilot 会在预工具 hook 以非零状态退出时拒绝工具调用。因此，该 hook 是一个 bash 命令：当 Copilot 的 PATH 中没有 node 时，它不会执行任何操作。否则，它会运行 scripts/copilot-hook.mjs（该脚本只转发 kya 永不允许列表中的 deny），并将除 2 以外的任何退出码转换为 0。记录功能需要 PATH 中的 Node.js 22 或更高版本。Copilot 会将 MCP 工具命名为 <server>-<tool>（例如 postgres-drop_table）；永不允许列表目前无法识别这种形式，因此 MCP 调用会被记录，但不会被阻止。记录中的行会将产品显示为 other。已在 macOS 上使用 Copilot CLI 1.0.98 测试。暂勿在 Windows 上安装：预工具 hook 仅提供 bash 形式，且尚未在 Windows 上运行；请在那里使用 kya connect copilot。详情：docs/hosts/copilot.md。

Codex 插件

同一仓库也是一个 Codex 插件市场（.agents/plugins/marketplace.json），其中包含相同的 kya 插件：

codex plugin marketplace add The-Pixel-Boys/shield-kya
codex plugin add kya@shield-kya

然后在 Codex CLI 中打开 /hooks，并信任这两个 Shield KYA 钩子：在你执行此操作前，Codex 不会运行任何插件钩子。Codex 信任的是钩子命令，而不是它运行的脚本；SessionStart 命令中包含 kya 版本，因此每次发布 kya 新版本时都会再次请求信任。Codex 还会在启动时自动升级 Git 市场，因此任何能向此仓库推送内容的人都可以更改下一次运行的内容；团队可以固定发布引用（参见指南）。其行为与 Claude Code 插件相同：仅提供建议、故障时放行，并记录 Codex 通过其钩子发送的每次工具调用（shell、apply_patch、MCP 和其他本地工具；不包括网页搜索等托管工具），只会阻止 never-list 中的工具。它不捆绑 MCP 服务；使用 kya connect codex 添加一个。详情：docs/hosts/codex.md。

Gemini CLI 扩展

仓库根目录也是一个 Gemini CLI 扩展（gemini-extension.json + hooks/hooks.json）：

gemini extensions install https://github.com/The-Pixel-Boys/shield-kya

其行为与其他插件相同：仅提供建议、故障时放行，并记录 Gemini 通过其 BeforeTool 钩子发送的每次工具调用，只会阻止 never-list 中的工具。Gemini 运行扩展钩子时无需单独的信任步骤。扩展会固定其发布时使用的 kya 版本。它不捆绑 MCP 服务；请参阅 MCP 示例。详情：docs/hosts/gemini.md。

Gate（本地 MCP 网关）

kya gate 会在你已使用的任意 MCP 服务前，设置一个仅监听回环地址（127.0.0.1，默认端口 3930）的监听器。你的主机与网关通信；网关再将请求分发给实际服务。各工具的策略来自排名前 20 的服务分类。具有破坏性的名称（drop/truncate/purge/transfer）以及各服务的 ADMIN 级工具都会被直接拒绝，并从 tools/list 中过滤掉。其他所有调用都以观察模式运行：允许执行并记录。每次调用都会写入本地记录和实时报告，也可以作为 OTLP 转发到托管接收端。

零接触： kya start 已会为你完成这些操作。它会扫描检测到的主机配置，查找第三方 MCP 服务，将其导入 .kya/gateways.json（并记录 importedFrom 字段，说明每个服务的来源），安装网关二进制文件，启动监听器，并重写各源主机的配置，使导入的服务通过网关路由。移除任何内容前，原始主机配置都会保存在 .kya/backups/ 下。未找到服务 → 不会下载任何内容，也不会启动监听器。使用 kya start --no-gate 或 KYA_GATE=off 可选择退出。如果二进制文件下载失败（离线或无网络），kya start 会警告一次，然后继续运行，但不启用网关。主机配置保持不变。需要完全控制时，仍可使用以下手动方式：

kya gate init     # scaffold .kya/gateways.json with ready-to-move recipes
# edit gateways.json: move a recipe into "servers", fill its placeholders
kya gate setup    # download the pinned gateway binary into .kya/bin
kya gate run      # generate the gateway config, start the listener detached
kya connect claude --gate   # point the host at the gateway (server key shield-kya-gate)
kya gate doctor   # binary, config, listener health, loopback-only posture

kya gate stop 会停止监管进程及其二进制文件。说明如下：kya gate setup（以及 kya start 的自动引导，仅在找到需要管控的服务时）会从我们的发布页下载固定版本的网关二进制文件。其他操作都不会下载任何内容。唯一的其他网络用途是 docs/telemetry.md 中介绍的可选匿名使用统计，除非你同意，否则默认关闭。run 从不下载任何内容。观察模式表示允许的调用会被记录，而不会被阻止。上述拒绝集合是唯一的硬性拦截，控制平面执行仍由 kya.policy_evaluate 负责。kya connect <host> --gate 支持与普通 connect 相同的主机。Grok 会在其 config.toml 中添加一个 [mcp_servers.shield-kya-gate] url 表（Grok 支持通过 HTTP 使用远程 MCP 服务）。各服务的等级和配置方法：docs/mcp-servers.md。

更长的路径（可选）

# Offline sample evaluate
kya eval-tool --offline --tool-id org.sample.never.event --irreversible
kya wrap --offline --tool-id Write --irreversible --args '{"path":"src/x.ts","content":"hi"}'
kya receipt --open
# Org Hold: KYA_HOLD=1 kya wrap …
kya dash --once --offline

安装中心：https://shield-agent.com/install

活动记录（全局）

所有项目共用一份记录（轨迹）：~/.kya/trail.jsonl（KYA_HOME 会覆盖 ~）。在任意目录运行 kya receipt --open，即可查看所有项目的活动。每个事件都包含其项目文件夹名称。出现两个或更多项目后，报告会新增项目汇总，并在每条活动流记录中显示项目名称。旧版项目级 <project>/.kya/trail.jsonl 文件仍会读取并合并；无需迁移。记录上限为 1 MB（从尾部读取：较早的事件会逐渐移除），并由所有项目共享。

报告本身是一个仪表板。顶部的主视觉行显示实时 Certify 结果、决策分布、活动迷你图和成本分摊（每个 Agent 的成本）。下方是分栏区域：Overview（分析、会话、原因）、Certify（完整的实时要求表：按领域分组的所有要求，以及状态、证据和证明）、Activity（可筛选的事件流）、System（已接入的主机、沙盒、ORR）。所有内容都包含在一个独立的离线 HTML 页面中。实时视图会添加一个外部链接：“Star on GitHub”。通过 kya start 启动的实时守护进程会在每次事件发生时重新渲染报告。

分享报告

kya receipt --share 会将当前时间窗口的脱敏摘要（聚合决策计数、产品和原因代码汇总，以及 Certify 状态；不包含路径、工具参数或会话 ID）发布到 shield-agent.com，并打印一个包含过期日期（7 天）的公开 URL（/r/<id>），任何人都可以打开；此外还会打印一行建议，提示你将报告发送给安全负责人。每个共享页面都包含一行安装命令，方便读者审查自己的 Agent，并提供一个用于为团队启动托管工作区的按钮。页面上的 Certify 状态会标明由 CLI 自行报告，而非由 Shield Agent 验证。使用 --json 时，命令只会打印 {"url", "expiresAt"}。使用 --share-url <base> 或 KYA_SHARE_URL 可指定其他收集器。

根据设计，共享操作只尝试一次（防止请求风暴：不会在后台向收集器静默重试）。使用 --share-retries <n>（最多 3 次）可选择在遇到 429/5xx/网络故障时进行有限次数的重试，采用带抖动的指数退避，并遵循服务器返回的 Retry-After。

自然语言搜索

Activity 搜索框支持普通英文。它结合了对工具 ID、摘要、原因代码、决策、项目和 MCP 服务标签进行 BM25 检索，以及本地 MiniLM 语义重排（作为可选依赖提供；如果模型运行时不可用，报告会回退到纯词法搜索）。内置的概念词汇表会将日常用词映射到事件实际使用的词汇，因此搜索 dangerous 可找到 rm/kill/delete/sudo 调用，搜索 blocked 可找到拒绝记录，搜索 held 可找到审批请求。你也可以输入 failed stripe transfers、files written by grok 或 approval required production 等内容。系统会自动处理停用词和词干，同样的搜索方式也适用于全局记录。

• 离线运行或设置 KYA_OFFLINE=1 时，搜索仅使用词法检索（不会下载模型）。
• 默认情况下，实时服务会将 BAAI/bge-small-en-v1.5 下载到 ~/.kya/models 一次，并将事件向量缓存到 ~/.kya/search-index.json。
• KYA_SEARCH_SEMANTIC=off 会停用模型，但仍保留 BM25。

托管控制台在服务端使用相同的混合搜索（Postgres 全文搜索 + 可选的 OpenAI 兼容嵌入），因此在任一位置输入的查询，效果都相同。

双平面

 host=ide (authoring)          host=runtime (production)
        │                              │
        └────────── same agent ────────┘
                    identity
                    policy evaluate  → ALLOW | DENY | REQUIRE_APPROVE
                    approval + trail

使用 KYA_HOST=ide 或 KYA_HOST=runtime 为会话添加标签。两种方式使用相同的策略路径。

环境

变量	必需	含义
KYA_BASE_URL	是（网络命令）	控制平面源站
KYA_API_KEY	启用身份验证时	API 密钥（或用于 decide 动词的 Bearer JWT）
KYA_HOST	否（默认 ide）	ide | runtime
KYA_AGENT_ID	注册后	Agent 主体 ID
KYA_MCP_PORT	否（默认 3920）	HTTP MCP 监听端口
KYA_OFFLINE	否	1/true 表示使用示例评估
KYA_HOLD	否	1/true 表示使用组织的 Hold 流程（REQUIRE_APPROVE 会创建人工工单）
KYA_DASH_PLAN	否	enterprise 可解锁许可的 TUI 窗格
KYA_DIFF_PREVIEW	否	0 禁用回执中的截断变更预览
KYA_RECEIPT_AUTO	否	0 禁用 wrap 后自动打开回执；1 强制启用
KYA_SEARCH_SEMANTIC	否	off 禁用 MiniLM 语义重排（BM25 仍可用）
KYA_SHARE_URL	否	kya receipt --share 收集器基址（默认 https://shield-agent.com）
KYA_TELEMETRY	否	0/off 强制关闭匿名使用统计（文档）；除非你选择启用，否则默认关闭
DO_NOT_TRACK	否	1 强制关闭匿名使用统计，效果与 KYA_TELEMETRY=0 相同

也可以在项目的 .kya/config.json 中设置 Gate 模式： {"gateMode": "hold"} 或 {"gateMode": "offline"}（仅接受这些确切值； 其他值均会被忽略）。Gate 本身（wrap / hook / eval）会遵循此设置， 其优先级为 flags > env > config > observe；kya certify 也使用同一解析器，因此 Gate 模式下的 certify 结果始终 反映 Gate 的实际运行方式。

MCP 工具

工具	作用
kya.policy_evaluate	ALLOW | DENY | REQUIRE_APPROVE
kya.session_ingest	观察／仅上报风险
kya.request_approval	发起人工 Hold。不会执行副作用

MCP Registry 条目：server.json，以及包的 mcpName io.github.The-Pixel-Boys/shield-kya。

{
  "mcpServers": {
    "shield-kya": {
      "command": "npx",
      "args": ["--no-install", "@shield-agent/[email protected]", "serve-mcp", "--stdio"],
      "env": {
        "KYA_BASE_URL": "http://127.0.0.1:8090",
        "KYA_API_KEY": "${KYA_API_KEY}",
        "KYA_HOST": "ide"
      }
    }
  }
}

Wrap 与 decide

npx @shield-agent/kya wrap --offline --tool-id org.sample.data.write --irreversible
npx @shield-agent/kya approve --id <approval-id>
npx @shield-agent/kya reject --id <approval-id>

托管的高风险请求（当前或此前优先级为 HIGH，或创建时带有不可逆提示）无法通过 CLI 或 TUI 批准：托管平面会返回 403 kya.approval_console_mfa_required。请在托管控制台中使用双重验证代码批准。reject 始终有效。

wrap 会进行评估，并可能创建待处理工单。它绝不会执行副作用。invoke 会在 Allow 或 APPROVED 后请求实时平面授权。它不会在此计算机上执行写入操作。TUI（dash）只能在使用 JWT（拒绝 sk_*）通过 y 确认后，才可使用 a/x 作出决定。

进程内 SDK 垫片

基于 LangGraph.js、Vercel AI SDK、Mastra、OpenAI Agents TS 或 Claude Agent SDK 构建的 Agent，无需网关即可通过相同的评估路径路由工具调用：

import { governed, governLangGraphTool, KyaDeniedError } from "@shield-agent/kya/sdk";

const run = governed({ toolId: "write_file", server: "filesystem", fn: myWrite });
await run({ path: "out.txt", content: "hi" }); // throws KyaDeniedError on DENY

默认离线评估（无网络，不连接托管平面）；显式配置后则使用实时平面。governA2aSend 会控制进程内 Agent 到 Agent 的发送。带有 LangChain 中间件的 fail-open Python 垫片正在开发中，尚未发布。支持矩阵和操作指南：docs/sdk-integrations.md；可运行脚本：examples/sdk/。

Claude 连接器

桌面端／Claude Code（本地 stdio）：

# Prefer a preinstalled package (no registry auto-install):
npx --no-install @shield-agent/[email protected] serve-mcp --stdio
# Or after npm i -g / local install:
kya serve-mcp --stdio

将 claude/claude_desktop_config.example.json 复制到 Claude Desktop MCP 设置中，或在 Claude Code 中使用 .mcp.json。使用 npx @anthropic-ai/mcpb pack 打包 Desktop 扩展（参见 manifest.json）。该包运行的是打包后的 dist/cli.js，而不是 npx -y。

Claude.ai／Cowork（托管）： 添加自定义连接器，地址为 https://shield-agent.com/mcp，请求头为 Authorization: Bearer <KYA_API_KEY>（或 X-API-Key）。目前尚未列入 Directory（使用 API 密钥身份验证，无 OAuth DCR）。

OpenAI（Codex / Responses）

**Codex CLI 插件（hooks）：**请参阅 Codex 插件。**Codex CLI / IDE（MCP）：**将 openai/codex.config.example.toml 复制到 ~/.codex/config.toml。本地 stdio 使用 npx --no-install @shield-agent/[email protected] serve-mcp --stdio。托管版 Codex 使用 url = "https://shield-agent.com/mcp"，并设置 bearer_token_env_var = "KYA_API_KEY"。

**Responses API：**请参阅 openai/responses-mcp.example.json（server_url + Authorization: Bearer <KYA_API_KEY>）。

**ChatGPT Apps（chatgpt.com）：**暂缓支持。Developer Mode 要求使用 OAuth。在此之前，请使用 Codex。

Gemini CLI

将 gemini/settings.example.json（stdio）或 gemini/settings.hosted.example.json（httpUrl + Bearer）合并到 ~/.gemini/settings.json 或 .gemini/settings.json 中。请勿同时启用两者。

Grok

**Grok CLI（本地）：**运行 kya connect grok，将 [mcp_servers.shield-kya] 表追加到 ~/.grok/config.toml（serve-mcp --stdio，无密钥离线示例评估）。在运行中的会话里，按 /mcps 中的 r 刷新。

**grok.com（托管）：**在 https://shield-agent.com/mcp 添加自定义连接器（参阅 grok/README.md）。Grok 不接受 localhost。若界面提供请求头选项，建议使用 Bearer 机器密钥。

更多宿主

每个宿主的目录中都附有可复制粘贴的示例；对于带星号的宿主，kya connect <host> 会写入相同配置。完整操作指南（验证、卸载、故障排除）：docs/hosts/。

宿主	设置	示例
Claude Code	kya connect claude（或 kya start）	-（合并 ~/.claude.json / .mcp.json）
Grok CLI	kya connect grok	-（将 [mcp_servers.shield-kya] 追加到 ~/.grok/config.toml）
OpenCode	kya connect opencode	opencode/opencode.example.json
Kilo Code	kya connect kilo	kilo/kilo.example.json
Kiro	kya connect kiro	kiro/mcp.example.json
Qwen Code	kya connect qwen	qwen/settings.example.json（+ settings.hosted.example.json）
Kimi Code	kya connect kimi	kimi/mcp.example.json
MastraCode	kya connect mastracode	mastracode/mcp.example.json
Amp	kya connect amp	amp/settings.example.json
GitHub Copilot CLI	kya connect copilot	copilot/mcp-config.example.json
Cline	npm install -g @shield-agent/kya@latest，然后按照 llms-install.md 中的步骤操作	cline/cline_mcp_settings.example.json
Droid	droid mcp add（架构未验证）	droid/mcp.example.json
Pi · OMP · Devin · Hermes · Qoder · Maki · Muse · Antigravity	kya wrap --offline -- <cmd>	docs/hosts/

Cursor 插件

此软件包包含 .cursor-plugin/plugin.json、mcp.json 和一个 wrap 技能。公开列表仓库：https://github.com/The-Pixel-Boys/shield-kya

ORR（仅报告）

npx @shield-agent/kya orr run --path . --out ./orr-report --skip-optional-producers
npx @shield-agent/kya orr run --path . --out ./orr-report --scorecard ./scorecard.json --producer openssf.scorecard
npx @shield-agent/kya orr run --path . --out ./orr-report --producer harness.agentshield --agentshield-json ./agentshield-report.json

ORR 会检查你的 Agent 设置是否安全可运行。它只是一个报告面板。扫描器、--scorecard 和 harness.agentshield 都是证据。它们绝不会允许高风险副作用，因此不是第二道策略关卡。AgentShield 是可选且只读的：没有 --fix、没有 MiniClaw，也没有运行时 hook。此软件包不依赖 ecc-agentshield。如果你传入 --producer harness.agentshield，但既未提供 --agentshield-json，也没有 agentshield 二进制文件，ORR 会记录覆盖缺口，并仍以 0 退出。显式传入 --producer 时总会尝试运行；--skip-optional-producers 只会跳过你未指定的生产器。

Certify（持续信任检查）

kya certify 会依据本地证据评估开放的 Agent Trust Baseline 目录（catalog/agent-trust-baseline-v0.json：涵盖数据与隐私、安全、保障、安全性、可靠性、问责和社会，共 31 项要求）：全局记录、ORR 输出、已连接的主机、沙箱清单、收据、成本分摊报告，以及你记录的声明。它会将差距报告写入 .kya/certify/（JSON、Markdown 和 HTML 格式）。差距列表就是你的工作计划。收据报告会实时显示相同的状态：每次渲染时都会重新计算 Certify 面板（因此随着事件流入，kya start 的实时报告也会更新），此外还有一个专门的 Certify 标签页，显示完整的实时要求表。运行 kya certify 可生成完整的差距报告和签名证据包。

npx @shield-agent/kya certify                  # gap report; exit 1 when gaps exist (CI-friendly)
npx @shield-agent/kya certify --open           # open the HTML report
npx @shield-agent/kya certify --fail-on never  # report only, always exit 0
npx @shield-agent/kya certify --attest SOC-01 --text "Acceptable-use policy: https://example.com/aup"
npx @shield-agent/kya certify --sign           # also emit a signed evidence-bundle.json

Certify 仅基于证据。它绝不会 ALLOW、DENY 或阻止任何操作。唯一的 PEP（策略执行点：能够阻止调用的组件）仍然是 Shield KYA。基于记录的机器检查在记录为空时永远不会通过（会报告 insufficient_evidence）。机器无法检查的内容由明确的本地声明（--attest）覆盖，并记录在 .kya/attestations.json 中。这些声明是未经验证的操作员陈述，并会标注为未经验证。

--sign 会生成 evidence-bundle.json：规范 JSON，由本地生成的密钥（~/.kya/keys/evidence-ed25519.json，模式为 0600，首次使用时自动创建）进行 ed25519 签名（公钥签名）。每次运行 --sign 都会打印签名密钥指纹。如果刚刚创建了密钥，CLI 会提示密钥连续性从此处重新开始（较早的证据包仍只能使用旧公钥验证）。自签名的开发者密钥可以证明证据包的完整性和密钥的连续性，但不能证明身份。通过 --sign 生成的证据包可离线验证。在公开验证端点（POST /api/v1/kya/evidence/verify）和徽章中，这些证据包会显示灰色的 self-signed 徽章。只有使用活跃托管工作区密钥签名的证据包才能获得绿色 Shield Verified 徽章。这会将徽章与托管账户关联起来，但不能证明公司或 Agent 的法律身份。证据包格式开放且有文档说明，见 docs/certify.md；任何人都可以使用其中嵌入的公钥离线验证证据包。

kya certify 在本地运行，免费且离线：无需账户，不会进行网络调用，也不检查许可证（绝不会发送使用统计信息）。目录采用 MIT 许可证，欢迎提交 PR。欧盟 AI 法案交叉映射（将基准要求映射到第 9–15、26、72 条）位于 docs/certify-eu-ai-act.md 和 src/certify/eu-ai-act-map.json。

导入追踪记录（LangSmith、Langfuse、Phoenix、OTel、AGT、ADR Sensor、OpenShell）

将现有监控导出数据导入记录，以便收据和 certify 查看：

kya import --from langsmith ./runs.json
kya import --from langfuse ./observations.jsonl
kya import --from otel ./otraces.json
kya import --from agt   # Microsoft Agent Governance Toolkit audit log
kya import --from adr-sensor ./adr-sensor-events.jsonl
kya import --from openshell ./openshell-events.jsonl

AGT 导入器会验证 AGT 的哈希链（日志行之间的校验和链接），将遭篡改的日志标记为 chainVerified=false，并且重新导入时绝不会重复添加行；详见 docs/import-agt.md。ADR Sensor 事件会将一个 AgentEvent 映射为一个或多个 KYA 事件，并在重新导入时通过稳定的 uuid 去重；详见 docs/import-adr-sensor.md。OpenShell OCSF 日志会将一行日志映射为一个 KYA 事件，并在重新导入时通过稳定的 uid 去重；详见 docs/import-openshell.md。AGT 的哈希链未使用密钥（没有密钥），因此“已验证”表示内部一致，并不代表真实可信。托管控制台接受相同的格式（docs/import-agt-hosted.md）。

导入内容会作为 observe 模式事件写入（host: import、reasonCode: IMPORTED；错误运行会变为 DENY/IMPORTED_ERROR），并在来源提供延迟和 token 数量时映射这些数据。超过 50MB 的文件会被拒绝。损坏的记录会被跳过，不会中止导入。任何导入内容写入后，报告（kya start / kya receipt）都会显示 Import 卡片，其中包含各格式的数量、错误数量，以及最新导入的事件。

调查（检测结果 + 修复简报）

kya investigate 会对记录运行固定的本地检测器，不会调用大模型：摘要中的 PII 泄露、DENY 激增、审批重试循环、反复尝试永不可执行的事件、管控期间使用未知工具、工具运行缓慢。检测结果会归入事件。每个事件都会生成一份 Markdown 修复简报，格式适合粘贴到 Claude Code、Cursor 或 Codex。每次运行还会将精简摘要保存到 ~/.kya/investigate-last.json，报告会将其呈现为 Investigations 卡片（按严重程度列出检测结果及检测器 ID，并附上优先级最高的修复简报）。

kya investigate           # summary: counts by severity + top incidents
kya investigate --json    # findings + incidents + briefs, machine-readable

端点发现

kya discover 会列出当前工作站上的 AI Agent、IDE 扩展、桌面应用、模型运行时和 MCP 服务。扫描器只检查路径和配置文件；不会执行发现的二进制文件，也不会连接运行时端口。快照会写入 ~/.kya/discovery/<iso-ts>.json，并同时复制到 latest.json；实时报告会显示 Discovery 卡片，其中包含总数、已批准/待审核数量和主要类别。

kya discover                              # scan, save snapshot, print summary
kya discover --json                       # print snapshot JSON to stdout
kya discover --diff ~/.kya/discovery/latest.json  # compare current scan to saved snapshot
kya discover --push                       # scan and push to hosted console

推送需要 KYA_BASE_URL 和 KYA_API_KEY：

export KYA_BASE_URL=https://shield-agent.com
export KYA_API_KEY=your-token
kya discover --push

证据路径中的主目录前缀会被脱敏（替换为 ~）。快照包含根据操作系统生成的稳定 endpointUid、主机名哈希和用户名哈希。原始主机名和用户名不会离开设备。完整扫描列表和隐私说明请参阅 docs/discovery.md。

告警 Webhook（决策路由）

将 DENY / REQUIRE_APPROVE 事件路由到 Slack、Microsoft Teams、Linear、Jira 或任意 Webhook。配置位于项目级 .kya/config.json 或全局级 ~/.kya/config.json 中：

{
  "notify": {
    "webhooks": [
      { "url": "https://hooks.slack.com/services/...", "template": "slack", "events": ["DENY", "REQUIRE_APPROVE"] },
      { "url": "https://<env>.environment.api.powerplatform.com:443/powerautomate/...", "template": "teams", "events": ["DENY"] },
      { "url": "https://example.invalid/jira", "template": "jira", "events": ["DENY"] }
    ]
  }
}

每条 Slack 消息的末尾都会注明，Slack 表情回应或回复不代表批准。托管端也可以向 Slack 发送新的审批请求（控制台中的 Approvals > Slack notify）；此消息只会链接到控制台，没有批准按钮。

teams 模板会向 Teams Workflows Webhook 发送一张 Adaptive Card（在 Teams 中依次选择频道、Workflows、“Send webhook alerts to a channel”，然后复制 Webhook 链接）。卡片没有按钮，末尾会注明，Teams 表情回应或回复不代表批准。事件文本中的 Teams 用于链接、提及和 Markdown 的字符会被移除。工作流 URL 中包含签名，因此请妥善保密；通知日志只会存储主机名。托管端也可以向 Teams 发送新的审批请求（控制台中的 Approvals > Teams notify）。

KYA_NOTIFY_WEBHOOK=<url> 是零配置方式（通用负载）。投递会采用指数退避重试（250ms/1s/4s + 随机抖动）、每次尝试设置超时、按 URL 使用熔断器（停止向持续失败的目标发送），并进行发送速率限制。负载仅由已脱敏的记录字段构建；如果密钥扫描发现敏感内容，则会自动回退到精简负载。对于短生命周期的 hook/wrap 子进程，会由分离的辅助进程（kya notify-flush）发送 Webhook，因此门控路径无需等待网络响应。每次投递尝试都会追加到 ~/.kya/notify-log.jsonl（仅记录目标主机名，不记录完整 URL；最多保留最近 500 条），报告的 System 选项卡会显示 Alerts 面板，其中包含各目标的投递成功/失败次数和最近一次尝试。

可选沙箱封装（Firecracker、OpenShell）

位于网关旁，而非 MCP 内部。仅限主动启用：

KYA_SANDBOX=mock kya sandbox spawn
KYA_SANDBOX=mock kya sandbox exec --sandbox-id <id> --cmd "true"
KYA_SANDBOX=mock kya sandbox kill --sandbox-id <id>

未指定 --sandbox-id 的 org.sample.sandbox.exec 会被拒绝，错误为 MISSING_SANDBOX_ID。使用真实的 Firecracker 需要 PATH 中有 firecracker 和 jailer，并设置内核/rootfs 环境变量（KYA_SANDBOX_KERNEL、KYA_SANDBOX_ROOTFS）。我们不随附这些二进制文件。KYA_SANDBOX=openshell 会通过 openshell CLI 调用 NVIDIA OpenShell，并要求 PATH 中有 openshell 和 docker 或 podman；KYA 会为每次生成渲染一份 OpenShell 策略，限定 CLI 的最低版本，并始终设置 OPENSHELL_TELEMETRY_ENABLED=false。后端详情请参阅 docs/sandbox.md。serve-mcp 仍仅开放 evaluate / ingest / request_approval。

成本分摊（仅观测）

kya orr run --usage ./usage.json（或 .kya/usage.json）会添加成本分摊部分：按 Agent 和运行统计 token 数与预估 USD。子 Agent 会嵌套在 parentRunId 下。该部分不是计费表，也不是策略网关。使用会话摄取用量后，托管指标会显示相同的汇总数据。记录中包含主机报告的 token 数的事件（带有 usage 对象的 hook 载荷、导入的追踪记录）会优先于静态的逐事件估算；报告还会说明有多少个时间窗口事件包含真实用量数据。

企业版（单独层级）

上述首日 npx 路径不需要固定版本、私有注册表、多租户密度、ORR 看板运维和支持服务。

开发

pnpm install
pnpm test
pnpm build

文档

• 安装中心
• KYA 的工作原理
• 各主机配置指南（23 种主机）
• Top-20 MCP 服务支持矩阵（分类 + 网关配置指南）
• OTLP 指标（开源版 + 托管版）
• 匿名使用统计（主动启用）：发送内容、控制选项、保留期限
• OWASP MCP 治理映射
• Claude Code 插件 · Copilot CLI 插件 · Codex 插件 · Gemini CLI 扩展
• 导入 AGT 审计日志（CLI） · 托管版
• kya certify - Agent Trust Baseline 差距报告
• Agent Trust Baseline 的 EU AI Act 对照表
• 沙箱后端（mock / firecracker / openshell）
• 适用于你的可观测性技术栈
• SDK 与框架集成（进程内垫片）
• 托管版运维人员 SSO / SCIM（不包含在开源 CLI 中）
• 开源内容与托管内容
• 另请参阅此仓库中的 LIMITATIONS.md

匿名使用统计（主动启用，默认关闭）

在终端中首次运行 kya start、kya init 或 kya connect 时，KYA 会询问一次是否分享匿名使用统计（[y/N]，默认选 No）。只有明确输入 y 或 yes 才会启用。在 CI、非交互式运行、使用 --json 时，或设置了 DO_NOT_TRACK=1 / KYA_TELEMETRY=0 时，都不会发送任何数据。kya hook 本身从不访问网络；启用后，它每天最多启动一次分离运行的辅助程序，发送一个 ping，因此仅安装 hook 也会计为活跃。

kya telemetry show        # the exact payload, field by field
kya telemetry status      # on / off / not asked, and what overrides it
kya telemetry off --purge # turn off and erase what the server holds for this install

完整详情、载荷、保留期限及如何自托管端点，请参阅：docs/telemetry.md。

OTLP（可选）

选择启用。默认关闭。

**OSS CLI：**设置 KYA_OTLP_ENDPOINT（或 OTEL_EXPORTER_OTLP_ENDPOINT）以导出精简的评估延迟（kya.client.evaluate.latency），仅带有 verdict 和 host 标签。不包含工具参数或 API 密钥。

**决策跨度导出：**设置 KYA_OTLP_EXPORT_ENDPOINT（或在 .kya/config.json 中设置 "otlpExport": { "endpoint": ... }），将每个决策作为 OTLP/JSON GenAI 跨度（gen_ai.tool.name、kya.verdict、kya.reason_code，以及已知时的令牌属性）发送到任意 OTLP/HTTP 后端。长时间运行的进程（MCP gate、网关）会导出每个决策。Hook/wrap 启动的进程会通过分离运行的 notify-flush 帮助程序导出 DENY / REQUIRE_APPROVE。明文 http 仅在回环地址的情况下接受，除非设置 "insecure": true。刷新结果会收集到 ~/.kya/otel-stats.json（端点主机标签、已发送/失败的跨度数、上次导出时间），并显示在报告 System 标签页的 OTel 导出面板中。

**托管平台：**当 KYA_OTLP_ENABLED=true 时，提供更丰富的 Micrometer 仪表和计时器。

完整的环境变量、Grafana/Datadog 说明、禁止列表和 Collector 示例：docs/otlp.md。