IronClaw Google Drive 权限清单：list_permissions 工具的参数、Schema 与 WASM 实现解析-平芜编程栈

人工智能
AI 应用
交互助手
AI Agent

【免费下载链接】ironclaw

IronClaw is an Agent OS focused on privacy, security and extensibility

项目地址：https://gitcode.com/gh_mirrors/iro/ironclaw

IronClaw 以「扩展即包（package）」的方式把 Google Drive 能力打包成 12 个独立工具，其中google-drive.list_permissions负责回答一个关键问题：这个文件/文件夹当前被分享给了谁、各持有什么角色。本文以 list_permissions.md 为线索，结合输入 Schema、manifest 配置与 WASM 客端源码，完整拆解该工具的调用约定、安全模型与底层实现，读完即可理解如何在 Agent 会话中正确触发它，以及它背后「host 注入凭据、客端零接触令牌」的设计逻辑。

工具定位：由 host 按 capability id 选择操作的声明式调用

在 IronClaw 的扩展体系中，工具提示词（prompt doc）不是给用户看的操作手册，而是给模型（Agent）看的「能力声明」。list_permissions.md全文只有两句约束：

List file permissions.—— 工具职责：列出文件权限。
The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.—— 关键调用约定：操作选择权在 host 侧，Agent 只需要按输入 Schema 提供参数，严禁自行添加action字段。

这与 lib.rs 中的运行时逻辑一一对应：WASM 客端通过action_from_context从 host 注入的ToolContext.capability_id解析出具体操作（"google-drive.list_permissions"→list_permissions），随后params_with_action会把action以内部方式合并进参数并主动拒绝用户侧提交的action字段（返回invalid_parameters）。也就是说，Agent 永远不会直接选择「我要执行 list_permissions」，它只会响应 host 基于 capability 暴露的调用请求。

该工具属于 google-drive 包 12 个工具之一（google-drive.list_files…google-drive.list_shared_drives），整个包是data-only package：不包含 Rust crate，工具实体以 WASM 客端形式随包分发。

输入参数：唯一必填项 file_id

工具的全部入参定义在 list_permissions.input.v1.json，这是一个 JSON Schema draft-07 描述：

