Arcrun/docs/user_requirements/ADR-lib-and-landingPage/arcrun-pages-spec.md

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：

pip install arcrun-auth

from arcrun import auth

# 就這樣，Google Drive 認證完成
drive = auth.bind("google_drive")
resp = drive.get("/files")

JavaScript tab：

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」這一節特別重要

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