bb-sync 1.9.0__py3-none-any.whl

bb_sync/core/doctor.py

@@ -0,0 +1,230 @@
+"""环境体检：逐项检查前置条件，输出 ✓/✗ 与修复提示。
+
+必查项（缺失即视为环境不可用）: Python / git / Node.js≥22 / npm / 浏览器 / 网络。
+可选展示项: 凭据 / Steel 后端状态。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from urllib import error, request
+
+from bb_sync import __version__
+from bb_sync.browser import steel
+from bb_sync.core.errors import EnvironmentError_
+from bb_sync.core.output import Console
+from bb_sync.creds import load_credentials
+
+
+@dataclass
+class CheckResult:
+    """单项体检结果。"""
+
+    ok: bool
+    label: str
+    detail: str = ""
+    hint: str = ""
+    required: bool = True
+
+
+def _tool_version(cmd: list[str]) -> str | None:
+    """运行 ``<tool> --version``，返回首行；失败返回 None。"""
+    try:
+        out = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=6, encoding="utf-8", errors="ignore"
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    lines = (out.stdout or out.stderr).strip().splitlines()
+    return lines[0].strip() if lines and out.returncode == 0 else None
+
+
+def _git_install_hint() -> str:
+    """按平台给出 git 安装方式。"""
+    if sys.platform == "darwin":
+        return "bb-sync 从 GitHub 安装需要 git：brew install git"
+    if sys.platform.startswith("win"):
+        return "bb-sync 从 GitHub 安装需要 git：winget install --id Git.Git -e"
+    return "bb-sync 从 GitHub 安装需要 git：请通过系统包管理器安装"
+
+
+def _browser_install_hint() -> str:
+    """按平台给出浏览器安装方式。"""
+    if sys.platform == "darwin":
+        return "macOS 可运行 brew install --cask google-chrome 或 microsoft-edge"
+    if sys.platform.startswith("win"):
+        return (
+            "安装 Google Chrome 或使用 Windows 自带的 Edge；非默认位置时设置 CHROME_EXECUTABLE_PATH"
+        )
+    return "安装 Google Chrome、Chromium 或 Microsoft Edge；非默认位置时设置 CHROME_EXECUTABLE_PATH"
+
+
+def check_python() -> CheckResult:
+    v = sys.version_info
+    return CheckResult(
+        (v.major, v.minor) >= (3, 11),
+        "Python",
+        f"{v.major}.{v.minor}.{v.micro}（需要 ≥3.11，uv 安装 bb-sync 时会自动准备）",
+    )
+
+
+def check_git() -> CheckResult:
+    path = shutil.which("git")
+    ver = _tool_version([path, "--version"]) if path else None
+    return CheckResult(
+        bool(ver),
+        "git",
+        ver or "未找到",
+        _git_install_hint(),
+    )
+
+
+def check_node() -> CheckResult:
+    try:
+        path = steel._node_bin()
+    except EnvironmentError_:
+        path = None
+    ver = _tool_version([path, "--version"]) if path else None
+    ok = False
+    if ver:
+        m = re.match(r"v(\d+)", ver)
+        ok = bool(m) and int(m.group(1)) >= 22
+    return CheckResult(
+        ok,
+        "Node.js",
+        ver or "未找到",
+        steel._node_install_hint() + "（自带 npm）",
+    )
+
+
+def check_npm() -> CheckResult:
+    path = steel._npm_bin()
+    ver = _tool_version([path, "--version"]) if path else None
+    return CheckResult(
+        bool(ver),
+        "npm",
+        ver or "未找到",
+        "npm 随 Node.js 一起安装，单独缺失请重装 Node.js",
+    )
+
+
+def check_browser() -> CheckResult:
+    custom = os.environ.get("CHROME_EXECUTABLE_PATH")
+    if custom and Path(custom).exists():
+        return CheckResult(True, "浏览器", f"自定义 {custom}")
+    browser = steel.detect_browser()
+    if browser:
+        name = "Edge" if "edge" in Path(browser).name.lower() else "Chrome"
+        return CheckResult(True, "浏览器", f"{name} ({browser})")
+    return CheckResult(
+        False,
+        "浏览器",
+        "未检测到 Chrome/Edge",
+        _browser_install_hint(),
+    )
+
+
+def check_network(retries: int = 3) -> CheckResult:
+    """检查 github.com 可达性（首次部署 Steel 需要；代理抖动会瞬时失败，故重试）。"""
+    last_err = ""
+    for _ in range(retries):
+        try:
+            req = request.Request("https://github.com", headers={"User-Agent": "bb-sync"})
+            request.urlopen(req, timeout=6)
+            return CheckResult(True, "网络", "github.com 可达")
+        except error.HTTPError:  # 有响应即视为可达（如 301/403）
+            return CheckResult(True, "网络", "github.com 可达")
+        except Exception as exc:
+            last_err = str(exc)
+            time.sleep(1.5)
+    return CheckResult(
+        False, "网络", f"github.com 不可达 ({last_err})", "代理用户请确认系统代理已开启"
+    )
+
+
+def check_credentials() -> CheckResult:
+    try:
+        creds = load_credentials()
+    except Exception as exc:
+        return CheckResult(
+            False, "凭据", f"读取失败: {exc}", "运行 bb-sync auth login 重新录入", required=False
+        )
+    if creds.ok:
+        return CheckResult(True, "凭据", f"已保存（{creds.source}）", required=False)
+    return CheckResult(
+        False, "凭据", "未配置", "运行 bb-sync auth login 录入学号密码", required=False
+    )
+
+
+def check_steel() -> CheckResult:
+    if steel.healthy():
+        return CheckResult(True, "Steel 后端", "服务端运行中", required=False)
+    if steel.is_deployed():
+        ref = steel.installed_ref()
+        label = f"{ref[:7]}…" if ref and len(ref) > 12 else ref
+        detail = f"已部署（{label}，未运行）" if label else "已部署（未运行，同步时自动启动）"
+        return CheckResult(True, "Steel 后端", detail, required=False)
+    return CheckResult(
+        False,
+        "Steel 后端",
+        "未部署",
+        "首次同步时自动下载部署（依赖 Node.js 与网络），无需手动操作",
+        required=False,
+    )
+
+
+#: 体检项顺序即输出顺序
+CHECKS = (
+    check_python,
+    check_git,
+    check_node,
+    check_npm,
+    check_browser,
+    check_network,
+    check_credentials,
+    check_steel,
+)
+
+
+def run_doctor(console: Console, *, skip_network: bool = False) -> list[CheckResult]:
+    """执行全部体检项，逐项输出，返回结果列表。"""
+    console.step(f"bb-sync {__version__} — doctor")
+    console.log("")
+    results: list[CheckResult] = []
+    for fn in CHECKS:
+        if skip_network and fn is check_network:
+            continue
+        result = fn()
+        results.append(result)
+        mark = "✓" if result.ok else "✗"
+        line = f"[{mark}] {result.label}" + (f"  {result.detail}" if result.detail else "")
+        if result.ok:
+            console.log(line)
+        else:
+            console.error(line)
+            if result.hint:
+                console.hint(result.hint)
+
+    required_fail = sum(1 for r in results if r.required and not r.ok)
+    total_ok = sum(1 for r in results if r.ok)
+    console.log(
+        f"\n{total_ok}/{len(results)} 项通过"
+        + ("，存在缺失项，请按提示修复" if required_fail else "")
+    )
+    return results
+
+
+def environment_ok(console: Console) -> bool:
+    """供 ``run`` 前置校验使用：必查项全过才返回 True。"""
+    missing = [r for r in run_doctor(console) if r.required and not r.ok]
+    return not missing
+
+
+__all__ = ["CHECKS", "CheckResult", "environment_ok", "run_doctor"]

bb_sync/core/due.py

@@ -0,0 +1,192 @@
+"""把课程 Due / To Do 数据渲染为按优先级排列的 ``due.md``。"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter, defaultdict
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+from bb_sync.blackboard.models import BASE, Course, DueItem
+
+#: 分组顺序就是学生处理任务的优先级；「已过期事件」只是留档回看，所以排最后。
+_BUCKET_ORDER = ("overdue", "today", "tomorrow", "next_7_days", "future", "unknown", "past_events")
+_BUCKET_LABELS = {
+    "overdue": "已逾期",
+    "today": "今天",
+    "tomorrow": "明天",
+    "next_7_days": "未来 7 天",
+    "future": "之后",
+    "unknown": "日期未知",
+    "past_events": "已过期事件",
+}
+
+#: 非普通任务的待办类型标签（来自公告的课堂测验 / 考试）；顺序即汇总文案里的出现顺序。
+_KIND_LABELS = {"quiz": "测验", "exam": "考试"}
+
+
+def kind_label(kind: str) -> str:
+    """返回待办类型的中文标签；普通任务返回空串。"""
+    return _KIND_LABELS.get(kind, "")
+
+
+def _is_past_event(item: DueItem, today: date) -> bool:
+    """公告里的一次性事件（测验 / 考试）日期已过：它只能回看，没法再「做」。
+
+    与 ``overdue`` 的区别：To Do 模块的逾期任务意味着「还没交」，仍然要行动；
+    考完的测验 / 考试已是历史，混进待办里只会淹没真正要做的事。
+    """
+    return item.kind in _KIND_LABELS and item.due_date is not None and item.due_date < today
+
+
+def _bucket(item: DueItem, today: date) -> str:
+    """按剩余时间归类；无法解析日期的任务放最后，避免被误判成低优先级。"""
+    if item.due_date is None:
+        return "unknown"
+    if _is_past_event(item, today):
+        return "past_events"
+    if item.due_date < today:
+        return "overdue"
+    if item.due_date == today:
+        return "today"
+    if item.due_date == today + timedelta(days=1):
+        return "tomorrow"
+    if item.due_date <= today + timedelta(days=7):
+        return "next_7_days"
+    return "future"
+
+
+def relative_due(item: DueItem, today: date) -> str:
+    """生成截止日期旁的中文提示。"""
+    if item.due_date is None:
+        return item.due_text or "日期未知"
+    delta = (item.due_date - today).days
+    if delta < 0:
+        # 逾期的 To Do 是「还没交」，公告里的测验 / 考试是「已经考过」，措辞分开。
+        return f"已过 {-delta} 天" if item.kind in _KIND_LABELS else f"逾期 {-delta} 天"
+    if delta == 0:
+        return "今天"
+    if delta == 1:
+        return "明天"
+    return f"还有 {delta} 天"
+
+
+def _escape_markdown(text: str) -> str:
+    """转义会改变 Markdown 结构的常见字符，同时保留可读标题。"""
+    text = re.sub(r"\s+", " ", text).strip()
+    return re.sub(r"([\\`*_\[\]])", r"\\\1", text)
+
+
+def _sort_key(item: DueItem) -> tuple[date, str, str]:
+    return (item.due_date or date.max, item.course_label, item.title)
+
+
+def sort_due_items(items: list[DueItem]) -> list[DueItem]:
+    """按截止日期、课程和任务名返回稳定排序的新列表。"""
+    return sorted(items, key=_sort_key)
+
+
+def build_due_markdown(
+    courses: list[Course],
+    items: list[DueItem],
+    *,
+    failed: int = 0,
+    today: date | None = None,
+    generated_at: datetime | None = None,
+) -> str:
+    """生成全局 ``due.md`` 文本。
+
+    输出按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后 → 日期未知 → 已过期事件」排序；
+    同一分组内再按日期、课程和任务名稳定排序。
+    """
+    day = today or date.today()
+    generated = generated_at or datetime.now().astimezone()
+    grouped: dict[str, list[DueItem]] = defaultdict(list)
+    for item in items:
+        grouped[_bucket(item, day)].append(item)
+    for bucket_items in grouped.values():
+        bucket_items.sort(key=_sort_key)
+
+    # 过期事件单独成区，汇总行也不把它算进「待办」，否则「测验 2 项」里混着考完的。
+    past_events = grouped.get("past_events", [])
+    kind_counts = Counter(item.kind for item in items if not _is_past_event(item, day))
+    # 只统计公告整理出的待办，按 _KIND_LABELS 的固定顺序列出（测验 → 考试）。
+    announcement_parts = [
+        f"{label} {kind_counts[kind]} 项"
+        for kind, label in _KIND_LABELS.items()
+        if kind_counts[kind]
+    ]
+    lines = [
+        "# Blackboard 待办",
+        "",
+        f"> 更新时间：{generated.strftime('%Y-%m-%d %H:%M')}（本地时间）",
+        f"> 已检查 {len(courses)} 门课程，发现 {len(items)} 项待办；按优先级和截止日期排列。",
+    ]
+    if announcement_parts:
+        lines.append(f"> 其中公告里的{'、'.join(announcement_parts)}已一并作为待办列出。")
+    if past_events:
+        lines.append(f"> 另有 {len(past_events)} 项公告里的测验/考试日期已过，列在最后仅供回看。")
+    if failed:
+        lines.append(f"> 注意：{failed} 门课程抓取失败，结果可能不完整。")
+    lines.append("")
+
+    if not items:
+        if failed:
+            lines.extend(["本次未读取到待办，但由于部分课程抓取失败，结果可能不完整。", ""])
+        else:
+            lines.extend(["## Congratulations! 🎉", "", "当前没有待办事项。", ""])
+        return "\n".join(lines)
+
+    for bucket in _BUCKET_ORDER:
+        bucket_items = grouped.get(bucket, [])
+        if not bucket_items:
+            continue
+        lines.append(f"## {_BUCKET_LABELS[bucket]}（{len(bucket_items)}）")
+        lines.append("")
+        for item in bucket_items:
+            due = item.due_date.isoformat() if item.due_date else "日期未知"
+            course_url = (
+                f"{BASE}/webapps/blackboard/execute/launcher?type=Course&id={item.course_id}"
+            )
+            label = kind_label(item.kind)
+            badge = f"【{label}】" if label else ""
+            lines.append(
+                f"- **{due}**（{relative_due(item, day)}） — "
+                f"[{_escape_markdown(item.course_label)}]({course_url}) — "
+                f"{badge}{_escape_markdown(item.title)}"
+            )
+        lines.append("")
+    return "\n".join(lines)
+
+
+def write_due_markdown(
+    path: Path,
+    courses: list[Course],
+    items: list[DueItem],
+    *,
+    failed: int = 0,
+    today: date | None = None,
+    generated_at: datetime | None = None,
+) -> Path:
+    """写入 ``due.md``，父目录不存在时自动创建。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        build_due_markdown(
+            courses,
+            items,
+            failed=failed,
+            today=today,
+            generated_at=generated_at,
+        ),
+        encoding="utf-8",
+    )
+    return path
+
+
+__all__ = [
+    "build_due_markdown",
+    "kind_label",
+    "relative_due",
+    "sort_due_items",
+    "write_due_markdown",
+]

bb_sync/core/errors.py

@@ -0,0 +1,107 @@
+"""异常体系与退出码。
+
+约定：CLI 层只捕获 :class:`BbSyncError`，由它自带的 ``exit_code`` 决定进程退出码；
+其他未预期异常统一归为 ``GENERAL_ERROR``，并打印堆栈方便报 bug。
+
+退出码语义（对齐 BSD sysexits 精神，保持小整数便于脚本判断）::
+
+    0  SUCCESS           成功
+    1  GENERAL_ERROR     未分类错误
+    2  USAGE_ERROR       命令行用法错误（Typer/Click 自身也用 2）
+    3  AUTH_ERROR        登录 / 凭据失败
+    4  CONFIG_ERROR      配置文件问题
+    5  NETWORK_ERROR     网络 / 代理 / 下载失败
+    6  NOT_FOUND         目标资源不存在
+    7  ENVIRONMENT_ERROR 依赖缺失（Node / 浏览器 / Steel 等）
+    8  INTERRUPTED       用户中断（Ctrl+C）
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """进程退出码。"""
+
+    SUCCESS = 0
+    GENERAL_ERROR = 1
+    USAGE_ERROR = 2
+    AUTH_ERROR = 3
+    CONFIG_ERROR = 4
+    NETWORK_ERROR = 5
+    NOT_FOUND = 6
+    ENVIRONMENT_ERROR = 7
+    INTERRUPTED = 8
+
+
+class BbSyncError(Exception):
+    """所有可预期错误的基类，自带退出码与可选修复提示。"""
+
+    exit_code: ExitCode = ExitCode.GENERAL_ERROR
+
+    def __init__(self, message: str, hint: str = "") -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+
+
+class UsageError(BbSyncError):
+    """命令行参数用法错误。"""
+
+    exit_code = ExitCode.USAGE_ERROR
+
+
+class ConfigError(BbSyncError):
+    """配置文件缺失、格式错误或不支持的操作。"""
+
+    exit_code = ExitCode.CONFIG_ERROR
+
+
+class AuthError(BbSyncError):
+    """登录失败、凭据无效或缺失。"""
+
+    exit_code = ExitCode.AUTH_ERROR
+
+
+class NetworkError(BbSyncError):
+    """网络不可达、代理异常、下载失败。"""
+
+    exit_code = ExitCode.NETWORK_ERROR
+
+
+class NotFoundError(BbSyncError):
+    """课程 / 配置键 / 文件等目标不存在。"""
+
+    exit_code = ExitCode.NOT_FOUND
+
+
+class EnvironmentError_(BbSyncError):
+    """运行环境不满足（Node / npm / 浏览器 / Steel 未就绪）。
+
+    名字带下划线后缀，避免与内置 :class:`EnvironmentError` 混淆。
+    """
+
+    exit_code = ExitCode.ENVIRONMENT_ERROR
+
+
+def exit_code_for(exc: BaseException) -> ExitCode:
+    """把任意异常映射为退出码。"""
+    if isinstance(exc, BbSyncError):
+        return exc.exit_code
+    if isinstance(exc, KeyboardInterrupt):
+        return ExitCode.INTERRUPTED
+    return ExitCode.GENERAL_ERROR
+
+
+__all__ = [
+    "AuthError",
+    "BbSyncError",
+    "ConfigError",
+    "EnvironmentError_",
+    "ExitCode",
+    "NetworkError",
+    "NotFoundError",
+    "UsageError",
+    "exit_code_for",
+]

bb_sync/core/output.py

@@ -0,0 +1,151 @@
+"""输出通道：结果走 stdout，诊断走 stderr。
+
+Unix CLI 的核心约定，本项目严格遵守：
+
+======================  =========================  ====================
+通道                    内容                       典型用法
+======================  =========================  ====================
+stdout                  命令的「数据结果」           ``bb-sync course list | jq '.[].code'``
+stderr                  日志 / 进度 / 警告 / 错误    人读，或 ``2>/dev/null`` 丢弃
+======================  =========================  ====================
+
+:class:`Console` 是唯一的输出入口，两个职责：
+
+1. **结果输出**（``result`` / ``table`` / ``emit``）—— 支持「人读」与「JSON」双模式。
+   机器模式（``--json``）下，只有 ``emit`` 会往 stdout 吐**一个** JSON 文档，
+   Rich 表格与人类可读文本全部被抑制，保证 stdout 是干净可解析的。
+2. **诊断输出**（``log`` / ``warn`` / ``error`` / ``success`` / ``hint``）—— 一律走 stderr，
+   且随 ``--quiet`` 降级。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+from rich.console import Console as RichConsole
+from rich.table import Table
+
+_NO_COLOR_ENV = "NO_COLOR"
+
+
+class Console:
+    """统一输出出口。
+
+    :param json_mode: ``--json``：stdout 只输出机器可读 JSON。
+    :param quiet: ``--quiet``：抑制 stderr 上的普通日志（错误与警告仍显示）。
+    :param verbose: ``--verbose``：stderr 上追加调试信息。
+    """
+
+    def __init__(self, *, json_mode: bool = False, quiet: bool = False, verbose: bool = False):
+        self.json_mode = json_mode
+        self.quiet = quiet
+        self.verbose = verbose
+        # 结果通道：人读内容可能带颜色；JSON 模式绝不带颜色
+        self._out = RichConsole(
+            file=sys.stdout,
+            soft_wrap=True,
+            no_color=json_mode,
+            highlight=False,
+        )
+        # 诊断通道：始终 stderr，颜色随 TTY 自适应
+        self._err = RichConsole(file=sys.stderr, stderr=True, soft_wrap=True, highlight=False)
+
+    # ------------------------------------------------------------ 诊断（stderr）
+    def log(self, message: str = "", *, level: str = "info") -> None:
+        """常规日志 → stderr。``--quiet`` 时不显示。"""
+        if self.quiet:
+            return
+        style = {"info": "dim", "step": "cyan"}.get(level, "dim")
+        self._err.print(message, style=style, markup=False, highlight=False)
+
+    def step(self, message: str) -> None:
+        """阶段性标题 → stderr，如 ``[scan] 获取课程列表 ...``。"""
+        if self.quiet:
+            return
+        self._err.print(message, style="bold cyan", markup=False, highlight=False)
+
+    def success(self, message: str) -> None:
+        """成功提示 → stderr，带 ✓。"""
+        if self.quiet:
+            return
+        self._err.print(f"✓ {message}", style="green", markup=False, highlight=False)
+
+    def warn(self, message: str) -> None:
+        """警告 → stderr，``--quiet`` 时仍显示。"""
+        self._err.print(f"! {message}", style="yellow", markup=False, highlight=False)
+
+    def error(self, message: str) -> None:
+        """错误 → stderr，始终显示。"""
+        self._err.print(f"✗ {message}", style="bold red", markup=False, highlight=False)
+
+    def hint(self, message: str) -> None:
+        """修复建议 → stderr，缩进显示在错误下方。"""
+        self._err.print(f"  → {message}", style="dim", markup=False, highlight=False)
+
+    def debug(self, message: str) -> None:
+        """调试信息 → stderr，仅 ``--verbose`` 显示。"""
+        if self.verbose and not self.quiet:
+            self._err.print(f"[debug] {message}", style="dim", markup=False, highlight=False)
+
+    def rule(self, title: str = "") -> None:
+        """分隔线 → stderr。"""
+        if not self.quiet:
+            self._err.rule(title, style="dim")
+
+    # ------------------------------------------------------------ 结果（stdout）
+    def emit(self, data: Any) -> None:
+        """输出结构化结果到 stdout。
+
+        人读模式（默认）只输出**标量**——因为 ``bb-sync run`` 的结果人类是通过
+        stderr 上的汇总看的，stdout 应保持干净，避免干扰 ``$(...)`` 取值。
+        容器类型（dict/list）在人读模式下**不输出**，仅在 ``--json`` 时输出，
+        这样 ``--json`` 的语义就是「stdout 上有且仅有一个 JSON 文档」。
+        """
+        if self.json_mode:
+            self._write_json(data)
+            return
+        if isinstance(data, (str, int, float, bool)):
+            self._out.print(str(data), markup=False, highlight=False)
+
+    def _write_json(self, data: Any) -> None:
+        """stdout 上输出单个 JSON 文档，UTF-8 原样保留中文。"""
+        text = json.dumps(data, ensure_ascii=False, indent=2, default=str)
+        sys.stdout.write(text + "\n")
+        sys.stdout.flush()
+
+    def table(
+        self,
+        columns: Sequence[str],
+        rows: Iterable[Sequence[Any]],
+        *,
+        title: str = "",
+        json_data: Any = None,
+    ) -> None:
+        """表格输出。
+
+        ``--json`` 模式下抑制表格，改为输出 ``json_data``（缺省时把 rows 转成
+        以 columns 为键的记录列表），保证脚本拿到的是稳定结构。
+        """
+        rows = list(rows)
+        if self.json_mode:
+            if json_data is None:
+                json_data = [dict(zip(columns, r, strict=False)) for r in rows]
+            self._write_json(json_data)
+            return
+        table = Table(title=title or None, header_style="bold", box=None, pad_edge=False)
+        for col in columns:
+            table.add_column(str(col))
+        for row in rows:
+            table.add_row(*[str(c) for c in row])
+        # 表格本身是「人读结果」，所以走 stdout
+        self._out.print(table if table.row_count else "", markup=False)
+
+    def print_raw(self, text: str) -> None:
+        """逐字输出到 stdout（不加样式），用于 ``config show`` 之类。"""
+        self._out.print(text, markup=False, highlight=False, soft_wrap=True)
+
+
+__all__ = ["Console"]