IronClaw 扩展开发实战：解读 Google Drive trash_file 能力（文件移到回收站）

IronClaw 扩展开发实战解读 Google Drive trash_file 能力文件移到回收站【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw导读本文以 IronClaw 开源仓库中 Google Drive 扩展包的trash_file操作文档为线索深入讲解一个 Agent 工具Tool从「输入 Schema → 能力清单 Manifest → WASM 实现 → 底层 HTTP 调用」的完整链路。读者将掌握google-drive.trash_file的调用约定、file_id参数规范、权限与门控配置以及它与delete_file永久删除的本质区别并可直接在 IronClaw 的 loop_run 场景中安全使用该能力管理 Google Drive 文件。操作定位把文件放进回收站而非永久删除关联文档 trash_file.md 对操作语义的描述极为精炼Move a file or folder to trash——将一个文件或文件夹移动到回收站。文档随后给出两条对 Agent 的硬性约束操作由宿主机根据 capability id 选择模型不需要、也不应该自行指定action字段宿主会根据google-drive.trash_file这个能力标识来分发只提供输入 Schema 描述的参数即只传file_id不得画蛇添足地携带多余字段。这意味着trash_file与同一扩展包中的 delete_file.mdPermanently delete a file or folder是两个语义不同、不可混用的操作操作语义底层实现可恢复性google-drive.trash_file移入回收站PATCH files/{id}携带{trashed: true}可恢复Google Drive 回收站google-drive.delete_file永久删除DELETE files/{id}不可恢复Agent 在整理用户文件时应优先选择trash_file而非delete_file这是文档语义与源码实现共同支持的结论。输入参数只认一个必填的 file_idtrash_file的输入约束定义在 trash_file.input.v1.jsonJSON Schema Draft-07{ $schema: http://json-schema.org/draft-07/schema#, title: Google Drive trash_file, description: Move a file or folder to trash., type: object, required: [file_id], properties: { file_id: { type: string, description: The file ID to trash. } }, additionalProperties: false }关键约束解析required: [file_id]file_id是唯一必填参数即 Google Drive 文件/文件夹的稳定标识URL 中open?id后的那串 ID可通过google-drive.list_files查询获得additionalProperties: false任何 schema 之外的字段都会被拒绝呼应了 prompt 文档中不要包含 action 字段的要求type: object整个请求体必须是 JSON 对象。从 types.rs 的源码结构看GoogleDriveAction::TrashFile变体与 Schema 严格对应/// Move a file to trash. TrashFile { /// The file ID to trash. file_id: String, },在 IronClaw 的扩展机制中Schema 与反序列化契约由schemars::JsonSchema自动同步生成见 lib.rs枚举的每个变体在oneOf中独占一个分支并声明各自的required数组因此模型在调用前就能看到file_id是必填项从根源上避免历史上模型缺参导致missing field file_id运行时错误的问题该动机记录在 types.rs 测试 中。能力注册Manifest 中的工具条目与安全门控google-drive.trash_file并不是零散存在的函数而是通过扩展清单 manifest.toml 向宿主声明的正式能力。其工具条目如下[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-drive.trash_file description Move a file or folder to trash. effects [network, use_secret, external_write] default_permission ask visibility model input_schema_ref schemas/google-drive/trash_file.input.v1.json prompt_doc_ref prompts/google-drive/trash_file.md [[tools.credentials]] handle google_runtime_token vendor google scopes [https://www.googleapis.com/auth/drive] audience { scheme https, host www.googleapis.com } injection { type header, name authorization, prefix Bearer }这份配置说明了 IronClaw 扩展安全模型的几个关键点effects [network, use_secret, external_write]该操作会发起网络请求、使用托管密钥并对 Google Drive 产生外部写入副作用三者缺一不可地列在效果声明中宿主据此做能力审计default_permission ask默认情况下每次调用都需要用户显式确认属于高风险写入操作的保守默认值origin_gate_matrixloop_run场景下为gated_unless_granted未授权则被门控拦截而在product与automation场景中直接被forbidden禁止——即该写操作目前只在 Agent 主循环loop_run中开放visibility model该工具对模型可见可被 Agent 自主选用凭证绑定google_runtime_token由宿主注入authorization: Bearer token请求头WASM 访客代码永远接触不到真实的 OAuth Token详见下文源码分析。在构建期这些 Manifest 与 Schema、Prompt 资产会被 gsuite.rs 通过include_str!/include_bytes!编译进ironclaw_extension_support包形成可嵌入的扩展资源清单包本身的定位在 google-drive 包 README 中有说明——这是一个data-only 包不包含 Rust crate可移植的工具半区以 WASM 访客形式交付。源码实现WASM 访客内的完整调用链trash_file的运行时代码位于 api.rs实现非常直观/// Move a file to trash. pub fn trash_file(file_id: str) - ResultDeleteResult, GuestFailure { let body r#{trashed: true}#; let path format!( files/{}?fields{}supportsAllDrivestrue, url_encode(file_id), FILE_FIELDS ); api_call(PATCH, path, Some(body))?; Ok(DeleteResult { file_id: file_id.to_string(), deleted: true, }) }底层原理拆解HTTP 方法选择Google Drive API v3 中移入回收站本质是元数据更新因此使用PATCH而非DELETE请求体只有一行{trashed: true}——这与delete_file使用DELETE files/{id}形成鲜明对比也是trash ≠ 永久删除的 API 层证据supportsAllDrivestrue显式声明该操作支持个人盘与共享盘Shared Drive中的文件这是 Drive API 对共享盘文件操作的必要参数fields参数请求完整的文件元数据字段集FILE_FIELDS常量在 api.rs 中定义包含id, name, mimeType, trashed, parents等 17 个字段虽然本操作不消费响应体但保持了与get_file一致的字段协议返回结构成功后返回DeleteResult { file_id, deleted: true }定义见 types.rsdeleted字段在此处表示已从正常列表中移除与永久删除共享同一结果类型。调用分发链路见 lib.rs宿主将能力标识google-drive.trash_file放入调用上下文ToolContextWASM 访客通过action_from_context将其映射为trash_file动作名params_with_action会把动作名写回参数 JSON但若调用方自己带了action字段则直接返回invalid_parameters错误——这正是 prompt 文档要求不要包含 action 字段的代码级强制最终由execute_inner匹配GoogleDriveAction::TrashFile { file_id }分支调用api::trash_file(file_id)。凭证与安全OAuth 令牌由宿主托管所有 Google Drive 工具的认证统一走 manifest.toml 中的[auth.google]配置[auth.google] method oauth2_code display_name Google account authorization_endpoint https://accounts.google.com/o/oauth2/v2/auth token_endpoint https://oauth2.googleapis.com/token pkce s256 scopes [https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/drive] extra_authorize_params { access_type offline, include_granted_scopes true, prompt consent } client_credentials { client_id_handle google_oauth_client_id, client_secret_handle google_oauth_client_secret }与trash_file直接相关的安全事实写操作需要完整drive权限trash_file绑定的凭证 scope 是https://www.googleapis.com/auth/drive完整读写而只读操作如list_files、get_file只申请drive.readonly子集——权限最小化原则体现在每个工具条目的凭证声明里OAuth 2.0 PKCES256授权码流程配合 PKCE 防拦截令牌由宿主注入api.rs 的模块注释明确写道所有 API 调用都经过宿主 HTTP 能力由它处理凭证注入与限流WASM 工具永远看不到真实的 OAuth 令牌OAuth 客户端凭据由部署管理员配置google_oauth_client_id/google_oauth_client_secret是扩展包级管理配置字段见 manifest 的[admin_configuration]由vendor.google组共享给 gmail 等其它 Google 扩展。错误处理可预期的失败码trash_file执行失败时通过结构化GuestFailure返回实现于 api.rs401 未授权映射为ErrorKind::AuthRequired固定错误码google_api_error_status_401——宿主可据此触发重新授权流程对应的单测见 api.rs 测试其它非 2xx 状态映射为ErrorKind::Client错误码形如api_status_{status}如限流时api_status_429并附带截断到 512 字符的响应体文本传输层失败由transport_failure按HttpErrorKind归类NetworkDenied、Executor、OperationFailed等参数非法由 serde 反序列化失败触发invalid_parameters。对 Agent 而言最值得关注的边界情况是目标文件已被移入回收站、file_id拼写错误、或对无权访问的共享盘文件操作——这些都会以api_status_404/api_status_403类错误码返回属于可向用户解释的常规失败而非系统故障。使用建议与注意事项优先回收站、慎用永久删除trash_file是 Google Drive 的软删除文件可从回收站恢复当模型不确定用户意图时应选择trash_file而非delete_filefile_id获取通过google-drive.list_files支持 Drive 查询语法如trashed false、name contains xxx或get_file获取稳定的文件 ID不要用文件名直接拼装共享盘支持supportsAllDrivestrue使该操作天然支持共享盘文件但前提是账号对该文件有写权限确认权限门控由于default_permission ask且loop_run场景为gated_unless_granted首次调用会触发用户确认/授权流程Agent 应在对话中主动说明将要执行的回收站操作凭证生命周期Google 处于 testing 发布状态的应用其 refresh token 在闲置 7 天后失效宿主认证引擎的 keepalive 清理会提前刷新闲置账号见 manifest 中keepalive_idle_seconds 604800的注释无需扩展作者干预。相关资源速览操作文档trash_file.md输入 Schematrash_file.input.v1.json能力清单manifest.tomlWASM 实现api.rs含trash_file、delete_file与错误处理单测、lib.rs、types.rs包嵌入逻辑gsuite.rs包说明与校验方式google-drive README构建产物新鲜度用python3 scripts/ci/check-wasm-artifact-freshness.py校验通过本文可以看到IronClaw 将一个看似简单的移入回收站操作通过 Schema 契约、能力清单门控、凭证托管和 WASM 隔离实现为既安全又可审计的 Agent 原生能力——这也是理解整个google-drive扩展包乃至全部 12 个工具list_files到list_shared_drives的通用方法论。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考