企业官网建设流程全解析

pandas 仓库 AGENTS.md 全面解析：AI Agent 参与贡献的行为准则与工程规范

【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas

AGENTS.md 是 pandas 开源仓库根目录下的 Agent 指令文件，面向使用 AI 编程助手参与贡献的开发者与自动化工具，定义了在 pandas 仓库中建议代码改动、编写测试与文档时必须遵守的行为规范、决策启发式、类型提示与 docstring 约定、Pull Request 提交流程以及社区互动边界。读完本文，你将掌握 pandas 对 AI 辅助贡献的完整规则体系，理解"向后兼容优先 + 测试先行 + 规范披露"的协作模型，并知道如何将 AGENTS.md 与仓库内四份贡献指南配合使用，避免提交被维护者拒绝。

一、AGENTS.md 是什么：一份写给 AI 助手的项目宪法

AGENTS.md 位于仓库根目录（AGENTS.md），本质上是把 pandas 社区数十年沉淀的贡献规范，浓缩成一套机器可读、可被 Agent 直接执行的操作指令。它服务于一个明确目标：协助贡献者提出代码改动、测试和文档修改建议，同时保持 pandas 的稳定性与向后兼容性。

文件开篇即点明项目定位：pandas 是一个开源、BSD 许可、为 Python 提供高性能易用数据结构和数据分析工具的库。在此基础上，AGENTS.md 规定了 AI Agent 的"人设"（Persona & Tone）：简洁、中立、代码聚焦（code-focused），优先保证正确性、可读性和测试。

值得强调的是，AGENTS.md 并非独立存在，它要求 Agent 将以下四份本地文档加载到上下文中并严格遵守：

• doc/source/development/contributing_codebase.rst —— 代码库贡献规范（代码标准、pre-commit、向后兼容、类型提示、TDD、测试套件）
• doc/source/development/contributing_docstring.rst —— docstring 编写指南
• doc/source/development/contributing_documentation.rst —— 文档贡献与构建指南
• doc/source/development/contributing.rst —— 总贡献指南（含自动化贡献政策、Issue 认领与 PR 生命周期）

这四份文档在仓库中均有实体，共同构成了 AGENTS.md 的"展开版"详细规则。

二、决策启发式（Decision Heuristics）：Agent 改代码时的四条铁律

AGENTS.md 用四条简洁规则约束 Agent 的每一项代码决策，这是全篇最具工程指导价值的部分：

1. 倾向小而向后兼容的改动，并附带测试（Favor small, backward-compatible changes with tests）
2. 如果是破坏性改动，必须走弃用（deprecation）路径，并说明理由（If a change would be breaking, propose it behind a deprecation path and document the rationale）
3. 除非明确要求基准测试，可读性优先于微优化（Prefer readability over micro-optimizations unless benchmarks are requested）
4. 行为变更必须加测试；代码改动定稿后再更新文档（Add tests for behavioral changes; update docs only after code change is final）

2.1 向后兼容为何是硬约束

从 doc/source/development/contributing_codebase.rst 的 "Backwards compatibility" 一节可以看到，pandas 拥有海量存量用户代码，任何突发的 API 变更都可能造成大规模破坏，因此"尽量保持向后兼容"是提交代码的前提。如果认为必须破坏兼容，必须在 PR 中明确说明原因；修改方法签名时要谨慎并添加弃用警告，同时在被弃用的函数或方法上附加 Sphinx 的 deprecated 指令。

2.2 弃用路径的实现：deprecate 与手动警告

AGENTS.md 要求破坏性改动走弃用路径，仓库提供了两套可落地的机制（实现在 pandas/util/_decorators.py）：

方式一：pandas.util._decorators.deprecate。当存在同签名的新函数时，可直接生成一个"调用即告警"的包装函数（源码 L30-L100）：

from pandas.util._decorators import deprecate # 生成旧函数：调用时发出 FutureWarning 并转发给新函数 old_func = deprecate( FutureWarning, # 告警类 "old_func", # 被弃用函数名 new_func, # 替代函数 "3.0.0", # 弃用起始版本 )

