Back to Details

diagnose

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

diagnose

诊断

This skill turns your agent into its own first-line support. Instead of forwarding "something's wrong" messages to a human, the agent inspects the VM, identifies the root cause, and either fixes it or reports a precise diagnosis.
该技能可让你的Agent成为自身的一线支持。无需将“出问题了”这类消息转发给人工，Agent会自行检查虚拟机，定位根本原因，要么自行修复，要么给出精准诊断结果。

When to trigger

触发时机

Trigger this skill automatically when:
  • The user says anything like "something's wrong", "not working", "broken", "help", "can't connect", "error", or "I'm stuck".
  • Any command or tool returns a non-zero exit code and you don't already know why.
  • A 
    StopFailure
    or similar hook fires.
  • An agent you spawned goes silent or returns a 
    generic
    / 
    timeout
    error class.
Do not trigger the security audit sub-capability automatically — run it only when the user explicitly asks for a security check or audit.
在以下场景自动触发该技能：
  • 用户提及类似“出问题了”“无法运行”“坏了”“求助”“连接不上”“报错”或“我卡住了”的内容时。
  • 任何命令或工具返回非零退出码且你不清楚原因时。
  • StopFailure
    或类似钩子触发时。
  • 你启动的Agent无响应或返回
    generic
    /
    timeout
    错误类型时。
请勿自动触发安全审计子功能——仅当用户明确要求进行安全检查或审计时才运行该功能。

Standard health check

标准健康检查

Run these in order. Stop at the first critical failure and attempt a fix before continuing. Report the full picture at the end.
按以下顺序执行检查。遇到首个严重故障时暂停，先尝试修复再继续。最后汇总完整检查结果。

1. Auth state

1. 认证状态

bash
undefined
bash
undefined

Check which agent types are authenticated on this host.

检查当前主机上已认证的Agent类型。

sudo 5dive doctor --json | jq '.data.checks | map(select(.name | startswith("auth")))'

If a type comes back `status: "fail"`, that's why agents of that type can't start.
Fix with `auth set` (API key) or guide the user through `auth start` (OAuth):

```bash
sudo 5dive doctor --json | jq '.data.checks | map(select(.name | startswith("auth")))'

若某类型返回`status: "fail"`，这就是该类型Agent无法启动的原因。使用`auth set`（API密钥）修复，或引导用户完成`auth start`（OAuth）流程：

```bash

API key path — pipe the key, never leave it in the shell history.

API密钥路径——通过管道传递密钥，切勿留在Shell历史记录中。

echo "$KEY" | sudo 5dive agent auth set claude --api-key=- --json
undefined
echo "$KEY" | sudo 5dive agent auth set claude --api-key=- --json
undefined

2. Recent 5dive-cli errors

2. 近期5dive-cli错误

bash
undefined
bash
undefined

Last 50 error/warning lines from the CLI audit log.

CLI审计日志中最近50条错误/警告记录。

sudo journalctl -u '5dive-agent@*' -p warning -n 50 --no-pager

Look for repeated `auth_required`, `not_running`, or `timeout` entries — they pin
down which agent is failing and why.
sudo journalctl -u '5dive-agent@*' -p warning -n 50 --no-pager

留意重复出现的`auth_required`、`not_running`或`timeout`条目——它们能明确指出哪个Agent出现故障及原因。

3. Service health

3. 服务健康度

bash
undefined
bash
undefined

Overall host check — exits 0 even with failures, read data.summary.errors.

整体主机检查——即使存在故障也会返回0，需查看data.summary.errors。

sudo 5dive doctor --json
sudo 5dive doctor --json

Per-agent status (running / stopped / failed).

各Agent状态（运行中/已停止/故障）。

sudo 5dive agent list --json | jq '.data.agents | to_entries[] | {name:.key, status:.value.status}'
sudo 5dive agent list --json | jq '.data.agents | to_entries[] | {name:.key, status:.value.status}'

Full systemd state for a specific agent:

特定Agent的完整systemd状态：

sudo systemctl status '5dive-agent@<name>'

A `failed` unit usually means the agent crashed on startup. Check
`journalctl -u 5dive-agent@<name> -n 30 --no-pager` for the stack trace.
sudo systemctl status '5dive-agent@<name>'

`failed`状态通常意味着Agent启动时崩溃。查看`journalctl -u 5dive-agent@<name> -n 30 --no-pager`获取堆栈跟踪信息。

4. Disk usage

4. 磁盘使用情况

