google-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Docs

Interact with Google Docs for document creation, editing, and content management.

与Google Docs进行交互，实现文档的创建、编辑和内容管理。

Installation

安装

Install Python dependencies:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Download the skill from Releases or use directly from this repository.

安装Python依赖:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

从Releases下载该技能，或直接使用本仓库中的内容。

Setup Verification

安装验证

After installation, verify the skill is properly configured:

bash

python scripts/google-docs.py check

This will check:

Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
Authentication configuration
Connectivity to Google Docs API

If anything is missing, the check command will provide setup instructions.

安装完成后，验证技能是否配置正确：

bash

python scripts/google-docs.py check

该命令将检查：

Python依赖（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
身份认证配置
与Google Docs API的连接性

如果有缺失项，检查命令会提供设置说明。

Authentication

身份认证

Google Docs uses OAuth 2.0 for authentication. For complete setup instructions, see:

GCP Project Setup Guide - Create project, enable Docs API
Google OAuth Setup Guide - Configure credentials

Google Docs使用OAuth 2.0进行身份认证。完整的设置说明请参考：

GCP项目设置指南 - 创建项目，启用Docs API
Google OAuth设置指南 - 配置凭据

Quick Start

快速开始

Create

~/.config/agent-skills/google.yaml

yaml

oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret

Run
```
python scripts/google-docs.py check
```
to trigger OAuth flow and verify setup.

创建

~/.config/agent-skills/google.yaml

yaml

oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret

运行
```
python scripts/google-docs.py check
```
触发OAuth流程并验证设置。

OAuth Scopes

OAuth权限范围

The skill requests granular scopes for different operations:

Scope	Permission	Used For
`documents.readonly`	Read documents	Reading document content and metadata
`documents`	Full access	Creating and modifying documents
`drive.readonly`	Read Drive files	Exporting documents as markdown or PDF

该技能针对不同操作请求细分的权限范围：

权限范围	权限	用途
`documents.readonly`	读取文档	读取文档内容和元数据
`documents`	完全访问	创建和修改文档
`drive.readonly`	读取云端硬盘文件	将文档导出为Markdown或PDF格式

Scope Errors

权限范围错误

If you encounter "insufficient scope" errors, revoke your token and re-authenticate:

Revoke at https://myaccount.google.com/permissions

Clear token:

keyring del agent-skills google-docs-token-json

Re-run:
```
python scripts/google-docs.py check
```

如果遇到"权限范围不足"错误，请撤销令牌并重新认证：

在https://myaccount.google.com/permissions撤销权限

清除令牌：

keyring del agent-skills google-docs-token-json

重新运行：
```
python scripts/google-docs.py check
```

Commands

命令

check

Verify configuration and connectivity.

bash

python scripts/google-docs.py check

This validates:

Python dependencies are installed
Authentication is configured
Can connect to Google Docs API
Creates a test document to verify write access

验证配置和连接性。

bash

python scripts/google-docs.py check

该命令将验证：

Python依赖已安装
身份认证已配置
可连接到Google Docs API
创建测试文档以验证写入权限

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

bash

python scripts/google-docs.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Credentials are saved to

~/.config/agent-skills/google-docs.yaml

Options:

```
--client-id
```
- OAuth 2.0 client ID (required)
```
--client-secret
```
- OAuth 2.0 client secret (required)

存储OAuth 2.0客户端凭据，用于自定义OAuth流程。

bash

python scripts/google-docs.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

凭据将保存到

~/.config/agent-skills/google-docs.yaml

。

选项:

```
--client-id
```
- OAuth 2.0客户端ID（必填）
```
--client-secret
```
- OAuth 2.0客户端密钥（必填）

documents create

Create a new blank Google Doc.

bash

python scripts/google-docs.py documents create --title "My Document"

Options:

```
--title
```
- Document title (required)
```
--json
```
- Output as JSON

Example:

bash

undefined

创建新的空白Google Doc文档。

bash

python scripts/google-docs.py documents create --title "My Document"

选项:

```
--title
```
- 文档标题（必填）
```
--json
```
- 以JSON格式输出

示例:

bash

undefined

Create a new document

创建新文档

python scripts/google-docs.py documents create --title "Project Notes"

Output:

输出:

✓ Document created successfully

✓ 文档创建成功

Title: Project Notes

标题: Project Notes

Document ID: 1abc...xyz

文档ID: 1abc...xyz

URL: https://docs.google.com/document/d/1abc...xyz/edit

链接: https://docs.google.com/document/d/1abc...xyz/edit

undefined

undefined

documents get

Get document metadata and structure.

bash

python scripts/google-docs.py documents get DOCUMENT_ID

Arguments:

```
document_id
```
- The Google Docs document ID

Options:

```
--json
```
- Output full document structure as JSON

Example:

bash

undefined

获取文档元数据和结构。

bash

python scripts/google-docs.py documents get DOCUMENT_ID

参数:

```
document_id
```
- Google Docs文档ID

选项:

```
--json
```
- 以JSON格式输出完整文档结构

示例:

bash

undefined

Get document metadata

获取文档元数据

python scripts/google-docs.py documents get 1abc...xyz

Output:

输出:

Title: Project Notes

标题: Project Notes

Document ID: 1abc...xyz

文档ID: 1abc...xyz

Characters: 1234

字符数: 1234

Revision ID: abc123

修订版本ID: abc123

undefined

undefined

documents read

Read document content as plain text, markdown, or PDF.

bash

python scripts/google-docs.py documents read DOCUMENT_ID

Arguments:

```
document_id
```
- The Google Docs document ID

Options:

```
--format
```
- Output format:
```
text
```
(default),
```
markdown
```
(preserves tables and headings), or
```
pdf
```
```
--output
```
,
```
-o
```
- Output file path (used with pdf format)
```
--json
```
- Output as JSON with content field (for text/markdown formats)

Example:

bash

undefined

以纯文本、Markdown或PDF格式读取文档内容。

bash

python scripts/google-docs.py documents read DOCUMENT_ID

参数:

```
document_id
```
- Google Docs文档ID

选项:

```
--format
```
- 输出格式：
```
text
```
（默认）、
```
markdown
```
（保留表格和标题）或
```
pdf
```
```
--output
```
,
```
-o
```
- 输出文件路径（PDF格式专用）
```
--json
```
- 以JSON格式输出包含内容字段的结果（适用于文本/Markdown格式）

示例:

bash

undefined

Read as plain text (default)

以纯文本格式读取（默认）

python scripts/google-docs.py documents read 1abc...xyz

Read as markdown with table preservation

以Markdown格式读取并保留表格

python scripts/google-docs.py documents read 1abc...xyz --format markdown

Export as PDF

导出为PDF格式

python scripts/google-docs.py documents read 1abc...xyz --format pdf --output document.pdf

Output as markdown:

Markdown格式输出示例:

# Heading

# 标题

This is a paragraph.

这是一段正文。

| Column 1 | Column 2 |

| 列1 | 列2 |

|----------|----------|

| Value 1 | Value 2 |

| 值1 | 值2 |


**Note:** Markdown and PDF export use Google's native Drive API export. Markdown preserves tables, headings, formatting, and structure with high fidelity. Both require the `drive.readonly` scope.


**注意:** Markdown和PDF导出使用Google原生云端硬盘API。Markdown格式可高度保真地保留表格、标题、格式和结构。这两种格式均需要`drive.readonly`权限范围。

content append

Append text to the end of a document.

bash

python scripts/google-docs.py content append DOCUMENT_ID --text "Additional content"

Arguments:

```
document_id
```
- The Google Docs document ID

Options:

```
--text
```
- Text to append (required)
```
--json
```
- Output API response as JSON

Example:

bash

undefined

在文档末尾追加文本。

bash

python scripts/google-docs.py content append DOCUMENT_ID --text "附加内容"

参数:

```
document_id
```
- Google Docs文档ID

选项:

```
--text
```
- 要追加的文本（必填）
```
--json
```
- 以JSON格式输出API响应

示例:

bash

undefined

Append text

追加文本

python scripts/google-docs.py content append 1abc...xyz --text "Meeting notes from today..."

python scripts/google-docs.py content append 1abc...xyz --text "今日会议记录..."

Output:

输出:

✓ Text appended successfully

✓ 文本追加成功

undefined

undefined

content insert

Insert text at a specific position in the document.

bash

python scripts/google-docs.py content insert DOCUMENT_ID --text "Insert this" --index 10

Arguments:

```
document_id
```
- The Google Docs document ID

Options:

```
--text
```
- Text to insert (required)
```
--index
```
- Position to insert at, 0-based (required)
```
--json
```
- Output API response as JSON

Example:

bash

undefined

在文档指定位置插入文本。

bash

python scripts/google-docs.py content insert DOCUMENT_ID --text "插入这段文本" --index 10

参数:

```
document_id
```
- Google Docs文档ID

选项:

```
--text
```
- 要插入的文本（必填）
```
--index
```
- 插入位置，从0开始计数（必填）
```
--json
```
- 以JSON格式输出API响应

示例:

bash

undefined

Insert text at the beginning (index 1, after title)

在文档开头（标题之后，索引1处）插入文本

python scripts/google-docs.py content insert 1abc...xyz --text "Introduction\n\n" --index 1

python scripts/google-docs.py content insert 1abc...xyz --text "简介\n\n" --index 1

Output:

输出:

✓ Text inserted successfully

✓ 文本插入成功


**Note:** Index 0 is before the document content. Index 1 is at the beginning of content.


**注意:** 索引0位于文档内容之前，索引1位于文档正文起始位置。

content delete

Delete a range of content from the document.

bash

python scripts/google-docs.py content delete DOCUMENT_ID --start-index 10 --end-index 50

Arguments:

```
document_id
```
- The Google Docs document ID

Options:

```
--start-index
```
- Start position, inclusive (required)
```
--end-index
```
- End position, exclusive (required)
```
--json
```
- Output API response as JSON

Example:

bash

undefined

删除文档中指定范围的内容。

bash

python scripts/google-docs.py content delete DOCUMENT_ID --start-index 10 --end-index 50

参数:

```
document_id
```
- Google Docs文档ID

选项:

```
--start-index
```
- 起始位置（包含，必填）
```
--end-index
```
- 结束位置（不包含，必填）
```
--json
```
- 以JSON格式输出API响应

示例:

bash

undefined

Delete characters 10-50

删除第10到50个字符

python scripts/google-docs.py content delete 1abc...xyz --start-index 10 --end-index 50

Output:

输出:

✓ Content deleted successfully

✓ 内容删除成功


**Warning:** Be careful with indices. Deleting the wrong range can corrupt document structure.


**警告:** 请谨慎使用索引。删除错误范围可能会破坏文档结构。

formatting apply

Apply text formatting to a range of text.

bash

python scripts/google-docs.py formatting apply DOCUMENT_ID \
  --start-index 1 --end-index 20 --bold --italic

Arguments:

```
document_id
```
- The Google Docs document ID

Options:

```
--start-index
```
- Start position, inclusive (required)
```
--end-index
```
- End position, exclusive (required)
```
--bold
```
- Apply bold formatting
```
--italic
```
- Apply italic formatting
```
--underline
```
- Apply underline formatting
```
--font-size SIZE
```
- Set font size in points
```
--json
```
- Output API response as JSON

Example:

bash

undefined

为指定范围的文本应用格式。

bash

python scripts/google-docs.py formatting apply DOCUMENT_ID \
  --start-index 1 --end-index 20 --bold --italic

参数:

```
document_id
```
- Google Docs文档ID

选项:

```
--start-index
```
- 起始位置（包含，必填）
```
--end-index
```
- 结束位置（不包含，必填）
```
--bold
```
- 应用粗体格式
```
--italic
```
- 应用斜体格式
```
--underline
```
- 应用下划线格式
```
--font-size SIZE
```
- 设置字体大小（单位：磅）
```
--json
```
- 以JSON格式输出API响应

示例:

bash

undefined

Make title bold and larger

将标题设置为粗体并增大字号

python scripts/google-docs.py formatting apply 1abc...xyz
--start-index 1 --end-index 20 --bold --font-size 18

Apply italic to a section

为某段文本应用斜体格式

python scripts/google-docs.py formatting apply 1abc...xyz
--start-index 50 --end-index 100 --italic

Output:

输出:

✓ Formatting applied successfully

✓ 格式应用成功

undefined

undefined

Examples

示例

Create and populate a document

创建并填充文档

bash

undefined

bash

undefined

Create a new document

创建新文档

DOC_ID=$(python scripts/google-docs.py documents create --title "Weekly Report" --json | jq -r '.documentId')

DOC_ID=$(python scripts/google-docs.py documents create --title "周报" --json | jq -r '.documentId')

Add content

添加内容

python scripts/google-docs.py content append $DOC_ID --text "Weekly Report\n\n" python scripts/google-docs.py content append $DOC_ID --text "Summary: This week's accomplishments...\n"

python scripts/google-docs.py content append $DOC_ID --text "周报\n\n" python scripts/google-docs.py content append $DOC_ID --text "摘要：本周完成的工作...\n"

Format the title

设置标题格式

python scripts/google-docs.py formatting apply $DOC_ID --start-index 1 --end-index 14 --bold --font-size 18

python scripts/google-docs.py formatting apply $DOC_ID --start-index 1 --end-index 4 --bold --font-size 18

Read it back

读取文档内容

python scripts/google-docs.py documents read $DOC_ID

undefined

python scripts/google-docs.py documents read $DOC_ID

undefined

Read and extract content

读取并提取内容

bash

undefined

bash

undefined

Get document info

获取文档信息

python scripts/google-docs.py documents get 1abc...xyz

Extract plain text

提取纯文本

python scripts/google-docs.py documents read 1abc...xyz > document.txt

Get full JSON structure

获取完整JSON结构

python scripts/google-docs.py documents get 1abc...xyz --json > document.json

undefined

python scripts/google-docs.py documents get 1abc...xyz --json > document.json

undefined

Edit existing content

编辑现有内容

bash

undefined

bash

undefined

Insert a new section

插入新章节

python scripts/google-docs.py content insert 1abc...xyz
--text "\n\nNew Section\n" --index 100

python scripts/google-docs.py content insert 1abc...xyz
--text "\n\n新章节\n" --index 100

Format the new section header

设置新章节标题格式

python scripts/google-docs.py formatting apply 1abc...xyz
--start-index 102 --end-index 113 --bold

python scripts/google-docs.py formatting apply $DOC_ID --start-index 102 --end-index 106 --bold

Append more content

追加更多内容

python scripts/google-docs.py content append 1abc...xyz
--text "Additional details about the new section..."

undefined

python scripts/google-docs.py content append $DOC_ID
--text "关于新章节的更多细节..."

undefined

Troubleshooting

故障排除

"Insufficient scope" errors

"权限范围不足"错误

You need to revoke and re-authenticate to grant additional permissions:

Go to https://myaccount.google.com/permissions
Find "Agent Skills" and remove access

Delete stored token:

keyring del agent-skills google-docs-token-json

Run
```
python scripts/google-docs.py check
```
to re-authenticate

您需要撤销权限并重新认证以获取额外权限：

访问https://myaccount.google.com/permissions撤销权限

删除存储的令牌：

keyring del agent-skills google-docs-token-json

运行
```
python scripts/google-docs.py check
```
重新认证

Cannot find document

无法找到文档

Make sure you're using the correct document ID from the URL:

URL:

https://docs.google.com/document/d/1abc...xyz/edit

Document ID:
```
1abc...xyz
```

请确保您使用的是URL中的正确文档ID：

URL:

https://docs.google.com/document/d/1abc...xyz/edit

文档ID:
```
1abc...xyz
```

Index errors when inserting/deleting

插入/删除时的索引错误

Use

documents get --json

to see the document structure and valid index ranges. Remember:

Index 0 is before any content
Index 1 is at the start of document body
The last index is the document length

使用

documents get --json

查看文档结构和有效索引范围。请记住：

索引0位于所有内容之前
索引1位于文档正文起始位置
最后一个索引等于文档长度

Dependencies not found

依赖未找到

Install required dependencies:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

安装所需依赖：

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

OAuth flow fails

OAuth流程失败

Ensure your GCP project has:

Google Docs API enabled (
```
docs.googleapis.com
```
)
OAuth 2.0 credentials created
OAuth consent screen configured
Your email added as a test user (if app is in testing mode)

See docs/gcp-project-setup.md for detailed instructions.

请确保您的GCP项目满足以下条件：

已启用Google Docs API (
```
docs.googleapis.com
```
)
已创建OAuth 2.0凭据
已配置OAuth同意屏幕
您的邮箱已添加为测试用户（如果应用处于测试模式）

详细说明请参考docs/gcp-project-setup.md。

Related Skills

API Reference

API参考

For advanced usage, see:

如需高级用法，请参考：