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>
This commit is contained in:
uncle6me-web
@@ -0,0 +1,360 @@
|
||||
# u6u 系統規格書 v1.0
|
||||
## 給 AI 的架構思考指引
|
||||
|
||||
> 本文件用途：讓 AI 理解 u6u 的完整設計意圖、現況、與未來路徑，
|
||||
> 在實作決策時能自行判斷方向正確性，而不只是執行單一任務。
|
||||
|
||||
---
|
||||
|
||||
## 一、系統本質（先理解再動手）
|
||||
|
||||
u6u 不是 workflow 工具，不是 no-code 平台，不是 iPaaS。
|
||||
|
||||
u6u 是一個**「意圖到系統」的生物體積木平台**：
|
||||
|
||||
- 人類說出意圖（自然語言）
|
||||
- AI 從零件宇宙組裝出可運行的系統
|
||||
- 系統會自動評價、演化、淘汰舊零件
|
||||
- 累積的零件就是核心資產，越積越有價值
|
||||
|
||||
**設計的終極體驗：** 工廠主管拖拉十分鐘，組出具備微服務架構的企業系統，零程式碼，但底層是真正的分散式系統。
|
||||
|
||||
---
|
||||
|
||||
## 二、四層邏輯架構
|
||||
|
||||
```
|
||||
Polaris（意圖層）
|
||||
↓ 自然語言 → AI 拆解
|
||||
Prototype（前端層）
|
||||
↓ UI 元件 + 觸發事件
|
||||
Workflow（編排層）
|
||||
↓ Cypher 語法定義執行順序
|
||||
Component（零件層）
|
||||
↓ .wasm 實際執行
|
||||
```
|
||||
|
||||
每一層向下只透過標準介面溝通，層與層之間完全解耦。
|
||||
|
||||
---
|
||||
|
||||
## 三、物理三層部署
|
||||
|
||||
```
|
||||
Tier 1：雲端總部（Cloudflare Workers）
|
||||
- CEO AI 讀取 Markdown 戰略文件
|
||||
- 全域零件同步至 R2
|
||||
- Cloudflare D1 + Vectorize（KBDB）
|
||||
|
||||
Tier 2：企業地端（workerd 叢集）
|
||||
- 部門主管 AI 派工
|
||||
- 工匠 AI 生成並測試新零件
|
||||
- Kùzu 或 PostgreSQL + AGE（圖資料庫）
|
||||
- pgvector 或 Milvus（向量搜尋）
|
||||
|
||||
Tier 3：邊緣載具（無人機、AGV、工廠設備）
|
||||
- 極小參數 SLM
|
||||
- Go 排程引擎 + 內嵌 Wazero（無 V8）
|
||||
- SQLite + sqlite-vss
|
||||
- 離線生存，DTN 短點射傳輸
|
||||
```
|
||||
|
||||
**關鍵約束：** Tier 3 沒有 V8，沒有 Node.js，沒有網路。
|
||||
所有零件必須在 Wazero 上跑，所有資料傳輸透過 stdin/stdout JSON。
|
||||
|
||||
---
|
||||
|
||||
## 四、零件規格（Component Contract）
|
||||
|
||||
這是整個系統最核心的不變量。零件規格定錯，累積的資產會變成技術債。
|
||||
|
||||
### 4.1 零件的本質定義
|
||||
|
||||
**一個零件只做一件事。**
|
||||
|
||||
```
|
||||
✅ gsheets_create_table
|
||||
✅ gsheets_delete_table
|
||||
✅ gsheets_get_entries
|
||||
❌ gsheets_manager（做太多事，禁止）
|
||||
```
|
||||
|
||||
### 4.2 零件合約格式（component.contract.yaml）
|
||||
|
||||
每個零件必須附帶此合約，這是 AI 讀取零件的唯一介面描述：
|
||||
|
||||
```yaml
|
||||
id: "gsheets_get_entries" # 功能合約名稱（永久不變）
|
||||
version: "v2" # 實作版本
|
||||
wasi_target: "preview1" # 明確標記 WASI 版本，未來升級用
|
||||
stability: "floating" # floating | stable | pinned
|
||||
|
||||
runtime_compat:
|
||||
- "cf-workers"
|
||||
- "workerd"
|
||||
- "wazero"
|
||||
|
||||
constraints:
|
||||
max_size_kb: 2048 # 超過視為打包了 runtime
|
||||
max_cold_start_ms: 50
|
||||
no_network_syscall: true # 禁止零件自己發 HTTP
|
||||
no_filesystem_syscall: true # 只能 stdin/stdout
|
||||
io_model: "stdin_stdout_json" # 唯一合法的 I/O 模型
|
||||
|
||||
input_schema:
|
||||
type: object
|
||||
required: ["spreadsheet_id", "sheet_name"]
|
||||
properties:
|
||||
spreadsheet_id: { type: string }
|
||||
sheet_name: { type: string }
|
||||
limit: { type: integer, default: 100 }
|
||||
|
||||
output_schema:
|
||||
type: object
|
||||
properties:
|
||||
rows: { type: array }
|
||||
total: { type: integer }
|
||||
error: { type: string }
|
||||
|
||||
gherkin_tests:
|
||||
- scenario: "正常取得資料"
|
||||
given: '{"spreadsheet_id":"abc","sheet_name":"Sheet1"}'
|
||||
then_contains: '{"total":1}'
|
||||
- scenario: "不存在的表格回傳錯誤"
|
||||
given: '{"spreadsheet_id":"abc","sheet_name":"不存在"}'
|
||||
then_contains: '{"error":'
|
||||
|
||||
tags: ["google", "sheets", "data", "read"]
|
||||
description: "從 Google Sheets 取得指定工作表的所有資料列"
|
||||
```
|
||||
|
||||
### 4.3 語言無限制原則
|
||||
|
||||
**零件開發語言完全不限制**，只要輸出符合以上合約的 .wasm 即可。
|
||||
|
||||
可接受語言（非排他）：TinyGo、Rust、AssemblyScript、C/C++
|
||||
|
||||
注意事項（不是禁止，是要求自行驗證）：
|
||||
- TypeScript via Extism：會打包 QuickJS，體積通常超過 2MB 限制
|
||||
- 標準 Go（非 TinyGo）：runtime 過肥，通常超過體積限制
|
||||
- 任何語言：不可在 .wasm 內部呼叫網路或檔案系統 syscall
|
||||
|
||||
**驗收標準只有一個：通過沙盒測試。** 語言是零件作者自己的事。
|
||||
|
||||
### 4.4 零件的前後端分類
|
||||
|
||||
| 類型 | 執行位置 | I/O | 範例 |
|
||||
|------|----------|-----|------|
|
||||
| 後端邏輯零件 | Workers/workerd/Wazero | JSON stdin/stdout | validate_json, http_request |
|
||||
| 前端 UI 零件 | 瀏覽器 | HTML attributes / DOM events | u6u-btn, u6u-chart |
|
||||
| **混合零件** | **禁止** | — | **強制拆成兩個** |
|
||||
|
||||
---
|
||||
|
||||
## 五、零件版本控制策略
|
||||
|
||||
### 5.1 命名規則
|
||||
|
||||
```
|
||||
gsheets_get_entries ← 功能合約名稱（搜尋用，永遠存在）
|
||||
gsheets_get_entries_v1 ← 第一個實作（慢但能用）
|
||||
gsheets_get_entries_v2 ← 更快的實作（由另一個 AI/用戶提交）
|
||||
```
|
||||
|
||||
### 5.2 穩定性標籤
|
||||
|
||||
Workflow 引用零件時可指定穩定性需求：
|
||||
|
||||
```
|
||||
gsheets_get_entries → 預設 floating，AI 自動選最優版本
|
||||
gsheets_get_entries@stable → 有更好版本時提示，人工確認才換
|
||||
gsheets_get_entries@pinned:v1 → 版本凍結，宇宙怎麼演化都不影響
|
||||
```
|
||||
|
||||
| 標籤 | 適用情境 | 更新行為 |
|
||||
|------|----------|----------|
|
||||
| `floating` | 一般企業應用 | AI 自動換成最優版本 |
|
||||
| `stable` | 重要業務流程 | 有更好版本時提示，人工確認 |
|
||||
| `pinned` | 工廠控制器、嵌入式設備 | 永遠不動，即使進入墓地也保留 .wasm |
|
||||
|
||||
### 5.3 淘汰機制
|
||||
|
||||
- AI 搜尋零件時，KBDB 依「成功率 × 速度 × 被調用次數」排序
|
||||
- 連續 30 天無使用且評價下降 → Deprecated
|
||||
- Deprecated 後繼續 90 天無復活 → 進墓地（從搜尋清單移除）
|
||||
- **墓地的 .wasm 永遠保留**，pinned 的 Workflow 永遠能拉到
|
||||
|
||||
---
|
||||
|
||||
## 六、零件製造指引書（給用戶 AI 的規範）
|
||||
|
||||
u6u 不限制誰來造零件，任何 AI（用戶自己的 Claude、GPT、本地模型）都可以。
|
||||
但必須遵守此指引書，否則沙盒測試不過，無法上架。
|
||||
|
||||
### Step 1：理解介面合約
|
||||
|
||||
造零件前，先定義合約 YAML。
|
||||
**零件只在乎輸入 JSON 和輸出 JSON，完全不管前端長什麼樣子。**
|
||||
|
||||
```
|
||||
人類：我要一個可以查 Google Sheets 的零件
|
||||
AI 的第一步：定義 input_schema 和 output_schema，不是寫程式
|
||||
```
|
||||
|
||||
### Step 2：選擇開發語言
|
||||
|
||||
選擇你最熟悉的、能產出 WASI preview1 相容 .wasm 的語言。
|
||||
建議：
|
||||
|
||||
- 小型邏輯零件（轉換、計算）→ TinyGo 或 AssemblyScript（體積小）
|
||||
- 效能敏感零件 → Rust（生態最成熟）
|
||||
- 任何語言都可以，只要通過合約限制
|
||||
|
||||
### Step 3：實作規則
|
||||
|
||||
```
|
||||
✅ 只用 stdin 讀取輸入 JSON
|
||||
✅ 只用 stdout 輸出結果 JSON
|
||||
✅ 錯誤也用 stdout 輸出：{"error": "說明"}，不要 panic/crash
|
||||
✅ 無狀態：每次呼叫都是獨立的，不依賴上一次執行的結果
|
||||
✅ 需要打外部 API？透過 host function 注入，不在 .wasm 裡自己發 HTTP
|
||||
❌ 禁止網路 syscall
|
||||
❌ 禁止檔案系統 syscall
|
||||
❌ 禁止打包 runtime（QuickJS、Node.js 等）
|
||||
❌ 禁止超過 2MB
|
||||
```
|
||||
|
||||
### Step 4：本地測試方式
|
||||
|
||||
```bash
|
||||
# 用任何 WASI runtime 本地測試
|
||||
echo '{"spreadsheet_id":"abc","sheet_name":"Sheet1"}' | \
|
||||
wasmtime gsheets_get_entries.wasm
|
||||
|
||||
# 預期輸出
|
||||
{"rows":[...],"total":5}
|
||||
```
|
||||
|
||||
### Step 5：提交審核
|
||||
|
||||
提交 `.wasm` + `component.contract.yaml`，系統自動執行：
|
||||
|
||||
1. 體積檢查（< 2MB）
|
||||
2. 冷啟動時間（< 50ms）
|
||||
3. Syscall 掃描（不能有網路/檔案系統呼叫）
|
||||
4. Gherkin 測試（合約裡的所有 scenario 必須 100% 通過）
|
||||
5. 多 runtime 相容測試（cf-workers / workerd / wazero）
|
||||
|
||||
全部通過 → 上架進入零件宇宙，開始累積評價。
|
||||
|
||||
---
|
||||
|
||||
## 七、Cypher 編排語言
|
||||
|
||||
Workflow 使用擴展三元組語法描述執行邏輯：
|
||||
|
||||
```yaml
|
||||
kind: Workflow
|
||||
id: wf_query_attendance
|
||||
|
||||
triplets:
|
||||
# 基本流程
|
||||
- "START >> TRIGGERS >> step_receive"
|
||||
- "step_receive >> IS_A >> component://webhook_receiver_v1"
|
||||
|
||||
# 條件分支
|
||||
- "step_receive >> ON_SUCCESS >> step_validate"
|
||||
- "step_receive >> ON_FAIL >> step_notify_error"
|
||||
|
||||
# 跨 Workflow 串接
|
||||
- "step_validate >> CALLS_SUBFLOW >> workflow://save_to_db"
|
||||
|
||||
# 前端觸發後端
|
||||
- "btn_submit >> ON_CLICK >> workflow://wf_query_attendance"
|
||||
```
|
||||
|
||||
**URI 協議規範：**
|
||||
- `component://` → 引用零件
|
||||
- `workflow://` → 引用子 Workflow
|
||||
- `ui://` → 引用前端零件
|
||||
- `style://` → 引用樣式零件
|
||||
|
||||
---
|
||||
|
||||
## 八、KBDB 在 u6u 的角色
|
||||
|
||||
u6u 的所有狀態都在 KBDB 裡：
|
||||
|
||||
| KBDB Block 類型 | 存放內容 |
|
||||
|-----------------|----------|
|
||||
| Component Block | 零件合約、.wasm 位置、版本、評價指標 |
|
||||
| Workflow Block | Cypher 三元組、依賴零件清單 |
|
||||
| Prototype Block | 前端結構、UI 零件樹 |
|
||||
| Pitfall Block | 避坑記錄，AI 搜尋時強制讀取 |
|
||||
| Evaluation Block | 每次 Workflow 執行後的強制評價結果 |
|
||||
|
||||
**KBDB 不變量：永遠只有三張表（blocks/templates/slots），不新增表。**
|
||||
所有以上類型都用 Template + Slot 實現。
|
||||
|
||||
---
|
||||
|
||||
## 九、自動演化迴圈
|
||||
|
||||
```
|
||||
執行 Workflow
|
||||
↓
|
||||
強制 AI 評價（Evaluator Agent）
|
||||
↓ 發現問題
|
||||
生成修復 Ticket → 通知製作人
|
||||
↓ AI 嘗試修復
|
||||
通過 Gherkin 驗收 → 熱更新
|
||||
↓ 無法修復
|
||||
標記 [HAS_PITFALL] 到 Cypher 圖
|
||||
↓
|
||||
下一個 AI 搜尋時讀到坑，強制繞道
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、現況與未來路徑
|
||||
|
||||
### 現在已有
|
||||
|
||||
- KBDB（blocks/templates/slots + Vectorize）
|
||||
- IS-Squad MCP（execute_cypher 等工具）
|
||||
- Cloudflare Workers 環境
|
||||
|
||||
### 最小可 demo 路徑
|
||||
|
||||
1. **Cypher 執行引擎**：三元組 → 實際執行順序（確認 execute_cypher 邊界）
|
||||
2. **首批核心零件**（5 個）：
|
||||
- `webhook_receiver`
|
||||
- `json_transform`
|
||||
- `http_request`（透過 host function）
|
||||
- `notify_line`
|
||||
- `validate_json`
|
||||
3. **機甲最小版本**：意圖 → 零件搜尋 → 組裝 Workflow（先用硬編碼路由）
|
||||
4. **前端畫布 MVP**：靜態 HTML 模擬雙面翻轉體驗
|
||||
|
||||
### 技術監控項目
|
||||
|
||||
- **WASI Component Model（preview2）**：目前用 preview1，未來 3-5 年會有遷移壓力。
|
||||
合約裡已有 `wasi_target: "preview1"` 標記，升級時知道要改什麼。
|
||||
- **Kùzu 成熟度**：地端圖資料庫首選，持續觀察 v1.0 穩定性。
|
||||
|
||||
---
|
||||
|
||||
## 十一、實作決策原則（CC 行動準則）
|
||||
|
||||
遇到不確定的實作決策時，依序問自己：
|
||||
|
||||
1. **這個決策會影響零件合約嗎？** 如果是，停下來討論，不要自行決定。
|
||||
2. **這個實作是否限制了未來換 runtime 的自由？** 如果是，重新設計介面。
|
||||
3. **這個零件做超過一件事嗎？** 如果是，拆成兩個零件。
|
||||
4. **這個設計在 Tier 3 離線環境能跑嗎？** 如果不能，重新考慮。
|
||||
5. **有沒有現成零件可以組合？** 先搜尋 KBDB，不要重造輪子。
|
||||
|
||||
---
|
||||
|
||||
*本文件版本：v1.0*
|
||||
*綜合自：u6u 系統與零件宇宙全景規劃白皮書、自動演化 ERP 架構藍圖、智慧前端與工匠開發藍圖，加入技術評論與補充建議。*
|
||||
Reference in New Issue
Block a user