人工智能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能力展开它定义了一个“创建一个全新 Google Docs 文档”的模型可见工具并约束了 Agent 在创建文档时必须遵守的语义纪律不创建草稿探测索引、由宿主按 capability id 分发操作、不传 action 字段。读完本文你将掌握该能力的输入 Schema、行为规则背后的设计动机以及它从 WASM 访客到 Google Docs API 的完整调用链与鉴权模型。一、create_document 在 google-docs 扩展中的定位create_document是 IronClaw 的 google-docs 扩展包 中 15 个工具之一。该包是纯数据包data-only package不包含 crate可移植工具侧以 WASM guest 形态发布见 README.md。扩展 id 为google-docs运行时为wasm产物是提交在仓库中的wasm/google_docs_tool.wasm访客源码位于wasm-src/。它面向的语义能力集合包括创建类create_document创建全新文档读取/检查类get_document、read_content、inspect_document编辑类insert_text、delete_content、replace_text、apply_text_edits格式化类format_text、format_paragraph、create_list、create_table_with_data、insert_table底层透传类batch_update校验类verify_document官方提示语明确建议普通文档工作流应优先走“语义化”路径——inspect_document做结构化检查、apply_text_edits/create_table_with_data做批量编辑、verify_document做结果校验整套流程通常只需 34 次模型可见调用索引发现、批量单元格写入、并发检查和 provider 回读都由扩展内部处理README.md。create_document正是这个工作流的起点。二、输入契约一个极简而严格的 JSON Schemacreate_document的输入由 create_document.input.v1.json 描述完整内容如下{ $schema: http://json-schema.org/draft-07/schema#, title: Google Docs create_document, description: Create a new Google Docs document., type: object, required: [title], properties: { title: { type: string, description: Document title. } }, additionalProperties: false }三个要点唯一必填参数title类型为字符串用于指定新文档的标题。additionalProperties: false不允许出现任何 Schema 之外的字段。这与提示语中“只提供输入 Schema 描述的参数”完全一致。不允许action字段这正是 create_document.md 第三条规则的落点——操作名由宿主根据 capability id 注入调用方不能自行携带action。从源码结构看这一契约与 wasm-src/src/types.rs 中的 serde 枚举是一一对应的#[derive(Debug, Deserialize, JsonSchema)] #[serde(tag action, rename_all snake_case)] pub enum GoogleDocsAction { /// Create a new document. CreateDocument { /// Document title. title: String, }, // ... 其余 14 个动作 }该枚举同时派生schemars::JsonSchema使对外暴露的 Schema 与 serde 反序列化契约永远不会漂移——这是lib.rs中schema()方法的实现方式wasm-src/src/lib.rs。三、提示语三条行为规则的语义解读create_document.md 的正文只有三条规则但它们分别约束了“做什么、怎么做、怎么传参”三个层面规则 1创建全新文档Create a new Google Docs document.这是能力的唯一职责在用户的 Google Drive 中新建一份空白文档。底层实现对应 api.rs 中的create_document函数/// Create a new document. pub fn create_document(title: str) - ResultCreateDocumentResult, GuestFailure { let body serde_json::json!({ title: title }); let body_str serde_json::to_string(body).map_err(|e| serialization_failure(e))?; let response api_call(POST, , Some(body_str))?; let parsed: serde_json::Value serde_json::from_str(response).map_err(|e| serialization_failure(e))?; Ok(CreateDocumentResult { document_id: parsed[documentId].as_str().unwrap_or().to_string(), title: parsed[title].as_str().unwrap_or().to_string(), }) }它向https://docs.googleapis.com/v1/documentsDOCS_API_BASE见 api.rs发起POST请求体为{title: ...}成功后在响应中提取documentId与title返回。返回值结构CreateDocumentResult定义于 types.rs包含两个字段pub struct CreateDocumentResult { pub document_id: String, pub title: String, }规则 2只创建被请求的交付物不得创建草稿文档探测索引Create only the requested deliverable. Do not create scratch documents to discover table indexes; useinspect_documentand the semantic editing operations instead.这条规则的设计动机来自 Google Docs 的索引机制文档正文的插入/删除以 0 基字符偏移index定位但索引会随每次编辑漂移人工推算极易出错。提示语禁止用“先建一份草稿文档、插入表格、读回索引”这种探测方式因为它会在用户的 Drive 中留下无用的垃圾文件探测本身要消耗多次网络往返和写入配额索引正确性完全可以通过只读的结构化检查获得。正确的替代方案是 inspect_document.md 定义的inspect_document——一次调用返回段落与表格的结构化信息含startIndex、endIndex、单元格内容、命名样式用于规划带索引的编辑随后用apply_text_edits文本锚点替换默认要求锚点唯一、create_table_with_data插入、填充、可选加粗表头并验证、insert_text等语义操作完成写入最后用verify_document回读校验。对应实现分别在 api.rs 的apply_text_edits、create_table_with_data、inspect_document函数中它们在每次批量写前都会fetch_document拉取最新revisionId并配合writeControl.requiredRevisionId做并发防护。规则 3宿主按 capability id 选择操作不传 action 字段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 扩展工具统一的安全约定在 lib.rs 中有完整的强制实现action_from_context从宿主注入的调用上下文ToolContext.capability_id映射出动作名google-docs.create_document→create_document未知 capability 返回unsupported_google_docs_capability错误params_with_action在解析入参后显式拒绝调用方携带的action字段——若入参对象中已存在action键立即返回invalid_parameters随后由execute_inner按动作分发将action注入参数后反序列化为GoogleDocsAction枚举。该行为还有单元测试背书lib.rs#[test] fn params_with_action_rejects_caller_supplied_action() { let error params_with_action( r#{action:delete_all,document_id:doc-1}#, get_document, ) .unwrap_err(); assert_eq!(error.kind, ErrorKind::Input); assert_eq!(error.code.as_deref(), Some(invalid_parameters)); }也就是说Agent 调用create_document时只需提交{title: ...}action由宿主从 capability id 推导后注入既杜绝了调用方越权选择其他动作也避免了参数与动作名不一致的漂移风险。四、工具注册、鉴权与权限门控manifest 视角create_document在 manifest.toml 中的注册片段如下[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-docs.create_document description Create a new Google Docs document. effects [network, use_secret, external_write] default_permission ask visibility model input_schema_ref schemas/google-docs/create_document.input.v1.json prompt_doc_ref prompts/google-docs/create_document.md [[tools.credentials]] handle google_runtime_token vendor google scopes [https://www.googleapis.com/auth/documents] audience { scheme https, host docs.googleapis.com } injection { type header, name authorization, prefix Bearer }从中可以解读出完整的权限与安全模型来源门控矩阵origin_gate_matrixloop_run下为gated_unless_granted默认门控授权后放行product与automation下为forbidden——即该能力只面向 Agent 循环且必须经过授权流程。副作用声明effectsnetwork发起外部 HTTP、use_secret使用凭据、external_write对外部系统产生写入宿主据此做资源隔离与审计。默认权限default_permission ask首次调用需用户确认。可见性visibility model工具对模型可见、供其自主决策调用。凭据注入使用google厂商凭据google_runtime_token申请https://www.googleapis.com/auth/documents写权限面向docs.googleapis.com以Authorization: Bearer token请求头注入。WASM 访客全程看不到真实的 OAuth token——所有 API 调用都通过宿主的 HTTP 能力完成凭据注入与限流api.rs。OAuth 流程本身也在 manifest 中声明oauth2_code授权码模式 PKCES256授权端点https://accounts.google.com/o/oauth2/v2/auth令牌端点https://oauth2.googleapis.com/token额外参数access_typeofflineinclude_granted_scopestruepromptconsent并配置了 7 天空闲保活刷新keepalive_idle_seconds 604800以规避 Google 测试态应用 refresh token 的过期限制manifest.toml。五、错误处理与传输语义create_document走统一的api_call传输层api.rs关键行为所有请求经宿主host::http_request发出宿主负责凭据注入、速率限制与网络策略裁决非 2xx 状态码会被转换为结构化GuestFailure401 返回AuthRequired类型、错误码google_api_error_status_401用于触发宿主侧的重新授权其余状态码返回Client类型、错误码api_status_code传输层失败网络被拒、输入非法、输出超限、执行器错误等映射为对应的ErrorKind响应体经 UTF-8 校验失败时返回invalid_utf8_response错误消息统一截断至 512 字符bounded_message避免无界字符串进入宿主日志。六、典型使用工作流将上述机制串起来一个符合规范的“创建并撰写文档”工作流如下创建调用google-docs.create_document参数{title: Meeting Notes}获得document_id与title。结构化检查调用google-docs.inspect_document获取段落/表格的结构与索引只读不产生额外文档。语义编辑用apply_text_edits做文本锚点替换锚点默认必须唯一replace_all仅在确认需全量替换时开启或用insert_text/create_table_with_data完成追加与表格写入。回读校验调用google-docs.verify_document断言期望文本片段与表格内容确实存在于 provider 状态中。整个流程保持 34 次模型可见调用索引发现与并发检查由扩展在内部完成——这正是create_document提示语要求“只创建交付物、不探测索引”所支撑的设计哲学。七、测试与产物新鲜度该扩展的工程质量由两类检查保障README.mdmanifest 投影测试cargo test -p ironclaw_extension_registry校验 manifest 声明的工具、Schema 引用与提示语引用的一致性WASM 产物新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py确保wasm/google_docs_tool.wasm与wasm-src/源码同步避免已提交二进制与源码漂移。八、实践建议参数从严调用create_document只传title不要附加任何多余字段更不要传action——宿主会以invalid_parameters拒绝并产生错误日志。创建即交付需要排版、表格等复杂结构时先create_document建空文档再用inspect_document 语义编辑操作逐步构建绝不通过创建草稿文档来试探索引。留意权限门控该工具默认ask权限且product/automation来源被禁止在生产自动化场景中需要先完成授权否则会遇到AuthRequired类错误。写后必验对写入结果有强一致性要求的场景用verify_document回读确认而不是依赖单次写入响应的乐观假设。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型 IronClaw 是人工智能AI 应用交互助手AI AgentIronClaw 中 Google Slides 段落对齐操作 format_paragraph 的输入契约与实现解析IronClaw 中 Google Slides 段落对齐操作 format_paragraph 的输入契约与实现解析 IronClaw 的 google sl人工智能AI 应用交互助手AI AgentIronClaw 扩展体系中的 Google Docs read_content 能力纯文本正文读取的协议、权限与 WASM 实现IronClaw 扩展体系中的 Google Docs read_content 能力纯文本正文读取的协议、权限与 WASM 实现 导读 google doc人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 IronClaw Google Docs 扩展的 create_document 能力：输入契约、行为规则与 WASM 实现剖析
人工智能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能力展开它定义了一个“创建一个全新 Google Docs 文档”的模型可见工具并约束了 Agent 在创建文档时必须遵守的语义纪律不创建草稿探测索引、由宿主按 capability id 分发操作、不传 action 字段。读完本文你将掌握该能力的输入 Schema、行为规则背后的设计动机以及它从 WASM 访客到 Google Docs API 的完整调用链与鉴权模型。一、create_document 在 google-docs 扩展中的定位create_document是 IronClaw 的 google-docs 扩展包 中 15 个工具之一。该包是纯数据包data-only package不包含 crate可移植工具侧以 WASM guest 形态发布见 README.md。扩展 id 为google-docs运行时为wasm产物是提交在仓库中的wasm/google_docs_tool.wasm访客源码位于wasm-src/。它面向的语义能力集合包括创建类create_document创建全新文档读取/检查类get_document、read_content、inspect_document编辑类insert_text、delete_content、replace_text、apply_text_edits格式化类format_text、format_paragraph、create_list、create_table_with_data、insert_table底层透传类batch_update校验类verify_document官方提示语明确建议普通文档工作流应优先走“语义化”路径——inspect_document做结构化检查、apply_text_edits/create_table_with_data做批量编辑、verify_document做结果校验整套流程通常只需 34 次模型可见调用索引发现、批量单元格写入、并发检查和 provider 回读都由扩展内部处理README.md。create_document正是这个工作流的起点。二、输入契约一个极简而严格的 JSON Schemacreate_document的输入由 create_document.input.v1.json 描述完整内容如下{ $schema: http://json-schema.org/draft-07/schema#, title: Google Docs create_document, description: Create a new Google Docs document., type: object, required: [title], properties: { title: { type: string, description: Document title. } }, additionalProperties: false }三个要点唯一必填参数title类型为字符串用于指定新文档的标题。additionalProperties: false不允许出现任何 Schema 之外的字段。这与提示语中“只提供输入 Schema 描述的参数”完全一致。不允许action字段这正是 create_document.md 第三条规则的落点——操作名由宿主根据 capability id 注入调用方不能自行携带action。从源码结构看这一契约与 wasm-src/src/types.rs 中的 serde 枚举是一一对应的#[derive(Debug, Deserialize, JsonSchema)] #[serde(tag action, rename_all snake_case)] pub enum GoogleDocsAction { /// Create a new document. CreateDocument { /// Document title. title: String, }, // ... 其余 14 个动作 }该枚举同时派生schemars::JsonSchema使对外暴露的 Schema 与 serde 反序列化契约永远不会漂移——这是lib.rs中schema()方法的实现方式wasm-src/src/lib.rs。三、提示语三条行为规则的语义解读create_document.md 的正文只有三条规则但它们分别约束了“做什么、怎么做、怎么传参”三个层面规则 1创建全新文档Create a new Google Docs document.这是能力的唯一职责在用户的 Google Drive 中新建一份空白文档。底层实现对应 api.rs 中的create_document函数/// Create a new document. pub fn create_document(title: str) - ResultCreateDocumentResult, GuestFailure { let body serde_json::json!({ title: title }); let body_str serde_json::to_string(body).map_err(|e| serialization_failure(e))?; let response api_call(POST, , Some(body_str))?; let parsed: serde_json::Value serde_json::from_str(response).map_err(|e| serialization_failure(e))?; Ok(CreateDocumentResult { document_id: parsed[documentId].as_str().unwrap_or().to_string(), title: parsed[title].as_str().unwrap_or().to_string(), }) }它向https://docs.googleapis.com/v1/documentsDOCS_API_BASE见 api.rs发起POST请求体为{title: ...}成功后在响应中提取documentId与title返回。返回值结构CreateDocumentResult定义于 types.rs包含两个字段pub struct CreateDocumentResult { pub document_id: String, pub title: String, }规则 2只创建被请求的交付物不得创建草稿文档探测索引Create only the requested deliverable. Do not create scratch documents to discover table indexes; useinspect_documentand the semantic editing operations instead.这条规则的设计动机来自 Google Docs 的索引机制文档正文的插入/删除以 0 基字符偏移index定位但索引会随每次编辑漂移人工推算极易出错。提示语禁止用“先建一份草稿文档、插入表格、读回索引”这种探测方式因为它会在用户的 Drive 中留下无用的垃圾文件探测本身要消耗多次网络往返和写入配额索引正确性完全可以通过只读的结构化检查获得。正确的替代方案是 inspect_document.md 定义的inspect_document——一次调用返回段落与表格的结构化信息含startIndex、endIndex、单元格内容、命名样式用于规划带索引的编辑随后用apply_text_edits文本锚点替换默认要求锚点唯一、create_table_with_data插入、填充、可选加粗表头并验证、insert_text等语义操作完成写入最后用verify_document回读校验。对应实现分别在 api.rs 的apply_text_edits、create_table_with_data、inspect_document函数中它们在每次批量写前都会fetch_document拉取最新revisionId并配合writeControl.requiredRevisionId做并发防护。规则 3宿主按 capability id 选择操作不传 action 字段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 扩展工具统一的安全约定在 lib.rs 中有完整的强制实现action_from_context从宿主注入的调用上下文ToolContext.capability_id映射出动作名google-docs.create_document→create_document未知 capability 返回unsupported_google_docs_capability错误params_with_action在解析入参后显式拒绝调用方携带的action字段——若入参对象中已存在action键立即返回invalid_parameters随后由execute_inner按动作分发将action注入参数后反序列化为GoogleDocsAction枚举。该行为还有单元测试背书lib.rs#[test] fn params_with_action_rejects_caller_supplied_action() { let error params_with_action( r#{action:delete_all,document_id:doc-1}#, get_document, ) .unwrap_err(); assert_eq!(error.kind, ErrorKind::Input); assert_eq!(error.code.as_deref(), Some(invalid_parameters)); }也就是说Agent 调用create_document时只需提交{title: ...}action由宿主从 capability id 推导后注入既杜绝了调用方越权选择其他动作也避免了参数与动作名不一致的漂移风险。四、工具注册、鉴权与权限门控manifest 视角create_document在 manifest.toml 中的注册片段如下[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-docs.create_document description Create a new Google Docs document. effects [network, use_secret, external_write] default_permission ask visibility model input_schema_ref schemas/google-docs/create_document.input.v1.json prompt_doc_ref prompts/google-docs/create_document.md [[tools.credentials]] handle google_runtime_token vendor google scopes [https://www.googleapis.com/auth/documents] audience { scheme https, host docs.googleapis.com } injection { type header, name authorization, prefix Bearer }从中可以解读出完整的权限与安全模型来源门控矩阵origin_gate_matrixloop_run下为gated_unless_granted默认门控授权后放行product与automation下为forbidden——即该能力只面向 Agent 循环且必须经过授权流程。副作用声明effectsnetwork发起外部 HTTP、use_secret使用凭据、external_write对外部系统产生写入宿主据此做资源隔离与审计。默认权限default_permission ask首次调用需用户确认。可见性visibility model工具对模型可见、供其自主决策调用。凭据注入使用google厂商凭据google_runtime_token申请https://www.googleapis.com/auth/documents写权限面向docs.googleapis.com以Authorization: Bearer token请求头注入。WASM 访客全程看不到真实的 OAuth token——所有 API 调用都通过宿主的 HTTP 能力完成凭据注入与限流api.rs。OAuth 流程本身也在 manifest 中声明oauth2_code授权码模式 PKCES256授权端点https://accounts.google.com/o/oauth2/v2/auth令牌端点https://oauth2.googleapis.com/token额外参数access_typeofflineinclude_granted_scopestruepromptconsent并配置了 7 天空闲保活刷新keepalive_idle_seconds 604800以规避 Google 测试态应用 refresh token 的过期限制manifest.toml。五、错误处理与传输语义create_document走统一的api_call传输层api.rs关键行为所有请求经宿主host::http_request发出宿主负责凭据注入、速率限制与网络策略裁决非 2xx 状态码会被转换为结构化GuestFailure401 返回AuthRequired类型、错误码google_api_error_status_401用于触发宿主侧的重新授权其余状态码返回Client类型、错误码api_status_code传输层失败网络被拒、输入非法、输出超限、执行器错误等映射为对应的ErrorKind响应体经 UTF-8 校验失败时返回invalid_utf8_response错误消息统一截断至 512 字符bounded_message避免无界字符串进入宿主日志。六、典型使用工作流将上述机制串起来一个符合规范的“创建并撰写文档”工作流如下创建调用google-docs.create_document参数{title: Meeting Notes}获得document_id与title。结构化检查调用google-docs.inspect_document获取段落/表格的结构与索引只读不产生额外文档。语义编辑用apply_text_edits做文本锚点替换锚点默认必须唯一replace_all仅在确认需全量替换时开启或用insert_text/create_table_with_data完成追加与表格写入。回读校验调用google-docs.verify_document断言期望文本片段与表格内容确实存在于 provider 状态中。整个流程保持 34 次模型可见调用索引发现与并发检查由扩展在内部完成——这正是create_document提示语要求“只创建交付物、不探测索引”所支撑的设计哲学。七、测试与产物新鲜度该扩展的工程质量由两类检查保障README.mdmanifest 投影测试cargo test -p ironclaw_extension_registry校验 manifest 声明的工具、Schema 引用与提示语引用的一致性WASM 产物新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py确保wasm/google_docs_tool.wasm与wasm-src/源码同步避免已提交二进制与源码漂移。八、实践建议参数从严调用create_document只传title不要附加任何多余字段更不要传action——宿主会以invalid_parameters拒绝并产生错误日志。创建即交付需要排版、表格等复杂结构时先create_document建空文档再用inspect_document 语义编辑操作逐步构建绝不通过创建草稿文档来试探索引。留意权限门控该工具默认ask权限且product/automation来源被禁止在生产自动化场景中需要先完成授权否则会遇到AuthRequired类错误。写后必验对写入结果有强一致性要求的场景用verify_document回读确认而不是依赖单次写入响应的乐观假设。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型 IronClaw 是人工智能AI 应用交互助手AI AgentIronClaw 中 Google Slides 段落对齐操作 format_paragraph 的输入契约与实现解析IronClaw 中 Google Slides 段落对齐操作 format_paragraph 的输入契约与实现解析 IronClaw 的 google sl人工智能AI 应用交互助手AI AgentIronClaw 扩展体系中的 Google Docs read_content 能力纯文本正文读取的协议、权限与 WASM 实现IronClaw 扩展体系中的 Google Docs read_content 能力纯文本正文读取的协议、权限与 WASM 实现 导读 google doc人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考