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:
@@ -8,7 +8,102 @@
|
||||
|
||||
## 待裁決
|
||||
|
||||
（無）
|
||||
### P-2026-07-21：registry 寫入端＋搜尋端修復（leo 親自交辦，最高優先）
|
||||
|
||||
> 提案人：總管交辦之 arcrun subagent。
|
||||
> 觸發：leo 2026-07-21 —「一旦推進一個零件，就自動進 registry；recipe、workflow、app 都應該可以 registry，
|
||||
> 不然搜不到。一邊是寫進去，另一邊是搜到，當然要有。」
|
||||
> 判準：「Arcrun ＝ 讓 AI 輕易建立程式碼」「AI 要覺得 Arcrun 比 Python 還簡單，絕不可迷路」。
|
||||
> **依 D35：本任務找不到對應的 active SDD（現行 active＝portal-auth，與本題無關），
|
||||
> 故不動 code、不自建 SDD，寫本 proposal 後停止等 leo confirm。**
|
||||
|
||||
#### 一句話
|
||||
|
||||
registry 的寫入機制**存在且可用**，但它唯一的自動觸發點長在 GitHub Actions 上；
|
||||
Actions 因防 flag 鐵律被整個刪除後（commit `037cf9b`），**寫入端失去觸發者、庫從此是空的**。
|
||||
這不是「沒有機制」，是「機制的手被砍掉、沒補上替代觸發點」。
|
||||
|
||||
#### 根因（file:line 級）
|
||||
|
||||
| 事實 | 證據 |
|
||||
|---|---|
|
||||
| 寫入端點存在 | `registry/src/routes/components.ts:112` `POST /components/index-only`（metadata-only 索引，冪等） |
|
||||
| 寫入實作存在 | `registry/src/actions/indexOnlyComponent.ts:44` 寫 `comp:{hash}:{ver}` + `idx:{canonical_id}` 兩個 KV key |
|
||||
| 批次灌注腳本存在 | `registry/scripts/backfill-index.mjs`（掃 22 個 contract.yaml → POST index-only） |
|
||||
| 單顆註冊腳本存在 | `registry/scripts/register-component.sh`（註解自稱「本地+CI 共用 SSOT」） |
|
||||
| **唯一自動觸發點已不存在** | `git show 037cf9b^:.github/workflows/deploy.yml` 第 269-275 行有 `Register component in registry` step 呼叫上述 sh；`037cf9b` 刪除整個 `.github/workflows/`，**該 step 隨之消失，無替代品** |
|
||||
| 從未跑過的實證 | 對 leo21c 跑 `REGISTRY_URL=... node scripts/backfill-index.mjs --dry-run` → 22 顆待灌；線上 `/components/search?q=http` 回 `count:0` |
|
||||
|
||||
→ **答案：是「有機制但從沒跑過」**（且失去觸發者），不是「沒有寫入機制」。
|
||||
→ 附帶事實：`registry/wrangler.toml:26` 的 `[[routes]]` 寫死 `registry.arcrun.dev`，
|
||||
self-hosted（leo21c）只能靠 workers.dev URL，backfill 腳本預設 `REGISTRY_URL` 也是官方域 —— 需帶環境變數才會打到自己的庫。
|
||||
|
||||
#### 重要更正：leo 要的東西**有一半已經存在，只是不在 registry 上**
|
||||
|
||||
`acr search <term>`（`cli/src/commands/search.ts`）已經是 leo 描述的「意圖驅動、跨類一次搜」——
|
||||
它 fan-out 四個來源（component 靜態清單 / `/recipes` / `/auth-recipes` / `/webhooks/named`）。
|
||||
**實測（2026-07-21，leo21c，真實輸出見交辦回報）**：
|
||||
- `acr search http` → 命中零件 `http_request`（驗收劇本 1 ✅）
|
||||
- `acr search notify` → 命中 recipe `line_notify_send` + auth-recipe `line_notify`（劇本 2 部分達成）
|
||||
- `acr search github` → 命中 auth-recipe `github`（驗收劇本 3 ✅）
|
||||
- `acr search telegram` → 命中 recipe `telegram_send` + auth-recipe `telegram`
|
||||
|
||||
→ **能力在 CLI 有、在 registry/MCP 沒有**。這正是薄殼原則（rule 07）被違反的典型：
|
||||
同一個「跨類搜尋」能力長在介面層（CLI）而非 API，於是另一個薄殼（MCP）享受不到。
|
||||
**修法的方向不是在 registry 重造一套搜尋，而是把 `acr search` 的 fan-out 能力下沉成 API 端點，CLI/MCP 同吃。**
|
||||
|
||||
#### 提案內容（四件，全部需 confirm 後才動）
|
||||
|
||||
**A. 寫入端：補回失去的觸發點（不復活 Actions）**
|
||||
- A1. `acr push` / `acr deploy` 成功後自動呼叫 `POST /components/index-only`（本機發起、低頻、單 repo，守 D20 讀寫界線與防 flag 鐵律）。
|
||||
- A2. `acr init` / `acr update` 部署完 22 顆零件後跑一次 backfill（讓新裝的人開箱即有索引）。
|
||||
- A3. **recipe / workflow 不需要新的 registry 寫入路徑**——它們本來就活在 store（KV），
|
||||
`acr recipe push` / `acr push` 當下就已「寫進去」。缺的只是**搜尋端讀得到**（見 B）。
|
||||
→ leo 說的「recipe、workflow、app 都應該可以 registry」，正解是**統一搜尋面**，不是把它們搬進 registry KV 再存一份（那會製造第二份真相源）。
|
||||
- A4. `app`（bundle）已有 P-2026-07-19 artifact-sharing 卷涵蓋，本卷不重複立案，只在搜尋面預留類別。
|
||||
|
||||
**B. 搜尋端：能力下沉 + 語意**
|
||||
- B1. 在 **cypher-executor** 開 `GET /search?q=`（不是 registry——因為 recipe/workflow 的真相源在 cypher 的 KV），
|
||||
server 端做 `acr search` 現有的四類 fan-out，回統一結果（含 `type` 欄位）。
|
||||
- B2. `acr search` 與 MCP 新 tool `arcrun_search`（或改造 `arcrun_search_components`）雙雙改為呼叫 B1，介面層不再自行 fan-out（回歸薄殼）。
|
||||
- B3. 語意搜尋：KBDB 那條路已驗證可用（Vectorize），把四類的 description 灌進去，讓「我要打一個 HTTP API」這種自然語言句命中 `http_request`。
|
||||
現行 `registry/src/actions/queryComponents.ts:104` 明載「這是 Phase 0 的純文字比對版本，Phase 2 接入 Vectorize」——本項即補完該 Phase 2。
|
||||
- B4. 搜不到時的文案改為「導向 recipe / 既有 workflow」，**移除「可以用 arcrun_publish_component 提交新零件」的建議**（見 C）。
|
||||
|
||||
**C. 斷掉「推人去寫零件」的路**
|
||||
- C1. `mcp/src/tools/arcrun_search_components.ts:50` 搜不到時明文建議 `arcrun_publish_component` —— 違反 leo 既定規矩（零件走 PR、專業等級）。改為導向 recipe/workflow。
|
||||
- C2. `arcrun_get_component_guide`（回 TinyGo 寫 WASM 教學）與 `arcrun_publish_component` 對一般使用者是誤導 → 建議降級為「專業模式」才暴露（預設不掛載），或在描述首句明寫「99% 情況你不需要這個，先用 recipe」。
|
||||
- C3. **查證結果：零件相關「已拆到另一個 repo」未獲證實**——`registry/components/` 22 顆零件仍在本 repo，
|
||||
wiki 與 git 均查無拆分紀錄。leo 的印象可能來自 `.github-public/` 對外鏡像（`GitHub mirror 發佈模型`）。**此點需 leo 確認**。
|
||||
|
||||
**D. 過時項**
|
||||
- D1. MCP 仍要求已廢的 `api_key` 參數者共 **15 處**：`arcrun_introspection.ts`（4）、`arcrun_recipe.ts`（6）、`arcrun_workflow_crud.ts`（5）。
|
||||
2026-07-20 已改 namespace 明碼 → 這些應改為由 server 端 namespace 推導，不再要 AI 傳。
|
||||
- D2. **1042 的真正解法已確認並已落地**（本項無需修 code，只需更正記載）：
|
||||
`global_fetch_strictly_public` compatibility flag，已實裝於 `cypher-executor/wrangler.toml:13`
|
||||
與 `.component-builds/http_request/wrangler.toml:8`。
|
||||
leo 說的「開了一個什麼，把所有呼叫都視為外部」＝**這個 flag**（讓 same-zone fetch 走公網前門）。
|
||||
wiki 已有正確記載：`system-dev/wiki/cards/decisions/same-zone-1042用flag解不用binding.md`、
|
||||
`mistakes.md:101`、`decisions-summary.md:84`。
|
||||
→ 「graph_neighbors 改用 recipe 繞過」的過時說法**在本 repo wiki 查無此記載**（status.md:50-52 只寫 MCP tool PR），
|
||||
該過時記載可能在頂層 InkStoneCo wiki 或 MEMORY.md，需由總管在該層更正。
|
||||
|
||||
#### 影響分析（D35 第 3 條要求）
|
||||
|
||||
- **現行 active SDD（portal-auth）**：完全不受影響，本提案不碰其任務。
|
||||
- **`component-registry-canon`（status: paused，2026-05-07 建）**：**本題其實早有此卷**，
|
||||
其 §1.2 診斷的根因與今日實測完全一致（「registry 活著但 index 空的，AI 找不到零件就會繞回 Python」），
|
||||
尚有 **29 個未完成任務**。→ **建議：不新開 SDD，改為把此卷 resume 成 active**（並把 A/B/C/D 的新項增補進其 tasks），
|
||||
這比另立新卷更符合 D35 第 4 條「先搬移未完成任務」的精神，也避免第二份重疊規格。
|
||||
⚠️ 但這需要先把 portal-auth 收尾或轉 paused（單一活性鐵律），**此為 leo 的排序決策，不是 CC 能裁的**。
|
||||
- **`workflow-discovery`（paused）／`library-map`（draft）**：與 B1 統一搜尋面高度重疊，resume 時應一併檢視是否合併。
|
||||
|
||||
#### 待 leo 拍板的四點
|
||||
|
||||
1. **排序**：要不要把 `portal-auth` 讓位、resume `component-registry-canon` 來做這件事？（單一活性鐵律強制二選一）
|
||||
2. **C2**：`get_component_guide` / `publish_component` 要「預設不掛載」還是「留著但改描述」？（品味/方向）
|
||||
3. **C3**：零件是否真的已拆到另一個 repo？（leo 記憶待證實）
|
||||
4. **B3 語意搜尋**：四類描述灌進 Vectorize 會產生 embedding 呼叫成本，確認可行？（花錢）
|
||||
|
||||
## 已裁決
|
||||
|
||||
|
||||
Reference in New Issue
Block a user