V3SP3R 架构解析:如何设计一个 AI Agent 驱动的三层安全架构

原创2026-10-10 19:34:321,354 阅读

V3SP3R 架构解析:如何设计一个 AI Agent 驱动的三层安全架构

V3SP3R(Vesper)是一款 AI Flipper control 应用:它在 Android 端为 Flipper Zero 装上一个 AI Agent 大脑,让你用一句自然语言就能完成读取设备信息、管理文件、发送 SubGHz 信号等操作。而它的核心看点,是一套"AI 只发命令、系统负责拦截"的三层安全架构——本文完整拆解这套架构的每一层设计,以及它如何让 AI Agent 既灵活又安全。

一、为什么需要"安全架构"来约束 AI Agent?

直接让大模型操作硬件是最危险的做法:模型会幻觉、会误判、也可能被诱导。V3SP3R 在 docs/architecture.md 中确立了 5 条核心原则:

  1. AI 发命令,Android 执行现实(The model never touches BLE)——模型永远碰不到蓝牙底层
  2. 单一命令接口——所有操作只走一个 execute_command 工具,杜绝旁路
  3. 写入前先看 diff——修改已有文件必须先展示差异
  4. 只在必要时确认——读取静默执行,破坏性操作才弹窗
  5. 一切操作留痕——所有 Agent 行为可审计、可回放

整个应用的架构分三层,来自官方架构图:

┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                        │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │
│  │  Chat   │ │  Files  │ │ Device  │ │  Audit  │ │Settings│ │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └───┬────┘ │
│  ┌────┴───────────┴───────────┴───────────┴───────────┴────┐ │
│  │                      ViewModels                         │ │
│  └────────────────────────────┬────────────────────────────┘ │
├───────────────────────────────┼──────────────────────────────┤
│                      Domain Layer                             │
│  VesperAgent → CommandExecutor → RiskAssessor /              │
│  PermissionService / DiffService / AuditService               │
├───────────────────────────────┼──────────────────────────────┤
│                       Data Layer                              │
│  FlipperFileSystem → FlipperProtocol → FlipperBLE / Room DB  │
└──────────────────────────────────────────────────────────────┘

💡 三层各司其职:展示层管"人怎么交互",领域层管"安全怎么落地",数据层管"设备怎么通信"。安全逻辑全部集中在领域层,这是理解整个项目的钥匙。

二、展示层(Presentation Layer):自然语言入口

展示层基于 Jetpack Compose + Hilt 构建,包含 Chat、文件浏览器、设备管理、审计、设置等 10+ 个屏幕:

  • Chat Screen:与 AI 对话的主入口,支持语音、图片、文字三种输入
  • Audit Screen:按会话、按操作类型过滤 AI 的历史行为
  • Device Screen:管理 BLE 连接、查看电量与固件信息

这一层的关键代码入口是 VesperAgent.kt。VesperAgent 是"会话编排者":你每发一条消息,它就负责把对话状态更新、调用大模型、接收工具调用、再交给 CommandExecutor 执行,并把进度(如"Planning next action...")实时推给 UI。

👉 设计启示:UI 层不写任何业务判断,只消费 Agent 暴露的 StateFlow 状态流,安全逻辑不会"漏"到界面上。

三、领域层(Domain Layer):三层安全架构的心脏

领域层是 V3SP3R 最精彩的部分,由 5 个协作组件构成。

1️⃣ 单一命令接口:execute_command

模型与设备之间只有一个桥梁——execute_command 工具,其完整参数定义在 execute_command_schema.json。它声明了 28 种动作:read_file、write_file、delete、subghz_transmit、badusb_execute、request_photo……

同时,系统提示词(vesper_system.txt)向模型反复强调三条纪律:

  • 只允许使用 execute_command 工具,单次响应最多 3 条命令
  • 遵循 Read-Verify-Write(先读、后改、再验证)模式
  • "系统会自动拦截危险操作"——模型不必(也不能)自己判断安全性

🎯 把模型能力收敛到一个结构化接口,是 AI Agent 安全设计的第一课。

2️⃣ RiskAssessor:风险分级由 Android 说了算

CommandExecutor 收到每条命令后,第一件事是调用 RiskAssessor 评估风险。源码注释写得很直白:"Android always computes the real risk, ignoring any AI assessment"(RiskAssessor.kt)。

四级风险模型:

风险级别 典型操作 处理方式
🟢 LOW 列目录、读文件、查电量 静默自动执行
🟡 MEDIUM 写文件、复制文件 展示 diff,用户点"Apply"
🔴 HIGH 删除、移动、覆盖写 二次确认(双击 armed 1.8 秒)
⛔ BLOCKED 系统路径、固件、密钥文件 直接拒绝,需设置中解锁

