fix(review-feedback-1003): address latest review comments

Author: ZhuLinsen

docs/CHANGELOG.md

@@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [文档] FAQ 补充 Ollama `OllamaException / APIConnectionError` 连接失败排障条目（Q12c），覆盖服务未启动、URL 配置错误、模型前缀缺失、模型未下载、远程防火墙等 5 个检查点
 - [修复] 技能加载异常被静默吞没问题 — 在 ask.py、skills/aggregator.py、skills/router.py 的静默 except 块补充 logger.warning 日志，确保技能列表为空时有日志可查（fixes #970）
 - [修复] SQLite 主写入链路现在对 `stock_daily(code,date)` 使用批量原子 upsert，并在文件型 SQLite 连接上默认启用 `WAL`、`busy_timeout` 与有限写入重试，降低批量分析和并发回写场景下的锁竞争与吞吐抖动，返回值中的“新增数”改为按本次真正插入窗口计算（并发场景不再把并行写入行误算入当前调用）。
+- [修复] 优化多 Agent 与单 Agent 的预算护栏语义：当后续阶段/步骤剩余预算低于最小阈值（首阶段除外）时会主动跳过并进行降级处理；在已有阶段结果可用于合成仪表盘时返回 `success=True`、`content` 非空的降级结果，若无可恢复输出则返回 `success=False`、`content=""`；同时补齐 `run_agent_loop` 与 `orchestrator` 的边界回归用例，并同步 `ResearchAgent._research_sub_question` 对“预算不足”语义的识别，避免单次子问题在预算耗尽时被静默降为空内容。
 
 ## [3.12.0] - 2026-04-01
 

src/agent/orchestrator.py

@@ -152,6 +152,51 @@ def _build_timeout_result(
             model=model,
         )
 
+    def _build_budget_skip_result(
+        self,
+        stats: AgentRunStats,
+        all_tool_calls: List[Dict[str, Any]],
+        models_used: List[str],
+        elapsed_s: float,
+        timeout_s: int,
+        stage_name: str,
+        remaining_budget: float,
+        min_stage_budget_s: int,
+        ctx: Optional[AgentContext] = None,
+        parse_dashboard: bool = True,
+    ) -> OrchestratorResult:
+        """Build a result for budget-insufficient stage skip (non-timeout semantics)."""
+        stats.total_duration_s = round(elapsed_s, 2)
+        stats.models_used = list(dict.fromkeys(models_used))
+        dashboard = None
+        content = ""
+        if ctx is not None:
+            dashboard, content = self._resolve_final_output(ctx, parse_dashboard=parse_dashboard)
+            if parse_dashboard and dashboard is not None:
+                dashboard = self._mark_partial_dashboard(
+                    dashboard,
+                    note="多 Agent 预算不足，以下结论基于已完成阶段自动降级生成。",
+                )
+                ctx.set_data("final_dashboard", dashboard)
+                content = json.dumps(dashboard, ensure_ascii=False, indent=2)
+
+        return OrchestratorResult(
+            success=bool(content) if (not parse_dashboard or dashboard is not None) else False,
+            content=content,
+            dashboard=dashboard,
+            error=(
+                f"Pipeline skipped before stage '{stage_name}' due to insufficient budget "
+                f"({remaining_budget:.1f}s remaining, minimum {min_stage_budget_s}s required)"
+            ),
+            stats=stats,
+            total_steps=stats.total_stages,
+            total_tokens=stats.total_tokens,
+            tool_calls_log=all_tool_calls,
+            provider=stats.models_used[0] if stats.models_used else "",
+            model=", ".join(stats.models_used),
+        )
+
+
     def _prepare_agent(self, agent: Any) -> Any:
         """Apply orchestrator-level runtime settings to a child agent."""
         if hasattr(agent, "max_steps"):
@@ -313,22 +358,31 @@ def _execute_pipeline(
         # completed so that the first stage always gets a chance to run
         # even when the total budget is small.
         _MIN_STAGE_BUDGET_S = 15
+        _MIN_TOOLLESS_STAGE_BUDGET_S = 0
 
         while index < len(agents):
             agent = agents[index]
             elapsed_s = time.time() - t0
             remaining_budget = timeout_s - elapsed_s if timeout_s else None
-            budget_exhausted = (
+            tool_names = getattr(agent, "tool_names", None)
+            stage_min_budget_s = (
+                _MIN_TOOLLESS_STAGE_BUDGET_S
+                if isinstance(tool_names, (list, tuple, set, frozenset)) and len(tool_names) == 0
+                else _MIN_STAGE_BUDGET_S
+            )
+            timeout_exhausted = (
                 timeout_s
                 and remaining_budget is not None
-                and (
-                    remaining_budget <= 0
-                    or (index > 0 and remaining_budget < _MIN_STAGE_BUDGET_S)
-                )
+                and remaining_budget <= 0
             )
-            if budget_exhausted:
-                reason = "timed out" if remaining_budget <= 0 else f"insufficient budget ({remaining_budget:.1f}s < {_MIN_STAGE_BUDGET_S}s)"
-                logger.error("[Orchestrator] pipeline %s before stage '%s'", reason, agent.agent_name)
+            budget_guard_triggered = (
+                timeout_s
+                and remaining_budget is not None
+                and index > 0
+                and remaining_budget < stage_min_budget_s
+            )
+            if timeout_exhausted:
+                logger.error("[Orchestrator] pipeline timed out before stage '%s'", agent.agent_name)
                 if progress_callback:
                     progress_callback({
                         "type": "pipeline_timeout",
@@ -346,6 +400,33 @@ def _execute_pipeline(
                     parse_dashboard=parse_dashboard,
                 )
 
+            if budget_guard_triggered:
+                logger.warning(
+                    "[Orchestrator] pipeline insufficient budget before stage '%s' (%.1fs remaining, min %ds)",
+                    agent.agent_name,
+                    remaining_budget,
+                    stage_min_budget_s,
+                )
+                if progress_callback:
+                    progress_callback({
+                        "type": "pipeline_timeout",
+                        "stage": agent.agent_name,
+                        "elapsed": round(elapsed_s, 2),
+                        "timeout": timeout_s,
+                    })
+                return self._build_budget_skip_result(
+                    stats,
+                    all_tool_calls,
+                    models_used,
+                    elapsed_s,
+                    timeout_s,
+                    agent.agent_name,
+                    remaining_budget,
+                    stage_min_budget_s,
+                    ctx=ctx,
+                    parse_dashboard=parse_dashboard,
+                )
+
             if (
                 self.mode == "specialist"
                 and agent.agent_name == "decision"

src/agent/research.py

@@ -236,7 +236,12 @@ def _resolve_step_timeout(default_timeout: int, timeout_seconds: Optional[float]
     def _looks_like_timeout_error(error: Any) -> bool:
         """Best-effort detection for timeout-like failures from lower layers."""
         message = str(error or "").lower()
-        return "timed out" in message or "timeout" in message
+        return (
+            "timed out" in message
+            or "timeout" in message
+            or "insufficient budget" in message
+            or "budget too low" in message
+        )
 
     @staticmethod
     def _build_timeout_result(

src/agent/runner.py

@@ -324,6 +324,35 @@ def _build_timeout_result(
     )
 
 
+def _build_budget_guard_result(
+    *,
+    start_time: float,
+    step: int,
+    tool_calls_log: List[Dict[str, Any]],
+    total_tokens: int,
+    provider_used: str,
+    models_used: List[str],
+    messages: List[Dict[str, Any]],
+    remaining_timeout_s: float,
+    min_step_budget_s: float,
+) -> RunLoopResult:
+    elapsed = time.time() - start_time
+    return RunLoopResult(
+        success=False,
+        content="",
+        tool_calls_log=tool_calls_log,
+        total_steps=step,
+        total_tokens=total_tokens,
+        provider=provider_used,
+        models_used=models_used,
+        error=(
+            "Agent step skipped due to insufficient budget: "
+            f"{remaining_timeout_s:.2f}s remaining, minimum {min_step_budget_s:.1f}s required"
+        ),
+        messages=messages,
+    )
+
+
 # ============================================================
 # Core loop
 # ============================================================
@@ -379,23 +408,35 @@ def run_agent_loop(
 
     for step in range(max_steps):
         remaining_timeout = _remaining_timeout_seconds(start_time, max_wall_clock_seconds)
-        budget_exhausted = (
-            remaining_timeout is not None
-            and (
-                remaining_timeout <= 0
-                or (step > 0 and remaining_timeout <= _MIN_STEP_BUDGET_S)
-            )
+        timeout_exhausted = remaining_timeout is not None and remaining_timeout <= 0
+        budget_guard_triggered = (
+            not timeout_exhausted
+            and remaining_timeout is not None
+            and step > 0
+            and remaining_timeout <= _MIN_STEP_BUDGET_S
         )
-        if budget_exhausted:
-            if remaining_timeout <= 0:
-                logger.warning("Agent timed out before step %d", step + 1)
-            else:
+        if timeout_exhausted or budget_guard_triggered:
+            if budget_guard_triggered:
                 logger.warning(
-                    "Agent budget too low for step %d (%.1fs remaining, min %.1fs) — treating as timeout",
+                    "Agent budget too low for step %d (%.1fs remaining, min %.1fs)",
                     step + 1,
                     remaining_timeout,
                     _MIN_STEP_BUDGET_S,
                 )
+                return _build_budget_guard_result(
+                    start_time=start_time,
+                    step=step,
+                    tool_calls_log=tool_calls_log,
+                    total_tokens=total_tokens,
+                    provider_used=provider_used,
+                    models_used=models_used,
+                    messages=messages,
+                    remaining_timeout_s=remaining_timeout,
+                    min_step_budget_s=_MIN_STEP_BUDGET_S,
+                )
+
+            if remaining_timeout <= 0:
+                logger.warning("Agent timed out before step %d", step + 1)
             return _build_timeout_result(
                 start_time=start_time,
                 max_wall_clock_seconds=float(max_wall_clock_seconds),

tests/test_agent_executor.py

@@ -17,7 +17,7 @@
 import sys
 import os
 from dataclasses import dataclass
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
 
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
 
@@ -580,6 +580,38 @@ def _capture_timeout(*_args, **kwargs):
         self.assertGreater(captured["timeout"], 0.0)
         self.assertLessEqual(captured["timeout"], 1.0)
 
+    def test_min_step_budget_skips_followup_llm_call(self):
+        """When step>0 and remaining budget is too small, no extra LLM call should be made."""
+        registry = _make_registry_with_echo()
+        adapter = _make_mock_adapter()
+        adapter.call_with_tools.return_value = LLMResponse(
+            content="Need one tool first.",
+            tool_calls=[ToolCall(id="echo_1", name="echo", arguments={"message": "hello"})],
+            usage={"total_tokens": 10},
+            provider="openai",
+        )
+
+        with patch(
+            "src.agent.runner._remaining_timeout_seconds",
+            side_effect=[9.0, 9.0, 7.5, 7.5],
+        ):
+            result = run_agent_loop(
+                messages=[
+                    {"role": "system", "content": "system"},
+                    {"role": "user", "content": "Analyze"},
+                ],
+                tool_registry=registry,
+                llm_adapter=adapter,
+                max_steps=3,
+                max_wall_clock_seconds=10.0,
+            )
+
+        self.assertFalse(result.success)
+        self.assertIn("insufficient budget", (result.error or "").lower())
+        self.assertEqual(adapter.call_with_tools.call_count, 1)
+        self.assertEqual(len(result.tool_calls_log), 1)
+        self.assertEqual(result.total_steps, 1)
+
 
 # ============================================================
 # Dashboard parsing