# Requirements Document

## Introduction

u6u 平台演進規格描述從現況（HTTP endpoint 零件、單一 Cloudflare 部署、無前端畫布）
到目標架構（WASM 零件模型、三層物理部署、雙面翻轉畫布）的完整演進路徑。

本規格涵蓋三個核心演進軸：

1. **零件模型遷移**：將 20 個內建零件從 Cloudflare Worker HTTP endpoint 遷移至 WASI preview1 `.wasm` 格式，附帶 `component.contract.yaml`，以 stdin/stdout JSON 作為唯一 I/O 模型。
2. **多 Tier 執行抽象**：讓 Cypher Executor 透過統一的 Component Dispatcher 介面，跨 Tier 1（Cloudflare Workers）、Tier 2（workerd 地端叢集）、Tier 3（Go + Wazero 邊緣載具）呼叫零件。
3. **前端雙面畫布**：建立以 Web Components 為基礎的視覺化畫布，正面為 UI 視圖，反面為 Cypher 邏輯視圖，智慧容器自動打包表單值。

---

## Glossary

- **Component（零件）**：系統最小執行單元，一個零件只做一件事，以 `.wasm`（WASI preview1）或 Web Component 形式存在。
- **Component_Contract**：每個零件附帶的 `component.contract.yaml`，定義 id、version、wasi_target、stability、runtime_compat、constraints、input_schema、output_schema、gherkin_tests。
- **Component_Registry**：KBDB 中儲存所有零件合約與 `.wasm` 位置的索引，以 `tpl-component` Template Block 實作。
- **Component_Dispatcher**：Cypher Executor 內部的路由層，根據零件的 `runtime_compat` 與目標 Tier 決定呼叫路徑（Service Binding / workerd HTTP / Wazero IPC）。
- **Cypher_Executor**：Workflow 執行引擎，解析三元組語法，透過 GraphExecutor 執行節點，現部署於 Cloudflare Workers。
- **Cypher_Triplet**：`"A >> 關係 >> B"` 格式的三元組，描述節點間的語意關係。
- **KBDB**：三位一體記憶庫（blocks / templates / slots），搭配 Cloudflare Vectorize，是平台唯一的持久化狀態來源。
- **Tier_1**：雲端層，Cloudflare Workers + D1 + Vectorize + R2，全球無伺服器部署。
- **Tier_2**：企業地端層，workerd 叢集 + Kùzu 或 PostgreSQL + AGE，高機密內網環境。
- **Tier_3**：邊緣載具層，Go 排程引擎 + 內嵌 Wazero + SQLite，無 V8、無網路的極限環境（無人機、AGV）。
- **WASI_Preview1**：WebAssembly System Interface preview1 規格，零件唯一合法的 WASM 目標格式。
- **Canvas（畫布）**：前端雙面翻轉介面，正面為 UI 視圖，反面為 Cypher 邏輯視圖。
- **Smart_Container**：畫布上的排版容器（如 `<u6u-card>`），自動打包同容器內所有輸入元件的值並附加至觸發事件的 payload。
- **Forge_AI**：工匠 AI，負責在 Tier 2 地端接收零件規格、生成 TinyGo 程式碼、編譯並測試 `.wasm`。
- **Evaluator_Agent**：強制評價代理，每次 Workflow 執行後自動評估成功率、效能、警告訊息。
- **Pitfall_Block**：KBDB 中記錄已知問題的 Block，AI 搜尋時強制讀取以繞道。
- **Stability_Tag**：零件版本穩定性標籤，值為 `floating`（AI 自動選最優）、`stable`（人工確認才換）、`pinned`（版本凍結）。
- **DTN**：Delay-Tolerant Networking，Tier 3 邊緣載具在間歇性網路下的短點射傳輸協議。

---

## Requirements

### Requirement 1：零件合約規格標準化

**User Story:** As a 平台架構師, I want 每個零件都有標準化的 `component.contract.yaml` 合約, so that AI 能透過統一介面讀取零件能力，並在任何 Tier 上驗證相容性。

#### Acceptance Criteria

