contract-archive-cli 0.2.7__py3-none-any.whl

contract_archive/cli_common.py

@@ -0,0 +1,293 @@
+"""
+CLI 基础设施（被各命令模块共享的叶子模块，不依赖任何 cli_* 命令模块）。
+
+放这里的都是"框架级"共享件，与具体命令无关：
+  - app          主 Typer 实例 + 全局 callback（命令在别处用 @app.command 挂上来）
+  - 参数 Enum    parse-time 校验，坏值由 typer 报 exit 2，不漏到数据层
+  - 双 console   数据走 stdout（可管道）/ 诊断走 stderr
+  - _resolve_*   档案库路径解析、ident 消歧、空库守卫（多个命令共用）
+
+依赖方向（保持 DAG，禁止反向）：cli_common ← cli_query / cli（写命令）。
+"""
+from __future__ import annotations
+
+import json as _json
+import logging
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+
+from . import __version__
+from .archive import (
+    ArchivePaths,
+    default_archive_root,
+    find_by_sha_prefix,
+    get_document,
+)
+from .config import load_settings
+
+# ---------- 参数枚举（parse-time 校验：坏值由 typer 报 exit 2，不再漏到数据层 ValueError）----------
+
+
+class OutputFormat(str, Enum):
+    """--format：人类表格 or 机器 JSON。"""
+
+    table = "table"
+    json = "json"
+
+
+class ColorWhen(str, Enum):
+    """--color：auto=仅 TTY 上色（管道纯文本）；always=强制（配 less -R）；never=禁用。"""
+
+    auto = "auto"
+    always = "always"
+    never = "never"
+
+
+class ProgressFormat(str, Enum):
+    """--progress：none=现状（汇总在末尾）；ndjson=逐文件向 stdout 吐事件流，供 agent 流式消费。"""
+
+    none = "none"
+    ndjson = "ndjson"
+
+
+class OrderBy(str, Enum):
+    """list --order-by。成员必须与 repository.list_documents 的 allowed_order 白名单一致。"""
+
+    ingested_at = "ingested_at"
+    primary_date = "primary_date"
+    primary_amount_cents = "primary_amount_cents"
+    sign_date = "sign_date"
+    expire_date = "expire_date"
+    amount_cents = "amount_cents"
+
+
+class DocStatus(str, Enum):
+    """--status：入库状态。"""
+
+    ok = "ok"
+    partial = "partial"
+    failed = "failed"
+
+
+class DocType(str, Enum):
+    """list --type：文档类型。值即 CLI choice，与抽取信封的类型枚举一致。"""
+
+    contract = "合同协议"
+    insurance = "保险凭证"
+    travel = "旅行资料"
+    proof = "证明"
+    invoice = "发票票据"
+    report = "报告"
+    certificate = "证件"
+    other = "其他"
+
+
+class Actor(str, Enum):
+    """--actor：义务主体。成员必须与 repository 的 party_a/party_b/both 校验一致。"""
+
+    party_a = "party_a"
+    party_b = "party_b"
+    both = "both"
+
+
+# ---------- 双 console：数据走 stdout（可管道），诊断/进度/错误走 stderr ----------
+
+console = Console()                    # 主数据：表格 + JSON
+err_console = Console(stderr=True)      # 人类消息：状态/进度/错误/确认
+
+
+def color_disabled() -> bool:
+    """
+    全局是否应禁用颜色：--no-color flag（落到 console.no_color）或 NO_COLOR 环境变量。
+
+    rich console 自身已尊重 NO_COLOR + 被 callback 的 --no-color 置过 no_color；但 raw 命令的
+    高亮不经 console（直写 ANSI 转义码），故需显式查这个开关。NO_COLOR 规范：非空即禁用
+    （空串不算），故 bool(os.environ.get("NO_COLOR")) 恰好对（空串 falsy）。
+    """
+    return bool(console.no_color) or bool(os.environ.get("NO_COLOR"))
+
+
+def _version_cb(value: bool) -> None:
+    """--version 的 eager 回调：版本号打到 stdout（机器可消费），随即退出。"""
+    if value:
+        print(f"contract-archive {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    help="本地文档档案库 CLI（合同/证明/发票等，OCR + qwen3.7-max）",
+    # clig.dev：无参数应展示帮助，而非报 "Missing command" 错误框。
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    # 关掉 typer 自带的 rich traceback 接管：未预期异常改由 cli.main_entry 的顶层钩子翻成
+    # 人话（默认一行错误 + 提示 -v 展开），别直接 dump 一坨实现细节给用户/agent。
+    pretty_exceptions_enable=False,
+    # show_locals=False 留作防御纵深：万一将来 enable 翻开，也不把局部变量（可能含 secret）dump 出。
+    pretty_exceptions_show_locals=False,
+    epilog=(
+        "示例：\n"
+        "  contract-archive ingest ./input            # 扫描目录入库\n"
+        "  contract-archive list --format json | jq   # 机器可读，管道友好\n"
+        "  contract-archive todo --within-days 30      # 近 30 天待办义务\n"
+        "\n文档：https://github.com/crhan/contract-archive-cli"
+    ),
+)
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        is_eager=True,
+        callback=_version_cb,
+        help="打印版本并退出",
+    ),
+    no_color: bool = typer.Option(
+        False, "--no-color", help="禁用彩色输出（管道/日志归档时用）"
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="DEBUG 级日志（更啰嗦，排查用）"
+    ),
+    quiet: bool = typer.Option(
+        False, "--quiet", "-q", help="仅 WARNING 及以上（更安静）"
+    ),
+) -> None:
+    """
+    全局选项在所有子命令前生效。flag 优先级高于环境变量：
+      --no-color 覆盖 NO_COLOR/TTY 自动探测；--verbose/--quiet 覆盖 LOG_LEVEL。
+    """
+    # dotenv 放到这里加载——保证 flag 解析后再读 env，且 CONTRACT_ARCHIVE_DIR 等及时可用。
+    # override=False 显式声明：shell 已 export 的变量压过 .env（即 env > 项目 .env），
+    # 与 config 层 env>file>default 的优先级语义一致。
+    load_dotenv(override=False)
+
+    if no_color:
+        console.no_color = True
+        err_console.no_color = True
+
+    # 日志默认 stderr；--verbose/--quiet 胜过 LOG_LEVEL env。
+    if verbose:
+        level: str | int = "DEBUG"
+    elif quiet:
+        level = "WARNING"
+    else:
+        level = _resolve_log_level(os.getenv("LOG_LEVEL", "INFO"))
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+
+_VALID_LOG_LEVELS = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+
+
+def _resolve_log_level(raw: str) -> str | int:
+    """
+    LOG_LEVEL 白名单归一：合法名（大小写不敏感）原样、纯数字转 int，其余降级 INFO 并 warning。
+
+    此前把原始字符串直喂 logging.basicConfig，`LOG_LEVEL=bogus` 会抛 ValueError 把所有命令打挂
+    （连只读的 list/show 都崩）。坏 env 不该让命令崩——与 config 层「坏配置不崩、warning 后降级」
+    一个取向，消除「文件配置坏了优雅、env 坏了硬崩」这个特殊情况。
+    """
+    norm = (raw or "").strip().upper()
+    if norm in _VALID_LOG_LEVELS:
+        return norm
+    if norm.isdigit():
+        return int(norm)
+    err_console.print(f"[yellow]无效 LOG_LEVEL={raw!r}，降级为 INFO[/yellow]")
+    return "INFO"
+
+
+# ---------- 全局 archive 路径解析 ----------
+
+
+def _resolve_archive(archive_opt: Optional[Path]) -> ArchivePaths:
+    """
+    --archive flag > CONTRACT_ARCHIVE_DIR env > config archive.dir > XDG 默认。
+
+    env 与 config 的合并交给 load_settings()（其 archive_dir 已是 env>config 短路结果，
+    env 严格优先、空串当未设），这里只在 flag 之后接住它，再回退 XDG 默认。
+    统一 expanduser：修掉历史上 CONTRACT_ARCHIVE_DIR=~/x 不展开 ~ 的坑。
+    """
+    if archive_opt:
+        root = archive_opt
+    else:
+        configured = load_settings().archive_dir
+        root = Path(configured) if configured else default_archive_root()
+    return ArchivePaths(root=root.expanduser().resolve())
+
+
+_archive_opt = typer.Option(
+    None,
+    "--archive",
+    "-a",
+    help="档案库根目录；不传则用 CONTRACT_ARCHIVE_DIR 或 XDG 默认 ~/.local/share/contract-archive",
+)
+
+
+def _archive_empty(paths: ArchivePaths, fmt: OutputFormat) -> bool:
+    """
+    读命令统一空库守卫。返回 True 表示库不存在、调用方应直接 return。
+      - json 模式：往 stdout 打 `[]`，保证管道消费者（jq）拿到合法 JSON
+      - table 模式：往 stderr 打人类提示，不污染 stdout
+    """
+    if paths.db_path.exists():
+        return False
+    if fmt is OutputFormat.json:
+        print("[]")
+    else:
+        err_console.print(f"[yellow]archive empty: {paths.db_path} not found[/yellow]")
+    return True
+
+
+def not_found_json(ident: str) -> None:
+    """
+    show/extract 的 json 模式未命中时吐合法 JSON 错误信封到 stdout（调用方随后 Exit(1)）。
+
+    与空集合命令吐 `[]`、stats 吐零值对象同一套 JSON 契约：json 模式永不让 stdout 为空，
+    保证 `| jq` / json.loads 拿到可解析对象。退出码仍非零，让 shell 也能判失败。
+    """
+    print(_json.dumps({"error": "not_found", "ident": ident}, ensure_ascii=False))
+
+
+def _resolve_ident(conn, ident: str):
+    """
+    show/extract/delete 共用：ident 可能是 id 或 sha 前缀。
+    消歧规则：
+      - 全数字且 <= 18 位 → 先按 id 查；查不到再按 sha 前缀
+      - 含非数字字符 → 按 sha 前缀（必须 >=4 字符）
+      - sha 前缀多匹配 → 报错列候选
+    """
+    if ident.isdigit() and len(ident) <= 18:
+        try:
+            doc_id = int(ident)
+            row = get_document(conn, doc_id)
+            if row:
+                return row
+        except ValueError:
+            pass
+        # 数字也可能是 sha 前缀（罕见但合法），fallthrough
+    if len(ident) < 4:
+        err_console.print(
+            f"[red]ident {ident!r} 不是有效 id；如要按 sha 前缀查询请提供 ≥4 字符[/red]"
+        )
+        return None
+    matches = find_by_sha_prefix(conn, ident.lower())
+    if not matches:
+        return None
+    if len(matches) > 1:
+        err_console.print(f"[red]sha prefix {ident!r} 命中 {len(matches)} 条，请提供更长前缀：[/red]")
+        for m in matches[:10]:
+            err_console.print(
+                f"  id={m.id} sha={m.short_sha} name={m.contract_name or '-'}"
+            )
+        return None
+    return matches[0]

