sproutclaw/CONTRIBUTING.md

贡献指南

本指南旨在为双方节省时间。

设计理念

首先明确一点：SproutClaw 的核心保持精简。

如果你的功能不属于核心，它应该以扩展的形式实现。会让核心臃肿的 PR 大概率会被拒绝。

SproutClaw 的核心存在的意义在于精简且可扩展，以便扩展能够影响和定制其行为。即便是扩展的 hook 点也需要经过充分考量和讨论，避免引入难以维护的冗余代码和复杂交互。

唯一准则

你必须理解自己提交的代码。 如果你无法解释你的改动做了什么、以及它与系统其他部分如何交互，你的 PR 将被关闭。

使用 AI 辅助编写代码没有问题，但在不理解代码的情况下直接提交 AI 生成的内容是不被接受的。

如果你使用 Agent，请在 sproutclaw 根目录运行，这样它会自动读取 AGENTS.md。你的 Agent 必须遵循该文件中的规则和指南。

贡献门槛

来自新贡献者的 issue 和 PR 默认会被自动关闭。

周五至周日提交的 issue 不保证会被审查。如有紧急问题，请在内部联系维护者。

维护者会每日审查被自动关闭的 issue，并重新开放值得处理的内容。不符合以下质量标准的 issue 将不会被重新开放或收到回复。

审批通过由维护者在 issue 中回复：

• lgtmi：你未来提交的 issue 将不再被自动关闭
• lgtm：你未来提交的 issue 和 PR 将不再被自动关闭

lgtmi 不授予提交 PR 的权限，只有 lgtm 才授予该权限。

Issue 质量标准

提交 issue 时，必须使用两个 GitHub issue 模板之一。

提交的 issue 应简洁、具体、有阅读价值：

• 保持简短。如果超过一屏，就太长了。
• 用自己的语言表达（不要用 LLM 生成文本；如果必须，请在后续评论中明确标注为 AI 生成）。
• 清晰说明 bug 或需求。
• 解释其重要性。
• 如果你希望自己来实现，请说明。

如果 issue 真实且表述良好，维护者可能会重新开放、回复 lgtmi 或回复 lgtm。

封禁规则

如果你两次无视本文档，或通过 Agent 批量刷 issue，你的账号将被永久封禁。

如果你通过自动化手段大量提交 issue，你的账号将被永久封禁，且不可申诉。

提交 PR 前

未获得 lgtm 批准前，请勿提交 PR。

提交 PR 前，请先执行：

npm run check
./test.sh

两项均须通过。

不要修改 CHANGELOG.md，更新日志条目由维护者添加。

如果你要在 packages/ai 中添加新的 provider，请参阅 AGENTS.md 中关于必要测试的说明。

有疑问？

请联系项目维护者。

常见问题

为什么新 issue 和 PR 会被自动关闭？

SproutClaw 收到的 issue 数量超过维护者能够实时处理的上限。许多报告不符合本指南的质量标准，或者是通过 Agent 随意提交而未经本人审查和整理的。自动关闭机制让维护者可以按自己的节奏审查，并重新开放符合质量要求的 issue。

为什么周末的 issue 优先级较低？

维护者在工作时间处理 issue。周末可能积累更多未处理内容，周五至周日提交的 issue 可能在周一审查时被遗漏或优先级降低。如有紧急问题，请直接联系维护者并附上简要描述、复现步骤和相关日志。

为什么有些 issue 没有收到回复？

回复本身也是一种维护成本。低质量 issue、表述不清的报告、重复 issue 以及不遵循本指南的 issue 可能被直接关闭而不作说明。这样可以将时间留给可复现的 bug、深思熟虑的需求，以及真正用心整理报告的贡献者。

为什么不用 AI 来做所有分类工作？

AI 可以帮助归纳重复内容、汇总报告、发现缺失信息，但不被信任来做最终的维护决策。经过润色的 AI 生成 issue 仍然可能是错误的、有误导性的，或需要大量时间排查。人工审查始终是最终把关环节。

这对贡献者是否过于苛刻？

不是。这是防止维护者精力耗尽和 issue 刷屏的保护机制。简洁、具体、可复现的 issue 是受欢迎的，有深度的贡献同样受欢迎。自动化生成的低质量内容、无理取闹以及大量低价值报告则不被接受。