> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 開發者指南

> 從本地開發到跨平台釋出，瞭解 Vibex 的工程約束。

Vibex 是 Rust workspace 驅動的原生應用。`DesktopRuntime` 是唯一的權威狀態所有者；桌面工作台、無頭服務端、行動端、TUI 和遠端傳輸都通過共享契約訪問它。

> [card] [架構邊界](https://vibex.peatboy.com/docs/developer/architecture.md)
>
> 瞭解 crate 劃分、權威執行階段、客戶端和 Relay 的職責。

> [card] [本地設定](https://vibex.peatboy.com/docs/developer/setup.md)
>
> 準備 Rust、Node、pnpm 和圖形構建環境。

> [card] [構建與測試](https://vibex.peatboy.com/docs/developer/build-and-test.md)
>
> 執行日常檢查、smoke test 和釋出構建門禁。

> [card] [平台支援](https://vibex.peatboy.com/docs/developer/platforms.md)
>
> 各平台的產物格式、構建方式和驗證要求。

> [card] [Remote v2 與 Relay](https://vibex.peatboy.com/docs/developer/remote-protocol.md)
>
> 配對、握手、同步和自託管傳輸的協議邊界。

> [card] [貢獻程式碼](https://vibex.peatboy.com/docs/developer/contributing.md)
>
> 提交變更時的架構、測試和隱私要求。

## 開發時必須保持的約束

* `DesktopRuntime` 負責 Agent、會話、時間線、檔案、Git、PTY、供應商、權限和持久化。
* **同一個核心有兩種前端**：`apps/desktop` 加 GPUI 視窗，`apps/server` 加守護程序生命週期。新增能力要同時適用於兩者。
* 客戶端只消費共享的遠端投影併發送型別化操作，不復制業務狀態。
* 新能力應經 `BackendFacade` 觸達權威端，而不是隻走本地執行階段路徑。
* Remote v2 的 DTO、錯誤、能力和序列號契約位於共享 `crates/core` 層。
* Relay 只轉發加密幀，不擁有業務授權、檔案或會話資料庫。
* 跨層行為變更必須補充確定性檢查或證據，並執行與風險匹配的最小測試集。

## 推薦閱讀順序

1. [架構與所有權邊界](https://vibex.peatboy.com/docs/zh-TW/developer/architecture.md)
2. [本地開發環境](https://vibex.peatboy.com/docs/zh-TW/developer/setup.md)
3. [構建與測試](https://vibex.peatboy.com/docs/zh-TW/developer/build-and-test.md)
4. [平台支援](https://vibex.peatboy.com/docs/zh-TW/developer/platforms.md)
5. [Remote v2 與 Relay](https://vibex.peatboy.com/docs/zh-TW/developer/remote-protocol.md)
6. [貢獻程式碼](https://vibex.peatboy.com/docs/zh-TW/developer/contributing.md)

## 倉庫內的設計文件

公開文件站只覆蓋使用者需要的內容。更細的設計與運維資料在倉庫 `docs/` 下：

| 路徑 | 內容 |
| - | - |
| `docs/architecture/ui-boundary.md` | UI 與權威端的所有權邊界。 |
| `docs/remote/protocol-v2.md` | Remote v2 線協議完整定義。 |
| `docs/remote/ssh-runtime.md` | SSH / WSL 遠端執行階段的使用者與運維契約。 |
| `docs/architecture/model-routing.md` | 路由組、閘道器觀測與協議轉換。 |
| `docs/tui/README.md` | TUI 的版面、會話狀態、鍵位和降級規則。 |
| `docs/platform/support-matrix.md` | 各平台能力的證據要求。 |
| `docs/operations/release.md` | 釋出 runbook。 |
| `docs/operations/release-packaging-matrix.md` | 產物與構建命令矩陣。 |
| `docs/operations/recovery-matrix.md` | 崩潰恢復：哪些狀態是持久的。 |
| `docs/smoke/relay-nat.md` | Relay 跨 NAT 的運維檢查清單。 |
| `docs/licenses/` | 第三方許可證與 SBOM。 |
| `deploy/server/README.md` | 無頭執行階段部署。 |
| `deploy/relay/README.md` | Relay 部署。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.