ty 类型检查器 CLI 完整参考：命令、选项、退出码与规则管理实战

ty 类型检查器 CLI 完整参考：命令、选项、退出码与规则管理实战

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff

导读

ty是本仓库中随 Astral 工具链一同开发的超高速 Python 类型检查器（源码位于 crates/ty，相关 crate 还包括类型语义分析 crates/ty_python_semantic 与项目解析 crates/ty_project），其核心日常操作全部集中在ty这一个命令及其子命令上。本文以官方文档 crates/ty/docs/cli.md 为骨架，逐条详解ty check的全部参数、ty server、ty version、ty explain等命令的语义，并结合 crates/ty/src/args.rs 与 crates/ty/src/lib.rs 的源码实现说明参数背后的真实行为（如规则覆盖顺序、退出码判定逻辑、配置优先级）。读完本文，你将能够熟练配置出适合本地开发与 CI 的类型检查命令。

文档一致性说明：cli.md是自动生成文件（文件头部注明由cargo dev generate-all生成），所有命令与参数的真实「唯一事实源」是 crates/ty/src/args.rs 中基于 clap 的 doc 注释与参数声明。若需修改 CLI 行为，正确做法是修改该文件后重新生成文档。

ty 顶层命令结构

ty本身不带子命令以外的直接参数，整体用法为：

ty <COMMAND>

顶层子命令共 5 个（外加 1 个隐藏命令），在 args.rs 的Command枚举中声明：

同时，ty --help与ty -h的区别在 clap 中表现为：-h输出精简版帮助，--help输出完整帮助。整个 CLI 采用 clap 定义，入口在 crates/ty/src/lib.rs 的run()：先进行通配符展开与@file参数文件展开，再按子命令分发执行。

ty check：项目类型检查主命令

ty check用于对一个 Python 项目（或一组路径）做全量类型检查，是本工具被调用频率最高的命令：

ty check [OPTIONS] [PATH]...

PATHS 参数与项目发现

• PATHS：要检查的文件或目录列表。不传时默认检查「项目根目录」；传多个路径时逐个检查。
• --project <project>：在给定的项目目录内运行命令。ty 会从该目录向上逐级发现pyproject.toml，并在未设置venv-path选项时顺带发现项目的虚拟环境.venv；但其他命令行参数（如相对路径）仍相对当前工作目录解析。

从源码 lib.rs 可以看到，所有传入路径在解析阶段都会被转换为相对当前工作目录的绝对路径；若命令行传入的是文件而非目录，ty 会按独立脚本处理（例如uv run --script场景），不继承外层 workspace。

环境解析：Python 解释器、typeshed 与额外搜索路径

其中--python在 args.rs 中被声明为--python的 alias，两种写法等价。

Python 版本与平台

版本取值：3.7、3.8、3.9、3.10、3.11、3.12、3.13、3.14、3.15（定义见 crates/ty/src/python_version.rs，两端取值可在ty check --help中复核）。

未显式指定时的推导顺序（按优先级从高到低，来自 args.rs 的 doc 注释）：

1. 读取pyproject.toml中project.requires-python设置，取该范围的最低版本；
2. 检查已激活或已配置的 Python 环境，尝试推断其版本；
3. 回退到 ty 支持的最新稳定版Python。

规则启用与禁用：--error / --warn / --ignore

规则严重级别调整是ty check最具特色的能力，三参数均支持多次出现，并可用all表示作用于全部规则：

• --error <rule>：将给定规则视为error级。可重复，可用all。
• --warn <rule>：将给定规则视为warn级。可重复，可用all。
• --ignore <rule>：禁用该规则。可重复，可用all。

从源码角度，这三个参数由 args.rs 中自定义的RulesArg类型解析，其注释明确指出：后出现的规则参数会覆盖先前的严重级别（"arguments last override previous severities"）。实现上，RulesArg::from_arg_matches会记录每个参数出现的索引并按索引排序，从而保证覆盖语义正确。例如：

# 全部规则按 error 级别检查，但禁用 call-non-callable ty check --error all --ignore call-non-callable # 只把 conflicting-metaclass 提级为 error、ambiguous-protocol-member 降级为 warn ty check --error conflicting-metaclass --warn ambiguous-protocol-member

可用的规则名以 crates/ty/docs/rules.md 列出的为准，例如abstract-and-final-method、call-non-callable、conflicting-metaclass等。

修复与自动抑制：--fix 与 --add-ignore

二者在 args.rs 中声明了conflicts_with（互斥，不能同时使用）。底层行为可追溯至 lib.rs 的主循环：

• --fix调用ty_python_semantic::fix_all_diagnostics，并以Applicability::Safe为界限，只应用安全的自动修复；
• --add-ignore调用ty_python_semantic::suppress_all_diagnostics，将诊断替换为行内ty: ignore注释；
• 在人类可读输出下，--add-ignore结束时还会打印 "Added N ignore comment(s)" 汇总。

文件选择与排除

注意这些布尔开关在 args.rs 中均为「配对」定义：一个公开的正向开关配一个隐藏的反向开关，最终通过resolve_bool_arg合并成Some(true)/Some(false)/None三态——只有当用户显式传参时才覆盖配置文件中的对应设置，避免 CLI 默认值意外压过配置文件里已显式声明的值。

诊断输出格式

五种可选值（枚举定义在 args.rs）：

例如在 GitHub Actions 中可直接使用--output-format github让错误以工作流注解形式内联显示；JUnit 与 GitLab 格式则面向对应的 CI 平台报表。

退出码控制

底层退出码判定见 lib.rs 的exit_status_from_diagnostics：程序先扫描所有诊断的最高严重级别（Info < Warning < Error < Fatal），再结合error_on_warning终端设置决定成败；若诊断中同时含有 IO 错误则直接返回「命令错误」。ExitStatus的完整语义如下：

这使 ty 可以直接嵌入 CI 判断：默认命令ty check返回 1 即表示需要修复，而--exit-zero可用于「只报告不阻断」的持续集成场景。

其他控制选项

配置优先级值得一提：CLI 通过--config传入的单项覆盖，其优先级始终高于所有配置文件。这在 args.rs 的ConfigsArg中实现——每个-c键值对被解析为一份Options（Options::from_toml_str），随后在 lib.rs 中按「先应用配置文件、再应用 CLI 覆盖」的顺序合并，CLI 覆盖天然胜出。完整配置项语义参见 crates/ty/docs/configuration.md。

示例——将配置与命令结合使用：

# 在指定 Python 3.12 环境下做全量检查 ty check --python .venv/bin/python3 --python-version 3.12 # 检查单个目录，并额外排除两个目录 ty check src/ --exclude "tests/" --exclude "**/generated/**" # 一次性查看所有错误并自动应用安全修复 ty check --fix # CI 中按 warning 即失败，并输出 GitHub 注解格式 ty check --error-on-warning --output-format github # 交互式持续开发：监听变化、增量重查 ty check --watch

watch 模式与主循环的内部结构

从源码看，--watch并非简单循环重跑：ty check的检查流程由基于 Salsa 增量数据库的MainLoop驱动（lib.rs）。主循环通过消息通道接收「检查请求、变更事件、uv 环境同步完成」三类消息，并让检查任务在 rayon 线程池中异步执行；文件系统变更会通过watch::directory_watcher上报，变更时自动取消进行中的查询并按 revision 丢弃过期的检查结果。Ctrl+C 处理被注册为取消令牌，触发后返回退出码 130。进度条由IndicatifReporter呈现（Checking {pos}/{len} files），因此--no-progress能关闭包括脚本同步进度在内的全部进度 UI。

ty server：启动语言服务器

ty server

