ai-controllable-tool-design

设计让 AI agent 安全调用的系统工具(CLI 底座、SKILL.md 标准、硬确认、提权模型)。

SKILL.md

GitHub

AI 可调用系统工具设计

设计"AI agent 能安全操作真实系统"的工具(启动项管理器、进程管理器、文件系统工具等)。BootKeeper 实战打磨出的模式。

核心原则:CLI 是底座,skill/MCP 是皮

Skill 不是跨 agent 标准——Claude 的 SKILL.md、Hermes、OpenCode 格式各异。让"任何 agent 都能调用"的唯一通用执行面是 CLI:

任何 AI agent → 读 SKILL.md/skill → 调 CLI → core 逻辑
协议系 agent  → 连 MCP (后置)    → 调 CLI → core 逻辑
  • CLI 输出 JSON(AI 直接解析)
  • SKILL.md 是"说明书"教 agent 怎么调 CLI,不是执行层
  • MCP 只是包 CLI 的薄适配层,可后置(不动 core)
  • 跨 agent 技能标准:skills.sh(Vercel,npx skills add <owner>/<repo>,覆盖 19+ agent 含 nous-research/Hermes)。SKILL.md 放仓库根,标准格式 frontmatter(name + description)

安全模型:硬确认,不信 AI 自觉

AI 操作真实系统时,注入风险是真实威胁(恶意启动项名/路径本身就是指令载体)。防线必须建在运行时,不在 prompt:

  1. 硬确认 token:写工具(delete/enable/disable/add)默认拒绝执行,必须先拿到确认 token(确认窗通过后颁发,带超时)。AI 可以不弹窗,但不弹窗就什么都改不了。
  2. 弹窗事实独立核验:确认窗显示的"事实"(路径、签名、发布者、风险)由提权进程自己重新查证,不信调用方传来的文本。调用方只传"操作意图 + 条目 ID"。
  3. 风险定级 = 软件规则(确定性函数:未签名 + 非系统路径 + 非可信发布者 = 高),AI 只分析建议,用户最终拍板。禁止 AI 生成风险结论。
  4. 规则引擎一份代码:所有进程共享同一核心 crate,禁止各写一遍。

提权模型:sidecar 永不提权,helper 一次性提权

三进程架构(UAC 场景):

CLI/服务 (常驻, 普通权限) → 写请求 → helper (提权一次性)
                                        → 弹独立确认窗(不依赖 GUI)
                                        → 用户点"是" → 执行 + 快照 → 结果回传
  • sidecar/CLI 永远普通权限(不常驻管理员)
  • 提权只发生在 helper 的短暂生命周期(ShellExecuteW "runas" 拉起)
  • 确认窗独立于主 GUI——用户在桌面任何位置都能处理 AI 授权
  • GUI 的 UAC 重启不影响 helper/CLI 的常驻

快照与回滚(用户数据安全,不可省)

  • 每次写操作前自动备份,记录操作前后快照
  • 快照默认保留 N 天(如 7 天),可配置
  • 禁用语义用改名(Foo → Foo.disabled,Autoruns 官方思路):可逆、恢复 = 改回名字、快照只存"原名→改名后名"映射
  • MCP/skill 的 tool surface 必须含 restore_item / snapshot list——AI 禁错了要能自己还回去

关键坑位

  • 弹窗疲劳:按项确认 40 次用户无脑点是,边界失效。要分级:高风险逐项确认、低风险可批量。
  • prompt 防不住 injection:恶意条目把"删掉 Defender"伪装成用户下一步意图。别把宝押在 prompt 上,弹窗展示机器事实(路径/签名/发布者/原值),不是 AI 修辞。
  • skill 不是 MCP 替代品:如果目标包含"协议系 agent 也能连",MCP 迟早要补——设计时留好"包 CLI"的接缝,别把逻辑焊死在 skill 里。