Harbor 项目贡献指南：在 AI 辅助编码时代写出能被合入的 PR

【免费下载链接】harborFramework for evaluating and improving agents项目地址https://gitcode.com/gh_mirrors/harbor17/harbor点击查看免费下载Harbor 是一个用于评估与改进 AI Agent 的开源框架支持 Claude Code、OpenHands、Codex CLI 等任意 Agent 的评估、基准测试接入、并行执行与 RL 优化。本文以仓库根目录的 CONTRIBUTING.md 为主体系统讲解 Harbor 社区如何管理 Issue 与 PR、如何在这种代码可以由 Agent 编写的工作流中贡献并被合入同时结合仓库内的开发环境配置AGENTS.md、pyproject.toml、CHANGELOG.md 与 rfcs/ 目录给出可落地的实操细节。读完本文你将掌握 Harbor 的 Golden Rule、Issue/PR 提交流程、RFC 设计讨论规范、CHANGELOG 更新策略以及一套完整的本地开发、测试与 lint 验证命令。Golden Rule你必须理解你贡献的代码Harbor 社区采纳了 Ghostty 项目的黄金法则Golden Rule你必须理解你贡献的代码。这一原则直接塑造了 Harbor 在 AI 辅助编码时代的分工方式——可以自由、大量地使用编码 Agent但最终由你来负责证明自己对代码的理解。贡献者被期望通过以下方式展示理解自己撰写 PR 描述而不是让 Agent 代写记录设计过程包括采用的技术路线与取舍approaches and tradeoffs提出干净的代码与良好的抽象——文档明确强调不做重度干预的编码 Agent 通常不会主动做到这一点如实披露使用了哪些 Agent 以及使用到什么程度。原文档还给出了一个前瞻性说明随着模型能力的提升社区可能会放宽这一约束——理想情况下可以信任 Agent 而无需人类理解代码但就 Harbor 团队的实践经验而言目前还没有达到这个阶段。从仓库的协作实践看这条原则贯穿始终例如 ADAPTER_CONTRIBUTING.mdAdapters 贡献规范同样是面向Agent 编写代码、人类负责把关的场景而设计的。沟通标准人类负责第一稿与最后一稿Harbor 对书面沟通有明确分工代码可以由 Agent 编写但文档、PR 描述、Issue 与评论应由人类在 AI 辅助下撰写。一条通用准则是人类负责第一稿first draft和最后一稿last draft中间过程可以交给 Agent。也就是说你可以在草拟与打磨阶段借助 Agent 加速但最终呈现给社区的文本质量与准确性由你负责。这既是质量控制手段也保证了 Issue 和 PR 中的信息对人类评审者和未来的维护者可读、可信。Issues报告问题与请求特性Issue 板块用于报告 bug 与请求新特性。按照上述沟通标准请自行撰写 Issue 描述的第一稿与最后一稿中间可自由使用 Agent。值得注意的一点是原文档强调你只需要理解问题本身the problem不一定要提出解决方案。在实现变得前所未有的容易的今天一个写得清楚的问题Issue往往比一个草率的 PR 更有价值——因为社区可以围绕准确的问题描述迭代出正确的实现。这一立场与 Harbor 以评估为核心的工程哲学一致先定义清楚要解决的问题与验收标准再谈实现。PR提高被合入概率的关键操作开启 fork 的 PR 时启用Allow edits by maintainers从 fork 提交 PR 时请勾选Allow edits by maintainers允许维护者编辑。这样维护者可以直接在你的分支上做小幅修正你的 PR 更有可能被合入也合入得更快。这是原文档中明确的、直接提升 PR 采纳率的实操建议。Agents、Sandboxes 与 Plugins 的合入政策Harbor 对集成integrations持相当开放的态度包括 Agent 集成与 Sandbox沙箱环境集成。唯一硬性要求是至少有一位真实用户请求过该集成——请提供证据例如让用户在该 PR 下留言。Plugins插件的门槛略高社区只计划维护高需求的插件。因此在提交插件类 PR 前建议先收集社区需求信号避免投入产出不匹配。接口与核心逻辑先讨论设计再动代码Harbor 不会轻易修改接口interfaces或核心逻辑core logic这一点对Harbor formatHarbor 任务/轨迹格式尤其严格。如果你要动这类代码先创建一个包含 RFC 的 PR 来开启设计讨论RFC 必须简洁concise且由人类在 AI 辅助下撰写——如果 RFC 是slop敷衍、低质量内容维护者会直接关闭它RFC 应放在仓库的 rfcs/ 目录下并遵循现有的命名约定。仓库中已有可参考的实例0001-trajectory-format.mdAgent Trajectory Interchange FormatATIF 轨迹交换格式规范包含完整的字段定义、版本历史与 schema 约束以及 0002-simulated-users.md基于 ACP 的模拟用户方案内含 CLI 示例与配置映射表。从中可以看出 Harbor 的 RFC 形态带元信息表状态、维护者、日期、changelog、精确定义的接口变更、breaking 迁移说明。遵循同样的命名NNNN-主题.md与结构你的 RFC 才符合社区预期。CHANGELOG.md只在必要时更新对于重大特性major feature或破坏性变更breaking change请在 CHANGELOG.md 的Unreleased段落中添加一条简洁的 bullet除此之外不要改动该文件。这意味着普通 bug 修复、小型内部重构不应污染 CHANGELOG维护者会据此快速判断 PR 的影响范围。仓库当前的 CHANGELOG.md 恰好展示了这类条目的写法例如 Unreleased 中关于独立的 verifier 镜像与构建定义优先于继承的 Agent 镜像、以及自定义 prompt 模板改用 Jinja sandbox等破坏性变更条目均以一句话概括变更 一句影响说明的形式呈现。模仿这种简洁、信息密度高的风格即可。提交前自检仓库的开发、测试与 lint 环境要让 PR 大概率被合入除了遵循上述流程还需要通过仓库的 CI 门槛。这些要求在仓库根目录的 AGENTS.md开发指引其首页即声明破坏性变更参见 CHANGELOG.md贡献规范参见 CONTRIBUTING.md中有完整定义可作为Golden Rule 可执行版本的实操配套。环境搭建# 安装依赖需要 Python 3.12 uv sync --all-extras --dev # 运行测试 uv run pytest tests/ # 带覆盖率运行 uv run pytest tests/ --covsrc/harbor --cov-reportterm-missing开发依赖在 pyproject.toml 中声明pytest8.4.2、pytest-asyncio、pytest-cov、pytest-xdist、ruff0.15.17、ty0.0.49等测试路径、标记与 pytest 行为--strict-markers、asyncio_mode auto也在同文件中配置。测试策略AGENTS.md 明确要求验证改动时默认只运行单元测试除非改动涉及集成测试覆盖的代码且确有必要# 单元测试验证改动的默认方式 uv run pytest tests/unit/ # 全部测试仅在必要时 uv run pytest tests/ # 指定标记 uv run pytest -m unit # 详细输出 uv run pytest -v --tbshort仓库定义了四种测试标记pyproject.toml 中配置标记含义pytest.mark.unit快速、无外部依赖pytest.mark.integration需要外部服务可 mockpytest.mark.runtime可能需要 Dockerpytest.mark.asyncio异步测试自动模式已启用此外有一条值得注意的测试纪律不要测试 CLI 帮助面板或命令控制台输出——Typer/Rich 的输出会随终端宽度、颜色与平台变化应测试命令行为、参数解析接线、回调效果或--json载荷。这既避免了脆弱的快照测试也符合理解你贡献的代码的初衷。代码风格与静态检查修改完代码后必须依次运行格式化、lint 与类型检查# 格式化 uv run ruff format . # Lint 并自动修复 uv run ruff check --fix . # 类型检查 uv run ty check关键约定包括Ruff 负责格式与 lintty负责类型检查第三方 import 需遵循isort规则known-first-party [harbor, ...]已在 pyproject.toml 中配置文件 I/O 优先使用Path.write_text()/Path.write_bytes()/Path.read_text()而非with open(...)内部不变式优先用会抛出清晰错误的显式if检查而非assert避免运行时守卫在优化执行下消失异步并发优先用asyncio.TaskGroup而非asyncio.gather日志默认用logger.debug仅对用户运行时必须可见的信息才用logger.info或更高等级。仓库在.github/workflows/下维护了对应的 CI 工作流pytest、ruff-format、ty、adapter-review、check-registry-format、pr-labeler、update-parity-summary 等因此本地跑通上述三件套基本等价于通过 PR 的自动化门槛。扩展Adapters 是另一条重要的贡献通道除了核心代码Harbor 有 50 个基准适配器adapters/目录将外部基准SWE-Bench、Terminal-Bench、Aider Polyglot 等转换为 Harbor 任务格式。完整的适配器贡献规范见 adapters/ADAPTER_CONTRIBUTING.md它同样遵循 Golden Rule适配器代码通常由 Agent 编写但人类需要理解每项任务的指令、环境、测试与参考解四个要素。快速上手的命令harbor dataset list # 列出可用数据集 harbor adapter init # 交互式脚手架 harbor adapter init my-adapter --name My Name # 非交互式脚手架适配器贡献者还需要提交adapter_metadata.json与parity_experiment.json一致性实验结果确保适配后的任务与原基准评分对齐。这与主贡献流程中的披露 Agent 使用情况同构——都是为了让评审者能够验证贡献者对代码的理解。总结一份高概率被合入的 PR 清单综合原文档与仓库实践提交 Harbor PR 前请对照以下清单理解你的代码亲手撰写 PR 描述记录设计过程与取舍披露所用 Agent 及程度沟通分级Issue/PR 描述/评论的第一稿与最后一稿由人类完成中间可借力 Agent从 fork 提交时勾选 Allow edits by maintainers新集成需有用户需求证据至少一位用户留言插件类集成需确认高需求涉及接口或核心逻辑尤其是 Harbor format时先提交简洁的人类撰写的 RFC放在 rfcs/ 并遵循命名约定重大特性或破坏性变更在 CHANGELOG.md 的 Unreleased 下添加一条简洁 bullet其余情况不动该文件本地验证uv run pytest tests/unit/uv run ruff check --fix .uv run ruff format .uv run ty check全部通过。这套流程的核心并不复杂Harbor 欢迎 AI 时代的协作方式但始终坚持人类对代码负责。遵循上述规则你的贡献——无论是一行修复、一个新适配器还是一份设计 RFC——都会更顺畅地进入这个评估 Agent 的框架。赞分享【免费下载链接】harborFramework for evaluating and improving agents项目地址https://gitcode.com/gh_mirrors/harbor17/harbor点击查看免费下载相关推荐OptiScaler跨GPU超分辨率技术框架的技术解析与实战指南OptiScaler跨GPU超分辨率技术框架的技术解析与实战指南 OptiScaler是一个创新的开源工具通过替换游戏内置的超分辨率技术让玩家能够在支持D图形学游戏开发Selenium 项目对 AI 辅助代码贡献有哪些要求Selenium 项目对 AI 辅助代码贡献有哪些要求 Selenium 官方明确允许贡献者使用 AI 工具Copilot、LLM、代码生成器等辅助编写代测试开发工具Open Notebook 贡献指南从 Ideas 讨论到可合入 PR 的协作流程、AI 辅助开发规范与代码质量红线Open Notebook 贡献指南从 Ideas 讨论到可合入 PR 的协作流程、AI 辅助开发规范与代码质量红线 Open Notebook仓库根目录即人工智能AI 应用RAG后端前端上一篇从零开始打造终极React 360全景视频播放器完整开发指南下一篇deepTools与其他生物信息工具的对比选择最适合你的分析工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考