oh-my-pi 贡献指南：PR 流程、AI 辅助开发规范与 MIT 许可实践

oh-my-pi 贡献指南：PR 流程、AI 辅助开发规范与 MIT 许可实践

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi

本指南基于 oh-my-pi 仓库根目录的 CONTRIBUTING.md 展开，系统讲解这个"Coding agent with the IDE wired in"项目的社区贡献规范：从 PR 提交前如何界定改动范围、为何不要为即将自己动手的工作开 Issue，到 AI 辅助贡献必须满足的审查义务、PR 验收标准与贡献许可政策。读完本文，你将完整掌握向 oh-my-pi 提交一个合格 PR 的全流程，并了解项目维护者在评审时的实际关注点，从而避免"改了不少、却被一键关闭"的常见返工。

项目定位与贡献入口

oh-my-pi 是一个终端内的编程 Agent 产品，核心 CLI 是omp，主包位于 packages/coding-agent，配套的模型目录、Agent 运行时、TUI 渲染库、原生 Rust 加速层分布在 packages 与 crates 下。仓库根目录的 AGENTS.md 明确规定：除非特别说明，所有开发工作默认聚焦于packages/coding-agent/。

CONTRIBUTING.md 是该项目唯一的贡献总入口，它规定了三类事项：何时需要提前讨论、PR 必须满足的硬性要求、以及代码归属与许可政策。与很多项目不同，这份文档将大量篇幅用于约束AI 辅助提交——这与项目自身就是 Agent 产品高度相关：项目维护者既欢迎 AI 参与开发，又严格防止"无人负责的自动提交"污染代码库。

开始之前：小改动与大改动的分界线

CONTRIBUTING.md 将改动按规模分为两类，处理方式截然不同：

• 小改动（可直接提 PR）：Bug 修复、文档更新、范围狭窄的改进。这类改动不需要事前讨论，可以直接进入 Pull Request 流程。
• 大改动（必须先讨论）：涉及新子系统、大规模 UI 改动、新增依赖、跨多个 package 的改动，以及任何架构性/行为性变更。文档明确要求：在动手写实现之前，先到 Discord 讨论方案（文档中给出的讨论渠道为discord.gg/4NMW9cdXZa）。

这里有一条关键提醒：GitHub Issue 不能替代事前讨论，且事前讨论并不保证 PR 会被合并。也就是说，讨论是准入条件，而非通行证；最终是否合并仍取决于提交质量与维护者评审。

这一"小步快跑、大动先行"的机制与仓库的物理结构一致：项目由十几个 package 组成（见 AGENTS.md 的包结构表），跨包改动牵一发而动全身，例如packages/ai、packages/catalog、packages/coding-agent之间存在严格的依赖约定（模型/提供商策略必须放在 KDL 规则树而非 TypeScript 里），随意跨包改动的代价远高于单包内的小修。

不要为自己即将提交的工作开 Issue

CONTRIBUTING.md 有一条容易被忽略但非常实际的规定：如果你打算自己实现某个改动，不要先为它创建 Issue。

原因是：仓库的自动化工具robomp会把可行动的 Issue 视为"待认领工作"并可能并行启动相同的修复，从而造成重复劳动、浪费计算资源与维护者时间。正确的做法是：

• 报告问题、或提出自己不打算亲手实现的改动→ 开 Issue；
• 已存在相关 Issue 时→ 在 PR 中链接它，而不是另开一个重复的 Issue；
• 打算自己实现→ 直接走 PR 流程（大改动先讨论，小改动直接提交）。

这条规则背后是 Agent 工作流特有的协作成本：当一个仓库同时存在自动化代理与人类贡献者时，Issue 既是"问题清单"也是"工作队列"，二者不加区分会导致同一修复被抢跑两次。

AI 辅助贡献：工具可用，但责任在提交者

这是 CONTRIBUTING.md 的核心章节，也最贴合 oh-my-pi 的 Agent 基因。项目态度明确：欢迎 AI 作为工具参与，但不接受无人值守的自动贡献。禁止的做法是"给 Agent 一个模糊目标，然后把它产出的一切原样提交"。

在打开 PR 之前，贡献者必须完成四步人工闭环：

1. 限定范围：把 Agent 约束到已商定的范围，拒绝无关改动；
2. 逐文件审查：审阅每一个被改动的文件，理解最终行为；
3. 亲自验证：运行相关检查、亲手操练被改动的行为；
4. 人工提交：审查通过后由人提交 PR，而不是让 Agent 自主发布。

文档用一句话总结了责任边界："无论代码由谁或什么生成，你都要对代码负责"（You are responsible for the code, regardless of who or what generated it）。

PR 说明必须包含一句人写的解释

每个 PR 的正文必须包含至少一句由你用自己的话撰写的句子，说明改了什么、为什么。以下内容不能替代这句人工说明：

• 自动生成的摘要；
• 粘贴的 Agent 对话记录；
• 单独的 checklist。

一句诚实的话就够了，文档给出了示例：

I reviewed the full diff; this change fixes duplicate PR reviews by reusing the existing delivery guard.

这句话的价值在于证明提交者确实审阅过 diff、理解改动意图，而非盲目转发 Agent 的输出。

验证要求：bun check通过不等于行为正确

CONTRIBUTING.md 明确警告："bun check通过了"本身不是充分的验证。bun check和自动化测试在相关时是"预期动作"，但它们不能证明行为按预期工作。贡献者必须自己走通被改动的路径，并在 PR 中报告确切的场景与结果：

