`herdr server start` 无效 / 后台 server 未拉起（v0.8.2 没有 server start 子命令）

你会遇到什么

装了 herdr，想让它在后台把 server 跑起来——敲 herdr server start，结果它不启动任何东西，只把 server 子命令列表（help 文本）打印一遍；herdr status 一直是 server: not running，~/.config/herdr/ 下也找不到 herdr.sock。看起来像「server 起不来」，其实是 v0.8.2 的命令面里根本没有 server start 这个子命令——不是坏了，是入口不对。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

先给结论：herdr 的进程模型是「客户端 + 后台 server（socket 通信）」，TUI 客户端 herdr 启动时按需自动拉起后台 server；headless 场景才需要手动把 herdr server 放后台。它没有 start/stop 对称的命令面——启动面只有两个入口，停止面只有一个：

链路：命令面解析 → server 进程 → socket 写面。断点就在第一步：server 是「运行 server」而不是「管理 server」，start 子命令不存在，所以敲 herdr server start 只会打印帮助，不会报错——这一类「命令不存在但报错温和」的入口错误，靠报错文本排查会走空。

实测（2026-08-29，WSL Ubuntu，隔离 HOME）：headless herdr server 启动 → status 显示 server: running → 四个写面文件就位（socket 权限 srwx-------）→ herdr server stop → status 回到 not running，socket 不再可访问。

推论：判断「server 有没有起来」不看命令敲没敲对，看两个硬信号——herdr status 的输出 + ~/.config/herdr/ 下的 socket 写面；脚本里以「status + socket 就位」作为启动成功的判据。

一步步来

1. 先确认命令面 — 必做

herdr --help 看一眼子命令列表：只有 herdr（TUI）与 herdr server（headless），没有 server start。

2. 交互使用：直接开 TUI — 必做

herdr 启动 TUI，后台 server 自动拉起；随即 herdr status 应显示 server: running。

3. 脚本化：headless 放后台 — 按场景

nohup herdr server > /tmp/herdr-server.log 2>&1 &
herdr status

4. 停止与复验 — 按场景

herdr server stop → 再 herdr status 确认 not running。

5. 写面核对 — 排查

ls -la ~/.config/herdr/：应出现 .plugins.lock、herdr-client.sock、herdr.sock、herdr-server.log；缺 socket = server 没起来。

怎么确认修好了

• herdr status 输出 server: running；
• ~/.config/herdr/ 下 herdr.sock、herdr-client.sock 就位（权限 srwx-------）；
• herdr server stop 后 status 回到 not running，socket 不再可访问。

其它环境的表现

• 服务器 / CI（无桌面）：用 headless 路径（nohup herdr server &），别指望 TUI；

本站实测记录

• 工作区零写入：herdr 只在 ~/.config/herdr/ 与 ~/.local/state/herdr/ 落文件，cwd 不写（2026-08-28 cli-smoke 验证）。

症状

输入 herdr server start 不启动 server，只打印 server 子命令列表（help 文本）；herdr status 显示 server: not running；~/.config/herdr/ 下没有 herdr.sock。

原因

v0.8.2 命令面里不存在 server start 子命令。正确启动面有两个：

• herdr（TUI 完整客户端）——正常使用路径，自动拉起后台 server；
• herdr server（headless）——前台运行 server，脚本化时用 nohup herdr server & 放后台；
• 停止面 = herdr server stop（经 API socket）；确认面 = herdr status（server: running / not running）。

解法

1. 交互使用：直接 herdr 开 TUI（server 自动拉起），无需显式 start。
2. 脚本化：nohup herdr server > /tmp/herdr-server.log 2>&1 &，然后 herdr status 确认 running。
3. 停止：herdr server stop；再次 herdr status 确认 not running。
4. 写面确认：~/.config/herdr/ 下应出现 .plugins.lock、herdr-client.sock、herdr.sock、herdr-server.log。