fix(mcp): 解掉三個把人推去寫零件的誤導入口(leo 2026-07-21 拍板)
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>
This commit is contained in:
@@ -0,0 +1,88 @@
|
||||
# 想貢獻零件(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 的慾望。**絕不可迷路、搞不懂。**
|
||||
Reference in New Issue
Block a user