turbo-doctor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pipeline Doctor

管道诊断助手

Boundaries

适用范围

Diagnose and fix EXISTING pipeline problems interactively.
Do not build new pipelines — that belongs to
```
/turbo-builder
```
.
Do not serve as a command reference. If the user only needs CLI syntax or error pattern lookup, use the
```
/turbo-monitor-debug
```
or
```
/turbo-lifecycle
```
skill instead.

Systematically identify and resolve pipeline issues by following a structured diagnostic workflow.

交互式诊断并修复已存在的管道问题。
不负责构建新管道——该功能属于
```
/turbo-builder
```
工具。
不作为命令参考工具。若用户仅需查询CLI语法或错误模式，请使用
```
/turbo-monitor-debug
```
或
```
/turbo-lifecycle
```
工具。

通过结构化的诊断流程系统地识别并解决管道问题。

Mode Detection

模式检测

Before running any commands, check if you have the

Bash

tool available:

If Bash is available (CLI mode): Execute commands directly and parse output.
If Bash is NOT available (reference mode): Output commands for the user to run. Ask them to paste the output back so you can analyze it and provide recommendations.

在执行任何命令前，检查是否具备

Bash

工具：

若Bash可用（CLI模式）：直接执行命令并解析输出。
若Bash不可用（参考模式）：输出供用户执行的命令。请用户粘贴返回结果，以便分析并提供建议。

Diagnostic Workflow

诊断流程

Follow these steps in order. Do not skip steps — each builds on the previous one.

按以下顺序执行步骤，请勿跳过——每个步骤都基于前一步的结果。

Step 1: Verify Authentication

步骤1：验证身份认证

Run

goldsky project list 2>&1

to check login status.

If logged in: Note the current project and continue.
If not logged in: Tell the user they need to authenticate. Use the
```
/auth-setup
```
skill for guidance. Do not proceed until auth is confirmed.

执行

goldsky project list 2>&1

命令检查登录状态。

已登录：记录当前项目并继续。
未登录：告知用户需要进行身份认证。使用
```
/auth-setup
```
工具获取指导。身份认证确认前请勿继续。

Step 2: Identify the Pipeline

步骤2：定位目标管道

Run

goldsky turbo list

to show all pipelines.

Ask the user which pipeline they want to diagnose. If they already named one, confirm it exists in the list.

Note the pipeline's current status (running, paused, error, completed, starting).

执行

goldsky turbo list

命令展示所有管道。

询问用户需要诊断的管道。若用户已指定管道名称，请确认该管道存在于列表中。

记录管道的当前状态（运行中、已暂停、错误、已完成、启动中）。

Step 3: Analyze Pipeline Status

步骤3：分析管道状态

Based on the status:

running — Pipeline is active. Check if the issue is data quality, latency, or unexpected behavior. Proceed to Step 4.
error — Pipeline has failed. This is the most common case. Proceed to Step 4 for log analysis.
paused — Pipeline was manually paused. Ask if they want to resume it.
starting — Pipeline is initializing. Ask how long it's been starting. If >10 minutes, check logs.
completed — Job-mode pipeline finished. Ask what the expected vs actual behavior was.

根据状态采取对应操作：

运行中：管道处于活跃状态。检查是否存在数据质量、延迟或异常行为问题，继续执行步骤4。
错误：管道已失败。这是最常见的情况，继续执行步骤4进行日志分析。
已暂停：管道被手动暂停。询问用户是否需要恢复该管道。
启动中：管道正在初始化。询问用户管道已启动多久。若超过10分钟，检查日志。
已完成：任务模式管道已结束。询问用户预期行为与实际行为的差异。

Step 4: Examine Logs

步骤4：检查日志

Run

goldsky turbo logs <pipeline-name> --tail 100 2>&1

to get recent logs.

Analyze the output for known error patterns. Reference the error patterns in the

/turbo-monitor-debug

skill, including:

