人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读google-drive.get_file是 IronClaw Agent OS 中 Google Drive 扩展包crates/extensions/packages/google-drive提供的一个只读工具用于按文件 ID 获取单个 Drive 文件/文件夹的元数据名称、类型、大小、所有者、共享状态、所在目录等而不下载其内容。本文以该工具的操作提示文档为核心骨架结合其输入 Schema、WASM 实现、扩展 Manifest 与契约测试完整剖析Agent 如何安全、规范地读取 Google Drive 文件元数据这条能力链路读完后你将掌握该工具的调用契约、底层 API 实现、凭据注入与错误处理机制以及它在整个扩展打包体系中的运作方式。一、get_file 的定位Google Drive 扩展包中的轻量元数据读取能力google-drive是一个data-only 扩展包无 Rust crate可移植工具半部分以 WASM guest 形式交付扩展 ID 为google-drive共暴露 12 个工具google-drive.list_files…google-drive.list_shared_drives外加[auth.google]认证面详见其 README.md。在这 12 个工具中get_file承担的是最基础的单文件元数据查询职责与周边工具形成明确分工工具职责google-drive.list_files按 Drive 查询语法搜索/列出文件定位目标file_idgoogle-drive.get_file按file_id读取单个文件的元数据本文主角google-drive.download_file下载文件内容为文本内部会先调用 get_file 获取元数据google-drive.update_file重命名、移动、加星、改描述移动时也会先调用 get_file从源码结构可以推断get_file是许多下游操作的前置依赖download_file在下载前需要先拿到mime_type判断是普通文件还是 Google Workspace 文件决定走altmedia下载还是/export导出见 api.rsupdate_file在移动文件时需要先读取当前parents才能构造removeParents参数。因此理解get_file是理解整个 Drive 扩展包读取链路的基础。二、操作提示文档面向模型的操作契约本文的关联文档位于 get_file.md全文如下Get file metadata.The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.这段看似简短的两句话实际上是 IronClaw 扩展体系中的模型可见操作契约包含三条关键约束能力语义该工具只做一件事——获取文件元数据Get file metadata.不包含内容下载或写入行为。操作选择由宿主完成The host selects this operation from the capability id——Agent 无需也不能自行声明要执行哪个操作宿主运行时根据能力 IDgoogle-drive.get_file确定具体动作。禁止携带 action 字段do not include an action field——模型只允许按 input schema 提供参数。2.1 宿主选择操作的源码印证这条契约在 WASM guest 的入口 lib.rs 中有严格实现action_from_context从调用上下文的capability_id解析动作名将google-drive.get_file映射为get_file其余 11 个能力 ID 同理映射未知 ID 返回unsupported_google_drive_capability错误params_with_action在把参数交给 serde 反序列化前先检查是否包含action字段——如果 Agent 违反 prompt 约束擅自传入action会被直接判定为invalid_parameters输入错误lib.rs中if obj.contains_key(action) { return Err(input_failure(invalid_parameters)); }。也就是说这条 prompt 不是建议性文案而是与 guest 代码硬性校验一一对应的契约动作由宿主注入模型越权声明动作即失败。2.2 prompt 文档在扩展包中的流转方式该 prompt 文档并非孤立的说明文件而是扩展资产的正式组成部分在 manifest.toml 中google-drive.get_file工具通过prompt_doc_ref prompts/google-drive/get_file.md引用它且visibility model表明其内容会暴露给模型打包时由 gsuite.rs 中的google_wasm_assets!宏通过include_bytes!将prompts/google-drive/get_file.md与同名 input schema、WASM 二进制一起嵌入包资产asset 路径为prompts/google-drive/get_file.md与同目录其他工具的 prompt 相比get_file的提示保持极简因为它没有可选参数、没有查询语法说明、没有下载/导出细节——只有一个必填的file_id全部语义由 schema 承载。对比 list_files.md附有 Drive 查询语法示例和 download_file.md说明二进制文档自动转文本可以看到 prompt 详略程度与工具参数复杂度是严格匹配的。三、输入契约JSON Schema 与 serde 的双重校验get_file的输入 Schema 位于 get_file.input.v1.json全文如下{ $schema: http://json-schema.org/draft-07/schema#, title: Google Drive get_file, description: Get file metadata., type: object, required: [file_id], properties: { file_id: { type: string, description: The file ID. } }, additionalProperties: false }要点唯一参数file_id字符串必填即 Drive 文件/文件夹的资源 ID形如1aB2cD3eF4gH5iJ6...的长字符串additionalProperties: false意味着不接受任何额外字段该工具没有任何可选参数——元数据读取不需要分页、查询或导出类型。3.1 与 serde 层的契约一致性输入参数在 guest 端由 types.rs 中的带标签枚举GoogleDriveAction约束#[serde(tag action, rename_all snake_case)] pub enum GoogleDriveAction { /// Get file metadata. GetFile { /// The file ID. file_id: String, }, // ...其余 11 个变体 }该类型同时派生JsonSchema由lib.rs的schema()方法在运行时生成对外公布的 schema每个枚举变体成为oneOf分支且各自的required数组独立确保广告给模型的 schema与serde 强制执行的解析契约永不漂移。types.rs的测试直接印证了这一设计动机get_file_requires_file_id_at_serde_layer{action:get_file}缺file_id必须在 serde 层被拒绝而{action:get_file,file_id:abc123}必须通过schema_marks_file_id_required_for_get_file生成的 schema 中get_file分支的required必须同时包含action与file_idschema_does_not_require_file_id_for_list_fileslist_files分支的required只能是[action]防止file_id在错误上下文中被误判为必填。测试注释中还记录了历史教训此前手写 schema 把所有变体字段都声明为顶层可选导致模型经常构造出缺file_id的畸形调用运行时才报missing field file_id改用 schemars 派生后模型在构造调用前就能看到字段是否必填。四、实现剖析WASM 中的 get_file 调用链get_file的完整执行链路为execute → execute_inner → action_from_context(capability_id) // google-drive.get_file → get_file → params_with_action(params, action) // 注入 action 字段、拒绝模型自带 action → serde 反序列化为 GoogleDriveAction::GetFile { file_id } → api::get_file(file_id) → 序列化 FileResult 返回核心实现在 api.rspub fn get_file(file_id: str) - ResultFileResult, GuestFailure { let path format!( files/{}?fields{}supportsAllDrivestrue, url_encode(file_id), FILE_FIELDS ); let response api_call(GET, path, None)?; let parsed: serde_json::Value serde_json::from_str(response).map_err(|e| serialization_failure(e))?; Ok(FileResult { file: parse_file(parsed) }) }4.1 请求构造细节请求目标GET https://www.googleapis.com/drive/v3/files/{file_id}supportsAllDrivestrue恒定携带即使文件位于共享云端硬盘Shared Drive也能正常访问fields参数精确裁剪响应只请求下面这组元数据字段常量FILE_FIELDSid, name, mimeType, description, size, createdTime, modifiedTime, webViewLink, parents, shared, starred, trashed, ownedByMe, driveId, owners(emailAddress, displayName)使用fields显式声明字段列表既减小响应体积也让返回值结构完全可控可预测。4.2 统一的 HTTP 封装所有 Drive API 调用都经过api_call封装api.rs它做三件事通过host::http_request发起请求——这是 IronClaw WASM 宿主提供的 HTTP 能力凭据注入与限流都由宿主完成WASM 工具本身永远看不到 OAuth tokenapi.rs文件头注释明确说明这一点非 2xx 状态码统一走api_status_error错误映射响应体按 UTF-8 解码解码失败映射为invalid_utf8_response执行错误。对模型而言get_file是一个无副作用、只读、单次请求的轻量操作不需要 Content-Type、没有请求体、没有 multipart 组装是所有 Drive 操作中最简单直接的一条路径。五、返回结构DriveFile 元数据模型逐字段解读get_file的返回值由FileResult { file: DriveFile }包装types.rsparse_file负责把 Drive API 响应 JSON 映射为结构化DriveFile。各字段及其含义如下字段类型说明idstring文件 IDnamestring文件名/文件夹名mime_typestringMIME 类型application/vnd.google-apps.folder表示文件夹is_folderbool由mime_type application/vnd.google-apps.folder推导方便模型快速判断descriptionstring?文件描述可为空sizestring?文件大小字符串形式Drive API 以字符串返回字节数created_time/modified_timestring?创建/修改时间RFC 3339web_view_linkstring?浏览器打开链接parentsstring[]父目录 ID 列表Drive 中一个文件可有多个父目录shared/starred/trashedbool是否共享、是否加星、是否在回收站owned_by_mebool是否本人所有drive_idstring?所属共享云端硬盘 ID个人盘为空ownersOwner[]所有者列表每项含emailAddress与displayNameparse_file对每个字段都做了容错缺失时对可选字段返回None对布尔字段回退为false对数组字段回退为空数组绝不因单字段缺失导致整个调用失败。输出侧还有配套的宽松 schema raw_output.v1.jsonadditionalProperties: true表示输出由 WASM 工具序列化、结构以实际返回为准。对 Agent 而言一次get_file调用即可回答诸如这个文件多大、谁拥有、在哪个目录、是否已共享/已加星/在回收站等问题作为是否值得download_file的决策依据。六、错误处理与失败语义get_file的失败路径经过精心设计见 api.rs6.1 HTTP 状态码映射401映射为ErrorKind::AuthRequired错误码固定为google_api_error_status_401——这是给宿主的可执行信号用于触发重新授权流程其他非 2xx 状态码映射为ErrorKind::Client错误码为api_status_{status}如api_status_404、api_status_429消息中附带服务名与响应正文无错误码兜底为google_api_transport_error。6.2 宿主传输层错误映射transport_failure将宿主 HTTP 能力的各类错误AuthRequired、Input、OutputTooLarge、Executor、NetworkDenied、Client、OperationFailed逐一映射为 guest 侧对应的ErrorKind保证错误分类在宿主与 guest 之间语义一致。6.3 消息长度边界所有自由文本错误消息都经过bounded_message截断到 512 字符以内——guest 永远不应向宿主交出无界字符串宿主侧后续还会再做二次截断与清洗避免恶意响应撑爆错误通道。对应的单元测试覆盖了这些语义api_status_error_401_maps_to_auth_required401 → AuthRequired 固定错误码、api_status_error_non_401_maps_to_client429 → Client api_status_429且消息包含rate limited。七、安全与权限模型只读、按需授权、凭据不可见get_file的安全设计可以从 manifest.toml 中完整读出[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-drive.get_file description Get file metadata. effects [network, use_secret] default_permission ask visibility model input_schema_ref schemas/google-drive/get_file.input.v1.json prompt_doc_ref prompts/google-drive/get_file.md [[tools.credentials]] handle google_runtime_token vendor google scopes [https://www.googleapis.com/auth/drive.readonly] audience { scheme https, host www.googleapis.com } injection { type header, name authorization, prefix Bearer }四个关键安全维度最小权限 OAuth 范围get_file只申请drive.readonly只读 scope写操作如upload_file、delete_file才用drive全量 scope与只读元数据的语义严格对应效果声明effects [network, use_secret]不含external_write——它在能力层面就被声明为无外部写入副作用默认询问default_permission ask模型每次调用该工具都需要用户按需授权origin_gate_matrix进一步限定只能在loop_run场景以未授权则门禁gated_unless_granted方式使用product与automation场景直接forbidden凭据不可见凭据句柄google_runtime_token由宿主以Authorization: Bearer token头注入injection { type header, name authorization, prefix Bearer }WASM guest 全程接触不到 OAuth token宿主 HTTP 能力同时负责限流。此外google是一个跨扩展共享的凭据权威vendorGmail、Docs、Sheets、Slides 与 Drive 共用同一个 OAuth 客户端注册表契约测试extensions_sharing_one_provider_project_the_same_auth_providermanifest_v2_contract.rs明确验证Gmail 与 Google Drive 是不同的扩展 ID但投影出的认证提供者都是google命名空间。[auth.google]段配置了 OAuth2 授权码流程authorization endpoint、token endpoint、PKCEs256、access_typeoffline换取刷新令牌并针对 Googletesting 发布状态的应用刷新令牌闲置 7 天过期的机制配置了keepalive_idle_seconds 604800的宿主保活刷新。部署侧管理员需要在[admin_configuration]中配置google_oauth_client_id与google_oauth_client_secret后者标记为secret true供所有 Google 系扩展共享使用。八、在扩展体系中的打包与投影google-drive包由ironclaw_extension_support::packages::gsuite模块负责嵌入与投影google_drive_bundle()gsuite.rs通过google_wasm_assets!宏一次性打包manifest.toml声明 12 个工具、认证面、管理员配置每个操作的schemas/google-drive/{operation}.input.v1.json每个操作的prompts/google-drive/{operation}.md含本文主角get_file.mdschemas/google-drive/raw_output.v1.json宽松输出 schemawasm/google_drive_tool.wasm编译产物guest 源码在wasm-src/WIT 世界为lanes/ironclaw_wasm/wit/tool.wasm中的sandboxed-tool。WASM 产物有专门的保鲜检查脚本scripts/ci/check-wasm-artifact-freshness.py保证提交的.wasm与wasm-src/源码一致manifest 投影则由cargo test -p ironclaw_extension_registry验证。模型最终通过注册表看到的能力形态是工具google-drive.get_file 认证面[auth.google]其中 prompt 文档与 input schema 成为模型可读的调用指南。九、典型使用链路在实际的 Agent 工作流中get_file通常出现在这样的链路中定位google-drive.list_files用查询如name contains 报告 and mimeType application/pdf and trashed false找到候选文件得到file_id甄别google-drive.get_file读取元数据判断大小、所有者、共享状态决定是否值得进一步处理读取google-drive.download_file下载内容为文本二进制文档自动转提取文本操作必要时再走update_file/share_file/trash_file等写操作这些操作需要用户按需授权。get_file因为是纯只读、单参数、无副作用的操作是模型在不确定某个文件是什么时最安全的探询手段——一次调用即可获得完整的元数据画像而不会触发任何外部写入。结语从 3 行 prompt 文档出发google-drive.get_file展示了 IronClaw 扩展体系的一贯设计哲学契约即代码、最小权限、凭据与决策分离。操作提示文档向模型声明只提供 schema 参数、不要带 actionguest 代码用capability_id解析 serde 严格反序列化把这条契约变成硬约束schema 由 schemars 从 Rust 类型自动派生杜绝手写漂移OAuth 凭据由宿主注入、scope 按工具粒度最小化、效果声明与门禁矩阵层层设防。理解这一个工具就理解了整个 Google Drive 扩展包乃至全部 WASM 工具包的运作范式。如果你想继续深入推荐按此顺序阅读仓库源码get_file.md 原文档 → input schema → types.rs → api.rs → lib.rs → manifest.toml → gsuite.rs 打包模块。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Sheets 扩展解析get_spreadsheet 元数据操作的设计与实现IronClaw Google Sheets 扩展解析get_spreadsheet 元数据操作的设计与实现 本篇文章聚焦 IronClaw 开源仓库中 Go人工智能AI 应用交互助手AI AgentIronClaw 扩展实战Google Slides get_presentation 工具解析与演示文稿元数据读取IronClaw 扩展实战Google Slides get_presentation 工具解析与演示文稿元数据读取 本篇技术指南聚焦 IronClaw 开源人工智能AI 应用交互助手AI AgentIronClaw Google Drive 扩展download_file 文件内容读取能力全解析IronClaw Google Drive 扩展download_file 文件内容读取能力全解析 导读 google drive.download_file人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考