Arcrun/mcp/CONTRIBUTING-components.md

貢獻新零件（WASM Component Authoring）

這份文件寫給貢獻者——想開發並投稿新零件到 Arcrun 零件庫的人。 只想「把 MCP 裝來用」的用戶請回 README.md。

零件是 Arcrun 的最小執行單元，以 TinyGo 編譯為 .wasm，透過 stdin/stdout JSON 通訊，可在 Cloudflare Workers（Tier 1/2）和 Wazero 邊緣環境（Tier 3）執行。提交後 Registry 會自動跑沙盒驗收（體積、syscall 掃描、Gherkin 測試）。

---

步驟一：取得開發指引（必做）

arcrun_get_component_guide

指引包含：TinyGo 白名單 import、禁止行為、component.contract.yaml 完整範例、本地測試指令。開發前務必先呼叫，白名單與禁止行為以指引回傳為準。

步驟二：搜尋現有零件（別重造輪子）

arcrun_search_components("查詢 Google Sheets 資料")

若已有符合的零件，直接使用，不需要重新開發。

步驟三：開發零件（若缺件）

依指引用 TinyGo 撰寫零件，只使用白名單 import：

import (
    "os"
    "io"
    "encoding/json"
)

編譯：

tinygo build -o my_component.wasm -target=wasi .

本地測試：

echo '{"input_field":"value"}' | wasmtime my_component.wasm

步驟四：提交零件

arcrun_publish_component(
  contract={...},    // component.contract.yaml 內容（合約物件）
  wasm_base64="..."  // base64(my_component.wasm)
)

Registry 自動執行沙盒驗收（體積、syscall 掃描、Gherkin 測試）。驗收通過才會進零件庫。

---

驗收與審查標準

arcrun_publish_component 的沙盒驗收會檢查：

• 體積上限：超過限制拒收。
• syscall 掃描：只允許白名單 import；踩到禁止行為（網路直連、檔案系統逃逸等）拒收。
• Gherkin 測試：合約裡的 gherkin_tests 必須全綠。

投稿前請自行用步驟三的本地測試把 Gherkin 情境跑過一遍，減少來回。