Ray 的 AI 辅助贡献规范与实践读懂 AGENTS.md正确提交 AI 协作 PR【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/rayRay 是一个高流量、多语言混合的 AI 计算引擎仓库C 核心运行时 Python API 与 AI 库 Java/Serve 生态每一次 PR 都会通知 CODEOWNERS、触发 CI 并消耗维护者精力。为了让 AI 辅助贡献AI-assisted contribution不成为维护者的负担Ray 在仓库根目录维护了 AGENTS.md 这一份对所有 AI 协助工作具有强制约束力的指令文件。本文将逐节解析这份规范的核心条款、可执行的命令行操作、与仓库内.claude/协作基础设施和 CI/git hooks 的对应关系并给出一份可直接套用的 AI 辅助贡献检查清单帮助你以符合社区预期的方式提交高质量 PR。AGENTS.md 是什么一份对 AI 贡献全局生效的指令AGENTS.md 开篇即声明其适用范围These instructions apply toallAI-assisted contributions toray-project/ray. PRs that ignore this policy may be closed without review.也就是说只要 PR 过程中使用了 AI 辅助包括代码生成、自动补全、批量重构等就必须遵守该文件违反政策的 PR 可能被不经过评审直接关闭。这一约束在仓库内有多处落地证据.claude/CLAUDE.md 的正文仅有一行../AGENTS.md通过 Claude Code 的 include 语法把 AGENTS.md 作为根指令加载到每个会话上下文中贡献指南 doc/source/ray-contribute/getting-involved.md 专门设有 AI-assisted contributions 一节用literalinclude将 AGENTS.md 全文内嵌向所有贡献者明示工具会被注入的规则doc/source/ray-contribute/agent-development.md 则从如何使用 AI agent 开发 Ray的角度补充了.claude/目录、skills、rules 的配置方法。理解这份文件的动机很关键Ray 是高频仓库自动化、低价值或重复的贡献会真实地消耗维护者注意力因此规范的核心是**把 AI 的产出提升到可评审的质量门槛之上**。贡献政策提交 AI 辅助 PR 前的强制检查重复工作检查在提出任何 PR 之前必须确认该工作尚未在途。AGENTS.md 给出了基于 GitHub CLIgh的两条检查命令# 如果你在解决某个已存在的 issue gh issue view issue_number --repo ray-project/ray --comments gh pr list --repo ray-project/ray --state open --search issue_number in:body # 在动手之前先搜索同一领域已打开的 PR gh pr list --repo ray-project/ray --state open --search short area keywords规则要点如果已有一个 PR 在解决同样的变更不要另开 PR改为在既有 PR 上评论如果你的方案与既有 PR 有实质差异必须先在该 issue 或既有 PR 的讨论线程中说明差异再考虑开竞争性 PR。这与 CONTRIBUTING.rst 中先通过 issue/PR 渠道对齐、再动手写代码的社区惯例一脉相承只是把这一要求显式化、可执行化。禁止低价值 busywork PR不要为琐碎改动单独开 PR一个拼写错误、孤立的风格调整、一个可变默认参数、孤立的类型注解等。机械式清理只有在与实质性工作捆绑、或事先与维护者协调时才可接受批量生成的 cleanup PR 不受欢迎。这条政策直接回应了 LLM 批量刷 PR 的典型滥用场景也从侧面说明了评审资源的稀缺性。人类问责制AGENTS.md 明确写了两条红线纯 code-agent PR 不被允许必须有一位人类提交者能端到端地理解并捍卫这项变更提交者义务人类提交者必须逐行 review 每一处改动并在请求评审前本地运行相关测试。此外AI 辅助工作的 PR 描述必须声明三件事为什么这不是对既有 issue/PR 的重复运行过的测试命令及其结果使用了 AI 辅助。Fail-closed 行为如果请求的工作属于重复、琐碎 busywork、或无法由人类测试和捍卫不要开 PR而是返回一段简短说明指出缺少了什么。这一默认拒绝的保守策略是 AGENTS.md 全篇的行为底线。开发工作流与仓库实际布局的对应AGENTS.md 第 2 节给出了 Ray 的源码布局这也是后续定位代码、运行测试的路径基础src/ray/C 核心运行时python/ray/Python API 与库data、serve、train、tunerllib/RLlib符号链接自python/ray/rllibdoc/source/Sphinx 文档。测试超时约定AGENTS.md 指出默认测试超时是 180 秒依据是 pytest.ini 中的timeout 180。同一文件中还配置了filterwarnings error将警告视为错误、asyncio_mode auto自动为 async 测试函数装饰pytest.mark.asyncio这些细节在编写和运行测试时都应当遵守。每个 commit 的硬性要求DCO 签名Developer Certificate of Origin所有 commit 必须带Signed-off-by尾注提交时始终使用-sgit commit -s -m Your commit message仓库为此提供了自动化支撑setup_hooks.sh 会把 ci/lint/pre-push 和ci/lint/prepare-commit-msg符号链接到.git/hooks/下——其中prepare-commit-msg负责自动追加签名尾注pre-push负责在推送前强制执行 lint。如果你跳过了 hook就必须手动用git commit -s补上签名否则无法通过 DCO 检查。pre-commit hooks安装后 hooks 会在 commit 时自动对暂存文件运行pip install -U pre-commit3.5.0 pre-commit install pre-commit run社区文档 doc/source/ray-contribute/getting-involved.md 还补充了更细的用法例如pre-commit run ruff -a自动修复 ruff 可修复的问题以及 C 侧需要 clang-format/clang-tidy 12 版本、Bazel 格式检查脚本 ci/lint/bazel-format.sh、clang-tidy 检查脚本 ci/lint/check-git-clang-tidy-output.sh 等不在 pre-commit 内的额外检查。Python 环境所有 Python 开发都必须使用虚拟环境严禁安装到系统 Python。相关文档入口AGENTS.md 明确不重复造轮子而是指向仓库内既有指南开发环境与代码风格doc/source/ray-contribute/getting-involved.md构建 Raydoc/source/ray-contribute/development.md通用贡献流程CONTRIBUTING.rst。配套的 AI 协作基础设施AGENTS.md 之外的工程化支撑AGENTS.md 定义了规则而仓库内的 .claude/ 目录提供了承载这些规则的工程化配置详见 doc/source/ray-contribute/agent-development.md.claude/CLAUDE.md根指令仅一行../AGENTS.md每个会话自动加载.claude/rules/按文件类型/目录生效的编码规则例如python-guidelines.md、security.md、timing.md支持用pathsfrontmatter 限定作用范围.claude/skills/按需加载的可复用工作流仓库内已提供rebuild按变更文件引导重建 Ray、lint运行 lint/格式化检查、fetch-buildkite-logs拉取 Buildkite CI 日志、backport-docs把已合入的文档 cherry-pick 到发布分支、ray-dependencies.claude/agents/项目专属 subagents。对贡献者而言这意味着即使不使用 Claude CodeAGENTS.md 的规范也是统一的而如果使用支持 AGENTS.md 约定的工具getting-involved.md 中特别提到 Claude Code 通过.claude/CLAUDE.md加载这些 skills/rules 会自动成为工作流的一部分例如/rebuild可以显著降低改一行 C 却不知道如何正确重建的摩擦。AI 辅助贡献检查清单从想法到合入综合 AGENTS.md 全文与仓库配套文档一份可执行的 AI 辅助贡献流程如下查重用gh issue view/gh pr list确认目标 issue/PR 无人处理或既有 PR 方案与你有实质差异且已在线程中说明立项判断评估工作是否属于琐碎 busywork单个拼写、孤立注解等如是则并入实质性工作或先与维护者协调环境准备创建虚拟环境安装 pre-commit 3.5.0 并pre-commit install运行 setup_hooks.sh 启用 pre-push 与签名 hook开发与测试在 src/ray/、python/ray/、rllib/ 对应位置修改代码本地运行相关测试Python 用python -m pytest -v -s test_file.py::test_nameC 用bazel test $(bazel query kind(cc_test, ...)) --test_filterTestName --test_outputstreamed注意 180 秒默认超时约束签名提交git commit -s -m ...确保每个 commit 带 DCO 尾注写 PR 描述声明a不重复的理由、b运行过的测试命令与结果、c使用了 AI 辅助人类终审逐行 review 所有 AI 生成的改动确保能端到端解释变更Fail-closed若以上任何一步无法满足不提交 PR而是说明缺失项。修改 AGENTS.md 本身的流程最后值得单独说明的是AGENTS.md 的任何改动都会影响所有 AI 辅助贡献。因此仓库要求对其修改走专门的 PR说明修改动机并 tag 负责贡献政策contribution policy的维护者评审。也就是说这份文件自身也是受治理的对象不应夹带在功能 PR 里顺手改动。总结AGENTS.md 是 Ray 面向 AI 辅助贡献者的一份行为契约它用强制条款查重、禁 busywork、人类问责、fail-closed划定了贡献的质量底线用开发工作流DCO、pre-commit、虚拟环境、测试超时规定了工程化红线并通过 .claude/ 目录和 doc/source/ray-contribute/agent-development.md 提供了可落地的工具支撑。对任何打算向 Ray 提交 AI 辅助 PR 的开发者而言先通读这份文件、再把上述检查清单走一遍是让 PR 获得评审机会而非被直接关闭的前提。【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考