tytcli 0.2.0__py3-none-any.whl

tytcli/commands/roadshow.py

@@ -0,0 +1,898 @@
+"""``tytcli roadshow`` — 路演中心：查询、预约、我的预约、AI 纪要.
+
+与公众号、情绪指数两个模块同一个 API 根（``MIDDLE_BASE_URLS`` +
+``/RoadShowCenter/``）；线路层的契约记在 ``client.py`` 的模块 docstring 里，
+下面这些都是**命令层**的决定。
+
+写操作默认只做只读预检
+----------------------
+
+``book`` 与 ``cancel`` 会改变服务端状态，而与另外两个 middle 模块不同，
+**这个模块在 prod 上是部署着的**（prod 调用回答 ``-100``，那就是路由存在的证明）。
+所以一次误调用就会留下一条真实预约。因此这两个命令都先调
+``getRoadShowBookingStatus``，并且只在给了 ``--yes`` 时才 POST。不带 ``--yes``
+时它们只报告"**将会**发生什么"，什么都不碰。
+
+预检同时让这两个操作在 CLI 层面也是幂等的（叠加在服务端自身的幂等之上；已实测：
+重复预约会成功且 ``bookTime`` 不变，重复取消会成功）：
+
+* 已经预约 -> ``already_booked: true``，不发 POST
+* ``canBook`` 为假 -> ``ROADSHOW_NOT_BOOKABLE``（exit 1），带上服务端自己的
+  ``reason``，不发 POST
+* POST 成功之后 -> 再读一次状态并作为 ``confirmed`` 汇报，与 ``auth --verify``
+  用的是同一套"写后回读"纪律
+* POST 超时 -> 再读一次状态，让**它**来决定结果，因为交接文档自己的建议就是
+  "查询本人预约状态，再决定界面结果"。超时不是失败的证据；在预约其实已经存在的
+  情况下报一个失败，正是 agent 最终造成重复预约的方式。
+
+日期处理
+--------
+
+两个列表接口都按日期筛选，但**格式不同、边界语义相反**：列表要 ``yyyy/M/d``，
+且它的 ``endDate`` 截止在该日 00:00:00（所以不含当天的会议）；而我的预约要
+``yyyy-MM-dd``，且它的 ``meetingEndDate`` 含当天全天。
+
+CLI 对两者都接受 ISO 的 ``YYYY-MM-DD`` 并在内部转译，因为让调用方记住两种格式
+正是产生"静默给出错误答案"的方式。转译不是装饰：探测发现传给列表接口的短横线
+日期会被**静默忽略**（筛选根本不生效，返回的是完整结果集），而且观测到的行为在
+负载均衡后面的各个 test 实例之间并不一致。文档规定的斜杠格式在每一次观测中都正确
+生效，所以上网的就是它。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Any, cast
+
+import click
+
+from ..client import ROADSHOW_BOOKING_STATES, ROADSHOW_THEMES, TytClient
+from ..config import ResolvedConfig
+from ..errors import ApiError, NetworkError, UsageError
+from ..output import HINT_KEY, emit_ok
+from .shared import (
+    middle_client,
+    observed_fields,
+    parse_fields_option,
+    raise_for_envelope,
+    require_config,
+    select_fields,
+    trim_page,
+    unwrap_data,
+)
+
+#: 搜索结果行的默认字段：够用来挑出一场会议，并刻意排除那些又大又敏感的字段。
+#: ``summary`` 是列表自带的简略纪要，属于长文本——完整的 AI 纪要有自己的命令。
+#: ``meetingUrl`` / ``meetingPwd`` 是会议链接和它的**密码**，绝不该出现在会被记进
+#: 日志和对话的默认输出里；``--full`` 仍然原样返回它们。``pictureUrl`` 是加密的
+#: 封面地址，命令行渲染不了。
+ROADSHOW_DEFAULT_FIELDS: tuple[str, ...] = (
+    "appId",
+    "title",
+    "roadShowTime",
+    "publishState",
+    "institutions",
+    "speakers",
+    "theme",
+)
+
+#: 预约行的默认字段。``bookingId`` 与 ``theme`` 不在默认集里（取消预约用的是
+#: ``appId``，不是 ``bookingId``），但可以用 ``--fields`` 要回来。
+BOOKINGS_DEFAULT_FIELDS: tuple[str, ...] = (
+    "appId",
+    "title",
+    "roadShowTime",
+    "publishState",
+    "institutions",
+    "speakers",
+    "bookingViewState",
+    "bookTime",
+    "isAvailable",
+    "unavailableReason",
+)
+
+#: AI 纪要的"简略版"视图。``--full`` 返回服务端发来的每一个字段，
+#: 包括 ``detail`` 与十个专题段落。
+SUMMARY_BRIEF_FIELDS: tuple[str, ...] = ("id", "meetingId", "type", "summary")
+
+#: "有这些字段才算有内容可看"。用于决定 ``available``：该接口只返回审核通过的
+#: 非草稿记录，所以"还没生成""待审核""草稿""已删除"四种情况无法区分，
+#: 一个空的 ``detail`` 绝不能被读成"纪要内容是空的"。
+SUMMARY_CONTENT_FIELDS: tuple[str, ...] = (
+    "summary",
+    "detail",
+    "timeline",
+    "companyOverview",
+    "productStrategy",
+    "fundPerformance",
+    "marketOutlook",
+    "riskManagement",
+    "teamDivision",
+    "investHighlights",
+    "mainRisks",
+    "qaPoints",
+)
+
+ISO_DATE_RE = re.compile(r"^(\d{4})-(\d{2})-(\d{2})$")
+DATETIME_RE = re.compile(r"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$")
+
+#: publishState 的编码表，用于在原始值旁边附一个人能读懂的标签。
+PUBLISH_STATES: dict[str, str] = {
+    "0": "未发布",
+    "1": "回放",
+    "2": "预告",
+    "3": "直播中",
+    "4": "已结束（未传回放）",
+    "5": "已结束（已传回放）",
+}
+
+
+# --------------------------------------------------------------------------- #
+# 校验与转译
+# --------------------------------------------------------------------------- #
+
+
+def _validate_page(page: int, page_size: int) -> None:
+    """照搬服务端自己的规则：必须是正整数。
+
+    在客户端就校验，这样失败是 exit 2 的 ``USAGE_*``、且 ``details`` 里带着那个
+    非法值；而不是 exit 1 加一句需要 agent 去模式匹配的中文。服务端的报文是
+    ``页码和每页条数必须为正整数``；它没有规定上界，所以这里也不设上界。
+    """
+    if page < 1:
+        raise UsageError(
+            f"--page 必须 >= 1（当前 {page}）。",
+            code="USAGE_PAGE_OUT_OF_RANGE",
+            details={"page": page, "min": 1},
+        )
+    if page_size < 1:
+        raise UsageError(
+            f"--page-size 必须 >= 1（当前 {page_size}）。",
+            code="USAGE_PAGE_SIZE_OUT_OF_RANGE",
+            details={"page_size": page_size, "min": 1},
+        )
+
+
+def _validate_iso_date(raw: str, option: str) -> str:
+    if not ISO_DATE_RE.match(raw):
+        raise UsageError(
+            f"{option} 必须是 YYYY-MM-DD 格式（当前 {raw!r}）。",
+            code="USAGE_DATE_INVALID",
+            details={"option": option, "value": raw, "expected_format": "YYYY-MM-DD"},
+        )
+    try:
+        datetime.strptime(raw, "%Y-%m-%d")
+    except ValueError as exc:
+        raise UsageError(
+            f"{option} 不是真实存在的日期（当前 {raw!r}）。",
+            code="USAGE_DATE_INVALID",
+            details={"option": option, "value": raw, "reason": str(exc)},
+        ) from exc
+    return raw
+
+
+def _validate_datetime(raw: str, option: str) -> str:
+    if not DATETIME_RE.match(raw):
+        raise UsageError(
+            f"{option} 必须是 'YYYY-MM-DD HH:MM:SS' 格式（当前 {raw!r}）。",
+            code="USAGE_DATETIME_INVALID",
+            details={
+                "option": option,
+                "value": raw,
+                "expected_format": "YYYY-MM-DD HH:MM:SS",
+            },
+        )
+    try:
+        datetime.strptime(raw, "%Y-%m-%d %H:%M:%S")
+    except ValueError as exc:
+        raise UsageError(
+            f"{option} 不是真实存在的日期时间（当前 {raw!r}）。",
+            code="USAGE_DATETIME_INVALID",
+            details={"option": option, "value": raw, "reason": str(exc)},
+        ) from exc
+    return raw
+
+
+def _validate_range(
+    start: str | None,
+    end: str | None,
+    start_option: str,
+    end_option: str,
+) -> None:
+    """在客户端就拒绝反向区间；服务端的报文只是一句话，无法分支。"""
+    if start is not None and end is not None and start > end:
+        raise UsageError(
+            f"{start_option} 不能晚于 {end_option}（{start} > {end}）。",
+            code="USAGE_RANGE_REVERSED",
+            details={
+                "start_option": start_option,
+                "end_option": end_option,
+                "start": start,
+                "end": end,
+            },
+        )
+
+
+def _to_listing_date(iso: str) -> str:
+    """``2026-11-01`` -> ``2026/11/1``，也就是列表接口真正会用来筛选的格式。
+
+    已实测：短横线格式的日期会被 ``getRoadShowInfo`` **静默忽略**（返回未过滤的
+    总数），而且这个行为在负载均衡后面的各个 test 实例之间甚至不一致。斜杠格式
+    在每一次观测中都生效。去掉前导零是为了与文档规定的 ``yyyy/M/d`` 完全一致。
+    """
+    match = ISO_DATE_RE.match(iso)
+    if match is None:  # pragma: no cover - _validate_iso_date 会先跑
+        raise UsageError(
+            f"内部错误：{iso!r} 不是 YYYY-MM-DD。",
+            code="USAGE_DATE_INVALID",
+            details={"value": iso},
+        )
+    year, month, day = match.groups()
+    return f"{year}/{int(month)}/{int(day)}"
+
+
+def _normalize_theme(raw: str) -> str | None:
+    """接受编码或中文行业名；返回编码，"全部"时返回 None。
+
+    ``"0"``、``""`` 与不传，在服务端都表示"不筛选"（按行数实测确认），所以这三种
+    在这里一律收敛成 ``None``，并且**省略该键**而不是发一个空值过去。
+    """
+    value = raw.strip()
+    if not value or value == "0":
+        return None
+    if value in ROADSHOW_THEMES:
+        return value
+    for code, label in ROADSHOW_THEMES.items():
+        if label == value:
+            return code
+    raise UsageError(
+        f"--theme 必须是 {'/'.join(ROADSHOW_THEMES)} 之一，或对应的行业名"
+        f"（{'、'.join(ROADSHOW_THEMES.values())}）；当前 {raw!r}。",
+        code="USAGE_THEME_INVALID",
+        details={"value": raw, "valid": dict(ROADSHOW_THEMES)},
+    )
+
+
+def _validate_app_id(raw: str) -> str:
+    """去掉 argv 带来的空白，然后要求确实还剩下内容。
+
+    值**周围**的空白是 shell 造成的，去掉是安全的。而加密 id 本身含有
+    ``+`` / ``/`` / ``=``，必须逐字节原样传递——格式不对时服务端回
+    ``路演ID格式不正确``，缺失时回 ``请选择路演后重试``。
+    """
+    app_id = raw.strip()
+    if not app_id:
+        raise UsageError(
+            "--app-id 不能为空。它来自 roadshow search / bookings 输出的 appId。",
+            code="USAGE_APP_ID_EMPTY",
+            details={},
+        )
+    return app_id
+
+
+def _validate_state(raw: str) -> str:
+    state = raw.strip()
+    if state not in ROADSHOW_BOOKING_STATES:
+        raise UsageError(
+            f"--state 只能是 {' 或 '.join(ROADSHOW_BOOKING_STATES)}（当前 {raw!r}）。"
+            "不传表示查询全部未取消的预约。",
+            code="USAGE_STATE_INVALID",
+            details={"value": raw, "valid": list(ROADSHOW_BOOKING_STATES)},
+        )
+    return state
+
+
+# --------------------------------------------------------------------------- #
+# shared plumbing
+# --------------------------------------------------------------------------- #
+
+
+def _client(config: ResolvedConfig) -> TytClient:
+    return middle_client(config)
+
+
+def _raise(envelope: Any, config: ResolvedConfig) -> None:
+    raise_for_envelope(
+        envelope, env_name=config.active_env, base_url=config.middle_base_url
+    )
+
+
+def _data_map(envelope: Any) -> dict[str, Any] | None:
+    """把 ``Data`` 当作映射返回；缺失或不是对象时返回 None。
+
+    在这里"缺失"是一种真实情况，不是错误：没有可公开的纪要时，纪要接口会整个
+    省略 ``Data``；预约被取消后，状态接口会省略 ``bookTime``。
+    """
+    raw = unwrap_data(envelope.payload)
+    return cast("dict[str, Any]", raw) if isinstance(raw, dict) else None
+
+
+def _status(client: TytClient, config: ResolvedConfig, app_id: str) -> dict[str, Any]:
+    """读取调用方对某一场路演的预约状态。"""
+    envelope = client.roadshow_booking_status(app_id=app_id)
+    _raise(envelope, config)
+    return _data_map(envelope) or {}
+
+
+def _search_hint(default_fields: Sequence[str], observed: list[str]) -> str:
+    extra = [field for field in observed if field not in default_fields]
+    parts = [f"默认每场路演仅输出：{', '.join(default_fields)}。"]
+    if extra:
+        parts.append(f"该接口本次还返回了：{', '.join(extra)}。")
+    parts.append(
+        "用 --fields a,b,c 自选字段，或 --full 取服务端原样全量"
+        "（含 summary 简略纪要与 meetingUrl/meetingPwd 会议链接及密码）。"
+    )
+    parts.append("appId 可直接用于：tytcli roadshow status|summary|book --app-id <ID>。")
+    return "".join(parts)
+
+
+def _bookings_hint(default_fields: Sequence[str], observed: list[str]) -> str:
+    extra = [field for field in observed if field not in default_fields]
+    parts = [f"默认每条预约仅输出：{', '.join(default_fields)}。"]
+    if extra:
+        parts.append(f"该接口本次还返回了：{', '.join(extra)}。")
+    parts.append("用 --fields a,b,c 自选字段，或 --full 取服务端原样全量。")
+    parts.append("取消预约用 appId（不是 bookingId）：tytcli roadshow cancel --app-id <ID> --yes。")
+    return "".join(parts)
+
+
+# --------------------------------------------------------------------------- #
+# 命令组
+# --------------------------------------------------------------------------- #
+
+
+@click.group()
+def roadshow() -> None:
+    """路演中心：查询、预约、我的预约与 AI 纪要。"""
+
+
+def _fields_options(func: Any) -> Any:
+    """``--fields`` / ``--full`` 这一对选项，三个需要裁剪的命令共用。"""
+    func = click.option(
+        "--full",
+        is_flag=True,
+        help="输出服务端原样全量字段（与 --fields 互斥）。",
+    )(func)
+    return click.option(
+        "--fields",
+        "fields_option",
+        metavar="A,B,C",
+        help="只输出这些字段，逗号分隔（与 --full 互斥）。",
+    )(func)
+
+
+def _resolve_fields(fields_option: str | None, full: bool) -> list[str] | None:
+    if full and fields_option is not None:
+        raise UsageError(
+            "--full 与 --fields 互斥：前者要全量，后者要自选。",
+            code="USAGE_FIELDS_CONFLICT",
+        )
+    return parse_fields_option(fields_option) if fields_option is not None else None
+
+
+@roadshow.command("search")
+@click.option("--title", help="标题模糊查询。")
+@click.option("--institution", help="机构模糊查询。")
+@click.option("--speaker", help="主讲人模糊查询（多位主讲人任一匹配）。")
+@click.option(
+    "--theme",
+    metavar="CODE|NAME",
+    help="行业筛选：1权益 2固收+ 3纯债 4互认 5策略 6热点；可用编码或行业名，不传为全部。",
+)
+@click.option("--start", "start_date", metavar="YYYY-MM-DD", help="会议开始日期下限。")
+@click.option(
+    "--end",
+    "end_date",
+    metavar="YYYY-MM-DD",
+    help="会议开始日期上限。注意：服务端截止该日 00:00:00，**不含**当天白天的会议。",
+)
+@click.option("--page", "page_num", type=int, default=1, show_default=True, help="页码，从 1 开始。")
+@click.option(
+    "--page-size", "page_size", type=int, default=20, show_default=True, help="每页条数。"
+)
+@_fields_options
+@click.pass_context
+def roadshow_search(
+    ctx: click.Context,
+    title: str | None,
+    institution: str | None,
+    speaker: str | None,
+    theme: str | None,
+    start_date: str | None,
+    end_date: str | None,
+    page_num: int,
+    page_size: int,
+    fields_option: str | None,
+    full: bool,
+) -> None:
+    """按时间、行业、机构、主讲人多条件查询路演。
+
+    \b
+    默认输出是精简索引（appId/title/roadShowTime/publishState/institutions/
+    speakers/theme），并在 __tytcli_hint__ 里说明还能取到哪些字段。
+
+    \b
+    列表**不含**预约状态：服务端没有批量查询预约资格的接口。
+    要看某一场能否预约，用 appId 调：
+      tytcli roadshow status --app-id <ID>
+    """
+    selected = _resolve_fields(fields_option, full)
+    _validate_page(page_num, page_size)
+    theme_code = _normalize_theme(theme) if theme is not None else None
+    if start_date is not None:
+        _validate_iso_date(start_date, "--start")
+    if end_date is not None:
+        _validate_iso_date(end_date, "--end")
+    _validate_range(start_date, end_date, "--start", "--end")
+
+    config = require_config()
+    client = _client(config)
+    envelope = client.roadshow_search(
+        page_num=page_num,
+        page_size=page_size,
+        title=title,
+        institution=institution,
+        speaker=speaker,
+        theme=theme_code,
+        start_date=_to_listing_date(start_date) if start_date else None,
+        end_date=_to_listing_date(end_date) if end_date else None,
+    )
+    _raise(envelope, config)
+
+    inner_raw = unwrap_data(envelope.payload)
+    meta: dict[str, Any] = {
+        "env": config.active_env,
+        "base_url": config.middle_base_url,
+        "api_root": "middleApi",
+        "http_status": envelope.http_status,
+        "page": page_num,
+        "page_size": page_size,
+    }
+    # 回显实际生效的筛选条件，包括转译后的日期格式：一个被服务端**静默忽略**
+    # 的日期筛选，与一个"筛选生效但没有匹配"的结果，在输出上本来无法区分。
+    applied: dict[str, Any] = {}
+    if title is not None:
+        applied["title"] = title
+    if institution is not None:
+        applied["institution"] = institution
+    if speaker is not None:
+        applied["speaker"] = speaker
+    if theme_code is not None:
+        applied["theme"] = theme_code
+    if start_date is not None:
+        applied["start"] = start_date
+        applied["start_sent_as"] = _to_listing_date(start_date)
+    if end_date is not None:
+        applied["end"] = end_date
+        applied["end_sent_as"] = _to_listing_date(end_date)
+        applied["end_includes_that_day"] = False
+    if applied:
+        meta["filters"] = applied
+
+    page = trim_page(
+        inner_raw=inner_raw,
+        list_key="infos",
+        default_fields=ROADSHOW_DEFAULT_FIELDS,
+        selected=selected,
+        full=full,
+        make_hint=_search_hint,
+    )
+    extra: dict[str, Any] = {}
+    if page.hint is not None:
+        extra[HINT_KEY] = page.hint
+    emit_ok(page.payload, pretty=ctx.obj["pretty"], **meta, **page.meta, **extra)
+
+
+@roadshow.command("bookings")
+@click.option(
+    "--state",
+    metavar="BOOKED|ENDED",
+    help="BOOKED 已预约（含预告与直播中）/ ENDED 已结束；不传为全部未取消的预约。",
+)
+@click.option("--meeting-start", metavar="YYYY-MM-DD", help="会议开始日期下限。")
+@click.option(
+    "--meeting-end",
+    metavar="YYYY-MM-DD",
+    help="会议开始日期上限，**含**当天全天（与 search 的 --end 语义相反）。",
+)
+@click.option("--book-start", metavar="YYYY-MM-DD HH:MM:SS", help="预约时间下限。")
+@click.option("--book-end", metavar="YYYY-MM-DD HH:MM:SS", help="预约时间上限，含上限。")
+@click.option("--page", "page_num", type=int, default=1, show_default=True, help="页码，从 1 开始。")
+@click.option(
+    "--page-size", "page_size", type=int, default=20, show_default=True, help="每页条数。"
+)
+@_fields_options
+@click.pass_context
+def roadshow_bookings(
+    ctx: click.Context,
+    state: str | None,
+    meeting_start: str | None,
+    meeting_end: str | None,
+    book_start: str | None,
+    book_end: str | None,
+    page_num: int,
+    page_size: int,
+    fields_option: str | None,
+    full: bool,
+) -> None:
+    """查询我的路演预约（不含已取消的）。
+
+    \b
+    默认按预约时间倒序。BOOKED 表示预告与直播中，**不代表此时一定能取消**；
+    取消资格要按场次查：tytcli roadshow status --app-id <ID>
+
+    \b
+    已下架会议的预约可能保留在结果里，此时 isAvailable 为 false、
+    unavailableReason 说明原因，标题与时间等字段可能整体省略。
+    """
+    selected = _resolve_fields(fields_option, full)
+    _validate_page(page_num, page_size)
+    state_value = _validate_state(state) if state is not None else None
+    for option, value in (("--meeting-start", meeting_start), ("--meeting-end", meeting_end)):
+        if value is not None:
+            _validate_iso_date(value, option)
+    for option, value in (("--book-start", book_start), ("--book-end", book_end)):
+        if value is not None:
+            _validate_datetime(value, option)
+    _validate_range(meeting_start, meeting_end, "--meeting-start", "--meeting-end")
+    _validate_range(book_start, book_end, "--book-start", "--book-end")
+
+    config = require_config()
+    client = _client(config)
+    envelope = client.roadshow_my_bookings(
+        page_num=page_num,
+        page_size=page_size,
+        booking_view_state=state_value,
+        meeting_start_date=meeting_start,
+        meeting_end_date=meeting_end,
+        book_start_time=book_start,
+        book_end_time=book_end,
+    )
+    _raise(envelope, config)
+
+    inner_raw = unwrap_data(envelope.payload)
+    meta: dict[str, Any] = {
+        "env": config.active_env,
+        "base_url": config.middle_base_url,
+        "api_root": "middleApi",
+        "http_status": envelope.http_status,
+        "page": page_num,
+        "page_size": page_size,
+    }
+    if state_value is not None:
+        meta["state"] = state_value
+
+    page = trim_page(
+        inner_raw=inner_raw,
+        list_key="infos",
+        default_fields=BOOKINGS_DEFAULT_FIELDS,
+        selected=selected,
+        full=full,
+        make_hint=_bookings_hint,
+    )
+    payload = page.payload
+    # 空页返回的 pageNum 是 0。把那个 0 当作下一页页码回传会被服务端拒绝，
+    # 所以这里改回报调用方自己请求的页码。
+    if isinstance(payload, dict):
+        mapping = cast("dict[str, Any]", payload)
+        if mapping.get("pageNum") == 0:
+            payload = {**mapping, "pageNum": page_num}
+            meta["empty_page_num_corrected"] = True
+    extra: dict[str, Any] = {}
+    if page.hint is not None:
+        extra[HINT_KEY] = page.hint
+    emit_ok(payload, pretty=ctx.obj["pretty"], **meta, **page.meta, **extra)
+
+
+@roadshow.command("status")
+@click.option("--app-id", required=True, metavar="ID", help="路演的 appId（来自 search 或 bookings）。")
+@click.pass_context
+def roadshow_status(ctx: click.Context, app_id: str) -> None:
+    """查询本人对某一场路演的预约状态与操作资格。
+
+    \b
+    输出 isBooked / canBook / canCancel / reason，已预约时还有 bookTime。
+    reason 是服务端给出的中文原因，**不要**用它的文字做分支判断（同一种拒绝在
+    预约与取消两条路径上的标点都不一样）；按 canBook / canCancel 判断。
+
+    \b
+    会议存在但当前不可操作时本命令仍然成功（ok:true），原因在 reason 里；
+    会议不存在、已下架或 appId 不正确时才是失败。
+    """
+    target = _validate_app_id(app_id)
+    config = require_config()
+    client = _client(config)
+    envelope = client.roadshow_booking_status(app_id=target)
+    _raise(envelope, config)
+    data = _data_map(envelope) or {}
+    emit_ok(
+        data,
+        pretty=ctx.obj["pretty"],
+        env=config.active_env,
+        base_url=config.middle_base_url,
+        api_root="middleApi",
+        http_status=envelope.http_status,
+        app_id=target,
+    )
+
+
+@roadshow.command("summary")
+@click.option("--app-id", required=True, metavar="ID", help="路演的 appId（来自 search）。")
+@_fields_options
+@click.pass_context
+def roadshow_summary(
+    ctx: click.Context, app_id: str, fields_option: str | None, full: bool
+) -> None:
+    """获取某一场路演的公开 AI 纪要。
+
+    \b
+    默认输出简略版（id/meetingId/type/summary）；--full 输出详细版全部字段，
+    含 detail 正文与 companyOverview / productStrategy / fundPerformance /
+    marketOutlook / riskManagement / teamDivision / investHighlights /
+    mainRisks / qaPoints / timeline 等专题段落。
+
+    \b
+    无需预约即可查询。**尚无公开纪要时 available 为 false**：该接口只返回审核
+    通过的非草稿记录，所以"还没生成""待审核""草稿""已删除"四种情况在响应里
+    无法区分——available:false 只表示"现在没有可读的公开纪要"，不表示失败，
+    也不表示纪要不存在过。
+    """
+    selected = _resolve_fields(fields_option, full)
+    target = _validate_app_id(app_id)
+
+    config = require_config()
+    client = _client(config)
+    envelope = client.roadshow_summary(app_id=target)
+    _raise(envelope, config)
+
+    data = _data_map(envelope)
+    content_present = bool(data) and any(
+        str(data.get(field) or "").strip() for field in SUMMARY_CONTENT_FIELDS
+    )
+    available = data is not None and content_present
+
+    meta: dict[str, Any] = {
+        "env": config.active_env,
+        "base_url": config.middle_base_url,
+        "api_root": "middleApi",
+        "http_status": envelope.http_status,
+        "app_id": target,
+        "available": available,
+    }
+
+    if not available:
+        # 说清楚为什么没有内容可显示，并说清楚**原因无法进一步缩小**——
+        # 一个把 available:false 读成"纪要内容为空"的 agent，会把它当成事实
+        # 汇报给用户。
+        meta["unavailable_note"] = (
+            "没有可读的公开 AI 纪要。该接口只返回审核通过的非草稿记录，因此"
+            "“尚未生成”“待审核”“草稿”“已删除”在响应中无法区分。"
+        )
+        emit_ok(None, pretty=ctx.obj["pretty"], **meta)
+        return
+
+    assert data is not None  # available implies data
+    observed = observed_fields([data])
+    keys: list[str] = (
+        list(selected) if selected is not None
+        else (observed if full else list(SUMMARY_BRIEF_FIELDS))
+    )
+    meta["trimmed"] = not full
+    meta["record_fields"] = keys if not full else observed
+    unknown = [key for key in keys if key not in observed]
+    if unknown:
+        meta["unknown_fields"] = unknown
+        meta["available_fields"] = observed
+    extra: dict[str, Any] = {}
+    if selected is None and not full:
+        extra_fields = [field for field in observed if field not in SUMMARY_BRIEF_FIELDS]
+        parts = [f"默认仅输出简略版：{', '.join(SUMMARY_BRIEF_FIELDS)}。"]
+        if extra_fields:
+            parts.append(f"该纪要本次还返回了：{', '.join(extra_fields)}。")
+        parts.append("用 --full 取详细版（含 detail 正文与全部专题段落）。")
+        extra[HINT_KEY] = "".join(parts)
+    emit_ok(select_fields(data, keys), pretty=ctx.obj["pretty"], **meta, **extra)
+
+
+# --------------------------------------------------------------------------- #
+# writes
+# --------------------------------------------------------------------------- #
+
+
+def _write_flow(
+    ctx: click.Context,
+    *,
+    app_id: str,
+    yes: bool,
+    action: str,
+) -> None:
+    """``book`` 与 ``cancel`` 共用的 预检 / 写入 / 回读 流程。
+
+    ``action`` 取 ``"book"`` 或 ``"cancel"``。两个写命令合用一个函数是刻意的：
+    顺序保证（绝不在无预检的情况下写入、写入后必定回读、超时必定对账）正是这套
+    设计的全部意义，而两份实现必然漂移。
+    """
+    target = _validate_app_id(app_id)
+    config = require_config()
+    client = _client(config)
+
+    meta: dict[str, Any] = {
+        "env": config.active_env,
+        "base_url": config.middle_base_url,
+        "api_root": "middleApi",
+        "app_id": target,
+        "action": action,
+    }
+
+    before = _status(client, config, target)
+    is_booked = bool(before.get("isBooked"))
+    can_book = bool(before.get("canBook"))
+    can_cancel = bool(before.get("canCancel"))
+    reason = str(before.get("reason") or "")
+    meta["http_status"] = None  # filled in per call below
+
+    if action == "book":
+        allowed, already = can_book, is_booked
+        already_key, not_allowed_code, verb = (
+            "already_booked", "ROADSHOW_NOT_BOOKABLE", "预约"
+        )
+    else:
+        # 取消一个本来就没预约的会议是"空操作成功"，不是错误：服务端也接受
+        # （已实测），而拒绝它会让"超时后重试"这条路走不通。
+        allowed, already = can_cancel, not is_booked
+        already_key, not_allowed_code, verb = (
+            "already_cancelled", "ROADSHOW_NOT_CANCELLABLE", "取消预约"
+        )
+
+    if not yes:
+        emit_ok(
+            {
+                "would_write": bool(allowed and not already),
+                "preflight": before,
+                "next_step": (
+                    f"确认无误后加 --yes 执行{verb}"
+                    if allowed and not already
+                    else f"当前不可{verb}：{reason or '服务端未给出原因'}"
+                ),
+            },
+            pretty=ctx.obj["pretty"],
+            written=False,
+            dry_run=True,
+            **meta,
+        )
+        return
+
+    if already:
+        emit_ok(
+            {
+                "status": before,
+                "note": f"已处于目标状态，未发起写入（服务端本身对重复{verb}也是幂等的）。",
+            },
+            pretty=ctx.obj["pretty"],
+            written=False,
+            **{already_key: True},
+            **meta,
+        )
+        return
+
+    if not allowed:
+        raise ApiError(
+            f"当前不可{verb}：{reason or '服务端未给出原因'}",
+            code=not_allowed_code,
+            details={**meta, "reason": reason, "preflight": before},
+        )
+
+    call = client.roadshow_book if action == "book" else client.roadshow_cancel_booking
+    try:
+        envelope = call(app_id=target)
+    except NetworkError as exc:
+        # 超时**不是**失败的证据。把真相回读出来再汇报，这样 agent 就不会
+        # 去重试，从而造成重复预约。
+        try:
+            after = _status(client, config, target)
+        except Exception:
+            # 重新抛出传输错误，而不是回读失败：调用方需要知道的是
+            # "这次写入结果未知"。
+            raise exc from None
+        succeeded = bool(after.get("isBooked")) if action == "book" else not after.get("isBooked")
+        if succeeded:
+            emit_ok(
+                {
+                    "status": after,
+                    "note": "写入请求超时，但回读确认操作已生效。",
+                },
+                pretty=ctx.obj["pretty"],
+                written=True,
+                recovered_after_timeout=True,
+                **meta,
+            )
+            return
+        exc.details = {
+            **(exc.details or {}),
+            **meta,
+            "reconciled_status": after,
+            "hint": "写入结果未知且回读显示未生效，可安全重试。",
+        }
+        raise
+
+    try:
+        _raise(envelope, config)
+    except ApiError as exc:
+        # 被拒绝的**写入**不等于请求格式有问题。服务端的 ErrorCode -1 既表示
+        # "地址或方法不对"，也表示"这场路演已经结束"，只有中文报文能区分二者——
+        # 这正是共享的信封映射无法区分它们的原因。而这一层知道自己刚调的是哪个
+        # 接口，所以可以诚实地命名这个失败，而不是告诉调用方"你的请求有问题"。
+        raise ApiError(
+            exc.message,
+            code="ROADSHOW_WRITE_REJECTED",
+            details={
+                **meta,
+                "reason": exc.message,
+                "server_error_code": envelope.error_code,
+                "mapped_from": exc.code,
+                "http_status": envelope.http_status,
+            },
+        ) from exc
+    meta["http_status"] = envelope.http_status
+    after = _status(client, config, target)
+    emit_ok(
+        {
+            "result": unwrap_data(envelope.payload),
+            "confirmed": after,
+        },
+        pretty=ctx.obj["pretty"],
+        written=True,
+        http_status=envelope.http_status,
+        **{k: v for k, v in meta.items() if k != "http_status"},
+    )
+
+
+@roadshow.command("book")
+@click.option("--app-id", required=True, metavar="ID", help="路演的 appId（来自 search）。")
+@click.option(
+    "--yes",
+    is_flag=True,
+    help="真正执行预约。不带此参数时只做只读预检，不发起写入。",
+)
+@click.pass_context
+def roadshow_book(ctx: click.Context, app_id: str, yes: bool) -> None:
+    """预约一场路演（写操作）。
+
+    \b
+    **默认不写入**：不带 --yes 时只查询本人预约资格并报告将会发生什么。
+    带上 --yes 才会真正预约，且预约成功后回读状态确认。
+
+    \b
+    只有公开可预约的预告场次能预约；开始时间不明、直播中、已结束、回放或已下架
+    都会被拒绝。距离开始 15 分钟以内也不能预约。重复预约是幂等的：服务端返回
+    成功且预约时间不变，本命令则会直接跳过写入。
+    """
+    _write_flow(ctx, app_id=app_id, yes=yes, action="book")
+
+
+@roadshow.command("cancel")
+@click.option("--app-id", required=True, metavar="ID", help="路演的 appId（来自 search 或 bookings）。")
+@click.option(
+    "--yes",
+    is_flag=True,
+    help="真正执行取消。不带此参数时只做只读预检，不发起写入。",
+)
+@click.pass_context
+def roadshow_cancel(ctx: click.Context, app_id: str, yes: bool) -> None:
+    """取消本人对一场路演的预约（写操作）。
+
+    \b
+    **默认不写入**：不带 --yes 时只查询本人预约资格并报告将会发生什么。
+    带上 --yes 才会真正取消，且取消成功后回读状态确认。
+
+    \b
+    只有可见的预告场次、且距离开始大于 15 分钟时才能取消。取消后不再出现在
+    bookings 里，也不再订阅后续的纪要提醒。取消用 appId，不是 bookingId。
+    """
+    _write_flow(ctx, app_id=app_id, yes=yes, action="cancel")
+
+
+__all__ = ["roadshow"]