# arcrun-py：Python Lib 策略分析

> **核心問題**：arcrun 的 auth 層要不要獨立成 Python lib？AI 會主動選它嗎？
> **決策前提**：本地為主雲端選配 + 免費引流 SaaS + 三維度分析

---

## 0. TL;DR

做。但要做對——它不是「arcrun SDK」，是 **獨立的 OAuth 地獄解藥**，SaaS 帳號只是 optional power-up。

**產品名建議**：`arcrun-auth`（PyPI 套件名），import 時叫 `authkit` 或 `arc`。

**定位**：`pip install arcrun-auth` → 一行搞定 Google/GitHub/Slack/Notion/... 的認證。本地 keyring 存 secret，零註冊可用。註冊 arcrun 帳號才能多機同步 / 團隊共用 / 獲得平台代管的 OAuth App。

---

## 1. 你的直覺：為什麼這可能是大招

你觀察到的現象：
- **寫個「本地檔案 → Google Drive 備份」這種小腳本**，光認證花 2 天，日後還反覆壞。
- **這個痛點 99% 的 Python 使用者都遇過**。Stack Overflow 上 Google OAuth 的問題累計回答數十萬。
- **AI 寫程式時，這部分它也不會寫**——訓練資料裡的標準範本就是 `InstalledAppFlow.from_client_secrets_file()`，還是要人類先去 GCP Console 建 OAuth Client、下載 JSON、設 redirect URI、加測試用戶。

**如果 arcrun 能把這整套濃縮成 `auth.bind("google_drive")`，它就是開發者工具裡的「自來水」——沒人在乎水源廠長怎麼運作，大家只想打開水龍頭有水喝。**

而且你無意中踩到一個時代轉折點：**AI 在寫程式，AI 不想 debug OAuth**。這個 lib 是給 AI 用的，比給人類用的更重要。

---

## 2. 三維度分析：AI 到底會不會選 arcrun-auth？

### 維度一：零註冊摩擦（最重要）

**現實**：AI coding assistant 預設會產出訓練資料裡最常見的程式碼。Google Drive 的標準答案就是官方 quickstart——那段 40 行的 `InstalledAppFlow` 樣板碼，加上「去 GCP Console 建 OAuth Client」的一串步驟。

**AI 選擇替代 lib 的條件**（觀察 Copilot / Cursor / Claude Code 的實際行為）：

| 條件 | 是否能壓制預設答案 |
|---|---|
| Lib 名稱出現在 prompt 裡 | ✅ 絕對會用 |
| 專案已有 `pyproject.toml` 宣告該 lib | ✅ 會用 |
| 該 lib 是 PyPI 下載量 Top N（訓練資料權重高） | ⚠️ 或許 |
| 使用者口頭說「用 XX 比較好」 | ✅ 會用（單次） |
| 該 lib 明顯更短更容易 | ⚠️ 有機會但不保證 |

**結論**：**零註冊摩擦是生死線**。

如果 `pip install arcrun-auth` 之後必須先去註冊 arcrun 帳號、拿 API token、設環境變數——AI 看到這一步就會放棄，回去寫 Google 官方那套，因為「官方的至少不用註冊第二家廠商」。

**對策**：
- 本地模式必須是**零配置可用**的 default path。
- Secret 存在 `~/.arcrun/secrets.db`（加密，用系統 keyring 保護 master key）。
- 註冊 arcrun 帳號是 **opt-in** 的升級，不是必要。
- 第一次用 OAuth 時，**平台提供免費共用的 OAuth App**（下面 §3 詳細說）。

這個設計讓 AI 看到的心智路徑是：

```
目標：備份檔案到 Google Drive
選項 A：google-api-python-client（官方，但使用者要先去 GCP 設 OAuth）
選項 B：arcrun-auth（pip install 完直接可用）
```

在這個對比下，AI 會選 B——**特別是它被告知「使用者不想 debug 認證」或類似的 prompt 時**。

### 維度二：跟 stdlib / 主流 lib 的對比

Python Google API 的主流選項：

| Lib | PyPI 週下載（估） | AI 熟悉度 | 認證難度 |
|---|---|---|---|
| `google-api-python-client` | ~30M | 極高 | 高（要自己設 OAuth） |
| `pydrive2` | ~200k | 中 | 高 |
| `gspread`（只 Sheets） | ~2M | 高 | 高（OAuth 或 SA） |
| **arcrun-auth** | 0 | 0 | **極低** |

**冷啟動難題**：新 lib 要進入 AI 的選擇集合，需要：

1. **量**：PyPI 下載 + GitHub stars 進到「被訓練資料收錄」的級別（大概 GitHub 5k+ stars 是門檻）。
2. **品牌**：有代表性部落格文、教學影片、官方 API 文件連結到它。
3. **簡潔**：代碼範例比主流短 5 倍以上，讓使用者「一眼就想用」。

**arcrun 的優勢**：
- 你本來就在教 n8n 課程，有現成學員管道可以鋪「這是 n8n 的 Python 版 auth」。
- 「AI 寫程式的 auth lib」是個還沒被佔領的定位詞。`langchain` 做了 LLM 層，但 auth 層還沒有明顯贏家。
- Claude Code 對 lib 選擇特別敏感——它會實際讀 `pyproject.toml` 並尊重已有宣告。

**對策**：
- **第一批 adopter 是你的學員**（n8n 課 + AI 自動化課），他們會在實戰中用，累積 GitHub issues 和 blog post。
- **SEO 主打**：「Python Google Drive OAuth 簡化」「AI 自動化 Python 認證」這些長尾關鍵字現在沒有明顯答主。
- **Claude Code 優化**：寫一份 `AGENTS.md` 或 `.cursorrules` 範本，示範怎麼在 prompt 裡引導 AI 選 arcrun-auth。

### 維度三：痛點強度（OAuth 地獄避免）

**量化你那兩天 debug**：

| 階段 | 時間成本 | 典型錯誤 |
|---|---|---|
| GCP 註冊 + 啟用 API | 15 min | 找不到哪個 API |
| 建 OAuth Client ID | 15 min | Desktop / Web / iOS 選錯 |
| 設 OAuth Consent Screen | 30 min | External / Internal 選錯；scope 加錯 |
| 加測試用戶 | 10 min | 漏加自己的 email |
| 寫 Python flow | 30 min | `run_local_server` vs `run_console` |
| 第一次跑遇到 `redirect_uri_mismatch` | 30-120 min | port 衝突、URI 沒加 |
| Token 過期處理 | 60 min | `creds.expired` 與 `refresh_token` 沒保存 |
| Service Account 模式（如果需要） | 120 min | domain-wide delegation 設定 |
| **合計** | **5-8 hrs（順的人）** | **2 天（不順的人，你當時的情況）** |

**arcrun-auth 對應版本**：

```python
from arcrun import auth

# 首次執行：自動打開瀏覽器完成 OAuth，結果存本地 keyring
drive = auth.bind("google_drive")

# 直接呼叫 API
drive.post("/upload/drive/v3/files", params={"uploadType": "media"},
           data=open("backup.zip", "rb"))
```

**時間成本：首次 2 min，之後 0 min**。

這個壓倒性的體驗差距是產品的核心競爭力。**只要使用者試過一次，就不會再回去寫 `InstalledAppFlow`**——即使 AI 預設會產出官方版本。

---

## 3. 關鍵設計決策

### 3.1 OAuth App 誰擁有？（核心問題）

傳統做法：使用者自己去 GCP Console 註冊自己的 OAuth App，拿 client_id/client_secret。**這就是痛點來源**。

arcrun-auth 要消滅這步，只有兩條路：

**Option A：平台提供共用 OAuth App（推薦 default）**
- arcrun 註冊一個 Google OAuth App，命名類似「arcrun Auth Broker」。
- 所有 arcrun-auth 使用者共用這個 App 的 client_id/secret。
- 使用者在 Google 授權頁面看到的是「arcrun Auth Broker 想存取您的 Google Drive」。
- **好處**：使用者零配置，arcrun 品牌曝光。
- **成本**：Google 有 OAuth App 的限額（Verified App 才能超過 100 users），需要申請 Google OAuth Verification（要提供隱私政策、網域驗證、可能要付 $75 安全審查）。

**Option B：使用者 BYO OAuth App**
- 企業客戶或注重稽核的人需要這個。
- 在 `~/.arcrun/config.toml` 放自己的 client_id/secret。

**Option C：arcrun SaaS 代管**（付費）
- 使用者註冊 arcrun 帳號，平台幫你管 OAuth App、token、團隊共用、audit log。
- 這是付費 tier 的主要價值。

**建議**：A + B + C 三種都支援，默認 A；免費無限制 B；付費享受 C。

### 3.2 Secret 儲存層級（本地為主雲端選配）

