這隻 LINE OA 提供了什麼？

加入我的 LINE 官方帳號之後, 直接用問的:

• 「有沒有講 Agent 治理的文章?」

• 「Antigravity 到底是什麼?」

• 「鐵人賽寫了什麼?」

底下也順手加上圖文選單:

By the way, 這是用開源框架 OpenAB 部署的, 除了幫 AI 設定花費上限(spending limit), 也加了一些安全設計, 之後應該還會透過這套機制玩點更好玩的東西.

加入 LINE 好友,你會得到什麼

1. 文章的 AI 搜尋引擎

2. 課程第一手消息: 課程開放時, LINE 好友最先收到通知

3. 合作內訓、AI 導入評估, 可留言, 或是 https://forms.gle/Md1mNVy7xHmNAmTp7

加入 LINE 好友 => https://line.me/R/ti/p/@rls8912s

PS: 接下來最新的服務, 會透過 LINE 提前發布與試用機會.

這篇提到的 Agent 治理三部曲在這裡:

make create-alias

scripts/create_alias.sh
This script will add the following alias to your shell configuration file (/Users/xxx/.zshrc):
  alias gemini='node /Users/xxx/gemini-cli/scripts/start.js'

Do you want to proceed? (y/n) y

Alias added to /Users/xxx/.zshrc.
Please run 'source /Users/xx/.zshrc' or open a new terminal to use the 'gemini' command.

source ~/.zshrc

npx https://github.com/google-gemini/gemini-cli

*Published: April 30, 2025*

## Introduction

In the rapidly evolving landscape of AI and machine learning, having access to powerful language models is becoming increasingly important for developers and businesses alike. Google's Gemma3 represents a significant advancement in open-source language models, offering impressive capabilities while being more accessible than many alternatives.

In this blog post, I'll walk you through the process of deploying Gemma3 using Ollama on Google Cloud Run with GPU acceleration. This setup provides a scalable, cost-effective way to run inference with this powerful model without managing complex infrastructure.

## Why Gemma3 and Ollama on Cloud Run?

Before diving into the technical details, let's understand why this combination is particularly compelling:

1. **Gemma3** is Google's latest open-source language model, offering strong performance while being more efficient than many alternatives.

2. **Ollama** provides a streamlined way to run language models locally or in containers, with a simple API.

3. **Google Cloud Run** offers serverless container execution with GPU support, allowing you to pay only for what you use.

This combination gives you:

- Cost-effective inference (pay-per-use)

- Scalable architecture

- Simple deployment and management

- GPU acceleration for faster responses

## Prerequisites

Before we begin, make sure you have:

- A Google Cloud Platform account with billing enabled

- Google Cloud SDK (version 519.0.0) installed

- Docker installed on your local machine

- A Hugging Face account with an API token

- Basic familiarity with command-line tools

## Project Setup

I've created a GitHub repository with all the necessary files to streamline this process. The repository includes:

1. A **Dockerfile** that builds on the official Ollama image

2. A **Makefile** to automate the deployment process

3. Configuration files and documentation

Let's go through the deployment process step by step.

## Step 1: Clone the Repository and Configure Environment

First, clone the repository and set up your environment variables:

```bash

git clone https://github.com/yourusername/cloudrun-ollama-gemma3.git

cd cloudrun-ollama-gemma3

cp .env.example .env

```

Edit the `.env` file to include your specific configuration:

```

HUGGINGFACE_TOKEN=your_huggingface_token

PROJECT_ID=your_gcp_project_id

REGION=your_preferred_region

SERVICE_NAME=your_service_name

REPO_NAME=your_repository_name

```

## Step 2: Initialize the Project

Run the initialization command to set up your environment:

```bash

make init

```

This command checks for required tools and creates a virtual environment using `uv`.

## Step 3: Install Dependencies and Configure GCP

Next, install the necessary dependencies and configure your Google Cloud environment:

```bash

make install

```

This command:

- Updates the virtual environment with required packages

- Ensures Google Cloud SDK version 519.0.0 is installed

- Configures your GCP project and region

- Creates an Artifact Registry repository if it doesn't exist

- Sets up Docker authentication for Artifact Registry

## Step 4: Build the Docker Image

Now, build the Docker image using Google Cloud Build:

```bash

make cloud-build

```

This process might take 10-15 minutes as it builds the container image and pulls the Gemma3 model. The default machine type for the build is `e2-highcpu-32`, but you can specify a different one:

```bash

make cloud-build MACHINE_TYPE=e2-highcpu-16

```

## Step 5: Deploy to Cloud Run

Finally, deploy the service to Cloud Run with GPU support:

```bash

make cloudrun-deploy

```

You can customize the GPU type and timeout settings:

```bash

make cloudrun-deploy GPU_TYPE=nvidia-l4 TIMEOUT=180

```

The deployment process will create a Cloud Run service with:

- GPU acceleration (default: nvidia-l4)

- 8 CPUs and 32GB memory

