17 第15章故障排除

17.1 安装问题排查

17.1.1 安装失败的常见原因

症状	可能原因	解决方案
`command not found: herdr`	PATH 未包含安装路径	见下方「PATH 修复」
安装脚本 404	网络问题或 CDN 故障	尝试镜像源或手动下载
权限不足（Permission denied）	安装目录无写权限	使用正确的安装路径
版本不兼容	操作系统版本过低	检查系统要求

17.1.2 PATH 修复

安装后如果 herdr 命令找不到，需要将安装路径加入 PATH：

# Homebrew 安装
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

# 官方脚本安装（默认路径）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# mise 安装
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

# 验证
which herdr
herdr --version

17.1.3 验证安装完整性

# 检查 Herdr 核心组件
herdr doctor

# 输出示例：
# ✅ herdr binary: v2.4.1
# ✅ terminal emulator: OK
# ✅ config file: valid
# ✅ agent manifests: 5 loaded
# ✅ SSH config: managed
# ⚠️  update channel: 1 version behind

Tip

herdr doctor 是排查任何问题的第一步。它会自动检测常见问题并给出修复建议。

17.2 Agent 状态问题

17.2.1 Agent 状态不正确

Agent 显示的状态（Idle / Running / Done / Blocked / Unknown）与实际不符，是最常见的问题之一。

17.2.1.1 使用 `herdr agent explain` 调试

# 查看 Agent 状态的详细诊断信息
herdr agent explain <agent-name>

# 输出示例：
# Agent: reviewer
# Tab: code-review
# Pane ID: tab1:pane2
# 
# Detection Method: screen_manifest
# Status: Done (confidence: 95%)
# 
# Matched Pattern:
#   regex: "^\\[review complete\\]"
#   source: pane_output (last 5 lines)
#   captured_at: 2026-08-01T14:32:15Z
# 
# Lifecycle Hooks:
#   on_start:  triggered ✅
#   on_done:   triggered ✅
#   on_block:  not triggered
# 
# Screen Checklist:
#   ✅ "Review Summary" heading detected
#   ✅ Exit code 0 detected
#   ⚠️  No explicit "done" keyword found

17.2.1.2 屏幕清单检测 vs 生命周期钩子

Herdr 通过两种机制判断 Agent 状态：

flowchart LR
    A[Agent 状态判断] --> B{检测方式}
    B --> C["屏幕清单检测<br/>Screen Manifest"]
    B --> D["生命周期钩子<br/>Lifecycle Hooks"]
    
    C --> C1[扫描窗格输出]
    C --> C2[匹配正则模式]
    C --> C3[返回状态 + 置信度]
    
    D --> D1[Agent 启动时触发 on_start]
    D --> D2[退出码 0 触发 on_done]
    D --> D3[退出码 ≠ 0 触发 on_error]

检测方式	原理	优点	局限
屏幕清单检测	扫描窗格最新输出，匹配预定义的正则模式	支持任意 Agent，无需集成	有延迟，可能误判
生命周期钩子	Agent 退出时根据退出码判断	精确无延迟	仅适用于支持的 Agent

17.2.1.3 本地覆盖清单

当内置的检测清单不准确时，可以为特定 Agent 创建本地覆盖：

# 创建本地覆盖文件
mkdir -p ~/.config/herdr/agent-detection

# ~/.config/herdr/agent-detection/reviewer.toml

# 自定义 reviewer Agent 的检测规则
[[detect]]
status = "done"
pattern = "✅ Review complete"
source = "pane_output"
lines = 10          # 扫描最后 10 行
confidence = 0.9

[[detect]]
status = "blocked"
pattern = "⚠️.*requires.*input"
source = "pane_output"
lines = 5
confidence = 0.85

[[detect]]
status = "running"
pattern = "Analyzing file"
source = "pane_output"
lines = 3
confidence = 0.7

17.2.1.4 手动更新清单

# 强制更新所有 Agent 检测清单
herdr server update-agent-manifests

