MemOS 桌面端 Safe File Deletion 安全删除机制实现解析:SKILL.md 指令、MCP 批量授权与红色删除告警 UI

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

MemOS 桌面端 Safe File Deletion 安全删除机制实现解析:SKILL.md 指令、MCP 批量授权与红色删除告警 UI

导读

本文围绕 openwork-memos-integration 桌面应用中的 Safe File Deletion(安全文件删除) 功能展开,完整拆解其从 Agent 行为约束(OpenCode SKILL.md)、MCP 工具参数扩展(filePaths 批量删除)、Electron 主进程权限中转(Permission API)到 React 渲染层红色删除告警 UI 的端到端实现链路。读完本文,你将掌握如何在 AI Agent 桌面应用中为"删除文件"这一高风险操作构建"强制授权—批量合并—醒目告警—明确按钮"的四层防线,并可直接对照仓库源码验证每一个落地细节。


一、功能背景与整体架构

在 AI Agent 自动执行任务的场景中,文件删除是不可逆且代价最高的操作。Agent 一旦误删,用户没有撤销的机会。openwork-memos-integration 桌面应用(Electron + React + Tailwind CSS,运行 OpenCode 作为 Agent 运行时)通过一份实现计划(2026-01-17-safe-file-deletion-impl.md)落地了如下机制:

  1. Agent 侧约束:创建 OpenCode 技能 safe-file-deletion(SKILL.md),强制 Agent 在任何删除操作前调用 request_file_permission;
  2. 工具侧批量能力:扩展 file-permission MCP 服务器,支持 filePaths 数组,一次弹窗审批多个文件的删除;
  3. 主进程中转:Permission API 接收 MCP 请求、校验字段、生成请求 ID,并向渲染进程派发权限弹窗;
  4. UI 侧告警强化:删除操作在 Execution 页面获得红色专属样式——警告横幅、红色路径框、红色 "Delete/Delete All" 按钮与 "This action cannot be undone" 提示。

完整实现共 9 个任务、约 9 次增量提交,链路如下:

OpenCode Agent
   │  (调用 request_file_permission, 传入 filePath / filePaths)
   ▼
file-permission MCP Server (stdio)
   │  (HTTP POST localhost:9226/permission)
   ▼
Permission API (Electron 主进程)
   │  (校验 → 生成 filereq_* 请求ID → webContents.send('permission:request'))
   ▼
Execution.tsx 权限弹窗 (红色删除告警 UI)
   │  (用户点击 Delete / Deny)
   ▼
pendingPermissions Map 回调 → HTTP 200 { allowed } → Agent 继续/中止

二、Task 1:创建 Safe File Deletion 技能(Agent 侧行为约束)

2.1 技能文件结构与 Frontmatter

实现计划要求创建 apps/desktop/skills/safe-file-deletion/SKILL.md,该文件已在仓库中落地(SKILL.md)。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.
---

description 中的 "MUST be followed" 属于 OpenCode 技能约定的强约束措辞,确保该技能在 Agent 即将执行任何删除类操作时被自动激活。

2.2 强制流程规则

技能正文给出 Agent 删除文件前的五步硬性流程:

  1. 调用 request_file_permission 并传入 operation: "delete";
  2. 多文件场景使用 filePaths 数组,禁止多次调用(批量合并为一次审批);
  3. 等待用户响应;
  4. 仅在返回 "allowed" 时继续执行;
  5. 返回 "denied" 时必须确认并放弃删除。

2.3 适用范围

删除面覆盖所有可能移除磁盘文件的路径:

  • rm(单个/多个文件);
  • rm -rf(目录递归删除);
  • unlink、fs.rm、fs.rmdir;
  • 任何脚本或工具中隐含删除行为的操作。

2.4 两种授权请求示例

单文件删除:

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

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

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

2.5 No Workarounds 条款

技能明确禁止 Agent 以任何形式绕过删除审批,包括:清空文件内容代替删除、移动到隐藏/临时目录、使用冷门命令等变通手段。理由是"用户会看到一个显著警告,必须等待显式批准"——这条约定与 UI 层的红色告警形成呼应:界面越醒目,越不允许绕过。


三、Task 2:在共享类型中新增 filePaths 字段

3.1 PermissionRequest 接口扩展

共享类型位于 packages/shared/src/types/permission.ts,PermissionRequest 接口在 filePath 之后新增了 filePaths:

/** File path being operated on if type is 'file' */
filePath?: string;
/** Multiple file paths for batch operations (e.g., deleting multiple files) */
filePaths?: string[];

同文件中 FileOperation 联合类型定义了六种文件操作:'create' | 'delete' | 'rename' | 'move' | 'modify' | 'overwrite',删除即为其中之一。该共享包由桌面端主进程与渲染进程共同消费,字段新增后全仓 pnpm typecheck 通过即可(计划中明确"尚无消费者使用该字段,预期 PASS")。

