元盾（yotta-guardian）
跨智能体的工具调用拦截护栏：确定性规则引擎 + 可插拔意图验证，对 exec / write / edit / read / run / shell 工具调用做安全评估，输出 allow / deny + 命中规则 + 审计日志。
零依赖（Python 3.8+ 标准库），Windows + Linux + macOS 通用；Claude Code / Cursor / Codex / 通用 Agent 均可调用。
何时使用
- 代理要执行高风险命令：递归删除系统路径、磁盘格式化（mkfs / fdisk / dd 写设备）、提权（chmod 全权限 / chown 系统路径 / 账户管理）、防火墙改动（iptables 清空 / ufw disable / netsh 关闭）、反向 shell（netcat 执行 / bash /dev/tcp）、下载即执行（curl / wget 管道交给 shell）等；
- 代理要写入系统敏感路径（/etc/passwd、/etc/sudoers、SSH 授权文件、Windows hosts / 系统目录、注册表启动项）或修改系统配置；
- 需要在执行危险操作前做一次确定性安全检查（gate），并留下审计记录。
Do NOT trigger：
- 默认只读评估，不自动执行、不放行危险操作，也不替代用户最终决策；
- 不隐藏审计记录；被拦截时如实上报原因与命中规则；
- 已获明确授权的运维操作应显式放行（--allow / --allow-path / 自定义规则），而不是绕过检查。
快速使用
Windows 用 python，Linux/macOS 用 python3。
# 检查一条 exec（0 = 允许）
python3 scripts/yotta_guardian.py check exec --cmd "git status"
# 检查危险命令（默认拒绝，退出码 3）
python3 scripts/yotta_guardian.py check exec --cmd "rm -rf /"
# 检查写操作
python3 scripts/yotta_guardian.py check write --path /etc/passwd --content "..."
# 批量检查（agent 在执行前把待执行调用列表交给护栏）
python3 scripts/yotta_guardian.py check --batch calls.json --json
# 审计
python3 scripts/yotta_guardian.py check exec --cmd "..." --audit-log .yotta-guardian/audit.jsonl
python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
工作流程（AI 智能体执行危险操作前）
- 先检查：把将要执行的工具调用交给护栏
check（单条或--batch批量）。 - 看退出码：0 = 允许；1 = 允许但带警告（建议人工复核）；2 / 3 = 拒绝（high / critical，不要执行）；4 = 用法错误 / 致命异常（引擎没跑起来 —— 绝不要当作放行）。
- 被拒绝怎么办：如实向用户报告原因与命中规则；确有授权的操作，用
--allow/--allow-path/ 自定义规则文件放行并留审计记录；不要绕过检查。 - 留痕：高风险场景用
--audit-log落审计日志，供追溯。
宿主接入（把护栏挂到「工具调用前」事件时）
skill-manifest.json 声明 before_tool + fallback: explicit-unverified。接入方按下面三条做，可避开实测踩过的坑：
- 放行不要回「允许」：只在拦截时输出拒绝判定（如
permissionDecision: "deny"）；放行时不输出任何判定，把决定权交回宿主。若放行时回「allow」，会覆盖宿主自身的权限流程，护栏就变成自动放行器 —— 护栏只该「拦」，不该「代批」。 - 用文件接引擎输出：部分 hook 进程环境里，用管道捕获子进程 stdout 会拿到空值（同一写法跑
python -c "print(1)"却正常）；把引擎 stdout / stderr 重定向到临时文件再读回，判定即稳定（引擎自身的 stdout 是纯净的，--json可直接解析）。 - stdin 先按 UTF-8 读：hook 载荷里的命令文本常含中文，按本机默认码页解码会乱码；读 stdin 前先
sys.stdin.reconfigure(encoding="utf-8")（引擎已对自身 stdout / stderr 做 UTF-8 处理，stdin 由接入方负责）。
另外：引擎对「没跑起来」是 fail-closed 的 —— 规则表加载失败或运行期未预期异常一律以退出码 4 结束并在 stderr 写「致命异常: …」。接入方应把 4 当作不放行 + 报告处理，而不是放行。
策略（policy）
| 策略 | 行为 |
|---|---|
| default（默认） | 拒绝 critical / high；中危警告（exit 1） |
| strict | 拒绝 medium 及以上；低危也提示 |
| loose | 仅拒绝 critical；高危仅警告 |
可插拔意图验证（不绑模型）
- 默认纯确定性规则，不调用任何模型、零外部依赖；
--heuristic：启用内置本地启发式验证（对高影响动词升级为需人工确认）；--verifier "命令"或配置文件：外接任意意图验证器（如 LLM 网关），协议见 references/intent-verifier.md。
参考文档
- references/rules.md — 规则目录与匹配说明
- references/policies.md — 策略 / 退出码 / 使用姿势
- references/intent-verifier.md — 意图验证器协议
使用范围、授权与法律红线
- 范围：本技能只对工具调用做执行前风险评估，并输出 allow / deny 与审计记录；它不是操作系统沙箱，不执行、不放行、不修改目标系统，也不替代宿主自身的权限控制。
- 授权：仅用于你拥有或已获得明确授权的系统、账户与数据。被拒绝的操作必须由有权限的人确认；显式放行只用于已确认的合法运维场景。
- 法律与合规红线：不得用于未授权访问、破坏、规避安全控制或其他违法用途；使用者应遵守适用法律、监管要求与组织安全政策。评估结果只作为决策辅助，最终责任由操作者承担。