1. THE Component_Contract SHALL 包含以下必填欄位：`canonical_id`（功能合約名稱，永久不變）、`display_name`（人類可讀名稱，可自由撰寫）、`description`（語意搜尋用途，需精確描述零件能做什麼、適用情境，至少 20 字）、`version`（實作版本）、`wasi_target`（值為 `"preview1"`）、`stability`（值為 `floating`、`stable` 或 `pinned` 之一）、`runtime_compat`（陣列，值為 `cf-workers`、`workerd`、`wazero` 的子集）、`constraints`、`input_schema`、`output_schema`、`gherkin_tests`。
1a. THE `canonical_id` SHALL 遵循以下命名規範，以確保全庫一致性：
    - 格式：`{scope}_{action}` 或 `{scope}_{object}` 或 `{scope}`（單詞），全部小寫底線，不超過 4 個單詞
    - **整合類**（category: api）：以服務名稱為 scope，可加動作；範例：`gmail`、`gmail_send`、`google_sheets`、`google_sheets_append`、`telegram`、`telegram_send`
    - **資料處理類**（category: data）：以資料型別或操作為 scope；範例：`string_ops`、`array_ops`、`date_ops`、`json_transform`
    - **控制流類**（category: logic）：以控制結構名稱命名；範例：`if_control`、`foreach_control`、`try_catch`、`switch`、`wait`
    - **AI 類**（category: ai）：以 `ai_` 為前綴；範例：`ai_transform_compile`、`ai_summarize`、`ai_classify`
    - 禁止：中文、空格、大寫、連字號（`-`）、版本號混入 id（`gmail_v2` 用 `version: v2` 表達）
1b. THE `display_name` SHALL 為人類可讀的自由格式名稱（可中文、可含空格）；此欄位供 UI 顯示用，不作為系統識別符。範例：`canonical_id: google_sheets_append` 配 `display_name: "Google Sheets — 新增一列"`。
1c. THE `description` SHALL 用於 Vectorize 語意搜尋索引；撰寫時應以「能做什麼、適合什麼情境」為核心，避免只寫零件名稱的同義詞。範例：`"傳送 Gmail 電子郵件，適合 Workflow 完成時通知使用者、訂閱確認信、錯誤警報等場景。需要 Gmail OAuth token。"` 而非 `"Gmail 發信零件"`。
2. THE Component_Contract SHALL 在 `constraints` 中包含以下欄位：`max_size_kb`（上限 2048）、`max_cold_start_ms`（上限 50）、`no_network_syscall`（布林值）、`io_model`（值為 `"stdin_stdout_json"`）。
3. WHEN 一個零件的 `id` 已存在於 Component_Registry，THE Component_Registry SHALL 允許以新 `version` 值新增該零件的新實作，而不覆蓋舊版本。
4. THE Component_Contract SHALL 在 `gherkin_tests` 中至少包含一個正常情境（happy path）與一個錯誤情境（error path）的測試案例。
5. IF 一個零件的 `input_schema` 或 `output_schema` 涉及序列化或反序列化操作，THEN THE Component_Contract SHALL 包含一個 round-trip 測試案例，驗證 `parse(format(x)) == x`。

---

### Requirement 2：零件沙盒驗收流程

**User Story:** As a 零件提交者（AI 或開發者）, I want 提交的零件自動通過沙盒驗收, so that 只有符合品質標準的零件才能進入零件宇宙。

#### Acceptance Criteria

1. WHEN 一個零件被提交至 Component_Registry，THE Component_Registry SHALL 依序執行以下驗收步驟：（a）體積檢查（`.wasm` 小於 `max_size_kb`）、（b）冷啟動時間測量（小於 `max_cold_start_ms`）、（c）syscall 掃描（不含網路或檔案系統 syscall）、（d）Gherkin 測試執行（所有 scenario 100% 通過）、（e）多 runtime 相容測試（`runtime_compat` 列出的所有 runtime）。
2. IF 任一驗收步驟失敗，THEN THE Component_Registry SHALL 拒絕該零件上架，並回傳包含失敗步驟名稱與具體原因的錯誤訊息。
3. WHEN 所有驗收步驟通過，THE Component_Registry SHALL 將零件合約存入 KBDB 的 `tpl-component` Template Block，並記錄上架時間戳記。
4. THE Component_Registry SHALL 以冪等方式執行驗收流程，對相同 `id` 與 `version` 的重複提交回傳相同結果而不重複執行測試。

