supervision 贡献工作流全解：API 设计原则、uv 开发环境、pre-commit 质量门禁与 Doctest 规范

本文基于 supervision 项目官方贡献文档 contributing（其正文 include 自 .github/CONTRIBUTING.md）编写，系统梳理了向这个计算机视觉工具库贡献代码的完整工程链路：API 设计的四条红线、fork 分支模型与 Conventional Commits、基于 uv 的开发者环境搭建、pre-commit 钩子构成的质量门禁、pytest + doctest 测试体系，以及维护者侧的 PR 评审标准。读完本文后，你能够独立搭建 supervision 的可复现开发环境，并产出一份能通过该仓库 lint、类型检查与全部测试的 Pull Request。

1. 项目欢迎哪些贡献，以及 API 设计红线

supervision 是一个面向计算机视觉项目的通用工具库（定位见 README 与 pyproject.toml 中 "A set of easy-to-use utils that will come in handy in any Computer Vision project" 的描述）。贡献文档明确欢迎以下五类贡献：

1. 为库添加新功能（需遵循下文的特性贡献指引）；
2. 改进文档、补充使用示例；
3. 报告 bug 与 issue；
4. 提交新功能请求；
5. 提升测试覆盖率。

1.1 特性贡献原则：通用性优先

supervision 的设计目标是提供通用工具，因此贡献应当能惠及范围广泛的项目。官方文档给出的对照例子很直观：

• "统计穿越图像中一条线（任意位置）的物体数量"是常见需求，值得做成通用工具；
• "统计穿越位于 75% 位置处的线的物体数量"则过于特化，价值有限。

文档建议：在动手写新特性之前，先提交一个 Issue 讨论，让社区先评估价值再动手。仓库的 examples 目录（如 examples/count_people_in_zone/、examples/track_objects_in_video/）也是判断"通用需求 vs 特化脚本"边界的现成参照。

1.2 四条 API 设计原则

文档对 API 设计给出了四条硬性原则，其核心思想是：容器负责状态，标注器负责渲染，模型输出负责归一化。逐条展开如下：

1. 模型集成必须把外部原始输出归一化进既有容器。

   • 检测、分割等实例级预测（含 boxes、masks、class ids、置信度或每实例附加字段）一律进入 sv.Detections（实现位于 src/supervision/detection/core.py）；
   • 独立于检测框存在的纯关键点/姿态预测使用 sv.KeyPoints（实现位于 src/supervision/key_points/core.py）；
   • 当关键点与同一模型的框必然重合时，使用 Detections.keypoints 字段，其存储 (n, K, 2) 或 (n, K, 3) 数组，可选的第三通道为 [0, 1] 区间内的逐点置信度。

2. 模型已经返回 Supervision 对象时，不要再添加 from_<model> 方法。 from_* 方法只用于转换 Ultralytics、Transformers、Inference、MediaPipe 等外部包的原始输出。若某模型的 predict() 已返回 sv.Detections，应保持该返回类型，并把额外的结构化载荷存入 detections.data 或 detections.metadata（需使用有文档约定的 key）。

3. 标注器只负责渲染；过滤与可见性是容器状态。 按置信度、类别、tracker id、几何条件或自定义数据的过滤，应在标注之前通过容器切片 API 完成，例如 detections[detections.confidence > 0.7]、key_points[key_points.confidence > 0.5]。逐点的表现状态（如 KeyPoints.visible 掩码）可以挂在容器上，并由标注器一致地消费。

4. 标注器构造参数只描述视觉表现，不做模型质量门禁。 构造参数应覆盖颜色、线宽、透明度、文本、位置、样式以及 sigma 级别的通用可视化参数。标注器可以防御性地跳过非法几何（缺失点、零面积框、非有限坐标、被标记为不可见的点），但不应把置信度阈值或模型相关的"质量门"做成渲染选项。

这四条原则从源码结构看在仓库中是一以贯之的：标注器实现集中于 src/supervision/annotators/core.py，各 *Annotator 的构造参数均为可视化参数；而过滤逻辑（置信度、NMS 等）放在检测工具模块 src/supervision/detection/utils/ 中，与渲染路径分离。

