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>
121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
# Implementation Plan: arcrun SDK Libraries + Website
|
||
|
||
## Overview
|
||
|
||
按 Design 的四個 Phase 實作。原則：修改不重建，SDK 是 HTTP API thin wrapper，加密只在 client 做 encrypt（不做 decrypt）。
|
||
|
||
**前置依賴**：必須先完成 `credential-primitives-wasm/tasks.md` 的 Phase 0-3（核心合併 + WASM primitives），確認核心穩定後才開始建三個介面。
|
||
|
||
---
|
||
|
||
## Phase 0（前置）：核心合併 + WASM 改寫
|
||
|
||
> 詳見 `.agents/specs/arcrun/credential-primitives-wasm/tasks.md`
|
||
>
|
||
> 摘要：
|
||
> - 合併 u6u-core → arcrun（搬 builtins、刪重複 credentials）
|
||
> - credential-injector TS → auth_static_key / auth_service_account WASM
|
||
> - 刪除 component-loader 內建 API recipes TS
|
||
> - 驗證 20 個 auth recipe 正常運作
|
||
|
||
---
|
||
|
||
## Phase 1：Python SDK
|
||
|
||
- [ ] 1. 建立 `arcrun/python-sdk/` 目錄
|
||
- [ ] 1.1 `pyproject.toml`：name=arcrun, deps=[httpx>=0.27, cryptography>=42], build-system=hatchling
|
||
- [ ] 1.2 `arcrun/__init__.py`：`from .client import Arcrun`
|
||
- [ ] 1.3 `arcrun/crypto.py`：AES-GCM encrypt only（使用 `cryptography` 套件）
|
||
- [ ] 1.4 `arcrun/creds.py`：CredentialsClient — push（加密 + POST /credentials）、list（GET /credentials）、delete
|
||
- [ ] 1.5 `arcrun/auth.py`：AuthClient — setup（fetch recipe → match secrets → encrypt → push）、bind（fetch recipe → resolve headers from cache → return AuthenticatedClient）、get_token、list_services
|
||
- [ ] 1.6 `arcrun/workflows.py`：WorkflowClient — run（POST /webhooks/named/{name}/trigger）、push（POST /webhooks/named）、list（GET /webhooks/named）、delete
|
||
- [ ] 1.7 `arcrun/client.py`：Arcrun class — 讀 api_key / encryption_key 從 param > env > config.yaml
|
||
|
||
- [ ] 2. 修正上次已知的 bug
|
||
- [ ] 2.1 `_fetch_recipe()` 回應是 `{ success: true, recipe: {...} }`，需讀 `.recipe` 欄位
|
||
- [ ] 2.2 `inject` 下的 key 是 `header`（singular），不是 `headers`
|
||
- [ ] 2.3 `required_secrets[].key` 是 prefixed（如 `openai_api_key`），setup() 的 kwargs alias 要能對應
|
||
- [ ] 2.4 `list_services()` 回應的 recipe 用 `service` 欄位（不是 `service_id`）
|
||
|
||
- [ ] 3. 測試（對 cypher.arcrun.dev live API）
|
||
- [ ] 3.1 `health()` → `{"ok": true}`
|
||
- [ ] 3.2 `auth.list_services()` → 20 個服務
|
||
- [ ] 3.3 `auth.setup("openai", api_key="sk-test-dummy")` → 成功
|
||
- [ ] 3.4 `auth.bind("openai")` → AuthenticatedClient with Authorization header
|
||
- [ ] 3.5 `auth.get_token("openai")` → "sk-test-dummy"
|
||
- [ ] 3.6 `creds.push("test_token", "value123")` → 成功
|
||
- [ ] 3.7 `creds.list()` → 含 "test_token"（注意 KV eventual consistency）
|
||
- [ ] 3.8 `workflows.list()` → []
|
||
- [ ] 3.9 cleanup: `creds.delete("test_token")`
|
||
|
||
---
|
||
|
||
## Phase 2：JS/TS SDK
|
||
|
||
- [ ] 4. 建立 `arcrun/js-sdk/` 目錄
|
||
- [ ] 4.1 `package.json`：name TBD（arcrun vs @arcrun/sdk），deps=devDeps only（tsup, typescript, @types/node）
|
||
- [ ] 4.2 `tsconfig.json`：ES2020, NodeNext
|
||
- [ ] 4.3 `src/crypto.ts`：Web Crypto API AES-GCM encrypt only
|
||
- [ ] 4.4 `src/creds.ts`：CredentialsClient — push/list/delete via fetch
|
||
- [ ] 4.5 `src/auth.ts`：AuthClient — setup/bind/getToken/listServices
|
||
- [ ] 4.6 `src/workflows.ts`：WorkflowClient — run/push/list/delete
|
||
- [ ] 4.7 `src/index.ts`：export class Arcrun + re-exports
|
||
|
||
- [ ] 5. 同步修正（與 Python SDK 同樣的 recipe 格式問題）
|
||
- [ ] 5.1 `_fetchRecipe()` 讀 `body.recipe`
|
||
- [ ] 5.2 inject key: `header` not `headers`
|
||
- [ ] 5.3 setup() secret key alias matching
|
||
- [ ] 5.4 listServices() 用 `service` 欄位
|
||
|
||
- [ ] 6. Build + 測試
|
||
- [ ] 6.1 `tsup` build → dist/index.js + dist/index.cjs + dist/index.d.ts
|
||
- [ ] 6.2 Node.js 腳本對 live API 測試（同 Python 測試項目）
|
||
|
||
---
|
||
|
||
## Phase 3：arcrun.dev 網站
|
||
|
||
- [ ] 7. 新增 `/components` 頁面
|
||
- [ ] 7.1 從 `registry/components/*/component.contract.yaml` 讀取 21 個零件資料
|
||
- [ ] 7.2 卡片顯示：canonical_id, display_name, description, input required/optional, credentials_required, config_example
|
||
- [ ] 7.3 分類篩選：邏輯類 / API 類 / 控制流類
|
||
|
||
- [ ] 8. 更新首頁
|
||
- [ ] 8.1 Code demo tabs 改為 CLI / Python / JS 三個
|
||
- [ ] 8.2 CLI tab 展示 `acr init → acr push → acr run`
|
||
- [ ] 8.3 Python tab 展示 `pip install arcrun → Arcrun() → auth.setup → auth.bind`
|
||
- [ ] 8.4 JS tab 展示 `npm install arcrun → new Arcrun() → auth.setup → auth.bind`
|
||
|
||
- [ ] 9. OAuth 流程補完
|
||
- [ ] 9.1 確認 cypher-executor 的 `/auth/google/start`、`/auth/github/start`、`/auth/callback` 路由正確
|
||
- [ ] 9.2 提供 richblack OAuth secrets 設定指令清單
|
||
- [ ] 9.3 richblack 設定 secrets 後驗證登入流程
|
||
|
||
- [ ] 10. 部署
|
||
- [ ] 10.1 Cloudflare Pages build + deploy
|
||
- [ ] 10.2 驗證所有頁面可存取
|
||
|
||
---
|
||
|
||
## Phase 4：README + 發布
|
||
|
||
- [ ] 11. 更新 `arcrun/README.md`
|
||
- [ ] 11.1 三種 Quick Start（CLI / Python / JS）
|
||
- [ ] 11.2 零件列表（21 個）
|
||
- [ ] 11.3 Auth Recipe 列表（20 個服務）
|
||
- [ ] 11.4 連結到 arcrun.dev 和 Swagger UI
|
||
|
||
- [ ] 12. 發布
|
||
- [ ] 12.1 Python SDK：`pip install build && python -m build && twine upload dist/*`
|
||
- [ ] 12.2 JS SDK：`npm run build && npm publish`
|
||
- [ ] 12.3 驗證：從零開始 `pip install arcrun` / `npm install arcrun` + hello world
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
- JS SDK 套件名需 richblack 決定（`arcrun` 已被 CLI 佔用 → 可能用 `@arcrun/sdk`）
|
||
- OAuth secrets 設定需 richblack 手動操作（GCP Console + GitHub Settings）
|
||
- `bind()` 跨 session 限制是已知的，封測期間先接受
|
||
- credential 加密用的 `encryption_key` 目前由 `/register` 回傳，`acr init` 自動存入 config
|