docs: 零件/binding PR 審核規範——結構性防架構錯誤(不靠記規則):A反過度工程(D27)/B binding層級(D28)/C contract/D驗證誠實/E部署資料鐵律/F走PR+機械化CI補強

2026-07-06 12:40:25 +00:00
parent 6c5706ba7d
commit 1eefce952b
1 changed files with 49 additions and 0 deletions
@@ -0,0 +1,49 @@
+# 零件 / 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）。