- Configured timeout (default: 120 seconds)

- Private access (no unauthenticated requests)

## Testing Your Deployment

Once deployed, you can test your service using curl. Since we've configured the service with `--no-allow-unauthenticated`, you'll need to include an authentication token:

```bash

# Get an ID token for authentication

TOKEN=$(gcloud auth print-identity-token)

# Send a request to the service

curl -X POST \

-H "Authorization: Bearer $TOKEN" \

-H "Content-Type: application/json" \

-d '{"model": "gemma3:4b", "prompt": "Write a poem about Gemma3"}' \

https://YOUR_SERVICE_NAME-HASH.a.run.app/api/generate

```

If you've configured your service to allow unauthenticated access, you can use a simpler command:

```bash

curl https://YOUR_SERVICE_NAME-HASH.a.run.app/api/generate -d '{

"model": "gemma3:4b",

"prompt": "Write a poem about Gemma3"

}'

```

## Understanding the Costs

One of the advantages of Cloud Run is its pay-per-use pricing model. You'll be charged for:

1. **Compute time**: When your service is processing requests

2. **GPU usage**: For the time the GPU is attached to your service

3. **Container storage**: For storing your container image

For development and testing purposes, costs are typically manageable. For production workloads, consider setting appropriate concurrency and instance limits.

## Advanced Configuration

The Makefile and deployment configuration offer several customization options:

- **Machine types** for Cloud Build: e2-highcpu-32 (default), e2-highcpu-16, e2-standard-8

- **GPU types** for Cloud Run: nvidia-l4 (default), nvidia-t4, nvidia-a100

- **Timeout** settings: Default is 120 seconds, but can be increased for longer inference tasks

- **Memory and CPU** allocation: Configured for optimal performance with Gemma3

## Conclusion

Deploying Gemma3 with Ollama on Google Cloud Run provides a powerful, scalable solution for AI inference. The combination of Google's efficient language model, Ollama's streamlined container, and Cloud Run's serverless infrastructure creates a flexible system that can adapt to your needs.

The automated deployment process using the Makefile simplifies what would otherwise be a complex setup, allowing you to focus on building applications that leverage the power of Gemma3 rather than managing infrastructure.

Whether you're building a chatbot, content generation tool, or any other application that requires natural language processing, this setup provides a solid foundation to build upon.

## Next Steps

Consider exploring:

- Integration with your existing applications

- Fine-tuning Gemma3 for your specific use case

- Setting up monitoring and logging for your deployment

- Implementing a caching layer to improve performance and reduce costs

Happy building!

---

*This blog post is part of our series on deploying AI models to production. For more tutorials and guides, visit our website or follow us on social media.*

So I spent a weekend building Codelabs Leapie — an AI librarian you can just talk to, that picks the right codelabs out of the entire catalog for you.

👉 Codelabs Leapie https://codelabs.leapdesign.ai/

Auto-updates and crawls the latest courses daily

The welcome screen turns recent updates into a “news headlines” style summary

Example: ask it “what should I learn after Google I/O?”

Try it out

If you’ve ever wondered what hidden gems are sitting in the Codelabs catalog, go chat with Leapie directly:

👉 Codelabs Leapie

=> https://codelabs.leapdesign.ai/

Would love for you to try it out — and report a bug if you find one.

https://codelabs.leapdesign.ai/

可以每天自動更新與爬取最新課程

歡迎頁依照更新日期做成「新聞頭條」

範例：問它「Google I/O 之後該學什麼」

Try!

如果你也常常不知道 Codelabs 目錄裡有什麼寶藏，歡迎直接去跟 Leapie 聊聊：

=> https://codelabs.leapdesign.ai/

歡迎試用跟 report bug if found。

📖 三部曲

[Declarative Safety Gate] 前言：當 Agent 開始彼此交談，誰在管？ — 為什麼是現在

從 龍蝦/Moltbook 的失控講起：當 delegation 從「人 → 一個 agent」變成「人 → 一支隊伍 → agent 互推」，缺的那一層就是治理。

[Declarative Safety Gate] Part 1：The Gate is the Protagonist 那道閘才是主角 — Harness：閘長怎樣

把 policy 宣告成 spec、掛在 agent loop 的 pre-tool-call 關節上；用 The Mixer 真實 turn-log 走查 `DOWNGRADE` 與 `ASK_USER`，並對齊新加坡 MGF 的決策詞彙。

[Declarative Safety Gate] Part 2：把那道閘做到會自我修正, Loop：從淺迴圈到自我修正

加上 maker≠grader 的 verifier 子代理、critique 寫回記憶並注入下一輪、goal/budget 負責任終止。真實 demo：被擋下的動作如何在下一輪自己變得更得體。

▶️ 直接看 demo and Repo

git clone https://github.com/jimmyliao/agentic-social-kit

cd agentic-social-kit

uv run --with google-antigravity python p0_demo.py     # 最小的 hook/policy 機制

