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/pandasAGENTS.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 HeuristicsAgent 改代码时的四条铁律AGENTS.md 用四条简洁规则约束 Agent 的每一项代码决策这是全篇最具工程指导价值的部分倾向小而向后兼容的改动并附带测试Favor small, backward-compatible changes with tests如果是破坏性改动必须走弃用deprecation路径并说明理由If a change would be breaking, propose it behind a deprecation path and document the rationale除非明确要求基准测试可读性优先于微优化Prefer readability over micro-optimizations unless benchmarks are requested行为变更必须加测试代码改动定稿后再更新文档Add tests for behavioral changes; update docs only after code change is final2.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-L100from 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, stacklevelfind_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._typingAGENTS.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等统一抽象为Dtypefrom pandas._typing import Dtype def as_type(dtype: Dtype) - ...: ...而面向用户公开的类型则应暴露在 pandas/api/typing/aliases.py并理想地同步到 pandas-stubs 项目。类型导入遵循from typing import ...约定pre-commit 检查会自动把某些旧式构造重写为内置泛型。3.2 为什么避免 castcontributing_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.typedpython -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, optionalNone作为实际取值时才写作default None短摘要必须以大写字母开头、以句点结尾、单行容纳且函数/方法必须以不定式动词开头如 Cast Series type. 而非 Casts Series type.示例Examples必须是确定性的、可复制运行的 Python 代码且遵循 doctest 规则表示代码、...表示续行、输出紧跟代码行。除 numpy 和 pandas 外其他库必须显式导入。一个符合规范的 docstring 范例取自 contributing_docstring.rst 中的head示例def head(self, n5): 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.pynumpydoc_validation_checks {all}。针对单个函数可快速验证python doc/make.py --warnings-are-errors --no-browser --single pandas.DataFrame.meandoctest 失败会成为 PR 合并的阻塞项因此 AGENTS.md 强调示例必须是确定性的——随机数据必须固定随机种子多行代码必须用...续行对象表示中不确定部分用...配合# doctest: ELLIPSIS代替。五、Pull Request 规范前缀体系与 AI 披露义务AGENTS.md 对 PR 提出了成体系的格式要求这在 AI 辅助贡献场景下尤为重要。5.1 描述性标题 强制前缀PR 标题必须描述清晰并带下列前缀之一前缀含义ENHEnhancement新增功能BUGBug fix缺陷修复DOC文档新增/更新TST测试新增/更新BLD构建流程/脚本更新PERF性能改进TYP类型标注CLN代码清理该前缀体系在 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 最容易越界的地方帮助编写代码、测试、文档是允许的但发表评论属于另一回事——详见 contributing.rst 的自动化贡献政策不得代用户在 GitHub Issue 或 PR 上发评论也不得代用户回复 reviewer不得替用户起草讨论发言让其直接粘贴**。正确的做法是在聊天中总结分析让用户用自己的话回应引用工具输出作为证据如 traceback 或建议的 diff时必须用引用块或三反引号代码块标注让读者区分哪些是用户自己的话翻译与语法编辑是上述规则的例外但仍须披露使用了工具。这条人机分工原则与 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 tmtest-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 辅助贡献流程可以归纳为读规范再动手先把 AGENTS.md 和 doc/source/development/contributing.rst 等四份文档载入上下文先认领、后开发在 Issue 评论/take认领再创建特性分支git checkout -b shiny-new-feature测试先行先写覆盖新行为的 pytest 测试函数式def test_*仅接受 fixture/参数用tm.assert_series_equal/tm.assert_frame_equal断言用pytest.raises验证异常、tm.assert_produces_warning验证告警代码遵循决策启发式小改动、可读性优先、破坏性变更走 deprecation 路径并附理由本地验证运行pre-commit run --files 修改的文件以及pytest pandas/path/to/test.py -k 用例名必要时跑类型检查mypy/pyright提交 PR 并披露使用 ENH/BUG/DOC 等前缀的标题简洁描述并链接 Issue勾选 AI 使用复选框按工具 模型版本 推理努力设置格式披露沟通留在聊天里把分析总结给用户由用户本人回复评审意见。这套流程既保证了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pandas 仓库 AGENTS.md 全面解析：AI Agent 参与贡献的行为准则与工程规范
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/pandasAGENTS.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 HeuristicsAgent 改代码时的四条铁律AGENTS.md 用四条简洁规则约束 Agent 的每一项代码决策这是全篇最具工程指导价值的部分倾向小而向后兼容的改动并附带测试Favor small, backward-compatible changes with tests如果是破坏性改动必须走弃用deprecation路径并说明理由If a change would be breaking, propose it behind a deprecation path and document the rationale除非明确要求基准测试可读性优先于微优化Prefer readability over micro-optimizations unless benchmarks are requested行为变更必须加测试代码改动定稿后再更新文档Add tests for behavioral changes; update docs only after code change is final2.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-L100from 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, stacklevelfind_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._typingAGENTS.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等统一抽象为Dtypefrom pandas._typing import Dtype def as_type(dtype: Dtype) - ...: ...而面向用户公开的类型则应暴露在 pandas/api/typing/aliases.py并理想地同步到 pandas-stubs 项目。类型导入遵循from typing import ...约定pre-commit 检查会自动把某些旧式构造重写为内置泛型。3.2 为什么避免 castcontributing_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.typedpython -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, optionalNone作为实际取值时才写作default None短摘要必须以大写字母开头、以句点结尾、单行容纳且函数/方法必须以不定式动词开头如 Cast Series type. 而非 Casts Series type.示例Examples必须是确定性的、可复制运行的 Python 代码且遵循 doctest 规则表示代码、...表示续行、输出紧跟代码行。除 numpy 和 pandas 外其他库必须显式导入。一个符合规范的 docstring 范例取自 contributing_docstring.rst 中的head示例def head(self, n5): 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.pynumpydoc_validation_checks {all}。针对单个函数可快速验证python doc/make.py --warnings-are-errors --no-browser --single pandas.DataFrame.meandoctest 失败会成为 PR 合并的阻塞项因此 AGENTS.md 强调示例必须是确定性的——随机数据必须固定随机种子多行代码必须用...续行对象表示中不确定部分用...配合# doctest: ELLIPSIS代替。五、Pull Request 规范前缀体系与 AI 披露义务AGENTS.md 对 PR 提出了成体系的格式要求这在 AI 辅助贡献场景下尤为重要。5.1 描述性标题 强制前缀PR 标题必须描述清晰并带下列前缀之一前缀含义ENHEnhancement新增功能BUGBug fix缺陷修复DOC文档新增/更新TST测试新增/更新BLD构建流程/脚本更新PERF性能改进TYP类型标注CLN代码清理该前缀体系在 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 最容易越界的地方帮助编写代码、测试、文档是允许的但发表评论属于另一回事——详见 contributing.rst 的自动化贡献政策不得代用户在 GitHub Issue 或 PR 上发评论也不得代用户回复 reviewer不得替用户起草讨论发言让其直接粘贴**。正确的做法是在聊天中总结分析让用户用自己的话回应引用工具输出作为证据如 traceback 或建议的 diff时必须用引用块或三反引号代码块标注让读者区分哪些是用户自己的话翻译与语法编辑是上述规则的例外但仍须披露使用了工具。这条人机分工原则与 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 tmtest-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 辅助贡献流程可以归纳为读规范再动手先把 AGENTS.md 和 doc/source/development/contributing.rst 等四份文档载入上下文先认领、后开发在 Issue 评论/take认领再创建特性分支git checkout -b shiny-new-feature测试先行先写覆盖新行为的 pytest 测试函数式def test_*仅接受 fixture/参数用tm.assert_series_equal/tm.assert_frame_equal断言用pytest.raises验证异常、tm.assert_produces_warning验证告警代码遵循决策启发式小改动、可读性优先、破坏性变更走 deprecation 路径并附理由本地验证运行pre-commit run --files 修改的文件以及pytest pandas/path/to/test.py -k 用例名必要时跑类型检查mypy/pyright提交 PR 并披露使用 ENH/BUG/DOC 等前缀的标题简洁描述并链接 Issue勾选 AI 使用复选框按工具 模型版本 推理努力设置格式披露沟通留在聊天里把分析总结给用户由用户本人回复评审意见。这套流程既保证了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考