openclaw-diag-cli 0.1.3 → 0.2.2

package/lib/bundle.py

@@ -21,19 +21,12 @@ from typing import Dict, List, Optional
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 
-# ID → script filename, kept in sync with ocdiag/dispatcher.py:MODULES.
-MODULES: List[tuple] = [
-    ("sys_health",     "diag/01_sys_health.py"),
-    ("environment",    "diag/02_environment.py"),
-    ("configuration",  "diag/03_configuration.py"),
-    ("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",       "diag/08_sessions.py"),
-    ("plugin_diag",    "diag/09_plugin_diag.py"),
-    ("shell_history",  "diag/10_shell_history.py"),
-]
+# Single source of truth: ocdiag.dispatcher. We import it dynamically so the
+# bundle script stays runnable from a fresh checkout (no install needed).
+sys.path.insert(0, str(REPO_ROOT))
+from ocdiag.dispatcher import STATE_COLLECTORS  # noqa: E402
+
+MODULES: List[tuple] = [(mid, rel) for mid, _label, rel in STATE_COLLECTORS]
 MODULE_BY_ID = {mid: rel for mid, rel in MODULES}
 
 # Order matters: each submodule is exec'd into its own module object, and its

package/ocdiag/__init__.py

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

package/ocdiag/cli.py

@@ -1,14 +1,23 @@
-"""Common argparse setup for diag scripts."""
+"""Common argparse setup for diag scripts.
+
+When invoked via the dispatcher (`openclaw-diag <id>`), the dispatcher exports
+OPENCLAW_DIAG_PROG="openclaw-diag <id>" before running the script so argparse
+uses that as `prog`. When you run the script directly (e.g.
+`python3 diag/01_sys_health.py`), argparse falls back to the script basename.
+"""
 
 from __future__ import annotations
 
 import argparse
+import os
 from typing import Optional
 
 from . import paths
 
 
 def build_common_parser(description: str, prog: Optional[str] = None) -> argparse.ArgumentParser:
+    if prog is None:
+        prog = os.environ.get("OPENCLAW_DIAG_PROG") or None
     p = argparse.ArgumentParser(
         prog=prog,
         description=description,
@@ -36,4 +45,10 @@ def build_common_parser(description: str, prog: Optional[str] = None) -> argpars
     )
     p.add_argument("--json", action="store_true", help="Emit JSON output")
     p.add_argument("--no-color", action="store_true", help="Disable colored output")
+    p.add_argument(
+        "--unmask",
+        action="store_true",
+        help="Disable default sanitization of secrets in free-form text "
+             "(shell history / plugin errors / systemd / sessions). Off by default.",
+    )
     return p

package/ocdiag/dispatcher.py

@@ -5,39 +5,42 @@ Layout:
   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
+  ocdiag bundle <id>            emits a self-contained single-file .py
+  ocdiag doctor                 environment health check
 """
 
 from __future__ import annotations
 
+import json
 import os
 import runpy
 import sys
 import time
+import traceback
 from pathlib import Path
-from typing import List
+from typing import List, Optional, Tuple
 
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 
 # 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"),
+    ("sys_health",     "系统健康（DNS / 网络 / CPU / 内存 / 磁盘 / 进程 / 时间）",  "diag/01_sys_health.py"),
+    ("environment",    "OpenClaw 版本、Gateway 进程环境变量",                       "diag/02_environment.py"),
+    ("configuration",  "openclaw.json 展平（敏感字段脱敏）",                        "diag/03_configuration.py"),
+    ("gateway",        "Gateway 进程、端口、24h 重启、WS 生命周期、错误码",         "diag/04_gateway.py"),
+    ("recent_errors",  "应用日志 / journalctl / session 工具调用错误聚合",           "diag/05_recent_errors.py"),
+    ("cron_jobs",      "定时任务状态、连续失败、调度漂移、静默检测",                "diag/06_cron_jobs.py"),
+    ("performance",    "模型/工具耗时 P50/P95、慢调用、E2E 延迟、Cache 命中率",     "diag/07_performance.py"),
+    ("sessions",       "Session 总览、活跃度、Stuck 探测",                          "diag/08_sessions.py"),
+    ("plugin_diag",    "插件状态一致性、ERROR/WARN、Hook、Channel、外部 DNS",       "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"),
+    ("trace",   "追踪一条用户消息从进入到响应的完整时间轴", "tools/oc_session_trace.py"),
+    ("extract", "导出 session.jsonl 为可读格式",            "tools/oc_session_extract.py"),
 ]
 
 STATE_BY_ID = {mid: (label, script) for mid, label, script in STATE_COLLECTORS}
@@ -46,31 +49,67 @@ MODULE_BY_ID = {**STATE_BY_ID, **OBJECT_BY_ID}
 MODULE_IDS = set(MODULE_BY_ID.keys())
 
 
+def cmd_list_json() -> int:
+    """Machine-readable module catalogue. Single source of truth consumed
+    by the Node shell and the bundle script (axiom #3)."""
+    payload = {
+        "state_collectors": [
+            {"id": mid, "label": label, "script": rel}
+            for mid, label, rel in STATE_COLLECTORS
+        ],
+        "object_inspectors": [
+            {"id": mid, "label": label, "script": rel}
+            for mid, label, rel in OBJECT_INSPECTORS
+        ],
+    }
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
+
+
 def cmd_list() -> int:
-    print("Available diagnostics:")
+    print("openclaw-diag — 可用诊断")
     print()
-    print("  State collectors (no args needed):")
+    print("  扫描类（无需参数）：")
     for mid, label, _ in STATE_COLLECTORS:
         print(f"    {mid:<16s} {label}")
     print()
-    print("  Object inspectors (require session uuid):")
+    print("  对象类（需要 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 单文件")
+    print("  其它命令：")
+    print("    all              一次跑完所有扫描类")
+    print("    doctor           检查 Node / Python / openclaw-diag / OpenClaw 环境")
+    print("    bundle <id>      生成 self-contained 单文件 .py（离线机器用）")
     return 0
 
 
-def run_script(script_rel: str, extra_args: List[str]) -> int:
+def run_script(
+    script_rel: str,
+    extra_args: List[str],
+    module_id: Optional[str] = None,
+) -> int:
+    """Execute a diag script in-process. Returns the rc.
+
+    On crash, in addition to the human-readable stderr trace we emit a single
+    NDJSON error record to stdout when the script was invoked with --json.
+    This guarantees `all --json` produces N records for N modules — including
+    crashes — so downstream parsers don't silently lose modules. (Axiom #4)
+    """
     script_path = REPO_ROOT / script_rel
     if not script_path.is_file():
         print(f"Error: script not found: {script_path}", file=sys.stderr)
         return 2
+    json_mode = "--json" in extra_args
+    mid = module_id or script_path.stem
     saved_argv = sys.argv[:]
+    saved_prog = os.environ.get("OPENCLAW_DIAG_PROG")
     try:
+        # runpy.run_path resets sys.argv[0] to the script path, so we
+        # advertise the user-facing name through an env var instead. cli.py
+        # picks it up as the argparse prog so --help reads as
+        # "openclaw-diag sys_health" rather than "01_sys_health.py".
+        os.environ["OPENCLAW_DIAG_PROG"] = f"openclaw-diag {mid}"
         sys.argv = [str(script_path), *extra_args]
         runpy.run_path(str(script_path), run_name="__main__")
         return 0
@@ -79,14 +118,32 @@ def run_script(script_rel: str, extra_args: List[str]) -> int:
             return int(e.code) if e.code is not None else 0
         except (TypeError, ValueError):
             return 1
-    except Exception as e:
+    except BaseException as e:  # noqa: BLE001 — emit then re-classify
         print(f"  ERROR: {script_path.name} crashed: {type(e).__name__}: {e}",
               file=sys.stderr)
-        import traceback
         traceback.print_exc(file=sys.stderr)
+        if json_mode:
+            err_record = {
+                "module": mid,
+                "status": "error",
+                "error": f"{type(e).__name__}: {e}",
+                "traceback": traceback.format_exc(),
+            }
+            try:
+                sys.stdout.write(json.dumps(err_record, ensure_ascii=False) + "\n")
+                sys.stdout.flush()
+            except Exception:
+                # If stdout itself is broken (closed pipe), there's nothing
+                # productive to do — the stderr trace above already records
+                # the crash.
+                pass
         return 2
     finally:
         sys.argv = saved_argv
+        if saved_prog is None:
+            os.environ.pop("OPENCLAW_DIAG_PROG", None)
+        else:
+            os.environ["OPENCLAW_DIAG_PROG"] = saved_prog
 
 
 def cmd_all(extra_args: List[str], skip_ids: List[str]) -> int:
@@ -101,7 +158,7 @@ def cmd_all(extra_args: List[str], skip_ids: List[str]) -> int:
         n += 1
         print(f"\n[{n}/{total}] {label} ({mid})...", flush=True, file=progress_stream)
         t0 = time.time()
-        rc = run_script(script, extra_args)
+        rc = run_script(script, extra_args, module_id=mid)
         elapsed = time.time() - t0
         print(f"[{n}/{total}] {label} ({mid}) ... done ({elapsed:.1f}s)",
               flush=True, file=progress_stream)
@@ -110,7 +167,27 @@ def cmd_all(extra_args: List[str], skip_ids: List[str]) -> int:
     return rc_overall
 
 
-def _split_skip(rest: List[str]) -> (List[str], List[str]):
+def cmd_bundle(rest: List[str]) -> int:
+    """Generate a self-contained single-file diag script.
+
+    Lives here (rather than in lib/bundle.py only) so the Python entry has
+    parity with Node — `python3 bin/ocdiag bundle gateway` works the same as
+    `node bin/openclaw-diag.js bundle gateway`. (Axiom #3)
+    """
+    if not rest or rest[0] in ("-h", "--help"):
+        print("Usage: openclaw-diag bundle <id>", file=sys.stderr)
+        print("       Emits the bundle to stdout. Use shell redirection to save.", file=sys.stderr)
+        print(file=sys.stderr)
+        print("Available ids:", file=sys.stderr)
+        for mid, _label, _ in STATE_COLLECTORS:
+            print(f"  {mid}", file=sys.stderr)
+        return 0 if rest else 2
+    sys.path.insert(0, str(REPO_ROOT / "lib"))
+    import bundle  # type: ignore
+    return bundle.main(rest)
+
+
+def _split_skip(rest: List[str]) -> Tuple[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] = []
@@ -126,22 +203,30 @@ def _split_skip(rest: List[str]) -> (List[str], List[str]):
     return skip_ids, passthrough
 
 
+def _suggest_command(unknown: str) -> Optional[str]:
+    """Best-effort typo suggestion for a misspelled command."""
+    import difflib
+    candidates = list(MODULE_BY_ID.keys()) + ["all", "list", "doctor", "bundle"]
+    matches = difflib.get_close_matches(unknown, candidates, n=1, cutoff=0.6)
+    return matches[0] if matches else None
+
+
 def print_help() -> None:
-    print("ocdiag — OpenClaw 诊断工具箱")
+    print("openclaw-diag — 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("  openclaw-diag <id> [args...]      跑单个诊断")
+    print("  openclaw-diag all [--skip a,b]    跑全部 state collectors")
+    print("  openclaw-diag list                列出所有诊断")
+    print("  openclaw-diag doctor              检查环境")
+    print("  openclaw-diag bundle <id>         生成单文件 .py")
     print()
-    print("State collectors:")
+    print("扫描类（无需参数）：")
     print("  " + "  ".join(mid for mid, _, _ in STATE_COLLECTORS))
-    print("Object inspectors:")
+    print("对象类（需要 session uuid）：")
     print("  " + "  ".join(mid for mid, _, _ in OBJECT_INSPECTORS))
     print()
-    print("--skip 后接逗号分隔 id 列表（仅对 all 有意义）。")
-    print("其它参数（--config / --log-dir / --json / --no-color）原样传递给脚本。")
+    print("常用 flag：--json（结构化输出）  --no-color（关掉颜色）  --unmask（不脱敏）")
 
 
 def main(argv=None) -> int:
@@ -154,33 +239,35 @@ def main(argv=None) -> int:
     head, rest = argv[0], argv[1:]
 
     if head == "list":
+        if "--json" in rest:
+            return cmd_list_json()
         return cmd_list()
 
+    if head == "doctor":
+        from ocdiag import doctor
+        json_mode = "--json" in rest
+        node_version = None
+        for i, a in enumerate(rest):
+            if a == "--node-version" and i + 1 < len(rest):
+                node_version = rest[i + 1]
+                break
+        return doctor.run(json_mode=json_mode, node_version=node_version)
+
     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, 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 == "bundle":
+        return cmd_bundle(rest)
 
     if head in MODULE_BY_ID:
         _, script = MODULE_BY_ID[head]
-        return run_script(script, rest)
+        return run_script(script, rest, module_id=head)
 
-    print(f"Error: unknown command '{head}'. Use `ocdiag list` to see available diagnostics.",
-          file=sys.stderr)
+    suggestion = _suggest_command(head)
+    hint = f"（你是不是想说 `{suggestion}`？）" if suggestion else ""
+    print(f"Error: 未知命令 '{head}'{hint}", file=sys.stderr)
+    print(f"运行 `openclaw-diag list` 查看全部诊断。", file=sys.stderr)
     return 2
 
 

package/ocdiag/doctor.py

@@ -0,0 +1,162 @@
+"""``ocdiag doctor`` — environment health-check.
+
+Sole authoritative implementation. Both Node (`bin/openclaw-diag.js doctor`)
+and Python (`bin/ocdiag doctor` / `python3 -m ocdiag.doctor`) entry points
+call this function. The Node entry is now a thin spawn wrapper.
+
+Checks:
+  - Python version (>= 3.8)
+  - ocdiag package importable + version
+  - All registered diag scripts respond to ``--help``
+  - openclaw.json exists at expected path
+
+Node version isn't visible from Python so we accept it as a passthrough
+argument; if absent, doctor reports node check as ``skipped``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _node_status(node_version: Optional[str]) -> dict:
+    if not node_version:
+        return {"version": None, "ok": True, "skipped": True,
+                "reason": "Node check is performed by the Node entry; "
+                          "ocdiag is fine without Node when invoked from Python"}
+    # Normalize: accept "v22.22.2" or "22.22.2"
+    normalized = node_version.lstrip("v")
+    try:
+        major = int(normalized.split(".", 1)[0])
+    except ValueError:
+        return {"version": normalized, "ok": False, "reason": "unparseable"}
+    return {"version": normalized, "ok": major >= 18,
+            "required": ">=18"}
+
+
+def _python_status() -> dict:
+    v = sys.version_info
+    return {
+        "version": f"{v.major}.{v.minor}.{v.micro}",
+        "ok": v >= (3, 8),
+        "required": ">=3.8",
+        "executable": sys.executable,
+    }
+
+
+def _ocdiag_status() -> dict:
+    try:
+        import ocdiag  # type: ignore
+        return {"ok": True, "version": getattr(ocdiag, "__version__", "?")}
+    except ImportError as e:
+        return {"ok": False, "error": str(e)[:200]}
+
+
+def _diag_scripts_status() -> dict:
+    from ocdiag.dispatcher import STATE_COLLECTORS, OBJECT_INSPECTORS
+    failed = []
+    all_scripts = []
+    for mid, _label, rel in (*STATE_COLLECTORS, *OBJECT_INSPECTORS):
+        all_scripts.append((mid, REPO_ROOT / rel))
+    for mid, path in all_scripts:
+        if not path.is_file():
+            failed.append({"script": mid, "reason": "missing", "path": str(path)})
+            continue
+        r = subprocess.run(
+            [sys.executable, str(path), "--help"],
+            capture_output=True, text=True, timeout=10, check=False,
+        )
+        if r.returncode != 0:
+            failed.append({
+                "script": mid,
+                "rc": r.returncode,
+                "stderr": (r.stderr or "")[:200],
+            })
+    return {"ok": not failed, "total": len(all_scripts), "failed": failed}
+
+
+def _openclaw_config_status() -> dict:
+    home = os.path.expanduser("~")
+    cfg = os.environ.get("OPENCLAW_CONFIG") or os.path.join(
+        os.environ.get("OPENCLAW_HOME", os.path.join(home, ".openclaw")),
+        "openclaw.json",
+    )
+    return {"path": cfg, "exists": os.path.isfile(cfg)}
+
+
+def run(json_mode: bool = False, node_version: Optional[str] = None) -> int:
+    """Execute the doctor check. Returns rc (0 if everything OK, 1 otherwise)."""
+    result = {
+        "node": _node_status(node_version),
+        "python": _python_status(),
+        "ocdiag": _ocdiag_status(),
+        "diag_scripts": _diag_scripts_status(),
+        "openclaw_config": _openclaw_config_status(),
+    }
+
+    ok = (
+        result["node"].get("ok", True)
+        and result["python"]["ok"]
+        and result["ocdiag"]["ok"]
+        and result["diag_scripts"]["ok"]
+    )
+
+    if json_mode:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        node = result["node"]
+        if node.get("skipped"):
+            print(f"ℹ Node check skipped (run via npx to verify Node version)")
+        elif node["ok"]:
+            print(f"✓ Node v{node['version']}")
+        else:
+            print(f"✗ Node v{node.get('version','?')} (need {node.get('required','?')})")
+
+        py = result["python"]
+        mark = "✓" if py["ok"] else "✗"
+        print(f"{mark} Python {py['version']} ({py['executable']})")
+
+        oc = result["ocdiag"]
+        if oc["ok"]:
+            print(f"✓ ocdiag package importable (version {oc['version']})")
+        else:
+            print(f"✗ ocdiag package not importable: {oc.get('error','?')}")
+
+        ds = result["diag_scripts"]
+        if ds["ok"]:
+            print(f"✓ All {ds['total']} diagnostics respond to --help")
+        else:
+            print(f"✗ {len(ds['failed'])}/{ds['total']} diagnostics failed --help:")
+            for f in ds["failed"]:
+                print(f"    {f.get('script','?')} (rc={f.get('rc','?')})")
+
+        cfg = result["openclaw_config"]
+        if cfg["exists"]:
+            print(f"✓ OpenClaw config present ({cfg['path']})")
+        else:
+            print(f"ℹ OpenClaw config not found ({cfg['path']}) — diagnostics will run but report missing")
+
+    return 0 if ok else 1
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="ocdiag-doctor",
+                                 description="Health-check the ocdiag install + environment")
+    p.add_argument("--json", action="store_true", help="Emit JSON output")
+    p.add_argument("--node-version", default=None,
+                   help="Node version string (e.g. '20.12.1') passed in by the Node "
+                        "shell. Omit when running from Python directly.")
+    args = p.parse_args(argv)
+    return run(json_mode=args.json, node_version=args.node_version)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/ocdiag/jsonlog.py

@@ -58,8 +58,3 @@ def parse_name(obj: Dict[str, Any]) -> Tuple[Optional[str], Optional[str]]:
     return p.get("plugin"), p.get("subsystem")
 
 
-def log_level(obj: Dict[str, Any]) -> str:
-    meta = obj.get("_meta") or {}
-    if isinstance(meta, dict):
-        return meta.get("logLevelName", "") or ""
-    return ""

package/ocdiag/paths.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import os
-from pathlib import Path
 
 
 def _env_path(name: str, default: str) -> str:
@@ -30,19 +29,3 @@ SERVICE_ENV_FILE = _env_path(
     "OPENCLAW_SERVICE_ENV_FILE",
     os.path.join(HOME, ".config", "systemd", "user", "openclaw-gateway.service.d", "env.conf"),
 )
-
-
-def home() -> str:
-    return HOME
-
-
-def config_path() -> str:
-    return CONFIG
-
-
-def log_dir() -> str:
-    return LOG_DIR
-
-
-def sessions_base() -> str:
-    return SESSIONS_BASE

package/ocdiag/recent_logs.py

@@ -48,6 +48,3 @@ def latest_app_log(log_dir: str) -> Optional[str]:
     return matched[0][1]
 
 
-def all_logs(log_dir: str) -> List[str]:
-    pattern = os.path.join(log_dir, "openclaw-*.log")
-    return sorted(glob.glob(pattern))