审查你所更改的 Python，而不是你所继承的 Python。Avouch 是一个轻量级、支持 Git 的 Python 静态分析 CLI。它询问 Git 你下一次提交将触及哪些文件，使用标准的 ast 模块解析每个更改的 .py 文件，并根据你在 avouch.toml 中配置的限制报告结构性问题。没有守护进程。没有网络。没有需要维护的路径列表。在 git push 之前的几秒钟内运行它，修复标记的问题，然后推送。pip install avouch cd your-repo avouch 目录 存在的原因 安装 快速开始 JSON 输出 安静模式 GitHub Actions 其他 CI 系统 配置 规则 工作原理 存储库布局 添加规则 测试 路线图 常见问题 贡献 许可证 存在的原因 审查集是差异，而不是存储库。Avouch 在运行时从 Git 计算审查集 (git diff HEAD --name-only 加上未跟踪的文件)。每个发现都可以归因于你即将推送的工作——而不是你继承的遗留代码。指标是准确的。参数计数、嵌套深度和行跨度来自 AST，而不是正则表达式。如果无法准确计算某个指标，Avouch 不会声称它。错误就是数据。一个不可读或语法错误的文件在报告中成为错误项。一个损坏的文件不会取消对其他文件的审查。Avouch 进行审查；它不做门控。退出代码表示结果——0 为干净，1 为发现违规，2 为 Avouch 错误——但执行必须位于可选择接口中，而不是在每次推送之前运行的工具中。 运行时是标准库。三次 git 子进程调用和 ast / tomllib。没有守护进程；运行时受限于差异的大小，而不是存储库。 安装 需要 Python 3.10+（规则使用 ast.Match；配置使用 tomllib）和在 PATH 中的 Git。pip install avouch 或从源代码安装：git clone https://github.com/mukundzha/avouch.git cd avouch pip install -e . 这两种方法都注册 avouch 控制台脚本 (avouch.cli:main)。 快速开始 接口是一个命令，加上一小组可选的标志： cd your-repo # ... 进行更改 ... avouch # 人类报告 avouch --json # 一个 JSON 文档在 stdout avouch --docs # 内置文档；未执行审查 avouch --version # 打印版本并退出 avouch --verbose # 步骤逐步审查详细信息在 stderr avouch --quiet # 分析，返回没有报告；只有退出代码 avouch --changed # 压缩与 HEAD 的更改文件的添加/删除视图 avouch --staged # 仅审查为下一个提交准备的文件 avouch --all-files # 审查每个符合条件的 Python 文件，而不仅仅是差异 avouch --not-git # 审查磁盘上每个符合条件的 .py 文件；不需要 Git 存储库 avouch --help # 每个标志 审查集由 Git 定义，因此在调用时没有任何可配置的内容。使用 --not-git，Avouch 跳过 Git 的要求，改为通过遍历当前目录审查每个符合条件的 .py 文件（跳过 Git、缓存和虚拟环境目录）。Avouch 审查：与 HEAD 的跟踪文件的修改（git diff HEAD --name-only）和未跟踪的 .py 文件（git ls-files --others --exclude-standard）。删除的路径和非 .py 文件将被跳过。已提交的、未修改的文件不会出现在输出中。看起来像生成的文件（generated.py、*_generated.py、codegen.py、autogen.py 等——见 src/avouch/utility/is_generated.py）也会被跳过。审查范围标志 --changed、--staged 和 --all-files 是相互排斥的——最多选择一个。输出标志 --json、--verbose 和 --quiet 可以与任何审查范围自由组合。 运行时的发现 $ avouch AVOUCH · 2 文件 · 4 警告 ──────────────────────────────────────────────────────────────────────────── bad.py:1: SCR002: 发现裸 except。请捕获特定异常，例如 except ValueError:。 │ 1 │ def connect(host, port, user, password, db, timeout): │ ^^^^^^^ SCR002 2 │ try: │ bad.py:1: SCR014: 参数过多 (6/5)。将相关参数组合成一个数据类或字典。 │ 1 │ def connect(host, port, user, password, db, timeout): │ ^^^^^^^ SCR014 2 │ try: ──────────────────────────────────────────────────────────────────────────── 按规则 SCR002 裸 except 1 SCR014 参数过多 1 ──────────────────────────────────────────────────────────────────────────── 通过 ✓ src/util.py 标题 — AVOUCH · N 文件 · W 警告 · E 错误：文件和按严重性计数，后跟每个文件的发现。 发现 — 每个发现呈现编译器风格：文件：行标题带有规则 ID 和完整消息，然后是被标记的代码区域，行号 dimmed 和标记名称下的插入符号 ^^^^^（在 TTY 上规则 ID 为蓝色）。按规则摘要 — 每个规则计数的发现，最常见者优先，计数右对齐。仅在有发现时呈现。通过网格通过 — 合规文件，压缩为几行，当数量较多时附带 [+N 更多] 注释。每个文件的相同（组件、规则）发现都被去重——标题计数每个发现，因此由于重叠的规则 ID（SCR004/SCR006 重复分支）