← 提示词库 Anthropic/claude-code/skills/google-workspace/SKILL.md 原文 md
🌐 中英双语对照

name: google-workspace
description: "Read this before the first Google Drive, Docs, Sheets or Slides connector call whenever the task creates or changes a Google file. Use this skill whenever the user wants to create or change a Google Doc, Sheet or Slides file in their Google Drive. Triggers include: a request that names Google Docs, Sheets, Slides or Drive and asks to make, edit, format, copy or rename a file; a docs.google.com link with a request to change that file, even a one-line fix or suggested edits; and any follow-up change to a Google file from earlier in the chat, even "change it" or "add a tab". Includes helper scripts for document positions, cell ranges and slide layout. However, if the user asks for a doc, deck or spreadsheet without naming Google, or gives a Google file only as source material for something new, use Claude's own output type instead. Do NOT use for read-only questions about a Google file, or for Word, Excel, PowerPoint or PDF files."

Google Docs, Sheets, and Slides / Google 文档、表格与幻灯片

The Google connectors are thin wrappers over Google's raw APIs, with almost no guidance of their own. This skill supplies that guidance: which connector does what, the rules that keep edits in the user's file, and, in one reference file per app, how each API really behaves. Most of the app-specific rules in the references were tested against Google's Docs, Sheets and Slides APIs; the rest were seen through the connectors, and a few have not been checked yet.

Google 连接器是对 Google 原始 API 的轻量封装，自身几乎没有提供任何指导。本技能补充这些指导：哪个连接器做什么、保证编辑落在用户文件内的规则，以及每个应用一份参考文件中各 API 的真实行为。参考文档中大多数应用专属规则都针对 Google 的 Docs、Sheets 和 Slides API 做过测试；其余规则通过连接器观察得到，还有少数尚未验证。

Read the reference before you touch the file / 动手改文件前先读参考文档

Working on Read first Why it matters
A Google Doc references/docs.md Docs edits address UTF-16 positions that shift after every insert and go stale after every write. Tabs and pending suggestions change the positions too.
A Google Sheet references/sheets.md Both write tools parse input like the Sheets UI, so text can silently become numbers or dates. Formatting needs numeric sheet IDs, 0-based ranges, and field masks without parentheses.
A Google Slides deck references/slides.md Positions are in EMU, an element's real size is its size times its scale, and an unmasked read can exceed 150 KB for three slides. Slides never shrinks text to fit.
处理对象 先读文档 为何重要
Google 文档 references/docs.md Docs 编辑使用 UTF-16 位置，每次插入后位置都会移动，每次写入后位置都会失效。标签页和待处理的建议也会改变位置。
Google 表格 references/sheets.md 两个写入工具都按 Sheets 界面的方式解析输入，文本可能被静默转换成数字或日期。格式化需要数字形式的表格 ID、从 0 开始的范围以及不带括号的字段掩码。
Google 幻灯片 references/slides.md 位置以 EMU 表示，元素的真实尺寸是其尺寸乘以缩放比例，且一次不带掩码的读取对三张幻灯片就可能超过 150 KB。幻灯片从不会缩小文字以适应形状。

Read the reference for every app the task touches before the first edit. Embedding a Sheets chart in a deck means reading both. The references are short, and skipping one is how edits land in the wrong place.

在首次编辑前，阅读任务涉及的每个应用的参考文档。在幻灯片中嵌入 Sheets 图表意味着两份都要读。参考文档都很简短，跳过其中一份正是编辑落错位置的原因。

1. Check the connectors before you start / 开始前先检查连接器

Connector What it can do
Google Drive Create files, upload and convert content, rename, read a file as text, export (PDF and other formats), search, trash
Google Docs Read a doc's full structure and edit it in place, directly or as suggestions
Google Sheets Read values and structure, write values and formulas, format, add tabs and charts
Google Slides Read a deck, add and edit slides, shapes, text, tables, and linked charts
连接器 能做的事
Google Drive 创建文件、上传并转换内容、重命名、将文件读取为文本、导出（PDF 及其他格式）、搜索、移入回收站
Google Docs 读取文档完整结构并就地编辑，可直接编辑或以建议形式编辑
Google Sheets 读取值与结构、写入值与公式、设置格式、添加标签页和图表
Google Slides 读取演示文稿、添加和编辑幻灯片、形状、文本、表格以及关联图表

Drive can create all three file types. It can't edit a file after that. Without the matching editor connector, every change means a new file and a new link, and the user loses the link they already have.

Drive 可以创建全部三种文件类型，但创建之后无法编辑文件。没有对应的编辑器连接器时，每次修改都意味着一个新文件和一个新链接，用户会失去他们已有的链接。

  1. Check which Google tools are available in this conversation. On surfaces where tools are deferred, search for and load the tools you need first, such as "google sheets update". Tool names differ by surface, so use the names your surface lists. If a search returns nothing, list all available tools before deciding the connector is missing, because the tool may exist under a different name.
    检查本次对话中可用的 Google 工具。在工具延迟加载的界面上，先搜索并加载所需工具，例如 "google sheets update"。工具名称因界面而异，请使用你的界面所列出的名称。如果搜索无结果，先列出所有可用工具再断定连接器缺失，因为该工具可能以其他名称存在。
  2. If the editor tools are missing, tell the user. When you can list the conversation's connectors, say which case it is: a connector that is set up but turned off in this chat (ask them to turn it on in the chat's connector settings, then continue), or one that isn't connected at all (tell them which connector to add and what it enables).
    如果缺少编辑器工具，请告知用户。当你能列出对话的连接器时，说明属于哪种情况：连接器已配置但在本对话中被关闭（请用户在对话的连接器设置中开启，然后继续），或完全未连接（告知用户应添加哪个连接器以及它能实现什么）。
  3. With an editor connector missing, a request to create a new file continues with Drive. A change to an existing file stops and asks. See the missing-connector rule in section 2.
    在缺少编辑器连接器的情况下，创建新文件的请求继续用 Drive 完成；对既有文件的修改则停下来询问。参见第 2 节的缺失连接器规则。
  4. If the user asks only for a new file, create it with Drive. If the editor connector is off, add one line saying edits will need it.
    如果用户只要求创建新文件，就用 Drive 创建。如果编辑器连接器被关闭，加一句说明后续编辑需要它。

Example: "I can create the sheet now. If you want changes later, turn on the Google Sheets connector in this chat first. Then I can edit this file, and the link will stay the same."

示例："我现在就可以创建这个表格。如果之后需要修改，请先在本对话中开启 Google Sheets 连接器。届时我就能编辑这个文件，链接也将保持不变。"

2. Rules for every file / 适用于所有文件的规则

3. Drive, for all three apps / Drive：三个应用通用

4. Helper scripts / 辅助脚本

The scripts/ folder next to this file holds tested helpers. They turn the APIs' raw JSON into short readable summaries, and turn simple specs into correct request batches, so the error-prone arithmetic never happens by hand. Use them wherever you can run Python. Run them by their full path inside this skill's folder; the references write that folder as <skill>.

本文件旁边的 scripts/ 文件夹存放经过测试的辅助脚本。它们把 API 的原始 JSON 转换为简短易读的摘要，并把简单规格转换为正确的请求批次，从而避免手工进行容易出错的算术计算。凡能运行 Python 的地方都应使用它们。以本技能文件夹内的完整路径运行；参考文档中把该文件夹写作 <skill>。

Script Commands Used for
docs_index.py outline, find, new-table, fill-table Docs positions, text search with bold and suggestion state, adding a filled table in one call, filling an existing table
sheets_helper.py range, format, cells A1 ranges to grid ranges, formatting batches from a short spec, reading formulas and error cells
slides_helper.py outline, build Real slide geometry with overflow and overlap warnings, building slides from an inch-based spec
render_export.py one command Decoding a PDF export into page images to look at
脚本 命令 用途
docs_index.py outline, find, new-table, fill-table Docs 位置、带加粗与建议状态的文本搜索、一次调用添加已填充的表格、填充既有表格
sheets_helper.py range, format, cells A1 范围转网格范围、由简短规格生成格式化批次、读取公式与错误单元格
slides_helper.py outline, build 带溢出与重叠警告的真实幻灯片几何信息、按英寸规格构建幻灯片
render_export.py one command 把 PDF 导出解码为页面图片以供查看

Getting JSON to a script. Large tool results are often saved to a file by the app, and the result tells you the path. Point the script at that path; the scripts read the file as the app saved it. When a result comes back in context and is small (a few KB, such as a masked read or sheet metadata), write it to a file and run the script on it. Don't re-type a large result into a file: that doubles the cost and invites copying errors. If a large result was cut off and not saved, read a smaller slice instead (a field mask, a range, or one tab) rather than guessing.

**把 JSON 交给脚本。**大型工具结果通常由应用保存到文件，结果中会告知路径。让脚本指向该路径；脚本会按应用保存的原样读取文件。当结果直接返回在上下文中且较小时（几 KB，例如带掩码的读取或表格元数据），把它写入文件再对文件运行脚本。不要把大结果重新敲进文件：那会使成本翻倍并容易引入抄写错误。如果大结果被截断且未保存，改为读取更小的一片（字段掩码、一个范围或单个标签页），而不是靠猜测。

Every script prints --help with its full usage. Each reference shows the commands in context.

每个脚本都会输出 --help 及其完整用法。每份参考文档都会在上下文中展示这些命令。

5. Common failures across apps / 各应用常见故障

Symptom Cause Fix
"No such tool available" The tool is deferred, or the name is different on this surface Search for and load the tool. Use the exact name your surface lists.
Permission denied on a file you created The file is in the trash Ask the user to restore it from Drive's trash. You can't restore it with the connectors.
400: required revision ID does not match The file changed after your read, often because of your own previous write Read again, rebuild the requests from the new read, and send them with the new revision.
A whole batch failed on one bad request Batches are atomic Fix the named request and resend the full batch. Nothing from the failed call was applied.
A read is too large or cut off Unmasked editor reads include everything Use Drive read_file_content, a field mask, a range, or a single tab. Run the helper on a saved result.
Two files where the user expected one An edit was done by creating a new file Make changes in place with the editor connector. Tell the user about the extra file; don't trash it without asking.
症状 原因 解决方法
"No such tool available" 工具被延迟加载，或在该界面上名称不同 搜索并加载该工具。使用你的界面列出的确切名称。
对你创建的文件权限被拒 文件在回收站里 请用户从 Drive 回收站恢复。你无法用连接器恢复。
400: required revision ID does not match 文件在你的读取之后发生了变化，往往是你自己上一次写入所致 重新读取，基于新读取重建请求，并携带新版本号发送。
整批因一个错误请求而失败 批次是原子的 修复所指出的请求并重发完整批次。失败的调用没有应用任何内容。
读取结果过大或被截断 不带掩码的编辑器读取会包含全部内容 改用 Drive 的 read_file_content、字段掩码、范围或单个标签页。对已保存的结果运行辅助脚本。
用户期望一个文件却出现两个 修改是通过创建新文件完成的 用编辑器连接器就地修改。告知用户多出的文件；未经询问不要删除。

Each reference ends with the failures specific to that app.

每份参考文档的结尾是该应用特有的故障。

6. What the connectors can't do / 连接器做不到的事

When a request runs into one of these, say so plainly and do the alternative. Reported: seen through the connectors or in their tool schemas. Untested: not yet checked.

当请求遇到下列情况之一时，如实说明并采用替代做法。Reported：通过连接器或其工具 schema 观察到。Untested：尚未验证。