{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Google Drive list_permissions", "description": "List file permissions.", "type": "object", "required": ["file_id"], "properties": { "file_id": { "type": "string", "description": "The file ID." } }, "additionalProperties": false }

要点拆解：

字段	类型	必填	说明
`file_id`	string	是	Google Drive 文件或文件夹的 ID，来自`list_files`/`get_file`等操作返回结果

additionalProperties: false意味着传任何未声明字段都会被 Schema 拒绝，这与「不要传action」的提示词约束形成双保险。
与 types.rs 中的GoogleDriveAction::ListPermissions { file_id }变体一致——这是整个 12 个操作中仅有的几个「单必填字段」操作之一，比list_files（全部可选参数）更严格。

值得注意的还有包内的 raw_output.v1.json：它声明「Google API response serialized by the WASM tool」，即本工具（以及同包其他工具）的响应由 WASM 客端序列化后直接上送 host，host 不做二次解释。

从 manifest 看安全与凭据模型

工具级声明位于 manifest.toml，google-drive.list_permissions一节完整定义了它的安全边界：

[[tools]] origin_gate_matrix = { loop_run = "gated_unless_granted", product = "forbidden", automation = "forbidden" } id = "google-drive.list_permissions" description = "List file permissions." effects = ["network", "use_secret"] default_permission = "ask" visibility = "model" input_schema_ref = "schemas/google-drive/list_permissions.input.v1.json" prompt_doc_ref = "prompts/google-drive/list_permissions.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_run下为gated_unless_granted（Agent 主循环中默认需要显式授权/批准才能执行），而product、automation场景一律forbidden——这意味着该工具只面向 Agent 会话开放，禁止在产品/自动化入口直接调用。
effects：声明副作用为network+use_secret。对比同包share_file/delete_file等写操作多出的external_write，list_permissions是纯读操作，不会产生外部写入。
default_permission = "ask"：首次调用需要用户确认（结合 origin gate，属于典型的「敏感能力需批准」模式）。
credentials 注入：使用 vendor 为google的google_runtime_token，作用域仅为https://www.googleapis.com/auth/drive.readonly（只读，无法改权限），host 会以Authorization: Bearer <token>请求头形式注入。WASM 客端永远看不到 OAuth 令牌本体——api.rs 头部注释明确写道「All API calls go through the host's HTTP capability, which handles credential injection and rate limiting. The WASM tool never sees the actual OAuth token.」这正是 IronClaw「凭据不出沙箱」的隐私设计核心。

OAuth 流程本身由[auth.google]段配置：oauth2_code授权码模式 + PKCE S256，授权端点https://accounts.google.com/o/oauth2/v2/auth，令牌端点https://oauth2.googleapis.com/token，应用级 client_id/client_secret 由部署方在[admin_configuration]的google_oauth_client_id/google_oauth_client_secret中提供，并被所有google-*扩展共享（group_id = "vendor.google"）。

WASM 实现：一次 GET 请求与精确的字段裁剪

核心实现在 api.rs 的 list_permissions 函数：

pub fn list_permissions(file_id: &str) -> Result<ListPermissionsResult, GuestFailure> { let path = format!( "files/{}/permissions?fields=permissions(id,role,type,emailAddress,displayName)&supportsAllDrives=true", url_encode(file_id) ); let response = api_call("GET", &path, None)?; let parsed: serde_json::Value = serde_json::from_str(&response).map_err(|e| serialization_failure(&e))?; let permissions = parsed["permissions"] .as_array() .map(|arr| { arr.iter() .map(|p| Permission { id: p["id"].as_str().unwrap_or("").to_string(), role: p["role"].as_str().unwrap_or("").to_string(), permission_type: p["type"].as_str().unwrap_or("").to_string(), email_address: p["emailAddress"].as_str().map(|s| s.to_string()), display_name: p["displayName"].as_str().map(|s| s.to_string()), }) .collect() }) .unwrap_or_default(); Ok(ListPermissionsResult { permissions }) }

实现要点：

端点：GET https://www.googleapis.com/drive/v3/files/{file_id}/permissions，file_id经url_encode处理（见 url_encode），API 基址常量DRIVE_API_BASE = "https://www.googleapis.com/drive/v3"。
fields 裁剪：fields=permissions(id,role,type,emailAddress,displayName)精确限定响应字段，避免拉取无关大字段，减少带宽与 token 消耗。
supportsAllDrives=true：与同包其他操作保持一致，使查询对共享盘（shared drive）中的文件同样生效。
解析容错：对缺失字段一律回退为空值/None，避免上游字段缺失导致整个工具失败；permissions数组缺失时返回空列表而非报错。
统一错误映射：所有 HTTP 调用经由api_call走 host 的http_request能力，非 2xx 状态码会进入api_status_error——401 映射为ErrorKind::AuthRequired并携带稳定错误码google_api_error_status_401，其余状态映射为ErrorKind::Client与api_status_{status}（api.rs 测试验证了 401 与 429 两条路径）。

响应结构：一条权限记录包含哪些信息

工具返回 JSON 形如：

{ "permissions": [ { "id": "0B12345...", "role": "writer", "type": "user", "emailAddress": "alice@example.com", "displayName": "Alice" } ] }

对应 types.rs 的 Permission 结构：

字段	类型	说明
`id`	string	权限记录 ID，是后续`remove_permission`撤销权限时必需的回执标识
`role`	string	角色，如`reader`、`commenter`、`writer`、`organizer`
`type`	string	权限主体类型（序列化为`permission_type`字段名保留关键字`type`），如`user`、`group`、`domain`、`anyone`
`emailAddress`	string?	主体邮箱（用户/群组类型时存在）
`displayName`	string?	主体显示名

id+role的组合是完整权限审计的最小信息单元：list_permissions负责「看清现状」，而修改现状由同包的两个写操作完成——share_file（POSTfiles/{file_id}/permissions，以type=user+role+emailAddress创建新权限）与remove_permission（DELETEfiles/{file_id}/permissions/{permission_id}，按权限 ID 撤销），三个工具构成完整的权限生命周期闭环，且写操作都携带external_writeeffect 与drive（非只读）作用域，安全级别与只读的list_permissions明确区分。

测试与交付：Schema 一致性由 schemars 保证

types.rs 的测试揭示了本项目一个值得借鉴的工程实践：工具对外公布的 Schema 不再手写，而是通过schemars::JsonSchema派生自GoogleDriveAction枚举，每个操作变体生成oneOf分支并带各自的required数组。测试明确断言：

get_file分支的required必须包含file_id（此前手写 Schema 把所有字段声明为可选，导致 Agent 频繁构造出缺字段的非法调用）；
list_files分支不得要求file_id（它本来就没有该参数），只要求判别字段action。

这意味着list_permissions的「file_id必填」约束同时存在于声明 Schema、serde 反序列化层与运行期校验三层，杜绝了「Schema 说可选、代码说必填」的漂移问题。

在交付侧，该包由 ironclaw_extension_support 的 gsuite.rs 以include_str!/include_bytes!方式内嵌 manifest 与 google_drive_tool.wasm 编译产物，仓库 CI 通过python3 scripts/ci/check-wasm-artifact-freshness.py校验 WASM 产物与源码一致性，manifest 投影则由cargo test -p ironclaw_extension_registry覆盖。

常见问题与排查指引

误传action字段：提示词与 Schema 双重禁止，WASM 客端会以invalid_parameters拒绝——Agent 调用时只传{"file_id": "..."}即可。
401 / 令牌失效：返回AuthRequired与google_api_error_status_401，说明drive.readonly作用域令牌缺失或过期，需要重新走[auth.google]的 OAuth 授权流程。
找不到任何权限：可能原因包括file_id不属于当前账户可访问范围，或文件从未被分享（permissions为空数组）；结合supportsAllDrives=true，对共享盘文件同样可用。
想查共享盘：先使用google-drive.list_shared_drives拿到共享盘 ID，再配合list_files（corpora=drive、drive_id=...）定位具体文件，最后用list_permissions审计其权限。

小结

google-drive.list_permissions是 IronClaw 扩展体系中「只读审计型工具」的典型样本：声明式提示词把操作选择权交给 host、JSON Schema 用required+additionalProperties: false约束入参、manifest 以drive.readonly作用域 +gated_unless_granted+ask默认权限层层设防，而 WASM 客端仅凭 host 注入的 Bearer 令牌完成一次字段精确裁剪的 GET 请求。理解了它，也就理解了整个google-drive包乃至 IronClaw 扩展框架「最小权限 + 凭据隔离 + Schema 一致性」的设计哲学。