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