---

### Requirement 3：現有 HTTP 零件遷移至 WASM

**User Story:** As a 平台開發者, I want 將現有 20 個 HTTP endpoint 零件遷移為 WASI preview1 `.wasm` 格式, so that 零件能在 Tier 3 邊緣載具（無 V8、無網路）上執行，消除技術債。

#### Acceptance Criteria

1. THE Component_Dispatcher SHALL 支援以 WASM 模式呼叫零件：讀取 `.wasm` 二進位、透過 WASI preview1 runtime 執行、將 input JSON 寫入 stdin、從 stdout 讀取 output JSON。
2. WHEN 一個 WASM 零件需要呼叫外部 HTTP API（如 Google Sheets），THE Component_Dispatcher SHALL 透過 host function 注入方式提供網路能力，而非允許 `.wasm` 內部直接發出網路 syscall。
3. THE Component_Dispatcher SHALL 在 Tier 1（Cloudflare Workers）環境中，以 `workerd` 內建的 WASM 執行能力執行 WASI preview1 零件。
4. WHEN 一個零件的 `runtime_compat` 不包含當前執行環境的 Tier，THE Component_Dispatcher SHALL 回傳錯誤，說明該零件不相容於當前 Tier，而非嘗試執行。
5. THE Component_Dispatcher SHALL 在遷移期間同時支援舊有 HTTP endpoint 模式（Service Binding 或外部 URL）與新 WASM 模式，以 Component_Contract 的 `io_model` 欄位區分呼叫路徑。
6. FOR ALL 現有 20 個內建零件，遷移後的 WASM 版本 SHALL 通過與原 HTTP 版本相同的 Gherkin 測試案例（round-trip 等效性）。

---

### Requirement 4：零件版本控制與穩定性標籤

**User Story:** As a Workflow 設計者, I want 在 Cypher 三元組中指定零件的穩定性需求, so that 關鍵業務流程不會因 AI 自動升級零件而中斷。

#### Acceptance Criteria

1. THE Cypher_Executor SHALL 支援以下三種零件引用語法：`component://id`（預設 floating）、`component://id@stable`、`component://id@pinned:vN`。
2. WHEN 一個 Workflow 引用 `component://id`（floating），THE Component_Dispatcher SHALL 從 Component_Registry 選取該 `id` 下「成功率 × 速度 × 被調用次數」評分最高的版本執行。
3. WHEN 一個 Workflow 引用 `component://id@stable`，THE Component_Dispatcher SHALL 使用當前標記為 stable 的版本，並在有更優版本時記錄提示至 KBDB，但不自動切換。
4. WHEN 一個 Workflow 引用 `component://id@pinned:vN`，THE Component_Dispatcher SHALL 永遠使用版本 `vN`，即使該版本已被標記為 Deprecated。
5. THE Component_Registry SHALL 保留所有歷史版本的 `.wasm` 二進位，不因版本淘汰而刪除檔案。

---

### Requirement 5：Cypher 語意關係擴展

**User Story:** As a Workflow 設計者, I want Cypher 三元組支援完整的語意關係集合, so that 能描述條件分支、子流程呼叫、前端觸發等複雜業務邏輯。

#### Acceptance Criteria

1. THE Cypher_Executor SHALL 解析並執行以下語意關係：`IS_A`（節點類型宣告）、`ON_SUCCESS`（成功後繼）、`ON_FAIL`（失敗後繼）、`ON_CLICK`（前端點擊觸發）、`CALLS_SUBFLOW`（呼叫子 Workflow）、`CONTAINS`（容器包含關係）、`HAS_STYLE`（樣式關聯）、`HAS_BEHAVIOR`（行為關聯）。
2. WHEN 解析 `IS_A` 關係，THE Cypher_Executor SHALL 從 Component_Registry 載入對應的零件合約，並以合約的 `input_schema` 驗證節點的輸入 context。
3. WHEN 解析 `ON_SUCCESS` 或 `ON_FAIL` 關係，THE Cypher_Executor SHALL 根據上游節點的執行結果（成功或拋出錯誤）決定走向，而非依賴 context 中的特定欄位。
4. WHEN 解析 `CALLS_SUBFLOW` 關係，THE Cypher_Executor SHALL 以當前 context 作為子 Workflow 的 initialContext 執行，並將子 Workflow 的輸出合併回主流程 context。
5. WHEN 解析 `ON_CLICK` 關係，THE Cypher_Executor SHALL 接受來自前端 Smart_Container 打包的 payload，並以該 payload 作為 Workflow 的 initialContext。
6. THE Cypher_Executor SHALL 支援 URI 協議前綴：`component://`（零件引用）、`workflow://`（Workflow 引用）、`ui://`（前端零件引用）、`style://`（樣式零件引用）。
7. FOR ALL 合法的 Cypher 三元組序列，THE Cypher_Executor SHALL 保證解析結果的冪等性：對相同輸入三元組集合，無論排列順序，產生語意等效的執行圖（Confluence 屬性）。

