Google Docs（云端文档技能）

通过 Maton 管理的 OAuth 认证访问 Google Docs API。创建、读取、更新、格式化以及批量编辑 Google 云端文档。

⚠️ 云文档与本地文件范围区分：

google-docs（本技能）：专用于在线 Google Docs 云文档（docs.google.com/document/d/{documentId}）。通过 Maton OAuth API 代理直接与 Google 云服务器交互。

docx 技能：用于读取、创建或编辑存储在本地磁盘上的本地 .docx / .doc 文件。

快速开始

命令行：

# 获取文档结构和文本内容
maton google-docs document get <documentId>

# 创建新的 Google 文档
maton google-docs document create --title '项目架构规范'

# 向文档正文追加文本
maton google-docs document write <documentId> --text '会议记录：关于 Q3 路线图的讨论。'

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://api.maton.ai/google-docs/{native-api-path}

Maton 代理请求至 docs.googleapis.com 并自动注入您的 OAuth 令牌。

CLI 安装（可选——智能体决定）

Maton CLI 是可选的。智能体可根据环境决定是否安装。

macOS / Linux

curl -fsSL https://maton.ai/install.sh | bash

Windows

irm https://maton.ai/install.ps1 | iex

npm（跨平台）

npm install -g @maton/cli

Homebrew（macOS）

brew install maton-ai/cli/maton

安装后，验证：

maton --version

身份验证

命令行：

maton login                          # 打开浏览器获取 API 密钥
maton login --interactive            # 跳过浏览器，直接粘贴 API 密钥
maton whoami                         # 显示当前身份验证状态

手动：

在 maton.ai 登录或创建账户
访问 maton.ai/settings
复制您的 API 密钥
将 API 密钥设置为环境变量 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

连接管理

在 https://api.maton.ai 管理您的 Google Docs OAuth 连接。

列出连接

命令行：

maton connection list google-docs --status ACTIVE

maton api -X GET /connections -f app=google-docs -f status=ACTIVE

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=google-docs&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

命令行：

maton connection create google-docs

maton api /connections -f app=google-docs

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-docs'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-docs"
  }
}

在浏览器中打开返回的 url 以完成 OAuth 授权。

获取连接

命令行：

maton connection get {connection_id}                 # 别名：maton connection view

maton api /connections/{connection_id}

删除连接

命令行：

maton connection delete {connection_id} --yes

maton api -X DELETE /connections/{connection_id}

指定连接

如果您有多个 Google Docs 连接，请指定使用哪一个：

命令行：

maton google-docs document get <documentId> --connection {connection_id}

maton api /google-docs/v1/documents/<documentId> --connection {connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果您有多个连接，请始终指定连接以确保请求路由到预期的账户。

安全与权限

访问范围限定在已连接 Google 账户内的 Google Docs。
所有写入和删除操作都需要明确的用户批准。 在执行前，请与用户确认目标资源 ID 和内容修改。

API 参考

1. 获取文档

检索完整的文档对象，包括标题、结构元素、内联对象和段落样式。

GET /google-docs/v1/documents/{documentId}

查询参数：

suggestionsViewMode - DEFAULT_FOR_CURRENT_ACCESS、PREVIEW_APPROVED、PREVIEW_WITHOUT_SUGGESTIONS、SUGGESTIONS_INLINE。

命令行示例：

maton google-docs document get <documentId>
maton google-docs document get <documentId> --json

2. 创建空白文档

创建一个新的空白 Google 文档，并指定标题。

POST /google-docs/v1/documents
Content-Type: application/json

{
  "title": "季度技术审查"
}

命令行示例：

maton google-docs document create --title '季度技术审查'

3. 将纯文本追加到文档

通过命令行将纯文本追加到文档正文末尾。

命令行示例：

# 直接文本
maton google-docs document write <documentId> --text '你好，世界！'

# 从文件读取
maton google-docs document write <documentId> -F notes.md

# 从标准输入管道
echo '管道汇总' | maton google-docs document write <documentId> -F -

4. 批量更新文档内容和结构（富格式）

对文档文本、格式、段落样式、页眉/页脚和内联表格执行原子化变更。

POST /google-docs/v1/documents/{documentId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "执行摘要\n\n本文档概述了我们的云迁移策略。"
      }
    }
  ]
}

命令行示例：

maton api -X POST /google-docs/v1/documents/<documentId>:batchUpdate \
  -d '{"requests":[{"insertText":{"location":{"index":1},"text":"Hello World\n"}}]}'

`batchUpdate` 的常见请求类型：

insertText：在指定索引位置插入文本。
deleteContentRange：删除指定 range（startIndex 和 endIndex）内的内容。

replaceAllText：在文档正文中全局搜索并替换文本。

{
  "replaceAllText": {
    "containsText": {
      "text": "{{PROJECT_NAME}}",
      "matchCase": true
    },
    "replaceText": "SoloQueue v2.0"
  }
}

updateTextStyle：对指定范围应用粗体、斜体、字体大小或颜色格式。
updateParagraphStyle：应用标题样式（HEADING_1、HEADING_2、NORMAL_TEXT）。

从文档结构中提取纯文本

Google Docs API 将内容返回在 body.content 中作为结构元素。通过 Python 读取文档的纯文本：

import os, json, urllib.request

req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
doc = json.load(urllib.request.urlopen(req))

text_chunks = []
for element in doc.get('body', {}).get('content', []):
    if 'paragraph' in element:
        for elem in element['paragraph'].get('elements', []):
            if 'textRun' in elem:
                text_chunks.append(elem['textRun'].get('content', ''))

print("".join(text_chunks))

代码示例

命令行

# 创建文档
maton google-docs document create --title '冲刺规划'

# 向文档写入初始笔记
maton google-docs document write <documentId> --text '冲刺 42 目标：\n- 启动身份验证\n- 速度测试'

# 以 JSON 格式检查文档结构
maton google-docs document get <documentId> --json

JavaScript

// 获取文档元数据和内容
const response = await fetch(
  'https://api.maton.ai/google-docs/v1/documents/<documentId>',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const doc = await response.json();
console.log(doc.title);

// 创建新文档
const createResponse = await fetch(
  'https://api.maton.ai/google-docs/v1/documents',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'RFC: AI 技能网关'
    })
  }
);
const newDoc = await createResponse.json();
console.log('创建的文档 ID:', newDoc.documentId);

Python

import os
import requests

# 获取文档
response = requests.get(
    'https://api.maton.ai/google-docs/v1/documents/<documentId>',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
doc = response.json()
print(doc.get('title'))

# 创建文档
create_response = requests.post(
    'https://api.maton.ai/google-docs/v1/documents',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'title': 'RFC: AI 技能网关'}
)
print('创建的文档 ID:', create_response.json().get('documentId'))

注意事项

文档 ID 是不透明的字符串（从 URL https://docs.google.com/document/d/<documentId>/edit 中提取）。
maton google-docs document write 将纯文本追加到文档正文末尾。如需在特定索引处插入文本、替换文本或应用标题/粗体样式，请使用 batchUpdate。
重要提示：使用 curl 命令时，如果 URL 包含方括号，请使用 curl -g 以禁用通配符解析。
重要提示：将 curl 输出通过管道传递给 jq 或其他命令时，环境变量（如 $MATON_API_KEY）在某些 shell 环境中可能无法正确展开。您可能会在管道操作时遇到“无效 API 密钥”错误。

错误处理

状态码	含义
400	缺少 Google Docs 连接或请求负载格式错误
401	无效或缺失 Maton API 密钥
404	Google Doc ID 未找到或访问被拒绝
429	超过速率限制
5xx	Google Docs API 后端错误

故障排除：API 密钥问题

命令行：

maton whoami
maton connection list google-docs

手动：

echo $MATON_API_KEY
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

确保您的 URL 路径以 google-docs 开头。例如：

正确：https://api.maton.ai/google-docs/v1/documents/<documentId>
错误：https://api.maton.ai/docs/v1/documents/<documentId>

在你喜欢的 AI 中提问

文档

Google Docs（云端文档技能）

快速开始

基础 URL

CLI 安装（可选——智能体决定）

macOS / Linux

Windows

npm（跨平台）

Homebrew（macOS）

身份验证

连接管理

列出连接

创建连接

获取连接

删除连接

指定连接

安全与权限

API 参考

1. 获取文档

2. 创建空白文档

3. 将纯文本追加到文档

4. 批量更新文档内容和结构（富格式）

batchUpdate 的常见请求类型：

从文档结构中提取纯文本

代码示例

命令行

JavaScript

Python

注意事项

错误处理

故障排除：API 密钥问题

故障排除：无效的应用名称

资源

相关技能

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7

`batchUpdate` 的常见请求类型：