从仓库证据看，"bun check"作为类型检查门禁有其具体定义：packages/coding-agent/package.json 中check脚本是oxlint . && oxfmt --check ... && bun run check:types（check:types走tsgo），即 lint + 格式 + 类型三层检查。项目规定永远不要直接调用tsc/npx tsc，一律以bun run check为类型检查门禁。

开发者常用命令速查

CONTRIBUTING.md 将本地开发命令指引到 packages/coding-agent/DEVELOPMENT.md，这份"开发者地图"给出了完整的本地开发循环命令表（在packages/coding-agent/目录下运行，或加--cwd=packages/coding-agent）：

另有两条与 Agent 产品强相关的注意事项：改动 React 工具渲染器后需用bun run gen:tool-views重建（涉及collab-web/src/tool-render/）；Rust 测试不要直接跑cargo test，而要使用bun run test:rs（内部以cargo nextest跑测试、再补一轮cargo test --doc）。

提交前后的质量红线（来自 AGENTS.md）

虽然 CONTRIBUTING.md 是贡献主文档，但仓库根目录的 AGENTS.md 补充了大量与"可评审、可维护"直接相关的硬性约束，贡献者应一并遵守：

• 除非被要求，绝不评论/创建 GitHub Issue；
• 绝不擅自 commit，未被要求时不要执行提交动作；
• 生成的代码质量：不用any（除非万不得已）、不用ReturnType<>、不用内联 import；prompt 一律放在静态.md文件中用 Handlebars 做动态渲染，禁止在代码里拼接 prompt 字符串；
• 日志：可能运行在 TUI/RPC/SDK/worker 中的代码不得使用console.log/error/warn，必须使用@oh-my-pi/pi-utils的集中式logger（日志写入~/.omp/logs/omp.YYYY-MM-DD.log并自动轮转）；
• 测试纪律：每个新测试必须捍卫一个具体的、可外部观察的契约（行为、输出形态、状态迁移、错误映射或易回归的解析边界）；禁止"静态回声"测试、禁止expect(true).toBe(true)式占位、禁止对源码文本做 grep 断言。

这些规则解释了 CONTRIBUTING.md 为何要求"理解你提交的工作"——项目用测试规范把"行为正确"提升为硬性门槛，而非只看代码能否编译。

贡献许可：MIT，无需 CLA/DCO

oh-my-pi 的贡献许可政策（Contribution licensing）要点如下：

• 有意提交以纳入 OMP（oh-my-pi）的贡献，默认按 MIT License 授权；
• 该政策不会重新授权第三方或 vendored 代码；
• 提交者必须有权提交自己的贡献，并保留适用的版权、许可、署名与声明材料；
• 提交贡献不需要签署 CLA（Contributor License Agreement）或 DCO（Developer Certificate of Origin）。

仓库根目录的 LICENSE 即为 MIT License（Copyright 2025 Mario Zechner、2025-2026 Can Bölük、2026 Stencil Labs, Inc.），与文档所述一致。对于开发者而言，这意味着：你只需确保自己拥有所提交代码的权利，贡献一经合入即按 MIT 条款被项目使用，无需任何额外签约流程。

评审：评审行为与理解，而非代码量

Review 章节定义了 oh-my-pi 的评审哲学：维护者评审的是"所提交的行为"和"贡献者对它的理解"，而不是生成代码的数量。

具体动作要求：

• 亲自回应评审反馈：由你自己回应 review 意见，且只采纳你已核实过的建议；
• 维护者会关闭 PR 的典型情形包括：
  • 跳过了要求的事前讨论；
  • 缺少人工撰写的解释说明；
  • 包含未经审查的 Agent 输出；
  • 混杂了无关的改动。

最后一条"保持每个 PR 只做一件逻辑改动"（one logical change per PR）贯穿全文：避免无关清理、顺手重构、生成噪音，以及不在约定范围内的功能。

当前开放状态：担保制度（vouch）的试验性放宽

CONTRIBUTING.md 与 README.md 都标注了同一则 NOTE：PR 目前作为试验，暂时向所有人开放。此前项目要求在合并 PR 前必须有成员担保（vouch），该要求在评估开放贡献效果期间暂时解除，视结果而定，担保制度可能回归。这意味着：当前阶段是社区贡献的低门槛窗口期，但贡献者仍须满足上述全部 PR 硬性要求。

结语：给 oh-my-pi 贡献者的行动清单

综合 CONTRIBUTING.md 及其引用的仓库证据，一个合格的 oh-my-pi 贡献流程可以浓缩为六步：

1. 判定规模：小改动直接提 PR；涉及新子系统、跨包、新依赖的大改动，先到 Discord 讨论；
2. 不要抢跑：自己要做的改动不开 Issue，已有相关 Issue 就在 PR 中链接；
3. 约束 Agent：若用 AI 辅助，限定范围、逐文件审查、亲自验证、人工提交，并在 PR 中写一句自己的解释；
4. 验证行为：以bun run check通过为前提，再亲手复现 Bug / 端到端使用功能 / 交互检查 UI，并在 PR 里报告场景与结果；
5. 单点聚焦：每个 PR 只含一个逻辑改动，不夹带无关重构；
6. 回应评审：亲自回复 review，只采纳自己核实过的建议，并留意 PR 暂时全开放、担保制度可能回归的政策变化。

按此流程提交，你的贡献将同时满足工具链门禁（lint/类型/测试）、行为验证与社区协作三重要求——这正是 oh-my-pi 作为一个由 Agent 驱动开发的项目，对每一位贡献者（无论人类还是 AI 辅助）的完整期望。

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi