openclaw-diag-cli 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
-# openclaw-diag-cli
+# OpenClaw 诊断工具箱
 
-> OpenClaw / ArkClaw 故障诊断 CLI。零依赖、只读、人和机器都能用。
+> 排查 OpenClaw / ArkClaw 故障的只读 CLI。一组诊断、一个入口、零依赖。
 
 ## 安装
 
@@ -18,25 +18,29 @@ openclaw-diag
 ## 五分钟上手
 
 ```bash
-# 1. 看看能做什么（直接列出所有模块 + 常用命令）
+# 1. 看看能做什么
 openclaw-diag
 
 # 2. 检查环境是否就绪
 openclaw-diag doctor
 
-# 3. 跑单个模块
-openclaw-diag run gateway
+# 3. 跑某个诊断
+openclaw-diag gateway
 
-# 4. 全部跑一遍（任一模块崩了不影响其他）
-openclaw-diag run all
+# 4. 全部 state collectors 跑一遍（任一崩了不影响其他）
+openclaw-diag all
 
 # 5. 输出结构化 JSON
-openclaw-diag run gateway --json
+openclaw-diag gateway --json
 ```
 
-## 诊断模块（10 个）
+## 诊断列表
 
-| 模块 | 看什么 |
+诊断按"是否需要参数"分两类。
+
+### State collectors（无需参数，扫一遍系统当前状态）
+
+| 诊断 | 看什么 |
 |---|---|
 | `sys_health` | DNS / 网络 / CPU / 内存 / 磁盘 / IO / 进程 / 时间同步 |
 | `environment` | OpenClaw 版本一致性、Gateway 进程环境变量 |
@@ -49,33 +53,45 @@ openclaw-diag run gateway --json
 | `plugin_diag` | 插件状态一致性、ERROR/WARN、Hook 异常、Channel、外部依赖 DNS |
 | `shell_history` | 高危命令、openclaw 命令、最近操作 |
 
-## 单点工具（2 个）
+### Object inspectors（需要 session uuid，深挖一个具体对象）
 
-```bash
-# 跟踪一条用户消息从进入到响应的完整时间轴
-openclaw-diag tools/oc_session_trace.py <session-uuid> --msg-index 0
+| 诊断 | 看什么 |
+|---|---|
+| `trace <uuid>` | 追踪一条用户消息从进入到响应的完整时间轴 |
+| `extract <uuid>` | 导出 session.jsonl 为可读格式（reset / bak / deleted 全状态） |
 
-# 导出 session 为可读格式（支持 reset / bak / deleted 全状态）
-openclaw-diag tools/oc_session_extract.py <session-uuid> --summary
-```
+### Meta
+
+| 命令 | 作用 |
+|---|---|
+| `openclaw-diag all` | 跑全部 state collectors |
+| `openclaw-diag list` | 列出所有诊断 |
+| `openclaw-diag doctor` | 检查 Node / Python / ocdiag / OpenClaw 环境 |
+| `openclaw-diag bundle <id>` | 打成 self-contained 单文件 .py |
 
 ## 常见配方
 
 ```bash
 # 找出哪个 cron 任务在连续失败
-openclaw-diag run cron_jobs --json | jq '.data.jobs[] | select(.status!="ok")'
+openclaw-diag cron_jobs --json | jq '.data.jobs[] | select(.status!="ok")'
 
 # 看哪个模型的 P95 延迟最高
-openclaw-diag run performance | grep -A1 "P95"
+openclaw-diag performance | grep -A1 "P95"
 
 # 哪些插件今天有 ERROR
-openclaw-diag run plugin_diag --json | jq '.data.plugin_errors | to_entries[] | select(.value.error_count > 0)'
+openclaw-diag plugin_diag --json | jq '.data.plugin_errors | to_entries[] | select(.value.error_count > 0)'
 
 # 把所有诊断聚合成单个 JSON 报告
-openclaw-diag run all --json 2>/dev/null | jq -s '.' > report.json
+openclaw-diag all --json 2>/dev/null | jq -s '.' > report.json
 
 # 找出有 stuck session 的事件
-openclaw-diag run sessions --json | jq '.data.stuck_sessions'
+openclaw-diag sessions --json | jq '.data.stuck_sessions'
+
+# 追踪用户消息时间轴
+openclaw-diag trace <session-uuid> --msg-index 0
+
+# 导出 session 为可读格式
+openclaw-diag extract <session-uuid> --summary
 ```
 
 ## 离线机器：bundle 出单文件
