gas-ai-companion

GAS AI Companion

GAS 智能開發與教學助手 — Chrome Extension (Manifest V3)

直接嵌入 Google Apps Script 編輯器側邊欄，提供 AI 驅動的問答輔導與完整程式碼生成能力。

---

功能亮點

功能	說明
💬 Q&A 問答模式	白話條列解答 GAS 問題：觸發器設定、HtmlService 模板、Gmail/Drive 串接、執行記錄、JDBC 資料庫等
💻 Code 程式碼模式	依需求生成完整可執行的 GAS V8 程式碼，含繁中註解、⚠️ 標示填入變數、try/catch 錯誤處理
🔍 Diff 差異預覽	程式碼插入前逐行對比現有程式，確認後才寫入，支援 Ctrl+Z 復原
📄 HTML 模板支援	自動偵測 .html / .gs 檔案，切換語法高亮與 AI 的 HtmlService scriptlet 知識
⚡ Monaco 直接注入	讀取/寫入 GAS Monaco Editor，支援「替換整個檔案」與「貼到游標位置」兩種模式
📚 獨立對話歷史	Q&A / Code 各有獨立歷史，按檔案分離；支援單筆刪除與批次管理
🎨 雙模式視覺區隔	Q&A 藍色系 / Code 綠色系，聊天區背景、傳送按鈕、輸入框同步配色
🔒 本機安全儲存	API Key 僅存於 chrome.storage.local，不經任何第三方伺服器

---

技術架構

Chrome Extension Manifest V3
├── background.js          Service Worker：RELAY_GET_CODE / RELAY_SET_CODE / RELAY_INSERT_AT_CURSOR
│                          chrome.scripting.executeScript (MAIN world) 直接存取 window.monaco
├── content.js             Content Script（佔位用；所有 Monaco 邏輯在 background.js）
├── sidepanel.html/js/css  側邊欄 UI
│   ├── Tailwind CSS        本機化（MV3 CSP）
│   ├── marked.min.js       Markdown 渲染
│   └── highlight.min.js    程式碼語法高亮（GitHub Dark 主題）
├── 128.png                128×128 PNG 圖示（Chrome Web Store 要求）
└── icons/                 SVG 圖示（16 / 48px）

LLM： Google Gemini gemini-2.5-flash（SSE 串流端點，需 Google AI Studio API Key）

---

安裝方式

1. 取得 Gemini API Key

前往 Google AI Studio 建立免費 API Key（AIzaSy...）。

2. 載入 Chrome 擴充功能

1. 開啟 Chrome，前往 chrome://extensions
2. 右上角開啟「開發人員模式」
3. 點擊「載入未封裝項目」
4. 選擇本專案資料夾（含 manifest.json 的根目錄）

3. 初次設定

1. 前往 script.google.com 開啟任意 GAS 專案
2. 點擊工具列擴充功能圖示 → 側邊欄開啟
3. 輸入 Gemini API Key → 點擊「驗證並開始使用」
4. 完成！即可切換 Q&A 或 Code 模式開始對話

---

使用說明

雙模式切換

	Q&A 模式 💬	Code 模式 💻
用途	問答、解釋、操作步驟引導	生成完整可執行程式碼
配色	藍色系	綠色系
程式碼輸出	僅 3–8 行短片段輔助說明	完整函式 + 使用步驟
歷史	獨立（按檔案）	獨立（按檔案）

插入程式碼

Code 模式下，AI 回應的程式碼區塊右側提供：

• 複製 — 複製到剪貼簿
• 插入編輯器 — 開啟 Diff 差異預覽 → 選擇「替換整個檔案」或「貼到游標位置」

HTML 模板檔案

切換至 GAS 專案中的 .html 檔案時，AI 會自動：

• 以 html 語法高亮顯示程式碼
• 切換到 HtmlService / Scriptlet 知識模式（<? ?>、<?= ?>、<?!= ?>、google.script.run）
• 跳過對 HTML 的括號平衡檢查（避免誤報）

快速操作按鈕

Q&A 模式	Code 模式
解釋程式碼	加說明標示
找 Bug	優化效能
設觸發器	加錯誤處理
錯誤分析	重新生成

重新生成：刪除前一輪 AI 回覆，以相同問題重新送出（非追加新對話）。

管理對話歷史

• Hover 任一對話 → 右上角出現 ×，點擊立即刪除
• 點擊模式指示列右側「管理」→ 進入選取模式 → 批次刪除
• 清除全部：頂部垃圾桶圖示

多檔案上下文

點擊模式列的「📁」按鈕，勾選專案中其他 .gs / .html 檔案名稱，提供給 AI 作為背景資訊（跨檔案函式呼叫關係）。

---

AI 知識涵蓋範圍（Q&A 模式）

GAS 核心

• Spreadsheet / Sheet / Range 操作
• getValues() / setValues() 批次讀寫（效能最佳實踐）
• SpreadsheetApp vs openById() 使用時機

