openclaw-diag-cli 1.11.1 → 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/ocdiag/__init__.py

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

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,22 +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 --all-messages     # 一次跑完全部用户消息（每轮一段）
-  openclaw-diag trace 7e9f3b31 -A --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
@@ -344,71 +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("-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)")
-    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
 
@@ -416,7 +544,7 @@ 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()
@@ -545,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:
@@ -618,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)
@@ -629,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.11.1",
+  "version": "1.12.1",
   "description": "OpenClaw observer-only diagnostic CLI. Zero-dependency Python scripts wrapped in Node for npx-friendly install.",
   "keywords": [
     "openclaw",