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:
@@ -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(少見場景)
|
||||
- 觸發外部 API(zapier / 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 < 500ms(trigger_workflow 應該很快)。
|
||||
Reference in New Issue
Block a user