Pyrefly 接入 AI Agent 工作流：用 Skill 文件与 Hooks 自动化 Python 类型检查-育师

Pyrefly 接入 AI Agent 工作流：用 Skill 文件与 Hooks 自动化 Python 类型检查

【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly

Coding agent 生成的 Python 代码越来越多，类型错误、签名不匹配和 API 误用也随之渗入大型项目。本文介绍如何把 Pyrefly 类型检查嵌入 Agent 的"生成-修正"循环（agentic loop）中，使每段生成代码都能自动通过类型校验。读完本文，你将掌握两种可落地的集成方案——CLI Skill 与 Stop 事件 Hook——并能结合 Pyrefly 源码理解其退出码、输出格式等与 Agent 自动交互密切相关的机制。

官方推荐的做法（TL;DR）如下：

为 Agent 添加一个 Skill 文件，并在AGENTS.md中写入指令，确保功能完成前项目类型检查必须通过；
如果所用模型不能可靠地触发该指令，则额外在 Stop 事件上配置 Hook。

类型检查恰好处于 Agent 工作流的"甜蜜点"：它足够快，适合迭代修复小问题；足够稳健，能捕获复杂度的类型问题；且诊断信息足够具体，Agent 可以直接据此修改代码。

1. 方案一：CLI Skills（技能文件）

如果你熟悉 agentic 工作流，应该已经定义过 skill 文件——这些文件指示 Agent 如何执行特定任务或使用特定工具。对 Pyrefly 这样的类型检查器，一个简单的 skill 如下（存放于项目内.agent/skills目录下的skill-name.md）：

--- name: pyrefly-cli description: Instructions to type check using Pyrefly's CLI. Use when function signatures of APIs change to validate program's types. --- Run `pyrefly check` at the root of the project. Try fixing all possible type errors before running `pyrefly check` again.

几个关键实践要点：

description 决定了触发时机。Agent 通常依靠标题和 description 判断何时使用某个 skill。description 必须清晰说明"什么时候该用它"，否则会被过度调用（浪费 token）或调用不足。
单独的 skill 并不总是可靠的。官方在博客中记录了实测：即使用如下强制性措辞，Claude Opus 4.6 依然没有触发类型检查：

MANDATORY type checker. You MUST run this before completing ANY task that modifies Python files. Never skip this step.

因此，如果使用 skill，官方建议同时在项目的AGENTS.md中追加一条收尾指令：

## Type Checking Before completing any task that creates or modifies Python files, you MUST: 1. Run `pyrefly check` at the root of the project 2. If there are any type errors, fix ALL of them 3. Run `pyrefly check` again to confirm 0 errors

Pyrefly 仓库本身就是这一惯例的实例：根目录的 AGENTS.md 即为该仓库中 Agent 提供的项目指导，其中明确列出了目录职责（如pyrefly/lib/commands对应 CLI、pyrefly/lib/test对应类型检查器集成测试）、提交前的格式化/lint 要求，以及测试书写规范（如优先使用assert_type而非reveal_type）。这正是一个"项目级指令 + 具体工具"的 AGENTS.md 范例。

不同 Agent 对 skill 的支持各有细节（如 Claude Code、Gemini CLI、OpenAI Codex 的 Skills 文档，Kiro 的 Hooks 文档），配置前建议查阅你所用 Agent 的官方文档。

2. 方案二：CLI Hooks（钩子）

Hooks 与主观性的 skill 不同：它在指定事件每次发生时强制执行某个动作，无需依赖模型的"自觉性"。这些事件通常与工具调用或 Agent 生命周期的关键阶段相关。

如果你已经配置了 pre-commit hooks，它们可能已经生效——当 Agent 向版本控制系统提交时，pre-commit 检查会产生同样性质的"阻力"。但为了让 Agent 在不提交的情况下就能完成类型检查，官方推荐使用 agentic hooks。

2.1 Stop 事件 + 命令 Hook

官方在 Claude Code 中实测 Pyrefly，建议在Stop事件（Agent 完成每个任务时触发）上挂接类型检查命令。在 Claude 中，向.claude/settings.json添加如下配置：

{ "hooks": { "Stop": [{ "hooks": [{ "type": "command", "command": "pyrefly check >&2 || exit 2", "timeout": 30 }] }] } }

这里有两条细节必须遵守，原因在于 Pyrefly 的输出与退出码约定：