contract_archive/cli_config.py

@@ -0,0 +1,96 @@
+"""
+`config` 子命令：查看 / 设置 / 删除全局配置。
+
+独立文件——cli.py 已逼近 1000 行红线，config 命令组不能再往里塞。
+只做 show / set / unset 三个核心命令（砍掉 meeting-asr 的 keys/path/import-env/--json：
+单用户本地工具用不上，path 并进 show 抬头即可）。
+"""
+from __future__ import annotations
+
+import json as _json
+
+import typer
+from rich.table import Table
+
+# 复用 cli_common 的全局 console（别各建实例）：全局 --no-color 在 callback 里只改 cli_common
+# 那对实例，子组自建 Console 会让 --no-color 对 config 命令全失效。cli_common 是叶子模块，
+# import 它不成环（cli_query 已用同款）。
+from .cli_common import OutputFormat, console, err_console
+from .config import (
+    config_path,
+    describe_items,
+    find_key,
+    set_value,
+    unset_value,
+    visible_items,
+)
+
+# pretty_exceptions_show_locals=False：防 traceback 把 api_key 等局部变量 dump 到终端。
+config_app = typer.Typer(
+    help="查看/设置全局配置（XDG ~/.config/contract-archive/config.json）",
+    pretty_exceptions_show_locals=False,
+    no_args_is_help=True,  # clig.dev：裸 `config` 列出 show/set/unset，而非报 Missing command
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+@config_app.command("show")
+def show(
+    reveal: bool = typer.Option(False, "--reveal", help="显示 secret 明文（默认掩码）"),
+    fmt: OutputFormat = typer.Option(
+        OutputFormat.table, "--format", help="table | json（json 含 key/env/secret/default/value/source）"
+    ),
+) -> None:
+    """列出各配置项当前生效值（优先级：环境变量 > 配置文件 > 默认）。"""
+    if fmt is OutputFormat.json:
+        # 机器发现：让 agent 程序化拿到「支持哪些配置键、对应哪个 env、是否 secret、当前值与来源」。
+        print(_json.dumps(describe_items(reveal=reveal), ensure_ascii=False, indent=2))
+        return
+    cfg = config_path()
+    table = Table(
+        title=f"Config · {cfg}",
+        caption="值来源优先级：环境变量(含 .env) > 配置文件 > 默认值",
+        caption_justify="left",
+    )
+    table.add_column("key", style="cyan")
+    table.add_column("value", overflow="fold")
+    for name, shown in visible_items(reveal=reveal):
+        table.add_row(name, shown)
+    console.print(table)
+    if not cfg.exists():
+        err_console.print(
+            "[dim]配置文件尚不存在；`config set` 后自动创建。当前值来自环境变量/默认。[/dim]"
+        )
+
+
+@config_app.command("set")
+def set_cmd(
+    key: str = typer.Argument(..., help="配置键，如 dashscope.api_key"),
+    value: str = typer.Argument(..., help="配置值"),
+) -> None:
+    """设置一个配置项，写入 ~/.config/contract-archive/config.json（文件权限 0600）。"""
+    try:
+        cfg = set_value(key, value)
+    except ValueError as e:
+        err_console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+    k = find_key(key)
+    # 状态变更确认是「消息」，走 stderr（与 delete/vacuum 的 ✓ 一致）；stdout 留给数据。
+    err_console.print(f"[green]已设置[/green] {k.name} → {cfg}")
+    if k.secret:
+        err_console.print(
+            "[yellow]注意：该文件明文存储 secret，已设为仅本人可读(0600)；请勿提交或分享。[/yellow]"
+        )
+
+
+@config_app.command("unset")
+def unset_cmd(
+    key: str = typer.Argument(..., help="配置键，如 dashscope.api_key"),
+) -> None:
+    """从配置文件删除一个配置项（不影响环境变量/默认值）。"""
+    try:
+        cfg = unset_value(key)
+    except ValueError as e:
+        err_console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+    err_console.print(f"[green]已删除[/green] {key.strip()} ← {cfg}")

contract_archive/cli_introspect.py

@@ -0,0 +1,204 @@
+"""
+introspection 命令：让机器（Agent / MCP wrapper）发现能力与结构，无需读源码或解析 --help。
+
+- capabilities      列所有命令 + 副作用/破坏性/幂等元数据（自动遍历 typer app + 安全表）
+- describe <cmd>    单命令的参数 schema（名称/类型/必填/默认/可选值/帮助）
+- schema <type>     核心数据结构的 JSON Schema（pydantic 直出）
+
+输出一律 JSON 到 stdout，可 `| jq` 消费。为什么手工维护安全元数据：
+side_effects / destructive 无法从函数签名推断，必须人为声明——这恰是 Agent 调用前最该知道的
+（这命令花不花钱？会不会删数据？能不能安全重试？）。命令清单本身由 click 内省自动生成，
+新增命令不会漏，只是缺省按只读安全值兜底，提醒维护者补 META。
+"""
+from __future__ import annotations
+
+import json as _json
+from enum import Enum
+from typing import Any
+
+import click
+import typer
+
+from . import __version__
+from .errors import ErrorInfo
+from .schemas import ContractExtraction, DocumentExtraction, ExtractionConfidence
+
+# 输出 schema 版本：未来字段演进时 +1，消费方据此判断兼容性。
+INTROSPECT_SCHEMA_VERSION = "1"
+
+# 命令安全元数据。side_effects 取值：
+#   read / fs_write / db_write / network / cost(消耗付费 API token)
+# destructive=True 表示会删除/不可逆覆盖已有数据；idempotent=True 表示重复执行结果一致。
+# 未列出的命令按「只读、非破坏、幂等」兜底（见 _command_entry）。
+COMMAND_META: dict[str, dict[str, Any]] = {
+    "ingest": {
+        "summary": "跑 OCR + 抽取，把文档入库",
+        "side_effects": ["fs_write", "db_write", "network", "cost"],
+        "destructive": False, "idempotent": True,
+    },
+    "extract": {
+        "summary": "只重跑抽取（不重跑 OCR），修复 partial / 改 prompt 后重抽",
+        "side_effects": ["fs_write", "db_write", "network", "cost"],
+        "destructive": False, "idempotent": True,
+    },
+    "list": {"summary": "列出档案", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "search": {"summary": "多字段过滤查询", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "show": {"summary": "查看单条详情", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "raw": {"summary": "打印文档原文（OCR 文本）", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "stats": {"summary": "档案库统计", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "todo": {"summary": "跨合同列待办义务", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "seals": {"summary": "跨文档列印章", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "delete": {
+        "summary": "删除单条档案（--purge-files 同时删文件）",
+        "side_effects": ["fs_write", "db_write"],
+        "destructive": True, "idempotent": True, "requires_confirmation": True,
+    },
+    "vacuum": {
+        "summary": "VACUUM 数据库（碎片整理）",
+        "side_effects": ["db_write"], "destructive": False, "idempotent": True,
+    },
+    "config": {"summary": "查看/设置全局配置", "side_effects": ["read", "fs_write"], "destructive": False, "idempotent": True},
+    "party": {
+        "summary": "管理 known_parties 身份基准库（list/show 读，set/rm 改）",
+        "side_effects": ["read", "fs_write"],
+        # group 入口本身非破坏；破坏在子命令 party rm。capabilities 暂只列顶层、不递归
+        # 展开 group 子命令——精确表达 party rm 的破坏性记入 backlog。
+        "destructive": False,
+        "idempotent": True,
+    },
+    "capabilities": {"summary": "列命令能力与副作用元数据", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "describe": {"summary": "打印单命令参数 schema", "side_effects": ["read"], "destructive": False, "idempotent": True},
+    "schema": {"summary": "打印核心数据结构 JSON Schema", "side_effects": ["read"], "destructive": False, "idempotent": True},
+}
+
+# 可经 `schema <type>` 暴露的数据结构（pydantic 直出 JSON Schema）。
+SCHEMA_TYPES: dict[str, type] = {
+    "document": DocumentExtraction,    # 通用抽取信封（list/show --json 的核心内容）
+    "contract": ContractExtraction,    # 合同专属字段
+    "confidence": ExtractionConfidence,
+    "error": ErrorInfo,                # 失败结果里的结构化错误
+}
+
+# register() 时由 cli.py 注入主 app；capabilities/describe 据此内省命令树（避免循环 import）。
+_APP: typer.Typer | None = None
+
+
+def _click_group() -> click.Group:
+    """主 app 的 click group——命令内省的入口。"""
+    if _APP is None:  # 理论上 register() 必先于命令执行；防御性报错而非静默
+        raise RuntimeError("introspect 未注册到 app")
+    return typer.main.get_command(_APP)  # type: ignore[return-value]
+
+
+def _param_to_dict(p: click.Parameter) -> dict[str, Any]:
+    """click 参数 → JSON 友好 dict：名称/种类/类型/必填/可选值/默认/帮助。"""
+    is_arg = isinstance(p, click.Argument)
+    entry: dict[str, Any] = {
+        "name": p.name,
+        "kind": "argument" if is_arg else "option",
+        "type": getattr(p.type, "name", "string"),
+        "required": bool(p.required),
+    }
+    if not is_arg:
+        entry["flags"] = list(p.opts) + list(p.secondary_opts or [])
+    choices = list(getattr(p.type, "choices", []) or [])
+    if choices:
+        entry["choices"] = choices
+    default = p.default
+    if isinstance(default, Enum):
+        default = default.value
+    if default is not None and not is_arg and isinstance(default, (str, int, float, bool)):
+        entry["default"] = default
+    help_text = getattr(p, "help", None)
+    if help_text:
+        entry["help"] = help_text
+    return entry
+
+
+def _command_params(cmd: click.Command) -> list[dict[str, Any]]:
+    """命令的全部参数（剔除 click 自动加的 --help）。"""
+    return [_param_to_dict(p) for p in cmd.params if p.name != "help"]
+
+
+def _command_entry(name: str, cmd: click.Command, *, with_params: bool) -> dict[str, Any]:
+    """组装单命令的能力描述。META 缺失时按只读安全值兜底。"""
+    meta = COMMAND_META.get(name, {})
+    # 命令摘要：优先用 META 登记的，回退命令 docstring 首行（纯空白 help 时为空，不取 [0] 防 IndexError）。
+    help_lines = (cmd.help or "").strip().splitlines()
+    summary = meta.get("summary") or (help_lines[0] if help_lines else "")
+    entry = {
+        "name": name,
+        "summary": summary,
+        "side_effects": meta.get("side_effects", ["read"]),
+        "destructive": meta.get("destructive", False),
+        "idempotent": meta.get("idempotent", True),
+        "requires_confirmation": meta.get("requires_confirmation", False),
+    }
+    if with_params:
+        entry["params"] = _command_params(cmd)
+    return entry
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    """结构化输出统一走 stdout（机器消费），保证可 `| jq`。"""
+    print(_json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def capabilities_cmd() -> None:
+    """列出所有命令及其副作用/破坏性/幂等元数据（机器可读 JSON）。"""
+    group = _click_group()
+    commands = [
+        _command_entry(name, cmd, with_params=False)
+        for name, cmd in sorted(group.commands.items())
+    ]
+    _emit({
+        "schema_version": INTROSPECT_SCHEMA_VERSION,
+        "tool": "contract-archive",
+        "version": __version__,
+        "commands": commands,
+    })
+
+
+def describe_cmd(
+    command: str = typer.Argument(..., help="要描述的命令名，如 ingest / list"),
+) -> None:
+    """打印单个命令的参数 schema（名称/类型/必填/默认/可选值/帮助）。"""
+    group = _click_group()
+    cmd = group.commands.get(command)
+    if cmd is None:
+        # 未知命令是用户错——提示走 stderr，退出码 2（与 typer 参数错一致）。
+        # 列出可选命令（与同模块 schema 对未知 type 的处理对齐），让用户/agent 少一步摸索。
+        names = ", ".join(sorted(group.commands))
+        typer.echo(
+            f"unknown command: {command}；可选: {names}（或跑 capabilities 看全部）", err=True
+        )
+        raise typer.Exit(2)
+    entry = _command_entry(command, cmd, with_params=True)
+    entry["schema_version"] = INTROSPECT_SCHEMA_VERSION
+    entry["help"] = (cmd.help or "").strip()
+    _emit(entry)
+
+
+def schema_cmd(
+    type_name: str = typer.Argument(
+        ..., help=f"数据结构名，可选：{', '.join(sorted(SCHEMA_TYPES))}"
+    ),
+) -> None:
+    """打印核心数据结构的 JSON Schema（pydantic 直出）。"""
+    model = SCHEMA_TYPES.get(type_name)
+    if model is None:
+        typer.echo(
+            f"unknown type: {type_name}; available: {', '.join(sorted(SCHEMA_TYPES))}",
+            err=True,
+        )
+        raise typer.Exit(2)
+    _emit(model.model_json_schema())
+
+
+def register(app: typer.Typer) -> None:
+    """把 introspection 命令挂到主 app。cli.py 在创建 app 后调用，避免循环 import。"""
+    global _APP
+    _APP = app
+    app.command("capabilities")(capabilities_cmd)
+    app.command("describe")(describe_cmd)
+    app.command("schema")(schema_cmd)