# 想貢獻零件（component）？先確認你真的需要

> **99% 的需求不需要新零件。** 零件是**專業等級**、走 PR 審核；
> **recipe / workflow / app 誰都可以做**，隨建隨用、不必部署。

---

## 先照這個順序找，多半不用寫零件

**1. 語意搜尋知識庫**（最強——它能找到你沒猜中的用詞）
```
kbdb_search(q="我想達成什麼（用一句話描述）", mode="semantic")
kbdb_get_map()          # 不確定該查哪個庫，先看藏書地圖
```

**2. 看現成的服務整合**（26 個：GitHub／Notion／Gemini／Slack…）
```bash
acr auth-recipe list
acr auth-recipe scaffold github     # 直接吐出 credentials 範本 ＋ workflow 範例
```

**3. 看零件全集**（21 顆通用零件）
```bash
acr parts
```
特別注意 **`http_request`**：它能打**任意** HTTP API。
「平台沒有 XX 服務的零件」通常不成立——用 `http_request` ＋ 一份 recipe 就有了。

**4. 看有沒有現成 workflow 可以直接接**
```bash
acr list
```

---

## 三層責任分工

| 層 | 誰做 | 怎麼做 |
|---|---|---|
| **通用能力** | 平台提供 | `http_request` ＋ auth-recipe 機制＝**能打任何 API**，這是地基 |
| **熱門服務 recipe** | 平台預鋪 | 減少常見情境的摩擦（現 26 個） |
| **冷門／特殊** | **誰用到誰開發** | recipe 是**設定不是程式**，門檻低 |

> 我們不會包辦全世界所有服務的 API。**用到就自己補一份 recipe**，那是設定檔不是程式碼。

---

## 什麼時候才真的需要新零件

**只有這種情況**：需要**新的原語能力**，而且**無法用既有零件組合出來**。例如——

- 一種新的控制流（現有 `if_control`／`switch`／`foreach_control`／`filter`／`try_catch` 都表達不了）
- 一種新的資料轉換原語（`code` 零件的沙箱做不到）
- 需要 WASM 層才能做的事（純計算、特殊編解碼）

**不算的情況**（這些都用 recipe／workflow 解）：
- 「我要接 XX 服務的 API」→ `http_request` ＋ recipe
- 「我要做 XX 業務邏輯」→ workflow 組合既有零件
- 「我要處理某種資料格式」→ `code` 零件（沙箱 JS）

---

## 真的要貢獻零件的話

零件是 WASM（TinyGo／AssemblyScript），有嚴格的沙箱約束
（禁網路 syscall、禁檔案系統、禁 goroutine、體積上限 2MB、
唯一 I/O 模型是 stdin/stdout JSON）。

**流程**：走 Arcrun repo 的 PR，過 `docs/component-pr-review-standard.md` 審核。
撰寫規範與 contract schema 見 `registry/` 底下的既有零件範例。

---

## 為什麼 MCP 不再暴露 `publish_component` / `get_component_guide`

（2026-07-21 leo 拍板停用）

那兩個工具對一般使用者是**誤導危機**：搜不到東西時，系統會建議「去提交新零件」，
把人推向最難、最該擋的那條路。

**實測**：總管想寫一支「定期打 API 然後通知」的 workflow（Python 約 10 行），
問 `foreach_control` 怎麼用，MCP 回傳的是**TinyGo 寫 WASM 零件的教學**
（白名單、syscall 限制、contract schema）——完全是另一件事，導致 40 分鐘未完成。

**設計判準**（leo）：
> 前端界面要**人類友善**，Arcrun 要 **AI 友善**——都要**從終點看**。
> Arcrun ＝ **讓 AI 輕易建立程式碼**；AI 要覺得 **Arcrun 比 Python 還簡單**，
> 因此沒有寫 Python 的慾望。**絕不可迷路、搞不懂。**