google-drive

Google Drive 文件

ID 来自搜索，绝不猜测

每个工具都需要 Drive 文件 ID。请从 search（或已知文件夹使用 list_folder，查询“我刚才在处理什么”时使用 list_recent_files）获取， 或使用用户粘贴的 URL 中的 ID。对于已知文件名，exact_name 优于 query；添加 mime_type_filter 可减少无关结果。绝不要编造 ID，也不要 重复使用过时对话中的 ID——请先重新搜索。

文件夹定位

• create_folder 接受 parent_folder_id；不提供时，文件夹会创建在“我的云端硬盘”根目录中。用户指定目标文件夹时，请解析其 ID 并传入——指定了文件夹却在根目录中创建文件夹，即使内容完美无误，结果也不正确。
• create_file 也接受 parent_folder_id，因此应直接在文件所属位置创建，而不是创建后再移动。
• Docs/Sheets/Slides 提供方自身的创建工具无法指定文件夹（其 API 没有父级参数）。需要指定位置时，可以使用 create_file 在目标位置创建相应文件（Markdown 转 Doc、CSV 转 Sheet），也可以先创建，再使用 move_or_rename 和 destination_folder_id 移动。
• move_or_rename 可在一次调用中完成移动、重命名或两者兼做；重命名不会更改 ID。
• update_file 与托管 Drive 工具执行相同的重命名/移动操作，但参数名称不同（fileId；title 用于重命名，parentId 用于替换当前父级以移动文件）；翻译器和托管接口都提供此工具，因此编写适用于任一接口的指导时应优先使用它。
• 授权限制：此应用的授权范围为 drive.file，因此将此应用从未创建（且用户从未选择）的文件/文件夹移入或写入其中，可能会返回 403。此 403 表示权限问题，并非暂时性错误；不要重试。

Markdown 和 CSV 转换

使用 target_mime_type: application/vnd.google-apps.document 调用 create_file，可在一次调用中将 Markdown（标题、列表、表格）转换为真正的 Google 文档；使用 ...spreadsheet 可将 CSV 转换为 Sheet。这是生成格式化文档的最快且正确的方式：内容已准备好时，应优先使用它，而不是先创建再插入内容。 update_file_content 也可以用相同方式原地转换。

复制、元数据和共享

• copy_file 用于复制文件（可选择放入文件夹）——这是创建模板副本而不改动原文件的正确方式。
• get_file_metadata 返回完整记录（MIME 类型、父级、大小、所有者、修改时间）；可用它确认文件是否已移至目标位置。
• get_file_permissions 列出有权访问的人员； share_file 向电子邮件地址授予角色。仅在用户提出要求时共享；请报告链接，不要擅自扩大访问范围。
• 对于非 Google 文件（图片、PDF、纯文本），download_file 会返回经 Base64 编码的原始字节。

读取和导出

• read_file 返回文本：Docs 为 Markdown，Sheets 按工作表标签返回 CSV，Slides 返回纯文本。写入后可用它验证内容。
• export_file 返回经 Base64 编码的渲染字节：Docs/Sheets/Slides 可导出为 pdf（Sheets PDF 会渲染每个标签页，包括图表），Drawings 可导出为 png/svg，还支持 Office 格式（docx/xlsx/pptx）。用户想查看最终效果时，请使用 PDF；导出上限为 10 MB。
• 要将单张幻灯片导出为 PNG，请使用 google-slides 的 get_slide_thumbnail 工具，而不要使用 Drive 导出。

评论

评论位于 Drive 文件上，因此同一套工具适用于 Docs、Sheets 和 Slides：

• list_comments 会返回每条评论的文本、引用的文档文本、已解决状态和回复；结果采用分页，因此在断定某个讨论串不存在之前，请继续获取 nextPageToken。
• add_comment 添加文件级评论（没有文本锚点）。
• reply_to_comment 按评论 ID 回复；其 action: "resolve"（内容可选）是解决讨论串的唯一方式；在评论附近编辑文档文本并不会解决评论。请不要处理已解决的讨论串。

删除

trash_file 可恢复（约 30 天），适用于文件和文件夹（移入回收站的文件夹会连同其内容一起移入）。本工具有意不提供永久删除功能；切勿承诺永久删除。

验证操作结果

创建和移动后，使用目标位置的 list_folder 或 get_file_metadata（检查 parents）确认位置。 写入内容后，read_file 是核实文本的权威依据，export_file（pdf）则用于查看渲染结果。