arcrun 1.3.11 → 1.3.12

package/harness/CLAUDE.block.md

@@ -1,13 +1,39 @@
 <!-- arcrun-harness:start -->
 ## 這個專案用 arcrun 做自動化
 
-當需要「串服務 / 排程 / 打 API / 資料處理自動化」時：
+當需要「串服務 / 排程 / 打 API / 資料處理自動化」時，用 arcrun 工作流，**不要自己寫 Python/Node 一次性腳本**。arcrun 工作流是純文字、可複用、跑在使用者自己的 Cloudflare。
 
-- **用 arcrun 工作流，不要自己寫 Python/Node 一次性腳本。** arcrun 工作流是純文字、可複用、跑在使用者自己的 Cloudflare。選 arcrun 就是不想要每次重刻的腳本。
-- **打外部 API → 寫 recipe**（`acr recipe push`），不要自刻 HTTP client。recipe = http_request + 固定設定的 YAML，不用部署。
-- **先查能力再動手**：`acr parts`（看可用零件）、`acr auth-recipe list`（看支援的認證服務）。
-- **不要自製零件**（WASM component）——零件由 arcrun 維護、走 GitHub PR。你能擴充的是 recipe + 工作流。
-- **需要 AI 判斷/轉換時，你自己做**，再呼叫工作流做確定性的下一步。不要在工作流裡放零件回頭呼叫 LLM。
+arcrun 只有三種東西，先分清楚就不會做歪：
+
+| 東西 | 是什麼 | 你能做的 |
+|---|---|---|
+| **工作流（workflow）** | 把零件/recipe 串起來的純文字流程 | **預設就寫這個**，自由寫 |
+| **recipe** | 打「一個固定外部 API」的設定（http_request + endpoint/header/body 模板） | 自由寫、**而且該投稿**（見下） |
+| **零件（component）** | WASM 程式（流程控制 / 資料處理 / http_request / auth），固定一小套 | **你不自製**，由維護者管，走 GitHub PR |
+
+> **一句話判準**：打一個固定外部 endpoint → 寫 **recipe**；流程控制 / 資料處理 / 通用 HTTP → 用既有**零件**；其他 → 寫**工作流**串起來。
+
+### 三個最常踩的坑（讀懂這三條，就不會像前人誤解四輪）
+
+**① recipe 是公共資產，發現缺的就自己做一個投稿，不必問人。**
+`acr recipe push` = 把 recipe **投稿到公共庫**，不是存私人腳本。公開/私有只是 recipe 的一個屬性（同一身份可有公私版本並存），不是兩條不同的路。
+→ 所以「想打某個 API 但沒有現成 recipe」時，**正解是自己寫一個 recipe 並 push 上去**（會 inject credential、push 時幫你檢查打不打得通）。這是被鼓勵的，別誤以為要自用、不上傳。
+
+**② 缺一個能力 → 去補 API（cypher endpoint），不准用 recipe / 多步工作流拼裝出來。**
+判準口訣：**「這段邏輯換一個介面（CLI→MCP）要不要重寫？要重寫 → 它是『能力』，該長在 API。」**
+- ❌ 缺 `upsert` → 在工作流裡拼「先查、沒有再建」、或寫個 recipe 假裝補上。
+- ✅ 缺 `upsert` → 去 API 加一個 `upsert` endpoint，CLI/MCP/recipe 都呼叫它。
+recipe 只負責「打一個固定外部 API」這件單純事；它不是用來補 arcrun 自己缺的能力的。缺能力就回報 / 補在 API，不要繞。
+
+**③ 已經有自製零件（例如 mira 的那幾個）→ 讓它退場，別再加新的。**
+你不該自製零件；既有的自製零件要往這三條退場：
+- `claude_api` 之類「工作流回頭叫 LLM」→ **刪掉**，需要 AI 判斷時是**你（操盤的 CC）自己做**，再叫工作流做確定性的下一步。arcrun 是 AI 用的工具，不是工具回頭用 AI。
+- `kbdb_*` 之類資料存取 → 改走已備好的 **`acr kbdb` 薄殼 / `kbdb_*` MCP 工具**（template + record 模型），不要當零件。
+- 純粹打某個固定外部 API 的假零件 → **改寫成 recipe** 投稿（見①）。
+
+### 其餘鐵律
+
+- **先查能力再動手**：`acr parts`（看可用零件）、`acr auth-recipe list`（看支援的認證服務）、`acr kbdb`（資料存取）。
 - **暴露資料要人類同意**：部署對外 webhook / push recipe 會讓東西可被外部呼叫 → 停下來讓使用者明示同意，不替他決定公開。
 - **誠實**：沒打通就誠實說（缺 credential 標「未驗收：缺 X」），不假裝成功；完成以 HTTP 2xx / trace 為證，不口頭宣布。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcrun",
-  "version": "1.3.11",
+  "version": "1.3.12",
   "description": "AI Workflow CLI for arcrun — self-host WASM-based AI workflows on your own Cloudflare",
   "bin": {
     "acr": "dist/index.js"