# Skill: INDEX（Arcrun 導航：什麼問題查哪裡）

> **這支的定位＝LLM wiki 的 `INDEX.md`**（leo 2026-07-30 點破：
> 「整個 arcrun instruction 很像 LLM wiki…它會拿到一個 index 把所有文件說明都塞給它，
> 它不會就可以查，範本全部寫在裡面」）。
>
> **push vs pull**（照 wiki 的分法）：
> - **push**＝MCP 連線時的 `instructions`（AI 一定看到，不看就出事的三句）
> - **pull**＝本檔。AI 卡住時 `arcrun_get_skill('INDEX')` 拿到全館導航

---

## 一、我現在該查哪個？（照症狀找）

| 你的處境 | 用這個 | 工具 |
|---|---|---|
| **要開始寫 workflow，但不知道有什麼零件** | `write_intent_workflow` | `arcrun_get_skill('write_intent_workflow')` |
| 想「每 X 分鐘掃 Y，找到就處理」 | `build_watcher_workflow` | `arcrun_get_skill('build_watcher_workflow')` |
| 要做檢索問答（RAG） | `rag_with_arcrun` | `arcrun_get_skill('rag_with_arcrun')` |
| workflow 卡住不動／paused | `debug_paused_workflow` | `arcrun_get_skill('debug_paused_workflow')` |
| 想把 http 呼叫改成觸發別的 workflow | `migrate_http_to_trigger_workflow` | 同上 |
| **缺某個外部 API 的 recipe**（查詢回 not_found 指 recipe 路）| `write_recipe` | `arcrun_get_skill('write_recipe')` |
| **真的需要新零件**（罕見）| `add_new_wasm_component` | 同上 ⚠️ 先確認工作流做不到 |

## 二、我要查「有沒有現成的東西」

| 找什麼 | 工具 | 注意 |
|---|---|---|
| 有哪些**零件** | `arcrun_list_components()` / `arcrun_search_components('自然語言')` | 零件＝能力（`http_request`／`code`／`if_control`…）|
| 有哪些 **recipe** | `arcrun_recipe_list()` / `arcrun_recipe_search('...')` | recipe＝打某個 API 的配方（`telegram_send`／`kbdb_get`…）|
| 有哪些**跑過的 workflow** | `arcrun_list_workflows()` / `arcrun_search_workflows('...')` | **這些是最可靠的範本**（實跑過）|
| 某個 workflow 的完整定義 | `arcrun_get_workflow(name)` | 拿來照抄結構 |
| 執行紀錄／為什麼失敗 | `arcrun_list_recent_executions()` / `arcrun_get_execution_trace(id)` | |

⚠️ **零件 vs recipe 分不清會寫錯**：
`telegram_send`／`gmail`／`kbdb_get` 是 **recipe 不是零件**。
它們要寫成 `http_request` ＋ 該 recipe。

## 三、已知的坑（不看會踩）

| 坑 | 現況 | 怎麼避 |
|---|---|---|
| **`/cypher/search` 曾回假 `found`** | 2026-07-31 已修：兩庫（零件＋recipe）都查，缺件回 `not_found`＋`suggestion` 指路。舊實例（未更新部署）仍是假 found | 拿到 `not_found` 照 `suggestion` 走；拿到 `unknown`＝查不到 registry ≠ 不存在 |
| ~~引擎沒有條件分支~~ **已解（2026-08-01）** | 引擎支援 `ON_TRUE`／`ON_FALSE`／`ON_BRANCH`；`if_control`／`switch`／`try_catch` 都輸出 `data.branch` 標籤，引擎依標籤選路（Arcrun#5 根治）| **需要判斷就用分支邊，別寫 code 判斷**。查零件的回應附 `branch_hint`（邊型＋可照抄範例），照著接 |
| **`registry/examples/` 8/13 是壞的** | 引用不存在的零件（把 recipe 當零件寫）| **別照抄 examples**，改用 `arcrun_get_workflow` 拿實跑過的 |
| **registry 可能是空的** | 安裝器無註冊步驟 ⇒ 新實例查不到零件 | 查不到 ≠ 不存在，別據此改寫成 code |

## 四、最重要的一條紅線

🔴 **查不到零件就改寫成 `code` 節點＝「腹語術」**（表面用 Arcrun、實際全寫 JS）。

- 缺 API → **寫 recipe**（`arcrun_recipe_push`）
- 缺能力 → **投稿零件 PR**（要人類確認，見 `add_new_wasm_component`）
- `code` 只用於**局部整形**（例：剝掉 LLM 回應的雜訊、切段落）

> 實錄：2026-07-30 盤點發現正式 workflow 只用 2 個零件，8 個 code 節點含 if×61 for×23，
> 最大一個 5509 字元——**每一個 if 都是沒被測過的新 bug**。
> 零件的價值是「被測過 1000 次」，寫進 code 就歸零。

## 五、還是不會？

- `arcrun_list_skills()` — 看全部 skill
- `arcrun_get_gui_context()` — 看目前實例的狀態
- `arcrun_report_feedback()` — **回報這裡沒寫清楚的地方**（這份 INDEX 該被你的問題改進）