其中 BLOCKED 级的受保护路径硬编码在 RiskLevel.kt:/int/ 内部存储、/ext/update/ 固件目录,以及 .key、.priv、.secret 后缀文件。这类路径默认锁死,即使用户解锁也有专门流程。

⚠️ 注意一个细节:模型"声称"自己删了文件,不代表真删了——风险分级在 Android 侧重新计算,模型的话只是建议。

3️⃣ PermissionService:最小权限 + 时限授权

PermissionService.kt 实现的是"按路径授权 + 自动过期"的机制:

  • 权限按 路径 + 操作类型 授予(比如只允许写 /ext/subghz/)
  • 每次授权默认 15 分钟自动过期,过期即回收
  • 权限外的写入会自动从 MEDIUM 升级为 HIGH 风险

这就是安全工程里经典的 least privilege(最小权限原则) 在 AI Agent 场景的落地。

4️⃣ DiffService:写入前先"看一眼"

文件修改类操作执行前,DiffService.kt 会基于 java-diff-utils 生成 unified diff 和并排对比视图(红删绿增、统计增删行数),由 DiffViewer.kt 渲染展示。用户确认看到"将要改什么",而不是"AI 说它要改什么"。

5️⃣ AuditService:全链路留痕

AuditService.kt 为每次会话建立审计记录:命令接收、风险评估结果、批准/拒绝决策、执行耗时、trace_id 全部落库(Room Database)。任何一条 AI 操作都可以事后回放——对安全研究场景,可审计性就是信任的基础。

四、数据层(Data Layer):真正触碰设备的地方

数据层是唯一允许接触硬件和网络的层:

  • FlipperBleService:前台 Service,管理 BLE 扫描、GATT 连接与串口特征读写(FlipperBleService.kt),通信采用"长度前缀帧协议"
  • FlipperProtocol / FlipperFileSystem:协议解析 + 高层文件操作
  • OpenRouterClient:调用大模型的 HTTP 客户端,内置 30 次/分钟限流、指数退避重试、JSON 修复(OpenRouterClient.kt)
  • Room + DataStore:聊天记录、审计日志入库;API Key 存入加密 DataStore

📌 这一层与领域层的边界至关重要:BLE 原始能力对外不可见,Agent 永远只能表达"我想写这个文件",而"怎么写、能不能写"由领域层裁决。

五、一条命令的完整旅程:从自然语言到硬件

以"把 garage.sub 频率改成 315MHz"为例,整条链路如下:

用户:"把 garage.sub 的频率改成 315MHz"
   │
   ▼
VesperAgent 转述给 LLM(OpenRouterClient,携带 execute_command 工具定义)
   │
   ▼
LLM 返回工具调用:write_file(path=/ext/subghz/garage.sub, content=...)
   │
   ▼
CommandExecutor.execute()
   ├─ AuditService 记录 COMMAND_RECEIVED(生成 trace_id)
   ├─ RiskAssessor.assess() → MEDIUM(路径在授权范围内)
   ├─ DiffService.computeDiff() → 生成 unified diff
   ├─ ApprovalDialog 弹出 → 用户点 "Apply"
   └─ FlipperFileSystem 通过 BLE 写入 → 执行成功
   │
   ▼
AuditService 记录最终结果,UI 更新,全程可审计

如果是删除操作,审批对话框 ApprovalDialog.kt 会要求双击确认(第一次点击后 1.8 秒内必须再点一次才生效),用交互成本物理性地阻止误操作。

六、这套架构给 AI Agent 开发的 3 个启发

  1. 命令与现实分离:LLM 输出永远视为"提议"而非"指令",执行权必须留在可信的系统侧
  2. 单一入口 + 结构化 schema:接口越收敛,攻击面越小;配合 JSON Schema 可让模型输出可校验
  3. 风险分级 + 时限权限 + 审计闭环:LOW 快、HIGH 慢、BLOCKED 绝不放,且每一级都有日志可查

V3SP3R 用一套简洁的三层架构证明:AI Agent 驱动硬件,"敢放手"的前提是"有护栏"。

相关模块速查

模块 路径
架构文档 docs/architecture.md
命令接口 Schema docs/execute_command_schema.json
Agent 系统提示词 docs/vesper_system.txt
会话编排 ai/
风险与执行引擎 domain/executor/
权限/审计/Diff 服务 domain/service/
BLE 通信 ble/

想动手体验的话,可以克隆仓库后在 Android Studio 中构建:

git clone https://gitcode.com/gh_mirrors/v3s/V3SP3R
cd V3SP3R
./gradlew assembleDebug

祝你在 AI Agent 安全架构的设计之路上,玩得开心、用得更安心 🚀

登录后查看全文
V3SP3R