uncle6me-web
922a57fe34
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>
341 lines
9.9 KiB
Markdown
341 lines
9.9 KiB
Markdown
# 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 都有效。
|