cheso-cli 0.2.0__py3-none-any.whl

cheso_cli/cli.py

@@ -0,0 +1,864 @@
+# pylint: disable=broad-except
+"""cheso CLI：在终端或编程 Agent 中使用 Cheso，支持任务、文件、转换、翻译、登录和技能安装。"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import sys
+import time
+import webbrowser
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, TextIO
+
+import httpx
+
+from cheso_cli import oauth, skill_install
+from cheso_cli.auth import TOKEN_SOURCE_ENV, TOKEN_SOURCE_FLAG, OAuthSession, login_hint, resolve_token_source
+from cheso_cli.client import ApiError, ChesoClient, Deadline, TimeLimitReached
+from cheso_cli.config import DEFAULT_SITE, ENV_TOKEN, SITES, VERSION, Settings, resolve_settings
+from cheso_cli.credentials import FILE_NAME as CREDENTIALS_FILE
+from cheso_cli.credentials import CredentialStore, default_config_dir
+from cheso_cli.errors import CliError, ExitCode, LoginRequired, UsageError
+from cheso_cli.legacy_commands import (
+    cmd_plan_create,
+    cmd_plan_get,
+    cmd_profile,
+    cmd_project_create,
+    cmd_project_delete,
+    cmd_project_fork,
+    cmd_project_get,
+    cmd_project_list,
+    cmd_project_update,
+    cmd_session_create,
+)
+from cheso_cli.tasks import (
+    AGENT_TYPES,
+    DEFAULT_WAIT_TIMEOUT,
+    KIND_TASK,
+    TRANSLATION_LANGUAGES,
+    Tasks,
+    is_credit_failure,
+    succeeded,
+    validate_id,
+)
+from cheso_cli.transfer import new_storage_client, upload_file
+
+DEFAULT_BASE_URL = SITES[DEFAULT_SITE]
+
+UNAUTHORIZED_CODES = {1001, 2401, 2402, 2403, 2404}
+CODE_SCOPE_INSUFFICIENT = 2410
+CODE_RATE_LIMITED = 2600
+CODE_PROJECT_BUSY = 2614
+# 项目忙：有运行中的任务（2614），或其他操作短暂持锁（2620 为项目锁，2621 为文件或目录锁），
+# 或运行中的任务阻止文件变更（2623），或有人正在浏览器中编辑（2624）。这些状态都会自行解除。
+PROJECT_BUSY_MESSAGES = {
+    CODE_PROJECT_BUSY: "This project already has a running task; wait for it to finish, then retry.",
+    2620: "Another operation on this project (starting a task, a rollback or a file edit) is in progress; "
+    "retry in a few seconds.",
+    2621: "Another operation is changing this file or folder; retry in a few seconds.",
+    2623: "A task is running in this project, so its files can't change right now; retry when it finishes.",
+    2624: "Someone is editing files in this project in the browser; retry when they finish.",
+}
+
+EXIT_CODES_HELP = """exit codes:
+  0  success
+  1  error
+  2  usage error
+  3  the task is waiting for your answer (cheso task reply)
+  4  login required (cheso login)
+  5  not enough credits
+  6  still running when --timeout passed (cheso task wait / cheso login --wait again)
+  7  rate limited or project busy; retry later
+  8  the task succeeded, but some result files were not downloaded (run the "next" command)
+"""
+
+
+@dataclass
+class Context:
+    """命令运行所需的上下文；测试可注入传输层、时钟和输入输出流。"""
+
+    args: argparse.Namespace
+    env: Mapping[str, str]
+    out: TextIO
+    err: TextIO
+    transport: httpx.BaseTransport | None = None
+    storage_transport: httpx.BaseTransport | None = None
+    sleep: Callable[[float], None] = time.sleep
+    clock: Callable[[], float] = time.monotonic
+    now: Callable[[], float] = time.time
+    browser_open: Callable[[str], Any] = webbrowser.open
+    credentials_path: Path | None = None
+    # 命令开始时的 ``clock`` 值；--timeout 从此刻起计时。
+    started: float = 0.0
+    token_source: str = ""
+    _settings: Settings | None = None
+    _client: ChesoClient | None = None
+    _storage: httpx.Client | None = None
+    _store: CredentialStore | None = None
+    _closers: list[Callable[[], None]] = field(default_factory=list)
+
+    @property
+    def json(self) -> bool:
+        return bool(getattr(self.args, "json", False))
+
+    @property
+    def settings(self) -> Settings:
+        if self._settings is None:
+            self._settings = resolve_settings(
+                site=getattr(self.args, "site", None),
+                base_url=getattr(self.args, "base_url", None),
+                env=self.env,
+                logged_in_default=self.store.default_base_url,
+            )
+        return self._settings
+
+    @property
+    def store(self) -> CredentialStore:
+        if self._store is None:
+            path = self.credentials_path or default_config_dir(self.env) / CREDENTIALS_FILE
+            self._store = CredentialStore(path)
+        return self._store
+
+    @property
+    def client(self) -> ChesoClient:
+        if self._client is None:
+            source, self.token_source = resolve_token_source(
+                self.settings,
+                self.store,
+                token_flag=getattr(self.args, "token", None),
+                env=self.env,
+                transport=self.transport,
+                now=self.now,
+            )
+            self._client = ChesoClient(
+                self.settings.base_url,
+                auth=source,
+                transport=self.transport,
+                headers=self.settings.extra_headers(),
+            )
+            self._closers.append(self._client.close)
+        return self._client
+
+    @property
+    def storage(self) -> httpx.Client:
+        if self._storage is None:
+            self._storage = new_storage_client(self.storage_transport)
+            self._closers.append(self._storage.close)
+        return self._storage
+
+    def tasks(self) -> Tasks:
+        return Tasks(
+            self.client,
+            self.settings,
+            self.storage,
+            progress=self.err,
+            sleep=self.sleep,
+            clock=self.clock,
+            now=self.now,
+        )
+
+    def close(self) -> None:
+        for closer in reversed(self._closers):
+            closer()
+
+    # ---- 输出 ----
+
+    def emit(self, data: Any, human: Callable[[], None] | None = None) -> None:
+        if self.json or human is None:
+            print(json.dumps(data, ensure_ascii=False, indent=2), file=self.out)
+        else:
+            human()
+
+    def line(self, text: str = "") -> None:
+        print(text, file=self.out)
+
+
+# ---- 账号 ----
+
+
+def cmd_login(ctx: Context) -> int:
+    args = ctx.args
+    if args.wait and args.device:
+        raise UsageError("use --device to start a sign-in with a code, or --wait to keep waiting for one, not both")
+    if args.no_wait and not args.device:
+        raise UsageError("--no-wait only applies to --device")
+    if args.device or args.wait:
+        return _login_with_code(ctx)
+    oauth.login(
+        ctx.settings,
+        ctx.store,
+        open_browser=not args.no_browser,
+        timeout=args.timeout,
+        port=args.port,
+        transport=ctx.transport,
+        browser_open=ctx.browser_open,
+        out=ctx.err,
+        now=ctx.now,
+    )
+    return _logged_in(ctx)
+
+
+def _login_with_code(ctx: Context) -> int:
+    """设备码登录（RFC 8628）：用户在任意设备上打开 Cheso 页面，输入此处显示的短码。"""
+    args = ctx.args
+    # --timeout 从命令开始计时，约束每次请求，包括读取完整响应的时间。
+    deadline = Deadline(ctx.started + max(args.timeout, 0.0), ctx.clock)
+    if args.device:
+        try:
+            login = oauth.start_device_login(
+                ctx.settings,
+                ctx.store,
+                transport=ctx.transport,
+                now=ctx.now,
+                deadline=deadline,
+            )
+        except TimeLimitReached as e:
+            raise CliError(
+                f"--timeout passed before {ctx.settings.base_url} answered; nothing was started. "
+                "Retry with a longer --timeout.",
+                kind="network",
+            ) from e
+    else:
+        login = oauth.pending_device_login(ctx.settings, ctx.store)
+        if login is None:
+            raise UsageError(f"no sign-in is waiting; start one with `{ctx.settings.command('login --device')}`")
+    view = _device_view(ctx, login)
+    _print_device_instructions(ctx, login)
+    if args.no_wait:
+        ctx.emit(view, lambda: ctx.line(f"Then run: {view['next']}"))
+        return ExitCode.OK
+    creds = oauth.wait_device_login(
+        ctx.settings,
+        ctx.store,
+        deadline=deadline,
+        poll_first=not args.device,
+        transport=ctx.transport,
+        sleep=ctx.sleep,
+        now=ctx.now,
+        out=ctx.err,
+    )
+    if creds is None:
+        view["timed_out"] = True
+        ctx.emit(view, lambda: ctx.line(f"Still waiting for the code to be entered. Next: {view['next']}"))
+        return ExitCode.WAIT_TIMEOUT
+    return _logged_in(ctx, deadline=oauth.after_login(deadline))
+
+
+def _device_view(ctx: Context, login: oauth.DeviceLogin) -> dict[str, Any]:
+    expires_in = max(int(login.expires_at - ctx.now()), 0)
+    return {
+        "logged_in": False,
+        "pending": True,
+        "base_url": ctx.settings.base_url,
+        "verification_uri": login.verification_uri,
+        "user_code": login.user_code,
+        "expires_in": expires_in,
+        "next": ctx.settings.command("login --wait"),
+    }
+
+
+def _print_device_instructions(ctx: Context, login: oauth.DeviceLogin) -> None:
+    minutes = max(round((login.expires_at - ctx.now()) / 60), 1)
+    print(
+        f"To sign in to {ctx.settings.base_url}, open this page on any device:\n\n"
+        f"  {login.verification_uri}\n\n"
+        f"and enter the code:  {login.user_code}\n\n"
+        f"The code expires in about {minutes} min. Only enter it if you started this sign-in yourself.",
+        file=ctx.err,
+    )
+
+
+def _logged_in(ctx: Context, *, deadline: Deadline | None = None) -> int:
+    session = OAuthSession(ctx.settings, ctx.store, transport=ctx.transport, now=ctx.now)
+    user: dict[str, Any] = {}
+    with (
+        ChesoClient(
+            ctx.settings.base_url, auth=session, transport=ctx.transport, headers=ctx.settings.extra_headers()
+        ) as client,
+        client.time_limit(deadline) if deadline else contextlib.nullcontext(),
+    ):
+        try:
+            user = (client.whoami() or {}).get("user") or {}
+        except (ApiError, CliError, httpx.TransportError) as e:
+            print(f"warning: logged in, but looking up the account failed ({e})", file=ctx.err)
+    data = {"logged_in": True, "base_url": ctx.settings.base_url, "user": _user_fields(user)}
+    ctx.emit(data, lambda: ctx.line(f"Logged in to {ctx.settings.base_url} as {_user_label(user)}."))
+    if ctx.env.get(ENV_TOKEN, "").strip():
+        print(f"note: {ENV_TOKEN} is set and takes precedence over this login.", file=ctx.err)
+    return ExitCode.OK
+
+
+def cmd_logout(ctx: Context) -> int:
+    removed = oauth.logout(ctx.settings, ctx.store, transport=ctx.transport, out=ctx.err)
+    data = {"logged_out": removed, "base_url": ctx.settings.base_url}
+    message = f"Logged out of {ctx.settings.base_url}." if removed else f"Not logged in to {ctx.settings.base_url}."
+    ctx.emit(data, lambda: ctx.line(message))
+    if ctx.env.get(ENV_TOKEN, "").strip():
+        print(f"note: {ENV_TOKEN} is still set; unset it to stop using that token.", file=ctx.err)
+    return ExitCode.OK
+
+
+def _user_fields(user: dict[str, Any]) -> dict[str, str]:
+    return {"user_id": str(user.get("user_id") or ""), "username": str(user.get("username") or "")}
+
+
+def _user_label(user: dict[str, Any]) -> str:
+    name, uid = user.get("username") or "", user.get("user_id") or ""
+    return f"{name} ({uid})" if name and uid else (name or uid or "unknown user")
+
+
+def cmd_whoami(ctx: Context) -> int:
+    user = (ctx.client.whoami() or {}).get("user") or {}
+    data = {"base_url": ctx.settings.base_url, "user": _user_fields(user), "token_source": ctx.token_source}
+    ctx.emit(
+        data,
+        lambda: ctx.line(f"{_user_label(user)} on {ctx.settings.base_url} (credentials: {ctx.token_source})"),
+    )
+    return ExitCode.OK
+
+
+def cmd_credits(ctx: Context) -> int:
+    data = ctx.tasks().credits()
+
+    def human() -> None:
+        ctx.line(f"Available credits: {data['available']}")
+        if data["available"] <= 0:
+            ctx.line(f"Top up at {data['topup_url']}")
+
+    ctx.emit(data, human)
+    return ExitCode.OK
+
+
+# ---- 任务 ----
+
+
+def _output_dir(args: argparse.Namespace) -> Path | None:
+    if getattr(args, "no_download", False):
+        return None
+    return Path(getattr(args, "output_dir", None) or ".").expanduser()
+
+
+def view_exit_code(view: dict[str, Any]) -> ExitCode:
+    """返回等待中的任务、转换或翻译对应的退出码。"""
+    if view.get("needs_input"):
+        return ExitCode.NEEDS_INPUT
+    if not view.get("done"):
+        return ExitCode.WAIT_TIMEOUT
+    # 优先保留任务本身的结果；只有任务成功时，文件下载失败才影响退出码。
+    if succeeded(view):
+        return ExitCode(view["error"]["exit_code"]) if view.get("error") else ExitCode.OK
+    if view.get("kind") == KIND_TASK and is_credit_failure(str(view.get("failure_reason") or "")):
+        return ExitCode.INSUFFICIENT_CREDITS
+    return ExitCode.ERROR
+
+
+def render_view(ctx: Context, view: dict[str, Any]) -> None:
+    kind = view.get("kind", "task")
+    title = f" - {view['title']}" if view.get("title") else ""
+    ctx.line(f"{kind.capitalize()} {view.get('task_id')}: {view.get('status') or 'unknown'}{title}")
+    if view.get("continued_from"):
+        ctx.line(f"  (continued from {view['continued_from']})")
+    if view.get("project_url"):
+        ctx.line(f"Project: {view['project_url']}")
+    if view.get("answer"):
+        ctx.line()
+        ctx.line(view["answer"].rstrip())
+        if view.get("answer_truncated"):
+            ctx.line("(answer truncated; the full content is in the result files and the project)")
+    files = view.get("files") or []
+    if files:
+        ctx.line()
+        ctx.line("Files:")
+        for item in files:
+            label = item.get("name") or item.get("path") or item["file_id"]
+            if item.get("saved_to"):
+                ctx.line(f"  {label} -> {item['saved_to']}")
+            elif item.get("error"):
+                ctx.line(f"  {label} ({item['file_id']}): download failed: {item['error']}")
+            else:
+                ctx.line(f"  {label} ({item['file_id']})")
+    question = view.get("question")
+    if view.get("needs_input") and question:
+        ctx.line()
+        ctx.line("Cheso is asking:")
+        for i, q in enumerate(question.get("questions") or [], 1):
+            header = f"[{q['header']}] " if q.get("header") else ""
+            multi = " (choose one or more)" if q.get("multi_select") else ""
+            ctx.line(f"  {i}. {header}{q['question']}{multi}")
+            for option in q.get("options") or []:
+                desc = f" - {option['description']}" if option.get("description") else ""
+                ctx.line(f"     * {option['label']}{desc}")
+        if question.get("raw"):
+            ctx.line(f"  {json.dumps(question['raw'], ensure_ascii=False)}")
+    if view.get("failure_reason"):
+        ctx.line(f"Reason: {view['failure_reason']}")
+    if view.get("topup_url"):
+        ctx.line(f"Top up credits: {view['topup_url']}")
+    if view.get("error"):
+        ctx.line(f"Error: {view['error']['message']}")
+    if view.get("timed_out"):
+        ctx.line("Still running; it continues on Cheso.")
+    if view.get("next"):
+        ctx.line(f"Next: {view['next']}")
+
+
+def cmd_task_create(ctx: Context) -> int:
+    args = ctx.args
+    tasks = ctx.tasks()
+    view = tasks.create_task(
+        prompt=args.prompt,
+        paths=[Path(p).expanduser() for p in args.file],
+        file_ids=args.file_id,
+        project_id=args.project,
+        agent_type=args.agent_type,
+    )
+    if not args.wait:
+        ctx.emit(view, lambda: render_view(ctx, view))
+        return ExitCode.OK
+    tasks.say(f"Started task {view['task_id']} ({view['project_url'] or 'new project'}); waiting ...")
+    waited = _wait_started(ctx, tasks, view["task_id"])
+    if view.get("uploaded_files"):
+        waited["uploaded_files"] = view["uploaded_files"]
+    ctx.emit(waited, lambda: render_view(ctx, waited))
+    return view_exit_code(waited)
+
+
+def _wait_started(ctx: Context, tasks: Tasks, task_id: str) -> dict[str, Any]:
+    """等待当前命令刚发起的任务；等待失败时，错误中仍包含已发起的任务 ID。"""
+    hint = f"It was started as {task_id}; follow it with `{ctx.settings.command(f'task wait {task_id}')}`."
+    try:
+        return tasks.wait(task_id, timeout=ctx.args.timeout, output_dir=_output_dir(ctx.args), started=ctx.started)
+    except KeyboardInterrupt:
+        print(f"Stopped waiting. {hint}", file=ctx.err)
+        raise
+    except (CliError, ApiError, httpx.TransportError) as e:
+        if isinstance(e, CliError):
+            err = e
+        elif isinstance(e, ApiError):
+            err = api_error(e, ctx)
+        else:
+            err = CliError(f"Lost the connection to {ctx.settings.base_url} ({e.__class__.__name__}).", kind="network")
+        err.message = f"{err.message} {hint}"
+        err.extra.setdefault("task_id", task_id)
+        raise err from e
+
+
+def cmd_task_wait(ctx: Context) -> int:
+    args = ctx.args
+    view = ctx.tasks().wait(args.task_id, timeout=args.timeout, output_dir=_output_dir(args), started=ctx.started)
+    ctx.emit(view, lambda: render_view(ctx, view))
+    return view_exit_code(view)
+
+
+def cmd_task_get(ctx: Context) -> int:
+    view = ctx.tasks().get(ctx.args.task_id)
+    ctx.emit(view, lambda: render_view(ctx, view))
+    return ExitCode.OK
+
+
+def cmd_task_reply(ctx: Context) -> int:
+    args = ctx.args
+    view = ctx.tasks().reply(args.task_id, args.answer, args.skip)
+
+    def human() -> None:
+        verb = "Skipped the question" if view["skipped"] else "Sent the answer"
+        ctx.line(f"{verb} for task {view['task_id']}. Next: {view['next']}")
+
+    ctx.emit(view, human)
+    return ExitCode.OK
+
+
+def cmd_task_cancel(ctx: Context) -> int:
+    view = ctx.tasks().cancel(ctx.args.task_id)
+    if view["cancelled"]:
+        message = f"Cancelled task {view['task_id']}. Work done so far stays in the project."
+    else:
+        message = f"Task {view['task_id']} had already finished ({view['status']}); nothing to cancel."
+    ctx.emit(view, lambda: ctx.line(message))
+    return ExitCode.OK
+
+
+# ---- 文件 ----
+
+
+def cmd_file_upload(ctx: Context) -> int:
+    args = ctx.args
+    project = validate_id("project id", args.project) if args.project else None
+    result = upload_file(ctx.client, ctx.storage, Path(args.path).expanduser(), project_id=project, now=ctx.now)
+    data = result.to_dict()
+    data["next"] = ctx.settings.command(f'task create --file-id {result.file_id} --prompt "..."')
+    where = f" into {result.file_path} of project {result.project_id}" if result.project_id else ""
+    ctx.emit(data, lambda: ctx.line(f"Uploaded {result.name}{where}: file_id {result.file_id}"))
+    return ExitCode.OK
+
+
+def cmd_file_list(ctx: Context) -> int:
+    data = ctx.tasks().list_files(ctx.args.project)
+
+    def human() -> None:
+        ctx.line(f"{data['total']} file(s) in {data['project_url']}")
+        for item in data["files"]:
+            size = f"{item['size']:>10}" if isinstance(item.get("size"), int) else " " * 10
+            ctx.line(f"  {item['file_id']}  {size}  {item['path']}")
+
+    ctx.emit(data, human)
+    return ExitCode.OK
+
+
+def cmd_file_download(ctx: Context) -> int:
+    args = ctx.args
+    item = ctx.tasks().download_file(args.file_id, Path(args.output_dir or ".").expanduser(), version=args.version)
+    ctx.emit(item, lambda: ctx.line(f"Saved {item['saved_to']}"))
+    return ExitCode.OK
+
+
+# ---- 转换 / 翻译 ----
+
+
+def _start_job(ctx: Context, view: dict[str, Any], tasks: Tasks) -> int:
+    args = ctx.args
+    if not args.wait:
+        ctx.emit(view, lambda: render_view(ctx, view))
+        return ExitCode.OK
+    waited = _wait_started(ctx, tasks, view["task_id"])
+    ctx.emit(waited, lambda: render_view(ctx, waited))
+    return view_exit_code(waited)
+
+
+def cmd_convert(ctx: Context) -> int:
+    tasks = ctx.tasks()
+    return _start_job(ctx, tasks.start_conversion(ctx.args.file_id, ctx.args.to), tasks)
+
+
+def cmd_translate(ctx: Context) -> int:
+    tasks = ctx.tasks()
+    return _start_job(ctx, tasks.start_translation(ctx.args.file_id, ctx.args.to, ctx.args.source), tasks)
+
+
+# ---- 技能 ----
+
+
+def cmd_skill_install(ctx: Context) -> int:
+    args = ctx.args
+    home = Path(ctx.env["HOME"]) if ctx.env.get("HOME") else None
+    results = skill_install.install(args.target, project=args.project, force=args.force, home=home)
+
+    def human() -> None:
+        for r in results:
+            ctx.line(f"{r['target']}: {r['action']} {r['path']}")
+
+    ctx.emit({"results": results}, human)
+    return ExitCode.OK
+
+
+def cmd_skill_show(ctx: Context) -> int:
+    ctx.out.write(skill_install.skill_text())
+    return ExitCode.OK
+
+
+# ---- 错误处理 ----
+
+
+def api_error(e: ApiError, ctx: Context) -> CliError:
+    """将 Manager 错误映射为退出码，并在消息中说明后续操作。"""
+    code, status = e.code, e.http_status or 0
+    extra = {k: v for k, v in {"api_code": code, "http_status": e.http_status, "span_id": e.span_id}.items() if v}
+    if status == 401 or code in UNAUTHORIZED_CODES:
+        if ctx.token_source == TOKEN_SOURCE_ENV:
+            message = f"The token in {ENV_TOKEN} was rejected (expired or revoked)."
+        elif ctx.token_source == TOKEN_SOURCE_FLAG:
+            message = "The token given with --token was rejected (expired or revoked)."
+        else:
+            message = f"The Cheso login has expired or was revoked. Run `{login_hint(ctx.settings)}`."
+        err = LoginRequired(message)
+        err.extra.update(extra)
+        return err
+    if e.retry_after:
+        extra["retry_after"] = e.retry_after
+    if code in PROJECT_BUSY_MESSAGES:
+        return CliError(PROJECT_BUSY_MESSAGES[code], exit_code=ExitCode.RETRYABLE, kind="project_busy", extra=extra)
+    if code == CODE_RATE_LIMITED or status == 429 or (code is not None and 2610 <= code <= 2619):
+        if e.retry_after:
+            message = f"Cheso rate limit reached; retry after {e.retry_after} s."
+        elif code is not None and 2610 <= code <= 2619:
+            message = "Too many Cheso tasks are running at once for this account; retry when one finishes."
+        else:
+            message = "Cheso rate limit reached; retry in about a minute."
+        return CliError(message, exit_code=ExitCode.RETRYABLE, kind="rate_limited", extra=extra)
+    if code == CODE_SCOPE_INSUFFICIENT:
+        return CliError(
+            "This action is not available to the Cheso CLI login; use the Cheso website "
+            f"(or a personal API token in {ENV_TOKEN}).",
+            kind="not_allowed",
+            extra=extra,
+        )
+    if code is not None and 2700 <= code <= 2799:
+        return CliError(f"Cheso usage limit reached: {e.message} (code {code}).", kind="quota", extra=extra)
+    if status >= 500:
+        return CliError(
+            f"Cheso is temporarily unavailable (http {status}); retry later.", kind="unavailable", extra=extra
+        )
+    if code is None and not isinstance(e.body, dict):
+        return CliError(f"The request failed (http {status}).", kind="http_error", extra=extra)
+    if status == 404:
+        return CliError(f"Not found, or you have no access ({e.message}).", kind="not_found", extra=extra)
+    if status == 403:
+        return CliError(f"Permission denied ({e.message}).", kind="forbidden", extra=extra)
+    suffix = f" (code {code})" if code is not None else ""
+    return CliError(f"Cheso rejected the request: {e.message}{suffix}.", kind="api_error", extra=extra)
+
+
+def report_error(ctx: Context, err: CliError) -> None:
+    print(f"error: {err.message}", file=ctx.err)
+    if ctx.json:
+        body = {"kind": err.kind, "message": err.message, "exit_code": int(err.exit_code), **err.extra}
+        print(json.dumps({"error": body}, ensure_ascii=False, indent=2), file=ctx.out)
+
+
+# ---- 参数解析 ----
+
+
+def _common_options(parser: argparse.ArgumentParser, *, suppress: bool) -> None:
+    default = argparse.SUPPRESS if suppress else None
+    parser.add_argument(
+        "--site",
+        choices=tuple(SITES),
+        default=default,
+        help=f"Cheso site: global ({SITES['global']}, default) or cn ({SITES['cn']})",
+    )
+    parser.add_argument("--base-url", default=default, help="API base URL; overrides --site and CHESO_BASE_URL")
+    parser.add_argument("--token", default=default, help=f"Cheso token; overrides {ENV_TOKEN} and the stored login")
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=argparse.SUPPRESS if suppress else False,
+        help="print one JSON document to stdout (progress goes to stderr)",
+    )
+
+
+class _Builder:
+    """给每个命令添加公共选项，使选项既能放在命令名前，也能放在命令名后。"""
+
+    def __init__(self) -> None:
+        self.common = argparse.ArgumentParser(add_help=False)
+        _common_options(self.common, suppress=True)
+
+    def add(self, subparsers: Any, name: str, func: Callable[[Context], int] | None, **kwargs: Any) -> Any:
+        parser = subparsers.add_parser(name, parents=[self.common], **kwargs)
+        if func is not None:
+            parser.set_defaults(func=func)
+        return parser
+
+
+def _wait_options(parser: argparse.ArgumentParser, *, no_download: bool) -> None:
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_WAIT_TIMEOUT,
+        metavar="SECONDS",
+        help=f"stop waiting after this many seconds (default {int(DEFAULT_WAIT_TIMEOUT)}); the task keeps running",
+    )
+    parser.add_argument("--output-dir", default=None, metavar="DIR", help="where result files go (default: .)")
+    if no_download:
+        parser.add_argument("--no-download", action="store_true", help="do not download result files")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="cheso",
+        description="Use Cheso from the terminal: research reports, PPT, web pages, posters, videos, images, "
+        "document translation and format conversion.",
+        epilog=EXIT_CODES_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--version", action="version", version=f"cheso-cli {VERSION}")
+    _common_options(p, suppress=False)
+    b = _Builder()
+    sub = p.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    c = b.add(sub, "login", cmd_login, help="log in with the browser (OAuth), or with a code (--device)")
+    c.add_argument("--no-browser", action="store_true", help="only print the sign-in URL")
+    c.add_argument("--port", type=int, default=0, help="loopback callback port (default: random)")
+    c.add_argument(
+        "--device",
+        action="store_true",
+        help="sign in with a code entered on any device; for SSH, containers and coding agents",
+    )
+    c.add_argument("--no-wait", action="store_true", help="with --device: print the page and code, then return")
+    c.add_argument("--wait", action="store_true", help="keep waiting for a sign-in started with --device")
+    c.add_argument(
+        "--timeout", type=float, default=oauth.DEFAULT_LOGIN_TIMEOUT, metavar="SECONDS", help="how long to wait (300)"
+    )
+    b.add(sub, "logout", cmd_logout, help="revoke the login and delete the stored tokens")
+    b.add(sub, "whoami", cmd_whoami, help="show the current account")
+    b.add(sub, "credits", cmd_credits, help="show available credits")
+
+    task = b.add(sub, "task", None, help="create, wait for and manage tasks")
+    task_sub = task.add_subparsers(dest="task_cmd", required=True, metavar="ACTION")
+    c = b.add(task_sub, "create", cmd_task_create, help="start a task")
+    c.add_argument("--prompt", required=True, help="what Cheso should produce")
+    c.add_argument("--file", action="append", default=[], metavar="PATH", help="upload a local file (repeatable)")
+    c.add_argument("--file-id", action="append", default=[], metavar="ID", help="attach an uploaded file (repeatable)")
+    c.add_argument("--project", default=None, metavar="ID", help="continue in this project")
+    c.add_argument("--agent-type", choices=AGENT_TYPES, default=None, help="cheso (default) or image_edit")
+    c.add_argument("--wait", action="store_true", help="wait for the result and download it")
+    _wait_options(c, no_download=False)
+    c = b.add(task_sub, "wait", cmd_task_wait, help="wait for a task, conversion or translation")
+    c.add_argument("task_id")
+    _wait_options(c, no_download=True)
+    c = b.add(task_sub, "get", cmd_task_get, help="show a task, conversion or translation")
+    c.add_argument("task_id")
+    c = b.add(task_sub, "reply", cmd_task_reply, help="answer the question a task is asking")
+    c.add_argument("task_id")
+    c.add_argument(
+        "--answer",
+        action="append",
+        default=[],
+        metavar="QUESTION=ANSWER",
+        help="answer keyed by the exact question text, its number (1=...) or header; repeatable",
+    )
+    c.add_argument("--skip", action="store_true", help="skip the question and let Cheso decide")
+    c = b.add(task_sub, "cancel", cmd_task_cancel, help="stop a running task")
+    c.add_argument("task_id")
+
+    file_cmd = b.add(sub, "file", None, help="upload, list and download files")
+    file_sub = file_cmd.add_subparsers(dest="file_cmd", required=True, metavar="ACTION")
+    c = b.add(file_sub, "upload", cmd_file_upload, help="upload a local file; prints its file_id")
+    c.add_argument("path")
+    c.add_argument("--project", default=None, metavar="ID", help="put it in this project's attachments folder")
+    c = b.add(file_sub, "list", cmd_file_list, help="list a project's files")
+    c.add_argument("--project", required=True, metavar="ID")
+    c = b.add(file_sub, "download", cmd_file_download, help="download a file")
+    c.add_argument("file_id")
+    c.add_argument("--version", type=int, default=None, help="this version of the file (default: the latest)")
+    c.add_argument("--output-dir", default=None, metavar="DIR", help="where to save it (default: .)")
+
+    c = b.add(sub, "convert", cmd_convert, help="convert a file to another format")
+    c.add_argument("file_id")
+    c.add_argument("--to", required=True, metavar="TYPE", help="target format, e.g. pdf, docx, pptx, mp4")
+    c.add_argument("--wait", action="store_true", help="wait and download the result")
+    _wait_options(c, no_download=False)
+    c = b.add(sub, "translate", cmd_translate, help="translate a document")
+    c.add_argument("file_id")
+    c.add_argument("--to", required=True, metavar="LANG", help=f"target language: {', '.join(TRANSLATION_LANGUAGES)}")
+    c.add_argument("--from", dest="source", default=None, metavar="LANG", help="source language (default: detect)")
+    c.add_argument("--wait", action="store_true", help="wait and download the result")
+    _wait_options(c, no_download=False)
+
+    skill = b.add(sub, "skill", None, help="install the Agent Skill for Claude Code / Codex")
+    skill_sub = skill.add_subparsers(dest="skill_cmd", required=True, metavar="ACTION")
+    c = b.add(skill_sub, "install", cmd_skill_install, help="install SKILL.md")
+    c.add_argument("--target", choices=("claude", "codex", "all"), default="all")
+    c.add_argument("--project", action="store_true", help="install into ./.claude and ./.agents instead of ~")
+    c.add_argument("--force", action="store_true", help="replace a modified SKILL.md")
+    b.add(skill_sub, "show", cmd_skill_show, help="print SKILL.md")
+
+    # 保留第一版的底层 API 命令，直接输出原始 JSON。
+    b.add(sub, "profile", cmd_profile, help="GET /api/v1/profile")
+    proj = b.add(sub, "project", None, help="Project lifecycle (raw API)")
+    proj_sub = proj.add_subparsers(dest="project_cmd", required=True)
+    c = b.add(proj_sub, "create", cmd_project_create, help="POST /api/v1/projects/create")
+    c.add_argument("--description", "-d", default=None)
+    c = b.add(proj_sub, "list", cmd_project_list, help="GET /api/v1/projects")
+    c.add_argument("--status", default=None, help="active|archived")
+    c.add_argument("--starred", choices=("true", "false"), default=None)
+    c.add_argument("--sort-by", default=None, help="starred")
+    c.add_argument("--page", type=int, default=None)
+    c.add_argument("--page-size", type=int, default=None)
+    c = b.add(proj_sub, "get", cmd_project_get, help="GET /api/v1/projects/{id}")
+    c.add_argument("project_id")
+    c = b.add(proj_sub, "update", cmd_project_update, help="PUT /api/v1/projects/{id}")
+    c.add_argument("project_id")
+    c.add_argument("--description", "-d", default=None)
+    c.add_argument("--starred", choices=("true", "false"), default=None)
+    c.add_argument("--cover-file-id", default=None)
+    c.add_argument("--cover-file-version", type=int, default=None)
+    c = b.add(proj_sub, "delete", cmd_project_delete, help="DELETE /api/v1/projects/{id}")
+    c.add_argument("project_id")
+    c = b.add(proj_sub, "fork", cmd_project_fork, help="POST /api/v1/projects/{id}/fork")
+    c.add_argument("project_id")
+    c.add_argument("--description", "-d", default=None)
+    sess = b.add(sub, "session", None, help="Session (raw API)")
+    sess_sub = sess.add_subparsers(dest="session_cmd", required=True)
+    c = b.add(sess_sub, "create", cmd_session_create)
+    c.add_argument("--project-id", required=True)
+    c.add_argument("--title", default="默认会话")
+    plan = b.add(sub, "plan", None, help="Plan (raw API)")
+    plan_sub = plan.add_subparsers(dest="plan_cmd", required=True)
+    c = b.add(plan_sub, "create", cmd_plan_create)
+    c.add_argument("--project-id", required=True)
+    c.add_argument("--prompt", required=True)
+    c.add_argument("--session-id", default=None)
+    c = b.add(plan_sub, "get", cmd_plan_get)
+    c.add_argument("plan_id")
+    return p
+
+
+def run(
+    argv: list[str] | None = None,
+    *,
+    env: Mapping[str, str] | None = None,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+    transport: httpx.BaseTransport | None = None,
+    storage_transport: httpx.BaseTransport | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+    now: Callable[[], float] = time.time,
+    browser_open: Callable[[str], Any] = webbrowser.open,
+    credentials_path: Path | None = None,
+) -> int:
+    """运行一个命令并返回退出码，含义见 ``EXIT_CODES_HELP``。"""
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as e:
+        return int(e.code or 0)
+    ctx = Context(
+        args=args,
+        env=os.environ if env is None else env,
+        out=stdout or sys.stdout,
+        err=stderr or sys.stderr,
+        transport=transport,
+        storage_transport=storage_transport,
+        sleep=sleep,
+        clock=clock,
+        now=now,
+        browser_open=browser_open,
+        credentials_path=credentials_path,
+        started=clock(),
+    )
+    try:
+        return int(args.func(ctx))
+    except CliError as e:
+        report_error(ctx, e)
+        return int(e.exit_code)
+    except ApiError as e:
+        err = api_error(e, ctx)
+        report_error(ctx, err)
+        return int(err.exit_code)
+    except httpx.TransportError as e:
+        err = CliError(
+            f"cannot reach {ctx.settings.base_url} ({e.__class__.__name__}); check the network and retry.",
+            kind="network",
+        )
+        report_error(ctx, err)
+        return int(err.exit_code)
+    except KeyboardInterrupt:
+        print("interrupted", file=ctx.err)
+        return 130
+    finally:
+        ctx.close()
+
+
+def main(argv: list[str] | None = None) -> None:
+    raise SystemExit(run(argv))
+
+
+if __name__ == "__main__":
+    main()