@neurocode-ai/web 1.18.8

package/src/content/docs/zh-cn/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-cn/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"
+/themes
+```
+
+**快捷键：** `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` 是分开的；`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` - 控制 diff 的显示方式。`"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 会话中保持记忆