cheso-cli 0.2.0__py3-none-any.whl

cheso_cli/tasks.py

@@ -0,0 +1,834 @@
+"""任务（Plan）、转换和翻译：发起、等待、查询、回答、取消及获取结果。
+
+各函数返回普通字典作为结果视图，由 CLI 输出为 JSON，或格式化后展示给用户。
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+import shlex
+import sys
+import time
+from collections.abc import Callable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, TextIO
+
+import httpx
+
+from cheso_cli.client import ApiError, ChesoClient, Deadline, TimeLimitReached
+from cheso_cli.config import Settings
+from cheso_cli.errors import CliError, ExitCode, UsageError
+from cheso_cli.transfer import download_url_to_dir, upload_file
+
+KIND_TASK = "task"
+KIND_CONVERSION = "conversion"
+KIND_TRANSLATION = "translation"
+# Manager 的 typeid 前缀。
+ID_PREFIXES = {"plan_": KIND_TASK, "cvt_": KIND_CONVERSION, "tlj_": KIND_TRANSLATION}
+
+PLAN_INTERACT = "interact"
+PLAN_COMPLETED = "completed"
+PLAN_TERMINAL = {"completed", "failed", "terminated", "rolled_back"}
+PLAN_RUNNING = {"in_progress", "interact", "pending"}
+CONVERT_COMPLETED = "completed"
+CONVERT_DONE = {"completed", "failed"}
+TRANSLATION_SUCCEEDED = "SUCCEEDED"
+TRANSLATION_DONE = {"SUCCEEDED", "FAILED", "CANCELED"}
+# 翻译过程中的中间产物，例如结构化文本块和提取的图片，不作为最终交付文件。
+TRANSLATION_SKIP_ROLES = {"blocks", "image"}
+
+# Agent 可能将执行交给后续 Plan，最多沿接续链跟进以下跳数。
+MAX_CHAIN_HOPS = 10
+DEFAULT_POLL_INTERVAL = 3.0
+DEFAULT_WAIT_TIMEOUT = 1800.0
+HEARTBEAT_SECONDS = 60.0
+# 等待期间允许连续出现的临时错误次数，包括网络错误、5xx 和 429。
+MAX_TRANSIENT_ERRORS = 5
+
+CODE_PROJECT_BUSY = 2614
+CODE_CONVERT_UNSUPPORTED = 1801
+AGENT_TYPES = ("cheso", "image_edit")
+# 网站支持的目标语言，见 services/frontend/src/config/translation-languages.ts。
+TRANSLATION_LANGUAGES = ("zh", "zh-Hant", "en", "ko", "ja", "es", "fr", "ar", "ru", "pt", "de", "th")
+# 按网站 convert-download-request.ts 的规则由扩展名确定源类型；其他类型直接使用扩展名。
+CONVERT_SOURCE_BY_EXT = {"md": "md", "markdown": "md", "html": "html", "htm": "html", "ppt": "pptx", "pptx": "pptx"}
+# Agent 积分不足时，失败原因中会包含以下任一标记。
+CREDIT_FAILURE_MARKERS = ("insufficient_credits", "insufficient credits", "额度不足", "积分不足")
+
+_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+_FRACTION = re.compile(r"\.(\d+)")
+
+
+# 任务、转换或翻译成功时对应的状态。
+SUCCESS_STATUS = {
+    KIND_TASK: PLAN_COMPLETED,
+    KIND_CONVERSION: CONVERT_COMPLETED,
+    KIND_TRANSLATION: TRANSLATION_SUCCEEDED,
+}
+
+
+def succeeded(view: dict[str, Any]) -> bool:
+    return bool(view.get("done")) and view.get("status") == SUCCESS_STATUS.get(view.get("kind", ""))
+
+
+def validate_id(label: str, value: str) -> str:
+    value = (value or "").strip()
+    if not _ID_PATTERN.match(value):
+        raise UsageError(f"{label} {value!r} is not a valid Cheso id")
+    return value
+
+
+def task_kind(task_id: str) -> str:
+    task_id = validate_id("task id", task_id)
+    for prefix, kind in ID_PREFIXES.items():
+        if task_id.startswith(prefix):
+            return kind
+    raise UsageError(f"unknown task id {task_id!r}: expected plan_..., cvt_... or tlj_...")
+
+
+def parse_time(value: Any) -> datetime | None:
+    """解析 Go 输出的 RFC 3339 时间，支持任意长度的小数秒及 ``Z``；零值时间 ``0001-01-01`` 表示未设置。"""
+    if not isinstance(value, str) or not value.strip():
+        return None
+    text = value.strip()
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+    text = _FRACTION.sub(lambda m: "." + (m.group(1) + "000000")[:6], text, count=1)
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return None if parsed.year <= 1 else parsed
+
+
+def available_credits(data: Any, now: datetime) -> int:
+    """汇总当前有效积分授权中的 ``amount_available``。"""
+    total = 0
+    grants = (data or {}).get("grants") if isinstance(data, dict) else None
+    for grant in grants or []:
+        if not isinstance(grant, dict):
+            continue
+        valid_from = parse_time(grant.get("valid_from"))
+        expires_at = parse_time(grant.get("expires_at"))
+        if valid_from and valid_from > now:
+            continue
+        if expires_at and expires_at <= now:
+            continue
+        try:
+            amount = int(grant.get("amount_available") or 0)
+        except (TypeError, ValueError):
+            continue
+        if amount > 0:
+            total += amount
+    return total
+
+
+def is_credit_failure(reason: str) -> bool:
+    lower = (reason or "").lower()
+    return any(marker in lower for marker in CREDIT_FAILURE_MARKERS)
+
+
+def question_from(interaction: Any) -> dict[str, Any] | None:
+    """将 Agent 提问（user_interact 数据）整理为精简结构；不认识的结构通过 ``raw`` 原样保留。"""
+    if not isinstance(interaction, dict) or not interaction:
+        return None
+    questions = interaction.get("questions")
+    if not isinstance(questions, list) or not questions:
+        return {"tool_call_id": str(interaction.get("tool_call_id") or ""), "questions": [], "raw": interaction}
+    items = []
+    for q in questions:
+        if not isinstance(q, dict):
+            continue
+        options = [
+            {"label": str(o.get("label") or ""), "description": str(o.get("description") or "")}
+            for o in q.get("options") or []
+            if isinstance(o, dict)
+        ]
+        items.append(
+            {
+                "question": str(q.get("question") or ""),
+                "header": str(q.get("header") or ""),
+                "options": options,
+                "multi_select": bool(q.get("multi_select")),
+            }
+        )
+    out: dict[str, Any] = {"tool_call_id": str(interaction.get("tool_call_id") or ""), "questions": items}
+    if isinstance(interaction.get("timeout"), (int, float)):
+        out["timeout_seconds"] = interaction["timeout"]
+    return out
+
+
+def parse_answers(pairs: list[str], question: dict[str, Any] | None) -> dict[str, str]:
+    """将 ``--answer`` 参数转换为 ``{问题文本: 回答}``。
+
+    支持 ``QUESTION=ANSWER``（精确问题文本，其中也可能包含 ``=``）、``N=ANSWER``（从 1 开始的问题编号）、
+    ``HEADER=ANSWER``（问题的简短标题）；只有一个问题时，也支持直接传入 ``ANSWER``。
+    """
+    items = (question or {}).get("questions") or []
+    texts = [q["question"] for q in items]
+    answers: dict[str, str] = {}
+    for raw in pairs:
+        key = value = None
+        for index, char in enumerate(raw):
+            if char == "=" and raw[:index].strip() in texts:
+                key, value = raw[:index].strip(), raw[index + 1 :].strip()
+                break
+        if key is None and "=" in raw:
+            left, value = (part.strip() for part in raw.split("=", 1))
+            if left.isdigit() and 1 <= int(left) <= len(texts):
+                key = texts[int(left) - 1]
+            else:
+                matches = [q["question"] for q in items if q["header"] and q["header"].casefold() == left.casefold()]
+                if len(matches) == 1:
+                    key = matches[0]
+                elif not texts:
+                    key = left
+        if key is None and "=" not in raw and len(texts) == 1:
+            key, value = texts[0], raw.strip()
+        if key is None or value is None:
+            listed = "; ".join(f"{i}. {t}" for i, t in enumerate(texts, 1)) or "(none)"
+            raise UsageError(
+                f"--answer {raw!r} does not match a question. Use QUESTION=ANSWER or N=ANSWER. Questions: {listed}"
+            )
+        answers[key] = value
+    return answers
+
+
+def _detail_str(data: Any, key: str) -> str:
+    value = data.get(key) if isinstance(data, dict) else None
+    return str(value) if value is not None else ""
+
+
+class Tasks:
+    """使用同一站点和令牌操作任务、转换及翻译。"""
+
+    def __init__(
+        self,
+        client: ChesoClient,
+        settings: Settings,
+        storage: httpx.Client,
+        *,
+        progress: TextIO | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+        now: Callable[[], float] = time.time,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        self.client = client
+        self.settings = settings
+        self.storage = storage
+        self.progress = progress or sys.stderr
+        self.sleep = sleep
+        self.clock = clock
+        self.now = now
+        self.poll_interval = poll_interval
+        # 转换详情中已有的带签名结果 URL，以结果文件 ID 为键保存。
+        self._known_urls: dict[str, str] = {}
+
+    def say(self, message: str) -> None:
+        print(message, file=self.progress, flush=True)
+
+    # ---- 积分 ----
+
+    def credits(self) -> dict[str, Any]:
+        data = self.client.credit_grants()
+        now = datetime.fromtimestamp(self.now(), tz=timezone.utc)
+        return {"available": available_credits(data, now), "topup_url": self.settings.topup_url}
+
+    def ensure_credits(self) -> None:
+        """账号没有积分时，在发起任务前停止，避免服务器执行到一半才失败。
+        查询余额失败不会阻止发起任务，只会跳过这次提前检查。
+        """
+        try:
+            info = self.credits()
+        except ApiError as e:
+            if e.http_status == 401:
+                raise
+            self.say(f"warning: could not check the credit balance ({e}); starting the task anyway")
+            return
+        except httpx.TransportError:
+            self.say("warning: could not check the credit balance; starting the task anyway")
+            return
+        if info["available"] <= 0:
+            raise CliError(
+                f"Your Cheso account has no credits left, so the task was not started. Top up at {info['topup_url']}",
+                exit_code=ExitCode.INSUFFICIENT_CREDITS,
+                kind="insufficient_credits",
+                extra={"available": info["available"], "topup_url": info["topup_url"]},
+            )
+
+    # ---- 创建 ----
+
+    def create_task(
+        self,
+        *,
+        prompt: str,
+        paths: list[Path],
+        file_ids: list[str],
+        project_id: str | None,
+        agent_type: str | None,
+    ) -> dict[str, Any]:
+        prompt = (prompt or "").strip()
+        if not prompt:
+            raise UsageError("--prompt must not be empty")
+        project_id = validate_id("project id", project_id) if project_id else None
+        ids = [validate_id("file id", f) for f in file_ids]
+        for path in paths:
+            if not path.is_file():
+                raise UsageError(f"not a file: {path}")
+        self.ensure_credits()
+        uploads = []
+        for path in paths:
+            self.say(f"Uploading {path} ...")
+            result = upload_file(self.client, self.storage, path, project_id=project_id, now=self.now)
+            uploads.append(result.to_dict())
+            ids.append(result.file_id)
+        contexts = [{"file_id": file_id, "category": "attachment"} for file_id in dict.fromkeys(ids)]
+        try:
+            data = self.client.plan_create(
+                prompt=prompt, project_id=project_id, contexts=contexts or None, agent_type=agent_type or None
+            )
+        except ApiError as e:
+            if e.code == CODE_PROJECT_BUSY and project_id:
+                raise self.project_busy(project_id) from e
+            raise
+        data = data or {}
+        plan_id = _detail_str(data, "plan_id")
+        if not plan_id:
+            raise CliError("the task was not started (no task id returned)")
+        new_project = _detail_str(data, "project_id") or project_id or ""
+        view: dict[str, Any] = {
+            "task_id": plan_id,
+            "kind": KIND_TASK,
+            "status": _detail_str(data, "plan_status") or "in_progress",
+            "done": False,
+            "needs_input": False,
+            "project_id": new_project,
+            "project_url": self.settings.project_url(new_project),
+        }
+        if uploads:
+            view["uploaded_files"] = uploads
+        view["next"] = self.settings.command(f"task wait {plan_id}")
+        return view
+
+    def project_busy(self, project_id: str) -> CliError:
+        running: dict[str, Any] | None = None
+        try:
+            data = self.client.plan_list(project_id=project_id) or {}
+            for plan in data.get("plans") or []:
+                if isinstance(plan, dict) and plan.get("status") in PLAN_RUNNING:
+                    running = plan
+                    break
+        except (ApiError, httpx.TransportError):
+            running = None
+        extra: dict[str, Any] = {"project_id": project_id}
+        if running:
+            task_id = str(running.get("plan_id") or "")
+            extra["running_task_id"] = task_id
+            message = (
+                f"Project {project_id} already has a running task {task_id} (status {running.get('status')}). "
+                f"Wait for it with `{self.settings.command(f'task wait {task_id}')}` "
+                f"(or cancel it with `{self.settings.command(f'task cancel {task_id}')}`), "
+                "then retry."
+            )
+        else:
+            message = f"Project {project_id} already has a running task. Wait for it to finish, then retry."
+        return CliError(message, exit_code=ExitCode.RETRYABLE, kind="project_busy", extra=extra)
+
+    # ---- Plan 接续链 ----
+
+    def _follow(self, plan_id: str, budget: int) -> tuple[dict[str, Any], int, bool]:
+        """沿 ``next_plan_id`` 跟进至最后一个 Plan，最多 ``budget`` 跳；返回 (result, hops, chain_ended)。"""
+        current = plan_id
+        hops = 0
+        while True:
+            result = self.client.plan_result(current) or {}
+            following = _detail_str(result, "next_plan_id")
+            if not following:
+                return result, hops, True
+            if hops >= budget:
+                return result, hops, False
+            current = validate_id("next task id", following)
+            hops += 1
+
+    def _plan_view(self, requested_id: str, result: dict[str, Any], chain_ended: bool) -> dict[str, Any]:
+        plan_id = _detail_str(result, "plan_id") or requested_id
+        status = _detail_str(result, "status")
+        following = _detail_str(result, "next_plan_id")
+        needs_input = status == PLAN_INTERACT
+        done = status in PLAN_TERMINAL and not following
+        view: dict[str, Any] = {
+            "task_id": plan_id,
+            "kind": KIND_TASK,
+            "status": status,
+            "done": done,
+            "needs_input": needs_input,
+        }
+        if plan_id != requested_id:
+            view["continued_from"] = requested_id
+        try:
+            detail = self.client.plan_get(plan_id) or {}
+        except ApiError as e:
+            if e.http_status == 401:
+                raise
+            detail = {}
+        except httpx.TransportError:
+            detail = {}
+        project_id = _detail_str(detail, "project_id")
+        if project_id:
+            view["project_id"] = project_id
+            view["project_url"] = self.settings.project_url(project_id)
+        if _detail_str(detail, "summary"):
+            view["title"] = detail["summary"]
+        body = result.get("result") if isinstance(result.get("result"), dict) else None
+        if body:
+            view["answer"] = str(body.get("text") or "")
+            if body.get("text_truncated"):
+                view["answer_truncated"] = True
+            view["files"] = [self._plan_file(f) for f in body.get("files") or [] if isinstance(f, dict)]
+        if needs_input:
+            view["question"] = question_from(result.get("interaction"))
+        reason = _detail_str(result, "reason")
+        if status in PLAN_TERMINAL and status != PLAN_COMPLETED and reason:
+            view["failure_reason"] = reason
+        if done and status != PLAN_COMPLETED and is_credit_failure(reason):
+            view["topup_url"] = self.settings.topup_url
+        if following and not chain_ended:
+            view["next_task_id"] = following
+        view["next"] = self._plan_next(view)
+        return view
+
+    @staticmethod
+    def _plan_file(raw: dict[str, Any]) -> dict[str, Any]:
+        keys = ("file_id", "name", "path", "title", "description", "mime_type", "size", "version")
+        item = {k: raw[k] for k in keys if raw.get(k) not in (None, "")}
+        if not item.get("name") and item.get("path"):
+            item["name"] = posixpath.basename(str(item["path"]))
+        return item
+
+    def _plan_next(self, view: dict[str, Any]) -> str:
+        task_id = view.get("next_task_id") or view["task_id"]
+        if view.get("needs_input"):
+            return self.settings.command(f'task reply {view["task_id"]} --answer "QUESTION=ANSWER"') + " (or --skip)"
+        if not view["done"]:
+            return self.settings.command(f"task wait {task_id}")
+        if view["status"] == PLAN_COMPLETED:
+            project = view.get("project_id")
+            return (
+                self.settings.command(f'task create --project {project} --prompt "..."') + " to revise"
+                if project
+                else ""
+            )
+        return ""
+
+    # ---- 查询 / 等待 ----
+
+    def get(self, task_id: str) -> dict[str, Any]:
+        kind = task_kind(task_id)
+        if kind == KIND_TASK:
+            result, _, ended = self._follow(task_id, MAX_CHAIN_HOPS)
+            return self._plan_view(task_id, result, ended)
+        if kind == KIND_CONVERSION:
+            return self._conversion_view(self.client.convert_get(task_id) or {})
+        return self._translation_view(self.client.translation_get(task_id) or {})
+
+    def wait(
+        self, task_id: str, *, timeout: float, output_dir: Path | None, started: float | None = None
+    ) -> dict[str, Any]:
+        """持续轮询，直到任务结束、等待用户回答，或从 ``started``（默认当前时刻）起经过 ``timeout`` 秒。
+        已结束任务的结果文件在同一时限内下载到 ``output_dir``，为 None 时跳过下载。
+        截止时间后不再发起请求，每次请求最多使用剩余时间。
+        """
+        kind = task_kind(task_id)
+        started = self.clock() if started is None else started
+        deadline = Deadline(started + max(timeout, 0.0), self.clock)
+        with self.client.time_limit(deadline):
+            view = self._poll(kind, task_id, started, deadline)
+            if view["done"] and output_dir is not None:
+                self.download_results(view, output_dir, deadline=deadline)
+        return view
+
+    def _poll(self, kind: str, task_id: str, started: float, deadline: Deadline) -> dict[str, Any]:
+        current, hops_left = task_id, MAX_CHAIN_HOPS
+        last_status = ""
+        last_report = started
+        transient = 0
+        snapshot: Any = None
+        while True:
+            try:
+                if kind == KIND_TASK:
+                    result, hops, ended = self._follow(current, hops_left)
+                    hops_left -= hops
+                    current = _detail_str(result, "plan_id") or current
+                    status = _detail_str(result, "status")
+                    following = _detail_str(result, "next_plan_id")
+                    settled = status == PLAN_INTERACT or (status in PLAN_TERMINAL and not following)
+                    if not ended:
+                        settled = True  # 接续跳数已用完，返回当前结果，让调用方从此处继续。
+                    snapshot = (result, ended)
+                elif kind == KIND_CONVERSION:
+                    snapshot = self.client.convert_get(task_id) or {}
+                    status = _detail_str(snapshot, "status")
+                    settled = status in CONVERT_DONE
+                else:
+                    snapshot = self.client.translation_get(task_id) or {}
+                    status = _detail_str(snapshot, "status")
+                    settled = status in TRANSLATION_DONE
+                transient = 0
+            except (ApiError, httpx.TransportError) as e:
+                if isinstance(e, TimeLimitReached) or (isinstance(e, httpx.TransportError) and deadline.expired()):
+                    break  # 时间已到：抛出 TimeLimitReached，或请求被剩余时限截断。
+                if not _transient(e) or transient >= MAX_TRANSIENT_ERRORS:
+                    raise
+                transient += 1
+                retry_after = e.retry_after if isinstance(e, ApiError) and e.retry_after else self.poll_interval
+                self.say(f"[{_elapsed(self.clock() - started)}] temporary error ({_brief(e)}); retrying")
+                if self.clock() + retry_after > deadline.at:
+                    break
+                self.sleep(retry_after)
+                continue
+            elapsed = self.clock() - started
+            label = current if kind == KIND_TASK else task_id
+            if status != last_status:
+                self.say(f"[{_elapsed(elapsed)}] {label}: {status or 'unknown'}")
+                last_status, last_report = status, self.clock()
+            elif self.clock() - last_report >= HEARTBEAT_SECONDS:
+                self.say(f"[{_elapsed(elapsed)}] {label}: still {status} ...")
+                last_report = self.clock()
+            if settled:
+                return self._view_of(kind, task_id, snapshot)
+            if deadline.at - self.clock() <= self.poll_interval:
+                break  # 已没有时间再轮询一次，剩余时间用于补齐返回结果的详情。
+            self.sleep(self.poll_interval)
+        # 时间已到，直接返回最后已知状态，不再发起查询。
+        if snapshot is not None:
+            view = self._view_of(kind, task_id, snapshot)
+        else:
+            view = {"task_id": task_id, "kind": kind, "status": "unknown"}
+        view["done"] = False
+        view["timed_out"] = True
+        view["next"] = self.settings.command(f"task wait {view.get('next_task_id') or view['task_id']}")
+        return view
+
+    def _view_of(self, kind: str, requested_id: str, snapshot: Any) -> dict[str, Any]:
+        if kind == KIND_TASK:
+            result, ended = snapshot
+            return self._plan_view(requested_id, result, ended)
+        if kind == KIND_CONVERSION:
+            return self._conversion_view(snapshot)
+        return self._translation_view(snapshot)
+
+    # ---- 转换 ----
+
+    def _conversion_view(self, detail: dict[str, Any]) -> dict[str, Any]:
+        status = _detail_str(detail, "status")
+        job_id = _detail_str(detail, "job_id")
+        view: dict[str, Any] = {
+            "task_id": job_id,
+            "kind": KIND_CONVERSION,
+            "status": status,
+            "done": status in CONVERT_DONE,
+            "source_file_id": _detail_str(detail, "source_file_id"),
+            "source_type": _detail_str(detail, "source_type"),
+            "target_type": _detail_str(detail, "target_type"),
+        }
+        result_id = _detail_str(detail, "result_file_id")
+        if status == CONVERT_COMPLETED and result_id:
+            item: dict[str, Any] = {"file_id": result_id}
+            if isinstance(detail.get("result_file_version"), int):
+                item["version"] = detail["result_file_version"]
+            url = _detail_str(detail, "attachment_url") or _detail_str(detail, "download_url")
+            if url:
+                self._known_urls[result_id] = url
+            view["files"] = [item]
+        if status == "failed":
+            view["failure_reason"] = _detail_str(detail, "error_message") or "conversion failed"
+        view["next"] = "" if view["done"] else self.settings.command(f"task wait {job_id}")
+        return view
+
+    def start_conversion(self, file_id: str, target: str) -> dict[str, Any]:
+        file_id = validate_id("file id", file_id)
+        target = (target or "").strip().lower().lstrip(".")
+        if not target:
+            raise UsageError("--to must name a target format, e.g. pdf")
+        info = self.client.file_get(file_id) or {}
+        name = _detail_str(info, "name")
+        source = _convert_source_type(name) or _convert_source_type(_detail_str(info, "file_path"))
+        try:
+            supported = (self.client.convert_supported() or {}).get("conversions") or []
+        except (ApiError, httpx.TransportError):
+            supported = None
+        if supported is not None and not any(
+            str(c.get("source_type", "")).lower() == source and str(c.get("target_type", "")).lower() == target
+            for c in supported
+            if isinstance(c, dict)
+        ):
+            raise _unsupported_conversion(supported, name or file_id, source, target)
+        try:
+            data = self.client.convert_create(file_id=file_id, source_type=source, target_type=target) or {}
+        except ApiError as e:
+            if e.code == CODE_CONVERT_UNSUPPORTED and supported is not None:
+                raise _unsupported_conversion(supported, name or file_id, source, target) from e
+            raise
+        job_id = _detail_str(data, "job_id")
+        status = _detail_str(data, "status")
+        return {
+            "task_id": job_id,
+            "kind": KIND_CONVERSION,
+            "status": status,
+            "done": status in CONVERT_DONE,
+            "reused": bool(data.get("reused")),
+            "source_file_id": file_id,
+            "source_type": source,
+            "target_type": target,
+            "next": self.settings.command(f"task wait {job_id}"),
+        }
+
+    # ---- 翻译 ----
+
+    def _translation_view(self, detail: dict[str, Any]) -> dict[str, Any]:
+        status = _detail_str(detail, "status")
+        job_id = _detail_str(detail, "job_id")
+        view: dict[str, Any] = {
+            "task_id": job_id,
+            "kind": KIND_TRANSLATION,
+            "status": status,
+            "done": status in TRANSLATION_DONE,
+            "source_file_id": _detail_str(detail, "source_file_id"),
+            "target_language": _detail_str(detail, "target_language"),
+        }
+        if status == TRANSLATION_SUCCEEDED:
+            files = []
+            for raw in detail.get("result_files") or []:
+                if not isinstance(raw, dict) or raw.get("is_temp") or not raw.get("file_id"):
+                    continue
+                if raw.get("role") in TRANSLATION_SKIP_ROLES:
+                    continue
+                item = {"file_id": raw["file_id"], "name": posixpath.basename(str(raw.get("path") or ""))}
+                if isinstance(raw.get("version"), int) and raw["version"]:
+                    item["version"] = raw["version"]
+                files.append(item)
+            view["files"] = files
+        elif status in TRANSLATION_DONE:
+            failure = detail.get("failure") if isinstance(detail.get("failure"), dict) else {}
+            view["failure_reason"] = str(failure.get("message") or status.lower())
+        view["next"] = "" if view["done"] else self.settings.command(f"task wait {job_id}")
+        return view
+
+    def start_translation(self, file_id: str, target: str, source: str | None) -> dict[str, Any]:
+        file_id = validate_id("file id", file_id)
+        target = (target or "").strip()
+        if not target:
+            raise UsageError("--to must name a language, e.g. en")
+        data = self.client.translation_create(
+            file_id=file_id, target_language=target, source_language=(source or "").strip() or None
+        )
+        data = data or {}
+        job_id = _detail_str(data, "job_id")
+        status = _detail_str(data, "status")
+        return {
+            "task_id": job_id,
+            "kind": KIND_TRANSLATION,
+            "status": status,
+            "done": status in TRANSLATION_DONE,
+            "reused": bool(data.get("reused")),
+            "source_file_id": file_id,
+            "target_language": target,
+            "next": self.settings.command(f"task wait {job_id}"),
+        }
+
+    # ---- 回答 / 取消 ----
+
+    def reply(self, task_id: str, answers: list[str], skip: bool) -> dict[str, Any]:
+        if task_kind(task_id) != KIND_TASK:
+            raise UsageError("only tasks (plan_... ids) ask questions")
+        if skip and answers:
+            raise UsageError("use either --answer or --skip, not both")
+        if not skip and not answers:
+            raise UsageError("give at least one --answer, or --skip to let Cheso decide")
+        result, _, _ = self._follow(task_id, MAX_CHAIN_HOPS)
+        plan_id = _detail_str(result, "plan_id") or task_id
+        status = _detail_str(result, "status")
+        if status != PLAN_INTERACT:
+            raise CliError(
+                f"Task {plan_id} is not waiting for an answer (status {status}). "
+                f"Use `{self.settings.command(f'task wait {plan_id}')}`.",
+                kind="not_waiting",
+                extra={"task_id": plan_id, "status": status},
+            )
+        question = question_from(result.get("interaction"))
+        args: dict[str, Any] = {}
+        if question and question.get("tool_call_id"):
+            args["tool_call_id"] = question["tool_call_id"]
+        parsed: dict[str, str] = {}
+        if not skip:
+            parsed = parse_answers(answers, question)
+            args["answers"] = parsed
+        self.client.plan_interact(plan_id, args=args, skip=skip)
+        view: dict[str, Any] = {"task_id": plan_id, "kind": KIND_TASK, "status": "in_progress", "skipped": skip}
+        if parsed:
+            view["answers"] = parsed
+        view["next"] = self.settings.command(f"task wait {plan_id}")
+        return view
+
+    def cancel(self, task_id: str) -> dict[str, Any]:
+        if task_kind(task_id) != KIND_TASK:
+            raise UsageError(
+                "only tasks (plan_... ids) can be cancelled; conversions and translations finish on their own"
+            )
+        result, _, _ = self._follow(task_id, MAX_CHAIN_HOPS)
+        plan_id = _detail_str(result, "plan_id") or task_id
+        status = _detail_str(result, "status")
+        if status in PLAN_TERMINAL and not _detail_str(result, "next_plan_id"):
+            return {"task_id": plan_id, "kind": KIND_TASK, "status": status, "cancelled": False}
+        self.client.plan_terminate(plan_id)
+        return {"task_id": plan_id, "kind": KIND_TASK, "status": "terminated", "cancelled": True}
+
+    # ---- 文件 ----
+
+    def list_files(self, project_id: str) -> dict[str, Any]:
+        project_id = validate_id("project id", project_id)
+        data = self.client.project_file_tree(project_id) or {}
+        files: list[dict[str, Any]] = []
+        _collect_tree(files, "", data.get("tree") or [], 0)
+        return {
+            "project_id": project_id,
+            "project_url": self.settings.project_url(project_id),
+            "files": files,
+            "total": len(files),
+        }
+
+    def download_file(self, file_id: str, output_dir: Path, *, version: int | None = None) -> dict[str, Any]:
+        file_id = validate_id("file id", file_id)
+        info = self.client.file_get(file_id) or {}
+        item: dict[str, Any] = {"file_id": file_id, "name": _detail_str(info, "name") or file_id}
+        if version:
+            item["version"] = version
+        self._download_item(item, output_dir, strict=True)
+        return item
+
+    def download_results(self, view: dict[str, Any], output_dir: Path, *, deadline: Deadline | None = None) -> None:
+        """下载结果文件，下载失败的文件保留 ``error``。
+        任务本身成功时，视图额外包含 ``download_failed`` 错误（退出码 8），并用 ``next`` 只补下载失败文件，
+        避免调用方为此重新发起任务。任务本身失败时保留其原始结果，下载错误仅记录在各文件上。
+        """
+        files = view.get("files") or []
+        for item in files:
+            if view["kind"] == KIND_CONVERSION and not item.get("name"):
+                try:
+                    info = self.client.file_get(item["file_id"]) or {}
+                    item["name"] = _detail_str(info, "name")
+                except (ApiError, httpx.TransportError):
+                    pass
+                item["name"] = item.get("name") or f"converted.{view.get('target_type') or 'out'}"
+            self._download_item(item, output_dir, strict=False, deadline=deadline)
+        failed = [item for item in files if item.get("error")]
+        if failed and succeeded(view):
+            view["error"] = {
+                "kind": "download_failed",
+                "message": f"The {view['kind']} finished, but {len(failed)} of {len(files)} result file(s) were not "
+                "downloaded. Download them with the `next` command; do not start the task again.",
+                "exit_code": int(ExitCode.DOWNLOAD_FAILED),
+                "file_ids": [item["file_id"] for item in failed],
+            }
+            view["next"] = " && ".join(self._download_command(item, output_dir) for item in failed)
+
+    def _download_command(self, item: dict[str, Any], output_dir: Path) -> str:
+        version = f" --version {item['version']}" if item.get("version") else ""
+        directory = shlex.quote(str(output_dir.absolute()))
+        return self.settings.command(f"file download {item['file_id']}{version} --output-dir {directory}")
+
+    def _download_item(
+        self, item: dict[str, Any], output_dir: Path, *, strict: bool, deadline: Deadline | None = None
+    ) -> None:
+        try:
+            url = self._known_urls.pop(item["file_id"], "")
+            if not url:
+                link = self.client.file_download_url(item["file_id"], version=item.get("version")) or {}
+                url = _detail_str(link, "attachment_url") or _detail_str(link, "download_url")
+            if not url:
+                raise CliError(f"no download link for {item['file_id']}")
+            saved = download_url_to_dir(
+                self.storage, url, output_dir, item.get("name") or item["file_id"], deadline=deadline
+            )
+            item["saved_to"] = str(saved)
+            if not strict:
+                self.say(f"Saved {saved}")
+        except (ApiError, CliError, httpx.TransportError) as e:
+            if strict:
+                raise
+            item["error"] = getattr(e, "message", None) or str(e)
+            self.say(f"warning: could not download {item.get('name') or item['file_id']}: {item['error']}")
+
+
+def _collect_tree(out: list[dict[str, Any]], parent: str, nodes: list[Any], depth: int) -> None:
+    if depth > 32:
+        return
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        name = str(node.get("name") or "")
+        path = f"{parent}/{name}" if parent else name
+        detail = node.get("file") if isinstance(node.get("file"), dict) else None
+        if node.get("file_id") and (node.get("type") == "file" or detail):
+            item: dict[str, Any] = {"path": path, "file_id": node["file_id"]}
+            if node.get("kind"):
+                item["kind"] = node["kind"]
+            if detail:
+                if detail.get("file_path"):
+                    item["path"] = detail["file_path"]
+                for key in ("file_type", "category", "mime_type", "size", "updated_at"):
+                    if detail.get(key) not in (None, ""):
+                        item[key] = detail[key]
+            out.append(item)
+        _collect_tree(out, path, node.get("children") or [], depth + 1)
+
+
+def _convert_source_type(name: str) -> str:
+    ext = posixpath.splitext(name or "")[1].lower().lstrip(".")
+    return CONVERT_SOURCE_BY_EXT.get(ext, ext)
+
+
+def _unsupported_conversion(supported: list[Any], name: str, source: str, target: str) -> CliError:
+    pairs = [c for c in supported if isinstance(c, dict)]
+    targets = sorted({str(c.get("target_type")) for c in pairs if str(c.get("source_type", "")).lower() == source})
+    if targets:
+        message = (
+            f"Cheso can't convert {name} ({source}) to {target}. Supported targets for this file: {', '.join(targets)}."
+        )
+    else:
+        sources = sorted({str(c.get("source_type")) for c in pairs})
+        message = (
+            f"Cheso can't convert {name}: type {source or 'unknown'!r} has no conversions. "
+            f"Convertible types: {', '.join(sources)}."
+        )
+    return CliError(
+        message,
+        exit_code=ExitCode.USAGE,
+        kind="unsupported_conversion",
+        extra={"source_type": source, "target_type": target, "supported_targets": targets},
+    )
+
+
+def _transient(e: Exception) -> bool:
+    if isinstance(e, httpx.TransportError):
+        return True
+    if isinstance(e, ApiError):
+        status = e.http_status or 0
+        return status >= 500 or status == 429
+    return False
+
+
+def _brief(e: Exception) -> str:
+    if isinstance(e, ApiError):
+        return f"http {e.http_status}" if e.http_status else e.message
+    return e.__class__.__name__
+
+
+def _elapsed(seconds: float) -> str:
+    seconds = max(int(seconds), 0)
+    return f"{seconds // 60:02d}:{seconds % 60:02d}"