ty server以无参数形式启动语言服务器，除--help/-h外没有公开选项。在 args.rs 中还存在一个被隐藏的调试参数--find-executable：它会打印当前目录对应项目应使用的 ty 可执行文件绝对路径（若已通过environment.python配置则优先使用，否则按常规顺序发现 Python 环境），供编辑器集成定位后端，退出码 0 表示找到、1 表示发现失败、2 表示意外错误。该命令的实际服务实现位于 crates/ty/src/server.rs，完整的 LSP 功能栈由 crates/ty_server 提供。

ty version：查看版本

ty version [OPTIONS]

唯一选项为--output-format，默认值text，可选text或json：

• text：输出形如ty 0.5.1+24 (53b0f5d92 2026-01-01)的单行信息；
• json：输出结构化 JSON。

版本数据的组装在 crates/ty/src/version.rs：VersionInfo由版本号字符串与可选的CommitInfo组成，其中提交信息（短哈希、完整哈希、提交日期、最近 tag、距最近 tag 的提交数）在构建期由build.rs注入环境变量读取；text格式规则为<version>[+N] (<short_commit_hash> <date>)，+N仅在距最近 tag 存在未发布提交时出现。发布版本号来自工作区的dist-workspace.toml（本仓库内ty包本身处于开发期，版本为0.0.0且不发布，见 crates/ty/Cargo.toml）。

ty generate-shell-completion：生成 shell 补全

ty generate-shell-completion <SHELL>

该命令在官方文档中有记录，但在 args.rs 中被标注为隐藏（#[clap(hide = true)]）。它接收一个 shell 名（由clap_complete_command支持）并输出对应 shell 的补全脚本到 stdout，例如可在 bash/zsh/fish 配置中将其输出重定向到补全目录。

ty explain：规则速查与解释

ty explain <COMMAND>

ty explain是面向文档与排查的子命令，下辖ty explain rule与帮助入口ty explain help。

ty explain rule：查看单条或全部规则

ty explain rule [OPTIONS] [RULE]

• 位置参数RULE：要解释的规则名；省略时默认解释全部规则。
• --output-format：输出格式，默认text，可选text或json。

实现位于 crates/ty/src/rule.rs：它会查询default_lint_registry()注册表，将匹配的LintId渲染为包含以下字段的说明：

• 规则名（如call-non-callable）；
• 默认级别（ignore / warn / error）；
• 状态：Preview (since X)、Stable (since X)、Deprecated (since X): reason、Removed (since X): reason；
• 规则的完整文档正文。

# 查看某条规则 ty explain rule call-non-callable # 以 JSON 输出全部规则的说明（可用于生成工具链） ty explain rule --output-format json

text输出以 Markdown 风格呈现，每条规则从# <rule-name>标题开始，可直接作为阅读材料；json输出为序列化数组，方便被脚本消费。所有规则的完整人类可读文档集中在 crates/ty/docs/rules.md。

常见组合：本地开发与 CI 两套命令

结合上述选项，可沉淀两套典型用法：

本地开发（自动修复 + 增量监听）：

# 一键安全检查并自动修复可安全修复的问题 ty check --fix # 开发期间持续监听 ty check --watch

CI 门槛（报警即失败 + 平台格式）：

# GitHub Actions：warning 也视为失败，输出注解 ty check --error-on-warning --output-format github # GitLab：输出 Code Quality 报告 JSON ty check --output-format gitlab # 只读报告、不阻断：即使有 error 也返回 0 ty check --exit-zero

相关参考

• 本命令参考文档原文件：crates/ty/docs/cli.md
• CLI 定义与参数解析（唯一事实源）：crates/ty/src/args.rs
• 入口与主循环、退出码： crates/ty/src/lib.rs、crates/ty/src/main.rs
• 规则文档与配置说明：crates/ty/docs/rules.md、crates/ty/docs/configuration.md
• 环境变量（如TY_CONFIG_FILE、TY_OUTPUT_FORMAT）完整清单：crates/ty/docs/environment.md

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff