Leo/Arcrun

Files

T

uncle6me-web 922a57fe34 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

8.2 KiB

Raw Blame History

Frontend Redesign — Requirements

來源：Claude Design bundle JAdpACs3cSyw_vN6Ketj1Q（已歸檔於 design-source/）。此 SDD 擴展 ../landing-page.md 的範圍：landing 從「單頁 + OAuth + Dashboard」升級為「5 screen app shell」。

1. 背景

arcrun/landing/ 目前只提供：

/ — Landing hero + code demo
/login — Google / GitHub OAuth
/dashboard — API Key 管理
/api-docs — Swagger UI（外部）
/integrations — 20 個 recipe 靜態清單

Claude Design 交付一套完整 5 screen 設計（Landing / Auth / API Keys / Dashboard / Workflow Viewer），與現有前端相比多了：

Dashboard 的 Apps Grid 與 Workflows Table（現在沒有應用/workflow 清單 UI）
API Keys 獨立頁（現在和 dashboard 混在一起）
Workflow Viewer：node-based canvas，對應 YAML workflow 的視覺化（目前 acr push YAML 後只有 CLI 輸出）

2. User Stories

US-1：新訪客認識 arcrun

作為沒用過 arcrun 的工程師，我要在 landing 看到兩條路（For Developers / For Everyone），5 秒內判斷這是否符合我要的用法。
驗收：hero + 雙 path card + feature strip 在首屏呈現；CTA「Start free」可點擊到 /auth。

US-2：取得 / 登入會員

作為訪客，我要用 GitHub / Google / Email 登入建立帳號。
驗收：/auth 支援 Sign in / Sign up tabs、GitHub + Google OAuth、Email + Password 表單。OAuth 成功後導向 /dashboard。

US-3：看見應用全貌

作為已登入用戶，我要在 Dashboard 看到我已部署的 App（packaged workflow）和 Workflow 清單。
驗收：
- Apps Grid：每個 app 卡片顯示名稱、描述、「Open app」「Edit in Claude」。
- Workflows Table：顯示 workflow 名稱、節點數、最後修改、執行次數、狀態。
- 若 app / workflow 為空，顯示新建 CTA（非硬編 mock）。

US-4：管理 API Keys

作為已登入用戶，我要建立、檢視、停用、刪除 API Key。
驗收：
- 剛產生的 Key 顯示在頂部高亮卡片（含警示文字「不會再顯示」）。
- 全部 Keys 在下方表格顯示（名稱、遮蔽後 key、建立時間、最後使用、狀態、toggle、trash）。
- Rotate / Revoke 立即生效（呼叫 cypher-executor）。

US-5：檢視 Workflow graph

作為已登入用戶，我要點 workflow 進到 viewer，看到節點 DAG 與每個節點的 I/O schema 與參數。
驗收：
- Canvas 顯示節點（含 icon / type badge），節點以 bezier 曲線相連。
- 選中節點後右側面板顯示 input / output schema、configuration（針對 ai.completion 等節點顯示 triplet 編輯器）。
- 工具列含 Share / Export YAML / Edit in Claude。
- Minimap + zoom 控制顯示可用。
- 「Export YAML」呼叫 cypher-executor 取得該 workflow 的原始 YAML。

US-6：Dogfooding

作為 arcrun 核心維護者，我要前端所有與服務打交道的動作都透過 arcrun 自家 API（cypher-executor）完成，不依賴第三方 OAuth / workflow / backend 服務。
驗收（見 §6）。

3. 非功能需求

項目	規範
技術棧	Next.js 15 App Router、React 19、Tailwind v4、TypeScript（沿用 `landing/` 現有堆疊）
部署	Cloudflare Pages（`@cloudflare/next-on-pages`），沿用 `landing/wrangler.toml`
字型	Inter、JetBrains Mono — 用 `next/font/google`，不拉 unpkg / fonts.googleapis.com `<link>`
依賴	僅 Next / React / Tailwind；禁止 tRPC、React Query、SWR、Auth.js/Clerk、ReactFlow/XYFlow、Radix、shadcn CLI install、animation library（framer-motion）等第三方
狀態管理	React 內建（useState / useReducer / Context）；持久化用 `localStorage` 或 server session cookie
國際化	延後；本次一律英文（與設計稿一致）。現有 `?lang=zh` 不擴展
無障礙	按鈕 `aria-label`、Form 控件有 `<label>`；鍵盤可完成登入 / 複製 key 流程
效能	Landing 首屏無阻塞 JS（RSC）；Dashboard / Workflow Viewer 可為 Client Component

4. 視覺基準

項目	值（source of truth：`design-source/index.html` 的 CSS 變數）
主背景	`#0F0F0F`（現有是 `#0a0a0a` — 本次改為 `#0F0F0F`）
Card	`#1A1A1A`
Line	`#262626` / `#303030`
Primary	`#6366F1`（indigo） → `#8B5CF6`（violet）漸層
Text	`#EDEDED` / dim `#A0A0A0` / mute `#6B6B6B`
字型	Inter 300/400/500/600/700/800；Mono 400/500/600

5. 範圍界線

納入

5 screen（Landing、Auth、Dashboard、API Keys、Workflow Viewer）
Logo（SVG arc wordmark）、Icon set（inline SVG，從 primitives.jsx port）
TopNav / Footer / Sidebar 三個 shell 元件

不納入（本次 SDD）

Multi-tenant workspace 切換（設計稿有 "Northwind" breadcrumb，本次純顯示用戶 email）
Multi-API-key CRUD 後端（cypher-executor 現只支援每帳號一把 key，多 key table 先以「目前只支援一把」狀態呈現 — 見 §6.2）
Workflow 編輯（只做 read-only viewer；編輯仍走 acr CLI / YAML）
即時執行狀態 stream（minimap / zoom 僅 UI，不做真實 pan-zoom transform）
i18n 中英切換、Hall of Fame、Donate
Swagger UI 頁（/api-docs） — 保留現狀

6. API 依賴（全部打 `cypher.arcrun.dev`）

6.1 既有（已實作於 cypher-executor）

GET /me — 取得登入用戶 + api_key（driver：dashboard 側欄 avatar / API Keys 頁的單把 key）
PUT /me/api-key/rotate、DELETE /me/api-key — Rotate / Revoke
GET /auth/google/start、GET /auth/github/start — OAuth 起點
POST /auth/logout
POST /webhooks/named/{name}/trigger — 觸發（給 Landing 文案展示）

6.2 需新增的 endpoint（阻擋項；本 SDD 只定義契約，cypher-executor 實作歸屬於另一個 task）

Method	Path	說明	用途
GET	`/workflows`	列出當前 api_key 名下的 workflow（名稱、nodes、modified、run_count、status）	Dashboard / Workflows Table
GET	`/workflows/:name`	取得 workflow 詳細（含 graph 節點 + edges + YAML）	Workflow Viewer
GET	`/workflows/:name/yaml`	下載 raw YAML	Workflow Viewer Export
GET	`/apps`	列出 app（= workflow 標上 icon/tone/description metadata）	Dashboard / Apps Grid
GET	`/api-keys`	列出多把 key（若後端仍是單把，回傳單元素 array）	API Keys 頁
POST	`/api-keys`	建立新 key	API Keys 頁「Create new key」
PATCH	`/api-keys/:id`	`{ active: boolean }` 切換	API Keys 頁 toggle
DELETE	`/api-keys/:id`	刪除	API Keys 頁 trash

在後端尚未實作前：前端用型別化 fetch wrapper 封裝呼叫；遇到 404 顯示 empty state（而非假資料）。本 SDD 明確禁止 hard-code mock fixture。

6.3 登入前後可用的公開資訊

Integrations 清單（20 個 recipe）：現有 /integrations 頁已有靜態清單，繼續複用。

7. Dogfooding 紅線

禁止	用哪個 arcrun 內部替代
Auth0 / Clerk / Supabase Auth	cypher-executor `/auth/*` + session cookie（現行 `arcrun_session`）
Segment / PostHog	不加，或用後續 arcrun `analytics` 零件
Vercel KV / Upstash	Cloudflare KV（經 cypher-executor）
直接寫第三方 API（Slack / Notion 等）作 dashboard demo	透過 arcrun workflow + trigger 模擬
ReactFlow / XYFlow	純 SVG 手刻（設計稿本來就是手刻）

8. 驗收總清單

5 個 screen 全部在 /, /auth, /dashboard, /keys, /workflows/[id] 可達。
設計稿的 spacing / color / border-radius 100% 對得上（以 design-source/index.html CSS 變數為準）。
middleware 保護 /dashboard, /keys, /workflows/*（未登入 → /auth?redirect=...）。
只打 cypher.arcrun.dev（可透過 NEXT_PUBLIC_API_BASE override），grep 結果不含其他外部 API host。
package.json 新增依賴 = 0（本次不引入新 npm 套件）。
無 mock 資料：若後端未實作，顯示 loading 或 empty state，不編假陣列給 UI。
pnpm build 通過，next-on-pages 輸出無 edge-runtime 錯誤。

8.2 KiB Raw Blame History Unescape Escape