PostHog 项目中如何手动运行 ty 类型检查？-编程实验室

PostHog 项目中如何手动运行 ty 类型检查？

【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog

在 PostHog 仓库中改动 Python 代码后，如果想在本地快速跑一遍类型检查——不等 CI 排队、又希望比 mypy 快得多——可以手动运行项目内置的ty检查器。ty是 Astral 出品的类型检查工具，PostHog 目前将它放在「试用模式（trial mode）」：比 mypy 快约 10–100 倍，但仍是 alpha 软件，预期会有边界情况；CI 中它的结果仅供参考、不阻塞合入，真正的权威检查仍是 mypy。

以下内容依据 docs/internal/ty.md、pyproject.toml 和 .github/workflows/ci-python.yml 整理。

准备条件

本地已用uv管理项目 Python 环境（PostHog 后端通过uv安装依赖，CI 中对应uv sync --frozen --dev）。
ty已作为项目依赖固定在 pyproject.toml 中，版本为ty==0.0.74，同步完依赖环境后即可通过uv run ty调用，无需单独安装。
类型环境按 pyproject.toml 中[tool.ty.environment]配置使用 Python 3.13 语义：

[tool.ty.environment] python-version = "3.13"

另外，[tool.ty.src]已排除一批不参与检查的路径，如bin/**、manage.py、posthog/hogql/grammar/**、posthog/personhog_client/proto/generated/**、posthog/schema.py、tools/**等。检查这些目录时 ty 本身也会跳过它们，不需要额外处理。

手动运行 ty 检查

在仓库根目录执行（命令来自 docs/internal/ty.md）：

uv run ty check path/to/file.py # Check specific files uv run ty check posthog ee # Check directories

第一条针对具体文件：把path/to/file.py换成你实际改动的 Python 文件路径，适合提交前快速核对单个改动。
第二条针对目录：对posthog和ee两个后端主目录做全量检查，范围更大，耗时也更长。

如果你已经用uv sync建好环境且不希望每次运行都重新同步依赖，仓库的 lint-staged 钩子里用的是带--no-sync的等价写法（见根目录 package.json 的lint-staged配置）：

uv run --no-sync ty check

这也是 git pre-commit 阶段的行为：当暂存的改动包含*.py/*.pyi（排除posthog/hogql/grammar/、posthog/personhog_client/proto/generated/、products/*/skills/*/scripts/下的文件）时，lint-staged 会自动对暂存文件执行uv run --no-sync ty check，作为提交前的快速预检。

如何看结果

ty 的输出是 warning 列表。CI 中 PostHog 通过 problem matcher（.github/ty-problem-matcher.json，在 ci-python.yml 里以::add-matcher::注册）把这些 warning 直接在 PR 上内联展示，方便对照代码行。
判定标准：ty的告警在 CI 中是 informational、非阻塞的，看到 warning 不代表合入会失败；mypy 才是 CI 中「出错即阻塞」的最终检查。所以本地读 ty 结果时，建议把它当作 mypy 的加速预览：对每条 warning 判断是否为真实类型问题，遇到 ty 与 mypy 结论不一致的边界情况不用纠结。
如果你是在 PR 上看到别人贴出的 ty 标注：文档的建议是审阅反馈内容（ty 经常能抓到真实类型问题），并到 Slack 的 #team-devex 频道分享你的使用体验——这个试用本身就是为了收集反馈、评估 ty 未来是否升级为阻塞检查。

遇到误报时如何调整规则

pyproject.toml 的[tool.ty.rules]已预先屏蔽了一批「ty 与 mypy 在惯用 Django/DRF 代码上不一致」的规则，例如unresolved-import、unresolved-attribute、invalid-argument-type、missing-argument、invalid-method-override等均设为"ignore"；这些屏蔽覆盖了 Django 元编程、queryset、DRF serializer 模式以及 mypy/ty 双检查器共存的产物（如redundant-cast、unused-type-ignore-comment）。这套配置取代了早期的ty-baseline.txt过滤文件（已在 #55368 移除）。

如果 CI 或本地检查暴露出某个 ty 规则类别的误报，处理方式是向 pyproject.toml 的[tool.ty.rules]中新增一条：

[tool.ty.rules] <rule> = "ignore"

注意：不是所有与 mypy 不一致的规则都适合屏蔽。文档明确保留了一批能在新代码中抓住真实 bug 的规则（如unused-ignore-comment = "error"，用于防止过期的ty: ignore注释溜进仓库），新增 ignore 时只针对确认的误报类别。

边界与限制

ty当前是 alpha 软件且处于试用模式，输出仅供参考；深度检查、以及需要确定「到底有没有类型错误」的场景，仍以 mypy 为准（文档明确 mypy 更成熟、更全面，是本地深度检查的推荐工具）。
ty 尚未支持 Django 元编程，相关规则已在配置中屏蔽，这既是限制也解释了为什么部分 Django 代码上 ty 报不出问题。

参考文件

docs/internal/ty.md — ty 的定位、手动用法与配置说明
pyproject.toml —ty==0.0.74依赖、[tool.ty.environment]/[tool.ty.src]/[tool.ty.rules]配置
.github/workflows/ci-python.yml — CI 中 problem matcher 注册与uv run ty check的执行步骤
package.json — lint-staged 中针对暂存 Python 文件的uv run --no-sync ty check钩子