MemOS 桌面端 Safe File Deletion 技能指南:为 AI Agent 构建不可绕过的文件删除许可机制

原创2026-09-22 20:19:041,752 阅读
文章标签:人工智能大模型AI AgentAgent 记忆AI 应用RAG多模态知识图谱本地部署向量数据库MCP 服务后端dsh-plugin

MemOS 桌面端 Safe File Deletion 技能指南:为 AI Agent 构建不可绕过的文件删除许可机制

本文以 MemOS 仓库中 apps/openwork-memos-integration/apps/desktop/skills/safe-file-deletion/SKILL.md 为骨架,系统讲解 openwork-memos-integration 桌面应用如何通过 OpenCode Skill + MCP 工具 + Electron 主进程 HTTP 桥 + 渲染层警告 UI 四层协作,强制任何文件删除操作先获得用户显式许可。读完本文,你将掌握 request_file_permission 工具的完整调用协议、批量删除参数的底层实现、删除警告 UI 的渲染细节,以及如何在本地验证整条安全链路。

为什么 AI Agent 删除文件必须"过一道闸"

在 MemOS 的 openwork-memos-integration 桌面应用中,Agent(Accomplish)通过 OpenCode CLI 执行文件管理任务。与纯 CLI 场景不同,桌面应用中的用户看不到 Agent 的终端输出,Agent 在静默执行 rm、unlink、fs.rm 等命令时,一旦路径写错或意图理解偏差,就可能造成不可逆的数据丢失。为此,仓库引入了 safe-file-deletion 技能(SKILL.md),将"删除前必须征得用户同意"从口头约定固化为 Agent 必须遵守的硬性流程。

该技能的核心设计目标有三个:

  1. 全量覆盖:不只拦截 rm,还覆盖 unlink、fs.rm、fs.rmdir 以及任何会从磁盘移除文件的脚本或工具;
  2. 批量友好:多文件删除合并为一次授权请求(filePaths 数组),而不是让用户逐条点击确认;
  3. 不可绕过:技能明确禁止通过清空文件内容、移动到隐藏目录、使用冷门命令等方式规避删除确认。

技能的声明式定义:Frontmatter 与触发条件

SKILL.md 以 YAML Frontmatter 声明技能元数据:

---
name: safe-file-deletion
description: Enforces explicit user permission before any file deletion. Activates when you're about to use rm, unlink, fs.rm, or any operation that removes files from disk. MUST be followed for all delete operations.
---
  • name 是技能的标识符,OpenCode 约定技能存放于 $OPENCODE_CONFIG_DIR/skills/<name>/SKILL.md;
  • description 是 Agent 的触发信号:当模型即将执行 rm、unlink、fs.rm 等删除操作时,会依据该描述自动加载技能正文并遵守其中的规则。

从仓库实现看,OpenCode 配置目录由 config-generator.ts 决定:开发环境下为 apps/desktop(技能位于 apps/desktop/skills/),打包后为 process.resourcesPath。这意味着本技能在开发与生产两种运行形态下都能被 OpenCode 发现。

核心规则:五步强制流程

技能正文规定了删除任何文件前必须执行的五步流程(原文完整继承如下):

  1. 调用 request_file_permission 并传入 operation: "delete";
  2. 若涉及多个文件,使用 filePaths 数组(而不是发起多次调用);
  3. 等待工具返回响应;
  4. 仅当响应为 "allowed" 时才继续执行删除;
  5. 若响应为 "denied",承认结果并不得删除。

这套流程与 Agent 系统提示词中的 filesystem-rules 章节互为表里。config-generator.ts 将如下规则注入 Accomplish 的系统提示词:

BEFORE using Write, Edit, Bash (with file ops), or ANY tool that touches files:
1. FIRST: Call request_file_permission tool and wait for response
2. ONLY IF response is "allowed": Proceed with the file operation
3. IF "denied": Stop and inform the user

同时给出了反例与正例:直接调用 Write({ path: "/tmp/file.txt", ... }) 而不请求许可属于错误行为;必须先 request_file_permission({ operation: "create", filePath: "/tmp/file.txt" }) 等待 "allowed" 后才可执行写入。删除操作(bash rm、delete 命令)同样适用。

适用操作范围

技能明确列出所有必须走许可流程的删除形态:

  • rm 命令(单文件或多文件)
  • rm -rf(递归删除目录)
  • unlink、fs.rm、fs.rmdir
  • 任何会删除文件的脚本或工具

从 MCP 服务端实现看,删除只是六种文件操作之一。file-permission/src/index.ts 定义了完整操作枚举:

interface FilePermissionInput {
  operation: 'create' | 'delete' | 'rename' | 'move' | 'modify' | 'overwrite';
  filePath?: string;
  filePaths?: string[];
  targetPath?: string;
  contentPreview?: string;
}

delete 操作还共享 filePaths 批量字段的设计,是全部六种操作中风险等级最高、UI 警告最强的一类。

请求参数详解:单文件与批量删除

技能给出两种标准请求负载,均可直接复制使用。

单文件删除:

{
  "operation": "delete",
  "filePath": "/path/to/file.txt"
}

多文件删除(合并为一次提示):

{
  "operation": "delete",
  "filePaths": ["/path/to/file1.txt", "/path/to/file2.txt"]
}

结合 MCP 服务端源码,可补充以下参数约束(index.ts 的 inputSchema):

  • operation:必填,枚举值为 create、delete、rename、move、modify、overwrite,其他取值会被拒绝;
  • filePath:可选,被操作文件的绝对路径;
  • filePaths:可选,批量操作的绝对路径数组(例如删除多个文件时使用);
  • targetPath:可选,rename/move 操作的目标路径;
  • contentPreview:可选,用于 create/modify/overwrite 的内容预览,服务端会截断为前 500 字符(contentPreview?.substring(0, 500))。

校验逻辑要求 operation 必填,且 filePath 与 filePaths 至少提供一个,否则返回错误:

if (!operation || (!filePath && (!filePaths || filePaths.length === 0))) {
  return {
    content: [{ type: 'text', text: 'Error: operation and either filePath or filePaths are required' }],
    isError: true,
  };
}

工具调用成功后返回文本结果:"allowed" 或 "denied",Agent 依据该结果决定是否执行删除。

端到端调用链:从 Agent 到用户点击的四层桥接

删除许可不是 Agent 自问自答,而是一条横跨四个进程/层的完整链路。从源码可以确认如下架构(实施方案 与代码实现一致):

  1. Agent(OpenCode):依据 SKILL.md 规则,调用 MCP 工具 request_file_permission;
  2. file-permission MCP Server(index.ts):基于 @modelcontextprotocol/sdk 实现,通过 stdio 与 OpenCode 通信,将请求以 HTTP POST 转发到 Electron 主进程;
  3. Electron 主进程 Permission API(permission-api.ts):监听 127.0.0.1:9226(端口可用环境变量 PERMISSION_API_PORT 覆盖,默认 9226),处理 POST /permission,向渲染进程发送 permission:request 事件并挂起等待用户响应;
  4. 渲染进程 UI(Execution.tsx):弹出权限模态框,用户点击 Allow/Deny 后,响应经 IPC 回到主进程,再由主进程把 { allowed: boolean } 返回给 MCP Server,最终以 "allowed"/"denied" 字符串返回给 Agent。

关键实现细节(均可从 permission-api.ts 确认):

  • 请求 ID:filereq_<时间戳>_<随机串>,用于唯一标识待处理请求;
  • 操作校验:operation 必须是六个合法值之一,否则返回 400;
  • 任务绑定:请求必须关联当前活动任务(getActiveTaskId()),无活动任务时返回 400;
  • 超时保护:默认 5 分钟(PERMISSION_TIMEOUT_MS = 5 * 60 * 1000)未响应则返回 408 超时,allowed: false,保证 Agent 不会无限期挂起;
  • CORS:对本地请求开放 Access-Control-Allow-Origin: *。

MCP Server 的注册同样由 config-generator.ts 生成,并将 PERMISSION_API_PORT 注入其环境:

"file-permission": {
  "type": "local",
  "command": ["npx", "tsx", "<skills>/file-permission/src/index.ts"],
  "enabled": true,
  "environment": { "PERMISSION_API_PORT": "9226" },
  "timeout": 10000
}

共享类型 PermissionRequest(permission.ts)中定义了 filePaths?: string[] 字段,批量为 delete 操作提供了类型级支撑,UI 与主进程均基于该类型渲染与传递批量路径。

