shumengya
812bca79a3
Some checks failed
CI / build-check-test (push) Has been cancelled
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
98 lines
4.3 KiB
Markdown
98 lines
4.3 KiB
Markdown
# 贡献指南
|
||
|
||
本指南旨在为双方节省时间。
|
||
|
||
## 设计理念
|
||
|
||
首先明确一点：**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 前，请先执行：
|
||
|
||
```bash
|
||
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 是受欢迎的，有深度的贡献同样受欢迎。自动化生成的低质量内容、无理取闹以及大量低价值报告则不被接受。
|