Skip to content

rainboyOJ/problems / .agents/skills/roj

FileKindSize
SKILL.mdskill md6.3 KB
agents/openai.yamlconfig271 B
scripts/roj.pyexecutablescript48.0 KB

scripts/roj.py

View on GitHub
#!/usr/bin/env python3
"""ROJ 题目站的只读命令行客户端。

本客户端刻意把评测留在本地:网站只暴露题面、元数据和公开数据,
从不接收源代码,也不在远端执行提交。
"""

# ---------------------------------------------------------------------------
# 标准库导入
# ---------------------------------------------------------------------------

from __future__ import annotations

import argparse
import json
import os
import re
import shutil
import subprocess
import sys
import tempfile
import time
from collections import deque
from pathlib import Path
from typing import Any, Callable, Iterable
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urljoin, urlparse
from urllib.request import Request, urlopen


# 默认 ROJ 站点地址;可通过环境变量 ROJ_URL 或 --base-url 覆盖(例如本地 127.0.0.1:3033)
DEFAULT_BASE_URL = "https://roj.ac.cn"
# download/test 命令的默认数据落盘目录(相对于当前工作目录)
DEFAULT_DOWNLOAD_ROOT = Path("roj-data")
# 本地评测每组数据的默认超时秒数(无元数据时兜底)
DEFAULT_TEST_TIMEOUT_SECONDS = 5.0
# 下载时的读取块大小(1 MiB)
CHUNK_SIZE = 1024 * 1024
# test 递归扫描 data/ 目录的最大深度(相对当前目录)
MAX_SCAN_DEPTH = 5
# 递归扫描时排除的目录名
EXCLUDED_SCAN_DIRS = {".git", "node_modules"}
# 候选目录交互最多显示的数量
MAX_CANDIDATES = 10


class RojError(Exception):
    """预期的错误:API 返回异常、网络失败或本地数据问题。"""

    def __init__(self, message: str, status: int | None = None):
        super().__init__(message)
        # status 保存 HTTP 状态码(若有),供上层判断如 404
        self.status = status


def json_requested(args: argparse.Namespace) -> bool:
    """判断当前命令是否要求 JSON 输出(全局 --json 或子命令 --json)。"""
    return bool(getattr(args, "json", False) or getattr(args, "command_json", False))


def problem_id(value: str) -> str:
    """argparse 类型校验:题号必须是纯数字。"""
    value = str(value).strip()
    if not re.fullmatch(r"\d+", value):
        raise argparse.ArgumentTypeError("题号必须是数字。")
    return value


def safe_relative_path(value: str) -> str:
    """校验清单中的相对路径,防止把本地文件系统用作攻击面。

    拒绝绝对路径、反斜杠、空段、. .. 以及隐藏文件段。
    """
    if not isinstance(value, str) or not value or "\x00" in value:
        raise RojError("服务器返回了无效的数据文件路径。")
    if value.startswith("/") or "\\" in value:
        raise RojError(f"拒绝不安全的数据路径:{value}")
    parts = value.split("/")
    if any(not part or part in (".", "..") or part.startswith(".") for part in parts):
        raise RojError(f"拒绝不安全的数据路径:{value}")
    return value


def natural_key(value: str) -> list[Any]:
    """自然排序键:把 "2.in" 按数字 2 排序,而非字符串 "2" 排在 "10" 后。"""
    return [(0, int(part)) if part.isdigit() else (1, part.lower()) for part in re.split(r"(\d+)", value)]


class RojClient:
    """封装与 ROJ 站点的 HTTP 交互,统一处理错误与超时。"""

    def __init__(self, base_url: str, timeout: float = 30.0):
        # 确保 base_url 以 / 结尾,便于 urljoin 拼接路径
        self.base_url = base_url.rstrip("/") + "/"
        self.timeout = timeout

    def make_url(self, path: str) -> str:
        """把站点相对路径拼成完整 URL。"""
        return urljoin(self.base_url, path.lstrip("/"))

    def request(self, path: str, accept: str = "application/json") -> tuple[bytes, Any]:
        """发起 GET 请求,返回 (响应体字节, 响应头)。

        网络/HTTP 错误统一转换为 RojError,并尽量提取服务端 message。
        """
        url = self.make_url(path)
        request = Request(url, headers={"Accept": accept, "User-Agent": "roj-cli/1.0"})
        try:
            with urlopen(request, timeout=self.timeout) as response:
                return response.read(), response.headers
        except HTTPError as error:
            # 服务端返回非 2xx:尝试解析 JSON 错误体中的 message
            detail = "请求失败。"
            try:
                payload = json.loads(error.read().decode("utf-8", errors="replace"))
                if isinstance(payload, dict) and payload.get("message"):
                    detail = str(payload["message"])
            except (ValueError, UnicodeError):
                pass
            raise RojError(f"HTTP {error.code}: {detail}", error.code) from error
        except URLError as error:
            raise RojError(f"无法连接 ROJ:{error.reason}") from error
        except TimeoutError as error:
            raise RojError("请求 ROJ 超时。") from error

    def json(self, path: str) -> dict[str, Any]:
        """请求 JSON 接口并校验返回结构。"""
        body, _ = self.request(path)
        try:
            value = json.loads(body.decode("utf-8"))
        except (UnicodeDecodeError, json.JSONDecodeError) as error:
            raise RojError("ROJ 返回了无效的 JSON。") from error
        if not isinstance(value, dict):
            raise RojError("ROJ 返回的 JSON 结构无效。")
        return value

    def problem(self, identifier: str) -> dict[str, Any]:
        """获取题目元数据:/api/problem/<id>"""
        return self.json(f"/api/problem/{quote(identifier, safe='')}")

    def manifest(self, identifier: str) -> dict[str, Any]:
        """获取公开数据清单:/api/problem/<id>/data

        对 sources(下载源)与 files(文件列表)做合法性校验,
        并规范化 baseUrl 结尾的 / 与文件的相对路径。
        """
        result = self.json(f"/api/problem/{quote(identifier, safe='')}/data")
        files = result.get("files")
        if not isinstance(files, list):
            raise RojError("ROJ 返回的数据清单无效。")
        sources = result.get("sources")
        if not isinstance(sources, list) or not sources:
            raise RojError("ROJ 返回的下载源清单无效。")
        normalized_sources = []
        for source in sources:
            # 下载源必须是带 id 与合法 http(s) baseUrl 的对象
            if not isinstance(source, dict) or not isinstance(source.get("id"), str) or not isinstance(source.get("baseUrl"), str):
                raise RojError("ROJ 返回了无效的下载源。")
            parsed = urlparse(source["baseUrl"])
            if parsed.scheme not in ("http", "https") or not parsed.netloc:
                raise RojError("ROJ 返回了不安全的下载源。")
            normalized_sources.append({
                **source,
                "baseUrl": source["baseUrl"].rstrip("/") + "/",
            })
        normalized = []
        for item in files:
            if not isinstance(item, dict) or not isinstance(item.get("path"), str):
                raise RojError("ROJ 返回了无效的数据文件项。")
            normalized.append({
                **item,
                # 每个路径都经过安全校验,防止路径穿越
                "path": safe_relative_path(item["path"]),
            })
        return {**result, "sources": normalized_sources, "files": normalized}

    def markdown(self, identifier: str) -> str | None:
        """获取 Markdown 题面;404 表示无 Markdown(可能是 PDF 题面)返回 None。"""
        try:
            body, _ = self.request(f"/api/problem/{quote(identifier, safe='')}/markdown", "text/markdown")
        except RojError as error:
            if error.status == 404:
                return None
            raise
        return body.decode("utf-8")


