人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载这篇技术指南以 IronClaw 开源仓库中google-drive扩展包的工具提示词文档 create_folder.md 为核心系统讲解google-drive.create_folder这个创建文件夹能力在 Agent OS 中的完整运行机制它如何通过 Input Schema 声明参数、如何在 manifest.toml 中登记为工具、提示词文档为什么要求不传 action 字段以及 WASM 沙箱内实际发起 Google Drive API 调用的源码实现。读完本文你将理解 IronClaw 的扩展工具从模型可见声明到沙箱执行的全链路设计并能据此排查与编写同类工具的提示词与 Schema。一、create_folder 在 Google Drive 扩展中的定位google-drive是一个data-only 包无独立 crate工具代码编译为 WASM 访客程序扩展 id 为google-drive提供 12 个工具覆盖搜索、读取、上传、分享、组织文件与文件夹等能力详见其 README.md工具 id作用写操作google-drive.list_files/get_file/download_file搜索、读取元数据、下载内容否google-drive.upload_file/update_file上传、更新文件是google-drive.create_folder创建文件夹是google-drive.delete_file/trash_file永久删除 / 移入回收站是google-drive.share_file/list_permissions/remove_permission分享与权限管理是google-drive.list_shared_drives列出共享云端硬盘否create_folder是这套工具集中组织文件结构的基础能力常与list_files、upload_file组合使用——例如 Agent 先搜索到某个父文件夹的 id再在其中创建子文件夹最后上传文件。二、提示词文档与 Input Schema一份工具契约的两个侧面create_folder的提示词文档全文只有两句话但它是模型可见声明层的一部分与 Input Schema 构成一个完整的工具契约Create a 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.这两句话传达三个关键约束操作语义本工具只做一件事——创建一个文件夹folder而不是普通文件。区分二者的关键在于 Google Drive 的 MIME 类型application/vnd.google-apps.folder。能力由宿主选择提示词明确说明The host selects this operation from the capability id——即 Agent 不需要、也不应该自行决定要执行哪个操作宿主运行时会根据能力 idcapability id把请求路由到对应操作。这一点在源码层面有直接印证WASM 访客的action_from_context函数从调用上下文的capability_id解析出内部动作名见 lib.rsmatch context.capability_id.as_str() { ... google-drive.create_folder Ok(create_folder), ... }禁止携带 action 字段提示词要求只提供 input schema 描述的参数不要包含 action 字段。这是因为action是内部路由用的判别字段discriminator由宿主注入。如果 Agent 擅自传入会被直接拒绝——params_with_action函数在params中发现action键会返回invalid_parameters错误见 lib.rs。与之配套的 Input Schema 定义在 create_folder.input.v1.json这是工具对模型公开的参数契约{ $schema: http://json-schema.org/draft-07/schema#, title: Google Drive create_folder, description: Create a folder., type: object, required: [name], properties: { name: { type: string, description: Folder name. }, parent_id: { type: [string, null], description: Parent folder ID. }, description: { type: [string, null], description: Folder description. } }, additionalProperties: false }参数语义可归纳如下参数类型必填说明namestring是文件夹名称最终作为 Google Drive 资源name字段parent_idstring | null否父文件夹 ID省略时创建在我的云端硬盘根目录descriptionstring | null否文件夹描述映射为 Google Drive 资源description字段其他字段——additionalProperties: false传入未声明字段会被 Schema 拒绝注意parent_id与description声明为可空类型[string, null]对应源码中serde(default)的OptionString处理见 types.rs。三、manifest.toml 中的工具声明权限、效果与凭据google-drive.create_folder在 manifest.toml 中被声明为一个独立工具条目这是工具在注册表中可安装、可枚举的根源[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-drive.create_folder description Create a folder. effects [network, use_secret, external_write] default_permission ask visibility model input_schema_ref schemas/google-drive/create_folder.input.v1.json prompt_doc_ref prompts/google-drive/create_folder.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 }这份声明揭示了几个重要设计点input_schema_ref与prompt_doc_refinput_schema_ref指向上面分析的 JSON Schemaprompt_doc_ref指向本文核心的提示词文档。二者共同构成工具对模型暴露的可见面。effects效果声明create_folder声明了network发起网络请求、use_secret使用秘密凭据、external_write对外部系统产生写副作用三类效果。对比只读工具如list_files仅networkuse_secretexternal_write是写操作工具的显著标志也是沙箱策略与审计关注的对象。default_permission ask工具默认权限为询问即每次调用前需要用户确认或已授予的授权origin_gate_matrix还限定了来源门控——loop_run场景为gated_unless_granted未授权则被门控而product与automation场景直接forbidden禁止。visibility model工具对模型可见可被 Agent 主动调用。凭据作用域与只读工具使用https://www.googleapis.com/auth/drive.readonly不同create_folder使用写作用域https://www.googleapis.com/auth/drive。凭据由宿主在发送 HTTP 请求时以Authorization: Bearer token头注入WASM 访客程序永远接触不到 OAuth token 本身见下文第五节。此外整个包通过[auth.google]段声明 OAuth 2.0 授权码流程PKCEs256、offline访问类型、promptconsent并复用google_oauth_client_id/google_oauth_client_secret两个管理配置字段与 gmail 等其它 Google 扩展共享同一套 Google OAuth 凭据。测试模式应用的 refresh token 有 7 天不活跃即失效的限制宿主 auth 引擎的 keepalive 机制会在keepalive_idle_seconds 604800内提前刷新空闲账号。四、WASM 访客中的 create_folder 实现工具的实际执行代码位于 api.rs 的create_folder函数pub fn create_folder( name: str, parent_id: Optionstr, description: Optionstr, ) - ResultFileResult, GuestFailure { let mut metadata serde_json::json!({ name: name, mimeType: application/vnd.google-apps.folder, }); if let Some(pid) parent_id { metadata[parents] serde_json::json!([pid]); } if let Some(desc) description { metadata[description] serde_json::Value::String(desc.to_string()); } let body serde_json::to_string(metadata).map_err(|e| serialization_failure(e))?; let path format!(files?fields{}supportsAllDrivestrue, FILE_FIELDS); let response api_call(POST, path, Some(body))?; let parsed: serde_json::Value serde_json::from_str(response).map_err(|e| serialization_failure(e))?; Ok(FileResult { file: parse_file(parsed) }) }实现要点固定 MIME 类型请求体固定写入mimeType: application/vnd.google-apps.folder这是 Google Drive API 中文件夹资源的标识。调用方Agent无法通过参数覆盖它从契约上保证了创建的一定是文件夹。父文件夹仅当传入parent_id时才写入parents数组不传则默认在根目录创建。parents是 Drive API 的数组字段这里以单元素数组形式指定唯一父级。描述字段description可选写入。共享云端硬盘支持请求路径固定携带supportsAllDrivestrue允许在共享团队云端硬盘内创建文件夹fields参数使用包级常量FILE_FIELDSid,name,mimeType,description,size,createdTime,...等 19 个标准字段确保响应包含足够的元数据。返回结构成功时解析响应为FileResult内含完整的DriveFile含is_folder布尔标志由mimeType application/vnd.google-apps.folder推导而来见 types.rs 与 api.rs。在 lib.rs 中GoogleDriveAction::CreateFolder变体将解析后的参数透传给上述实现并把结果序列化为 JSON 字符串返回GoogleDriveAction::CreateFolder { name, parent_id, description } { let result api::create_folder(name, parent_id.as_deref(), description.as_deref())?; serde_json::to_string(result).map_err(|e| api::serialization_failure(e))? }五、沙箱边界凭据永不进入 WASMcreate_folder的一切网络行为都经由宿主提供的 HTTP 能力完成而不是在 WASM 内直接发请求。WIT 接口定义于 tool.wit其安全模型在文件头明确声明WASM tools are untrusted and run in a sandboxAll capabilities are opt-in (default: no access)Secrets are NEVER exposed to WASM; credentials are injected at host boundaryAll outputs are scanned for secret leakage before returning to WASM具体到create_folder的执行链路WASM 访客调用host::http_request(POST, url, headers, body, None)见 api.rs 的api_call其中 headers 仅携带Content-Type: application/json宿主在沙箱出口处检查目标端点是否在允许清单内www.googleapis.com及其/drive/v3/*、/upload/drive/v3/*路径模式并将 manifest 中登记的google_runtime_token以Authorization: Bearer token注入请求头响应在返回访客前会扫描秘密泄漏访客返回的结果与错误信息GuestFailure在宿主侧还会被再次裁剪与校验api.rs中的bounded_message将消息截断至 512 字符HTTP 层错误被映射为结构化错误401 映射为AuthRequired错误码google_api_error_status_401其余状态码映射为Client类错误并携带api_status_{status}码见 api.rs配套测试api_status_error_401_maps_to_auth_required验证了这一映射。因此即使 WASM 访客被攻破攻击者也拿不到 Google 凭据只能按 manifest 声明的端点和作用域行事。六、参数校验的双层保障create_folder的参数校验存在两层防线这是理解为什么 Agent 传错参数会收到明确错误的关键第一层运行时 serde 反序列化。访客入口把params解析为GoogleDriveAction枚举。该枚举使用#[serde(tag action, rename_all snake_case)]标记见 types.rs每个变体有独立的必填字段集合CreateFolder变体要求name必填parent_id、description可选。缺少name会触发 serde 报错访客返回invalid_parameters输入错误。第二层Schema 契约一致性。访客的schema()方法通过schemars::schema_for!(GoogleDriveAction)从枚举自动生成 JSON Schema——也就是说模型看到的参数契约与 serde 反序列化契约由同一份 Rust 代码推导而来杜绝了文档说可选、代码却强制之类的漂移。types.rs 中的测试schema_marks_file_id_required_for_get_file、schema_does_not_require_file_id_for_list_files正是为此而设Schema 中每个oneOf分支的required数组必须与对应变体的必填字段严格一致。对create_folder而言这意味着 Agent 看到的 Schema 中name在required数组内而 serde 层同样强制name存在——两层校验对齐调用失败时模型能快速定位问题。七、实操从安装到让 Agent 创建文件夹结合 drive.md 与 oauth-setup.md完整的启用流程如下。前置配置 Google OAuth一次性。在 Google Cloud Console 创建项目开启Google Drive API创建Web application类型的 OAuth 客户端并将回调 URI 配置为你实例的网关路由https://your-host/api/reborn/product-auth/oauth/google/callbackGoogle 对 redirect URI 做精确匹配scheme、host、port、路径必须完全一致不一致会在授权页出现前报redirect_uri_mismatch。IronClaw 的产品授权流程在网关 HTTP 路由上接收回调因此必须使用实例 URL且完成流程时实例必须可达。然后在 IronClaw 运行机器上写入凭据client_secret会隐藏输入不落入 shell 历史ironclaw config set google.client_id your-client-id ironclaw config set google.redirect_uri https://your-instance-host/api/reborn/product-auth/oauth/google/callback ironclaw config set google.client_secret重启服务生效ironclaw service restartNEAR AI 托管实例需在 Agent Dashboard 重启。安装并激活扩展ironclaw extension install google-drive ironclaw extension activate google-drive激活需要凭据的扩展会启动其设置流程在 Web 界面Extensions中完成 Google OAuth 授权。注意即使已认证过其它 Google 扩展每个 Google 扩展仍需单独认证。使用示例。配置完成后Agent 收到自然语言指令Create a folder called Project Assets inside my Work folder时会先通过list_files按名称匹配mimeType application/vnd.google-apps.folder定位 Work 文件夹的 id然后发起create_folder调用其实际参数形如{ name: Project Assets, parent_id: 1AbCdEfGhIjKlMnOpQrStUvWxYz }如果不指定parent_id文件夹将创建在云端硬盘根目录{ name: Project Assets }也可以同时附带描述{ name: Project Assets, parent_id: 1AbCdEfGhIjKlMnOpQrStUvWxYz, description: Q3 campaign assets }由于default_permission ask首次调用需要用户批准批准后同一 loop 运行内的后续调用在门控策略下放行。响应会返回新建文件夹的id、webViewLink等元数据Agent 可据此继续在文件夹内上传文件或建立子目录。如需在共享云端硬盘内创建可通过list_shared_drives先定位团队盘 id 再作为parent_id传入源码路径已携带supportsAllDrivestrue。八、调试与验证验证 manifest 投影运行cargo test -p ironclaw_extension_registry验证 manifest 能被正确解析与投影见 README.md。验证 WASM 产物新鲜度修改wasm-src/后必须重新构建并更新记录运行python3 scripts/ci/check-wasm-artifact-freshness.py否则 CI 会失败。构建命令为./scripts/build-wasm-extensions.sh --first-partywasm-src/的访客 crate 不在工作区构建图中。观察日志访客执行时会通过host::log输出调试日志如Drive API: POST files?...可在宿主侧查看执行轨迹。错误排查401 表示凭据失效或作用域不足检查是否配置了写作用域driveinvalid_parameters表示参数不符合 Schema最常见的是缺少name或误传了action字段api_status_*类错误可在响应体中看到 Google API 的原始错误信息。九、小结google-drive.create_folder是理解 IronClaw 扩展工具契约的一个极佳样例提示词文档 Input Schema 构成模型可见的契约面manifest 声明权限、效果与凭据作用域WASM 访客按 capability id 路由并在宿主的 HTTP 能力与凭据注入保护下执行真实 API 调用双层参数校验确保契约一致。这条从声明到执行的链路适用于google-drive包内其余 11 个工具upload_file、update_file、share_file等同为写操作仅凭据作用域与效果声明不同也可作为编写其它>赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Docs 扩展的 create_document 能力输入契约、行为规则与 WASM 实现剖析IronClaw Google Docs 扩展的 create_document 能力输入契约、行为规则与 WASM 实现剖析 本篇技术指南围绕 IronCl人工智能AI 应用交互助手AI AgentIronClaw 扩展体系中的 Google Docs read_content 能力纯文本正文读取的协议、权限与 WASM 实现IronClaw 扩展体系中的 Google Docs read_content 能力纯文本正文读取的协议、权限与 WASM 实现 导读 google doc人工智能AI 应用交互助手AI AgentIronClaw google-docs 扩展完全指南语义化文档工作流与 WASM 工具实现解析IronClaw google docs 扩展完全指南语义化文档工作流与 WASM 工具实现解析 本文以 IronClaw 开源仓库中 google docs人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考