google-drive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Drive files

Google Drive 文件

Ids come from search, never guesses

ID 来自搜索，切勿猜测

Every tool takes Drive file ids. Get them from

search

(or

list_folder

for a known folder,

list_recent_files

for "what was I just working on"), or from the id in a URL the user pasted.

exact_name

beats

query

for a known filename; add

mime_type_filter

to cut noise. Never invent an id or reuse one from a stale conversation - re-search first.

每个工具都需要Drive文件ID。你可以通过

search

获取（已知文件夹用

list_folder

，想找「刚才在处理的文件」用

list_recent_files

），也可以从用户粘贴的URL中提取ID。对于已知文件名，

exact_name

比

query

更精准；可添加

mime_type_filter

减少无关结果。切勿编造ID或复用旧对话中的ID——请先重新搜索。

Folder targeting

文件夹定位

```
create_folder
```
takes
```
parent_folder_id
```
; without it the folder lands in My Drive root. When the user names a destination folder, resolve its id and pass it - a file created in root when a folder was specified is a wrong result even if the content is perfect.
```
create_file
```
also takes
```
parent_folder_id
```
, so create files directly where they belong instead of creating then moving.
The Docs/Sheets/Slides providers' own create tools CANNOT target a folder (their APIs have no parent parameter). When placement matters, either create the artifact there with
```
create_file
```
(Markdown to Doc, CSV to Sheet), or create it and then
```
move_or_rename
```
with
```
destination_folder_id
```
.
```
move_or_rename
```
does either or both in one call; renaming does not change the id.
```
update_file
```
is the same rename/move with the hosted Drive tool's argument names (
```
fileId
```
;
```
title
```
renames,
```
parentId
```
moves by replacing the current parent); it exists on both the translator and hosted surfaces, so prefer it in guidance that must work on either.
Grant limits: this app's grant is
```
drive.file
```
, so moving into or writing files/folders this app never created (and the user never picked) can 403. That 403 is a permission fact, not a transient error; do not retry it.

```
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 and CSV conversion

Markdown与CSV转换

create_file

with

target_mime_type: application/vnd.google-apps.document

converts Markdown (headings, lists, tables) into a real Google Doc in one call;

...spreadsheet

converts CSV into a Sheet. This is the fastest correct way to produce a formatted Doc: prefer it over create-then-insert when the content is known up front.

update_file_content

converts in place the same way.

create_file

配合

target_mime_type: application/vnd.google-apps.document

可一步将Markdown（标题、列表、表格）转换为正式的Google Doc；指定

...spreadsheet

则可将CSV转换为Sheet。这是生成格式化文档最快、最正确的方式：如果内容已提前确定，优先使用此方法，而非先创建再插入内容。

update_file_content

也支持同样的就地转换。

Copying, metadata, and sharing

复制、元数据与共享

```
copy_file
```
duplicates a file (optionally into a folder) - the right way to instantiate a template without touching the original.
```
get_file_metadata
```
returns the full record (mime type, parents, size, owners, modified time); use it to confirm a move landed.
```
get_file_permissions
```
lists who has access;
```
share_file
```
grants a role to an email. Share only when the user asked; report the link rather than widening access speculatively.
```
download_file
```
returns the raw bytes base64-encoded for non-Google files (images, PDFs, plain text).

```
copy_file
```
用于复制文件（可选择复制到指定文件夹）——这是实例化模板且不改动原文件的正确方式。
```
get_file_metadata
```
返回完整的文件记录（MIME类型、父级、大小、所有者、修改时间）；可用于确认文件是否移动成功。
```
get_file_permissions
```
列出拥有访问权限的人员；
```
share_file
```
为指定邮箱授予角色权限。仅在用户要求时才共享；直接返回链接即可，不要擅自扩大访问范围。
```
download_file
```
以base64编码形式返回非Google文件（图片、PDF、纯文本）的原始字节。

Reading and exporting

读取与导出

```
read_file
```
returns text: Docs as Markdown, Sheets as CSV per tab, Slides as plain text. Use it to verify content after writes.
```
export_file
```
returns rendered bytes base64-encoded:
```
pdf
```
for Docs/Sheets/Slides (Sheets PDF renders every tab, charts included),
```
png
```
/
```
svg
```
for Drawings, plus office formats (docx/xlsx/pptx). Use PDF when the user wants to see the final look; exports cap at 10 MB.
For one slide as PNG use the google-slides
```
get_slide_thumbnail
```
tool, not Drive export.

```
read_file
```
返回文本内容：Docs转为Markdown，Sheets按工作表转为CSV，Slides转为纯文本。可用于写入后验证内容。
```
export_file
```
以base64编码形式返回渲染后的字节：Docs/Sheets/Slides支持导出为
```
pdf
```
（Sheets的PDF会导出所有工作表，包含图表），Drawings支持导出为
```
png
```
/
```
svg
```
，还支持Office格式（docx/xlsx/pptx）。当用户需要查看最终效果时使用PDF导出；导出文件大小上限为10MB。
若要将单张幻灯片导出为PNG，请使用google-slides的
```
get_slide_thumbnail
```
工具，而非Drive导出功能。

Comments

Comments live on the Drive file, so one tool set covers Docs, Sheets, and Slides alike:

```
list_comments
```
returns each comment's text, quoted document text, resolved state, and replies; it pages, so follow
```
nextPageToken
```
before concluding a thread does not exist.
```
add_comment
```
adds a file-level comment (no text anchor).
```
reply_to_comment
```
replies by comment id, and its
```
action: "resolve"
```
(content optional) is the ONLY way to resolve a thread; editing document text near a comment never resolves it. Leave already-resolved threads alone.

评论存储在Drive文件中，因此同一套工具可同时支持Docs、Sheets和Slides：

```
list_comments
```
返回每条评论的文本、引用的文档文本、解决状态和回复；该接口支持分页，因此在判定某个评论线程不存在之前，需跟随
```
nextPageToken
```
拉取所有页。
```
add_comment
```
添加文件级评论（无文本锚点）。
```
reply_to_comment
```
通过评论ID回复，其
```
action: "resolve"
```
（content可选）是唯一能解决评论线程的方式；编辑评论附近的文档文本永远不会解决该评论。不要改动已解决的评论线程。

Deleting

删除

trash_file

is recoverable (~30 days) and works on files and folders (a trashed folder takes its contents). Permanent deletion is deliberately not available; never promise it.

trash_file

是可恢复的（保留约30天），支持文件和文件夹（被移到回收站的文件夹会连同其内容一起）。永久删除功能刻意未提供；切勿向用户承诺永久删除。

Verify your work

验证操作结果

After creates and moves, confirm placement with

list_folder

on the destination or

get_file_metadata

(check

parents

). After content writes,

read_file

is the ground truth for text and

export_file

(pdf) for the rendered result.

创建和移动操作后，可通过对目标文件夹调用

list_folder

或调用

get_file_metadata

（检查

parents

字段）确认存放位置。写入内容后，

read_file

是文本内容的事实标准，

export_file

（pdf）是渲染结果的事实标准。