@@ -108,9 +124,9 @@ ssh prod-server "python3 /tmp/standalone-gateway.py --json"
 
 | rc | 含义 |
 |---|---|
-| 0 | 模块成功 |
-| 1 | 模块运行成功但报告 `status: "error"`（数据源缺失等） |
-| 2 | 模块崩溃（已隔离，不影响其他模块） |
+| 0 | 诊断成功 |
+| 1 | 诊断运行成功但报告 `status: "error"`（数据源缺失等） |
+| 2 | 诊断崩溃（已隔离，不影响 `all`） |
 
 ## 设计原则
 
@@ -118,7 +134,7 @@ ssh prod-server "python3 /tmp/standalone-gateway.py --json"
 |---|---|
 | **只读** | 永远不修改文件、不重启服务 |
 | **零依赖** | 仅 Python 3.8+ 标准库 |
-| **故障隔离** | 单模块崩溃不带崩 `run all` |
+| **故障隔离** | 单诊断崩溃不带崩 `all` |
 | **数据可靠** | 每个字段都能溯源 |
 | **可组合** | 文本 + JSON 双输出，stderr 与 stdout 分流 |
 

package/bin/openclaw-diag.js

@@ -17,6 +17,22 @@ 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 {
@@ -51,23 +67,26 @@ function printVersion() {
 
 function printHelp() {
   const lines = [
-    'openclaw-diag — OpenClaw / ArkClaw read-only diagnostic CLI',
+    'openclaw-diag — OpenClaw / ArkClaw 诊断工具箱',
     '',
     'Usage:',
-    '  openclaw-diag                          Show banner + module list',
-    '  openclaw-diag list                     List all diagnostic modules',
-    '  openclaw-diag run <id>                 Run a single module (or "all")',
-    '  openclaw-diag run all [--skip a,b]     Run all modules (skip optional)',
-    '  openclaw-diag run <id> --json          Emit JSON (NDJSON for "all")',
-    '  openclaw-diag bundle <id>              Print self-contained single-file .py to stdout',
-    '  openclaw-diag doctor [--json]          Check Node / Python / ocdiag / OpenClaw env',
-    '  openclaw-diag --version                Print package version',
-    '  openclaw-diag --help                   Print this help',
+    '  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 --version                打印版本号',
+    '  openclaw-diag --help                   本帮助',
+    '',
+    'State collectors (无需参数):',
+    '  ' + STATE_COLLECTORS.join('  '),
     '',
-    'Module ids: sys_health environment configuration gateway recent_errors',
-    '            cron_jobs performance sessions plugin_diag shell_history',
+    'Object inspectors (需要 session uuid):',
+    '  ' + OBJECT_INSPECTORS.join('  '),
     '',
-    'Pass-through flags (forwarded to Python): --config --log-dir --json --no-color',
+    '透传给诊断脚本: --config --log-dir --json --no-color',
   ];
   console.log(lines.join('\n'));
 }
@@ -90,15 +109,10 @@ function runDispatcher(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);
-  }
+function runScript(scriptPath, args) {
   const py = findPython();
   if (!py) pythonNotFound();
-  const bundleScript = path.join(REPO_ROOT, 'lib', 'bundle.py');
-  const child = spawn(py.cmd, [bundleScript, ...args], { stdio: 'inherit' });
+  const child = spawn(py.cmd, [scriptPath, ...args], { stdio: 'inherit' });
   child.on('error', (err) => {
     console.error(`Error: failed to spawn ${py.cmd}: ${err.message}`);
     process.exit(1);
@@ -112,14 +126,15 @@ function runBundle(args) {
   });
 }
 
-// ── doctor ──
+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);
+}
 
