mcpField
G
google-docs

google-docs

github.com/odyssey4me文档处理13262 次安装1 天前更新
代码仓库

关于 google-docs

google-docs 是用于创建、读取、导入和编辑 Google Docs 的命令行技能。它支持保留格式的 Markdown 导入及本地图片嵌入，并提供 OAuth 设置和文档检查功能。

主要功能

  1. 01创建和查看文档
  2. 02读取为 Markdown 或 PDF
  3. 03按格式导入 Markdown
  4. 04插入、删除和追加内容
  5. 05应用文本格式
  6. 06管理 OAuth 身份验证

适用场景

  1. 01创建并填写新文档
  2. 02将文档导出为 PDF
  3. 03导入带格式的 Markdown 报告
  4. 04更新现有文档的章节

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/odyssey4me/agent-skills --skill google-docs

安装后在 Claude Code 中输入/google-docs确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
formatting-guide.md
permissions.md
scripts/
google-docs.py

详细介绍

Google Docs

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

安装

依赖项：pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml markdown-it-py

设置验证

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

$SKILL_DIR/scripts/google-docs.py check

此操作将检查：

  • Python 依赖项（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml、markdown-it-py）
  • 身份验证配置
  • 与 Google Docs API 的连通性

如果缺少任何内容，检查命令会提供设置说明。

身份验证

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

  1. GCP 项目设置指南 - 创建项目并启用 Docs API
  2. Google OAuth 设置指南 - 配置凭据
快速开始

  1. 创建 ~/.config/agent-skills/google.yaml：

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

  2. 运行 $SKILL_DIR/scripts/google-docs.py check 以触发 OAuth 流程并验证设置。

如果遇到范围或身份验证错误，请参阅 OAuth 故障排除指南。

命令

每条命令的读写分类请参阅 permissions.md。

check

验证配置和连通性。

$SKILL_DIR/scripts/google-docs.py check

此操作会验证：

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

为自定义 OAuth 流程保存 OAuth 2.0 客户端凭据。

$SKILL_DIR/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 客户端密钥（必需）
auth reset

清除已保存的 OAuth 令牌。下一个需要身份验证的命令会自动触发重新身份验证。

$SKILL_DIR/scripts/google-docs.py auth reset

遇到范围或身份验证错误时，请使用此命令。

auth status

显示当前 OAuth 令牌信息，不会调用 API。

$SKILL_DIR/scripts/google-docs.py auth status

显示内容：是否已保存令牌、已授予的范围、是否存在刷新令牌、令牌过期时间以及客户端 ID。

documents create

创建一个新的空白 Google Docs 文档。

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

选项：

  • --title - 文档标题（必需）

示例：

# Create a new document
$SKILL_DIR/scripts/google-docs.py documents create --title "Project Notes"

# Output:
# ✓ Document created successfully
#   Title: Project Notes
#   Document ID: 1abc...xyz
#   URL: https://docs.google.com/document/d/1abc...xyz/edit
documents get

获取文档元数据和结构。

$SKILL_DIR/scripts/google-docs.py documents get DOCUMENT_ID

参数：

  • document_id - Google Docs 文档 ID

示例：

# Get document metadata
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz

# Output:
# Title: Project Notes
# Document ID: 1abc...xyz
# Characters: 1234
# Revision ID: abc123
documents read

将文档内容读取为纯文本、Markdown 或 PDF。

$SKILL_DIR/scripts/google-docs.py documents read DOCUMENT_ID

参数：

  • document_id - Google Docs 文档 ID

选项：

  • --format - 输出格式：markdown（默认，会保留表格和标题）或 pdf
  • --output、-o - 输出文件路径（与 pdf 格式搭配使用）

示例：

# Read as markdown (default, preserves tables and headings)
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz

# Export as PDF
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz --format pdf --output document.pdf

# Output as markdown:
# # Heading
#
# This is a paragraph.
#
# | Column 1 | Column 2 |
# |----------|----------|
# | Value 1  | Value 2  |

