tytcli 0.2.0__py3-none-any.whl

tytcli/commands/__init__.py

@@ -0,0 +1,52 @@
+"""一个命令组一个模块。
+
+``cli.py`` 刻意保持为入口：console script 是 ``tytcli.cli:entrypoint``，而自更新的
+re-exec 跑的是 ``python -m tytcli.cli``。把 ``cli`` 变成包会**静默**破坏后者（那时
+它需要一个 ``__main__.py``），所以拆分放在这里，``cli.py`` 仍然是一个普通模块。
+
+命令模块**绝不能** import ``tytcli.cli``——那是循环依赖。它们改为 import
+``tytcli.output`` 与 ``tytcli.commands.shared``。
+"""
+
+from __future__ import annotations
+
+import click
+
+from . import (
+    auth,
+    config,
+    env,
+    help,
+    roadshow,
+    sentiment,
+    upgrade,
+    wechat,
+    whoami,
+)
+
+#: 全部顶层命令，由 ``cli.py`` 注册到根 group 上。
+#: click 显示时会自己排序，所以这里的顺序只影响注册次序。
+ALL_COMMANDS: tuple[click.Command, ...] = (
+    whoami.whoami,
+    auth.auth,
+    env.env,
+    config.config,
+    upgrade.upgrade,
+    wechat.wechat,
+    sentiment.sentiment,
+    roadshow.roadshow,
+    help.help_command,
+)
+
+__all__ = [
+    "ALL_COMMANDS",
+    "auth",
+    "config",
+    "env",
+    "help",
+    "roadshow",
+    "sentiment",
+    "upgrade",
+    "wechat",
+    "whoami",
+]

tytcli/commands/auth.py

