整個農曆假期, 刻意不碰什麼 AI Coding, 龍蝦什麼的. 身心靈獲得徹底放鬆,

這幾年最大的體認是, 與其拿來跟 AI 不斷的對話, 奮戰, 寫扣 (過去數十年的跨年, 我好像也都還在 commit code) , 沒什麼一定要放棄掉與家人僅有的相處時間, 尤其是, 連續假期親朋好友也都剛好處於放假模式. 沒什麼理由是你應該放掉跟朋友好好聊上天的難得機會.

能多跟家人抱抱, 聊聊天, 就要不怕羞的表達. 家家永遠有難念的經, 也許總是有難解的 GAP issues, 加上對於害羞兼總是神遊的 i 型人, 每次親友聚會相當考驗耐心啊, 但是身為已經是中年大叔過來人的經驗, 可以跟大家說, 家庭時光才是最重要的. 各位！除非你是還沒有小孩, 長輩年紀還年輕, 有餘裕揮霍你的假期 + 只需要管好自己的年輕人!

年輕時間成本低, 就要趕快把自己的時間成本拉高, 低的任務就趕快 Delegate 出去. 但是 但是 與家人相處時間就永遠是無價, 無法用金錢評量的,

記得, 時間永遠是最寶貴的. 越是要把握時間, 越要懂得時間就該花在重要的人事物上.

而且, 身為人 (human being) 與機器 (也須此時此刻還稱為 GenAI 吧) 的差別就是, 你永遠有自己應該在乎的人/事/物. 保持人性!

大家新年快樂!

• 🌟 分享給需要的朋友

• 💌 [訂閱電子報](https://leapdesign.ai/zh/subscribe/)，每週收到最新技術文章

大家好，又是新的一年，也即將開始 BuildWithAI 的活動，大家應該都會透過參加 Google Developers Group 舉辦的 Hands-On (動手做) 拿到試用 Google Cloud 的 Credit (點數)。這篇可以幫助你有效率的管理拿到的 Billing Account。

GCP 的專案與帳單帳戶採一對多關聯，雖然試用額度無法合併到同一個 Billing Account，但我們可以透過「重新命名」與「靈活切換連結」來優化管理效率。

將預設名稱改為具辨識度的標籤（如：Trial_End_202605xx），能讓你在多個專案測試時，可以選用到最需要消耗掉的 Billing Account ，最大化你的使用率。

現況: 每次兌換之後，都會產生一組 Google Cloud Platform Trial Billing Account (或是對應的中文翻譯名稱)

或是你也可以從這個網址 https://console.cloud.google.com/billing 看到

or 點選右上角的 …. > Billing account management

就可以看到你帳號底下所有的 Billing Accounts

點選其中一個

點選 Manage billing account

點 Rename billing account

這邊可以輸入容易管理的名稱, 舉例: Credit 到期時間

你可以從左方選單看到 Credits 檢查

舉例來說，我是命名為 Trial_Exp_yyyymmdd

這樣在 GCP Project 選擇 billing account 時, 就會更方便了!

(Optional) 新增 GCP Project 並連結到 Billing account

接著，你可以新增一個 GCP project，搜尋 Create Project

或是網址 https://console.cloud.google.com/projectcreate

之後當 Billing account 的 Credit 使用完之後，想要切換到其他 Billing account

搜尋 Billing > Manage billing accounts

找到該專案, 右方的 … 點選 Change billing 即可

✨ 更多技術解決方案 → [https://leapdesign.ai/]

• 🌟 分享給需要的朋友

• 💌 [訂閱電子報](https://leapdesign.ai/zh/subscribe/)，每週收到最新技術文章

💬 覺得有幫助嗎？

• 🌟 分享給需要的朋友

• 💌 [訂閱電子報](https://leapdesign.ai/zh/subscribe/)，每週收到最新技術文章

✨ 更多快速技術解決方案 → [https://leapdesign.ai/)

⚡ 快速版

Looplia + Gemini Proxy，無縫切換

步驟：

# 1. 設定 Gemini API key

export GEMINI_API_KEY=”AIzaSy...”

# 2. 啟動 proxy（Anthropic API 相容層）

npm install -g @vitorcen/gemini-cli-anthropic

gemini-cli-anthropic  # 監聽 port 41242

# 3. 使用 Claude API 格式呼叫 Gemini

curl -X POST http://127.0.0.1:41242/v1/messages \

  -H “x-api-key: dummy” \

-H “anthropic-version: 2023-06-01” \

  -d ‘{”model”:”gemini-2.5-flash”,”messages”:[...]}’

📖 完整版

利用 Looplia 的 workflow 利用 AI code review，Gemini 提供更大的 context 與多模態理解

本文用 gemini-cli-anthropic 提供 Anthropic API 相容層，無縫使用 Looplia。

💡 適合誰？

• 想使用 Gemini 2.5 Flash 進行 code review

• 原有 Gemini 生態系的想使用 Looplia 的 workflow cli

🔑 Part 1: 設定 Gemini API

步驟 1：獲取 Gemini API Key

這不用多說, 到 https://ai.dev/apikey

步驟 2：設定環境變數

export GEMINI_API_KEY=”AIxx_gxxx”

# 永久保存

echo ‘export GEMINI_API_KEY=”AIzaSy...”’ >> ~/.zshrc

source ~/.zshrc

✅ 驗證 API Key

# 簡單測試

curl -X POST “https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${GEMINI_API_KEY}” \

  -H ‘Content-Type: application/json’ \

-d ‘{”contents”:[{”parts”:[{”text”:”Hello”}]}]}’

🚀 Part 2: 部署 gemini-cli-anthropic Proxy

什麼是 gemini-cli-anthropic？

[gemini-cli-anthropic] 是一個 proxy server，提供：

• Anthropic API 相容層- 使用 Claude API 格式呼叫 Gemini

• 無縫切換 - 現有 Claude 工具無需修改即可使用 Gemini

• 完整支援 - streaming、tool use、multimodal 等功能

架構圖

Client (Claude API format)

    ↓

gemini-cli-anthropic proxy (port 41242)

    ↓ (轉換格式)

Google Gemini API

    ↓

Response (Claude API format)

步驟 1：安裝 (方式 A - NPM 全域安裝)

npm install -g @vitorcen/gemini-cli-anthropic

步驟 2：啟動 Proxy Server

gemini-cli-anthropic

# 輸出：

# Server listening on port 41242

# Using Gemini API Key: AIzaSy...xxx

步驟 1-2：從原始碼安裝 (方式 B)

# Clone repository with submodules

git clone --recurse-submodules https://github.com/vitorcen/gemini-cli-anthropic.git

cd gemini-cli-anthropic

# 安裝相依套件

npm install

# 安裝 gemini-cli submodule

cd gemini-cli

npm install

cd ..

# 啟動 server

npm start

預期輸出：

🚀 Gemini CLI Anthropic Proxy Server

📡 Listening on: http://127.0.0.1:41242

🔑 Using Gemini API Key: AIzaSy...xxx

✅ Server ready!

步驟 3：驗證 Proxy

測試 proxy 是否正常運作：

curl -X POST http://127.0.0.1:41242/v1/messages \

  -H “Content-Type: application/json” \

-H “x-api-key: dummy” \

  -H “anthropic-version: 2023-06-01” \

-d ‘{

    “model”: “gemini-2.5-flash”,

    “max_tokens”: 1024,

    “messages”: [{

      “role”: “user”,

      “content”: “你好，請用繁體中文回答：1+1=?”

    }]

  }’

預期回應：

{

“id”: “msg_...”,

“type”: “message”,

“role”: “assistant”,

“content”: [{

“type”: “text”,

“text”: “1 + 1 等於 二。”

  }],

“model”: “gemini-2.5-flash”,

“usage”: {

“input_tokens”: 15,

“output_tokens”: 8

  }

}

✅ 成功！Proxy 正常運作且支援繁體中文。

📝 Part 3: 實現 Code Review

Python 實作（完整範例）

創建 `gemini-review.py`：

#!/usr/bin/env python3

import json

import urllib.request

# 讀取要審查的程式碼

with open(’smart-code-review.sh’, ‘r’) as f:

    code = f.read()[:1000]  # 前 1000 字元

# 構建請求

data = {

“model”: “gemini-2.5-flash”,

“max_tokens”: 4096,

“messages”: [{

“role”: “user”,

“content”: f“”“請審查以下程式碼的品質、安全性和可讀性，用繁體中文詳細回答：

{code}

請提供：

1. 程式碼品質評估（1-10分）

2. 安全性問題（如有）

3. 可讀性改進建議

4. 最佳實踐建議

5. 優先級標註（P0/P1/P2）

“”“

    }]

}

# 發送請求到 proxy

req = urllib.request.Request(

‘http://127.0.0.1:41242/v1/messages’,

    data=json.dumps(data).encode(’utf-8’),

    headers={

‘Content-Type’: ‘application/json’,

‘x-api-key’: ‘dummy’,  # proxy 不需要真實 API key

‘anthropic-version’: ‘2023-06-01’

    }

)

print(”🔍 開始 Code Review...”)

print(”📡 使用 Gemini 2.5 Flash via Proxy\n”)

with urllib.request.urlopen(req) as response:

    result = json.loads(response.read())

# 顯示審查結果

print(”=” * 60)

print(”📋 CODE REVIEW REPORT”)

print(”=” * 60)

print(result[’content’][0][’text’])

print(”\n” + “=” * 60)

# 顯示使用統計

    usage = result[’usage’]

print(f“\n📊 Token 使用情況：”)

print(f“   - Input tokens: {usage[’input_tokens’]}”)

print(f“   - Output tokens: {usage[’output_tokens’]}”)

print(f“   - Total: {usage[’input_tokens’] + usage[’output_tokens’]}”)

Bash 實作

創建 `review-test.sh`：

#!/bin/bash

CODE=$(cat ~/dot-agents-test/smart-code-review.sh | head -30)

curl -X POST http://127.0.0.1:41242/v1/messages \

  -H “Content-Type: application/json” \

-H “x-api-key: dummy” \

  -H “anthropic-version: 2023-06-01” \

-d @- << JSON | jq -r ‘.content[0].text’

{

  “model”: “gemini-2.5-flash”,

  “max_tokens”: 4096,

  “messages”: [{

    “role”: “user”,

    “content”: “請審查以下程式碼的品質、安全性和可讀性，用繁體中文詳細回答：\n\n${CODE}”

  }]

}

🧪 Part 4: 實際測試結果

執行測試

cd ~/dot-agents-test

python3 gemini-proxy-review.py article-1-claude-subscription-code-review.md

測試輸出（實測結果）

🔍 開始 Code Review...

📡 使用 Gemini 2.5 Flash via Proxy

============================================================

📋 CODE REVIEW REPORT

============================================================

### 程式碼品質評估 (分數：7/10)

這份教學文章的結構清晰，分為快速版和完整版，便於不同程度的讀者

快速理解。提供的指令多數是正確且直接的，整體邏輯流暢。

### 安全性問題

**P1 - OAuth Token 硬編碼**

- 問題：直接將 OAuth token 以明文形式展示

- 風險：可能誤導使用者將其硬編碼到腳本或公開的地方

- 建議：使用佔位符 (YOUR_CLAUDE_OAUTH_TOKEN) 並警告切勿提交到版本控制

**P1 - curl | bash 自動安裝腳本**

- 問題：Bun 的安裝指令 `curl -fsSL https://bun.sh/install | bash`

- 風險：直接執行從網路獲取的腳本

- 建議：增加安全提示，建議使用者先審查腳本內容

**P0 - 指令不完整**

- 問題：Step 1 指令被截斷為 `claude setup-`

- 影響：導致指令無法執行

- 修正：應為 `claude setup-token`

### 可讀性改進建議

**P2 - 環境變數寫入**

- 問題：只提及 `~/.zshrc`，未考慮其他 shell 使用者

- 建議：提及 `~/.bashrc` 或更通用的 `~/.profile`

**P2 - 章節編排一致性**

- 問題：「實作步驟」不夠完整，與快速版有重複

- 建議：統一步驟說明或提供更深入的解釋

### 最佳實踐建議

1. **腳本魯棒性** - 使用 `set -euo pipefail`

2. **依賴鎖定** - 確保 `bun.lockb` 檔案提交到 Git

3. **環境變數冪等性** - 檢查變數是否存在再添加

============================================================

📊 Token 使用情況：

   - Input tokens: 923

   - Output tokens: 1702

   - Total: 2625 tokens

⏱️ 執行時間：約 5-7 秒

🚨 注意事項與限制

1. Proxy 可用性

⚠️ gemini-cli-anthropic proxy 必須持續運行

解決方案 A - systemd service (Linux)

or

解決方案 B - pm2 (Node.js)

💬 覺得有幫助嗎？

• 🌟 分享給需要的朋友

• 💌 [訂閱電子報](https://leapdesign.ai/zh/subscribe/)，每週收到最新技術文章

✨ 更多快速技術解決方案 → [https://leapdesign.ai/)

💌 [訂閱電子報](https://leapdesign.ai/zh/subscribe/)，每週收到最新技術文章

✨ 更多快速技術解決方案 → 請找目前服務入口:

我這邊背景:

1. 已經有自己習慣的工作流程, 可以 Agentic CLI (Claude Code + Gemini-CLI + Codex), 貼上 PR link 做 Code review, comment, change PR status

2. 團隊的 code review 流程: 有 mono repo, 也有同時要看多個相關 repo. 更大多數是 user story based 會跨不同的 repo…很想把 code review 之前的 review convention 等等先定義下來

之前就聽說 Spencer 寫了一個 Skills-first agentic workflow CLI 的開源專案: Looplia , 先拿來做這種自動化應該會很方便. Then…Go!

🎯 你會學到什麼

• 10 分鐘內完成 Claude Code Subscription OAuth 認證

• 整合 Looplia 實現自動化 code review workflow

• 建立完整的品質、安全性、可讀性審查流程

• 生成結構化的 code review 報告

⚡ 速查版: Looplia + Anthropic Subscription OAuth

# 1. 獲取 OAuth token（30 秒，會自動打開瀏覽器）

claude setup-token

# 2. 設定環境變數

export CLAUDE_CODE_OAUTH_TOKEN=”sk-ant-oat01-...”

echo ‘export CLAUDE_CODE_OAUTH_TOKEN=”...”’ >> ~/.zshrc

# 3. 配置 Looplia 使用 Claude Haiku 4.5

looplia config provider preset CLAUDE_CODE_SUBSCRIPTION_HAIKU

# 4. 建立並執行 code review workflow

looplia build “create a code review workflow”

📖 完整版

本文用 **Claude Code Subscription** + **Looplia** 框架，教您快速建立自動化 code review 流程。

💡 **適合誰？**

• 已有 Claude Max subscription

• 想使用最新 Claude 模型

• 需要整合到開發工作流程

—

環境準備

需求：

• Claude Code CLI 2.1.39+

• Bun 1.0+ (JavaScript runtime & package manager)

• Claude subscription

安裝確認：

# 檢查 Claude CLI 版本

claude --version

# 輸出：2.1.39 (Claude Code)

# 檢查 Bun 版本

bun --version

# 輸出：1.0.0+

安裝 Looplia：

# 1. Clone repository

git clone https://github.com/memorysaver/looplia-core.git

cd looplia-core

# 2. 安裝依賴、建置、建立全域連結（一次完成）

bun install && bun run build && bun link

# 3. 驗證安裝成功

looplia --version

# 輸出：looplia/1.x.x

# 4. 初始化 workspace（會在 ~/.looplia/ 建立配置）

looplia init --yes

實作步驟

Step 1: 獲取 OAuth Token

# Claude CLI 會自動打開瀏覽器完成 OAuth 授權

claude setup-token

成功畫面：

✓ Long-lived authentication token created successfully!

Your OAuth token (valid for 1 year):

sk-ant-oat01-_6ejYBCQ2Q_3t4dvivHWdO4S9vlIC_4iHz1W8QsDzS3p_...

Store this token securely. You won’t be able to see it again.

Step 2: 設定環境變數

# 設定環境變數

export CLAUDE_CODE_OAUTH_TOKEN=”sk-ant-oat01-xxxx...”

# 永久保存到 shell 配置（重要！）

echo ‘export CLAUDE_CODE_OAUTH_TOKEN=”sk-ant-oat01-...”’ >> ~/.zshrc

source ~/.zshrc

# 驗證設定成功

echo ${CLAUDE_CODE_OAUTH_TOKEN:0:30}...

# 輸出：sk-ant-oat01-_6ejYBCQ2Q_3t4dvi...

Step 3: 配置 Looplia

# 一鍵設定使用 Claude Haiku 4.5（最省錢的選擇）

looplia config provider preset CLAUDE_CODE_SUBSCRIPTION_HAIKU

# 驗證配置

looplia config provider show

預期輸出：

Model Provider Configuration:

  Status: configured ✓

  Preset: CLAUDE_CODE_SUBSCRIPTION_HAIKU

  Provider: Anthropic (direct)

  Auth Source: Claude Code Subscription (OAuth)

  Agent Models:

    Main: claude-haiku-4-5-20251001

    Executor: claude-haiku-4-5-20251001

配置檔案位置 => ~/.looplia/looplia.setting.json

Step 4: 使用 Looplia 執行 Code Review

設定完成後，就可以用 Looplia 自動建立和執行 code review workflow：

建立 Code Review Workflow

# Looplia 會自動建立完整的 code review workflow

looplia build “create a code review workflow that analyzes code quality, security, and readability”

Looplia 會自動生成：

• 程式碼品質分析步驟

• 安全性審查步驟

• 可讀性評估步驟

• 綜合報告生成步驟

生成的 workflow 檔案位置：

~/.looplia/workflows/code-review-quality-security-readability-[date].md

執行 Workflow

# 執行剛建立的 workflow

looplia run code-review-quality-security-readability \

  --context “請審查專案中的主要程式碼檔案”

執行過程：

1. 🔍 分析程式碼結構和品質

2. 🔒 掃描安全性問題

3. 📖 評估可讀性

4. 📊 生成綜合報告

輸出檔案位置：

~/.looplia/sandbox/[session-id]/outputs/

├── comprehensive_report.md    # 完整審查報告

├── quality_analysis.json      # 品質評估

├── security_analysis.json     # 安全性分析

└── readability_review.json    # 可讀性評估

報告範例

comprehensive_report.md 包含：

1. 執行摘要

• 整體評分（⭐⭐⭐⭐）

• 主要發現摘要

• 優先改進項目

2. 程式碼品質評估

• 結構分析

• 複雜度評估

• 改進建議

3. 安全性評估

• 發現的漏洞清單（依優先級：P0/P1/P2）

• 修復建議

• 最佳實踐

4. 可讀性評估

• 命名規範檢查

• 程式碼風格一致性

• 文件完整性

5. 行動項目

• 優先順序排列的改進清單

• 每項預估工作量

• 預期效益

常見問題 ❓

Q: Build 顯示 “No result received from analysis” 錯誤？

這是**已知問題**，不影響使用！雖然顯示錯誤，但 workflow 檔案已成功生成。

錯誤畫面：

┌ Workflow Builder ─────────────────────────────┐

│ ✗ Error                                       │

│ No result received from analysis              │

└───────────────────────────────────────────────┘

✗ Build failed: Build cancelled by user

解決方法：

1. ⌨️ 按 `Ctrl+C` 跳出錯誤畫面

2. 📁 直接查看生成的 workflow 檔案：

ls -lht ~/.looplia/workflows/ | head -5

3. ✅ 使用生成的 workflow 名稱執行 `looplia run`

範例：

# 即使顯示錯誤，workflow 仍成功生成

# 檔案位置：~/.looplia/workflows/code-review-quality-security-readability-build-2026-02-11-xxxx.md

# 直接執行即可

looplia run code-review-quality-security-readability-build-2026-02-11-xxxx

Q: 如何審查特定檔案？

# 在 --context 中指定檔案

looplia run code-review-quality-security-readability \

  --context “請審查 src/main.py 檔案”

Q: 如何客製化審查重點？

# 在建立 workflow 時指定重點

looplia build “create a code review workflow focusing on security vulnerabilities and performance issues”

Q: Workflow 執行失敗怎麼辦？

檢查以下項目：

1. ✅ `CLAUDE_CODE_OAUTH_TOKEN` 環境變數是否設定

2. ✅ Looplia provider 配置是否正確

3. ✅ 查看 `~/.looplia/logs/` 的錯誤訊息

💬 討論與訂閱

覺得有幫助嗎？

• 🌟 分享給需要的朋友

• 💌 [訂閱電子報](https://leapdesign.ai/zh/subscribe/)，每週收到最新技術文章

想看更多實戰案例？

下一篇文章將介紹如何用 Gemini Proxy 節省 70% 成本，記得訂閱不錯過！

✨ 更多快速技術解決方案 → 請找目前服務入口 https://leapdesign.ai/

公告: 預計會推出訂閱制, 之後應該會部分轉往其他平台, 當然你也可以持續關注這個電子報收到訂閱消息.

Announcement: We are planning to launch a subscription model and may partially migrate to other platforms in the future. Please stay tuned to this newsletter for updates.

技術實作

架構

使用者

  ↓

Colab Notebook

  ├─ 環境偵測

  ├─ 下載 arXiv PDF (urllib)

  ├─ 提取文字 (PyMuPDF)

  ├─ 翻譯 (TranslateGemma 4B on T4 GPU)

  ├─ 後處理 (OpenCC for zh-TW)

  └─ 產生 HTML

  ↓

下載到本地

規格

**模型**

- TranslateGemma 4B (~8.6GB)

- 專門針對學術文本訓練

- 支援 50+ 種語言

**硬體需求**

- Google Colab 免費 T4 GPU (15GB VRAM)

- 或 macOS 16GB+ VRAM

- 或本地 NVIDIA GPU (10GB+ VRAM)

**效能**

- 每頁翻譯時間：~3 分鐘

- 首次模型下載：~5 分鐘（一次性）

- 成本：$0

前置準備

1. Google 帳號（Colab）

2. [HuggingFace 帳號](https://huggingface.co/join)

3. [HF Token](https://huggingface.co/settings/tokens)（讀取權限）

4. [接受 Gemma 使用條款](https://huggingface.co/google/translategemma-4b-it)

使用步驟

Step 1: 啟動 Notebook

**[👉 在 Google Colab 開啟](https://colab.research.google.com/github/jimmyliao/trans-gemma/blob/main/arxiv-reader.ipynb)**

啟用 GPU：

1. **Runtime** → **Change runtime type**

2. 選擇 **T4 GPU**

3. **Save**

Step 2: 環境偵測

執行第一個 cell：

ENV = detect_environment()

輸出範例：

🖥️  Environment: COLAB

🐍 Python: 3.10

📂 Working dir: /content

✅ Environment: COLAB - Ready!

Notebook 自動適應 Colab/GCP/Local 環境。

Step 3: 安裝相依套件

!pip install -q huggingface_hub transformers accelerate \

             sentencepiece protobuf pymupdf pillow \

             opencc-python-reimplemented

**關鍵套件：** `opencc-python-reimplemented`

- 將簡體中文輸出轉換為繁體中文（zh-TW）

- 確保台灣用語正確（基於 not 基于）

Step 4: HuggingFace 認證

輸入 HF token：

📝 Please enter HuggingFace Token:

   1. Get token: https://huggingface.co/settings/tokens

   2. Accept model: https://huggingface.co/google/translategemma-4b-it

Token: █

**安全提示：** 使用 Colab Secrets (🔑) 管理 token

Step 5: 載入模型

from transformers_backend import TransformersBackend

backend = TransformersBackend()

result = backend.load_model()

首次執行輸出：

🚀 Loading TranslateGemma (4B)...

⏳ Downloading model (~8.6GB)...

Downloading: 100% |████████████| 8.6G/8.6G [04:32<00:00]

✅ Model loaded!

📍 Device: cuda:0

📊 Load time: 37.8s

💾 Memory: 13.8 GB / 15.0 GB

後續執行：~30 秒（快取）

Step 6: 設定翻譯任務

# arXiv ID

ARXIV_ID = “2403.08295”

# 頁面範圍

SECTIONS = {

“abstract”: (1, 3),  # 第 1-3 頁

}

# 語言設定

SOURCE_LANG = “en”

TARGET_LANG = “zh-TW”  # 繁體中文（台灣）

# 產生 HTML

SAVE_HTML = True

**支援語言：** `zh-TW`, `zh-CN`, `ja`, `ko`, `fr`, `de`, `es`, `pt`, `ru` 等 50+ 種

**客製化範例：**

翻譯 Abstract：

SECTIONS = {”intro”: (2, 5)}

翻譯全文：

SECTIONS = {”full”: (1, 20)}

翻譯成日文：

TARGET_LANG = “ja”

Step 7: 執行翻譯

# 下載 PDF

pdf_path, total_pages = download_arxiv(ARXIV_ID)

# 翻譯

with tqdm(total=3, desc=”📖 Translating”) as pbar:

for page_num in range(1, 4):

        text = extract_text(pdf_path, page_num)

        result = backend.translate(text,

                                  source_lang=SOURCE_LANG,

                                  target_lang=TARGET_LANG)

        results.append(result)

        pbar.update(1)

實測輸出：

📥 Downloading arXiv:2403.08295

✅ Downloaded: 2403.08295.pdf (17 pages)

🚀 Translation Started

📊 Pages: 3

⏱️  Est. time: ~9 minutes

📖 Translating: 33% |████████▌    | 1/3 [02:48<05:36, 168.05s]

✅ Page 1: 168.05s

📖 Translating: 67% |█████████████| 2/3 [05:51<02:43, 163.25s]

✅ Page 2: 163.25s

📖 Translating: 100% |████████████| 3/3 [08:37<00:00, 166.29s]

✅ Page 3: 166.29s

✅ Translation Complete!

📊 Total: 8 min 37 sec

⚡ Avg: 2.8 min/page

Step 8: 查看結果

Notebook 輸出：

================================================================================

📄 Page 1 - ABSTRACT

================================================================================

📝 Original:

--------------------------------------------------------------------------------

This work introduces Gemma, a family of lightweight, state-of-the-art open

models built from the research and technology used to create Gemini models.

🌐 Translation:

--------------------------------------------------------------------------------

論文摘要：

Gemma 是一系列基於 Gemini 的輕量級、先進的開源模型。這些模型在語言理解、

推理和安全性等方面的表現優異。

Step 9: 下載雙語 HTML

filename = f“arxiv_{ARXIV_ID}_{SOURCE_LANG}-{TARGET_LANG}.html”

from google.colab import files

files.download(filename)

輸出：

💾 HTML saved: arxiv_2403.08295_en-zh-TW.html

📊 Size: 143.2 KB

📄 Pages: 3

HTML 功能

**介面組成：**

- Header：arXiv ID、語言對、產生日期

- Navigation：上一頁/下一頁按鈕

- 提示列：鍵盤操作說明（← → 鍵）

- 章節標題：頁碼、翻譯時間

- 雙欄佈局：原文（左）、翻譯（右）

**功能：**

- 原文與翻譯並排對照

- 鍵盤導航（← → 方向鍵）

- 頁面計數器（1/3）

- 顯示每頁翻譯時間

- 離線可用

- 響應式設計

翻譯品質評估

測試論文：Gemma Technical Report (arXiv:2403.08295)

測試範例

**原文：**

The Gemma model architecture is based on the transformer decoder (Vaswani et al., 2017).

Models are trained on a context length of 8192 tokens. We also utilize several improvements

proposed after the original transformer paper.

Multi-Query Attention (Shazeer, 2019). Notably, the 7B model uses multi-head attention

while the 2B checkpoints use multi-query attention (with num_kv_heads = 1).

**TranslateGemma 輸出：**

Gemma 模型架構基於 Transformer 解碼器（Vaswani 等人，2017）。模型是在 8192 個

token 的上下文長度上訓練的。我們還使用了原始 Transformer 論文之後提出的幾項改進。

多查詢注意力（Shazeer，2019）。值得注意的是，7B 模型使用多頭注意力，而 2B 檢查點

使用多查詢注意力（num_kv_heads = 1）。

GPU 使用

📊 GPU 記憶體：

   Total: 15.0 GB

   Model: ~8.6 GB

   Working: ~1.2 GB

   Available: ~5.2 GB

📊 使用率：

   翻譯中：95-100%

   閒置：0%

進階使用

先翻譯重點章節：

SECTIONS = {

“abstract”: (1, 1),      # 快速瀏覽

“intro”: (2, 4),         # 背景動機

“conclusion”: (15, 16),  # 結論

}

確認相關後再翻譯全文：

SECTIONS = {

“method”: (5, 10),

“results”: (11, 14),

}

多語言翻譯

for lang in [”zh-TW”, “ja”]:

TARGET_LANG = lang

# 執行翻譯

產生 3 個版本對照：

- 原始英文

- 繁體中文

- 日文

**GitHub:** [github.com/jimmyliao/trans-gemma]

公告: 預計會推出訂閱制, 之後應該會部分轉往其他平台, 當然你也可以持續關注這個電子報收到訂閱消息.

Announcement: We are planning to launch a subscription model and may partially migrate to other platforms in the future. Please stay tuned to this newsletter for updates.

The Problem: You’re Wasting Hours on Research Papers

Here’s a situation you might recognize:

You open an arXiv paper. It’s groundbreaking work in your field. You **need** to understand it. But after 20 minutes staring at the abstract, you’ve only grasped about 60% of what’s happening.

So you start the copy-paste dance:

1. Highlight a paragraph 📋

2. Open DeepL in another tab

3. Paste and translate

4. Copy translation back to your notes

5. Lose all formatting 😫

6. Repeat 47 more times...

Three hours later, you’re exhausted, your notes are a mess, and you’re not even sure you understood the methodology correctly.

What if I told you there’s a better way?

In this post, I’ll show you how to translate entire arXiv papers into beautiful bilingual HTML — original and translation side-by-side — using Google’s TranslateGemma model on free Colab GPU.

Set it up once, translate forever. Let’s dive in.

🎯 What Makes This Different?

Before we jump into the tutorial, let’s understand why this approach beats traditional tools:

TranslateGemma is Like a Specialized Translator for Academics

Think of general translation APIs (DeepL, Google Translate) as **generalist interpreters**. They’re great at casual conversations but sometimes stumble on domain-specific jargon.

TranslateGemma is like hiring a PhD student who speaks both languages — it understands:

- Technical terminology in context

- Academic writing conventions

- The difference between “model” (ML model) vs “model” (fashion model)

- How to preserve mathematical notation

The Bilingual HTML is Like Having Training Wheels

Instead of reading pure translation, you get:

┌─────────────────────────────────┬─────────────────────────────────┐

│ Original (English)              │ Translation (Your Language)     │

├─────────────────────────────────┼─────────────────────────────────┤

│ This work introduces Gemma...   │ 本研究介紹了 Gemma...             │

│ ...                             │ ...                             │

└─────────────────────────────────┴─────────────────────────────────┘

         ↑ Navigate with ← → keys ↑

This means:

- ✅ Learn English while reading in your language

- ✅ Check translations when something feels off

- ✅ Build vocabulary by seeing terms in context

🧠 How This Actually Works (For the Curious)

Let me pull back the curtain on the technical implementation.

Architecture Overview

┌──────────────┐

│   User       │

│  (Browser)   │

└──────┬───────┘

       │ 1. Click Colab link

       ▼

┌──────────────────────────────────┐

│   Colab Notebook                 │

│   ┌──────────────────────────┐   │

│   │ Environment Detection    │   │

│   └──────────┬───────────────┘   │

│              │ 2. Auto-config    │

│              ▼                    │

│   ┌──────────────────────────┐   │

│   │ Download arXiv PDF       │   │

│   │ (via urllib)             │   │

│   └──────────┬───────────────┘   │

│              │ 3. Extract text   │

│              ▼                    │

│   ┌──────────────────────────┐   │

│   │ PyMuPDF (page-by-page)   │   │

│   └──────────┬───────────────┘   │

│              │ 4. Send to model  │

│              ▼                    │

│   ┌──────────────────────────┐   │

│   │ TranslateGemma 4B        │◄──┼─ HuggingFace Hub

│   │ (on T4 GPU)              │   │   (model download)

│   └──────────┬───────────────┘   │

│              │ 5. Post-process   │

│              ▼                    │

│   ┌──────────────────────────┐   │

│   │ OpenCC (if zh-TW)        │   │

│   └──────────┬───────────────┘   │

│              │ 6. Generate HTML  │

│              ▼                    │

│   ┌──────────────────────────┐   │

│   │ Bilingual HTML           │   │

│   │ (side-by-side layout)    │   │

│   └──────────┬───────────────┘   │

│              │ 7. Download       │

└──────────────┼───────────────────┘

               ▼

       ┌───────────────┐

       │  User’s PC    │

       │  (HTML file)  │

       └───────────────┘

🚀 Let’s Build This: 10-Minute Setup

Instead of drowning you in theory, let’s get your first paper translated. We’ll explain what’s happening as we go.

Prerequisites (5 minutes setup, one-time)

You’ll need:

1. **Google Account** (for Colab)

2. **HuggingFace Account** ([sign up free](https://huggingface.co/join))

3. **HF Token** with read access ([create here](https://huggingface.co/settings/tokens))

4. **Accept Gemma Terms** ([click here](https://huggingface.co/google/translategemma-4b-it))

Step 1: Open Notebook & Enable GPU (1 minute)

**[👉 Click here to open in Google Colab]**

Then:

1. **Runtime** menu → **Change runtime type**

2. Select **T4 GPU** from dropdown

3. Click **Save**

**Why T4?** It’s the free tier GPU that’s perfect for this task — enough memory for the 4B model, but not overkill.

Step 2: Run Environment Detection (30 seconds)

Execute the first code cell (click ▶️ or press Shift+Enter):

# This auto-detects whether you’re on Colab, GCP, or local Jupyter

ENV = detect_environment()

**Output:**

========================================================================

🔍 Environment Detection

========================================================================

🖥️  Environment: COLAB

🐍 Python: 3.10

📂 Working dir: /content

========================================================================

✅ Environment: COLAB - Ready!

========================================================================

*The notebook automatically detects your runtime environment*

**What’s happening here?**

The notebook adapts to your environment automatically. Same notebook works on:

- Google Colab (most users)

- GCP Custom Runtime (advanced)

- Local Jupyter (if you have GPU)

No need to modify code — it just works™.

Step 3: Install Dependencies (2 minutes)

Next cell installs packages based on your environment:

# Colab gets lightweight dependencies

!pip install -q huggingface_hub transformers accelerate \

             sentencepiece protobuf pymupdf pillow \

             opencc-python-reimplemented

**Key package:** `opencc-python-reimplemented`

This ensures if you’re translating to **Traditional Chinese** (Taiwan/Hong Kong), you get 基**於** not 基**于**. Small details matter in academic writing.

Just click ▶️ and wait for installation to complete.

Step 4: Authenticate with HuggingFace (1 minute)

The notebook will prompt for your HF token:

📝 Please enter HuggingFace Token:

   💡 Tip: Use Colab Secrets (🔑 icon) for better security

   1. Get token: https://huggingface.co/settings/tokens

   2. Accept model: https://huggingface.co/google/translategemma-4b-it

Token: █

Paste your token and press Enter. Done.

**Security tip:** Use Colab’s built-in secrets manager (🔑 sidebar icon) instead of pasting tokens directly if you’re sharing notebooks.

Step 5: Load the Model (First run: 5 min, After: 30 sec)

This is where the magic happens:

from transformers_backend import TransformersBackend

backend = TransformersBackend()

result = backend.load_model()

**First run output:**

🚀 Loading TranslateGemma (4B)...

   ⏳ Downloading model (~8.6GB) on first run...

Downloading: 100% |████████████████████| 8.6G/8.6G [04:32<00:00, 31.5MB/s]

✅ Model loaded!

📍 Device: cuda:0

📊 Load time: 37.8s

💾 Memory: 13.8 GB used / 15.0 GB total

🎉 Ready to translate!

**What just happened?**

- Downloaded TranslateGemma 4B (8.6GB) to Colab’s disk

- Loaded model into GPU memory

- Cached for future runs (next time: 30 seconds!)

Grab a coffee ☕ on first run. It’s worth the wait.

### Step 6: Configure Your Translation (30 seconds)

Now the fun part — telling it **what** to translate:

# Which paper?

ARXIV_ID = "2403.08295"  # Gemma paper (or any arXiv ID)

# Which pages?

SECTIONS = {

"abstract": (1, 3),  # Pages 1-3

}

# What languages?

SOURCE_LANG = "en"

TARGET_LANG = "zh-TW"  # Traditional Chinese (Taiwan)

# Generate beautiful HTML?

SAVE_HTML = True

**Customization examples:**

Translate intro section only:

SECTIONS = {

"intro": (2, 5),

}

Translate to Japanese:

TARGET_LANG = "ja"

Translate everything:

SECTIONS = {

"full": (1, 20),  # All pages

}

**Supported languages:** 50+ including `zh-TW`, `zh-CN`, `ja`, `ko`, `fr`, `de`, `es`, `pt`, `ru`, etc.

Step 7: Hit Translate! (3 min per page)

Execute the translation cell:

# Download PDF from arXiv

pdf_path, total_pages = download_arxiv(ARXIV_ID)

# Translate page by page with progress bar

with tqdm(total=3, desc=”📖 Translating”) as pbar:

for page_num in range(1, 4):

        text = extract_text(pdf_path, page_num)

        result = backend.translate(text,

                                  source_lang=SOURCE_LANG,

                                  target_lang=TARGET_LANG)

        results.append(result)

        pbar.update(1)

**Real output from my test:**

📥 Downloading arXiv:2403.08295

✅ Downloaded: 2403.08295.pdf (17 pages)

========================================================================

🚀 Translation Started

========================================================================

📊 Pages: 3

⏱️  Est. time: ~9 minutes

📖 Translating: 33% |████████▌         | 1/3 [02:48<05:36, 168.05s/page]

✅ Page 1: 168.05s

📖 Translating: 67% |█████████████████ | 2/3 [05:51<02:43, 163.25s/page]

✅ Page 2: 163.25s

📖 Translating: 100% |█████████████████| 3/3 [08:37<00:00, 166.29s/page]

✅ Page 3: 166.29s

========================================================================

✅ Translation Complete!

========================================================================

📊 Pages: 3

⏱️  Total: 8 min 37 sec

⚡ Avg: 2.8 min/page

========================================================================

*Live translation progress with tqdm showing real-time status per page*

**What’s happening under the hood?**

For each page, the backend:

1. Sends text to TranslateGemma with a **simple, direct prompt**:

Translate the following text from en to Traditional Chinese (Taiwan, 繁體中文).

Only output the translation, do not include explanations:

[Original text here]

Translation:

2. Model generates translation using GPU acceleration

3. Extracts clean translation from output

4. Applies OpenCC post-processing (for zh-TW)

**Pro tip:** Pages with heavy math/tables take similar time — the model handles them well.

Step 8: View Results in Notebook

Immediately after translation, you’ll see:

========================================================================

📄 Page 1 - ABSTRACT

========================================================================

📝 Original:

------------------------------------------------------------------------

This work introduces Gemma, a family of lightweight, state-of-the-art open

models built from the research and technology used to create Gemini models.

Gemma models demonstrate strong performance across academic benchmarks for

language understanding, reasoning, and safety.

🌐 Translation:

------------------------------------------------------------------------

論文摘要：

Gemma 是一系列基於 Gemini 的輕量級、先進的開源模型。這些模型在語言理解、

推理和安全性等方面的表現優異，並在 18 項文字任務中，在同等規模的開源模型

中表現更佳。

**Notice the quality:**

- “lightweight” → “輕量級” ✅ (not “輕” or “光”)

- “state-of-the-art” → “先進” ✅ (contextually appropriate)

- “benchmarks” → “基準測試” ✅ (technical term)

- Traditional Chinese: 基**於** ✅ (not 基**于**)

This is **way better** than copy-pasting into Google Translate.

Step 9: Download Interactive HTML (10 seconds)

The final cell generates a self-contained HTML file:

# Generate bilingual HTML

filename = f“arxiv_{ARXIV_ID}_{SOURCE_LANG}-{TARGET_LANG}.html”

# Auto-download in Colab

from google.colab import files

files.download(filename)

**Output:**

💾 HTML saved: arxiv_2403.08295_en-zh-TW.html

📂 Full path: /content/arxiv_2403.08295_en-zh-TW.html

📊 Size: 143.2 KB

📄 Pages: 3

📥 To view the full HTML:

   1. Download: Right-click ‘arxiv_2403.08295_en-zh-TW.html’ in Files panel → Download

   2. Or use auto-download (Colab native only)

**Open the HTML in your browser:**

*Clean header with title, language pair, date, and keyboard-friendly navigation*

*Original English (left) and Traditional Chinese translation (right) in perfect sync*

**What you’re seeing:**

- **Header:** arXiv:2403.08295 Bilingual Translation

- **Metadata:** en → zh-TW | 2026-01-19 14:22

- **Navigation:** ◄ Prev | Page 1 (1/3) | Next ▶

- **Hint bar:** 💡 Use ← → keys (yellow background for visibility)

- **Section header:** 📄 ABSTRACT - Page 1 ⏱️ 179.74s (shows translation time)

- **Dual columns:** Gray background for original, white for translation

**Features:**

- ✅ Side-by-side original + translation (never lose context)

- ✅ Keyboard navigation (← → arrow keys for fast reading)

- ✅ Page counter with progress (”Page 1 (1/3)”)

- ✅ Translation time per page (⏱️ 179.74s shown in purple header)

- ✅ Works offline (no internet needed after download)

- ✅ Mobile responsive (columns stack vertically on small screens)

- ✅ Clean typography (monospace for original, sans-serif for translation)

**This is your forever-reference** for that paper. Share it, annotate it, or keep it for later.

🔬 Translation Quality: Let’s Be Honest

I tested this on the **Gemma Technical Report** (arXiv:2403.08295), a genuinely complex paper with:

- Model architecture details

- Training methodology

- Benchmark results (tables)

- Mathematical notation

- Lots of jargon (”multi-query attention”, “RoPE embeddings”, “supervised fine-tuning”)

### Sample: Original Text

The Gemma model architecture is based on the transformer decoder (Vaswani et al., 2017).

The core parameters of the architecture are summarized in Table 1. Models are trained on

a context length of 8192 tokens. We also utilize several improvements proposed after the

original transformer paper, and list them below:

Multi-Query Attention (Shazeer, 2019). Notably, the 7B model uses multi-head attention

while the 2B checkpoints use multi-query attention (with num_kv_heads = 1), based on

ablations that showed that multi-query attention works well at small scales.

TranslateGemma Output

Gemma 模型架構基於 Transformer 解碼器（Vaswani 等人，2017）。架構的核心參數

總結於表 1 中。模型是在 8192 個 token 的上下文長度上訓練的。我們還使用了原始

Transformer 論文之後提出的幾項改進，並在下面列出：

多查詢注意力（Shazeer，2019）。值得注意的是，7B 模型使用多頭注意力，而 2B 檢查

點使用多查詢注意力（num_kv_heads = 1），這是基於消融研究顯示多查詢注意力在小規模

下效果良好。

My Assessment

| Aspect | Rating | Notes |

|--------|--------|-------|

| **Technical Accuracy** | ⭐⭐⭐⭐⭐ | “multi-query attention” → “多查詢注意力” is spot-on |

| **Terminology Consistency** | ⭐⭐⭐⭐⭐ | Same term translated same way throughout |

| **Grammar & Flow** | ⭐⭐⭐⭐⭐ | Reads naturally in target language |

| **Format Preservation** | ⭐⭐⭐⭐⭐ | Keeps paragraphs, citations, structure intact |

| **Context Understanding** | ⭐⭐⭐⭐ | Gets that “ablations” means ablation studies (not medical) |

**Where it shines:**

- ✅ Technical jargon (transformers, attention mechanisms, tokens)

- ✅ Citations format preserved: (Vaswani et al., 2017)

- ✅ Numbers and variables unchanged: 8192, 7B, num_kv_heads

- ✅ Academic tone maintained

**Minor quirks:**

- ⚠️ Sometimes literal translation where paraphrase would be smoother

- ⚠️ Very occasional wrong word choice (maybe 1-2 per page)

**Compared to:**

- **DeepL:** Better for general text, but struggles with ML terminology

- **Google Translate:** Faster, but often mistranslates domain terms

- **GPT-4/Claude API:** Similar quality, but costs $0.01-0.02 per page

- **Human translator:** Obviously better, but and slow

For **free academic translation**, this is **unbeatable**.

⚡ Performance & Cost: The Real Numbers

Let me share actual benchmarks from my testing:

My Setup

- **Platform:** Google Colab Free Tier

- **GPU:** Tesla T4 (15GB VRAM)

- **Model:** TranslateGemma 4B (~8.6GB)

- **Test paper:** Gemma Report (arXiv:2403.08295)

Timing Breakdown

| Operation | First Run | Subsequent Runs |

|-----------|-----------|-----------------|

| Model download | ~5 min (one-time) | - |

| Model loading | 37.8 sec | 30 sec (cached) |

| Translation | 165-170 sec/page | Same |

| HTML generation | <1 sec | <1 sec |

**Total for 3 pages:**

- First ever run: ~15 minutes (including model download)

- After model cached: ~9 minutes (just translation time)

GPU Usage

📊 GPU Memory:

   Total: 15.0 GB

   Model: ~8.6 GB

   Working: ~1.2 GB

   Available: ~5.2 GB

📊 Utilization:

   During translation: 95-100%

   Idle: 0%

The T4 is fully utilized during translation — that’s why it’s relatively fast.

Cost Comparison (10-page paper)

| Method | Time | Cost | Quality |

|--------|------|------|---------|

| **TranslateGemma + Colab** | ~30 min | **$0.00** | ⭐⭐⭐⭐⭐ |

| **Claude 3.5 API** | ~2 min | $0.10 | ⭐⭐⭐⭐ |

| **DeepL Pro API** | ~1 min | $0.20 | ⭐⭐⭐⭐ |

| **Google Translate** | Instant | $0.00 | ⭐⭐⭐ |

| **Human translator** | 2-3 days | $50-200 | ⭐⭐⭐⭐⭐ |

**My take:** If you’re reading 5-10 papers per week, the **time investment** of TranslateGemma pays off in **quality + zero cost**. For one-off urgent translations, APIs are faster.

🛠️ Power User Tips

Once you’ve got the basics down, here are some pro moves:

Tip 1: Batch Translate Strategically

Don’t translate entire papers blindly. Use this approach:

SECTIONS = {

“abstract”: (1, 1),      # Quick scan: worth deep reading?

“intro”: (2, 4),         # Context and motivation

“conclusion”: (15, 16),  # Main takeaways

}

Read these first (10 min translation). If it’s relevant, come back for:

SECTIONS = {

“method”: (5, 10),

“results”: (11, 14),

}

**Why?** You’ll save time on papers that aren’t relevant to your work.

Tip 2: Translate to Multiple Languages

Learning Japanese and Chinese? Do this:

for lang in [”zh-TW”, “ja”]:

TARGET_LANG = lang

# Run translation

# Generate HTML

Now you have **3 versions** to compare:

- Original English

- Traditional Chinese

- Japanese

Great for building technical vocabulary across languages.

Tip 3: Fix the “Pages 2-3 Didn’t Translate” Bug

If you’re using an older version, pages with lots of charts/tables might fail to translate (they just return the original text).

**We fixed this recently!** Update to latest:

cd trans-gemma && git pull

**What we changed:**

- Switched from complex chat template to **simple direct prompt**

- More robust extraction logic

- Better handling of mixed-content pages (text + figures)

Tip 4: Run Locally If You Have GPU

Don’t want to depend on Colab quotas? Run locally:

git clone https://github.com/jimmyliao/trans-gemma.git

cd trans-gemma

pip install -e “.[examples]”

# Open notebook

jupyter notebook arxiv-reader.ipynb

The notebook **auto-detects** your environment (Colab vs Local) and adapts. Just works.

**Requirements:**

- Python 3.10+

- NVIDIA GPU with 10GB+ VRAM (or use CPU, but very slow)

- ~15GB disk space for model

Tip 5: Customize the HTML Output

The generated HTML uses **vanilla JavaScript** and can be easily customized. Open the notebook cell that generates HTML and modify:

**Change color scheme:**

.header {

background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

}

**Add dark mode:**

@media (prefers-color-scheme: dark) {

body { background: #1a1a1a; color: #e0e0e0; }

}

**Adjust layout ratio:**

.columns {

grid-template-columns: 45% 55%; /* Favor translation side */

}

🤔 Common Questions

Q: “Colab says GPU unavailable?”

**A:** Free tier has daily quotas (typically refreshes every 12-24 hours). Try:

1. **Wait a few hours** and retry

2. **Try off-peak times** (evenings/weekends in US timezones)

3. **Switch Google accounts** if you have multiple

4. **Upgrade to Colab Pro** ($10/month) for guaranteed GPU

Q: “Model download stuck at 45%?”

**A:** Network hiccups happen. Try:

1. **Restart runtime:** Runtime → Restart runtime

2. **Clear outputs:** Edit → Clear all outputs

3. **Re-run from Step 5:** Model downloads resume where they left off

If still stuck after 15 minutes, it’s likely a HuggingFace server issue. Wait 30 min and retry.

Q: “Translation has simplified + traditional Chinese mixed?”

**A:** This **should be fixed** in latest version. We added `opencc-python-reimplemented` to backend.

If still happening:

cd trans-gemma && git pull

Then restart notebook.

Q: “Can I translate non-arXiv PDFs?”

**A:** The current notebook is optimized for arXiv URLs. For local PDFs, modify:

# Instead of:

pdf_path, total = download_arxiv(ARXIV_ID)

# Use:

pdf_path = “/content/your_paper.pdf”

total = len(fitz.open(pdf_path))

Then run translation cells as normal.

Q: “Is this safe for commercial use?”

**A:** Tricky question:

- **Code (MIT license):** Yes, use commercially

- **Gemma model:** Read [Terms of Use](https://ai.google.dev/gemma/terms)

- **Colab:** Free tier meant for learning/research

**My advice:** Use for research/learning. If you’re making money from translations, consider:

- Running on your own GPU

- Using Colab Pro (legitimized commercial use)

- Checking Gemma’s commercial terms carefully

Key Technical Decisions

**1. Simple Prompt Over Chat Template**

Initially, we used HuggingFace’s `apply_chat_template()`:

# Old approach (failed on pages with tables/math)

messages = [{

“role”: “user”,

“content”: [{”type”: “text”, “text”: text, ...}]

}]

inputs = tokenizer.apply_chat_template(messages, ...)

**Problem:** Pages with heavy formatting confused the template, and extraction logic failed.

**Fix:** Switched to dead-simple prompt:

# New approach (rock solid)

prompt = f“”“Translate the following text from {source_lang} to Traditional Chinese (Taiwan, 繁體中文). Only output the translation, do not include explanations:

{text}

Translation:”“”

inputs = tokenizer(prompt, return_tensors=”pt”)

**Result:** 100% success rate across all page types.

**2. OpenCC Post-Processing**

TranslateGemma 4B tends to output **Simplified Chinese** by default, even when asked for Traditional.

Solution: **Always post-process** for zh-TW:

if target_lang == “zh-TW”:

from opencc import OpenCC

    cc = OpenCC(’s2twp’)  # Simplified → Traditional (Taiwan phrases)

    translation = cc.convert(translation)

This ensures:

- 基于 → 基於

- 轻量级 → 輕量級

- 这些 → 這些

Taiwan readers notice these details!

**3. Dynamic Environment Detection**

Same notebook runs on Colab, GCP, or local Jupyter:

def detect_environment():

try:

import google.colab

return ‘colab’

except ImportError:

pass

if os.path.exists(’/opt/conda/envs/py310’):

return ‘gcp’

return ‘local’

Then:

if ENV == ‘colab’:

# Lightweight installs

elif ENV == ‘gcp’:

# Custom runtime configs

else:

# Local includes PyTorch

**Why?** Colab has PyTorch pre-installed; local doesn’t. One notebook, zero friction.

**4. Progressive HTML Generation**

Instead of loading entire paper at once, the HTML uses:

// Page navigation with keyboard shortcuts

let currentPage = 0;

function showPage(n) {

document.querySelectorAll(’.page’).forEach(p => p.style.display = ‘none’);

document.getElementById(`page-${n}`).style.display = ‘block’;

currentPage = n;

}

document.addEventListener(’keydown’, e => {

if (e.key === ‘ArrowLeft’) showPage(currentPage - 1);

if (e.key === ‘ArrowRight’) showPage(currentPage + 1);

});

**Benefit:** Even 50-page papers load instantly in browser.

🎯 Who This Is (and Isn’t) For

✅ Perfect For:

**Graduate Students**

- Reading 5-10 papers per week

- Budget: $0

- Time: Can wait 3 min/page for quality translations

- Bonus: Learn English terminology via side-by-side reading

**Non-native English Researchers**

- Deep-reading important papers

- Want to **understand**, not just skim

- Appreciate bilingual layout for learning

**AI/ML Engineers Keeping Current**

- Track latest arXiv preprints

- Translate abstract + intro first, decide if worth full read

- Free tier is plenty for 2-3 papers daily

❌ Not Ideal For:

**Urgent Deadlines**

- If you need a paper translated in 5 minutes, use Claude/GPT-4 API

- They’re faster (~10 sec/page), just costs $0.01-0.02 per page

**Large-Scale Translation**

- Translating 100 papers → you’ll hit Colab quotas

- Consider running on your own GPU or cloud instance

**Commercial Translation Services**

- Check Gemma Terms of Use carefully

- May need different licensing

🔮 What’s Next for This Project

I’m actively developing this, and here’s what’s coming:

Short-term (Next Month)

- 🔜 **Auto-language detection** from paper metadata

- 🔜 **DOCX/Markdown output** formats (not just HTML)

- 🔜 **Batch mode:** Translate multiple papers in one go

- 🔜 **Dark mode** for HTML output

### Medium-term (Next Quarter)

- 🔜 **Gemma 2/3 support** when released

- 🔜 **Terminology glossary** extraction (build your own vocab list)

- 🔜 **Figure/table captions** translation

- 🔜 **API mode** for programmatic access

### Long-term (This Year)

- 🔜 **Web UI** (no notebook required)

- 🔜 **Mobile app** for reading on-the-go

- 🔜 **Community translations** (share & reuse)

Want to contribute? **Pull requests welcome!** → [GitHub](https://github.com/jimmyliao/trans-gemma)

---

🚀 Your Turn: Translate Your First Paper

Alright, you’ve read 3000+ words about this. Time to actually try it.

### 5-Minute Challenge:

1. **Pick a paper:** Go to [arXiv.org](https://arxiv.org), find something interesting

2. **Copy the ID:** It looks like `2403.08295` (from URL)

3. **Click this badge:** [](https://colab.research.google.com/github/jimmyliao/trans-gemma/blob/main/arxiv-reader.ipynb)

4. **Enable T4 GPU:** Runtime → Change runtime type → T4 GPU

5. **Run all cells:** Runtime → Run all (or Ctrl+F9)

6. **Wait ~10 minutes** (first run includes model download)

7. **Download the HTML** and open in browser

**Boom.** You just translated an academic paper for free.

💬 Let’s Make This Better Together

**If this helped you:**

- ⭐ **Star the repo:** [github.com/jimmyliao/trans-gemma]

- 🐛 **Report bugs:** [Open an issue]

- 💡 **Share ideas:** [Start a discussion]

Open source makes projects like this possible. Thank you! 🙌

**P.S.** If you made it this far, you’re either genuinely interested or an excellent skimmer. Either way, I appreciate you reading. Now go translate something! 📚✨

嘗試不少電子報/Blogpost 平台, 最近打算轉往收費平台, 才發現針對台灣特有法規, 要收費還真是麻煩. Stripe 應該是最簡單, 但是台灣金流…

另一個可能方向就是, 部分仍然會是免費, 但是有些是業界經驗/回饋, 以及個人的觀察心得, 想要維持更有品質的輸出. 原有訂閱的朋友也可以直接回信給我你的想法, 有意願可以回信跟我說一聲, 我會優先列入在新的訂閱服務裡. 🙇

預計收費可能是訂閱制 (一年, 一個月), 但是收費內容還在訂定中, 既然是維持原本公開免費版本+進階聽者收費, 內容也會跟著推出的服務調整. 但主要是想聽聽讀者們的回饋, 你覺得比較合理的訂閱制內容是？可以直接回信 (brewbuild@substack.com) 或是留言.

1. AI First 開發之於傳統軟體開發的影響

傳統開發 vs AI Fist 驅動開發

傳統開發流程：

1. 構思想法 → 2. 學習框架 → 3. 環境設定 → 4. 撰寫程式碼 → 5. 除錯 → 6. 部署

• 時間成本：往往需要好幾個工作日，甚至是需要與多個職能負責人溝通

• 技術門檻：需要深厚的程式設計經驗

• 迭代速度：每次修改都需要完整的開發週期 (ex. 排入 Backlog, PRD review etc.)

AI First 開發：

1. 描述想法（Prompt）→ 2. AI 生成完整應用 → 3. 測試 → 4. 對話式修改 → 5. 重新部署

• 時間成本：數小時 (這次我大概只花了 1-1.5 小時)

• 技術門檻：會寫 Prompt 就能開發

• 迭代速度：對話即修改，即時看到結果

本文展示了什麼

這篇文章記錄了 **Nano Banana Lab** 的完整開發過程，一個用 Google AI Studio 從零到部署的 IP 角色生成應用。更重要的是，展示了：

✅ **如何用 Prompt 快速將想法轉化為可運行的應用**

✅ **如何透過對話持續測試、修改、發布**

✅ **如何讓開發者與 Builder 快速實踐創意**

*圖 1：Nano Banana Lab 的圖像編輯介面 — 從想法到這個應用，只花了1小時*

Nano Banana Lab 是什麼

一個為 IP 角色「Jimmy」設計的多模態內容生成工具，提供：

• **DNA 模式**：文生圖，基於「Visual DNA」生成一致性角色

• **編輯模式**：圖生圖，AI 輔助圖像編輯

• **Veo 模式**：圖生影片，將靜態圖像轉換為短影片

關鍵：

• No-Build 架構（無需 npm、webpack）

• BYOK 安全機制（Bring Your Own Key）

• 完整的存取控制（Passcode + Idle Timeout）

重要的是：這個應用完全由 AI Studio 對話生成，並在持續對話中完成 4 次功能修改。

2. 成果展示：先看看我們做出了什麼

在深入開發過程之前，先看看最終成果，讓您了解這個應用的實際效果。

應用功能概覽

Nano Banana Lab 整合了三個核心功能，提供完整的 IP 角色內容生成工作流：

1. **DNA 模式**：快速生成一致性角色圖像

2. **編輯模式**：精細調整圖像細節

3. **Veo 模式**：將靜態圖像轉換為動態影片

Demo 影片

完整工作流程演示

**Veo 影片生成演示**

此影片展示：

- 上傳 Jimmy 角色圖像

- 輸入動畫提示詞（「跳個 Rat Dance」）

- 等待 Veo 生成 5 秒短影片

- 播放與下載生成的影片

實際生成範例

**Jimmy 角色的 Visual DNA 生成結果**

基於相同的 Visual DNA Prompt，模型能夠生成具有一致視覺特徵的角色圖像：

結果：角色主體特徵保持不變，成功轉換為影片。

**影片生成示例**

動畫提示詞：「跳個 Rat Dance」

結果：Jimmy 角色以 Pixar 風格執行跳舞動作，保持視覺一致性，動作流暢自然。

---

3. AI First (with AI Studio) 驅動的開發工作流

核心循環：Prompt → Code → Test → Deploy → Iterate

這是 Nano Banana Lab 的完整開發流程，展示如何透過 AI Studio 實現快速迭代：

┌─────────────────────────────────────────────────────┐
│                    開發循環                          │
│                                                     │
│  1. Prompt（描述想法）                                │
│         ↓                                           │
│  2. AI 生成程式碼                                    │
│         ↓                                           │
│  3. 測試（發現問題）                                  │
│         ↓                                           │
│  4. 對話式修改（提出需求）                             │
│         ↓                                           │
│  5. AI 修正程式碼                                    │
│         ↓                                           │
│  6. 部署（Cloud Run / 本地）                          │
│         ↓                                           │
│  回到步驟 3（持續迭代）                                │
└─────────────────────────────────────────────────────┘

第 1 輪：初始 Prompt → 完整應用

**使用者的初始想法**（用自然語言描述）：

我是直接先用 Gemini Web App (https://gemini.google.com) 先討論:

> IP 視覺DNA的編碼術： 使用Nano Banana 鑄造一致性角色的應用代理

> 翻譯成英文，我打算放到 google ai studio 的 prompt 產生看看, 然後預計先有一個範例 (故事性), 產出人物圖片, 在接續產生影片.

> 提供 prompt 讓我之後方便打造 app, 不是幫我直接產圖。

**Gemini 的回應與理解**：

好的，非常抱歉！我理解您的意思了。您需要的是一個結構化的、可以重複使用的 Prompt 範本，以便在 Google AI Studio 中鑄造出名為 Jimmy 的一致性 IP 角色，並能將這個 **視覺 DNA** 應用於圖片和影片生成。

*圖 1-2：Gemini 生成的 Jimmy IP 視覺 DNA 鑄造 Prompt 範本（第一部分）*

**Jimmy 的 Visual DNA 核心設定**：

- **CHARACTER NAME**: Jimmy

- **AESTHETIC STYLE**: High-detail 2D/3D hybrid rendering (Pixar meets Sci-Fi)

- **VISUAL DNA KEY TRAITS**:

1. **Hair**: Bright, spiky purple hair (Magenta/Violet tone)

2. **Signature Item**: Yellow banana headband with solar panel

3. **Outfit**: High-tech explorer jumpsuit (safety orange and neon green)

4. **Companion**: Pee-Wee（黃色香蕉機器人夥伴）

5. **Expression/Vibe**: Energetic, curious, determined

*圖 1-3：Prompt 範本包含靜態圖片與動態影片的生成範例*

**Prompt 範本的應用場景**：

1. **靜態圖片生成範例（故事性應用）**:

- TASK: Generate a full-body, high-resolution static image of Jimmy

- SCENE CONTEXT: Jimmy 在外星叢林中，站在巨大的機器人雕像頭上

- CAMERA/LIGHTING: Wide shot, 強調霓虹光效

2. **動態影片生成準備（動作一致性）**:

- TASK: Describe a 5-second action sequence

- ACTION/MOTION SEQUENCE: Jimmy 從機器人頭上跳躍至蘑菇帽

- 確保 Jimmy 的視覺一致性在整個動作中保持

*圖 1-4：Gemini 說明如何在開發 App 時使用這個 Visual DNA Prompt 範本*

**如何使用這個範本**：

- 在開發 App 時，可以將「**核心 IP 視覺 DNA 設定**」作為固定的參數模組

- 當使用者選擇生成圖片或影片時，只需修改「應用 1」或「應用 2」中的 **SCENE/TASK 內容**

- 這樣無論場景如何變化，AI 都會被追迫遵守 Jimmy 的核心視覺特徵（頭髮、香蕉頭帶、制服等），從而實現視覺一致性

**從 Visual DNA 到完整應用**：

有了這個 Prompt 範本後，下一步就是將它整合到應用中。我將這個範本帶到 **Google AI Studio**，並用它來生成完整的 React 應用程式。

- 打開 AI Studio 選取這個範本:

- 貼上剛剛透過 Gemini Web App 產生的 Prompt

**AI Studio 的回應**：

模型理解需求之後，產生一下檔案:

- `index.html`：包含 Import Maps 的入口檔案

- `App.tsx`：主應用邏輯（狀態管理、路由）

- `components/CharacterGenerator.tsx`：DNA 生成組件

- `components/ImageEditor.tsx`：圖像編輯組件

- `components/VideoGenerator.tsx`：Veo 影片生成組件

- `services/geminiService.ts`：所有 AI API 呼叫邏輯

**關鍵亮點**：

- ✅ Visual DNA 成為應用的核心參數

- ✅ 零安裝，直接可運行（No-Build）

- ✅ 完整的組件架構

- ✅ 預填的 Jimmy Visual DNA Prompt

*圖 1-5：AI Studio 的 Code Assistant 自動分析應用架構*

**一鍵部署到 Cloud Run**：

AI Studio 最強大的功能之一，就是生成完應用後，可以直接點擊「**Deploy app**」按鈕，一鍵部署到 Google Cloud Run：

*圖 1-6：AI Studio 介面中的「Deploy app」按鈕，支援一鍵部署至 Cloud Run*

點擊後，AI Studio 會自動：

• 📦 打包應用程式碼

• 🚀 部署至 Google Cloud Run

• 🔗 生成可公開訪問的 URL

*圖 1-7：部署成功通知，顯示應用已上線並提供 Cloud Run URL*

**時間成本**：約 30 分鐘（Gemini 對話 + AI Studio 生成 + 一鍵部署 + 初步測試）

這就是 AI First 開發的核心優勢：**從想法到可運行的應用程式，全程透過對話完成，無需手動配置伺服器或容器化流程**。

第 2 輪：測試發現問題 → 對話式修正

**測試階段發現的問題**：

使用者部署應用後測試，發現：

“為何其他使用者沒有輸入 API Key 也可以產圖、修圖、產影片？！”

**對話式修改**：

使用者直接在 AI Studio 中描述問題：

User: “passcode works! but...為何其他使用者沒有輸入 API key 也可以產圖, 修圖, 產影片？”

Gemini: “偵測到安全性問題！App.tsx 中自動讀取 process.env.API_KEY。

        解決方案：實作 BYOK (Bring Your Own Key) 機制...”

**AI 自動修正**：

Gemini 分析問題後，提供完整的修正方案：

1. **移除環境變數自動讀取**

// App.tsx

- const apiKey = process.env.API_KEY || “”;

+ const apiKey = localStorage.getItem(”gemini_api_key”) || “”;

2. **新增 ApiKeyInput Modal**

if (!apiKey) {

return <ApiKeyInput onSubmit={handleApiKeySubmit} />;

}

3. **更新 geminiService.ts**

// 強制使用者提供的 Key

const genAI = new GoogleGenerativeAI(userProvidedKey);

第 3 輪：功能需求變更 → 即時迭代

**新需求**：

使用者測試後提出新的安全需求：

“頁面重整時，或是頁面 idle 超過 5 mins，也要重新輸入 passcode”

**對話式開發**：

User: “頁面重整時, 或是頁面 idle 超過 5 mins, 也要重新輸入 passcode”

Gemini: “了解！需要兩個修改：

        1. 移除 sessionStorage 持久化

        2. 新增閒置計時器監聽 mousemove/keydown...”

**AI 生成的解決方案**：

1. **移除 Session Persistence**

- const [isUnlocked, setIsUnlocked] = useState(

-   sessionStorage.getItem(”unlocked”) === “true”

- );

+ const [isUnlocked, setIsUnlocked] = useState(false);

2. **新增 Idle Timeout 邏輯**

useEffect(() => {

if (isUnlocked) {

const timer = setTimeout(() => {

setIsUnlocked(false);

alert(”已閒置 5 分鐘，應用已鎖定”);

    }, 5 * 60 * 1000);

const resetTimer = () => { /* 重置邏輯 */ };

window.addEventListener(”mousemove”, resetTimer);

window.addEventListener(”keydown”, resetTimer);

return () => { /* 清理邏輯 */ };

  }

}, [isUnlocked]);

**成果**：

- ✅ 頁面刷新後需重新驗證

- ✅ 5 分鐘無操作自動鎖定

- ✅ 多層安全防護

第 4 輪：模型調整 → 一句話搞定

原因: veo 3.1 的 Token per min 蠻少，猶豫是否要改成 veo 3.0 or 2.0

**需求**：

“veo-3.1-fast-generate-preview 改成 veo-3.0-fast-generate-001，但是 veo-3.1 可以先註解掉”

**AI 的回應**：

Gemini: “明白！切換到穩定版本。修改 geminiService.ts：...”

**程式碼變更**：

// services/geminiService.ts

- const VIDEO_MODEL = “veo-3.1-fast-generate-preview”;

+ const VIDEO_MODEL = “veo-3.0-fast-generate-001”;

+ // 備用版本：veo-3.1-fast-generate-preview

**成果**：

- ✅ 切換至穩定版本

- ✅ 保留備用註解

- ✅ API 相容性提升

**時間成本**：約 5 分鐘（一句話 + AI 修改）

Master Prompt：將經驗固化為可重複流程

經過 4 輪迭代後，我們將所有需求、修正、最佳實踐整合成一個 **Master Prompt**。

任何人都可以用這個 Prompt 在 AI Studio 中**一次性生成完整的應用**，包含：

- ✅ 所有功能（DNA、編輯、Veo）

- ✅ 所有安全機制（BYOK、Passcode、Idle Timeout）

- ✅ 最佳實踐（Base64 處理、錯誤處理）

- ✅ 完整的檔案結構

*圖 5：使用 Master Prompt 在 AI Studio 中一鍵生成完整應用*

這就是 AI Studio 價值：將迭代過程中的知識累積，轉化為可重複、可分享的開發資產。

總結與展望

收穫：從「寫程式」到「對話式開發」

傳統開發：

想法 → 學習技術 → 寫程式 → 除錯 → 部署

（需要深厚的技術背景，時間成本高）

AI First：

想法 → 用自然語言描述 → AI 生成 → 測試 → 對話修改 → 部署

（會寫 Prompt 就能開發，1.5 小時完成）
（當然你還是要懂軟體工程與軟體架構！)

啟示

1. 想法驗證的速度是關鍵

• 傳統方式可能花數週實作，最後發現方向不對

• AI Studio 讓你在數小時內驗證想法可行性

• 快速失敗，快速迭代

2. 技術不再是瓶頸

• 不需要精通 React、Tailwind、API 設計

• 專注於產品邏輯與使用者需求

• AI 處理技術實作細節

3. Master Prompt 是可複製的資產

• 迭代過程中累積的知識可以固化為 Prompt

• 任何人都能用相同 Prompt 重現應用

Google AI Studio 在這次開發過程中的的價值

• 多模態整合：Imagen + Veo + Gemini 在同一平台

• 對話式迭代：持續對話中精準修改程式碼

• 即時反饋：生成 → 測試 → 修改循環只需數分鐘

資源

• Google AI Studio - 官方開發平台 https://aistudio.google.com/

但就像 Major Tom 的太空之旅,這種失重既是自由,也是失控的開始。

底下是之前研究 Major Tom 的連結，對，這篇其實是趁機記錄一下，以後自己找來播放比較方便，哈！

(訝異蠻多人不知道這首歌的意思)

原版 David Bowie 是從 阿姆斯壯 登陸月球產生的靈感:

我是從 Chris Hadfield 的版本開始聽的, 從太空艙看地球時唱這首歌好有感覺啊！

應該比較多人是從白日夢冒險王聽到:

或是 陳果《那夜凌晨，我坐上了旺角開往大埔的紅 van》（The Midnight After）

或是這邊有很棒的介紹文

Ground Control to Major Tom: 傳統開發流程的重力

“This is Ground Control to Major Tom

You’ve really made the grade”

在傳統的開發世界裡,我們像是被重力牢牢綁在地面上:

- **環境配置的重力**: `npm install`、Docker 容器、環境變數、依賴版本衝突

- **本地資源的重力**: 記憶體不足、磁碟空間、CPU 風扇狂轉

- **協作同步的重力**: Git 衝突、程式碼審查延遲、”works on my machine” 綜合症

Ground Control(傳統開發流程)總是在那裡,給我們指令、限制、框架。安全,可預測,但也沉重。

Stepping Through the Door: 進入雲端 IDE

“This is Major Tom to Ground Control

I’m stepping through the door”

當你第一次打開 Google Antigravity(或任何現代雲端 IDE):

**那扇門** = 瀏覽器分頁

**倒數計時** = 載入進度條

**發射** = 環境自動配置完成

不需要 `brew install`、不需要等待 Docker 啟動、不需要擔心 Python 版本。你只是「stepping through the door」,然後環境就準備好了。

這是第一次體驗失重的時刻——突然意識到,原來開發可以這麼「輕」。

Floating in a Most Peculiar Way: AI 輔助的奇妙感受

“And I’m floating in a most peculiar way

And the stars look very different today”

在 Antigravity 裡,AI 輔助編程帶來的感受確實是 “peculiar”(奇特的):

**失重感之一:智慧補全的預知能力**

你才剛開始打字,IDE 就已經「知道」你想寫什麼。就像在無重力環境中,輕輕一推就能滑行很遠——你只需要給一個意圖,AI 就幫你完成整段程式碼。

**失重感之二:語言的跨界流動**

在地面上,切換程式語言就像跨越國界——需要適應、學習、重新配置。但在 AI IDE 中,Python、JavaScript、Go 之間的界線變得模糊。AI 成為即時翻譯機,讓你在不同語言間「漂浮」。

**失重感之三:抽象層級的自由移動**

從高階架構設計到底層實作細節,AI 讓你可以在不同抽象層級間快速切換。不再需要「爬樓梯」——你可以直接「漂浮」到你需要的高度。

星星看起來確實不一樣了。

Planet Earth is Blue: 失重的代價

“Planet Earth is blue

And there’s nothing I can do”

但 Space Oddity 不只是讚頌太空旅行。歌曲後半段揭示了失控的一面——Major Tom 失去了與 Ground Control 的聯繫,漂浮在虛空中,無助而孤獨。

**雲端 IDE 的失控時刻:**

**網路斷線** = 失去生命線

當網路中斷,你突然意識到自己完全依賴這條看不見的連線。本地開發環境的「重力」,此刻反而成為一種安全感的來源。

**AI 的黑盒決策** = “There’s nothing I can do”

AI 給你的程式碼建議,有時候你不完全理解為什麼要這樣寫。你接受了,但也隱約感到一種失控——你是在編程,還是在「監督」AI 編程?

**供應商鎖定** = 無法返回地球

當你的整個工作流程都建立在特定雲端 IDE 上,遷移成本變得極高。就像 Major Tom 一樣,你可能真的回不去了。

Can You Hear Me, Major Tom?: 找到新的平衡

“Can you hear me, Major Tom?

Can you hear me, Major Tom?”

Ground Control 一直在呼叫,但 Major Tom 選擇了自己的路。

對於現代開發者,這不是「要不要使用雲端 IDE/AI 輔助」的二選一問題。真正的問題是:**如何在失重中找到平衡?**

**實踐心得:**

1. **保持本地備案**

就像太空人的逃生艙,維持一個精簡的本地開發環境。不是每天用,但關鍵時刻能救命。

2. **理解 AI 的建議**

不要盲目接受 AI 產生的程式碼。花時間理解它為什麼這樣寫,這是避免「失聯」的方式。就像 Major Tom 應該保持與 Ground Control 的溝通。

3. **選擇可遷移的技術棧**

使用開放標準、避免過度依賴專有功能。給自己保留「返回地球」的選項。

4. **享受失重,但記得重力**

AI 輔助帶來的效率提升是真實的,但不要忘記基礎原理。失重很爽,但你需要知道重力如何運作。

Here Am I Sitting in a Tin Can: 終極的孤獨與自由

“Here am I sitting in a tin can

Far above the world

Planet Earth is blue

And there’s nothing I can do”

Space Oddity 的結局是開放的——Major Tom 到底怎麼了?他死了?迷失了?還是找到了新的存在方式?

使用 Google Antigravity(或任何次世代 IDE)的體驗也是如此。你確實在一個「tin can」(瀏覽器視窗)裡,遠離傳統開發的地面。地球(傳統開發方式)在下方變得越來越藍、越來越遙遠。

**但這不一定是壞事。**

也許,這就是開發的未來——我們不再被重力(環境配置、資源限制、協作摩擦)束縛。我們學會在失重中工作,在 AI 的輔助下「漂浮」得更快、更遠。

也許,Major Tom 並沒有失控。他只是找到了一種新的存在方式——一種我們還不完全理解,但已經無法回頭的方式。

## 實用指南:你的 Liftoff Checklist

如果你決定開始自己的「太空之旅」,建議:

**發射前檢查(Pre-launch):**

- [ ] 了解 Antigravity 的基本功能和限制

- [ ] 準備本地備份方案(以防網路問題)

- [ ] 選擇一個試驗性專案開始(不要直接用生產環境)

**軌道中(In Orbit):**

- [ ] 學習 AI 快捷鍵和 prompt 技巧

- [ ] 建立程式碼審查習慣(不盲目接受 AI 建議)

- [ ] 記錄遷移痛點和最佳實踐

**返回準備(Re-entry Plan):**

- [ ] 保持技術棧的可遷移性

- [ ] 定期匯出重要設定和程式碼

- [ ] 維持對底層技術的理解

---

*”Check ignition and may God’s love be with you”*

Liftoff 的時刻,既興奮又不安。但也許這就是進步的本質——離開已知的地面,進入未知的太空。

Google Antigravity 不只是一個 IDE,它是一個關於未來開發方式的宣言:**我們正在離開地球**。問題不是要不要走,而是我們能否在失重中,找到新的平衡與掌控。

各位 Major Tom,準備好了嗎?

*”This is Ground Control to Major Tom... Commencing countdown, engines on...”*

**延伸閱讀:**

- [Google Antigravity 官方文件](https://developers.google.com/antigravity)

一個在傳統 IDE 和雲端環境之間漂浮的全端工程師,仍在尋找 Ground Control 的訊號。

---

*P.S. 如果你也是 David Bowie 粉絲,推薦聽完整專輯。Space Oddity 只是開始,後面還有 Ashes to Ashes,講述 Major Tom 的後續故事...*

The Problem

Common repetitive work when using Antigravity IDE:

Day 1:

Developer: Create a React component

AI: Sure, using class component

Developer: No, we only use function components

AI: Understood, corrected

Day 2 (new conversation):

Developer: Create another React component

AI: Sure, using class component

Developer: (explaining again...) We only use function components

Day 3 (reopen project):

Developer: Create login component

AI: Which framework should I use?

Developer: (third time...) React, function component, TypeScript

Every time you start a new conversation or restart the IDE, you have to tell the AI again:

- Code style preferences

- Naming conventions

- Testing requirements

- Documentation format

These rules should be part of the project, not something you explain every time.

The Solution

**Antigravity provides two official mechanisms** to make AI automatically follow your development standards:

1. Rules

- Like “system prompts”

- Always active, no need to remind every time

- Define AI’s behavior guidelines

2. Workflows

- Like “quick actions”

- Trigger on demand, execute complex tasks

- Standardize repetitive work

Get Started: Experience Rules & Workflows with agy-starter

Instead of starting with theory, let’s dive right in. We’ve prepared a complete example project `agy-starter` for hands-on learning.

Repo: https://github.com/AgentWorkshop/agy-starter.git

Step 1: Clone the Project

git clone https://github.com/AgentWorkshop/agy-starter.git

cd agy-starter

Open this folder in Antigravity IDE (File → Open Folder → select `agy-starter/`)

💡 What are Rules?

After opening the project, Antigravity automatically reads the `.antigravity/rules.md` file. **Rules are AI’s behavior guidelines**, like a constitution that’s always in effect:

• **Always active**: No need to repeat instructions every conversation

• **Auto-applied**: AI automatically loads when opening the project

• **Team-shared**: After committing to git, all members follow the same standards

**Example:** Open `.antigravity/rules.md` to see complete writing standards. Try asking AI to create a new article - it will automatically follow these rules.

Step 2: Explore Project Structure

View the project file tree:

*Image: agy-starter project structure - actual file tree in Antigravity IDE*

💡 File Location Explanation

Antigravity projects have two official directories:

`.antigravity/rules.md` - Project Standards

• AI’s behavior guidelines

• Auto-loaded, always active

`.agent/workflows/` - Workflows

• Reusable task templates

• Triggered with `/commands`

**Tip:** You can also set global configuration (`~/.gemini/GEMINI.md`) for personal preferences across all projects.

Step 3: Try Your First Workflow

In the Antigravity conversation, type: `/`

You’ll see the list of available workflows:

*Image: Triggering a Workflow - interface after typing /*

Select `/create` to have AI create a new article.

💡 What are Workflows?

**Workflows are reusable task templates**, like scripts:

• **Standardized process**: Ensures consistent steps every time

• **Time-saving**: No need to describe steps in detail each time

• **Team collaboration**: Everyone completes tasks the same way

**Workflows included in agy-starter:**

• `/create` - Create new article (with template and image directory)

• `/update` - Update code examples in articles

• `/proof` - Proofread article (check format, links, tone)

Open `.agent/workflows/create-article.md` to see the workflow structure: includes step instructions, examples, and expected results.

Step 4: Customize Your Rules

Now that you understand how Rules work, try editing `.antigravity/rules.md` to match your project needs.

💡 Writing Good Rules

**❌ Bad Examples (too abstract):**

- Write good code

- Follow best practices

**✅ Good Examples (specific and clear):**

- Use Function Components, not Class Components

- Props must define TypeScript interface

- Every component must have a corresponding .test.tsx file

**Editing Steps:**

1. Open `.antigravity/rules.md`

2. Modify standards based on your project tech stack

3. Save and reload Antigravity (or start a new conversation)

4. Test if AI follows the new rules

Step 5: Create Your First Workflow

Try creating a new workflow file in `.agent/workflows/`.

💡 Workflow Structure

Basic format:

---

description: Brief description of what this workflow does

---

## Steps

### 1. First Step

- Specific operation instructions

- Expected results

### 2. Second Step

- Specific operation instructions

- Expected results

**Example: Generate Test Files**

---

description: Generate unit tests for existing code

---

## Steps

### 1. Analyze Target File

- Read the specified code file

- Identify all exported functions

### 2. Generate Test Cases

- Create at least 3 tests for each function

- Use clear test names

### 3. Run Tests

- Automatically execute npm test

- Verify all tests pass

Save as `.agent/workflows/generate-tests.md`, then trigger it with `/generate`.

Deep Understanding

Global vs Workspace Rules

You might wonder: When should I use global Rules vs project Rules?

**Global Configuration (`~/.gemini/GEMINI.md`):**

• Personal code style (applies to all projects)

• Preferred naming conventions

• Documentation writing habits

**Project Configuration (`.antigravity/rules.md`):**

• Project-specific tech stack

• Team-shared standards

• Client-specific requirements

**Priority:** Workspace Rules > Global Rules (project settings take precedence)

FAQ

Q: What’s the difference between Rules and Workflows?*

A: Rules are “passive guidelines”, Workflows are “active tasks”

Q: When I reopen the project, do Rules still work?

A: Yes! Rules and Workflows are stored in project files, and AI automatically loads them every time you open the project.

Q: What if team members don’t have Antigravity?

A: These files are plain text Markdown and can be read as the project’s CONTRIBUTING.md.

## Summary

**After implementing Rules & Workflows, you’ll see:**

✅ **No more repetition** - Set once, AI remembers forever

✅ **Instant onboarding** - New team members get the same AI behavior

✅ **Consistent quality** - All code follows the same standards

✅ **Time savings** - Complex tasks become one-command operations

✅ **Knowledge transfer** - Project standards are documented and executable

Start using agy-starter and experience the power of Antigravity Rules & Workflows! 🚀

Resources

- [Google Developers Blog - Antigravity Launch] - link

- [Google Codelabs - Antigravity Tutorial] - link

- [Antigravity Workspace Template]: https://github.com/jimmyliao/antigravity-web-fullstack

- [Antigravity Codes - Workflows Guide] link

Jimmy Liao

• CTO/Co-founder @ Stealth Startup

問題

在使用 Antigravity IDE 開發時，常見的重複工作:

第一天：

開發者：建立一個 React 元件

AI：好的，使用 class component

開發者：不對，我們只用 function component

AI：了解，已修正

第二天（新對話）：

開發者：建立另一個 React 元件

AI：好的，使用 class component

開發者：（又要重新解釋...）我們只用 function component

第三天（重新開啟專案）：

開發者：建立登入元件

AI：要用什麼框架？

開發者：（第三次...）React，function component，TypeScript

每次開新對話、重啟 IDE，都要重新告訴 AI：

- 使用的程式碼風格

- 命名慣例

- 測試要求

- 文件格式

這些規則應該是專案的一部分，而不是每次都要口頭說明。

解決方案

Antigravity 官方提供兩種機制，讓 AI 自動遵循你的開發規範：

1. Rules（規則）

- 類似「系統指令」

- 永遠生效，不需要每次提醒

- 定義 AI 的行為準則

2. Workflows（工作流程）

- 類似「快捷指令」

- 按需觸發，執行複雜任務

- 標準化重複性工作

用 agy-starter 體驗 Rules & Workflows

與其從理論開始，不如直接動手試試。我們準備了一個完整的範例專案 `agy-starter`，讓你邊做邊學。

Repo: https://github.com/AgentWorkshop/agy-starter

步驟 1：Clone 專案並開啟

git clone https://github.com/AgentWorkshop/agy-starter.git

cd agy-starter

在 Antigravity IDE 中開啟此資料夾（File → Open Folder → 選擇 `agy-starter/`）

💡 什麼是 Rules？

打開專案後，Antigravity 會自動讀取 `.antigravity/rules.md` 檔案。**Rules 是 AI 的行為準則**，就像憲法一樣永遠生效：

• **永遠生效**：不需要每次對話都重複說明

• **自動套用**：開啟專案時 AI 自動載入

• **團隊共享**：commit 到 git 後，所有成員都遵循同樣規範

範例： 打開 `.antigravity/rules.md`，你會看到文章撰寫的完整規範。試著讓 AI 建立新文章，它會自動遵循這些規則。

步驟 2：探索專案結構

查看專案檔案結構：

*圖片說明：agy-starter 專案結構 - 在 Antigravity IDE 中的實際檔案樹*

💡 檔案位置說明

Antigravity 專案有兩個官方目錄：

1. `.antigravity/rules.md` - 專案規範

• AI 的行為準則

• 自動載入，永遠生效

2. `.agent/workflows/` - 工作流程

• 可重複使用的任務範本

• 用 `/指令` 觸發

Tips： 也可以在全域設定（`~/.gemini/GEMINI.md`），適用所有專案的個人偏好。

步驟 3：體驗第一個 Workflow

在 Antigravity 對話中輸入：`/`

你會看到可用的 workflows 列表：

*圖片說明：觸發 Workflow - 輸入 / 後的介面*

選擇 `/create`，讓 AI 建立一篇新文章。

💡 什麼是 Workflows？

Workflows 是可重複使用的任務範本，就像腳本一樣：

• **標準化流程**：確保每次執行步驟一致

• **節省時間**：不用每次都詳細描述步驟

• **團隊協作**：所有人用同樣方式完成任務

agy-starter 包含的 workflows：

• `/create` - 建立新文章（含模板、圖片目錄）

• `/update` - 更新文章中的程式碼範例

• `/proof` - 校對文章（檢查格式、連結、語氣）

打開 `.agent/workflows/create-article.md` 看看 workflow 的結構：包含步驟說明、範例、和預期結果。

步驟 4：自訂你的 Rules

現在你理解 Rules 的運作方式，試著編輯 `.antigravity/rules.md` 來匹配你的專案需求。

💡 撰寫好的 Rules

❌ 不好的範例（太抽象）：

- 寫出好的程式碼

- 遵循 Best Practice

✅ 好的範例（具體明確）：

- 使用 Function Component，不要用 Class Component

- Props 必須定義 TypeScript interface

- 每個元件都要有對應的 .test.tsx 檔案

編輯步驟：

1. 開啟 `.antigravity/rules.md`

2. 根據你的專案技術棧修改規範

3. 儲存後重新載入 Antigravity（或開新對話）

4. 測試 AI 是否遵循新規則

步驟 5：建立你的第一個 Workflow

試著在 `.agent/workflows/` 建立一個新的 workflow 檔案。

💡 Workflow 結構

基本格式：

---

description: 簡短描述這個 workflow 做什麼

---

## 步驟

### 1. 第一個步驟

- 具體操作說明

- 預期結果

### 2. 第二個步驟

- 具體操作說明

- 預期結果

範例：建立測試檔案

---

description: 為現有程式碼產生單元測試

---

## 步驟

### 1. 分析目標檔案

- 讀取指定的程式碼檔案

- 識別所有 exported functions

### 2. 產生測試案例

- 為每個 function 建立至少 3 個測試

- 使用清楚的測試名稱

### 3. 執行測試

- 自動執行 npm test

- 確認所有測試通過

儲存為 `.agent/workflows/generate-tests.md`，然後用 `/generate` 觸發它。

深入理解

Global vs Workspace Rules

你可能會疑惑：什麼時候用全域 Rules，什麼時候用專案 Rules？

全域設定（`~/.gemini/GEMINI.md`）：

- 個人程式碼風格（適用所有專案）

- 慣用的命名方式

- 文件撰寫習慣

專案設定（`.antigravity/rules.md`）：

- 專案特定技術棧

- 團隊共享規範

- 客戶特殊要求

優先順序： Workspace Rules > Global Rules（專案設定優先）

常見問題

Q: Rules 和 Workflows 有什麼不同？

A: Rules 是「被動規則」，Workflows 是「主動任務」

Q: 重新開啟專案時，Rules 還會生效嗎？

A: 是的！Rules 和 Workflows 儲存在專案檔案中，每次開啟專案 AI 都會自動載入。

Q: 團隊成員沒有 Antigravity 怎麼辦？

A: 這些檔案是純文字 Markdown，可以當作專案的 CONTRIBUTING.md 閱讀。

總結

實施 Rules & Workflows 後

✅ 不再重複 - 設定一次，AI 永遠記得

✅ 即時 onboarding - 新成員立刻獲得相同的 AI 行為

✅ 品質一致 - 所有程式碼遵循相同標準

✅ 複雜任務變成一鍵操作

✅ 專案規範被文件化且可執行

相關資源

• Google Developers Blog - Antigravity 發布 - link

• Google Codelabs - Antigravity 教學 - link

• Antigravity Workspace Template - https://github.com/jimmyliao/antigravity-web-fullstack

• Antigravity Codes - Workflows 指南 link

Jimmy Liao

• CTO/Co-founder @ Stealth Startup

VS Code 擴充套件，在狀態列顯示 Antigravity AI 模型的額度使用情況

*圖片說明：AGQ 擴充套件主視覺，展示狀態列整合效果*

---

問題

在使用 Antigravity 進行開發時，AI 模型的額度管理是個實際問題。當額度用盡時，開發流程會被迫中斷，但目前沒有簡單的方式即時掌握各模型的使用狀況。

開發者需要手動進入設定頁面查看額度，這在實際工作中並不實用。

---

解決方案

Antigravity Quota (AGQ) 是一個輕量級的 VS Code 擴充套件，將額度資訊整合到狀態列。

*圖片說明：VS Code 狀態列顯示 “AGQ” 圖示，點擊後展開用量詳情*

主要功能

• 即時顯示所有 AI 模型的用量百分比

• 倒數計時器顯示額度重置時間

• 可自訂要顯示的模型

• 手動刷新功能

• 狀態列整合，隨時可見

採用情況

• henrikdev 持續維護

• 開源且免費

🤖 支援的 AI 模型

AGQ 支援 Antigravity IDE 中所有主流 AI 模型

模型選擇策略

根據任務複雜度和額度狀況選擇適當模型：

日常開發任務

• Gemini 3 Pro (Low) 或 Claude Sonnet 4.5

  • 適用於常見的 CRUD、重構、除錯

複雜問題處理

• Claude Sonnet 4.5 (Thinking) 或 Claude Opus 4.5

• 適用於架構設計、演算法優化、系統整合

額度不足時

• 切換到 GPT-OSS 120B

• 或優先處理可手動完成的工作

安裝

透過 Marketplace

1. 開啟 Extensions 面板 (`Cmd/Ctrl + Shift + X`)

2. 搜尋 “Antigravity Quota”

3. 點擊 Install

初次設定

安裝完成後，狀態列會出現 “AGQ” 圖示。

*圖片說明：VS Code 狀態列右下角的 AGQ 圖示*

點擊模型名稱左側的圓圈來切換顯示/隱藏：

- ✅ 勾選 = 顯示在狀態列

- ⭕ 未勾選 = 隱藏

*圖片說明：點擊模型前的圓圈切換顯示狀態*

需要即時更新

• 使用指令面板 (`Cmd/Ctrl + Shift + P`)

• 執行 `AGQ: Refresh Now`

進階使用

模型切換策略

根據額度剩餘百分比調整模型選擇：

額度 > 80%  → 任何模型皆可

額度 50-80% → 優先中階模型（Sonnet, Gemini Low）

額度 < 50%  → 僅使用低階模型，保留高階模型給關鍵任務

額度 < 20%  → 暫停 AI 輔助，等待重置或手動處理

時間分配

AGQ 顯示的重置週期通常約 157 小時（約 6.5 天）：

週期前段（Day 1-3）→ 可使用高階模型進行架構設計、重構

週期中段（Day 4-5）→ 切換中階模型處理一般開發任務

週期後段（Day 6-7）→ 保守使用，以低階模型或手動開發為主

快捷鍵設定

可在 Antigravity 設定自訂快捷鍵：

// keybindings.json

{

“key”: “cmd+shift+q”,

“command”: “agq.refreshNow”,

“when”: “editorTextFocus”

}

可用指令

• `AGQ: Refresh Now` : 手動重新整理額度資訊

• `AGQ: Open Settings` : 開啟 Antigravity 設定

• `AGQ: Toggle Model Visibility` : 切換模型顯示

執行方式

開啟指令面板 (`Cmd/Ctrl + Shift + P`)，輸入 `AGQ` 選擇指令。

*圖片說明：VS Code 指令面板顯示 AGQ 相關指令*

延伸閱讀

Antigravity Fullstack Template

AGQ 解決了額度監控問題，但在專案開發效率上還有優化空間。

Antigravity Fullstack Template 提供：

- 繁體中文開發環境

- 預設整合的 AI 協作規則

- 完整的工具鏈和專案結構

git clone https://github.com/jimmyliao/antigravity-web-fullstack.git

完整說明請靜待下一篇 →

Jimmy Liao

• CTO/Co-founder @ Steath Mode Startup

• GitHub: @jimmyliao

• Template: antigravity-web-fullstack: https://github.com/jimmyliao/antigravity-web-fullstack

相關資源

• [AGQ Extension - VS Code Marketplace](https://github.com/Henrik-3/AntigravityQuota/tree/v1.0.4)

• [Antigravity 官方文件](https://docs.antigravity.com)

• [GitHub Repository](https://github.com/jimmyliao/antigravity-web-fullstack)

*最後更新：2025年12月13日*

Google 最近推出了 Gemini Interactions API，為開發者建構有狀態 AI 應用程式的方式帶來了範式轉移。與傳統需要自行管理對話歷史的方法不同，這個 API 提供了內建的對話狀態管理功能。雖然這簡化了開發流程，但也伴隨著值得仔細審視的架構影響和成本考量。

什麼是 Interactions API？

Interactions API 實現了具有持久狀態管理的多輪對話功能。開發者不需要手動追蹤對話歷史並在每次請求時傳遞，API 會透過 Interaction Objects 自動處理這一切——這些結構化記錄封裝了使用者訊息、模型回應、工具呼叫和工具結果。

核心功能

• 自動狀態管理：API 透過 `previous_interaction_id` 在多輪對話中維護對話上下文

• 工具編排：無縫整合函數呼叫、內建工具（Google 搜尋、程式碼執行）和 MCP 伺服器

• 長時間運行任務：支援背景執行的非同步操作（`background=true`）

• 內建記憶體：伺服器端儲存對話歷史

儲存架構：雖然文件中沒有明確說明，但這些 Interaction Objects 很可能儲存在 Google Cloud Storage (GCS) 或類似的持久化基礎設施中，這直接影響了資料保留政策和成本。

1 天 vs. 55 天保留期

免費方案

• 資料保留期: 1 天

• 場景: 快速示範、測試、無狀態應用

• 限制: 無法支援回訪使用者或需要持久記憶的應用

付費方案

• 資料保留期: 55 天

• 場景: 具有對話歷史的生產環境應用

• 限制: 儲存成本累積；必須管理資料生命週期

🚨 免費方案使用者的影響

24 小時保留限制從根本上限制了你能建構的應用類型。在 25 小時後，你無法使用 `previous_interaction_id` 來繼續對話——伺服器端的狀態已經消失。這迫使開發者必須：

- 只建構無狀態或短會話的應用程式

- 為超過 24 小時的使用者上下文實作外部記憶體儲存

- 在客戶端手動管理對話歷史（無狀態模式）

解決方案：如果你在免費方案上需要超過 24 小時的記憶，必須實作自己的解決方案，使用外部資料庫、向量儲存或類似的持久化層。

💸 付費方案的隱藏成本

升級到付費方案可獲得 55 天的保留期，但引入了新的成本維度：

傳統 LLM 成本：

1. 輸入 Token（提示處理）

2. 輸出 Token（回應生成）

Interactions API 的新成本：

3. 互動儲存成本

對於高流量應用，這會快速累積：

範例：客戶支援聊天機器人

- 每天 10,000 位使用者

- 平均每位使用者 5 次互動

- 每天 50,000 個互動物件

- 保留 55 天 = 275 萬個儲存物件

- 即使每個物件只需幾分錢，這也會累積成可觀的數字

控制儲存：Opt-in 選擇

關鍵是，你可以透過 `store` 參數控制要儲存什麼：

何時應該使用 `store=false`：

• GDPR/HIPAA 合規要求

• 敏感的財務或醫療資料

• 臨時除錯會話

• 高頻率、低價值互動

限制：當 `store=false` 時，你無法在後續輪次中使用 `previous_interaction_id`，因為互動沒有在伺服器端持久化。你必須改為在客戶端管理狀態。

架構決策框架

在採用 Interactions API 之前，評估以下問題：

1. 記憶持續時間需求

如果所需記憶 ≤ 24 小時：

    → 免費方案可能足夠

如果 24 小時 < 所需記憶 ≤ 55 天：

    → 需要付費方案

如果所需記憶 > 55 天：

    → 需要混合方法（API + 外部儲存）

2. 資料敏感性與合規性

高敏感性（財務、醫療、個人）：

• 考慮對所有互動使用 `store=false`

• 實作自己的加密安全儲存

• 仔細審查資料處理協議

中等敏感性（商業資料）：

• 審查 Google 的資料處理條款

• 考慮僅對敏感輪次選擇退出

• 實作生命週期管理

低敏感性（公開內容、示範）：

• 完全接受 API 便利性

• 標準保留政策即可滿足

3. 成本

計算每月總成本，包括：

• Token 成本：輸入和輸出 token 使用量

• 儲存成本：互動數量 × 保留期 × 每次互動的儲存成本

• 平均儲存互動數：每日互動數 × 27.5（55 天的平均值）

對於每日互動量高的應用程式，儲存成本可能成為 API 總帳單的重要組成部分。

混合架構模式

對於具有多樣化需求的生產應用，混合方法提供了最佳平衡：

短期上下文（≤55 天）：

• 使用 Interactions API 與 `previous_interaction_id`

• 利用自動狀態管理

• 受益於隱式快取以提升效能

長期上下文（>55 天）：

• 在向量資料庫中儲存摘要

• 檢索相關上下文並注入新互動

• 維持對資料生命週期的控制

敏感資料：

• 對敏感互動使用 `store=false`

• 在你的安全資料庫中儲存加密版本

• 遵守監管要求

無狀態操作：

• (待續)

進階功能

Interactions API 超越了簡單的對話：

多輪對話：同時支援有狀態（伺服器管理）和無狀態（客戶端管理）模式

工具整合：函數呼叫、內建工具（Google 搜尋、程式碼執行、URL 上下文）和遠端 MCP 伺服器

多模態：支援圖像理解、音訊處理、影片分析、PDF 文件和圖像生成

結構化輸出：JSON schema 強制執行以實現可靠的資料提取和分類

串流：在生成時逐步接收回應

背景執行：支援非同步輪詢的長時間運行任務（僅限代理, aka. Agent）

限制與考量

Beta 狀態：API 處於 beta 階段——schema 和功能可能會有破壞性更新

工具組合：混合使用 MCP、函數呼叫和內建工具有一些限制

輸出排序：某些內建工具的工具結果排序存在已知問題

模型支援：目前支援 Gemini 2.5 Flash、2.5 Pro 和 3 Pro Preview 模型，以及 Deep Research 代理

結論

Gemini Interactions API 為建構對話式 AI 應用提供了顯著的便利性，但它不是萬靈丹。內建的記憶體管理帶來了明確的權衡：

✅ 優勢：

- 簡化開發工作流程

- 自動狀態管理

- 無縫工具編排

- 減少基礎設施負擔

- 快取帶來的效能優勢

⚠️ 考量事項：

- 嚴格的保留限制（1 天或 55 天）

- 儲存成本捆綁到 API 使用中

- 資料主權和合規性影響

- 潛在的供應商鎖定

- Beta 期間可能出現破壞性變更

建議：將 Interactions API 視為你架構中的有價值工具，而非完整解決方案。對於大多數生產應用，混合方法提供了最佳平衡——利用 API 的便利性處理短期到中期狀態，同時維護你自己的系統來處理長期記憶、敏感資料和自訂分析。

關鍵在於提前理解這些限制並相應地設計你的架構。只有這樣，你才能在保持對成本、合規性和使用者體驗控制的同時，充分利用 API 的強大功能。

---

資源

• [官方 Interactions API 文件](https://ai.google.dev/gemini-api/docs/interactions)

• [使用 ADK 和 Interactions API 建構代理](https://developers.googleblog.com/building-agents-with-the-adk-and-the-new-interactions-api/)

• [Google AI 部落格：Interactions API 公告](https://blog.google/technology/developers/interactions-api/)

• [API 參考文件](https://ai.google.dev/api/interactions-api)

This is the the the speak experience from DevFest Taichung, DevFest Taipei. You can check the online deck here. or https://devfest2025taipei-jimmyliao.web.app/

• Enterprise level Agentic dev workflow with Gemini CLI, ADK, and Antigravity

Introduction: Agentic AI as an Orchestration Challenge

At DevFest Taipei 2025, I had the opportunity to share insights from building an enterprise-grade AI agent platform across cities (Taichung, Taipei, and beyond). The core lesson? Treat agentic development as an orchestration problem, not just a coding exercise.

Most enterprises face similar challenges when adopting AI:

- **Sensitive data restrictions**: Can’t upload proprietary data to cloud LLM providers

- **Internal authentication hurdles**: Legacy systems with complex auth requirements

- **Lack of standardized APIs**: Every internal tool speaks a different language

- **Tool fragmentation**: Developers juggle multiple AI platforms with inconsistent interfaces

The solution isn’t building everything from scratch—it’s about smart orchestration through standards like **MCP (Model Context Protocol)**, rapid prototyping with **Gemini CLI**, and production deployment via **Google ADK SDK**.

*Full technical notes:* https://hackmd.io/@devfest-taipei-2025/SyFuv9gZWl

---

Architecture: Three Ways to Integrate MCP

Our architecture demonstrates **three validated MCP client approaches**, each serving different deployment needs:

```

Developer → [MCP Clients] → MCP Protocol → [4 MCP Servers]

↓ ↓

[1] Gemini CLI Enterprise Data

[2] Google Antigravity Internal APIs

[3] Standalone Python Document DB

```

Core Components

**MCP Protocol**: The standardization layer that connects AI models to enterprise tools using two transport modes:

- **SSE (Server-Sent Events)**: For remote MCP servers (HTTP-based)

- **STDIO**: For local MCP servers (process-based, higher security)

**Three MCP Client Validations**:

1. **Gemini CLI** (Remote MCP, SSE transport)

- 1M+ token context window

- Free quota for rapid prototyping

- Ideal for developer experimentation

2. **Google Antigravity (or AnythingLLM)** (Local MCP, STDIO transport)

- Enterprise Web UI with RAG capabilities

- Docker-based deployment (`anythingllm-adk`)

- Verified with Taiwan Stock MCP + Investment Agent

3. **Standalone Python** (Direct execution)

- No MCP layer needed

- Direct ADK agent execution

- Best for demos and benchmarking

**Development Frameworks**:

- **FastMCP**: Build MCP servers in ~50 lines of Python

- **Google ADK SDK 1.17.0**: Agent-first architecture with automatic tool orchestration

---

Five Key Implementations

1. Browserbase: Open-Source Browser Automation

Native MCP support for cloud-based browser automation—demonstrating MCP’s versatility beyond data APIs.

2. FastMCP Taiwan Stock Query ⭐

**50 lines of Python** to build a production-ready MCP server using the FastMCP framework. Serves real-time Taiwan stock data over SSE (Port 8080). This implementation showcases **MCP’s accessibility**: you don’t need complex infrastructure to get started.

3. Enterprise Document Management MCP ⭐

Goes beyond simple document search—includes **compliance checking** with sensitive data detection. All processing happens locally, ensuring **zero data leakage** to external LLM providers. This addresses the #1 concern for regulated industries.

4. Google Antigravity (or AnythingLLM) Integration ⭐

**Official name**: Google Antigravity (open-sourced as AnythingLLM)

**Role**: MCP Client with STDIO transport for local integration

**Features**:

- Enterprise Web UI replacing CLI workflows

- RAG (Retrieval-Augmented Generation) for document grounding

- Docker-based deployment with `google-adk` pre-installed

**Validation**: Successfully integrated Taiwan Stock MCP (STDIO mode) + Investment Agent—proving the **CLI-to-Web UI evolution path**.

5. Google ADK Investment Agent ⭐⭐

**Impact**: **3 seconds** (automated) vs. **3.5 hours** (manual) for investment analysis reports

**Features**:

- Multi-tool reasoning (combines stock price APIs + document search)

- Automatic tool orchestration—no hardcoded workflows

- **Three-version architecture**:

- Standalone Python (for demos)

- Remote MCP Server (for Gemini CLI)

- STDIO MCP (for AnythingLLM)

This demonstrates ADK’s **agent-first design**: define capabilities, let the framework handle orchestration.

---

Deployment Strategy: Remote vs. Local MCP

**Remote MCP** (SSE/HTTP):

- Deploy to Cloud Run, Kubernetes, or any HTTP endpoint

- Cross-platform support (any MCP-compatible client)

- Trade-off: Network latency, requires internet access

**Local MCP** (STDIO):

- Process-based, runs on the same machine as the client

- **Faster** (no network overhead) + **More Secure** (no external traffic)

- Ideal for **sensitive data workflows**

**Decision rule**: For regulated industries or proprietary data → **Local MCP**. For shared enterprise services → **Remote MCP**.

---

Key Takeaways for AI/ML Engineers

1. Treat Agentic AI as an Orchestration Challenge

- **MCP Protocol**: Standardize tool integration (stop reinventing the wheel)

- **Gemini CLI + ADK**: Provide reasoning and automatic orchestration

- **Shift thinking**: From “I need to build everything” to “How do I compose existing capabilities?”

2. Incremental Path: CLI → Production

- **Stage 1**: Gemini CLI (free quota, 1M context, rapid prototyping)

- **Stage 2**: MCP Servers (standardized tool layer)

- **Stage 3**: Vertex AI / Cloud Run (enterprise deployment)

**Don’t start with production complexity**—validate with CLI first.

3. Methodology > Code

- **1,952 lines of docs** > 10,000 lines of implementation code

- **Reusable templates** = sustainable innovation

- **10-minute replication** > 2-week rewrite

**Example**: Our .NET Conf 2025 prep took 5 days (not 3 weeks) because we had templates.

---

Resources

**Live Slides**: https://devfest2025taipei-jimmyliao.web.app/

**Workshop Site**: https://devfest2025-workshop-jimmyliao.web.app/

**Technical Walkthrough**: https://hackmd.io/@devfest-taipei-2025/SyFuv9gZWl

**Official Documentation**:

- MCP Protocol: https://modelcontextprotocol.io

- Google ADK SDK: https://github.com/google/adk-python

- Gemini CLI:

**Connect**: https://linktr.ee/jimmyliao

---

Closing Thoughts

Building production-ready AI agents isn’t about writing the most code—it’s about **orchestrating the right components** with proven patterns. The DevFest 2025 journey taught us that:

1. **Standards matter**: MCP eliminates integration chaos

2. **Start small, scale smart**: Gemini CLI → MCP → Production

3. **Methodology compounds**: Reusable templates pay dividends

If you’re building agentic AI systems, don’t start from scratch. Leverage MCP, experiment with Gemini CLI’s free tier, and document your patterns—your future self (and team) will thank you.

---

**Tags**: #AI-Agents #MCP #GeminiCLI #GoogleADK #AnythingLLM #DevFest #AgenticAI #EnterpriseAI

**Published**: December 2025

**Author**: Jimmy Liao | Google Developer Expert (AI)

**License**: CC BY 4.0 (code examples), text content © 2025

---

*Generated with insights from DevFest Taichung, DevFest Taipei, and .NET Conf 2025 workshop experiences.*

在 Google Antigravity 點下 Cmd + Shift + P, 輸入 language, 選擇 Configure Display Language

輸入 Tranditional, 會跳出 Chinse (Tranditional) Language Pack for Visual Studio Code. 點選 Trust Publisher and Install.

重開機

#Antigravaty

#AISprintH2

1. 透過這個連結直接在 AI Studio 試試吧: https://goo.gle/try-gemini3

2. 專案 repo => https://github.com/jimmyliao/lab-gemini-3

=> 幫忙按個 Star, Fork, 跟貢獻吧！

核心技術選型

使用者輸入 (自然語言)
    ↓
Gemini 3 Pro Agent (理解意圖 + 編排工具)
    ↓
Multi-Tool Integration
    ├─→ Google Flights API (fast-flights)
    ├─→ Google Maps MCP
    └─→ Gemini Grounding (即時資訊)
    ↓
Gemini 3 Pro (整合所有資訊)
    ↓
結構化輸出 (完整行程規劃)

專案設置

首先創建專案結構並設置環境：

git clone https://github.com/jimmyliao/lab-gemini-3

cd lab-gemini-3.0/

初始化專案

make setup

# 進入虛擬環境
source .venv/bin/activate

# 運行旅遊顧問 demo
python examples/travel_advisor.py

Demo 會展示：

1. 航班搜尋功能（TPE → NRT）

2. 景點推薦功能（東京熱門景點）

3. 完整 3 天 2 夜旅遊行程規劃

…

Gemini Agent

agent.py 提供了 Gemini 3.0 Pro 的封裝：

from gemini_adk_demo.agent import create_agent

# 創建 Agent
agent = create_agent(
    model=”gemini-3-pro-preview”,
    name=”my_assistant”
)

# 發送查詢
response = agent.query(”解釋量子計算”)
print(response)

Google 在今天 (2025-11-18) 發佈了 Gemini 3 Pro，這是迄今為止最先進的基礎模型，具備卓越的推理能力、1M tokens 長上下文處理和原生多模態支援。本文將透過實際的 Gemini-CLI 測試，深入探討 Gemini 3 Pro 的核心能力、技術規格，並提供完整的測試腳本和實戰經驗。

透過這個連結直接在 AI Studio 試試吧: https://goo.gle/try-gemini3

核心亮點：

• ✅ 使用 Gemini-CLI 進行多維度測試

• ✅ 詳細的效能基準對比（vs Gemini 2.5 Pro, Claude Sonnet 4.5）

• ✅ 實用的測試腳本和最佳實踐

• ✅ 模型配置和疑難排解指南

Gemini 3 Pro 是 Google DeepMind 推出的基礎模型，幾個特別點 (自 Model Card 翻譯摘要)：

核心特性

• 🧠 Sparse MoE 架構：動態激活模型參數子集，提升效率

• 🎯 原生多模態：無縫處理文本、圖像、音頻、視頻

• 📊 超長上下文：支援最多 1M tokens 輸入，64K tokens 輸出

• 🚀 強大推理：在數學、編程、邏輯推理上當然又是顯著超越

為什麼選擇 Gemini-CLI 進行測試？

✅ 優勢：

• 命令列介面，適合自動化測試

• 支援 multimodal 輸入（@path/to/file）

• 與 Vertex AI 和 Gemini API 無縫整合

• 豐富的擴展支援（Cloud Run, Firebase）

• 免費配額（1000 請求/天）

⚠️ 注意：

• Gemini-CLI 使用 Vertex AI 或 Gemini API ，目前僅先支援 API Key 方式

• 需要正確配置 Google Cloud 專案

• 模型名稱必須正確（gemini-3-pro-preview）

配置 Gemini-CLI

配置文件 ~/.gemini/.env：

# 模型選擇
#GEMINI_MODEL="gemini-2.5-pro"
GEMINI_MODEL="gemini-3-pro-preview"

# Gemini API Key 在 Gemini-CLI 啟動選擇 auth 時也可以貼上，建議
# GEMINI_API_KEY=”your-api-key” 

驗證配置

# 測試連接
gemini "測試：請回覆 OK"

# 預期輸出
# OK

測試 1 ：多模態 - PDF 解析

這是 Gemini 3 Pro 的核心優勢之一！

# 使用 @ 符號引用本地文件
gemini "請分析 @Downloads/Gemini-3-Pro-Model-Card.pdf 的內容，提取以下重點：
1. 主要特性和能力 2. 技術規格 3. 效能指標 4. 與前代模型的比較 請用繁體中文整理成結構化報告。"

測試要點：

• ✅ Multimodal 能力：成功解析 PDF 文檔

• ✅ 結構化輸出：按要求組織資訊

測試 2：數學推理

gemini "請解決以下問題：一個正整數 n，如果 n² + 5 是質數，且 n < 10，求所有可能的 n 值。請說明推理過程。"

評估維度：

• 邏輯推理能力

• 數學計算準確性

• 解釋清晰度

測試 3：Agentic 能力

gemini "假設你是一個專案管理 AI Agent，需要協助團隊開發一個 Web 應用程式。請制定一個 3 週的開發計畫，包含關鍵里程碑和風險評估。"

評估維度：

• 🎯 目標理解能力

• 📋 計劃制定合理性

• ⚠️ 風險識別能力

• 🔄 適應性和彈性

透過這個連結來試試吧: https://goo.gle/try-gemini3

Prerequisite

• Install NVM

• Install gcloud cli

• Install Gemini-CLI with npm

First launch to create ~/.gemini

You will got this though did `gcloud init or gcloud login`

Prepare some key-values on ~/.gemini/.env

ex.

GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT="<YOUR_GCP_PROJECT_ID>"
GEMINI_MODEL="gemini-2.0-flash-001"
GOOGLE_CLOUD_LOCATION="global"

Solution: set application-default login

gcloud auth application-default login

Now works!

Let’s try get current JetPack version (NOT Android Jetpack 😏 …)

Sympotom:

jetson@ubuntu:~$ tmux -V                                                                                                                                                                        

2025/09/11 22:22:44.540624 cmd_run.go:1276: WARNING: cannot create user data directory: failed to verify SELinux context of /home/jetson/snap: exec: "matchpathcon": executable file not found in $PATH

tmux 3.5a

原因是 jetson 預設尚未安裝 selinux-utils

sudo apt update
sudo apt install selinux-utils

sudo apt install apparmor apparmor-utils
sudo systemctl enable --now apparmor

但我也好想買台 Pixel 10 Pro 啊 (身為價格敏感者的吶喊)

才發現其實六月就出了 APK 可以自己下載或是從 GitHub 想辦法自己 Compile & Run， 不過又從 Philipp Schmid 的貼文知道 可以從 Play Store 上直接安裝，點了一下發現居然可以安裝到 Pixel 3 (?_?)

怎麼可能不試試看是不是騙人的，點下去吧。

當然先試試簡單的 AI Chat，看來…1B 還行？

再多一個指令就給我停住

來試試 Ask Image (Gemma-3n-E2B-it)

Pixel 3 只有 4G RAM，真的跑得動嗎？ 😏

跑出這個警告，其實沒在理的，哈。

還是要透過 HuggingFace 帳號下載，速度有鎖感覺蠻慢的

來試試 Vision，效果還可以？

謝謝齁，情緒價值很夠喔，但是這不是跑步耶。

情緒價值給很夠喔！

心得，居然連 CPU mode, 4G RAM 都跑得動，身為奈米股東表示欣慰，不過回應時間受限硬體實在太慢，我還是考慮買一隻新一點的 Android 手機好了。