---

### Requirement 6：Component Dispatcher 多 Tier 路由

**User Story:** As a 平台架構師, I want Cypher Executor 透過統一的 Component Dispatcher 介面呼叫跨 Tier 零件, so that Workflow 設計者不需要知道零件部署在哪個 Tier。

#### Acceptance Criteria

1. THE Component_Dispatcher SHALL 根據以下優先序決定呼叫路徑：（1）Tier 1：Cloudflare Service Binding（若零件部署為 Worker）或 WASM 直接執行；（2）Tier 2：workerd 叢集 HTTP endpoint；（3）Tier 3：Wazero IPC（stdin/stdout）。
2. WHEN Component_Dispatcher 在 Tier 1 環境中呼叫一個 `runtime_compat` 包含 `cf-workers` 的零件，THE Component_Dispatcher SHALL 優先使用 Cloudflare Service Binding，若 binding 不存在則退回 WASM 執行模式。
3. WHEN Component_Dispatcher 在 Tier 3 環境中呼叫零件，THE Component_Dispatcher SHALL 只使用 Wazero 執行本地 `.wasm` 檔案，不發出任何網路請求。
4. IF Component_Dispatcher 無法在當前 Tier 找到可用的呼叫路徑，THEN THE Component_Dispatcher SHALL 回傳結構化錯誤，包含：零件 id、當前 Tier、嘗試的呼叫路徑清單。
5. THE Component_Dispatcher SHALL 對每次零件呼叫記錄執行時間（ms）、成功或失敗狀態，並非同步寫入 KBDB 的 Evaluation Block，不阻擋主流程。
6. WHILE Component_Dispatcher 執行零件呼叫，THE Component_Dispatcher SHALL 強制套用 Component_Contract 中的 `max_cold_start_ms` 作為逾時上限，超時後回傳逾時錯誤。

---

### Requirement 7：Tier 3 邊緣離線生存能力

**User Story:** As a 邊緣載具操作者（無人機、AGV）, I want 載具在完全離線環境中仍能執行預載的 Workflow, so that 業務不因網路中斷而停擺。

#### Acceptance Criteria

1. THE Tier_3 執行引擎 SHALL 在無網路連線的環境中，使用本地 SQLite 作為 KBDB 替代儲存，執行預先下載的 Cypher Workflow 與 `.wasm` 零件。
2. WHEN Tier_3 執行引擎在執行中發現缺少所需零件，THE Tier_3 執行引擎 SHALL 記錄缺失零件的 `id` 與 `input_schema` 至本地 DTN 佇列，待下次連網時以 Burst 傳輸方式送至 Tier_2 請求代工。
3. WHEN Tier_3 執行引擎收到來自 Tier_2 的新 `.wasm` 零件，THE Tier_3 執行引擎 SHALL 在執行前對該零件進行 syscall 掃描，確認不含網路或檔案系統 syscall，通過後才載入執行。
4. THE Tier_3 執行引擎 SHALL 在 Cypher 圖譜執行中途動態替換失敗零件（如感測器零件因環境變化失效），以 Component_Registry 中相同 `input_schema` 的備用零件繼續執行，不中斷整體 Workflow。
5. WHEN Tier_3 執行引擎重新連線至 Tier_2，THE Tier_3 執行引擎 SHALL 將本地執行日誌（包含 trace、評價結果、Pitfall 記錄）同步至 Tier_2 的 KBDB，確保全局狀態一致。

