Please scroll down for the English version.

一個信箱不夠用的日常

相信大家都有不只一個電子郵件,平常大多是開著 Gmail 視窗、切換 Profile 來收信,不然就是借助 App 統整。

但如果你打開螢幕的日常 80% 是用 Agent(這次以 Agent CLI 為例),客戶或同事傳信過來,還要再打開另一個 App,也太麻煩了。

不是已經有工具了嗎?

你一定會說:Antigravity CLI (前身 Gemini-CLI)可以裝 Google Workspace Extension 收信, 或是今年三月推出的 gws cli. 或是 Claude 可透過 MCP 連 Google Account。

但是 —— 如果你平常要檢查的不只是單一信箱, 或是哪一天 Claude 突然不能用、甚至 Antigravity quota limit 又要等 5 小時,我們絕對不能讓 3rd-party agent 影響到日常運作。

於是我把自家的服務透過這個工具小小升級了一下整個工作流程 —— gwx。

gwx 是什麼: gws 的加強版

等等,有跟過新技術的朋友,一定聽過今年三月有個 gws – Google Workspace CLI —— 那有什麼差別?

可以把 gwx 視為 gws 的加強版:

• 支援多帳號

• 權限管控 (可以讓 agent 幫你看信、擬草稿, 但是…最終 review 必須還是你)

• 本機優先 (目前開源版本)

• 支援遠端服務 (除了 Google Workspace 之外, Microsoft 365 也在未來預計的支援列表上)

重點的重點: 就是可以直接以「人的視角」輔助工作日常。

實際跑起來

簡單收信,一次跨帳號彙整:

換個 agent 可以繼續使用: 如果你的 Antigravity 額度用完了,想改用 Claude / Codex / Copilot / 其他 Agent CLI,也沒問題。

Sonnet 5 真的很愛透過 Artifact 作彙整報表!

連信裡的附件、連結、Shared Google Drive 都讀得懂: 與客戶來往的信件內容裡,有時會有附件、連結,甚至一個 Shared Google Drive。現在透過 Agent 可以直接讀懂這些內容,並提供決策輔助資訊。這是不是很棒呢!

試試看

趕快來試試看! gwx — https://github.com/jimmyliao/gwx

如果有興趣了解怎麼輔助你/你的團隊導入這類實用服務,歡迎直接聯絡我。

English version below 👇

One inbox is never enough

I’m guessing you have more than one email address too. Most of the time you keep a Gmail window open and switch profiles to check them — or lean on some app to pull them all together.

But when 80% of your screen time is spent inside an agent (an agent CLI, in my case), and a client or a colleague mails you, opening yet another app is just friction.

“Aren’t there tools for this already?”

You’ll say: Antigravity CLI (formerly Gemini-CLI) can install the Google Workspace extension to read mail, or there’s the gws CLI released this March, or Claude can reach Google via MCP.

Sure — but what if the mailbox you need to check isn’t just one? Or Claude is suddenly down one day, or you hit an Antigravity quota limit and have to wait five hours? I really can’t let a third-party agent get in the way of my daily work.

So I gave my own setup — my whole workflow — a small upgrade: gwx.

What gwx is: gws, leveled up

Hang on — anyone who follows this space has heard of gws (the Google Workspace CLI) from this March. So what’s the difference?

Think of gwx as gws, leveled up:

• Multiple accounts

• Access governance — an agent can read your mail and draft replies for you, but… the final review has to be you

• Local-first (in the current open-source version)

• Remote-capable (besides Google Workspace, Microsoft 365 is on the planned roadmap)

The point of points: it augments your actual workday from a human’s point of view.

Seeing it run

Just reading mail — one sweep across accounts:

Switch agents and keep going: ran out of Antigravity quota and want to move to Claude / Codex / Copilot / another agent CLI? No problem.

Sonnet 5 really loves turning things into an Artifact report!

It even reads the attachments, links, and Shared Google Drive inside a mail: in back-and-forth with clients, an email often carries attachments, links, even a Shared Google Drive. Now the agent can read straight through them and hand back decision-support. Pretty great, right?

Give it a try

Go give it a try! gwx — https://github.com/jimmyliao/gwx

If you’re interested in bringing something like this to you or your team, feel free to reach out.

