Leo/Arcrun
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

arcrun — AI workflow execution engine (clean history)

Browse Source 
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>
This commit is contained in:
uncle6me-web
2026-06-03 15:52:38 +08:00
commit 922a57fe34
485 changed files with 89356 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user_requirements/ADR-lib-and-landingPage/arcrun-pages-spec.md
+340
View File
@@ -0,0 +1,340 @@
# arcrun.dev Pages 規格
> **讀者**：CC（可直接照做）
> **部署**：Cloudflare Pages + Workers
> **語言**：英文為主，中文切換
> **技術棧**：Astro（靜態生成）+ Cloudflare Pages + D1（使用統計）
---
## 0. 這個 Pages 的三個角色
1. **門面**：第一次看到 arcrun 的人，30 秒內要懂「這是什麼、對我有什麼用」
2. **轉換漏斗**：工程師 → 試用 lib → 申請 API Key；小白 → 看榮譽牆 → 問 AI 能不能用
3. **社群磁鐵**：榮譽牆讓工程師有動機貢獻 recipe，貢獻越多服務越多，用戶越多
---
## 1. 網站結構（五個頁面）
```
arcrun.dev/
├── / 首頁（門面 + 轉換）
├── /docs 用法文件
├── /integrations 榮譽牆（服務目錄）
├── /api Swagger UI（原始 API）
└── /changelog 版本記錄
```
---
## 2. 首頁（/）
### 2.1 Hero Section
**英文**：
```
Stop fighting OAuth.
One API key. Every service. Works anywhere.
arcrun handles Google, Notion, GitHub, Slack authentication
so your Python / JS code doesn't have to.
[Get API Key — Free] [View on GitHub]
```
**中文切換後**：
```
不要再跟 OAuth 搏鬥了。
一個 API Key，接通所有服務，在哪跑都行。
[免費取得 API Key] [查看 GitHub]
```
語言切換按鈕放右上角，用 `?lang=zh` query param，Cloudflare Worker 記住偏好存 cookie。
### 2.2 三行說清楚（Why arcrun）
```
┌────────────────────┬────────────────────┬────────────────────┐
│ Before │ │ After │
│ │ │ │
│ 40 行 OAuth 程式 │ →→→ │ 1 行 │
│ GCP Console 設定 │ │ arcrun.auth.bind │
│ debug 兩天 │ │ ("google_drive") │
└────────────────────┴────────────────────┴────────────────────┘
```
### 2.3 Code Demo（互動式 tab）
三個 tab 切換：Python / JavaScript / HTTP（給 n8n 小白）
**Python tab**：
```python
pip install arcrun-auth
from arcrun import auth
# 就這樣，Google Drive 認證完成
drive = auth.bind("google_drive")
resp = drive.get("/files")
```
**JavaScript tab**：
```javascript
npm install arcrun-auth
import { auth } from 'arcrun-auth'
const drive = await auth.bind('google_drive')
const resp = await drive.get('/files')
```
**HTTP tab（給 n8n 用戶）**：
```
POST https://api.arcrun.dev/v1/auth/bind
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"service": "google_drive",
"secret": "{{ $env.GOOGLE_SA_JSON }}"
}
```
下方加一行小字：「n8n 用戶：用 HTTP Request 節點貼上這段，不需要安裝任何東西」
### 2.4 數字牆（social proof）
```
127 個認證服務 1,247,832 次呼叫 89 位貢獻者
```
這三個數字從 D1 即時讀，每小時更新一次（Cloudflare KV cache）。
### 2.5 CTA
```
[免費取得 API Key]
註冊後立即可用，不需要信用卡
```
---
## 3. 榮譽牆（/integrations）★ 核心頁面
### 3.1 頁面頂部
```
127 個已驗證的認證服務
由社群工程師貢獻並測試，每個 recipe 都有真實使用數據
[搜尋服務...] [全部] [AI] [Google] [社群媒體] [生產力] [台灣]
```
### 3.2 服務卡片
每個 recipe 一張卡：
```
┌──────────────────────────────────────────┐
│ [圖示] Google Drive ★ 官方 │
│ │
│ 認證方式：Service Account │
│ 貢獻者：@richblack ──→ GitHub profile │
│ 驗證日期：2026-03-15 │
│ │
│ 使用次數：██████████ 12,847 次 │
│ │
│ [查看 Recipe] [複製 Python 範例] │
└──────────────────────────────────────────┘
┌──────────────────────────────────────────┐
│ [圖示] OpenRouter │
│ │
│ 認證方式：API Key (Header) │
│ 貢獻者：@some_engineer ──→ GitHub │
│ 驗證日期：2026-04-01 │
│ │
│ 使用次數：██░░░░░░░░ 89 次 │
│ │
│ [查看 Recipe] [複製 Python 範例] │
└──────────────────────────────────────────┘
```
badge 規則：
- `★ 官方`：arcrun 團隊維護
- `✓ 社群驗證`：100+ 次使用 + 30 天無錯誤回報
- `🆕 新加入`：30 天內合併的 PR
### 3.3 貢獻者排行（頁面底部）
```
Top Contributors
🥇 @some_engineer 23 個 recipe 89,234 次呼叫
🥈 @another_dev 15 個 recipe 45,123 次呼叫
🥉 @third_person 8 個 recipe 12,456 次呼叫
...
[我也要貢獻 →] （連到 CONTRIBUTING.md）
```
### 3.4 「我要貢獻」的 CTA
```
找不到你要的服務？
大部分 API Key 類的服務，填一份 YAML 就能加進來。
把 API 文件丟給 AI，五分鐘生成，開 PR 送出。
[查看 Recipe 格式] [開始貢獻]
```
---
## 4. 用法文件（/docs）
### 結構
```
快速開始
├── 取得 API Key
├── Python 安裝與第一個範例
├── JavaScript 安裝與第一個範例
└── 直接用 HTTP（n8n / 任何工具）
認證方式
├── API Key 類服務
├── OAuth2 類服務
├── Google Service Account
└── mTLS
進階用法
├── 多帳號（multi-instance）
├── 只取 token（escape hatch）
└── 錯誤處理
貢獻 Recipe
├── Recipe YAML 格式說明
├── 讓 AI 幫你寫 Recipe
└── 提交流程
```
### 「讓 AI 幫你寫 Recipe」這一節特別重要
```markdown
## 讓 AI 幫你寫 Recipe
把下面這段丟給 Claude / ChatGPT，
再把目標服務的 API 文件一起貼進去：
---
請根據以下 API 文件，
生成一份符合 arcrun recipe schema 的 YAML。
Schema 文件：https://arcrun.dev/docs/recipe-schema
目標服務：[貼上 API 文件]
---
AI 生成後，你只需要：
1. 把 YAML 存成 recipes/community/服務名.yaml
2. 跑 `acr recipe test 服務名.yaml`
3. 開 PR
通常整個過程不超過十分鐘。
```
這一節讓「貢獻門檻」從「工程師才能做」變成「任何人叫 AI 做」。
---
## 5. API 文件（/api）
直接嵌入 Swagger UI，連到 `https://api.arcrun.dev/swagger.json`。
頁面頂部加一行說明：
```
這是 arcrun 的原始 API。
Python / JS lib 是它的包裝，
任何能發 HTTP request 的工具都能直接用。
```
這一句話讓 n8n 用戶、Make 用戶、甚至 Excel 用戶都知道「我也能用」。
---
## 6. 技術實作
### 6.1 技術選型
**Astro**（靜態生成）是首選，原因：
- 頁面大部分是靜態內容（docs / recipe 卡片），Astro 的 SSG 完美對應
- 動態數字（使用次數、貢獻者排行）用 Astro 的 `client:load` island 局部更新
- 部署到 Cloudflare Pages 零配置
**不用 Next.js**，因為你已在 Cloudflare 生態，Next.js 的 SSR 在 CF Pages 有摩擦。Astro + CF Pages 是更自然的組合。
### 6.2 資料來源
| 資料 | 來源 | 更新頻率 |
|---|---|---|
| Recipe 清單、metadata | GitHub repo `recipes/` 目錄 | CI merge 時觸發 rebuild |
| 使用次數 | Cloudflare D1（API call log） | 每小時從 D1 聚合 → KV cache |
| 貢獻者排行 | 同上 | 每小時 |
| 總呼叫次數 | 同上 | 每小時 |
### 6.3 多語言
用 Astro 的 i18n routing：
- `/` → 英文
- `/zh/` → 中文
語言切換按鈕寫入 cookie `arcrun_lang`，CF Worker 在 edge 讀 cookie 做 redirect。
不用 JS framework 的 i18n library，保持輕量。
### 6.4 部署流程
```
GitHub push to main
→ GitHub Actions 跑 astro build
→ 產出 dist/
→ 自動部署到 Cloudflare Pages
→ Pages 掛 arcrun.dev domain
```
recipe YAML 有變動時（PR merge）額外觸發一次 rebuild。
---
## 7. CC 的實作任務
### Phase 1：靜態骨架（3-5 天）
- [ ] Astro 專案初始化，設定 CF Pages 部署
- [ ] 首頁 Hero + Code Demo tab（靜態版，數字先寫死）
- [ ] `/integrations` 靜態版（先手動列 5-10 個服務）
- [ ] `/docs` 基本結構（快速開始 + Python 範例）
- [ ] `/api` 嵌入 Swagger UI
- [ ] 中英切換機制
### Phase 2：動態資料（3-5 天）
- [ ] D1 schema：`recipe_calls(recipe_id, count, last_updated)`
- [ ] CF Worker：API call 時寫入 D1
- [ ] 每小時聚合 Worker：D1 → KV cache（總數 / per recipe / per contributor）
- [ ] 首頁數字牆：從 KV 讀即時數字
- [ ] `/integrations` 卡片：使用次數從 KV 讀，進度條動態顯示
### Phase 3：社群功能（2-3 天）
- [ ] 貢獻者排行從 KV 讀
- [ ] Recipe 頁面：點「查看 Recipe」展開 YAML
- [ ] 點「複製 Python 範例」自動生成對應 code snippet
- [ ] GitHub PR merge webhook → 觸發 Pages rebuild
---
## 8. 一個不能省的細節
榮譽牆的貢獻者欄位**一定要連到他的 GitHub profile**，不是只顯示名字。
工程師貢獻的動機之一是「這個會出現在我的公開作品集」。連到 GitHub 就意味著他的 followers 可能看到他貢獻了 arcrun，這比任何 badge 都有效。
docs/user_requirements/ADR-lib-and-landingPage/arcrun-py-strategy-analysis.md
+486
View File
@@ -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 寫程式的時代站住腳。
docs/user_requirements/ADR-lib-and-landingPage/strategy.md
+55
View File
@@ -0,0 +1,55 @@
# Arcrun 推廣策略修正
20260418 by Leo
## Arcrun 的最近幾次變化
- Arcrun 原是 Matrix 的原子化純雲端 CF 程式框架，有 MCP 讓 AI 使用
- 轉以 WASM + WASI + TinyGo 成為未來具有雲端、地端、邊緣端的執行能力，可以用來做到無人機等終端。
- 再解耦成獨立的 Open Source 專案，脫離 KBDB 用 YAML 即可，允許整個 Fork，但推廣 SaaS 模式
- 今天的變化是發現成為 Lib 和 n8n 社群節點的用法。說明如下。
## 推廣方式 1：寫成 Lib
參考文件：docs/user_requirements/arcrun/ADR-lib-and-landingPage/arcrun-py-strategy-analysis.md
Leo 教 n8n 時常舉例我叫 AI 幫我寫個簡單的程式把 server 的檔案備份到 Google Drive 後刪除，光是 OAuth 用 Service Account 就花了 2 天測試，後來還發生好幾次出錯重修。
網路設定對 vibe coder 太複雜了，看到 AI 一次次修改一次次出錯，知道一週後才穩定，而 n8n 只需要申請 credential 填入，10 分鐘搞定，差距太大了。
問題是，n8n 實在太慢了，全圖像界面也難以跟程式碼整合，vibe coder 就算知道了也無法整合，他會繼續用 python 就是無法忍受 n8n 的慢速、沉重，及對 AI 的不友善。
Arcrun 用幾個基礎 Auth 零件取代 n8n 幾百個不同的 credentials 設定，arcrun 完全可以跟程式碼整合，只是目前沒有整合工具，也就是說，工程師不想面對一個認證花好幾天，他只要用 Arcrun 打 API 就幾行解決了。
用這個策略，讓具有程式知識的人會：
- 對 Arcrun 有好感，在 GitHub 按星
- 成為 Arcrun 用戶，增加會員 base
- 寫文分享，讓 Arcrun 被傳出去
反之，小白初學 vibe coding，看到老工程師說 2 天變成 10 分鐘，百行程式碼變成 2 行，也會被影響。
所以，把 API 包裝成 Lib 或 SDK 是個 Get Member 的好方法，不過一定要有 Email。
## 推廣方式 2: 讓 n8n 來 call
身為 n8n 講師，我非常清楚 n8n 有個大缺陷（或說是安全設計），就是它只能呼叫在工作流實例化前就寫好的程式，無法注入新的。
所以，雖然它可以安裝一個實作 langchain AI Agent 的 AI Agent 節點，但 AI 卻不可能在遇到問題時立刻寫個程式運行解決問題，甚至使用它內建的 task runners 或使用外部的 Python runtime 也無法。
但只要使用 http request 節點呼叫外部的 Arcrun tool，它就可以輸出三元組寫一個程式解決它現在遇到的問題，並且運算完後回傳，只需要取得一個 API Key。
## 可能的效應
工程師是意見領袖，他們會去按星，幫忙教育市場，而小白需要被教育，但他們是較大的社群，這些星數和聲量會在未來變成 AI 訓練素材，甚至推薦用戶使用最 AI Friendly 的 Arcrun。
而實際上 Arcrun 的設計讓 AI 更輕鬆。
## 要做什麼
docs/user_requirements/arcrun/ADR-lib-and-landingPage/arcrun-pages-spec.md 這是 claude.ai 寫的規劃，因為它看不到 codebase，所以你要斟酌如何開發。
另外，當前的 API Key 雖然很容易取得，卻有個問題，用戶無法管理，所以頁面應該要有取得 API Key 的界面，可以 Google, GitHub 等 OAuth 或 Email + Password 登入，用來管理它的 API Key 的 CRUD。
或許是可以外接一個 SMTP 服務來確認他的 Email 真實，SaaS 服務還是有成本，雖然成本不高。
另外，既然是 OpenSource，成本雖然不高，似乎可以銜接 Donate 服務？