uncle6me-web
7e87a3336b
📋 SDD：workflow-discovery task 3.8（3.7 的 suggestion 指 skill write_recipe， 之前是空地——指路會指到不存在的 skill）。 - registry/skills/write_recipe.md：從真 code 反推，不是憑空教學—— schema＝routes/recipes.ts RecipeDefinition（canonical_id/endpoint/method/auth_service…）； 真範例＝api-recipe-seeds.ts 的 telegram_send（URL path 注入）＋gmail_send（service account）； auth recipe 必填欄位（required_secrets 的 help_url 必填）照 POST /auth-recipes 驗證邏輯； 常犯錯收錄實錄（sheets append PUT→POST、telegram auth recipe 漏種、金鑰只准名字 D36） - INDEX.md 補 write_recipe 入口；「/cypher/search 假 found」坑改標已修（2026-07-31） - write_intent_workflow.md §6 status 表改 not_found 契約＋suggestion/similar_* 欄說明 安裝器 seed：registry/skills/*.md 由 sync-registry-to-kbdb.py 自動收，新檔即納入。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
65 lines
4.0 KiB
Markdown
65 lines
4.0 KiB
Markdown
# 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 ≠ 不存在 |
|
||
| **引擎沒有條件分支** | `grep ON_TRUE\|ON_FALSE` = 0；`if_control` 只回 boolean | 判斷寫成獨立節點接 `ON_SUCCESS`。見 Gitea Arcrun#5 |
|
||
| **`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 該被你的問題改進）
|