English version: CONTRIBUTING.md
环境搭建请参考 docs/contributing/development.md，你需要：
每个 PR 只能包含一个不可再拆的 feature 或一个 bug fix。
判断方法： 问自己（或 AI）："这个 diff 能否拆成多个独立可合并的 PR？" 如果能，提交前必须拆分。
可接受（单个 PR）：
- 一个根因的 bug 修复，即使涉及多个文件（例如修复 toast 在 modal 和聊天层的 z-index 问题）
- 一个完整的功能（例如团队创建弹窗及其表单校验）
必须拆分成多个 PR：
- 团队聊天滚动修复 + Sentry 用户追踪 + Office 预览性能优化 = 3 个 PR
- 多个不相关的 bug 修复打包在一起（例如标题栏导航修复 + i18n 缺失 key + 语音输入 UI 修复）
- 独立的技术层（例如 IPC 桥接重构 + 渲染进程组件 + Worker 进程变更，分属不相关的功能）
CI 会在这些检查失败时拒绝你的 PR。推送前在本地运行，节省时间。
# 1. 格式化（必须运行 — 覆盖 .ts, .tsx, .css, .json, .md）
bun run format
# 2. Lint 检查（如果没改 .ts/.tsx 文件可跳过）
bun run lint
# 3. 类型检查（如果没改 .ts/.tsx 文件可跳过）
bunx tsc --noEmit
# 4. i18n 校验（仅当修改了 src/renderer/、locales/ 或 src/common/config/i18n/ 下的文件时）
bun run i18n:types
node scripts/check-i18n.js
# 5. 测试
bunx vitest run完全复刻 CI 质量检查，再跑测试：
prek run --from-ref origin/main --to-ref HEAD
bunx vitest run
prek以只读模式运行 format-check + lint + tsc。如果报错，先运行上面的自动修复命令，再重新运行 prek。
| 失败类型 | 修复方法 |
|---|---|
| 格式错误 | bun run format（自动修复） |
| Lint 错误 | bun run lint:fix 修复可自动修复的部分，其余手动修复 |
| 类型错误 | 修复 TypeScript 问题，重新运行 bunx tsc --noEmit |
| i18n 错误 | 检查缺失的 key，运行 bun run i18n:types 重新生成类型 |
| 测试失败 | 修复失败的测试或实现，重新运行 bunx vitest run |
如果你使用 Claude Code，运行 /oss-pr 即可自动完成全部检查 + 提交 + PR 流程。
本仓库运行 PR 自动化 bot，自动 review、修复小问题、准备合并。你的 PR 上可能出现以下 label：
| Label | 含义 | 需要的操作 |
|---|---|---|
bot:reviewing |
Bot 正在 review 你的 PR | 等待 |
bot:ci-waiting |
CI 失败，bot 等你修复 | 推送新 commit 修复 CI |
bot:needs-rebase |
有合并冲突，bot 无法自动 rebase | 将分支 rebase 到 main 后推送 |
bot:needs-human-review |
发现阻塞性问题 | 维护者会介入审查并评论 |
bot:ready-to-merge |
所有检查已通过 | 维护者会在准备好后合并 |
完整自动化流程请参考 docs/contributing/pr-automation.md。
不符合规则时，维护者可能：
- 关闭并要求重新提交（首选）—— 正确重提后你保留全部署名。
- Cherry-pick 有价值的部分 —— 你的作者信息保留在 git 历史中，但原 PR 显示为 "Closed" 而非 "Merged"。
代码风格、依赖选择、文档润色由维护者在合并后处理。你的 PR 只需聚焦功能变更本身。