arcrun — AI workflow execution engine (clean history)

Self-hosted 開源：WASM 零件 + recipe + cypher-executor，跑在你自己的 Cloudflare。此為重建的乾淨歷史起點（移除曾誤 commit 的 GCP SA 金鑰，舊歷史保留在 richblack/arcrun 與本地 backup 分支）。含： - acr init --self-hosted installer（建 KV/R2 + codeload 拉預編譯 wasm + wrangler deploy + seed recipe） - recipe push 把關（資料外流提醒 + 打通檢查） - 19 個正當零件預編譯 wasm（claude_api/km_writer/kbdb_upsert_block 排除：違反 DECISIONS §1） - CLI / cypher-executor / registry / 完整 SDD Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-03 15:52:38 +08:00
commit 922a57fe34
485 changed files with 89356 additions and 0 deletions
@@ -0,0 +1,486 @@
+# 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 寫程式的時代站住腳。
+