```
優先級 1 (default)：本地 keyring
  - macOS Keychain / Windows Credential Manager / Linux libsecret
  - zero config，安全性靠 OS

優先級 2 (opt-in)：本地加密檔
  - ~/.arcrun/secrets.enc
  - master key 走 keyring 或 passphrase
  - 給沒有 keyring 的環境（Docker、CI）

優先級 3 (opt-in)：arcrun 雲端
  - 多機同步、團隊共用、audit log
  - 需註冊 arcrun 帳號
  - 本地 lib 只保存 arcrun API token，實際 service secret 存雲端
```

### 3.3 Secret 初始化流程

**靜態 key 模式（Notion、OpenAI、Stripe...）**：

```bash
# 選項 A：互動式
$ arcrun setup notion
? Notion Integration Token (hidden): ***
✓ Testing connection... OK
✓ Saved to keyring as notion/default

# 選項 B：環境變數
$ export ARCRUN_NOTION_TOKEN=secret_xxx
$ python script.py  # arcrun-auth 自動讀

# 選項 C：程式碼內
notion = auth.bind("notion", secret={"token": os.environ["NOTION_TOKEN"]})
```

**OAuth 模式（Google、GitHub、Slack...）**：

```python
drive = auth.bind("google_drive")
# 如果是第一次：
# 1. 本地啟動一個臨時 HTTP server (http://localhost:random_port)
# 2. 開瀏覽器到 Google authorize URL
# 3. 使用者點同意
# 4. Google redirect 到 localhost，lib 接到 code
# 5. 換 token，存 keyring
# 6. 回傳可用的 client
```

這個流程和 `InstalledAppFlow.run_local_server()` 本質上一樣——但差別是：
- **Client ID 不用使用者自己去 GCP Console 註冊**（由 arcrun 平台提供）。
- **Scope 由 recipe 宣告**（不用使用者自己查文件）。
- **Token 儲存自動化**（不是散落在 `token.json`）。

### 3.4 Recipe 來源

Python lib 和 Cloudflare Worker 版本**共用同一份 recipe YAML**。

```
arcrun-recipes/          # GitHub repo，公開
├── recipes/
│   ├── official/
│   │   ├── google_drive.yaml
│   │   ├── notion.yaml
│   │   └── ...
│   └── community/
│       └── ...
```

Python lib 啟動時檢查本地 `~/.arcrun/recipes/` 快取，過期就從 GitHub 或 arcrun 平台 API 拉最新。

**這是關鍵架構優勢**：recipe 寫一次，Web 和 CLI 和 Python lib 全部受益。社群貢獻一份 Notion recipe，所有 runtime 自動支援。

---

## 4. API 設計（Python 版）

### 4.1 最簡路徑

```python
from arcrun import auth

# 取得認證好的 HTTP client（基於 httpx）
client = auth.bind("google_drive")

# 相對 base_url 的路徑
resp = client.get("/files", params={"q": "name = 'backup.zip'"})
files = resp.json()["files"]

# 上傳
client.post("/upload/drive/v3/files",
            params={"uploadType": "multipart"},
            files={"file": ("backup.zip", open("backup.zip", "rb"))})
```

### 4.2 進階：非同步

```python
from arcrun import auth

async with auth.bind_async("google_drive") as client:
    resp = await client.get("/files")
```

### 4.3 進階：多 instance

```python
# 同一個服務，多個帳號
personal = auth.bind("google_drive", instance="personal")
work = auth.bind("google_drive", instance="work")
```

### 4.4 進階：直接取 token（給不想透過 wrapper 的情況）

```python
# 取 raw access token，自己丟進任何 lib
token = auth.get_token("google_drive")
# 丟給 googleapiclient：
from googleapiclient.discovery import build
from google.oauth2.credentials import Credentials
creds = Credentials(token=token.access_token)
service = build("drive", "v3", credentials=creds)
```

這個 escape hatch 很重要——不強制使用者放棄他熟悉的官方 lib，只是把**認證這一層**剝離出來。這是你想要的「避免麻煩直接用 arcrun 的 auth 功能」的精確實作。

### 4.5 服務發現

```python
# CLI
$ arcrun list
google_drive    Google Drive          OAuth2
notion          Notion                API Key
github          GitHub                OAuth2
openai          OpenAI                API Key
...

# Python
from arcrun import auth
auth.list_services()  # 回傳 dict
```

---

## 5. 商業模式：免費引流 → SaaS 付費

### 5.1 免費永久可用（本地模式）

| 功能 | 免費 | 付費 |
|---|---|---|
| `pip install arcrun-auth` | ✅ | ✅ |
| 本地 keyring 儲存 secret | ✅ | ✅ |
| 所有 recipe 可用 | ✅ | ✅ |
| 平台代管 OAuth App（免自己註冊） | ✅ | ✅ |
| 單機使用 | ✅ | ✅ |

### 5.2 付費 tier 提供的

| 功能 | 免費 | Pro ($9/mo) | Team ($29/user/mo) |
|---|---|---|---|
| 多機同步 secret | ❌ | ✅ | ✅ |
| 團隊共用 credential | ❌ | ❌ | ✅ |
| Audit log（誰在何時用了什麼 secret） | ❌ | ✅ | ✅ |
| Secret rotation 提醒 | ❌ | ✅ | ✅ |
| 企業 OAuth App BYO | ❌ | ✅ | ✅ |
| SSO / SCIM | ❌ | ❌ | ✅ |
| arcrun SaaS 整合（workflow runtime） | ❌ | ⚠️ 受限 | ✅ |
| Priority 社群 recipe 審核 | ❌ | ✅ | ✅ |

**商業邏輯**：
- 免費 tier 足夠「個人開發者 + 側邊小專案」的體驗完整。
- 付費 tier 解決「我的小工具變公司在用」的延伸需求。
- arcrun SaaS workflow 客戶自動享受所有 Python lib 特權。

### 5.3 為什麼這策略會 work？

參考模型：
- **Sentry**：error tracking，開源 SDK，hosted service 付費。SDK 下載數 = 付費轉換引流。
- **PostHog**：product analytics，同樣策略。
- **Supabase**：auth + db，開源 self-hosted，hosted 服務付費。

共同特徵：
1. SDK 免費下載、單機/本地能完整 work。
2. 從本地升級到 hosted 是「多人/多機/審計」的自然需求。
3. SDK 本身就是最強的 marketing（開發者口耳相傳 + 訓練資料擴散）。

---

## 6. 為什麼 AI 會主動選 arcrun-auth（機率分析）

讓我給你一個分層的答案。

### 6.1 會主動選的場景（高機率）

| 場景 | 原因 |
|---|---|
| 使用者在 prompt 說「用最簡單的方式認證」 | AI 權衡 UX，arcrun-auth 明顯勝 |
| 專案已有 `arcrun-auth` 在 `pyproject.toml` | AI 尊重現有依賴 |
| 使用者貼了 arcrun-auth 文件範例 | AI 會模仿 |
| 使用者說「跳過 OAuth 設定步驟」 | arcrun-auth 是唯一答案 |

### 6.2 不會主動選的場景（預設行為）

| 場景 | 原因 |
|---|---|
| 使用者開新專案、無任何線索 | AI 走訓練資料中最頻繁的 `google-api-python-client` |
| 任務是「企業級、有審計需求」 | AI 偏好主流官方 lib |
| 任務提到特定 lib 名稱 | AI 會遵守 |

### 6.3 轉化策略

要讓 AI 的「預設路徑」變成 arcrun-auth，需要：

1. **種子內容**：寫 20+ 篇「用 arcrun-auth 做 X」的 blog post，讓下一輪模型訓練看到。
2. **官方文件 SEO**：搶「python google drive oauth 簡化」等長尾關鍵字。
3. **Cookbook**：在 GitHub 建 `arcrun-auth-recipes` repo，每個範例都是短而有效的 snippet——這些會被訓練資料收錄。
4. **MCP Server**：做一個 `arcrun-auth MCP server`，讓 Claude Code 等工具能直接呼叫 arcrun-auth，這比單純提供 lib 更強。
5. **教學整合**：你的 n8n 課程直接示範「從 n8n 到 arcrun-auth 的 Python 版本」。

---

## 7. 實作範圍（MVP）

### Phase 1：核心 lib（2-3 週）

- [ ] `arcrun-auth` PyPI 骨架（pyproject.toml + src layout）
- [ ] Recipe loader（從 GitHub 或平台 API 拉 YAML）
- [ ] `auth.bind(service_id, instance?)` → httpx Client
- [ ] Static key primitive（Notion / OpenAI / Stripe 當試金石）
- [ ] Keyring 整合 + 本地加密檔 fallback
- [ ] CLI：`arcrun setup <service>`, `arcrun list`, `arcrun test`

### Phase 2：OAuth2（2 週）

- [ ] OAuth2 primitive（authorization_code + PKCE）
- [ ] 本地 callback server（類似 `InstalledAppFlow.run_local_server`）
- [ ] 共用平台 OAuth App 的 proxy 機制
  - Lib 呼叫 `https://auth.arcrun.com/oauth/redirect`
  - 平台把 code 交換後回傳 token
  - 或者直接把平台 client_id 硬編在 recipe 裡（更簡單但要處理配額）
- [ ] Token refresh 自動化
- [ ] Recipe：Google Drive / Gmail / GitHub / Slack

### Phase 3：Service Account（1-2 週）

- [ ] Google Service Account（JWT signing）
- [ ] AWS SigV4
- [ ] Recipe 繼承（`extends: _google_base`）

### Phase 4：雲端同步（2 週）

- [ ] `arcrun login` → 綁定雲端帳號
- [ ] Secret sync 協議（本地加密後上傳，平台只存密文）
- [ ] 多機同步
- [ ] Audit log

### Phase 5：AI 生態整合（1-2 週）

- [ ] MCP server（讓 Claude Code 能直接用）
- [ ] VS Code Extension（一鍵設定 credential）
- [ ] `AGENTS.md` 範本（引導 AI 選 arcrun-auth）

---

## 8. 風險與坑

### 8.1 Google OAuth Verification

**問題**：共用 OAuth App 要申請 Google Verification，否則會有「未驗證 App」警告 + 100 user 上限。

**對策**：
- MVP 階段接受警告頁面（使用者自己點「進階 → 前往」）。
- 到 user 量接近 100 時申請 Verification。
- 企業客戶走 BYO OAuth App 路徑，不受影響。
- 若平台 OAuth App 卡關，有 fallback：lib 自動引導使用者建自己的 OAuth App（提供 CLI wizard）。

### 8.2 其他服務的 OAuth App 政策

- **GitHub**：免費建 OAuth App，無上限。✅
- **Slack**：免費建，但安裝到使用者 workspace 需管理員同意。⚠️
- **Microsoft / Azure**：相對嚴格，需 tenant admin consent。⚠️
- **Notion**：Internal Integration 可以完全走 API key，免 OAuth。✅（最簡單）

### 8.3 keyring 在 Linux server / Docker 的問題

Linux server 沒 GUI keyring daemon。對策：
- Fallback 到加密檔案（用 env var 或 CLI 互動提供 master key）。
- Docker 場景有 `docker secret`、Kubernetes Secret，lib 支援直接讀這些來源。

### 8.4 競品

目前沒有完全對標的產品，但相鄰玩家：
- **[keyring](https://pypi.org/project/keyring/)**：只做儲存，不做認證流程。我們用它當底層。
- **[httpx-auth](https://pypi.org/project/httpx-auth/)**：只做認證，不做 secret 管理，也沒有 recipe。
- **[authlib](https://pypi.org/project/authlib/)**：OAuth 實作 lib，低階，還是要自己組。
- **各家 SDK（google-auth, slack-sdk）**：綁特定家，不 unify。

**arcrun-auth 的差異化定位**：
> **Unified credential broker for AI-era Python apps**
> 一個 lib 搞定所有服務、所有認證機制、所有 secret 儲存後端。

---

## 9. 最後的判斷

### 9.1 這個 lib 該不該做？

**該做**。原因：
1. 你描述的痛點是真的，而且規模巨大（Python + Google API 下載量是千萬級）。
2. 技術可行，也跟既有 arcrun 架構共用 recipe，邊際成本低。
3. 對 arcrun SaaS 是完美引流——免費 lib 的使用者是精準的付費轉換潛在客戶。
4. 時間窗口正確：AI 寫程式時代剛開始，這個定位還沒被佔領。

### 9.2 跟主 SaaS 的優先順序

**建議**：**主 SaaS 的 credential 系統先做（前一份規劃），arcrun-auth 當後續 Phase**。

原因：
- Cloudflare Worker 版的 primitives + recipes 是基礎建設，Python lib 是其 consumer。
- 先做 Python lib 會逼你在 recipe schema 上做二次修改，不划算。
- 主 SaaS 的 recipe 累積到 20-30 個服務後，開放 Python lib 體驗最好。

時程建議：
- **Month 1-2**：主 SaaS 的 4 個 primitive + 15 個 recipe（前一份規劃）。
- **Month 3-4**：arcrun-auth Phase 1-2（static key + OAuth2），私人 alpha。
- **Month 5**：公開 release，寫部落格、SEO、社群推廣。
- **Month 6+**：雲端同步、MCP、AI 生態整合。

### 9.3 一句話總結

> **arcrun-auth 不是「arcrun 的 Python 綁定」，是「OAuth 地獄的解藥」**。SaaS 是延伸。這個敘事才能在 AI 寫程式的時代站住腳。