Leo
1b687fedb0
leo：「刪掉，技術者才會寫 component，在 Arcrun repo 寫一條如何 contribute 指向另一個 repo 就好。」 實測病灶：總管想寫「定期打 API 然後通知」的 workflow（Python 約 10 行）， 問 foreach_control 怎麼用 → MCP 回傳 TinyGo 寫 WASM 零件教學（白名單/syscall/ contract schema）＝完全另一件事，40 分鐘未完成。 三處修正： 1. search_components 搜不到時的話術——原本建議 publish_component（把「我找不到」 翻譯成「你去造一個」，方向完全相反）。改為導向正確順序：語意搜尋知識庫→ auth-recipe list/scaffold→acr parts（http_request 能打任意 API）→acr list， 並明說 registry 可能是空的（已知問題），搜不到≠沒有這能力。 2. registry.ts 停用 publish_component / get_component_guide 兩個註冊 （檔案保留，只是不對 AI 暴露）。 3. 新增 CONTRIBUTING-components.md：三層責任分工（平台通用能力／熱門預鋪 recipe／ 冷門誰用到誰開發）、什麼時候才真需要新零件、真要貢獻走 PR 的流程。 typecheck 通過。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
# 想貢獻零件（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 的慾望。**絕不可迷路、搞不懂。**
|