IronClaw Google Drive 扩展 delete_file 工具实战：永久删除文件与文件夹的完整调用契约与底层实现

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 的google-drive扩展以 WASM 沙箱工具的形式向 Agent 提供 12 个 Google Drive 操作能力其中google-drive.delete_file负责永久删除文件或文件夹不可恢复。本文以官方提示文档 delete_file.md 为核心骨架结合包内 schema、manifest 与 WASM 源码完整讲解该工具的调用契约、输入参数、底层 HTTP 实现、安全模型及与回收站操作trash_file的差异帮助你在编写提示词、扩展注册或二次开发时准确使用这一高危能力。一、工具定位12 个 Drive 工具中的最终处置操作google-drive是 IronClaw 中一个纯数据包data-only package没有独立 crate可移植工具半体以 WASM guest 形态交付详见 google-drive/README.md。其清单manifest声明了 12 个工具覆盖列表、读取、上传、更新、分享与整理全链路操作说明写操作google-drive.list_files搜索/列举文件支持 Drive 查询语法否google-drive.get_file读取文件元数据否google-drive.download_file下载文件内容含二进制文档文本抽取否google-drive.upload_file上传新文本文件是google-drive.update_file重命名/移动/加星/改描述是google-drive.create_folder创建文件夹是google-drive.delete_file永久删除文件或文件夹是google-drive.trash_file移入回收站可恢复是google-drive.share_file分享给用户是google-drive.list_permissions查看权限否google-drive.remove_permission撤销权限是google-drive.list_shared_drives列举共享云端硬盘否在 manifest.toml 中delete_file被声明为effects [network, use_secret, external_write]——它需要联网、消费 OAuth 密钥并且会对外部系统Google Drive产生写入副作用是权限矩阵中最敏感的一档。二、调用契约由 capability id 选择操作绝不携带 action 字段原提示文档的核心约束只有两条却非常关键Permanently delete a file or folder. The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.拆解如下宿主通过 capability id 选择操作Agent 调用时使用的是完整能力标识google-drive.delete_file。在 WASM guest 端action_from_context正是通过解析调用上下文中的capability_id来映射内部动作名见 lib.rs将google-drive.delete_file映射为delete_file其余 11 个能力 id 一一对应未识别的 id 直接返回unsupported_google_drive_capability输入错误。参数中不要包含action字段这是由params_with_action强制执行的见 lib.rsguest 会把从 context 得到的 action 名注入到请求参数 JSON 中若模型自行塞入action键则直接报invalid_parameters输入错误。因此模型侧只需要提交 schema 中声明的业务参数这里是file_idaction由宿主链路统一补全避免模型与宿主两处声明不一致。三、输入参数delete_file 的 JSON Schema 精解工具输入由 delete_file.input.v1.json 声明是一个极简的 JSON Schemadraft-07{ $schema: http://json-schema.org/draft-07/schema#, title: Google Drive delete_file, description: Permanently delete a file or folder., type: object, required: [file_id], properties: { file_id: { type: string, description: The file ID to delete. } }, additionalProperties: false }要点唯一必填参数file_idstring目标文件或文件夹的 ID即 Drive API 中files/{fileId}路径段的资源标识。它可以通过google-drive.list_files或google-drive.get_file的返回结果取得。additionalProperties: false除file_id外不接受任何额外字段配合上文禁止 action 字段的约定参数面被收敛到最小。在 serde 侧DeleteFile变体同样只声明file_id: String一个字段见 types.rs与 schema 严格对齐——这也是该包整体采用schemars::JsonSchema派生、让广告 schema 永不与 serde 契约漂移的设计动机。一个合法的模型调用参数示例{file_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms}四、底层实现WASM guest 如何执行永久删除delete_file的实现位于 api.rs/// Delete a file permanently. pub fn delete_file(file_id: str) - ResultDeleteResult, GuestFailure { let path format!(files/{}?supportsAllDrivestrue, url_encode(file_id)); api_call(DELETE, path, None)?; Ok(DeleteResult { file_id: file_id.to_string(), deleted: true, }) }调用链与关键细节HTTP 方法为DELETE目标为 Drive API v3https://www.googleapis.com/drive/v3/files/{file_id}?supportsAllDrivestrueAPI 基地址常量DRIVE_API_BASE https://www.googleapis.com/drive/v3见 api.rs。supportsAllDrivestrue查询参数保证对共享云端硬盘shared drive中的文件同样可操作与list_files等其余工具保持一致的跨盘能力。请求通过 WIT 定义的宿主能力host::http_request发出接口定义见 tool.witWASM guest 自身不直接持有网络套接字——HTTP 由宿主运行时代理执行。成功时返回DeleteResult { file_id: ..., deleted: true }结构体定义见 types.rs即已删除的确定性确认无文件内容回传。需要特别说明该删除是永久性的。与trash_file通过PATCH {trashed: true}移入回收站、可恢复不同delete_file调用 Drive 的files.delete接口删除后资源立即不可恢复若目标是文件夹则其中的全部内容一并被永久删除。五、安全与权限模型凭证注入、效果声明与来源门控delete_file的高危属性在 manifest 中有三重体现见 manifest.toml1. 效果声明与默认权限effects [network, use_secret, external_write]三项效果叠加标识联网 使用密钥 外部写入。default_permission ask默认情况下每次执行都需用户显式确认不会静默放行。visibility model该工具向模型可见可被 Agent 主动调用。2. 来源门控矩阵origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden }在 Agent 主循环loop_run中除非已被授权granted否则一律处于需门控状态在 product / automation 来源下则直接禁止。这意味着删除类操作被严格限制在经授权的对话循环内自动化工位无法触碰。3. 凭证注入与最小作用域该工具绑定的凭证 handle 为google_runtime_tokenvendor 为googleOAuth 作用域为https://www.googleapis.com/auth/drive完整读写而非只读 scope这是执行删除所必需的最小授权。凭证注入方式为injection { type header, name authorization, prefix Bearer }宿主在代发 HTTP 请求时把Authorization: Bearer token头注入到请求中WASM guest 全程看不到 OAuth token 本身tool.wit的安全模型明确声明Secrets are NEVER exposed to WASM。即便 guest 被攻破也拿不到凭据只能借助宿主的能力通道发起受限请求。六、错误处理401 与 API 状态码的映射所有 Drive API 调用统一经由api_call与api_status_error做错误归一化见 api.rsHTTP 401令牌失效/未授权映射为ErrorKind::AuthRequired稳定错误码google_api_error_status_401。此时宿主应触发重新授权流程。其他非 2xx 状态码映射为ErrorKind::Client错误码为api_status_{status}如 403、404、429错误消息被bounded_message截断到 512 字符内防止超大文本进入失败回传。网络层失败域名不在白名单、限流、超时、响应过大等由transport_failure按http-error-kind枚举逐类映射见 api.rs并在宿主出口统一做密钥形状的脱敏清洗。单元测试 api.rs 内 tests 模块 明确验证了 401 →AuthRequired、429 →Client且消息包含服务端错误正文的映射行为。七、使用建议与安全须知结合文档约束与源码实现实际使用该工具时应注意先确认后删除删除不可逆。建议先通过google-drive.get_file或list_files带trashed false查询确认目标file_id与name再发起删除必要时改走google-drive.trash_file保留恢复窗口。文件夹删除是级联的删除文件夹会连同其内部所有文件一并永久移除模型不应在未向用户说明后果的情况下删除非空文件夹。共享云端硬盘支持实现中始终携带supportsAllDrivestrue可删除用户有足够权限的共享盘文件权限不足时收到 403映射为api_status_403。不要手工构造action字段宿主会依据capability_id自动补全动作额外携带action只会触发invalid_parameters错误。依赖授权状态由于default_permission ask且origin_gate_matrix在 loop 场景默认 gated工具真正执行前通常需要用户批准401 时需先完成 Google OAuth 重新授权。八、如何验证与回归google-drive包的可移植半体是编译产物改动wasm-src/源码后必须重新构建 WASM 并保持产物新鲜构建./scripts/build-wasm-extensions.sh --first-partyguest crate 不在工作区构建图中属带外构建一致性校验python3 scripts/ci/check-wasm-artifact-freshness.py以scripts/ci/wasm-src-digests.toml中记录的源码树摘要为准源码改动但未重建会直接 CI 失败清单投影测试cargo test -p ironclaw_extension_registry验证 manifest 中 12 个工具的 schema 引用与声明一致性。结语google-drive.delete_file是 IronClaw 扩展体系中最小表面 强安全边界设计的一个典型样本模型侧只需提交一个file_id动作选择由 capability id 隐式完成底层 WASM guest 只负责构造DELETE files/{id}?supportsAllDrivestrue请求网络与凭证全部交由宿主代管。理解这一调用契约、输入 schema 与安全门控是安全、正确地让 Agent 具备永久删除 Google Drive 文件能力的前提。与之配套的回收站操作可参考 trash_file 提示文档形成可恢复处置 最终处置的完整数据治理闭环。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Drive 扩展让 Agent 安全地管理你的云端文件与文件夹IronClaw Google Drive 扩展让 Agent 安全地管理你的云端文件与文件夹 本篇技术指南围绕 IronClawAgent OS中的 G人工智能AI 应用交互助手AI AgentIronClaw google-slides 扩展 insert_image 能力详解幻灯片插图工具的调用约定与底层实现IronClaw google slides 扩展 insert_image 能力详解幻灯片插图工具的调用约定与底层实现 本篇文章聚焦 IronClaw Ag人工智能AI 应用交互助手AI Agentgulp 5 实战用 del 模块删除文件与文件夹构建前清理与管道内删除完整指南gulp 5 实战用 del 模块删除文件与文件夹构建前清理与管道内删除完整指南 本指南基于 gulp 官方 Recipes 中的 Delete file构建工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考