2. 分支模型、分支命名与 Conventional Commits

2.1 Fork 与 upstream 设置

贡献流程遵循标准的 fork 工作流，目标分支（base）是 develop。完整命令如下：

# 克隆你自己的 fork（推荐浅克隆 develop 分支）
git clone --depth 1 -b develop https://github.com/YOUR_USERNAME/supervision.git
cd supervision

# 将官方仓库配置为 upstream 远程
git remote add -t develop upstream https://github.com/roboflow/supervision.git
git fetch upstream

其中 --depth 1 创建最小历史的浅克隆，-b develop 确保起点是开发分支，可显著减小下载体积；如果你需要完整历史，改为 git clone 后 git checkout develop 即可。

2.2 分支命名前缀

从 upstream 的 develop 切出功能分支：

git checkout -b <scope>/<your_branch_name> upstream/develop

分支名必须描述你要做的改动，并以约定的前缀开头：

前缀	用途	示例
feat/	新功能	feat/line-counter
fix/	缺陷修复	fix/memory-leak
docs/	文档变更	docs/update-readme
chore/	例行维护/工具链	chore/update-dependencies
test/	新增或修改测试	test/add-unit-tests
refactor/	代码重构	refactor/simplify-algorithm

2.3 提交信息与推送

git add -A
git commit -m "feat: add line counter functionality"
git push -u origin <your_branch_name>

提交信息遵循 Conventional Commits 格式 <type>[optional scope]: <description>，常用 type 包括：

• feat：新功能；
• fix：缺陷修复；
• docs：仅文档变更；
• style：不影响代码语义的变更（空白、格式等）；
• refactor：既不修 bug 也不加功能的代码变更；
• perf：性能改进；
• test：补充缺失测试或修正既有测试；
• chore：构建过程或辅助工具、依赖的变更。

推送后在 fork 中发起 Pull Request，务必确认 base 分支是 develop。提交 PR 前还需要注意两件事：

1. 提交时 cla-assistant 机器人会要求签署 CLA（Contributor License Agreement），未签署的 PR 维护者无法响应；
2. PR 必须通过全部测试与 lint 检查后才能合并。

2.4 新增函数的五项硬性要求

文档对每个新函数列出了明确清单，这也是 PR 完整性的核心判据：

1. 函数及所有参数都有 docstring；
2. 有单元测试；
3. 文档中有使用示例；
4. 在 docs 中创建条目以便自动生成功能文档；
5. 尽可能提供一个可无限制访问的 Google Colab（最小代码验证新特性或复现问题）。

3. 贡献者开发环境：venv + uv 的组合

官方推荐的环境搭建流程（以仓库当前 pyproject.toml 为准）如下。

第 1 步，克隆并初始化（见上文 2.1）；第 2 步，创建并激活虚拟环境：

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

第 3 步，安装 uv（Astral 出品的快速 Python 包管理器），然后第 4 步一键安装贡献所需的全部依赖：

uv pip install -r pyproject.toml --group dev --group docs --extra metrics

这三个依赖维度在 pyproject.toml 中有明确对应：

• --group dev：dependency-groups.dev，包含 pre-commit、pytest、pytest-cov、tox、jupytext 等贡献工具；
• --group docs：dependency-groups.docs，包含 mkdocs-material、mkdocstrings、mike 等文档构建栈；
• --extra metrics：optional-dependencies.metrics，即 pandas>=2，用于评估指标模块。

此外还有一个 geotiff extra（rasterio），供 GeoTIFF 相关功能使用。项目要求 Python >= 3.10（requires-python）。

第 5 步，验证环境：

uv run pytest

注意一个细节：由于 [tool.pytest] 的 addopts 默认带 --doctest-modules（见 pyproject.toml），uv run pytest 除了跑 tests/ 下的用例，还会执行 src/ 内所有 docstring 中的 doctest——这既是环境验证手段，也是后文测试规范的前提。

4. 代码风格与质量门禁：pre-commit 钩子详解

项目使用 pre-commit 维护代码质量，且该钩子同时以 GitHub Action 形式集成进 CI：每个 PR 打开时都会自动强制执行，本地跑不过就无需等待 CI 报错。

4.1 运行与安装钩子

# 安装 pre-commit（若按上文步骤装好依赖组则已具备）
uv sync --group dev

# 在仓库根目录运行全部检查
uv run pre-commit run --all-files

# 可选但推荐：注册为 git hook，每次 git commit 自动触发
uv run pre-commit install

4.2 当前启用的钩子清单

结合 .pre-commit-config.yaml 可以确认项目实际启用的检查项：

钩子	作用
check-doctest-fences（local）	校验 src/ 下源码 docstring 中 doctest 提示符（>>>）必须位于 ```pycon 围栏内等格式规则，脚本见 check_doctest_fences.py
trailing-whitespace / end-of-file-fixer / mixed-line-ending 等 pre-commit-hooks	空白、文件结尾、行尾符、JSON/YAML/TOML 合法性、大文件（>500KB）、私钥检测等
ruff-check --fix + ruff-format	lint 与格式化；规则集（A/E/F/I/PT/Q/RUF/S/UP/W、Google 约定 docstring、88 列、py310 目标）全部定义在 pyproject.toml 的 [tool.ruff]
mypy	类型检查（见 4.3）
mdformat	Markdown 格式化，分 gfm 与 mkdocs 两套配置，docs/ 目录走 mkdocs 扩展
prettier	格式化 .yaml/.yml/.toml（print-width 120）
pyproject-fmt + validate-pyproject	pyproject.toml 的格式化与合法性校验
codespell	拼写检查（配置见 pyproject.toml 的 [tool.codespell]）

配置文件中的 ci: 段还开启了 autofix_prs: true 与每月自动更新钩子版本（autoupdate_schedule: monthly），意味着格式类问题有可能由机器人直接自动修复到你的 PR 分支上。

4.3 Docstring 规范

• 所有新函数/类必须带 docstring，这是合入前提；
• 遵循 Google Python docstring style（ruff 的 lint.pydocstyle.convention = "google" 在 pyproject.toml 中已固化）；
• 每个 docstring 应包含使用示例；当示例只依赖 supervision、NumPy 与标准库（无可选 extra、无外部文件、无网络）时，优先写 >>> doctest 格式，让它被测试套件自动验证——详见第 6 节。

4.4 类型检查（mypy）

所有新代码必须带类型注解。mypy 由 pre-commit 钩子强制执行，PR 若被 mypy 报错将无法通过 CI。从 pyproject.toml 的 [tool.mypy] 可以看到检查口径相当严格：strict = true、ignore_missing_imports = false、warn_unused_ignores = true，仅对 examples.*、tests.* 与内部 _cv2 模块做了放宽。

4.5 可读性与性能约定

文档还规定了若干代码级约定：

• 可读性：避免在函数/构造器实参里写多分支条件表达式。若参数需要超过 a if condition else b 的简单三目运算，先赋值给命名局部变量再传参；
• 性能：
  • 避免 NumPy 数组的无谓拷贝；
  • 热路径优先向量化运算而非 Python 循环；
  • 重型框架依赖（torch、transformers、ultralytics）必须懒导入——在真正用到的函数内部 import，严禁出现在模块顶层。

这一条与第 1 节"模型集成归一化"原则相呼应：supervision 核心零深度学习依赖（核心依赖列表见 pyproject.toml dependencies，只有 numpy、av、scipy、pillow 等），框架相关能力全部走懒导入路径。

5. 弃用策略：三套机制 + 最小三个小版本窗口

supervision 对 API 弃用有明确的政策与配套工具链：

最小窗口：被弃用的 API 至少要保留 3 个 minor 版本才能移除。文档给出的例子：0.29.0 弃用 → 0.32.0 移除。且无论使用哪种机制，都必须在警告消息或装饰器参数中同时写明弃用版本与计划移除版本。

按弃用对象选择机制：

弃用对象	机制
模块级别名	supervision.utils.internal.warn_deprecated，放在被弃用模块的 __init__.py 中
重命名参数	supervision.utils.internal.deprecated_parameter 装饰器
公开函数/方法/类	pydeprecate 的 @deprecated（依赖见 pyproject.toml 的 pydeprecate>=0.9,<0.12）

这两套自研工具的实现位于 src/supervision/utils/internal.py：warn_deprecated 通过自定义警告类别 SupervisionWarnings 发出警告（可用环境变量 SUPERVISION_DEPRECATION_WARNING=0 关闭）；deprecated_parameter 装饰器在检测到旧参数名出现在 kwargs 中时发出警告，并通过 map_function 把旧值映射为新参数后继续执行——旧调用方式"仍然可用但被提示"。

真实用例：src/supervision/keypoint/init.py 展示了模块级弃用别名的标准写法——在 __init__.py 顶部先调用 warn_deprecated(...)，再从新模块 supervision.key_points 转发全部导出（KeyPoints、EdgeAnnotator、VertexAnnotator、VertexLabelAnnotator）。需要留意版本口径：贡献文档写的是 0.27.0 弃用、0.30.0 移除，而源码中的警告消息与当前开发版本 0.31.0.dev0（见 pyproject.toml）表明移除目标已顺延至 0.31.0，两者存在出入，以源码消息为准，正确写法是始终从 supervision.key_points 导入：

from supervision.key_points import KeyPoints  # correct

另外，pyproject.toml 的 pytest 配置 filterwarnings = ["error::DeprecationWarning"] 会把弃用警告提升为错误——从源码结构看，这意味着测试套件会主动暴露"内部代码仍在使用被弃用 API"的问题，是弃用窗口政策的一个自动化护栏。

6. 文档与 Cookbooks

6.1 本地运行 mkdocs 文档

supervision 的文档存放在 docs/ 目录，用 mkdocs 构建（配置入口 mkdocs.yml，主题定制在 docs/theme/）。本地预览流程：

# 安装文档依赖组
uv sync --group docs

# 启动文档服务器
uv run mkdocs serve

然后浏览器访问 http://127.0.0.1:8000。docs 依赖组（pyproject.toml）包含 mkdocs-material[imaging]、mkdocstrings（用于从 docstring 自动生成 API 页面，即 2.4 节第 4 条要求的"docs 条目"）以及 git 元数据插件。

6.2 提交 Cookbook 的规范

项目持续征集示例 notebook。提交新 cookbook 的完整要求：

1. 在 docs/notebooks/ 目录新建 notebook；
2. 在 docs/theme/cookbooks.html 中为新 notebook 添加卡片条目，必须包含路径、标题、标签（labels）、作者与 supervision 版本号；
3. 以 Count Objects Crossing the Line 作为模板；
4. 在 notebook 中固定（pin）你所用的 supervision 版本；
5. 在 notebook 顶部放置 "Open in Colab" 按钮（可参考上述模板 notebook）；
6. notebook 必须自包含：若依赖外部数据（视频、图片）或第三方库，需把下载与安装命令写进 notebook；
7. 用注释标注代码，并附各工具对应文档的链接。

从 docs/theme/cookbooks.html 的现有条目可以看到卡片的标准 HTML 结构：data-name（标题）、data-labels（逗号分隔的标签，如 ANNOTATORS,LINE ZONE,TRACKING）、data-version（形如 v0.26.0）、data-author 四个属性由 docs/javascripts/cookbooks-card.js 与 docs/stylesheets/cookbooks_card.css 渲染成卡片，新增条目时照此格式即可。

7. 测试规范：AAA 结构、Parametrize 与 Doctest

测试基于 pytest，运行命令：

# 全量测试
uv run pytest

# 带覆盖率
uv run pytest --cov=supervision

# 单独跑 doctest
uv run pytest --doctest-modules src/

7.1 组织结构

• Arrange-Act-Assert（AAA）：每个测试只有一个 setup 块、一个动作、一组断言；严禁把两个独立动作塞进同一个测试；
• 按类分组：相关测试归入同一个类，类名承载"被测单元"，方法名只描述期望结果而非实现机制：

class TestDetectionsWithNms:
    def test_keeps_highest_confidence_detection(self): ...
    def test_suppresses_lower_score_when_overlap_exceeds_threshold(self): ...
    def test_raises_when_confidence_missing(self): ...

• 激进 parametrize：三个以上结构相同的测试必须合并为一个 @pytest.mark.parametrize 用例；优先使用裸字符串/数字/布尔/None；当用例传递函数、对象或复合配置、需要 per-case mark、或默认 ID 不清晰时，用 pytest.param(..., id="语义化-slug")，不要用平行的 ids=[...] 列表（ID 要与参数紧邻放置以抵御重排）；只用于命名用例的尾随注释应移入 ID，只有解释非显然不变量的注释才保留。示例：

@pytest.mark.parametrize(
    ("overlap_metric", "expected_keep"),
    [
        pytest.param(OverlapMetric.IOU, [True, True], id="iou-keeps-both"),
        pytest.param(OverlapMetric.IOS, [True, False], id="ios-suppresses-small"),
    ],
)
def test_overlap_metric_determines_suppression(
    overlap_metric: OverlapMetric, expected_keep: list[bool]
) -> None:
    """Small box inside large: IOU keeps both; IOS suppresses small."""
    ...

• docstring：每个测试函数/方法至少一行 docstring（长度受 pyproject.toml 的 88 列限制约束），描述场景而非实现。

7.2 Doctest：让文档示例成为测试的一部分

选型规则：当示例只使用 supervision、NumPy 与标准库——没有可选 extra（如 --extra metrics 的包）、没有外部文件、没有网络与设备——时，优先写成 >>> doctest，让它被测试套件自动执行；当示例无法合理运行（加载第三方模型、读视频文件）或主要目的是演示报错/异常行为时，才用围栏 ```python 代码块。

自动验证链路来自 pyproject.toml 的 [tool.pytest]：addopts 默认含 --doctest-modules，且全局开启 ELLIPSIS 与 NORMALIZE_WHITESPACE 两个 doctest 选项——即 ... 可匹配任意输出片段，微小空白差异被忽略。

编写格式：在 Google 风格 docstring 的 Example: 小节中，输入行以 >>> 开头，续行以 ... 开头，期望输出紧跟最后一条输入行，中间不留空行：

def clip_boxes(xyxy: np.ndarray, resolution_wh: tuple) -> np.ndarray:
    """Clip bounding boxes to frame boundaries.

    Args:
        xyxy: Box coordinates as (N, 4) float array.
        resolution_wh: Frame size as (width, height).

    Returns:
        Clipped boxes as (N, 4) float array.

    Example:
        >>> import numpy as np
        >>> import supervision as sv
        >>> boxes = np.array([[-10, -5, 120, 80]], dtype=np.float32)
        >>> sv.clip_boxes(boxes, resolution_wh=(100, 60))
        array([[ 0.,  0., 100.,  60.]], dtype=float32)
    """

关键书写规则：

• 单行表达式——把 repr 写成期望输出：>>> len(result) → 1；
• 多行语句——用 ... 续行：>>> arr = np.array([ / ... [1, 2], / ... ])；
• print 输出——写不带引号的打印字符串；
• 返回 None——不需要输出行（用赋值或 _ = 抑制）；
• 大型/易变数组——用 ELLIPSIS：array([...]) 匹配任意内容；
• # doctest: +SKIP——仅在确实不可运行的行（如其他可运行示例中混入的 GPU 调用）作为最后手段使用，更推荐把示例拆成两个代码块。

围栏 ```python 块适用于：导入可选 extra（supervision[metrics]、torch、ultralytics）的示例；需要读文件、采集视频或运行中服务的示例；有意不完整的教学伪代码。

此外，pre-commit 钩子 check_doctest_fences.py 对 src/ 下的源码文件做额外格式门禁：>>> 提示符必须位于 ```pycon 围栏内，且 pycon 块结束围栏前必须恰好有一个空行——即 doctest 的"可运行性"和"书写格式"都有自动化保障。

8. PR 评审标准（贡献者与评审人共同参照）

文档同时面向维护者定义了统一的评审框架，贡献者提前对照它可以显著减少返工轮次。

总体建议分四级：

• 🟢 Approve — 可直接合并；
• 🟡 Minor Suggestions — 有改进建议但不阻塞；
• 🟠 Request Changes — 合并前必须处理；
• 🔴 Block — 存在重大问题，需要大改。

格式示例：🟠 Request Changes — Missing unit tests for PolygonMerger and no mkdocs entry.

完整性核对（✅ Complete / ⚠️ Incomplete / ❌ Missing / 🔵 N/A）：

• [ ] 清晰描述改了什么、为什么改；
• [ ] 新功能或修复已添加/更新测试；
• [ ] docstring 符合 Google 风格；
• [ ] 新函数/类已加入 mkdocs 条目；
• [ ] 展示特性/修复的 PR 附带 Google Colab；
• [ ] 可视化变更包含截图/视频。

质量评分采用 n/5 制并配合行内评论：

• 代码质量：5/5 优秀 — 4/5 良好 — 3/5 可接受 — 2/5 需改进 — 1/5 差。检查点：正确性（边界情况、None 检查、越界）、Python 最佳实践（惯用写法、错误处理、类型注解）、项目约定（docstring、lint、导入顺序、PEP 8 命名）；
• 测试：检查新代码单测、边界覆盖、具体断言、真实场景、清晰的测试命名；
• 文档：检查公开函数/类的 docstring、参数/返回/异常说明、使用示例、mkdocs 集成、面向用户的变更是否有 changelog 条目。

风险评估（5/5 严重 — 4/5 高 — 3/5 中 — 2/5 低 — 1/5 可忽略）聚焦四类风险：破坏性变更（必须附迁移指南）、性能、兼容性（新的 Python/依赖要求、平台相关代码）、安全（未校验输入、数据暴露）。

评审模板（Review Summary）：

## Review Summary

**Recommendation:** [emoji] [Status] — [justification]

**PR Completeness:**
- ✅ Complete: [items]
- ❌ Missing: [gaps]

**Quality Scores:**
- Code: n/5 [emoji] — [reason]
- Testing: n/5 [emoji] — [reason]
- Documentation: n/5 [emoji] — [reason]

**Risk Level:** n/5 [emoji] — [description]

**Critical Issues (Must Fix):**
1. [Issue] — See comment on `file.py`

**Suggestions (Optional):**
1. [Improve] — See suggestion on `file.py`

**Next Steps:**
1. [Action item]

评审实践：DO——用 GitHub 行内评论给建议、解释"为什么"而不只是"是什么"、区分阻塞项与锦上添花项、肯定做得好的部分、必要时运行 uv run pre-commit run --all-files 验证；DON'T——在总结里提行号（用行内评论）、给模糊反馈、纠结风格问题（交给工具）、假设评审人熟知项目约定、为小问题阻塞合并。语气要求：尊重、具体、务实、一致。

9. 许可证与行为准则

提交贡献即表示同意你的贡献以 MIT License 许可（见 LICENSE.md）；仓库同样提供 py.typed 标记（src/supervision/py.typed），保证你贡献的类型注解随分发给下游。参与项目前还应阅读 行为准则，其中规定了对所有参与者的行为期望。

---

小结：supervision 的贡献体系可以概括为"三道闸门 + 四条 API 原则"。API 设计闸门（容器归一化、渲染与过滤分离）决定了特性该不该做；pre-commit 闸门（ruff、mypy strict、mdformat、doctest 围栏检查等，见 .pre-commit-config.yaml）决定了代码写得够不够规范；测试闸门（AAA 结构、parametrize、doctest 自动验证、弃用警告升级为错误）决定了实现靠不靠谱。对照第 2.4 节的五项硬性要求准备 PR、以第 8 节的评审模板自我预审，就能让贡献在 fork → develop 分支 → CI 的链路上顺畅流转。