删除警告 UI:红色警示如何一步步加强

safe-file-deletion 技能不仅约束 Agent,还配套了专门的高危操作 UI。从 Execution.tsx 源码可确认以下渲染逻辑:

识别辅助函数(约第 79-90 行):

function isDeleteOperation(request: { type: string; fileOperation?: string }): boolean {
  return request.type === 'file' && request.fileOperation === 'delete';
}

function getDisplayFilePaths(request: { filePath?: string; filePaths?: string[] }): string[] {
  if (request.filePaths && request.filePaths.length > 0) {
    return request.filePaths;
  }
  if (request.filePath) {
    return [request.filePath];
  }
  return [];
}

警告呈现(约第 694-793 行):

  • 图标区:删除操作使用 AlertTriangle 图标,底色为 bg-red-500/10,图标为 text-red-600;
  • 标题:删除操作显示 "File Deletion Warning",文字红色加粗,普通文件操作仍为 "File Permission Required";
  • 警告横幅:多文件删除提示 N files will be permanently deleted:,单文件提示 This file will be permanently deleted:;
  • 路径列表:多文件以红色圆点列表逐条展示,单文件显示在红色描边框中,字体为等宽 font-mono;
  • 兜底文案:"This action cannot be undone."(此操作不可撤销);
  • 按钮语义:确认按钮在删除场景由 "Allow" 变为红色 "Delete"(多文件时为 "Delete All",样式 bg-red-600 hover:bg-red-700 text-white),拒绝按钮保持 "Deny"。

按钮测试锚点 permission-allow-button 与 permission-deny-button 同时保留,便于端到端测试定位(参见 Execution.tsx)。

禁止的绕过手段

技能最后用一节专门封堵常见的"规避"做法,原文要求如下:

绝不通过以下方式绕过删除警告:

  • 用清空文件内容代替删除(Emptying files instead of deleting);
  • 把文件移动到隐藏/临时目录(Moving to hidden/temp locations);
  • 使用晦涩冷门的命令(Using obscure commands)。

结尾强调:"用户会看到醒目的警告。请等待明确的批准。"(The user will see a prominent warning. Wait for explicit approval.)这一节的价值在于:LLM 在"完成任务"的压力下可能倾向于找捷径,技能把"等待批准"显式声明为不可协商的前置条件,从提示词层面杜绝了 Agent 自说自话。

如何验证与调试整条链路

仓库提供了实施与验证的完整线索:

  1. 类型检查:修改共享类型或 MCP 代码后执行 pnpm typecheck,确保 PermissionRequest.filePaths 等字段在消费端编译通过;
  2. 集成测试:config-generator.integration.test.ts 覆盖了 request_file_permission 相关配置生成逻辑,可验证 MCP Server 与系统提示词是否正确写入;
  3. 手动验证(对应 实施方案 第 9 步):运行 pnpm dev 启动桌面应用,让 Agent 删除一个文件,依次确认:
    • 红色警告横幅出现;
    • 文件路径显示在红色描边框中;
    • 出现 "This action cannot be undone" 提示;
    • 按钮由 "Allow" 变为红色 "Delete"(多文件为 "Delete All")。

该实施计划(2026-01-17-safe-file-deletion-impl.md)将整个功能拆解为 9 个可独立提交的任务:创建 SKILL.md、扩展共享类型、升级 MCP Server、更新 Permission API、新增 UI 辅助函数、改造删除图标与标题、增加警告横幅与文件列表、更新确认按钮、最终验证,每个任务都带类型检查与提交步骤,可作为理解模块耦合关系与复现实现的参考。

结语

safe-file-deletion 技能表面上是几十行 Markdown,背后却串联起 OpenCode Skill 约定、MCP 工具协议、Electron 主进程 HTTP 桥与 React 高危操作 UI 四条技术线。它证明了一个通用结论:在 Agent 自主执行文件操作的场景中,安全边界不能只靠模型自觉,而要靠"提示词规则 + 工具强制 + UI 人审"的闭环——规则负责约束行为,工具负责阻断执行,UI 负责把不可逆操作的后果以最高优先级呈现给用户。对于任何需要 Agent 操作宿主文件系统的桌面应用,这套"删前必问、批量合并、红色警示、不可绕过"的实践都值得直接复用。

登录后查看全文
MemOS