Arcrun/.agents/specs/u6u-platform-evolution/requirements.md

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 資料不變的情況下，對相同查詢參數回傳相同結果（查詢冪等性）。