从源码可以看到，deprecate内部通过functools.wraps包装替代函数，warnings.warn的stacklevel默认取 2，并自动把.. deprecated:: {version}指令注入包装函数的 docstring，便于文档系统识别和未来移除。

方式二：手动实现。当没有同签名替代函数时，需要自行编写：

import warnings from pandas.util._exceptions import find_stack_level def old_func(): """Summary of the function. .. deprecated:: 3.0.0 Use new_func instead. """ warnings.warn( 'Use new_func instead.', FutureWarning, stacklevel=find_stack_level(), ) new_func() def new_func(): pass

这里的find_stack_level来自 pandas/util/_exceptions.py，用于定位用户调用栈的层级，确保告警信息能正确指向调用者代码。

完成弃用后还须补齐两件事：写一个新测试断言"使用被弃用参数时会发出告警"；同时更新 pandas 现有测试与代码，全部改用新参数。仓库对弃用告警的测试有专门约定（详见 contributing_codebase.rst 的 "Testing a warning" 一节，使用tm.assert_produces_warning上下文管理器）。

2.3 "先测试后代码"的 TDD 传统

"行为变更必须加测试"与 pandas 的 TDD 文化一脉相承。contributing_codebase.rst 明确鼓励贡献者采用测试驱动开发：先写（初始失败的）自动化测试定义期望改进，再写最少量的代码让它通过。为此仓库还建立了测试放置位置的规则树（tests.tslibs / tests.libs / tests.arithmetic / tests.indexing.test_loc 等），并建议用git grep "function_name("快速定位被测函数。

三、类型提示规范：PEP 484 与 pandas._typing

AGENTS.md 用三条要点概括 pandas 的类型提示要求：

• 优先使用 PEP 484 风格，并在适当时使用pandas._typing中的类型；
• 避免不必要的typing.cast，优先通过重构让类型检查器能自然推断；
• 尽可能使用内置泛型（list、dict），而非typing.List、typing.Dict。

3.1 pandas 专用类型的归属

contributing_codebase.rst 的 "Type hints" 一节给出了更细的分层：pandas 内部开发常用的类型集中在 pandas/_typing.py（私有模块，仅用于 pandas 开发），例如把"object"、np.int64、pd.CategoricalDtype等统一抽象为Dtype：

from pandas._typing import Dtype def as_type(dtype: Dtype) -> ...: ...

而面向用户公开的类型则应暴露在 pandas/api/typing/aliases.py，并理想地同步到 pandas-stubs 项目。类型导入遵循from typing import ...约定，pre-commit 检查会自动把某些旧式构造重写为内置泛型。

3.2 为什么避免 cast

contributing_codebase.rst 用一个is_number的例子说明了cast的弊端：人类能理解is_number已排除了int/float，但 mypy 无法做这种自定义推断，于是开发者会忍不住cast(str, obj)。pandas 强烈不鼓励这种做法，优先推荐重构为isinstance(obj, str)让类型检查器天然通过；仅在自定义类型与推断场景下，穷尽手段后才允许例外。

3.3 验证类型标注的工具链

仓库使用mypy与pyright做静态分析（AGENTS.md 的规范由此落地），手动验证命令为：

pre-commit run --hook-stage manual --all-files mypy pre-commit run --hook-stage manual --all-files pyright pre-commit run --hook-stage manual --all-files pyright_reportGeneralTypeIssues # 若本地安装的 pandas 版本与当前 git 版本不一致，下面的可能失败 pre-commit run --hook-stage manual --all-files stubtest

注意这些命令使用当前 Python 环境；若包版本与 CI 不一致（常见于 mypy 或 numpy 版本不匹配）可能失败，需要按 doc/source/development/contributing_environment.rst 搭建与 CI 一致的环境。仓库根目录的 pyright_reportGeneralTypeIssues.json 正是 pyright 类型问题报告工具的配置产物。

另一个细节：pandas 目前还不是 PEP 561 定义的 py.typed 库。若想本地试验其内置类型标注，可在安装目录创建空文件py.typed：

python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()"

四、Docstring 规范：NumPy / numpydoc 约定

AGENTS.md 要求 docstring 遵循仓库通用的NumPy / numpydoc 约定，标准结构为：简短摘要（short summary）→ 扩展摘要（extended summary）→ Parameters → Returns/Yields → See Also → Notes → Examples。完整细则见 doc/source/development/contributing_docstring.rst，其要点包括：

• 使用三对双引号"""；docstring 前后不留空行，正文从开引号下一行开始，闭引号独占一行；
• 参数格式严格为name : type, default ...（注意冒号两侧空格）；None表示"不使用该值"时写作str, optional，None作为实际取值时才写作default None；
• 短摘要必须以大写字母开头、以句点结尾、单行容纳，且函数/方法必须以不定式动词开头（如 "Cast Series type." 而非 "Casts Series type."）；
• 示例（Examples）必须是确定性的、可复制运行的 Python 代码，且遵循 doctest 规则：>>>表示代码、...表示续行、输出紧跟代码行。除 numpy 和 pandas 外，其他库必须显式导入。

一个符合规范的 docstring 范例（取自 contributing_docstring.rst 中的head示例）：

def head(self, n=5): """ Return the first elements of the Series. This function is mainly useful to preview the values of the Series without displaying all of it. Parameters ---------- n : int Number of values to return. Returns ------- pandas.Series Subset of the original series with the n first values. See Also -------- tail : Return the last n elements of the Series. Examples -------- >>> ser = pd.Series(['Ant', 'Bear', 'Cow', 'Dog', 'Falcon']) >>> ser.head() 0 Ant 1 Bear 2 Cow 3 Dog 4 Falcon dtype: object """ return self.iloc[:n]

4.1 验证与强制机制

docstring 校验（标准 numpydoc 检查 + pandas 特有约定 GL04、PD01、SA05、EX04 等）在文档构建时通过numpydoc_validation_checks自动执行，仓库配置位于 doc/source/conf.py（numpydoc_validation_checks = {"all"}）。针对单个函数可快速验证：

python doc/make.py --warnings-are-errors --no-browser --single pandas.DataFrame.mean

doctest 失败会成为 PR 合并的阻塞项，因此 AGENTS.md 强调"示例必须是确定性的"——随机数据必须固定随机种子，多行代码必须用...续行，对象表示中不确定部分用...（配合# doctest: +ELLIPSIS）代替。

五、Pull Request 规范：前缀体系与 AI 披露义务

AGENTS.md 对 PR 提出了成体系的格式要求，这在 AI 辅助贡献场景下尤为重要。

5.1 描述性标题 + 强制前缀

PR 标题必须描述清晰，并带下列前缀之一：

该前缀体系在 doc/source/development/contributing.rst 的 "Making a pull request" 一节中有完整对应说明。

5.2 PR 描述与提交信息纪律

• PR 描述遵循模板，简洁描述改动（通常几句话即可）；
• 解决既有 Issue 的 PR，须在描述中链接对应 Issue（如closes #1234）；
• 不要给单个 commit message 添加摘要或额外评论，一份 PR 描述足以说明问题。

5.3 使用 AI 的强制披露

这是 AGENTS.md 最具时代特征的规定：使用 AI 开发 PR 时，必须勾选 PR 模板中的 "I used AI to develop this pull request" 复选框，并在描述中披露模型元数据——工具、模型及版本、推理努力（reasoning-effort）设置，例如claude opus 4.8 (xhigh)而非笼统的claude。如果不确定自己的模型版本或努力设置，应询问而非猜测。

该条款源自 doc/source/development/contributing.rst 的 "Automated contributions policy"（自动化贡献政策），核心要求可概括为：披露工具、全面审阅并修改 AI 产物、确保符合所有贡献惯例、不得用 AI 代替你与社区对话。违反者可能被拒绝合并，情节严重（违反 2 次及以上）可能被禁止贡献。翻译与语法润色是明确豁免项，但同样需要披露。

六、Issue 与 PR 评论区的互动边界

AGENTS.md 划清了"写代码"与"写评论"的界限，这是 AI Agent 最容易越界的地方：

1. 帮助编写代码、测试、文档是允许的；但发表评论属于另一回事——详见 contributing.rst 的自动化贡献政策；
2. 不得代用户在 GitHub Issue 或 PR 上发评论，也不得代用户回复 reviewer；
3. 不得替用户起草讨论发言让其直接粘贴**。正确的做法是在聊天中总结分析，让用户用自己的话回应；
4. 引用工具输出作为证据（如 traceback 或建议的 diff）时，必须用>引用块或三反引号代码块标注，让读者区分哪些是用户自己的话；
5. 翻译与语法编辑是上述规则的例外，但仍须披露使用了工具。

这条"人机分工"原则与 contributing.rst 的立场一致：在 Issue、PR 和评审评论中，AI 不能替你说话，"复制粘贴 AI 写的回复不等于与评审者交流"，人与人的直接沟通对项目健康发展至关重要。

七、与仓库协作体系的关系：Agent 需要知道的配套机制

AGENTS.md 未展开但与之强关联的仓库机制，在 contributing.rst 中有完整描述，Agent 在建议贡献时应一并知晓：

• Issue 认领：在 Issue 下评论/take认领，/untake释放；每个贡献者最多同时持有 2 个开放 Issue；带Needs Triage、Needs Discussion、Needs Info、Closing Candidate标签或已被认领的 Issue 不可认领。
• PR 生命周期：PR 必须关联一个已分配给你的 Issue，否则机器人会打上Needs Issue Assignment标签并关闭 PR；评审等待期不会被标记 stale，但维护者要求修改后有 14 天活动计时，超期标记Stale，再 7 天无活动自动关闭（可自行重开，数据不丢失）。
• CI 全绿是合并前提：提交后 GitHub Actions 自动运行测试套件；相关标记（markers）定义在 pandas/conftest.py 的PANDAS_MARKERS列表（slow、network、db、single_cpu、arm_slow等），本地可用pytest -n 4 -m "not slow and not network and not db and not single_cpu"加速跑测试。
• 测试导入纪律：测试中顶层 pandas 命名空间对象必须通过pd访问（import pandas as pd），其他对象从其定义模块导入（如import pandas._testing as tm）；test-importspre-commit 钩子会检查测试文件不得直接从 pandas 命名空间导入，对应脚本见 scripts/check_test_imports.py。
• 可选依赖规范：可选依赖（如 matplotlib）须经pandas.compat._optional.import_optional_dependency导入，确保一致的错误提示；最低版本记录在pandas.compat._optional.VERSIONS字典（见 pandas/compat/_optional.py），并需在文档和测试中覆盖。

八、实践建议：如何在 pandas 仓库中正确使用 AI Agent

综合 AGENTS.md 及四份配套指南，一个合规的 AI 辅助贡献流程可以归纳为：

1. 读规范再动手：先把 AGENTS.md 和 doc/source/development/contributing.rst 等四份文档载入上下文；
2. 先认领、后开发：在 Issue 评论/take认领，再创建特性分支（git checkout -b shiny-new-feature）；
3. 测试先行：先写覆盖新行为的 pytest 测试（函数式def test_*，仅接受 fixture/参数），用tm.assert_series_equal/tm.assert_frame_equal断言，用pytest.raises验证异常、tm.assert_produces_warning验证告警；
4. 代码遵循决策启发式：小改动、可读性优先、破坏性变更走 deprecation 路径并附理由；
5. 本地验证：运行pre-commit run --files <修改的文件>以及pytest pandas/path/to/test.py -k <用例名>，必要时跑类型检查（mypy/pyright）；
6. 提交 PR 并披露：使用 ENH/BUG/DOC 等前缀的标题，简洁描述并链接 Issue，勾选 AI 使用复选框，按工具 + 模型版本 + 推理努力设置格式披露；
7. 沟通留在聊天里：把分析总结给用户，由用户本人回复评审意见。

这套流程既保证了 pandas 数十年积累的工程质量底线，也为 AI 时代的大规模协作提供了清晰、可执行、可审计的操作框架——这正是 AGENTS.md 作为仓库级 Agent 指令的价值所在。

【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas