openclaw-diag-cli 0.1.2 → 0.2.1

package/README.md

@@ -1,49 +1,89 @@
-# OpenClaw 诊断工具箱
+# openclaw-diag
 
-> 排查 OpenClaw / ArkClaw 故障的只读 CLI。一组诊断、一个入口、零依赖。
+OpenClaw 出问题时，**先跑这条命令再开 ticket**：
 
-## 安装
+```bash
+npx openclaw-diag-cli all
+```
+
+零安装、零依赖、observer-only — 只读探测，绝不改你的状态。
+
+## 这是什么
+
+一个排查 [OpenClaw](https://github.com/openclaw/openclaw) 运行问题的命令行工具箱。
+
+把日常排障要做的事情切成 12 个原子诊断：每个回答一个具体问题（"Gateway 起来了吗？"、"哪个 cron 连续失败？"、"P95 延迟最高的模型是哪个？"），可以单独跑、可以一键全跑、也可以拼成 jq 管道喂给监控。
+
+**适合谁用**
+
+- 用 OpenClaw 的运维 / SRE — 想知道线上某个组件在不在状态
+- 应急响应工程师 — 用户报障时要 5 分钟摸清"哪挂了、什么时候挂的、谁动过它"
+- 自动化平台 — 想把 OpenClaw 健康指标接到自家监控
+
+**不是什么**
+
+- 不是修复工具 — 它告诉你出了什么问题，但不会去改任何东西
+- 不是替代 `openclaw doctor` 的内置检查 — 它做的是更深一层的事故诊断
+- 不是性能压测工具 — 它读真实运行数据，不主动施压
+
+## 安装与上手
+
+需要 Node 18+ 和 Python 3.8+。
 
 ```bash
-# 一次性运行（无需安装，npm 缓存后离线可用）
+# 一次性运行（首次会下载到 npm cache，之后离线可用）
 npx openclaw-diag-cli
 
-# 装到 PATH
+# 或装到 PATH
 npm install -g openclaw-diag-cli
-openclaw-diag
 ```
 
-依赖：Node 18+ 和 Python 3.8+。
-
-## 五分钟上手
-
 ```bash
-# 1. 看看能做什么
-openclaw-diag
-
-# 2. 检查环境是否就绪
+# 检查工具自身环境
 openclaw-diag doctor
 
-# 3. 跑某个诊断
+# 跑某个具体诊断（看 Gateway 状态）
 openclaw-diag gateway
 
-# 4. 全部 state collectors 跑一遍（任一崩了不影响其他）
+# 一次跑完所有 state collectors（任一崩了不影响其他）
 openclaw-diag all
 
-# 5. 输出结构化 JSON
+# 输出结构化 JSON（适合喂给 jq / 监控）
 openclaw-diag gateway --json
+
+# 追踪一条用户消息从进入到响应的完整时间轴
+openclaw-diag trace <session-uuid>
+```
+
+输出大致长这样（截取 `openclaw-diag gateway`）：
+
+```
+── 模块 4：Gateway 状态 ──
+
+  • 进程 / 端口
+    PID 12847 (uptime 3d 2h)，监听 :8080，HTTP /healthz → 200
+  • 24h 重启
+    无重启事件
+  • Model API
+    amazon-bedrock 可达（DNS+HTTP+认证均通）
+  • WS 生命周期
+    最近 1h 内 134 次连接，平均存活 47s，无异常关闭
 ```
 
+加 `--json` 后输出严格结构化（同字段、同值），方便管道处理。
+
 ## 诊断列表
 
-诊断按"是否需要参数"分两类。
+```bash
+openclaw-diag list   # 看完整列表
+```
 
-### State collectors（无需参数，扫一遍系统当前状态）
+**扫描类（无需参数，扫一遍系统当前状态）**
 
 | 诊断 | 看什么 |
 |---|---|
 | `sys_health` | DNS / 网络 / CPU / 内存 / 磁盘 / IO / 进程 / 时间同步 |
-| `environment` | OpenClaw 版本一致性、Gateway 进程环境变量 |
+| `environment` | OpenClaw 版本一致性、Gateway 进程的环境变量 |
 | `configuration` | `openclaw.json` 展平（敏感字段已脱敏） |
 | `gateway` | Gateway 进程、端口、24h 启停、WS 生命周期、错误码 |
 | `recent_errors` | 应用日志 / journalctl / session 工具调用错误聚合 |
@@ -53,74 +93,62 @@ openclaw-diag gateway --json
 | `plugin_diag` | 插件状态一致性、ERROR/WARN、Hook 异常、Channel、外部依赖 DNS |
 | `shell_history` | 高危命令、openclaw 命令、最近操作 |
 
-### Object inspectors（需要 session uuid，深挖一个具体对象）
+**对象类（需要 session uuid）**
 
 | 诊断 | 看什么 |
 |---|---|
-| `trace <uuid>` | 追踪一条用户消息从进入到响应的完整时间轴 |
-| `extract <uuid>` | 导出 session.jsonl 为可读格式（reset / bak / deleted 全状态） |
+| `trace <uuid>` | 一条用户消息从进入到响应的完整时间轴 |
+| `extract <uuid>` | session.jsonl 导出为可读格式（active / reset / deleted / backup 全状态） |
 
-### Meta
+**其它命令**
 
 | 命令 | 作用 |
 |---|---|
 | `openclaw-diag all` | 跑全部 state collectors |
-| `openclaw-diag list` | 列出所有诊断 |
-| `openclaw-diag doctor` | 检查 Node / Python / ocdiag / OpenClaw 环境 |
-| `openclaw-diag bundle <id>` | 打成 self-contained 单文件 .py |
+| `openclaw-diag doctor` | 检查 Node / Python / openclaw-diag / OpenClaw 环境 |
+| `openclaw-diag bundle <id>` | 打成单文件 .py，离线机器零依赖运行 |
 
-## 常见配方
+## 配方（jq 管道）
 
 ```bash
-# 找出哪个 cron 任务在连续失败
+# 哪些 cron 任务出问题了
 openclaw-diag cron_jobs --json | jq '.data.jobs[] | select(.status!="ok")'
 
-# 看哪个模型的 P95 延迟最高
-openclaw-diag performance | grep -A1 "P95"
-
-# 哪些插件今天有 ERROR
-openclaw-diag plugin_diag --json | jq '.data.plugin_errors | to_entries[] | select(.value.error_count > 0)'
+# P95 延迟 top 3 的模型
+openclaw-diag performance --json | jq '.data.models | to_entries | sort_by(-.value.p95_s) | .[0:3]'
 
-# 把所有诊断聚合成单个 JSON 报告
-openclaw-diag all --json 2>/dev/null | jq -s '.' > report.json
-
-# 找出有 stuck session 的事件
+# 找出有 stuck session 的 agent
 openclaw-diag sessions --json | jq '.data.stuck_sessions'
 
-# 追踪用户消息时间轴
-openclaw-diag trace <session-uuid> --msg-index 0
-
-# 导出 session 为可读格式
-openclaw-diag extract <session-uuid> --summary
+# 把所有诊断聚合成 NDJSON 报告（崩溃模块也有错误行，不会丢）
+openclaw-diag all --json 2>/dev/null > report.ndjson
 ```
 
-## 离线机器：bundle 出单文件
+## 离线机器与配置覆盖
+
+如果目标机器没法装 npm，先在有网的机器上 `bundle` 出单文件：
 
 ```bash
-# 在有网的机器
+# 在有网的机器上
 openclaw-diag bundle gateway > standalone-gateway.py
 
-# scp 到目标机器（只需要 Python 3.8+，无需安装任何东西）
+# 拷到目标机器（只需 Python 3.8+，无需安装任何东西）
 scp standalone-gateway.py prod-server:/tmp/
 ssh prod-server "python3 /tmp/standalone-gateway.py --json"
 ```
 
-`bundle` 会把脚本和它依赖的共享代码合并成一个 self-contained `.py`，零依赖。
-
-## 配置覆盖
-
-诊断别人机器或容器时，无需改代码：
+诊断他人机器或容器时，无需改代码，用环境变量或 flag 覆盖默认路径：
 
 | 环境变量 | 默认值 | 说明 |
 |---|---|---|
 | `OPENCLAW_HOME` | `~/.openclaw` | OpenClaw 主目录 |
 | `OPENCLAW_CONFIG` | `$OPENCLAW_HOME/openclaw.json` | 配置文件 |
 | `OPENCLAW_LOG_DIR` | `/tmp/openclaw` | 日志目录 |
-| `OPENCLAW_SESSIONS` | `$OPENCLAW_HOME/agents` | Session 根 |
+| `OPENCLAW_SESSIONS` | `$OPENCLAW_HOME/agents` | Session 根目录 |
 
-也可以用 `--config /path/to/file --log-dir /path/to/logs` 覆盖单次。
+或单次运行时用 flag：`--config /path/to/file --log-dir /path/to/logs`。
 
-## 退出码
+## 退出码与设计
 
 | rc | 含义 |
 |---|---|
@@ -128,23 +156,8 @@ ssh prod-server "python3 /tmp/standalone-gateway.py --json"
 | 1 | 诊断运行成功但报告 `status: "error"`（数据源缺失等） |
 | 2 | 诊断崩溃（已隔离，不影响 `all`） |
 
-## 设计原则
-
-| | |
-|---|---|
-| **只读** | 永远不修改文件、不重启服务 |
-| **零依赖** | 仅 Python 3.8+ 标准库 |
-| **故障隔离** | 单诊断崩溃不带崩 `all` |
-| **数据可靠** | 每个字段都能溯源 |
-| **可组合** | 文本 + JSON 双输出，stderr 与 stdout 分流 |
-
-详细设计 → [docs/DESIGN.md](docs/DESIGN.md)（公理推导、目录结构、扩展指南）
+设计上遵循 7 条公理：observer-only、零运行时依赖、仓库内独立、双视角输出（文本/JSON 同字段同值）、数据溯源、失败显式、默认脱敏。详细推导见 [docs/DESIGN.md](docs/DESIGN.md)。
 
 ## 反馈
 
-- Issues: https://github.com/wujiaming88/openclaw-diag-cli/issues
-- 来源：从 4391 行的 `openclaw-diag.sh` 拆分重写
-
-## License
-
-MIT
+Issues: https://github.com/wujiaming88/openclaw-diag-cli/issues。License: MIT。

package/bin/openclaw-diag.js

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 // openclaw-diag — Node entry shell.
-// Locates python3, forwards args to ocdiag.dispatcher, transparently passes stdio
-// and exit code. Implements two Node-side commands (doctor, bundle dispatch,
-// --version, --help) so the user gets useful UX even before Python runs.
+//
+// All real logic lives in Python (ocdiag.dispatcher, ocdiag.doctor). This
+// shell exists for one reason only: npx-friendly install. It locates a
+// suitable python3, hands argv to the Python dispatcher, and forwards stdio
+// + exit code transparently. The single source of truth for the module
+// catalogue is `ocdiag/dispatcher.py`; the Node shell pulls the list from
+// `ocdiag list --json` instead of duplicating it (axiom #3).
 
 'use strict';
 
@@ -12,27 +16,12 @@ const fs = require('fs');
 
 const REPO_ROOT = path.resolve(__dirname, '..');
 const PKG = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+const DISPATCHER = path.join(REPO_ROOT, 'bin', 'ocdiag');
 
 const PYTHON_CANDIDATES = process.platform === 'win32'
   ? ['python3', 'python', 'py']
   : ['python3', 'python'];
 
-// Keep these in sync with ocdiag/dispatcher.py.
-const STATE_COLLECTORS = [
-  'sys_health', 'environment', 'configuration', 'gateway', 'recent_errors',
-  'cron_jobs', 'performance', 'sessions', 'plugin_diag', 'shell_history',
-];
-const OBJECT_INSPECTORS = ['trace', 'extract'];
-const MODULE_IDS = new Set([...STATE_COLLECTORS, ...OBJECT_INSPECTORS]);
-
-const STATE_SCRIPTS = [
-  '01_sys_health.py', '02_environment.py', '03_configuration.py',
-  '04_gateway.py', '05_recent_errors.py', '06_cron_jobs.py',
-  '07_performance.py', '08_sessions.py', '09_plugin_diag.py',
-  '10_shell_history.py',
-];
-const OBJECT_SCRIPTS = ['oc_session_trace.py', 'oc_session_extract.py'];
-
 function findPython() {
   for (const cmd of PYTHON_CANDIDATES) {
     try {
@@ -49,55 +38,68 @@ function findPython() {
         }
       }
     } catch (_) {
-      // try next
+      // try next candidate
     }
   }
   return null;
 }
 
 function pythonNotFound() {
-  console.error('Error: Python 3.8+ required but not found.');
-  console.error('  Install: https://www.python.org/downloads/  or  apt install python3');
+  console.error('Error: 需要 Python 3.8+ 但未找到。');
+  console.error('  Linux:   sudo apt install python3   /   sudo yum install python3');
+  console.error('  macOS:   brew install python3       /   或从 https://www.python.org/downloads/ 安装');
+  console.error('  Windows: https://www.python.org/downloads/  （记得勾上 "Add to PATH"）');
+  console.error('  装完后再次运行 openclaw-diag 即可。');
   process.exit(127);
 }
 
+function fetchModules(pyCmd) {
+  const r = spawnSync(pyCmd, [DISPATCHER, 'list', '--json'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (r.status !== 0) return null;
+  try {
+    return JSON.parse((r.stdout || '').toString());
+  } catch (_) {
+    return null;
+  }
+}
+
 function printVersion() {
   console.log(PKG.version);
 }
 
-function printHelp() {
+function printHelp(modules) {
+  const state = modules ? modules.state_collectors.map((m) => m.id) : [];
+  const obj = modules ? modules.object_inspectors.map((m) => m.id) : [];
   const lines = [
-    'openclaw-diag — OpenClaw / ArkClaw 诊断工具箱',
+    'openclaw-diag — OpenClaw 诊断工具箱',
     '',
-    'Usage:',
+    '用法：',
     '  openclaw-diag                          打印 banner + 诊断目录',
-    '  openclaw-diag list                     列出全部诊断（按类型分组）',
     '  openclaw-diag <id> [args...]           跑单个诊断',
     '  openclaw-diag all [--skip a,b]         跑全部 state collectors',
-    '  openclaw-diag all [--json]             NDJSON 聚合输出',
-    '  openclaw-diag bundle <id>              打成 self-contained 单文件 .py',
-    '  openclaw-diag doctor [--json]          检查 Node / Python / ocdiag / OpenClaw env',
+    '  openclaw-diag list                     列出所有诊断',
+    '  openclaw-diag doctor                   检查 Node / Python / 环境',
+    '  openclaw-diag bundle <id>              生成单文件 .py（离线机器用）',
     '  openclaw-diag --version                打印版本号',
     '  openclaw-diag --help                   本帮助',
     '',
-    'State collectors (无需参数):',
-    '  ' + STATE_COLLECTORS.join('  '),
+    '扫描类（无需参数）：',
+    '  ' + (state.length ? state.join('  ') : '（无法连接到 Python）'),
     '',
-    'Object inspectors (需要 session uuid):',
-    '  ' + OBJECT_INSPECTORS.join('  '),
+    '对象类（需要 session uuid）：',
+    '  ' + (obj.length ? obj.join('  ') : '（无法连接到 Python）'),
     '',
-    '透传给诊断脚本: --config --log-dir --json --no-color',
+    '常用 flag：--json（结构化输出）  --no-color（关掉颜色）  --unmask（不脱敏）',
   ];
   console.log(lines.join('\n'));
 }
 
-function runDispatcher(args) {
-  const py = findPython();
-  if (!py) pythonNotFound();
-  const dispatcher = path.join(REPO_ROOT, 'bin', 'ocdiag');
-  const child = spawn(py.cmd, [dispatcher, ...args], { stdio: 'inherit' });
+function spawnDispatcher(pyCmd, args) {
+  const child = spawn(pyCmd, [DISPATCHER, ...args], { stdio: 'inherit' });
   child.on('error', (err) => {
-    console.error(`Error: failed to spawn ${py.cmd}: ${err.message}`);
+    console.error(`Error: failed to spawn ${pyCmd}: ${err.message}`);
     process.exit(1);
   });
   child.on('exit', (code, signal) => {
@@ -109,12 +111,16 @@ function runDispatcher(args) {
   });
 }
 
-function runScript(scriptPath, args) {
-  const py = findPython();
-  if (!py) pythonNotFound();
-  const child = spawn(py.cmd, [scriptPath, ...args], { stdio: 'inherit' });
+function runBundle(pyCmd, args) {
+  if (args.length === 0) {
+    console.error('Error: bundle requires a module id (e.g. `openclaw-diag bundle gateway`)');
+    process.exit(2);
+  }
+  const child = spawn(pyCmd, [path.join(REPO_ROOT, 'lib', 'bundle.py'), ...args], {
+    stdio: 'inherit',
+  });
   child.on('error', (err) => {
-    console.error(`Error: failed to spawn ${py.cmd}: ${err.message}`);
+    console.error(`Error: failed to spawn ${pyCmd}: ${err.message}`);
     process.exit(1);
   });
   child.on('exit', (code, signal) => {
@@ -126,142 +132,21 @@ function runScript(scriptPath, args) {
   });
 }
 
-function runBundle(args) {
-  if (args.length === 0) {
-    console.error('Error: bundle requires a module id (e.g. `openclaw-diag bundle gateway`)');
-    process.exit(2);
-  }
-  runScript(path.join(REPO_ROOT, 'lib', 'bundle.py'), args);
-}
-
-// ── doctor ──
-
-function nodeVersionOk() {
-  const m = process.versions.node.match(/^(\d+)\./);
-  return m && parseInt(m[1], 10) >= 18;
-}
-
-function checkOcdiagImport(pyCmd) {
-  const r = spawnSync(
-    pyCmd,
-    ['-c', 'import sys, os; sys.path.insert(0, os.environ["OCDIAG_REPO_ROOT"]); import ocdiag; print(ocdiag.__version__)'],
-    {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, OCDIAG_REPO_ROOT: REPO_ROOT },
-    },
-  );
-  if (r.status === 0) {
-    return { ok: true, version: (r.stdout || '').toString().trim() };
-  }
-  return { ok: false, error: ((r.stderr || '') + (r.stdout || '')).toString().trim() };
-}
-
-function checkDiagScripts(pyCmd) {
-  const failed = [];
-  const all = [
-    ...STATE_SCRIPTS.map((n) => ({ name: n, path: path.join(REPO_ROOT, 'diag', n) })),
-    ...OBJECT_SCRIPTS.map((n) => ({ name: n, path: path.join(REPO_ROOT, 'tools', n) })),
-  ];
-  for (const item of all) {
-    const r = spawnSync(pyCmd, [item.path, '--help'], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: 10000,
-    });
-    if (r.status !== 0) {
-      failed.push({ script: item.name, status: r.status, stderr: ((r.stderr || '').toString().trim()).slice(0, 200) });
-    }
-  }
-  return { failed, total: all.length };
-}
-
-function checkOpenclawConfig() {
-  const home = process.env.HOME || require('os').homedir();
-  const cfg = process.env.OPENCLAW_CONFIG
-    || path.join(process.env.OPENCLAW_HOME || path.join(home, '.openclaw'), 'openclaw.json');
-  return { path: cfg, exists: fs.existsSync(cfg) };
-}
-
-function runDoctor(args) {
-  const jsonMode = args.includes('--json');
-  const result = {
-    node: { version: process.versions.node, ok: nodeVersionOk() },
-    python: null,
-    ocdiag: null,
-    diag_scripts: null,
-    openclaw_config: null,
-  };
-
-  const py = findPython();
-  if (!py) {
-    result.python = { ok: false, error: 'Python 3.8+ not found in PATH' };
-    if (jsonMode) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`✓ Node v${result.node.version}${result.node.ok ? '' : ' (need >= 18)'}`);
-      console.log('✗ Python 3.8+ not found in PATH');
-      console.log('  Install: https://www.python.org/downloads/  or  apt install python3');
-    }
-    process.exit(1);
-  }
-  result.python = { ok: true, version: py.version, cmd: py.cmd };
-
-  const ocdiag = checkOcdiagImport(py.cmd);
-  result.ocdiag = ocdiag;
-
-  const { failed, total } = checkDiagScripts(py.cmd);
-  result.diag_scripts = {
-    ok: failed.length === 0,
-    total,
-    failed,
-  };
-
-  const cfg = checkOpenclawConfig();
-  result.openclaw_config = cfg;
-
-  if (jsonMode) {
-    console.log(JSON.stringify(result, null, 2));
-  } else {
-    console.log(`${result.node.ok ? '✓' : '✗'} Node v${result.node.version}${result.node.ok ? '' : ' (need >= 18)'}`);
-    console.log(`✓ Python ${py.version} (${py.cmd})`);
-    if (ocdiag.ok) {
-      console.log(`✓ ocdiag package importable (version ${ocdiag.version})`);
-    } else {
-      console.log('✗ ocdiag package not importable');
-      if (ocdiag.error) {
-        console.log('  ' + ocdiag.error.split('\n').slice(-3).join(' | '));
-      }
-    }
-    if (failed.length === 0) {
-      console.log(`✓ All ${total} diagnostics respond to --help`);
-    } else {
-      console.log(`✗ ${failed.length}/${total} diagnostics failed --help:`);
-      for (const f of failed) {
-        console.log(`    ${f.script} (rc=${f.status})`);
-      }
-    }
-    if (cfg.exists) {
-      console.log(`✓ OpenClaw config present (${cfg.path})`);
-    } else {
-      console.log(`ℹ OpenClaw config not found (${cfg.path}) — diagnostics will run but report missing`);
-    }
-  }
-
-  const ok = result.node.ok && result.python.ok && ocdiag.ok && failed.length === 0;
-  process.exit(ok ? 0 : 1);
+function runDoctor(pyCmd, args) {
+  // Forward Node version into the Python doctor so it can include it in the
+  // report. ocdiag.doctor handles the actual logic; we just spawn it.
+  spawnDispatcher(pyCmd, ['doctor', '--node-version', process.versions.node, ...args]);
 }
 
-// ── main ──
-
 function main() {
   const argv = process.argv.slice(2);
+  const py = findPython();
 
   if (argv.length === 0) {
-    const py = findPython();
     if (!py) pythonNotFound();
-    console.log(`openclaw-diag v${PKG.version} — OpenClaw / ArkClaw 诊断工具箱`);
+    console.log(`openclaw-diag v${PKG.version} — OpenClaw 诊断工具箱`);
     console.log('');
-    const dispatcher = path.join(REPO_ROOT, 'bin', 'ocdiag');
-    spawnSync(py.cmd, [dispatcher, 'list'], { stdio: 'inherit' });
+    spawnSync(py.cmd, [DISPATCHER, 'list'], { stdio: 'inherit' });
     console.log('');
     console.log('常用命令：');
     console.log('  openclaw-diag gateway           跑单个 state collector');
@@ -279,20 +164,24 @@ function main() {
     process.exit(0);
   }
   if (head === '--help' || head === '-h') {
-    printHelp();
+    if (!py) pythonNotFound();
+    printHelp(fetchModules(py.cmd));
     process.exit(0);
   }
+
+  if (!py) pythonNotFound();
+
   if (head === 'doctor') {
-    runDoctor(argv.slice(1));
+    runDoctor(py.cmd, argv.slice(1));
     return;
   }
   if (head === 'bundle') {
-    runBundle(argv.slice(1));
+    runBundle(py.cmd, argv.slice(1));
     return;
   }
 
-  // Pass through everything else (flat ids, `all`, `list`, `run` alias, unknown) to dispatcher.
-  runDispatcher(argv);
+  // Pass everything else (flat ids, `all`, `list`, `run` alias, unknown) to dispatcher.
+  spawnDispatcher(py.cmd, argv);
 }
 
 main();

package/diag/01_sys_health.py

@@ -7,7 +7,6 @@ import json
 import os
 import re
 import shutil
-import socket
 import subprocess
 import sys
 import time
@@ -412,7 +411,6 @@ def section_time_sync(out: output.Output) -> None:
 def main() -> int:
     parser = cli.build_common_parser(
         description="模块 1：系统健康检查",
-        prog="01_sys_health",
     )
     args = parser.parse_args()