openclaw-diag-cli 1.10.4 → 1.12.1

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## v1.12.1 — --help / list / examples output switched to English (2026-06-18)
+
+`v1.12.0` made the help comprehensive but in Chinese. This patch translates
+every custom help string surfaced by `--help` (top-level + each subcommand +
+each collector/inspector), `openclaw-diag list`, and `openclaw-diag examples`
+to clear English. argparse framework strings (`usage:`, `options:`, `-h, --help`)
+were already English and are unchanged.
+
+### Changes
+
+Only `ocdiag/main.py` + `tests/test_cli_help.py` are touched. Collectors /
+inspectors business logic, collector `title` attributes, and report rendering
+are untouched.
+
+1. `_COMMAND_DESC` values translated to English; `_desc()` unchanged.
+2. `_common_arguments` group renamed to `"global options"`; every flag
+   (`--config` / `--log-dir` / `--sessions-base` / `--openclaw-home` /
+   `--format` / `--json` / `--no-color` / `--unmask`) carries an English help
+   string. The `channel options` group + `--account` help are also English.
+3. `trace` / `extract` / `panorama` parsers: per-command group headers
+   (`trace options`, `extract options`, `panorama options`), every flag's
+   help text, and the `Examples:` epilog blocks are all English. Description
+   line uses the English `_desc()` only — the Chinese collector `title` no
+   longer leaks into help.
+4. `_print_help()` rewritten in English (intro / Usage / Health checks / Scan
+   diagnostics / Object diagnostics / Helper commands / Global options /
+   Exit codes / More).
+5. `cmd_list` pretty + json outputs are fully English. The json `label` field
+   now mirrors the English description (no Chinese title leak).
+6. `cmd_examples()` translated; example commands themselves are unchanged.
+7. Per-collector `<id> --help` description switched from
+   `f"{coll.title} ({coll.id}) — {desc}"` to `f"{desc} ({coll.id})"` so the
+   Chinese title is never printed.
+8. Error messages: `"Error: 未知 ..."` -> `"Error: unknown ..."` and the
+   "run `openclaw-diag list`..." hint translated.
+
+### Tests
+
+`tests/test_cli_help.py`: every assertion that pinned a Chinese substring is
+swapped to its English equivalent. Test intent is preserved 1:1.
+
+## v1.12.0 — --help 全面改造：命令/参数清晰说明 + 分组 + 退出码 (2026-06-18)
+
+让 `--help`（顶层 + 每个子命令 + 每个 collector/inspector）对**用户和 agent 都
+清晰、明确、直接**。每个命令、每个参数都有一句话说明，零猜测。
+
+### 改动
+
+唯一业务改动文件：`ocdiag/main.py`（外加 `tests/test_cli_help.py` 新增测试）。
+不动 collectors/inspectors 业务逻辑、不动默认路径/参数 default 值。
+
+1. 新增集中式命令描述表 `_COMMAND_DESC`（id → 一句话中文）+ helper `_desc(mid)`，
+   供 `list`、`<id> --help` 的 description、顶层 help 复用，未来新增 collector
+   缺失时回退空串、不报错。
+2. `_common_arguments` 内全局参数放进 `argument group "全局选项 (global options)"`，
+   每个 flag 都补了清晰中文 help（`--config` / `--log-dir` / `--sessions-base` /
+   `--openclaw-home` / `--format` / `--json` / `--no-color` / `--unmask`），路径
+   类参数加 `metavar=PATH` 让 usage 行更整齐。`--account` 同样进 `"channel 选项"`
+   group。
+3. `trace --help` 之前 `--no-trajectory` / `--no-log` / `--show-tool-metas` /
+   `--show-plugin-snapshot` / `--mask` 都是裸 flag，本次补齐每个的中文说明，
+   并把 trace/extract/panorama 的命令专属参数各自放进 `"trace/extract/panorama 选项"`
+   group。
+4. 顶层 `_print_help()` 重写：工具简介 → 用法 → 体检命令 → 扫描类（动态从
+   registry 渲染，对齐排版）→ 对象诊断 → 辅助命令 → 全局选项 → 退出码
+   (0/1/2/3) → 更多。
+5. `cmd_list` pretty 输出每项追加 `— 描述`；`list --format json` 在每项里加
+   `description` 字段，便于 agent / 脚本消费。
+6. 各 collector parser 的 `description` 从 `f"{title} ({id})"` 改为
+   `f"{title} ({id}) — {_desc(id)}"`，`<id> --help` 顶部就能看到一句话简介。
+
+### Tests
+
+`tests/test_cli_help.py` 追加 8 个用例：
+- 顶层 help 含工具简介 / 体检命令 / 扫描类 / 对象诊断 / 辅助命令 / 全局选项 /
+  退出码（含 0/1/2/3）等关键 section 标题。
+- 顶层 help 遍历 registry 断言每个 state collector id 出现，未来新增不漏排。
+- 顶层 help 含 trace/extract/panorama 三个 inspector。
+- `trace --help` 五个之前的裸 flag 都带中文 help 片段，且分组标题 `trace 选项`
+  + description 一句话简介都在。
+- `gateway --help` 含 `全局选项` 分组，`--config` / `--unmask` / `--no-color` /
+  `--log-dir` / `--sessions-base` / `--openclaw-home` 都带中文说明。
+- `gateway --help` description 拼上 `_COMMAND_DESC['gateway']` 一句话片段。
+- `list` pretty 含已知 collector 的描述片段；`list --format json` 每项含
+  `description` key（已登记 id 描述非空）。
+
+`pytest tests/ -q` → 234 passed, 1 skipped。
+
+### 行为不变
+
+- 默认参数值（paths.\*）、各 collector/inspector 业务逻辑、退出码定义、
+  argv 解析顺序、扫描结果与 v1.11.x 完全一致。
+- 之前 215+ 用例全绿；本次只增不改测试。
+
+
 ## v1.10.4 — plugin_diag windowed scan filters to dated-in-window (2026-06-16)
 
 Minimal correctness hardening of the v1.10.2 full-cache reuse. The 7d/30d

package/README.md

@@ -125,6 +125,7 @@ openclaw-diag examples               # Show usage examples
 openclaw-diag trace <uuid>                    # Last user message
 openclaw-diag trace <uuid> --msg-index 0      # First message
 openclaw-diag trace <uuid> --msg-match "deploy"  # Match by content
+openclaw-diag trace <uuid> --all-messages     # Every user turn, one block each
 openclaw-diag trace <uuid> --no-trajectory    # Skip trajectory enrichment
 
 # Extract: dump session content

package/ocdiag/__init__.py

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

package/ocdiag/inspectors/trace.py

@@ -26,6 +26,7 @@ from ..core.types import Report, Section, Verdict
 from ..tracing import (
     analyze_phases,
     build_system_prompt_info,
+    extract_text,
     extract_trace_records,
     find_first_message,
     find_gateway_logs,
@@ -370,6 +371,152 @@ def _section_gateway(s: Section, gw: Dict[str, Any]) -> None:
         )
 
 
+def _user_text_snippet(user_rec: Dict[str, Any], max_chars: int = 80) -> str:
+    """One-line preview of a user message's text content.
+
+    Used in the per-turn meta header when --all-messages is on so the reader
+    can tell turns apart at a glance. Whitespace is collapsed to single
+    spaces; the result is truncated with an ellipsis.
+    """
+    msg = user_rec.get("message") or {}
+    text = extract_text(msg.get("content", "")) or ""
+    text = " ".join(text.split())
+    if len(text) > max_chars:
+        text = text[:max_chars - 1] + "…"
+    return text
+
+
+def _build_turn_sections(
+    report: Report,
+    *,
+    analysis: Dict[str, Any],
+    user_msg_ordinal: int,
+    user_msg_id: str,
+    total_user_msgs: int,
+    turn_label: str,
+    user_snippet: str,
+) -> None:
+    """Append the per-turn timeline / summary / model / tool sections.
+
+    ``turn_label`` is prepended to each section title so multi-turn output
+    keeps the per-turn blocks visually delimited (e.g. ``"Turn #2/5 · "``).
+
+    Per-turn vs session-level enrichment split (see TraceInspector.collect):
+      Per-turn here = timeline + summary + model breakdown + tool breakdown.
+      Trajectory + System Prompt + Gateway are session-scoped (one per file)
+      and are emitted ONCE by the caller, not per turn.
+    """
+    s_meta = report.section(f"{turn_label}Trace · 元信息")
+    s_meta.ok(
+        "user_message",
+        f"user message #{user_msg_ordinal} of {total_user_msgs} "
+        f"(id: {user_msg_id})  {user_snippet}",
+        data={
+            "index": user_msg_ordinal,
+            "id": user_msg_id,
+            "total": total_user_msgs,
+            "snippet": user_snippet,
+        },
+    )
+
+    s_timeline = report.section(f"{turn_label}Trace · 时间轴")
+    _section_timeline(s_timeline, analysis)
+
+    s_summary = report.section(f"{turn_label}Trace · 汇总")
+    _section_summary(s_summary, analysis)
+
+    if analysis["model_calls"]:
+        s_models = report.section(f"{turn_label}Trace · Model 拆解")
+        _section_model_breakdown(s_models, analysis)
+
+    if analysis["tool_execs"]:
+        s_tools = report.section(f"{turn_label}Trace · 工具拆解")
+        _section_tool_breakdown(s_tools, analysis)
+
+    # Slow E2E → WARN. Attach to this turn's summary section so the verdict
+    # surfaces without inventing a new section.
+    total_ms = analysis["summary"]["total_ms"]
+    if total_ms > SLOW_THRESHOLD_MS:
+        s_summary.warn(
+            "trace.slow",
+            f"E2E elapsed {fmt_duration(total_ms)} > "
+            f"{SLOW_THRESHOLD_MS // 1000}s",
+            data={"total_ms": total_ms, "threshold_ms": SLOW_THRESHOLD_MS},
+        )
+
+
+def _section_aggregate(
+    s: Section, per_turn: List[Dict[str, Any]],
+) -> None:
+    """Render the cross-turn summary at the end of an --all-messages run.
+
+    Aggregates totals across every turn (count, cumulative E2E / model /
+    tool time, cumulative tokens) and surfaces any turn whose E2E exceeded
+    SLOW_THRESHOLD_MS as a per-turn WARN line.
+    """
+    n = len(per_turn)
+    total_e2e = sum(t["summary"]["total_ms"] for t in per_turn)
+    total_model = sum(t["summary"]["model_total_ms"] for t in per_turn)
+    total_tool = sum(t["summary"]["tool_total_ms"] for t in per_turn)
+    total_in = sum(t["summary"]["total_input_tokens"] for t in per_turn)
+    total_out = sum(t["summary"]["total_output_tokens"] for t in per_turn)
+    total_cr = sum(t["summary"]["total_cache_read"] for t in per_turn)
+    total_cw = sum(t["summary"]["total_cache_write"] for t in per_turn)
+    total_models = sum(t["summary"]["model_count"] for t in per_turn)
+    total_tools = sum(t["summary"]["tool_count"] for t in per_turn)
+
+    s.ok(
+        "agg.turns", f"Turns: {n}",
+        data={"count": n},
+    )
+    s.ok(
+        "agg.total", f"Cumulative E2E: {fmt_duration(total_e2e)}",
+        data={"total_ms": total_e2e},
+    )
+    s.ok(
+        "agg.model",
+        f"Cumulative model time: {fmt_duration(total_model)} "
+        f"across {total_models} call(s)",
+        data={"total_ms": total_model, "count": total_models},
+    )
+    s.ok(
+        "agg.tool",
+        f"Cumulative tool time: {fmt_duration(total_tool)} "
+        f"across {total_tools} call(s)",
+        data={"total_ms": total_tool, "count": total_tools},
+    )
+    tok_msg = f"Cumulative tokens: in={total_in} out={total_out}"
+    if total_cr:
+        tok_msg += f" cache_read={total_cr}"
+    if total_cw:
+        tok_msg += f" cache_write={total_cw}"
+    s.ok(
+        "agg.tokens", tok_msg,
+        data={
+            "input": total_in,
+            "output": total_out,
+            "cache_read": total_cr,
+            "cache_write": total_cw,
+        },
+    )
+
+    for t in per_turn:
+        if t["summary"]["total_ms"] > SLOW_THRESHOLD_MS:
+            s.warn(
+                f"agg.slow.{t['index']}",
+                f"Turn #{t['index'] + 1} slow: "
+                f"{fmt_duration(t['summary']['total_ms'])} > "
+                f"{SLOW_THRESHOLD_MS // 1000}s "
+                f"(id: {t['user_message_id']})",
+                data={
+                    "index": t["index"],
+                    "user_message_id": t["user_message_id"],
+                    "total_ms": t["summary"]["total_ms"],
+                    "threshold_ms": SLOW_THRESHOLD_MS,
+                },
+            )
+
+
 @register
 class TraceInspector:
     id = "trace"
