# 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 都有效。