def local_destination(root: Path, relative: str) -> Path:
    """把清单相对路径映射到本地目标路径,并确认不越出 root。"""
    relative = safe_relative_path(relative)
    root = root.expanduser().absolute()
    destination = (root / Path(*relative.split("/"))).absolute()
    try:
        destination.relative_to(root)
    except ValueError as error:
        raise RojError(f"数据路径超出目标目录:{relative}") from error
    return destination


def download_to(client: RojClient, urls: list[str], destination: Path, force: bool = False,
                on_attempt: Callable[[], None] | None = None,
                on_chunk: Callable[[int], None] | None = None,
                on_start: Callable[[int], None] | None = None) -> int:
    """依次尝试多个下载源,把文件下载到 destination,返回字节数。

    先写入同目录临时文件再原子改名,避免半截文件残留;
    所有源都失败才报错。--force 允许覆盖已存在文件。
    on_attempt/on_chunk/on_start 用于进度回调:换源、拿到 Content-Length、
    每读一块时分别触发(归档大小只有响应头里才知道,用 on_start 补进进度条)。
    """
    if destination.exists() and not force:
        raise RojError(f"文件已存在,未覆盖:{destination}(如需覆盖请使用 --force)")
    if not urls:
        raise RojError("没有可用的下载源。")
    errors = []
    destination.parent.mkdir(parents=True, exist_ok=True)
    for url in urls:
        temporary = None
        total = 0
        if on_attempt:
            on_attempt()
        try:
            with urlopen(Request(url, headers={"Accept": "application/octet-stream", "User-Agent": "roj-cli/1.0"}), timeout=client.timeout) as response:
                if on_start:
                    length = (response.headers.get("Content-Length") or "").strip()
                    if length.isdigit():
                        on_start(int(length))
                # 与目标同目录的临时文件,保证同文件系统可原子 rename
                with tempfile.NamedTemporaryFile(prefix=".roj-download-", dir=destination.parent, delete=False) as output:
                    temporary = Path(output.name)
                    while True:
                        chunk = response.read(CHUNK_SIZE)
                        if not chunk:
                            break
                        output.write(chunk)
                        total += len(chunk)
                        if on_chunk:
                            on_chunk(total)
            os.replace(temporary, destination)
            temporary = None
            return total
        except HTTPError as error:
            errors.append(f"HTTP {error.code}")
        except URLError as error:
            errors.append(str(error.reason))
        except TimeoutError:
            errors.append("请求超时")
        except OSError as error:
            # 本地写盘失败属于环境问题,直接抛出而非继续换源
            raise RojError(f"无法写入下载文件:{destination}({error.strerror or error})") from error
        finally:
            # 清理可能残留的临时文件
            if temporary:
                temporary.unlink(missing_ok=True)
    detail = ";".join(errors) if errors else "未知错误"
    raise RojError(f"下载失败,已尝试 {len(urls)} 个源:{detail}")


def archive_name(manifest: dict[str, Any]) -> str:
    """取清单里的归档文件名(ROJ 只以整包提供公开数据,形如 1337.tar.zst)。"""
    archive = manifest.get("archive")
    name = archive.get("name") if isinstance(archive, dict) else None
    if not isinstance(name, str) or not name:
        raise RojError("数据清单没有 archive.name,无法下载公开数据。")
    return safe_relative_path(name)


def archive_urls(manifest: dict[str, Any]) -> list[str]:
    """按清单给出的源顺序生成归档 URL。

    清单里 files[].path 的直链在 ROJ 上并不存在(逐文件请求一律 404),
    真正可取的只有 <baseUrl><archive.name> 这一个整包,所以这里只拼归档地址。
    """
    name = "/".join(quote(part, safe="") for part in archive_name(manifest).split("/"))
    sources = manifest.get("sources") or []
    if not sources:
        raise RojError("数据清单没有可用的下载源。")
    return [f"{source['baseUrl']}{name}" for source in sources]