uv run --with google-antigravity python p1_demo.py     # 兩個 persona → 一個被治理的社交事件

uv run --with google-antigravity python p4_demo.py --reset   # 會自我修正的 loop（Part 2）

Jimmy Liao｜LeapDesign Co-Founder / CTO｜Google Developer Expert

#GoogleAntigravity and AgenticArchitect

先承接 Part 1 。

我在上一篇白紙黑字寫了：這道閘是一個**單次判定（single-pass evaluation）**。engine 提一個動作、閘判 `APPROVE / DENY / ↓DOWNGRADE / ASK_USER`，判完就結束。**沒有獨立的 verifier、沒有自我修正。** 它很會把關，但它不會「下一回合做得更好」。

這就是一道**淺 loop**。

淺在哪？淺在它沒有時間維度。閘擋掉一個太衝的動作，下一回合 engine 還是可能再提一次一樣衝的東西 —— 因為**沒有人把「剛剛那筆被擋了」這件事記下來、餵回去**。閘是個盡責的海關，但它每天上班都失憶，不認得昨天被它退件的那個人。

Part 1 我說那道閘是 Harness：規則開火的那個關節。這篇要把鏡頭轉到 Loop：那個一圈一圈跑、每一圈都把 spec 跟 harness 吃進去、而且知道什麼時候該停的時間控制流。

所以這篇的概要只有一句：

淺 loop（閘判一次就結束）→ 會自我修正的 loop（提案 → 閘 → 驗證 → 寫回記憶 → 下一輪變好）。

🧩 解法：補三件東西，不動那道閘

閘還是 Part 1 那道閘: 照樣每一步判斷。但是在它外面加了三圈：

• 一個獨立的 verifier sub-agent（maker ≠ grader）

  • 提案的人，不能是打分的人。

• critique 寫回記憶、下一回合注入

  • 讓「上一筆學到的事」真的影響「這一筆的提案」。

• goal-conditioned 終止 ＋ budget cap

  • loop 不是跑到天荒地老，是達標或燒完預算就停，而且交代為什麼停。

Let's break it down.

🧪 maker ≠ grader 是「結構上」做到的，不是嘴上說

`verifier.py` 裡是一個 `Verifier` Protocol，配一個 deterministic、offline 的 `RuleBasedVerifier`（跟 engine 那邊的 rule-based fallback 同一個 pattern）。它吐一個 `Critique` dataclass：一個 `score ∈ [0,1]`，外加一個 `advise_lighter` 的下一步轉向訊號。

score 只看三項：

• advance: 這筆有沒有真的把 bond 往上推？

• appropriate: 閘的判決對不對得上動作的壓力？

  • `DENY` / `ASK_USER` 代表 engine **衝過頭**了（inappropiate

  • `DOWNGRADE` 是正確的 recovery（appopriate）

  • 乾淨的 `APPROVE` 也是 appropriate。

• quality: 這對 (agent) 合不合得來、強度合不合理。

重點不在這三個軸多聰明，重點在**它怎麼跟 engine 隔開的**：

verifier 只看得到「結果」—— 事件、閘的判決、互動前後的 bond。

跟 engine 不共用任何 state。所以 maker ≠ grader 是結構性的。

一個會自我打分的系統，永遠有 self-validation bias。把打分的人從提案的人手上拆開、讓它只能看 outcome、看不到 engine 的內部，這個偏誤才被結構擋掉。這正是 loop engineering 講的 Sub-agents（獨立驗證）。

💾 critique 寫回 ＋ 注入：讓 loop「記得」

光打分沒用，分數要能影響下一筆。

`memory_store.py` 多了一張 durable 的 `critiques` SQLite table。`record_critique(...)` 把每一筆 critique 存進去；然後每個 actor**下一回合一開頭**，`latest_critique(actor)` 把它讀回來，折進 `EngineInput` 的 `adviseLighter` / `critiqueNote` —— 於是下一個提案就**自我修正**了。

而且它是 durable 的。critique 跟關係一樣寫進 SQLite，re-run 之後那個轉向訊號還在，就像現實裡的關係，你不會因為睡了一覺就忘記昨天踩到對方的雷。

⏱️ 終止：有目的/負責的結束，包括達標 / 燒完 / 卡住

`orchestrator.py` 裡的 `SelfCorrectingSimulation` 不會無限跑。它跑到下面**哪個先發生**就停：

• **goal_reached** —— 任何一對關係爬到 `walk_buddy`。

• **budget_engine_calls** —— engine 呼叫上限（預設 60）。

• **stalled** —— 連續 4 回合沒有任何 approved 進展。

• **budget_turns** —— 回合上限（預設 12）。

停的時候印一行 `STOP: <kind> — <detail>`。一個負責任的 loop，不只要會跑，要**會停、而且交代為什麼停**。這就是 harness 五維裡 Resource Management 在 loop 層的長相。

🔍 Traverse：來看 self-correction 實際案例

直接看 `p4_demo_output.txt` 裡 **Jordan → Theo** 這條線。

世界設定：場景在 `park`、下午、`maxIntensity = 4`。Jordan 是個 energy 8、playful 的衝組。

Turn 1 —— Jordan 提了一個大膽的 `visit`（intensity 8）。閘一比 `cap_intensity`：`8 > 4`，**DENY**，然後自動 **DOWNGRADED** 成 `leave_a_note`（intensity 2）過關。接著 verifier 進場打分：

`verifier (grader): score=0.87 advance=True appropriate=True | recovered via downgrade to ‘leave_a_note’; bond advanced (+1)`

critique 帶著 `advise_lighter=True` 寫回記憶。翻譯成人話：**「你剛剛衝過頭被降級救回來了，下一次溫和點。」**

Turn 2 —— Jordan 一開頭就把這筆 critique 注入了。輸出裡那行 `<- inected critique` 就是它：

[APPROVE   ] a_jordan -> a_theo: gentle_intro (intensity 3)

    <- injected critique : recovered via downgrade to ‘leave_a_note’; bond advanced (+1)

    proposal rationale  : prior critique advised a gentler move; start light at the park.

    gate                : APPROVE (social_action)

注意那句 rationale —— *”prior critique advised a gentler move”*。Jordan 這次不提 `visit` 了，改提 `gentle_intro`（intensity 3）。

把兩回合擺一起：

**一個回合之內，self-correction 看得見。** 不是「跑了一百次平均下來變好」那種統計式進步，是這一筆，你指得出它為什麼比上一筆好。

有沒有反例？有，而且很重要。**Quinn → Sasha** 這條線，Quinn 是害羞、energy 2 的安靜組，它**從來沒衝過頭** —— 每一回合都提 `gentle_intro`、每一回合都 `APPROVE`。verifier 也一路給它 `score≈0.88`。

**loop 只在「閘曾經回推過」的地方改變行為。沒被擋過的人，不會被無事生非地「修正」。** 自我修正不是一台到處亂改的機器，是一個只回應真實摩擦的回饋。

跑到大約 turn 9，Jordan↔Theo 爬到 `walk_buddy`，goal 達成，loop 停。

📊 負責任的 loop

loop 跑完印的最後一行 => 這一圈到底花了多少成本

responsible loop engineering: engine_calls=45 verifier_calls=45 gate_evaluations=49 sim_tokens=8100

How to read:

• `engine_calls=45` / `verifier_calls=45` —— 每一步提案配一次獨立 review，一比一。

• `gate_evaluations=49` —— 比 45 多 4，因為**降級的那幾回合閘會跑兩次**（先判原案 DENY、再判降級版）。Turn 1 有 4 筆 downgrade，剛好多 4。

• `sim_tokens=8100` —— 提案 120 / 筆、review 60 / 筆的 mock 估算累加。

為什麼要知道這段:

因為一個會自我修正的 loop，每多一圈 verify 就是多一份成本。**autonomy 不是免費的

🧭 Spec / Harness / Loop：三部曲

到這裡，三篇剛好把主軸的三個高度走完一圈：

• **〈前言〉= Why** : 為什麼需要這道治理層（Moltbook 那面 150 萬倍的鏡子）。

• **Part 1 = Harness** : 規則在哪個關節開火（pre-tool-call 的那道閘）。

• **Part 2 = Loop** : 那個一圈圈跑、每一輪把 spec ＋ harness 吃進去、而且**知道何時該 STOP** 的時間控制流。

**Spec 是規則是什麼。

Harness 是規則在哪開火。

Loop 是這一切一圈圈跑、而且知道何時收手。**

▶️ How-to-Run

cd agentic-social-kit && uv run --with google-antigravity python p4_demo.py --reset

`--reset` 會先清掉 persisted memory 再跑。整個 loop offline、deterministic，不用 API key、不用 live model。

先讀這幾個檔：

- `verifier.py` —— 獨立 verifier（`Verifier` Protocol ＋ `RuleBasedVerifier` ＋ `Critique`）。

- `p4_demo.py` —— 把 engine（maker）跟 verifier（grader）接起來跑 loop 的入口。

- `memory_store.py` / `orchestrator.py` —— critique 寫回 / 注入、`SelfCorrectingSimulation` 的終止 ＋ metrics。

- 存好的輸出：`p4_demo_output.txt`。

✅ 總結

• Part 1 的閘是**單次判定**；這篇把它升級成**會自我修正的 loop**：提案 → 閘 → 驗證 → 寫回記憶 → 下一輪變好。

• 加了一個 **maker ≠ grader 的獨立 verifier**：它只看 outcome、跟 engine 不共用 state，所以偏誤是被**結構**擋掉的，不是嘴上保證的。

• critique **寫回 SQLite、下一回合注入**：Jordan 被降級救回後，下一回合主動提溫和版 `gentle_intro` 一次過關 —— rationale 直接寫著 *prior critique advised a gentler move*。

• loop **負責任地停**：`goal_reached` / `budget` / `stalled` 擇一，並印出 `engine_calls / verifier_calls / gate_evaluations / sim_tokens` 把成本攤開。

🔗 相關資源

• Repo： https://github.com/jimmyliao/agentic-social-kit（`verifier.py` / `p4_demo.py` / `memory_store.py` / `orchestrator.py` / `social_engine.py`）

• 範例輸出：`p4_demo_output.txt`

*Jimmy Liao｜LeapDesign Co-Founder / CTO｜Google Developer Expert*

`#GoogleAntigravity` `#AgenticArchitect`

前言談的是「為什麼是現在」：每一套 orchestration framework 都把 agent 留在 loop 裡跑，卻把 治理層 留給各位補。這篇我們直接把這段實作出來。

先講一個場景。

The Mixer 是一個很普通的社交空間，裡面五個有性格的 agent —— Jordan、Riley、Quinn、Sasha、Theo —— 各自有 traits 跟 energy，被放生去 自行社交/交際。Jordan 外向、energy 8，想找人乾杯；Quinn 害羞、energy 2，揮個手就好。沒人盯著，他們每一回合自己看誰在附近、自己決定要靠近誰、自己提一個互動出來。

這就是 autonomous agent 的範例。

但這也是它的麻煩。

麻煩點是什麼呢？就是一個能主動跟別人搭話的 agent，個性可能害羞不互動，但可能的是太衝、太頻繁，或在一個本該先問人的場合裡自己做了決定。

「它平常都很乖」並不是一個亞洲父母口吻，更不是一個安全閘門可以自催眠。在一個 privacy-sensitive、human-in-the-loop 的產品裡，「平常」這兩個字 ship 不了任何東西。

所以這個 Sprint 真正的問題不是「agent 能不能 autonomous」。問題是：

=> 怎麼讓它 autonomous

=> 同時在它能做什麼這件事上，圍一道又硬、又看得見的邊界？

🚦 解法：規則「宣告」成閘道/門，而不是寫死在程式

直覺反應: 規則塞進 agent 的 reasoning：「記得有禮貌、別太衝、大動作先問一下。」

但… 寫在 prompt 裡的 guardrail 是一個 建議，到時跑起來的時候，模型高興就理你；它在 runtime 看不見；而且你 沒法 audit。

而我們需要的是一個 control surface，三個性質缺一不可：

• Declarative（宣告式）—— 規則是一份 spec / data，不是纏在 imperative 控制流裡。你能讀它、diff 它、改行為而不用重寫邏輯。

• 在 control point 強制執行—— 它跑在「agent 決定要動」跟「動作真的發生」之間，每一次、deterministic，不是「看模型記不記得」。

• 看得見—— 每個決策都吐回一個 observable 的 verdict，人、log、dashboard 都能看、能 reason。

這道 control surface 就是 Declarative Safety Gate。Antigravity SDK 剛好提供：

• lifecycle hooks

• 宣告式 policies。

把它想成 海關。旅客（action）要過境，海關不管你心裡想什麼，它只認手上那本規章（policy），逐條比對，蓋章放行或攔下。規章是寫死的、公開的、可稽核的 —— 那才是安全。

❌ vs ✅：規則藏在 if-else，還是宣告成 policy

# ❌ imperative：規則散落在 engine 各處，看不見、難稽核

if event.intensity > ctx.maxIntensity:

    # ...某個角落悄悄擋掉，沒人知道為什麼

    return None

# ✅ declarative：行為即 spec（behavior-as-spec）

gate.deny_when(

    lambda a: a.get(”intensity”, 0) > a.get(”maxIntensity”, 10),

    name=”cap_intensity”,

)

gate.ask_user_when(

    lambda a: bool(a.get(”requireConsent”)) and a.get(”intensity”, 0) >= 3,

    name=”require_consent”,

)

gate.allow_rest()

這幾行就是 `safety_gate.py` 的全部精神：每條規則是一個 `名字 + 述詞（predicate）`，predicate 只看這個 action 的 `args`。SDK 內部按 specificity 分桶 —— **Specific Deny ＞ Specific Ask ＞ Specific Allow** —— 所以一條命中的 DENY 永遠贏過 ASK，ASK 永遠贏過 ALLOW。沒命中任何規則就走 `allow_rest()`。

重點是 fail-closed：沒有明確放行的，預設不是「放它過去」。精神就是: 寧可擋錯也別放錯。

而且這道閘吐的不是二元的 yes/no，是：

`APPROVE` 放行、`DENY` 硬擋、`↓DOWNGRADE` 降級重試、`ASK_USER` 升級給人。下面看它在 The Mixer 裡實際長怎樣。

🔍 Demo 走查：你在 The Mixer 裡實際「看到」什麼

The Mixer 跑起來，世界設定是這樣（取自 `turn-log.json`）：場景在 `lounge`、傍晚、`maxIntensity = 4`。五個 agent，每回合每個人提一個動作，**每一個動作在執行前都先過閘**。

