tytcli 0.2.0__py3-none-any.whl

tytcli/config.py

@@ -0,0 +1,578 @@
+"""配置的发现、加载与解析。
+
+**可配置**的那些设置，其优先级为::
+
+    环境变量  >  配置文件  >  内置默认值
+
+**环境的 base URL 不可配置。**下面的 ``BASE_URLS`` 是唯一真相来源：配置文件里的键
+和环境变量都不能覆盖它。若配置文件把 `base_url` 设成了**不同**的值，会大声报错而
+不是静默忽略——被静默忽略的覆盖项正是那种要花几个小时才能查清的东西。若它只是
+**复述**内置值，则容忍并忽略，这样旧模板写出来的配置文件仍然能加载。
+
+两个 base URL 已于 2026-11-06 对着线上服务验证过。注意这个不对称：
+**prod 没有 ``/api`` 路径前缀，test 有。**所以 ``client.py`` 里的端点一律写成
+相对于 base URL、且不带前导 ``/api`` 的形式::
+
+    prod  https://tytapi.1234567.com.cn         + Login/GetLoginInfoV2
+    test  https://tytapitest.1234567.com.cn/api + Login/GetLoginInfoV2
+
+在某个 URL 上拿到 ``ErrorCode -100``（认证）而不是 ``-1``（地址错误），就是该路由
+存在的证明。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+from urllib.parse import urlsplit
+
+from .errors import ConfigError
+
+DEFAULT_ENV = "prod"
+
+#: 仅有的两个环境及其 API base URL。固定在代码里。
+BASE_URLS: dict[str, str] = {
+    "prod": "https://tytapi.1234567.com.cn",
+    "test": "https://tytapitest.1234567.com.cn/api",
+}
+
+#: 公众号（WeChat Official Account）模块所用的第二个 API 根。
+#:
+#: 2026-11-06 在 ``test`` 上实测：这些路由住在 ``/middleApi/`` 下面，**不在**
+#: ``BASE_URLS`` 下面。``{test_base}/WechatPublic/getPostPage`` 回答
+#: ``ErrorCode -1``（地址错误），而 ``/middleApi/WechatPublic/…`` 才能用。
+#: 路径**大小写敏感**——小写的 ``wechatPublic`` 直接返回 HTTP 404。
+#:
+#: ``prod`` 那一条是按 test 的规律**外推**出来的，无法证实：2026-11-06 时 prod 上
+#: 每一个 ``/middleApi/`` 路径都返回 HTTP 404，而 prod 已知可用的
+#: ``Login/GetLoginInfoV2`` 返回 ``-100``——所以 prod 是可达的，只是该模块没有部署
+#: 在那里。仍然把 URL 列出来，是为了让 404 **自然发生**（并带上提示），而不是在代码里
+#: 写死"prod 不可用"；若 prod 将来部署到这个路径，命令不改一行代码就能用。若部署到
+#: 别处，要改的就是这一行。
+#:
+#: 与 ``BASE_URLS`` 同一策略：固定在代码里，配置文件和环境变量都不能覆盖。
+MIDDLE_BASE_URLS: dict[str, str] = {
+    "prod": "https://tytapi.1234567.com.cn/middleApi",
+    "test": "https://tytapitest.1234567.com.cn/middleApi",
+}
+
+#: 排序后的全部合法环境名。**只用于校验**——面向用户的输出必须改走
+#: ``visible_envs()``。
+KNOWN_ENVS: tuple[str, ...] = tuple(sorted(BASE_URLS))
+
+#: CLI 允许向用户宣传的环境。
+#:
+#: ``test`` 确实存在、确实可用，也在 AGENTS.md 里为开发者记录了；但它是**开发**
+#: 环境，不得出现在最终用户面前。
+PUBLIC_ENVS: tuple[str, ...] = ("prod",)
+
+
+def visible_envs(active_env: str | None = None) -> tuple[str, ...]:
+    """返回面向用户的输出里可以列出的那些环境。
+
+    ``test`` 保持隐藏，除非它正是当前生效的环境——这样一个已经切过去的开发者仍然
+    能得到自洽的输出，而普通用户永远不会从 CLI 里学到这个名字。所有用户可见的列举
+    （``env list``、``env show``、未知环境的报错、``--help``）都要走本函数，
+    而不是直接读 ``KNOWN_ENVS``。
+    """
+    envs = list(PUBLIC_ENVS)
+    if active_env is not None and active_env not in envs:
+        envs.append(active_env)
+    return tuple(sorted(envs))
+
+DEFAULT_TIMEOUT_SECONDS = 15.0
+MIN_TIMEOUT_SECONDS = 0.1
+MAX_TIMEOUT_SECONDS = 300.0
+
+ENV_VAR_CONFIG = "TYTCLI_CONFIG"
+ENV_VAR_ENV = "TYTCLI_ENV"
+ENV_VAR_TOKEN = "TYTCLI_TOKEN"
+ENV_VAR_XDG_CONFIG_HOME = "XDG_CONFIG_HOME"
+
+APP_DIR_NAME = "tytcli"
+CONFIG_FILE_NAME = "config.toml"
+
+_SECTION_RE = re.compile(r"^\s*\[(?P<name>[^\]]+?)\]\s*(?:#.*)?$")
+_KEY_RE = re.compile(r"^\s*(?P<key>[A-Za-z0-9_-]+)\s*=")
+
+def _validate_base_urls() -> None:
+    """在 import 时就对硬编码的 base URL 做一次合理性检查。
+
+    它们是唯一**绝不能**出错的东西，因为解析链上再没有别的环节能纠正它们。这里用
+    ``RuntimeError`` 而不是 ``assert``：``python -O`` 会把 assert 全部剥掉，那样
+    这项检查就被静默关掉了。
+    """
+    for name, url in BASE_URLS.items():
+        if not url.startswith("https://") or url.endswith("/"):
+            raise RuntimeError(
+                f"BASE_URLS[{name!r}] 必须是不带末尾斜杠的 https URL：{url!r}"
+            )
+    for name, url in MIDDLE_BASE_URLS.items():
+        if not url.startswith("https://") or url.endswith("/"):
+            raise RuntimeError(
+                f"MIDDLE_BASE_URLS[{name!r}] 必须是不带末尾斜杠的 https URL："
+                f"{url!r}"
+            )
+    # middle 根如果与所属环境不同主机，就会把 TYT_Token cookie 送到意料之外的
+    # 地方。重定向本来就禁用了，但主机本身也值得钉住。
+    for name in BASE_URLS:
+        if name not in MIDDLE_BASE_URLS:
+            raise RuntimeError(f"MIDDLE_BASE_URLS 缺少环境 {name!r}")
+        core_host = urlsplit(BASE_URLS[name]).netloc
+        middle_host = urlsplit(MIDDLE_BASE_URLS[name]).netloc
+        if core_host != middle_host:
+            raise RuntimeError(
+                f"MIDDLE_BASE_URLS[{name!r}] 的主机 {middle_host!r} 与 "
+                f"BASE_URLS[{name!r}] 的主机 {core_host!r} 不同；TYT_Token cookie "
+                "绝不能被发往另一个主机"
+            )
+
+
+_validate_base_urls()
+
+
+def default_config_path() -> Path:
+    """返回 ``$XDG_CONFIG_HOME/tytcli/config.toml``（默认 ``~/.config``）。"""
+    xdg = os.environ.get(ENV_VAR_XDG_CONFIG_HOME, "").strip()
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    return base / APP_DIR_NAME / CONFIG_FILE_NAME
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    """一个命令需要的全部东西，均已解析并校验完毕。"""
+
+    path: Path
+    path_source: str  # TYTCLI_CONFIG | default（默认路径）
+    path_exists: bool
+    active_env: str
+    env_source: str  # TYTCLI_ENV | config | default（默认值）
+    base_url: str  # 永远来自 BASE_URLS；不可配置
+    #: 公众号模块所用的根（``MIDDLE_BASE_URLS``）；同样不可配置。
+    middle_base_url: str
+    token: str | None
+    token_source: str | None  # TYTCLI_TOKEN | config（配置文件）| None
+    timeout_seconds: float
+    raw: dict[str, Any]
+
+    def require_token(self) -> str:
+        if self.token:
+            return self.token
+
+        message = (
+            f"环境 '{self.active_env}' 缺少 TYT_Token。"
+            f"运行 `tytcli auth --token <TOKEN>` 写入配置，"
+            f"或设置环境变量 {ENV_VAR_TOKEN}。"
+        )
+        details: dict[str, Any] = {
+            "env": self.active_env,
+            "config_path": str(self.path),
+            "path_exists": self.path_exists,
+            "env_var": ENV_VAR_TOKEN,
+            "hint": f"tytcli auth --env {self.active_env} --token <TOKEN>",
+        }
+
+        # 一个常见陷阱：用户跑了 `auth --env test`，但 active_env 仍是 prod，
+        # 于是刚设完 Token，下一条命令就说"缺少 Token"。这里直接指出**哪个**环境
+        # 确实有 Token，而不是让用户去猜。我们刻意不替用户切换环境——
+        # `auth --env` 只写那一个段落，别的什么都不动。
+        others = [
+            name
+            for name in KNOWN_ENVS
+            if name != self.active_env
+            and str(env_section(self.raw, name).get("tyt_token") or "").strip()
+        ]
+        if others:
+            listed = ", ".join(others)
+            message += f"（注意：{listed} 环境已配置 Token，但当前生效的是 '{self.active_env}'）"
+            details["envs_with_token"] = others
+            details["hint"] = (
+                f"切换默认环境：tytcli env use {others[0]}；"
+                f"或单次运行：TYTCLI_ENV={others[0]} tytcli <command>；"
+                f"或为当前环境写入：tytcli auth --env {self.active_env} --token <TOKEN>"
+            )
+
+        raise ConfigError(message, code="CONFIG_MISSING_TOKEN", details=details)
+
+    def masked_token(self) -> str | None:
+        return mask_token(self.token)
+
+
+def mask_token(token: str | None) -> str | None:
+    """首 4 位 / 末 4 位的掩码，可以安全打印。**绝不**返回完整值。"""
+    if not token:
+        return None
+    if len(token) <= 8:
+        return "*" * len(token)
+    return f"{token[:4]}…{token[-4:]} (len={len(token)})"
+
+
+# --------------------------------------------------------------------------- #
+# 加载
+# --------------------------------------------------------------------------- #
+
+
+def _config_path_from_env(environ: dict[str, str]) -> tuple[Path, str, bool]:
+    raw = environ.get(ENV_VAR_CONFIG)
+    if raw is not None:
+        if not raw.strip():
+            raise ConfigError(f"{ENV_VAR_CONFIG} 已设置但为空，无法确定配置文件位置。")
+        path = Path(raw.strip()).expanduser()
+        if not path.is_file():
+            raise ConfigError(
+                f"{ENV_VAR_CONFIG} 指定的配置文件不存在：{path}",
+                code="CONFIG_NOT_FOUND",
+                details={"path": str(path), "source": ENV_VAR_CONFIG},
+            )
+        return path, ENV_VAR_CONFIG, True
+    path = default_config_path()
+    return path, "default", path.is_file()
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(
+            f"配置文件不是合法的 TOML：{path}（{exc}）",
+            code="CONFIG_PARSE_ERROR",
+            details={"path": str(path)},
+        ) from exc
+    except OSError as exc:
+        raise ConfigError(
+            f"配置文件无法读取：{path}（{exc}）",
+            code="CONFIG_UNREADABLE",
+            details={"path": str(path)},
+        ) from exc
+    # tomllib.load() 的类型就是 `dict[str, Any]`，而 TOML 文档的根一定是一张表，
+    # 所以这里没有需要防的形状。
+    return data
+
+
+def _as_table(value: object, *, error: str) -> dict[str, Any]:
+    """把一个 TOML 值窄化成"键为字符串的表"；缺失时返回 ``{}``。
+
+    ``raw.get()`` 给出的是 ``Any``；没有这次 cast，下游每一次访问的类型都是
+    ``Unknown``，而 basedpyright（正确地）拒绝在这种类型上做推理。
+    """
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(error)
+    return cast("dict[str, Any]", value)
+
+
+def env_section(raw: dict[str, Any], name: str) -> dict[str, Any]:
+    """返回 ``[env.<name>]`` 这张表；缺失时返回 ``{}``。"""
+    envs = _as_table(
+        raw.get("env"), error="配置项 [env] 必须是表（每个子表对应一个环境）。"
+    )
+    return _as_table(envs.get(name), error=f"[env.{name}] 必须是表。")
+
+
+def _check_configured_base_url(raw: dict[str, Any], path: Path) -> None:
+    """拒绝那些试图**改变** base URL 的配置文件。
+
+    若 `base_url` 的值与内置常量相同，则容忍并忽略：它在语义上是个空操作，而拒绝它
+    会让所有由"带这个键的旧模板"写出来的配置文件直接坏掉。只有值**真的不同**才是
+    值得失败的冲突——静默忽略那一种要糟得多，因为用户会以为自己的覆盖生效了。
+    """
+    envs_raw = raw.get("env")
+    if not isinstance(envs_raw, dict):
+        return
+    envs = cast("dict[str, Any]", envs_raw)
+
+    conflicts: list[tuple[str, str]] = []
+    for name, section in envs.items():
+        if not isinstance(section, dict):
+            continue
+        table = cast("dict[str, Any]", section)
+        value = table.get("base_url")
+        if value is None:
+            continue
+        if not isinstance(value, str):
+            conflicts.append((name, f"<非字符串: {type(value).__name__}>"))
+            continue
+        normalized = value.strip().rstrip("/")
+        expected = BASE_URLS.get(name)
+        if expected is None or normalized != expected:
+            conflicts.append((name, value.strip() or "<空值>"))
+
+    if conflicts:
+        listed = ", ".join(f"[env.{n}] = {v!r}" for n, v in conflicts)
+        raise ConfigError(
+            "环境 API 地址固定在代码中，不可通过配置文件覆盖。"
+            f"{path} 中的这些值与内置地址不一致：{listed}。"
+            f"请删除这些 base_url 键（内置值："
+            + ", ".join(f"{n}={u}" for n, u in sorted(BASE_URLS.items()))
+            + "）。可用 `tytcli config init --force` 重新生成模板。",
+            code="CONFIG_BASE_URL_NOT_CONFIGURABLE",
+            details={
+                "path": str(path),
+                "conflicts": [{"section": f"env.{n}", "value": v} for n, v in conflicts],
+                "base_urls": dict(BASE_URLS),
+            },
+        )
+
+
+def load_config(environ: dict[str, str] | None = None) -> ResolvedConfig:
+    """加载并解析出实际生效的配置。"""
+    env_map = dict(os.environ if environ is None else environ)
+
+    path, path_source, path_exists = _config_path_from_env(env_map)
+    raw = _read_toml(path) if path_exists else {}
+    _check_configured_base_url(raw, path)
+
+    active_env = _resolve_active_env(env_map, raw)
+    section = env_section(raw, active_env)
+    token, token_source = _resolve_token(env_map, section)
+
+    return ResolvedConfig(
+        path=path,
+        path_source=path_source,
+        path_exists=path_exists,
+        active_env=active_env,
+        env_source=_active_env_source(env_map, raw),
+        base_url=BASE_URLS[active_env],
+        middle_base_url=MIDDLE_BASE_URLS[active_env],
+        token=token,
+        token_source=token_source,
+        timeout_seconds=_resolve_timeout(raw),
+        raw=raw,
+    )
+
+
+def _active_env_source(env_map: dict[str, str], raw: dict[str, Any]) -> str:
+    if env_map.get(ENV_VAR_ENV) is not None:
+        return ENV_VAR_ENV
+    if isinstance(raw.get("active_env"), str) and raw["active_env"].strip():
+        return "config"
+    return "default"
+
+
+def _resolve_active_env(env_map: dict[str, str], raw: dict[str, Any]) -> str:
+    from_env = env_map.get(ENV_VAR_ENV)
+    if from_env is not None:
+        name, source = from_env.strip(), ENV_VAR_ENV
+        if not name:
+            raise ConfigError(f"{ENV_VAR_ENV} 已设置但为空。")
+    else:
+        configured = raw.get("active_env")
+        if configured is None:
+            return DEFAULT_ENV
+        if not isinstance(configured, str):
+            raise ConfigError("配置项 active_env 必须是字符串。")
+        if not configured.strip():
+            return DEFAULT_ENV
+        name, source = configured.strip(), "active_env"
+
+    if name not in BASE_URLS:
+        raise ConfigError(
+            f"未知环境 {name!r}（来源：{source}）。tytcli 只支持这两个环境：{', '.join(KNOWN_ENVS)}",
+            code="CONFIG_UNKNOWN_ENV",
+            details={"env": name, "known_envs": list(KNOWN_ENVS), "source": source},
+        )
+    return name
+
+
+def _resolve_token(env_map: dict[str, str], section: dict[str, Any]) -> tuple[str | None, str | None]:
+    override = env_map.get(ENV_VAR_TOKEN)
+    if override is not None:
+        # 显式的空值是一个错误，而不是"静默回退到配置文件里的值"。
+        if not override.strip():
+            raise ConfigError(
+                f"{ENV_VAR_TOKEN} 已设置但为空；不会静默回退到配置文件中的 Token。",
+                code="CONFIG_EMPTY_TOKEN",
+                details={"env_var": ENV_VAR_TOKEN},
+            )
+        return override.strip(), ENV_VAR_TOKEN
+
+    configured = section.get("tyt_token")
+    if configured is None:
+        return None, None
+    if not isinstance(configured, str):
+        raise ConfigError("tyt_token 必须是字符串。")
+    value = configured.strip()
+    return (value or None), ("config" if value else None)
+
+
+def _resolve_timeout(raw: dict[str, Any]) -> float:
+    value = raw.get("timeout_seconds", DEFAULT_TIMEOUT_SECONDS)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ConfigError("timeout_seconds 必须是数字（秒）。")
+    seconds = float(value)
+    if not MIN_TIMEOUT_SECONDS <= seconds <= MAX_TIMEOUT_SECONDS:
+        raise ConfigError(
+            f"timeout_seconds 必须在 {MIN_TIMEOUT_SECONDS}–{MAX_TIMEOUT_SECONDS} 之间，当前为 {seconds}。"
+        )
+    return seconds
+
+
+# --------------------------------------------------------------------------- #
+# writing
+# --------------------------------------------------------------------------- #
+
+CONFIG_TEMPLATE = """\
+# tytcli 配置文件
+#
+# 环境的 API base URL 固定在代码里，**刻意不在此处提供配置项**。
+# 若 base_url 与内置值不同，会直接报错。
+#
+# 可覆盖的设置，按优先级从高到低：
+#   TYTCLI_CONFIG  本文件的路径
+#   TYTCLI_ENV     当前生效的环境
+#   TYTCLI_TOKEN   当前生效环境的 tyt_token
+#
+# 写入 Token 最省事的方式：  tytcli auth --token <TOKEN>
+# 不要把本文件提交进版本库。权限：0600。
+
+active_env = "prod"
+timeout_seconds = 15.0
+
+[env.prod]
+tyt_token = ""
+"""
+
+
+def validate_token(token: str) -> str:
+    """规范化并校验用户提供的 Token。"""
+    value = token.strip()
+    if not value:
+        raise ConfigError("Token 为空。", code="AUTH_EMPTY_TOKEN")
+    if any(char.isspace() for char in value):
+        raise ConfigError(
+            "Token 中含有空白字符，很可能是复制粘贴出错。",
+            code="AUTH_MALFORMED_TOKEN",
+            details={"token_hint": mask_token(value)},
+        )
+    return value
+
+
+def _toml_basic_string(value: str) -> str:
+    escaped = (
+        value.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\r", "\\r")
+        .replace("\t", "\\t")
+    )
+    return f'"{escaped}"'
+
+
+def _write_locked(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with contextlib.suppress(OSError):
+        os.chmod(path.parent, 0o700)
+    path.write_text(text, encoding="utf-8")
+    with contextlib.suppress(OSError):
+        os.chmod(path, 0o600)
+
+
+def write_default_config(path: Path, *, force: bool = False) -> Path:
+    """创建一个 0600 权限的初始配置文件。"""
+    if path.exists() and not force:
+        raise ConfigError(
+            f"配置文件已存在：{path}（使用 --force 覆盖）",
+            code="CONFIG_EXISTS",
+            details={"path": str(path)},
+        )
+    _write_locked(path, CONFIG_TEMPLATE)
+    return path
+
+
+def ensure_config_file(config: ResolvedConfig) -> Path:
+    """确保存在一个可写的配置文件；必要时按模板创建。"""
+    if config.path_exists:
+        return config.path
+    if config.path_source == ENV_VAR_CONFIG:
+        # load_config() 已经会拒绝"显式指定的路径不存在"；这里是双保险。
+        raise ConfigError(
+            f"{ENV_VAR_CONFIG} 指定的配置文件不存在：{config.path}",
+            code="CONFIG_NOT_FOUND",
+            details={"path": str(config.path)},
+        )
+    write_default_config(config.path)
+    return config.path
+
+
+def _split_sections(lines: list[str]) -> list[tuple[str | None, int, int]]:
+    """返回 ``(段落名, 段落头行号, 段落正文结束行号)`` 这些区间。
+
+    第一个 ``[table]`` 头之前的那段顶层区域，其 ``section_name`` 为 ``None``。
+    """
+    spans: list[tuple[str | None, int, int]] = [(None, -1, len(lines))]
+    for index, line in enumerate(lines):
+        match = _SECTION_RE.match(line)
+        if match:
+            spans[-1] = (spans[-1][0], spans[-1][1], index)
+            spans.append((match.group("name").strip(), index, len(lines)))
+    return spans
+
+
+def _set_key(
+    path: Path,
+    key: str,
+    value_toml: str,
+    *,
+    section: str | None = None,
+) -> None:
+    """就地在 TOML 文件里设置 ``key = value``，其余内容原样保留。
+
+    ``section=None`` 表示顶层（任何 ``[table]`` 头之前）。段落缺失时会创建它。
+    注释与无关的行都会被保留。
+    """
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    trailing_newline = text.endswith("\n") or not text
+    lines = text.splitlines()
+    assignment = f"{key} = {value_toml}"
+
+    spans = _split_sections(lines)
+    target = next((span for span in spans if span[0] == section), None)
+
+    if target is None:
+        if section is None:
+            # 没找到顶层区域（文件以一张表开头）：插到它上面。
+            insert_at = spans[1][1] if len(spans) > 1 else len(lines)
+            lines[insert_at:insert_at] = [assignment, ""]
+        else:
+            if lines and lines[-1].strip():
+                lines.append("")
+            lines.extend([f"[{section}]", assignment])
+    else:
+        _name, header_index, body_end = target
+        start = header_index + 1 if section is not None else 0
+        replaced = False
+        for index in range(start, body_end):
+            match = _KEY_RE.match(lines[index])
+            if match and match.group("key") == key:
+                lines[index] = assignment
+                replaced = True
+                break
+        if not replaced:
+            # 插到段落正文的末尾，并跳过尾部的空行，这样这个键就不会落在
+            # "下一个段落头之前的空档"后面。
+            insert_at = body_end
+            while insert_at > start and not lines[insert_at - 1].strip():
+                insert_at -= 1
+            lines.insert(insert_at, assignment)
+
+    new_text = "\n".join(lines)
+    if trailing_newline:
+        new_text += "\n"
+    _write_locked(path, new_text)
+
+
+def set_active_env(path: Path, name: str) -> None:
+    """把 ``active_env`` 持久化到配置文件的顶层。"""
+    _set_key(path, "active_env", _toml_basic_string(name))
+
+
+def set_env_token(path: Path, env_name: str, token: str) -> None:
+    """把 ``tyt_token`` 持久化到 ``[env.<env_name>]`` 里。"""
+    _set_key(path, "tyt_token", _toml_basic_string(token), section=f"env.{env_name}")

tytcli/errors.py

@@ -0,0 +1,71 @@
+"""tytcli 的错误类型体系。
+
+每个错误都带一个稳定的、机器可读的 ``code`` 和 ``exit_code``，这样 agent 可以直接
+按结果分支，而不需要去解析文案。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TytCliError(Exception):
+    """所有"预期内失败"的基类。"""
+
+    default_code = "ERROR"
+    default_exit_code = 1
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        exit_code: int | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code or self.default_code
+        self.exit_code = self.default_exit_code if exit_code is None else exit_code
+        self.details = details or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"code": self.code, "message": self.message}
+        if self.details:
+            payload["details"] = self.details
+        return payload
+
+
+class UsageError(TytCliError):
+    """命令行用法错误。"""
+
+    default_code = "USAGE"
+    default_exit_code = 2
+
+
+class ConfigError(TytCliError):
+    """配置缺失、不可读或自相矛盾。"""
+
+    default_code = "CONFIG_INVALID"
+    default_exit_code = 2
+
+
+class AuthError(TytCliError):
+    """服务端拒绝了我们的凭证（TYT_Token 缺失或已过期）。"""
+
+    default_code = "AUTH_EXPIRED"
+    default_exit_code = 3
+
+
+class NetworkError(TytCliError):
+    """HTTP 交换没能完成（DNS、TLS、超时等）。"""
+
+    default_code = "NETWORK"
+    default_exit_code = 4
+
+
+class ApiError(TytCliError):
+    """服务端有响应，但返回的是业务失败或无法解析的内容。"""
+
+    default_code = "API_ERROR"
+    default_exit_code = 1