IronClaw Google Drive 扩展能力解析：`list_shared_drives` 共享云端硬盘列举工具

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文围绕 IronClaw 开源仓库中google-drive扩展包crates/extensions/packages/google-drive的list_shared_drives列举共享云端硬盘工具展开从其模型提示文档prompt doc、输入 JSON Schema、WASM 沙箱实现到扩展清单manifest逐层剖析。读者读完可以掌握该工具如何被宿主运行时选中并触发、page_size参数的行为与默认值、底层调用的 Google Drive v3 API 路径与返回结构以及它和list_files的corporadrive/drive_id参数如何协同从而让 Agent 在共享盘与个人盘之间自由检索文件。文中所有结论均可对照仓库源码与配置文件验证。一、关联文档定位一份面向模型的工具使用说明list_shared_drives的核心文档位于 prompts/google-drive/list_shared_drives.md全文很短但信息密度明确List shared drives.The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.这段文字不是给人读的普通说明而是注入给 LLM 的工具契约它传达了三条关键约定操作由宿主根据 capability id 选择Agent 无需也不能自行声明要执行哪个操作宿主host runtime会依据能力标识符如google-drive.list_shared_drives把请求路由到对应的 WASM 函数只按输入 schema 提供参数list_shared_drives的全部入参只有一个可选字段page_sizeAgent 只需按 schema 给出合法参数禁止携带action字段这与实现细节有关——见下文宿主注入 action一节。该 prompt 文档通过 manifest 中的prompt_doc_ref字段与工具绑定见 manifest.toml 中google-drive.list_shared_drives的prompt_doc_ref prompts/google-drive/list_shared_drives.md。二、输入参数JSON Schema 与page_size默认值与 prompt 文档配套的输入模式定义在 schemas/google-drive/list_shared_drives.input.v1.json{ $schema: http://json-schema.org/draft-07/schema#, title: Google Drive list_shared_drives, description: List shared drives., type: object, required: [], properties: { page_size: { type: integer, description: Maximum number of results. Defaults to 25. } }, additionalProperties: false }要点required为空数组说明该操作可以零参数调用直接返回用户有权限访问的共享盘列表唯一可选参数page_size为整数用于限制单次返回条数默认 25additionalProperties: false意味着传入 schema 之外的字段会被拒绝——这与 prompt 文档只提供 schema 描述的参数的要求互为印证。page_size的默认值在 Rust 侧也有对应实现。见 wasm-src/src/types.rs 中ListSharedDrives变体/// List shared drives the user has access to. ListSharedDrives { /// Maximum results (default: 25). #[serde(default default_page_size)] page_size: u32, },其中default_page_size()返回25同文件第 161-163 行。即Agent 不传page_size时serde 反序列化会自动填入 25再传给底层 API。三、底层实现GET https://www.googleapis.com/drive/v3/driveslist_shared_drives的 WASM 实现位于 wasm-src/src/api.rs/// List shared drives. pub fn list_shared_drives(page_size: u32) - ResultListSharedDrivesResult, GuestFailure { let path format!(drives?pageSize{}, page_size); let response api_call(GET, path, None)?; let parsed: serde_json::Value serde_json::from_str(response).map_err(|e| serialization_failure(e))?; let drives parsed[drives] .as_array() .map(|arr| { arr.iter() .map(|d| SharedDrive { id: d[id].as_str().unwrap_or().to_string(), name: d[name].as_str().unwrap_or().to_string(), }) .collect() }) .unwrap_or_default(); Ok(ListSharedDrivesResult { drives }) }结合同文件开头的常量定义可以还原完整调用链const DRIVE_API_BASE: str https://www.googleapis.com/drive/v3;即实际请求为GET https://www.googleapis.com/drive/v3/drives?pageSizeN走的是 Google Drive API v3 的drives.list端点。整个调用统一经由api_call见 api.rs拼接 URL、设置请求头无 body 时传{}通过宿主提供的host::http_request发起请求——WASM 工具自身不发网络请求全部委托给宿主的 HTTP capability对非 2xx 状态码统一映射为api_status_error401 映射为ErrorKind::AuthRequired且固定错误码google_api_error_status_401其余映射为ErrorKind::Client并携带api_status_{status}码响应体按 UTF-8 解码解码失败返回invalid_utf8_response。返回结构与结果类型成功响应中的drives数组会被解析为SharedDrive结构见 types.rs/// A shared drive. #[derive(Debug, Serialize)] pub struct SharedDrive { pub id: String, pub name: String, }每个共享盘只暴露两个字段id共享盘 ID后续可传给list_files的drive_id参数和name显示名称。最终结果包装为/// Result from list_shared_drives. #[derive(Debug, Serialize)] pub struct ListSharedDrivesResult { pub drives: VecSharedDrive, }四、宿主如何选中并执行该操作capability id 与 action 注入prompt 文档强调host selects this operation from the capability id其机制在 wasm-src/src/lib.rs 的action_from_context中体现fn action_from_context(context: Optionstr) - Resultstatic str, GuestFailure { let context context.ok_or_else(|| input_failure(missing_invocation_context))?; let context: ToolContext serde_json::from_str(context).map_err(|_| input_failure(invalid_invocation_context))?; match context.capability_id.as_str() { // ... google-drive.list_shared_drives Ok(list_shared_drives), _ Err(input_failure(unsupported_google_drive_capability)), } }执行流程对应execute_inner见 lib.rs宿主把capability_id如google-drive.list_shared_drives放在请求的context中传给 WASM 工具WASM 侧据此解析出内部 action 名list_shared_drivesparams_with_action再把action字段注入到参数 JSON 中若 Agent 已自行携带action字段则直接报invalid_parameters——这正是 prompt 文档要求do not include an action field的代码级原因见 lib.rsserde 按#[serde(tag action, rename_all snake_case)]标签将 JSON 反序列化为GoogleDriveAction::ListSharedDrives { page_size }分发到api::list_shared_drives(page_size)结果 JSON 序列化后经Response::Success返回。Schema 自描述schemars 保证契约不漂移GoogleDriveAction枚举派生自schemars::JsonSchema见 types.rs工具通过schema()方法把生成的 JSON Schema 暴露给模型见 lib.rs使每个 action 变体成为oneOf分支并携带各自的required数组。仓库中的单元测试验证了该契约get_file分支必须要求file_id而list_files分支只要求判别字段action见 types.rs 测试模块。同理ListSharedDrives分支对page_size不设required模型据此知道该参数可省略。五、扩展清单中的注册信息权限、凭据与运行约束manifest.toml 中google-drive.list_shared_drives的完整注册项如下[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-drive.list_shared_drives description List shared drives. effects [network, use_secret] default_permission ask visibility model input_schema_ref schemas/google-drive/list_shared_drives.input.v1.json prompt_doc_ref prompts/google-drive/list_shared_drives.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 }解读origin_gate_matrix该工具在loop_runAgent 主循环下默认未授予则需门禁审批gated_unless_granted在product/automation场景下被禁止——属于只读工具但仍受权限门禁约束effects声明network网络访问与use_secret使用凭据两类副作用供宿主做资源记账与策略判定default_permission ask默认情况下调用前需要用户确认授权凭据注入使用 Google 产品级凭据google_runtime_tokenscope 为drive.readonly只读与工具的只读语义匹配由宿主在 HTTP 出口以Authorization: Bearer token请求头注入——WASM 工具永远接触不到 OAuth token 明文auth.google扩展包同时声明了 OAuth2 授权端点https://accounts.google.com/o/oauth2/v2/auth与 token 端点启用 PKCEs256access_typeoffline以获取 refresh tokenauth.google.refresh中keepalive_idle_seconds 6048007 天用于对抗 Google 对 testing 发布状态下 refresh token 的 7 天不活动过期策略。六、与list_files协同从列举共享盘到检索共享盘内文件list_shared_drives的实战价值在于为list_files提供drive_id。在 wasm-src/src/api.rs 的list_files实现中请求固定携带supportsAllDrivestrue.to_string(), includeItemsFromAllDrivestrue.to_string(),并在指定drive_id时追加driveId{id}参数、把corpora设为drive。结合 types.rs 对corpora的注释典型的两段式调用模式为先调用list_shared_drives可省略page_size拿到共享盘id与name再以{action: list_files, corpora: drive, drive_id: 上一步拿到的 id, query: trashed false}在该共享盘内检索文件。此外list_shared_drives是包内 12 个工具之一google-drive.list_files到google-drive.list_shared_drives该包为data-only 包不包含 Rust crate工具本体以 WASM guest 形式交付提交产物在wasm/google_drive_tool.wasm源码在wasm-src/见 README.md。整个扩展由ironclaw_extension_support::packages::gsuite嵌入与 gmail 等google-*扩展共享 vendorgoogle作为凭据权威。七、安全模型与验证方式list_shared_drives运行在 WASM 沙箱中其安全边界由 tool.wit 定义能力最小化guest 只能通过host接口的http-request等少数入口与外界交互默认无任何访问权限凭据不出沙箱WIT 注释明确Secrets are NEVER exposed to WASM; credentials are injected at host boundarytoken 只在宿主出口注入错误分类闭环guest 通过guest-failure返回封闭的error-kind如auth-required、client宿主侧再映射为RuntimeDispatchErrorKind401 会映射为DispatchError::AuthRequired从而触发重新授权流程消息有界bounded_message将自由文本错误限制在 512 字符内见 api.rs防止无界字符串泄漏。仓库为api_status_error的行为提供了单元测试见 api.rs401 映射为AuthRequired且错误码为google_api_error_status_401429 等非 401 状态映射为Client并携带api_status_429码与原始响应摘要。扩展包的 manifest 投影由cargo test -p ironclaw_extension_registry校验WASM 产物新鲜度由python3 scripts/ci/check-wasm-artifact-freshness.py校验。八、使用要点小结维度结论关联文档prompts/google-drive/list_shared_drives.md宿主按 capability id 选操作只传 schema 参数禁止带action入参仅可选page_sizeinteger默认 25additionalProperties: false底层 APIGET https://www.googleapis.com/drive/v3/drives?pageSizeN返回结构ListSharedDrivesResult { drives: VecSharedDrive{id, name} }凭据 scopehttps://www.googleapis.com/auth/drive.readonly只读宿主注入Authorization: Bearer权限策略loop_run下gated_unless_granteddefault_permission ask典型用法先list_shared_drives拿drive_id再list_files配合corporadrivedrive_id检索共享盘文件安全边界WASM 沙箱 宿主 HTTP capability 出口凭据注入guest 不可见 token对 Agent 而言这条工具是进入组织共享盘世界的钥匙先列举出当前账号可访问的共享盘集合再借助list_files的共享盘检索能力深入其中查找、读取文档是文档检索类任务的标准起手式。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Drive 扩展download_file 文件内容读取能力全解析IronClaw Google Drive 扩展download_file 文件内容读取能力全解析 导读 google drive.download_file人工智能AI 应用交互助手AI AgentIronClaw Google Drive 扩展分享文件能力解析share_file 工具的输入契约、权限模型与 WASM 实现IronClaw Google Drive 扩展分享文件能力解析share_file 工具的输入契约、权限模型与 WASM 实现 本篇技术指南聚焦 IronC人工智能AI 应用交互助手AI AgentIronClaw google-drive 扩展12 个 Google Drive 工具包的清单、认证与 WASM 实现解析IronClaw google drive 扩展12 个 Google Drive 工具包的清单、认证与 WASM 实现解析 本指南围绕 IronClaw 的人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考