docs(mcp): README 改為安裝+使用導向,零件投稿拆成 CONTRIBUTING-components.md

- README 補三種前端安裝(claude.ai connector / Claude Code / Claude Desktop),
  MCP URL 以源碼為準 = <origin>/mcp(DEFAULT_MCP_URL、resourceUri)。
- 認證段講 OAuth owner secret 閘 + MCP_STATIC_TOKEN 真祕密路徑,明講明碼-namespace 已移除。
- 工具總覽全用 arcrun_* 現役名(#20 rename)+ kbdb_* 資料層。
- 修正舊 README 兩處連結:.mcp.json url 補 /mcp、inspector 改 /mcp/inspector。
- 零件開發/投稿流程搬到 mcp/CONTRIBUTING-components.md,README 末留連結。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Leo
2026-07-07 06:39:04 +00:00
parent b13b4dfe49
commit 0617dab70a
2 changed files with 241 additions and 130 deletions
+71
View File
@@ -0,0 +1,71 @@
# 貢獻新零件(WASM Component Authoring
> 這份文件寫給**貢獻者**——想開發並投稿新零件到 Arcrun 零件庫的人。
> 只想「把 MCP 裝來用」的用戶請回 **[README.md](./README.md)**。
零件是 Arcrun 的最小執行單元,以 **TinyGo** 編譯為 `.wasm`,透過 stdin/stdout JSON 通訊,可在 Cloudflare WorkersTier 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 情境跑過一遍,減少來回。