V3SP3R 架构解析:如何设计一个 AI Agent 驱动的三层安全架构
V3SP3R 架构解析:如何设计一个 AI Agent 驱动的三层安全架构
V3SP3R(Vesper)是一款 AI Flipper control 应用:它在 Android 端为 Flipper Zero 装上一个 AI Agent 大脑,让你用一句自然语言就能完成读取设备信息、管理文件、发送 SubGHz 信号等操作。而它的核心看点,是一套"AI 只发命令、系统负责拦截"的三层安全架构——本文完整拆解这套架构的每一层设计,以及它如何让 AI Agent 既灵活又安全。
一、为什么需要"安全架构"来约束 AI Agent?
直接让大模型操作硬件是最危险的做法:模型会幻觉、会误判、也可能被诱导。V3SP3R 在 docs/architecture.md 中确立了 5 条核心原则:
- AI 发命令,Android 执行现实(The model never touches BLE)——模型永远碰不到蓝牙底层
- 单一命令接口——所有操作只走一个
execute_command工具,杜绝旁路 - 写入前先看 diff——修改已有文件必须先展示差异
- 只在必要时确认——读取静默执行,破坏性操作才弹窗
- 一切操作留痕——所有 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 个启发
- 命令与现实分离:LLM 输出永远视为"提议"而非"指令",执行权必须留在可信的系统侧
- 单一入口 + 结构化 schema:接口越收敛,攻击面越小;配合 JSON Schema 可让模型输出可校验
- 风险分级 + 时限权限 + 审计闭环: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 安全架构的设计之路上,玩得开心、用得更安心 🚀