bash
undefined
bash
undefined

Filesystem usage — warn if any mount is over 80 %.

文件系统使用情况——若任何挂载点使用率超过80%则发出警告。

df -h | awk 'NR==1 || $5+0 > 80'
df -h | awk 'NR==1 || $5+0 > 80'

Top 10 disk consumers under /home and /var/lib/5dive:

/home和/var/lib/5dive目录下占用空间Top10的文件/文件夹：

du -sh /home/*/ /var/lib/5dive/ 2>/dev/null | sort -rh | head -10

High disk is the #1 cause of silent install failures and agent crashes.
Clean logs with `sudo journalctl --vacuum-size=200M` if journals are the culprit.
du -sh /home/*/ /var/lib/5dive/ 2>/dev/null | sort -rh | head -10

磁盘空间不足是静默安装失败和Agent崩溃的头号原因。若日志文件占用过多，可使用`sudo journalctl --vacuum-size=200M`清理日志。

5. Memory

5. 内存状态

bash
free -h
bash
free -h

Swap usage over 50 % with low free RAM = OOM risk.

交换分区使用率超过50%且可用内存不足=存在内存耗尽（OOM）风险。


If an agent OOM-killed, systemd shows `status=1/KILLED` and journalctl shows
`Killed process`. The fix is usually `sudo 5dive agent rm <heavy-agent>` or
adding swap.

若Agent因OOM被杀死，systemd会显示`status=1/KILLED`，journalctl会显示`Killed process`。通常的修复方法是`sudo 5dive agent rm <heavy-agent>`或添加交换分区。

6. Skill integrity

6. 技能完整性

bash
undefined
bash
undefined

List installed skills for each running agent.

列出每个运行中Agent已安装的技能。

for agent in $(sudo 5dive agent list --json | jq -r '.data.agents | keys[]'); do echo "=== $agent ==="; sudo 5dive agent skill "$agent" list --json | jq -r '.data.skills[].name'; done

A missing skill that the agent depends on causes silent capability gaps — not errors,
just "I don't know how to do that". Re-install with:

```bash
sudo 5dive agent skill <name> add --source=<source> --skill=<skillId> --json
for agent in $(sudo 5dive agent list --json | jq -r '.data.agents | keys[]'); do echo "=== $agent ==="; sudo 5dive agent skill "$agent" list --json | jq -r '.data.skills[].name'; done

Agent依赖的技能缺失会导致静默功能缺口——不会报错，只会返回“我不知道如何操作”。可通过以下命令重新安装：

```bash
sudo 5dive agent skill <name> add --source=<source> --skill=<skillId> --json

Putting it together — the diagnosis report

整合诊断报告

After running the checks above, produce a report in this structure:
undefined
完成上述检查后，按以下结构生成报告：
undefined

Diagnosis

诊断结果

Status: [Healthy / Degraded / Critical]
状态: [健康/性能下降/严重故障]

Findings

检查发现

  • [auth] claude: authenticated ✓
  • [service] agent-worker: failed — exit code 1, OOM at 03:12 UTC
  • [disk] /var/lib: 87 % full — journals consuming 4.2 GB
  • [skill] worker: brainstorming missing
  • [认证] claude: 已认证 ✓
  • [服务] agent-worker: 故障——退出码1，于UTC时间03:12因OOM崩溃
  • [磁盘] /var/lib: 使用率87%——日志文件占用4.2 GB
  • [技能] worker: 缺失brainstorming技能

Root cause

根本原因

<one sentence>
<一句话总结>

Actions taken

已执行操作

  • Vacuumed journals (freed 3.8 GB)
  • Re-installed brainstorming skill on worker
  • 清理日志文件（释放3.8 GB空间）
  • 为worker重新安装brainstorming技能

Remaining issues

剩余问题

  • worker OOM: recommend reducing concurrent agents or adding 2 GB swap

Keep findings machine-readable (one fact per bullet, consistent prefixes) so a
calling agent can parse them with `agent ask`.
  • worker OOM：建议减少并发Agent数量或添加2 GB交换分区

检查发现需保持机器可读（每个项目一个事实，前缀一致），以便调用方Agent可通过`agent ask`解析。

Quick fix recipes

快速修复方案

Restart a failed agent

重启故障Agent

bash
sudo systemctl restart 5dive-agent@<name>
sudo 5dive agent list --json | jq '.data.agents["<name>"].status'
bash
sudo systemctl restart 5dive-agent@<name>
sudo 5dive agent list --json | jq '.data.agents["<name>"].status'

