fix(coding): 支持窗口预热调试请求

Author: mudssky

.trellis/spec/infra/coding-plan-window-warmer.md

@@ -18,13 +18,15 @@
   - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml`
   - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml --print-next`
   - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml --once --dry-run`
+  - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml --debug-request --plan glm-coding-plan`
 - PM2:
   - `pm2 start ai/coding/window-warmer/window-warmer.pm2.config.cjs`
   - PM2 app name: `coding-window-warmer`
 - Python script:
   - Entry file: `ai/coding/window-warmer/window_warmer.py`
   - Dependency declaration: `ai/coding/window-warmer/pyproject.toml`
   - Locked dependencies: `ai/coding/window-warmer/uv.lock`
+  - SOCKS proxy support: `httpx[socks]` must remain in project dependencies because LiteLLM/OpenAI may route through host proxy environment variables.
   - Helper package: `ai/coding/window-warmer/window_warmer_lib/`
 
 ### 3. Contracts
@@ -65,6 +67,7 @@
 | `api_key_env` configured but missing from env and `env_file` | Warmup is skipped with missing key diagnostic |
 | `health_path` configured but direct target health check fails | Warmup is skipped before completion request |
 | `--dry-run` or `scheduler.dry_run=true` | Docker/API readiness checks and completion request are skipped |
+| `--debug-request --plan <name>` | Sends one real completion request for the named enabled plan and exits |
 | LiteLLM SDK completion fails | Failure is logged without prompt/key/body; retry up to `retry_count` |
 | Multiple plans share the same base time | Each plan remains in the event queue and is executed independently |
 
@@ -87,6 +90,7 @@
 - Unit tests for multiple plans with simultaneous base time remaining independently executable.
 - Config parse tests for multiple `[[plans]]`.
 - Logging regression test asserting real warmups log lifecycle checkpoints without exposing prompt text or API key values.
+- Debug request test asserting `--debug-request` can target one enabled plan without running all plans.
 - SDK call test mocking the local wrapper around `litellm.completion`, asserting:
   - `model` keeps the configured provider-prefixed model.
   - `api_base` is the direct target URL.

ai/coding/window-warmer/README.md