重定向到 stderr：Pyrefly 的check输出走 stdout（见 test/args.md 中大量output_stream: stdout的测试用例，均断言诊断行出现在 stdout 上），而 Claude 的 command hook 需要读取 stderr 才能把输出回传给模型，因此用>&2显式重定向。
以退出码 2 结束：Claude 的 hook 协议要求返回 exit code 2 才能让模型"理解"这是一条阻塞性反馈，故命令尾部加|| exit 2。注意这与 Pyrefly 自身的退出码语义不同——见下节源码分析。

2.2 Stop 事件 + Agent Hook（进阶）

另一种做法是让 Hook 调度一个子 Agent 去调查类型错误：

{ "hooks": { "Stop": [ { "hooks": [ { "type": "agent", "prompt": "Verify that all Python files pass pyrefly type checking. Run `pyrefly check` and check the results. If there are any type errors, return ok: false with the errors. $ARGUMENTS", "timeout": 30 } ] } ] } }

官方表示这种方式需要一些自定义指令但效果良好。一个容易踩坑的细节：agent类型的 hook 与prompt类型看起来相似，但在 Claude 中必须使用agenthook，模型才能在其中调用 Pyrefly 工具。

3. 源码佐证：`pyrefly check`的退出码与输出格式

Agent 自动化依赖检查器的机器可读行为。阅读 Pyrefly 源码可以确认上面 Hook 配置的每个细节都有对应实现。

3.1 退出码语义

Pyrefly 将命令完成状态抽象为三档，映射到进程退出码 pyrefly/lib/commands/util.rs#L64-L84：

pub enum CommandExitStatus { /// The command completed without an issue. Success, /// The command completed, but problems (e.g. type errors) were found. UserError, /// An error occurred in the environment or the underlying infrastructure... InfraError, } impl CommandExitStatus { pub fn to_exit_code(self) -> ExitCode { match self { CommandExitStatus::Success => ExitCode::SUCCESS, // 0 CommandExitStatus::UserError => ExitCode::FAILURE, // 1 // Exit code 2 is reserved for Meta-internal usages CommandExitStatus::InfraError => ExitCode::from(3), } } }

即：0 表示通过，1 表示发现类型错误，3 表示环境/基础设施错误。这正是 Stop hook 中|| exit 2存在的原因——Pyrefly 检查失败时返回 1，而 Claude 的 hook 协议要求 2，所以由 hook 命令本身负责"翻译"退出码。CLI 入口 pyrefly/bin/main.rs#L121-L144 中的run()最终将CommandExitStatus通过status.to_exit_code()转换为进程退出码，确认了这条链路。

3.2`check`命令的可配置性

check子命令的参数定义在 pyrefly/lib/commands/check.rs#L133-L153：文件选择参数（FilesArgs）、实验性的--watch模式、类型检查参数，以及一组"Config Overrides"（配置覆盖选项）。仓库的端到端测试 test/args.md 验证了其中与 Agent 场景最相关的开关：

--preset off|basic|strict：预设检查强度，且配置文件中显式设置会覆盖--preset；
--error <kind>/--ignore <kind>：按错误类型单独升降级，如--error=missing-source、--ignore=missing-source；
--search-path/--site-package-path：控制 stub 与运行时模块的查找路径（影响 Agent 引入新依赖后的类型可见性）；
--output-format=min-text：紧凑文本格式，如ERROR * [bad-assignment] (glob)，适合喂给模型的上下文窗口。

此外OutputFormat枚举还支持Json输出（crates/pyrefly_config/src/config.rs#L208-L217），配合 SARIF 输出可进一步接入 CI 生态——仓库中 test/sarif/ 目录提供了 SARIF 诊断格式的预期输出与校验脚本。若你的 Agent 工作流需要结构化消费诊断结果，JSON/SARIF 格式比纯文本更稳妥。

4. 小结

Skill 文件（.agent/skills/*.md）+AGENTS.md 收尾指令是第一选择：成本低、语义清晰，但依赖模型的依从性；官方实测表明即便措辞强硬（"MANDATORY … Never skip"）也不能保证每次触发。
Stop 事件 Hook是强制性兜底：pyrefly check >&2 || exit 2一行命令即可把类型检查变成 Agent 生命周期的硬关卡；进阶版可用agent类型 hook 让子 Agent 自主调查并回报错误。
Pyrefly 的三档退出码（0/1/3）、stdout 输出以及--output-format、--preset、--error/--ignore等开关，为上述两种集成方案提供了可靠的机器接口。

将类型检查器接入 agentic loop 是提升 Agent 产出可靠性的一条低成本路径：开发者工具不再只服务于人，同样服务于 Agent。建议从 Skill + AGENTS.md 起步，观测模型依从性后再决定是否叠加 Hook。

【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Pyrefly 接入 AI Agent 工作流：用 Skill 文件与 Hooks 自动化 Python 类型检查