Antigravity CLI has recently received a series of major updates! From custom Agents now supporting a brand-new Markdown format, dynamically adjustable AI reasoning depth (/effort), to Headless mode and cross-platform bug fixes, here is a breakdown of this week's most notable highlights and details.

🌟 Highlights

• 🤖 Custom Agents Support Markdown Format (v1.1.6): You can now define Agent roles using agent.md files (with YAML frontmatter and H1 titles), granularly controlling permissions such as subagent and commandExecutionPolicy.

• ⚙️ AI Reasoning Depth Control `/effort` (v1.1.5): Added /effort command and --effort CLI flag, allowing users to dynamically switch between fast responses and deep reasoning.

• 📋 Windows CJK Clipboard Fix (v1.1.7): Resolved clipboard encoding issues when copying CJK (Chinese, Japanese, Korean) characters on Windows.

• 🔐 Enhanced Permission Prompts for Compound Shell Commands (v1.1.7): Compound shell commands requiring authorization now display in full, ensuring total auditing safety.

• 🔍 Global Code Search `/codesearch` (v1.1.6): Search results are now streamed asynchronously in real time, supporting cancellation at any time with Esc.

📌 Changelog Breakdown

🚀 v1.1.7 (Bug Fixes & Security Improvements)

• Security & Permissions: Full command view now displayed during permission prompts for compound shell commands.

• Plugin Logic: Fixed an issue where disabled plugins continued executing hooks and interfering with file editing tools.

• Character Compatibility: Fixed clipboard text corruption when copying CJK characters on Windows platforms.

• OAuth Specs: Relaxed OAuth issuer verification for non-standard MCP providers (e.g., Salesforce, Atlassian) and completed the refresh_token authorization flow.

🚀 v1.1.6 (Custom Agents & UX Improvements)

• Markdown Agent: Introduced standard agent.md format for defining custom agents with commandExecutionPolicy controls.

• Command History Copying: Supports numeric parameter /copy <n> to copy the n-th previous AI response.

• Search Experience: /codesearch upgraded to asynchronous streaming with real-time counters, cancelable with Esc.

🚀 v1.1.5 (Reasoning Mode & Architecture Refactoring)

• Reasoning Effort: Added /effort command and status bar badge to quickly adjust deep reasoning levels.

• Background Task Stability: Background tasks isolated with independent lifecycles so individual task failures do not affect the main conversation.

💡 Official CHANGELOG: https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md

#Antigravity #AntigravityCLI #AI #Changelog #DevRel #OpenAB

Antigravity CLI has recently received a series of major updates! From custom Agents now supporting a brand-new Markdown format, dynamically adjustable AI reasoning depth (/effort), to Headless mode and cross-platform bug fixes, here is a breakdown of this week's most notable highlights and details.

🌟 Highlights

• 🤖 Custom Agents Support Markdown Format (v1.1.6): You can now define Agent roles using agent.md files (with YAML frontmatter and H1 titles), granularly controlling permissions such as subagent and commandExecutionPolicy.

• ⚙️ AI Reasoning Depth Control `/effort` (v1.1.5): Added /effort command and --effort CLI flag, allowing users to dynamically switch between fast responses and deep reasoning.

• 📋 Windows CJK Clipboard Fix (v1.1.7): Resolved clipboard encoding issues when copying CJK (Chinese, Japanese, Korean) characters on Windows.

• 🔐 Enhanced Permission Prompts for Compound Shell Commands (v1.1.7): Compound shell commands requiring authorization now display in full, ensuring total auditing safety.

• 🔍 Global Code Search `/codesearch` (v1.1.6): Search results are now streamed asynchronously in real time, supporting cancellation at any time with Esc.

📌 Changelog Breakdown

🚀 v1.1.7 (Bug Fixes & Security Improvements)

• Security & Permissions: Full command view now displayed during permission prompts for compound shell commands.

• Plugin Logic: Fixed an issue where disabled plugins continued executing hooks and interfering with file editing tools.

• Character Compatibility: Fixed clipboard text corruption when copying CJK characters on Windows platforms.

• OAuth Specs: Relaxed OAuth issuer verification for non-standard MCP providers (e.g., Salesforce, Atlassian) and completed the refresh_token authorization flow.

🚀 v1.1.6 (Custom Agents & UX Improvements)

• Markdown Agent: Introduced standard agent.md format for defining custom agents with commandExecutionPolicy controls.

• Command History Copying: Supports numeric parameter /copy <n> to copy the n-th previous AI response.

• Search Experience: /codesearch upgraded to asynchronous streaming with real-time counters, cancelable with Esc.

🚀 v1.1.5 (Reasoning Mode & Architecture Refactoring)

• Reasoning Effort: Added /effort command and status bar badge to quickly adjust deep reasoning levels.

• Background Task Stability: Background tasks isolated with independent lifecycles so individual task failures do not affect the main conversation.

💡 Official CHANGELOG: https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md

#Antigravity #AntigravityCLI #AI #Changelog #DevRel #OpenAB

Antigravity CLI has recently received a series of major updates! From custom Agents now supporting a brand-new Markdown format, dynamically adjustable AI reasoning depth (/effort), to Headless mode and cross-platform bug fixes, here is a breakdown of this week's most notable highlights and details.

🌟 Highlights

• 🤖 Custom Agents Support Markdown Format (v1.1.6): You can now define Agent roles using agent.md files (with YAML frontmatter and H1 titles), granularly controlling permissions such as subagent and commandExecutionPolicy.

• ⚙️ AI Reasoning Depth Control `/effort` (v1.1.5): Added /effort command and --effort CLI flag, allowing users to dynamically switch between fast responses and deep reasoning.

• 📋 Windows CJK Clipboard Fix (v1.1.7): Resolved clipboard encoding issues when copying CJK (Chinese, Japanese, Korean) characters on Windows.

• 🔐 Enhanced Permission Prompts for Compound Shell Commands (v1.1.7): Compound shell commands requiring authorization now display in full, ensuring total auditing safety.

• 🔍 Global Code Search `/codesearch` (v1.1.6): Search results are now streamed asynchronously in real time, supporting cancellation at any time with Esc.

📌 Changelog Breakdown

🚀 v1.1.7 (Bug Fixes & Security Improvements)

• Security & Permissions: Full command view now displayed during permission prompts for compound shell commands.

• Plugin Logic: Fixed an issue where disabled plugins continued executing hooks and interfering with file editing tools.

• Character Compatibility: Fixed clipboard text corruption when copying CJK characters on Windows platforms.

• OAuth Specs: Relaxed OAuth issuer verification for non-standard MCP providers (e.g., Salesforce, Atlassian) and completed the refresh_token authorization flow.

🚀 v1.1.6 (Custom Agents & UX Improvements)

• Markdown Agent: Introduced standard agent.md format for defining custom agents with commandExecutionPolicy controls.

• Command History Copying: Supports numeric parameter /copy <n> to copy the n-th previous AI response.

• Search Experience: /codesearch upgraded to asynchronous streaming with real-time counters, cancelable with Esc.

🚀 v1.1.5 (Reasoning Mode & Architecture Refactoring)

• Reasoning Effort: Added /effort command and status bar badge to quickly adjust deep reasoning levels.

• Background Task Stability: Background tasks isolated with independent lifecycles so individual task failures do not affect the main conversation.

💡 Official CHANGELOG: https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md

#Antigravity #AntigravityCLI #AI #Changelog #DevRel #OpenAB

Antigravity CLI Digest: v1.1.5 ~ v1.1.7 Latest Release Analysis

Antigravity CLI 近期迎來了一系列重磅更新！從自訂 Agent 支援全新的 Markdown 格式、可動態調整的 AI 思考深度 (/effort)，到無頭模式（Headless mode）與跨平台修復，以下為您整理本週最值得關注的核心亮點與細節。

Antigravity CLI has recently received a series of major updates! From custom Agents now supporting a brand-new Markdown format, dynamically adjustable AI reasoning depth (/effort), to Headless mode and cross-platform bug fixes, here is a breakdown of this week's most notable highlights and details.

🌟 核心亮點速覽 (Highlights)

• 🤖 自訂 Agent 正式支援 Markdown 格式 (v1.1.6)：現在能直接使用 agent.md 設定檔（搭配 YAML frontmatter 與 H1 標題）定義 Agent 角色，並細緻調控 subagent、commandExecutionPolicy 等權限。

• 🤖 Custom Agents Support Markdown Format (v1.1.6): You can now define Agent roles using agent.md files (with YAML frontmatter and H1 titles), granularly controlling permissions such as subagent and commandExecutionPolicy.

• ⚙️ AI 推理深度控制 `/effort` (v1.1.5)：新增 /effort 指令與 --effort 啟動參數，讓使用者能在「快速回應」與「深度思考 (Reasoning Depth)」之間動態切換。

• ⚙️ AI Reasoning Depth Control `/effort` (v1.1.5): Added /effort command and --effort CLI flag, allowing users to dynamically switch between fast responses and deep reasoning.

• 📋 Windows CJK 亂碼徹底修復 (v1.1.7)：解決在 Windows 系統上複製中日韓（CJK）等非 ASCII 文字時的剪貼簿亂碼問題。

• 📋 Windows CJK Clipboard Fix (v1.1.7): Resolved clipboard encoding issues when copying CJK (Chinese, Japanese, Korean) characters on Windows.

• 🔐 複合 Shell 指令權限提示優化 (v1.1.7)：當複合指令包含需授權的部分時，系統會完整展示整條指令，確保審核安全無死角。

• 🔐 Enhanced Permission Prompts for Compound Shell Commands (v1.1.7): Compound shell commands requiring authorization now display in full, ensuring total auditing safety.

• 🔍 全域程式碼搜尋 `/codesearch` (v1.1.6)：搜尋結果改為即時非同步串流顯示，支援按 Esc 隨時打斷搜尋。

• 🔍 Global Code Search `/codesearch` (v1.1.6): Search results are now streamed asynchronously in real time, supporting cancellation at any time with Esc.

📌 版本詳細履歷 (Changelog Breakdown)

🚀 v1.1.7 (最新修復與安全性優化 / Bug Fixes & Security Improvements)

• 安全與權限 / Security & Permissions：複合 Shell 指令權限詢問改為完整呈現全貌。

• Full command view now displayed during permission prompts for compound shell commands.

• Plugin 邏輯 / Plugin Logic：修復已停用的 Plugin 仍會執行 Hook 並干擾檔案編輯工具的缺陷。

• Fixed an issue where disabled plugins continued executing hooks and interfering with file editing tools.

• 字元相容性 / Character Compatibility：修復 Windows 平台上複製 CJK（中日韓）文字時剪貼簿出現亂碼的現象。

• Fixed clipboard text corruption when copying CJK characters on Windows platforms.

• OAuth 規範 / OAuth Specs：放寬對非標準 MCP 服務商（如 Salesforce, Atlassian）的 OAuth 發行者驗證並補齊 refresh_token 授權流程。

• Relaxed OAuth issuer verification for non-standard MCP providers (e.g., Salesforce, Atlassian) and completed the refresh_token authorization flow.

🚀 v1.1.6 (自訂 Agent 與互動體驗 / Custom Agents & UX Improvements)

• Markdown Agent：開啟以 agent.md 定義 Agent 的新標準，支援設定 commandExecutionPolicy 等行為。

• Introduced standard agent.md format for defining custom agents with commandExecutionPolicy controls.

• 歷史複製 `/copy <n>` / Command History Copying: 支援帶入數字參數，複製倒數第 n 次的 AI 回應。

• Supports numeric parameter /copy <n> to copy the n-th previous AI response.

• 搜尋體驗 / Search Experience: /codesearch 改為非同步串流顯示與即時計數，按 Esc 可隨時打斷搜尋。

• /codesearch upgraded to asynchronous streaming with real-time counters, cancelable with Esc.

🚀 v1.1.5 (思考模式 /effort 與背景架構重構 / Reasoning Mode & Architecture Refactoring)

• Reasoning Effort: 提供 /effort 與狀態欄 Badge，快速調整深度推理等級。

• Added /effort command and status bar badge to quickly adjust deep reasoning levels.

• 背景任務穩定性 / Background Task Stability: 背景任務採用獨立生命週期管理，單一任務異常不影響主對話。

• Background tasks isolated with independent lifecycles so individual task failures do not affect the main conversation.

💡 官方 CHANGELOG 原文 / Official CHANGELOG: https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md

#Antigravity #AntigravityCLI #AI #Changelog #DevRel #OpenAB #Bilingual

這隻 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! 📚✨