50 lines
3.5 KiB
Markdown
50 lines
3.5 KiB
Markdown
# 零件 / binding PR 審核規範
|
||
|
||
> **為什麼有這份**：靠「AI 記住規則」防架構錯誤不 scale（規定說幾次都沒用）。零件與 service binding 本來就**要走 PR**——所以把錯誤擋在 **PR 審核這道結構性閘**，讓錯誤路徑「根本碰不到」，不靠自覺。
|
||
> **適用**：任何「新增/改一個 component」或「改 worker binding（`[[services]]` 等）」或「新增 workflow/部署到 cypher」的 PR。
|
||
> **審核者**：先由 reviewer（AI subagent 戴 reviewer 人格）逐條過；未過不得 merge/deploy。逐步補機械化 CI（見文末）。
|
||
|
||
---
|
||
|
||
## Checklist（逐條，任一「否」→ 打回）
|
||
|
||
### A. 這東西該不該存在（反過度工程，D27）
|
||
- [ ] **新增命名零件？** 只准當它是「**常用、多人/多 workflow 會用的可複用原語**」（如 http_request/cron）。
|
||
- 一次性 / 專案專用邏輯 → **打回**，改用通用 **`code` 零件**內聯。
|
||
- 判準：**三個月後會有第二個 workflow 用它嗎？** 不會＝不是零件。
|
||
- 反例：`km_wiki_card_parse`（card→envelope 一次性解析）被否。
|
||
|
||
### B. binding 層級對不對（D28，最常踩）
|
||
- [ ] **用了 Service Bindings（`[[services]]` / `env.SVC.fetch()`）？**
|
||
- 只准**唯一例外**：把**幾個 wasm 綁成「一個複合零件」**（零件等級的組合）。
|
||
- **跨-worker 編排**（workflow 串多個 worker/零件，如 ingest 串 code+kbdb+graph）→ **打回**，走 **cypher binding＝跑成 cypher 上的 workflow**。
|
||
- 判準：這是「**零件內部組 wasm**」還是「**工作流編排多 worker**」？後者一律 cypher binding。
|
||
- 反例：ingest drainer 自建 standalone worker + service binding 串 code/kbdb/graph＝錯位，被否。
|
||
|
||
### C. 零件 contract 合規
|
||
- [ ] stdin JSON → stdout JSON；`no_network`/`no_filesystem`（除非明確申報且審核放行）；資源限制（timeout/mem/輸出/code 上限）；錯誤**結構化回傳**（不讓 Worker 掛）。
|
||
|
||
### D. 驗證誠實（測試≠執行路徑）
|
||
- [ ] 驗證打的是**部署後的真端點**，不是只 `wrangler dev`/miniflare 本地（本地不強制 worker-to-worker 等生產限制，會假綠）。**禁假綠。**
|
||
- 反例：drainer 本地 miniflare 綠、production 撞 1042。
|
||
|
||
### E. 部署 / 資料鐵律
|
||
- [ ] 部署 **wrangler 直推**、**不用 `acr update`**（部署源綁 GitHub codeload，會假綠蓋改動）。
|
||
- [ ] account 正確（self-hosted＝leo21c；別讓 repo `.env` 的官方帳號 id 污染）。
|
||
- [ ] 碰 KBDB＝**零建表、全走 base API、零 SQL**（插件層）。
|
||
|
||
### F. 走 PR（結構性，不繞道）
|
||
- [ ] component/binding/workflow 變更**走 PR ＋ 本規範審核 ＋ merge 才 deploy**，不 ad-hoc 從 branch 直接 wrangler deploy 上 production。
|
||
|
||
---
|
||
|
||
## 機械化補強（讓它「根本碰不到」，待實作）
|
||
逐步把可機械判的移到 CI，PR 命中即 fail，不等人審：
|
||
- lint `wrangler.toml` 出現 `[[services]]` → 標記需 B 條人工放行理由（wasm-composite 例外）。
|
||
- 偵測新增 `registry/components/<name>/` 目錄 → 要求 A 條「可複用原語」論證。
|
||
- 偵測 KBDB migration/`CREATE TABLE` → 直接 fail（鐵律）。
|
||
- 偵測 `acr update` 於部署腳本 → 警告。
|
||
|
||
## 對應決策
|
||
D27（一次性用 code 零件不鑄 domain 零件）、D28（跨-worker 走 cypher binding 不走 service binding）、KBDB 鐵律（D6）、測試≠執行路徑（mistakes）。
|