Fize/workspace-kit

Google Docs（雲端文件技能）

透過 Maton 管理的 OAuth 認證，存取 Google Docs API。建立、讀取、更新、格式化及批次編輯 Google Docs 雲端文件。

⚠️ 雲端與本機檔案範圍區別：

• google-docs（此技能）：僅適用於線上 Google Docs 雲端文件（docs.google.com/document/d/{documentId}）。透過 Maton OAuth API 代理直接與 Google 雲端伺服器互動。
• docx 技能：用於讀取、建立或編輯儲存在本機磁碟的本機 .docx / .doc 檔案。

---

快速開始

命令列介面 (CLI)：

# 取得文件結構與文字內容
maton google-docs document get <documentId>

# 建立新的 Google Doc
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

---

認證

命令列介面 (CLI)：

maton login                          # 開啟瀏覽器獲取 API 金鑰
maton login --interactive            # 跳過瀏覽器，直接貼上 API 金鑰
maton whoami                         # 顯示目前認證狀態

手動操作：

1. 在 maton.ai 登入或建立帳戶
2. 前往 maton.ai/settings
3. 複製您的 API 金鑰
4. 將 API 金鑰設為 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

---

連線管理

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

列出連線

命令列介面 (CLI)：

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

建立連線

命令列介面 (CLI)：

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 授權。

取得連線

命令列介面 (CLI)：

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

maton api /connections/{connection_id}

刪除連線

命令列介面 (CLI)：

maton connection delete {connection_id} --yes

maton api -X DELETE /connections/{connection_id}

指定連線

如果您有多個 Google Docs 連線，請指定要使用哪一個：

命令列介面 (CLI)：

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。

範例 CLI：

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

---

2. 建立空白文件

建立一個指定標題的新空白 Google Doc。

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

{
  "title": "季度技術審查"
}

範例 CLI：

maton google-docs document create --title '季度技術審查'

---

3. 在文件末尾附加純文字

透過 CLI 將純文字附加到文件結尾。

範例 CLI：

# 直接文字
maton google-docs document write <documentId> --text 'Hello, world!'

# 從檔案讀取
maton google-docs document write <documentId> -F notes.md

# 從標準輸入 pipe
echo 'Piped summary' | 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本文件概述我們的雲端遷移策略。"
      }
    }
  ]
}

範例 CLI：

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

batchUpdate 的常見請求類型：

1. insertText：在指定索引位置插入文字。
2. deleteContentRange：刪除指定 range（startIndex 和 endIndex）內的內容。
3. replaceAllText：在整個文件正文中進行全域搜尋與取代。

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

4. updateTextStyle：對指定範圍套用粗體、斜體、字型大小或顏色格式。
5. 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))

---

程式碼範例

CLI

# 建立文件
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('已建立：', create_response.json().get('documentId'))

---

備註

• 文件 ID 為不透明字串（從網址 https://docs.google.com/document/d/<documentId>/edit 中提取）。
• maton google-docs document write 會將純文字附加到文件結尾。如需在特定索引插入文字、取代文字或套用標題/粗體樣式，請使用 batchUpdate。
• 重要：使用 curl 指令時，若網址包含方括號，請使用 curl -g 以停用 glob 解析。
• 重要：將 curl 輸出 pipe 至 jq 或其他指令時，$MATON_API_KEY 等環境變數在某些 shell 環境中可能無法正確展開。在 pipe 時，您可能會收到「無效的 API 金鑰」錯誤。

---

錯誤處理

狀態	意義
400	缺少 Google Docs 連線或請求格式錯誤
401	無效或遺失的 Maton API 金鑰
404	Google Doc ID 未找到或存取遭拒
429	超出速率限制
5xx	Google Docs API 後端錯誤

疑難排解：API 金鑰問題

命令列介面 (CLI)：

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

疑難排解：應用程式名稱無效

1. 確保您的 URL 路徑以 google-docs 開頭。例如：

• 正確：https://api.maton.ai/google-docs/v1/documents/<documentId>
• 錯誤：https://api.maton.ai/docs/v1/documents/<documentId>

---

資源

• Google Docs REST API v1 文件
• Google Docs 批次更新參考
• Maton CLI Google Docs 手冊
• Maton 社群
• Maton 支援