新增 Google Docs tab 存取 library 的一些心得

今天把 Google Docs 的 tab 操作整理成一套可重複用的 library，也順手整理了三支 script：

• google_docs_tab_write.py
• google_docs_update_four_tabs.py
• google_docs_create_tab_mvt.py

這套工具主要只用 Python 標準庫（urllib / json / argparse / pathlib / tempfile，加上 subprocess）。

起因很實際：同一份文件有多個 tab，每天又要固定更新四塊內容（最近行程 / AI 新聞 / 美股 / 台股），手動貼上很容易貼錯、漏貼，最後還要回頭對帳。

---

先試 OpenClaw + gog（我原本最想走的路）

一開始我先試的是 OpenClaw + gog，因為這條路最快、維護成本也最低。對「單份文件、單一主體內容」來說，gog docs write 很好用。

但做到多 tab 後，問題就出來了：當時 gog docs write 不能指定要寫哪個 tab。也就是說，我可以寫進文件，但不能精準控制「寫進哪一個 tab」。

這個限制對自動化是致命的：一旦不能保證寫入位置，就不能放心交給排程。

---

為什麼我最後改走 Google Docs API

我最後的判斷很單純：需求核心是「指定 tab 寫入 + 批次更新 + 出錯可追」，那就要能直接控制 API request 與 tab 身分。CLI 做不到，就切 API。

這裡有兩個很容易混在一起的參數，我這次特別釐清來源：

• includeTabsContent=true：這是 Google Docs API 的 documents.get query 參數。沒帶這個，拿到的 tab 資訊會不完整，後續就很難穩定定位目標 tab。
• --continue-on-error：這是 我自己包的 wrapper script CLI 參數，不是 Google Docs API 內建欄位。用途是四 tab 批次更新時，某一個失敗不要整批中止，方便先跑完再補救。

前因後果就是：先遇到 CLI 無法指定 tab 的邊界，再往下拆成「API 層該帶什麼」與「腳本層該怎麼控流程」兩件事，最後才變成現在這套。

---

最終方案（現在怎麼做）

• 讀文件：用 Google Docs API documents.get，並帶 includeTabsContent=true 取得完整 tab 資訊。
• 寫內容：以 tabId 當主要定位鍵，執行 replace / append。
• 批次更新：四個 tab 一次處理，支援 --continue-on-error，每個 tab 各自回報結果。
• 補建 tab：若目標 tab 不存在，就先建立再寫入，避免流程卡死。

這樣做的好處是：流程可預期、錯誤可定位、排程可穩定跑。

---

如果用 curl 打 Google Docs API 會長怎樣

下面放兩個最小可讀範例，重點是先看懂 request 形狀，不先陷入太多細節。

1) 讀文件（documents.get，帶 includeTabsContent=true）：

curl -sS \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://docs.googleapis.com/v1/documents/$DOC_ID?includeTabsContent=true"

2) 寫入內容（documents.batchUpdate，這裡示範 insertText）：

curl -sS -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://docs.googleapis.com/v1/documents/$DOC_ID:batchUpdate" \
  -d '{
    "requests": [
      {
        "insertText": {
          "location": {
            "tabId": "TAB_ID",
            "index": 1
          },
          "text": "Hello from curl\\n"
        }
      }
    ]
  }'

實務上我在 Python 裡做的事，就是把上面這兩種 request 包成可重複呼叫的流程，讓 tab 更新可以穩定跑。

---

我怎麼判斷要不要自己寫工具

我目前用這 4 個準則：

1. 核心需求是否被工具卡住：像這次「指定 tab 寫入」是核心需求，不是 nice-to-have，被卡就要換路。
2. workaround 會不會變技術債：如果要靠一堆人工步驟或脆弱腳本補洞，長期一定更貴。
3. 失誤成本高不高：寫錯 tab 會直接影響每日產出，錯誤成本高就值得投資穩定化。
4. 是否會重複發生：每天都要跑、每週都會用，自己做一層抽象通常划算。

簡單說：CLI 能穩定解決 80% 而且不痛，就繼續用；一旦核心流程被卡住、又會反覆發生，就別硬撐，直接做自己的工具層。

---

實際使用範例

列出文件裡所有 tab：

python3 scripts/google_docs_tab_write.py \
  --doc-id <DOC_ID> \
  --list-tabs

指定 tab 寫入（replace）：

python3 scripts/google_docs_tab_write.py \
  --doc-id <DOC_ID> \
  --tab-title "最近行程" \
  --file /tmp/recent.txt \
  --mode replace

一次更新四個 tab（可選擇遇錯是否繼續）：

python3 scripts/google_docs_update_four_tabs.py \
  --doc-id <DOC_ID> \
  --recent-file /tmp/recent.txt \
  --ai-news-file /tmp/ai_news.txt \
  --us-stock-file /tmp/us_stock.txt \
  --tw-stock-file /tmp/tw_stock.txt \
  --mode replace \
  --continue-on-error

---

小結

這次最大的收穫不是「多寫了幾支 script」，而是把決策順序走清楚：先用現成工具（OpenClaw + gog）驗證需求，再在關鍵邊界切到 API，最後把重複工作包成可維護的流程。

對我來說，這比單次把任務做完更重要，因為它決定了之後每天跑起來會不會穩。