# dsh-herdr 运维与故障排查

## 1. 诊断顺序

遇到问题时从外到内检查：

```text
插件是否安装
  -> DSH 是否加载 bundle
  -> DSH 进程能否找到 herdr
  -> Herdr server/socket 是否运行
  -> 目标 workspace/pane/agent 是否存在
  -> CLI 参数和版本是否兼容
```

不要一开始就重装所有插件或删除 lockfile。

## 2. `server_not_running`

含义：`herdr` CLI 已成功启动，但无法连接默认或指定 session 的 Herdr server。

插件会把 stderr 中的 JSON 解析进 `data`，并提供顶层 `errorCode`，因此工具结果中 `errorCode === "server_not_running"`（或 `data.error.code`）可直接判断。

检查：

```bash
command -v herdr
herdr --version
herdr status
herdr workspace list
```

处理：在真实交互终端运行并保持 Herdr：

```bash
herdr
```

如果使用自定义 `HERDR_SOCKET_PATH` 或 `HERDR_SESSION`，启动 DSH 的进程必须获得相同环境。不要在确认 Herdr 仍运行时删除 socket。

## 3. `herdr` 不在 PATH

可选环境变量：

- `DSH_HERDR_CLI_TIMEOUT_MS`（毫秒）：为 `herdr` 子进程增加硬超时兜底。
- `DSH_HERDR_PREVIEW_REQUIRED=1`：要求 R2 工具先 `preview=true` 再执行，否则返回 `preview_required`。

不设置 `DSH_HERDR_CLI_TIMEOUT_MS` 或设为 0 时沿用 Herdr CLI 自身的行为。

症状：结果中的 stderr 类似 `spawn herdr ENOENT`。

检查 DSH 启动环境，而不只是当前 shell：

```bash
command -v herdr
printf '%s\n' "$PATH"
```

确保启动 `dsh web` 的用户和环境包含 Herdr 安装目录。插件不会使用硬编码 `/home/.../herdr`，以保持可移植性。

## 4. 目标不存在

pane、tab 或 agent ID 可能在关闭、移动或重启后失效。处理：

1. 重新调用对应 list。
2. 从 JSON 结果读取真实 ID。
3. 不按 UI 顺序推测编号。
4. agent 名称必须在 live agents 中唯一。

## 5. 安装时供应链策略失败

错误：

```text
ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION
```

若错误列出的是 profile 已有旧 lockfile 条目，且该 lockfile 来源可信，可使用：

```bash
dsh plugin --profile web add github:wenhao4126/dsh-herdr --trust-lockfile
```

这不是让用户忽略未知 lockfile。若来源不可信，应审查或重建，不要全局关闭 `minimumReleaseAge`。

## 6. Peer dependency warning

DSH profile 中的 UI 插件常把 React 和 DSH host 包声明为 peer，但它们由 DSH host 提供，并未作为 profile 普通 dependency 安装。

检查：

```bash
cd ~/.dsh/profiles/web
pnpm peers check
```

如果确认缺失项全部是 host 提供的 `react`、`react-dom`、`@deepseek-ai/*`，可以在 profile 的 `pnpm-workspace.yaml` 使用：

```yaml
peerDependencyRules:
  ignoreMissing:
    - react
    - react-dom
    - '@deepseek-ai/*'
  allowedVersions:
    '@deepseek-ai/dsh-tools': '*'
```

不要为了消除提示在 profile 重复安装 React 或 DSH runtime；多实例可能导致 hooks、context 或注册表不一致。

## 7. `Packages: -12`

这是 pnpm 对 hoisted 中间依赖重新布置或清理的统计，不等于删除 12 个顶层插件。

验证顶层依赖：

```bash
cd ~/.dsh/profiles/web
pnpm list --depth 0
```

只要 package.json、bundle list 和顶层依赖仍在，不应把该统计视为卸载事故。

## 8. 插件已安装但工具未出现

检查：

1. profile `package.json` dependencies 是否包含插件。
2. `dsh.profile.bundles` 是否包含 `@dsh-external/dsh-herdr-toolkit`。
3. 安装包是否有 `cordis.patch.yml` 和 `dsh.bundle.patch`。
4. 重启 DSH，使新版本工具目录重新装配。
5. 检查 loader entry 是否 active。

GitHub 安装后当前对话可能仍保留旧工具 schema；新工具通常需要重启 DSH 或创建新会话。

## 9. 工具返回 invalid output

DSH 要求 lossless JSON。常见原因：返回对象含 `undefined`、函数、BigInt 或循环引用。

本插件的约束：

- 缺失字段必须完全省略。
- stdout JSON 解析后必须是 lossless JSON。
- 不应把 Node Error 对象直接返回。

## 10. Agent 无法启动

检查：

```bash
herdr pane get <pane-id>
herdr pane process-info --pane <pane-id>
herdr agent list
```

要求：

- pane 存在且是可用 shell。
- agent kind 在当前 Herdr 支持列表中。
- agent 可执行程序已安装。
- agent 名称合法且唯一。
- timeout 足够。

`agent start` 不会自动创建 pane。

## 11. 等待超时

超时不代表任务失败。处理：

1. `agent get` 或 `pane get` 查询状态。
2. `agent read` / `pane read` 读取最近输出。
3. 若处于 blocked，交给用户确认。
4. 若仍 working，选择延长等待。
5. 不要无限循环短 timeout。

## 12. 收集故障报告

报告至少包含：

- DSH 版本。
- 插件版本和 Git commit。
- Herdr 版本。
- 安装方式。
- 工具名称和去敏参数类别。
- 完整结构化结果。
- `herdr <group> help` 中相关命令。
- 是否使用自定义 socket/session。

不要附带 token、完整敏感 prompt、私有源码内容或未去敏环境变量。