uncle6me-web
ae81d22775
引擎自 2026-08-01 起已支援條件邊（cypher-executor/src/graph-executor.ts case 'ON_TRUE'/'ON_FALSE'/'ON_BRANCH'，VALID_EDGE_TYPES 亦已列入；31 個 cypher-executor 測試全過）。registry/skills/write_intent_workflow.md（單一 真相源）也已在同日更正為教 ON_TRUE/ON_FALSE/ON_BRANCH 是合法邊。 但 cli/scripts/check-harness-generation.mjs 的世代閘還停在舊世代判準： 只要 SKILL.md 出現正面示範的 ON_TRUE 就擋——這道閘本身才是落後的一方， 把已經寫對的教材當錯誤攔下，害乾淨 `npm run build` 必敗。 同源的過時內容還藏在三個手動維護的 harness 原始檔（非腳本產物）： CLAUDE.block.md／commands/arcrun.md／hooks/arcrun-guard.sh 都寫著 「引擎沒有條件邊」「沒有 ON_TRUE/ON_FALSE/ON_FAILURE」，一併更正。 真正不存在的邊是 ON_FAILURE（VALID_EDGE_TYPES 只有 ON_FAIL），把 mustNot 判準從 ON_TRUE 換成 ON_FAILURE，並新增 must 規則要求 ON_TRUE 必須出現， 防止教材日後又被改回「條件邊不存在」的舊世代說法。 skills/arcrun-mindset/SKILL.md 是由 registry 於建置期重建的產物 （build-harness-skill.mjs），本次改動只跑 `npm run build:harness` 重建、不手改。 驗證：故意把 SKILL.md 的 ON_FAILURE 改成正面示範，確認閘仍會擋下 （exit 1），還原後 `npm run build` 連跑兩次皆全綠且冪等（SKILL.md md5 不變）。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
66 lines
4.1 KiB
Markdown
66 lines
4.1 KiB
Markdown
<!-- arcrun-harness:start -->
|
||
## 這個專案用 Arcrun 做自動化
|
||
|
||
當需要「串服務／排程／打 API／資料處理自動化」時，用 Arcrun 工作流，**不要自己寫 Python/Node 一次性腳本**。
|
||
Arcrun 工作流是純文字、可複用、跑在使用者自己的 Cloudflare。
|
||
|
||
⚠️ **不要上網搜 Arcrun 文件**——網路上沒有，找到的都是錯的。
|
||
語法與範本全在 **arcrun-mindset** Skill 裡，`acr` 指令查得到現況。
|
||
|
||
### 怎麼開始：先寫「意圖」，不要先寫 YAML
|
||
|
||
你**不需要先知道有哪些零件**。把需求寫成一串「誰接誰」，丟去查，系統會告訴你哪些存在：
|
||
|
||
```
|
||
input >> ON_SUCCESS >> fetch_rows
|
||
fetch_rows >> 對每個 row >> notify
|
||
```
|
||
|
||
- 第一個節點固定是 `input`（觸發時帶進來的資料）
|
||
- **邊有這些**：`ON_SUCCESS`、`對每個 <變數>`（FOREACH）、`ON_TRUE`／`ON_FALSE`（配 `if_control`）、`ON_BRANCH`＋`branch:`（配 `switch`／`try_catch`）
|
||
- **沒有** `ON_FAILURE`——要處理失敗用 `try_catch` ＋ `ON_BRANCH(catch)`。
|
||
|
||
完整語法、四份實跑過的範本、節點命名慣例 → 讀 **arcrun-mindset** Skill。
|
||
|
||
### Arcrun 只有三種東西，先分清楚就不會做歪
|
||
|
||
| 東西 | 是什麼 | 你能做的 |
|
||
|---|---|---|
|
||
| **工作流（workflow）** | 把零件／recipe 串起來的純文字流程 | **預設就寫這個**，自由寫 |
|
||
| **recipe** | 打「一個固定外部 API」的設定（endpoint／header／body 模板） | 自由寫、**而且該投稿** |
|
||
| **零件（component）** | WASM 程式（流程控制／資料處理／`http_request`／auth），固定一小套 | **你不自製**，走 PR |
|
||
|
||
> **一句話判準**：打一個固定外部 endpoint → 寫 **recipe**；流程控制／資料處理／通用 HTTP → 用既有**零件**；其他 → 寫**工作流**串起來。
|
||
>
|
||
> ⚠️ 常見錯誤：把 `telegram_send`／`gmail_send`／`kbdb_get` 當**零件**寫。它們是 **recipe**。
|
||
|
||
### 查詢回 `not_found` 時：兩條路，都不准改寫成 code
|
||
|
||
查詢會誠實回報（兩庫都查過才點名）：
|
||
|
||
| status | 意思 | 你該做什麼 |
|
||
|---|---|---|
|
||
| `found` / `resolved` | 有現成的可用 | **只填 payload** |
|
||
| `not_found` | 零件庫與 recipe 庫都沒有 | 照回應的 `suggestion` 走（見下兩條路），並看 `similar_components`／`similar_recipes` 有沒有能直接用的 |
|
||
| `unknown` | 查不到 registry（未部署／網路失敗） | **不代表不存在**，別據此改寫成 code |
|
||
|
||
- **缺外部 API** → **自己寫一個 recipe** 並 `acr recipe push`（幾行 YAML，不用部署 Worker、不用寫程式）。
|
||
recipe 是公共資產，發現缺的就補一個投稿，不必問人。
|
||
- **缺計算能力**（加解密／壓縮這類純運算） → 投稿**零件 PR**（要人類確認，罕見）。
|
||
|
||
🔴 **查不到就改寫成 `code` 節點 ＝「腹語術」**（表面用 Arcrun、實際全寫 JS）。
|
||
`code` 只用於**局部整形**（例：剝掉 LLM 回應的雜訊、切段落），不用來取代零件與流程控制。
|
||
> 實錄：每一個寫進 `code` 的 `if` 都是沒被測過的新 bug；零件的價值是「被測過 1000 次」，寫進 code 就歸零。
|
||
|
||
### 其餘鐵律
|
||
|
||
- **先查能力再動手**：`acr search <關鍵字>`（一次掃零件／recipe／auth-recipe／workflow）、
|
||
`acr parts`（零件）、`acr recipe list`（recipe）、`acr auth-recipe list`（支援的認證）。
|
||
- **需要 AI 判斷時你自己做**，不要讓工作流回頭呼叫 LLM。Arcrun 是 AI 用的工具，不是工具回頭用 AI。
|
||
- **金鑰只拿名字**：定義裡只寫 `{{credential.<名字>}}`，真身絕不寫進 workflow／recipe 檔案。
|
||
- **暴露資料要人類同意**：`acr push`／`acr recipe push` 會讓東西可被外部呼叫 → 停下來讓使用者明示同意，不替他決定公開。
|
||
- **誠實**：沒打通就誠實說（缺 credential 標「未驗收：缺 X」），不假裝成功；完成以 HTTP 2xx／trace 為證，不口頭宣布。
|
||
|
||
開始前讀 **arcrun-mindset** Skill（意圖語法＋範本＋世界觀）。使用者技術細節交給你，CLI 操作你來做。
|
||
<!-- arcrun-harness:end -->
|