-const DIAG_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',
-];
+// ── doctor ──
 
 function nodeVersionOk() {
   const m = process.versions.node.match(/^(\d+)\./);
@@ -143,17 +158,20 @@ function checkOcdiagImport(pyCmd) {
 
 function checkDiagScripts(pyCmd) {
   const failed = [];
-  for (const name of DIAG_SCRIPTS) {
-    const p = path.join(REPO_ROOT, 'diag', name);
-    const r = spawnSync(pyCmd, [p, '--help'], {
+  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: name, status: r.status, stderr: ((r.stderr || '').toString().trim()).slice(0, 200) });
+      failed.push({ script: item.name, status: r.status, stderr: ((r.stderr || '').toString().trim()).slice(0, 200) });
     }
   }
-  return failed;
+  return { failed, total: all.length };
 }
 
 function checkOpenclawConfig() {
@@ -190,10 +208,10 @@ function runDoctor(args) {
   const ocdiag = checkOcdiagImport(py.cmd);
   result.ocdiag = ocdiag;
 
-  const failed = checkDiagScripts(py.cmd);
+  const { failed, total } = checkDiagScripts(py.cmd);
   result.diag_scripts = {
     ok: failed.length === 0,
-    total: DIAG_SCRIPTS.length,
+    total,
     failed,
   };
 
@@ -214,9 +232,9 @@ function runDoctor(args) {
       }
     }
     if (failed.length === 0) {
-      console.log(`✓ All ${DIAG_SCRIPTS.length} diag modules respond to --help`);
+      console.log(`✓ All ${total} diagnostics respond to --help`);
     } else {
-      console.log(`✗ ${failed.length}/${DIAG_SCRIPTS.length} diag modules failed --help:`);
+      console.log(`✗ ${failed.length}/${total} diagnostics failed --help:`);
       for (const f of failed) {
         console.log(`    ${f.script} (rc=${f.status})`);
       }
@@ -240,14 +258,15 @@ function main() {
   if (argv.length === 0) {
     const py = findPython();
     if (!py) pythonNotFound();
-    console.log(`openclaw-diag v${PKG.version} — OpenClaw / ArkClaw 诊断 CLI`);
+    console.log(`openclaw-diag v${PKG.version} — OpenClaw / ArkClaw 诊断工具箱`);
     console.log('');
     const dispatcher = path.join(REPO_ROOT, 'bin', 'ocdiag');
     spawnSync(py.cmd, [dispatcher, 'list'], { stdio: 'inherit' });
     console.log('');
     console.log('常用命令：');
-    console.log('  openclaw-diag run gateway       跑单个模块');
-    console.log('  openclaw-diag run all           全部模块');
+    console.log('  openclaw-diag gateway           跑单个 state collector');
+    console.log('  openclaw-diag all               全部 state collectors');
+    console.log('  openclaw-diag trace <uuid>      追踪一条用户消息');
     console.log('  openclaw-diag doctor            检查环境');
     console.log('  openclaw-diag --help            完整帮助');
     process.exit(0);
@@ -272,7 +291,7 @@ function main() {
     return;
   }
 
-  // Pass through everything else to the Python dispatcher.
+  // Pass through everything else (flat ids, `all`, `list`, `run` alias, unknown) to dispatcher.
   runDispatcher(argv);
 }
 

package/ocdiag/__init__.py

@@ -1,3 +1,3 @@
 """ocdiag — shared library for openclaw-diag-cli scripts."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

package/ocdiag/dispatcher.py

@@ -1,8 +1,15 @@
-"""Dispatcher: list / run <name> / run all."""
+"""Dispatcher: every diagnostic is a top-level subcommand.
+
+Layout:
+  ocdiag <state-collector>      runs that collector (e.g. `ocdiag gateway`)
+  ocdiag <object-inspector> ARG runs that inspector  (e.g. `ocdiag trace UUID`)
+  ocdiag all [--skip a,b]       runs every state collector
+  ocdiag list                   prints the catalogue grouped by parameter mode
+  ocdiag run <id> [args...]     legacy alias retained for 0.1.x users
+"""
 
 from __future__ import annotations
 
-import argparse
 import os
 import runpy
 import sys
@@ -13,27 +20,47 @@ from typing import List
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 
-# Module ID -> (label, script filename relative to REPO_ROOT)
-MODULES = [
-    ("sys_health",     "系统健康检查",     "diag/01_sys_health.py"),
-    ("environment",    "采集基础环境",     "diag/02_environment.py"),
-    ("configuration",  "采集配置",         "diag/03_configuration.py"),
-    ("gateway",        "采集 Gateway 状态", "diag/04_gateway.py"),
-    ("recent_errors",  "采集近期日志",     "diag/05_recent_errors.py"),
-    ("cron_jobs",      "采集定时任务",     "diag/06_cron_jobs.py"),
-    ("performance",    "采集模型与性能数据", "diag/07_performance.py"),
-    ("sessions",       "采集 Session 数据", "diag/08_sessions.py"),
-    ("plugin_diag",    "采集插件诊断",     "diag/09_plugin_diag.py"),
-    ("shell_history",  "采集命令执行历史",  "diag/10_shell_history.py"),
+# State collectors: zero required args, parameter-free observation of system state.
+STATE_COLLECTORS = [
+    ("sys_health",     "系统健康检查",          "diag/01_sys_health.py"),
+    ("environment",    "OpenClaw 基础环境",     "diag/02_environment.py"),
+    ("configuration",  "配置展平（脱敏）",      "diag/03_configuration.py"),
+    ("gateway",        "Gateway 状态",          "diag/04_gateway.py"),
+    ("recent_errors",  "近期错误聚合",          "diag/05_recent_errors.py"),
+    ("cron_jobs",      "定时任务状态",          "diag/06_cron_jobs.py"),
+    ("performance",    "模型/工具性能",         "diag/07_performance.py"),
+    ("sessions",       "Session 数据",          "diag/08_sessions.py"),
+    ("plugin_diag",    "插件诊断",              "diag/09_plugin_diag.py"),
+    ("shell_history",  "Shell 历史",            "diag/10_shell_history.py"),
+]
+
+# Object inspectors: take a session uuid (or other identifier) and inspect it.
+OBJECT_INSPECTORS = [
+    ("trace",   "追踪用户消息时间轴",  "tools/oc_session_trace.py"),
+    ("extract", "导出 session 为可读格式", "tools/oc_session_extract.py"),
 ]
 
-MODULE_BY_ID = {mid: (label, script) for mid, label, script in MODULES}
+STATE_BY_ID = {mid: (label, script) for mid, label, script in STATE_COLLECTORS}
+OBJECT_BY_ID = {mid: (label, script) for mid, label, script in OBJECT_INSPECTORS}
+MODULE_BY_ID = {**STATE_BY_ID, **OBJECT_BY_ID}
+MODULE_IDS = set(MODULE_BY_ID.keys())
 
 
 def cmd_list() -> int:
-    print("Available modules:")
-    for mid, label, _ in MODULES:
-        print(f"  [x] {mid:<16s} {label}")
+    print("Available diagnostics:")
+    print()
+    print("  State collectors (no args needed):")
+    for mid, label, _ in STATE_COLLECTORS:
+        print(f"    {mid:<16s} {label}")
+    print()
+    print("  Object inspectors (require session uuid):")
+    for mid, label, _ in OBJECT_INSPECTORS:
+        print(f"    {mid:<16s} {label}")
+    print()
+    print("  Meta:")
+    print("    all              跑全部 state collectors")
+    print("    doctor           检查 Node/Python/OpenClaw 环境")
+    print("    bundle <id>      打包成 self-contained 单文件")
     return 0
 
 
@@ -62,72 +89,98 @@ def run_script(script_rel: str, extra_args: List[str]) -> int:
         sys.argv = saved_argv
 
 
-def cmd_run(target: str, extra_args: List[str], skip_ids: List[str]) -> int:
+def cmd_all(extra_args: List[str], skip_ids: List[str]) -> int:
     json_mode = "--json" in extra_args
     progress_stream = sys.stderr if json_mode else sys.stdout
-    if target == "all":
-        rc_overall = 0
-        total = sum(1 for mid, _, _ in MODULES if mid not in skip_ids)
-        n = 0
-        for mid, label, script in MODULES:
-            if mid in skip_ids:
-                continue
-            n += 1
-            print(f"\n[{n}/{total}] {label} ({mid})...", flush=True, file=progress_stream)
-            t0 = time.time()
-            rc = run_script(script, extra_args)
-            elapsed = time.time() - t0
-            print(f"[{n}/{total}] {label} ({mid}) ... done ({elapsed:.1f}s)", flush=True, file=progress_stream)
-            if rc != 0:
-                rc_overall = rc
-        return rc_overall
-    if target not in MODULE_BY_ID:
-        print(f"Error: unknown module '{target}'. Use `ocdiag list`.", file=sys.stderr)
-        return 2
-    _, script = MODULE_BY_ID[target]
-    return run_script(script, extra_args)
+    rc_overall = 0
+    total = sum(1 for mid, _, _ in STATE_COLLECTORS if mid not in skip_ids)
+    n = 0
+    for mid, label, script in STATE_COLLECTORS:
+        if mid in skip_ids:
+            continue
+        n += 1
+        print(f"\n[{n}/{total}] {label} ({mid})...", flush=True, file=progress_stream)
+        t0 = time.time()
+        rc = run_script(script, extra_args)
+        elapsed = time.time() - t0
+        print(f"[{n}/{total}] {label} ({mid}) ... done ({elapsed:.1f}s)",
+              flush=True, file=progress_stream)
+        if rc != 0:
+            rc_overall = rc
+    return rc_overall
+
+
+def _split_skip(rest: List[str]) -> (List[str], List[str]):
+    """Pull out --skip a,b out of an argv tail; return (skip_ids, passthrough)."""
+    skip_ids: List[str] = []
+    passthrough: List[str] = []
+    i = 0
+    while i < len(rest):
+        a = rest[i]
+        if a == "--skip" and i + 1 < len(rest):
+            skip_ids.extend(s.strip() for s in rest[i + 1].split(",") if s.strip())
+            i += 2
+            continue
+        passthrough.append(a)
+        i += 1
+    return skip_ids, passthrough
+
+
+def print_help() -> None:
+    print("ocdiag — OpenClaw 诊断工具箱")
+    print()
+    print("Usage:")
+    print("  ocdiag <id> [args...]            跑单个诊断（state collector 或 object inspector）")
+    print("  ocdiag all [--skip a,b]          跑全部 state collectors")
+    print("  ocdiag list                      列出所有诊断")
+    print("  ocdiag run <id> [args...]        旧用法别名（0.1.x 兼容）")
+    print()
+    print("State collectors:")
+    print("  " + "  ".join(mid for mid, _, _ in STATE_COLLECTORS))
+    print("Object inspectors:")
+    print("  " + "  ".join(mid for mid, _, _ in OBJECT_INSPECTORS))
+    print()
+    print("--skip 后接逗号分隔 id 列表（仅对 all 有意义）。")
+    print("其它参数（--config / --log-dir / --json / --no-color）原样传递给脚本。")
 
 
 def main(argv=None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
 
     if not argv or argv[0] in ("-h", "--help"):
-        print("ocdiag — OpenClaw 诊断 CLI dispatcher")
-        print()
-        print("Usage:")
-        print("  ocdiag list                      列出所有诊断模块")
-        print("  ocdiag run <id>                  运行单个模块（id 或 all）")
-        print("  ocdiag run all [--skip ids]      运行全部模块，可跳过若干")
-        print()
-        print("--skip 后接逗号分隔的 module id 列表（如 performance,sessions）。")
-        print("其它参数（--config / --log-dir / --json / --no-color）原样传递。")
+        print_help()
         return 0
 
-    cmd, rest = argv[0], argv[1:]
+    head, rest = argv[0], argv[1:]
 
-    if cmd == "list":
+    if head == "list":
         return cmd_list()
 
-    if cmd == "run":
+    if head == "all":
+        skip_ids, passthrough = _split_skip(rest)
+        return cmd_all(passthrough, skip_ids)
+
+    # Backward-compat alias: `ocdiag run <id> [args...]` still works.
+    if head == "run":
         if not rest:
             print("Error: run requires a target (module id or 'all').", file=sys.stderr)
             return 2
-        target = rest[0]
-        sub = rest[1:]
-        skip_ids: List[str] = []
-        passthrough: List[str] = []
-        i = 0
-        while i < len(sub):
-            a = sub[i]
-            if a == "--skip" and i + 1 < len(sub):
-                skip_ids.extend(s.strip() for s in sub[i + 1].split(",") if s.strip())
-                i += 2
-                continue
-            passthrough.append(a)
-            i += 1
-        return cmd_run(target, passthrough, skip_ids)
-
-    print(f"Error: unknown command '{cmd}'", file=sys.stderr)
+        target, sub = rest[0], rest[1:]
+        if target == "all":
+            skip_ids, passthrough = _split_skip(sub)
+            return cmd_all(passthrough, skip_ids)
+        if target in MODULE_BY_ID:
+            _, script = MODULE_BY_ID[target]
+            return run_script(script, sub)
+        print(f"Error: unknown diagnostic '{target}'. Use `ocdiag list`.", file=sys.stderr)
+        return 2
+
+    if head in MODULE_BY_ID:
+        _, script = MODULE_BY_ID[head]
+        return run_script(script, rest)
+
+    print(f"Error: unknown command '{head}'. Use `ocdiag list` to see available diagnostics.",
+          file=sys.stderr)
     return 2
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-diag-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "OpenClaw / ArkClaw read-only diagnostic CLI. Zero-dependency Python scripts wrapped in Node for npx-friendly install.",
   "keywords": [
     "openclaw",