---

### Requirement 8：前端 Web Components 零件庫

**User Story:** As a 前端開發者, I want 一套以 Web Components 標準實作的 u6u UI 零件庫, so that 畫布上的 UI 元件能在任何現代瀏覽器中獨立運作，不依賴特定前端框架。

#### Acceptance Criteria

1. THE Canvas SHALL 提供以下核心 Web Components：`<u6u-btn>`（按鈕）、`<u6u-text-input>`（文字輸入）、`<u6u-text-field>`（多行文字）、`<u6u-chart>`（圖表）、`<u6u-card>`（智慧容器）。
2. THE `<u6u-btn>` SHALL 支援以下 HTML attributes：`label`（顯示文字）、`color`（主題色）、`tooltip`（滑鼠懸停提示，純靜態，不觸發 Webhook）、`workflow`（綁定的 Workflow URI，格式為 `workflow://id`）。
3. WHEN `<u6u-btn>` 的 `workflow` attribute 被設定且使用者點擊按鈕，THE `<u6u-btn>` SHALL 發出 `u6u:trigger` 自訂事件，事件 detail 包含 `{ workflowId, payload }`。
4. THE `<u6u-card>` SHALL 在接收到子元件的 `u6u:trigger` 事件時，自動收集同容器內所有 `<u6u-text-input>` 與 `<u6u-text-field>` 的當前值，合併至事件的 `payload` 後再向上冒泡。
5. FOR ALL Web Components，THE Canvas SHALL 保證元件的 HTML attribute 變更能即時反映至視覺渲染，且渲染結果與 attribute 值之間的對應關係具有冪等性（相同 attribute 值永遠產生相同渲染結果）。

---

### Requirement 9：雙面翻轉畫布介面

**User Story:** As a 業務使用者（非工程師）, I want 畫布上每個 UI 元件都能翻面查看並編輯其 Cypher 邏輯連線, so that 不需要寫程式就能理解並修改業務邏輯。

#### Acceptance Criteria

1. THE Canvas SHALL 為每個 UI 零件提供「翻面」操作，切換至邏輯視圖後，顯示該零件關聯的 Cypher 三元組（以視覺化節點連線方式呈現）。
2. WHEN 使用者在邏輯視圖中修改 Cypher 連線（新增、刪除或修改三元組），THE Canvas SHALL 即時更新對應 Workflow 的 KBDB Block，並在正面 UI 視圖中反映連線狀態變更（如按鈕顏色或 badge 提示）。
3. THE Canvas SHALL 在邏輯視圖中提供 Workflow URI 選擇器，列出 KBDB 中所有可用的 Workflow，讓使用者透過下拉選單完成 `ON_CLICK >> workflow://id` 的綁定，不需手動輸入 URI。
4. WHEN 使用者在畫布上將兩個 UI 零件拖入同一個 `<u6u-card>` 容器，THE Canvas SHALL 自動在邏輯視圖中顯示 Smart_Container 的自動打包關係，說明哪些輸入值會被自動收集。
5. THE Canvas SHALL 在使用者嘗試替換一個已綁定 Workflow 的 UI 零件時，只顯示 Component_Registry 中具備相同觸發能力（即 `u6u:trigger` 事件）的候選零件，過濾掉不相容的零件。

---

### Requirement 10：自動演化評價迴圈

**User Story:** As a 平台維運者, I want 每次 Workflow 執行後自動觸發 AI 評價, so that 系統能持續識別問題零件並累積避坑知識。

#### Acceptance Criteria

