@neurocode-ai/web 1.18.8

package/src/content/docs/zh-tw/troubleshooting.mdx

@@ -0,0 +1,299 @@
+---
+title: 疑難排解
+description: 常見問題及其解決方法。
+---
+
+要偵錯 OpenCode 的問題，請先檢查其儲存在磁碟上的日誌和本地資料。
+
+---
+
+## 日誌
+
+日誌檔案寫入位置：
+
+- **macOS/Linux**: `~/.local/share/opencode/log/`
+- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.local\share\opencode\log`
+
+日誌檔案以時間戳記命名（例如 `2025-01-09T123456.log`），並保留最近的 10 個日誌檔案。
+
+你可以透過 `--log-level` 命令列選項設定日誌等級以取得更詳細的偵錯資訊。例如：`opencode --log-level DEBUG`。
+
+---
+
+## 儲存
+
+OpenCode 將工作階段資料和其他應用程式資料儲存在磁碟上：
+
+- **macOS/Linux**: `~/.local/share/opencode/`
+- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.local\share\opencode`
+
+該目錄包含：
+
+- `auth.json` - 身分驗證資料，如 API 金鑰、OAuth Token
+- `log/` - 應用程式日誌
+- `project/` - 專案特定資料，如工作階段和訊息資料
+  - 如果專案位於 Git 儲存庫中，則儲存在 `./<project-slug>/storage/`
+  - 如果不是 Git 儲存庫，則儲存在 `./global/storage/`
+
+---
+
+## 桌面應用程式
+
+OpenCode Desktop 會在背景執行一個本地 OpenCode 伺服器（即 `opencode-cli` 附屬程序）。大多數問題是由外掛異常、快取損壞或錯誤的伺服器設定引起的。
+
+### 快速檢查
+
+- 完全退出並重新啟動應用程式。
+- 如果應用程式顯示錯誤頁面，請點擊**重新啟動**並複製錯誤詳情。
+- 僅限 macOS：`OpenCode` 選單 -> **Reload Webview**（當 UI 空白或凍結時有效）。
+
+---
+
+### 停用外掛
+
+如果桌面應用程式在啟動時當機、卡住或行為異常，請先停用外掛。
+
+#### 檢查全域設定
+
+開啟你的全域設定檔，查找 `plugin` 鍵。
+
+- **macOS/Linux**: `~/.config/opencode/opencode.jsonc`（或 `~/.config/opencode/opencode.json`）
+- **macOS/Linux**（舊版安裝）: `~/.local/share/opencode/opencode.jsonc`
+- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.config\opencode\opencode.jsonc`
+
+如果你設定了外掛，請透過移除該鍵或將其設定為空陣列來暫時停用它們：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [],
+}
+```
+
+#### 檢查外掛目錄
+
+OpenCode 還可以從磁碟載入本地外掛。暫時將這些外掛移走（或重新命名資料夾），然後重新啟動桌面應用程式：
+
+- **全域外掛**
+  - **macOS/Linux**: `~/.config/opencode/plugins/`
+  - **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.config\opencode\plugins`
+- **專案外掛**（僅當你使用了專案級設定時）
+  - `<your-project>/.opencode/plugins/`
+
+如果應用程式恢復正常，請逐個重新啟用外掛，找出導致問題的那個。
+
+---
+
+### 清除快取
+
+如果停用外掛沒有幫助（或外掛安裝卡住了），請清除快取以便 OpenCode 重新建置。
+
+1. 完全退出 OpenCode Desktop。
+2. 刪除快取目錄：
+
+- **macOS**: Finder -> `Cmd+Shift+G` -> 貼上 `~/.cache/opencode`
+- **Linux**: 刪除 `~/.cache/opencode`（或執行 `rm -rf ~/.cache/opencode`）
+- **Windows**: 按 `WIN+R` 並貼上 `%USERPROFILE%\.cache\opencode`
+
+3. 重新啟動 OpenCode Desktop。
+
+---
+
+### 修復伺服器連線問題
+
+OpenCode Desktop 可以啟動自己的本地伺服器（預設行為），也可以連線到你設定的伺服器 URL。
+
+如果你看到**「Connection Failed」**對話框（或應用程式始終停留在啟動畫面），請檢查自訂伺服器 URL。
+
+#### 清除桌面預設伺服器 URL
+
+在主頁面上，點擊伺服器名稱（帶有狀態指示點）以開啟伺服器選擇器。在**預設伺服器**部分，點擊**清除**。
+
+#### 從設定中移除 `server.port` / `server.hostname`
+
+如果你的 `opencode.json(c)` 包含 `server` 部分，請暫時移除該部分並重新啟動桌面應用程式。
+
+#### 檢查環境變數
+
+如果你在環境中設定了 `OPENCODE_PORT`，桌面應用程式將嘗試使用該連接埠作為本地伺服器連接埠。
+
+- 取消設定 `OPENCODE_PORT`（或選擇一個空閒連接埠）並重新啟動。
+
+---
+
+### Linux: Wayland / X11 問題
+
+在 Linux 上，某些 Wayland 設定可能會導致視窗空白或合成器錯誤。
+
+- 如果你使用 Wayland 且應用程式出現空白或當機，請嘗試使用 `OC_ALLOW_WAYLAND=1` 啟動。
+- 如果情況變得更糟，請移除該設定並嘗試在 X11 工作階段下啟動。
+
+---
+
+### Windows: WebView2 執行階段
+
+在 Windows 上，OpenCode Desktop 需要 Microsoft Edge **WebView2 Runtime**。如果應用程式開啟後是空白視窗或無法啟動，請安裝或更新 WebView2 後重試。
+
+---
+
+### Windows: 常見效能問題
+
+如果你在 Windows 上遇到效能緩慢、檔案存取問題或終端機問題，請嘗試使用 [WSL (Windows Subsystem for Linux)](/docs/windows-wsl)。WSL 提供了一個 Linux 環境，能更好地與 OpenCode 的功能相容。
+
+---
+
+### 通知不顯示
+
+OpenCode Desktop 僅在以下情況下顯示系統通知：
+
+- 在作業系統設定中已為 OpenCode 啟用通知，且
+- 應用程式視窗未處於焦點狀態。
+
+---
+
+### 重設桌面應用程式儲存（最後手段）
+
+如果應用程式無法啟動且你無法從 UI 內部清除設定，請重設桌面應用程式的儲存狀態。
+
+1. 退出 OpenCode Desktop。
+2. 找到並刪除以下檔案（它們位於 OpenCode Desktop 應用程式資料目錄中）：
+
+- `opencode.settings.dat`（桌面預設伺服器 URL）
+- `opencode.global.dat` 和 `opencode.workspace.*.dat`（UI 狀態，如最近的伺服器/專案）
+
+快速找到該目錄：
+
+- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support`（然後搜尋上述檔案名稱）
+- **Linux**: 在 `~/.local/share` 下搜尋上述檔案名稱
+- **Windows**: 按 `WIN+R` -> `%APPDATA%`（然後搜尋上述檔案名稱）
+
+---
+
+## 取得幫助
+
+如果你遇到 OpenCode 的問題：
+
+1. **在 GitHub 上回報問題**
+
+   回報 Bug 或請求功能的最佳方式是透過我們的 GitHub 儲存庫：
+
+   [**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
+
+   在建立新 Issue 之前，請先搜尋已有的 Issue，看看你的問題是否已被回報。
+
+2. **加入我們的 Discord**
+
+   如需即時幫助和社群討論，請加入我們的 Discord 伺服器：
+
+   [**opencode.ai/discord**](https://opencode.ai/discord)
+
+---
+
+## 常見問題
+
+以下是一些常見問題及其解決方法。
+
+---
+
+### OpenCode 無法啟動
+
+1. 檢查日誌中的錯誤訊息
+2. 嘗試使用 `--print-logs` 執行以在終端機中查看輸出
+3. 使用 `opencode upgrade` 確保你使用的是最新版本
+
+---
+
+### 身分驗證問題
+
+1. 嘗試在 TUI 中使用 `/connect` 指令重新進行身分驗證
+2. 檢查你的 API 金鑰是否有效
+3. 確保你的網路允許連線到供應商的 API
+
+---
+
+### 模型不可用
+
+1. 檢查你是否已通過供應商的身分驗證
+2. 驗證設定中的模型名稱是否正確
+3. 某些模型可能需要特定的存取權限或訂閱
+
+如果你遇到 `ProviderModelNotFoundError`，很可能是在某處錯誤地參考了模型。
+模型應按如下方式參考：`<providerId>/<modelId>`
+
+範例：
+
+- `openai/gpt-4.1`
+- `openrouter/google/gemini-2.5-flash`
+- `opencode/kimi-k2`
+
+要查看你有權存取哪些模型，請執行 `opencode models`
+
+---
+
+### ProviderInitError
+
+如果你遇到 ProviderInitError，很可能是設定無效或已損壞。
+
+要解決此問題：
+
+1. 首先，按照[供應商指南](/docs/providers)驗證你的供應商是否已正確設定
+2. 如果問題仍然存在，請嘗試清除已儲存的設定：
+
+   ```bash
+   rm -rf ~/.local/share/opencode
+   ```
+
+   在 Windows 上，按 `WIN+R` 並刪除：`%USERPROFILE%\.local\share\opencode`
+
+3. 在 TUI 中使用 `/connect` 指令重新與供應商進行身分驗證。
+
+---
+
+### AI_APICallError 和供應商套件問題
+
+如果你遇到 API 呼叫錯誤，可能是由於供應商套件過期導致的。OpenCode 會根據需要動態安裝供應商套件（OpenAI、Anthropic、Google 等）並將它們快取到本地。
+
+要解決供應商套件問題：
+
+1. 清除供應商套件快取：
+
+   ```bash
+   rm -rf ~/.cache/opencode
+   ```
+
+   在 Windows 上，按 `WIN+R` 並刪除：`%USERPROFILE%\.cache\opencode`
+
+2. 重新啟動 OpenCode 以重新安裝最新的供應商套件
+
+這將強制 OpenCode 下載最新版本的供應商套件，通常可以解決模型參數和 API 變更帶來的相容性問題。
+
+---
+
+### 在 Linux 上複製/貼上不可用
+
+Linux 使用者需要安裝以下剪貼簿工具之一，複製/貼上功能才能正常運作：
+
+**對於 X11 系統：**
+
+```bash
+apt install -y xclip
+# or
+apt install -y xsel
+```
+
+**對於 Wayland 系統：**
+
+```bash
+apt install -y wl-clipboard
+```
+
+**對於無頭環境：**
+
+```bash
+apt install -y xvfb
+# and run:
+Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+export DISPLAY=:99.0
+```
+
+OpenCode 會偵測你是否正在使用 Wayland 並優先使用 `wl-clipboard`，否則將按以下順序嘗試查找剪貼簿工具：`xclip` 和 `xsel`。

package/src/content/docs/zh-tw/tui.mdx

@@ -0,0 +1,426 @@
+---
+title: TUI
+description: 使用 OpenCode 終端機使用者介面。
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components"
+
+OpenCode 提供了一個互動式終端機介面（TUI），用於配合 LLM 處理您的專案。
+
+執行 OpenCode 即可啟動當前目錄的 TUI。
+
+```bash
+opencode
+```
+
+或者您可以為指定的工作目錄啟動它。
+
+```bash
+opencode /path/to/project
+```
+
+進入 TUI 後，您可以輸入訊息進行提示。
+
+```text
+Give me a quick summary of the codebase.
+```
+
+---
+
+## 檔案參考
+
+您可以使用 `@` 在訊息中參考檔案。這會在當前工作目錄中進行模糊檔案搜尋。
+
+:::tip
+您還可以使用 `@` 來參考訊息中的檔案。
+:::
+
+```text "@packages/functions/src/api/index.ts"
+How is auth handled in @packages/functions/src/api/index.ts?
+```
+
+檔案的內容會自動新增到對話中。
+
+---
+
+## Bash 指令
+
+以 `!` 開頭的訊息會作為 shell 指令執行。
+
+```bash frame="none"
+!ls -la
+```
+
+指令的輸出會作為工具結果新增到對話中。
+
+---
+
+## 指令
+
+使用 OpenCode TUI 時，您可以輸入 `/` 後跟指令名稱來快速執行操作。例如：
+
+```bash frame="none"
+/help
+```
+
+大多數指令還支援以 `ctrl+x` 作為前導鍵的快速鍵，其中 `ctrl+x` 是預設前導鍵。[了解更多](/docs/keybinds)。
+
+以下是所有可用的斜線指令：
+
+---
+
+### connect
+
+將供應商新增到 OpenCode。允許您從可用的供應商中選擇並新增其 API 金鑰。
+
+```bash frame="none"
+/connect
+```
+
+---
+
+### compact
+
+壓縮當前工作階段。_別名_：`/summarize`
+
+```bash frame="none"
+/compact
+```
+
+**快速鍵：** `ctrl+x c`
+
+---
+
+### details
+
+切換工具執行詳情的顯示。
+
+```bash frame="none"
+/details
+```
+
+**快速鍵：** `ctrl+x d`
+
+---
+
+### editor
+
+開啟外部編輯器來撰寫訊息。使用 `EDITOR` 環境變數中設定的編輯器。[了解更多](#editor-setup)。
+
+```bash frame="none"
+/editor
+```
+
+**快速鍵：** `ctrl+x e`
+
+---
+
+### exit
+
+退出 OpenCode。_別名_：`/quit`、`/q`
+
+```bash frame="none"
+/exit
+```
+
+**快速鍵：** `ctrl+x q`
+
+---
+
+### export
+
+將當前對話匯出為 Markdown 並在預設編輯器中開啟。使用 `EDITOR` 環境變數中設定的編輯器。[了解更多](#editor-setup)。
+
+```bash frame="none"
+/export
+```
+
+**快速鍵：** `ctrl+x x`
+
+---
+
+### help
+
+顯示說明對話框。
+
+```bash frame="none"
+/help
+```
+
+**快速鍵：** `ctrl+x h`
+
+---
+
+### init
+
+建立或更新 `AGENTS.md` 檔案。[了解更多](/docs/rules)。
+
+```bash frame="none"
+/init
+```
+
+**快速鍵：** `ctrl+x i`
+
+---
+
+### models
+
+列出可用模型。
+
+```bash frame="none"
+/models
+```
+
+**快速鍵：** `ctrl+x m`
+
+---
+
+### new
+
+開始新的工作階段。_別名_：`/clear`
+
+```bash frame="none"
+/new
+```
+
+**快速鍵：** `ctrl+x n`
+
+---
+
+### redo
+
+重做之前復原的訊息。僅在使用 `/undo` 後可用。
+
+:::tip
+所有檔案變更也會被恢復。
+:::
+
+在內部，這使用 Git 來管理檔案變更。因此您的專案**需要是一個 Git 儲存庫**。
+
+```bash frame="none"
+/redo
+```
+
+**快速鍵：** `ctrl+x r`
+
+---
+
+### sessions
+
+列出工作階段並在工作階段之間切換。_別名_：`/resume`、`/continue`
+
+```bash frame="none"
+/sessions
+```
+
+**快速鍵：** `ctrl+x l`
+
+---
+
+### share
+
+分享當前工作階段。[了解更多](/docs/share)。
+
+```bash frame="none"
+/share
+```
+
+**快速鍵：** `ctrl+x s`
+
+---
+
+### themes
+
+列出可用主題。
+
+```bash frame="none"
+/theme
+```
+
+**快速鍵：** `ctrl+x t`
+
+---
+
+### thinking
+
+切換對話中思考/推理區塊的可見性。啟用後，您可以看到支援擴充思考的模型的推理過程。
+
+:::note
+此指令僅控制思考區塊是否**顯示** — 它不會啟用或停用模型的推理能力。要切換實際的推理能力，請使用 `ctrl+t` 循環切換模型變體。
+:::
+
+```bash frame="none"
+/thinking
+```
+
+---
+
+### undo
+
+復原對話中的最後一條訊息。移除最近的使用者訊息、所有後續回應以及所有檔案變更。
+
+:::tip
+所做的任何檔案變更也會被還原。
+:::
+
+在內部，這使用 Git 來管理檔案變更。因此您的專案**需要是一個 Git 儲存庫**。
+
+```bash frame="none"
+/undo
+```
+
+**快速鍵：** `ctrl+x u`
+
+---
+
+### unshare
+
+取消分享當前工作階段。[了解更多](/docs/share#un-sharing)。
+
+```bash frame="none"
+/unshare
+```
+
+---
+
+## 編輯器設定
+
+`/editor` 和 `/export` 指令都使用 `EDITOR` 環境變數中指定的編輯器。
+
+<Tabs>
+  <TabItem label="Linux/macOS">
+    ```bash
+    # Example for nano or vim
+    export EDITOR=nano
+    export EDITOR=vim
+
+    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
+    # include --wait
+    export EDITOR="code --wait"
+    ```
+
+    要使其永久生效，請將其新增到您的 shell 設定檔中；
+    `~/.bashrc`、`~/.zshrc` 等。
+
+  </TabItem>
+
+  <TabItem label="Windows (CMD)">
+    ```bash
+    set EDITOR=notepad
+
+    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
+    # include --wait
+    set EDITOR=code --wait
+    ```
+
+    要使其永久生效，請使用**系統內容** > **環境變數**。
+
+  </TabItem>
+
+  <TabItem label="Windows (PowerShell)">
+    ```powershell
+    $env:EDITOR = "notepad"
+
+    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
+    # include --wait
+    $env:EDITOR = "code --wait"
+    ```
+
+    要使其永久生效，請將其新增到您的 PowerShell 設定檔中。
+
+  </TabItem>
+</Tabs>
+
+常用的編輯器選項包括：
+
+- `code` - Visual Studio Code
+- `cursor` - Cursor
+- `windsurf` - Windsurf
+- `nvim` - Neovim 編輯器
+- `vim` - Vim 編輯器
+- `nano` - Nano 編輯器
+- `notepad` - Notepad（Windows 記事本）
+- `subl` - Sublime Text
+
+:::note
+某些編輯器（如 VS Code）需要以 `--wait` 旗標啟動。
+:::
+
+某些編輯器需要命令列參數才能以阻塞模式執行。`--wait` 旗標使編輯器程序阻塞直到關閉。
+
+---
+
+## 設定
+
+您可以透過 `tui.json`（或 `tui.jsonc`）自訂 TUI 行為。
+
+```json title="tui.json"
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "theme": "opencode",
+  "leader_timeout": 2000,
+  "keybinds": {
+    "leader": "ctrl+x",
+    "command_list": "ctrl+p"
+  },
+  "scroll_speed": 3,
+  "scroll_acceleration": {
+    "enabled": false
+  },
+  "diff_style": "auto",
+  "mouse": true,
+  "attention": {
+    "enabled": true,
+    "notifications": true,
+    "sound": true,
+    "volume": 0.4,
+    "sound_pack": "opencode.default",
+    "sounds": {
+      "error": "./sounds/error.mp3"
+    }
+  }
+}
+```
+
+這與設定伺服器/執行時行為的 `opencode.json` 是分開的。
+
+`keybinds` 會與內建預設值合併，因此您只需要設定想要修改的快捷鍵。
+
+### 選項
+
+- `theme` - 設定您的 UI 主題。[了解更多](/docs/themes)。
+- `keybinds` - 自訂鍵盤快速鍵。[了解更多](/docs/keybinds)。
+- `leader_timeout` - 控制按下 leader key 後 OpenCode 等待後續按鍵的時間。預設為 `2000`。
+- `scroll_acceleration.enabled` - 啟用 macOS 風格的捲動加速，實現平滑、自然的捲動體驗。啟用後，快速捲動時速度會增加，慢速移動時保持精確。**此設定優先於 `scroll_speed`，啟用時會覆蓋它。**
+- `scroll_speed` - 控制使用捲動指令時 TUI 的捲動速度（最小值：`0.001`，支援小數值）。預設為 `3`。**注意：如果 `scroll_acceleration.enabled` 設定為 `true`，則此設定會被忽略。**
+- `diff_style` - 控制差異呈現方式。`"auto"` 根據終端機寬度自適應，`"stacked"` 始終顯示單列。
+- `mouse` - 在 TUI 中啟用或停用滑鼠捕捉（預設：`true`）。停用後，會保留終端機原生的滑鼠選取和捲動行為。
+- `attention` - 設定 TUI 桌面通知和聲音。預設停用。
+
+使用 `OPENCODE_TUI_CONFIG` 載入自訂 TUI 設定路徑。
+
+### Attention
+
+當 OpenCode 需要你處理問題、核准權限請求、查看工作階段錯誤，或告知工作階段已完成時，TUI 可以透過聲音和桌面通知提醒你。設定 `attention.enabled` 後會啟用這些提醒；內建事件觸發時會播放聲音。桌面通知只會在終端機視窗未聚焦時傳送，且不會用於 subagent 事件。
+
+- `enabled` - 開啟 Attention 的所有通知和聲音。預設為 `false`。
+- `notifications` - 啟用 Attention 後，允許 TUI 透過終端機傳送桌面通知。預設為 `true`。
+- `sound` - 啟用 Attention 後，允許播放提示音。預設為 `true`。
+- `volume` - 預設提示音音量，範圍從 `0` 到 `1`。預設為 `0.4`。
+- `sound_pack` - 要使用的 sound pack ID。預設為 `opencode.default`。
+- `sounds` - 為 `default`、`question`、`permission`、`error`、`done` 或 `subagent_done` 指定自訂聲音檔案。路徑可以是絕對路徑、`file://` URL，或相對於 `tui.json` 的路徑。
+
+---
+
+## 自訂
+
+您可以使用指令面板（`ctrl+x h` 或 `/help`）自訂 TUI 檢視的各個方面。這些設定在重新啟動後仍會保留。
+
+---
+
+#### 使用者名稱顯示
+
+切換您的使用者名稱是否顯示在聊天訊息中。透過以下方式存取：
+
+- 指令面板：搜尋「username」或「hide username」
+- 該設定會自動儲存，並在各個 TUI 工作階段中保持記憶