# 貢獻新零件（WASM Component Authoring）

> 這份文件寫給**貢獻者**——想開發並投稿新零件到 Arcrun 零件庫的人。
> 只想「把 MCP 裝來用」的用戶請回 **[README.md](./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：

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

編譯：

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

本地測試：

```bash
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 情境跑過一遍，減少來回。