注意： Markdown 和 PDF 导出使用 Google 原生 Drive API 导出功能。Markdown 能够高保真地保留表格、标题、格式和结构。两种格式都需要 drive.readonly 范围。

documents import

将本地 Markdown 文件导入为原生格式的 Google 文档。使用 Drive API 的 HTML 转 Docs 转换功能，完整保留 Markdown 格式，包括表格、代码块、标题、粗体、斜体、链接和列表。

$SKILL_DIR/scripts/google-docs.py documents import FILE_PATH [--title TITLE] [--document-id DOC_ID] [--folder-id ID]

参数：

  • file_path - Markdown 文件的本地路径

选项：

  • --title - 文档标题（默认为第一个 H1 标题或文件名）
  • --document-id - 要更新的现有文档 ID（替换内容）
  • --folder-id - 新建文档的父文件夹 ID
  • --no-format - 跳过导入后的格式设置
  • --no-images - 跳过嵌入本地图片
  • --json - 以 JSON 格式输出

示例：

# Import a markdown file as a new Google Doc
$SKILL_DIR/scripts/google-docs.py documents import ./report.md --title "Monthly Report"

# Import using the first H1 heading as the title
$SKILL_DIR/scripts/google-docs.py documents import ./notes.md

# Update an existing document with new markdown content
$SKILL_DIR/scripts/google-docs.py documents import ./updated.md --document-id 1abc...xyz

# Import without post-import formatting
$SKILL_DIR/scripts/google-docs.py documents import ./raw.md --no-format

# Import without embedding images
$SKILL_DIR/scripts/google-docs.py documents import ./doc.md --no-images

图片： Markdown 中的本地图片引用（![alt text](path/to/image.png)）会自动嵌入 Google 文档，并保留其原始位置。路径会相对于 Markdown 文件所在目录进行解析。不支持基于 URL 的图片（![alt](https://...)），此类图片会被忽略。使用 --no-images 可跳过图片处理。

Frontmatter： 导入前会从 Markdown 中移除 YAML frontmatter（以 --- 分隔），不会将其包含在 Google 文档内容中。支持以下 frontmatter 字段：

  • title — 文档标题（可由 --title 标志覆盖）
  • folder_id — 父文件夹 ID（可由 --folder-id 标志覆盖）
  • line_spacing — 行距百分比（默认值：115）
  • space_below — 段落后间距，单位为 pt（默认值：8）
  • pageless — 设为 true 可启用无分页模式
---
title: My Document
line_spacing: 130
space_below: 10
---

格式设置完成后，会输出可读性摘要，显示标题、段落和列表项的数量。

注意： 需要 markdown-it-py Python 库，以及 drive.file 和 documents 权限范围。

另请参阅： 如需将文件（非 Markdown）上传到 Google Drive、共享文件、整理文件夹或导出文档，请使用 google-drive 技能。

content append

在文档末尾追加文本。

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

参数：

  • document_id - Google 文档 ID

选项：

  • --text - 要追加的文本（必需）

示例：

# Append text
$SKILL_DIR/scripts/google-docs.py content append 1abc...xyz --text "Meeting notes from today..."

# Output:
# ✓ Text appended successfully
content insert

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

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

参数：

  • document_id - Google 文档 ID

选项：

  • --text - 要插入的文本（必需）
  • --index - 插入位置，从 0 开始计数（必需）

示例：

# Insert text at the beginning (index 1, after title)
$SKILL_DIR/scripts/google-docs.py content insert 1abc...xyz --text "Introduction\n\n" --index 1

# Output:
# ✓ Text inserted successfully

注意： 索引 0 表示位于文档内容之前。索引 1 表示位于内容开头。

content delete

删除文档中的一段内容。

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

参数：

  • document_id - Google 文档 ID

选项：

  • --start-index - 起始位置，包含此位置（必需）
  • --end-index - 结束位置，不包含此位置（必需）

示例：

# Delete characters 10-50
$SKILL_DIR/scripts/google-docs.py content delete 1abc...xyz --start-index 10 --end-index 50

# Output:
# ✓ Content deleted successfully

警告： 请谨慎处理索引。删除错误的范围可能会破坏文档结构。

content insert-after-anchor

在文档中的结构锚点（水平分隔线、标题或书签）之后插入 Markdown 格式的内容。一次操作即可处理文本插入、标题样式、项目符号列表、粗体格式和链接。

$SKILL_DIR/scripts/google-docs.py content insert-after-anchor DOCUMENT_ID \
  --anchor-type ANCHOR_TYPE --markdown "MARKDOWN_CONTENT"

参数：

  • document_id - Google 文档 ID

选项：

  • --anchor-type - 要查找的锚点类型：horizontal_rule、heading 或 bookmark（必需）
  • --anchor-value - 锚点对应的值：标题文本（用于 heading）、书签 ID（用于 bookmark）或出现序号（用于 horizontal_rule，默认为 1）
  • --markdown - 要插入的 Markdown 格式内容（必需）。使用 \n 表示换行。

支持的 Markdown 语法：

语法结果
## Heading标题（级别 1-6）
**text**粗体文本
[text](url)超链接
- item项目符号列表
- item嵌套项目符号（每层缩进 2 个空格）

示例：

# Insert after the first horizontal rule
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type horizontal_rule \
  --markdown '## Status Update\n\n**Summary:**\n- Task completed\n  - Sub-task done\n- [Details](https://example.com)'

# Insert after a specific heading
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type heading \
  --anchor-value "Notes" \
  --markdown '- New note item\n- Another item'

# Insert after the second horizontal rule
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type horizontal_rule \
  --anchor-value 2 \
  --markdown '## New Section\n\nParagraph text here.'
应用格式

对一段文本应用格式。

$SKILL_DIR/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 - 设置字号（磅）

示例：

# Make title bold and larger
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
  --start-index 1 --end-index 20 --bold --font-size 18

# Apply italic to a section
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
  --start-index 50 --end-index 100 --italic

# Output:
# ✓ Formatting applied successfully

示例

创建并填充文档
# Create a new document
$SKILL_DIR/scripts/google-docs.py documents create --title "Weekly Report"

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

# Format the title
$SKILL_DIR/scripts/google-docs.py formatting apply $DOC_ID --start-index 1 --end-index 14 --bold --font-size 18

# Read it back
$SKILL_DIR/scripts/google-docs.py documents read $DOC_ID
读取并提取内容
# Get document info
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz

# Extract plain text
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz > document.txt

# Get document structure
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz
在锚点后插入带格式的内容
# Insert a formatted status update after a horizontal rule
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor $DOC_ID \
  --anchor-type horizontal_rule \
  --markdown '## Weekly Update\n\n**Completed:**\n- Feature implementation\n  - Backend API\n  - Frontend UI\n- [Project board](https://example.com/board)'
编辑现有内容
# Insert a new section
$SKILL_DIR/scripts/google-docs.py content insert 1abc...xyz \
  --text "\n\nNew Section\n" --index 100

# Format the new section header
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
  --start-index 102 --end-index 113 --bold

# Append more content
$SKILL_DIR/scripts/google-docs.py content append 1abc...xyz \
  --text "Additional details about the new section..."

错误处理

身份验证和权限范围错误不可重试。 如果命令因身份验证错误、权限范围不足错误或权限被拒绝错误（退出代码 1）而失败，请停止并告知用户。不要重试，也不要尝试自行解决问题——这些错误需要用户交互（基于浏览器的 OAuth 授权）。请引导用户查看 OAuth 故障排除指南。

可重试错误：速率限制（HTTP 429）和临时服务器错误（HTTP 5xx）在短暂等待后重试可能会成功。其他所有错误都应报告给用户。

模型指南

此技能需要进行 API 调用，并要求使用结构化输入/输出。建议使用具备标准能力的模型。

故障排除

找不到文档

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

  • URL：https://docs.google.com/document/d/1abc...xyz/edit
  • 文档 ID：1abc...xyz
插入/删除时出现索引错误

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

  • 索引 0 位于所有内容之前
  • 索引 1 位于文档正文的开头
  • 最后一个索引是文档长度

API 参考

如需高级用法，请参阅：

评论

支持 Markdown