@@ -402,6 +549,28 @@ class TraceInspector:
             report.elapsed_ms = (time.time() - t0) * 1000
             return report
 
+        # --all-messages is mutually exclusive with the single-turn selectors.
+        # The CLI parser already rejects the combination, but inspectors can
+        # also be called programmatically (tests, future SDK callers); guard
+        # here so the contract holds end-to-end.
+        all_messages = bool(kwargs.get("all_messages"))
+        if all_messages and (
+            kwargs.get("msg_index") is not None
+            or kwargs.get("msg_id") is not None
+            or kwargs.get("msg_match") is not None
+        ):
+            report.error = (
+                "--all-messages cannot be combined with "
+                "--msg-index/--msg-id/--msg-match"
+            )
+            report.diag_error = DiagError(
+                code="INVALID_ARGUMENT",
+                message=report.error,
+                hint="pick either --all-messages OR a single-turn selector",
+            )
+            report.elapsed_ms = (time.time() - t0) * 1000
+            return report
+
         files, candidates = sessions.resolve(
             session_id,
             base_dir=str(ctx.sessions_base),
@@ -466,41 +635,69 @@ class TraceInspector:
             report.elapsed_ms = (time.time() - t0) * 1000
             return report
 
-        rec_idx, user_rec = select_user_message(
-            records,
-            kwargs.get("msg_index"),
-            kwargs.get("msg_id"),
-            kwargs.get("msg_match"),
-        )
-        try:
-            user_msg_ordinal = next(
-                i for i, (ri, _) in enumerate(user_msgs) if ri == rec_idx
+        # ── Pick which user turn(s) to analyze ──
+        # Single-turn (default, or any --msg-* selector) → one analysis.
+        # All-messages → analyze every user turn from find_user_messages.
+        # We still call analyze_phases per turn so each block has its own
+        # base_epoch_ms / timeline / summary identical to a single-turn run.
+        total_user_msgs = len(user_msgs)
+        if all_messages:
+            selected: List[tuple] = list(user_msgs)
+        else:
+            rec_idx, user_rec = select_user_message(
+                records,
+                kwargs.get("msg_index"),
+                kwargs.get("msg_id"),
+                kwargs.get("msg_match"),
             )
-        except StopIteration:
-            user_msg_ordinal = 0
-        user_msg_id = user_rec.get("id", "?")
-        report.data["user_message_index"] = user_msg_ordinal
-        report.data["user_message_id"] = user_msg_id
-
-        trace_records = extract_trace_records(records, rec_idx)
-        analysis = analyze_phases(trace_records)
-        report.data["base_epoch_ms"] = analysis["base_epoch_ms"]
-        report.data["timeline"] = analysis["events"]
-        report.data["model_calls"] = analysis["model_calls"]
-        report.data["tool_execs"] = analysis["tool_execs"]
-        report.data["summary"] = analysis["summary"]
+            selected = [(rec_idx, user_rec)]
+
+        # Run analyze_phases for each selected turn. The first turn's
+        # analysis seeds the session-level enrichment (trajectory / system
+        # prompt / gateway) — those data sources are session-scoped, not
+        # per-turn, so they are computed ONCE using the first turn's
+        # base_epoch_ms (which is the earliest timestamp in selected turns).
+        per_turn_analyses: List[Dict[str, Any]] = []
+        for ordinal, (rec_idx, user_rec) in enumerate(selected):
+            try:
+                turn_index = next(
+                    i for i, (ri, _) in enumerate(user_msgs) if ri == rec_idx
+                )
+            except StopIteration:
+                turn_index = ordinal
+            turn_records = extract_trace_records(records, rec_idx)
+            analysis = analyze_phases(turn_records)
+            per_turn_analyses.append({
+                "index": turn_index,
+                "user_message_id": user_rec.get("id", "?"),
+                "user_record": user_rec,
+                "analysis": analysis,
+            })
+
+        # ── Session-level enrichment (computed once) ──
+        # Trajectory / system prompt / gateway timing reflect properties of
+        # the whole run/file, not a single user turn. Computing them once
+        # keeps cost down on long sessions and avoids duplicating identical
+        # blocks per turn. The base epoch we hand to load_trajectory_info /
+        # load_gateway_timing is the FIRST selected turn's base_epoch_ms;
+        # for single-turn this matches the legacy behaviour exactly, and for
+        # all-messages it puts the trajectory offsets on the same axis as
+        # the first turn block (the most useful anchor point).
+        first_analysis = per_turn_analyses[0]["analysis"]
+        base_epoch_ms = first_analysis["base_epoch_ms"]
 
         traj_info: Optional[Dict[str, Any]] = None
         if not kwargs.get("no_trajectory"):
             traj_path = find_trajectory_file(session_file)
             if traj_path:
-                traj_info = load_trajectory_info(traj_path, analysis["base_epoch_ms"])
+                traj_info = load_trajectory_info(traj_path, base_epoch_ms)
                 if traj_info is not None:
                     _apply_traj_redaction(
                         traj_info,
                         mask=bool(kwargs.get("mask")),
                         show_tool_metas=bool(kwargs.get("show_tool_metas")),
-                        show_plugin_snapshot=bool(kwargs.get("show_plugin_snapshot")),
+                        show_plugin_snapshot=bool(
+                            kwargs.get("show_plugin_snapshot")),
                     )
 
         gw_info: Optional[Dict[str, Any]] = None
@@ -508,15 +705,15 @@ class TraceInspector:
             log_files = find_gateway_logs(str(ctx.log_dir))
             if log_files:
                 gw_info = load_gateway_timing(
-                    log_files, full_session_id, analysis["base_epoch_ms"],
+                    log_files, full_session_id, base_epoch_ms,
                 )
 
         store_report = sessions.lookup_system_prompt_report(
             session_file, full_session_id,
         )
         system_prompt = build_system_prompt_info(store_report, traj_info)
-        if system_prompt is not None and analysis.get("model_calls"):
-            first_call = analysis["model_calls"][0]
+        if system_prompt is not None and first_analysis.get("model_calls"):
+            first_call = first_analysis["model_calls"][0]
             actual_input = (
                 (first_call.get("tokens_in") or 0)
                 + (first_call.get("cache_read") or 0)
@@ -532,58 +729,179 @@ class TraceInspector:
         if system_prompt is not None:
             report.data["systemPrompt"] = system_prompt
 
-        # ── Sections ──
-        s_meta = report.section("Trace · 元信息")
-        s_meta.ok(
-            "session", f"session: {full_session_id}",
-            data={"session_id": full_session_id, "file": session_file},
-        )
-        total_user_msgs = len(user_msgs)
-        msg_hint = (
-            f"user message #{user_msg_ordinal} of {total_user_msgs} (id: {user_msg_id})"
-        )
-        if total_user_msgs > 1:
-            msg_hint += f"  [use --msg-index 0~{total_user_msgs - 1} to select]"
-        s_meta.ok(
-            "user_message", msg_hint,
-            data={"index": user_msg_ordinal, "id": user_msg_id, "total": total_user_msgs},
-        )
-
-        s_timeline = report.section("Trace · 时间轴")
-        _section_timeline(s_timeline, analysis)
-
-        s_summary = report.section("Trace · 汇总")
-        _section_summary(s_summary, analysis)
-
-        if analysis["model_calls"]:
-            s_models = report.section("Trace · Model 拆解")
-            _section_model_breakdown(s_models, analysis)
-
-        if analysis["tool_execs"]:
-            s_tools = report.section("Trace · 工具拆解")
-            _section_tool_breakdown(s_tools, analysis)
-
-        if traj_info:
-            s_traj = report.section("Trace · Trajectory")
-            _section_trajectory(s_traj, traj_info)
+        # ── report.data wiring ──
+        # Single-turn path: keep the legacy keys (timeline, model_calls,
+        # tool_execs, summary, base_epoch_ms, user_message_*) at the top
+        # level so existing JSON consumers see no schema change.
+        # All-messages path: add report.data["all_messages"] (per-turn list)
+        # and report.data["aggregate"] (cumulative). The legacy single-turn
+        # keys are NOT populated in this mode — consumers that asked for
+        # all-messages should read the new keys.
+        if not all_messages:
+            single = per_turn_analyses[0]
+            report.data["base_epoch_ms"] = single["analysis"]["base_epoch_ms"]
+            report.data["timeline"] = single["analysis"]["events"]
+            report.data["model_calls"] = single["analysis"]["model_calls"]
+            report.data["tool_execs"] = single["analysis"]["tool_execs"]
+            report.data["summary"] = single["analysis"]["summary"]
+            report.data["user_message_index"] = single["index"]
+            report.data["user_message_id"] = single["user_message_id"]
+        else:
+            all_msgs_payload: List[Dict[str, Any]] = []
+            for t in per_turn_analyses:
+                a = t["analysis"]
+                all_msgs_payload.append({
+                    "index": t["index"],
+                    "user_message_id": t["user_message_id"],
+                    "user_message_snippet": _user_text_snippet(t["user_record"]),
+                    "base_epoch_ms": a["base_epoch_ms"],
+                    "timeline": a["events"],
+                    "model_calls": a["model_calls"],
+                    "tool_execs": a["tool_execs"],
+                    "summary": a["summary"],
+                })
+            report.data["all_messages"] = all_msgs_payload
+            report.data["aggregate"] = {
+                "turns": len(per_turn_analyses),
+                "total_ms": sum(
+                    t["analysis"]["summary"]["total_ms"]
+                    for t in per_turn_analyses
+                ),
+                "model_total_ms": sum(
+                    t["analysis"]["summary"]["model_total_ms"]
+                    for t in per_turn_analyses
+                ),
+                "tool_total_ms": sum(
+                    t["analysis"]["summary"]["tool_total_ms"]
+                    for t in per_turn_analyses
+                ),
+                "total_input_tokens": sum(
+                    t["analysis"]["summary"]["total_input_tokens"]
+                    for t in per_turn_analyses
+                ),
+                "total_output_tokens": sum(
+                    t["analysis"]["summary"]["total_output_tokens"]
+                    for t in per_turn_analyses
+                ),
+                "total_cache_read": sum(
+                    t["analysis"]["summary"]["total_cache_read"]
+                    for t in per_turn_analyses
+                ),
+                "total_cache_write": sum(
+                    t["analysis"]["summary"]["total_cache_write"]
+                    for t in per_turn_analyses
+                ),
+            }
 
-        if system_prompt:
-            s_sp = report.section("Trace · System Prompt")
-            _section_system_prompt(s_sp, system_prompt)
+        # ── Sections ──
+        if not all_messages:
+            # Single-turn: emit one "session" line under 元信息 followed by
+            # the per-turn block, byte-identical to pre-1.11.0 output.
+            single = per_turn_analyses[0]
+            s_meta = report.section("Trace · 元信息")
+            s_meta.ok(
+                "session", f"session: {full_session_id}",
+                data={"session_id": full_session_id, "file": session_file},
+            )
+            msg_hint = (
+                f"user message #{single['index']} of {total_user_msgs} "
+                f"(id: {single['user_message_id']})"
+            )
+            if total_user_msgs > 1:
+                msg_hint += (
+                    f"  [use --msg-index 0~{total_user_msgs - 1} to select]"
+                )
+            s_meta.ok(
+                "user_message", msg_hint,
+                data={
+                    "index": single["index"],
+                    "id": single["user_message_id"],
+                    "total": total_user_msgs,
+                },
+            )
+            s_timeline = report.section("Trace · 时间轴")
+            _section_timeline(s_timeline, single["analysis"])
+            s_summary = report.section("Trace · 汇总")
+            _section_summary(s_summary, single["analysis"])
+            if single["analysis"]["model_calls"]:
+                s_models = report.section("Trace · Model 拆解")
+                _section_model_breakdown(s_models, single["analysis"])
+            if single["analysis"]["tool_execs"]:
+                s_tools = report.section("Trace · 工具拆解")
+                _section_tool_breakdown(s_tools, single["analysis"])
+
+            if traj_info:
+                s_traj = report.section("Trace · Trajectory")
+                _section_trajectory(s_traj, traj_info)
+            if system_prompt:
+                s_sp = report.section("Trace · System Prompt")
+                _section_system_prompt(s_sp, system_prompt)
+            if gw_info:
+                s_gw = report.section("Trace · Gateway 计时")
+                _section_gateway(s_gw, gw_info)
+
+            total_ms = single["analysis"]["summary"]["total_ms"]
+            if total_ms > SLOW_THRESHOLD_MS:
+                s_summary.warn(
+                    "trace.slow",
+                    f"E2E elapsed {fmt_duration(total_ms)} > "
+                    f"{SLOW_THRESHOLD_MS // 1000}s",
+                    data={
+                        "total_ms": total_ms,
+                        "threshold_ms": SLOW_THRESHOLD_MS,
+                    },
+                )
+        else:
+            # All-messages: a session-wide overview, then per-turn blocks
+            # delimited by a "Turn #i/N" prefix, then session-level
+            # enrichment ONCE, then a final aggregate section.
+            n = len(per_turn_analyses)
+            s_overview = report.section("Trace · 元信息 (全部消息)")
+            s_overview.ok(
+                "session", f"session: {full_session_id}",
+                data={"session_id": full_session_id, "file": session_file},
+            )
+            s_overview.ok(
+                "all_messages",
+                f"tracing all {n} user message(s) in this session",
+                data={"count": n},
+            )
 
-        if gw_info:
-            s_gw = report.section("Trace · Gateway 计时")
-            _section_gateway(s_gw, gw_info)
+            for t in per_turn_analyses:
+                turn_label = f"Turn #{t['index'] + 1}/{total_user_msgs} · "
+                _build_turn_sections(
+                    report,
+                    analysis=t["analysis"],
+                    user_msg_ordinal=t["index"],
+                    user_msg_id=t["user_message_id"],
+                    total_user_msgs=total_user_msgs,
+                    turn_label=turn_label,
+                    user_snippet=_user_text_snippet(t["user_record"]),
+                )
 
-        # Slow E2E → WARN. Add as a synthetic check on the summary section so
-        # the verdict surfaces without inventing a new section.
-        total_ms = analysis["summary"]["total_ms"]
-        if total_ms > SLOW_THRESHOLD_MS:
-            s_summary.warn(
-                "trace.slow",
-                f"E2E elapsed {fmt_duration(total_ms)} > {SLOW_THRESHOLD_MS//1000}s",
-                data={"total_ms": total_ms, "threshold_ms": SLOW_THRESHOLD_MS},
-            )
+            # Session-scoped enrichment is rendered ONCE — emitting it per
+            # turn would duplicate large, identical blocks (system prompt
+            # alone can be 10k+ chars). Title-prefixed with "Session · " so
+            # the reader sees it is run-wide, not turn-specific.
+            if traj_info:
+                s_traj = report.section("Session · Trajectory")
+                _section_trajectory(s_traj, traj_info)
+            if system_prompt:
+                s_sp = report.section("Session · System Prompt")
+                _section_system_prompt(s_sp, system_prompt)
+            if gw_info:
+                s_gw = report.section("Session · Gateway 计时")
+                _section_gateway(s_gw, gw_info)
+
+            s_agg = report.section("Trace · 跨消息汇总")
+            _section_aggregate(s_agg, [
+                {
+                    "index": t["index"],
+                    "user_message_id": t["user_message_id"],
+                    "summary": t["analysis"]["summary"],
+                }
+                for t in per_turn_analyses
+            ])
 
         report.elapsed_ms = (time.time() - t0) * 1000
         return report

package/ocdiag/main.py

@@ -36,6 +36,37 @@ from .render.ndjson import NdjsonRenderer
 _FORMAT_CHOICES = ("pretty", "json", "ndjson")
 
 
+# Centralized command description table (id -> one-line English summary).
+# Reused by `list`, `<id> --help`, and the top-level help. When adding a new
+# collector/inspector, add a row here; missing ids fall back to "" via _desc().
+_COMMAND_DESC = {
+    # Scan-type collectors (state)
+    "channel":        "Scan channel (Feishu/Telegram/etc.) connect + message logs; flag disconnects, expired-discard, auth failures",
+    "configuration":  "Parse key openclaw.json settings (agents/models/plugins/channels) and flag missing or risky values",
+    "cron_jobs":      "List every cron job's full config (schedule/payload/sessionTarget/delivery/enabled); detect no-fire / delivery failures",
+    "doctor":         "Check Node / Python / openclaw-diag / OpenClaw install and versions are ready",
+    "environment":    "Collect host environment, Gateway process, and OpenClaw version basics",
+    "gateway":        "Analyze Gateway process lifecycle logs (start/restart/WS connect/crash)",
+    "performance":    "Measure model-call latency (E2E/TTFT), tool durations, and availability",
+    "plugin_diag":    "Check plugin load status, hook subscriptions, trust gate, and plugin errors",
+    "recent_errors":  "Extract and categorize recent errors/exceptions from logs",
+    "run_health":     "Assess agent run completion rate, stalls, and interruptions",
+    "sessions_diag":  "Scan session.jsonl; count toolCall/toolResult pairing, orphans, anomalies",
+    "shell_history":  "Summarize shell commands the agent has executed",
+    "sys_health":     "Check system-level health: CPU/memory/disk/OOM/processes",
+    "task_health":    "Assess background task (openclaw tasks) status and health",
+    # Object-type inspectors
+    "extract":        "Export a session file to readable form (incl. active/reset/deleted/backup versions)",
+    "panorama":       "360° diagnosis: correlate trajectory + app logs + subtasks + cron",
+    "trace":          "Trace one user message's full lifecycle (prompt->toolCall->toolResult->reply)",
+}
+
+
+def _desc(mid: str) -> str:
+    """Return the one-line English description for a command id, or ""."""
+    return _COMMAND_DESC.get(mid, "")
+
+
 def _paged_print(text: str) -> None:
     """Print text through a pager when stdout is a TTY and output is long.
 
@@ -99,28 +130,53 @@ def _build_context(args) -> DiagContext:
 
 
 def _common_arguments(p: argparse.ArgumentParser) -> None:
-    p.add_argument("--config", default=paths.CONFIG)
-    p.add_argument("--log-dir", default=paths.LOG_DIR)
-    p.add_argument("--sessions-base", default=paths.SESSIONS_BASE)
-    p.add_argument("--openclaw-home", default=paths.OPENCLAW_HOME)
-    p.add_argument(
+    """Register the global options shared by every subcommand, in a dedicated
+    argument group so --help output stays aligned.
+    """
+    g = p.add_argument_group("global options")
+    g.add_argument(
+        "--config", metavar="PATH", default=paths.CONFIG,
+        help="Path to openclaw.json (default: ~/.openclaw/openclaw.json)",
+    )
+    g.add_argument(
+        "--log-dir", metavar="PATH", default=paths.LOG_DIR,
+        help="OpenClaw log directory (default: /tmp/openclaw)",
+    )
+    g.add_argument(
+        "--sessions-base", metavar="PATH", default=paths.SESSIONS_BASE,
+        help="Sessions root directory (default: ~/.openclaw/agents)",
+    )
+    g.add_argument(
+        "--openclaw-home", metavar="PATH", default=paths.OPENCLAW_HOME,
+        help="OpenClaw home directory (default: ~/.openclaw)",
+    )
+    g.add_argument(
         "--format",
         choices=list(_FORMAT_CHOICES),
         default=None,
-        help="Output format (pretty|json|ndjson). Default: pretty.",
+        help="Output format pretty|json|ndjson (default: pretty; json/ndjson suit agents/scripts)",
+    )
+    g.add_argument(
+        "--json", action="store_true",
+        help="Alias for --format json",
+    )
+    g.add_argument(
+        "--no-color", action="store_true",
+        help="Disable ANSI color (use when writing to a file or pipe)",
+    )
+    g.add_argument(
+        "--unmask", action="store_true",
+        help="Do not mask; show raw sensitive content (tokens/message bodies). Masked by default",
     )
-    p.add_argument("--json", action="store_true", help="Alias for --format json.")
-    p.add_argument("--no-color", action="store_true")
-    p.add_argument("--unmask", action="store_true")
 
 
 def _channel_arguments(p: argparse.ArgumentParser) -> None:
-    p.add_argument(
+    g = p.add_argument_group("channel options")
+    g.add_argument(
         "--account", default=None,
         help="Filter channel signals by account substring "
              "(matched against the channel-prefix portion of the message body, "
-             "e.g. ``--account default`` to keep only ``feishu[default]:`` lines). "
-             "Default: no filter.",
+             "e.g. --account default keeps only feishu[default]: lines). Default: no filter",
     )
 
 
@@ -159,63 +215,67 @@ def cmd_list(args) -> int:
     if fmt != "pretty":
         payload = {
             "state_collectors": [
-                {"id": c.id, "label": c.title} for c in state
+                {"id": c.id, "label": _desc(c.id), "description": _desc(c.id)}
+                for c in state
             ],
             "object_inspectors": [
-                {"id": c.id, "label": c.title} for c in inspectors
+                {"id": c.id, "label": _desc(c.id), "description": _desc(c.id)}
+                for c in inspectors
             ],
         }
         print(json.dumps(payload, ensure_ascii=False))
         return 0
-    print("openclaw-diag — 可用诊断 (v2)")
+    print("openclaw-diag — available diagnostics (v2)")
     print()
-    print("  扫描类（无需参数）：")
+    print("  Scan type (no args required):")
     for c in state:
-        print(f"    {c.id:<16s} {c.title}")
+        d = _desc(c.id)
+        print(f"    {c.id:<16s} {d}")
     print()
     if inspectors:
-        print("  对象类（需要 session uuid）：")
+        print("  Object type (require session uuid):")
         for c in inspectors:
-            print(f"    {c.id:<16s} {c.title}")
+            d = _desc(c.id)
+            print(f"    {c.id:<16s} {d}")
         print()
-    print("  其它命令：")
-    print("    all              一次跑完所有扫描类")
-    print("    doctor           检查 Node / Python / openclaw-diag / OpenClaw 环境")
-    print("    examples         打印常用使用示例")
+    print("  Other commands:")
+    print("    all              Run all scan-type diagnostics at once")
+    print("    doctor           Check Node / Python / openclaw-diag / OpenClaw environment")
+    print("    examples         Print common usage examples")
     return 0
 
 
 def cmd_examples() -> int:
-    print("""openclaw-diag — 常用场景
+    print("""openclaw-diag — common scenarios
 
-  # 全面体检
+  # Full health check
   openclaw-diag all
 
-  # JSON 输出（Agent / 脚本）
+  # JSON output (for agents / scripts)
   openclaw-diag all --format json
 
-  # 查 Gateway 状态
+  # Check Gateway status
   openclaw-diag gateway
 
-  # 追踪一条消息的完整生命周期
+  # Trace one message's full lifecycle
   openclaw-diag trace <uuid>
   openclaw-diag trace abc12345 --msg-index 0
 
-  # 导出 session 对话内容
+  # Export session conversation content
   openclaw-diag extract <uuid>
   openclaw-diag extract abc12345 --summary
 
-  # session 全景诊断（关联到 trajectory + 日志 + 子任务 + cron）
+  # Session panorama diagnosis (correlates trajectory + logs + subtasks + cron)
   openclaw-diag panorama <uuid>
   openclaw-diag panorama abc12345 --strict-correlation --format json
 
-  # 模型性能
+  # Model performance
   openclaw-diag performance
 
-  # 定时任务状态
+  # Cron job status
   openclaw-diag cron_jobs
 
-  # jq 快速看 verdict
+  # Quick verdict via jq
   openclaw-diag all --format json | jq '.data.verdict'
 """)
     return 0
@@ -300,7 +360,7 @@ def cmd_all(args, skip_ids: List[str]) -> int:
 def cmd_run_collector(args, mid: str) -> int:
     c = registry.get(mid)
     if c is None:
-        print(f"Error: 未知 collector '{mid}'", file=sys.stderr)
+        print(f"Error: unknown collector '{mid}'", file=sys.stderr)
         return EXIT_INPUT_ERROR
     ctx = _build_context(args)
     t0 = time.time()
@@ -319,21 +379,22 @@ def cmd_run_collector(args, mid: str) -> int:
     return _exit_code(report)
 
 
-_TRACE_EPILOG = """示例:
-  openclaw-diag trace 7e9f3b31                    # 该 session 最后一条用户消息
-  openclaw-diag trace 7e9f3b31 --msg-index 0      # 第一条
-  openclaw-diag trace 7e9f3b31 --msg-match deploy # 按内容匹配
-  openclaw-diag trace 7e9f3b31 --format json      # JSON 输出
+_TRACE_EPILOG = """Examples:
+  openclaw-diag trace 7e9f3b31                    # last user message in the session
+  openclaw-diag trace 7e9f3b31 --msg-index 0      # the first one
+  openclaw-diag trace 7e9f3b31 --msg-match deploy # match by content
+  openclaw-diag trace 7e9f3b31 --all-messages     # trace every user message in one run (one block per turn)
+  openclaw-diag trace 7e9f3b31 -A --format json   # all user messages, JSON output
 """
 
-_EXTRACT_EPILOG = """示例:
-  openclaw-diag extract 7e9f3b31              # 默认导出 active 文件
-  openclaw-diag extract 7e9f3b31 --summary    # 只看统计
-  openclaw-diag extract 7e9f3b31 --all        # 含 reset / deleted / backup
+_EXTRACT_EPILOG = """Examples:
+  openclaw-diag extract 7e9f3b31              # export the active file by default
+  openclaw-diag extract 7e9f3b31 --summary    # stats only
+  openclaw-diag extract 7e9f3b31 --all        # include reset / deleted / backup
   openclaw-diag extract 7e9f3b31 --format json
 """
 
-_PANORAMA_EPILOG = """示例:
+_PANORAMA_EPILOG = """Examples:
   openclaw-diag panorama 7e9f3b31                       # latest run
   openclaw-diag panorama 7e9f3b31 --all-runs            # every run
   openclaw-diag panorama 7e9f3b31 --run-index 0         # first run
@@ -343,67 +404,139 @@ _PANORAMA_EPILOG = """示例:
 
 
 def _build_trace_parser() -> argparse.ArgumentParser:
+    desc_text = _desc("trace")
+    description = f"{desc_text} (trace)" if desc_text else "(trace)"
     p = argparse.ArgumentParser(
         prog="openclaw-diag trace",
+        description=description,
         add_help=True,
         epilog=_TRACE_EPILOG,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    p.add_argument("session_id", help="Session UUID (full or 8+ char prefix)")
-    p.add_argument("--msg-index", type=int, default=None,
-                   help="Nth user message (0-based)")
-    p.add_argument("--msg-id", default=None, help="Message by id field")
-    p.add_argument("--msg-match", default=None,
-                   help="First user message containing TEXT")
-    p.add_argument("--no-trajectory", action="store_true")
-    p.add_argument("--no-log", action="store_true")
-    p.add_argument("--show-tool-metas", action="store_true")
-    p.add_argument("--show-plugin-snapshot", action="store_true")
-    p.add_argument("--mask", action="store_true")
-    p.add_argument("--agent", default=None, help="Limit to specific agent")
+    g = p.add_argument_group("trace options")
+    g.add_argument(
+        "session_id",
+        help="Target session UUID (full or 8+ char prefix)",
+    )
+    g.add_argument(
+        "--msg-index", type=int, default=None,
+        help="Nth user message (0-based)",
+    )
+    g.add_argument(
+        "--msg-id", default=None,
+        help="User message by id field",
+    )
+    g.add_argument(
+        "--msg-match", default=None,
+        help="First user message containing TEXT",
+    )
+    g.add_argument(
+        "-A", "--all-messages", action="store_true", dest="all_messages",
+        help="Trace every user message in the session "
+             "(mutually exclusive with --msg-index/--msg-id/--msg-match)",
+    )
+    g.add_argument(
+        "--no-trajectory", action="store_true",
+        help="Do not read trajectory.jsonl; analyze from session.jsonl only",
+    )
+    g.add_argument(
+        "--no-log", action="store_true",
+        help="Do not correlate openclaw application logs",
+    )
+    g.add_argument(
+        "--show-tool-metas", action="store_true",
+        help="Show full meta for each toolCall",
+    )
+    g.add_argument(
+        "--show-plugin-snapshot", action="store_true",
+        help="Show plugin snapshot (hooks/status)",
+    )
+    g.add_argument(
+        "--mask", action="store_true",
+        help="Force masking (trace does not mask by default)",
+    )
+    g.add_argument(
+        "--agent", default=None,
+        help="Limit to a specific agent",
+    )
     _common_arguments(p)
     return p
 
 
 def _build_extract_parser() -> argparse.ArgumentParser:
+    desc_text = _desc("extract")
+    description = f"{desc_text} (extract)" if desc_text else "(extract)"
     p = argparse.ArgumentParser(
         prog="openclaw-diag extract",
+        description=description,
         add_help=True,
         epilog=_EXTRACT_EPILOG,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    p.add_argument("session_id", help="Session UUID (full or 8+ char prefix)")
-    p.add_argument("--summary", action="store_true",
-                   help="Per-file record-count summary, no record dump")
-    p.add_argument("-a", "--all", action="store_true", dest="all_versions",
-                   help="Extract all versions (active + reset + deleted + backup)")
-    p.add_argument("--list", action="store_true", dest="list_only",
-                   help="List matching files; do not extract")
-    p.add_argument("--types", default=None,
-                   help="Filter by record type (comma-separated)")
-    p.add_argument("--agent", default=None, help="Limit to specific agent")
+    g = p.add_argument_group("extract options")
+    g.add_argument(
+        "session_id",
+        help="Target session UUID (full or 8+ char prefix)",
+    )
+    g.add_argument(
+        "--summary", action="store_true",
+        help="Per-file record-count summary; do not dump record bodies",
+    )
+    g.add_argument(
+        "-a", "--all", action="store_true", dest="all_versions",
+        help="Export all versions (active + reset + deleted + backup)",
+    )
+    g.add_argument(
+        "--list", action="store_true", dest="list_only",
+        help="List matching files only; do not extract content",
+    )
+    g.add_argument(
+        "--types", default=None,
+        help="Filter by record type (comma-separated, e.g. user,assistant,toolCall)",
+    )
+    g.add_argument(
+        "--agent", default=None,
+        help="Limit to a specific agent",
+    )
     _common_arguments(p)
     return p
 
 
 def _build_panorama_parser() -> argparse.ArgumentParser:
+    desc_text = _desc("panorama")
+    description = f"{desc_text} (panorama)" if desc_text else "(panorama)"
     p = argparse.ArgumentParser(
         prog="openclaw-diag panorama",
+        description=description,
         add_help=True,
         epilog=_PANORAMA_EPILOG,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    p.add_argument("session_id", help="Session UUID (full or 8+ char prefix)")
-    p.add_argument("--mask", action="store_true",
-                   help="Sanitize tool args / message content / api keys")
-    p.add_argument("--run-index", type=int, default=None,
-                   help="Pick the Nth run (default: -1 = latest)")
-    p.add_argument("--all-runs", action="store_true",
-                   help="Include every run in the session")
-    p.add_argument("--strict-correlation", action="store_true",
-                   help="Match only on sessionId / runIds (drops sessionKey "
-                        "and toolCallId hits)")
-    p.add_argument("--agent", default=None, help="Limit to specific agent")
+    g = p.add_argument_group("panorama options")
+    g.add_argument(
+        "session_id",
+        help="Target session UUID (full or 8+ char prefix)",
+    )
+    g.add_argument(
+        "--mask", action="store_true",
+        help="Sanitize tool args / message content / api keys",
+    )
+    g.add_argument(
+        "--run-index", type=int, default=None,
+        help="Pick the Nth run (default: -1 = latest)",
+    )
+    g.add_argument(
+        "--all-runs", action="store_true",
+        help="Include every run in the session",
+    )
+    g.add_argument(
+        "--strict-correlation", action="store_true",
+        help="Match only on sessionId / runIds (drop sessionKey and toolCallId hits)",
+    )
+    g.add_argument(
+        "--agent", default=None,
+        help="Limit to a specific agent",
+    )
     _common_arguments(p)
     return p
 
@@ -411,16 +544,29 @@ def _build_panorama_parser() -> argparse.ArgumentParser:
 def cmd_inspector(head: str, rest: List[str]) -> int:
     inspector = registry.get(head)
     if inspector is None or inspector.kind != "inspector":
-        print(f"Error: 未知 inspector '{head}'", file=sys.stderr)
+        print(f"Error: unknown inspector '{head}'", file=sys.stderr)
         return EXIT_INPUT_ERROR
     if head == "trace":
         parser = _build_trace_parser()
         ns = parser.parse_args(rest)
+        # --all-messages traces every user turn; it is mutually exclusive with
+        # the single-turn selectors. Reject the combination at parse time so
+        # the inspector never sees an ambiguous request.
+        if ns.all_messages and (
+            ns.msg_index is not None
+            or ns.msg_id is not None
+            or ns.msg_match is not None
+        ):
+            parser.error(
+                "--all-messages/-A cannot be combined with "
+                "--msg-index/--msg-id/--msg-match",
+            )
         kwargs = {
             "session_id": ns.session_id,
             "msg_index": ns.msg_index,
             "msg_id": ns.msg_id,
             "msg_match": ns.msg_match,
+            "all_messages": ns.all_messages,
             "no_trajectory": ns.no_trajectory,
             "no_log": ns.no_log,
             "show_tool_metas": ns.show_tool_metas,
@@ -527,19 +673,61 @@ def _split_skip(rest: List[str]):
 
 
 def _print_help() -> None:
-    print(f"openclaw-diag v{__version__} (v2)")
-    print()
-    print("用法：")
-    print("  openclaw-diag <id> [args...]      跑单个诊断")
-    print("  openclaw-diag all [--skip a,b]    跑全部 state collectors")
-    print("  openclaw-diag list [--format X]   列出所有诊断")
-    print("  openclaw-diag doctor              检查环境")
-    print("  openclaw-diag trace <uuid>        追踪一条用户消息")
-    print("  openclaw-diag extract <uuid>      导出 session 为可读格式")
-    print("  openclaw-diag panorama <uuid>     360° session 全景诊断")
-    print("  openclaw-diag examples            打印常用示例")
-    print()
-    print("通用 flag：--format pretty|json|ndjson  --json (alias)  --no-color  --unmask  --version")
+    """Render the top-level --help.
+
+    Structure: intro -> usage -> health checks -> scan diagnostics (rendered
+    dynamically from the registry) -> object diagnostics -> helper commands
+    -> global options -> exit codes -> more. Scan-list ids/descriptions are
+    pulled from registry + _COMMAND_DESC so newly registered collectors are
+    never missed.
+    """
+    state_ids = [c.id for c in registry.all_state()]
+    width = 16
+    lines: List[str] = []
+    lines.append(f"openclaw-diag v{__version__} — OpenClaw operations diagnostics CLI")
+    lines.append("")
+    lines.append("Scans config / logs / sessions to pinpoint connection, performance, cron,")
+    lines.append("plugin, and run issues in an OpenClaw deployment.")
+    lines.append("")
+    lines.append("Usage:")
+    lines.append("  openclaw-diag <command> [args...]")
+    lines.append("  openclaw-diag <command> --help     Show detailed args for a command")
+    lines.append("")
+    lines.append("Health checks:")
+    lines.append(f"  {'all':<{width}s}Run every scan-type diagnostic at once (recommended first step)")
+    lines.append(f"  {'doctor':<{width}s}Check the runtime (Node / Python / OpenClaw readiness)")
+    lines.append("")
+    lines.append("Scan diagnostics (no args required):")
+    for sid in state_ids:
+        if sid == "doctor":
+            # doctor is already listed under Health checks; skip the duplicate.
+            continue
+        lines.append(f"  {sid:<{width}s}{_desc(sid)}")
+    lines.append("")
+    lines.append("Object diagnostics (require a session uuid):")
+    lines.append(f"  {'trace <uuid>':<{width}s}{_desc('trace')}")
+    lines.append(f"  {'extract <uuid>':<{width}s}{_desc('extract')}")
+    lines.append(f"  {'panorama <uuid>':<{width}s}{_desc('panorama')}")
+    lines.append("")
+    lines.append("Helper commands:")
+    lines.append(f"  {'list':<{width}s}List all available diagnostics (supports --format json)")
+    lines.append(f"  {'examples':<{width}s}Print common usage examples")
+    lines.append("")
+    lines.append("Global options (all commands):")
+    lines.append("  --format pretty|json|ndjson   Output format (default: pretty)")
+    lines.append("  --json                        Alias for --format json")
+    lines.append("  --no-color                    Disable colored output")
+    lines.append("  --unmask                      Show raw (unmasked) sensitive content")
+    lines.append("  --config / --log-dir / --sessions-base / --openclaw-home   Override default paths")
+    lines.append("")
+    lines.append("Exit codes:")
+    lines.append("  0  OK (no warn/fail)")
+    lines.append("  1  Warn or fail present")
+    lines.append("  2  Input error (bad args/uuid)")
+    lines.append("  3  Runtime error")
+    lines.append("")
+    lines.append("More: `openclaw-diag list` for all diagnostics, `openclaw-diag <command> --help` for details.")
+    print("\n".join(lines))
 
 
 def main(argv: Optional[List[str]] = None) -> int:
@@ -600,9 +788,11 @@ def main(argv: Optional[List[str]] = None) -> int:
         # parse_known_args (which would otherwise execute the diagnostic).
         # parse_known_args is preserved to keep the existing lenient handling
         # of unrecognized flags from external callers.
+        d = _desc(coll.id)
+        desc = f"{d} ({coll.id})" if d else f"({coll.id})"
         cparser = argparse.ArgumentParser(
             prog=f"openclaw-diag {head}",
-            description=f"{coll.title} ({coll.id})",
+            description=desc,
             add_help=True,
         )
         _common_arguments(cparser)
@@ -611,8 +801,8 @@ def main(argv: Optional[List[str]] = None) -> int:
         args, _ = cparser.parse_known_args(rest)
         return cmd_run_collector(args, head)
 
-    print(f"Error: 未知命令 '{head}'", file=sys.stderr)
-    print("运行 `openclaw-diag list` 查看全部诊断。", file=sys.stderr)
+    print(f"Error: unknown command '{head}'", file=sys.stderr)
+    print("Run `openclaw-diag list` to see all diagnostics.", file=sys.stderr)
     return EXIT_INPUT_ERROR
 
 

package/package.json

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