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
commit 922a57fe34
485 changed files with 89356 additions and 0 deletions
@@ -0,0 +1,156 @@
+# Skill: Add New WASM Component
+
+## 何時用這個 skill
+
+`arcrun_list_components()` 沒有你需要的零件。要寫一個新的 TinyGo / AssemblyScript WASM。
+
+**重要**：寫零件 = **改 arcrun 平台本身**，不是改 user workflow。
+這 skill 預設你有 arcrun repo write access。沒有 → 告訴用戶「需要 X 零件，請聯絡平台維護者」，停手。
+
+## 7 步流程
+
+### 1. 確認真的需要新零件
+
+先想：能不能用 `http_request` 加組合搞定？
+- 多數第三方 API → `http_request` 已夠（搭配 `auth_recipe` 處理 auth）
+- 簡單轉換 → 用 logic primitives（`set` / `filter` / `array_ops`）
+- 複雜流程編排 → cypher binding 多步而非單一大零件
+
+真的需要新零件的場景：
+- 跟 cypher-executor host functions 互動（KV、加解密、簽 JWT）
+- 邏輯太複雜不適合多節點分解
+- 為效能（一次 worker call 取代 10 次 fetch）
+
+### 2. 讀規範
+
+- `matrix/arcrun/.claude/rules/03-component-architecture.md` — 部署慣例
+- `matrix/arcrun/.claude/rules/01-tech-stack.md` — TinyGo 限制
+- 既有相似零件範例：`matrix/arcrun/registry/components/{name}/main.go`
+
+### 3. 開新目錄
+
+```
+matrix/arcrun/registry/components/{your_component}/
+├── main.go                    TinyGo source
+├── component.contract.yaml    input/output schema + 描述
+└── (build 後產出 .wasm)
+```
+
+合約格式（contract.yaml）：
+```yaml
+canonical_id: your_component
+display_name: 中文顯示名
+category: data | auth | api | logic
+version: 0.1.0
+description: |
+  做什麼用、限制、注意事項。AI 看這份決定要不要用你的零件
+input_schema:
+  type: object
+  required: [foo, bar]
+  properties:
+    foo: { type: string, description: "..." }
+    bar: { type: number, description: "..." }
+output_schema:
+  type: object
+  properties:
+    result: { type: string }
+    success: { type: boolean }
+gherkin_tests:
+  - given: "input foo=hello"
+    when: "component runs"
+    then: "result contains hello"
+```
+
+### 4. 寫 main.go
+
+```go
+package main
+
+import (
+    "encoding/json"
+    "io"
+    "os"
+)
+
+type Input struct {
+    Foo string `json:"foo"`
+    Bar int    `json:"bar"`
+}
+
+type Output struct {
+    Result  string `json:"result"`
+    Success bool   `json:"success"`
+}
+
+func main() {
+    bytes, _ := io.ReadAll(os.Stdin)
+    var in Input
+    json.Unmarshal(bytes, &in)
+
+    // 你的邏輯
+    result := in.Foo + ":" + string(rune(in.Bar))
+
+    out := Output{Result: result, Success: true}
+    json.NewEncoder(os.Stdout).Encode(out)
+}
+```
+
+限制：
+- 只 import：`os`、`io`、`encoding/json`、`encoding/base64`、`strings`、`time` 等 stdlib
+- **禁用**：`net/http`（用 host function `u6u.http_request`）、`crypto/rsa`（用 host function）
+- 全部 logic 在 main()，stdin/stdout JSON I/O
+
+### 5. 本地 build + 測
+
+```bash
+cd registry/components/your_component
+tinygo build -target=wasi -o your_component.wasm main.go
+echo '{"foo":"hello","bar":42}' | wasmtime your_component.wasm
+```
+
+### 6. 部署成獨立 Worker
+
+```
+.component-builds/your_component/
+├── wrangler.toml      name = "arcrun-your-component"
+├── package.json
+├── component.wasm     從上面 build 複製過來
+└── src/index.ts       固定 WASI shim（複製 component-worker-template）
+```
+
+`wrangler.toml`：
+```toml
+name = "arcrun-your-component"
+main = "src/index.ts"
+compatibility_date = "2025-02-19"
+workers_dev = true   # 必須 true，cypher-executor 走 workers.dev 對內 URL
+[[routes]]
+pattern = "your-component.arcrun.dev/*"
+zone_name = "arcrun.dev"
+```
+
+push → CI 自動部署。
+
+### 7. 註冊到 cypher-executor 白名單
+
+⚠️ **目前的架構債**（M2 計畫修）：每加零件要手動加 `cypher-executor/src/lib/component-loader.ts`：
+
+```ts
+const WASM_HTTP_RUNNER_IDS: ReadonlySet<string> = new Set([
+  // ... 既有
+  'your_component',  // ← 加這行
+]);
+```
+
+不加 → workflow 用你的零件會噴「找不到零件」。
+
+未來會改成 registry KV 動態查（`cypher-executor-dynamic-component-discovery` SDD 待開）。
+
+## 驗證上線
+
+```
+arcrun_list_components() → 應該看到 your_component
+arcrun_get_component_contract(canonical_id='your_component') → 看 schema
+```
+
+寫個 test workflow 用你的零件，跑通就完成。