1. WHEN 一個 Workflow 執行完畢（無論成功或失敗），THE Evaluator_Agent SHALL 在執行結束後非同步評估以下維度：執行狀態（成功 / 失敗 / 逾時）、各節點執行時間、零件錯誤率趨勢。
2. WHEN Evaluator_Agent 發現某零件的錯誤率在連續 5 次執行中超過 50%，THE Evaluator_Agent SHALL 在 KBDB 中為該零件建立 Pitfall_Block，記錄：零件 id、失敗模式描述、首次發現時間戳記。
3. WHEN Component_Dispatcher 在 Component_Registry 搜尋零件時，THE Component_Dispatcher SHALL 讀取目標零件的所有關聯 Pitfall_Block，並在選擇版本時降低有 Pitfall 記錄的版本的評分權重。
4. WHEN 一個零件連續 30 天無任何 Workflow 引用，THE Component_Registry SHALL 將該零件標記為 `Deprecated`，並從預設搜尋結果中移除，但保留 `.wasm` 二進位與合約。
5. WHEN 一個 `Deprecated` 零件再經過 90 天仍無引用，THE Component_Registry SHALL 將該零件移入墓地（tombstone 狀態），從所有搜尋結果中移除，但 `pinned` 版本的 `.wasm` 永遠保留且可被 Component_Dispatcher 存取。
6. THE Evaluator_Agent SHALL 以冪等方式處理重複的執行日誌，對相同 `run_id` 的重複評價請求回傳相同結果而不重複建立 Pitfall_Block。

---

### Requirement 11：零件開發指引（Component Authoring Guide）

**User Story:** As a 零件開發者（使用自己的 AI 工具，如 Claude、GPT、本地模型）, I want 平台提供完整的零件開發指引, so that 我的 AI 能根據指引生成符合合約規格的 `.wasm` 零件，並一次通過沙盒驗收。

#### Acceptance Criteria

1. THE Component_Registry SHALL 在 `GET /components/guide` 端點提供機器可讀的開發指引文件（Markdown 格式），內容包含：零件合約 YAML 完整範例、I/O 模型說明（stdin/stdout JSON）、各語言（TinyGo、Rust、AssemblyScript）的最小可運行範例程式碼、本地測試指令（`wasmtime` 執行方式）、常見錯誤與解法。
2. THE Component_Registry SHALL 在開發指引中明確列出所有禁止行為：網路 syscall、檔案系統 syscall、打包 runtime（QuickJS、Node.js 等）、超過 2MB、混合前後端邏輯於同一零件。
3. THE Component_Registry SHALL 在開發指引中提供 `component.contract.yaml` 的 JSON Schema 定義，讓開發者的 AI 能在提交前自行驗證合約格式正確性。
4. WHEN 一個零件提交驗收失敗，THE Component_Registry SHALL 在錯誤回應中附上指向開發指引對應章節的錨點連結（如 `#syscall-constraints`），讓開發者的 AI 能直接定位修復方向。
5. THE Component_Registry SHALL 提供 `POST /components/validate-contract` 端點，接受 `component.contract.yaml` 內容，回傳格式驗證結果（欄位完整性、schema 合法性、gherkin_tests 最低數量），讓開發者在提交 `.wasm` 前先驗證合約。
6. FOR ALL 開發指引中的程式碼範例，THE Component_Registry SHALL 保證範例能通過 Requirement 2 定義的沙盒驗收流程（指引本身是可執行的 ground truth）。

---

### Requirement 12：KBDB Component Registry 整合

**User Story:** As a 系統開發者, I want Component Registry 完全以 KBDB 的 Template/Block/Slot 機制實作, so that 零件狀態與平台其他知識共享同一個持久化層，不引入新的資料庫。

#### Acceptance Criteria

1. THE Component_Registry SHALL 以 KBDB 的 `tpl-component` Template 儲存零件合約，每個零件版本對應一個 Block，Block 的 slots 對應合約的各欄位（id、version、wasi_target、stability、runtime_compat、constraints 等）。
2. THE Component_Registry SHALL 以 KBDB 的 Vectorize 索引零件的 `description` 與 `tags` 欄位，支援語意搜尋（如「查詢 Google Sheets 資料」能找到 `gsheets_get_entries`）。
3. WHEN Component_Dispatcher 搜尋零件時，THE Component_Registry SHALL 回傳按「成功率 × 速度評分 × 被調用次數」排序的版本清單，最多回傳 10 個候選版本。
4. THE Component_Registry SHALL 透過 KBDB 的 HTTP API 存取所有資料，不直接操作 D1 SQL，符合平台的 API-First 通訊鐵律。
5. FOR ALL Component_Registry 的讀取操作，THE Component_Registry SHALL 保證在 KBDB 資料不變的情況下，對相同查詢參數回傳相同結果（查詢冪等性）。