hotplex-diagnostics

# HotPlex 运行时诊断 ## 诊断哲学 诊断不是跑检查清单 — 而是从症状出发，逐层缩小范围。 核心层次：**进程 → 数据 → 反馈链路 → 日志 → 适配器 → 源码**。 每层都有**跳过条件**：进程不在就停；没有 running session 就跳过反馈检查；日志干净就跳过源码。不要做无用功。 --- ## 第一步：进程与端口 为什么先查进程 — 进程不在，后面所有的日志和状态都可能过时。 确认组件存活：Gateway（8888）、WebChat（3000）、Admin（9999）、Worker 子进程（`claude --session-id` / `--resume`、`codex`、`opencode-server`、ACP agent via stdio JSON-RPC）。 检查要点： - PID 文件（`~/.hotplex/.pids/`）中的 PID 是否对应实际进程 — 不对应说明进程异常退出但系统未清理 - 端口是否在预期地址监听 — 仅绑定 localhost 是安全基线 - RSS/CPU/运行时长 — RSS 持续增长暗示泄漏（>500MB 需关注），CPU 持续 >50% 需排查 **跳过条件**：Gateway 进程不在 → 🔴 诊断结束，报告进程问题即可。 --- ## 第二步：Session 状态一致性 为什么查 session — HotPlex 的 session 状态是内存 + SQLite 双写，两处可能不同步，而大多数用户问题（"任务卡住"、"响应慢"）都能从 session 状态找到线索。 查 `~/.hotplex/data/hotplex.db`，关注： - 各状态 session 数量：`SELECT state, COUNT(*) FROM sessions GROUP BY state` - 对 running/idle session：进程是否存活？Worker PID 匹配？ - Worker session 持久化方式因 worker 类型而异： - Claude Code Worker：`~/.claude/projects/*/<uuid>.jsonl`（JSONL session 文件） - Codex CLI Worker：通过 app-server HTTP API 管理，无本地文件 - OCS Worker：单例进程内维护 session 状态 - ACP Worker：通过 stdio JSON-RPC 管理，生命周期与子进程绑定 不一致分类（表示系统健康问题的术语）： - **ORPHANED**：DB 记录在但进程已死 — 等 GC 自动清理或手动终止记录 - **ZOMBIE**：进程在但 DB 状态是 terminated — GC 漏扫，通常是 race condition - **STALE_RESUME**：标记 running/idle 但磁盘上 session 文件不存在 — resume 时必定失败 **跳过条件**：无 running/idle session → 直接跳到第四步（日志分析），反馈链路检查不适用。 --- ## 第三步：反馈连续性 这是用户体验的核心能力 — 任务执行中用户看不到更新，但任务实际上还在跑。这种问题最隐蔽，因为 Worker 日志看起来一切正常。 ### 反馈链路 事件从 Worker 到用户经历一条管道，任何环节断裂都导致用户端无反馈： ...