人工智能AI 應(yīng)用交互助手AI Agent【免費下載鏈接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility項目地址https://gitcode.com/gh_mirrors/iro/ironclaw點擊查看免費下載這篇技術(shù)指南以 IronClaw 開源倉庫中g(shù)oogle-drive擴展包的工具提示詞文檔 create_folder.md 為核心系統(tǒng)講解google-drive.create_folder這個創(chuàng)建文件夾能力在 Agent OS 中的完整運行機制它如何通過 Input Schema 聲明參數(shù)、如何在 manifest.toml 中登記為工具、提示詞文檔為什么要求不傳 action 字段以及 WASM 沙箱內(nèi)實際發(fā)起 Google Drive API 調(diào)用的源碼實現(xiàn)。讀完本文你將理解 IronClaw 的擴展工具從模型可見聲明到沙箱執(zhí)行的全鏈路設(shè)計并能據(jù)此排查與編寫同類工具的提示詞與 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搜索、讀取元數(shù)據(jù)、下載內(nèi)容否google-drive.upload_file/update_file上傳、更新文件是google-drive.create_folder創(chuàng)建文件夾是google-drive.delete_file/trash_file永久刪除 / 移入回收站是google-drive.share_file/list_permissions/remove_permission分享與權(quán)限管理是google-drive.list_shared_drives列出共享云端硬盤否create_folder是這套工具集中組織文件結(jié)構(gòu)的基礎(chǔ)能力常與list_files、upload_file組合使用——例如 Agent 先搜索到某個父文件夾的 id再在其中創(chuàng)建子文件夾最后上傳文件。二、提示詞文檔與 Input Schema一份工具契約的兩個側(cè)面create_folder的提示詞文檔全文只有兩句話但它是模型可見聲明層的一部分與 Input Schema 構(gòu)成一個完整的工具契約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.這兩句話傳達三個關(guān)鍵約束操作語義本工具只做一件事——創(chuàng)建一個文件夾folder而不是普通文件。區(qū)分二者的關(guān)鍵在于 Google Drive 的 MIME 類型application/vnd.google-apps.folder。能力由宿主選擇提示詞明確說明The host selects this operation from the capability id——即 Agent 不需要、也不應(yīng)該自行決定要執(zhí)行哪個操作宿主運行時會根據(jù)能力 idcapability id把請求路由到對應(yīng)操作。這一點在源碼層面有直接印證WASM 訪客的action_from_context函數(shù)從調(diào)用上下文的capability_id解析出內(nèi)部動作名見 lib.rsmatch context.capability_id.as_str() { ... google-drive.create_folder Ok(create_folder), ... }禁止攜帶 action 字段提示詞要求只提供 input schema 描述的參數(shù)不要包含 action 字段。這是因為action是內(nèi)部路由用的判別字段discriminator由宿主注入。如果 Agent 擅自傳入會被直接拒絕——params_with_action函數(shù)在params中發(fā)現(xiàn)action鍵會返回invalid_parameters錯誤見 lib.rs。與之配套的 Input Schema 定義在 create_folder.input.v1.json這是工具對模型公開的參數(shù)契約{ $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 }參數(shù)語義可歸納如下參數(shù)類型必填說明namestring是文件夾名稱最終作為 Google Drive 資源name字段parent_idstring | null否父文件夾 ID省略時創(chuàng)建在我的云端硬盤根目錄descriptionstring | null否文件夾描述映射為 Google Drive 資源description字段其他字段——additionalProperties: false傳入未聲明字段會被 Schema 拒絕注意parent_id與description聲明為可空類型[string, null]對應(yīng)源碼中serde(default)的OptionString處理見 types.rs。三、manifest.toml 中的工具聲明權(quán)限、效果與憑據(jù)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 }這份聲明揭示了幾個重要設(shè)計點input_schema_ref與prompt_doc_refinput_schema_ref指向上面分析的 JSON Schemaprompt_doc_ref指向本文核心的提示詞文檔。二者共同構(gòu)成工具對模型暴露的可見面。effects效果聲明create_folder聲明了network發(fā)起網(wǎng)絡(luò)請求、use_secret使用秘密憑據(jù)、external_write對外部系統(tǒng)產(chǎn)生寫副作用三類效果。對比只讀工具如list_files僅networkuse_secretexternal_write是寫操作工具的顯著標志也是沙箱策略與審計關(guān)注的對象。default_permission ask工具默認權(quán)限為詢問即每次調(diào)用前需要用戶確認或已授予的授權(quán)origin_gate_matrix還限定了來源門控——loop_run場景為gated_unless_granted未授權(quán)則被門控而product與automation場景直接forbidden禁止。visibility model工具對模型可見可被 Agent 主動調(diào)用。憑據(jù)作用域與只讀工具使用https://www.googleapis.com/auth/drive.readonly不同create_folder使用寫作用域https://www.googleapis.com/auth/drive。憑據(jù)由宿主在發(fā)送 HTTP 請求時以Authorization: Bearer token頭注入WASM 訪客程序永遠接觸不到 OAuth token 本身見下文第五節(jié)。此外整個包通過[auth.google]段聲明 OAuth 2.0 授權(quán)碼流程PKCEs256、offline訪問類型、promptconsent并復(fù)用google_oauth_client_id/google_oauth_client_secret兩個管理配置字段與 gmail 等其它 Google 擴展共享同一套 Google OAuth 憑據(jù)。測試模式應(yīng)用的 refresh token 有 7 天不活躍即失效的限制宿主 auth 引擎的 keepalive 機制會在keepalive_idle_seconds 604800內(nèi)提前刷新空閑賬號。四、WASM 訪客中的 create_folder 實現(xiàn)工具的實際執(zhí)行代碼位于 api.rs 的create_folder函數(shù)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) }) }實現(xiàn)要點固定 MIME 類型請求體固定寫入mimeType: application/vnd.google-apps.folder這是 Google Drive API 中文件夾資源的標識。調(diào)用方Agent無法通過參數(shù)覆蓋它從契約上保證了創(chuàng)建的一定是文件夾。父文件夾僅當傳入parent_id時才寫入parents數(shù)組不傳則默認在根目錄創(chuàng)建。parents是 Drive API 的數(shù)組字段這里以單元素數(shù)組形式指定唯一父級。描述字段description可選寫入。共享云端硬盤支持請求路徑固定攜帶supportsAllDrivestrue允許在共享團隊云端硬盤內(nèi)創(chuàng)建文件夾fields參數(shù)使用包級常量FILE_FIELDSid,name,mimeType,description,size,createdTime,...等 19 個標準字段確保響應(yīng)包含足夠的元數(shù)據(jù)。返回結(jié)構(gòu)成功時解析響應(yīng)為FileResult內(nèi)含完整的DriveFile含is_folder布爾標志由mimeType application/vnd.google-apps.folder推導(dǎo)而來見 types.rs 與 api.rs。在 lib.rs 中GoogleDriveAction::CreateFolder變體將解析后的參數(shù)透傳給上述實現(xiàn)并把結(jié)果序列化為 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))? }五、沙箱邊界憑據(jù)永不進入 WASMcreate_folder的一切網(wǎng)絡(luò)行為都經(jīng)由宿主提供的 HTTP 能力完成而不是在 WASM 內(nèi)直接發(fā)請求。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的執(zhí)行鏈路WASM 訪客調(diào)用host::http_request(POST, url, headers, body, None)見 api.rs 的api_call其中 headers 僅攜帶Content-Type: application/json宿主在沙箱出口處檢查目標端點是否在允許清單內(nèi)www.googleapis.com及其/drive/v3/*、/upload/drive/v3/*路徑模式并將 manifest 中登記的google_runtime_token以Authorization: Bearer token注入請求頭響應(yīng)在返回訪客前會掃描秘密泄漏訪客返回的結(jié)果與錯誤信息GuestFailure在宿主側(cè)還會被再次裁剪與校驗api.rs中的bounded_message將消息截斷至 512 字符HTTP 層錯誤被映射為結(jié)構(gòu)化錯誤401 映射為AuthRequired錯誤碼google_api_error_status_401其余狀態(tài)碼映射為Client類錯誤并攜帶api_status_{status}碼見 api.rs配套測試api_status_error_401_maps_to_auth_required驗證了這一映射。因此即使 WASM 訪客被攻破攻擊者也拿不到 Google 憑據(jù)只能按 manifest 聲明的端點和作用域行事。六、參數(shù)校驗的雙層保障create_folder的參數(shù)校驗存在兩層防線這是理解為什么 Agent 傳錯參數(shù)會收到明確錯誤的關(guān)鍵第一層運行時 serde 反序列化。訪客入口把params解析為GoogleDriveAction枚舉。該枚舉使用#[serde(tag action, rename_all snake_case)]標記見 types.rs每個變體有獨立的必填字段集合CreateFolder變體要求name必填parent_id、description可選。缺少name會觸發(fā) serde 報錯訪客返回invalid_parameters輸入錯誤。第二層Schema 契約一致性。訪客的schema()方法通過schemars::schema_for!(GoogleDriveAction)從枚舉自動生成 JSON Schema——也就是說模型看到的參數(shù)契約與 serde 反序列化契約由同一份 Rust 代碼推導(dǎo)而來杜絕了文檔說可選、代碼卻強制之類的漂移。types.rs 中的測試schema_marks_file_id_required_for_get_file、schema_does_not_require_file_id_for_list_files正是為此而設(shè)Schema 中每個oneOf分支的required數(shù)組必須與對應(yīng)變體的必填字段嚴格一致。對create_folder而言這意味著 Agent 看到的 Schema 中name在required數(shù)組內(nèi)而 serde 層同樣強制name存在——兩層校驗對齊調(diào)用失敗時模型能快速定位問題。七、實操從安裝到讓 Agent 創(chuàng)建文件夾結(jié)合 drive.md 與 oauth-setup.md完整的啟用流程如下。前置配置 Google OAuth一次性。在 Google Cloud Console 創(chuàng)建項目開啟Google Drive API創(chuàng)建Web application類型的 OAuth 客戶端并將回調(diào) URI 配置為你實例的網(wǎng)關(guān)路由https://your-host/api/reborn/product-auth/oauth/google/callbackGoogle 對 redirect URI 做精確匹配scheme、host、port、路徑必須完全一致不一致會在授權(quán)頁出現(xiàn)前報redirect_uri_mismatch。IronClaw 的產(chǎn)品授權(quán)流程在網(wǎng)關(guān) HTTP 路由上接收回調(diào)因此必須使用實例 URL且完成流程時實例必須可達。然后在 IronClaw 運行機器上寫入憑據(jù)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重啟服務(wù)生效ironclaw service restartNEAR AI 托管實例需在 Agent Dashboard 重啟。安裝并激活擴展ironclaw extension install google-drive ironclaw extension activate google-drive激活需要憑據(jù)的擴展會啟動其設(shè)置流程在 Web 界面Extensions中完成 Google OAuth 授權(quán)。注意即使已認證過其它 Google 擴展每個 Google 擴展仍需單獨認證。使用示例。配置完成后Agent 收到自然語言指令Create a folder called Project Assets inside my Work folder時會先通過list_files按名稱匹配mimeType application/vnd.google-apps.folder定位 Work 文件夾的 id然后發(fā)起create_folder調(diào)用其實際參數(shù)形如{ name: Project Assets, parent_id: 1AbCdEfGhIjKlMnOpQrStUvWxYz }如果不指定parent_id文件夾將創(chuàng)建在云端硬盤根目錄{ name: Project Assets }也可以同時附帶描述{ name: Project Assets, parent_id: 1AbCdEfGhIjKlMnOpQrStUvWxYz, description: Q3 campaign assets }由于default_permission ask首次調(diào)用需要用戶批準批準后同一 loop 運行內(nèi)的后續(xù)調(diào)用在門控策略下放行。響應(yīng)會返回新建文件夾的id、webViewLink等元數(shù)據(jù)Agent 可據(jù)此繼續(xù)在文件夾內(nèi)上傳文件或建立子目錄。如需在共享云端硬盤內(nèi)創(chuàng)建可通過list_shared_drives先定位團隊盤 id 再作為parent_id傳入源碼路徑已攜帶supportsAllDrivestrue。八、調(diào)試與驗證驗證 manifest 投影運行cargo test -p ironclaw_extension_registry驗證 manifest 能被正確解析與投影見 README.md。驗證 WASM 產(chǎn)物新鮮度修改wasm-src/后必須重新構(gòu)建并更新記錄運行python3 scripts/ci/check-wasm-artifact-freshness.py否則 CI 會失敗。構(gòu)建命令為./scripts/build-wasm-extensions.sh --first-partywasm-src/的訪客 crate 不在工作區(qū)構(gòu)建圖中。觀察日志訪客執(zhí)行時會通過host::log輸出調(diào)試日志如Drive API: POST files?...可在宿主側(cè)查看執(zhí)行軌跡。錯誤排查401 表示憑據(jù)失效或作用域不足檢查是否配置了寫作用域driveinvalid_parameters表示參數(shù)不符合 Schema最常見的是缺少name或誤傳了action字段api_status_*類錯誤可在響應(yīng)體中看到 Google API 的原始錯誤信息。九、小結(jié)google-drive.create_folder是理解 IronClaw 擴展工具契約的一個極佳樣例提示詞文檔 Input Schema 構(gòu)成模型可見的契約面manifest 聲明權(quán)限、效果與憑據(jù)作用域WASM 訪客按 capability id 路由并在宿主的 HTTP 能力與憑據(jù)注入保護下執(zhí)行真實 API 調(diào)用雙層參數(shù)校驗確保契約一致。這條從聲明到執(zhí)行的鏈路適用于google-drive包內(nèi)其余 11 個工具upload_file、update_file、share_file等同為寫操作僅憑據(jù)作用域與效果聲明不同也可作為編寫其它>贊分享人工智能AI 應(yīng)用交互助手AI Agent【免費下載鏈接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility項目地址https://gitcode.com/gh_mirrors/iro/ironclaw點擊查看免費下載相關(guān)推薦IronClaw Google Docs 擴展的 create_document 能力輸入契約、行為規(guī)則與 WASM 實現(xiàn)剖析IronClaw Google Docs 擴展的 create_document 能力輸入契約、行為規(guī)則與 WASM 實現(xiàn)剖析 本篇技術(shù)指南圍繞 IronCl人工智能AI 應(yīng)用交互助手AI AgentIronClaw 擴展體系中的 Google Docs read_content 能力純文本正文讀取的協(xié)議、權(quán)限與 WASM 實現(xiàn)IronClaw 擴展體系中的 Google Docs read_content 能力純文本正文讀取的協(xié)議、權(quán)限與 WASM 實現(xiàn) 導(dǎo)讀 google doc人工智能AI 應(yīng)用交互助手AI AgentIronClaw google-docs 擴展完全指南語義化文檔工作流與 WASM 工具實現(xiàn)解析IronClaw google docs 擴展完全指南語義化文檔工作流與 WASM 工具實現(xiàn)解析 本文以 IronClaw 開源倉庫中 google docs人工智能AI 應(yīng)用交互助手AI Agent創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考