def archive_path_for(destination: Path, manifest: dict[str, Any]) -> Path:
    """归档落盘位置:目标目录名是 data 时放上一级(roj-data/<id>/<id>.tar.zst),
    否则放目标目录里,避免归档和数据文件混在一起。"""
    root = destination.expanduser().absolute()
    holder = root.parent if root.name == "data" else root
    return holder / archive_name(manifest)


def archive_strip_components(members: list[str], paths: list[str]) -> int:
    """判断归档是否多包了一层顶层目录(常见 data/)。

    只有当「去掉顶层目录后正好包含全部清单路径」才剥掉这层,
    保证解包结果落在 destination/<path> 上;否则原样解包。
    """
    tops = {member.split("/", 1)[0] for member in members if member and member != "."}
    if len(tops) != 1:
        return 0
    top = tops.pop()
    stripped = [member.split("/", 1)[1] for member in members if member.startswith(top + "/")]
    return 1 if set(paths) <= set(stripped) else 0


def zstd_stdout(archive: Path) -> Any:
    """把 .tar.zst 解到标准输出(系统 tar 没编进 --zstd 时的回退)。"""
    try:
        return subprocess.Popen(["zstd", "-dc", str(archive)], stdout=subprocess.PIPE)
    except OSError as error:
        raise RojError(f"解包需要 tar 与 zstd:{error.strerror or error}") from error


def tail_error(data: bytes) -> str:
    """截取子进程 stderr 尾部作为报错细节,避免整段刷屏。"""
    return data.decode("utf-8", errors="replace").strip()[-300:]


