uncle6me-web
922a57fe34
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>
361 lines
11 KiB
Markdown
361 lines
11 KiB
Markdown
# 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 架構藍圖、智慧前端與工匠開發藍圖，加入技術評論與補充建議。*
|