diff --git a/cli/harness/CLAUDE.block.md b/cli/harness/CLAUDE.block.md index f12f7c0..cc2d081 100644 --- a/cli/harness/CLAUDE.block.md +++ b/cli/harness/CLAUDE.block.md @@ -17,9 +17,8 @@ fetch_rows >> 對每個 row >> notify ``` - 第一個節點固定是 `input`（觸發時帶進來的資料） -- **邊只有兩種**：`ON_SUCCESS` 與 `對每個 <變數>`（FOREACH） -- **沒有** `ON_TRUE`／`ON_FALSE`／`ON_FAILURE`——引擎不支援條件分支。 - 需要判斷就寫成一個獨立節點再接 `ON_SUCCESS`。 +- **邊有這些**：`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。 diff --git a/cli/harness/commands/arcrun.md b/cli/harness/commands/arcrun.md index 7bd39b3..dce1200 100644 --- a/cli/harness/commands/arcrun.md +++ b/cli/harness/commands/arcrun.md @@ -22,8 +22,8 @@ fetch_rows >> 對每個 row >> notify ``` - 第一個節點固定是 `input` -- 邊只有 `ON_SUCCESS` 與 `對每個 <變數>`（**沒有** `ON_TRUE`／`ON_FALSE`／`ON_FAILURE`） -- 需要判斷 → 寫成獨立節點（例 `check_amount`）再接 `ON_SUCCESS` +- 邊有 `ON_SUCCESS`、`對每個 <變數>`（FOREACH）、`ON_TRUE`／`ON_FALSE`（配 `if_control`）、`ON_BRANCH`＋`branch:`（配 `switch`／`try_catch`）；**沒有** `ON_FAILURE` +- 需要判斷 → 用條件邊（`if_control` 配 `ON_TRUE`／`ON_FALSE`），不要寫 code 判斷 語法細節、四份實跑過的範本、節點命名慣例 → **arcrun-mindset** Skill。 diff --git a/cli/harness/hooks/arcrun-guard.sh b/cli/harness/hooks/arcrun-guard.sh index 5831f90..dfdd9a7 100644 --- a/cli/harness/hooks/arcrun-guard.sh +++ b/cli/harness/hooks/arcrun-guard.sh @@ -96,7 +96,7 @@ if [ "$TOOL" = "Write" ] || [ "$TOOL" = "Edit" ] || [ "$TOOL" = "MultiEdit" ]; t # 只在 code 內容看起來在做流程控制/取代零件時提醒（含 if/for/fetch），單純整形不吵 if echo "$CONTENT" | grep -qE '\b(if[[:space:]]*\(|for[[:space:]]*\(|fetch\(|await[[:space:]]+fetch)'; then remind "workflow 裡的 \`code\` 節點含流程控制/HTTP 呼叫——這可能是「腹語術」（表面用 Arcrun、實際全寫 JS）。" \ - "\`code\` 只用於局部整形（例：剝掉 LLM 回應的雜訊、切段落）。缺外部 API → 寫 recipe（\`acr recipe push\`）；缺計算能力 → 投稿零件 PR；要判斷 → 寫成獨立節點接 \`ON_SUCCESS\`（引擎沒有條件邊）。每個寫進 code 的 if 都是沒被測過的新 bug。見 arcrun-mindset Skill。" + "\`code\` 只用於局部整形（例：剝掉 LLM 回應的雜訊、切段落）。缺外部 API → 寫 recipe（\`acr recipe push\`）；缺計算能力 → 投稿零件 PR；要判斷 → 用條件邊（\`if_control\` 配 \`ON_TRUE\`／\`ON_FALSE\`，或 \`switch\`／\`try_catch\` 配 \`ON_BRANCH\`），不要寫 code 判斷。每個寫進 code 的 if 都是沒被測過的新 bug。見 arcrun-mindset Skill。" fi fi fi diff --git a/cli/harness/skills/arcrun-mindset/SKILL.md b/cli/harness/skills/arcrun-mindset/SKILL.md index 4fcc5d8..e212895 100644 --- a/cli/harness/skills/arcrun-mindset/SKILL.md +++ b/cli/harness/skills/arcrun-mindset/SKILL.md @@ -54,17 +54,55 @@ description: >- - **節點**＝一個步驟。用你想得到的名字（中文可以），**不必是真實零件名** - **邊**＝什麼情況下往下走 -## 2. 邊只有兩種（真範本裡出現過的） +## 2. 邊有這些 | 邊 | 意思 | 真例 | |---|---|---| | `ON_SUCCESS` | 上一步成功就往下 | `input >> ON_SUCCESS >> prep` | | `對每個 <變數>` | 上一步產出清單，逐項處理（FOREACH）| `parse_card >> 對每個 block >> post_block` | +| `ON_TRUE` / `ON_FALSE` | 條件成立／不成立各走一條（配 `if_control`）| `判斷有沒有新資料 >> ON_TRUE >> 傳到 telegram` | +| `ON_BRANCH`＋`branch:` | 依標籤選路（配 `switch` 每個 case、`try_catch` 的 try/catch）| `my_switch >> ON_BRANCH(branch_active) >> 處理啟用` | -⚠️ **不要寫 `ON_FAILURE`／`ON_TRUE`／`ON_FALSE`**——引擎目前**沒有條件分支** -（實測 `grep ON_TRUE|ON_FALSE` 於 cypher-executor = 0；見 Gitea Arcrun#5）。 -需要判斷時：**寫成一個獨立節點**（例 `check_amount`）再接 `ON_SUCCESS`， -讓查詢告訴你有沒有零件可用。 +### 2.1 條件分支怎麼寫（2026-08-01 起引擎支援） + +**需要判斷時，用分支邊，不要寫 `code` 判斷。** +三顆流程控制零件都輸出 `data.branch` 標籤，引擎依標籤選路： + +| 零件 | 輸出的標籤 | 接法 | +|---|---|---| +| `if_control` | `"true"` / `"false"` | `ON_TRUE`／`ON_FALSE` 各一條 | +| `switch` | 你在 `cases[].branch` 取的名字（沒中則 `default_branch`）| 每條路一條 `ON_BRANCH`，邊上標 `branch` | +| `try_catch` | `"try"`（沒錯）／`"catch"`（有錯）| 兩條 `ON_BRANCH`，標 `try` 與 `catch` | + +``` +判斷有沒有新資料 >> ON_TRUE >> 傳到 telegram +判斷有沒有新資料 >> ON_FALSE >> 結束 +``` +中文語意詞亦可：「成立時」＝`ON_TRUE`、「否則」＝`ON_FALSE`。 + +💡 **不必背**：查零件時回應會附 `branch_hint`（有哪些標籤、用哪些邊型、可照抄的範例）， +照著接就對了。 + +⚠️ 仍然**不要寫 `ON_FAILURE`**（沒有這種邊；要處理失敗用 `try_catch` ＋ `ON_BRANCH(catch)`）。 + +### 2.2 怎麼確認分支真的走對了（**別看不懂就以為壞掉**） + +分支工作流「有沒有成功」看兩件事，**不是看某條沒走的路沒有輸出**： + +1. **`verdict`**：`GET /workflows//executions?limit=1` + → `data.executions[0].verdict === "success"` 就是成功了。 +2. **`trace` 裡有沒有出現該走的節點**：走 TRUE 路時 FALSE 路的節點**本來就不該出現** + ——**那是正確行為，不是失敗**。 + +``` +# 條件成立 → 只有 true 那條的節點在 trace +{"amount": 5000} → if_control 回 branch="true" → 走 ON_TRUE 那條 +{"amount": 100} → if_control 回 branch="false" → 走 ON_FALSE 那條 +``` + +🔴 **實撞（2026-08-01 考試）**：有考生的分支工作流**其實完全正常** +（`amount=5000`→true、`amount=100`→false 都對），但它以為「跑不通」而放棄改寫成 code。 +**看到只有一條路有輸出＝分支正在正確運作**，不要因此判定失敗。 ## 3. 第一個節點固定是 `input` @@ -157,7 +195,9 @@ curl -s -X POST https://arcrun-cypher-executor..workers.dev/cypher/se ## 7. 常犯的錯 -1. **用不存在的邊**（`ON_FAILURE`／`ON_TRUE`）→ 只有 `ON_SUCCESS` 與 `對每個 X` +1. **用不存在的邊**（`ON_FAILURE`）→ 沒有這種邊；要處理失敗用 `try_catch` ＋ `ON_BRANCH(catch)` + ⚠️ `ON_TRUE`／`ON_FALSE`／`ON_BRANCH` **是存在的**（2026-08-01 起），見 §2.1—— + 本行以前寫「ON_TRUE 不存在」是舊世代，已更正 2. **第一個節點不是 `input`** 3. **把 recipe 當零件寫**——`telegram_send`／`gmail`／`kbdb_get` 是 **recipe** 不是零件 → 寫成 `http_request` ＋ 該 recipe diff --git a/cli/scripts/check-harness-generation.mjs b/cli/scripts/check-harness-generation.mjs index 334d068..09c1bba 100644 --- a/cli/scripts/check-harness-generation.mjs +++ b/cli/scripts/check-harness-generation.mjs @@ -31,11 +31,17 @@ const CHECKS = [ ['not_found', '現世代查詢狀態（舊版寫 missing／假 found）'], ['腹語術', '缺件不准改寫成 code 的紅線'], ['recipe', '零件 vs recipe 分型'], + // 條件邊自 2026-08-01 起引擎已支援（cypher-executor/src/graph-executor.ts + // case 'ON_TRUE'/'ON_FALSE'/'ON_BRANCH'，31 個測試全過）。教材該教會怎麼用， + // 不是教「不存在」——這條 must 同時防「哪天又被改回舊世代說法」的回歸。 + ['ON_TRUE', '條件邊（配 if_control）自 2026-08-01 起引擎已支援，教材須教會用法'], ], mustNot: [ - // ON_TRUE 只准出現在「教它不存在」的脈絡（否定詞／實測證據）。 - // 若哪天它出現在範本裡（正面示範），就是教材寫錯，該擋。 - ['ON_TRUE', '引擎沒有條件邊，教材不該把它當可用的邊', /不要寫|不存在|沒有條件|❌|非法|grep|= 0/], + // ON_FAILURE 才是真的不存在（VALID_EDGE_TYPES 只有 ON_FAIL，見 + // cypher-executor/src/lib/constants.ts）。只准出現在「教它不存在」的脈絡。 + // 2026-08-10 修正：這道閘原本擋的是 ON_TRUE——但 ON_TRUE/ON_FALSE/ON_BRANCH + // 已是引擎現世代能力，正確教材反而被這道閘擋下，是閘的判準過時了，不是教材寫錯。 + ['ON_FAILURE', '引擎沒有這種邊（只有 ON_FAIL）；教材不該把它教成可用的邊', /不要寫|不存在|沒有這種|❌|非法/], ], }, {