> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/zhong-wen-fan-ti/contribution/code.md).

# 貢獻代碼

代碼貢獻要由一個清楚嘅問題開始。修復缺陷之前先確認可唔可以重現；增加功能之前先講明用戶場景同預期行為。範圍較大嘅改動，建議先喺 GitHub Issue 或 Discussion 入面對齊方向。

<figure><img src="https://2742912793-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Ut5BptC3t8CtSU1UWpM%2Fuploads%2FcMEZnURLllvPJjbTjF31%2Fclipboard.png?alt=media&amp;token=2ebd2302-01ea-4d15-81ce-62fa878c4894" alt="从说明问题、最小改动、本地验证到提交评审和合并的贡献流程图"><figcaption><p>一次貢獻只解決一個清楚嘅問題，先完成本地驗證，再提交評審。</p></figcaption></figure>

## 開始前

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Cherry Studio 倉庫</strong></td><td>源碼、README 同開發入口</td><td><a href="https://github.com/CherryHQ/cherry-studio">https://github.com/CherryHQ/cherry-studio</a></td></tr><tr><td><strong>GitHub Issues</strong></td><td>缺陷、功能建議同待解決問題</td><td><a href="https://github.com/CherryHQ/cherry-studio/issues">https://github.com/CherryHQ/cherry-studio/issues</a></td></tr><tr><td><strong>貢獻指南</strong></td><td>分支、測試、簽署同評審要求</td><td><a href="https://github.com/CherryHQ/cherry-studio/blob/main/CONTRIBUTING.md">https://github.com/CherryHQ/cherry-studio/blob/main/CONTRIBUTING.md</a></td></tr><tr><td><strong>行為準則</strong></td><td>社區協作邊界</td><td><a href="https://github.com/CherryHQ/cherry-studio/blob/main/CODE_OF_CONDUCT.md">https://github.com/CherryHQ/cherry-studio/blob/main/CODE_OF_CONDUCT.md</a></td></tr></tbody></table>

適合上手嘅任務可以從 `good first issue`、`help wanted` 同 `kind/bug` 標籤入面搵。準備開始之前，喺 Issue 中說明你打算處理，避免多人重複投入。

## 分支點揀

大多數目前功能、修復、重構同優化都提交到 `main`。如果 Issue、維護者說明或貢獻指南指定咗其他目標分支，就以當時嘅項目說明為準；唔好淨係憑舊教程判斷。

{% hint style="warning" %}
唔好從舊教程判斷目標分支。建立 PR 前再睇一次倉庫而家嘅貢獻指南同 PR 模板；分支策略有變化時，以倉庫內容為準。
{% endhint %}

## 適合貢獻代碼嘅情況

| 情況           | 建議做法                       |
| ------------ | -------------------------- |
| 可以穩定重現嘅問題    | 先提交最小修復同對應檢查               |
| 邊界清楚嘅小功能     | 先確認需求同目標分支，再開始實現           |
| 涉及數據遷移、權限或架構 | 先喺 Issue 或 Discussion 對齊方案 |
| 只需要改說明或截圖    | 走【貢獻文檔】，唔好混入代碼 PR          |

{% hint style="info" %}
一個 PR 只解決一個清楚嘅問題。若修改同時包含功能、重構同無關格式化，審閱者好難判斷風險，亦都更難回滾。
{% endhint %}

## 提交流程

{% stepper %}
{% step %}

### 1. Fork 並建立分支

從正確嘅目標分支建立一個範圍清楚嘅工作分支。一個 PR 只解決一個主題，唔好將順手嘅重構同格式調整混埋入去。
{% endstep %}

{% step %}

### 2. 準備開發環境

按照倉庫【Developer Guide】安裝指定嘅 Node.js 同 pnpm 版本，執行 `pnpm install`。開始改動前先運行同目標模組相關嘅現有檢查，確認基線可用。
{% endstep %}

{% step %}

### 3. 修改同驗證

缺陷修復應該加入可以重現問題嘅測試；新功能應覆蓋關鍵路徑同失敗場景。提交前運行倉庫要求嘅格式、靜態檢查、測試同構建檢查。
{% endstep %}

{% step %}

### 4. 提交同簽署

提交信息寫清改動類型同模組，並使用 `git commit --signoff` 加入 DCO 簽署。簽署表示你有權按照項目許可提交呢部分內容。
{% endstep %}

{% step %}

### 5. 建立 PR

按照模板填寫改動前後、採用呢種方案嘅原因、取捨同替代方案、破壞性變化、驗證方式同 Release Note。仍然需要討論嘅改動可以先建 Draft PR。
{% endstep %}
{% endstepper %}

## PR 提交之後

新貢獻者嘅 PR 會先帶有 `needs-ok-to-test`，自動測試唔會即刻開始。倉庫成員確認後會使用 `/ok-to-test` 啟動流水線。Draft PR 唔會分配常規評審，亦都會跳過自動測試；準備好之後再標記做 Ready for review。

評審意見應該透過新增提交修復，保持討論上下文。出現設計分歧時，先返到用戶問題同可驗證行為，唔好用大範圍改寫去迴避一個局部問題。

## 提交前自查

* 目標分支正確；
* 變更範圍同 Issue/PR 描述一致；
* 新行為有測試或可重複嘅手動驗證步驟；
* 用戶可見變化同步更新文檔；
* 數據遷移、升級同兼容性已經考慮；
* 冇提交 API Key、真實用戶數據或調試文件；
* Commit 已簽署，Release Note 符合模板要求。

<details>

<summary>細改動都需要 Issue 嗎？</summary>

拼寫、明顯嘅小修復可以直接提交；涉及產品行為、架構或較大工作量時，先開 Issue 更容易確認方向。使唔使 Issue 以倉庫而家嘅維護規則為準。

</details>

<details>

<summary>CI 點解冇自動運行？</summary>

先確認 PR 唔係 Draft。新貢獻者嘅 PR 需要倉庫成員 `/ok-to-test`，見到 `needs-ok-to-test` 時喺 PR 入面耐心等確認就得。

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/docs/zhong-wen-fan-ti/contribution/code.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.