Free disk space fast

快速释放磁盘空间

bash
sudo journalctl --vacuum-size=200M
docker system prune -f 2>/dev/null || true
bash
sudo journalctl --vacuum-size=200M
docker system prune -f 2>/dev/null || true

Re-authenticate a type

重新认证Agent类型

bash
undefined
bash
undefined

API key (non-interactive, safe from an agent):

API密钥（非交互式，Agent执行安全）:

echo "$KEY" | sudo 5dive agent auth set <type> --api-key=- --json
echo "$KEY" | sudo 5dive agent auth set <type> --api-key=- --json

OAuth (needs a human — give them the URL):

OAuth（需人工操作——提供URL给用户）:

sudo 5dive agent auth start <type> --json
sudo 5dive agent auth start <type> --json

Relay the URL to the user; they paste back the callback code:

将URL转发给用户；用户返回回调代码后执行:

sudo 5dive agent auth submit <type> --code=<callback-code> --json
undefined
sudo 5dive agent auth submit <type> --code=<callback-code> --json
undefined

Add swap (if OOM is the culprit)

添加交换分区（若OOM是问题根源）

bash
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
bash
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Security audit (explicit only — do not auto-run)

安全审计（仅明确触发——请勿自动运行）

Run this block only when the user explicitly asks for a security check.
bash
undefined
仅当用户明确要求安全检查时才执行以下操作。
bash
undefined

1. SSH authorized keys — list all keys across all users.

1. SSH授权密钥——列出所有用户的密钥。

for f in /root/.ssh/authorized_keys /home/*/.ssh/authorized_keys; do [ -f "$f" ] && echo "=== $f ===" && cat "$f"; done
for f in /root/.ssh/authorized_keys /home/*/.ssh/authorized_keys; do [ -f "$f" ] && echo "=== $f ===" && cat "$f"; done

2. Open listening ports.

2. 开放监听端口。

ss -tlnp
ss -tlnp

3. Recent auth failures (last 50).

3. 近期认证失败记录（最近50条）。

sudo journalctl -u ssh -n 50 --no-pager | grep -i 'fail|invalid|refused'
sudo journalctl -u ssh -n 50 --no-pager | grep -i 'fail|invalid|refused'

4. World-writable files under /etc and /var/lib/5dive (should be empty).

4. /etc和/var/lib/5dive下的全局可写文件（正常应为空）。

find /etc /var/lib/5dive -maxdepth 4 -perm -o+w -type f 2>/dev/null
find /etc /var/lib/5dive -maxdepth 4 -perm -o+w -type f 2>/dev/null

5. Setuid/setgid binaries not in the baseline (spot new surprises).

5. 不在基线内的Setuid/Setgid二进制文件（排查新增风险）。

find / -maxdepth 5 ( -perm -4000 -o -perm -2000 ) -type f 2>/dev/null
| grep -v '^/usr/|^/bin/|^/sbin/'
find / -maxdepth 5 ( -perm -4000 -o -perm -2000 ) -type f 2>/dev/null
| grep -v '^/usr/|^/bin/|^/sbin/'

6. Agent env files — confirm they are root-readable only.

6. Agent环境文件——确认仅root可读。

ls -la /etc/5dive/connectors/

Report findings with a **Risk** label: `Low`, `Medium`, or `High`. Only flag
deviations from the expected baseline — an empty world-writable list is a pass,
not a finding.
ls -la /etc/5dive/connectors/

报告结果时需标注**风险等级**：`低`、`中`或`高`。仅标记与预期基线不符的情况——全局可写文件列表为空属于正常，无需记录。

Rules of engagement

操作规则

  1. Read before writing. Run checks before attempting fixes.
  2. Fix one thing at a time. Each fix should be verifiable — rerun the relevant check after each action.
  3. Never touch production credentials. If you find a misconfigured key, report it; don't rotate it without explicit user approval.
  4. Security audit is opt-in. Never run the security section automatically.
  5. Surface uncertainty. If you can't determine the root cause, say so clearly rather than guessing.
  1. 先读后写：执行修复前先完成检查。
  2. 一次修复一项：每项修复需可验证——每次操作后重新运行相关检查。
  3. 切勿触碰生产凭证：若发现配置错误的密钥，仅需报告；未经用户明确批准不得轮换。
  4. 安全审计需主动触发：切勿自动运行安全审计模块。
  5. 明确告知不确定性：若无法确定根本原因，需清晰说明，切勿猜测。