@@ -79,6 +79,16 @@ cd ai/coding/window-warmer
 uv run python window_warmer.py --config window-warmer.toml --once --dry-run
 ```
 
+立即发送一次真实调试请求：
+
+```bash
+cd ai/coding/window-warmer
+uv run python window_warmer.py \
+  --config window-warmer.toml \
+  --debug-request \
+  --plan glm-coding-plan
+```
+
 ## PM2 管理
 
 启动：

ai/coding/window-warmer/pyproject.toml

@@ -3,6 +3,7 @@ name = "coding-window-warmer"
 version = "0.1.0"
 requires-python = ">=3.11"
 dependencies = [
+    "httpx[socks]>=0.27.0",
     "litellm>=1.81.0",
     "python-dotenv>=1.0.0",
 ]

ai/coding/window-warmer/tests/test_window_warmer.py

@@ -341,6 +341,54 @@ def test_read_api_key_falls_back_to_dotenv_file(self) -> None:
 
             self.assertEqual(warmer.read_api_key(config), "sk-from-file")
 
+    def test_run_debug_request_uses_named_enabled_plan(self) -> None:
+        """调试请求应只执行指定的启用 plan。
+
+        Args:
+            None.
+
+        Returns:
+            无返回值。
+        """
+        scheduler = warmer.SchedulerConfig(True, 60, 120, 1, 30, False)
+        first = warmer.parse_plan_config(
+            {
+                "name": "first",
+                "model": "openai/first",
+                "schedule_mode": "fixed_times",
+                "times": ["08:00"],
+            },
+            scheduler,
+        )
+        second = warmer.parse_plan_config(
+            {
+                "name": "second",
+                "model": "openai/second",
+                "schedule_mode": "fixed_times",
+                "times": ["08:00"],
+            },
+            scheduler,
+        )
+        config = warmer.AppConfig(
+            target=warmer.TargetConfig(
+                name="z-ai",
+                base_url="https://open.bigmodel.cn/api/coding/paas/v4",
+                container_name=None,
+                api_key_env=None,
+                env_file=None,
+                health_path=None,
+                request_timeout_seconds=30,
+            ),
+            scheduler=scheduler,
+            plans=(first, second),
+        )
+
+        with patch("window_warmer_lib.runner.warm_plan", return_value=True) as warm_plan:
+            exit_code = warmer.run_debug_request(config, plan_name="second")
+
+        self.assertEqual(exit_code, 0)
+        warm_plan.assert_called_once_with(config, second, dry_run=False)
+
 
 if __name__ == "__main__":
     unittest.main()

ai/coding/window-warmer/uv.lock

@@ -2,7 +2,7 @@
 
 from .config import load_config, parse_config, parse_plan_config
 from .models import AppConfig, PlanConfig, SchedulerConfig, TargetConfig, WarmEvent
-from .runner import print_next_event, run_once, run_watch, warm_plan
+from .runner import print_next_event, run_debug_request, run_once, run_watch, select_plan, warm_plan
 from .scheduler import (
     build_warm_event,
     build_warm_events,
@@ -37,8 +37,10 @@
     "read_api_key",
     "request_json",
     "run_once",
+    "run_debug_request",
     "run_watch",
     "select_next_event",
+    "select_plan",
     "send_warm_completion",
     "warm_plan",
 ]

ai/coding/window-warmer/window_warmer_lib/__init__.py

@@ -11,7 +11,7 @@
 
 from .config import load_config
 from .constants import DEFAULT_CONFIG_NAME
-from .runner import log, print_next_event, run_once, run_watch
+from .runner import log, print_next_event, run_debug_request, run_once, run_watch
 
 
 def default_config_path() -> Path:
@@ -51,6 +51,15 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
         action="store_true",
         help="Send one warmup request for every enabled plan immediately, then exit.",
     )
+    parser.add_argument(
+        "--debug-request",
+        action="store_true",
+        help="Send one real warmup request for a single plan immediately, then exit.",
+    )
+    parser.add_argument(
+        "--plan",
+        help="Plan name for --debug-request. Defaults to the first enabled plan.",
+    )
     parser.add_argument(
         "--print-next",
         action="store_true",
@@ -81,6 +90,8 @@ def main(argv: list[str] | None = None) -> int:
     try:
         if args.print_next:
             return print_next_event(config, rng)
+        if args.debug_request:
+            return run_debug_request(config, plan_name=args.plan)
         if args.once:
             return run_once(config, dry_run=dry_run)
         return run_watch(config, rng, dry_run=dry_run)

ai/coding/window-warmer/window_warmer_lib/cli.py

@@ -12,6 +12,22 @@
 from .target import ensure_target_ready, send_warm_completion
 
 
+def select_plan(config: AppConfig, plan_name: str | None) -> PlanConfig | None:
+    """选择一个启用的 plan。
+
+    Args:
+        config: 应用配置。
+        plan_name: 可选 plan 名称；为空时选择第一个启用 plan。
+
+    Returns:
+        找到时返回 plan，否则返回 None。
+    """
+    enabled_plans = [plan for plan in config.plans if plan.enabled]
+    if plan_name is None:
+        return enabled_plans[0] if enabled_plans else None
+    return next((plan for plan in enabled_plans if plan.name == plan_name), None)
+
+
 def warm_plan(config: AppConfig, plan: PlanConfig, dry_run: bool = False) -> bool:
     """执行单个 plan 的预热请求。
 
@@ -70,6 +86,30 @@ def warm_plan(config: AppConfig, plan: PlanConfig, dry_run: bool = False) -> boo
     return False
 
 
+def run_debug_request(config: AppConfig, plan_name: str | None = None) -> int:
+    """立即发送一次指定 plan 的真实调试请求。
+
+    Args:
+        config: 应用配置。
+        plan_name: 可选 plan 名称；为空时使用第一个启用 plan。
+
+    Returns:
+        调试请求成功返回 0，否则返回 1。
+    """
+    plan = select_plan(config, plan_name)
+    if plan is None:
+        if plan_name is None:
+            log("debug request failed: 没有启用的 plan。")
+        else:
+            log(f"debug request failed: 未找到启用的 plan name={plan_name}")
+        return 1
+
+    log(f"debug request started plan={plan.name}")
+    success = warm_plan(config, plan, dry_run=False)
+    log(f"debug request finished plan={plan.name} success={str(success).lower()}")
+    return 0 if success else 1
+
+
 def run_once(config: AppConfig, dry_run: bool = False) -> int:
     """立即执行所有启用 plan 的预热。