源码提示:由于 PermissionRequest 同时承载 tool / question / file 三类请求(见 type: 'tool' | 'question' | 'file'),新增字段均为可选(?),不会破坏既有问题询问与工具授权流程。


四、Task 3:扩展 MCP Server 支持批量 filePaths

4.1 输入接口调整

file-permission MCP 服务器(apps/desktop/skills/file-permission/src/index.ts)将 filePath 从必选改为可选,并新增 filePaths:

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

4.2 inputSchema 与 required 变更

工具 request_file_permission 的 JSON Schema 增加 filePaths 数组属性(type: 'array',元素为字符串,描述为"批量操作的绝对路径数组,例如删除多个文件"),同时 required 从 ['operation', 'filePath'] 收窄为 ['operation']——filePath 与 filePaths 二选一即可。

4.3 参数解构与校验逻辑

CallToolRequestSchema 处理器中解构新增 filePaths,校验逻辑同步放宽:

const { operation, filePath, filePaths, targetPath, contentPreview } = args;

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

4.4 中转 HTTP 请求体

校验通过后,MCP 服务器通过 fetch 向 Electron 主进程的 http://localhost:${PERMISSION_API_PORT}/permission 发起 POST(端口由 PERMISSION_API_PORT 环境变量指定,默认 9226),请求体携带 operation、filePath、filePaths、targetPath 以及截断到 500 字符的 contentPreview。主进程最终返回 { allowed: boolean },MCP 将其映射为纯文本 "allowed" 或 "denied" 返回给 Agent——这正是技能规则中 Agent 等待的两个响应值。


五、Task 4:Permission API 主进程处理 filePaths

5.1 请求体类型与校验

Electron 主进程的权限服务(apps/desktop/src/main/permission-api.ts)在解析 JSON 请求体时加入 filePaths:

let data: {
  operation?: string;
  filePath?: string;
  filePaths?: string[];
  targetPath?: string;
  contentPreview?: string;
};

// Validate required fields
if (!data.operation || (!data.filePath && (!data.filePaths || data.filePaths.length === 0))) {
  res.writeHead(400, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ error: 'operation and either filePath or filePaths are required' }));
  return;
}

此外主进程还会校验 operation 是否属于六个合法值之一,未初始化(无主窗口或活动任务)时返回 503。

5.2 组装 PermissionRequest 并派发

通过校验后,主进程生成形如 filereq_<timestamp>_<random> 的请求 ID(generateRequestId()),组装 PermissionRequest 并通过 IPC 事件 permission:request 发送给渲染进程:

const permissionRequest: PermissionRequest = {
  id: requestId,
  taskId,
  type: 'file',
  fileOperation: data.operation as FileOperation,
  filePath: data.filePath,
  filePaths: data.filePaths,
  targetPath: data.targetPath,
  contentPreview: data.contentPreview?.substring(0, 500),
  createdAt: new Date().toISOString(),
};

mainWindow.webContents.send('permission:request', permissionRequest);

5.3 等待用户响应(超时与回调)

主进程将 { resolve, timeoutId } 存入 pendingPermissions Map,等待渲染进程调用 resolvePermission(requestId, allowed) 回填结果,默认超时 5 分钟(PERMISSION_TIMEOUT_MS = 5 * 60 * 1000),超时后返回 408 与 allowed: false(即默认拒绝)。isFilePermissionRequest 通过 filereq_ 前缀区分文件授权请求。

从源码可见:同一服务还承载了问题询问接口(POST /question,端口 9227,请求 ID 前缀 questionreq_),删除授权与问题询问共用 PermissionRequest 结构,互不干扰。


六、Task 5:UI 辅助函数——识别删除操作与展示路径

渲染进程在 apps/desktop/src/renderer/pages/Execution.tsx 中新增两个纯函数:

// Helper to check if this is a delete operation
function isDeleteOperation(request: { type: string; fileOperation?: string }): boolean {
  return request.type === 'file' && request.fileOperation === 'delete';
}

// Get file paths to display (handles both single and multiple)
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 [];
}
  • isDeleteOperation:仅当请求类型为 file 且 fileOperation === 'delete' 时返回 true,作为所有红色样式的判定开关;
  • getDisplayFilePaths:统一将单文件 filePath 与多文件 filePaths 归一化为字符串数组,供横幅与路径列表渲染复用,避免两套展示逻辑。

同时从 lucide-react 引入 AlertTriangle 图标,用于删除告警的视觉标识。


七、Task 6–8:红色删除告警 UI 的三处关键改造

7.1 图标与标题:普通文件请求 → 删除专属红色

权限弹窗中,isDeleteOperation(permissionRequest) 为真时:

  • 图标容器背景切换为 bg-red-500/10,图标改为 <AlertTriangle className="h-5 w-5 text-red-600" />(普通文件操作为琥珀色 File 图标);
  • 标题从 File Permission Required 切换为醒目的 File Deletion Warning,并着色 text-red-600。

7.2 警告横幅、红色路径列表与不可撤销提示

文件类授权 UI 部分按删除/非删除分流:

  • 删除警告横幅:bg-red-500/10 border border-red-500/20 红色半透明面板,文案根据路径数量动态生成——多文件显示 "{n} files will be permanently deleted:",单文件显示 "This file will be permanently deleted:";
  • 操作徽标:非删除操作保留原有 getOperationBadgeClasses 徽标(如 CREATE、MODIFY、MOVE、OVERWRITE、RENAME),删除操作不再显示徽标,改用横幅替代;
  • 路径展示:getDisplayFilePaths 返回多个路径时渲染为红色圆点列表(• path),单个路径则渲染为红色单行文本,容器统一为 bg-red-500/5 border border-red-500/20;targetPath(重命名/移动目标)仍以灰色箭头行展示;
  • 不可逆提示:删除操作下追加红色警示文案 This action cannot be undone.;
  • 内容预览(contentPreview)逻辑保持不变,继续以可折叠 <details> 展示。

7.3 操作按钮:Allow → 红色 Delete / Delete All

弹窗底部按钮区(含 data-testid="permission-allow-button")在删除场景下:

className={cn(
  "flex-1",
  isDeleteOperation(permissionRequest) && "bg-red-600 hover:bg-red-700 text-white"
)}

按钮文字按路径数量切换:

  • 多文件(getDisplayFilePaths(...).length > 1)→ Delete All;
  • 单文件 → Delete;
  • 其他操作保持 Allow;问题请求为 Submit。

拒绝按钮(permission-deny-button)在问题请求下显示 Cancel,其余保持 Deny。

7.4 测试验证

仓库集成测试 Execution.integration.test.tsx 中 "file permission dialog details" 分组覆盖了该改造:构造 type: 'file'、fileOperation: 'delete'、filePath: '/path/to/file.txt' 的权限请求后,断言页面渲染出 File Deletion Warning 标题与 Delete 按钮;相邻用例还验证了 rename/move 的目标路径、overwrite/modify 的徽标、以及 contentPreview 折叠预览等非删除路径的行为,确认删除告警与普通文件授权互不干扰。


八、Task 9:验证流程与增量提交节奏

计划将收尾验证分为四步(对应 package.json 中的脚本):

  1. pnpm typecheck(即 tsc --noEmit):全仓类型检查,预期 PASS;
  2. pnpm lint:预期 PASS 或仅存在存量警告;
  3. pnpm dev 手动验证(需开发环境):让 Agent 删除一个文件,逐一核对红色警告横幅、红色路径框、This action cannot be undone. 提示以及红色 Delete 按钮是否出现;
  4. 最终 git status 检查工作区,干净则跳过,否则 git add -A 后以 chore: final cleanup 提交。

每个 Task 独立提交、提交信息语义化(feat: add safe-file-deletion skill、feat(types): add filePaths ...、feat(file-permission): ...、feat(permission-api): ...、feat(ui): ...),整体"约 9 次提交、增量且可回滚"——这是该计划最重要的工程约束:高风险功能按任务粒度提交,任何一步出错都能精确定位并单独回退。


九、落地代码与设计要点总结

对照计划与仓库现状,全部 9 个任务均已落地,关键落点如下:

层级 落点文件 核心改动
Agent 技能 safe-file-deletion/SKILL.md 删除前强制调用授权工具、多文件用数组、禁止变通绕过
共享类型 packages/shared/src/types/permission.ts PermissionRequest 增加可选 filePaths: string[]
MCP 工具 apps/desktop/skills/file-permission/src/index.ts filePath 改为可选、required 仅保留 operation、透传 filePaths
主进程中转 apps/desktop/src/main/permission-api.ts 字段校验、filePaths 入 PermissionRequest、permission:request 派发
渲染层 UI apps/desktop/src/renderer/pages/Execution.tsx isDeleteOperation/getDisplayFilePaths、红色横幅/路径/按钮
集成测试 Execution.integration.test.tsx 断言 File Deletion Warning 与 Delete 按钮

这套方案的设计要点可归纳为四点:

  1. 约束在源头:用 OpenCode SKILL.md 把"删除前必须请示"固化为 Agent 的运行时规则,而非依赖开发者自觉;
  2. 批量合并审批:filePaths 数组避免逐文件弹窗轰炸,同时通过 UI 列出全部待删路径,让用户对删除范围一目了然;
  3. 视觉差异化:删除操作独享红色警告体系(图标、标题、横幅、路径框、按钮),与普通文件操作(琥珀色)、工具授权(警告色)、问题询问(主色)形成强区分;
  4. 默认安全:超时未响应按拒绝处理(allowed: false),保证"没有明确批准,就绝不删除"。

对于任何需要在桌面端授权 Agent 执行文件系统变更的 Electron + MCP 应用,这条"技能约束 → 工具参数 → 主进程中转 → UI 告警 → 测试验证"的实施链路都具备直接的借鉴价值。

登录后查看全文
MemOS