def tar_members(archive: Path) -> list[str]:
    """列出归档成员路径,供解包层级判断使用。"""
    result = subprocess.run(["tar", "--zstd", "-tf", str(archive)],
                            stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
    if result.returncode != 0:
        decompressor = zstd_stdout(archive)
        assert decompressor.stdout is not None
        result = subprocess.run(["tar", "-tf", "-"], stdin=decompressor.stdout,
                                stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
        decompressor.stdout.close()
        decompressor.wait()
        if result.returncode != 0:
            raise RojError(f"读取归档成员失败:{tail_error(result.stderr)}")
    return [line for line in result.stdout.decode("utf-8", errors="replace").splitlines() if line.strip()]


def extract_archive(archive: Path, destination: Path, strip_components: int = 0) -> None:
    """把归档解包到 destination;strip_components 用于去掉多余的顶层目录。"""
    destination.mkdir(parents=True, exist_ok=True)
    command = ["tar", "--zstd", "-xf", str(archive), "-C", str(destination)]
    if strip_components:
        command.append(f"--strip-components={strip_components}")
    result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
    if result.returncode == 0:
        return
    primary_error = tail_error(result.stderr)
    # 回退:zstd 解到管道再交给 tar
    decompressor = zstd_stdout(archive)
    assert decompressor.stdout is not None
    fallback = ["tar", "-xf", "-", "-C", str(destination)]
    if strip_components:
        fallback.append(f"--strip-components={strip_components}")
    result = subprocess.run(fallback, stdin=decompressor.stdout,
                            stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
    decompressor.stdout.close()
    decompressor.wait()
    if result.returncode != 0:
        raise RojError(f"解包失败(--zstd:{primary_error};回退:{tail_error(result.stderr)})")


def download_archive(client: RojClient, identifier: str, manifest: dict[str, Any], destination: Path,
                     force: bool = False, skip_existing: bool = False,
                     progress: DownloadProgress | None = None) -> tuple[list[dict[str, Any]], list[Path]]:
    """下载题目数据归档并解包到 destination(整包取回,不再逐文件下载)。

    归档长期保留在 archive_path_for(...) 指定的位置;解包后的文件与清单
    files[].path 一一对应地落在 destination 下,解包后逐个校验,缺文件直接报错。
    skip_existing 且清单文件全部已存在时整体跳过(test --download 用)。
    返回 (已落盘文件列表, 跳过的本地路径列表)。
    """
    paths = [item["path"] for item in manifest.get("files", [])]
    local = [local_destination(destination, path) for path in paths]
    if skip_existing and all(target.is_file() for target in local):
        return [], local

    name = archive_name(manifest)
    archive_path = archive_path_for(destination, manifest)

    if progress is not None:
        # 归档大小要等响应头才拿得到,先只画状态行,拿到 Content-Length 再补分母
        progress.enable(0)
    if archive_path.is_file() and not force:
        if progress is not None:
            progress.show_status(f"复用已有归档 {name}")
    else:
        if progress is not None:
            progress.show_status(f"下载 {name}")
        download_to(client, archive_urls(manifest), archive_path, force=force,
                    on_attempt=progress.on_attempt if progress else None,
                    on_chunk=progress.on_chunk if progress else None,
                    on_start=progress.set_total if progress else None)

    if progress is not None:
        progress.show_status(f"解包 {name}")
    extract_archive(archive_path, destination, archive_strip_components(tar_members(archive_path), paths))

    missing = [path for path, target in zip(paths, local) if not target.is_file()]
    if missing:
        shown = ", ".join(missing[:5])
        raise RojError(f"归档解包后缺少 {len(missing)} 个清单文件:{shown}"
                       + (" ..." if len(missing) > 5 else ""))
    downloaded = [{"path": path, "size": target.stat().st_size}
                  for path, target in zip(paths, local)]
    return downloaded, []


def print_manifest_summary(manifest: dict[str, Any]) -> None:
    """打印公开数据清单概要(文件数与总大小)。"""
    files = manifest.get("files", [])
    total_bytes = manifest.get("totalBytes")
    if not isinstance(total_bytes, (int, float)):
        total_bytes = sum(int(item.get("size", 0) or 0) for item in files)
    print(f"公开数据:{len(files)} 个文件,共 {format_bytes(total_bytes)}")


def format_bytes(value: int | float) -> str:
    """把字节数格式化为 B/KiB/MiB/GiB 可读字符串。"""
    value = max(0, float(value))
    units = ("B", "KiB", "MiB", "GiB")
    index = 0
    while value >= 1024 and index < len(units) - 1:
        value /= 1024
        index += 1
    return f"{value:.1f} {units[index]}" if index else f"{int(value)} B"


class DownloadProgress:
    """下载总体进度条,绘制到 stderr。

    仅当 stderr 是 TTY 且总大小为正时才启用;管道/重定向/JSON 输出时静默。
    进度 = 已成功落盘的字节(committed)+ 当前源尝试中已读的字节(attempt)。
    分母是待下载归档的字节数(Content-Length),拿不到时只画状态行。
    """

    BAR_WIDTH = 30  # 进度条字符宽度
    MIN_REFRESH_SECONDS = 0.05  # 最小刷新间隔,避免小文件快速闪烁
    SPEED_WINDOW_SAMPLES = 8  # 速度滑动窗口的样本数(每块 1MiB,约 8MiB)

    def __init__(self):
        # 构造即检测 TTY:状态行(请求清单等)在 enable 之前就要显示
        self.enabled = sys.stderr.isatty()
        self.total = 0
        self.committed = 0
        self.attempt = 0
        self.status = ""  # 状态行文字(请求数据清单/准备下载/下载 <path>)
        self.last_render = 0.0
        self.last_len = 0  # 进度行长度(清行用)
        self.last_status_len = 0  # 状态行长度(清行用)
        # 滑动窗口:每个样本是 (monotonic 时间, 累计字节),用于算速度
        self.samples: deque[tuple[float, int]] = deque()

    def enable(self, total_bytes: int) -> None:
        """按本次任务的总字节数启用进度条(总量无效时保持只有状态行)。"""
        self.total = max(0, int(total_bytes))
        self.samples.clear()
        self.show_status("准备下载")

    def set_total(self, total_bytes: int) -> None:
        """下载开始后才拿到 Content-Length:补上分母,状态行保持不变。"""
        if total_bytes > 0 and self.total <= 0:
            self.total = int(total_bytes)
            self.samples.clear()

    def show_status(self, text: str) -> None:
        """设置状态行文字并强制刷新(清单请求、文件开始等阶段切换)。"""
        if not self.enabled:
            return
        self.status = text
        self._render(time.monotonic(), force=True)

    def on_attempt(self) -> None:
        """当前源尝试开始:清空已读字节,失败的源进度不累计。"""
        self.attempt = 0

    def on_chunk(self, file_bytes: int) -> None:
        """当前文件已读 file_bytes 字节(实时进度)。"""
        self.attempt = file_bytes
        self._maybe_render(force=False)

    def commit(self, size: int) -> None:
        """一个文件下载成功落盘(os.replace 完成),累计其大小。"""
        self.committed += size
        self.attempt = 0
        self._maybe_render(force=True)

    def done_bytes(self) -> int:
        return self.committed + self.attempt

    def finish(self) -> None:
        """任务完成:强制绘制最终行并换行,供"已下载"列表输出前调用。"""
        if not self.enabled:
            return
        self._render(time.monotonic(), force=True)
        sys.stderr.write("\n")
        sys.stderr.flush()
        self.last_len = 0
        self.last_status_len = 0

    def fail(self) -> None:
        """失败:清掉全部进度行与状态行,供错误信息输出前调用。"""
        if not self.enabled:
            return
        rows = 2 if self.total > 0 else 1
        if rows > 1:
            # 回到第一行
            sys.stderr.write(f"\033[{rows - 1}A")
        for index in range(rows):
            width = self.last_len if index == 0 else self.last_status_len
            sys.stderr.write("\r" + " " * width)
            if index < rows - 1:
                sys.stderr.write("\033[1B")
        sys.stderr.write("\r")
        sys.stderr.flush()
        self.last_len = 0
        self.last_status_len = 0

    def _maybe_render(self, force: bool) -> None:
        if not self.enabled:
            return
        now = time.monotonic()
        if not force and now - self.last_render < self.MIN_REFRESH_SECONDS:
            return
        self._render(now, force=force)

    def _speed(self, now: float) -> float | None:
        """滑动窗口速度:最近样本差 / 时间差;样本不足或间隔为 0 时返回 None。"""
        cumulative = self.done_bytes()
        self.samples.append((now, cumulative))
        while len(self.samples) > self.SPEED_WINDOW_SAMPLES:
            self.samples.popleft()
        if len(self.samples) < 2:
            return None
        (start_time, start_bytes), (end_time, end_bytes) = self.samples[0], self.samples[-1]
        elapsed = end_time - start_time
        if elapsed <= 0:
            return None
        return max(0, end_bytes - start_bytes) / elapsed

    def _truncate_status(self, text: str) -> str:
        """状态行截断到终端宽度,避免超长路径换行破坏两行布局。"""
        width = max(10, shutil.get_terminal_size().columns - 1)
        return text if len(text) <= width else text[: width - 1] + "…"

    def _render(self, now: float, force: bool = False) -> None:
        if not self.enabled:
            return
        # 进度行:total 未知(请求清单阶段)时不画
        progress_line = ""
        if self.total > 0:
            done = self.done_bytes()
            ratio = min(1.0, done / self.total)
            filled = round(ratio * self.BAR_WIDTH)
            bar = "=" * filled + " " * (self.BAR_WIDTH - filled)
            percent = f"{ratio * 100:>3.0f}%"
            progress_line = f"[{bar}]  {percent}  {format_bytes(done)} / {format_bytes(self.total)}"
            speed = self._speed(now)
            if speed is not None:
                progress_line += f"  {format_bytes(speed)}/s"
        status_line = self._truncate_status(self.status)
        if self.total > 0:
            # 两行布局:重画进度行,下移重画状态行,再回到进度行
            padding = " " * (self.last_len - len(progress_line)) if self.last_len > len(progress_line) else ""
            status_padding = " " * (self.last_status_len - len(status_line)) if self.last_status_len > len(status_line) else ""
            sys.stderr.write("\r" + progress_line + padding)
            sys.stderr.write(f"\033[1B\r{status_line}{status_padding}\033[1A")
            self.last_len = len(progress_line)
            self.last_status_len = len(status_line)
        else:
            # 清单阶段:只有状态行
            status_padding = " " * (self.last_status_len - len(status_line)) if self.last_status_len > len(status_line) else ""
            sys.stderr.write("\r" + status_line + status_padding)
            self.last_status_len = len(status_line)
        sys.stderr.flush()


def cmd_list(client: RojClient, args: argparse.Namespace) -> int:
    """list 命令:按题号/标题搜索题目。

    未指定 --page 时自动遍历全部结果页,合并到一个列表。
    """
    query = args.query or ""
    if args.page:
        # 只取指定页
        result = client.json(f"/api/problems?q={quote(query)}&page={args.page}")
        items = result.get("items", [])
        payload = result
    else:
        # 自动翻页:从第 1 页起,直到 totalPages
        first = client.json(f"/api/problems?q={quote(query)}&page=1")
        items = list(first.get("items", []))
        total_pages = int(first.get("totalPages", 1) or 1)
        for page in range(2, total_pages + 1):
            current = client.json(f"/api/problems?q={quote(query)}&page={page}")
            items.extend(current.get("items", []))
        payload = {**first, "items": items, "page": 1, "totalPages": total_pages}

    if json_requested(args):
        print(json.dumps(payload, ensure_ascii=False, indent=2))
        return 0
    if not items:
        print("没有找到题目。")
        return 0
    # 人类可读输出:ID 与标题表格
    print(f"共 {len(items)} 道题目" + (f"(关键词:{query})" if query else ""))
    print(f"{'ID':<8} {'题目'}")
    print("-" * 72)
    for item in items:
        print(f"{str(item.get('id', '-')):<8} {item.get('title', '未命名题目')}")
    return 0


def cmd_get(client: RojClient, args: argparse.Namespace) -> int:
    """get 命令:获取题目元数据与题面。

    默认同时拉取 Markdown 题面;PDF 题面只输出浏览器链接。
    """
    metadata = client.problem(args.identifier)
    markdown = None if args.no_markdown else client.markdown(args.identifier)
    if json_requested(args):
        print(json.dumps({**metadata, "markdown": markdown}, ensure_ascii=False, indent=2))
        return 0
    print(f"题目 {metadata.get('id', args.identifier)}:{metadata.get('title', '未命名题目')}")
    if metadata.get("time") is not None:
        print(f"时间限制:{metadata['time']} ms")
    if metadata.get("memory") is not None:
        print(f"内存限制:{metadata['memory']} MB")
    if metadata.get("tags"):
        print(f"标签:{'、'.join(metadata['tags'])}")
    print(f"题面类型:{'Markdown' if metadata.get('hasMarkdown') else 'PDF'}")
    print(f"公开数据:{'有' if metadata.get('hasPublicData') else '无'}")
    if metadata.get("source"):
        print(f"来源:{metadata['source']}")
    if markdown is not None:
        print("\n" + markdown, end="" if markdown.endswith("\n") else "\n")
    elif metadata.get("hasPdf"):
        print(f"\n这道题是 PDF 题面,请在浏览器打开:{client.make_url(metadata.get('urls', {}).get('pdf', f'/problem/{args.identifier}/pdf'))}")
    return 0


def prompt_download_destination(identifier: str) -> Path:
    """交互式询问下载位置(仅 TTY 时由调用方触发)。

    提供 4 个选项:./data、./roj-data/<id>/data、./、自定义路径;
    回车取默认值(./roj-data/<id>/data)。
    """
    default = DEFAULT_DOWNLOAD_ROOT / identifier / "data"
    options = [Path("data"), default, Path(".")]
    print("选择下载位置:")
    for index, option in enumerate(options, 1):
        print(f"{index}. {option}/")
    print("4. 自定义路径")
    while True:
        try:
            choice = input(f"输入 1-4(回车默认 {default}/): ").strip()
        except EOFError:
            # 输入流意外关闭时退回默认位置,避免卡死
            return default
        if not choice:
            return default
        if choice in ("1", "2", "3"):
            return options[int(choice) - 1]
        if choice == "4":
            custom = input("输入路径: ").strip()
            if custom:
                return Path(custom).expanduser()
            print("路径不能为空。")
            continue
        print("无效选择,请输入 1-4。")


def scan_data_directories(identifier: str) -> list[tuple[Path, int]]:
    """递归扫描当前目录下所有 data/ 目录(深度 ≤5,排除 .git/node_modules)。

    返回按 (题号匹配优先, 深度浅优先, 路径字典序) 排序的 (目录, 配对组数) 列表;
    只保留能成功配对的目录。
    """
    root = Path.cwd()
    found: list[tuple[Path, int]] = []
    for directory, dirnames, _ in os.walk(root):
        # 剪枝:排除指定目录,超过深度不再深入
        dirnames[:] = sorted(d for d in dirnames if d not in EXCLUDED_SCAN_DIRS)
        relative = Path(directory).relative_to(root).parts
        if len(relative) >= MAX_SCAN_DEPTH:
            dirnames[:] = []
        if Path(directory).name != "data":
            continue
        try:
            pairs, _ = find_data_pairs(Path(directory))
        except RojError:
            continue
        if pairs:
            found.append((Path(directory), len(pairs)))

    def sort_key(item: tuple[Path, int]) -> tuple[int, int, str]:
        directory, _ = item
        parts = directory.relative_to(root).parts
        has_id = identifier in parts
        return (0 if has_id else 1, len(parts), str(directory))

    found.sort(key=sort_key)
    return found


def prompt_data_directory(identifier: str) -> Path:
    """为 test 命令选择本地数据目录。

    递归扫描当前目录的 data/ 目录作为候选;TTY 时显示前 MAX_CANDIDATES 个
    供选择(回车默认第一候选),非 TTY 直接取第一候选。
    """
    candidates = scan_data_directories(identifier)
    if not candidates:
        raise RojError("找不到本地数据;请先运行 download,或给 test 加 --download。")
    if not sys.stdin.isatty():
        # 脚本场景:自动取排序后的第一个候选
        return candidates[0][0]

    shown = candidates[:MAX_CANDIDATES]
    custom_index = len(shown) + 1
    print(f"找到 {len(candidates)} 个数据目录:")
    for index, (directory, count) in enumerate(shown, 1):
        print(f"{index}. {directory} ({count} 组数据)")
    print(f"{custom_index}. 自定义路径")
    while True:
        try:
            choice = input(f"输入 1-{custom_index}(回车默认 1): ").strip()
        except EOFError:
            # 输入流意外关闭时退回第一候选,避免卡死
            return candidates[0][0]
        if not choice:
            return candidates[0][0]
        if choice.isdigit() and 1 <= int(choice) <= len(shown):
            return shown[int(choice) - 1][0]
        if choice.isdigit() and int(choice) == custom_index:
            custom = input("输入路径: ").strip()
            if not custom:
                print("路径不能为空。")
                continue
            path = Path(custom).expanduser()
            # 立即校验自定义路径:无效(不存在/无法配对)直接报错,不重试
            try:
                pairs, _ = find_data_pairs(path)
            except RojError as error:
                raise RojError(f"自定义路径无效:{error}") from error
            if not pairs:
                raise RojError(f"自定义路径无效:{path} 没有可评测的数据")
            return path
        print(f"无效选择,请输入 1-{custom_index}。")


def resolve_download_destination(identifier: str, explicit_output: str | None) -> Path:
    """确定下载落盘目录:--output 指定 > TTY 交互询问 > 默认位置。"""
    if explicit_output:
        return Path(explicit_output)
    if sys.stdin.isatty():
        # 交互式终端:让用户选下载位置
        return prompt_download_destination(identifier)
    # 管道/脚本场景:静默使用默认位置(与交互选项 2 一致),避免卡住
    return DEFAULT_DOWNLOAD_ROOT / identifier / "data"


def perform_download(client: RojClient, identifier: str, manifest: dict[str, Any], destination: Path,
                     force: bool = False, skip_existing: bool = False,
                     progress: DownloadProgress | None = None) -> tuple[list[dict[str, Any]], list[Path]]:
    """执行归档下载并解包(带进度条),失败时清进度条并抛错。

    供 cmd_download 与 cmd_test --download 复用。
    """
    try:
        downloaded, skipped = download_archive(client, identifier, manifest, destination,
                                               force=force, skip_existing=skip_existing, progress=progress)
    except RojError:
        if progress is not None:
            # 失败:清掉进度条行,保留"卡在哪"的上下文后重新抛出
            progress.fail()
            if progress.enabled:
                print(f"已下载 {format_bytes(progress.committed)} / {format_bytes(progress.total)} 后失败",
                      file=sys.stderr)
        raise
    if progress is not None:
        progress.finish()
    return downloaded, skipped


def cmd_download(client: RojClient, args: argparse.Namespace) -> int:
    """download 命令:把题目的公开数据下载到本地目录。

    未指定 --output 且 stdin 是 TTY 时,先询问下载位置。
    """
    # JSON 输出时进度条静默;否则在 TTY 上显示状态行与进度条
    progress = None if json_requested(args) else DownloadProgress()
    try:
        if progress is not None:
            progress.show_status("请求数据清单")
        manifest = client.manifest(args.identifier)
    except RojError:
        if progress is not None:
            # 清单请求失败:清掉状态行后再报错
            progress.fail()
        raise
    destination = resolve_download_destination(args.identifier, args.output)
    if not manifest.get("files"):
        raise RojError("这道题没有公开数据。")

    downloaded, skipped = perform_download(client, args.identifier, manifest, destination,
                                           force=args.force, progress=progress)
    payload = {
        "problemId": args.identifier,
        "kind": "archive",
        "archive": str(archive_path_for(destination, manifest)),
        "destination": str(destination),
        "downloaded": [{**item, "localPath": str(local_destination(destination, item["path"]))} for item in downloaded],
        "skipped": [str(target) for target in skipped],
    }
    if json_requested(args):
        print(json.dumps(payload, ensure_ascii=False, indent=2))
    else:
        print_manifest_summary(manifest)
        print(f"归档:{archive_path_for(destination, manifest)}")
        for item in downloaded:
            print(f"已解包:{local_destination(destination, item['path'])}")
        for target in skipped:
            print(f"已存在,跳过:{target}")
    return 0


def find_data_pairs(data_dir: Path) -> tuple[list[tuple[Path, Path, str]], list[str]]:
    """扫描数据目录,把 .in/.out(或 .in/.ans)配对。

    返回 (配对列表, 缺失警告列表);空配对时抛错。
    """
    if not data_dir.is_dir():
        raise RojError(f"数据目录不存在:{data_dir}")
    inputs: dict[str, Path] = {}
    outputs: dict[str, Path] = {}
    for path in data_dir.rglob("*"):
        # 跳过目录与符号链接,只认普通文件
        if not path.is_file() or path.is_symlink():
            continue
        suffix = path.suffix.lower()
        relative = path.relative_to(data_dir).as_posix()
        # 以去掉扩展名的相对路径为配对键
        key = str(Path(relative).with_suffix(""))
        if suffix == ".in":
            inputs[key] = path
        elif suffix == ".out" or (suffix == ".ans" and key not in outputs):
            # .out 优先;没有 .out 时允许 .ans
            outputs[key] = path
    missing: list[str] = []
    pairs: list[tuple[Path, Path, str]] = []
    for key in sorted(set(inputs) | set(outputs), key=natural_key):
        if key not in inputs:
            missing.append(f"缺少输入:{key}")
        elif key not in outputs:
            missing.append(f"缺少输出:{key}")
        else:
            pairs.append((inputs[key], outputs[key], key))
    if not pairs:
        raise RojError(f"数据目录没有可评测的 .in/.out 或 .in/.ans 数据:{data_dir}")
    return pairs, missing


def run_case(executable: Path, input_path: Path, expected_path: Path, output_path: Path,
             timeout_seconds: float, diff_command: str) -> dict[str, Any]:
    """运行单组测试:喂入输入文件,用 diff -b 比较输出。

    返回结果字典:AC/WA/TLE/RE 与耗时;RE 时附带 stderr 尾部。
    """
    started = time.monotonic()
    try:
        # stdin 重定向到输入文件,stdout 落到输出文件
        with input_path.open("rb") as source, output_path.open("wb") as actual:
            process = subprocess.run([str(executable)], stdin=source, stdout=actual, stderr=subprocess.PIPE,
                                     timeout=timeout_seconds, check=False)
    except subprocess.TimeoutExpired:
        return {"name": input_path.name, "input": str(input_path), "expected": str(expected_path),
                "status": "TLE", "timeMs": round((time.monotonic() - started) * 1000, 2)}
    except OSError as error:
        raise RojError(f"无法运行测试数据 {input_path}:{error}") from error
    elapsed = round((time.monotonic() - started) * 1000, 2)
    if process.returncode != 0:
        # 非零退出码视为运行时错误,截取 stderr 尾部便于诊断
        stderr = process.stderr.decode("utf-8", errors="replace")[-4000:]
        return {"name": input_path.name, "input": str(input_path), "expected": str(expected_path),
                "status": "RE", "returnCode": process.returncode, "stderr": stderr, "timeMs": elapsed}
    try:
        # 忽略行尾空白差异(diff -b)
        diff = subprocess.run([diff_command, "-b", str(expected_path), str(output_path)],
                              stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
    except OSError as error:
        raise RojError("系统中找不到 diff,无法按约定比较输出。") from error
    if diff.returncode == 0:
        status = "AC"
    elif diff.returncode == 1:
        status = "WA"
    else:
        # diff 自身出错(如文件不可读)
        raise RojError("diff 比较输出时发生错误:" + diff.stderr.decode("utf-8", errors="replace"))
    return {"name": input_path.name, "input": str(input_path), "expected": str(expected_path),
            "status": status, "timeMs": elapsed}


def cmd_test(client: RojClient, args: argparse.Namespace) -> int:
    """test 命令:编译 C++ 源码并用公开数据在本地评测。

    数据来源:--data-dir 指定 > 本地扫描候选(递归 data/ 目录)> --download 现场下载。
    --download 时复用 download 的流程(请求清单、选择落盘位置、下载)。
    时间限制取题目元数据(毫秒),无元数据时用默认 5 秒。
    """
    metadata = client.problem(args.identifier)
    explicit_data_dir = Path(args.data_dir) if args.data_dir else None
    if args.download:
        # 复用 download 的下载流程:请求清单 → 选择落盘位置 → 下载(跳过已有)
        progress = None if json_requested(args) else DownloadProgress()
        try:
            if progress is not None:
                progress.show_status("请求数据清单")
            manifest = client.manifest(args.identifier)
        except RojError:
            if progress is not None:
                progress.fail()
            raise
        if not manifest.get("files"):
            if progress is not None:
                progress.fail()
            raise RojError("这道题没有公开数据,无法评测。")
        destination = explicit_data_dir if explicit_data_dir else resolve_download_destination(args.identifier, None)
        perform_download(client, args.identifier, manifest, destination,
                         force=args.force, skip_existing=True, progress=progress)
        data_dir = destination
    elif explicit_data_dir is not None:
        data_dir = explicit_data_dir
    else:
        # 本地查找:递归扫描当前目录的 data/ 目录并让用户选择
        data_dir = prompt_data_directory(args.identifier)

    pairs, missing = find_data_pairs(data_dir)
    compiler = shutil.which(args.compiler)
    if not compiler:
        raise RojError(f"找不到 C++ 编译器:{args.compiler}")
    diff_command = shutil.which("diff")
    if not diff_command:
        raise RojError("找不到系统 diff,无法按 diff -b 比较输出。")

    timeout_seconds = DEFAULT_TEST_TIMEOUT_SECONDS
    if isinstance(metadata.get("time"), (int, float)) and metadata["time"] > 0:
        # 元数据时间限制单位是毫秒,转成秒
        timeout_seconds = max(0.001, float(metadata["time"]) / 1000)
    source = Path(args.source).expanduser()
    if not source.is_file():
        raise RojError(f"源代码文件不存在:{source}")
    results: list[dict[str, Any]] = []
    compile_error = None
    with tempfile.TemporaryDirectory(prefix=f"roj-test-{args.identifier}-") as temporary_dir:
        # 在临时目录编译,避免污染工作区
        executable = Path(temporary_dir) / "main"
        try:
            compile_process = subprocess.run([compiler, "-std=c++17", "-O2", str(source.absolute()), "-o", str(executable)],
                                             stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False, timeout=60)
        except subprocess.TimeoutExpired:
            compile_error = "编译超时。"
        else:
            if compile_process.returncode != 0:
                # 编译失败:截取编译器输出尾部
                compile_error = compile_process.stderr.decode("utf-8", errors="replace")[-6000:]
        if compile_error is None:
            # 逐组运行测试
            for index, (input_path, expected_path, key) in enumerate(pairs, 1):
                output_path = Path(temporary_dir) / f"output-{index}.txt"
                result = run_case(executable, input_path, expected_path, output_path, timeout_seconds, diff_command)
                result["index"] = index
                result["case"] = key
                results.append(result)

    passed = sum(result["status"] == "AC" for result in results)
    payload = {
        "problem": metadata,
        "source": str(source),
        "dataDir": str(data_dir),
        "timeLimitMs": metadata.get("time"),
        "memoryLimitMb": metadata.get("memory"),
        "comparison": "diff -b",
        "compile": {"compiler": compiler, "standard": "c++17", "error": compile_error},
        "missingData": missing,
        "passed": passed,
        "total": len(pairs),
        "results": results,
    }
    if json_requested(args):
        print(json.dumps(payload, ensure_ascii=False, indent=2))
    else:
        print(f"题目 {args.identifier}:{metadata.get('title', '未命名题目')}")
        print(f"数据目录:{data_dir};比较方式:diff -b;时间限制:{timeout_seconds:g} 秒/组")
        if compile_error is not None:
            print("编译失败:")
            print(compile_error.rstrip())
            return 1
        for result in results:
            print(f"{result['index']:>3}. {result['case']:<30} {result['status']:<3} {result['timeMs']:>8} ms")
        for warning in missing:
            print(f"警告:{warning}")
        print(f"结果:{passed}/{len(pairs)} AC")
    # 只有全 AC 且无缺数据、编译成功才算通过
    return 0 if compile_error is None and passed == len(pairs) and not missing else 1


def build_parser() -> argparse.ArgumentParser:
    """构建命令行参数解析器:全局选项 + list/get/download/test 四个子命令。"""
    parser = argparse.ArgumentParser(description="ROJ 只读题目客户端:查询题面、下载公开数据并在本地评测。")
    parser.add_argument("--base-url", default=os.environ.get("ROJ_URL", DEFAULT_BASE_URL), help="ROJ 地址,默认读取 ROJ_URL 或 https://roj.ac.cn")
    parser.add_argument("--timeout", type=float, default=30.0, help="网络请求超时秒数")
    parser.add_argument("--json", action="store_true", help="使用 JSON 输出")
    commands = parser.add_subparsers(dest="command", required=True)

    list_parser = commands.add_parser("list", help="列出题目")
    list_parser.add_argument("query", nargs="?", help="按题号或标题搜索")
    list_parser.add_argument("--page", type=int, help="只请求指定页;省略时自动翻页")
    list_parser.add_argument("--json", dest="command_json", action="store_true", help="使用 JSON 输出")
    list_parser.set_defaults(handler=cmd_list)

    get_parser = commands.add_parser("get", help="获取题目信息和题面")
    get_parser.add_argument("identifier", type=problem_id)
    get_parser.add_argument("--no-markdown", action="store_true", help="只获取元数据,不读取 Markdown")
    get_parser.add_argument("--json", dest="command_json", action="store_true", help="使用 JSON 输出")
    get_parser.set_defaults(handler=cmd_get)

    download_parser = commands.add_parser("download", help="下载公开数据(整包归档)")
    download_parser.add_argument("identifier", type=problem_id)
    download_parser.add_argument("--output", help="目标目录,默认 ./roj-data/<id>/data/")
    download_parser.add_argument("--force", action="store_true", help="允许覆盖已有文件")
    download_parser.add_argument("--json", dest="command_json", action="store_true", help="使用 JSON 输出")
    download_parser.set_defaults(handler=cmd_download)

    test_parser = commands.add_parser("test", help="使用公开数据在本地评测 C++")
    test_parser.add_argument("identifier", type=problem_id)
    test_parser.add_argument("source", help="C++ 源代码文件")
    test_parser.add_argument("--data-dir", help="本地数据目录")
    test_parser.add_argument("--download", action="store_true", help="数据缺失时显式下载到 ./roj-data/<id>/")
    test_parser.add_argument("--force", action="store_true", help="配合 --download 覆盖已有数据")
    test_parser.add_argument("--compiler", default="g++", help="C++ 编译器,默认 g++")
    test_parser.add_argument("--json", dest="command_json", action="store_true", help="使用 JSON 输出")
    test_parser.set_defaults(handler=cmd_test)
    return parser


def main(argv: Iterable[str] | None = None) -> int:
    """入口:解析参数、构造客户端、分发给子命令处理函数。"""
    parser = build_parser()
    args = parser.parse_args(argv)
    client = RojClient(args.base_url, args.timeout)
    try:
        return int(args.handler(client, args))
    except RojError as error:
        # 预期错误:按 --json 模式输出结构化错误,否则输出中文错误信息
        if json_requested(args):
            print(json.dumps({"error": "roj_error", "message": str(error)}, ensure_ascii=False), file=sys.stderr)
        else:
            print(f"错误:{error}", file=sys.stderr)
        return 2
    except KeyboardInterrupt:
        print("已取消。", file=sys.stderr)
        return 130


if __name__ == "__main__":
    raise SystemExit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall