Leo
13b01328c1
- .agents/specs/: spec-driven-dev docs for arcrun MVP, auth-recipe, credential-primitives-wasm (active refactor), landing-page, sdk-and-website, u6u-core-mvp, u6u-platform-evolution. - .agents/steerings/tech.md: detailed tech stack rationale. - docs/user_requirements/: long-form requirements incl. credential primitives, pages spec, py strategy analysis. - tests/: end-to-end harness scaffolding. These are the durable context backing CLAUDE.md's SDD protocol. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
132 lines
7.4 KiB
Markdown
132 lines
7.4 KiB
Markdown
# Requirements: arcrun SDK Libraries + Website
|
||
|
||
## Introduction
|
||
|
||
arcrun 目前有三個使用介面：
|
||
1. **CLI**（`acr` 指令）— 已完成，用 YAML 定義 workflow 並推送執行
|
||
2. **Python / JS SDK lib**（本次新增）— `pip install arcrun` / `npm install arcrun`，讓開發者在寫程式時直接用 arcrun 功能
|
||
3. **arcrun.dev 網站**（本次完成）— 登入取得 API Key、管理 Key、瀏覽零件 / recipe 列表
|
||
|
||
**核心原則**：SDK lib 是 `cypher.arcrun.dev` HTTP API 的 thin wrapper。所有業務邏輯（加解密、credential 注入、workflow 執行）都在 server 端完成。Client 端不重做 server 已有的邏輯。
|
||
|
||
**現有基礎設施**（不重建，直接使用）：
|
||
- `cypher.arcrun.dev`：cypher-executor Worker（workflow 執行、credential 管理、auth recipe、webhook）
|
||
- `u6u-core/credentials`：credential Worker（AES-GCM 加解密）— arcrun/credentials 是其 cherry-pick
|
||
- `arcrun/cli`：CLI 工具（已發布 npm `arcrun@1.1.0`）
|
||
- `arcrun/landing`：Next.js 前端（已部署 Cloudflare Pages，有 hero/login/dashboard/integrations 骨架）
|
||
|
||
---
|
||
|
||
## Glossary
|
||
|
||
- **SDK lib**：Python / JS 套件，wrapping `cypher.arcrun.dev` HTTP API，安裝後可在程式碼中直接使用
|
||
- **auth.setup()**：上傳一個服務的 credential（如 Notion token、OpenAI API Key）到 arcrun
|
||
- **auth.bind()**：取回已設定服務的 pre-authenticated HTTP client
|
||
- **auth.get_token()**：取回某服務的 raw token（escape hatch，給官方 SDK 用）
|
||
- **workflows.run()**：觸發已部署的 workflow
|
||
- **workflows.push()**：上傳 workflow 定義
|
||
- **Recipe**：描述「如何對某服務認證」的 YAML 設定，存在 RECIPES KV
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1：Python SDK（`pip install arcrun`）
|
||
|
||
**User Story:** As a Python 開發者, I want `pip install arcrun` 後在程式碼中使用 arcrun, so that 不用離開寫程式環境就能串接 20+ 服務。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Python SDK SHALL 以 `arcrun` 套件名發布到 PyPI，支援 Python 3.10+。
|
||
2. THE SDK SHALL 提供以下 API：
|
||
- `Arcrun(api_key=, base_url=)` — 建構 client，api_key 支援從環境變數 `ARCRUN_API_KEY` 或 `~/.arcrun/config.yaml` 自動讀取
|
||
- `client.health()` — 健康檢查
|
||
- `client.auth.list_services()` — 列出可用 auth recipe 服務
|
||
- `client.auth.setup(service, **kwargs)` — 上傳 credential
|
||
- `client.auth.bind(service)` — 取得 pre-authenticated HTTP client
|
||
- `client.auth.get_token(service)` — 取得 raw token
|
||
- `client.creds.push(name, value)` — 上傳加密 credential
|
||
- `client.creds.list()` — 列出 credential 名稱
|
||
- `client.creds.delete(name)` — 刪除 credential
|
||
- `client.workflows.run(name, input)` — 觸發 workflow
|
||
- `client.workflows.push(name, graph)` — 上傳 workflow
|
||
- `client.workflows.list()` — 列出已部署 workflow
|
||
3. THE SDK 的 credential 加密 SHALL 在 client 端完成（使用 `cryptography` 套件 AES-GCM），然後以 `POST /credentials` 上傳加密後的 `{ name, encrypted, iv }` 到 server。
|
||
4. THE `auth.bind()` SHALL 從 server 取得 auth recipe 的 inject template，在 client 端用 cache 的 plaintext 值填入，回傳 pre-configured `httpx.Client`。
|
||
5. THE SDK SHALL 使用 `httpx` 做 HTTP client（async 版使用 `httpx.AsyncClient`）。
|
||
6. THE SDK 位置 SHALL 為 `arcrun/python-sdk/`，build 系統用 `hatchling`（`pyproject.toml`）。
|
||
|
||
---
|
||
|
||
### Requirement 2：JavaScript/TypeScript SDK（`npm install arcrun`）
|
||
|
||
**User Story:** As a JS/TS 開發者, I want `npm install arcrun` 後在程式碼中使用 arcrun, so that 可以嵌入現有 Node.js / Deno / Cloudflare Workers 專案。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE JS SDK SHALL 以 `arcrun` 套件名發布到 npm，提供 ESM + CJS 雙格式 + TypeScript 型別定義。
|
||
2. THE SDK SHALL 提供與 Python SDK 對等的 API（camelCase 版）：
|
||
- `new Arcrun({ apiKey?, baseUrl? })` — 讀 `process.env.ARCRUN_API_KEY`
|
||
- `client.health()` — 回傳 `Promise<unknown>`
|
||
- `client.auth.listServices()` / `setup()` / `bind()` / `getToken()`
|
||
- `client.creds.push()` / `list()` / `delete()`
|
||
- `client.workflows.run()` / `push()` / `list()` / `delete()`
|
||
3. THE SDK 的 credential 加密 SHALL 使用 Web Crypto API（`crypto.subtle` AES-GCM），相容 Node 18+、browsers、Cloudflare Workers、Deno。
|
||
4. THE `auth.bind()` SHALL 回傳一個有 `get/post/put/delete/patch` 方法的 `AuthenticatedClient`，base URL + auth headers 已配置。
|
||
5. THE SDK SHALL 使用原生 `fetch()` API，不依賴外部 HTTP client 套件。
|
||
6. THE SDK 位置 SHALL 為 `arcrun/js-sdk/`，build 用 `tsup`（ESM + CJS + DTS），`tsconfig.json` target ES2020 + NodeNext module。
|
||
7. THE JS SDK 套件名與 CLI 套件名衝突（都叫 `arcrun`），SHALL 使用 `@arcrun/sdk` 或由 richblack 決定套件名。
|
||
|
||
---
|
||
|
||
### Requirement 3：arcrun.dev 網站完成
|
||
|
||
**User Story:** As a 潛在用戶, I want 在 arcrun.dev 上登入取得 API Key、瀏覽零件和 recipe 列表, so that 我可以評估 arcrun 是否符合需求並立即開始使用。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE 網站 SHALL 在 `arcrun.dev` 提供以下頁面：
|
||
- `/` — 首頁 Hero + 三種使用方式（CLI / Python / JS）
|
||
- `/login` — Google + GitHub OAuth 登入
|
||
- `/dashboard` — 登入後顯示 API Key（查看/Copy/Rotate/Revoke）
|
||
- `/integrations` — 列出 20 個 auth recipe 服務，可按分類篩選
|
||
- `/components` — 列出所有零件（21 個 WASM 零件），顯示 input/output schema、config_example
|
||
- `/api-docs` — Swagger UI，可直接試打 API
|
||
2. THE 登入 SHALL 使用 Google + GitHub OAuth，流程走 `cypher.arcrun.dev` 的 `/auth/*` 端點。
|
||
3. THE 登入後 SHALL 自動對該 email 呼叫 `/register` 取得 API Key（若已有則取回現有 key）。
|
||
4. THE `/dashboard` SHALL 允許 Rotate（生成新 key）、Revoke（標記失效）、Copy to clipboard。
|
||
5. THE 網站 SHALL 部署在 Cloudflare Pages（現有 `arcrun/landing`），使用 Next.js App Router。
|
||
6. THE 首頁 code demo 區 SHALL 包含三個 tab：Python、JavaScript、HTTP/curl，展示三種使用方式。
|
||
|
||
---
|
||
|
||
### Requirement 4：GitHub README 更新
|
||
|
||
**User Story:** As a GitHub 訪客, I want README 清楚說明三種使用方式, so that 我能選擇最適合的方式開始用 arcrun。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE `arcrun/README.md` SHALL 包含三種 Quick Start：
|
||
- **CLI**：`npm i -g arcrun && acr init && acr push workflow.yaml && acr run`
|
||
- **Python**：`pip install arcrun && from arcrun import Arcrun && ...`
|
||
- **JavaScript**：`npm install arcrun && import { Arcrun } from 'arcrun' && ...`
|
||
2. THE README SHALL 包含完整零件列表（21 個）和 auth recipe 列表（20 個服務）。
|
||
3. THE README SHALL 連結到 `arcrun.dev`（取得 API Key）和 Swagger UI（API 文件）。
|
||
|
||
---
|
||
|
||
### Requirement 5：SDK 發布
|
||
|
||
**User Story:** As a SDK 使用者, I want 公開安裝並直接使用, so that 不需要從原始碼 build。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Python SDK SHALL 發布到 PyPI，`pip install arcrun` 可安裝。
|
||
2. THE JS SDK SHALL 發布到 npm，`npm install arcrun`（或 `@arcrun/sdk`）可安裝。
|
||
3. THE 發布前 SHALL 完成以下測試（對 `cypher.arcrun.dev` live API）：
|
||
- `health()` ✅
|
||
- `auth.list_services()` ✅
|
||
- `auth.setup()` + `auth.bind()` ✅（至少一個 static_key 服務如 openai）
|
||
- `creds.push()` + `creds.list()` ✅
|
||
- `workflows.list()` ✅
|