Arcrun/docs/user_requirements/u6u-long-term/u6u_system_spec.md

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 讀取零件的唯一介面描述：

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：本地測試方式

# 用任何 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 使用擴展三元組語法描述執行邏輯：

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