# 更新后重启 server 使清单生效
herdr server restart

Note

Agent 检测清单由 Herdr 官方维护并定期更新。如果发现某个 Agent 状态识别不准确，也可以在 GitHub 上提交 issue 报告。

17.3 Pane 输出读取问题

17.3.1 Agent 的输出无法被正确读取

有时 Agent 窗格中有输出，但侧边栏状态、herdr agent explain 或其他读取机制无法获取到正确内容。

17.3.1.1 原因一：Alternate Screen 模式

许多 TUI 程序（vim、less、htop、Claude Code）使用 alternate screen（备用屏幕缓冲区）。当 Agent 在 alternate screen 中运行时，Herdr 只能读到空内容或控制字符。

flowchart TD
    A[Agent 窗格输出] --> B{Alternate Screen?}
    B -->|是| C[输出在备用缓冲区]
    C --> D[Herdr 读不到内容 ❌]
    B -->|否| E[输出在主缓冲区]
    E --> F[Herdr 正常读取 ✅]
    D --> G[解决方案]
    G --> G1[请求 Agent 写文件]
    G --> G2[使用 --no-alt-screen]
    G --> G3[通过 Socket API 读取]

解决方案：

# 方案 1：让 Agent 将结果写入文件
# 在 Agent 的命令中添加文件输出
claude-code --task "审查代码" --output /tmp/review-result.txt

# 方案 2：禁用 alternate screen（如果 Agent 支持）
LESS="--no-alt-screen" some-tui-command

# 方案 3：通过 Socket API 读取 alternate screen 内容
herdr socket send pane.alt-screen-read tab1:pane2

17.3.1.2 原因二：字体大小/窗格尺寸

窗格尺寸过小时（例如被分割成很多小窗格），输出会被截断或换行异常：

# 检查窗格尺寸
herdr pane info <pane-id>

# 输出示例：
# Pane ID: tab1:pane3
# Rows: 24
# Cols: 80
# Scrollback: 1000 lines
# Alt screen: active

建议： - Agent 窗格至少保持 80×24 的尺寸 - 不要在一个 tab 中分割超过 4 个窗格 - 使用 Ctrl+a Z 快速最大化当前窗格查看完整输出

17.3.1.3 原因三：Agent 输出速度过快

某些 Agent 输出大量内容时（如构建日志），Herdr 的读取可能滞后：

# 在配置中增加输出历史缓冲
[experimental]
pane_history = true
pane_history_lines = 5000   # 保存最近 5000 行

17.4 远程连接问题

17.4.1 SSH 连接失败

# 测试基本 SSH 连通性
ssh -v herdr-remote-server

# 常见错误：
# Permission denied (publickey) → SSH 密钥问题
# Connection refused → 远程 Herdr 未运行
# Connection timed out → 网络/防火墙问题

17.4.1.1 SSH 认证问题

# 1. 确认 ssh-agent 正在运行
eval "$(ssh-agent -s)"

# 2. 添加密钥
ssh-add ~/.ssh/id_ed25519

# 3. 测试密钥
ssh -T git@github.com

# 4. 确认 Herdr 管理的 SSH 配置
cat ~/.ssh/config | grep -A5 "herdr-"

17.4.1.2 ssh-agent 持久化配置

# macOS：使用钥匙串
# ~/.zshrc 或 ~/.bash_profile
ssh-add --apple-use-keychain ~/.ssh/id_ed25519 2>/dev/null

# Linux：使用 keychain
sudo apt install keychain
# 在 ~/.zshrc 中添加
eval "$(keychain --eval --quiet id_ed25519)"

17.4.1.3 平台不匹配

问题	原因	解决方案
远程不支持 Herdr	远程未安装	在远程执行安装脚本
版本不一致	客户端/服务端版本差异	统一升级到同一版本
架构不匹配	ARM vs x86	使用对应架构的二进制文件

# 在远程安装 Herdr
ssh user@remote-server "curl -fsSL https://herdr.dev/install.sh | bash"

# 验证版本
ssh user@remote-server "herdr --version"

17.5 更新问题

17.5.1 协议不兼容

当客户端和服务端版本差异过大时，可能出现协议不兼容：

Error: Protocol version mismatch (client: v3.0, server: v2.1)

17.5.1.1 使用 `--handoff` 模式升级

# 平滑升级：先升级客户端，再逐步升级服务端
herdr update --handoff

# --handoff 模式会：
# 1. 下载新版本
# 2. 检查与服务端的兼容性
# 3. 如不兼容，提示先升级服务端
# 4. 升级完成后自动迁移配置

17.5.1.2 不同安装方式的更新路径

# Homebrew
brew update && brew upgrade herdr

# mise
mise upgrade herdr

# Nix
nix-channel --update && nix-env -u herdr

# 官方脚本
herdr update

# 手动下载
curl -fsSL https://herdr.dev/releases/latest/herdr-darwin-arm64.tar.gz | tar xz -C ~/.local/bin/

Warning

如果你在团队中使用 Herdr，建议所有成员保持同一版本。可以在项目 .herdr/ 目录中指定最低版本要求：

# .herdr/config.toml
min_version = "2.4.0"

17.6 性能问题排查

17.6.1 CPU/内存占用过高

# 查看 Herdr 进程资源占用
herdr stats

# 输出示例：
# PID: 48923
# CPU: 3.2%
# Memory: 156 MB
# Panes: 12
# Active Agents: 3
# Uptime: 2h 34m

17.6.1.1 性能优化建议

问题	检查方法	优化方案
窗格过多导致 CPU 高	`herdr pane list \\| wc -l`	关闭不需要的窗格和 tab
输出历史占用内存	`herdr stats --memory`	减小 `pane_history_lines`
Agent 检测扫描频繁	`herdr agent explain --timing`	降低检测频率或精简模式
网络延迟高	`herdr remote ping <host>`	使用 SSH 连接复用

17.6.2 检测频率调优

# 默认每 2 秒扫描一次
[experimental]
detection_interval_ms = 2000     # 增大间隔降低 CPU 使用
detection_max_panes = 20         # 限制扫描的窗格数量

17.7 日志与诊断

17.7.1 日志文件位置

平台	日志路径
macOS	`~/Library/Logs/herdr/`
Linux	`~/.local/share/herdr/logs/`

17.7.2 查看日志

# 查看最新日志
herdr logs

# 实时跟踪日志
herdr logs --follow

# 查看特定级别的日志
herdr logs --level error

# 查看最近 100 行
herdr logs --lines 100

# 查看特定组件的日志
herdr logs --component agent-detection
herdr logs --component remote
herdr logs --component terminal

17.7.3 日志级别

# 在配置中设置日志级别
# 可选：trace / debug / info / warn / error
[logging]
level = "info"
file_rotation = true
max_file_size = "10MB"
keep_files = 5

Tip

排查问题时建议临时将日志级别设为 debug 或 trace：

# 临时启用 debug 日志（不修改配置文件）
herdr --log-level debug server start

17.8 常见错误信息速查表

错误信息	错误码	原因	解决方案
`Connection refused`	ECONNREFUSED	Herdr server 未运行	执行 `herdr server start`
`Protocol version mismatch`	EPROTO	客户端/服务端版本不一致	升级到同一版本
`Agent not found`	EAGENTNOTFOUND	Agent 名称不存在或清单未加载	执行 `herdr agent list` 检查
`Pane not found`	EPANENOTFOUND	窗格 ID 无效或已关闭	使用 `herdr pane list` 查看
`Permission denied`	EACCES	文件或端口权限不足	检查文件权限或使用正确端口
`SSH auth failed`	ESSHAUTH	SSH 密钥未配置或已过期	配置 ssh-agent 和密钥
`Config parse error`	ECONFIGPARSE	配置文件语法错误	执行 `herdr config validate`
`Port already in use`	EADDRINUSE	Herdr 默认端口被占用	修改端口或终止占用进程
`Agent detection timeout`	EDETECTTIMEOUT	Agent 状态检测超时	检查 Agent 是否正常运行
`Worktree creation failed`	EWORKTREE	Git 仓库状态异常	执行 `git status` 检查
`Remote handshake failed`	EHANDSHAKE	远程 Herdr 版本不兼容	升级远程 Herdr
`Disk full`	ENOSPC	磁盘空间不足	清理 worktree 和日志

17.9 调试工作流

当遇到问题时，按以下流程系统排查：

flowchart TD
    P[遇到问题] --> S1[Step 1: herdr doctor]
    S1 --> S2{问题已解决?}
    S2 -->|是| DONE[✅ 完成]
    S2 -->|否| S3[Step 2: herdr logs --level debug]
    S3 --> S4{找到线索?}
    S4 -->|是| S5[Step 3: 根据错误码查表]
    S4 -->|否| S6[Step 4: herdr agent explain]
    S5 --> FIX[应用解决方案]
    S6 --> S7{找到问题?}
    S7 -->|是| FIX
    S7 -->|否| S8[Step 5: 提交 Issue]
    FIX --> S2
    S8 --> S8A[附上 herdr doctor 输出]
    S8 --> S8B[附上 debug 日志]
    S8 --> S8C[附上 herdr --version 和操作系统信息]

提交 Issue 时请包含

herdr doctor 的完整输出
herdr --version 和操作系统版本
相关的 debug 级别日志片段
复现步骤
配置文件（隐去敏感信息）

17.10 小结

本章涵盖了 Herdr 使用中最常见的故障场景和排查方法：

安装问题：PATH 配置、完整性验证（herdr doctor）
Agent 状态：使用 herdr agent explain 诊断，配置本地覆盖清单
Pane 输出：alternate screen 限制及三种解决方案
远程连接：SSH 认证、ssh-agent 持久化、平台兼容性
更新：协议不兼容时使用 --handoff 模式平滑升级
性能：检测频率调优、窗格数量控制
日志：日志位置、级别调整、按组件过滤
错误速查表：12 个常见错误的快速定位

记住排查的黄金流程：herdr doctor → 查看日志 → herdr agent explain → 查错误码表 → 提交 Issue。下一章将介绍最佳实践，帮助你从开始就避免这些常见问题。

17.1 安装问题排查

17.1.1 安装失败的常见原因

17.1.2 PATH 修复

17.1.3 验证安装完整性

17.2 Agent 状态问题

17.2.1 Agent 状态不正确

17.2.1.1 使用 herdr agent explain 调试

17.2.1.2 屏幕清单检测 vs 生命周期钩子

17.2.1.3 本地覆盖清单

17.2.1.4 手动更新清单

17.3 Pane 输出读取问题

17.3.1 Agent 的输出无法被正确读取

17.3.1.1 原因一：Alternate Screen 模式

17.3.1.2 原因二：字体大小/窗格尺寸

17.3.1.3 原因三：Agent 输出速度过快

17.4 远程连接问题

17.4.1 SSH 连接失败

17.4.1.1 SSH 认证问题

17.4.1.2 ssh-agent 持久化配置

17.4.1.3 平台不匹配

17.5 更新问题

17.5.1 协议不兼容

17.5.1.1 使用 --handoff 模式升级

17.5.1.2 不同安装方式的更新路径

17.6 性能问题排查

17.6.1 CPU/内存占用过高

17.6.1.1 性能优化建议

17.6.2 检测频率调优

17.7 日志与诊断

17.7.1 日志文件位置

17.7.2 查看日志

17.7.3 日志级别

17.8 常见错误信息速查表

17.9 调试工作流

17.10 小结

17.2.1.1 使用 `herdr agent explain` 调试

17.5.1.1 使用 `--handoff` 模式升级