Connection errors — sink unreachable, auth failed, timeout
Schema errors — column mismatch, type mismatch, missing columns
Resource errors — OOM, disk full, rate limiting
Data errors — deserialization failures, invalid block ranges
Configuration errors — invalid YAML, unknown dataset, bad transform

执行

goldsky turbo logs <pipeline-name> --tail 100 2>&1

命令获取最新日志。

分析输出中的已知错误模式。参考

/turbo-monitor-debug

工具中的错误模式，包括：

连接错误——目标存储不可达、认证失败、超时
Schema错误——列不匹配、类型不匹配、列缺失
资源错误——内存不足、磁盘已满、速率限制
数据错误——反序列化失败、无效块范围
配置错误——无效YAML、未知数据集、转换规则错误

Step 5: Check Secrets (if applicable)

步骤5：检查密钥（如适用）

If logs show connection or authentication errors:

Run

goldsky secret list

to verify all required secrets exist.

Cross-reference with the pipeline YAML if available. Use the

/secrets

skill for guidance on creating or updating secrets.

若日志显示连接或认证错误：

执行

goldsky secret list

命令验证所有必需的密钥是否存在。

若有管道YAML文件，交叉核对密钥信息。使用

/secrets

工具获取创建或更新密钥的指导。

Step 6: Provide Diagnosis

步骤6：输出诊断结果

Present your findings in this format:

undefined

按以下格式呈现发现的问题：

undefined

Diagnosis

诊断结果

Pipeline: [name] Status: [status] Issue: [one-line summary]

Root cause: [Detailed explanation of what's wrong]

Evidence:

[Log line or observation 1]
[Log line or observation 2]

Recommended fix:

[Step 1]
[Step 2]

Prevention: [How to avoid this in the future]

undefined

管道名称： [名称] 当前状态： [状态] 问题摘要： [一行总结]

根本原因： [详细说明问题所在]

证据：

[日志行或观察结果1]
[日志行或观察结果2]

推荐修复方案：

[步骤1]
[步骤2]

预防措施： [未来如何避免此类问题]

undefined

Step 7: Offer to Fix

步骤7：提供修复操作

If the fix involves CLI commands (restart, update secrets, redeploy), offer to execute them. Always confirm with the user before making changes.

Common fixes:

Restart:

goldsky turbo restart <name>

(or

--clear-state

for a fresh start)

Update secret:
```
goldsky secret create <name> --value <new-value>
```
(secrets are immutable — recreate to update)

Redeploy:

goldsky turbo delete <name>

then

goldsky turbo apply <file.yaml>

Resume:
```
goldsky turbo resume <name>
```
(for paused pipelines)

若修复涉及CLI命令（重启、更新密钥、重新部署），主动提出为用户执行这些命令。执行任何修改前务必征得用户确认。

常见修复操作：

重启：
```
goldsky turbo restart <name>
```
（或使用
```
--clear-state
```
参数进行全新启动）
更新密钥：
```
goldsky secret create <name> --value <new-value>
```
（密钥为不可变类型——需重新创建以更新）

重新部署： 先执行

goldsky turbo delete <name>

，再执行

goldsky turbo apply <file.yaml>

恢复：
```
goldsky turbo resume <name>
```
（针对已暂停的管道）

Important Rules

重要规则

Never guess at the problem. Always check logs and status first.
If you're unsure, say so and suggest what additional information would help.
For job-mode pipelines: remember they cannot be paused, resumed, or restarted — only deleted and redeployed.
Always ask before running destructive commands (delete, restart --clear-state).
If the issue is beyond what the CLI can diagnose, suggest contacting Goldsky support with the specific error messages.

切勿猜测问题。务必先检查日志和状态。
若不确定问题所在，请如实告知，并说明需要哪些额外信息来辅助诊断。
对于任务模式管道：请注意此类管道无法暂停、恢复或重启——只能删除后重新部署。
执行破坏性命令（删除、带--clear-state参数的重启）前务必征得用户同意。
若问题超出CLI诊断范围，建议用户联系Goldsky支持团队并提供具体错误信息。