# 贡献说明

[English](./CONTRIBUTING.md)

感谢你为 DeepSeek GUI 做贡献。

这份文档说明了贡献者应该如何协作、遵循什么标准，以及改动应如何提交。

## 项目品味

代码不难，难得的是好品味。

在 DeepSeek GUI 里，品味意味着清晰的流程、克制的界面、自然的文案，以及用一次就能理解的行为。好的贡献不只是把功能做出来，也要体现判断力。

## 贡献范围

欢迎以下方向的贡献：

- 缺陷修复
- UI / UX 优化
- 运行时集成改进
- 文档补充与修订
- 本地化内容完善
- 构建和发布流程优化

## 分支策略

建议采用以下分支流转方式：

- `develop`：协作与日常集成分支
- `master`：稳定发布分支，由维护者从 `develop` 合入
- 功能分支：可选，从 `develop` 拉出的短期分支

规则如下：

- 不要直接在 `master` 上开发
- 日常开发优先从最新 `develop` 开始
- 如果要建立功能分支，应从 `develop` 拉出
- 除非维护者明确指定，否则 PR 默认提到 `develop`

## 开始之前

1. 先确保本地仓库已同步到最新状态。
2. 切换到 `develop` 分支。
3. 运行 `npm install` 安装依赖。
4. 在修改前先确认项目可以正常启动或构建。

## 典型 PR 的结构

一个结构良好的 DeepSeek GUI PR 应该聚焦且自包含。通常：

- 涉及 **1-3 个新文件**，修改 **2-5 个现有文件**进行接入
- 范围限定在单个功能、修复或文档更新
- 如果界面有变化，附带视频或 GIF
- 如果项目逻辑有变化，附带单元测试
- 通过 `npm run typecheck`、`npm run build` 和 `npm run test`

如果在开发过程中发现其他需要处理的问题，请单独开 issue，不要扩大当前 PR 的范围。

## 本地开发检查清单

在发起 PR 之前，贡献者应至少确认：

- 应用可通过 `npm run dev` 正常开发运行
- `npm run typecheck` 通过
- `npm run build` 通过
- `npm run test` 通过
- UI 改动已附带展示变更流程的视频或 GIF
- 逻辑改动已为变更行为补充单元测试
- 如果改动影响使用方式、安装方式或流程，已同步更新文档
- 如果改动影响用户可见文案，已同步更新本地化内容

### CI 验证命令

```bash
# 类型检查
npm run typecheck

# 生产构建
npm run build

# 单元测试
npm run test

# 完整开发冒烟测试
npm run dev
```

## 代码要求

- 改动尽量聚焦、范围清晰
- 不要在同一个 PR 里夹带无关重构
- 尽量遵循现有项目结构和命名方式
- 优先写易读、易维护的代码
- 尽量保持跨平台行为一致
- 不要提交密钥、Token、API Key 或带有隐私的机器本地路径

## 文档要求

当你的改动会影响项目使用方式或协作方式时，请同步更新相关文档：

- `README.md` 和 `README.en.md`：项目级说明
- `docs/DEVELOPMENT.md` 和 `docs/DEVELOPMENT.zh-CN.md`：开发流程与协作规范
- 当前这份贡献说明：当贡献标准发生变化时更新

## Pull Request 标准

每个 PR 应尽量满足：

- 标题清晰、具体
- 说明改了什么以及为什么改
- 写清楚用户侧会受到什么影响
- 如有安装、迁移、兼容性注意事项，应明确说明
- 规模尽量可控，方便评审

推荐 PR 描述结构：

```text
## Summary

用一两句话说明这个 PR 做了什么。

## Why

要解决的问题或填补的空白。

## Validation

如何验证改动（执行的命令、手动测试步骤）。

## Media

如果界面有变化，附上视频或 GIF。截图可以作为补充材料。

## Tests

如果项目逻辑有变化，列出新增或更新的单元测试。
```

对于大多数贡献，建议从短期功能分支发起 PR，而不是直接向 `develop` 或 `master` 推送提交。

## 评审标准

评审时建议重点关注：

- 正确性
- 是否引入回归
- 产品品味与交互质量
- 可读性与可维护性
- 是否符合当前架构方向
- 文档是否同步完整
- 校验步骤是否真实执行

## Commit 建议

好的 Commit 应该：

- 颗粒度适中，便于审阅
- 按逻辑分组
- 提交信息清晰明确

遵循 conventional commits 规范：

- `feat:` 新功能
- `fix:` 缺陷修复
- `docs:` 文档变更
- `refactor:` 代码重构
- `style:` 格式化、界面调整
- `chore:` 维护任务

示例：

- `docs: rewrite README and contribution guides`
- `feat: improve runtime connection recovery`
- `fix: handle missing DeepSeek binary path`

## 提交 Issue

提交 Issue 时，请尽可能包含以下信息：

- 操作系统及版本
- DeepSeek GUI 版本（可在设置页或关于对话框查看）
- 内置的 `kun` 版本（如可用，在同目录下执行 `kun --version`）
- 复现步骤
- 预期行为与实际行为
- 相关错误信息、日志或截图

## 贡献者协作方式

请以以下方式协作：

- 尊重他人
- 表达清晰
- 反馈建设性
- 愿意讨论与调整

如果改动范围较大或风险较高，建议先和维护者对齐方向，再投入较多实现成本。

## 需要帮助？

如果需求或边界不明确，先沟通确认，再进行较大范围的架构或流程调整。如有任何关于贡献的问题，欢迎提 Issue。

## 许可证

向 DeepSeek GUI 贡献代码即表示你同意你的贡献将基于 [MIT 许可证](../LICENSE) 发布。