[wangl-cc]

Requested by Loong · project thread

动机 / Motivation

仓库没有 PR 模板，也没有写明对贡献的约定。随着 AI 工具普及，PR 的规模和数量都在增加，维护者 review 的负担也随之加重。需要一个地方写明约定，让贡献者提交前知道我们的期望，也让维护者在 review 时有据可依。

方案 / Solution

• CONTRIBUTING.md：中英文分节，列出 5 条约定（大改动先在 issue 讨论方案、一个 PR 只做一件事、欢迎使用 AI 但需作者本人审阅、描述简洁、用自己的话回复 review），以及不符合约定时的处理方式。规则编号，方便 review 时引用。修 bug、文档和小改进不受「先开 issue」约束。
• .github/pull_request_template.md：中英双语的「动机 / 方案 / 变更与影响」三节、两条检查项（只含必要改动、同步多语言文档）和「AI 辅助」一节（未使用 AI，或已亲自审阅 AI 生成的改动二选一）。自动化测试由 CI 覆盖，不单设验证一节；只有涉及设备连接或平台相关的改动，才需要在「变更与影响」中说明实测情况。小改动只需填写动机。
• AGENTS.md：新增给 agent 的贡献规则，比如没有已认可的设计时先停下、在人看完 diff 前不开 PR、不替人勾自审检查项、不代写 review 回复。agent 会自动读 AGENTS.md，但不一定会打开 CONTRIBUTING。
• DEVELOPMENT.md：注意事项里加上 CONTRIBUTING 的链接。
• .github/.markdownlint.yaml：继承根目录配置，对 .github/ 下的文件关闭 MD041（首行必须是一级标题），因为模板不以一级标题开头。

不确定的地方：「约 500 行」和「review 后 30 天无回应」这两个数字是经验值，可以再调整。

变更与影响 / Changes and impact

新开的 PR 会自动带上模板，GitHub 也会在开 PR 时提示 CONTRIBUTING。代码没有改动。

检查项 / Checklist

• 本 PR 只包含实现上述目的所需的改动，无关的修复或重构已拆出 / This PR only contains changes needed for the purpose above; unrelated fixes and refactors are split out
• 改了用户可见行为的话，已同步更新 crates/maa-cli/docs/ 下所有语言的文档 / User-visible behavior changed: docs under crates/maa-cli/docs/ are updated for every language（不涉及 / N/A）

AI 辅助 / AI assistance

• 未使用 AI / No AI used
• 使用了 AI，我已亲自审阅并整理全部改动，能解释每一处修改 / AI was used, and I have personally reviewed and cleaned up all changes and can explain each of them
  • AI 编写的部分 / AI-written parts: 全部文件由 Claude Code 起草，内容和措辞经 @wangl-cc 多轮修改

🤖 Generated with Claude Code

https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA

Sourcery 总结

统一人类和 AI 辅助贡献的贡献规范与拉取请求准备要求。

新功能：

• 新增双语贡献指南，明确 PR 范围、设计讨论、作者对 AI 辅助修改的审核、简洁的描述，以及对评审意见的回复要求。
• 新增双语拉取请求模板，涵盖动机、解决方案、影响、验证、范围检查、文档更新和 AI 辅助情况。

改进：

• 新增针对智能体的贡献规则，要求发布前由人工审核、较大改动事先达成设计共识、保持差异聚焦，并由作者撰写评审回复。
• 在开发文档中链接新的贡献指南。

构建：

• 新增 GitHub 专用的 Markdown lint 配置，允许模板不包含顶层标题。

文档：

• 说明维护者的期望，以及未遵循贡献规范的 PR 可能会如何处理。

Original summary in English

Sourcery 摘要

为人工贡献和 AI 辅助贡献制定清晰的双语贡献规范与 PR 准备指南。

新功能：

• 添加双语贡献指南，涵盖 PR 范围、设计讨论、作者对 AI 辅助变更的审查、简洁的描述以及评审回复。
• 添加双语拉取请求模板，涵盖动机、解决方案、影响、范围与文档检查，以及 AI 辅助情况说明。

增强：

• 添加针对智能体的贡献规则，要求重大变更须先就设计达成一致、保持差异内容聚焦、发布前由人工审查，并由作者撰写评审回复。
• 在开发文档中添加指向贡献指南的链接。

构建：

• 添加 GitHub Markdown lint 配置，允许 PR 模板不包含顶级标题。

文档：

• 说明维护者的预期，以及对不遵循贡献规范的 PR 可能采取的处理方式。

Original summary in English

Summary by Sourcery

Establish clear bilingual contribution standards and PR preparation guidance for both human and AI-assisted contributions.

New Features:

• Add bilingual contribution guidelines covering PR scope, design discussion, author review of AI-assisted changes, concise descriptions, and review responses.
• Add a bilingual pull request template covering motivation, solution, impact, scope and documentation checks, and AI assistance disclosure.

Enhancements:

• Add agent-specific contribution rules requiring agreed designs for substantial changes, focused diffs, human review before publication, and author-written review replies.
• Link the contribution guidelines from the development documentation.

Build:

• Add GitHub Markdown lint configuration allowing PR templates without a top-level heading.

Documentation:

• Document maintainer expectations and how PRs that do not follow contribution conventions may be handled.

[sourcery-ai]

你好——我已经审阅了你的更改，整体看起来很棒！

---

Sourcery 对开源项目免费——如果你喜欢我们的评审，欢迎分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

Original comment in English

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook