feat: main.py 支持 -h/--help 瞬时退出

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## [Unreleased]
 
+### 新增
+
+- **``main.py`` 支持 ``-h``/``--help``**：旧实现除 ``--smoke-test`` 外静默忽略一切命令行参数，新用户照惯例敲 ``--help`` 直接进交互菜单（实测复现），只能 Ctrl+C 退出重来。现在 ``-h``/``--help`` 在初始化依赖之前打印用法（``--smoke-test``、无参数行为说明）并瞬时退出；回归测试红/绿验证。
+
 ### 修复
 
 - **外部模型（codex）全 diff 复核收口 2 处**（九轮 agents 之外的独立视角，逐条探针核实均属实）：

main.py

@@ -371,6 +371,16 @@ def run_cli(argv: list[str] | None = None) -> int:
     import 期的失败由 ``get_settings`` 的边界负责（此处尚未执行）。
     """
     args = list(sys.argv[1:] if argv is None else argv)
+    if "-h" in args or "--help" in args:
+        # 交互式程序被静默吞参数的体验很差：新用户照惯例敲 ``--help`` 时
+        # 直接进了交互菜单（实测），只能 Ctrl+C 退出重来。给出简明用法
+        # 后退出，不初始化依赖（``--help`` 必须瞬时返回）。
+        console.print(markup_text("PyRAG-Kit {}", VERSION))
+        console.print("用法: python main.py [选项]")
+        console.print("  --smoke-test   非交互式启动自检（构建验证用）")
+        console.print("  -h, --help     显示本帮助并退出")
+        console.print("  无参数          进入交互式菜单（向量化 / 召回测试 / 聊天）")
+        return 0
     try:
         if "--smoke-test" in args:
             return run_smoke_test()

tests/test_main_entry.py

@@ -334,3 +334,26 @@ def split(self, documents):
 def test_splitter_self_check_passes_in_real_environment():
     """正常环境下真实分片器必须产出分片（守卫的绿色一侧）。"""
     main._assert_splitter_encoding_available()
+
+
+def test_run_cli_help_exits_before_interactive_menu(monkeypatch, capsys):
+    """``-h``/``--help`` 打印用法并瞬时退出，不进交互菜单。
+
+    旧实现除 ``--smoke-test`` 外静默忽略一切参数（实测 ``--help`` 直接进
+    交互菜单），新用户只能 Ctrl+C 退出重来。
+    """
+    called = {"main": 0, "smoke": 0}
+
+    monkeypatch.setattr(main, "main", lambda: called.__setitem__("main", 1))
+    monkeypatch.setattr(main, "run_smoke_test", lambda: called.__setitem__("smoke", 1))
+
+    for flag in ("-h", "--help"):
+        called.update(main=0, smoke=0)
+        result = main.run_cli([flag])
+
+        assert result == 0
+        assert called["main"] == 0  # 未进交互菜单
+        assert called["smoke"] == 0  # 未误触发自检
+        output = capsys.readouterr().out
+        assert "用法" in output
+        assert "--smoke-test" in output