Agent Skills › rocketride-org/rocketride-server › rocketride-debugging-pipelines

rocketride-debugging-pipelines

GitHub

用于诊断 RocketRide 流水线运行失败、错误或输出异常的问题。通过读取运行状态和执行轨迹定位故障节点，分类原因并路由修复方案。

docs/agents/skills/rocketride-debugging-pipelines/SKILL.md rocketride-org/rocketride-server

触发场景

流水线运行失败或报错产出错误/空输出需要排查运行故障

安装

npx skills add rocketride-org/rocketride-server --skill rocketride-debugging-pipelines -g -y

更多选项

非标准路径

npx skills add https://github.com/rocketride-org/rocketride-server/tree/develop/docs/agents/skills/rocketride-debugging-pipelines -g -y

不安装直接使用

npx skills use rocketride-org/rocketride-server@rocketride-debugging-pipelines

指定 Agent (Claude Code)

npx skills add rocketride-org/rocketride-server --skill rocketride-debugging-pipelines -a claude-code -g -y

安装 repo 全部 skill

npx skills add rocketride-org/rocketride-server --all -g -y

预览 repo 内 skill

npx skills add rocketride-org/rocketride-server --list

SKILL.md

Frontmatter

{
    "name": "rocketride-debugging-pipelines",
    "description": "Use when a RocketRide pipeline run failed, errored, or produced wrong\/empty output, and you need to find the failing node and fix it. Reads run status and execution traces, diagnoses the cause, and routes back to design or configuration. Also use directly when asked to debug a run."
}

Debugging RocketRide Pipelines

Diagnose, don't guess. A failed run has a real cause in the status/trace; find it, then route the fix to the right phase. No re-running until the cause is identified and the fix is validated.

Procedure

Read the status. MCP: monitor(task_token) → quote state_label, errors[], warnings[], counts verbatim. SDK: get_task_status(token) → state, errors[], warnings[], exitCode, exitMessage, failedCount. Don't paraphrase error messages.
Read the trace. MCP — the run-log (DVR) tools work for past and live runs, keyed by the projectId + source returned by run_pipeline/run_dropper_pipe (never the task token): log_chapters to find the run → log_read for paged events (≤200/page; follow the cursor) → log_traces to list per-object traces → log_trace for one object's full per-node enter/leave with lane, data, result, error. Retention: 7 days dev / 30 days deploy. A run started with pipelineTraceLevel="none" has chapters/console but empty traces — re-run with "summary"/"full" for flow evidence. SDK fallback: the apaevt_flow / _trace events in the response. Either way, find the first node whose op shows an error or whose output is empty/wrong — that's the failure point. Downstream errors are usually consequences.
Classify the cause (see ERROR_TABLE.md):
- Config — bad/missing field, wrong API key, wrong model name → fix in rocketride-configuring-pipelines (re-fetch schema, re-validate).
- Wiring/lane — lane mismatch, missing converter, wrong source method → fix in rocketride-designing-pipelines (re-wire), then re-configure + re-validate.
- Runtime — event-loop blocked (Connection closed/timeout), Pipeline already running, blocking I/O → fix the run code in rocketride-running-pipelines.
- Data — empty/garbage input, wrong response key (KeyError) → check input + result_types.
Propose a specific fix tied to the evidence: "Node llm_1 failed: Invalid API key. The ${ROCKETRIDE_OPENAI_KEY} env var is unset / wrong. Fix: set it, re-validate, re-run." Route to the owning phase. Do not re-run until the fix is made and validate() is clean again.

Common diagnoses (full table in ERROR_TABLE.md)

Connection closed / Connection closed unexpectedly → event loop blocked by sync I/O (most common runtime failure) — fix the run code, not the pipeline.
The service <provider> was not found → misspelled provider; check the index.
input has unknown lane (validate) → lane mismatch; add a converter or pick compatible nodes.
KeyError: '<key>' → response key vs laneName mismatch; read result_types.
Pipeline is already running. → use_existing=True or terminate() first.
Invalid API key / a project_id rejection → config fix.

Red flags

Thought	Reality
"I'll just re-run, maybe it works"	Find the cause first; blind re-runs cost money and teach nothing.
"The last node errored, fix that node"	The first failing node in the trace is usually the cause; later errors cascade.
"Connection dropped — the engine is flaky"	Almost always a blocked event loop (sync I/O in async code), not the engine.
"I'll paraphrase the error"	Quote it verbatim — the exact message maps to the exact fix.
"Fixed it, re-running"	Re-validate() after any fix before re-running.

Supporting files

ERROR_TABLE.md — error message → cause → owning phase → fix
deep docs — for failure modes the table doesn't cover, fetch ONE page: ../rocketride-building-pipelines/tools/fetch-doc.py "error handling" (→ /concepts/error-handling.md) or … "observability" (→ /protocols/websocket/observability.md). Never llms-full.txt.