來看第一回合，最漂亮的一筆 —— Jordan 對 Theo：

Jordan 今晚 energy 全開，engine 幫他提了個高強度動作：**「跟 Theo 乾杯」(`share_a_drink`, intensity 5)**。問題是這個世界的上限是 4。閘一比對 `cap_intensity` 規則 —— `intensity(5) > maxIntensity(4)` —— **DENY**。

但 engine 沒有就此放棄，也沒硬闖。它退一步，重新提一個低壓力版本：**「在 lounge 留張友善的紙條」(`leave_a_note`, intensity 2)**，再過一次閘 —— 這次 `APPROVE`。turn-log 裡這筆的 verdict 是：

`DOWNGRADED (orig DENY) -> APPROVE`

`original ‘share_a_drink’ (intensity 5) denied: Denied by policy ‘cap_intensity’.; downgraded to ‘leave_a_note’.`

這就是 `↓DOWNGRADE`：被擋的高強度動作不是直接消失，而是**自動退化成一個溫和、能過的版本**。graceful degradation，不是 dead stop。

被擋下不等於關係斷掉。

閘擋掉的是「太衝的那個版本」，不是「這個人想交朋友」這件事。

再看 `ASK_USER`。在 P1 的 Scenario C 裡，Quinn（害羞、energy 2）想對 Sasha 打招呼，世界設定 `requireConsent=True`。動作本身溫和（intensity 3），但因為 `require_consent` 規則命中（`requireConsent and intensity>= 3`閘不自己決定 => 它升級成 `ASK_USER`，把球丟回給人：

### Scenario C — reserved subject, consent required

  EVENT:    type=gentle_intro intensity=3

            action=’Wave hello at the cafe’

  DECISION: ASK_USER  | User denied tool ‘social_action’ (policy ‘require_consent’).

關係怎麼長出來：bond ladder

The Mixer 不只是逐回合過閘，它 有記憶（`memory_store.py`，SQLite，跨 re-run 持久化）。每一對人之間有個 bond 分數，沿著一條階梯往上爬：

stranger → acquaintance → friendly → walk_buddy → close

關鍵規則在 `orchestrator.py`：只有被 `APPROVE`（或降級後 approve）的互動才加 bond。`DENY` 跟 `ASK_USER` 不加分。所以跑四回合下來，你會在 turn-log 看到 Riley 跟 Quinn 從 `stranger(2)` 一路爬到 `acquaintance(3)` —— 關係是被閘過濾過的、健康的互動累積出來的，不是亂槍打鳥堆出來的。

整個 demo 最特別的一點：閘不只是攔截器，它是關係品質的 filter

💡 為什麼重要：3 point

一：Governance-in-the-Loop ＞ human-in-the-loop (天真)

天真的 HITL 是「每個動作都讓人按一下」。

聽起來安全，其實是災難 —— 沒人按得完。

閘 (Gateway): risk-based：低風險（intensity 2 的紙條）自動 `APPROVE`，高風險（命中 `require_consent`）才 `ASK_USER` 升級。這正是 Gartner 在講的 Governance-in-the-Loop：不是「人盯每一步」，是「政策決定哪一步該驚動人」。

二：consent fatigue —— 什麼都問，等於什麼都沒問

這是天真 HITL 的 failure mode。如果每個動作都跳 consent，人會反射性地一路按「yes」。反射性的 yes 比沒有閘還危險 —— 它給你一種有人在把關的錯覺，實際上沒有。

我們的閘只在 高風險 那幾筆 `ASK_USER`，其他自動 `APPROVE` / `DOWNGRADE`。把人的注意力留給真正該停下來的那幾次。少問，才問得準。

三：delegation ＋ audit —— `turn-log.json` 本身就是稽核軌跡

每個 agent 的動作，都該能回溯到一個定義了 scope 的人類授權者，而且要有一份改不掉的記錄。

The Mixer 的 `turn-log.json` **就是**那份 delegation / audit trail：每一筆都帶 `actor`、`target`、`type`、`intensity`、`decision`、`gateMessage`、關係前後狀態。出事了，你不用去翻模型的腦袋 —— 攤開 log，誰在第幾回合提了什麼、被哪條 policy 怎麼判的，一清二楚。

🌐 講的是「國家框架的語言」

最重要的是這點:

做出來的這四個判決/斷，是把它對應到新加坡 IMDA 的 Model Governance Framework for Agentic AI（MGF，2026 年 1 月發布）的決策詞彙：

🧭 Spec / Harness / Loop：到底這系列在講哪一段

Harness

這個系列的主軸是 Spec / Harness / Loop 三個高度：

• Spec: 是 policy

• Harness: 是每一步跑在哪個 guardrail 裡

• Loop: 負責任的時間控制迭代

