mtsa-agent 0.3.0__py3-none-any.whl

mtsa/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""通用时序分析引擎：与场景解耦的导入、质量、预处理、指标、频域、检验、异常、图表与报告。"""

mtsa/agent_guards.py

@@ -0,0 +1,142 @@
+# -*- coding: utf-8 -*-
+"""决策安全边界（T2.4）：模型能选什么、不能改什么、越界几次后停下。
+
+设计原则
+--------
+1. **边界独立于运行时**。运行时只负责循环；「动作是否合法」由本模块判断，
+   这样规则可以被单独测试，也不会随着提示词改动而漂移。
+2. **拒绝必须有理由，且理由要回灌模型**。只返回 False 会让模型反复尝试同一动作。
+3. **拒绝要留痕**。每次越界记录 kind、动作、步序与说明，供报告与后续指标统计。
+4. **失败可重试一次**。工具失败可能是瞬时的；但成功或 skipped 的工具不得重复，
+   否则会白白消耗步数与 token。
+
+边界只覆盖「选择」：不改参数、不改数据、不改计算。锁定的标定参数直接拒绝，
+未知参数也拒绝——静默忽略会让模型误以为参数生效。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Sequence
+
+from .planner import PARAM_LOCKED
+
+# 越界类型。报告与指标按这个分类统计，不靠自由文本解析。
+VIOLATION_TOOL_NOT_ALLOWED = "tool_not_allowed"
+VIOLATION_DUPLICATE = "duplicate_tool"
+VIOLATION_LOCKED_PARAM = "locked_parameter"
+VIOLATION_UNKNOWN_ARG = "unknown_argument"
+VIOLATION_STEP_BUDGET = "step_budget"
+
+
+@dataclass(frozen=True)
+class GuardPolicy:
+    """一次运行的硬边界。"""
+
+    allowed_tools: tuple[str, ...]
+    max_steps: int = 8
+    max_consecutive_violations: int = 3
+    # 失败工具允许重试的次数。成功或 skipped 的工具不允许重复。
+    max_retries_per_tool: int = 1
+    locked_parameters: frozenset[str] = field(default_factory=lambda: frozenset(PARAM_LOCKED))
+    # 当前工具全部从计划取参数，因此默认不接受任何入参。
+    accepts_args: bool = False
+
+
+@dataclass
+class GuardDecision:
+    allowed: bool
+    kind: str = "ok"
+    detail: str = ""
+    is_retry: bool = False
+
+
+class ActionGuard:
+    """按策略检查动作，并累计越界与重试统计。"""
+
+    def __init__(self, policy: GuardPolicy) -> None:
+        self.policy = policy
+        self.violations: list[dict[str, Any]] = []
+        self._consecutive = 0
+        self._retries: dict[str, int] = {}
+        self._ok: dict[str, int] = {}
+
+    @property
+    def consecutive_violations(self) -> int:
+        return self._consecutive
+
+    def retry_count(self, tool: str) -> int:
+        """某个工具已用掉的重试次数（运行时判断「已失败且无法再试」时需要）。"""
+        return self._retries.get(tool, 0)
+
+    def check(self, action: str, args: Mapping[str, Any],
+              results: Mapping[str, Any], step_index: int) -> GuardDecision:
+        """判断动作是否可执行。results 为 tool -> ToolResult（含 outcome）。"""
+        if step_index >= self.policy.max_steps:
+            return GuardDecision(False, VIOLATION_STEP_BUDGET,
+                                 f"已达步数上限 {self.policy.max_steps}，只能结束")
+
+        if action not in self.policy.allowed_tools:
+            return GuardDecision(
+                False, VIOLATION_TOOL_NOT_ALLOWED,
+                f"工具 {action} 不在本场景白名单中，可选：{list(self.policy.allowed_tools)}")
+
+        params = dict(args or {})
+        locked = sorted(set(params) & set(self.policy.locked_parameters))
+        if locked:
+            return GuardDecision(
+                False, VIOLATION_LOCKED_PARAM,
+                f"参数 {locked} 属于已标定参数，禁止模型修改；如需调整请用 --param 显式覆盖")
+        if params and not self.policy.accepts_args:
+            return GuardDecision(
+                False, VIOLATION_UNKNOWN_ARG,
+                f"{action} 不接受参数，实际收到 {sorted(params)}")
+
+        prev = results.get(action)
+        if prev is not None:
+            if getattr(prev, "outcome", None) == "failed":
+                used = self._retries.get(action, 0)
+                if used < self.policy.max_retries_per_tool:
+                    return GuardDecision(True, "retry", f"{action} 上次失败，允许重试一次",
+                                         is_retry=True)
+                return GuardDecision(
+                    False, VIOLATION_DUPLICATE,
+                    f"{action} 已重试 {used} 次仍失败，不得继续重复调用")
+            return GuardDecision(
+                False, VIOLATION_DUPLICATE,
+                f"{action} 已执行过（{getattr(prev, 'outcome', 'ok')}），不得重复调用")
+
+        return GuardDecision(True)
+
+    def record_violation(self, decision: GuardDecision, action: str, step_index: int) -> None:
+        self._consecutive += 1
+        self.violations.append({
+            "step": step_index, "action": action,
+            "kind": decision.kind, "detail": decision.detail,
+        })
+
+    def record_execution(self, action: str, outcome: str, is_retry: bool = False) -> None:
+        if is_retry:
+            self._retries[action] = self._retries.get(action, 0) + 1
+        if outcome in ("ok", "skipped"):
+            self._consecutive = 0
+            self._ok[action] = self._ok.get(action, 0) + 1
+
+    def stats(self) -> dict[str, Any]:
+        by_kind: dict[str, int] = {}
+        for v in self.violations:
+            by_kind[v["kind"]] = by_kind.get(v["kind"], 0) + 1
+        return {
+            "violations": len(self.violations),
+            "by_kind": by_kind,
+            "consecutive_violations": self._consecutive,
+            "retries": dict(self._retries),
+            "ok_executions": dict(self._ok),
+            "policy": {
+                "allowed_tools": list(self.policy.allowed_tools),
+                "max_steps": self.policy.max_steps,
+                "max_consecutive_violations": self.policy.max_consecutive_violations,
+                "max_retries_per_tool": self.policy.max_retries_per_tool,
+                "locked_parameters": sorted(self.policy.locked_parameters),
+                "accepts_args": self.policy.accepts_args,
+            },
+        }

mtsa/agent_runtime.py

@@ -0,0 +1,527 @@
+# -*- coding: utf-8 -*-
+"""Agent 运行时：观察—决策—行动循环。
+
+与计划层的区别
+--------------
+M1 的计划层是**一次性规划**：看完数据摘要就定下 12 个分析项，之后代码按固定
+顺序执行，模型看不到任何中间结果。本模块改为**逐步决策**：每执行完一个工具，
+就把结果摘要回灌给模型，由它决定下一步做什么，或宣布结束。
+
+这才是「流程长度由模型决定」的落点。计划层仍在准备阶段产出基底计划
+（场景、目标列、参数），但分析层走哪几个工具、什么顺序，由这里的循环决定。
+
+边界
+----
+1. **只编排白名单内的分析工具**。数据管道（导入至清洗）与收尾（图表至报告）不进
+   循环：前者有严格前置依赖，后者需聚合全部结果。本轮天气场景白名单为五个工具，
+   股票专属的 `check_lookahead` 不在其中。
+2. **数值不经模型**。模型只看到 `ToolResult.summary`，看不到 `data`。
+3. **失败可重试一次**。工具失败后，模型可以在下一步重试同一工具；成功或 skipped
+   的工具不得重复。边界由 `agent_guards.ActionGuard` 判定并留痕。
+
+终止条件
+--------
+| 原因 | 触发 |
+| --- | --- |
+| `model_finished` | 模型输出 `finish` |
+| `max_steps` | 步数达上限 |
+| `idle_loop` | 连续被拒次数达上限（反复选已执行或无效工具） |
+| `decision_error` | 模型输出连续无法解析 |
+| `scope_unmet` | guided 模式下反复要求结束，而下限始终未覆盖 |
+| `budget_exhausted` | guided 模式下限之外的追加步数已用尽，模型仍要求追加 |
+| `token_budget` | 累计 token 达到 `agent_max_tokens`，在下次模型调用前停止 |
+
+范围下限（T2.11）
+----------------
+`guided`（默认）先用关键词把「这个问题至少要做什么」算成下限，再让模型决定顺序：
+
+- 下限未覆盖时 `finish` 被拒绝（`scope_incomplete`），并告知缺哪几个工具；
+- 下限之外最多追加 `max_extra_steps`（默认 1）步，超出记 `scope_exceeded` 并结束（不计入越界）；
+- 下限工具若失败且重试用尽，允许结束——否则会空转到 `max_steps`，把
+  「做不到」伪装成「没做完」。
+
+`free` 保留 T2.2 的原始语义（范围完全由模型判断）。两种模式的步数分布都在
+T2.11 里实测，没有用推断代替测量。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+
+from . import tools
+from .agent_guards import ActionGuard, GuardPolicy
+from .llm_client import LLMError
+from .observation import build_observation
+from .scope import ScopeFloor, describe, infer_floor
+
+TERMINATE_MODEL_FINISHED = "model_finished"
+TERMINATE_MAX_STEPS = "max_steps"
+TERMINATE_IDLE = "idle_loop"
+TERMINATE_DECISION_ERROR = "decision_error"
+# 下限始终未覆盖、且模型反复要求结束时使用。与 max_steps 分开，才能区分
+# 「步数用尽」和「该做的一直没做」。
+TERMINATE_SCOPE_UNMET = "scope_unmet"
+# 下限外步数预算用尽：模型仍想追加工具。此时再问一次也不可能获批，
+# 直接结束，避免白花 3 次模型调用并让终止原因在 idle_loop 与 model_finished 之间抖动。
+TERMINATE_BUDGET = "budget_exhausted"
+# 累计 token 达到上限。与 budget_exhausted（步数预算）区分：一个是「步数」，
+# 一个是「成本」，报告与统计不能混为一谈。
+TERMINATE_TOKEN_BUDGET = "token_budget"
+
+# guided：下限由问题关键词确定，达标前不得结束，达标后最多再追加 1 步；
+# free：T2.2 的原始行为，范围与结束时机完全由模型判断（步数会波动）。
+SCOPE_GUIDED = "guided"
+SCOPE_FREE = "free"
+SCOPE_MODES = (SCOPE_GUIDED, SCOPE_FREE)
+
+DEFAULT_MAX_STEPS = 8
+MAX_CONSECUTIVE_REJECTS = 3
+MAX_DECISION_ERRORS = 2
+MAX_SCOPE_REJECTS = 3
+DEFAULT_MAX_EXTRA_STEPS = 1
+
+AGENT_VERSION = "agent-v1"
+
+# 本轮 Agent 只实现天气正式场景。股票场景不接入，股票专属的 check_lookahead
+# 因此不在此集合内——它仍可由 pipeline 使用，但不作为天气 Agent 的可选动作。
+WEATHER_AGENT_TOOLS: tuple[str, ...] = (
+    "compute_metrics",
+    "analyze_spectrum",
+    "run_stat_tests",
+    "detect_anomalies",
+    "detect_change_points",
+)
+
+
+@dataclass
+class AgentStep:
+    """一步轨迹。字段即 T2.5 重放所需的最小信息集。"""
+
+    index: int
+    action: str
+    args: dict[str, Any] = field(default_factory=dict)
+    reason: str = ""
+    outcome: str = ""
+    summary: dict[str, Any] = field(default_factory=dict)
+    elapsed_ms: int = 0
+    error: Optional[str] = None
+    # 该步的开始时间。engine 用它写 events，T2.5 重放时也用它对照。
+    started_at: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        out = {"index": self.index, "action": self.action, "reason": self.reason,
+               "outcome": self.outcome, "summary": self.summary,
+               "elapsed_ms": self.elapsed_ms, "started_at": self.started_at}
+        if self.args:
+            out["args"] = self.args
+        if self.error:
+            out["error"] = self.error
+        return out
+
+
+@dataclass
+class AgentTrajectory:
+    question: str
+    steps: list[AgentStep] = field(default_factory=list)
+    terminate_reason: str = ""
+    results: dict[str, Any] = field(default_factory=dict)   # tool -> ToolResult（含 data）
+    rejects: list[dict[str, Any]] = field(default_factory=list)
+    model: str = ""
+    agent_version: str = AGENT_VERSION
+    allowed_tools: list[str] = field(default_factory=list)
+    # T2.11 范围下限：guided 模式下记录下限、命中词与达标情况
+    scope_mode: str = SCOPE_FREE
+    scope: dict[str, Any] = field(default_factory=dict)
+    # T2.13 token 预算：limit / used / remaining / enforced / exhausted / unavailable
+    budget: dict[str, Any] = field(default_factory=dict)
+    # T2.4 越界事件与统计；与 rejects 的区别：rejects 是运行时视角，guard_events 是边界视角
+    guard_events: list[dict[str, Any]] = field(default_factory=list)
+    guard_stats: dict[str, Any] = field(default_factory=dict)
+
+    # ---- 供 T2.8 指标与报告使用的派生量 ----
+    @property
+    def tools_run(self) -> list[str]:
+        """成功执行过的工具（去重保序）；重试成功也只算一次。"""
+        out: list[str] = []
+        for s in self.steps:
+            if s.outcome == "ok" and s.action not in out:
+                out.append(s.action)
+        return out
+
+    @property
+    def step_count(self) -> int:
+        return len(self.steps)
+
+    def data_of(self, tool: str, default: Any = None) -> Any:
+        res = self.results.get(tool)
+        return default if res is None else res.data
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "agent_version": self.agent_version,
+            "model": self.model,
+            "question": self.question,
+            "terminate_reason": self.terminate_reason,
+            "step_count": self.step_count,
+            "allowed_tools": self.allowed_tools,
+            "tools_run": self.tools_run,
+            "scope_mode": self.scope_mode,
+            "scope": self.scope,
+            "budget": self.budget,
+            "steps": [s.to_dict() for s in self.steps],
+            "rejects": self.rejects,
+            "guard_events": self.guard_events,
+            "guard_stats": self.guard_stats,
+        }
+
+
+class DecisionError(RuntimeError):
+    """模型输出不合法（非 JSON、缺字段、动作无效）。"""
+
+
+class AgentRunner:
+    """一次分析任务的自主编排器。
+
+    用法::
+
+        runner = AgentRunner(ctx, client, question="分析温度趋势")
+        traj = runner.run()
+    """
+
+    def __init__(self, ctx: tools.ToolContext, client, question: str,
+                 max_steps: int = DEFAULT_MAX_STEPS,
+                 allowed_tools: Optional[list[str] | tuple[str, ...]] = None,
+                 scope_mode: str = SCOPE_GUIDED,
+                 max_extra_steps: int = DEFAULT_MAX_EXTRA_STEPS,
+                 max_tokens: int = 0) -> None:
+        if client is None:
+            raise ValueError("AgentRunner 需要 LLM 客户端；无客户端时应走固定流水线")
+        if scope_mode not in SCOPE_MODES:
+            raise ValueError(f"scope_mode 只能是 {SCOPE_MODES}，收到 {scope_mode!r}")
+        # 默认放开全部注册工具，便于单测直接复用；生产入口（engine）必须显式传入
+        # 场景白名单，否则一旦新增工具就会被模型看到。
+        names = list(allowed_tools) if allowed_tools is not None else tools.tool_names()
+        unknown = [n for n in names if n not in tools.tool_names()]
+        if unknown:
+            raise ValueError(f"白名单包含未注册的工具：{unknown}")
+        if not names:
+            raise ValueError("白名单不能为空")
+        self.allowed_tools = tuple(dict.fromkeys(names))
+        self.ctx = ctx
+        self.client = client
+        self.question = question
+        self.max_steps = max(1, max_steps)
+        self.scope_mode = scope_mode
+        self.max_extra_steps = max(0, int(max_extra_steps))
+        # 0 = 不限制；只约束模型调用，工具执行不消耗 token
+        self.max_tokens = max(0, int(max_tokens))
+        # 下限只约束「至少做什么」，顺序仍由模型决定。free 模式不设下限。
+        self.floor: Optional[ScopeFloor] = (
+            infer_floor(question, self.allowed_tools) if scope_mode == SCOPE_GUIDED else None)
+        self.traj = AgentTrajectory(question=question,
+                                    model=getattr(client, "model", "") or "",
+                                    allowed_tools=list(self.allowed_tools),
+                                    scope_mode=scope_mode)
+        self.guard = ActionGuard(GuardPolicy(
+            allowed_tools=self.allowed_tools,
+            max_steps=self.max_steps,
+            max_consecutive_violations=MAX_CONSECUTIVE_REJECTS,
+        ))
+        self._decision_errors = 0
+        self._scope_rejects = 0
+        # E2：预算前置检查的状态。用在报告里区分「调用后才发现超限」与
+        # 「调用前就拦住」，否则两者都表现为 token_budget，看不出差在哪。
+        self._reserve_value: Optional[int] = None
+        self._reserve_basis = "unavailable"
+        self._precheck_blocked = False
+
+    # ---------------- 对外入口 ----------------
+
+    def run(self) -> AgentTrajectory:
+        while True:
+            if len(self.traj.steps) >= self.max_steps:
+                self.traj.terminate_reason = TERMINATE_MAX_STEPS
+                break
+            if self.guard.consecutive_violations >= MAX_CONSECUTIVE_REJECTS:
+                self.traj.terminate_reason = TERMINATE_IDLE
+                break
+            if self._decision_errors >= MAX_DECISION_ERRORS:
+                self.traj.terminate_reason = TERMINATE_DECISION_ERROR
+                break
+            if self._scope_rejects >= MAX_SCOPE_REJECTS:
+                self.traj.terminate_reason = TERMINATE_SCOPE_UNMET
+                break
+            used = self._usage_total()
+            if self.max_tokens and used is not None:
+                if used >= self.max_tokens:
+                    # 已经到限：下一次模型调用之前停，此前已选中的工具仍执行完
+                    self.traj.terminate_reason = TERMINATE_TOKEN_BUDGET
+                    break
+                reserve, basis = self._reserve_tokens(used)
+                self._reserve_value, self._reserve_basis = reserve, basis
+                if reserve is not None and used + reserve > self.max_tokens:
+                    # 预扣：按已观测的单次调用量估计，下一步会超限就直接停，
+                    # 而不是先花掉再报告「小幅超限」。
+                    self._precheck_blocked = True
+                    self.traj.terminate_reason = TERMINATE_TOKEN_BUDGET
+                    break
+
+            try:
+                decision = self._decide()
+            except (DecisionError, LLMError) as exc:
+                self._decision_errors += 1
+                self.traj.rejects.append({"kind": "decision_error",
+                                          "detail": str(exc)[:200]})
+                continue
+
+            action = decision["action"]
+            if action == "finish":
+                blocked = self._finish_blocked()
+                if blocked:
+                    self._reject_scope(blocked)
+                    continue
+                self.traj.terminate_reason = TERMINATE_MODEL_FINISHED
+                break
+
+            verdict = self.guard.check(action, decision.get("args") or {},
+                                       self.traj.results, len(self.traj.steps))
+            if not verdict.allowed:
+                self.guard.record_violation(verdict, action, len(self.traj.steps))
+                self.traj.rejects.append({
+                    "kind": "invalid_action", "reason_kind": verdict.kind,
+                    "action": action, "detail": verdict.detail,
+                })
+                continue
+
+            over = self._extra_budget_exceeded(action)
+            if over:
+                # 预算用尽不是越界：工具合法、参数合法，只是不在下限内。
+                # 若记进 guard_events，「越界次数」会把正常的追加尝试也算进去。
+                self.traj.rejects.append({
+                    "kind": "scope_exceeded", "action": action, "detail": over,
+                })
+                self.traj.terminate_reason = TERMINATE_BUDGET
+                break
+
+            self._execute(action, decision.get("args") or {},
+                          decision.get("reason", ""), is_retry=verdict.is_retry)
+            self._scope_rejects = 0
+
+        self.traj.guard_events = list(self.guard.violations)
+        self.traj.guard_stats = self.guard.stats()
+        self.traj.scope = self._scope_report()
+        self.traj.budget = self._budget_report()
+        return self.traj
+
+    # ---------------- 范围下限 ----------------
+
+    def _extra_used(self) -> int:
+        """下限之外已成功执行（ok / skipped）的工具数。"""
+        if self.floor is None:
+            return 0
+        return sum(1 for t in self.floor_tools_run() if t not in self.floor.tools)
+
+    def floor_tools_run(self) -> list[str]:
+        """已成功执行的工具（去重保序），与 AgentTrajectory.tools_run 同口径。"""
+        return self.traj.tools_run
+
+    def _hopeless(self, tool: str) -> bool:
+        """下限工具已失败且重试次数用尽——再拒绝结束只会空转到 max_steps。"""
+        res = self.traj.results.get(tool)
+        if getattr(res, "outcome", None) != "failed":
+            return False
+        return self.guard.retry_count(tool) >= self.guard.policy.max_retries_per_tool
+
+    def _finish_blocked(self) -> Optional[str]:
+        """结束请求是否应被拒绝。返回拒绝理由，None 表示允许结束。"""
+        if self.floor is None:
+            return None
+        missing = self.floor.missing(self.traj.results)
+        if not missing:
+            return None
+        if all(self._hopeless(t) for t in missing):
+            return None
+        return ("范围下限未覆盖：{}。请先执行这些工具再结束（下限来自问题关键词：{}）"
+                .format("、".join(missing), describe(self.floor)))
+
+    def _extra_budget_exceeded(self, action: str) -> Optional[str]:
+        """下限之外最多追加 max_extra_steps 步；超出即拒绝。"""
+        if self.floor is None or action in self.floor.tools:
+            return None
+        used = self._extra_used()
+        if used >= self.max_extra_steps:
+            return ("范围下限之外的追加步数已用尽（{} / {}）：{} 不在下限内，"
+                    "请回到下限工具或结束".format(used, self.max_extra_steps, action))
+        return None
+
+    def _usage_total(self) -> Optional[int]:
+        """服务端累计 token；未返回 usage 时返回 None（不估算、不猜测）。
+
+        客户端以 `usage_summary()` 暴露累计值；没有任何调用或服务端不给 usage
+        时它返回 None。这里把「没有数据」和「用了 0」分开，前者不能用来判断预算。
+        """
+        fn = getattr(self.client, "usage_summary", None)
+        if not callable(fn):
+            return None
+        try:
+            usage = fn()
+        except Exception:                      # noqa: BLE001
+            return None
+        if not isinstance(usage, dict):
+            return None
+        try:
+            total = int(usage.get("total_tokens") or 0)
+        except (TypeError, ValueError):
+            return None
+        return total if total > 0 else None
+
+    def _reserve_tokens(self, used: int) -> tuple[Optional[int], str]:
+        """估计下一次模型调用的 token 数，用于预算前置检查。
+
+        只用真实观测值：优先服务端记录的单次最大值，缺失时退回均值。
+        `calls == 0` 时没有依据，返回 None——第一次调用无法预扣，
+        这时只能退回「调用后检查」，并在 budget 里标成 unavailable。
+        """
+        fn = getattr(self.client, "usage_summary", None)
+        if not callable(fn):
+            return None, "unavailable"
+        try:
+            usage = fn()
+        except Exception:                      # noqa: BLE001
+            return None, "unavailable"
+        if not isinstance(usage, dict):
+            return None, "unavailable"
+        try:
+            calls = int(usage.get("calls") or 0)
+        except (TypeError, ValueError):
+            calls = 0
+        if calls <= 0 or used <= 0:
+            return None, "unavailable"
+        raw_max = usage.get("max_call_tokens")
+        if isinstance(raw_max, (int, float)) and not isinstance(raw_max, bool) and raw_max > 0:
+            return int(raw_max), "observed_max"
+        return -(-used // calls), "observed_avg"      # 向上取整
+
+    def _budget_report(self) -> dict[str, Any]:
+        used = self._usage_total()
+        limit = self.max_tokens
+        enforced = limit > 0
+        return {
+            "limit": limit,
+            "used": used,
+            "remaining": (max(0, limit - (used or 0)) if enforced else None),
+            "enforced": enforced,
+            "exhausted": self.traj.terminate_reason == TERMINATE_TOKEN_BUDGET,
+            # 设了限但服务端不给用量：预算事实上没生效，必须如实标注
+            "unavailable": bool(enforced and used is None),
+            # E2 前置检查：reserve 是「下一次调用预计消耗」，basis 说明依据，
+            # blocked 表示这次是调用前拦下的（used 仍小于 limit）。
+            "precheck": {
+                "enabled": bool(enforced and used is not None),
+                "reserve": self._reserve_value,
+                "basis": self._reserve_basis,
+                "blocked": self._precheck_blocked,
+            },
+        }
+
+    def _reject_scope(self, detail: str) -> None:
+        self._scope_rejects += 1
+        self.traj.rejects.append({"kind": "scope_incomplete", "detail": detail})
+
+    def _scope_report(self) -> dict[str, Any]:
+        if self.floor is None:
+            return {"mode": SCOPE_FREE, "enforced": False}
+        report = {"mode": SCOPE_GUIDED, "enforced": True}
+        report.update(self.floor.to_dict(self.traj.results))
+        report.update({
+            "extra_used": self._extra_used(),
+            "max_extra_steps": self.max_extra_steps,
+            "scope_rejects": self._scope_rejects,
+        })
+        return report
+
+    # ---------------- 内部实现 ----------------
+
+    def _decide(self) -> dict[str, Any]:
+        """调模型取一步决策。"""
+        payload = self.client.chat_json(self._system_prompt(), self._user_prompt())
+        if not isinstance(payload, dict):
+            raise DecisionError("决策必须是 JSON 对象")
+        action = payload.get("action")
+        if not isinstance(action, str) or not action.strip():
+            raise DecisionError("缺少 action 字段")
+        reason = payload.get("reason")
+        if not isinstance(reason, str) or not reason.strip():
+            # 理由为空说明模型没在做判断，按不合法处理
+            raise DecisionError("reason 不得为空")
+        args = payload.get("args")
+        if args is not None and not isinstance(args, dict):
+            raise DecisionError("args 必须是对象")
+        return {"action": action.strip(), "args": args or {}, "reason": reason.strip()}
+
+    def _execute(self, action: str, args: dict[str, Any], reason: str,
+                 is_retry: bool = False) -> None:
+        started_at = datetime.now().isoformat(timespec="seconds")
+        res = tools.run_tool(action, self.ctx)
+        self.traj.results[action] = res
+        self.traj.steps.append(AgentStep(
+            index=len(self.traj.steps),
+            action=action, args=args, reason=reason,
+            outcome=res.outcome, summary=res.summary,
+            elapsed_ms=res.elapsed_ms, error=res.error,
+            started_at=started_at,
+        ))
+        self.guard.record_execution(action, res.outcome, is_retry=is_retry)
+
+    # ---------------- 提示词 ----------------
+
+    def _system_prompt(self) -> str:
+        catalog = "\n".join(
+            f"- {t['name']}：{t['description']} 适用：{t['when_to_use']}"
+            for t in tools.describe_tools() if t["name"] in self.allowed_tools)
+        return (
+            "你是时序分析的执行决策器。每一步从工具清单中选择一个尚未执行的分析工具，"
+            "或宣布结束。你会看到此前各步的执行结果摘要。\n\n"
+            f"可用工具：\n{catalog}\n\n"
+            "规则：\n"
+            "1. 只输出 JSON 对象，不要解释性文字或代码块标记。\n"
+            "2. 输出格式：{\"action\": \"工具名或 finish\", "
+            "\"args\": {}, \"reason\": \"一句话理由\"}。\n"
+            "3. action 必须是清单中的工具名，或字符串 finish；成功或跳过的工具不得重复，"
+            "失败的工具可以重试一次。\n"
+            "4. args 一律留空对象；这些工具不接受额外参数。\n"
+            "5. reason 必须说明为什么选它，或为什么结束；不得为空。\n"
+            "6. 观察里会给出「范围下限」：下限工具未全部执行时输出 finish 会被拒绝，"
+            "必须先补齐；下限已覆盖时应结束，不必跑完全部工具。\n"
+            "7. 若已有结果之间存在矛盾或某列未被覆盖而问题涉及它，可在下限之外"
+            "追加 1 个工具，用完即止。\n"
+            "8. 工具顺序自行决定；同一工具成功后不得重复，失败可重试一次。"
+        )
+
+    def _user_prompt(self) -> str:
+        """交给观察摘要器生成，不再在这里拼接无限增长的历史。"""
+        return build_observation(self.ctx, self.question, self.traj,
+                                 self.allowed_tools, self.max_steps,
+                                 floor=self.floor,
+                                 max_extra_steps=self.max_extra_steps)
+
+
+def build_agent_runner(ctx: tools.ToolContext, question: str, env: Optional[dict[str, str]] = None,
+                       max_steps: int = DEFAULT_MAX_STEPS,
+                       allowed_tools: Optional[list[str] | tuple[str, ...]] = None,
+                       scope_mode: str = SCOPE_GUIDED,
+                       max_extra_steps: int = DEFAULT_MAX_EXTRA_STEPS,
+                       max_tokens: int = 0) -> Optional[AgentRunner]:
+    """按环境变量构造运行时；无模型配置返回 None（调用方应回退固定流水线）。"""
+    import os
+
+    from .llm_client import client_from_env
+
+    env = env if env is not None else os.environ
+    client = client_from_env(env)
+    if client is None:
+        return None
+    return AgentRunner(ctx, client, question, max_steps=max_steps,
+                       allowed_tools=allowed_tools, scope_mode=scope_mode,
+                       max_extra_steps=max_extra_steps, max_tokens=max_tokens)