docs(registry): seed 10 examples + 5 skills (LI SDD M3.1 + M3.3)

對應 .agents/specs/llm-interface/ Milestone 3.1 + 3.3。

registry/examples/ — 10 個可直接 push 的 workflow 範本:
  starter:    webhook-to-http
  common:     cron-watcher, llm-classify, rag-search-answer, daily-digest
  external:   email-summary (gmail+claude+telegram), pdf-to-blocks,
              github-issue-bot
  advanced:   parallel-fanout (trigger_workflow fan-out),
              error-retry (try_catch+wait pattern)

  每個含:workflow.yaml(可直接 push)+ description.md(解決什麼問題 /
  改成你自己的 / 學到什麼)+ tags.json(搜尋用)

registry/skills/ — 5 個 AI playbook(markdown):
  build_watcher_workflow            — cron + filter + trigger 模式
  debug_paused_workflow             — claude_api callback paused 怎麼追
  migrate_http_to_trigger_workflow  — 從 self-fetch 換 trigger_workflow
  rag_with_arcrun                   — KBDB + claude_api 組裝 RAG
  add_new_wasm_component            — TinyGo 寫 + 部署全流程

兩者差異:
  examples = 可直接拿來改的 YAML
  skills = 面對 X 問題該怎麼想 + 該用哪個 example

兩者後續:CI 自動同步進 KBDB(type=workflow-example / type=agent-skill),
MCP arcrun_search_examples / arcrun_list_skills 走 KBDB semantic search。
(CI sync 是 M3.4 工作)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-05-16 16:33:54 +08:00
parent 989fbeb9ac
commit 388c193ae7
37 changed files with 1324 additions and 0 deletions
@@ -0,0 +1,90 @@
# Skill: Migrate http_request → trigger_workflow
## 何時用這個 skill
你看到既有 workflow YAML 內有:
```yaml
some_node:
component: http_request
url: "https://cypher.arcrun.dev/webhooks/named/another_workflow/trigger"
# 或
url: "https://arcrun-cypher-executor.uncle6-me.workers.dev/webhooks/named/X/trigger"
```
這是 **錯誤 pattern** — CF Workers self-fetch 防護會擋掉,回 1042 / 522。
**永遠改用 `trigger_workflow` 內建零件**
## 為什麼會擋
Cloudflare Workers 有反同 zone 自循環防護:
- 同 zone`*.arcrun.dev`Worker 互打容易死鎖
- workers.dev 也擋(Worker → 自身 URL
歷史背景:mira_feed_watcher 之前用 http_request 自打,怎麼設都失敗,最終加 `trigger_workflow` 內建零件繞掉(commit b8ecef0, 2026-05-16)。
## 怎麼遷移(3 行改動)
### Before
```yaml
trigger_synthesis:
component: http_request
url: "https://arcrun-cypher-executor.uncle6-me.workers.dev/webhooks/named/wiki_synthesis/trigger"
method: POST
headers:
X-Arcrun-API-Key: "{{api_key}}"
Content-Type: "application/json"
body_json:
api_key: "{{api_key}}"
raw_block_id: "{{item.id}}"
```
### After
```yaml
trigger_synthesis:
component: trigger_workflow
workflow_name: "wiki_synthesis"
api_key: "{{api_key}}"
input:
api_key: "{{api_key}}"
raw_block_id: "{{item.id}}"
```
key 對應:
- `url` → 拆 `workflow_name`
- `headers.X-Arcrun-API-Key``api_key`
- `body_json``input`
- method / Content-Type → 不需要(in-process call
## 行為差異
| 維度 | http_request 自打 | trigger_workflow |
|---|---|---|
| 走的路徑 | 外部 HTTP(被擋) | in-process call executeWebhookGraph |
| latency | 一次 round-trip 50-200ms | < 1ms |
| paused 狀態回報 | http 收 5xx 視為失敗 | status='paused_awaiting_resume' 算成功 |
| auth 注入 | 手寫 header | 自動 |
| 跨 zone | 會撞 self-fetch | 完全繞掉 |
| 計量 | 算外部 fetch quota | 算同 Worker CPU |
## 例外:什麼時候真的需要 http_request
`trigger_workflow` 只能觸發**同一 arcrun 帳號**的 workflow(同 api_key namespace)。
跨帳號 / 跨環境 / 觸發其他平台需要 http_request
- 觸發另一個 arcrun 用戶的 webhook(少見場景)
- 觸發外部 APIzapier / n8n / 自家別的 service
- 跨 Cloudflare account 的 worker
這些**不會** self-fetch 問題(因為目的地不是自己 Worker),http_request 仍適用。
## 部署前驗證
```
arcrun_validate_yaml(yaml)
arcrun_push_workflow(yaml)
arcrun_run_workflow(your_watcher_name, {...})
arcrun_list_recent_executions(workflow_name='your_watcher_name')
```
確認 verdict='success' 且 duration_ms < 500mstrigger_workflow 應該很快)。