HTML 模板

• HtmlService.createTemplateFromFile() / createHtmlOutputFromFile()
• Scriptlet 語法：<? ?>、<?= ?>、<?!= ?>
• google.script.run 前端呼叫後端函式
• 側邊欄、對話框、網頁應用程式部署（doGet / doPost）

觸發器

• 簡單觸發器（onOpen / onEdit / onFormSubmit）vs 可安裝觸發器差異
• 時間驅動設定（everyMinutes / everyHours / everyDays）
• 觸發器上限（20 個/專案）、授權層級、無法取得使用者身份等陷阱

執行記錄

• Logger.log() vs console.log() 在觸發器中的差異
• Google Cloud Logging 查看方式
• 執行記錄在 GAS IDE 中的查看路徑

Google Workspace 服務串接

Gmail、Google Drive、Google 日曆、Google 文件、Google 表單、Google 幻燈片、Admin SDK

外部 API 與資料庫

• UrlFetchApp.fetch() — HTTP 請求（GET / POST / 自訂 headers）
• Firebase REST API 整合
• JDBC（Cloud SQL / MySQL）連線
• PropertiesService 儲存設定（替代全域變數）
• ScriptApp.getOAuthToken() 取得 OAuth token

配額限制

UrlFetchApp 20,000 次/日（免費）、Email 100 封/日、執行時間 6 分鐘上限等

---

開發筆記

Cross-World 架構

GAS 編輯器使用的 Monaco Editor 僅存在於頁面的 MAIN world（window.monaco）。 Content Script 執行於隔離的 Isolated World，無法存取頁面全域變數。

解決方案：所有 Monaco 操作透過 background.js 的 chrome.scripting.executeScript({ world: 'MAIN' }) 執行：

// sidepanel.js → background.js → Monaco (MAIN world)
chrome.runtime.sendMessage({ type: 'RELAY_GET_CODE' });
// background.js 接收後：
chrome.scripting.executeScript({
  target: { tabId },
  world: 'MAIN',
  func: () => window.monaco?.editor?.getEditors?.()?.[0]?.getValue()
});

Gemini SSE 串流

使用 streamGenerateContent?alt=sse 端點，token 逐步顯示：

const res = await fetch(
  `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?key=${key}&alt=sse`,
  { method: 'POST', body: JSON.stringify({ system_instruction, contents, generationConfig }) }
);
// ReadableStream 逐 chunk 解析 SSE events

429 Rate Limit 處理

最多自動重試 3 次，每次等待 15 秒倒數：

async function callGemini(userMessage, retryCount = 0) {
  // ...
  if (res.status === 429) {
    if (retryCount >= 3) { /* 顯示錯誤，停止重試 */ return; }
    for (let remaining = 15; remaining > 0; remaining--) {
      noteContent.textContent = `☕ API 流量限制，${remaining} 秒後自動重試（第 ${retryCount + 1}/3 次）...`;
      await new Promise(r => setTimeout(r, 1000));
    }
    state.isLoading = false;
    return await callGemini(userMessage, retryCount + 1);
  }
}

Content Security Policy (MV3)

所有 CDN 依賴已下載至 lib/ 本機目錄，不使用任何外部 URL：

<!-- ✅ 正確 -->
<link rel="stylesheet" href="lib/tailwind.min.css">
<script src="lib/marked.min.js"></script>

<!-- ❌ MV3 CSP 封鎖 -->
<script src="https://cdn.tailwindcss.com"></script>

Token 優化

相同程式碼不重複傳送，改以函式清單摘要節省 token：

// 程式碼未變動時
contextualMessage = `【程式碼】: 同本對話前一則，內容未變動\n函式：${functions.join('、')}`;
// 程式碼有變動時，完整傳送
contextualMessage = `【程式碼內容】:\n\`\`\`javascript\n${code}\n\`\`\``;

---

隱私聲明

• API Key 僅儲存於瀏覽器本機（chrome.storage.local），不傳送至任何第三方
• 當前編輯器中的程式碼會傳送至 Google Gemini API 進行分析
• 請勿在程式碼中包含密碼、憑證或機敏商業邏輯

---

版本紀錄

版本	日期	說明
1.1.0	2026-04-12	HTML 模板檔案支援、雙模式視覺區隔（藍/綠配色）、Q&A 全面補入 GAS 生態系知識（觸發器/HtmlService/Gmail/JDBC 等）、修復「重新生成」按鈕、429 重試上限（最多 3 次）、插入後游標保留、首次使用 📁 按鈕修復、歷史訊息解析優化
1.0.0	2026-04-06	初始版本：Q&A / Code 雙模式、SSE 串流、Monaco 直接注入、Diff 差異預覽、獨立對話歷史、批次歷史管理、多檔案上下文

---

License

MIT License — 自由使用、修改與散佈。