@@ -0,0 +1,147 @@
+"""``tytcli auth`` —— 写入并校验一个 TYT_Token。"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+import click
+
+from ..client import TytClient
+from ..config import (
+    BASE_URLS,
+    ENV_VAR_ENV,
+    ENV_VAR_TOKEN,
+    KNOWN_ENVS,
+    ensure_config_file,
+    load_config,
+    mask_token,
+    set_env_token,
+    validate_token,
+    visible_envs,
+)
+from ..errors import ConfigError, TytCliError, UsageError
+from ..output import emit_ok
+from .shared import raise_for_envelope, require_config
+from .whoami import extract_identity
+
+
+@click.command()
+@click.option(
+    "--token",
+    "token_option",
+    required=True,
+    metavar="TOKEN",
+    help="要写入的 TYT_Token；传 '-' 从 stdin 读（不进 shell 历史，推荐）。",
+)
+@click.option(
+    "--env",
+    "env_name",
+    default=None,
+    metavar="ENV",
+    # **刻意不用 click.Choice**：那会把每一个合法环境名打进 --help 和它自己的
+    # 报错信息里，等于对外宣传那个开发环境。改为在命令体里手工对着 KNOWN_ENVS 校验。
+    help="写入哪个环境（默认：当前生效环境）。Token 按环境隔离。",
+)
+@click.option("--verify", is_flag=True, help="写入后立即调用 whoami 验证 Token 是否可用。")
+@click.pass_context
+def auth(ctx: click.Context, token_option: str, env_name: str | None, verify: bool) -> None:
+    """把 TYT_Token 写入配置文件（0600）。
+
+    \b
+    安全提示：--token 的值会留在 shell 历史和 `ps` 进程列表里。
+    交互式使用请改用管道：
+      tytcli auth --token -            # 从 stdin 读
+    或先用 shell 的隐藏输入：
+      read -rs TOK && tytcli auth --token "$TOK"
+    """
+    pretty: bool = ctx.obj["pretty"]
+    config = require_config(allow_missing_token=True)
+
+    target_env = (env_name or config.active_env).strip().lower()
+    if target_env not in KNOWN_ENVS:
+        visible = visible_envs(config.active_env)
+        raise ConfigError(
+            f"未知环境 {target_env!r}。可用环境：{', '.join(visible)}",
+            code="CONFIG_UNKNOWN_ENV",
+            details={"env": target_env, "known_envs": list(visible)},
+        )
+
+    token = validate_token(_read_token(token_option))
+
+    path = ensure_config_file(config)
+    set_env_token(path, target_env, token)
+
+    # 往返校验：把 TYTCLI_TOKEN 从环境里剔掉后再回读文件，这样我们证明的是
+    # **真正落盘的内容**，而不是把自己刚传进来的值回显一遍。
+    readback_env = {k: v for k, v in os.environ.items() if k != ENV_VAR_TOKEN}
+    readback_env[ENV_VAR_ENV] = target_env
+    fresh = load_config(readback_env)
+    if fresh.token != token or fresh.token_source != "config":
+        raise ConfigError(
+            f"Token 已写入 {path} 但回读校验失败，请检查文件内容。",
+            code="CONFIG_WRITE_VERIFY_FAILED",
+            details={
+                "env": target_env,
+                "config_path": str(path),
+                "token_source": fresh.token_source,
+                "token_hint": fresh.masked_token(),
+            },
+        )
+
+    # TYTCLI_TOKEN 的优先级高于配置文件，所以一个忘了 unset 的 export 会**静默**
+    # 遮蔽我们刚写进去的值。这件事报在 JSON 文档里而不是 stderr 上，这样自动化
+    # 可以按字段分支，而不必去刮一句给人看的警告。
+    shadowed = os.environ.get(ENV_VAR_TOKEN)
+
+    result: dict[str, Any] = {
+        "env": target_env,
+        "base_url": BASE_URLS[target_env],
+        "config_path": str(path),
+        "token_hint": mask_token(token),
+        "token_source": "config",
+        "verified": None,
+        "token_shadowed": shadowed is not None,
+    }
+    if shadowed is not None:
+        result["shadow_warning"] = (
+            f"{ENV_VAR_TOKEN} 已设置，它会覆盖刚写入配置文件的 Token（当前生效："
+            f"{mask_token(shadowed.strip()) or '<empty>'}）。"
+            f"unset {ENV_VAR_TOKEN} 后才会使用文件里的值。"
+        )
+
+    if verify:
+        client = TytClient(BASE_URLS[target_env], token, timeout=config.timeout_seconds)
+        try:
+            envelope = client.whoami()
+            raise_for_envelope(
+                envelope, env_name=target_env, base_url=BASE_URLS[target_env]
+            )
+        except TytCliError as exc:
+            # Token **确实**已经在磁盘上了——包括失败来自传输层而不是 API 的情形。
+            # 把这一点说得毫无歧义，agent 才会去修凭证，而不是重试写入。
+            exc.details = {**exc.details, "written": True, "config_path": str(path)}
+            raise
+        result["verified"] = True
+        result["identity"] = extract_identity(envelope.payload)
+
+    emit_ok(result, pretty=pretty)
+
+
+def _read_token(value: str) -> str:
+    """解析 --token 的值，其中 '-' 表示"从 stdin 读"。"""""
+    if value != "-":
+        return value
+    if sys.stdin.isatty():
+        # tytcli 绝不阻塞在交互式输入上：一个传了 '-' 却没有接管道的 agent 会
+        # 永远挂住。所以直接快速失败。
+        raise UsageError(
+            "--token - 需要从 stdin 管道输入，但当前 stdin 是终端。"
+            "请改用：echo \"$TOK\" | tytcli auth --token - ，或直接传 --token <TOKEN>。",
+            code="USAGE_STDIN_REQUIRED",
+        )
+    data = sys.stdin.read()
+    if not data.strip():
+        raise UsageError("从 stdin 未读到任何 Token。", code="USAGE_STDIN_EMPTY")
+    return data.strip()

tytcli/commands/config.py

@@ -0,0 +1,61 @@
+"""``tytcli config`` —— 定位与初始化配置文件。
+
+不要与 ``tytcli.config``（配置**解析器**）混淆。本模块是命令组；下面的 import 一律
+用显式相对路径（``from ..config import ...``），这样两者不可能被误当成同一个东西。
+"""
+
+from __future__ import annotations
+
+import click
+
+from ..config import default_config_path, write_default_config
+from ..output import emit_ok
+from .shared import effective_config_payload, require_config
+
+
+@click.group()
+def config() -> None:
+    """配置文件相关操作。"""
+
+
+@config.command("path")
+@click.pass_context
+def config_path(ctx: click.Context) -> None:
+    """打印配置文件路径以及是否存在。"""
+    cfg = require_config(allow_missing_token=True)
+    emit_ok(
+        {
+            "path": str(cfg.path),
+            "source": cfg.path_source,
+            "exists": cfg.path_exists,
+            "default_path": str(default_config_path()),
+        },
+        pretty=ctx.obj["pretty"],
+    )
+
+
+@config.command("show")
+@click.pass_context
+def config_show(ctx: click.Context) -> None:
+    """显示当前生效配置：API 地址、Token 是否已配置及其来源（Token 脱敏）。"""
+    emit_ok(effective_config_payload(require_config(allow_missing_token=True)),
+            pretty=ctx.obj["pretty"])
+
+
+@config.command("init")
+@click.option("--force", is_flag=True, help="覆盖已存在的配置文件。")
+@click.pass_context
+def config_init(ctx: click.Context, force: bool) -> None:
+    """在默认位置创建一个 0600 权限的配置模板。"""
+    path = default_config_path()
+    created = not path.exists()
+    write_default_config(path, force=force)
+    emit_ok(
+        {
+            "path": str(path),
+            "created": created,
+            "overwritten": force and not created,
+            "next_step": "运行 tytcli auth --token <TOKEN> 写入凭证",
+        },
+        pretty=ctx.obj["pretty"],
+    )

tytcli/commands/env.py

@@ -0,0 +1,103 @@
+"""``tytcli env`` —— 环境的查看与切换。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..config import (
+    BASE_URLS,
+    KNOWN_ENVS,
+    ensure_config_file,
+    env_section,
+    load_config,
+    set_active_env,
+    visible_envs,
+)
+from ..errors import ConfigError, UsageError
+from ..output import emit_ok
+from .shared import effective_config_payload, require_config
+
+
+#: hidden=True — 环境切换是**开发人员**的配置面，不对外宣传（产品决定）。
+#: 命令本身完整可用，只是不出现在 `tytcli --help` 与随包文档里；说明留在
+#: AGENTS.md。别把它删掉，也别把它改成可见。
+@click.group(hidden=True)
+def env() -> None:
+    """查看与切换目标环境（开发用，不在 --help 中列出）。"""
+
+
+@env.command("list")
+@click.pass_context
+def env_list(ctx: click.Context) -> None:
+    """列出两个环境及其固定的 API base URL。"""
+    config = require_config(allow_missing_token=True)
+    rows: list[dict[str, Any]] = []
+    # visible_envs() 会隐藏开发环境，除非它正是当前生效的那个。
+    for name in visible_envs(config.active_env):
+        section = env_section(config.raw, name)
+        rows.append(
+            {
+                "name": name,
+                "base_url": BASE_URLS[name],
+                "active": name == config.active_env,
+                "token_configured": bool(str(section.get("tyt_token") or "").strip()),
+            }
+        )
+    emit_ok(
+        rows,
+        pretty=ctx.obj["pretty"],
+        active_env=config.active_env,
+        env_source=config.env_source,
+    )
+
+
+@env.command("show")
+@click.pass_context
+def env_show(ctx: click.Context) -> None:
+    """显示当前生效的环境、base URL 与配置来源（Token 已脱敏）。"""
+    config = require_config(allow_missing_token=True)
+    # 与公开的 `config show` 是同一份 payload；见 shared.effective_config_payload。
+    emit_ok(effective_config_payload(config), pretty=ctx.obj["pretty"])
+
+
+@env.command("use")
+@click.argument("name")
+@click.pass_context
+def env_use(ctx: click.Context, name: str) -> None:
+    """把 NAME 设为默认环境（写入配置文件的 active_env）。"""
+    target = name.strip()
+    if not target:
+        raise UsageError("环境名不能为空。")
+
+    config = require_config(allow_missing_token=True)
+    # 校验接受**每一个**真实环境（所以开发者的 `env use test` 仍然可用）；
+     # 但报错文案只列出面向用户的那几个。
+    if target not in KNOWN_ENVS:
+        visible = visible_envs(config.active_env)
+        raise ConfigError(
+            f"未知环境 {target!r}。可用环境：{', '.join(visible)}",
+            code="CONFIG_UNKNOWN_ENV",
+            details={"env": target, "known_envs": list(visible)},
+        )
+
+    path = ensure_config_file(config)
+    set_active_env(path, target)
+
+    # 重新读一遍，让汇报的状态反映磁盘上现在真实的内容。
+    fresh = load_config()
+    payload: dict[str, Any] = {
+        "active_env": fresh.active_env,
+        "base_url": fresh.base_url,
+        "config_path": str(path),
+        "token_configured": fresh.token is not None,
+    }
+    if fresh.token is None:
+        # 建议要放进 JSON 文档，而不是 stderr：一个命令只输出恰好一个机器可读的
+        # 结果，并保持 stderr 静默。
+        payload["hint"] = (
+            f"环境 '{target}' 尚未配置 TYT_Token，whoami 会失败。"
+            f"运行：tytcli auth --env {target} --token <TOKEN>"
+        )
+    emit_ok(payload, pretty=ctx.obj["pretty"])

tytcli/commands/help.py

@@ -0,0 +1,105 @@
+"""``help`` 命令：把随包发布的 skill 文档与命令关联起来。
+
+``tytcli help`` 打印命令摘要加路由文档（``SKILL.md``）；``tytcli help <command>``
+打印该命令的用法加记录它的那份参考文档。命令 -> 文档的映射只由这一处拥有
+（见 :mod:`tytcli.skill`）。
+
+刻意做成顶层子命令，既不是 ``--help`` 的扩展，也不是 ``<command> help`` 后缀：
+
+* ``--help`` 必须保持"快而可扫"的用法摘要；把上百行文档塞在选项下面会损害最常见
+  的用法，而且文档一改，每个 help 面都会跟着变。
+* ``<command> help`` 与位置参数冲突。已实测：``tytcli env use help`` 会报
+  ``CONFIG_UNKNOWN_ENV``，因为 ``help`` 被当成环境名吃掉了。将来任何带位置参数的
+  命令都会以同样的方式**静默**坏掉。
+
+每个命令的 ``--help`` 仍然带一行指针（在 ``cli.py`` 里追加），这样文档是可发现的，
+又不必被内嵌进去。
+"""
+
+from __future__ import annotations
+
+import click
+
+from .. import skill
+
+#: 命令用法与其长篇文档之间的视觉分隔线。
+_SEPARATOR = "\n────────────────────────────────────────\n\n"
+
+
+def _help_text(command: click.Command, name: str) -> str:
+    """按 ``--help`` 的原样渲染一个命令的帮助文本。"""
+    ctx = click.Context(command, info_name=f"tytcli {name}")
+    formatter = ctx.make_formatter()
+    command.format_help(ctx, formatter)
+    return formatter.getvalue()
+
+
+def _root_summary() -> str:
+    """``tytcli help`` 开头那份命令清单。
+
+    从命令注册表构造，而不是从根 group 对象：根 group 住在 ``cli.py`` 里，而
+    ``cli.py`` 又 import 本模块，所以在这里引用它就是循环依赖。
+    """
+    from . import ALL_COMMANDS
+
+    lines = ["命令："]
+    for command in ALL_COMMANDS:
+        # hidden=True 是 click 自己的标志位；而这份摘要是手工拼的，所以必须自己
+        # 尊重它。忘掉这一点，正是一个标着"不在 --help 中列出"的命令出现在这里
+        # 的原因。
+        if command.hidden:
+            continue
+        first_line = (command.help or command.short_help or "").strip().splitlines()
+        summary = first_line[0] if first_line else ""
+        lines.append(f"  {command.name:<10} {summary}")
+    lines.append("")
+    lines.append(skill.pointer_line(""))
+    return "\n".join(lines) + "\n"
+
+
+def _command_by_name() -> dict[str, click.Command]:
+    """延迟解析命令名，避免在加载期就构成循环 import。"""
+    from . import ALL_COMMANDS
+
+    return {command.name: command for command in ALL_COMMANDS if command.name}
+
+
+@click.command("help")
+@click.argument("topic", required=False)
+def help_command(topic: str | None) -> None:
+    """打印命令用法与随包发布的 skill 文档。
+
+    \b
+    tytcli help              命令摘要 + SKILL.md（路由文档）
+    tytcli help <command>    该命令用法 + 对应的子模块文档
+    tytcli help output       输出契约 / 错误码文档
+
+    文档随 wheel 一起发布（tytcli/skill/），与仓库 skills/tytcli/ 同源。
+    """
+    if topic is None:
+        body = skill.read_skill_doc(skill.SKILL_FILENAME)
+        if body is None:
+            raise click.UsageError("随包文档缺失：SKILL.md")
+        click.echo(_root_summary() + _SEPARATOR + skill.strip_frontmatter(body))
+        return
+
+    # 一个主题只要能解析就行：它是已注册命令，**或**它拥有一份参考文档。这两个
+    # 集合并不相同：`output` 有文档却没有命令，而 `env` 这类隐藏命令有用法却刻意
+    # 不带随包文档。接受两者的并集，才能让每一个 `--help` 指针都诚实——指向
+    # `tytcli help X` 的指针绝不能走进死胡同。
+    command = _command_by_name().get(topic)
+    resolved = skill.doc_for_topic(topic)
+    if command is None and resolved is None:
+        raise click.UsageError(
+            f"未知主题 '{topic}'。可用：{', '.join(skill.available_topics())}"
+        )
+
+    parts: list[str] = []
+    if command is not None:
+        parts.append(_help_text(command, topic))
+    if resolved is not None:
+        parts.append(resolved[1])
+    click.echo(_SEPARATOR.join(parts))
+
+
+__all__ = ["help_command"]