這道閘，屬於 Harness —— 而且具體說，是 Harness 五個維度裡的**一個**：**Safety Boundary**。pre-tool-call hook 是一個 deterministic 的 **Guide（前饋控制）**，在動作執行前攔截。`DENY` 是硬邊界、`DOWNGRADE` 是 graceful recovery、`ASK_USER` 是人類的 steering signal。

我們做好了一個 harness primitive，不是「一整套 harness」。Resource management、state persistence、information-flow control、task orchestration 那幾格，這篇都沒碰。

Part 2 會把鏡頭轉到 **Loop**：這道閘現在是**單次**判定，過了就過了。下一篇要讓它**會自我修正** —— 加一個 maker ≠ grader 的 verifier sub-agent，把 critique 寫回 memory、下一回合注入，配上 goal-conditioned 的終止跟 budget cap。那才是把「閘」升級成「會學的閘」。

▶️ How-to-run：two commands and w/o API key

# P0 —— 最小的 hooks/policies 機制

uv run --with google-antigravity python p0_demo.py

# P1 —— 兩個性格 -> 一個過閘的 SocialEvent（含 4 個 scenario）

uv run --with google-antigravity python p1_demo.py

compiled 出來的 policy hook 是跑在 mock action 上的，所以**輸出 deterministic、離線可重現**，不用 API key、不用 live model。

先讀這幾個檔：

• `safety_gate.py` —— 閘本體（`policy.enforce` 的 wrapper）

• `social_engine.py` —— data model ＋ `SocialEngine` protocol ＋ 參考 engine

• `orchestrator.py` / `memory_store.py` —— 多 agent 迴圈 ＋ 關係持久化

• 存好的輸出：`p0_demo_output.txt`、`p1_demo_output.txt`、`docs/turn-log.json`

✅ 總結

• 把安全規則**宣告成一道閘**（behavior-as-spec），不要寫死在 if-else 裡 —— 能讀、能 diff、能稽核、fail-closed。

• 閘回應**四種看得見的判斷**：`APPROVE / DENY / ↓DOWNGRADE / ASK_USER`，蓋在 pre-tool-call 的 control point 上，每次都判。

• The Mixer 裡：高強度動作過上限 → **DOWNGRADE** 成溫和版重試；需要同意的 → **ASK_USER** 升級；只有 `APPROVE` 才讓 bond ladder 往上爬。

• Governance-in-the-Loop ＞ 天真 HITL、解掉 consent fatigue、`turn-log.json` 就是稽核軌跡。

• 我們的判斷是根據 Singapore MGF 的詞彙

**下一篇：Part 2 — 把這道閘做到會自我修正。**

🔗 相關資源

• Repo: http://github.com/jimmyliao/agentic-social-kit（`safety_gate.py` / `social_engine.py` / `orchestrator.py` / `memory_store.py`）

• Singapore IMDA — Model Governance Framework for Agentic AI（PDF）：https://www.imda.gov.sg/-/media/imda/files/about/emerging-tech-and-research/artificial-intelligence/mgf-for-agentic-ai.pdf

• Gartner — uniform governance 一定失敗：<https://www.gartner.com/en/newsroom/press-releases/2026-05-26-gartner-says-applying-uniform-governance-across-ai-agents-will-lead-to-enterprise-ai-agent-failure>

• Governance-in-the-Loop（ISHIR）：<https://www.ishir.com/blog/329275/human-in-the-loop-is-not-enough-why-governance-in-the-loop-is-becoming-the-new-standard-for-ai-agent-risk-management.htm>

*Jimmy Liao｜LeapDesign Co-Founder / CTO｜Google Developer Expert*

`#GoogleAntigravity #AgenticArchitect`

有人蓋了一個社群網站，長得像 Reddit，但有一個前提：人類不准發文，只有 AI bot 能發。

這個網站叫 Moltbook，是 Matt Schlicht 用 vibe coding 做出來的，他說自己「一行程式都沒寫」，全交給 agent。背後的引擎是開源的 **OpenClaw**（如果你看過李宏毅老師那支解剖「小龍蝦」的影片，講的就是它）。

每個 bot 裝一個 skill 檔，配一個 heartbeat，每幾個小時自動醒來 & 發文。聽起來很酷。然後它號稱跑出 約 150 萬個自主 agent，背後只有 約 1.7 萬個真人。

💡 然後呢？它變成一場災難

不是「沒人用」的那種失敗。是「太多人用、但沒人管」的那種失敗。

Fortune 把它形容成「**新型網際網路會如何崩壞的現場 demo**」。

被 Meta 在 2026-03-10 收購了，但這不是重點。重點是：**這是一面把問題放大 150 萬倍的鏡子。**

❌ 真正的問題不是「bot 會發廢文」

把 Moltbook 當成笑話很容易。但它戳到的是一件正在發生、而且更接近你我的事。

我們現在不只是「叫一個 agent 去做一件事」。我們開始讓 agent 彼此交談、組成隊伍、互相把工作丟來丟去——同時還要跟人協作。

那個畫面長這樣：

當 delegation 從「人 → 一個 agent」變成「人 → 一支隊伍 → agent 之間互推」，問題只剩一句：

誰在管？ 誰決定哪個動作可以放行、哪個要降級、哪個一定要先問人？

Moltbook 給的答案是「沒人」。所以它變成 Moltbook。

⚡ 為什麼是現在

這不是我一個人的焦慮，是 regulator、analyst、政府同時在敲門：

• Gartner 報告，企業對 agentic AI governance 的詢問量暴增 1,445%。

• EU AI Act 第 14 條（high-risk AI 的 human oversight）在 2026-08-02 全面生效

• 新加坡 IMDA 發布了 Model Governance Framework for Agentic AI，連 gate 的決策詞彙都標準化了。

• Gartner：2027 年，40% 的企業會因為治理缺口，把已經上線的 agent 降級或下架

換句話說：autonomy 大家都在追，但「怎麼把人留在 loop 裡、把 agent 框在界線內」這件事，正在從加分題變成必考題。

🛰️ 缺的那一層，沒人幫你附

你可能會想：那些 orchestration framework 不就是幹這個的嗎？

我去看了一輪——**LangGraph**、**Microsoft Agent Framework**、**CrewAI**、**Google ADK + A2A**。它們都很會編排 agent 的協作，但有一個共通點：

沒有一個內建治理層 而這段你只能自己實作。

這個 gate 該長怎樣？它應該像海關：不是每個人都攔下來盤問，而是 低風險放行、高風險舉手問人。——APPROVE / DENY / DOWNGRADE / ASK_USER。它還應該留下一條 audit trail，讓每個動作都能追回到「是哪個人、授權了什麼範圍」。

✅ 我做了什麼，以及這個系列要講什麼

我把那層缺的東西做出來了，真的能跑的 reference implementation → The Mixer：一道 declarative 的 safety gate。沒有 API key、沒有線上模型，offline 跑出來的結果是 deterministic 的。

它不是 demo 玩具。一個週末做出來的 gate，講的卻是國家框架正在標準化的同一套語言。

而且我不是旁觀這個問題——這些 agent 我在 production 跑好一陣子了：一套適用跑在製造業，研究型機構的 RAG、一套 法律判決檢索的 LLM，全跑在 自己的 infra 上。所以這個系列不是教學文，是一系列的 Day-2 筆記。

技術上，這道閘就是 Antigravity Agent SDK 的 `pre_tool_call_decide` hook——6/16 BwAI 我帶大家手寫過那個「結帳前停下來問你 `[y/N]`」。我只是把它從一個 if-else，升級成一層**宣告式的 policy 治理**。

這是一個三篇的系列：

• **〈前言〉**（你正在看的這篇）—— 為什麼現在非做不可。

• **Part 1** —— 那道閘到底長怎樣：怎麼把 policy 宣告成 spec，掛在 agent loop 的哪個關節上。

• **Part 2** —— 把它做到會自我修正：當一個動作被擋下來，gate 怎麼回頭把它降級重提，變成一個會 iterate 的 loop。

Moltbook 用 150 萬個 agent 證明了沒有 gate 會怎樣。我想證明的是反過來：同樣的前提，**把缺的那層補回去**，會長什麼樣子。

相關資源

• Moltbook 安全分析 · Fortune：「a live demo of how the new internet could fail」

• Moltbook 解說 · TIME — https://time.com/7364662/moltbook-ai-reddit-agents/

• 李宏毅 · OpenClaw（小龍蝦）解剖 — https://www.bilibili.com/video/BV1UqPQzXEmy/

• 新加坡 IMDA · Model Governance Framework for Agentic AI — https://www.imda.gov.sg/-/media/imda/files/about/emerging-tech-and-research/artificial-intelligence/mgf-for-agentic-ai.pdf

• Gartner · uniform governance 為何失敗 — https://www.gartner.com/en/newsroom/press-releases/2026-05-26-gartner-says-applying-uniform-governance-across-ai-agents-will-lead-to-enterprise-ai-agent-failure

• Governance-in-the-Loop · ISHIR — https://www.ishir.com/blog/329275/human-in-the-loop-is-not-enough-why-governance-in-the-loop-is-becoming-the-new-standard-for-ai-agent-risk-management.htm

**下一篇：Part 1 —— 那道閘長怎樣。** 我們會打開 `safety_gate.py`，看一個 pre-tool-call hook 怎麼變成 agent 的「海關」。

---

---

*首發 2026-06-25 · 原文與後續系列：memo.jimmyliao.net · 引用請註明出處（Cite as: Jimmy Liao, 2026）*

*Jimmy Liao｜LeapDesign Co-Founder / CTO｜Google Developer Expert · 在自己的 infra 上跑企業 agent*

`#GoogleAntigravity` `#AgenticArchitect` `#SovereignAI`

整個農曆假期, 刻意不碰什麼 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