Shadowzzh

tasks.py

tasks.py
"""模拟的异步"终端命令"与任务管理器。

为了安全(绝不真跑危险命令)与可复现,长任务用"带进度输出的模拟脚本"实现:
每个模拟脚本以固定的"每(模拟)秒进度百分比"推进,直到 100% 完成。

时间轴加速:真实世界里每 TICK_REAL 秒代表 1 个"模拟秒"。
默认 TICK_REAL=0.4,即 2.5 倍速——保留"3%/2%/1% 的速度差 + 是否过 50% 的判定"逻辑,
但把几十秒的等待压缩到几秒,方便演示复现。
"""

from __future__ import annotations

import asyncio
import os
from dataclasses import dataclass, field
from typing import Awaitable, Callable, Dict, Optional


def _env_float(name: str, default: float) -> float:
    """读取浮点环境变量;值非法时回退到默认值并打印警告。"""
    raw = os.getenv(name)
    if raw is None:
        return default
    try:
        return float(raw)
    except ValueError:
        print(f"⚠️ 环境变量 {name}={raw!r} 非法(应为数字),使用默认值 {default}")
        return default


# 1 个"模拟秒"对应的真实秒数(可用环境变量覆盖)。
# 默认 0.4(2.5 倍速):既压缩了等待,又给模型的"查询-判定-取消"决策留足时间窗口,
# 保证场景 4 里"慢脚本尚未过 50% 就被取消"能稳定复现。
TICK_REAL = _env_float("FLUX_TICK_REAL", 0.4)

# 不同脚本的"每模拟秒进度%"档位。实验 4-5 场景 4 需要 3% / 2% / 1% 的速度差。
_SCRIPT_RATES = [
    ("fast", 3.0),
    ("mid", 2.0),
    ("slow", 1.0),
]
_DEFAULT_RATE = 4.5  # 场景 1/2/3 的普通长任务(约 22 模拟秒 ≈ 5.5 真实秒完成)


def resolve_rate(command: str) -> float:
    """根据命令字符串推断该模拟脚本的推进速度(%/模拟秒)。"""
    low = command.lower()
    for key, rate in _SCRIPT_RATES:
        if key in low:
            return rate
    return _DEFAULT_RATE


@dataclass
class TaskState:
    """一个异步终端任务的实时状态。"""

    task_id: str
    command: str
    rate: float
    progress: float = 0.0
    status: str = "running"          # running | completed | cancelled
    result: str = ""
    _task: Optional[asyncio.Task] = field(default=None, repr=False)


class TaskManager:
    """管理所有异步终端任务:启动、查询进度、取消。

    on_complete 回调会在任务自然完成时被调用(用于把真实结果作为"新事件"注入对话)。
    """

    def __init__(self, on_complete: Callable[[TaskState], Awaitable[None]],
                 log: Callable[[str, str], None]):
        self._on_complete = on_complete
        self._log = log
        self._tasks: Dict[str, TaskState] = {}
        self._counter = 0

    def start(self, command: str) -> TaskState:
        """启动一个异步终端命令,立即返回其状态(含 task_id 占位符)。"""
        self._counter += 1
        task_id = f"T{self._counter}"
        state = TaskState(task_id=task_id, command=command, rate=resolve_rate(command))
        self._tasks[task_id] = state
        state._task = asyncio.create_task(self._run(state))
        self._log("TASK", f"启动异步任务 {task_id}: `{command}` (速度 {state.rate:.0f}%/模拟秒)")
        return state

    async def _run(self, state: TaskState) -> None:
        """后台推进进度,直到完成或被取消。"""
        next_milestone = 20.0
        try:
            while state.progress < 100.0:
                await asyncio.sleep(TICK_REAL)
                state.progress = min(100.0, state.progress + state.rate)
                if state.progress >= next_milestone:
                    self._log("TASK", f"{state.task_id} `{state.command}` 进度 {state.progress:.0f}%")
                    next_milestone += 20.0
            state.status = "completed"
            state.result = (f"命令 `{state.command}` 执行完毕:共扫描 12,840 条记录,"
                            f"发现 3 个异常峰值、1 处可疑错误码(HTTP 503 突增),"
                            f"平均响应时间 128ms。")
            self._log("TASK", f"{state.task_id} 完成 ✅")
            await self._on_complete(state)
        except asyncio.CancelledError:
            # 被取消:标记状态并静默退出(不再注入完成结果)
            state.status = "cancelled"
            self._log("TASK", f"{state.task_id} 已被取消 🛑(进度停在 {state.progress:.0f}%)")
            raise

    def query(self, task_id: str) -> Optional[TaskState]:
        return self._tasks.get(task_id)

    def cancel(self, task_id: str) -> bool:
        """按 ID 取消单个任务。"""
        state = self._tasks.get(task_id)
        if state and state.status == "running":
            state.status = "cancelled"
            if state._task:
                state._task.cancel()
            return True
        return False

    def cancel_all(self) -> list[str]:
        """取消所有仍在运行的任务,返回被取消的 task_id 列表。"""
        cancelled = []
        for tid, state in self._tasks.items():
            if state.status == "running":
                state.status = "cancelled"
                if state._task:
                    state._task.cancel()
                cancelled.append(tid)
        return cancelled

    def any_running(self) -> bool:
        return any(s.status == "running" for s in self._tasks.values())

    def all_states(self) -> list[TaskState]:
        return list(self._tasks.values())

    # --------------------------- 状态检查点(持久化) ---------------------------

    def snapshot(self) -> list[dict]:
        """导出所有任务的最后已知状态,供检查点持久化。

        注意:正在跑的 asyncio 协程无法序列化,只能记录其最后已知进度;
        重启后据此决定「重跑」还是「按进度续跑」,这正是异步任务状态管理的意义。
        """
        return [
            {"task_id": s.task_id, "command": s.command, "rate": s.rate,
             "progress": s.progress, "status": s.status, "result": s.result}
            for s in self._tasks.values()
        ]

    def restore(self, records: list[dict]) -> None:
        """从检查点还原任务的历史状态(不重启协程)。

        还原时把「运行中」的任务标记为 suspended(挂起)——它没有活着的协程,
        只保留了被打快照那一刻的进度,等待上层逻辑决定如何续跑。
        """
        for r in records:
            status = "suspended" if r["status"] == "running" else r["status"]
            state = TaskState(
                task_id=r["task_id"], command=r["command"], rate=r["rate"],
                progress=r["progress"], status=status, result=r.get("result", ""),
            )
            self._tasks[state.task_id] = state
            try:
                self._counter = max(self._counter, int(state.task_id.lstrip("T") or 0))
            except ValueError:
                pass