Leo/Arcrun
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
268cca9865327a36c3dacd09f9155b3cf98426ec
Arcrun/.agents/specs/arcrun-platform-evolution/requirements.md
T
Leo 180cef26c7 docs: rename SDD folders u6u-* → arcrun-* + update cross-refs 
對應 SDD arcrun/.agents/specs/llm-interface/ M5.6（之前列為 backlog 連動）。
leo 2026-05-16 拍板 u6u 整體退場後，順手把兩個 SDD 也改名。

- .agents/specs/u6u-core-mvp/ → arcrun-core-mvp/
- .agents/specs/u6u-platform-evolution/ → arcrun-platform-evolution/
- CLAUDE.md / .claude/rules/00-sdd-protocol.md / 04-current-progress.md /
  llm-interface SDD 內所有跨 SDD 引用同步更新

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-16 15:24:22 +08:00

22 KiB
Raw Blame History

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 資料不變的情況下，對相同查詢參數回傳相同結果（查詢冪等性）。
Reference in New Issue View Git Blame Copy Permalink