monadical/opencode
13
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs: improve zh-cn and zh-tw documentation translations (#13942)

Browse Source
This commit is contained in:
chenmi
2026-02-17 20:06:39 +08:00
committed by GitHub
parent 8d0a303af4
commit 4fd3141ab5
68 changed files with 4624 additions and 4518 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
packages/web/src/content/docs/zh-cn/acp.mdx
View File

@@ -1,31 +1,31 @@
---
title: ACP 支持
description: 在任何 ACP 兼容编辑器中使用 opencode。
description: 在任何兼容 ACP 的编辑器中使用 OpenCode。
---
opencode 支持 [Agent Client Protocol](https://agentclientprotocol.com) (ACP)，允许您直接在兼容的编辑器和 IDE 中使用它。
OpenCode 支持 [Agent Client Protocol](https://agentclientprotocol.com)（ACP），允许你直接在兼容的编辑器和 IDE 中使用它。
:::tip
有关支持 ACP 的编辑器和工具的列表，请查看 [Zed ACP progress report](https://zed.dev/blog/acp-progress-report#available-now)。
有关支持 ACP 的编辑器和工具列表，请查看 [ACP 进展报告](https://zed.dev/blog/acp-progress-report#available-now)。
:::
ACP 是一种开放协议，用于标准化代码编辑器和 AI 编码代理之间的通信。
ACP 是一个开放协议，用于标准化代码编辑器与 AI 编码代理之间的通信。
---
## 配置
要通过 ACP 使用 opencode，须编辑器配置为运行 `opencode acp` 命令。
要通过 ACP 使用 OpenCode，请在编辑器中配置运行 `opencode acp` 命令。
该命令将 opencode 作为 ACP 兼容的子进程启动，通过 stdio 通过 JSON-RPC 与您的编辑器进行通信。
该命令会将 OpenCode 作为兼容 ACP 的子进程启动，通过 stdio 上的 JSON-RPC 与编辑器进行通信。
以下是支持 ACP 的流行编辑器的示例。
以下是支持 ACP 的常用编辑器的配置示例。
---
### Zed
添加到您的 [Zed](https://zed.dev) 配置 (`~/.config/zed/settings.json`)：
添加到你的 [Zed](https://zed.dev) 配置文件（`~/.config/zed/settings.json`）中：
```json title="~/.config/zed/settings.json"
{
@@ -38,9 +38,9 @@ ACP 是一种开放协议，用于标准化代码编辑器和 AI 编码代理之
}
```
要打开它，请使用 **命令面板** 中的 `agent: new thread` 操作。
打开方式：在**命令面板**中执行 `agent: new thread` 操作。
您还可以通过编辑 `keymap.json` 来绑定键盘快捷键：
你也可以通过编辑 `keymap.json` 来绑定键盘快捷键：
```json title="keymap.json"
[
@@ -67,9 +67,9 @@ ACP 是一种开放协议，用于标准化代码编辑器和 AI 编码代理之
---
### JetBrains IDE
### JetBrains IDEs
根据 [文档](https://www.jetbrains.com/help/ai-assistant/acp.html) 添加到你的 [JetBrains IDE](https://www.jetbrains.com/) `acp.json`：
根据[文档](https://www.jetbrains.com/help/ai-assistant/acp.html)，将以下内容添加到你的 [JetBrains IDE](https://www.jetbrains.com/) 的 acp.json 中：
```json title="acp.json"
{
@@ -82,13 +82,13 @@ ACP 是一种开放协议，用于标准化代码编辑器和 AI 编码代理之
}
```
要打开它，请在 AI Chat 代理选择器中使用新的 "opencode" 代理。
打开方式：在 AI Chat 代理选择器中选择新的 'OpenCode' 代理。
---
### Avante.nvim
添加到您的 [Avante.nvim](https://github.com/yetone/avante.nvim) 配置：
添加到你的 [Avante.nvim](https://github.com/yetone/avante.nvim) 配置中：
```lua
{
@@ -121,7 +121,7 @@ ACP 是一种开放协议，用于标准化代码编辑器和 AI 编码代理之
### CodeCompanion.nvim
相当于 opencode 网关 [CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim) 中的 ACP 代理，接下来将以下内容添加到 Neovim 配置中：
要在 [CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim) 中将 OpenCode 用作 ACP 代理，请将以下内容添加到你的 Neovim 配置中：
```lua
require("codecompanion").setup({
@@ -136,21 +136,21 @@ require("codecompanion").setup({
})
```
此配置将 CodeCompanion.nvim 设置为使用 opencode 作为聊天的 ACP 代理。
此配置将 CodeCompanion 设置为使用 OpenCode 作为聊天的 ACP 代理。
如果您需要传递环境变量（如 `OPENCODE_API_KEY`），请参阅 CodeCompanion.nvim 文档中的 [Configuration: Adapters](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key) 了解完整信息。
如果需要传递环境变量（如 `OPENCODE_API_KEY`），请参阅 CodeCompanion.nvim 文档中的[配置适配器：环境变量](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key)了解详细信息。
## 支持
opencode 通过 ACP 的工作方式与在终端中的工作方式相同。支持所有功能：
OpenCode 通过 ACP 使用时与在终端中使用的效果完全一致。所有功能均受支持：
:::note
目前不支持某些内置斜杠命令，例如 `/undo` 和 `/redo`。
部分内置斜杠命令（如 `/undo` 和 `/redo`）目前暂不支持。
:::
- 内置工具（文件操作、终端命令等）
- 自定义工具和斜杠命令
- 在 opencode 配置中配置的 MCP 服务器
- `AGENTS.md` 的项目特定规则
- 自定义程序和 linter
- 在 OpenCode 配置中配置的 MCP 服务器
- 来自 `AGENTS.md` 的项目级规则
- 自定义格式化工具和代码检查工具
- 代理和权限系统

183
packages/web/src/content/docs/zh-cn/agents.mdx
View File

@@ -3,46 +3,45 @@ title: 代理
description: 配置和使用专门的代理。
---
代理是专门的人工智能助手，可以针对特定任务和工作流程进行配置。它们允许您创建具有自定义提示、模型和工具访问权限的专用工具。
代理是专门的 AI 助手，可以针对特定任务和工作流程进行配置。它们允许您创建具有自定义提示词、模型和工具访问权限的专用工具。
:::tip
使用 Plan 代理来分析代码并审查建议，而无需进行任何代码更改。
使用 Plan 代理来分析代码和审查建议，而不会进行任何代码更改。
:::
您可以在会话期间在代理之间切换，或使用 `@` 提及来调用它们。
您可以在会话期间切换代理，或使用 `@` 提及来调用它们。
---
## 类型
OpenCode 有两种类型的代理；主代理和子代理。
OpenCode 中有两种类型的代理：主代理和子代理。
---
### 主代理
主代理 (Primary) 是与您直接交互的主要助手。您可以使用 **Tab** 键或您配置的 `switch_agent` 键绑定循环浏览它们。这些代理处理您的主要对话。工具访问是通过权限配置的 - 例如，“Build”启用了所有工具，而“Plan”则受到限制。
主代理是您直接交互的主要助手。您可以使用 **Tab** 键或配置的 `switch_agent` 快捷键来循环切换它们。这些代理处理您的主要对话。工具访问通过权限进行配置——例如，Build 启用了所有工具，而 Plan 则受到限制。
:::tip
您可以在会话期间使用 **Tab** 键在主代理之间进行切换。
您可以在会话期间使用 **Tab** 键在主代理之间切换。
:::
OpenCode 附带两个内置的主代理：**Build** 和 **Plan**。
看看下面这些。
OpenCode 内置了两个主代理：**Build** 和 **Plan**。我们将在下面介绍它们。
---
### 子代理
子代理 (Subagents) 是主代理可以调用​​来执行特定任务的专业助手。您还可以通过在消息中 **@提及** 它们来手动调用它们。
子代理是主代理可以调用来执行特定任务的专业助手。您也可以通过在消息中 **@ 提及**它们来手动调用。
OpenCode 附带两个内置子代理：**General** 和 **Explore**。我们将在下面看看这个。
OpenCode 内置了两个子代理：**General** 和 **Explore**。我们将在下面介绍它们。
---
## 内置
## 内置代理
OpenCode 附带两个内置主代理和两个内置子代理。
OpenCode 内置了两个主代理和两个子代理。
---
@@ -50,7 +49,7 @@ OpenCode 附带两个内置主代理和两个内置子代理。
_模式_：`primary`
Build 是启用所有工具的 **默认** Primary 代理。这是用于需要完全访问文件操作和系统命令的开发工作的标准代理。
Build 是启用了所有工具的**默认**主代理。这是用于需要完全访问文件操作和系统命令的开发工作的标准代理。
---
@@ -58,13 +57,13 @@ Build 是启用所有工具的 **默认** Primary 代理。这是用于需要完
_模式_：`primary`
专为规划和分析而设计的受限代理。我们使用权限系统为您提供更多控制并防止意外更改。
一个专为规划和分析设计的受限代理。我们使用权限系统来为您提供更多控制权，并防止意外更改。
默认情况下，以下所有项均设置为 `ask`：
- `file edits`：所有书写、修复和编辑
- `file edits`：所有写入、补丁和编辑
- `bash`：所有 bash 命令
当您希望 LLM 分析代码、建议更改或创建计划而不是对代码库进行任何实际修改时，此代理非常有用。
当您希望 LLM 分析代码、建议更改或创建计划，而不对代码库进行任何实际修改时，此代理非常有用。
---
@@ -72,7 +71,7 @@ _模式_：`primary`
_模式_：`subagent`
用于研究复杂问题和执行多步骤任务的通用代理。它具有完整的工具访问权限（待办事项除外），因此可在需要时修改文件，并并行运行多个工作单元。
一个用于研究复杂问题和执行多步骤任务的通用代理。拥有完整的工具访问权限（todo 除外），因此可以在需要时修改文件。可用于并行运行多个工作单元。
---
@@ -80,15 +79,15 @@ _模式_：`subagent`
_模式_：`subagent`
用于探索代码库的快速只读代理。无法修改文件。当您需要按模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时，请使用此功能。
一个用于探索代码库的快速只读代理。无法修改文件。当您需要按模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时，请使用此代理。
---
### 使用 Compact
### 使用 Compaction
_模式_：`primary`
隐藏的系统代理，将长上下文压缩为更小的抽象。它会在需要时自动运行，并且无法在 UI 中选择。
隐藏的系统代理，将长上下文压缩为较小的摘要。它会在需要时自动运行，且无法在 UI 中选择。
---
@@ -96,7 +95,7 @@ _模式_：`primary`
_模式_：`primary`
生成短会话标题的隐藏系统代理。它会自动运行，并且无法在 UI 中选择。
隐藏的系统代理，用于生成简短的会话标题。它会自动运行，且无法在 UI 中选择。
---
@@ -104,33 +103,33 @@ _模式_：`primary`
_模式_：`primary`
创建会话摘要的系统代理。它会自动运行，并且无法在 UI 中选择。
隐藏的系统代理，用于创建会话摘要。它会自动运行，且无法在 UI 中选择。
---
## 用法
1. 对于主代理，请在会话期间使用 **Tab** 键循环浏览它们。您还可以使用配置的 `switch_agent` 键绑定。
1. 对于主代理，在会话期间使用 **Tab** 键循环切换。您也可以使用配置的 `switch_agent` 快捷键。
2. 可以调用子代理：
- **自动**由主代理根据其描述执行专门任务。
- 通过在消息中 **@提及** 子代理手动进行。例如。
2. 子代理可以通过以下方式调用：
- 由主代理根据其描述**自动**调用以执行专门任务。
- 通过在消息中 **@ 提及**子代理来手动调用。例如：
```txt frame="none"
@general help me search for this function
```
3. **会话之间导航**：当子代理创建自己的子会话时，您可以使用以下命令在父会话和所有子会话之间导航：
- **\<Leader>+Right**（或您配置的 `session_child_cycle` 键绑定）向前循环父级 → 子级 1 → 子级 2 → ... → 父级
- **\<Leader>+Left**（或您配置的 `session_child_cycle_reverse` 键绑定）向后循环父级 ← 子级 1 ← 子级 2 ← ... ← 父级
3. **会话间导航**：当子代理创建自己的子会话时，您可以使用以下方式在父会话和所有子会话之间导航：
- **\<Leader>+Right**（或配置的 `session_child_cycle` 快捷键）向前循环：父会话 → 子会话1 → 子会话2 → ... → 父会话
- **\<Leader>+Left**（或配置的 `session_child_cycle_reverse` 快捷键）向后循环：父会话 ← 子会话1 ← 子会话2 ← ... ← 父会话
这使您可以在主要对话和专门的子代理工作之间无缝切换。
这使您可以在主对话和专门的子代理工作之间无缝切换。
---
## 配置
您也可以自定义内置代理或通过配置创建您自己的代理。可以通过两种方式配置代理：
您可以自定义内置代理或通过配置创建自己的代理。代理可以通过两种方式进行配置：
---
@@ -179,10 +178,10 @@ _模式_：`primary`
### Markdown
您还可以使用 Markdown 文件定义代理。将它们放入：
您还可以使用 Markdown 文件定义代理。将它们放在：
- 全局：`~/.config/opencode/agents/`
- 每个项目：`.opencode/agents/`
- 项目级：`.opencode/agents/`
```markdown title="~/.config/opencode/agents/review.md"
---
@@ -206,19 +205,19 @@ You are in code review mode. Focus on:
Provide constructive feedback without making direct changes.
```
Markdown 文件名成为代理名称。例如，`review.md` 创建 `review` 代理。
Markdown 文件名即为代理名称。例如，`review.md` 会创建一个名为 `review` 的代理。
---
## 选项
让我们详细看看这些配置选项。
让我们详细了解这些配置选项。
---
### 描述
使用 `description` 选项提供代理的作用以及使用时的简要描述。
使用 `description` 选项提供代理的功能及使用场景的简要描述。
```json title="opencode.json"
{
@@ -236,9 +235,9 @@ Markdown 文件名成为代理名称。例如，`review.md` 创建 `review` 代
### 温度
使用 `temperature` 配置控制 LLM 响应的随机性和创意。
使用 `temperature` 配置控制 LLM 响应的随机性和创造力。
较低的值使响应更加集中和确定，而较高的值则增加创造力和可变性。
较低的值使响应更加集中和确定，而较高的值则增加创造力和多样性。
```json title="opencode.json"
{
@@ -253,11 +252,11 @@ Markdown 文件名成为代理名称。例如，`review.md` 创建 `review` 代
}
```
温度值范围通常为 0.0 到 1.0：
温度值通常范围为 0.0 到 1.0：
- **0.0-0.2**：响应更集中、确定性更高，适合代码分析和规划
- **0.3-0.5**：平衡型响应，兼顾稳定性与创造力
- **0.6-1.0**：响应更有创意和多样性，适合头脑风暴和探索
- **0.0-0.2**：非常集中和确定性的响应，适合代码分析和规划
- **0.3-0.5**：平衡的响应，兼顾一定创造力，适合一般开发任务
- **0.6-1.0**：更有创造力和多样性的响应，适合头脑风暴和探索
```json title="opencode.json"
{
@@ -277,15 +276,15 @@ Markdown 文件名成为代理名称。例如，`review.md` 创建 `review` 代
}
```
如果未指定温度，OpenCode 将使用特定于模型的默认值；大多数模型通常为 0，Qwen 模型为 0.55。
如果未指定温度，OpenCode 将使用模型特定的默认值；大多数模型通常为 0，Qwen 模型为 0.55。
---
### 最大步数
控制代理在被迫仅使用文本响应之前可以执行的最大代理迭代次数。这允许希望控制成本的用户对代理操作设置限制。
控制代理在被强制以纯文本响应之前可以执行的最大代理迭代次数。这允许希望控制成本的用户对代理操作设置限制。
如果未设置，代理将继续迭代，直到模型选择停止或用户中断会话。
如果未设置此选项，代理将持续迭代，直到模型选择停止或用户中断会话。
```json title="opencode.json"
{
@@ -299,17 +298,17 @@ Markdown 文件名成为代理名称。例如，`review.md` 创建 `review` 代
}
```
当达到限制时，代理会收到特殊的系统提示，指示其响应其工作摘要和建议的剩余任务。
当达到限制时，代理会收到一个特殊的系统提示词，指示其回复工作摘要和建议的剩余任务。
:::caution
旧版 `maxSteps` 字段已废弃。请改用 `steps`。
旧版 `maxSteps` 字段已弃用。请改用 `steps`。
:::
---
### 禁用
设置为 `true` 以取消代理。
设置为 `true` 以禁用代理。
```json title="opencode.json"
{
@@ -323,9 +322,9 @@ Markdown 文件名成为代理名称。例如，`review.md` 创建 `review` 代
---
### 提示
### 提示词
使用 `prompt` 配置为代理指定自定义系统提示文件。提示文件应包含特定于代理目的的说明。
使用 `prompt` 配置为代理指定自定义系统提示词文件。提示词文件应包含针对代理用途的具体指令。
```json title="opencode.json"
{
@@ -337,16 +336,16 @@ Markdown 文件名成为代理名称。例如，`review.md` 创建 `review` 代
}
```
该路径相对于文件所在位置的配置。因此，这适用于全局 OpenCode 配置和项目特定配置。
此路径相对于配置文件所在位置。因此它同时适用于全局 OpenCode 配置和项目级配置。
---
### 模型
使用 `model` 配置此代理的模型。对于使用针对不同任务优化的不同模型很有帮助。例如，更快的规划模型、更强大的实施模型。
使用 `model` 配置为代理覆盖模型。适用于针对不同任务使用不同的优化模型。例如，用更快的模型进行规划，用更强大的模型进行实现。
:::tip
如果您不指定模型，主代理将使用 [全局配置的模型](/docs/config#models)，而子代理将使用调用子代理的主代理的模型。
如果您不指定模型，主代理将使用[全局配置的模型](/docs/config#models)，而子代理将使用调用它的主代理所使用的模型。
:::
```json title="opencode.json"
@@ -359,13 +358,13 @@ Markdown 文件名成为代理名称。例如，`review.md` 创建 `review` 代
}
```
OpenCode 配置中的模型 ID 使用格式 `provider/model-id`。例如，如果您使用 [OpenCode Zen](/docs/zen)，则您将使用 `opencode/gpt-5.1-codex` 来表示 GPT 5.1 Codex。
OpenCode 配置中的模型 ID 使用 `provider/model-id` 格式。例如，如果您使用 [OpenCode Zen](/docs/zen)，则可以使用 `opencode/gpt-5.1-codex` 来表示 GPT 5.1 Codex。
---
### 工具
使用 `tools` 配置控制此代理中可用的工具。您可以通过将特定工具设置为 `true` 或 `false` 来启用或禁用特定工具。
使用 `tools` 配置控制代理中可用的工具。您可以通过将特定工具设置为 `true` 或 `false` 来启用或禁用它们。
```json title="opencode.json" {3-6,9-12}
{
@@ -386,7 +385,7 @@ OpenCode 配置中的模型 ID 使用格式 `provider/model-id`。例如，如
```
:::note
特定于代理的配置会覆盖全局配置。
代理级配置会覆盖全局配置。
:::
您还可以使用通配符同时控制多个工具。例如，要禁用 MCP 服务器中的所有工具：
@@ -406,7 +405,7 @@ OpenCode 配置中的模型 ID 使用格式 `provider/model-id`。例如，如
}
```
[了解有关工具的更多信息](/docs/tools)。
[了解更多关于工具的信息](/docs/tools)。
---
@@ -414,9 +413,9 @@ OpenCode 配置中的模型 ID 使用格式 `provider/model-id`。例如，如
您可以配置权限来管理代理可以执行的操作。目前，`edit`、`bash` 和 `webfetch` 工具的权限可以配置为：
- `"ask"` — 运行工具提示批准之前
- `"allow"` — 尚未批准所有操作
- `"deny"` — 取消该工具
- `"ask"` — 运行工具前提示审批
- `"allow"` — 允许所有操作，无需审批
- `"deny"` — 禁用该工具
```json title="opencode.json"
{
@@ -427,7 +426,7 @@ OpenCode 配置中的模型 ID 使用格式 `provider/model-id`。例如，如
}
```
您可以覆盖每个代理的这些权限。
您可以按代理覆盖这些权限。
```json title="opencode.json" {3-5,8-10}
{
@@ -464,7 +463,7 @@ permission:
Only analyze code and suggest changes.
```
您可以设置特定的 bash 命令的权限。
您可以为特定的 bash 命令设置权限。
```json title="opencode.json" {7}
{
@@ -482,7 +481,7 @@ Only analyze code and suggest changes.
}
```
这可以采用全局模式。
这可以使用 glob 模式。
```json title="opencode.json" {7}
{
@@ -500,7 +499,7 @@ Only analyze code and suggest changes.
```
您还可以使用 `*` 通配符来管理所有命令的权限。
由于最后一个匹配规则优先，因此将 `*` 通配符放在前面，将特定规则放在后面。
由于最后匹配的规则优先，请将 `*` 通配符放在前面，将具体规则放在后面。
```json title="opencode.json" {8}
{
@@ -518,13 +517,13 @@ Only analyze code and suggest changes.
}
```
[了解有关权限的更多信息](/docs/permissions)。
[了解更多关于权限的信息](/docs/permissions)。
---
### 模式
使用 `mode` 配置控制代理的模式。 `mode` 选项用于确定如何使用代理。
使用 `mode` 配置控制代理的模式。`mode` 选项用于确定代理的使用方式。
```json title="opencode.json"
{
@@ -536,13 +535,13 @@ Only analyze code and suggest changes.
}
```
`mode` 选项可设置为 `primary`、`subagent` 或 `all`。如果未指定 `mode`，则默认为 `all`。
`mode` 选项可以设置为 `primary`、`subagent` 或 `all`。如果未指定 `mode`，则默认为 `all`。
---
### 隐藏
使用 `hidden: true` 从 `@` 自动完成菜单隐藏子代理。对于只能由其他代理通过任务工具以编程方式调用的内部子代理很有帮助。
使用 `hidden: true` 将子代理从 `@` 自动补全菜单中隐藏。适用于只应由其他代理通过 Task 工具以编程方式调用的内部子代理。
```json title="opencode.json"
{
@@ -555,17 +554,17 @@ Only analyze code and suggest changes.
}
```
这仅影响自动完成菜单中的用户可见性。如果权限允许，模型仍然可以通过任务工具调用隐藏代理。
这仅影响自动补全菜单中的用户可见性。如果权限允许，模型仍然可以通过 Task 工具调用隐藏的代理。
:::note
仅适用于 `mode: subagent` 代理。
仅适用于 `mode: subagent` 的代理。
:::
---
### 任务权限
使用 `permission.task` 控制代理可以通过任务工具调用哪些子代理。使用 glob 模式进行灵活匹配。
使用 `permission.task` 控制代理可以通过 Task 工具调用哪些子代理。使用 glob 模式进行灵活匹配。
```json title="opencode.json"
{
@@ -584,21 +583,21 @@ Only analyze code and suggest changes.
}
```
当设置为 `deny` 时，子代理社区任务工具描述中因此完全删除，模型不会尝试调用它。
当设置为 `deny` 时，子代理将从 Task 工具描述中完全移除，因此模型不会尝试调用它。
:::tip
规则按顺序评估，**最后匹配的规则触发**。在上面的示例中，`orchestrator-planner` 匹配 `*`（拒绝）和 `orchestrator-*`（允许），但由于 `orchestrator-*` 位于 `*` 之后，因此结果为 `allow`。
规则按顺序评估，**最后匹配的规则优先**。在上面的示例中，`orchestrator-planner` 同时匹配 `*`（deny）和 `orchestrator-*`（allow），但由于 `orchestrator-*` 在 `*` 之后，所以结果为 `allow`。
:::
:::tip
用户始终可以通过 `@` 自动完成菜单直接调用任何子代理，即使代理的任务权限会拒绝它。
用户始终可以通过 `@` 自动补全菜单直接调用任何子代理，即使代理的任务权限会拒绝它。
:::
---
### 颜色
在 UI 中的界面外观中使用 `color` 选项自定义代理。这会影响代理在界面中的显示方式。
使用 `color` 选项自定义代理在 UI 中的视觉外观。这会影响代理在界面中的显示方式。
使用有效的十六进制颜色（例如 `#FF5733`）或主题颜色：`primary`、`secondary`、`accent`、`success`、`warning`、`error`、`info`。
@@ -619,7 +618,7 @@ Only analyze code and suggest changes.
### Top P
使用 `top_p` 选项控制响应多样性。控制随机性的温度替代方案。
使用 `top_p` 选项控制响应多样性。这是控制随机性的温度替代方案。
```json title="opencode.json"
{
@@ -635,11 +634,11 @@ Only analyze code and suggest changes.
---
### 其他
### 其他选项
您在代理配置中指定的任何其他选项都将作为模型选项 **直接** 传递给提供商。这允许您使用特定于提供商的功能和参数。
您在代理配置中指定的任何其他选项都将作为模型选项**直接传递**给提供商。这允许您使用提供商特定的功能和参数。
例如，使用 OpenAI 的推理模型，您可以控制推理工作：
例如，使用 OpenAI 的推理模型时，您可以控制推理力度：
```json title="opencode.json" {6,7}
{
@@ -654,10 +653,10 @@ Only analyze code and suggest changes.
}
```
这些附加选项是特定于模型和提供商的。检查提供商的文档以获取可用参数。
这些附加选项是模型和提供商特定的。请查阅您的提供商文档以获取可用参数。
:::tip
运行 `opencode models` 查看可用模型的列表。
运行 `opencode models` 查看可用模型列表。
:::
---
@@ -672,23 +671,23 @@ opencode agent create
此交互式命令将：
1. 询问代理保存在哪里；全局或特定项目。
1. 询问代理的保存位置——全局或项目级。
2. 描述代理应该做什么。
3. 生成适当的系统提示和标识符。
3. 生成合适的系统提示词和标识符。
4. 让您选择代理可以访问哪些工具。
5. 最后，使用代理配置创建一个 markdown 文件。
5. 最后，创建一个包含代理配置的 Markdown 文件。
---
## 使用案例
## 使用场景
以下是不同代理的一些常见用例。
以下是不同代理的一些常见使用场景。
- **Build Agent**：启用所有工具的完整开发工作
- **Plan Agent**：分析规划，不做改动
- **Review Agent**：具有只读访问权限和文档工具的代码审查
- **Debug Agent**：专注于启用 bash 和读取工具的调查
- **Docs Agent**：使用文件操作但不使用系统命令的文档编写
- **Build 代理**：启用所有工具的完整开发工作
- **Plan 代理**：分析和规划，不进行任何更改
- **Review 代理**：具有只读访问权限和文档工具的代码审查
- **Debug 代理**：专注于问题排查，启用 bash 和读取工具
- **Docs 代理**：文档编写，具有文件操作但不使用系统命令
---
@@ -724,7 +723,7 @@ Focus on:
---
### 安全审计员
### 安全审计代理
```markdown title="~/.config/opencode/agents/security-auditor.md"
---

234
packages/web/src/content/docs/zh-cn/cli.mdx
View File

@@ -1,17 +1,17 @@
---
title: CLI
description: opencode CLI 选项和命令。
description: OpenCode CLI 选项和命令。
---
import { Tabs, TabItem } from "@astrojs/starlight/components"
默认情况下，opencode CLI 在不带任何参数运行时启动 [TUI](/docs/tui)。
OpenCode CLI 在不带任何参数运行时，默认启动 [TUI](/docs/tui)。
```bash
opencode
```
但它也接受本页记录的命令。这允许您以编程方式与 opencode 交互。
但它也接受本页面中记录的命令，使您可以通过编程方式与 OpenCode 进行交互。
```bash
opencode run "Explain how closures work in JavaScript"
@@ -21,7 +21,7 @@ opencode run "Explain how closures work in JavaScript"
### tui
启动 opencode 终端用户界面。
启动 OpenCode 终端用户界面。
```bash
opencode [project]
@@ -32,25 +32,25 @@ opencode [project]
| 标志 | 简写 | 描述 |
| ------------ | ---- | --------------------------------------------------------- |
| `--continue` | `-c` | 继续上一个会话 |
| `--session` | `-s` | 继续的会话 ID |
| `--fork` | | 继续时分叉会话（与 `--continue` 或 `--session` 一起使用） |
| `--prompt` | | 使用的提示 |
| `--model` | `-m` | 使用的模型 (provider/model) |
| `--agent` | | 使用的代理 |
| `--session` | `-s` | 要继续的会话 ID |
| `--fork` | | 继续时分叉会话（与 `--continue` 或 `--session` 配合使用） |
| `--prompt` | | 要使用的提示词 |
| `--model` | `-m` | 要使用的模型，格式为 provider/model |
| `--agent` | | 要使用的代理 |
| `--port` | | 监听端口 |
| `--hostname` | | 监听的主机名 |
| `--hostname` | | 监听主机名 |
---
## 命令
opencode CLI 还具有以下命令。
OpenCode CLI 还提供以下命令。
---
### agent
管理 opencode 代理。
管理 OpenCode 的代理。
```bash
opencode agent [command]
@@ -60,13 +60,13 @@ opencode agent [command]
### attach
将终端附加到通过 `serve` 或 `web` 命令启动的已运行 opencode 后端服务器。
将终端连接到已通过 `serve` 或 `web` 命令启动的 OpenCode 后端服务器。
```bash
opencode attach [url]
```
这允许将 TUI 与远程 opencode 后端一起使用。例如：
这允许将 TUI 与远程 OpenCode 后端配合使用。例如：
```bash
# Start the backend server for web/mobile access
@@ -81,19 +81,19 @@ opencode attach http://10.20.30.40:4096
| 标志 | 简写 | 描述 |
| ----------- | ---- | ------------------- |
| `--dir` | | 启动 TUI 的工作目录 |
| `--session` | `-s` | 继续的会话 ID |
| `--session` | `-s` | 要继续的会话 ID |
---
#### create
使用自定义配置创建新代理。
使用自定义配置创建新的代理。
```bash
opencode agent create
```
此命令将指导您使用自定义系统提示和工具配置创建新代理。
此命令将引导您使用自定义系统提示词和工具配置来创建新的代理。
---
@@ -109,7 +109,7 @@ opencode agent list
### auth
用于管理提供商的凭据和登录的命令。
管理提供商的凭据和登录信息的命令。
```bash
opencode auth [command]
@@ -119,25 +119,25 @@ opencode auth [command]
#### login
opencode 由 [Models.dev](https://models.dev) 上的提供商列表支持，因此您可以使用 `opencode auth login` 来为您想要使用的任何提供商配置 API 密钥。它存储在 `~/.local/share/opencode/auth.json` 中。
OpenCode 基于 [Models.dev](https://models.dev) 的提供商列表运行，因此您可以使用 `opencode auth login` 为任何想要使用的提供商配置 API 密钥。密钥存储在 `~/.local/share/opencode/auth.json` 中。
```bash
opencode auth login
```
当 opencode 启动时，它会从凭据文件加载提供商。以及如果在您的环境或项目中的 `.env` 文件中定义了任何密钥。
OpenCode 启动时会从凭据文件加载提供商信息，同时也会加载环境变量或项目中 `.env` 文件中定义的密钥。
---
#### list
列出凭据文件中存储的所有经过身份验证的提供商。
列出凭据文件中存储的所有已认证提供商。
```bash
opencode auth list
```
或者简短的版本。
或使用简写版本。
```bash
opencode auth ls
@@ -147,7 +147,7 @@ opencode auth ls
#### logout
通过从凭据文件中清除提供商，将您从提供商中注销。
从凭据文件中清除提供商信息以完成登出。
```bash
opencode auth logout
@@ -157,7 +157,7 @@ opencode auth logout
### github
管理 GitHub 代理以实现存储库自动化。
管理用于仓库自动化的 GitHub 代理。
```bash
opencode github [command]
@@ -167,36 +167,36 @@ opencode github [command]
#### install
在您的存储库中安装 GitHub 代理。
在您的仓库中安装 GitHub 代理。
```bash
opencode github install
```
这将设置必要的 GitHub Actions 工作流程并指导您完成配置过程。 [了解更多](/docs/github)。
此命令会设置必要的 GitHub Actions 工作流并引导您完成配置过程。[了解更多](/docs/github)。
---
#### run
运行 GitHub 代理。这通常用在 GitHub Actions 中。
运行 GitHub 代理。通常在 GitHub Actions 中使用。
```bash
opencode github run
```
#### 标志
##### 标志
| 标志 | 描述 |
| --------- | ------------------------------ |
| `--event` | 用于运行代理的 GitHub 模拟事件 |
| `--token` | GitHub 个人访问 Token |
| `--token` | GitHub 个人访问令牌 |
---
### mcp
管理模型上下文协议 (MCP) 服务器。
管理 Model Context Protocol 服务器。
```bash
opencode mcp [command]
@@ -212,7 +212,7 @@ opencode mcp [command]
opencode mcp add
```
此命令将指导您添加本地或远程 MCP 服务器。
此命令将引导您添加本地或远程 MCP 服务器。
---
@@ -224,7 +224,7 @@ opencode mcp add
opencode mcp list
```
或者使用简短版本。
或使用简写版本。
```bash
opencode mcp ls
@@ -234,7 +234,7 @@ opencode mcp ls
#### auth
使用启用 OAuth 的 MCP 服务器进行身份验证。
对支持 OAuth 的 MCP 服务器进行认证。
```bash
opencode mcp auth [name]
@@ -242,13 +242,13 @@ opencode mcp auth [name]
如果您不提供服务器名称，系统将提示您从可用的支持 OAuth 的服务器中进行选择。
您还可以列出支持 OAuth 的服务器及其身份验证状态。
您还可以列出支持 OAuth 的服务器及其认证状态。
```bash
opencode mcp auth list
```
或者使用简短版本。
或使用简写版本。
```bash
opencode mcp auth ls
@@ -258,7 +258,7 @@ opencode mcp auth ls
#### logout
删除 MCP 服务器的 OAuth 凭据。
移除 MCP 服务器的 OAuth 凭据。
```bash
opencode mcp logout [name]
@@ -284,11 +284,11 @@ opencode mcp debug <name>
opencode models [provider]
```
此命令以 `provider/model` 格式显示您配置的提供商中可用的所有模型。
此命令以 `provider/model` 的格式显示所有已配置提供商中可用的模型。
这对于确定 [你的配置](/docs/config/) 中使用的确切模型名称很有帮助。
这对于确定在[配置文件](/docs/config/)中使用的确切模型名称非常有用。
您可以选择提供提供商 ID 并按该提供商筛选模型。
您可以选择传入提供商 ID 来按提供商筛选模型。
```bash
opencode models anthropic
@@ -299,9 +299,9 @@ opencode models anthropic
| 标志 | 描述 |
| ----------- | ---------------------------------------- |
| `--refresh` | 从 models.dev 刷新模型缓存 |
| `--verbose` | 使用更详细的模型输出（包括成本等元数据） |
| `--verbose` | 使用更详细的模型输出（包含费用等元数据） |
使用 `--refresh` 标志来更新服务器的模型列表。当新模型已添加到提供商并且您希望在 opencode 中查看它们时，这非常有用。
使用 `--refresh` 标志可以更新缓存的模型列表。当提供商新增了模型并且您希望在 OpenCode 中看到它们时，此功能非常有用。
```bash
opencode models --refresh
@@ -311,19 +311,19 @@ opencode models --refresh
### run
通过直接传递提示以非交互模式运行 opencode。
以非交互模式运行 OpenCode，直接传入提示词。
```bash
opencode run [message..]
```
这对于编写脚本、自动化，或者当您想要快速获得答案而不是完整的 TUI 时非常有用。例如。
这对于脚本编写、自动化或无需启动完整 TUI 即可快速获取答案的场景非常有用。例如：
```bash "opencode run"
opencode run Explain the use of context in Go
```
您还可以附加到正在运行的 `opencode serve` 实例，以避免每次运行时 MCP 服务器冷启动时间：
您还可以连接到正在运行的 `opencode serve` 实例，以避免每次运行时 MCP 服务器的冷启动时间：
```bash
# Start a headless server in one terminal
@@ -336,46 +336,46 @@ opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
#### 标志
| 标志 | 简写 | 描述 |
| ------------ | ---- | --------------------------------------------------------------- |
| `--command` | | 要运行的命令，使用消息作为参数 |
| ------------ | ---- | -------------------------------------------------------------- |
| `--command` | | 要运行的命令，使用 message 作为参数 |
| `--continue` | `-c` | 继续上一个会话 |
| `--session` | `-s` | 继续的会话 ID |
| `--fork` | | 继续时分叉会话（与 `--continue` 或 `--session` 一起使用） |
| `--session` | `-s` | 要继续的会话 ID |
| `--fork` | | 继续时分叉会话（与 `--continue` 或 `--session` 配合使用） |
| `--share` | | 分享会话 |
| `--model` | `-m` | 使用的模型 (provider/model) |
| `--agent` | | 使用的代理 |
| `--file` | `-f` | 要附加到消息的文件 |
| `--format` | | 格式：default（格式化）或 json（原始 JSON 事件） |
| `--title` | | 会话标题（如果未提供值，则使用截断的提示） |
| `--attach` | | 连接到正在运行的 opencode 服务器（例如，http://localhost:4096） |
| `--port` | | 本地服务器的端口（默认为随机端口） |
| `--model` | `-m` | 要使用的模型，格式为 provider/model |
| `--agent` | | 要使用的代理 |
| `--file` | `-f` | 附加到消息的文件 |
| `--format` | | 格式：default（格式化输出）或 json（原始 JSON 事件） |
| `--title` | | 会话标题（未提供值时使用截断的提示词） |
| `--attach` | | 连接到正在运行的 opencode 服务器（例如 http://localhost:4096） |
| `--port` | | 本地服务器端口（默认为随机端口） |
---
### serve
启动无头 opencode 服务器以进行 API 访问。查看 [服务器文档](/docs/server) 以获取完整的 HTTP 接口。
启动无界面的 OpenCode 服务器以提供 API 访问。查看[服务器文档](/docs/server)了解完整的 HTTP 接口。
```bash
opencode serve
```
这将启动一个 HTTP 服务器，该服务器提供对 opencode 功能的 API 访问，无需 TUI 界面。设置 `OPENCODE_SERVER_PASSWORD` 以启用 HTTP 基本身份验证（用户名默认为 `opencode`）。
此命令启动一个 HTTP 服务器，提供对 OpenCode 功能的 API 访问，无需 TUI 界面。设置 `OPENCODE_SERVER_PASSWORD` 可启用 HTTP 基本认证（用户名默认为 `opencode`）。
#### 标志
| 标志 | 描述 |
| ------------ | ------------------------ |
| ------------ | -------------------------- |
| `--port` | 监听端口 |
| `--hostname` | 监听的主机名 |
| `--hostname` | 监听主机名 |
| `--mdns` | 启用 mDNS 发现 |
| `--cors` | 允许 CORS 的其他浏览器源 |
| `--cors` | 允许 CORS 的额外浏览器来源 |
---
### session
管理 opencode 会话。
管理 OpenCode 会话。
```bash
opencode session [command]
@@ -385,7 +385,7 @@ opencode session [command]
#### list
列出所有 opencode 会话。
列出所有 OpenCode 会话。
```bash
opencode session list
@@ -394,15 +394,15 @@ opencode session list
##### 标志
| 标志 | 简写 | 描述 |
| ------------- | ---- | ------------------------------ |
| `--max-count` | `-n` | 限制为最近的 N 个会话 |
| `--format` | | 输出格式：table 或 json(table) |
| ------------- | ---- | ------------------------------------- |
| `--max-count` | `-n` | 限制为最近 N 个会话 |
| `--format` | | 输出格式：table 或 json（默认 table） |
---
### stats
显示 opencode 会话的 Token 使用情况和成本统计信息。
显示 OpenCode 会话的 Token 用量和费用统计信息。
```bash
opencode stats
@@ -411,11 +411,11 @@ opencode stats
#### 标志
| 标志 | 描述 |
| ----------- | -------------------------------------------------------- |
| `--days` | 显示过去 N 天（所有时间）的统计数据 |
| `--tools` | 显示工具数量（全部） |
| `--models` | 显示模型使用情况细分（默认隐藏）。输入一个数字来显示前 N |
| `--project` | 按项目过滤（所有项目，空字符串：当前项目） |
| ----------- | ------------------------------------------------------ |
| `--days` | 显示最近 N 天的统计信息（默认为所有时间） |
| `--tools` | 显示的工具数量（默认为全部） |
| `--models` | 显示模型用量明细（默认隐藏）。传入数字可显示前 N 个 |
| `--project` | 按项目筛选（默认为所有项目，传入空字符串表示当前项目） |
---
@@ -433,13 +433,13 @@ opencode export [sessionID]
### import
从 JSON 文件或 opencode 共享 URL 导入会话数据。
从 JSON 文件或 OpenCode 分享链接导入会话数据。
```bash
opencode import <file>
```
您可以从本地文件或 opencode 共享 URL 导入。
您可以从本地文件或 OpenCode 分享链接导入。
```bash
opencode import session.json
@@ -450,48 +450,48 @@ opencode import https://opncd.ai/s/abc123
### web
使用 Web 界面启动无头 opencode 服务器。
启动带有 Web 界面的无界面 OpenCode 服务器。
```bash
opencode web
```
这将启动 HTTP 服务器并打开 Web 浏览器以通过 Web 界面访问 opencode。设置 `OPENCODE_SERVER_PASSWORD` 以启用 HTTP 基本身份验证（用户名默认为 `opencode`）。
此命令启动一个 HTTP 服务器并打开浏览器，通过 Web 界面访问 OpenCode。设置 `OPENCODE_SERVER_PASSWORD` 可启用 HTTP 基本认证（用户名默认为 `opencode`）。
#### 标志
| 标志 | 描述 |
| ------------ | ------------------------ |
| ------------ | -------------------------- |
| `--port` | 监听端口 |
| `--hostname` | 监听的主机名 |
| `--hostname` | 监听主机名 |
| `--mdns` | 启用 mDNS 发现 |
| `--cors` | 允许 CORS 的其他浏览器源 |
| `--cors` | 允许 CORS 的额外浏览器来源 |
---
### acp
启动 ACP (Agent Client Protocol) 服务器。
启动 ACP（Agent Client Protocol）服务器。
```bash
opencode acp
```
此命令启动一个 ACP 服务器，该服务器使用 nd-JSON 通过 stdin/stdout 进行通信。
此命令启动一个通过 stdin/stdout 使用 nd-JSON 进行通信的 ACP 服务器。
#### 标志
| 标志 | 描述 |
| ------------ | ------------ |
| ------------ | ---------- |
| `--cwd` | 工作目录 |
| `--port` | 监听端口 |
| `--hostname` | 监听的主机名 |
| `--hostname` | 监听主机名 |
---
### uninstall
卸载 opencode 并删除所有相关文件。
卸载 OpenCode 并删除所有相关文件。
```bash
opencode uninstall
@@ -500,29 +500,29 @@ opencode uninstall
#### 标志
| 标志 | 简写 | 描述 |
| --------------- | ---- | ---------------------------- |
| --------------- | ---- | ------------------------------ |
| `--keep-config` | `-c` | 保留配置文件 |
| `--keep-data` | `-d` | 保留会话数据和快照 |
| `--dry-run` | | 显示将删除的内容但不实际删除 |
| `--dry-run` | | 显示将被删除的内容但不实际删除 |
| `--force` | `-f` | 跳过确认提示 |
---
### upgrade
将 opencode 更新到最新版本或特定版本。
将 OpenCode 更新到最新版本或指定版本。
```bash
opencode upgrade [target]
```
升级到最新版本。
更新到最新版本。
```bash
opencode upgrade
```
升级到特定版本。
更新到指定版本。
```bash
opencode upgrade v0.1.48
@@ -532,71 +532,71 @@ opencode upgrade v0.1.48
| 标志 | 简写 | 描述 |
| ---------- | ---- | ------------------------------------------ |
| `--method` | `-m` | 使用的安装方法；curl, npm, pnpm, bun, brew |
| `--method` | `-m` | 使用的安装方式：curl、npm、pnpm、bun、brew |
---
## 全局标志
opencode CLI 接受以下全局标志。
OpenCode CLI 接受以下全局标志。
| 标志 | 简写 | 描述 |
| -------------- | ---- | ----------------------------------- |
| `--help` | `-h` | 显示帮助 |
| -------------- | ---- | ------------------------------------ |
| `--help` | `-h` | 显示帮助信息 |
| `--version` | `-v` | 打印版本号 |
| `--print-logs` | | 将日志打印到 stderr |
| `--log-level` | | 日志级别 (DEBUG, INFO, WARN, ERROR) |
| `--print-logs` | | 将日志输出到 stderr |
| `--log-level` | | 日志级别（DEBUG、INFO、WARN、ERROR） |
---
## 环境变量
可以使用环境变量配置 opencode。
OpenCode 可以通过环境变量进行配置。
| 变量 | 类型 | 描述 |
| ------------------------------------- | ------- | ----------------------------------------- |
| `OPENCODE_AUTO_SHARE` | boolean | 自动共享会话 |
| ------------------------------------- | ------- | --------------------------------------- |
| `OPENCODE_AUTO_SHARE` | boolean | 自动分享会话 |
| `OPENCODE_GIT_BASH_PATH` | string | Windows 上 Git Bash 可执行文件的路径 |
| `OPENCODE_CONFIG` | string | 配置文件路径 |
| `OPENCODE_CONFIG_DIR` | string | 配置目录的路径 |
| `OPENCODE_CONFIG_CONTENT` | string | 内联 json 配置内容 |
| `OPENCODE_CONFIG_DIR` | string | 配置目录路径 |
| `OPENCODE_CONFIG_CONTENT` | string | 内联 JSON 配置内容 |
| `OPENCODE_DISABLE_AUTOUPDATE` | boolean | 禁用自动更新检查 |
| `OPENCODE_DISABLE_PRUNE` | boolean | 禁用数据的修剪 |
| `OPENCODE_DISABLE_PRUNE` | boolean | 禁用旧数据清理 |
| `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | 禁用自动终端标题更新 |
| `OPENCODE_PERMISSION` | string | 内联 json 权限配置 |
| `OPENCODE_PERMISSION` | string | 内联 JSON 权限配置 |
| `OPENCODE_DISABLE_DEFAULT_PLUGINS` | boolean | 禁用默认插件 |
| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | 禁用自动 LSP 服务器下载 |
| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | 启用实验模型 |
| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | 禁用 LSP 服务器自动下载 |
| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | 启用实验性模型 |
| `OPENCODE_DISABLE_AUTOCOMPACT` | boolean | 禁用自动上下文压缩 |
| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | 禁用从 `.claude` 读取（提示+技能） |
| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | 禁用读取 `.claude`（提示词 + 技能） |
| `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | 禁用读取 `~/.claude/CLAUDE.md` |
| `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | 禁用加载 `.claude/skills` |
| `OPENCODE_DISABLE_MODELS_FETCH` | boolean | 禁用从远程源获取模型 |
| `OPENCODE_FAKE_VCS` | string | 用于测试目的的伪造 VCS |
| `OPENCODE_DISABLE_FILETIME_CHECK` | boolean | 禁用文件时间检查以进行优化 |
| `OPENCODE_FAKE_VCS` | string | 用于测试目的的模拟 VCS 提供商 |
| `OPENCODE_DISABLE_FILETIME_CHECK` | boolean | 禁用文件时间检查优化 |
| `OPENCODE_CLIENT` | string | 客户端标识符（默认为 `cli`） |
| `OPENCODE_ENABLE_EXA` | boolean | 启用 Exa 网络搜索工具 |
| `OPENCODE_SERVER_PASSWORD` | string | 为 `serve`/`web` 启用基本身份验证 |
| `OPENCODE_SERVER_USERNAME` | string | 覆盖基本身份验证用户名（默认 `opencode`） |
| `OPENCODE_MODELS_URL` | string | 用于获取模型配置的自定义 URL |
| `OPENCODE_SERVER_PASSWORD` | string | 为 `serve`/`web` 启用基本认证 |
| `OPENCODE_SERVER_USERNAME` | string | 覆盖基本认证用户名（默认为 `opencode`） |
| `OPENCODE_MODELS_URL` | string | 自定义模型配置获取 URL |
---
### 实验性功能
这些环境变量启用可能会更改或删除的实验性功能。
这些环境变量用于启用可能会更改或移除的实验性功能。
| 变量 | 类型 | 描述 |
| ----------------------------------------------- | ------- | ----------------------------------- |
| ----------------------------------------------- | ------- | ------------------------------- |
| `OPENCODE_EXPERIMENTAL` | boolean | 启用所有实验性功能 |
| `OPENCODE_EXPERIMENTAL_ICON_DISCOVERY` | boolean | 启用图标发现 |
| `OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT` | boolean | 在 TUI 中禁用选择时复制 |
| `OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS` | number | bash 命令的默认超时（以毫秒为单位） |
| `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | number | LLM 响应的最大输出 Token |
| `OPENCODE_EXPERIMENTAL_FILEWATCHER` | boolean | 为整个目录启用文件观察器 |
| `OPENCODE_EXPERIMENTAL_OXFMT` | boolean | 启用 oxfmt 格式化程序 |
| `OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT` | boolean | 禁用 TUI 中的选中即复制 |
| `OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS` | number | bash 命令的默认超时时间（毫秒） |
| `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | number | LLM 响应的最大输出 Token 数 |
| `OPENCODE_EXPERIMENTAL_FILEWATCHER` | boolean | 启用整个目录的文件监听器 |
| `OPENCODE_EXPERIMENTAL_OXFMT` | boolean | 启用 oxfmt 格式化器 |
| `OPENCODE_EXPERIMENTAL_LSP_TOOL` | boolean | 启用实验性 LSP 工具 |
| `OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER` | boolean | 禁用文件观察器 |
| `OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER` | boolean | 禁用文件监听器 |
| `OPENCODE_EXPERIMENTAL_EXA` | boolean | 启用实验性 Exa 功能 |
| `OPENCODE_EXPERIMENTAL_LSP_TY` | boolean | 启用实验性 LSP 类型检查 |
| `OPENCODE_EXPERIMENTAL_MARKDOWN` | boolean | 启用实验性 Markdown 功能 |

93
packages/web/src/content/docs/zh-cn/commands.mdx
View File

@@ -3,13 +3,13 @@ title: 命令
description: 为重复任务创建自定义命令。
---
自定义命令允许您指定在 TUI 中执行该命令时要运行的提示。
自定义命令允许你指定一个提示词，当在 TUI 中执行该命令时会运行这个提示词。
```bash frame="none"
/my-command
```
除了 `/init`、`/undo`、`/redo`、`/share`、`/help` 等内置命令之外，还有自定义命令。 [了解更多](/docs/tui#commands)。
自定义命令是 `/init`、`/undo`、`/redo`、`/share`、`/help` 等内置命令之外的补充。[了解更多](/docs/tui#commands)。
---
@@ -30,9 +30,9 @@ Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.
```
frontmatter 定义命令属性。内容成为模板。
frontmatter 定义命令属性，内容则成为模板。
通过键入 `/` 后跟命令名称来使用该命令。
通过输入 `/` 后跟命令名称来使用该命令。
```bash frame="none"
"/test"
@@ -42,13 +42,13 @@ frontmatter 定义命令属性。内容成为模板。
## 配置
您可以通过 opencode 配置或通过在 `commands/` 目录中创建 markdown 文件来添加自定义命令。
你可以通过 OpenCode 配置或在 `commands/` 目录中创建 markdown 文件来添加自定义命令。
---
### JSON
在 opencode [配置](/docs/config) 中使用 `command` 选项：
在 OpenCode [配置](/docs/config)中使用 `command` 选项：
```json title="opencode.jsonc" {4-12}
{
@@ -67,7 +67,7 @@ frontmatter 定义命令属性。内容成为模板。
}
```
现在您可以在 TUI 中运行这个命令：
现在你可以在 TUI 中运行这个命令：
```bash frame="none"
/test
@@ -77,10 +77,10 @@ frontmatter 定义命令属性。内容成为模板。
### Markdown
您还可以使用 Markdown 文件定义命令。将它们放入：
你还可以使用 markdown 文件定义命令。将它们放在：
- 全局：`~/.config/opencode/commands/`
- 每个项目：`.opencode/commands/`
- 项目级：`.opencode/commands/`
```markdown title="~/.config/opencode/commands/test.md"
---
@@ -93,8 +93,7 @@ Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.
```
Markdown 文件名成为命令名。例如，`test.md` 让
你运行：
markdown 文件名即为命令名。例如，`test.md` 允许你运行：
```bash frame="none"
/test
@@ -102,15 +101,15 @@ Markdown 文件名成为命令名。例如，`test.md` 让
---
## 提示配置
## 提示词配置
自定义命令的提示支持几个特殊的占位符和语法。
自定义命令的提示词支持多种特殊占位符和语法。
---
### 参数
使用 `$ARGUMENTS` 占位符将参数提交给命令。
使用 `$ARGUMENTS` 占位符向命令传递参数。
```md title=".opencode/commands/component.md"
---
@@ -121,20 +120,20 @@ Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.
```
使用参数运行命令：
带参数运行命令：
```bash frame="none"
/component Button
```
`$ARGUMENTS` 将替换为 `Button`。
`$ARGUMENTS` 将被替换为 `Button`。
您还可以使用位置参数访问各个参数：
你还可以使用位置参数访问各个参数：
- `$1` - 第一个参数
- `$2` - 第二个参数
- `$3` - 第三个参数
- 等等...
- 以此类推...
例如：
@@ -153,19 +152,19 @@ with the following content: $3
/create-file config.json src "{ \"key\": \"value\" }"
```
这取代了：
替换结果为：
- `$1` 与 `config.json`
- `$2` 与 `src`
- `$3` 与 `{ "key": "value" }`
- `$1` 替换为 `config.json`
- `$2` 替换为 `src`
- `$3` 替换为 `{ "key": "value" }`
---
### Shell 输出
使用 _!`command`_ 将 [bash 命令](/docs/tui#bash-commands) 输出注入到提示符中。
使用 _!`command`_ 将 [bash 命令](/docs/tui#bash-commands)输出注入到提示词中。
例如，要创建分析测试覆盖率的自定义命令：
例如，创建一个分析测试覆盖率的自定义命令：
```md title=".opencode/commands/analyze-coverage.md"
---
@@ -191,13 +190,13 @@ Recent git commits:
Review these changes and suggest any improvements.
```
命令在项目的根目录中运行，其输出成为提示的一部分。
命令在项目的根目录中运行，其输出会成为提示词的一部分。
---
### 文件引用
使用 `@` 后跟文件名将文件包含在命令中。
使用 `@` 后跟文件名在命令中引用文件。
```md title=".opencode/commands/review-component.md"
---
@@ -208,19 +207,19 @@ Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.
```
文件内容会自动包含在提示中。
文件内容会自动包含在提示词中。
---
## 选项
让我们详细看看配置选项。
让我们详细了解各配置选项。
---
### template
### Template
`template` 选项定义执行命令时将发送到 LLM 的提示。
`template` 选项定义执行命令时发送给 LLM 的提示词。
```json title="opencode.json"
{
@@ -236,7 +235,7 @@ Check for performance issues and suggest improvements.
---
### description
### Description
使用 `description` 选项提供命令功能的简要描述。
@@ -250,15 +249,15 @@ Check for performance issues and suggest improvements.
}
```
当您输入命令时，这将在 TUI 中显示为描述。
当你输入命令时，这将在 TUI 中显示为描述。
---
### agent
### Agent
使用 `agent` 配置选择指定哪个 [Agent](/docs/agents) 应执行此命令。
如果是 [Subagents](/docs/agents/#subagents) 该命令将默认触发子代理调用。
要取消此行为，则将 `subtask` 设置为 `false`。
使用 `agent` 配置可选地指定由哪个[代理](/docs/agents)执行此命令。
如果这是一个[子代理](/docs/agents/#subagents)，该命令默认会触发子代理调用。
要禁用此行为，请将 `subtask` 设置为 `false`。
```json title="opencode.json"
{
@@ -270,15 +269,15 @@ Check for performance issues and suggest improvements.
}
```
这是一个 **可选** 配置选项。如果未指定，则默认为您当前的代理。
这是一个**可选的**配置选项。如果未指定，默认使用你当前的代理。
---
### subtask
### Subtask
使用 `subtask` 布尔值强制命令触发 [Subagents](/docs/agents/#subagents) 调用。
如果您希望命令不污染您的主要上下文并且将 **强制** 代理充当子代理，那么这非常有用，
即使 `mode` 在 [Agent](/docs/agents) 配置上设置为 `primary`。
使用 `subtask` 布尔值强制命令触发[子代理](/docs/agents/#subagents)调用。
如果你希望命令不污染主要上下文，这会很有用，它会**强制**代理作为子代理运行，
即使[代理](/docs/agents)配置中的 `mode` 设置为 `primary`。
```json title="opencode.json"
{
@@ -290,11 +289,11 @@ Check for performance issues and suggest improvements.
}
```
这是一个 **可选** 配置选项。
这是一个**可选的**配置选项。
---
### model
### Model
使用 `model` 配置覆盖此命令的默认模型。
@@ -308,16 +307,16 @@ Check for performance issues and suggest improvements.
}
```
这是一个 **可选** 配置选项。
这是一个**可选的**配置选项。
---
## 内置
## 内置命令
opencode 包含 `/init`、`/undo`、`/redo`、`/share`、`/help` 等内置命令；[了解更多](/docs/tui#commands)。
opencode 包含多个内置命令，如 `/init`、`/undo`、`/redo`、`/share`、`/help`；[了解更多](/docs/tui#commands)。
:::note
自定义命令可以覆盖内置命令。
:::
如果您定义同名的自定义命令，它将覆盖内置命令。
如果你定义了同名的自定义命令，它将覆盖内置命令。

198
packages/web/src/content/docs/zh-cn/config.mdx
View File

@@ -1,15 +1,15 @@
---
title: 配置
description: 使用 opencode JSON 配置。
description: 使用 OpenCode JSON 配置。
---
您可以使用 JSON 配置文件配置 opencode。
您可以使用 JSON 配置文件来配置 OpenCode。
---
## 格式
opencode 支持 **JSON** 和 **JSONC**（带注释的 JSON）格式。
OpenCode 支持 **JSON** 和 **JSONC**（带注释的 JSON）格式。
```jsonc title="opencode.jsonc"
{
@@ -25,44 +25,44 @@ opencode 支持 **JSON** 和 **JSONC**（带注释的 JSON）格式。
## 位置
您可以将配置放置在几个不同的位置，它们有一个不同的优先顺序。
您可以将配置放置在不同的位置，它们具有不同的优先级顺序。
:::note
配置文件**合并在一起**，而不是替换。
配置文件是**合并在一起**的，而不是替换。
:::
配置文件被合并在一起，而不是被替换。以下配置位置的设置被合并。仅当密钥冲突时，后面的配置才会覆盖前面的配置。保留所有配置中的非冲突设置。
配置文件是合并在一起的，而不是被替换。来自以下配置位置的设置会被合并。后面的配置仅在键冲突时覆盖前面的配置。所有配置中的非冲突设置都会被保留。
例如，如果您的全局配置设置 `theme: "opencode"` 和 `autoupdate: true`，并且您的项目配置设置 `model: "anthropic/claude-sonnet-4-5"`，则最终配置将包括所有三个设置。
例如，如果您的全局配置设置了 `theme: "opencode"` 和 `autoupdate: true`，而您的项目配置设置了 `model: "anthropic/claude-sonnet-4-5"`，则最终配置将包含所有三个设置。
---
### 优先级
### 优先级顺序
配置源按以下顺序加载（后面的源覆盖前面的源）：
1. **Remote config** (来自 `.well-known/opencode`) - 组织默认值
2. **Global config** (`~/.config/opencode/opencode.json`) - 用户首选项
3. **Custom config** (`OPENCODE_CONFIG` env var) - 自定义覆盖
4. **Project config** (项目中的 `opencode.json`) - 项目特定的设置
1. **远程配置**（来自 `.well-known/opencode`）- 组织默认值
2. **全局配置**（`~/.config/opencode/opencode.json`）- 用户偏好
3. **自定义配置**（`OPENCODE_CONFIG` 环境变量）- 自定义覆盖
4. **项目配置**（项目中的 `opencode.json`）- 项目特定设置
5. **`.opencode` 目录** - 代理、命令、插件
6. **Inline config** (`OPENCODE_CONFIG_CONTENT` env var) - 运行时覆盖
6. **内联配置**（`OPENCODE_CONFIG_CONTENT` 环境变量）- 运行时覆盖
这意味着项目配置可以覆盖全局默认值，全局配置可以覆盖远程组织默认值。
:::note
`.opencode` 和 `~/.config/opencode` 目录对子目录使用 **复数名称**：`agents/`、`commands/`、`modes/`、`plugins/`、`skills/`、`tools/` 和 `themes/`。为了向后兼容，还支持单数名称（例如 `agent/`）。
`.opencode` 和 `~/.config/opencode` 目录的子目录使用**复数名称**：`agents/`、`commands/`、`modes/`、`plugins/`、`skills/`、`tools/` 和 `themes/`。为了向后兼容，也支持单数名称（例如 `agent/`）。
:::
---
### 远程
组织可以通过 `.well-known/opencode` 端点提供默认配置。当您向支持的提供商进行身份验证时，会自动获取该信息。
组织可以通过 `.well-known/opencode` 端点提供默认配置。当您使用支持该功能的提供商进行身份验证时，会自动获取此配置。
首先加载远程配置，作为基础层。所有其他配置源（全局、项目）都可以覆盖这些默认值。
远程配置最先加载，作为基础层。所有其他配置源（全局、项目）都可以覆盖这些默认值。
例如，如果您的组织提供默认禁用的 MCP 服务器：
例如，如果您的组织提供了默认禁用的 MCP 服务器：
```json title="Remote config from .well-known/opencode"
{
@@ -94,7 +94,7 @@ opencode 支持 **JSON** 和 **JSONC**（带注释的 JSON）格式。
### 全局
将全局 opencode 配置放在 `~/.config/opencode/opencode.json` 中。使用全局配置来实现用户范围的首选项，例如主题、提供商或按键绑定。
将全局 OpenCode 配置放在 `~/.config/opencode/opencode.json` 中。使用全局配置来设置用户级别的偏好，例如主题、提供商或快捷键。
全局配置覆盖远程组织默认值。
@@ -102,15 +102,15 @@ opencode 支持 **JSON** 和 **JSONC**（带注释的 JSON）格式。
### 项目级
在项目根目录中添加 `opencode.json`。项目配置在标准配置文件中具有最高优先级 - 它覆盖全局配置和远程配置。
在项目根目录中添加 `opencode.json`。项目配置在标准配置文件中具有最高优先级——它会覆盖全局配置和远程配置。
:::tip
将项目特定配置放在项目的根目录中。
:::
当 opencode 启动时，它会在当前目录中查找配置文件或向上遍历到最近的 Git 目录。
当 OpenCode 启动时，它会在当前目录中查找配置文件，或向上遍历到最近的 Git 目录。
这也可以安全地签入 Git 并使用与全局模式相同的架构。
该配置文件也可以安全地提交到 Git 中，并使用与全局配置相同的 Schema。
---
@@ -123,34 +123,34 @@ export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"
```
自定义配置按优先顺序在全局配置和项目配置之间加载。
自定义配置在优先级顺序中位于全局配置和项目配置之间加载。
---
### 自定义目录
使用 `OPENCODE_CONFIG_DIR` 环境变量指定自定义配置目录。将在该目录中搜索代理、命令、模式和插件，就像标准 `.opencode` 目录一样，并且应该遵循相同的结构。
使用 `OPENCODE_CONFIG_DIR` 环境变量指定自定义配置目录。该目录会像标准 `.opencode` 目录一样被搜索代理、命令、模式和插件，并且应遵循相同的结构。
```bash
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"
```
自定义目录在全局配置和 `.opencode` 目录加载后，因此 **可以覆盖** 它们的设置。
自定义目录在全局配置和 `.opencode` 目录之后加载，因此**可以覆盖**它们的设置。
---
## 模式
## Schema
配置文件具有在 [**`opencode.ai/config.json`**](https://opencode.ai/config.json) 中定义的架构。
配置文件具有在 [**`opencode.ai/config.json`**](https://opencode.ai/config.json) 中定义的 Schema。
您的编辑器应该能够根据架构进行验证和自动完成。
您的编辑器应该能够基于该 Schema 进行验证和自动补全。
---
### TUI
您可以通过 `tui` 选项配置特定于 TUI 的设置。
您可以通过 `tui` 选项配置 TUI 相关设置。
```json title="opencode.json"
{
@@ -168,16 +168,16 @@ opencode run "Hello world"
可用选项：
- `scroll_acceleration.enabled` - 启用 macOS 风格的滚动加速。**优先于 `scroll_speed`。**
- `scroll_speed` - 自定义滚动速度倍增（默认值：`3`，最小值：`1`）。如果 `scroll_acceleration.enabled` 是 `true`，则忽略。
- `diff_style` - 控制差异渲染。 `"auto"` 适应终端宽度，`"stacked"` 始终显示单列。
- `scroll_speed` - 自定义滚动速度倍率（默认值：`3`，最小值：`1`）。如果 `scroll_acceleration.enabled` 为 `true`，则忽略此选项。
- `diff_style` - 控制差异渲染方式。`"auto"` 根据终端宽度自适应，`"stacked"` 始终显示单列。
[在此处了解有关使用 TUI 的更多信息](/docs/tui)。
[在此了解更多关于 TUI 的信息](/docs/tui)。
---
### 服务器
您可以通过 `opencode serve` 选项为 `opencode web` 和 `server` 命令配置服务器设置。
您可以通过 `server` 选项为 `opencode serve` 和 `opencode web` 命令配置服务器设置。
```json title="opencode.json"
{
@@ -195,12 +195,12 @@ opencode run "Hello world"
可用选项：
- `port` - 监听端口。
- `hostname` - 监听的主机名。当 `mdns` 启用且未设置主机名时，默认为 `0.0.0.0`。
- `mdns` - 启用 mDNS 服务发现。这允许网络上的其他设备发现您的 opencode 服务器。
- `mdnsDomain` - mDNS 服务的自定义域名。默认为 `opencode.local`。对于在同一个网络上运行多个实例很有帮助。
- `cors` - 从基于浏览器的客户端使用 HTTP 服务器时允许 CORS 的其他来源。值必须是完整来源（协议+主机+可选端口），例如 `https://app.example.com`。
- `hostname` - 监听主机名。当 `mdns` 启用且未设置主机名时，默认为 `0.0.0.0`。
- `mdns` - 启用 mDNS 服务发现。这允许网络上的其他设备发现您的 OpenCode 服务器。
- `mdnsDomain` - mDNS 服务的自定义域名。默认为 `opencode.local`。适用于在同一网络上运行多个实例的场景。
- `cors` - 从基于浏览器的客户端使用 HTTP 服务器时允许 CORS 的额外来源。值必须是完整的来源（协议 + 主机 + 可选端口），例如 `https://app.example.com`。
[在此处了解有关服务器的更多信息](/docs/server)。
[在此了解更多关于服务器的信息](/docs/server)。
---
@@ -218,13 +218,13 @@ opencode run "Hello world"
}
```
[在此处了解有关工具的更多信息](/docs/tools)。
[在此了解更多关于工具的信息](/docs/tools)。
---
### 模型
您可以通过 `provider`、`model` 和 `small_model` 选项来配置要在 opencode 配置中使用的提供商和模型。
您可以通过 `provider`、`model` 和 `small_model` 选项在 OpenCode 配置中设置要使用的提供商和模型。
```json title="opencode.json"
{
@@ -235,7 +235,7 @@ opencode run "Hello world"
}
```
`small_model` 选项为标题生成等轻量级任务配置单独的模型。默认情况下，如果您的提供商可以提供更便宜的模型，opencode 会尝试使用更便宜的模型，否则它会退回到您的主模型。
`small_model` 选项为标题生成等轻量级任务配置单独的模型。默认情况下，如果您的提供商有更便宜的模型可用，OpenCode 会尝试使用该模型，否则会回退到您的主模型。
提供商选项可以包括 `timeout` 和 `setCacheKey`：
@@ -253,16 +253,16 @@ opencode run "Hello world"
}
```
- `timeout` - 请求超时以毫秒为单位（默认值：300000）。设置为 `false` 以禁用。
- `setCacheKey` - 确保始终为指定的提供商设置缓存键。
- `timeout` - 请求超时时间，单位为毫秒（默认值：300000）。设置为 `false` 可禁用超时。
- `setCacheKey` - 确保始终为指定提供商设置缓存键。
您还可以配置[本地模型](/docs/models#local)。[了解更多](/docs/models)。
---
#### 特定于提供商的选项
#### 提供商特定选项
有些提供商支持除通用 `timeout` 和 `apiKey` 之外的其他配置选项。
一些提供商支持除通用 `timeout` 和 `apiKey` 设置之外的额外配置选项。
##### Amazon Bedrock
@@ -283,21 +283,21 @@ Amazon Bedrock 支持 AWS 特定配置：
}
```
- `region` - Bedrock 的 AWS 区域（默认为 `AWS_REGION` env var 或 `us-east-1`）
- `profile` - 来自 `~/.aws/credentials` 的 AWS 命名配置文件（默认为 `AWS_PROFILE` env var）
- `endpoint` - VPC 终端节点的自定义节点 URL。这是使用 AWS 特定术语的通用 `baseURL` 选项的别名。如果两者都指定，`endpoint` 优先。
- `region` - Bedrock 的 AWS 区域（默认为 `AWS_REGION` 环境变量或 `us-east-1`）
- `profile` - 来自 `~/.aws/credentials` 的 AWS 命名配置文件（默认为 `AWS_PROFILE` 环境变量）
- `endpoint` - VPC 端点的自定义端点 URL。这是通用 `baseURL` 选项使用 AWS 特定术语的别名。如果两者都指定，`endpoint` 优先。
:::note
Bearer Tokens (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 优先于基于配置文件的身份验证。详情请参见 [身份验证优先级](/docs/providers#authentication-precedence)。
Bearer Token（`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`）优先于基于配置文件的身份验证。详情请参见[身份验证优先级](/docs/providers#authentication-precedence)。
:::
[了解有关 Amazon Bedrock 配置的更多信息](/docs/providers#amazon-bedrock)。
[了解更多关于 Amazon Bedrock 配置的信息](/docs/providers#amazon-bedrock)。
---
### 主题
您可以通过 opencode 配置中的 `theme` 选项配置要使用的主题。
您可以通过 OpenCode 配置中的 `theme` 选项设置要使用的主题。
```json title="opencode.json"
{
@@ -306,7 +306,7 @@ Bearer Tokens (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 优先于基于配置
}
```
[在这里了解更多](/docs/themes)。
[在此了解更多](/docs/themes)。
---
@@ -332,13 +332,13 @@ Bearer Tokens (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 优先于基于配置
}
```
您还可以使用 `~/.config/opencode/agents/` 或 `.opencode/agents/` 中的 markdown 文件定义代理。 [在这里了解更多](/docs/agents)。
您还可以使用 `~/.config/opencode/agents/` 或 `.opencode/agents/` 中的 Markdown 文件定义代理。[在此了解更多](/docs/agents)。
---
### 默认代理
您可以使用 `default_agent` 选项设置默认代理。当没有明确指定时，这将确定使用哪个代理。
您可以使用 `default_agent` 选项设置默认代理。当未明确指定代理时，将使用该默认代理。
```json title="opencode.json"
{
@@ -347,9 +347,9 @@ Bearer Tokens (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 优先于基于配置
}
```
默认代理必须是 Primary 代理（不是 Subagent）。这可以是内置代理（如 `"build"` 或 `"plan"`），也可以是您定义的 [Custom Agent](/docs/agents)。如果指定的代理不存在或者是子代理，opencode 将回退到 `"build"` 并发出警告。
默认代理必须是主代理（不能是子代理）。可以是内置代理（如 `"build"` 或 `"plan"`），也可以是您定义的[自定义代理](/docs/agents)。如果指定的代理不存在或是子代理，OpenCode 将回退到 `"build"` 并发出警告。
此设置适用于所有界面：TUI、CLI (`opencode run`)、桌面应用程序和 GitHub Action。
此设置适用于所有界面：TUI、CLI（`opencode run`）、桌面应用和 GitHub Action。
---
@@ -364,13 +364,13 @@ Bearer Tokens (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 优先于基于配置
}
```
这需要：
该选项接受：
- `"manual"` - 允许通过命令手动共享（默认）
- `"auto"` - 自动分享新对话
- `"disabled"` - 完全禁用共享
- `"manual"` - 允许通过命令手动分享（默认）
- `"auto"` - 自动分享新会话
- `"disabled"` - 完全禁用分享
默认情况下，共享设置为手动模式，您需要使用 `/share` 命令显式共享对话。
默认情况下，分享设置为手动模式，您需要使用 `/share` 命令显式分享会话。
---
@@ -396,13 +396,13 @@ Bearer Tokens (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 优先于基于配置
}
```
您还可以使用 `~/.config/opencode/commands/` 或 `.opencode/commands/` 中的 Markdown 文件定义命令。 [在这里了解更多](/docs/commands)。
您还可以使用 `~/.config/opencode/commands/` 或 `.opencode/commands/` 中的 Markdown 文件定义命令。[在此了解更多](/docs/commands)。
---
### 快捷键
您可以通过 `keybinds` 选项自定义您的按键绑定。
您可以通过 `keybinds` 选项自定义快捷键。
```json title="opencode.json"
{
@@ -411,13 +411,13 @@ Bearer Tokens (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 优先于基于配置
}
```
[在这里了解更多](/docs/keybinds)。
[在此了解更多](/docs/keybinds)。
---
### 自动更新
opencode 将在启动时自动下载任何新的更新。您可以使用 `autoupdate` 选项禁用此功能。
OpenCode 启动时会自动下载新版本。您可以使用 `autoupdate` 选项禁用此功能。
```json title="opencode.json"
{
@@ -426,8 +426,8 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
如果您不想更新但希望在新版本可用时收到通知，则需将 `autoupdate` 设置为 `"notify"`。
请注意，这仅在未使用 Homebrew 等包管理器安装时才有效。
如果您不想自动更新但希望在新版本可用时收到通知，可将 `autoupdate` 设置为 `"notify"`。
请注意，此功能仅在未通过 Homebrew 等包管理器安装时有效。
---
@@ -453,15 +453,15 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
[在这里了解有关格式化程序的更多信息](/docs/formatters)。
[在此了解更多关于格式化程序的信息](/docs/formatters)。
---
### 权限
默认情况下，opencode **允许所有操作**，无需明确批准。您可以使用 `permission` 选项更改此设置。
默认情况下，OpenCode **允许所有操作**，无需明确批准。您可以使用 `permission` 选项更改此行为。
例如，要确保 `edit` 和 `bash` 工具需要用户批准：
例如，要让 `edit` 和 `bash` 工具需要用户确认：
```json title="opencode.json"
{
@@ -473,7 +473,7 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
[在此处了解有关权限的更多信息](/docs/permissions)。
[在此了解更多关于权限的信息](/docs/permissions)。
---
@@ -486,19 +486,21 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
"$schema": "https://opencode.ai/config.json",
"compaction": {
"auto": true,
"prune": true
"prune": true,
"reserved": 10000
}
}
```
- `auto` - 当上下文已满时自动压缩会话（默认值：`true`）。
- `prune` - 删除旧工具输出以保存 Tokens（默认值：`true`）。
- `prune` - 删除旧的工具输出以节省 Token（默认值：`true`）。
- `reserved` - 压缩时的 Token 缓冲区。保留足够的窗口以避免压缩过程中溢出。
---
### 观察器
### 文件监视器
您可以通过 `watcher` 选项配置文件观察器忽略模式。
您可以通过 `watcher` 选项配置文件监视器的忽略模式。
```json title="opencode.json"
{
@@ -509,7 +511,7 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
模式遵循 glob 语法。使用它可以从文件监视中排除嘈杂的目录。
模式遵循 glob 语法。使用此选项可以从文件监视中排除频繁变动的目录。
---
@@ -524,13 +526,13 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
[在这里了解更多](/docs/mcp-servers)。
[在此了解更多](/docs/mcp-servers)。
---
### 插件
[Plugins](/docs/plugins) 使用自定义工具、挂钩和集成扩展 opencode。
[插件](/docs/plugins)通过自定义工具、钩子和集成来扩展 OpenCode。
将插件文件放置在 `.opencode/plugins/` 或 `~/.config/opencode/plugins/` 中。您还可以通过 `plugin` 选项从 npm 加载插件。
@@ -541,13 +543,13 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
[在这里了解更多](/docs/plugins)。
[在此了解更多](/docs/plugins)。
---
### 指令
您可以通过 `instructions` 选项配置您正在使用的模型的说明。
您可以通过 `instructions` 选项为所使用的模型配置指令。
```json title="opencode.json"
{
@@ -556,13 +558,13 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
这需要指令文件的路径和 glob 模式数组。 [在此处了解有关规则的更多信息](/docs/rules)。
该选项接受指令文件路径和 glob 模式的数组。[在此了解更多关于规则的信息](/docs/rules)。
---
### 禁用提供商
您可以通过 `disabled_providers` 选项禁用自动加载的提供商。当您想要阻止加载某些提供商（即使其凭据可用）时，这非常有用。
您可以通过 `disabled_providers` 选项禁用自动加载的提供商。当您希望阻止某些提供商被加载（即使其凭据可用）时，此选项非常有用。
```json title="opencode.json"
{
@@ -575,17 +577,17 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
`disabled_providers` 优先于 `enabled_providers`。
:::
`disabled_providers` 选项接受提供商 ID 数组。当提供商被禁用时：
`disabled_providers` 选项接受提供商 ID 的数组。当某个提供商被禁用时：
- 即使设置了环境变量也不会加载。
- 即使通过 `/connect` 命令配置 API 密钥，也不会加载它。
- 提供商的模型不会出现在模型选择列表中。
- 即使设置了环境变量，也不会被加载。
- 即使通过 `/connect` 命令配置了 API 密钥，也不会被加载。
- 该提供商的模型不会出现在模型选择列表中。
---
### 启用提供商
您可以通过 `enabled_providers` 选项指定允许的提供商列表。设置后，仅启用指定的提供商，所有其他提供商将被忽略。
您可以通过 `enabled_providers` 选项指定允许使用的提供商白名单。设置后，仅启用指定的提供商，所有其他提供商将被忽略。
```json title="opencode.json"
{
@@ -594,19 +596,19 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
当您想要限制 opencode 仅使用特定的提供商而不是逐一禁用它们时，这非常有用。
当您希望限制 OpenCode 仅使用特定提供商，而不是逐一禁用其他提供商时，此选项非常有用。
:::note
`disabled_providers` 优先于 `enabled_providers`。
:::
如果提供商同时出现在 `enabled_providers` 和 `disabled_providers` 中，则 `disabled_providers` 优先以保持一致性。
如果某个提供商同时出现在 `enabled_providers` 和 `disabled_providers` 中，为了向后兼容，`disabled_providers` 优先。
---
### 实验性功能
`experimental` 键包含正在积极开发的选项。
`experimental` 键包含正在积极开发中的选项。
```json title="opencode.json"
{
@@ -616,7 +618,7 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
```
:::caution
实验选项不稳定。它们可能会更改或被删除，恕不另行通知。
实验性选项不稳定。它们可能会在不另行通知的情况下被更改或移除。
:::
---
@@ -629,7 +631,7 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
### 环境变量
使用 `{env:VARIABLE_NAME}` 替换环境变量：
使用 `{env:VARIABLE_NAME}` 来替换环境变量：
```json title="opencode.json"
{
@@ -646,13 +648,13 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
}
```
如果未设置环境变量，它将被替换为空字符串。
如果环境变量未设置，它将被替换为空字符串。
---
### 文件
使用 `{file:path/to/file}` 替换文件的内容：
使用 `{file:path/to/file}` 来替换文件内容：
```json title="opencode.json"
{
@@ -670,11 +672,11 @@ opencode 将在启动时自动下载任何新的更新。您可以使用 `autoup
文件路径可以是：
- 相对于配置文件目录
- 或者以 `/` 或 `~` 开头的绝对路径
- 相对于配置文件所在目录的路径
- 以 `/` 或 `~` 开头的绝对路径
这些对于：
这些功能适用于：
- 将 API 密钥等敏感数据保存在单独的文件中。
- 包含大型指令文件，而不会弄乱您的配置。
- 跨多个配置文件共享通用配置片段。
- 引入大型指令文件而不会使配置变得杂乱。
- 在多个配置文件之间共享通用配置片段。

42
packages/web/src/content/docs/zh-cn/custom-tools.mdx
View File

@@ -1,30 +1,30 @@
---
title: 自定义工具
description: 创建 LLM 可以在 opencode 中调用的工具。
description: 创建 LLM 可在 opencode 中调用的工具。
---
自定义工具是您创建的函数，LLM 可以在对话期间调用。它们与 opencode 的 [Built-in Tools](/docs/tools) 一起工作，例如 `read`、`write` 和 `bash`。
自定义工具是你创建的函数，LLM 可以在对话过程中调用它们。它们与 opencode 的[内置工具](/docs/tools)（如 `read`、`write` 和 `bash`）协同工作。
---
## 创建工具
工具定义为 **TypeScript** 或 **JavaScript** 文件。但是，工具定义调用可以使用 **任何语言** 编写的脚本 - TypeScript 或 JavaScript 仅用于工具定义本身。
工具以 **TypeScript** 或 **JavaScript** 文件的形式定义。不过，工具定义可以调用**任何语言**编写的脚本——TypeScript 或 JavaScript 仅用于工具定义本身。
---
### 位置
它们可以定义为：
工具可以在以下位置定义：
- 通过将它们放在项目的 `.opencode/tools/` 目录中来本地进行。
- 或者在全局范围内，将它们放在 `~/.config/opencode/tools/` 中。
- 本地定义：将工具文件放在项目的 `.opencode/tools/` 目录中。
- 全局定义：将工具文件放在 `~/.config/opencode/tools/` 中。
---
### 结构
创建工具最简单的方法是使用 `tool()` 帮助程序，它提供类型安全和验证。
创建工具最简单的方式是使用 `tool()` 辅助函数，它提供类型安全和参数校验。
```ts title=".opencode/tools/database.ts" {1}
import { tool } from "@opencode-ai/plugin"
@@ -41,13 +41,13 @@ export default tool({
})
```
**文件名** 成为 **工具名称**。以上创建了一个 `database` 工具。
**文件名**即为**工具名称**。上面的示例创建了一个名为 `database` 的工具。
---
#### 每个文件多个工具
#### 单文件多工具
您还可以从单个文件导出多个工具。每个导出都会成为 **一个单独的工具**，名称为 **`<filename>_<exportname>`**：
你也可以从单个文件中导出多个工具。每个导出都会成为**一个独立的工具**，命名格式为 **`<filename>_<exportname>`**：
```ts title=".opencode/tools/math.ts"
import { tool } from "@opencode-ai/plugin"
@@ -75,13 +75,13 @@ export const multiply = tool({
})
```
这将创建两个工具：`math_add` 和 `math_multiply`。
这会创建两个工具：`math_add` 和 `math_multiply`。
---
### 参数
您可以使用 `tool.schema`（即 [Zod](https://zod.dev)）来定义参数类型。
你可以使用 `tool.schema`（即 [Zod](https://zod.dev)）来定义参数类型。
```ts "tool.schema"
args: {
@@ -89,7 +89,7 @@ args: {
}
```
您还可以直接导入 [Zod](https://zod.dev) 并返回一个普通对象：
你也可以直接导入 [Zod](https://zod.dev) 并返回一个普通对象：
```ts {6}
import { z } from "zod"
@@ -110,7 +110,7 @@ export default {
### 上下文
工具接收有关当前会话的上下文：
工具会接收当前会话的上下文信息：
```ts title=".opencode/tools/project.ts" {8}
import { tool } from "@opencode-ai/plugin"
@@ -126,18 +126,18 @@ export default tool({
})
```
使用 `context.directory` 作为会话工作目录。
使用 `context.worktree` 作为 git 工作树根。
使用 `context.directory` 获取会话的工作目录。
使用 `context.worktree` 获取 git worktree 根目录。
---
## 示例
### 使用 Python 编写工具
### 用 Python 编写工具
您可以使用任何您想要的语言编写工具。下面是一个使用 Python 将两个数字相加的示例。
你可以使用任何语言编写工具。以下示例展示了如何用 Python 实现两数相加。
首先，使用创建 Python 脚本的工具：
首先，创建一个 Python 脚本作为工具：
```python title=".opencode/tools/add.py"
import sys
@@ -147,7 +147,7 @@ b = int(sys.argv[2])
print(a + b)
```
然后创建调用它的工具定义：
然后创建调用该脚本的工具定义：
```ts title=".opencode/tools/python-add.ts" {10}
import { tool } from "@opencode-ai/plugin"
@@ -167,4 +167,4 @@ export default tool({
})
```
这里我们使用 [`Bun.$`](https://bun.com/docs/runtime/shell) 实用程序来运行 Python 脚本。
这里我们使用 [`Bun.$`](https://bun.com/docs/runtime/shell) 工具函数来运行 Python 脚本。

96
packages/web/src/content/docs/zh-cn/ecosystem.mdx
View File

@@ -1,52 +1,52 @@
---
title: 生态系统
description: 使用 opencode 构建的项目和集成。
description: 基于 OpenCode 构建的项目与集成。
---
基于 opencode 的社区项目集合。
基于 OpenCode 构建的社区项目合集。
:::note
想要将您的 opencode 相关项目添加到此列表中吗？提交 PR。
想将您的 OpenCode 相关项目添加到此列表中？欢迎提交 PR。
:::
您还可以查看 [awesome-opencode](https://github.com/awesome-opencode/awesome-opencode) 和 [opencode.cafe](https://opencode.cafe)，这是一个聚合生态系统和社区的社区。
您还可以查看 [awesome-opencode](https://github.com/awesome-opencode/awesome-opencode) 和 [opencode.cafe](https://opencode.cafe)，这是一个聚合生态系统与社区资源的社区。
---
## 插件
| 名称 | 描述 |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [opencode-daytona](https://github.com/jamesmurdza/daytona/blob/main/guides/typescript/opencode/README.md) | 在隔离的 Daytona 沙箱中自动运行 opencode 会话，并使用 git 同步和实时预览 |
| [opencode-helicone-session](https://github.com/H2Shami/opencode-helicone-session) | 自动注入 Helicone 会话标头以进行请求包 |
| [opencode-type-inject](https://github.com/nick-vi/opencode-type-inject) | 使用查找工具将 TypeScript/Svelte 类型自动注入到文件读取中 |
| [opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth) | 使用您的 ChatGPT Plus 或 Pro 订阅而不是 API 积分 |
| [opencode-gemini-auth](https://github.com/jenslys/opencode-gemini-auth) | 使用您现有的 Gemini 计划而不是 API 密钥 |
| [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) | 使用 Antigravity 的免费模型代替 API |
| [opencode-devcontainers](https://github.com/athal7/opencode-devcontainers) | 具有浅克隆和自动分配端口的多分支开发容器隔离 |
| [opencode-google-antigravity-auth](https://github.com/shekohex/opencode-google-antigravity-auth) | Google Antigravity OAuth 插件，支持 Google 搜索和更强大的 API 处理 |
| [opencode-dynamic-context-pruning](https://github.com/Tarquinen/opencode-dynamic-context-pruning) | 通过修剪过时的工具输出来优化 token 使用 |
| [opencode-websearch-cited](https://github.com/ghoulr/opencode-websearch-cited.git) | 为具有 Google 接地风格的受支持增加本机网络搜索支持 |
| [opencode-pty](https://github.com/shekohex/opencode-pty.git) | 使 AI 代理能够在 PTY 中运行后台进程，末端发送其交互输入。 |
| [opencode-shell-strategy](https://github.com/JRedeker/opencode-shell-strategy) | 非交互式 shell 命令指令 - 防止依赖 TTY 的操作挂起 |
| [opencode-wakatime](https://github.com/angristan/opencode-wakatime) | 使用 Wakatime 跟踪 opencode 使用情况 |
| [opencode-md-table-formatter](https://github.com/franlol/opencode-md-table-formatter/tree/main) | 清理 LLM 生成的 markdown 表 |
| [opencode-morph-fast-apply](https://github.com/JRedeker/opencode-morph-fast-apply) | 使用 Morph Fast Apply API 和取消编辑标记将代码编辑速度提高 10 倍 |
| [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) | 后台代理、预构建的 LSP/AST/MCP 工具、精选代理、兼容 Claude Code |
| [opencode-notificator](https://github.com/panta82/opencode-notificator) | opencode 会话的桌面通知和声音警报 |
| [opencode-notifier](https://github.com/mohak34/opencode-notifier) | 针对权限、完成和错误事件的桌面通知和声音警报 |
| [opencode-zellij-namer](https://github.com/24601/opencode-zellij-namer) | 基于 opencode 上下文的 AI 支持的自动 Zellij 会话命名 |
| [opencode-skillful](https://github.com/zenobi-us/opencode-skillful) | 允许 opencode 代理通过技能发现和注入失败延迟加载提示 |
| [opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory) | 使用 Supermemory 跨会话持久内存 |
| [@plannotator/opencode](https://github.com/backnotprop/plannotator/tree/main/apps/opencode-plugin) | 具有视觉注释和私人/离线共享的交互式计划审查 |
| [@openspoon/subtask2](https://github.com/spoons-and-mirrors/subtask2) | 将 opencode/命令扩展为具有精细流程控制的强大编排系统 |
| [opencode-scheduler](https://github.com/different-ai/opencode-scheduler) | 使用带 cron 语法的 launchd (Mac) 或 systemd (Linux) 安排重复作业 |
| [micode](https://github.com/vtemian/micode) | 塑造头脑风暴 → 计划 → 实施具有会议连续性的工作流程 |
| [octto](https://github.com/vtemian/octto) | 用于通过多问题形式进行 AI 头脑风暴的交互式浏览器 UI |
| [opencode-background-agents](https://github.com/kdcokenny/opencode-background-agents) | 具有异步委托和上下文持久性的 Claude Code 风格后台代理 |
| [opencode-notify](https://github.com/kdcokenny/opencode-notify) | opencode 的本机操作系统通知 – 了解任务何时完成 |
| [opencode-workspace](https://github.com/kdcokenny/opencode-workspace) | 一堆多代理编排工具 – 16个，组件一次安装 |
| [opencode-worktree](https://github.com/kdcokenny/opencode-worktree) | opencode 的零难度 git 工作树 |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [opencode-daytona](https://github.com/jamesmurdza/daytona/blob/main/guides/typescript/opencode/README.md) | 在隔离的 Daytona 沙箱中自动运行 OpenCode 会话，支持 git 同步和实时预览 |
| [opencode-helicone-session](https://github.com/H2Shami/opencode-helicone-session) | 自动注入 Helicone 会话头信息，用于请求分组 |
| [opencode-type-inject](https://github.com/nick-vi/opencode-type-inject) | 通过查找工具自动将 TypeScript/Svelte 类型注入到文件读取中 |
| [opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth) | 使用您的 ChatGPT Plus/Pro 订阅替代 API 额度 |
| [opencode-gemini-auth](https://github.com/jenslys/opencode-gemini-auth) | 使用您现有的 Gemini 套餐替代 API 计费 |
| [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) | 使用 Antigravity 的免费模型替代 API 计费 |
| [opencode-devcontainers](https://github.com/athal7/opencode-devcontainers) | 多分支开发容器隔离，支持浅克隆和自动分配端口 |
| [opencode-google-antigravity-auth](https://github.com/shekohex/opencode-google-antigravity-auth) | Google Antigravity OAuth 插件，支持 Google 搜索及更强健的 API 处理 |
| [opencode-dynamic-context-pruning](https://github.com/Tarquinen/opencode-dynamic-context-pruning) | 通过修剪过时的工具输出来优化 Token 使用 |
| [opencode-websearch-cited](https://github.com/ghoulr/opencode-websearch-cited.git) | 为受支持的提供商添加原生网页搜索支持，采用 Google grounded 风格 |
| [opencode-pty](https://github.com/shekohex/opencode-pty.git) | 使 AI 代理能够在 PTY 中运行后台进程，并向其发送交互式输入 |
| [opencode-shell-strategy](https://github.com/JRedeker/opencode-shell-strategy) | 非交互式 shell 命令指令——防止依赖 TTY 的操作导致挂起 |
| [opencode-wakatime](https://github.com/angristan/opencode-wakatime) | 使用 Wakatime 追踪 OpenCode 的使用情况 |
| [opencode-md-table-formatter](https://github.com/franlol/opencode-md-table-formatter/tree/main) | 清理 LLM 生成的 Markdown 表格 |
| [opencode-morph-fast-apply](https://github.com/JRedeker/opencode-morph-fast-apply) | 通过 Morph Fast Apply API 和惰性编辑标记实现 10 倍更快的代码编辑 |
| [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) | 后台代理、预构建的 LSP/AST/MCP 工具、精选代理，兼容 Claude Code |
| [opencode-notificator](https://github.com/panta82/opencode-notificator) | OpenCode 会话的桌面通知和声音提醒 |
| [opencode-notifier](https://github.com/mohak34/opencode-notifier) | 针对权限请求、任务完成和错误事件的桌面通知与声音提醒 |
| [opencode-zellij-namer](https://github.com/24601/opencode-zellij-namer) | 基于 OpenCode 上下文的 AI 驱动自动 Zellij 会话命名 |
| [opencode-skillful](https://github.com/zenobi-us/opencode-skillful) | 允许 OpenCode 代理通过技能发现和注入按需延迟加载提示词 |
| [opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory) | 使用 Supermemory 实现跨会话的持久记忆 |
| [@plannotator/opencode](https://github.com/backnotprop/plannotator/tree/main/apps/opencode-plugin) | 支持可视化标注和私有/离线分享的交互式计划审查 |
| [@openspoon/subtask2](https://github.com/spoons-and-mirrors/subtask2) | 将 OpenCode /commands 扩展为具有精细流程控制的强大编排系统 |
| [opencode-scheduler](https://github.com/different-ai/opencode-scheduler) | 使用 cron 语法通过 launchd (Mac) 或 systemd (Linux) 调度周期性任务 |
| [micode](https://github.com/vtemian/micode) | 结构化的头脑风暴 → 计划 → 实现工作流，支持会话连续性 |
| [octto](https://github.com/vtemian/octto) | 用于 AI 头脑风暴的交互式浏览器 UI，支持多问题表单 |
| [opencode-background-agents](https://github.com/kdcokenny/opencode-background-agents) | Claude Code 风格的后台代理，支持异步委托和上下文持久化 |
| [opencode-notify](https://github.com/kdcokenny/opencode-notify) | OpenCode 的原生操作系统通知——随时了解任务完成情况 |
| [opencode-workspace](https://github.com/kdcokenny/opencode-workspace) | 捆绑式多代理编排套件——16 个组件，一次安装 |
| [opencode-worktree](https://github.com/kdcokenny/opencode-worktree) | OpenCode 的零摩擦 git worktree 管理 |
---
@@ -54,17 +54,17 @@ description: 使用 opencode 构建的项目和集成。
| 名称 | 描述 |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| [kimaki](https://github.com/remorses/kimaki) | 用于控制 opencode 会话的 Discord 机器人，基于 SDK 构建 |
| [opencode.nvim](https://github.com/NickvanDyke/opencode.nvim) | Neovim 插件，用于编辑器采集提示，基于 API 构建 |
| [portal](https://github.com/hosenur/portal) | 通过 Tailscale/VPN 实现 opencode 的移动优先 Web UI |
| [opencode plugin template](https://github.com/zenobi-us/opencode-plugin-template/) | 用于构建 opencode 插件的模板 |
| [opencode.nvim](https://github.com/sudo-tee/opencode.nvim) | Neovim opencode 前端 - 基于终端的 AI 编码代理 |
| [ai-sdk-provider-opencode-sdk](https://github.com/ben-vargas/ai-sdk-provider-opencode-sdk) | Vercel AI SDK 提供商，用于通过 @opencode-ai/sdk 使用 opencode |
| [OpenChamber](https://github.com/btriapitsyn/openchamber) | opencode 的 Web/桌面应用程序和 VS Code 扩展 |
| [OpenCode-Obsidian](https://github.com/mtymek/opencode-obsidian) | 在 Obsidian 的 UI 中嵌入 opencode 的 Obsidian 插件 |
| [OpenWork](https://github.com/different-ai/openwork) | Claude Cowork 的替代开源方案，由 opencode 提供支持 |
| [ocx](https://github.com/kdcokenny/ocx) | opencode 扩展管理器具有可移植、隔离的配置文件。 |
| [CodeNomad](https://github.com/NeuralNomadsAI/CodeNomad) | opencode 的桌面、Web、移动和远程客户端应用程序 |
| [kimaki](https://github.com/remorses/kimaki) | 用于控制 OpenCode 会话的 Discord 机器人，基于 SDK 构建 |
| [opencode.nvim](https://github.com/NickvanDyke/opencode.nvim) | Neovim 插件，提供编辑器感知的提示词，基于 API 构建 |
| [portal](https://github.com/hosenur/portal) | 通过 Tailscale/VPN 使用的移动优先 OpenCode Web UI |
| [opencode plugin template](https://github.com/zenobi-us/opencode-plugin-template/) | 用于构建 OpenCode 插件的模板 |
| [opencode.nvim](https://github.com/sudo-tee/opencode.nvim) | OpenCode 的 Neovim 前端——基于终端的 AI 编码代理 |
| [ai-sdk-provider-opencode-sdk](https://github.com/ben-vargas/ai-sdk-provider-opencode-sdk) | Vercel AI SDK 提供商，用于通过 @opencode-ai/sdk 使用 OpenCode |
| [OpenChamber](https://github.com/btriapitsyn/openchamber) | OpenCode 的 Web / 桌面应用和 VS Code 扩展 |
| [OpenCode-Obsidian](https://github.com/mtymek/opencode-obsidian) | 将 OpenCode 嵌入 Obsidian UI 的 Obsidian 插件 |
| [OpenWork](https://github.com/different-ai/openwork) | Claude Cowork 的开源替代方案，由 OpenCode 驱动 |
| [ocx](https://github.com/kdcokenny/ocx) | OpenCode 扩展管理器，支持可移植的隔离配置 |
| [CodeNomad](https://github.com/NeuralNomadsAI/CodeNomad) | OpenCode 的桌面、Web、移动和远程客户端应用 |
---
@@ -72,5 +72,5 @@ description: 使用 opencode 构建的项目和集成。
| 名称 | 描述 |
| ----------------------------------------------------------------- | ---------------------------------------- |
| [Agentic](https://github.com/Cluster444/agentic) | 用于格式化开发的 Agentic AI 代理和命令 |
| [opencode-agents](https://github.com/darrenhinde/opencode-agents) | 用于增强工作流程的配置、提示、代理和插件 |
| [Agentic](https://github.com/Cluster444/agentic) | 用于结构化开发的模块化 AI 代理和命令 |
| [opencode-agents](https://github.com/darrenhinde/opencode-agents) | 用于增强工作流的配置、提示词、代理和插件 |

82
packages/web/src/content/docs/zh-cn/enterprise.mdx
View File

@@ -1,47 +1,47 @@
---
title: 企业版
description: 在您的组织中安全地使用 opencode。
description: 在您的组织中安全地使用 OpenCode。
---
import config from "../../../../config.mjs"
export const email = `mailto:${config.email}`
opencode 企业版适用于希望确保其代码和数据永远不会离开其基础设施的组织。它可以通过使用与 SSO 和内部 AI 网关集成的集中方式配置来实现此目的。
OpenCode 企业版面向希望确保代码和数据始终留在自有基础设施内的组织。它通过集中式配置与您的 SSO 和内部 AI 网关集成来实现这一目标。
:::note
opencode 不存储您的任何代码或上下文数据。
OpenCode 不会存储您的任何代码或上下文数据。
:::
要开始使用 opencode 企业版：
开始使用 OpenCode 企业版：
1. 与您的团队进行内部试用。
2. **<a href={email}>联系我们</a>** 讨论定价和实施选项。
1. 在团队内部进行试用。
2. **<a href={email}>联系我们</a>**，讨论定价和实施方案。
---
## 试用
opencode 是开源的，不存储您的任何代码或上下文数据，因此您的开发人员只需 [开始吧](/docs/) 并进行试用。
OpenCode 是开源的，不会存储您的任何代码或上下文数据，因此您的开发人员可以直接[开始使用](/docs/)并进行试用。
---
### 数据处理
**opencode 不会存储您的代码或上下文数据。** 所有处理都在本地进行或通过直接 API 调用您的 AI 提供商。
**OpenCode 不会存储您的代码或上下文数据。**所有处理均在本地完成，或通过直接 API 调用发送至您的 AI 提供商。
这意味着只要您使用您信任的提供商或内部 AI 网关，您就可以安全使用 opencode。
这意味着，只要您使用的是信任的提供商或内部 AI 网关，就可以安全地使用 OpenCode。
这里唯一需要注意的是可选的 `/share` 功能。
唯一需要注意的是可选的 `/share` 功能。
---
#### 分享对话
如果用户启用 `/share` 功能，对话和关联的数据将被发送到我们用于在 opencode.ai 上托管这些共享页面的服务。
如果用户启用了 `/share` 功能，对话及其关联数据将被发送到我们用于在 opencode.ai 上托管共享页面的服务。
数据当前通过我们的 CDN 边缘网络提供服务，并缓存在用户附近的边缘。
数据目前通过我们 CDN 的边缘网络提供服务，并缓存在靠近用户的边缘节点上。
我们建议您在试用时禁用此功能。
我们建议您在试用期间禁用此功能。
```json title="opencode.json"
{
@@ -56,110 +56,110 @@ opencode 是开源的，不存储您的任何代码或上下文数据，因此
### 代码所有权
**您拥有 opencode 生成的所有代码。** 没有许可限制或所有权主张。
**您拥有 OpenCode 生成的所有代码。**不存在任何许可限制或所有权声明。
---
## 定价
我们对 opencode Enterprise 使用按席位模型。如果您有自己的 LLM 网关，我们不会对使用的 Token 收取费用。有关定价和实施选项的更多详细信息，请 **<a href={email}>联系我们</a>**。
OpenCode 企业版采用按席位定价模型。如果您拥有自己的 LLM 网关，我们不会对使用的 Token 收取费用。有关定价和实施方案的更多详情，请**<a href={email}>联系我们</a>**。
---
## 部署
完成试用并准备好在您的组织中使用 opencode 后，您可以 **<a href={email}>联系我们</a>** 进行讨论定价和实施选项。
完成试用并准备好在组织中使用 OpenCode 后，您可以**<a href={email}>联系我们</a>**，讨论定价和实施方案。
---
### 中央配置
### 集中式配置
我们可以将 opencode 设置为您的整个组织使用单一的中央配置。
我们可以为您的整个组织设置 OpenCode 的统一集中式配置。
这种集中式配置可以与您的 SSO 提供商集成，并确保所有用户仅访问您的内部 AI 网关。
该集中式配置可与您的 SSO 提供商集成，确保所有用户仅访问您的内部 AI 网关。
---
### SSO 集成
通过中央配置，opencode 可以与您组织的 SSO 提供商集成以进行身份验证。
通过集中式配置，OpenCode 可以与您组织的 SSO 提供商集成进行身份验证。
这使得 opencode 能够通过现有的身份管理系统获取内部 AI 网关的凭据。
这使得 OpenCode 能够通过您现有的身份管理系统获取内部 AI 网关的凭据。
---
### 内部 AI 网关
通过中央配置，opencode 还可以配置为仅使用您的内部 AI 网关。
通过集中式配置，OpenCode 还可以被配置为仅使用您的内部 AI 网关。
您还可以禁用所有其他 AI 提供商，确保所有请求都通过组织批准的基础设施。
您还可以禁用所有其他 AI 提供商，确保所有请求都经过组织批准的基础设施。
---
### 自托管
虽然我们建议禁用共享页面以确保您的数据永远不会离开您的组织，我们还可以帮助您在您的基础设施上自行托管它们。
虽然我们建议禁用共享页面以确保您的数据始终不会离开组织，但我们也可以帮助您在自己的基础设施上自行托管这些页面。
目前这已在我们的路线图上。如果您有兴趣，**<a href={email}>让我们知道</a>**。
此功能目前已列入我们的路线图。如果您感兴趣，请**<a href={email}>告诉我们</a>**。
---
## 常见问题
<details>
<summary>什么是 opencode 企业版？</summary>
<summary>什么是 OpenCode 企业版？</summary>
opencode 企业版适用于希望确保其代码和数据永远不会离开其基础设施的组织。它可以通过使用与 SSO 和内部 AI 网关集成的集中方式配置来实现此目的。
OpenCode 企业版面向希望确保代码和数据始终留在自有基础设施内的组织。它通过集中式配置与您的 SSO 和内部 AI 网关集成来实现这一目标。
</details>
<details>
<summary>如何开始使用 opencode 企业版？</summary>
<summary>如何开始使用 OpenCode 企业版？</summary>
与您的团队进行内部实验即可。opencode 默认情况下不存储您的代码或上下文数据，可以轻松上手。
只需在团队内部开始试用即可。OpenCode 默认不存储您的代码或上下文数据，因此可以轻松上手。
然后 **<a href={email}>联系我们</a>** 讨论定价和实施选项。
然后**<a href={email}>联系我们</a>**，讨论定价和实施方案。
</details>
<details>
<summary>企业定价如何运作？</summary>
<summary>企业版定价如何运作？</summary>
我们提供按席位企业定价。如果您有自己的 LLM 网关，我们不会对使用的 Token 收取费用。如需了解更多详情，请 **<a href={email}>联系我们</a>**，获取根据您组织的需求定制的报价。
我们提供按席位的企业版定价。如果您拥有自己的 LLM 网关，我们不会对使用的 Token 收取费用。如需了解更多详情，请**<a href={email}>联系我们</a>**，获取根据您组织需求定制的报价。
</details>
<details>
<summary>opencode 企业版保证我的数据安全吗？</summary>
<summary>我的数据在 OpenCode 企业版中是否安全？</summary>
是的。opencode 不存储您的代码或上下文数据。所有处理都在本地进行或通过直接 API 调用您的 AI 提供商。通过中央配置和 SSO 集成，您的数据在组织的基础架构中保持安全。
是的。OpenCode 不会存储您的代码或上下文数据。所有处理均在本地完成，或通过直接 API 调用发送至您的 AI 提供商。通过集中式配置和 SSO 集成，您的数据将安全地保留在组织的基础设施内。
</details>
<details>
<summary>我们可以使用自己的私有 npm 注册表吗？</summary>
<summary>我们可以使用自己的私有 NPM 注册表吗？</summary>
opencode 通过 Bun 的本机 `.npmrc` 文件支持来支持私有 npm 注册表。如果您的组织使用私有注册表，例如 JFrog Artifactory、Nexus 或类似的，请确保开发人员在运行 opencode 之前经过身份验证。
OpenCode 通过 Bun 原生的 `.npmrc` 文件支持来支持私有 npm 注册表。如果您的组织使用私有注册表（例如 JFrog Artifactory、Nexus 或类似产品），请确保开发人员在运行 OpenCode 之前已完成身份验证。
要使用您的私有注册表设置身份验证：
要设置私有注册表的身份验证：
```bash
npm login --registry=https://your-company.jfrog.io/api/npm/npm-virtual/
```
这将创建带有身份验证详细信息的 `~/.npmrc`。 opencode 会自动读取这个。
这会创建包含身份验证信息的 `~/.npmrc` 文件。OpenCode 会自动识别并使用它。
:::caution
在运行 opencode 之前，您必须登录私有注册表。
在运行 OpenCode 之前，您必须先登录私有注册表。
:::
或者，您可以手动配置 `.npmrc` 文件：
或者，您也可以手动配置 `.npmrc` 文件：
```bash title="~/.npmrc"
registry=https://your-company.jfrog.io/api/npm/npm-virtual/
//your-company.jfrog.io/api/npm/npm-virtual/:_authToken=${NPM_AUTH_TOKEN}
```
开发人员必须在运行 opencode 之前登录私有注册表，以确保可以从您的企业注册表安装软件包。
开发人员必须在运行 OpenCode 之前登录私有注册表，以确保能够从您的企业注册表安装软件包。
</details>

107
packages/web/src/content/docs/zh-cn/formatters.mdx
View File

@@ -1,63 +1,64 @@
---
title: 格式化程序
description: opencode 使用特定于语言的格式化程序。
title: 格式化工具
description: OpenCode 使用特定语言的格式化工具。
---
使用特定于语言的格式化程序编写或编辑文件后，opencode 会自动格式化文件。这可以确保生成的代码遵循项目的代码风格。
OpenCode 会在文件写入或编辑后，自动使用特定语言的格式化工具对其进行格式化。这确保了生成的代码遵循你项目的代码风格。
---
## 内置
## 内置格式化工具
opencode 附带了多个适用于流行语言和框架的内置格式化程序。下面是格式化程序、支持的文件扩展名以及所需的命令或配置选项的列表。
OpenCode 内置了多种适用于主流语言和框架的格式化工具。下表列出了各格式化工具、支持的文件扩展名以及所需的命令或配置选项。
| 格式化程序 | 扩展名 | 要求 |
| -------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| gofmt | .go | `gofmt` command available |
| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | `mix` command available |
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://prettier.io/docs/en/index.html) | `prettier` dependency in `package.json` |
| biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://biomejs.dev/) | `biome.json(c)` config file |
| zig | .zig, .zon | `zig` command available |
| clang-format | .c, .cpp, .h, .hpp, .ino, and [more](https://clang.llvm.org/docs/ClangFormat.html) | `.clang-format` config file |
| ktlint | .kt, .kts | `ktlint` command available |
| ruff | .py, .pyi | `ruff` command available with config |
| rustfmt | .rs | `rustfmt` command available |
| cargofmt | .rs | `cargo fmt` command available |
| uv | .py, .pyi | `uv` command available |
| rubocop | .rb, .rake, .gemspec, .ru | `rubocop` command available |
| standardrb | .rb, .rake, .gemspec, .ru | `standardrb` command available |
| htmlbeautifier | .erb, .html.erb | `htmlbeautifier` command available |
| air | .R | `air` command available |
| dart | .dart | `dart` command available |
| dfmt | .d | `dfmt` command available |
| ocamlformat | .ml, .mli | `ocamlformat` command available and `.ocamlformat` config file |
| terraform | .tf, .tfvars | `terraform` command available |
| gleam | .gleam | `gleam` command available |
| nixfmt | .nix | `nixfmt` command available |
| shfmt | .sh, .bash | `shfmt` command available |
| pint | .php | `laravel/pint` dependency in `composer.json` |
| oxfmt (Experimental) | .js, .jsx, .ts, .tsx | `oxfmt` dependency in `package.json` and an [experimental env variable flag](/docs/cli/#experimental) |
| ormolu | .hs | `ormolu` command available |
| 格式化工具 | 扩展名 | 要求 |
| -------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| air | .R | `air` 命令可用 |
| biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml 及[更多](https://biomejs.dev/) | `biome.json(c)` 配置文件 |
| cargofmt | .rs | `cargo fmt` 命令可用 |
| clang-format | .c, .cpp, .h, .hpp, .ino 及[更多](https://clang.llvm.org/docs/ClangFormat.html) | `.clang-format` 配置文件 |
| cljfmt | .clj, .cljs, .cljc, .edn | `cljfmt` 命令可用 |
| dart | .dart | `dart` 命令可用 |
| dfmt | .d | `dfmt` 命令可用 |
| gleam | .gleam | `gleam` 命令可用 |
| gofmt | .go | `gofmt` 命令可用 |
| htmlbeautifier | .erb, .html.erb | `htmlbeautifier` 命令可用 |
| ktlint | .kt, .kts | `ktlint` 命令可用 |
| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | `mix` 命令可用 |
| nixfmt | .nix | `nixfmt` 命令可用 |
| ocamlformat | .ml, .mli | `ocamlformat` 命令可用且存在 `.ocamlformat` 配置文件 |
| ormolu | .hs | `ormolu` 命令可用 |
| oxfmt (Experimental) | .js, .jsx, .ts, .tsx | `package.json` 中有 `oxfmt` 依赖，且设置了[实验性环境变量标志](/docs/cli/#experimental) |
| pint | .php | `composer.json` 中有 `laravel/pint` 依赖 |
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml 及[更多](https://prettier.io/docs/en/index.html) | `package.json` 中有 `prettier` 依赖 |
| rubocop | .rb, .rake, .gemspec, .ru | `rubocop` 命令可用 |
| ruff | .py, .pyi | `ruff` 命令可用且有相应配置 |
| rustfmt | .rs | `rustfmt` 命令可用 |
| shfmt | .sh, .bash | `shfmt` 命令可用 |
| standardrb | .rb, .rake, .gemspec, .ru | `standardrb` 命令可用 |
| terraform | .tf, .tfvars | `terraform` 命令可用 |
| uv | .py, .pyi | `uv` 命令可用 |
| zig | .zig, .zon | `zig` 命令可用 |
因此，如果您的项目的 `prettier` 中有 `package.json`，opencode 将自动使用它。
因此，如果你的项目 `package.json` 中包含 `prettier`，OpenCode 会自动使用它进行格式化。
---
## 它是如何工作的
## 工作原理
当 opencode 写入或编辑文件时，它：
当 OpenCode 写入或编辑文件时，它会：
1. 根据所有启用的格式化程序检查文件扩展名。
2. 对文件运行适当的格式化程序命令。
3. 自动应用格式更改。
1. 根据所有已启用的格式化工具检查文件扩展名。
2. 对文件运行相应的格式化命令。
3. 自动应用格式化更改。
此过程在后台进行，确保无需任何手动步骤即可维护您的代码样式。
整个过程在后台完成，无需任何手动操作即可保持代码风格的一致性。
---
## 配置
您可以通过 opencode 配置中的 `formatter` 部分自定义格式化程序。
你可以通过 OpenCode 配置中的 `formatter` 部分自定义格式化工具。
```json title="opencode.json"
{
@@ -66,22 +67,22 @@ opencode 附带了多个适用于流行语言和框架的内置格式化程序
}
```
每个格式化程序配置支持以下内容：
每个格式化工具的配置支持以下属性：
| 属性 | 类型 | 描述 |
| ------------- | -------- | ---------------------------------- |
| `disabled` | boolean | 将其设置为 `true` 以禁用格式化程序 |
| `command` | string[] | 格式化运行的命令 |
| `environment` | object | 运行格式化程序时要设置的环境变量 |
| `extensions` | string[] | 此格式化程序应处理的文件扩展名 |
| ------------- | -------- | ------------------------------ |
| `disabled` | boolean | 设为 `true` 可禁用该格式化工具 |
| `command` | string[] | 执行格式化的命令 |
| `environment` | object | 运行格式化工具时设置的环境变量 |
| `extensions` | string[] | 该格式化工具处理的文件扩展名 |
让我们看一些例子。
下面来看一些示例。
---
### 禁用格式化程序
### 禁用格式化工具
要全局禁用 **所有** 格式化程序，将 `formatter` 设置为 `false`：
要全局禁用**所有**格式化工具，将 `formatter` 设为 `false`：
```json title="opencode.json" {3}
{
@@ -90,7 +91,7 @@ opencode 附带了多个适用于流行语言和框架的内置格式化程序
}
```
要禁用 **特定** 格式化程序，将 `disabled` 设置为 `true`：
要禁用**特定**格式化工具，将 `disabled` 设为 `true`：
```json title="opencode.json" {5}
{
@@ -105,9 +106,9 @@ opencode 附带了多个适用于流行语言和框架的内置格式化程序
---
### 自定义格式化程序
### 自定义格式化工具
您可以覆盖内置格式化程序或通过指定命令、环境变量和文件扩展名添加新格式化程序：
你可以通过指定命令、环境变量和文件扩展名来覆盖内置格式化工具或添加新的格式化工具：
```json title="opencode.json" {4-14}
{
@@ -128,4 +129,4 @@ opencode 附带了多个适用于流行语言和框架的内置格式化程序
}
```
命令中的 **`$FILE` 占位符** 将替换为正在格式化的文件的路径。
命令中的 **`$FILE` 占位符**会被替换为待格式化文件的路径。

114
packages/web/src/content/docs/zh-cn/github.mdx
View File

@@ -1,43 +1,43 @@
---
title: GitHub
description: 在 GitHub 问题和拉取请求中使用 opencode。
description: 在 GitHub Issue 和 Pull Request 中使用 OpenCode。
---
opencode 与您的 GitHub 工作流程集成。在评论中提及 `/opencode` 或 `/oc`，opencode 将在您的 GitHub Actions 运行器中执行任务。
OpenCode 可以与你的 GitHub 工作流集成。在评论中提及 `/opencode` 或 `/oc`，OpenCode 就会在你的 GitHub Actions 运行器中执行任务。
---
## 功能
## 功能特性
- **Triage issues**: 要求 opencode 调查问题并向您解释。
- **Fix and implement**: 要求 opencode 修复问题或实施功能。将在一个新的分支中工作并提交包含所有更改的 PR。
- **Secure**: opencode 在 GitHub 的运行器中运行。
- **问题分类**：让 OpenCode 调查某个 Issue 并为你做出解释。
- **修复与实现**：让 OpenCode 修复 Issue 或实现某个功能。它会在新分支中工作，并提交包含所有变更的 PR。
- **安全可靠**：OpenCode 在你自己的 GitHub 运行器中运行。
---
## 安装
在 GitHub 存储库中的项目中运行以下命令：
在一个位于 GitHub 仓库中的项目里运行以下命令：
```bash
opencode github install
```
这将引导您完成安装 GitHub 应用程序、创建工作流程和设置机密。
该命令会引导你完成 GitHub App 的安装、工作流的创建以及密钥的配置。
---
### 手动设置
或者您可以手动设置。
你也可以手动进行设置。
1. **Install the GitHub app**
1. **安装 GitHub App**
前往 [**github.com/apps/opencode-agent**](https://github.com/apps/opencode-agent)。确保它​​已安装在目标存储库上。
前往 [**github.com/apps/opencode-agent**](https://github.com/apps/opencode-agent)，确保已在目标仓库中安装该应用。
2. **Add the workflow**
2. **添加工作流**
将以下工作流程文件添加到存储库中的 `.github/workflows/opencode.yml` 中。确保在 `model` 中设置适当的 `env` 和所需的 API 密钥。
将以下工作流文件添加到仓库的 `.github/workflows/opencode.yml` 中。请确保在 `env` 中设置合适的 `model` 及所需的 API 密钥。
```yml title=".github/workflows/opencode.yml" {24,26}
name: opencode
@@ -73,21 +73,21 @@ opencode github install
# github_token: xxxx
```
3. **Store the API keys in secrets**
3. **将 API 密钥存储到 Secrets 中**
在您的组织或项目的 **Settings** 中，展开左侧的 **Secrets and variables**，然后选择 **Actions**。并添加所需的 API 密钥。
在你的组织或项目的 **Settings** 中，展开左侧的 **Secrets and variables**，然后选择 **Actions**，添加所需的 API 密钥。
---
## 配置
- `model`：与 opencode 一起使用的模型。采用 `provider/model` 格式。这是 **必需的**。
- `agent`：要使用的代理。必须是一级代理。如果未找到，则从配置回退到 `default_agent` 或 `"build"`。
- `share`：是否共享 opencode 会话。对于公共存储库，默认为 **true**。
- `prompt`：可选的自定义提示以覆盖默认行为。使用它来自定义 opencode 处理请求的方式。
- `token`：可选的 GitHub 访问 Token，用于执行创建评论、提交更改和打开拉取请求等操作。默认情况下，opencode 使用来自 opencode GitHub 应用程序的安装访问 Token，因此提交、评论和拉取请求显示为来自应用。
- `model`：OpenCode 使用的模型，格式为 `provider/model`。此项为**必填**。
- `agent`：要使用的代理，必须是主代理。如果未找到，则回退到配置中的 `default_agent`，若仍未找到则使用 `"build"`。
- `share`：是否共享 OpenCode 会话。对于公开仓库，默认为 **true**。
- `prompt`：可选的自定义提示词，用于覆盖默认行为。可通过此项自定义 OpenCode 处理请求的方式。
- `token`：可选的 GitHub 访问 Token，用于执行创建评论、提交变更和创建 Pull Request 等操作。默认情况下，OpenCode 使用 OpenCode GitHub App 的安装访问 Token，因此提交、评论和 Pull Request 会显示为来自该应用。
或者，您可以使用 GitHub Action 运行程序的 [内置 `GITHUB_TOKEN`](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token)，而无需安装 opencode GitHub 应用程序。只需确保在您的工作流程中所需的权限：
你也可以使用 GitHub Action 运行器内置的 [`GITHUB_TOKEN`](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token)，而无需安装 OpenCode GitHub App。只需确保在工作流中授予所需的权限：
```yaml
permissions:
@@ -97,26 +97,26 @@ opencode github install
issues: write
```
您可以在 GitHub Actions 文档中了解有关配置工作流程的更多信息。
如果你愿意，也可以使用[个人访问令牌](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)（PAT）。
---
## 支持的事件
opencode 可以由以下 GitHub 事件触发：
OpenCode 可以由以下 GitHub 事件触发：
| 事件类型 | 触发方式 | 详情 |
| ----------------------------- | ---------------------------- | --------------------------------------------------------------------------------------- |
| `issue_comment` | 对问题或 PR 发表评论 | 在评论中提及 `/opencode` 或 `/oc`。 opencode 读取上下文并可以创建分支、打开 PR 或回复。 |
| `pull_request_review_comment` | 对 PR 中的特定代码行进行评论 | 在检查代码时提及 `/opencode` 或 `/oc`。 opencode 接收文件路径、行号和 diff 上下文。 |
| `issues` | 问题已打开或已编辑 | 创建或修改问题时自动触发 opencode。需要 `prompt` 输入。 |
| `pull_request` | PR 已开启或已更新 | 当 PR 打开、同步或重新打开时自动触发 opencode。对于自动评论很有帮助。 |
| `schedule` | 基于 Cron 的计划 | 按计划运行 opencode。需要 `prompt` 输入。输出进入日志和 PR（没有可评论的问题）。 |
| `workflow_dispatch` | 从 GitHub UI 手动触发 | 通过“操作”选项卡触发 opencode。需要 `prompt` 输入。输出进入日志和 PR。 |
| ----------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------- |
| `issue_comment` | 在 Issue 或 PR 上发表评论 | 在评论中提及 `/opencode` 或 `/oc`。OpenCode 会读取上下文，并可创建分支、提交 PR 或回复。 |
| `pull_request_review_comment` | 在 PR 中对特定代码行发表评论 | 在代码审查时提及 `/opencode` 或 `/oc`。OpenCode 会接收文件路径、行号和 diff 上下文。 |
| `issues` | Issue 被创建或编辑 | 在 Issue 创建或修改时自动触发 OpenCode。需要提供 `prompt` 输入。 |
| `pull_request` | PR 被创建或更新 | 在 PR 被打开、同步或重新打开时自动触发 OpenCode。适用于自动化审查场景。 |
| `schedule` | 基于 Cron 的定时任务 | 按计划运行 OpenCode。需要提供 `prompt` 输入。输出会写入日志和 PR（没有 Issue 可供评论）。 |
| `workflow_dispatch` | 从 GitHub UI 手动触发 | 通过 Actions 选项卡按需触发 OpenCode。需要提供 `prompt` 输入。输出会写入日志和 PR。 |
### 计划示例
### 定时任务示例
按计划运行 opencode 以执行自动化任务：
按计划运行 OpenCode 以执行自动化任务：
```yaml title=".github/workflows/opencode-scheduled.yml"
name: Scheduled OpenCode Task
@@ -150,13 +150,13 @@ jobs:
If you find issues worth addressing, open an issue to track them.
```
对于计划事件，`prompt` 输入是 **必需的**，因为没有注释可以从中提取指令。希望计划工作流在没有用户上下文的情况下运行并进行权限检查，因此如果您 opencode 创建分支或 PR，工作流必须支持 `contents: write` 和 `pull-requests: write`。
对于定时事件，`prompt` 输入为**必填**，因为没有评论可供提取指令。定时工作流在运行时没有用户上下文来进行权限检查，因此如果你希望 OpenCode 创建分支或 PR，工作流必须授予 `contents: write` 和 `pull-requests: write` 权限。
---
### Pull Request 示例
或更新 PR 时自动审核：
在 PR 被创建或更新时自动进行审查：
```yaml title=".github/workflows/opencode-review.yml"
name: opencode-review
@@ -191,13 +191,13 @@ jobs:
- Suggest improvements
```
对于 `pull_request` 事件，如果未提供 `prompt`，opencode 将默认审核拉取请求。
对于 `pull_request` 事件，如果未提供 `prompt`，OpenCode 将默认对该 Pull Request 进行审查。
---
### Issue 分类示例
自动分类新问题。此示例过滤超过 30 天的账户以减少垃圾邮件：
自动分类新建的 Issue。以下示例会过滤掉注册不满 30 天的账户以减少垃圾信息：
```yaml title=".github/workflows/opencode-triage.yml"
name: Issue Triage
@@ -246,13 +246,13 @@ jobs:
Otherwise, do not comment.
```
对于 `issues` 事件，`prompt` 输入是 **必需的**，因为没有注释可以从中提取指令。
对于 `issues` 事件，`prompt` 输入为**必填**，因为没有评论可供提取指令。
---
## 自定义提示
## 自定义提示词
覆盖默认提示，为您的工作流程自定义 opencode 的行为。
覆盖默认提示词，以便为你的工作流自定义 OpenCode 的行为。
```yaml title=".github/workflows/opencode.yml"
- uses: anomalyco/opencode/github@latest
@@ -265,57 +265,57 @@ jobs:
- Suggest improvements
```
这对于执行与您的项目相关的特定审查标准、编码标准或重点领域非常有用。
这对于在项目中实施特定的审查标准、编码规范或关注重点非常有用。
---
## 示例
以下是如何在 GitHub 中使用 opencode 的一些示例。
以下是在 GitHub 中使用 OpenCode 的一些示例。
- **Explain an issue**
- **解释 Issue**
在 GitHub 问题中添加此评论。
在 GitHub Issue 中添加以下评论：
```
/opencode explain this issue
```
opencode 将阅读整个线程，包括所有评论，并回复并提供清晰的解释。
OpenCode 会阅读整个讨论串（包括所有评论），并回复一份清晰的解释。
- **Fix an issue**
- **修复 Issue**
在 GitHub 问题中，说：
在 GitHub Issue 中输入：
```
/opencode fix this
```
opencode 将创建一个新分支，实施更改，并使用更改打开 PR。
OpenCode 会创建一个新分支，实现变更，并提交一个包含所有修改的 PR。
- **Review PRs and make changes**
- **审查 PR 并进行修改**
在 GitHub PR 上留下以下评论。
在 GitHub PR 上留下以下评论：
```
Delete the attachment from S3 when the note is removed /oc
```
opencode 将实施请求的更改并提交到同一个 PR。
OpenCode 会实现所请求的变更并将其提交到同一个 PR 中。
- **Review specific code lines**
- **审查特定代码行**
直接在 PR 的“文件”选项卡中的代码行上留下评论。opencode 自动检测文件、行号和差异上下文以提供准确的响应。
在 PR 的 "Files" 选项卡中直接对代码行留下评论。OpenCode 会自动检测文件、行号和 diff 上下文，从而提供精准的响应。
```
[Comment on specific lines in Files tab]
/oc add error handling here
```
当评论特定行时，opencode 接收：
- 正在审查的确切文件
- 具体代码行
- 周围的差异上下文
当你对特定代码行发表评论时，OpenCode 会接收到：
- 正在审查的具体文件
- 特定的代码行
- 周围的 diff 上下文
- 行号信息
这允许更有针对性的请求，而无需手动指定文件路径或行号。
这样你就可以提出更有针对性的请求，而无需手动指定文件路径或行号。

71
packages/web/src/content/docs/zh-cn/gitlab.mdx
View File

@@ -1,34 +1,34 @@
---
title: GitLab
description: 在 GitLab 问题和合并请求中使用 opencode。
description: 在 GitLab issue 和合并请求中使用 OpenCode。
---
opencode 通过 GitLab CI/CD 管道或与 GitLab Duo 与您的 GitLab 工作流程集成。
OpenCode 通过 GitLab CI/CD 流水线或 GitLab Duo 与你的 GitLab 工作流集成。
在这两种情况下，opencode 都会在您的 GitLab 运行器上运行。
在这两种情况下，OpenCode 都将在你的 GitLab Runner 上运行。
---
## GitLab CI
opencode 在常规 GitLab 管道中工作。您可以将其构建为管道 [CI 组件](https://docs.gitlab.com/ee/ci/components/)
OpenCode 可以在常规的 GitLab 流水线中运行。你可以将其作为 [CI 组件](https://docs.gitlab.com/ee/ci/components/) 集成到流水线中。
在这里，我们使用社区创建的 opencode CI/CD 组件 — [nagyv/gitlab-opencode](https://gitlab.com/nagyv/gitlab-opencode)。
这里我们使用的是社区创建的 OpenCode CI/CD 组件 — [nagyv/gitlab-opencode](https://gitlab.com/nagyv/gitlab-opencode)。
---
### 功能
### 功能特性
- **Use custom configuration per job**: 使用自定义配置目录配置 opencode，例如 `./config/#custom-directory` 以启用或禁用 opencode 调用的功能。
- **Authentication**: Uses OIDC for secure authentication
- **Flexible**: CI 组件支持多种输入来自定义其行为
- **按任务自定义配置**：使用自定义配置目录来配置 OpenCode，例如 `./config/#custom-directory`，以便为每次 OpenCode 调用启用或禁用特定功能。
- **最小化配置**：CI 组件会在后台完成 OpenCode 的设置，你只需创建 OpenCode 配置和初始提示词即可。
- **灵活可定制**：CI 组件支持多种输入参数来自定义其行为。
---
### 设置
1. 将 opencode 身份验证 JSON 作为文件类型 CI 环境变量存储在 **Settings** > **CI/CD** > **Variables** 下。确保将它们标记为“隐藏和隐藏”。
2. 将以下内容添加到您的 `.gitlab-ci.yml` 文件中。
1. 将你的 OpenCode 身份验证 JSON 作为文件类型的 CI 环境变量存储在 **Settings** > **CI/CD** > **Variables** 下。请确保将其标记为 "Masked and hidden"。
2. 将以下内容添加到你的 `.gitlab-ci.yml` 文件中。
```yaml title=".gitlab-ci.yml"
include:
@@ -40,40 +40,39 @@ opencode 在常规 GitLab 管道中工作。您可以将其构建为管道 [CI
message: "Your prompt here"
```
有关此组件的更多输入和示例[查看文档](https://gitlab.com/explore/catalog/nagyv/gitlab-opencode)。
有关更多输入参数和使用场景，请[查看该组件的文档](https://gitlab.com/explore/catalog/nagyv/gitlab-opencode)。
---
## GitLab Duo
opencode 与您的 GitLab 工作流程集成。
在评论中提及 `@opencode`，opencode 将在您的 GitLab CI 管道中执行任务。
OpenCode 与你的 GitLab 工作流集成。
在评论中提及 `@opencode`，OpenCode 将在你的 GitLab CI 流水线中执行任务。
---
### 功能
### 功能特性
- **Triage issues**: 要求 opencode 调查问题并向您解释。
- **Fix and implement**: 要求 opencode 修复问题或实施功能。
它将创建一个新分支并提出包含更改的合并请求。
- **Secure**: opencode 在您的 GitLab 运行器上运行。
- **问题分类**：让 OpenCode 调查某个 issue 并为你解释。
- **修复与实现**：让 OpenCode 修复 issue 或实现某个功能。它会创建一个新分支，并提交包含更改的合并请求。
- **安全可靠**：OpenCode 在你的 GitLab Runner 上运行。
---
### 设置
opencode 在您的 GitLab CI/CD 管道中运行，您需要进行以下设置：
OpenCode 在你的 GitLab CI/CD 流水线中运行，以下是设置所需的步骤：
:::tip
查看 [**GitLab docs**](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) 获取最新说明。
请查看 [**GitLab 文档**](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) 获取最新说明。
:::
1. 配置您的 GitLab 环境
1. 配置你的 GitLab 环境
2. 设置 CI/CD
3. 获取 AI 模型提供商 API 密钥
3. 获取 AI 模型提供商的 API 密钥
4. 创建服务账户
5. 配置 CI/CD 变量
6. 创建一个流配置文件，这是一个示例：
6. 创建流程配置文件，以下是一个示例：
<details>
@@ -152,44 +151,44 @@ opencode 在您的 GitLab CI/CD 管道中运行，您需要进行以下设置：
</details>
详细说明可以参考 [GitLab CLI agents docs](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/)。
详细说明请参考 [GitLab CLI agents 文档](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/)。
---
### 示例
以下是如何在 GitLab 中使用 opencode 的一些示例。
以下是在 GitLab 中使用 OpenCode 的一些示例。
:::tip
您可以配置使用与 `@opencode` 不同的触发词。
你可以配置使用不同于 `@opencode` 的触发词。
:::
- **Explain an issue**
- **解释 issue**
在 GitLab 问题中添加此评论。
在 GitLab issue 中添加以下评论。
```
@opencode explain this issue
```
opencode 将阅读该问题并回复并提供清晰的解释。
OpenCode 会阅读该 issue 并回复清晰的解释。
- **Fix an issue**
- **修复 issue**
在 GitLab 问题中，说：
在 GitLab issue 中输入：
```
@opencode fix this
```
opencode 将创建一个新分支，实施更改，并打开包含更改的合并请求。
OpenCode 会创建一个新分支，实现更改，并提交包含更改的合并请求。
- **Review merge requests**
- **审查合并请求**
对 GitLab 合并请求留下以下评论。
在 GitLab 合并请求中留下以下评论。
```
@opencode review this merge request
```
opencode 将审核合并请求并提供反馈。
OpenCode 会审查合并请求并提供反馈。

38
packages/web/src/content/docs/zh-cn/ide.mdx
View File

@@ -1,48 +1,48 @@
---
title: IDE
description: VS Code、Cursor 等 IDE 的 opencode 扩展
description: 适用于 VS Code、Cursor 及其他 IDE 的 OpenCode 扩展
---
opencode 与 VS Code、Cursor 或任何支持终端的 IDE 集成。只需在终端中运行 `opencode` 即可开始。
OpenCode 可与 VS Code、Cursor 或任何支持终端的 IDE 集成。只需在终端中运行 `opencode` 即可开始使用。
---
## 用法
- **快速启动**：使用 `Cmd+Esc` (Mac) 或 `Ctrl+Esc` (Windows/Linux) 在分割终端视图中打开 opencode，或者聚焦现有终端会话（如果现有终端会话正在运行）。
- **新会话**：使用 `Cmd+Shift+Esc` (Mac) 或 `Ctrl+Shift+Esc` (Windows/Linux) 启动新的 opencode 终端会话，即使该会话已打开。您还可以单击 UI 中的 opencode 按钮。
- **上下文获取**：自动与 opencode 共享您当前的选择或选项卡。
- **文件引用快捷方式**：使用 `Cmd+Option+K` (Mac) 或 `Alt+Ctrl+K` (Linux/Windows) 插入文件引用。例如，`@File#L37-42`。
- **快速启动**：使用 `Cmd+Esc`（Mac）或 `Ctrl+Esc`（Windows/Linux）在分屏终端视图中打开 OpenCode，如果已有终端会话正在运行，则会自动聚焦到该会话。
- **新建会话**：使用 `Cmd+Shift+Esc`（Mac）或 `Ctrl+Shift+Esc`（Windows/Linux）启动新的 OpenCode 终端会话，即使已有会话在运行也会新建。你也可以点击界面中的 OpenCode 按钮。
- **上下文感知**：自动将当前选中内容或标签页共享给 OpenCode。
- **文件引用快捷键**：使用 `Cmd+Option+K`（Mac）或 `Alt+Ctrl+K`（Linux/Windows）插入文件引用。例如 `@File#L37-42`。
---
## 安装
要在 VS Code 和 Cursor、Windsurf、VSCodium 等流行分支上安装 opencode：
在 VS Code 及其常见分支（如 Cursor、Windsurf、VSCodium）上安装 OpenCode：
1. 打开 VS Code
2. 打开集成终端
3. 运行 `opencode` - 扩展会自动安装
3. 运行 `opencode`——扩展将自动安装
另一方面，如果您想在从 TUI 运行 `/editor` 或 `/export` 时使用自己的 IDE，则需要设置 `export EDITOR="code --wait"`。 [了解更多](/docs/tui/#editor-setup)。
如果你希望在 TUI 中执行 `/editor` 或 `/export` 时使用自己的 IDE，需要设置 `export EDITOR="code --wait"`。[了解更多](/docs/tui/#editor-setup)。
---
### 手动安装
在扩展市场中搜索 **opencode**，然后单击 **Install**。
在扩展商店中搜索 **OpenCode**，然后点击 **Install**。
---
### 故障排除
如果扩展无法自动安装：
如果扩展未能自动安装：
- 确定您在集成终端中运行 `opencode`。
- 确认您的 IDE 和 CLI 已安装：
- 对于 VS Code：`code` 命令
- 对于 Cursor：`cursor` 命令
- 对于 Windsurf：`windsurf` 命令
- 对于 VSCodium：`codium` 命令
- 如果没有，请运行 `Cmd+Shift+P` (Mac) 或 `Ctrl+Shift+P` (Windows/Linux) 并搜索 “Shell Command: Install 'code' command in PATH”（或适用于您的 IDE 的对应命令）
- 确保 VS Code 能够安装扩展
- 确保你是在集成终端中运行的 `opencode`。
- 确认你的 IDE 对应的 CLI 命令已安装：
- VS Code：`code` 命令
- Cursor：`cursor` 命令
- Windsurf：`windsurf` 命令
- VSCodium：`codium` 命令
- 如果未安装，请按 `Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），搜索 "Shell Command: Install 'code' command in PATH"（或你的 IDE 对应的命令）
- 确保 VS Code 有权限安装扩展

134
packages/web/src/content/docs/zh-cn/index.mdx
View File

@@ -1,43 +1,43 @@
---
title: 介绍
description: 开始使用 opencode。
title: 简介
description: 开始使用 OpenCode。
---
import { Tabs, TabItem } from "@astrojs/starlight/components"
import config from "../../../../config.mjs"
export const console = config.console
[**opencode**](/) 是一个开源人工智能编码代理。它可用于基于终端的界面、桌面应用程序或 IDE 扩展。
[**OpenCode**](/) 是一个开源的 AI 编码代理。它提供终端界面、桌面应用和 IDE 扩展等多种使用方式。
![具有 opencode 主题的 opencode TUI](../../../assets/lander/screenshot.png)
![使用 opencode 主题的 OpenCode TUI](../../../assets/lander/screenshot.png)
让我们开始吧。
---
#### 先决条件
#### 前提条件
要在终端中使用 opencode，您需要：
要在终端中使用 OpenCode，你需要：
1. 现代终端模拟器，例如：
1. 一款现代终端模拟器，例如：
- [WezTerm](https://wezterm.org)，跨平台
- [Alacritty](https://alacritty.org)，跨平台
- [Ghostty](https://ghostty.org)，Linux 和 macOS
- [Kitty](https://sw.kovidgoyal.net/kitty/)，Linux 和 macOS
2. 你要使用的 LLM 提供商 API 密钥。
2. 你想使用的 LLM 提供商的 API 密钥。
---
## 安装
安装 opencode 最简单的方法是通过安装脚本。
安装 OpenCode 最简单的方法是通过安装脚本。
```bash
curl -fsSL https://opencode.ai/install | bash
```
您还可以使用以下命令安装它：
你也可以使用以下方式安装：
- **使用 Node.js**
@@ -79,9 +79,9 @@ curl -fsSL https://opencode.ai/install | bash
brew install anomalyco/tap/opencode
```
> 我们使用 opencode Tap 来获取最新版本。官方 `brew install opencode` 公式由 Homebrew 团队建议，维护频率较低。
> 我们推荐使用 OpenCode tap 以获取最新版本。官方的 `brew install opencode` formula 由 Homebrew 团队维护，更新频率较低。
- **在 Arch Linux 上使用 Paru**
- **在 Arch Linux 上安装**
```bash
sudo pacman -S opencode # Arch Linux (Stable)
@@ -91,7 +91,7 @@ curl -fsSL https://opencode.ai/install | bash
#### Windows
:::tip[推荐：使用 WSL]
为了在 Windows 上获得最佳体验，我们建议使用 [Windows Subsystem for Linux (WSL)](/docs/windows-wsl)。它提供了更好的性能并与 opencode 的功能完全兼容。
为了在 Windows 上获得最佳体验，我们推荐使用 [Windows Subsystem for Linux (WSL)](/docs/windows-wsl)。它提供更好的性能，并完全兼容 OpenCode 的所有功能。
:::
- **使用 Chocolatey**
@@ -106,7 +106,7 @@ curl -fsSL https://opencode.ai/install | bash
scoop install opencode
```
- **使用 npm**
- **使用 NPM**
```bash
npm install -g opencode-ai
@@ -124,18 +124,17 @@ curl -fsSL https://opencode.ai/install | bash
docker run -it --rm ghcr.io/anomalyco/opencode
```
目前正在支持在 Windows 上安装 opencode 时使用 Bun。
在 Windows 上通过 Bun 安装 OpenCode 的支持目前正在开发中。
您还可以从 [Releases](https://github.com/anomalyco/opencode/releases) 获取二进制文件。
你也可以从 [Releases](https://github.com/anomalyco/opencode/releases) 页面直接下载二进制文件。
---
## 配置
借助 opencode，你可以通过配置 API 使用任意 LLM 提供商。
通过 OpenCode，你可以配置 API 密钥来使用任意 LLM 提供商。
如果你刚开始使用 LLM 提供商，我们建议使用 [OpenCode Zen](/docs/zen)。
这是经过 opencode 团队测试和验证的精选模型列表。
如果你刚开始接触 LLM 提供商，我们推荐使用 [OpenCode Zen](/docs/zen)。这是一组经过 OpenCode 团队测试和验证的精选模型。
1. 在 TUI 中运行 `/connect` 命令，选择 opencode，然后前往 [opencode.ai/auth](https://opencode.ai/auth)。
@@ -143,9 +142,9 @@ curl -fsSL https://opencode.ai/install | bash
/connect
```
2. 登录，添加您的账单信息，然后复制您的详细 API 密钥。
2. 登录并添加账单信息，然后复制你的 API 密钥。
3. 粘贴您的 API 密钥。
3. 粘贴你的 API 密钥。
```txt
┌ API key
@@ -154,82 +153,79 @@ curl -fsSL https://opencode.ai/install | bash
└ enter
```
或者，你也可以选择其他提供商之一。[了解更多](/docs/providers#directory)。
你也可以选择其他提供商。[了解更多](/docs/providers#directory)。
---
## 初始化
现在您已经配置了提供商，您可以导航到一个项目
你想继续工作。
配置好提供商后，导航到你想要处理的项目目录。
```bash
cd /path/to/project
```
并运行 opencode。
然后运行 OpenCode。
```bash
opencode
```
接下来，通过运行以下命令来初始化项目的 opencode。
接下来，运行以下命令为项目初始化 OpenCode。
```bash frame="none"
/init
```
这涉及 opencode 分析您的项目并在以下位置创建 `AGENTS.md` 文件
项目根。
OpenCode 会分析你的项目并在项目根目录创建一个 `AGENTS.md` 文件。
:::tip
您应该将项目的 `AGENTS.md` 文件提交到 Git。
你应该将项目的 `AGENTS.md` 文件提交到 Git。
:::
这有助于 opencode 理解项目结构和使用的编码模式。
这有助于 OpenCode 理解项目结构和编码规范。
---
## 用法
## 使用
您现在已准备好使用 opencode 来处理您的项目。请轻松询问任何事物！
现在你已经准备好使用 OpenCode 来处理项目了，尽管提问吧！
如果您不熟悉使用 AI 编码代理，以下是一些可能会有所帮助的示例。
如果你是第一次使用 AI 编码代理，以下示例可能会对你有所帮助。
---
### 提问
您可以要求 opencode 向您解释代码库。
你可以让 OpenCode 为你讲解代码库。
:::tip
使用 `@` 键模糊搜索工程中的文件。
使用 `@` 键可以模糊搜索项目中的文件。
:::
```txt frame="none" "@packages/functions/src/api/index.ts"
How is authentication handled in @packages/functions/src/api/index.ts
```
如果您没有处理代码库的一部分，这会很有帮助。
当你遇到不熟悉的代码时，这个功能非常有用。
---
### 添加功能
您可以要求 opencode 向您的项目添加新功能。但是我们首先建议要求它制定一个计划。
你可以让 OpenCode 为项目添加新功能。不过我们建议先让它制定一个计划。
1. **创建计划**
1. **制定计划**
opencode 有一个 _计划模式_，该模式禁止其进行更改和
相反，建议 _如何_ 实现该功能。
OpenCode 有一个*计划模式*，该模式下它不会进行任何修改，而是建议*如何*实现该功能。
使用 **Tab** 键切换到它。您会在右下角有一个指示符。
使用 **Tab** 键切换到计划模式。你会在右下角看到模式指示器。
```bash frame="none" title="Switch to Plan mode"
<TAB>
```
现在让我们描述一下我们想要它做什么。
接下来描述你希望它做什么。
```txt frame="none"
When a user deletes a note, we'd like to flag it as deleted in the database.
@@ -237,17 +233,15 @@ How is authentication handled in @packages/functions/src/api/index.ts
From this screen, the user can undelete a note or permanently delete it.
```
您需要为 opencode 提供足够的详细信息才能了解您想要的内容。它有帮助
就像与团队中的初级开发人员交谈一样与它交谈。
你需要提供足够的细节，让 OpenCode 理解你的需求。可以把它当作团队中的一名初级开发者来沟通。
:::tip
为 opencode 提供大量上下文和示例，以帮助其理解您的内容
想。
为 OpenCode 提供充足的上下文和示例，帮助它理解你的需求。
:::
2. **迭代计划**
一旦它为您提供了计划，您就可以提供反馈或添加更多详细信息。
当它给出计划后，你可以提供反馈或补充更多细节。
```txt frame="none"
We'd like to design this new screen using a design I've used before.
@@ -255,22 +249,20 @@ How is authentication handled in @packages/functions/src/api/index.ts
```
:::tip
将图像拖放到终端中以将其添加到提示中。
将图片拖放到终端中即可将其添加到提示词中。
:::
opencode 可以扫描您提供的任何图像并将其添加到提示中。您可以
通过将图像拖放到终端中来完成此操作。
OpenCode 可以扫描你提供的图片并将其添加到提示词中。只需将图片拖放到终端窗口即可。
3. **构建功能**
一旦您对计划感到满意，请切换回 _构建模式_
再次按 **Tab** 键。
当你对计划满意后，再次按 **Tab** 键切换回*构建模式*。
```bash frame="none"
<TAB>
```
并要求它做出改变。
然后让它开始实施。
```bash frame="none"
Sounds good! Go ahead and make the changes.
@@ -278,10 +270,9 @@ How is authentication handled in @packages/functions/src/api/index.ts
---
### 进行更改
### 直接修改
对于更直接的更改，您可以要求 opencode 直接构建它
无需先审查计划。
对于比较简单的修改，你可以直接让 OpenCode 实施，无需先审查计划。
```txt frame="none" "@packages/functions/src/settings.ts" "@packages/functions/src/notes.ts"
We need to add authentication to the /settings route. Take a look at how this is
@@ -289,38 +280,37 @@ handled in the /notes route in @packages/functions/src/notes.ts and implement
the same logic in @packages/functions/src/settings.ts
```
您需要确保提供大量详细信息，以便 opencode 做出正确的决定变化。
请确保提供足够的细节，以便 OpenCode 做出正确的修改。
---
### 撤消更改
### 撤销修改
假设您要求 opencode 进行一些更改。
假设你让 OpenCode 做了一些修改。
```txt frame="none" "@packages/functions/src/api/index.ts"
Can you refactor the function in @packages/functions/src/api/index.ts?
```
但你意识到这不是你想要的。您 **可以撤消** 更改
使用 `/undo` 命令。
但你发现结果不是你想要的。你**可以使用** `/undo` 命令来撤销修改。
```bash frame="none"
/undo
```
opencode 现在将恢复您所做的更改并再次显示您的原始消息。
OpenCode 会还原所做的修改，并重新显示你之前的消息。
```txt frame="none" "@packages/functions/src/api/index.ts"
Can you refactor the function in @packages/functions/src/api/index.ts?
```
您可以从这里调整提示并要求 opencode 重试。
你可以调整提示词，让 OpenCode 重新尝试。
:::tip
您可以多次运行 `/undo` 以撤销多次更改。
你可以多次运行 `/undo` 来撤销多次修改。
:::
或者您 **可以使用 `/redo` 命令重做** 更改。
你也**可以使用** `/redo` 命令来重做修改。
```bash frame="none"
/redo
@@ -330,24 +320,24 @@ Can you refactor the function in @packages/functions/src/api/index.ts?
## 分享
您与 opencode 的对话可以 [与您的团队分享](/docs/share)。
你与 OpenCode 的对话可以[与团队分享](/docs/share)。
```bash frame="none"
/share
```
这会创建当前对话的链接并复制到剪贴板。
这会生成当前对话的链接并复制到剪贴板。
:::note
默认情况下不共享对话。
对话默认不会被分享。
:::
这是带有 opencode 的 [示例对话](https://opencode.ai/s/4XP1fce5)。
这是一个与 OpenCode 的[示例对话](https://opencode.ai/s/4XP1fce5)。
---
## 定制
## 个性化
就是这样！你现在已经是 opencode 高手了。
以上就是全部内容！你现在已经是 OpenCode 的使用高手了。
要让您成为自己的，我们建议 [选择一个主题](/docs/themes)、[自定义交互绑定](/docs/keybinds)、[配置代码整理程序](/docs/formatters)、[创建自定义命令](/docs/commands) 或使用 [opencode 配置](/docs/config)。
要让它更符合你的习惯，我们推荐[选择一个主题](/docs/themes)、[自定义快捷键](/docs/keybinds)、[配置代码格式化工具](/docs/formatters)、[创建自定义命令](/docs/commands)，或者探索 [OpenCode 配置](/docs/config)。

58
packages/web/src/content/docs/zh-cn/keybinds.mdx
View File

@@ -1,9 +1,9 @@
---
title: 快捷键
description: 自定义您的按键绑定。
description: 自定义您的快捷键。
---
opencode 有一个按键绑定列表，您可以通过 opencode 配置进行自定义。
OpenCode 提供了一系列快捷键，您可以通过 OpenCode 配置进行自定义。
```json title="opencode.json"
{
@@ -105,19 +105,19 @@ opencode 有一个按键绑定列表，您可以通过 opencode 配置进行自
---
## Leader 键
## 前导键
opencode 对大多数按键绑定使用 `leader` 键。这可以避免终端中的冲突。
OpenCode 的大多数快捷键使用 `leader`（前导键）。这可以避免与终端中的其他快捷键冲突。
默认情况下，`ctrl+x` 是主键，大多数操作要求您先按主键，再按快捷键。例如，要开始新会话，请先按 `ctrl+x`，然后按 `n`。
默认情况下，`ctrl+x` 是前导键，大多数操作需要您先按下前导键，然后再按对应的快捷键。例如，要新建一个会话，请先按 `ctrl+x`，然后按 `n`。
您不需要为键绑定使用主键，但我们建议您这样做。
您不一定需要使用前导键来设置快捷键，但我们建议您这样做。
---
## 禁用按键绑定
## 禁用快捷键
您可以通过将按键添加到您的配置中并使用值“none”来禁用按键绑定。
您可以通过在配置中将对应的键值设置为 "none" 来禁用某个快捷键。
```json title="opencode.json"
{
@@ -130,41 +130,41 @@ opencode 对大多数按键绑定使用 `leader` 键。这可以避免终端中
---
## 桌面提示快捷键
## 桌面版提示词输入快捷键
opencode 桌面应用程序提示输入支持常见的 Readline/Emacs 风格的文本编辑快捷方式。这些是内置的，目前无法通过 `opencode.json` 进行配置。
OpenCode 桌面应用的提示词输入框支持常见的 Readline/Emacs 风格文本编辑快捷键。这些快捷键为内置功能，目前无法通过 `opencode.json` 进行配置。
| 快捷键 | 动作 |
| -------- | ------------------------- |
| `ctrl+a` | 移至当前行起点 |
| `ctrl+e` | 移至当前行尾 |
| `ctrl+b` | 将光标向后移动一个字符 |
| `ctrl+f` | 将光标向前移动一个字符 |
| `alt+b` | 将光标向后移动一个单词 |
| `alt+f` | 将光标向前移动一个单词 |
| `ctrl+d` | 删除光标下的字符 |
| `ctrl+k` | 删除到行尾 |
| `ctrl+u` | 删除到行首 |
| 快捷键 | 操作 |
| -------- | --------------------------------- |
| `ctrl+a` | 移动到当前行的开头 |
| `ctrl+e` | 移动到当前行的末尾 |
| `ctrl+b` | 光标向后移动一个字符 |
| `ctrl+f` | 光标向前移动一个字符 |
| `alt+b` | 光标向后移动一个单词 |
| `alt+f` | 光标向前移动一个单词 |
| `ctrl+d` | 删除光标所在位置的字符 |
| `ctrl+k` | 删除从光标到行尾的内容 |
| `ctrl+u` | 删除从光标到行首的内容 |
| `ctrl+w` | 删除前一个单词 |
| `alt+d` | 删除下一个单词 |
| `ctrl+t` | 转置字符 |
| `ctrl+g` | 取消弹出窗口/中止运行响应 |
| `alt+d` | 删除后一个单词 |
| `ctrl+t` | 交换光标前后的字符 |
| `ctrl+g` | 取消弹出窗口 / 中止正在运行的响应 |
---
## Shift+Enter
默认情况下，某些终端不发送带有 Enter 的修饰键。您可能需要配置终端发送 `Shift+Enter` 作为转义序列。
某些终端默认不会发送带修饰键的 Enter 键。您可能需要配置终端将 `Shift+Enter` 作为转义序列发送。
### Windows Terminal
打开您的 `settings.json`：
打开您的 `settings.json` 文件，路径为：
```
%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
```
将其添加到根级 `actions` 数组：
将以下内容添加到根级 `actions` 数组中：
```json
"actions": [
@@ -178,7 +178,7 @@ opencode 桌面应用程序提示输入支持常见的 Readline/Emacs 风格的
]
```
将其添加到根级 `keybindings` 数组：
将以下内容添加到根级 `keybindings` 数组中：
```json
"keybindings": [
@@ -189,4 +189,4 @@ opencode 桌面应用程序提示输入支持常见的 Readline/Emacs 风格的
]
```
保存文件并重新启动 Windows Terminal 或打开新选项卡。
保存文件并重启 Windows Terminal，或打开一个新标签页。

118
packages/web/src/content/docs/zh-cn/lsp.mdx
View File

@@ -1,71 +1,71 @@
---
title: LSP 服务器
description: opencode 与您的 LSP 服务器集成。
description: OpenCode 与你的 LSP 服务器集成。
---
opencode 与您的语言服务器协议 (LSP) 集成，以帮助 LLM 与您的代码库交互。它使用诊断向 LLM 提供反馈。
OpenCode 与你的语言服务器协议（LSP）集成，帮助 LLM 与你的代码库进行交互。它利用诊断信息向 LLM 提供反馈。
---
## 内置
## 内置支持
opencode 附带了多种适用于流行语言的内置 LSP 服务器：
OpenCode 内置了多种适用于主流语言的 LSP 服务器：
| LSP 服务器 | 扩展名 | 要求 |
| ------------------ | ------------------------------------------------------------------- | ------------------------------------------------ |
| astro | .astro | Astro 项目自动安装 |
| ------------------ | ------------------------------------------------------------------- | ----------------------------------------------------- |
| astro | .astro | 为 Astro 项目自动安装 |
| bash | .sh, .bash, .zsh, .ksh | 自动安装 bash-language-server |
| clangd | .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++ | 自动安装 C/C++ 项目 |
| csharp | .cs | `.NET SDK` 已安装 |
| clojure-lsp | .clj, .cljs, .cljc, .edn | `clojure-lsp` 命令可用 |
| dart | .dart | `dart` 命令可用 |
| deno | .ts, .tsx, .js, .jsx, .mjs | `deno` 命令可用（自动检测 deno.json/deno.jsonc） |
| elixir-ls | .ex, .exs | `elixir` 命令可用 |
| eslint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue | `eslint` 项目中的依赖项 |
| fsharp | .fs, .fsi, .fsx, .fsscript | `.NET SDK` 已安装 |
| gleam | .gleam | `gleam` 命令可用 |
| gopls | .go | `go` 命令可用 |
| hls | .hs, .lhs | `haskell-language-server-wrapper` 命令可用 |
| jdtls | .java | `Java SDK (version 21+)` 已安装 |
| kotlin-ls | .kt, .kts | Kotlin 项目的自动安装 |
| lua-ls | .lua | 自动安装 Lua 项目 |
| nixd | .nix | `nixd` 命令可用 |
| ocaml-lsp | .ml, .mli | `ocamllsp` 命令可用 |
| oxlint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | `oxlint` 项目中的依赖项 |
| php intelephense | .php | PHP 项目的自动安装 |
| prisma | .prisma | `prisma` 命令可用 |
| pyright | .py, .pyi | `pyright` 依赖项已安装 |
| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru | `ruby` 和 `gem` 命令可用 |
| rust | .rs | `rust-analyzer` 命令可用 |
| sourcekit-lsp | .swift, .objc, .objcpp | `swift` 已安装（`xcode` 在 macOS 上） |
| svelte | .svelte | Svelte 项目的自动安装 |
| terraform | .tf, .tfvars | 从 GitHub 版本自动安装 |
| tinymist | .typ, .typc | 从 GitHub 版本自动安装 |
| typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | `typescript` 项目中的依赖项 |
| vue | .vue | Vue 项目自动安装 |
| clangd | .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++ | 为 C/C++ 项目自动安装 |
| csharp | .cs | 需要已安装 `.NET SDK` |
| clojure-lsp | .clj, .cljs, .cljc, .edn | 需要 `clojure-lsp` 命令可用 |
| dart | .dart | 需要 `dart` 命令可用 |
| deno | .ts, .tsx, .js, .jsx, .mjs | 需要 `deno` 命令可用（自动检测 deno.json/deno.jsonc） |
| elixir-ls | .ex, .exs | 需要 `elixir` 命令可用 |
| eslint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue | 项目中需要 `eslint` 依赖 |
| fsharp | .fs, .fsi, .fsx, .fsscript | 需要已安装 `.NET SDK` |
| gleam | .gleam | 需要 `gleam` 命令可用 |
| gopls | .go | 需要 `go` 命令可用 |
| hls | .hs, .lhs | 需要 `haskell-language-server-wrapper` 命令可用 |
| jdtls | .java | 需要已安装 `Java SDK (version 21+)` |
| kotlin-ls | .kt, .kts | 为 Kotlin 项目自动安装 |
| lua-ls | .lua | 为 Lua 项目自动安装 |
| nixd | .nix | 需要 `nixd` 命令可用 |
| ocaml-lsp | .ml, .mli | 需要 `ocamllsp` 命令可用 |
| oxlint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | 项目中需要 `oxlint` 依赖 |
| php intelephense | .php | 为 PHP 项目自动安装 |
| prisma | .prisma | 需要 `prisma` 命令可用 |
| pyright | .py, .pyi | 需要已安装 `pyright` 依赖 |
| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru | 需要 `ruby` 和 `gem` 命令可用 |
| rust | .rs | 需要 `rust-analyzer` 命令可用 |
| sourcekit-lsp | .swift, .objc, .objcpp | 需要已安装 `swift`（macOS 上为 `xcode`） |
| svelte | .svelte | 为 Svelte 项目自动安装 |
| terraform | .tf, .tfvars | 从 GitHub releases 自动安装 |
| tinymist | .typ, .typc | 从 GitHub releases 自动安装 |
| typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | 项目中需要 `typescript` 依赖 |
| vue | .vue | 为 Vue 项目自动安装 |
| yaml-ls | .yaml, .yml | 自动安装 Red Hat yaml-language-server |
| zls | .zig, .zon | `zig` 命令可用 |
| zls | .zig, .zon | 需要 `zig` 命令可用 |
当检测到上述文件扩展名之一并且满足要求时，LSP 服务器将自动启用。
当检测到上述文件扩展名且满足相应要求时，LSP 服务器会自动启用。
:::note
您可以通过将 `OPENCODE_DISABLE_LSP_DOWNLOAD` 环境变量设置为 `true` 来取消自动 LSP 服务器下载。
你可以将 `OPENCODE_DISABLE_LSP_DOWNLOAD` 环境变量设置为 `true` 来禁用 LSP 服务器的自动下载。
:::
---
## 它是如何工作的
## 工作原理
当 opencode 打开一个文件时，它：
当 opencode 打开一个文件时，它会：
1. 根据所有启用的 LSP 服务器检查文件扩展名。
2. 如果尚未运行，则启动相应的 LSP 服务器。
1. 将文件扩展名与所有已启用的 LSP 服务器进行匹配。
2. 如果对应的 LSP 服务器尚未运行，则自动启动它。
---
## 配置
您可以通过 opencode 配置中的 `lsp` 部分自定义 LSP 服务器。
你可以通过 opencode 配置文件中的 `lsp` 部分来自定义 LSP 服务器。
```json title="opencode.json"
{
@@ -74,23 +74,23 @@ opencode 附带了多种适用于流行语言的内置 LSP 服务器：
}
```
每个 LSP 服务器支持以下功能：
每个 LSP 服务器支持以下配置项：
| 属性 | 类型 | 描述 |
| ---------------- | -------- | ----------------------------------- |
| `disabled` | boolean | 将其设置为 `true` 以禁用 LSP 服务器 |
| ---------------- | -------- | --------------------------------- |
| `disabled` | boolean | 设置为 `true` 可禁用该 LSP 服务器 |
| `command` | string[] | 启动 LSP 服务器的命令 |
| `extensions` | string[] | 此 LSP 服务器应处理的文件扩展名 |
| `extensions` | string[] | 该 LSP 服务器需要处理的文件扩展名 |
| `env` | object | 启动服务器时设置的环境变量 |
| `initialization` | object | 发送到 LSP 服务器的初始化选项 |
| `initialization` | object | 发送给 LSP 服务器的初始化选项 |
让我们看一些例子。
下面来看一些示例。
---
### 环境变量
启动 LSP 服务器时使用 `env` 参数设置环境变量：
使用 `env` 属性在启动 LSP 服务器时设置环境变量：
```json title="opencode.json" {5-7}
{
@@ -109,7 +109,7 @@ opencode 附带了多种适用于流行语言的内置 LSP 服务器：
### 初始化选项
使用 `initialization` 属性将初始化选项传递给 LSP 服务器。这些是在 LSP `initialize` 请求发送期间的服务器特定设置：
使用 `initialization` 属性向 LSP 服务器传递初始化选项。这些是在 LSP `initialize` 请求期间发送的服务器特定设置：
```json title="opencode.json" {5-9}
{
@@ -127,14 +127,14 @@ opencode 附带了多种适用于流行语言的内置 LSP 服务器：
```
:::note
初始化选项因 LSP 服务器而异。检查 LSP 服务器的文档以获得可用选项。
初始化选项因 LSP 服务器而异。请查阅你所使用的 LSP 服务器的文档以了解可用选项。
:::
---
### 禁用 LSP 服务器
要全局禁用 **所有** LSP 服务，将 `lsp` 设置为 `false`：
要全局禁用**所有** LSP 服务器，将 `lsp` 设置为 `false`：
```json title="opencode.json" {3}
{
@@ -143,7 +143,7 @@ opencode 附带了多种适用于流行语言的内置 LSP 服务器：
}
```
要禁用 **特定** LSP 服务器，将 `disabled` 设置为 `true`：
要禁用**特定的** LSP 服务器，将 `disabled` 设置为 `true`：
```json title="opencode.json" {5}
{
@@ -160,7 +160,7 @@ opencode 附带了多种适用于流行语言的内置 LSP 服务器：
### 自定义 LSP 服务器
您可以通过指定命令和文件扩展名来添加自定义 LSP 服务器：
你可以通过指定命令和文件扩展名来添加自定义 LSP 服务器：
```json title="opencode.json" {4-7}
{
@@ -176,13 +176,13 @@ opencode 附带了多种适用于流行语言的内置 LSP 服务器：
---
## 其他信息
## 补充信息
### PHP Intelephense
PHP Intelephense 通过许可证密钥提供高级功能。您可以通过将（仅）密钥放置在以下位置的文本文件中来提供许可证密钥：
PHP Intelephense 通过许可证密钥提供高级功能。你可以将许可证密钥单独放在以下路径的文本文件中：
- 在 macOS/Linux 上：`$HOME/intelephense/license.txt`
- 在 Windows 上：`%USERPROFILE%/intelephense/license.txt`
- macOS/Linux：`$HOME/intelephense/license.txt`
- Windows：`%USERPROFILE%/intelephense/license.txt`
该文件应仅包含许可证密钥，不包含其他内容。
该文件应仅包含许可证密钥，不要添加其他任何内容。

152
packages/web/src/content/docs/zh-cn/mcp-servers.mdx
View File

@@ -3,27 +3,27 @@ title: MCP 服务器
description: 添加本地和远程 MCP 工具。
---
您可以使用“模型上下文协议”或MCP将外部工具添加到opencode。opencode支持本地和远程服务器。
你可以通过 _Model Context Protocol_（MCP）为 OpenCode 添加外部工具。OpenCode 同时支持本地和远程服务器。
添加使用后，MCP工具将自动与内置工具一起供LLM。
添加后，MCP 工具会自动与内置工具一起提供给 LLM 使用。
---
#### 注意事项
当您使用 MCP 服务器时，它会添加到上下文中。如果您有很多工具，这会很快增加。因此，我们建议您选择使用哪些 MCP 服务器。
使用 MCP 服务器时，它会占用上下文空间。如果你启用了大量工具，上下文消耗会迅速增加。因此，我们建议谨慎选择要使用的 MCP 服务器。
:::tip
MCP服务器会添加到您的上下文中，因此您需要小心启用哪些服务器。
MCP 服务器会占用你的上下文空间，所以请谨慎选择启用哪些服务器。
:::
某些MCP服务器（例如GitHub MCP服务器）往往会添加大量代币，并且很容易超出上下文限制。
某些 MCP 服务器（例如 GitHub MCP 服务器）往往会消耗大量 Token，很容易超出上下文限制。
---
## 启用
您可以在`mcp`下的[opencode配置](https://opencode.ai/docs/config/)中定义MCP服务器。为每个MCP添加唯一的名称。当提示LLM时，您可以通过名称引用该MCP。
你可以在 [OpenCode 配置](https://opencode.ai/docs/config/)的 `mcp` 字段下定义 MCP 服务器。为每个 MCP 指定一个唯一的名称，在提示词中可以通过该名称来引用对应的 MCP。
```jsonc title="opencode.jsonc" {6}
{
@@ -40,15 +40,15 @@ MCP服务器会添加到您的上下文中，因此您需要小心启用哪些
}
```
您还可以通过将`enabled`设置为`false`来取消服务器。如果您想暂时取消服务器而不将其从配置中删除，这非常有用。
你也可以将 `enabled` 设置为 `false` 来禁用某个服务器。当你想临时禁用某个服务器而不将其从配置中移除时，这个选项非常有用。
---
### 覆盖远程默认值
组织可以通过其 `.well-known/opencode` 端点提供默认的 MCP 服务器。这些服务器可能默认被禁用，允许用户选择他们需要的服务器。
组织可以通过其 `.well-known/opencode` 端点提供默认的 MCP 服务器。这些服务器可能默认处于禁用状态，允许用户按需启用。
要从组织的远程特定启用服务器，请使用配置 `enabled: true` 将其添加到本地配置：
要启用组织远程配置中的某个服务器，请在本地配置中添加该服务器并设置 `enabled: true`：
```json title="opencode.json"
{
@@ -63,13 +63,13 @@ MCP服务器会添加到您的上下文中，因此您需要小心启用哪些
}
```
您的本地配置值会覆盖远程默认值。有关更多详细信息，请参阅[配置优先级](/docs/config#precedence-order)。
本地配置值会覆盖远程默认值。详情请参阅[配置优先级](/docs/config#precedence-order)。
---
## 本地
使用`type`将本地MCP服务器添加到MCP对像中的`"local"`。
通过在 MCP 对象中将 `type` 设置为 `"local"` 来添加本地 MCP 服务器。
```jsonc title="opencode.jsonc" {15}
{
@@ -88,9 +88,9 @@ MCP服务器会添加到您的上下文中，因此您需要小心启用哪些
}
```
该命令是本地MCP服务器的启动方式。您还可以确定环境变量列表。
`command` 用于指定本地 MCP 服务器的启动命令。你还可以传入一组环境变量。
例如，以下是添加测试 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 服务器的方法。
例如，以下是添加测试用的 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 服务器的方法。
```jsonc title="opencode.jsonc"
{
@@ -104,7 +104,7 @@ MCP服务器会添加到您的上下文中，因此您需要小心启用哪些
}
```
要使用它，我可以将 `use the mcp_everything tool` 添加到我的提示中。
要使用它，可以在提示词中添加 `use the mcp_everything tool`。
```txt "mcp_everything"
use the mcp_everything tool to add the number 3 and 4
@@ -117,18 +117,18 @@ use the mcp_everything tool to add the number 3 and 4
以下是配置本地 MCP 服务器的所有选项。
| 选项 | 类型 | 必填 | 描述 |
| ------------- | ------ | ---- | -------------------------------------------------------------- |
| `type` | 字符串 | 是 | MCP 服务器连接类型，必须是`"local"`。 |
| `command` | 数据库 | 是 | 运行 MCP 服务器的命令和参数。 |
| ------------- | ------ | ---- | ----------------------------------------------------------------- |
| `type` | 字符串 | 是 | MCP 服务器连接类型，必须为 `"local"`。 |
| `command` | 数组 | 是 | 运行 MCP 服务器的命令及参数。 |
| `environment` | 对象 | | 运行服务器时设置的环境变量。 |
| `enabled` | 布尔 | | 在启动时启用或禁用MCP 服务器。 |
| `timeout` | 数量 | | 从MCP服务器获取工具的超时（以毫秒为单位）。默认为5000（5秒）。 |
| `enabled` | 布尔值 | | 启动时启用或禁用该 MCP 服务器。 |
| `timeout` | 数字 | | 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。 |
---
## 远程
通过将`type`设置为ZZPH1Z添加远程MCP服务器。
通过将 `type` 设置为 `"remote"` 来添加远程 MCP 服务器。
```json title="opencode.json"
{
@@ -146,36 +146,36 @@ use the mcp_everything tool to add the number 3 and 4
}
```
`"remote"` 是远程MCP服务器的URL，使用`url`选项您可以创建标头列表。
`url` 是远程 MCP 服务器的地址，通过 `headers` 选项可以传入一组请求头。
---
#### 选项
| 选项 | 类型 | 必填 | 描述 |
| ---------- | ------ | ---- | -------------------------------------------------------------- |
| `headers` | 字符串 | 是 | MCP 服务器连接类型，必须是`type`。 |
| `"remote"` | 字符串 | 是 | 远程 MCP 服务器的 URL。 |
| `url` | 布尔 | | 在启动时启用或禁用MCP 服务器。 |
| `enabled` | 对象 | | 随请求一起发送的标头。 |
| `headers` | 对象 | | OAuth 身份验证。请参阅下面的配置[开放认证](#oauth) 部分。 |
| `oauth` | 数量 | | 从MCP服务器获取工具的超时（以毫秒为单位）。默认为5000（5秒）。 |
| --------- | ------ | ---- | ----------------------------------------------------------------- |
| `type` | 字符串 | 是 | MCP 服务器连接类型，必须为 `"remote"`。 |
| `url` | 字符串 | 是 | 远程 MCP 服务器的 URL。 |
| `enabled` | 布尔值 | | 启动时启用或禁用该 MCP 服务器。 |
| `headers` | 对象 | | 随请求发送的请求头。 |
| `oauth` | 对象 | | OAuth 身份验证配置。详见下方 [OAuth](#oauth) 部分。 |
| `timeout` | 数字 | | 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。 |
---
## OAuth
opencode自动处理远程MCP服务器的OAuth身份验证。当服务器需要身份验证时，opencode将：
OpenCode 会自动处理远程 MCP 服务器的 OAuth 身份验证。当服务器需要身份验证时，OpenCode 将：
1. 检测 401 响应并启动 OAuth 流程
2. 如果服务器支持，请使用**动态客户端注册 (RFC 7591)**
3. 安全地存储Tokens以供将来的请求
2. 在服务器支持的情况下使用**动态客户端注册（RFC 7591）**
3. 安全地存储 Token 以供后续请求使用
---
### 自动
### 自动认证
对于大多数支持 OAuth 的 MCP 配置服务器，不需要特殊配置。只需远程服务器：
对于大多数支持 OAuth 的 MCP 服务器，无需特殊配置。只需配置远程服务器即可：
```json title="opencode.json"
{
@@ -189,13 +189,13 @@ opencode自动处理远程MCP服务器的OAuth身份验证。当服务器需要
}
```
如果服务器需要身份验证，opencode 将在您第一次尝试使用它时提示您进行身份验证。如果没有，您可以使用 `timeout`[手动触发流量](#authenticating)。
如果服务器需要身份验证，OpenCode 会在你首次使用时提示你进行认证。你也可以使用 `opencode mcp auth <server-name>` [手动触发认证流程](#authenticating)。
---
### 预注册
如果您有来自MCP服务器强大的客户端，则可以配置它们：
如果你已经从 MCP 服务器提供商处获得了客户端凭据，可以直接配置：
```json title="opencode.json" {7-11}
{
@@ -218,33 +218,33 @@ opencode自动处理远程MCP服务器的OAuth身份验证。当服务器需要
### 身份验证
您可以手动触发身份验证或管理凭据。
你可以手动触发身份验证或管理凭据。
使用特定MCP服务器进行身份验证：
对特定 MCP 服务器进行身份验证：
```bash
opencode mcp auth my-oauth-server
```
列出所有MCP服务器及其身份验证状态：
列出所有 MCP 服务器及其认证状态：
```bash
opencode mcp list
```
删除存储的凭据：
删除已存储的凭据：
```bash
opencode mcp logout my-oauth-server
```
`opencode mcp auth <server-name>` 命令将打开您的浏览器进行授权。授权后，opencode Tokens安全地存储在 `mcp auth` 中。
`mcp auth` 命令会打开浏览器进行授权。授权完成后，OpenCode 会将 Token 安全地存储在 `~/.local/share/opencode/mcp-auth.json` 中。
---
#### 禁用 OAuth
如果要禁用服务器的自动OAuth（例如，对于使用API密钥的服务器），则`~/.local/share/opencode/mcp-auth.json`设置为`oauth`：
如果你想为某个服务器禁用自动 OAuth（例如，该服务器使用 API 密钥而非 OAuth），可以将 `oauth` 设置为 `false`：
```json title="opencode.json" {7}
{
@@ -267,37 +267,37 @@ opencode mcp logout my-oauth-server
#### OAuth 选项
| 选项 | 类型 | 描述 |
| -------------- | --------------- | --------------------------------------------------- |
| `false` | 对象 \| `oauth` | OAuth 配置对象，或 `false` 以取消 OAuth 自动检测。 |
| -------------- | --------------- | ------------------------------------------------------ |
| `oauth` | 对象 \| `false` | OAuth 配置对象，或设为 `false` 以禁用 OAuth 自动检测。 |
| `clientId` | 字符串 | OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。 |
| `clientSecret` | 字符串 | OAuth客户端密钥（如果需要授权服务器）。 |
| `scope` | 字符串 | 授权期间请求的 OAuth 范围。 |
| `clientSecret` | 字符串 | OAuth 客户端密钥（如果授权服务器要求提供）。 |
| `scope` | 字符串 | 授权时请求的 OAuth 作用域。 |
#### 调试
如果远程MCP服务器无法进行身份验证，您可以通过以下方式诊断问题：
如果远程 MCP 服务器身份验证失败，你可以通过以下方式诊断问题：
```bash
# View auth status for all OAuth-capable servers
# 查看所有支持 OAuth 的服务器的认证状态
opencode mcp auth list
# Debug connection and OAuth flow for a specific server
# 调试特定服务器的连接和 OAuth 流程
opencode mcp debug my-oauth-server
```
`mcp debug`命令显示当前身份验证状态、测试HTTP连接并尝试OAuth发现流程。
`mcp debug` 命令会显示当前认证状态、测试 HTTP 连接，并尝试执行 OAuth 发现流程。
---
## 管理
您的 MCP 可以作为 opencode 中的工具以及内置工具使用。，您可以像任何其他工具一样通过 opencode 配置来管理它们。
你的 MCP 在 OpenCode 中作为工具使用，与内置工具并列。因此，你可以像管理其他工具一样，通过 OpenCode 配置来管理它们。
---
### 全局
这意味著您可以全局启用或禁用它们。
你可以全局启用或禁用 MCP 工具。
```json title="opencode.json" {14}
{
@@ -318,7 +318,7 @@ opencode mcp debug my-oauth-server
}
```
我们还可以使用 glob 模式来取消所有匹配的 MCP。
也可以使用 glob 模式来禁用所有匹配的 MCP。
```json title="opencode.json" {14}
{
@@ -339,16 +339,16 @@ opencode mcp debug my-oauth-server
}
```
这里我们使用 glob 模式 `my-mcp*` 来取消所有 MCP。
这里使用 glob 模式 `my-mcp*` 来禁用所有 MCP。
---
### 每个代理人
### 按代理配置
如果您有大量 MCP 服务器，您可以选择为每个代理启用它们并全局取消它们。因此：
如果你有大量 MCP 服务器，可以选择全局禁用它们，然后仅在特定代理中启用。具体做法：
1. 全局禁用它作为工具。
2. 在您的[代理配置](/docs/agents#tools)中，启用MCP作为服务器工具。
1. 全局禁用该工具。
2. 在[代理配置](/docs/agents#tools)中，将 MCP 服务器作为工具启用。
```json title="opencode.json" {11, 14-18}
{
@@ -375,16 +375,16 @@ opencode mcp debug my-oauth-server
---
#### 全局模式
#### Glob 模式
glob 模式使用简单的正则表达式 globbing 模式：
glob 模式使用简单的正则通配符规则：
- `*` 匹配零个或多个任意字符（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等）
- `?` 恰好匹配一个字符
- 所有其他字符均按字面意思匹配
- `?` 匹配恰好一个字符
- 其他字符按字面值匹配
:::note
MCP服务器工具以名称服务器作为出口进行注册，要因此禁用服务器的所有工具，只需使用：
MCP 服务器工具在注册时以服务器名称作为前缀，因此要禁用某个服务器的所有工具，只需使用：
```
"mymcpservername_*": false
@@ -396,13 +396,13 @@ MCP服务器工具以名称服务器作为出口进行注册，要因此禁用
## 示例
以下是一些常见的 MCP 服务器的示例。如果您想记录其他服务器，您可以提交 PR。
以下是一些常见 MCP 服务器的配置示例。如果你想记录其他服务器的用法，欢迎提交 PR。
---
### 哨兵
### Sentry
添加[哨兵MCP服务器](https://mcp.sentry.dev)以与您的Sentry项目和问题进行交互。
添加 [Sentry MCP 服务器](https://mcp.sentry.dev) 以与你的 Sentry 项目和问题进行交互。
```json title="opencode.json" {4-8}
{
@@ -423,9 +423,9 @@ MCP服务器工具以名称服务器作为出口进行注册，要因此禁用
opencode mcp auth sentry
```
这将打开一个浏览器窗口以完成 OAuth 流程并将 opencode 连接到您的 Sentry 账户。
这会打开浏览器窗口完成 OAuth 流程，将 OpenCode 连接到你的 Sentry 账户。
通过身份验证后，您可以在提示中使用Sentry工具来查询问题、项目和错误数据。
认证完成后，你可以在提示词中使用 Sentry 工具来查询问题、项目和错误数据。
```txt "use sentry"
Show me the latest unresolved issues in my project. use sentry
@@ -433,7 +433,7 @@ Show me the latest unresolved issues in my project. use sentry
---
### 背景7
### Context7
添加 [Context7 MCP 服务器](https://github.com/upstash/context7) 以搜索文档。
@@ -449,7 +449,7 @@ Show me the latest unresolved issues in my project. use sentry
}
```
如果您注册了免费帐户，则可以使用 API 轴并获得更高的速率限制。
如果你注册了免费账户，可以使用 API 密钥来获得更高的速率限制。
```json title="opencode.json" {7-9}
{
@@ -466,15 +466,15 @@ Show me the latest unresolved issues in my project. use sentry
}
```
这里我们假设您设置了 `CONTEXT7_API_KEY` 环境变量。
这里假设你已经设置了 `CONTEXT7_API_KEY` 环境变量。
将 `use context7` 添加到提示中以使用 Context7 MCP 服务器。
在提示词中添加 `use context7` 即可使用 Context7 MCP 服务器。
```txt "use context7"
Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
```
或者，您可以将类似的内容添加到您的[代理.md](/docs/rules/)。
你也可以在 [AGENTS.md](/docs/rules/) 中添加类似的规则。
```md title="AGENTS.md"
When you need to search docs, use `context7` tools.
@@ -482,9 +482,9 @@ When you need to search docs, use `context7` tools.
---
### Vercel 的 Grep
### Grep by Vercel
添加 [Vercel 的 Grep](https://grep.app) MCP 服务器正在搜索 GitHub 上的代码片段。
添加 [Grep by Vercel](https://grep.app) MCP 服务器以搜索 GitHub 上的代码片段。
```json title="opencode.json" {4-7}
{
@@ -498,13 +498,13 @@ When you need to search docs, use `context7` tools.
}
```
由于我们将 MCP 服务器命名为 `gh_grep`，因此您可以将 `use the gh_grep tool` 添加到提示中以便代理使用它。
由于我们将 MCP 服务器命名为 `gh_grep`，你可以在提示词中添加 `use the gh_grep tool` 来让代理使用它。
```txt "use the gh_grep tool"
What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
```
或者，您可以将类似的内容添加到您的[代理.md](/docs/rules/)。
你也可以在 [AGENTS.md](/docs/rules/) 中添加类似的规则。
```md title="AGENTS.md"
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.

77
packages/web/src/content/docs/zh-cn/models.mdx
View File

@@ -3,21 +3,21 @@ title: 模型
description: 配置 LLM 提供商和模型。
---
opencode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.dev) 支持 **75+ LLM 提供商**，并支持运行本地模型。
OpenCode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.dev) 支持 **75+ LLM 提供商**，并支持运行本地模型。
---
## 提供商
默认会预加载大多数流行的提供商。如果您已通过 `/connect` 命令添加了提供商的凭据，那么它们将在您启动 opencode 时可用。
大多数热门提供商已默认预加载。如果你通过 `/connect` 命令添加了提供商的凭据，它们将在你启动 OpenCode 时自动可用。
了解有关[提供商](/docs/providers) 的更多信息。
了解更多关于[提供商](/docs/providers)的信息。
---
## 选择模型
配置完提供商后，您可以通过输入以下内容来选择您想要的模型：
配置好提供商后，你可以通过输入以下命令来选择想要使用的模型：
```bash frame="none"
/models
@@ -27,15 +27,15 @@ opencode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.de
## 推荐模型
那里有很多模型，每周都会有新模型问世。
市面上有非常多的模型，每周都有新模型发布。
:::tip
考虑使用我们推荐的模型之一。
建议使用我们推荐的模型。
:::
然而，既擅长生成代码又擅长工具调用的只有少数。
然而，真正擅长代码生成和工具调用的模型只有少数几个。
以下是与 opencode 配合良好的几个模型，排名不分前面。（这不是好看的列表，也不一定是最新的）：
以下是与 OpenCode 配合良好的几个模型，排名不分先后（此列表并非详尽无遗，也不一定是最新的）：
- GPT 5.2
- GPT 5.1 Codex
@@ -46,10 +46,9 @@ opencode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.de
---
## 设置默认值
## 设置默认模型
要将其中之一设置为默认模型，您可以在您的
打开代码配置。
要将某个模型设为默认模型，可以在 OpenCode 配置中设置 `model` 字段。
```json title="opencode.json" {3}
{
@@ -58,15 +57,15 @@ opencode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.de
}
```
这里完整的ID是`provider_id/model_id`。例如，如果您使用[OpenCode Zen](/docs/zen)，则您将使用`opencode/gpt-5.1-codex`来表示GPT 5.1 Codex。
这里完整的 ID 格式为 `provider_id/model_id`。例如，如果你使用 [OpenCode Zen](/docs/zen)，则 GPT 5.1 Codex 对应的值为 `opencode/gpt-5.1-codex`。
如果您配置了[定制生产](/docs/providers#custom)，则`provider_id` 是配​​置中`provider` 部分的按键，`model_id` 是`provider.models` 中的按键。
如果你配置了[自定义提供商](/docs/providers#custom)，`provider_id` 是配置中 `provider` 部分的键名，`model_id` 是 `provider.models` 中的键名。
---
## 配置模型
您可以通过 config.json 全局配置模型的选项。
你可以通过配置文件全局配置模型的选项。
```jsonc title="opencode.jsonc" {7-12,19-24}
{
@@ -100,12 +99,12 @@ opencode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.de
}
```
在这里，我们为两个内置模型配置全局设置：`gpt-5`（通过 `openai` 提供商访问）和 `claude-sonnet-4-20250514`（通过 `anthropic` 提供商访问）。
内置结构和模型名称可以在[Models.dev](https://models.dev) 上找到。
这里我们为两个内置模型配置了全局设置：通过 `openai` 提供商访问的 `gpt-5`，以及通过 `anthropic` 提供商访问的 `claude-sonnet-4-20250514`。
内置的提供商和模型名称可以在 [Models.dev](https://models.dev) 上查阅。
您还可以为您正在使用的任何代理配置这些选项。代理配置会覆盖此处的所有全局选项。 [了解更多](/docs/agents/#additional)。
你还可以为使用中的任何代理配置这些选项。代理配置会覆盖此处的全局选项。[了解更多](/docs/agents/#additional)。
你还可以定义扩展内置 variants 的自定义 variants。variants 允许你为同一模型配置不同设置，而无需创建重复条目：
你也可以定义扩展内置变体的自定义变体。变体允许你为同一个模型配置不同的设置，而无需创建重复的条目：
```jsonc title="opencode.jsonc" {6-21}
{
@@ -137,40 +136,40 @@ opencode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.de
## 变体
许多模型支持具有不同配置的多种变体。opencode附带了流行建设的内置默认变体。
许多模型支持具有不同配置的多种变体。OpenCode 为热门提供商内置了默认变体。
### 内置变体
opencode 附带了许多重大的默认变体：
OpenCode 为许多提供商提供了默认变体：
**Anthropic**：
- `high` - 高思维预算（默认）
- `max` - 最大预算规划
- `high` - 高思考预算（默认）
- `max` - 最大思考预算
**OpenAI**：
因模型而异，但大致如下：
- `none` - 没有推理
- `minimal` - 最少的推理工作
- `low` - 推理工作量低
- `medium` - 中等推理努力
- `high` - 高推理能力
- `xhigh` - 极高的推理能力
- `none` - 无推理
- `minimal` - 极少推理
- `low` - 低推理
- `medium` - 中等推理
- `high` - 高推理
- `xhigh` - 超高推理
**Google**：
- `low` - 降低工作量/Tokens预算
- `high` - 更高的努力/Tokens预算
- `low` - 较低推理/Token 预算
- `high` - 较高推理/Token 预算
:::tip
该列表并不全面。许多其他提供商也有内置的默认值。
此列表并不全面，许多其他提供商也有内置的默认变体。
:::
### 自定义变体
您可以覆盖现有变体或添加您自己的变体：
你可以覆盖现有变体或添加自己的变体：
```jsonc title="opencode.jsonc" {7-18}
{
@@ -197,17 +196,17 @@ opencode 附带了许多重大的默认变体：
### 切换变体
使用按键绑定`variant_cycle`在变体之间快速切换。 [了解更多](/docs/keybinds)。
使用快捷键 `variant_cycle` 可以快速在变体之间切换。[了解更多](/docs/keybinds)。
---
## 加载模型
当opencode启动时，它会按以下优先顺序检查模型：
OpenCode 启动时，会按以下优先顺序加载模型：
1. `--model` 或 `-m` 配置命令行标志。格式与文件中的相同：`provider_id/model_id`。
1. `--model` 或 `-m` 命令行标志。格式与配置文件中相同：`provider_id/model_id`。
2. opencode 配置中的模型列表。
2. OpenCode 配置中的 model 字段。
```json title="opencode.json"
{
@@ -216,8 +215,8 @@ opencode 附带了许多重大的默认变体：
}
```
这里的格式是`provider/model`。
格式为 `provider/model`。
3. 最后使用的模型。
3. 上次使用的模型。
4. 第一个模型使用内部优先级。
4. 按内部优先级排列的第一个可用模型。

89
packages/web/src/content/docs/zh-cn/modes.mdx
View File

@@ -1,58 +1,56 @@
---
title: 模式
description: 不同的模式适用于不同的用例。
description: 不同模式适用于不同的使用场景。
---
:::caution
现在通过opencode配置中的`agent`选项配置模式。这
`mode` 选项现已废弃。 [了解更多](/docs/agents)。
模式现在通过 opencode 配置中的 `agent` 选项进行配置。`mode` 选项已废弃。[了解更多](/docs/agents)。
:::
opencode 中的模式允许自定义不同的示例行为、工具和提示。
opencode 中的模式允许你为不同的使用场景自定义行为、工具和提示词。
它具有两种内置模式：**构建**和**计划**。您可以定制
这些或通过 opencode 配置配置您自己的。
opencode 自带两种内置模式：**build** 和 **plan**。你可以自定义这些模式，也可以通过 opencode 配置创建自己的模式。
您可以在会话期间在模式之间切换或在配置文件中配置它们。
你可以在会话中切换模式，也可以在配置文件中进行配置。
---
## 内置
## 内置模式
opencode 有两种内置模式。
opencode 自带两种内置模式。
---
### 构建
### Build
构建是启用所有工具的**默认**模式。这是开发工作的标准模式，您需要完全访问文件操作和系统命令。
Build 是启用了所有工具的**默认**模式。这是进行开发工作的标准模式，你可以完全访问文件操作和系统命令。
---
### 计划
### Plan
专为规划和分析而设计的受限模式。在计划模式下，默认情况下禁用以下工具：
Plan 是一种为规划和分析设计的受限模式。在 plan 模式下，以下工具默认被禁用：
- `write` - 无法创建新文件
- `edit` - 无法修改现有文件，位于 `.opencode/plans/*.md` 的用于详细说明计划本身的文件另外
- `edit` - 无法修改现有文件，但位于 `.opencode/plans/*.md` 的文件除外，用于详细说明计划本身
- `patch` - 无法应用补丁
- `bash` - 无法执行 shell 命令
当您希望人工智能分析代码、建议更改或创建计划而不对代码库进行任何实际修改时，此模式非常有用。
当你希望 AI 分析代码、提出修改建议或制定计划，而不对代码库进行任何实际更改时，此模式非常有用。
---
## 切换
您可以在会话期间使用 _Tab_ 键在模式之间切换。或者您配置的 `switch_mode` 键绑定。
你可以在会话中使用 _Tab_ 键切换模式，或者使用你配置的 `switch_mode` 快捷键。
另请参见：[格式化程序](/docs/formatters)相关代码配置的信息。
另请参阅：[格式化工具](/docs/formatters)了解代码格式化配置的相关信息。
---
## 配置
您可以自定义内置模式或通过配置创建自己的模式。可以通过两种方式配置模式：
你可以自定义内置模式或通过配置创建自己的模式。模式可以通过两种方式进行配置：
### JSON 配置
@@ -85,9 +83,9 @@ opencode 有两种内置模式。
### Markdown 配置
您还可以使用 Markdown 文件定义模式。将它们放入：
你还可以使用 Markdown 文件定义模式。将文件放置在以下位置：
- 全球：`~/.config/opencode/modes/`
- 全局：`~/.config/opencode/modes/`
- 项目：`.opencode/modes/`
```markdown title="~/.config/opencode/modes/review.md"
@@ -110,15 +108,15 @@ You are in code review mode. Focus on:
Provide constructive feedback without making direct changes.
```
Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模式）。
Markdown 文件名即为模式名称（例如，`review.md` 创建一个名为 `review` 的模式）。
让我们详细看看这些配置选项。
下面让我们详细了解这些配置选项。
---
### 模型
使用`model`配置覆盖此模式的默认模型。对于使用针对不同任务优化的不同模型很有帮助。例如，更快的规划模型、更强大的实施模型。
使用 `model` 配置可以覆盖该模式的默认模型。这对于针对不同任务使用不同模型非常有用。例如，规划时使用更快的模型，实现时使用更强大的模型。
```json title="opencode.json"
{
@@ -134,7 +132,7 @@ Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模
### 温度
使用`temperature`配置控制AI响应的随机性和创造。较低的值使响应更加集中和确定，而较高的值则增加创造力和可变性。
使用 `temperature` 配置控制 AI 响应的随机性和创造性。较低的值使响应更加集中和确定性，较高的值则增加创造性和多样性。
```json title="opencode.json"
{
@@ -149,11 +147,11 @@ Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模
}
```
温度值范围通常为 0.0 到 1.0：
温度值的范围通常为 0.0 到 1.0：
- **0.0-0.2**：响应更集中、确定性更高，适合代码分析和规划
- **0.3-0.5**：平衡型响应，兼顾稳定性与创造力
- **0.6-1.0**：响应更有创意和多样性，适合头脑风暴和探索
- **0.0-0.2**：非常集中且确定性高的响应，适合代码分析和规划
- **0.3-0.5**：兼顾稳定性与创造力的平衡型响应，适合一般开发任务
- **0.6-1.0**：更具创造性和多样性的响应，适合头脑风暴和探索性工作
```json title="opencode.json"
{
@@ -173,13 +171,13 @@ Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模
}
```
如果未指定温度，opencode将使用特定于模型的默认值（大多数模型通常为0，Qwen模型为0.55）。
如果未指定温度，opencode 将使用模型特定的默认值（大多数模型通常为 0，Qwen 模型为 0.55）。
---
### 提示词
使用 `prompt` 配置为模式指定自定义系统提示文件。提示文件应包含特定于该模式用途的指令。
使用 `prompt` 配置为模式指定自定义系统提示词文件。提示词文件应包含针对该模式用途的具体指令。
```json title="opencode.json"
{
@@ -191,14 +189,13 @@ Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模
}
```
该路径是相对于配置文件所在位置的。所以这适用于
全局opencode配置和项目特定配置。
此路径相对于配置文件所在位置。因此，全局 opencode 配置和项目特定配置均可使用。
---
### 工具
使用 `tools` 配置控制模式下可用的工具。您可以通过将特定工具设置为 `true` 或 `false` 来启用或禁用特定工具。
使用 `tools` 配置控制该模式下可用的工具。你可以将特定工具设置为 `true` 或 `false` 来启用或禁用它们。
```json
{
@@ -223,7 +220,7 @@ Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模
#### 可用工具
这里是所有可以通过模式配置控制的工具。
以下是所有可通过模式配置控制的工具。
| 工具 | 描述 |
| ----------- | ---------------- |
@@ -233,17 +230,17 @@ Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模
| `read` | 读取文件内容 |
| `grep` | 搜索文件内容 |
| `glob` | 按模式查找文件 |
| `list` | 上市目录内容 |
| `list` | 列出目录内容 |
| `patch` | 对文件应用补丁 |
| `todowrite` | 管理待办事项列表 |
| `todoread` | 阅读待办事项列表 |
| `todoread` | 读取待办事项列表 |
| `webfetch` | 获取网页内容 |
---
## 自定义模式
您可以通过将自定义模式添加到配置来创建自己的自定义模式。以下是使用这两种方法的示例：
你可以通过在配置中添加自定义模式来创建自己的模式。以下是两种方式的示例：
### 使用 JSON 配置
@@ -268,7 +265,7 @@ Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模
### 使用 Markdown 文件
在`.opencode/modes/`中为项目特定模式创建模式文件，在`~/.config/opencode/modes/`中为全局模式创建模式文件：
在 `.opencode/modes/` 中创建项目特定的模式文件，或在 `~/.config/opencode/modes/` 中创建全局模式文件：
```markdown title=".opencode/modes/debug.md"
---
@@ -318,14 +315,14 @@ Priorities:
---
### 使用案例
### 使用场景
以下是不同模式的一些常见用例。
以下是不同模式的一些常见使用场景。
- **构建模式**：启用所有工具的完整开发工作
- **计划模式**：分析和计划，无需更改
- **审阅模式**：使用只读访问权限和文档工具进行代码审阅
- **调试模式**：专注于启用bash和读取工具的调查
- **文档模式**：使用文件操作但不使用系统命令的文档编写
- **Build 模式**：启用所有工具的完整开发工作
- **Plan 模式**：分析和规划，不做任何更改
- **Review 模式**：使用只读访问权限加文档工具进行代码审查
- **Debug 模式**：启用 bash 和读取工具，专注于问题排查
- **Docs 模式**：支持文件操作但不支持系统命令的文档编写
您可能还会发现不同的模型适用于不同的用例。
你可能还会发现不同的模型适用于不同的使用场景。

20
packages/web/src/content/docs/zh-cn/network.mdx
View File

@@ -3,13 +3,13 @@ title: 网络
description: 配置代理和自定义证书。
---
opencode支持企业网络环境的标准代理环境变量和自定义证书。
OpenCode 支持标准代理环境变量和自定义证书，适用于企业网络环境。
---
## 代理
opencode 遵循标准代理环境变量。
OpenCode 遵循标准代理环境变量。
```bash
# HTTPS proxy (recommended)
@@ -23,35 +23,35 @@ export NO_PROXY=localhost,127.0.0.1
```
:::caution
TUI 与本地 HTTP 服务器通信。您必须绕过此连接的代理以防止路由循环。
TUI 与本地 HTTP 服务器进行通信。你必须为此连接绕过代理，以防止路由循环。
:::
您可以使用[CLI 标志](/docs/cli#run)配置服务器的端口和主机名。
你可以使用 [CLI 标志](/docs/cli#run)来配置服务器的端口和主机名。
---
### 认证
### 身份验证
如果您的代理需要基本身份验证，请在 URL 中包含凭据。
如果你的代理需要基本身份验证，请在 URL 中包含凭据。
```bash
export HTTPS_PROXY=http://username:password@proxy.example.com:8080
```
:::caution
避免对密码进行硬编码。使用环境变量或安全凭证存储。
避免将密码硬编码在代码中。请使用环境变量或安全的凭据存储方式。
:::
对于需要高级身份验证（例如 NTLM 或 Kerberos）的代理，请考虑使用支持您的身份验证方法的 LLM 网关。
对于需要高级身份验证（如 NTLM 或 Kerberos）的代理，建议使用支持相应身份验证方式的 LLM 网关。
---
## 自定义证书
如果您的企业使用自定义 CA 进行 HTTPS 连接，请配置 opencode 以信任它们。
如果你的企业使用自定义 CA 进行 HTTPS 连接，请配置 OpenCode 以信任这些证书。
```bash
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```
这适用于代理连接和直接 API 访问。
此配置同时适用于代理连接和直接 API 访问。

92
packages/web/src/content/docs/zh-cn/permissions.mdx
View File

@@ -1,27 +1,27 @@
---
title: 权限
description: 控制哪些操作需要批准才能运行。
description: 控制哪些操作需要审批才能运行。
---
opencode 使用`permission` 配置来决定给定的操作是否应自动运行、提示您或被阻止。
OpenCode 使用 `permission` 配置来决定某个操作是否应自动运行、提示你审批，还是被阻止。
从 `v1.1.1` 开始，旧版配置 `tools` 布尔已被废弃，并已合并到 `permission` 中。仍支持旧版的 `tools` 配置以实现平滑兼容。
从 `v1.1.1` 开始，旧版 `tools` 布尔配置已被弃用，并已合并到 `permission` 中。旧版 `tools` 配置仍然支持，以保持向后兼容。
---
## 动作
## 操作
每个权限规则解析为以下之一：
每条权限规则解析为以下之一：
- `"allow"` — 尚未批准运行
- `"ask"` — 提示批准
- `"allow"` — 无需审批直接运行
- `"ask"` — 提示审批
- `"deny"` — 阻止该操作
---
## 配置
您可以全局设置权限（使用`*`），并覆盖特定工具。
你可以全局设置权限（使用 `*`），并覆盖特定工具的权限。
```json title="opencode.json"
{
@@ -34,7 +34,7 @@ opencode 使用`permission` 配置来决定给定的操作是否应自动运行
}
```
您还可以一次设置所有权限：
你还可以一次性设置所有权限：
```json title="opencode.json"
{
@@ -45,9 +45,9 @@ opencode 使用`permission` 配置来决定给定的操作是否应自动运行
---
## 粒度规则（对象语法）
## 细粒度规则（对象语法）
对于大多数权限，您可以使用对象根据工具输入应用不同的操作。
对于大多数权限，你可以使用对象来根据工具输入应用不同的操作。
```json title="opencode.json"
{
@@ -68,19 +68,19 @@ opencode 使用`permission` 配置来决定给定的操作是否应自动运行
}
```
规则通过模式匹配进行评估，**最后匹配的规则获胜**。常见的模式是将包罗万象的 `"*"` 规则放在前面，然后再放置更具体的规则。
规则通过模式匹配进行评估，**最后匹配的规则优先**。常见做法是将通配的 `"*"` 规则放在最前面，更具体的规则放在后面。
### 通配符
权限模式使用简单的通配符匹配：
- `*` 匹配零个或多个任意字符
- `?` 恰好匹配一个字符
- 所有其他字符均按字面意思匹配
- `?` 精确匹配一个字符
- 所有其他字符按字面值匹配
### 主目录扩展
### 主目录展开
您可以在模式目录中使用 `~` 或 `$HOME` 来引用您的主目录。这对于 [`外部目录`](#external_directory) 规则特别有用。
你可以在模式开头使用 `~` 或 `$HOME` 来引用你的主目录。这对于 [`external_directory`](#外部目录) 规则特别有用。
- `~/projects/*` -> `/Users/username/projects/*`
- `$HOME/projects/*` -> `/Users/username/projects/*`
@@ -88,11 +88,11 @@ opencode 使用`permission` 配置来决定给定的操作是否应自动运行
### 外部目录
使用 `external_directory` 允许工具调用启动 opencode 的工作目录之外的路径。这适用于任何采用路径作为输入的工具（例如 `read`、`edit`、`list`、`glob`、`grep` 和许多Z`bash` 命令）。
使用 `external_directory` 允许工具调用访问 OpenCode 启动时工作目录之外的路径。这适用于任何接受路径作为输入的工具（例如 `read`、`edit`、`list`、`glob`、`grep` 以及许多 `bash` 命令）。
主扩展（如`~/...`）仅影响模式的编写方式。它不会使外部路径成为当前工作空间的一部分，因此仍然必须通过 `external_directory` 允许工作目录之外的路径。
主目录展开（如 `~/...`）仅影响模式的书写方式。它不会将外部路径纳入当前工作空间，因此工作目录之外的路径仍然必须通过 `external_directory` 来允许。
例如，这允许访问`~/projects/personal/`下的所有内容：
例如，以下配置允许访问 `~/projects/personal/` 下的所有内容：
```json title="opencode.json"
{
@@ -105,7 +105,7 @@ opencode 使用`permission` 配置来决定给定的操作是否应自动运行
}
```
这里允许的任何目录都会继承与当前工作空间默认相同的值。自[`read`默认为`allow`](#defaults)起，也允许读取`external_directory`下面的边界，除非被覆盖。当工具应在这些路径中时添加显式规则，例如在保留读取的同时阻止编辑：
此处允许的任何目录都会继承与当前工作空间相同的默认值。由于 [`read` 默认为 `allow`](#默认值)，`external_directory` 下的条目也允许读取，除非另行覆盖。当需要在这些路径中限制某个工具时，请添加显式规则，例如在保留读取的同时阻止编辑：
```json title="opencode.json"
{
@@ -121,38 +121,38 @@ opencode 使用`permission` 配置来决定给定的操作是否应自动运行
}
```
将列表重点放在受信任的路径上，并根据其他工具的需要分层额外的允许或拒绝规则（例如`bash`）。
请将列表限定在受信任的路径上，并根据需要为其他工具（例如 `bash`）叠加额外的允许或拒绝规则。
---
## 可用权限
opencode权限由工具名称和一些安全防护措施决定：
OpenCode 的权限以工具名称为键，外加几个安全防护项：
- `read` — 读取文件（与文件路径匹配）
- `edit` — 所有文件修改（头部`edit`、`write`、`patch`、`multiedit`）
- `glob` — 文件通配符（匹配通配符模式）
- `read` — 读取文件（匹配文件路径）
- `edit` — 所有文件修改（涵盖 `edit`、`write`、`patch`、`multiedit`）
- `glob` — 文件通配（匹配通配模式）
- `grep` — 内容搜索（匹配正则表达式模式）
- `list` — 列出目录中的文件（与目录路径匹配）
- `bash` — 运行 shell 命令（匹配 `git status --porcelain` 等解析命令）
- `task` — 启动子代理（与子代理类型匹配）
- `skill` — 加载技能（与技能名称匹配）
- `lsp` — 运行 LSP 查询（当前非粒度）
- `list` — 列出目录中的文件（匹配目录路径）
- `bash` — 运行 shell 命令（匹配解析后的命令，如 `git status --porcelain`）
- `task` — 启动子代理（匹配子代理类型）
- `skill` — 加载技能（匹配技能名称）
- `lsp` — 运行 LSP 查询（当前不支持细粒度配置）
- `todoread`、`todowrite` — 读取/更新待办事项列表
- `webfetch` — 获取 URL（与 URL 匹配）
- `websearch`、`codesearch` — 网页/代码搜索（与查询匹配）
- `external_directory` — 当工具访问项目工作目录外部的路径时触发
- `doom_loop` — 当相同的工具调用相同的输入重复 3 次时触发
- `webfetch` — 获取 URL（匹配 URL）
- `websearch`、`codesearch` — 网页/代码搜索（匹配查询内容）
- `external_directory` — 当工具访问项目工作目录之外的路径时触发
- `doom_loop` — 当同一工具调用以相同输入重复 3 次时触发
---
## 默认值
如果您未指定任何内容，opencode将从宽松的默认值开始：
如果你未指定任何配置，OpenCode 将使用宽松的默认值：
- 大部分权限默认为`"allow"`。
- 大多数权限默认为 `"allow"`。
- `doom_loop` 和 `external_directory` 默认为 `"ask"`。
- `read` 是 `"allow"`，但 `.env` 文件默认被拒绝：
- `read` 为 `"allow"`，但 `.env` 文件默认被拒绝：
```json title="opencode.json"
{
@@ -169,24 +169,24 @@ opencode权限由工具名称和一些安全防护措施决定：
---
## “询问”的作用是什么
## "Ask"的作用
当 opencode 提示批准时，UI 会提供三种结果：
当 OpenCode 提示审批时，界面提供三种选择：
- `once` — 仅批准此请求
- `always` — 批准与建议模式匹配的未来请求（对于当前 opencode 会话的其余部分）
- `once` — 仅批准本次请求
- `always` — 批准与建议模式匹配的后续请求（在当前 OpenCode 会话的剩余时间内有效）
- `reject` — 拒绝请求
`always` 将批准的模式集由该工具提供（例如，bash 批准通常将安全端口（如 `git status*`）列入白名单）。
`always` 所批准的模式集合由工具提供（例如，bash 审批通常会将安全的命令前缀如 `git status*` 加入白名单）。
---
## 代理
您可以覆盖每个代理的权限。代理权限与全局​​配置合并，代理规则优先。 [了解更多](/docs/agents#permissions)关于代理权限。
你可以为每个代理单独覆盖权限。代理权限会与全局配置合并，且代理规则优先。[了解更多](/docs/agents#permissions)关于代理权限的内容。
:::note
有关更详细的模式匹配示例，请参见上面的 [粒度规则（对象语法）](#granular-rules-object-syntax) 部分。
有关更详细的模式匹配示例，请参阅上方的[细粒度规则（对象语法）](#细粒度规则对象语法)部分。
:::
```json title="opencode.json"
@@ -217,7 +217,7 @@ opencode权限由工具名称和一些安全防护措施决定：
}
```
您还可以在 Markdown 中配置代理权限：
你还可以在 Markdown 中配置代理权限：
```markdown title="~/.config/opencode/agents/review.md"
---
@@ -233,5 +233,5 @@ Only analyze code and suggest changes.
```
:::tip
对参数的命令使用模式匹配。 `"grep *"` 允许 `grep pattern file.txt`，而 `"grep"` 单独会阻止它。像 `git status` 这样的命令适用于默认行为，但在传递参数时需要显式许可（如 `"git status *"`）。
对带参数的命令使用模式匹配。`"grep *"` 允许执行 `grep pattern file.txt`，而单独的 `"grep"` 则会阻止它。像 `git status` 这样的命令适用于默认行为，但在传递参数时需要显式权限（如 `"git status *"`）。
:::

87
packages/web/src/content/docs/zh-cn/plugins.mdx
View File

@@ -1,21 +1,21 @@
---
title: 插件
description: 编写您自己的插件来扩展 opencode。
description: 编写自己的插件来扩展 OpenCode。
---
插件允许您通过挂钩各种事件和自定义行为来扩展 opencode。您可以创建插件来添加新功能、与外部服务集成或修改 opencode 的默认行为。
插件允许你通过挂钩各种事件和自定义行为来扩展 OpenCode。你可以创建插件来添加新功能、集成外部服务，或修改 OpenCode 的默认行为。
例如，查看社区创建的[插件](/docs/ecosystem#plugins)。
如需了解示例，请查看社区创建的[插件](/docs/ecosystem#plugins)。
---
## 使用插件
有两种加载插件的方法。
有两种方式加载插件。
---
### 从本地文件
### 从本地文件加载
将 JavaScript 或 TypeScript 文件放置在插件目录中。
@@ -26,7 +26,7 @@ description: 编写您自己的插件来扩展 opencode。
---
### 来自 npm
### 从 npm 加载
在配置文件中指定 npm 包。
@@ -37,43 +37,42 @@ description: 编写您自己的插件来扩展 opencode。
}
```
支持常规和范围的 npm 包。
支持常规和带作用域的 npm 包。
浏览[生态系统](/docs/ecosystem#plugins)中的可用插件。
---
### 插件是如何安装的
### 插件的安装方式
**npm 插件** 在启动时使用 Bun 自动安装。包及其依赖项缓存在 `~/.cache/opencode/node_modules/` 中。
**npm 插件**在启动时使用 Bun 自动安装。包及其依赖项会缓存在 `~/.cache/opencode/node_modules/` 中。
**本地插件**直接从插件目录加载。要使用外部包，您必须在配置目录中创建`package.json`（请参阅[依赖关系](#dependencies)），或将插件发布到npm和[将其添加到您的配置中](/docs/config#plugins)。
**本地插件**直接从插件目录加载。如果需要使用外部包，你必须在配置目录中创建 `package.json`（参见[依赖项](#dependencies)），或者将插件发布到 npm 并[将其添加到配置中](/docs/config#plugins)。
---
### 加载顺序
插件从所有源加载，所有挂钩按顺序运行。加载顺序为：
插件从所有来源加载，所有钩子按顺序执行。加载顺序为：
1. 全局配置 (`~/.config/opencode/opencode.json`)
2. 项目配置（`opencode.json`）
3. 插件全局目录 (`~/.config/opencode/plugins/`)
2. 项目配置 (`opencode.json`)
3. 全局插件目录 (`~/.config/opencode/plugins/`)
4. 项目插件目录 (`.opencode/plugins/`)
具有相同的名称和版本，但是重复的 npm 包将被加载一次。，本地插件和名称相似的 npm 插件都是分开加载的。
名称和版本相同的重复 npm 包只会加载一次。但本地插件和名称相似的 npm 插件会分别独立加载。
---
## 创建一个插件
## 创建插件
插件是一个 **JavaScript/TypeScript 模块多个**，它导出一个或插件
功能。每个函数接收一个上下文对象并返回一个钩子对象。
插件是一个 **JavaScript/TypeScript 模块**，它导出一个或多个插件函数。每个函数接收一个上下文对象，并返回一个钩子对象。
---
### 依赖关系
### 依赖项
本地插件和自定义工具可以使用外部 npm 包。将 `package.json` 添加到您的配置目录，其中包含您需要的依赖项。
本地插件和自定义工具可以使用外部 npm 包。在配置目录中添加一个 `package.json`，列出所需的依赖项。
```json title=".opencode/package.json"
{
@@ -83,7 +82,7 @@ description: 编写您自己的插件来扩展 opencode。
}
```
opencode 在启动时运行 `bun install` 来安装这些。然后你的插件和工具就可以导入它们了。
OpenCode 会在启动时运行 `bun install` 来安装这些依赖项。之后你的插件和工具就可以导入它们了。
```ts title=".opencode/plugins/my-plugin.ts"
import { escape } from "shescape"
@@ -113,19 +112,19 @@ export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
}
```
插件函数接收：
插件函数接收以下参数：
- `project`：当前项目信息。
- `directory`：当前工作目录。
- `worktree`：git 工作树路径。
- `client`：用于与AI交互的opencodeSDK客户端。
- `$`：Bun的[外壳API](https://bun.com/docs/runtime/shell)用于执行命令。
- `client`：用于与 AI 交互的 OpenCode SDK 客户端。
- `$`：Bun 的 [Shell API](https://bun.com/docs/runtime/shell)，用于执行命令。
---
### TypeScript 支持
对于 TypeScript 插件，您可以从插件包中导入类型：
对于 TypeScript 插件，你可以从插件包中导入类型：
```ts title="my-plugin.ts" {1}
import type { Plugin } from "@opencode-ai/plugin"
@@ -141,7 +140,7 @@ export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree
### 事件
插件可以订阅事件，如下面的示例部分所示。以下是可用的不同事件的列表。
插件可以订阅事件，如下方示例部分所示。以下是所有可用事件的列表。
#### 命令事件
@@ -211,13 +210,13 @@ export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree
## 示例
以下是一些可用于扩展 opencode 的插件示例。
以下是一些可用于扩展 OpenCode 的插件示例。
---
### 发送通知
当某些事件发生时发送通知：
在特定事件发生时发送通知：
```js title=".opencode/plugins/notification.js"
export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
@@ -232,17 +231,17 @@ export const NotificationPlugin = async ({ project, client, $, directory, worktr
}
```
我们在 macOS 上使用 `osascript` AppleScript。这里我们用它运行来发送通知。
这里使用 `osascript` 在 macOS 上运行 AppleScript 来发送通知。
:::note
如果您使用 opencode 桌面应用程序，它可以在响应准备就绪或会话错误时自动发送系统通知。
如果你使用 OpenCode 桌面应用，它可以在响应就绪或会话出错时自动发送系统通知。
:::
---
### .env 保护
阻止opencode读取`.env`文件：
阻止 OpenCode 读取 `.env` 文件：
```javascript title=".opencode/plugins/env-protection.js"
export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
@@ -260,7 +259,7 @@ export const EnvProtection = async ({ project, client, $, directory, worktree })
### 注入环境变量
将环境变量注入所有shell执行（AI工具和用户终端）：
将环境变量注入所有 Shell 执行（AI 工具和用户终端）：
```javascript title=".opencode/plugins/inject-env.js"
export const InjectEnvPlugin = async () => {
@@ -277,7 +276,7 @@ export const InjectEnvPlugin = async () => {
### 自定义工具
插件还可以向 opencode 添加自定义工具：
插件还可以为 OpenCode 添加自定义工具：
```ts title=".opencode/plugins/custom-tools.ts"
import { type Plugin, tool } from "@opencode-ai/plugin"
@@ -300,19 +299,19 @@ export const CustomToolsPlugin: Plugin = async (ctx) => {
}
```
`tool` 帮助器创建一个可以调用的自定义工具的opencode。它采用 Zod 模式函数并返回一个工具定义：
`tool` 辅助函数用于创建 OpenCode 可调用的自定义工具。它接受一个 Zod schema 函数，并返回一个工具定义，包含：
- `description`：该工具的作用
- `args`：Zod 模式的工具参数
- `execute`：调用工具时运行的函数
- `description`：工具的功能描述
- `args`：工具参数的 Zod schema
- `execute`：工具被调用时执行的函数
您的自定义工具将可与内置工具一起用于opencode。
你的自定义工具将与内置工具一起在 OpenCode 中可用。
---
### 日志
### 日志记录
使用 `client.app.log()` 而不是 `console.log` 进行成型日志记录：
使用 `client.app.log()` 代替 `console.log` 进行结构化日志记录：
```ts title=".opencode/plugins/my-plugin.ts"
export const MyPlugin = async ({ client }) => {
@@ -327,13 +326,13 @@ export const MyPlugin = async ({ client }) => {
}
```
级别：`debug`、`info`、`warn`、`error`。详情请参见【SDK文档](https://opencode.ai/docs/sdk)。
日志级别：`debug`、`info`、`warn`、`error`。详情请参阅 [SDK 文档](https://opencode.ai/docs/sdk)。
---
### 压缩钩子
自定义压缩会话时包含的上下文：
自定义会话压缩时包含的上下文：
```ts title=".opencode/plugins/compaction.ts"
import type { Plugin } from "@opencode-ai/plugin"
@@ -355,9 +354,9 @@ Include any state that should persist across compaction:
}
```
`experimental.session.compacting`钩子在LLM生成驱动机之前触发。使用它来填充默认压缩提示会丢失的特定于域的上下文。
`experimental.session.compacting` 钩子在 LLM 生成续接摘要之前触发。使用它来注入默认压缩提示词可能遗漏的领域特定上下文。
您还可以通过设置`output.prompt`来完全替换压缩提示：
你还可以通过设置 `output.prompt` 来完全替换压缩提示词：
```ts title=".opencode/plugins/custom-compaction.ts"
import type { Plugin } from "@opencode-ai/plugin"
@@ -382,4 +381,4 @@ Format as a structured prompt that a new agent can use to resume work.
}
```
当设置`output.prompt`时，它会取代完全默认的压缩提示。在这种情况下，`output.context` 内存将被忽略。
当设置了 `output.prompt` 时，它会完全替换默认的压缩提示词。在这种情况下，`output.context` 数组将被忽略。

655
packages/web/src/content/docs/zh-cn/providers.mdx
View File

File diff suppressed because it is too large Load Diff

76
packages/web/src/content/docs/zh-cn/rules.mdx
View File

@@ -1,9 +1,9 @@
---
title: 规则
description: 设置opencode的自定义指令。
description: 为 opencode 设置自定义指令。
---
您可以通过 `AGENTS.md` 文件创建 opencode 的自定义指令。这和 Cursor 的规则类似。它包含将包含在 LLM 上下文中的说明，方便您的特定项目自定义其行为。
您可以通过创建 `AGENTS.md` 文件来为 opencode 提供自定义指令。这类似于 Cursor 的规则功能。该文件包含的指令会被纳入 LLM 的上下文中，以便针对您的特定项目自定义其行为。
---
@@ -15,15 +15,15 @@ description: 设置opencode的自定义指令。
您应该将项目的 `AGENTS.md` 文件提交到 Git。
:::
这将扫描您的项目及其所有内容，以了解该项目的内容并生成一个 `AGENTS.md` 文件。这有助于更好地打开代码导航项目。
该命令会扫描您的项目及其所有内容，了解项目的用途，并据此生成一个 `AGENTS.md` 文件。这有助于 opencode 更好地导航您的项目。
如果您已有现有的 `AGENTS.md` 文件，将尝试添加到其中。
如果您已有 `AGENTS.md` 文件，该命令会尝试在其基础上进行补充。
---
## 例子
## 示例
您也可以手动创建此文件。以下是您可以导入 `AGENTS.md` 文件中的一些内容的示例。
您也可以手动创建此文件。以下是一些可以放入 `AGENTS.md` 文件中的内容示例。
```markdown title="AGENTS.md"
# SST v3 Monorepo Project
@@ -48,33 +48,33 @@ This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for
- Import shared modules using workspace names: `@my-app/core/example`
```
我们在此处添加特定于项目的说明，这将在您的团队中共享。
我们在这里添加了项目特定的指令，这些指令会在您的团队中共享。
---
## 类型
opencode 还支持从多个位置读取 `AGENTS.md` 文件。这有不同的目的。
opencode 还支持从多个位置读取 `AGENTS.md` 文件，不同的位置有不同的用途。
### 项目
### 项目级
将 `AGENTS.md` 放置在项目根目录中以获取特定于项目的规则。这些仅适用于您在此目录或子目录中工作时。
在项目根目录放置一个 `AGENTS.md` 文件，用于定义项目特定的规则。这些规则仅在您在该目录或其子目录中工作时生效。
### 全局
### 全局级
您还可以在 `~/.config/opencode/AGENTS.md` 文件中包含全局规则。这适用于所有opencode会话。
您还可以在 `~/.config/opencode/AGENTS.md` 文件中设置全局规则。这些规则会应用于所有 opencode 会话。
由于此未提交给 Git 或与您的团队共享，因此我们建议使用它来指定 LLM 应遵循的任何个人规则。
由于该文件不会被提交到 Git 或与团队共享，我们建议用它来指定 LLM 应遵循的个人规则。
### 克劳德代码兼容性
### Claude Code 兼容性
Error 500 (Server Error)!!1500.That’s an error.There was an error. Please try again later.That’s all we know.
对于从 Claude Code 迁移过来的用户，OpenCode 支持 Claude Code 的文件约定作为回退方案：
- **项目规则**：项目目录中的`CLAUDE.md`（如果`AGENTS.md`不存在则使用）
- **全局规则**：`~/.claude/CLAUDE.md`（如果不存在`~/.config/opencode/AGENTS.md`则使用）
- **技能**：`~/.claude/skills/` — 详情请参见[代理技巧](/docs/skills/)
- **项目规则**：项目目录中的 `CLAUDE.md`（在没有 `AGENTS.md` 的情况下使用）
- **全局规则**：`~/.claude/CLAUDE.md`（在没有 `~/.config/opencode/AGENTS.md` 的情况下使用）
- **技能**：`~/.claude/skills/` — 详情请参阅[代理技能](/docs/skills/)
要取消Claude Code兼容性，请设置以下环境变量之一：
要禁用 Claude Code 兼容性，请设置以下环境变量之一：
```bash
export OPENCODE_DISABLE_CLAUDE_CODE=1 # Disable all .claude support
@@ -88,19 +88,19 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
当 opencode 启动时，它会按以下顺序查找规则文件：
1. **本地文件**，从当前目录向上浏览(`AGENTS.md`,`CLAUDE.md`)
2. **全局文件** `~/.config/opencode/AGENTS.md`
3. **克劳德代码文件**位于`~/.claude/CLAUDE.md`（禁用禁用）
1. **本地文件**，从当前目录向上遍历（`AGENTS.md`、`CLAUDE.md`）
2. **全局文件**，位于 `~/.config/opencode/AGENTS.md`
3. **Claude Code 文件**，位于 `~/.claude/CLAUDE.md`（除非已禁用）
第一个匹配的文件每个在类别中触发。例如，如果您同时拥有`AGENTS.md`和`CLAUDE.md`，则仅使用`AGENTS.md`。同样，`~/.config/opencode/AGENTS.md`优先于`~/.claude/CLAUDE.md`。
在每个类别中，第一个匹配的文件优先。例如，如果您同时拥有 `AGENTS.md` 和 `CLAUDE.md`，则只会使用 `AGENTS.md`。同样，`~/.config/opencode/AGENTS.md` 优先于 `~/.claude/CLAUDE.md`。
---
## 自定义指令
您可以在 `opencode.json` 或全局 `~/.config/opencode/opencode.json` 中指定自定义指令文件。这允许您和您的团队重用现有规则，而不必将它们复制到 AGENTS.md。
您可以在 `opencode.json` 或全局配置文件 `~/.config/opencode/opencode.json` 中指定自定义指令文件。这允许您和团队复用现有规则，而无需将它们复制到 AGENTS.md 中。
例子：
示例：
```json title="opencode.json"
{
@@ -109,7 +109,7 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
}
```
您还可以使用远程URL从Web加载说明。
您还可以使用远程 URL 从网络加载指令。
```json title="opencode.json"
{
@@ -118,19 +118,19 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
}
```
远程指令的获取有 5 秒的超时时间。
远程指令的获取超时时间为 5 秒。
所有说明文件均与您的`AGENTS.md`文件合并。
所有指令文件都会与您的 `AGENTS.md` 文件合并。
---
## 引用外部文件
虽然opencode不会自动解析`AGENTS.md`中的文件引用，但您可以通过两种方式实现类似的功能：
虽然 opencode 不会自动解析 `AGENTS.md` 中的文件引用，但您可以通过以下两种方式实现类似的功能：
### 使用 opencode.json
推荐的方法是在`instructions`中使用`opencode.json`字段：
推荐的方式是使用 `opencode.json` 中的 `instructions` 字段：
```json title="opencode.json"
{
@@ -139,9 +139,9 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
}
```
### AGENTS.md 中的手册说明
### 在 AGENTS.md 中手动指定
您可以通过在 `AGENTS.md` 中明确提供的指令来教 opencode 读取外部文件。这是一个实际的示例：
您可以在 `AGENTS.md` 中提供明确的指令，教 opencode 读取外部文件。以下是一个实际示例：
```markdown title="AGENTS.md"
# TypeScript Project Rules
@@ -168,13 +168,13 @@ For testing strategies and coverage requirements: @test/testing-guidelines.md
Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.
```
这种方法允许您：
这种方式允许您：
- 创建模块化、可重用的规则文件
- 通过符号链接或git子模块在项目之间共享规则
- 保持 AGENTS.md 简洁，同时参考详细指南
- 确保opencode仅在特定任务需要时加载文件
- 创建模块化、可复用的规则文件
- 通过符号链接或 Git 子模块在项目之间共享规则
- 保持 AGENTS.md 简洁，同时引用详细的指南
- 确保 opencode 仅在特定任务需要时才加载文件
:::tip
对于 monorepos 或具有共享标准的项目，使用 `opencode.json` 和 glob 模式（如 `packages/*/AGENTS.md`）比手动指令更易于维护。
对于 monorepo 或具有共享标准的项目，使用 `opencode.json` 配合 glob 模式（如 `packages/*/AGENTS.md`）比手动指定指令更易于维护。
:::

256
packages/web/src/content/docs/zh-cn/sdk.mdx
View File

@@ -1,15 +1,15 @@
---
title: SDK
description: opencode 服务器的类型不同于安全 JS 客户端。
description: opencode 服务器的类型安全 JS 客户端。
---
import config from "../../../../config.mjs"
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
opencode JS/TS SDK 提供类型其他安全的客户端用于与服务器交互。
使用它以程序设计方式构建集成和控制opencode。
opencode JS/TS SDK 提供了一个类型安全的客户端，用于与服务器进行交互。
你可以用它来构建集成方案，并以编程方式控制 opencode。
[了解更多关于服务器如何工作的](/docs/server)。例如，查看社区构建的[projects](/docs/ecosystem#projects)。
[了解更多](/docs/server)关于服务器的工作原理。如需示例，请查看社区构建的[项目](/docs/ecosystem#projects)。
---
@@ -25,7 +25,7 @@ npm install @opencode-ai/sdk
## 创建客户端
创建opencode的示例项：
创建一个 opencode 实例：
```javascript
import { createOpencode } from "@opencode-ai/sdk"
@@ -33,23 +33,23 @@ import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()
```
这会同时启动服务器和客户端
这会同时启动服务器和客户端。
#### 选项
| 选项 | 型别 | 描述 | 默认 |
| ---------- | ------------- | ------------------------------ | ----------- |
| 选项 | 类型 | 描述 | 默认值 |
| ---------- | ------------- | -------------------------- | ----------- |
| `hostname` | `string` | 服务器主机名 | `127.0.0.1` |
| `port` | `number` | 服务器埠 | `4096` |
| `signal` | `AbortSignal` | 取消的中止讯号 | `undefined` |
| `timeout` | `number` | 服务器启动超时（以毫秒为单位） | `5000` |
| `config` | `Config` | 放置的财产 | `{}` |
| `port` | `number` | 服务器端口 | `4096` |
| `signal` | `AbortSignal` | 用于取消操作的中止信号 | `undefined` |
| `timeout` | `number` | 服务器启动超时时间（毫秒） | `5000` |
| `config` | `Config` | 配置对象 | `{}` |
---
## 配置
You can pass a configuration object to customize behavior. The instance still picks up your `opencode.json`, but you can override or add configuration inline:
你可以传入一个配置对象来自定义行为。实例仍然会读取你的 `opencode.json`，但你可以通过内联方式覆盖或添加配置：
```javascript
import { createOpencode } from "@opencode-ai/sdk"
@@ -67,9 +67,9 @@ console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()
```
## 仅限客户端
## 仅客户端模式
如果您已经有 opencode 的正在执行示例项，则可以创建一个客户端示例项来连线到它：
如果你已经有一个正在运行的 opencode 实例，可以创建一个客户端实例来连接它：
```javascript
import { createOpencodeClient } from "@opencode-ai/sdk"
@@ -81,31 +81,31 @@ const client = createOpencodeClient({
#### 选项
| 选项 | 型别 | 描述 | 默认 |
| 选项 | 类型 | 描述 | 默认值 |
| --------------- | ---------- | ---------------------------- | ----------------------- |
| `baseUrl` | `string` | 服务器的 URL | `http://localhost:4096` |
| `fetch` | `function` | 习俗获取实现 | `globalThis.fetch` |
| `parseAs` | `string` | 响应解析方法 | `auto` |
| `responseStyle` | `string` | 返回样式：`data` 或 `fields` | `fields` |
| `throwOnError` | `boolean` | 掷骰错误而不是返回 | `false` |
| `baseUrl` | `string` | 服务器 URL | `http://localhost:4096` |
| `fetch` | `function` | 自定义 fetch 实现 | `globalThis.fetch` |
| `parseAs` | `string` | 响应解析方式 | `auto` |
| `responseStyle` | `string` | 返回风格：`data` 或 `fields` | `fields` |
| `throwOnError` | `boolean` | 抛出错误而非返回错误 | `false` |
---
## 类型
SDK 包括所有 API 型以外的 TypeScript 定义。直接汇入其中：
SDK 包含所有 API 类型的 TypeScript 定义。你可以直接导入它们：
```typescript
import type { Session, Message, Part } from "@opencode-ai/sdk"
```
所有型别均根据服务器的 OpenAPI 规范生成，并可在 <a href={typesUrl}> 型别文件 </a> 中找到。
所有类型均根据服务器的 OpenAPI 规范生成，可在<a href={typesUrl}>类型文件</a>中查看。
---
## 错误
## 错误处理
SDK 可能会丢掷错误，您可以捕获并处理这些错误：
SDK 可能会抛出错误，你可以捕获并处理这些错误：
```typescript
try {
@@ -117,17 +117,89 @@ try {
---
## API
## 结构化输出
SDK跨越型别安全客户端公开所有服务器API。
你可以通过指定带有 JSON Schema 的 `format` 来请求模型返回结构化的 JSON 输出。模型会使用 `StructuredOutput` 工具返回符合你 Schema 的经过验证的 JSON。
### 基本用法
```typescript
const result = await client.session.prompt({
path: { id: sessionId },
body: {
parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
format: {
type: "json_schema",
schema: {
type: "object",
properties: {
company: { type: "string", description: "Company name" },
founded: { type: "number", description: "Year founded" },
products: {
type: "array",
items: { type: "string" },
description: "Main products",
},
},
required: ["company", "founded"],
},
},
},
})
// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }
```
### 输出格式类型
| 类型 | 描述 |
| ------------- | --------------------------------------- |
| `text` | 默认值。标准文本响应（无结构化输出） |
| `json_schema` | 返回符合所提供 Schema 的经过验证的 JSON |
### JSON Schema 格式
使用 `type: 'json_schema'` 时，需提供以下字段：
| 字段 | 类型 | 描述 |
| ------------ | --------------- | ------------------------------------- |
| `type` | `'json_schema'` | 必填。指定 JSON Schema 模式 |
| `schema` | `object` | 必填。定义输出结构的 JSON Schema 对象 |
| `retryCount` | `number` | 可选。验证重试次数（默认值：2） |
### 错误处理
如果模型在所有重试后仍无法生成有效的结构化输出，响应中会包含 `StructuredOutputError`：
```typescript
if (result.data.info.error?.name === "StructuredOutputError") {
console.error("Failed to produce structured output:", result.data.info.error.message)
console.error("Attempts:", result.data.info.error.retries)
}
```
### 最佳实践
1. **在 Schema 属性中提供清晰的描述**，帮助模型理解需要提取的数据
2. **使用 `required`** 指定哪些字段必须存在
3. **保持 Schema 简洁** — 复杂的嵌套 Schema 可能会让模型更难正确填充
4. **设置合适的 `retryCount`** — 对于复杂 Schema 可增加重试次数，对于简单 Schema 可减少
---
### 全局
## API
| 方法 | 描述 | 回应 |
SDK 通过类型安全的客户端暴露所有服务器 API。
---
### Global
| 方法 | 描述 | 响应 |
| ----------------- | ------------------------ | ------------------------------------ |
| `global.health()` | 检查服务器健康状况和版本 | `{ healthy: true, version: string }` |
| `global.health()` | 检查服务器健康状态和版本 | `{ healthy: true, version: string }` |
---
@@ -140,12 +212,12 @@ console.log(health.data.version)
---
### 应用程序
### App
| 方法 | 描述 | 回应 |
| -------------- | ------------------ | ------------------------------------------ |
| `app.log()` | 登录日志 | `boolean` |
| `app.agents()` | 列出所有可用的代理 | <a href={typesUrl}><code>代理[]</code></a> |
| 方法 | 描述 | 响应 |
| -------------- | ------------------ | ------------------------------------------- |
| `app.log()` | 写入一条日志 | `boolean` |
| `app.agents()` | 列出所有可用的代理 | <a href={typesUrl}><code>Agent[]</code></a> |
---
@@ -167,12 +239,12 @@ const agents = await client.app.agents()
---
### 项目
### Project
| 方法 | 描述 | 回应 |
| ------------------- | ------------ | ------------------------------------------ |
| `project.list()` | 列出所有专案 | <a href={typesUrl}><code>专案[]</code></a> |
| `project.current()` | 获取当前专案 | <a href={typesUrl}><code>专案</code></a> |
| 方法 | 描述 | 响应 |
| ------------------- | ------------ | --------------------------------------------- |
| `project.list()` | 列出所有项目 | <a href={typesUrl}><code>Project[]</code></a> |
| `project.current()` | 获取当前项目 | <a href={typesUrl}><code>Project</code></a> |
---
@@ -188,11 +260,11 @@ const currentProject = await client.project.current()
---
### 路径
### Path
| 方法 | 描述 | 回应 |
| 方法 | 描述 | 响应 |
| ------------ | ------------ | ---------------------------------------- |
| `path.get()` | 获取当前路径 | <a href={typesUrl}><code>路径</code></a> |
| `path.get()` | 获取当前路径 | <a href={typesUrl}><code>Path</code></a> |
---
@@ -205,12 +277,12 @@ const pathInfo = await client.path.get()
---
### 配置
### Config
| 方法 | 描述 | 回应 |
| -------------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
| `config.get()` | 获取配置资讯 | <a href={typesUrl}><code>配置</code></a> |
| `config.providers()` | 列出提供商和默认模型 | `{ providers: `<a href={typesUrl}><code>提供商[]</code></a>`, default: { [key: string]: string } }` |
| 方法 | 描述 | 响应 |
| -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
| `config.get()` | 获取配置信息 | <a href={typesUrl}><code>Config</code></a> |
| `config.providers()` | 列出提供商和默认模型 | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
---
@@ -224,29 +296,29 @@ const { providers, default: defaults } = await client.config.providers()
---
### 会话
### Sessions
| 方法 | 描述 | 备注 |
| ---------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| ---------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session.list()` | 列出会话 | 返回 <a href={typesUrl}><code>Session[]</code></a> |
| `session.get({ path })` | 获取会话 | 返回 <a href={typesUrl}><code>会话</code></a> |
| `session.get({ path })` | 获取会话 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.children({ path })` | 列出子会话 | 返回 <a href={typesUrl}><code>Session[]</code></a> |
| `session.create({ body })` | 建立会话 | 返回 <a href={typesUrl}><code>会话</code></a> |
| `session.delete({ path })` | 离开会话 | 返回`boolean` |
| `session.update({ path, body })` | 更新会话属性 | 返回 <a href={typesUrl}><code>会话</code></a> |
| `session.init({ path, body })` | Analyze app and create `AGENTS.md` | Returns `boolean` |
| `session.abort({ path })` | 中止正在执行的会话 | 返回`boolean` |
| `session.share({ path })` | 分享会 | 返回 <a href={typesUrl}><code>会话</code></a> |
| `session.unshare({ path })` | 取消共享会话 | 返回 <a href={typesUrl}><code>会话</code></a> |
| `session.summarize({ path, body })` | 会议总结 | 返回`boolean` |
| `session.messages({ path })` | 列出会话中的消息 | 返回 `{ info: `<a href={typesUrl}><code>消息</code></a>`, parts: `<a href={typesUrl}><code>部分[]</code></a>`}[]` |
| `session.message({ path })` | 获取消息详情 | 返回 `{ info: `<a href={typesUrl}><code>消息</code></a>`, parts: `<a href={typesUrl}><code>部分[]</code></a>`}` |
| `session.prompt({ path, body })` | 发送提示资讯 | `body.noReply: true` 返回 UserMessage（仅限上下文）。默认返回 <a href={typesUrl}><code>AssistantMessage</code></a> 以及 AI 响应 |
| `session.command({ path, body })` | 向会话发送命令 | 返回 `{ info: `<a href={typesUrl}><code>AssistantMessage</code></a>`, parts: `<a href={typesUrl}><code>部分[]</code></a>`}` |
| `session.create({ body })` | 创建会话 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.delete({ path })` | 删除会话 | 返回 `boolean` |
| `session.update({ path, body })` | 更新会话属性 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.init({ path, body })` | 分析应用并创建 `AGENTS.md` | 返回 `boolean` |
| `session.abort({ path })` | 中止正在运行的会话 | 返回 `boolean` |
| `session.share({ path })` | 分享会话 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.unshare({ path })` | 取消分享会话 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.summarize({ path, body })` | 总结会话 | 返回 `boolean` |
| `session.messages({ path })` | 列出会话中的消息 | 返回 `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]` |
| `session.message({ path })` | 获取消息详情 | 返回 `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
| `session.prompt({ path, body })` | 发送提示词消息 | `body.noReply: true` 返回 UserMessage（仅注入上下文）。默认返回带有 AI 响应的 <a href={typesUrl}><code>AssistantMessage</code></a>。支持通过 `body.outputFormat` 使用[结构化输出](#结构化输出) |
| `session.command({ path, body })` | 向会话发送命令 | 返回 `{ info: `<a href={typesUrl}><code>AssistantMessage</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
| `session.shell({ path, body })` | 执行 shell 命令 | 返回 <a href={typesUrl}><code>AssistantMessage</code></a> |
| `session.revert({ path, body })` | 回复消息 | 返回 <a href={typesUrl}><code>会话</code></a> |
| `session.unrevert({ path })` | 恢复已恢复的消息 | 返回 <a href={typesUrl}><code>会话</code></a> |
| `postSessionByIdPermissionsByPermissionId({ path, body })` | 回复许可权限请求 | 返回`boolean` |
| `session.revert({ path, body })` | 撤回消息 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.unrevert({ path })` | 恢复已撤回的消息 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `postSessionByIdPermissionsByPermissionId({ path, body })` | 响应权限请求 | 返回 `boolean` |
---
@@ -281,21 +353,21 @@ await client.session.prompt({
---
### 文件
### Files
| 方法 | 描述 | 回应 |
| 方法 | 描述 | 响应 |
| ------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
| `find.text({ query })` | 搜索档案中文字 | 具有 `path`、`lines`、`line_number`、`absolute_offset`、`submatches` 的匹配对象数组 |
| `find.files({ query })` | 按名称查询档案和目录 | `string[]`（路径） |
| `find.symbols({ query })` | 查询工作区符号 | <a href={typesUrl}><code>符号[]</code></a> |
| `file.read({ query })` | 读取档案 | `{ type: "raw" \| "patch", content: string }` |
| `file.status({ query? })` | 获取跟踪文件的状态 | <a href={typesUrl}><code>文件[]</code></a> |
| `find.text({ query })` | 搜索文件中的文本 | 包含 `path`、`lines`、`line_number`、`absolute_offset`、`submatches` 的匹配对象数组 |
| `find.files({ query })` | 按名称查找文件和目录 | `string[]`（路径） |
| `find.symbols({ query })` | 查找工作区符号 | <a href={typesUrl}><code>Symbol[]</code></a> |
| `file.read({ query })` | 读取文件 | `{ type: "raw" \| "patch", content: string }` |
| `file.status({ query? })` | 获取已跟踪文件的状态 | <a href={typesUrl}><code>File[]</code></a> |
`find.files` 支持一些可选的查询栏位：
`find.files` 支持以下可选查询字段：
- `type`：`"file"` 或 `"directory"`
- `directory`：覆盖搜索的专案根目录
- `limit`：最大结果 (1–200)
- `directory`：覆盖搜索的项目根目录
- `limit`：最大结果数（1–200）
---
@@ -324,17 +396,17 @@ const content = await client.file.read({
### TUI
| 方法 | 描述 | 回应 |
| 方法 | 描述 | 响应 |
| ------------------------------ | ---------------- | --------- |
| `tui.appendPrompt({ body })` | 将文字附加到提示 | `boolean` |
| `tui.openHelp()` | 开启帮助对话方块 | `boolean` |
| `tui.openSessions()` | 开启会话选择器 | `boolean` |
| `tui.openThemes()` | 开启主题选择器 | `boolean` |
| `tui.openModels()` | 开启模型选择器 | `boolean` |
| `tui.submitPrompt()` | 提交当前提示 | `boolean` |
| `tui.clearPrompt()` | 清除提示 | `boolean` |
| `tui.appendPrompt({ body })` | 向提示词追加文本 | `boolean` |
| `tui.openHelp()` | 打开帮助对话框 | `boolean` |
| `tui.openSessions()` | 打开会话选择器 | `boolean` |
| `tui.openThemes()` | 打开主题选择器 | `boolean` |
| `tui.openModels()` | 打开模型选择器 | `boolean` |
| `tui.submitPrompt()` | 提交当前提示词 | `boolean` |
| `tui.clearPrompt()` | 清除提示词 | `boolean` |
| `tui.executeCommand({ body })` | 执行命令 | `boolean` |
| `tui.showToast({ body })` | 显示吐司通知 | `boolean` |
| `tui.showToast({ body })` | 显示 Toast 通知 | `boolean` |
---
@@ -353,11 +425,11 @@ await client.tui.showToast({
---
### 授权
### Auth
| 方法 | 描述 | 回应 |
| ------------------- | ---------------- | --------- |
| `auth.set({ ... })` | 设定身份验证凭据 | `boolean` |
| 方法 | 描述 | 响应 |
| ------------------- | ------------ | --------- |
| `auth.set({ ... })` | 设置认证凭据 | `boolean` |
---
@@ -372,11 +444,11 @@ await client.auth.set({
---
### 事件
### Events
| 方法 | 描述 | 回应 |
| 方法 | 描述 | 响应 |
| ------------------- | ------------------ | ------------------ |
| `event.subscribe()` | 服务器传送的事件流 | 服务器传送的事件流 |
| `event.subscribe()` | 服务器发送的事件流 | 服务器发送的事件流 |
---

249
packages/web/src/content/docs/zh-cn/server.mdx
View File

@@ -6,7 +6,7 @@ description: 通过 HTTP 与 opencode 服务器交互。
import config from "../../../../config.mjs"
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
The `opencode serve` command runs a headless HTTP server that exposes an OpenAPI endpoint that an opencode client can use.
`opencode serve` 命令运行一个无界面的 HTTP 服务器，暴露一个 OpenAPI 端点供 opencode 客户端使用。
---
@@ -18,15 +18,15 @@ opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
#### 选项
| 标志 | 描述 | 默认 |
| --------------- | ----------------------------------- | ---------------- |
| `--port` | 监听音频 | `4096` |
| 标志 | 描述 | 默认值 |
| --------------- | --------------------- | ---------------- |
| `--port` | 监听端口 | `4096` |
| `--hostname` | 监听的主机名 | `127.0.0.1` |
| `--mdns` | 启用 mDNS 发现 | `false` |
| `--mdns-domain` | Custom domain name for mDNS service | `opencode.local` |
| `--cors` | 允许的其他浏览器来源 | `[]` |
| `--mdns-domain` | mDNS 服务的自定义域名 | `opencode.local` |
| `--cors` | 额外允许的浏览器来源 | `[]` |
`--cors` 可以多次交付：
`--cors` 可以多次传递：
```bash
opencode serve --cors http://localhost:5173 --cors https://app.example.com
@@ -34,9 +34,9 @@ opencode serve --cors http://localhost:5173 --cors https://app.example.com
---
### 验证
### 认证
Set `OPENCODE_SERVER_PASSWORD` to protect the server with HTTP basic auth. The username defaults to `opencode`, or set `OPENCODE_SERVER_USERNAME` to override it. This applies to both `opencode serve` and `opencode web`.
设置 `OPENCODE_SERVER_PASSWORD` 以使用 HTTP 基本认证保护服务器。用户名默认为 `opencode`，也可以设置 `OPENCODE_SERVER_USERNAME` 来覆盖它。这适用于 `opencode serve` 和 `opencode web`。
```bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve
@@ -44,100 +44,97 @@ OPENCODE_SERVER_PASSWORD=your-password opencode serve
---
### 它是如何运作的
### 工作原理
When you run `opencode` it starts a TUI and a server. Where the TUI is the
与服务器器对话的客户端。服务器器公开 OpenAPI 3.1 规范
该端点还用于生成 [SDK](/docs/sdk)。
当你运行 `opencode` 时，它会启动一个 TUI 和一个服务器。TUI 是与服务器通信的客户端。服务器暴露一个 OpenAPI 3.1 规范端点。该端点也用于生成 [SDK](/docs/sdk)。
:::tip
使用opencode服务器以程序设计方式与opencode交互。
使用 opencode 服务器以编程方式与 opencode 交互。
:::
该架构让 opencode 支持客户端，并允许您以多种设计方式与 opencode 交互。
这种架构让 opencode 支持多个客户端，并允许你以编程方式与 opencode 交互。
You can run `opencode serve` to start a standalone server. If you have the
opencode TUI running, `opencode serve` will start a new server.
你可以运行 `opencode serve` 来启动一个独立的服务器。如果你已经在运行 opencode TUI，`opencode serve` 会启动一个新的服务器。
---
#### 连接到现有服务器
当您启动 TUI 时，它会随机分配端口和主机名。您可以重新设置 `--hostname` 和 `--port` [flags](/docs/cli)。使用它连线到其服务器然后器。
当你启动 TUI 时，它会随机分配端口和主机名。你也可以传入 `--hostname` 和 `--port` [标志](/docs/cli)，然后用它来连接对应的服务器。
[**_T2_**](#tui) 端点可用于跨境服务器驱动 TUI。例如，您可以预填充或执行提示。此设置由 opencode [IDE](/docs/ide) 外挂使用。
[`/tui`](#tui) 端点可用于通过服务器驱动 TUI。例如，你可以预填充或运行一个提示词。此方式被 OpenCode [IDE](/docs/ide) 插件所使用。
---
## 规格
## 规范
服务器发布了OpenAPI 3.1规范，可以在以下位置查看：
服务器发布了一个 OpenAPI 3.1 规范，可在以下地址查看：
```
http://<hostname>:<port>/doc
```
例如，`http://localhost:4096/doc`。使用规范生成客户端或检查请求和响应类型其他。或者在 Swagger 浏览器中查看它。
例如，`http://localhost:4096/doc`。使用该规范可以生成客户端或检查请求和响应类型，也可以在 Swagger 浏览器中查看。
---
## API
opencode服务器公开以下API。
opencode 服务器暴露以下 API。
---
### 全局
| 方法 | 路径 | 描述 | 回应 |
| 方法 | 路径 | 描述 | 响应 |
| ----- | ---------------- | ------------------------ | ------------------------------------ |
| `GET` | `/global/health` | 获取服务器运行状况和版本 | `{ healthy: true, version: string }` |
| `GET` | `/global/event` | 获取全域性事件（SSE 流） | 事件流 |
| `GET` | `/global/health` | 获取服务器健康状态和版本 | `{ healthy: true, version: string }` |
| `GET` | `/global/event` | 获取全局事件（SSE 流） | 事件流 |
---
### 项目
| 方法 | 路径 | 描述 | 回应 |
| ----- | ------------------ | ------------ | ------------------------------------------ |
| `GET` | `/project` | 列出所有专案 | <a href={typesUrl}><code>专案[]</code></a> |
| `GET` | `/project/current` | 获取当前专案 | <a href={typesUrl}><code>专案</code></a> |
| 方法 | 路径 | 描述 | 响应 |
| ----- | ------------------ | ------------ | --------------------------------------------- |
| `GET` | `/project` | 列出所有项目 | <a href={typesUrl}><code>Project[]</code></a> |
| `GET` | `/project/current` | 获取当前项目 | <a href={typesUrl}><code>Project</code></a> |
---
### 路径和 VCS
| 方法 | 路径 | 描述 | 回应 |
| 方法 | 路径 | 描述 | 响应 |
| ----- | ------- | ----------------------- | ------------------------------------------- |
| `GET` | `/path` | 获取当前路径 | <a href={typesUrl}><code>路径</code></a> |
| `GET` | `/vcs` | 获取当前专案的 VCS 资讯 | <a href={typesUrl}><code>VcsInfo</code></a> |
| `GET` | `/path` | 获取当前路径 | <a href={typesUrl}><code>Path</code></a> |
| `GET` | `/vcs` | 获取当前项目的 VCS 信息 | <a href={typesUrl}><code>VcsInfo</code></a> |
---
### 例项
### 实例
| 方法 | 路径 | 描述 | 回应 |
| ------ | ------------------- | -------------- | --------- |
| `POST` | `/instance/dispose` | 执行当前实例项 | `boolean` |
| 方法 | 路径 | 描述 | 响应 |
| ------ | ------------------- | ------------ | --------- |
| `POST` | `/instance/dispose` | 销毁当前实例 | `boolean` |
---
### 配置
| 方法 | 路径 | 描述 | 回应 |
| ------- | ------------------- | -------------------- | -------------------------------------------------------------------------------------- |
| `GET` | `/config` | 获取配置资讯 | <a href={typesUrl}><code>配置</code></a> |
| `PATCH` | `/config` | 更新配置 | <a href={typesUrl}><code>配置</code></a> |
| `GET` | `/config/providers` | 列出提供商和默认模型 | `{ providers: `<a href={typesUrl}>提供商[]</a>`, default: { [key: string]: string } }` |
| 方法 | 路径 | 描述 | 响应 |
| ------- | ------------------- | -------------------- | ---------------------------------------------------------------------------------------- |
| `GET` | `/config` | 获取配置信息 | <a href={typesUrl}><code>Config</code></a> |
| `PATCH` | `/config` | 更新配置 | <a href={typesUrl}><code>Config</code></a> |
| `GET` | `/config/providers` | 列出提供商和默认模型 | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
---
### 提供商
| 方法 | 路径 | 描述 | 回应 |
| ------ | -------------------------------- | ----------------------- | --------------------------------------------------------------------------------- |
| `GET` | `/provider` | 列出所有提供商 | `{ all: `<a href={typesUrl}>提供商[]</a>`, default: {...}, connected: string[] }` |
| `GET` | `/provider/auth` | 获取提供商身份验证方法 | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` |
| 方法 | 路径 | 描述 | 响应 |
| ------ | -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- |
| `GET` | `/provider` | 列出所有提供商 | `{ all: `<a href={typesUrl}>Provider[]</a>`, default: {...}, connected: string[] }` |
| `GET` | `/provider/auth` | 获取提供商认证方式 | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` |
| `POST` | `/provider/{id}/oauth/authorize` | 使用 OAuth 授权提供商 | <a href={typesUrl}><code>ProviderAuthAuthorization</code></a> |
| `POST` | `/provider/{id}/oauth/callback` | 处理提供商的 OAuth 回调 | `boolean` |
@@ -145,143 +142,143 @@ opencode服务器公开以下API。
### 会话
| 方法 | 路径 | 描述 | 笔记 |
| -------- | ---------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------- |
| 方法 | 路径 | 描述 | 说明 |
| -------- | ---------------------------------------- | -------------------------- | --------------------------------------------------------------------------------- |
| `GET` | `/session` | 列出所有会话 | 返回 <a href={typesUrl}><code>Session[]</code></a> |
| `POST` | `/session` | 建立新会话 | 正文： `{ parentID?, title? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/status` | 获取所有会话的会话状态 | 返回 `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` |
| `GET` | `/session/:id` | 获取会话详细信息 | 返回<a href={typesUrl}><code>会话</code></a> |
| `DELETE` | `/session/:id` | 删除会话及所有资料 | 返回`boolean` |
| `PATCH` | `/session/:id` | 更新会话属性 | 正文： `{ title? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `POST` | `/session` | 创建新会话 | 请求体：`{ parentID?, title? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/status` | 获取所有会话的状态 | 返回 `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` |
| `GET` | `/session/:id` | 获取会话详情 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `DELETE` | `/session/:id` | 删除会话及其所有数据 | 返回 `boolean` |
| `PATCH` | `/session/:id` | 更新会话属性 | 请求体：`{ title? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/children` | 获取会话的子会话 | 返回 <a href={typesUrl}><code>Session[]</code></a> |
| `GET` | `/session/:id/todo` | 获取会话的待办事项列表 | 返回 <a href={typesUrl}><code>Todo[]</code></a> |
| `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }`, returns `boolean` |
| `POST` | `/session/:id/fork` | 在消息中分叉现有会话 | 正文： `{ messageID? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `POST` | `/session/:id/abort` | 中止正在执行的会话 | 返回`boolean` |
| `POST` | `/session/:id/share` | 分享会话 | 返回<a href={typesUrl}><code>会话</code></a> |
| `DELETE` | `/session/:id/share` | 取消共享会话 | 返回<a href={typesUrl}><code>会话</code></a> |
| `GET` | `/session/:id/diff` | 获取本次会话的差异 | 查询：`messageID?`，返回 <a href={typesUrl}><code>FileDiff[]</code></a> |
| `POST` | `/session/:id/summarize` | 会议总结 | 正文：`{ providerID, modelID }`，返回 `boolean` |
| `POST` | `/session/:id/revert` | 回复讯息 | 正文：`{ messageID, partID? }`，返回 `boolean` |
| `POST` | `/session/:id/unrevert` | 恢复所有已恢复的消息 | 返回`boolean` |
| `POST` | `/session/:id/permissions/:permissionID` | 回复许可权限请求 | 正文：`{ response, remember? }`，返回 `boolean` |
| `POST` | `/session/:id/init` | 分析应用并创建 `AGENTS.md` | 请求体：`{ messageID, providerID, modelID }`，返回 `boolean` |
| `POST` | `/session/:id/fork` | 在某条消息处分叉现有会话 | 请求体：`{ messageID? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `POST` | `/session/:id/abort` | 中止正在运行的会话 | 返回 `boolean` |
| `POST` | `/session/:id/share` | 分享会话 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `DELETE` | `/session/:id/share` | 取消分享会话 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/diff` | 获取本次会话的差异 | 查询参数：`messageID?`，返回 <a href={typesUrl}><code>FileDiff[]</code></a> |
| `POST` | `/session/:id/summarize` | 总结会话 | 请求体：`{ providerID, modelID }`，返回 `boolean` |
| `POST` | `/session/:id/revert` | 回退消息 | 请求体：`{ messageID, partID? }`，返回 `boolean` |
| `POST` | `/session/:id/unrevert` | 恢复所有已回退的消息 | 返回 `boolean` |
| `POST` | `/session/:id/permissions/:permissionID` | 响应权限请求 | 请求体：`{ response, remember? }`，返回 `boolean` |
---
### 留言
### 消息
| 方法 | 路径 | 描述 | 笔记 |
| ------ | --------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/session/:id/message` | 列出会话中的消息 | 查询： `limit?`，返回 `{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
| `POST` | `/session/:id/message` | 发送消息并等待回复 | 正文： `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`，返回 `{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>部分[]</a>`}` |
| `GET` | `/session/:id/message/:messageID` | 获取消息详情 | 返回 `{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>部分[]</a>`}` |
| `POST` | `/session/:id/prompt_async` | 非同步传送消息（休眠等待） | 主体：与 `/session/:id/message` 相同，返回 `204 No Content` |
| `POST` | `/session/:id/command` | 执行斜杠命令 | 正文： `{ messageID?, agent?, model?, command, arguments }`，返回 `{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>部分[]</a>`}` |
| `POST` | `/session/:id/shell` | 执行 shell 命令 | 正文： `{ agent, model?, command }`，返回 `{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>部分[]</a>`}` |
| 方法 | 路径 | 描述 | 说明 |
| ------ | --------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/session/:id/message` | 列出会话中的消息 | 查询参数：`limit?`，返回 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
| `POST` | `/session/:id/message` | 发送消息并等待响应 | 请求体：`{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`，返回 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `GET` | `/session/:id/message/:messageID` | 获取消息详情 | 返回 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/prompt_async` | 异步发送消息（不等待响应） | 请求体：与 `/session/:id/message` 相同，返回 `204 No Content` |
| `POST` | `/session/:id/command` | 执行斜杠命令 | 请求体：`{ messageID?, agent?, model?, command, arguments }`，返回 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/shell` | 运行 shell 命令 | 请求体：`{ agent, model?, command }`，返回 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
---
### 命令
| 方法 | 路径 | 描述 | 回应 |
| ----- | ---------- | ------------ | ------------------------------------------ |
| `GET` | `/command` | 列出所有命令 | <a href={typesUrl}><code>命令[]</code></a> |
| 方法 | 路径 | 描述 | 响应 |
| ----- | ---------- | ------------ | --------------------------------------------- |
| `GET` | `/command` | 列出所有命令 | <a href={typesUrl}><code>Command[]</code></a> |
---
### 文件
| 方法 | 路径 | 描述 | 回应 |
| 方法 | 路径 | 描述 | 响应 |
| ----- | ------------------------ | -------------------- | ----------------------------------------------------------------------------------- |
| `GET` | `/find?pattern=<pat>` | 搜索文件中的文字 | 具有 `path`、`lines`、`line_number`、`absolute_offset`、`submatches` 的匹配对像数组 |
| `GET` | `/find/file?query=<q>` | 按名称查询文件和目录 | `string[]`（路径） |
| `GET` | `/find/symbol?query=<q>` | 查询工作区符号 | <a href={typesUrl}><code>符号[]</code></a> |
| `GET` | `/find?pattern=<pat>` | 在文件中搜索文本 | 包含 `path`、`lines`、`line_number`、`absolute_offset`、`submatches` 的匹配对象数组 |
| `GET` | `/find/file?query=<q>` | 按名称查找文件和目录 | `string[]`（路径） |
| `GET` | `/find/symbol?query=<q>` | 查找工作区符号 | <a href={typesUrl}><code>Symbol[]</code></a> |
| `GET` | `/file?path=<path>` | 列出文件和目录 | <a href={typesUrl}><code>FileNode[]</code></a> |
| `GET` | `/file/content?path=<p>` | 读取文件 | <a href={typesUrl}><code>文件内容</code></a> |
| `GET` | `/file/status` | 获取跟踪文件的状态 | <a href={typesUrl}><code>文件[]</code></a> |
| `GET` | `/file/content?path=<p>` | 读取文件 | <a href={typesUrl}><code>FileContent</code></a> |
| `GET` | `/file/status` | 获取已跟踪文件的状态 | <a href={typesUrl}><code>File[]</code></a> |
#### `/find/file` 查询参数
- `query`（必需）—搜寻字符串（模糊匹配）
- `query`（必需）— 搜索字符串（模糊匹配）
- `type`（可选）— 将结果限制为 `"file"` 或 `"directory"`
- `directory` (任选) — 覆盖搜索的专案根目录
- `limit`（任选）— 最大结果 (1–200)
- `dirs`（任选）— 旧标志（`"false"`仅返回档案）
- `directory`（可选）— 覆盖搜索的项目根目录
- `limit`（可选）— 最大结果数（1–200）
- `dirs`（可选）— 旧版标志（`"false"` 仅返回文件）
---
### 工具（实验）
### 工具（实验性）
| 方法 | 路径 | 描述 | 回应 |
| ----- | ------------------------------------------- | ---------------------------- | -------------------------------------------- |
| `GET` | `/experimental/tool/ids` | 列出所有工具 ID | <a href={typesUrl}><code>工具ID</code></a> |
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | 列出具有模型 JSON 模式的工具 | <a href={typesUrl}><code>工具列表</code></a> |
| 方法 | 路径 | 描述 | 响应 |
| ----- | ------------------------------------------- | ---------------------------------- | -------------------------------------------- |
| `GET` | `/experimental/tool/ids` | 列出所有工具 ID | <a href={typesUrl}><code>ToolIDs</code></a> |
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | 列出指定模型的工具及其 JSON Schema | <a href={typesUrl}><code>ToolList</code></a> |
---
### LSP、格式化程式和 MCP
### LSP、格式化器和 MCP
| 方法 | 路径 | 描述 | 回应 |
| ------ | ------------ | ------------------- | ------------------------------------------------------ |
| 方法 | 路径 | 描述 | 响应 |
| ------ | ------------ | ------------------- | -------------------------------------------------------- |
| `GET` | `/lsp` | 获取 LSP 服务器状态 | <a href={typesUrl}><code>LSPStatus[]</code></a> |
| `GET` | `/formatter` | 获取格式化程式状态 | <a href={typesUrl}><code>FormatterStatus[]</code></a> |
| `GET` | `/mcp` | 获取 MCP 服务器状态 | `{ [name: string]: `<a href={typesUrl}>MCP状态</a>` }` |
| `POST` | `/mcp` | 动态添加 MCP 服务器 | 主体：`{ name, config }`，返回 MCP 状态对象 |
| `GET` | `/formatter` | 获取格式化器状态 | <a href={typesUrl}><code>FormatterStatus[]</code></a> |
| `GET` | `/mcp` | 获取 MCP 服务器状态 | `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` |
| `POST` | `/mcp` | 动态添加 MCP 服务器 | 请求体：`{ name, config }`，返回 MCP 状态对象 |
---
### 代理商
### 代理
| 方法 | 路径 | 描述 | 回应 |
| ----- | -------- | ------------------ | ------------------------------------------ |
| `GET` | `/agent` | 列出所有可用的代理 | <a href={typesUrl}><code>代理[]</code></a> |
| 方法 | 路径 | 描述 | 响应 |
| ----- | -------- | ------------------ | ------------------------------------------- |
| `GET` | `/agent` | 列出所有可用的代理 | <a href={typesUrl}><code>Agent[]</code></a> |
---
### 日志
| 方法 | 路径 | 描述 | 回应 |
| ------ | ------------------------------------------- | ------ | -------------------- |
| `POST` | 身体：`{ service, level, message, extra? }` | `/log` | 写入日志。 `boolean` |
| 方法 | 路径 | 描述 | 响应 |
| ------ | ------ | ----------------------------------------------------------- | --------- |
| `POST` | `/log` | 写入日志条目。请求体：`{ service, level, message, extra? }` | `boolean` |
---
### TUI
| 方法 | 路径 | 描述 | 回应 |
| ------ | ----------------------- | ----------------------------------------- | ------------ |
| `POST` | `/tui/append-prompt` | 将文字附加到提示 | `boolean` |
| `POST` | `/tui/open-help` | 开启帮助对话方块 | `boolean` |
| `POST` | `/tui/open-sessions` | 开启会话选择器 | `boolean` |
| `POST` | `/tui/open-themes` | 开启主题选择器 | `boolean` |
| `POST` | `/tui/open-models` | 开启模型选择器 | `boolean` |
| `POST` | `/tui/submit-prompt` | 提交当前提示 | `boolean` |
| `POST` | `/tui/clear-prompt` | 清除提示 | `boolean` |
| `POST` | `/tui/execute-command` | 执行命令 (`{ command }`) | `boolean` |
| `POST` | `/tui/show-toast` | 显示祝酒 (`{ title?, message, variant }`) | `boolean` |
| 方法 | 路径 | 描述 | 响应 |
| ------ | ----------------------- | ---------------------------------------------- | ------------ |
| `POST` | `/tui/append-prompt` | 向提示词追加文本 | `boolean` |
| `POST` | `/tui/open-help` | 打开帮助对话框 | `boolean` |
| `POST` | `/tui/open-sessions` | 打开会话选择器 | `boolean` |
| `POST` | `/tui/open-themes` | 打开主题选择器 | `boolean` |
| `POST` | `/tui/open-models` | 打开模型选择器 | `boolean` |
| `POST` | `/tui/submit-prompt` | 提交当前提示词 | `boolean` |
| `POST` | `/tui/clear-prompt` | 清除提示词 | `boolean` |
| `POST` | `/tui/execute-command` | 执行命令（`{ command }`） | `boolean` |
| `POST` | `/tui/show-toast` | 显示提示消息（`{ title?, message, variant }`） | `boolean` |
| `GET` | `/tui/control/next` | 等待下一个控制请求 | 控制请求对象 |
| `POST` | `/tui/control/response` | 响应控制请求 (`{ body }`) | `boolean` |
| `POST` | `/tui/control/response` | 响应控制请求（`{ body }`） | `boolean` |
---
### 授权
### 认证
| 方法 | 路径 | 描述 | 回应 |
| ----- | ----------- | ------------------------------------------ | --------- |
| `PUT` | `/auth/:id` | 设置身份验证凭据。正文必须与提供商架构匹配 | `boolean` |
| 方法 | 路径 | 描述 | 响应 |
| ----- | ----------- | -------------------------------------------- | --------- |
| `PUT` | `/auth/:id` | 设置认证凭据。请求体必须匹配提供商的数据结构 | `boolean` |
---
### 活动
### 事件
| 方法 | 路径 | 描述 | 回应 |
| ----- | -------- | ------------------------------------------------------------------- | ------------------ |
| `GET` | `/event` | 服务器发送事件流。第一个事件是 `server.connected`，之后是总线事件。 | 服务器发送事件流。 |
| 方法 | 路径 | 描述 | 响应 |
| ----- | -------- | ----------------------------------------------------------------- | ---------------- |
| `GET` | `/event` | 服务器发送事件流。第一个事件是 `server.connected`，之后是总线事件 | 服务器发送事件流 |
---
### 文档
| 方法 | 路径 | 描述 | 回应 |
| ----- | ------ | --------------- | ------------------------- |
| `GET` | `/doc` | 开启API 3.1规范 | 具有OpenAPI规范的HTML页面 |
| 方法 | 路径 | 描述 | 响应 |
| ----- | ------ | ---------------- | ----------------------------- |
| `GET` | `/doc` | OpenAPI 3.1 规范 | 包含 OpenAPI 规范的 HTML 页面 |

73
packages/web/src/content/docs/zh-cn/share.mdx
View File

@@ -1,41 +1,41 @@
---
title: 分享
description: 分享您的 opencode 对话。
description: 分享您的 OpenCode 对话。
---
opencode 的共享功能允许您建立指向 opencode 对话的公共链接，以便您可以与蓝牙进行战斗或从其他人那里获得帮助。
OpenCode 的分享功能允许您创建指向 OpenCode 对话的公开链接，方便与团队成员协作或向他人寻求帮助。
:::note
任何知道链接的人都可以公开访问共享对话。
共享的对话对任何拥有链接的人都是公开可访问的。
:::
---
## 它是如何运作的
## 工作原理
当您分享对话时，opencode：
当您分享一段对话时，OpenCode 会：
1. 为您的会话建立唯一的公共 URL
2. 将您的对话历史记录同步到我们的服务器
3. 通过可共享链接访问对话 — `opncd.ai/s/<share-id>`
1. 为您的会话创建一个唯一的公开 URL
2. 将您的对话历史同步到我们的服务器
3. 通过可分享的链接使对话可访问 — `opncd.ai/s/<share-id>`
---
## 分享
## 分享模式
opencode 支持三种控制对话共享方式的共享模式：
OpenCode 支持三种分享模式，用于控制对话的共享方式：
---
### 手动（默认）
### 手动模式（默认）
在默认情况下，opencode 使用手动共享模式。会话不会自动共享，但您可以使用 `/share` 命令手动共享它们：
默认情况下，OpenCode 使用手动分享模式。会话不会自动共享，但您可以使用 `/share` 命令手动分享：
```
/share
```
这将生成一个唯一的 URL，将其复制到您的剪贴板中。
这将生成一个唯一的 URL 并复制到您的剪贴板。
要在[配置文件](/docs/config)中显式设置手动模式：
@@ -50,7 +50,7 @@ opencode 支持三种控制对话共享方式的共享模式：
### 自动分享
您可以通过将 [配置文件](/docs/config) 中的 `share` 选项设置为 `"auto"` 来为所有新对话启用自动共享：
您可以在[配置文件](/docs/config)中将 `share` 选项设置为 `"auto"`，为所有新对话启用自动分享：
```json title="opencode.json"
{
@@ -59,13 +59,13 @@ opencode 支持三种控制对话共享方式的共享模式：
}
```
启用自动共享后，每个新对话都会自动共享并生成链接。
启用自动分享后，每个新对话都会自动共享并生成链接。
---
### 已禁用
### 禁用
您可以通过将 [配置文件](/docs/config) 中的 `share` 选项设置为 `"disabled"` 来完全禁用共享：
您可以在[配置文件](/docs/config)中将 `share` 选项设置为 `"disabled"`，完全禁用分享功能：
```json title="opencode.json"
{
@@ -74,34 +74,33 @@ opencode 支持三种控制对话共享方式的共享模式：
}
```
为了在您的团队中针对特定项目强制执行此操作，请将其添加到您项目的 `opencode.json` 文件中，并将其提交到Git。
要在团队中对特定项目强制执行此设置，请将其添加到项目的 `opencode.json` 文件中并提交到 Git。
---
## 取消共享
## 取消分享
要停止共享对话并将其从公共访问中删除：
要停止分享对话并将其从公开访问中移除：
```
/unshare
```
这将删除共享链接并删除与对话相关的数据。
这将移除分享链接并删除与该对话相关的数据。
---
## 隐私
分享对话时需要记住一些事项。
分享对话时需要注意以下几点。
---
### 数据保留
### 数据留存
共享对话仍然可以访问，直到您明确取消共享。这
包括：
共享的对话在您明确取消分享之前将一直保持可访问状态。这包括：
- 完整的对话历史记录
- 完整的对话历史
- 所有消息和回复
- 会话元数据
@@ -109,20 +108,20 @@ opencode 支持三种控制对话共享方式的共享模式：
### 建议
- 仅共享不包含敏感资讯的对话。
- 分享之前查看对话内容。
- 协作完成后取消共享对话。
- 避免共享包括专有代码或机密数据的对话。
- 对于敏感项目，完全禁用共享。
- 仅分享不包含敏感信息的对话。
- 分享前请检查对话内容。
- 协作完成后请取消分享。
- 避免分享包含专有代码或机密数据的对话。
- 对于敏感项目，请完全禁用分享功能。
---
## 对于企业
## 企业版
对于企业部署，共享功能可以是：
对于企业部署，分享功能可以：
- **出于安全合规性完全禁用**
- **仅限** 仅通过 SSO 进行身份验证的用户
- **在您自己的基础设施上自行托管**
- 出于安全合规考虑**完全禁用**
- **限制**为仅通过 SSO 身份验证的用户可用
- **自托管**在您自己的基础设施上
[了解更多关于在您的组织中使用opencode的](/docs/enterprise)。
[了解更多](/docs/enterprise)关于在您的组织中使用 OpenCode 的信息。

112
packages/web/src/content/docs/zh-cn/skills.mdx
View File

@@ -1,62 +1,62 @@
---
title: 代理技能
description: “通过 SKILL.md 定义可复用的行为”
title: "代理技能"
description: "通过 SKILL.md 定义可复用的行为"
---
代理技能使 OpenCode 能够从您的仓库或主目录中发现可重用的指令。
技能通过原生 `skill` 工具输入导入 - 代理可以查看可用技能并可以在需要时加载完整内容。
代理技能让 OpenCode 能够从你的仓库或主目录中发现可复用的指令。
技能通过原生的 `skill` 工具按需加载——代理可以查看可用技能，并在需要时加载完整内容。
---
## 放置文件
为每个技能名称建立一个资料夹，并在其中放入`SKILL.md`。
opencode 搜索这些位置：
为每个技能名称创建一个文件夹，并在其中放入 `SKILL.md`。
OpenCode 会搜索以下位置：
- Project config: `.opencode/skills/<name>/SKILL.md`
- Global config: `~/.config/opencode/skills/<name>/SKILL.md`
- 专案Claude兼容：`.claude/skills/<name>/SKILL.md`
- 全域性 Claude 兼容： `~/.claude/skills/<name>/SKILL.md`
- 专案代理兼容：`.agents/skills/<name>/SKILL.md`
- 全球代理兼容：`~/.agents/skills/<name>/SKILL.md`
- 项目配置：`.opencode/skills/<name>/SKILL.md`
- 全局配置：`~/.config/opencode/skills/<name>/SKILL.md`
- 项目 Claude 兼容：`.claude/skills/<name>/SKILL.md`
- 全局 Claude 兼容：`~/.claude/skills/<name>/SKILL.md`
- 项目代理兼容：`.agents/skills/<name>/SKILL.md`
- 全局代理兼容：`~/.agents/skills/<name>/SKILL.md`
---
## 了解发现
## 了解发现机制
对于专案本地路径， opencode 从当前工作目录向上走，直到到达 git 工作树。
It loads any matching `skills/*/SKILL.md` in `.opencode/` and any matching `.claude/skills/*/SKILL.md` or `.agents/skills/*/SKILL.md` along the way.
对于项目本地路径，OpenCode 会从当前工作目录向上遍历，直到到达 git 工作树根目录。
在此过程中，它会加载 `.opencode/` 中所有匹配的 `skills/*/SKILL.md`，以及匹配的 `.claude/skills/*/SKILL.md` 或 `.agents/skills/*/SKILL.md`。
Global definitions are also loaded from `~/.config/opencode/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`, and `~/.agents/skills/*/SKILL.md`.
全局定义也会从 `~/.config/opencode/skills/*/SKILL.md`、`~/.claude/skills/*/SKILL.md` 和 `~/.agents/skills/*/SKILL.md` 中加载。
---
## 编写 Frontmatter
## 编写 frontmatter
每个 `SKILL.md` 必须以 YAML frontmatter 。
仅识别这些栏位：
每个 `SKILL.md` 必须以 YAML frontmatter 开头。
仅识别以下字段：
- `name`（必填）
- `description`（必填）
- `license`（任选）
- `compatibility`（任选）
- `metadata`（任选，字符串到字符串对映）
- `license`（可选）
- `compatibility`（可选）
- `metadata`（可选，字符串到字符串的映射）
未知的 frontmatter 栏位将被忽略。
未知的 frontmatter 字段会被忽略。
---
## 验证名称
`name` 必须：
`name` 必须满足：
- 长度为 1–64 个字元
- 为小写字母数字并带有单个连字元分隔符
- 不以 `-` 开始或结束
- 长度为 1–64 个字符
- 仅包含小写字母和数字，可用单个连字符分隔
- 不以 `-` 开头或结尾
- 不包含连续的 `--`
- 匹配包含 `SKILL.md` 的目录名
- 与包含 `SKILL.md` 的目录名称一致
等效的正规表示式：
等效的正则表达式：
```text
^[a-z0-9]+(-[a-z0-9]+)*$
@@ -66,14 +66,14 @@ Global definitions are also loaded from `~/.config/opencode/skills/*/SKILL.md`,
## 遵循长度规则
`description` 必须是 1-1024 个字元。
保持足够具体，以便代理能够正确选择。
`description` 必须为 1-1024 个字符。
请保持描述足够具体，以便代理能够正确选择。
---
## 使用一个例子
## 使用示例
Create `.opencode/skills/git-release/SKILL.md` like this:
创建 `.opencode/skills/git-release/SKILL.md`，内容如下：
```markdown
---
@@ -100,10 +100,10 @@ Ask clarifying questions if the target versioning scheme is unclear.
---
## 识别工具说明
## 识别工具描述
opencode 列出了 `skill` 工具描述中的可用技能。
每个条目都包含技能名称和描述：
OpenCode 会在 `skill` 工具描述中列出可用技能。
每个条目包含技能名称和描述：
```xml
<available_skills>
@@ -114,7 +114,7 @@ opencode 列出了 `skill` 工具描述中的可用技能。
</available_skills>
```
代理通过呼叫工具来载入技能：
代理通过调用工具来加载技能：
```
skill({ name: "git-release" })
@@ -124,7 +124,7 @@ skill({ name: "git-release" })
## 配置权限
Control which skills agents can access using pattern-based permissions in `opencode.json`:
在 `opencode.json` 中使用基于模式的权限来控制代理可以访问哪些技能：
```json
{
@@ -139,21 +139,21 @@ Control which skills agents can access using pattern-based permissions in `openc
}
```
| 许可 | 行为 |
| ------- | -------------------------- |
| 权限 | 行为 |
| ------- | ------------------------ |
| `allow` | 技能立即加载 |
| `deny` | 对特工隐藏技能，访问被拒绝 |
| `ask` | 加载前提示用户批准 |
| `deny` | 对代理隐藏技能，拒绝访问 |
| `ask` | 加载前提示用户确认 |
模式支持万用字元：`internal-*` 匹配 `internal-docs`、`internal-tools` 等。
模式支持通配符：`internal-*` 可匹配 `internal-docs`、`internal-tools` 等。
---
## 覆盖每个代理
## 按代理覆盖权限
为特定代理授予与全域性默认权限不同的权限。
为特定代理授予与全局默认值不同的权限。
**对于自定义代理**（在代理前言中）：
**自定义代理**（在代理 frontmatter 中）：
```yaml
---
@@ -163,7 +163,7 @@ permission:
---
```
**For built-in agents** (in `opencode.json`):
**内置代理**（在 `opencode.json` 中）：
```json
{
@@ -183,9 +183,9 @@ permission:
## 禁用技能工具
完全禁用不应该使用技能的特工：
为不需要使用技能的代理完全禁用技能功能：
**对于定制代理**：
**自定义代理**：
```yaml
---
@@ -194,7 +194,7 @@ tools:
---
```
**对于内建代理**：
**内置代理**：
```json
{
@@ -212,11 +212,11 @@ tools:
---
## 解决加载问题
## 排查加载问题
如果某项技能没有显示：
如果某个技能没有显示：
1. 验证 `SKILL.md` 拼写为全部大写
2. 检查 frontmatter 是否包括 `name` 和 `description`
3. 确保技能名称在所有位置都是唯一的
4. 查询权限——具有`deny`的代理隐藏技能
1. 确认 `SKILL.md` 文件名全部为大写字母
2. 检查 frontmatter 是否包含 `name` 和 `description`
3. 确保技能名称在所有位置中唯一
4. 检查权限设置——设为 `deny` 的技能会对代理隐藏

106
packages/web/src/content/docs/zh-cn/themes.mdx
View File

@@ -1,67 +1,67 @@
---
title: 主题
description: 选择内建主题或定义您自己的主题。
description: 选择内置主题或定义您自己的主题。
---
使用 opencode，您可以从多个内建主题中进行选择，使用适合您的终端主题的主题，或定义您自己的自定义主题。
通过 OpenCode，您可以从多个内置主题中进行选择，使用能自动适配终端主题的主题，或者定义您自己的自定义主题。
By default, opencode uses our own `opencode` theme.
默认情况下，OpenCode 使用我们自己的 `opencode` 主题。
---
## 终端要求
为了使主题能够正确显示完整的调色板，您的终端必须支持**真彩色**（24 位颜色）。大多数现代终端默认支持此功能，但您可能需要启用它：
为了使主题能够正确显示完整的调色板，您的终端必须支持**真彩色**（24 位色）。大多数现代终端默认支持此功能，但您可能需要手动启用：
- **检查支持**：执行 `echo $COLORTERM` - 它应该输出 `truecolor` 或 `24bit`
- **启用真彩色**：在shell配置文件中设置环境变量`COLORTERM=truecolor`
- **您的终端兼容性**：确保终端模拟器支持24位颜色（大多数现代终端，​​​​如iTerm2、Alacritty、Kitty、Windows终端和最新版本的GNOME终端都支持）
- **检查支持情况**：运行 `echo $COLORTERM` — 输出应为 `truecolor` 或 `24bit`
- **启用真彩色**：在您的 shell 配置文件中设置环境变量 `COLORTERM=truecolor`
- **终端兼容性**：确保您的终端模拟器支持 24 位色（大多数现代终端如 iTerm2、Alacritty、Kitty、Windows Terminal 以及较新版本的 GNOME Terminal 均已支持）
如果没有真彩色支持，主题的颜色精度可能会降低或回落到最接近的 256 色近似值。
如果没有真彩色支持，主题可能会出现色彩精度下降的情况，或者回退到最接近的 256 色近似值。
---
## 内置主题
opencode 带有几个内建主题。
OpenCode 自带多个内置主题。
| 名称 | 描述 |
| ---------------------- | ---------------------------------------------------------------------------- |
| `system` | 适应您所处的背景颜色 |
| `tokyonight` | Based on the [Tokyonight](https://github.com/folke/tokyonight.nvim) theme |
| `everforest` | Based on the [Everforest](https://github.com/sainnhe/everforest) theme |
| `ayu` | Based on the [Ayu](https://github.com/ayu-theme) dark theme |
| `catppuccin` | Based on the [Catppuccin](https://github.com/catppuccin) theme |
| `catppuccin-macchiato` | Based on the [Catppuccin](https://github.com/catppuccin) theme |
| `gruvbox` | Based on the [Gruvbox](https://github.com/morhetz/gruvbox) theme |
| `kanagawa` | Based on the [Kanagawa](https://github.com/rebelot/kanagawa.nvim) theme |
| `nord` | Based on the [Nord](https://github.com/nordtheme/nord) theme |
| `matrix` | 骇客风格黑底绿主题 |
| `one-dark` | Based on the [Atom One](https://github.com/Th3Whit3Wolf/one-nvim) Dark theme |
| ---------------------- | ------------------------------------------------------------------- |
| `system` | 自动适配终端的背景颜色 |
| `tokyonight` | 基于 [Tokyonight](https://github.com/folke/tokyonight.nvim) 主题 |
| `everforest` | 基于 [Everforest](https://github.com/sainnhe/everforest) 主题 |
| `ayu` | 基于 [Ayu](https://github.com/ayu-theme) 暗色主题 |
| `catppuccin` | 基于 [Catppuccin](https://github.com/catppuccin) 主题 |
| `catppuccin-macchiato` | 基于 [Catppuccin](https://github.com/catppuccin) 主题 |
| `gruvbox` | 基于 [Gruvbox](https://github.com/morhetz/gruvbox) 主题 |
| `kanagawa` | 基于 [Kanagawa](https://github.com/rebelot/kanagawa.nvim) 主题 |
| `nord` | 基于 [Nord](https://github.com/nordtheme/nord) 主题 |
| `matrix` | 黑客风格的黑底绿字主题 |
| `one-dark` | 基于 [Atom One](https://github.com/Th3Whit3Wolf/one-nvim) Dark 主题 |
此外，我们还在不断添加新主题。
我们还在不断添加更多主题。
---
## 系统主题
`system` 主题旨在自动适应您的最终方案。与使用固定颜色的传统主题不同，_system_ 主题：
`system` 主题旨在自动适配您终端的配色方案。与使用固定颜色的传统主题不同，_system_ 主题具有以下特点：
- **生成灰度**：根据终端的背景颜色建立自定义灰度，确保最佳对比度。
- **使用 ANSI 颜色**：使用标准 ANSI 颜色 (0-15) 进行语法突出显示和 UI 元素，尊重 Windows 的调色盘。
- **保留默认设置**：使用 `none` 作为文字和背景颜色以保持本机的外观。
- **生成灰度色阶**：根据终端的背景颜色创建自定义灰度色阶，确保最佳对比度。
- **使用 ANSI 颜色**：利用标准 ANSI 颜色（0-15）进行语法高亮和 UI 元素渲染，遵循终端的调色板设置。
- **保留终端默认值**：将文本和背景颜色设为 `none`，以保持终端的原生外观。
系统主题适合以下用户：
- 希望 opencode 与终端的外观相匹配
- 使用自定义终端配色方案
- 希望所有终端应用程序具有一致的外观
- 希望 OpenCode 与终端的外观保持一致
- 使用了自定义终端配色方案
- 偏好所有终端应用程序拥有统一的视觉风格
---
## 使用主题
您可以通过使用 `/theme` 命令调出主题选择来选择主题。或者您可以在 [config](/docs/config) 中指定它。
您可以通过 `/theme` 命令调出主题选择界面来选择主题，也可以在[配置](/docs/config)文件中直接指定。
```json title="opencode.json" {3}
{
@@ -74,35 +74,35 @@ opencode 带有几个内建主题。
## 自定义主题
opencode 支持灵活的基于 JSON 的主题系统，允许用户轻松创建和自定义主题。
OpenCode 支持灵活的基于 JSON 的主题系统，让用户可以轻松创建和自定义主题。
---
### 优先级
### 层级优先级
主题按以下顺序从多个目录载入，其中后面的目录覆盖前面的目录：
主题按以下顺序从多个目录加载，后面的目录会覆盖前面的目录：
1. **内建主题** - 这些主题嵌入在二进制文件中
2. **User config directory** - Defined in `~/.config/opencode/themes/*.json` or `$XDG_CONFIG_HOME/opencode/themes/*.json`
3. **Project root directory** - Defined in the `<project-root>/.opencode/themes/*.json`
4. **Current working directory** - Defined in `./.opencode/themes/*.json`
1. **内置主题** — 嵌入在二进制文件中
2. **用户配置目录** — 定义在 `~/.config/opencode/themes/*.json` 或 `$XDG_CONFIG_HOME/opencode/themes/*.json`
3. **项目根目录** — 定义在 `<project-root>/.opencode/themes/*.json`
4. **当前工作目录** — 定义在 `./.opencode/themes/*.json`
如果多个目录包含同名主题，则将使用优先顺序较高的目录中的主题。
如果多个目录包含同名主题，将使用优先级较高的目录中的主题。
---
### 创建主题
要创建自定义主题，请在主题目录中创建 JSON 档案。
要创建自定义主题，请在上述任一主题目录中创建一个 JSON 文件。
对于用户范围的主题：
创建用户级主题：
```bash no-frame
mkdir -p ~/.config/opencode/themes
vim ~/.config/opencode/themes/my-theme.json
```
以及针对特定项目的主题。
创建项目级主题：
```bash no-frame
mkdir -p .opencode/themes
@@ -113,34 +113,34 @@ vim .opencode/themes/my-theme.json
### JSON 格式
主题使用灵活的 JSON 格式，支持：
主题使用灵活的 JSON 格式，支持以下特性：
- **十六进位制造颜色**： `"#ffffff"`
- **ANSI 颜色**： `3` (0-255)
- **颜色参考**： `"primary"` 或自定义定义
- **深色/light 变体**： `{"dark": "#000", "light": "#fff"}`
- **无颜色**： `"none"` - 使用终端的默认颜色或透明
- **十六进制颜色**：`"#ffffff"`
- **ANSI 颜色**：`3`（0-255）
- **颜色引用**：`"primary"` 或自定义定义的颜色名
- **深色/浅色变体**：`{"dark": "#000", "light": "#fff"}`
- **无颜色**：`"none"` — 使用终端的默认颜色或透明背景
---
### 颜色定义
`defs` 部分是可选的，它允许您定义可在主题中引用的可重用颜色。
`defs` 部分是可选的，它允许您定义可在主题中重复引用的可复用颜色。
---
### 终端默认值
特殊值 `"none"` 可用于任何颜色以继承默认的默认颜色。这对于建立与终端方案无缝的融合主题特别有用：
特殊值 `"none"` 可用于任何颜色属性，以继承终端的默认颜色。这在创建需要与终端配色方案无缝融合的主题时特别有用：
- `"text": "none"` - 使用遥控器的预设前景色
- `"background": "none"` - 使用桌面的背景颜色
- `"text": "none"` — 使用终端的默认前景色
- `"background": "none"` — 使用终端的默认背景色
---
### 例子
### 示例
以下是自定义主题的示例：
以下是一个自定义主题的完整示例：
```json title="my-theme.json"
{

98
packages/web/src/content/docs/zh-cn/tools.mdx
View File

@@ -3,15 +3,15 @@ title: 工具
description: 管理 LLM 可以使用的工具。
---
Tools allow the LLM to perform actions in your codebase. opencode comes with a set of built-in tools, but you can extend it with [custom tools](/docs/custom-tools) or [MCP servers](/docs/mcp-servers).
工具允许 LLM 在您的代码库中执行操作。OpenCode 自带一组内置工具，您也可以通过[自定义工具](/docs/custom-tools)或 [MCP 服务器](/docs/mcp-servers)来扩展它。
默认情况下，所有工具都是**启用**并且不需要执行权限。您可以交叉[permissions](/docs/permissions) 控制工具行为。
默认情况下，所有工具都是**启用**的，且无需权限即可运行。您可以通过[权限](/docs/permissions)来控制工具的行为。
---
## 配置
使用 `permission` 栏位控制工具行为。您可以允许、拒绝或要求批准每个工具。
使用 `permission` 字段来控制工具行为。您可以对每个工具设置允许、拒绝或需要审批。
```json title="opencode.json"
{
@@ -24,7 +24,7 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
您还可以使用通配符同时控制多个工具。例如，要求 MCP 服务器批准所有工具：
您还可以使用通配符同时控制多个工具。例如，要求某个 MCP 服务器的所有工具都需要审批：
```json title="opencode.json"
{
@@ -35,13 +35,13 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
[了解更多](/docs/permissions)关于配置许可权。
[了解更多](/docs/permissions)关于配置权限的内容。
---
## 內建工具
## 内置工具
以下是 opencode 中可用的所有内置工具。
以下是 OpenCode 中所有可用的内置工具。
---
@@ -58,13 +58,13 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
这个工具允许 LLM 运行终端命令，例如：`npm install`, `git status`，或者其他任何终端命令。
该工具允许 LLM 运行终端命令，例如 `npm install`、`git status` 或其他任何 shell 命令。
---
### edit
使用精确的字符串替换来修改现有文件。
通过精确的字符串替换来修改现有文件。
```json title="opencode.json" {4}
{
@@ -75,13 +75,13 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
该工具通过替换完全匹配的文本来对文件进行精确编辑。这是 LLM 修改代码的主要方式。
该工具通过替换精确匹配的文本来对文件进行编辑。这是 LLM 修改代码的主要方式。
---
### write
建立新文件或覆盖现有文件。
创建新文件或覆盖现有文件。
```json title="opencode.json" {4}
{
@@ -92,10 +92,10 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
使用此功能可允许 LLM 创建新文件。如果文件已存在，则会覆盖现有文件。
使用此工具允许 LLM 创建新文件。如果文件已存在，则会覆盖现有文件。
:::note
`写入`工具由`编辑`权限控制，涵盖所有文件修改（`编辑`、`写入`、`修补`、`多重编辑`）。
`write` 工具由 `edit` 权限控制，该权限涵盖所有文件修改操作（`edit`、`write`、`patch`、`multiedit`）。
:::
---
@@ -113,7 +113,7 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
该工具读取文件并返回其内容。它支持读取大型文件中的特定行范围。
该工具读取文件并返回其内容。它支持对大文件读取指定行范围。
---
@@ -130,7 +130,7 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
快速搜索代码库中的内容。支持完整的正则表达式语法和文件模式过滤。
在代码库中快速搜索内容。支持完整的正则表达式语法和文件模式过滤。
---
@@ -147,13 +147,13 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
使用类似 **/\*.js 或 src/**/\*.ts 的通配符模式搜索文件。返回按修改时间排序的匹配文件路径。
使用 `**/*.js` 或 `src/**/*.ts` 等 glob 模式搜索文件。返回按修改时间排序的匹配文件路径。
---
### list
列出给定路径中的文件和目录。
列出指定路径下的文件和目录。
```json title="opencode.json" {4}
{
@@ -164,16 +164,16 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
此工具用于列出目录内容。它接受通配符模式来筛选结果。
该工具用于列出目录内容。它接受 glob 模式来过滤结果。
---
### lsp（实验性）
与已配置的 LSP 服务器交互，以获取代码智能功能，例如定义、引用、悬停信息和调用层次结构。
与已配置的 LSP 服务器交互，获取代码智能功能，如定义跳转、引用查找、悬停信息和调用层次结构。
:::note
只有当 OPENCODE_EXPERIMENTAL_LSP_TOOL=true（或 OPENCODE_EXPERIMENTAL=true）时，此工具才可用。
该工具仅在设置 `OPENCODE_EXPERIMENTAL_LSP_TOOL=true`（或 `OPENCODE_EXPERIMENTAL=true`）时可用。
:::
```json title="opencode.json" {4}
@@ -187,7 +187,7 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
支持的操作包括 `goToDefinition`、`findReferences`、`hover`、`documentSymbol`、`workspaceSymbol`、`goToImplementation`、`prepareCallHierarchy`、`incomingCalls` 和 `outgoingCalls`。
要配置哪些 LSP 服务器可用于您的项目，请参阅 [LSP Servers](/docs/lsp).
要配置项目可用的 LSP 服务器，请参阅 [LSP 服务器](/docs/lsp)。
---
@@ -204,17 +204,17 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
此工具可将补丁文件应用到您的代码库。它可用于应用来自各种来源的差异和补丁。
该工具将补丁文件应用到您的代码库中。适用于应用来自各种来源的 diff 和补丁。
:::note
`修补`工具由`编辑`权限控制，涵盖所有文件修改（`编辑`、`写入`、`修补`、`多重编辑`）。
`patch` 工具由 `edit` 权限控制，该权限涵盖所有文件修改操作（`edit`、`write`、`patch`、`multiedit`）。
:::
---
### skill
加载[技能](/docs/skills)（`SKILL.md` 文件）并在对话中返回其内容。
加载一个[技能](/docs/skills)（即 `SKILL.md` 文件）并在对话中返回其内容。
```json title="opencode.json" {4}
{
@@ -229,7 +229,7 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
### todowrite
在编码会话过程中管理待办事项列表。
在编码会话中管理待办事项列表。
```json title="opencode.json" {4}
{
@@ -240,17 +240,17 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
创建和更新任务列表，以跟踪复杂操作的进度。LLM 利用此功能来组织多步骤任务。
创建和更新任务列表以跟踪复杂操作的进度。LLM 使用此工具来组织多步骤任务。
:::note
此工具默认情况下对子代理禁用，但您可以手动启用它。 [了解更多](/docs/agents/#permissions)
该工具默认对子代理禁用，但您可以手动启用。[了解更多](/docs/agents/#permissions)
:::
---
### todoread
阅读现有的待办事项清单。
读取现有的待办事项列表。
```json title="opencode.json" {4}
{
@@ -261,10 +261,10 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
读取当前待办事项列表状态。LLM 使用此信息来跟踪哪些任务处于待处理状态或已完成状态。
读取当前待办事项列表的状态。LLM 使用此工具来跟踪哪些任务待处理、哪些已完成。
:::note
此工具默认情况下对子代理禁用，但您可以手动启用它。 [了解更多](/docs/agents/#permissions)
该工具默认对子代理禁用，但您可以手动启用。[了解更多](/docs/agents/#permissions)
:::
---
@@ -282,16 +282,16 @@ Tools allow the LLM to perform actions in your codebase. opencode comes with a s
}
```
允许LLM获取并读取网页。可用于查找文档或研究在线资源。
允许 LLM 获取并读取网页内容。适用于查阅文档或研究在线资源。
---
### websearch
在网络上搜索资料。
在网络上搜索信息。
:::note
只有在使用 OpenCode 提供程序时，或者当 OPENCODE_ENABLE_EXA 环境变量被设置为任何真值（例如 true 或 1）时，此工具才可用。
该工具仅在使用 OpenCode 提供商时，或当 `OPENCODE_ENABLE_EXA` 环境变量设置为任意真值（例如 `true` 或 `1`）时可用。
在启动 OpenCode 时启用：
@@ -310,12 +310,12 @@ OPENCODE_ENABLE_EXA=1 opencode
}
```
利用 Exa AI 进行网络搜索，查找相关信息。可用于研究特定主题、了解时事新闻或收集超出训练数据范围的信息。
使用 Exa AI 进行网络搜索以查找相关信息。适用于研究主题、了解时事动态或获取超出训练数据截止日期的信息。
无需 API 密钥——该工具无需身份验证即可直接连接到 Exa AI 托管的 MCP 服务。
无需 API 密钥——该工具无需身份验证即可直接连接到 Exa AI 的托管 MCP 服务。
:::tip
当您需要查找信息时，请使用`网页搜索`；当您需要从特定 URL 检索内容时，请使用`网页获取`。
当您需要查找信息（发现）时使用 `websearch`，当您需要从特定 URL 获取内容（检索）时使用 `webfetch`。
:::
---
@@ -333,42 +333,42 @@ OPENCODE_ENABLE_EXA=1 opencode
}
```
该工具允许 LLM 在执行任务期间向用户提问。它在以下方面很有用：
该工具允许 LLM 在执行任务期间向用户提问。适用于以下场景：
- 收集用户偏好或需求
- 澄清含糊不清的指示
- 就实施方案做出决定
- 提供关于选择下一步方向的选项
- 澄清模糊的指令
- 获取实现方案的决策
- 提供方向选择的选项
每个问题都包含标题、问题正文和选项列表。用户可以从提供的选项中选择答案，也可以输入自定义答案。如果有多个问题，用户可以在提交所有答案之前在不同问题之间切换。
每个问题包含标题、问题正文和选项列表。用户可以从提供的选项中选择，也可以输入自定义答案。当有多个问题时，用户可以在提交所有答案之前在各问题之间切换浏览。
---
## 自定义工具
自定义工具允许您定义LLM可以调用的自定义函数。这些函数在您的配置文件中定义，并且可以执行任意代码。
自定义工具允许您定义 LLM 可以调用的自定义函数。这些函数在您的配置文件中定义，可以执行任意代码。
[了解更多](/docs/custom-tools)关于创建自定义工具。
[了解更多](/docs/custom-tools)关于创建自定义工具的内容。
---
## MCP 服务器
MCP（模型上下文协议）服务器允许您集成外部工具和服务。这包括数据库访问、API 集成和第三方服务。
MCP（Model Context Protocol）服务器允许您集成外部工具和服务，包括数据库访问、API 集成和第三方服务。
[了解更多](/docs/mcp-servers)关于配置MCP服务器。
[了解更多](/docs/mcp-servers)关于配置 MCP 服务器的内容。
---
## 内部规则
## 内部机制
在内部，`grep`、 `通配符` 和 `罗列` 等工具底层都使用了 ripgrep。默认情况下，ripgrep 会遵循 .gitignore 文件中的规则，这意味着 .gitignore 文件中列出的文件和目录将被排除在搜索和列表之外。
在内部，`grep`、`glob` 和 `list` 等工具底层使用 [ripgrep](https://github.com/BurntSushi/ripgrep)。默认情况下，ripgrep 遵循 `.gitignore` 中的模式，这意味着 `.gitignore` 中列出的文件和目录将被排除在搜索和列表结果之外。
---
### 忽略模式
为了使工具不跳过那些通常会被忽略的文件，请在项目根目录下创建一个 `.ignore` 文件。该文件内定义的目录可以不会被跳过。
要包含通常会被忽略的文件，请在项目根目录下创建一个 `.ignore` 文件。该文件可以显式允许某些路径。
```text title=".ignore"
!node_modules/
@@ -376,4 +376,4 @@ MCP（模型上下文协议）服务器允许您集成外部工具和服务。
!build/
```
例如，这个 `.ignore` 文件允许 ripgrep 在 `node_modules/`、`dist/` 和 `build/` 目录中搜索，即使它们已在 `.gitignore` 中列出。
例如，这个 `.ignore` 文件允许 ripgrep 在 `node_modules/`、`dist/` 和 `build/` 目录中进行搜索，即使它们已在 `.gitignore` 中列出。

201
packages/web/src/content/docs/zh-cn/troubleshooting.mdx
View File

@@ -1,67 +1,67 @@
---
title: 故障排除
description: 常见问题以及如何解决它们。
description: 常见问题及其解决方法。
---
要排除 opencode 的问题，请首先检查其存储在磁盘上的日志和本地数据。
要调试 OpenCode 的问题，请先检查其存储在磁盘上的日志和本地数据。
---
## 日志
日志文件写入：
日志文件写入位置：
- **macOS/Linux**: `~/.local/share/opencode/log/`
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode\log`
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.local\share\opencode\log`
日志档案以时间命名（例如`2025-01-09T123456.log`），并保留最近10个日志档案。
日志文件以时间戳命名（例如 `2025-01-09T123456.log`），并保留最近的 10 个日志文件。
You can set the log level with the `--log-level` command-line option to get more detailed debug information. For example, `opencode --log-level DEBUG`.
你可以通过 `--log-level` 命令行选项设置日志级别以获取更详细的调试信息。例如：`opencode --log-level DEBUG`。
---
## 存储
opencode程序将会话数据和其他应用程序数据存储在磁碟上：
OpenCode 将会话数据和其他应用数据存储在磁盘上：
- **macOS/Linux**: `~/.local/share/opencode/`
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode`
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.local\share\opencode`
该目录包含：
- `auth.json` - 身份验证凭据，例如 API 密钥、OAuth Tokens
- `auth.json` - 身份验证数据，如 API 密钥、OAuth Token
- `log/` - 应用日志
- `project/` - 项目特定数据，例如会话和消息数据
- 如果项目位于 Git 仓库中，则存储在 `./<project-slug>/storage/` 中
- 如果不是 Git 存储库，则存储在 `./global/storage/` 中
- `project/` - 项目特定数据，如会话和消息数据
- 如果项目位于 Git 仓库中，则存储在 `./<project-slug>/storage/`
- 如果不是 Git 仓库，则存储在 `./global/storage/`
---
## 桌面应用程序
## 桌面应用
opencode Desktop runs a local opencode server (the `opencode-cli` sidecar) in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.
OpenCode Desktop 会在后台运行一个本地 OpenCode 服务器（即 `opencode-cli` 附属进程）。大多数问题是由插件异常、缓存损坏或错误的服务器设置引起的。
### 快速检查
- 完全退出并重新启动应用程序。
- 如果应用程序显示错误界面，请单击“**重新启动**”并复制错误详细信息。
- macOS only: `OpenCode` menu -> **Reload Webview** (helps if the UI is blank/frozen).
- 完全退出并重新启动应用。
- 如果应用显示错误页面，请点击**重新启动**并复制错误详情。
- 仅限 macOS：`OpenCode` 菜单 -> **Reload Webview**（当 UI 空白或冻结时有效）。
---
### 禁用插件
如果桌面应用程序在启动时崩溃、挂起或行为异常，请首先禁用插件。
如果桌面应用在启动时崩溃、卡住或行为异常，请先禁用插件。
#### 检查全域性配置
#### 检查全局配置
开启全域性文件并查询`plugin`键。
打开你的全局配置文件，查找 `plugin` 键。
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc` (or `~/.config/opencode/opencode.json`)
- **macOS/Linux** (older installs): `~/.local/share/opencode/opencode.jsonc`
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\opencode\opencode.jsonc`
- **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
{
@@ -72,118 +72,118 @@ opencode Desktop runs a local opencode server (the `opencode-cli` sidecar) in th
#### 检查插件目录
opencode 还可以从磁碟加载本地外挂。暂时将它们移开（或重新命名资料夹）并重新启动桌面应用程序：
OpenCode 还可以从磁盘加载本地插件。临时将这些插件移走（或重命名文件夹），然后重新启动桌面应用：
- **全域性插件**
- **全局插件**
- **macOS/Linux**: `~/.config/opencode/plugins/`
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\opencode\plugins`
- **项目插件**（仅当您使用每个项目配置时）
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.config\opencode\plugins`
- **项目插件**（仅当你使用了项目级配置时）
- `<your-project>/.opencode/plugins/`
如果应用程序再次开始工作，请一次重新启用一个插件，以找出导致问题的插件。
如果应用恢复正常，请逐个重新启用插件，找出导致问题的那个。
---
### 清除缓存
如果取消外挂没有帮助（或者外挂安装被卡住），请清除缓存，方便opencode可以重建它。
如果禁用插件没有帮助（或插件安装卡住了），请清除缓存以便 OpenCode 重新构建。
1. 完全退出 opencode 桌面。
1. 完全退出 OpenCode Desktop。
2. 删除缓存目录：
- **macOS**: Finder -> `Cmd+Shift+G` -> paste `~/.cache/opencode`
- **Linux**: delete `~/.cache/opencode` (or run `rm -rf ~/.cache/opencode`)
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.cache\opencode`
- **macOS**: Finder -> `Cmd+Shift+G` -> 粘贴 `~/.cache/opencode`
- **Linux**: 删除 `~/.cache/opencode`（或运行 `rm -rf ~/.cache/opencode`）
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.cache\opencode`
3. 重新启动 opencode 桌面。
3. 重新启动 OpenCode Desktop。
---
### 修复服务器连接问题
opencode Desktop 可以启动自己的本地服务器（默认配置）或连线到您的服务器 URL。
OpenCode Desktop 可以启动自己的本地服务器（默认行为），也可以连接到你配置的服务器 URL。
如果您看到**“连线失败”**对话中断（或者应用程序永远无法穿透启动萤幕），请检查自定义服务器URL。
如果你看到**"Connection Failed"**对话框（或应用始终停留在启动画面），请检查自定义服务器 URL。
#### 清除桌面桌面服务器 URL
#### 清除桌面默认服务器 URL
在主屏幕中，单击服务器名称（带有状态点）以打开服务器选择器。在“**默认服务器**”部分中，单击“**清除**”。
在主页面上，点击服务器名称（带有状态指示点）以打开服务器选择器。在**默认服务器**部分，点击**清除**。
#### 从配置中删除 `server.port` / `server.hostname`
#### 从配置中移除 `server.port` / `server.hostname`
If your `opencode.json(c)` contains a `server` section, temporarily remove it and restart the desktop app.
如果你的 `opencode.json(c)` 包含 `server` 部分，请临时移除该部分并重新启动桌面应用。
#### 检查环境变量
如果您在环境中设置了 `OPENCODE_PORT`，桌面应用程序将尝试将交换机用于本地服务器。
如果你在环境中设置了 `OPENCODE_PORT`，桌面应用将尝试使用该端口作为本地服务器端口。
- 取消设置`OPENCODE_PORT`（或选择一个休闲摊）并重新启动。
- 取消设置 `OPENCODE_PORT`（或选择一个空闲端口）并重新启动。
---
### Linux：Wayland / X11 问题
### Linux: Wayland / X11 问题
在 Linux 上，某些 Wayland 设置可能会导致空白视窗或合成器错误。
在 Linux 上，某些 Wayland 设置可能会导致窗口空白或合成器错误。
- 如果您在 Wayland 程序上并且应用的是 blank/crashing，请尝试使用 `OC_ALLOW_WAYLAND=1` 启动。
- 如果这让事情变得更糟糕，请完成其删除并尝试在 X11 会话下启动。
- 如果你使用 Wayland 且应用出现空白或崩溃，请尝试使用 `OC_ALLOW_WAYLAND=1` 启动。
- 如果情况变得更糟，请移除该设置并尝试在 X11 会话下启动。
---
### Windows：WebView2执行时
### Windows: WebView2 运行时
在 Windows 上，opencode 桌面需要 Microsoft Edge **WebView2 执行时**。如果应用程序打开为空白视窗或无法启动，请 install/update WebView2 并重试。
在 Windows 上，OpenCode Desktop 需要 Microsoft Edge **WebView2 Runtime**。如果应用打开后是空白窗口或无法启动，请安装或更新 WebView2 后重试。
---
### Windows：一般问题
### Windows: 常见性能问题
If you're experiencing slow performance, file access issues, or terminal problems on Windows, try using [WSL (Windows Subsystem for Linux)](/docs/windows-wsl). WSL provides a Linux environment that works more seamlessly with opencode's features.
如果你在 Windows 上遇到性能缓慢、文件访问问题或终端问题，请尝试使用 [WSL (Windows Subsystem for Linux)](/docs/windows-wsl)。WSL 提供了一个 Linux 环境，能更好地与 OpenCode 的功能兼容。
---
### 通知不显示
opencode 桌面仅在以下情况下显示系统通知：
OpenCode Desktop 仅在以下情况下显示系统通知：
- 在您的作业系统中设置为 opencode 启用了通知，并且
- 应用程序视窗未聚焦。
- 在操作系统设置中已为 OpenCode 启用通知，且
- 应用窗口未处于焦点状态。
---
### 重置桌面应用程序储存（最后的手段）
### 重置桌面应用存储（最后手段）
如果应用程序无法并且启动您无法从 UI 内部清除设置，请重置桌面应用程序的存储状态。
如果应用无法启动且你无法从 UI 内部清除设置，请重置桌面应用的保存状态。
1. 退出 opencode 桌面。
2. 查询并删除这些文件（它们位于 opencode 桌面应用程序数据目录中）：
1. 退出 OpenCode Desktop。
2. 找到并删除以下文件（它们位于 OpenCode Desktop 应用数据目录中）：
- `opencode.settings.dat` (desktop default server URL)
- `opencode.global.dat` and `opencode.workspace.*.dat` (UI state like recent servers/projects)
- `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%` （然后搜索上面的档名）
- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support`（然后搜索上述文件名）
- **Linux**: 在 `~/.local/share` 下搜索上述文件名
- **Windows**: 按 `WIN+R` -> `%APPDATA%`（然后搜索上述文件名）
---
## 寻求帮助
## 获取帮助
如果您遇到 opencode 问题：
如果你遇到 OpenCode 的问题：
1. **报告 GitHub** 上的问题
1. **在 GitHub 上报告问题**
报告错误或请求功能的最佳方式是利用我们的 GitHub 存储库：
报告 Bug 或请求功能的最佳方式是通过我们的 GitHub 仓库：
[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
在建立新问题之前，请搜索现有问题以查看您的问题是否已被报告。
在创建新 Issue 之前，请先搜索已有的 Issue，看看你的问题是否已被报告。
2. **加入我们的不和谐**
2. **加入我们的 Discord**
获得实时帮助和社群讨论，请加入我们的Discord服务器：
如需实时帮助和社区讨论，请加入我们的 Discord 服务器：
[**opencode.ai/discord**](https://opencode.ai/discord)
@@ -191,35 +191,34 @@ opencode 桌面仅在以下情况下显示系统通知：
## 常见问题
以下是一些常见问题以及解决方法。
以下是一些常见问题及其解决方法。
---
### opencode 无法启动
### OpenCode 无法启动
1. 检查日志中是否有错误消息
2. 尝试使用 `--print-logs` 执行以查看终端中的输出
3. Ensure you have the latest version with `opencode upgrade`
1. 检查日志中的错误消息
2. 尝试使用 `--print-logs` 运行以在终端中查看输出
3. 使用 `opencode upgrade` 确保你使用的是最新版本
---
### 身份验证问题
1. 尝试使用 TUI 中的 `/connect` 命令重新进行身份验证
2. 检查您的API 密钥是否有效
3. 保证您的网路允许连线到达辉煌的API
1. 尝试在 TUI 中使用 `/connect` 命令重新进行身份验证
2. 检查你的 API 密钥是否有效
3. 确保你的网络允许连接到提供商的 API
---
### 模型不可用
1. 检查您是否已通过提供商的身份验证
1. 检查你是否已通过提供商的身份验证
2. 验证配置中的模型名称是否正确
3. 某些模型可能需要特定的访问权限或订阅
如果您遇到 `ProviderModelNotFoundError` 您很可能是错误的
在某处引用模型。
模型应该像这样引用：`<providerId>/<modelId>`
如果你遇到 `ProviderModelNotFoundError`，很可能是在某处错误地引用了模型。
模型应按如下方式引用：`<providerId>/<modelId>`
示例：
@@ -227,52 +226,52 @@ opencode 桌面仅在以下情况下显示系统通知：
- `openrouter/google/gemini-2.5-flash`
- `opencode/kimi-k2`
To figure out what models you have access to, run `opencode models`
要查看你有权访问哪些模型，请运行 `opencode models`
---
### 提供商初始化错误
### ProviderInitError
如果遇到 ProviderInitError，您的配置可能无效或损坏。
如果你遇到 ProviderInitError，很可能是配置无效或已损坏。
要解决这个问题：
要解决此问题：
1. 首先，按照[提供商指南](/docs/providers) 验证您的事业是否已正确设置
2. 如果问题仍然存在，请尝试清除储存的配置：
1. 首先，按照[提供商指南](/docs/providers)验证你的提供商是否已正确设置
2. 如果问题仍然存在，请尝试清除已存储的配置：
```bash
rm -rf ~/.local/share/opencode
```
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.local\share\opencode`
在 Windows 上，按 `WIN+R` 并删除：`%USERPROFILE%\.local\share\opencode`
3. 使用 TUI 中的 `/connect` 命令指示您的企业重新进行身份验证。
3. 在 TUI 中使用 `/connect` 命令重新与提供商进行身份验证。
---
### AI_API_CallError 和提供包问题
### AI_APICallError 和提供商包问题
如果您遇到 API 呼叫错误，这可能是由于过去提供包造成的。 opencode 根据需要动态安装提供包（OpenAI、Anthropic、Google 等）将其缓存放在本地。
如果你遇到 API 调用错误，可能是由于提供商包过期导致的。OpenCode 会根据需要动态安装提供商包（OpenAI、Anthropic、Google 等）并将它们缓存到本地。
要解决provider 包问题：
要解决提供商包问题：
1. 清除provider 包缓存：
1. 清除提供商包缓存：
```bash
rm -rf ~/.cache/opencode
```
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.cache\opencode`
在 Windows 上，按 `WIN+R` 并删除：`%USERPROFILE%\.cache\opencode`
2. 重新启动 opencode 以重新安装最新的提供包
2. 重新启动 OpenCode 以重新安装最新的提供商包
这将需要 opencode 下载最新版本的提供包，这通常可以解决模型参数和 API 更改的兼容性问题。
这将强制 OpenCode 下载最新版本的提供商包，通常可以解决模型参数和 API 变更带来的兼容性问题。
---
### 复制/粘贴在 Linux 上不可用
### 在 Linux 上复制/粘贴不可用
Linux 用户需要安装以下剪贴簿实用程序之一才能使 copy/paste 功能正常工作：
Linux 用户需要安装以下剪贴板工具之一，复制/粘贴功能才能正常工作：
**对于 X11 系统：**
@@ -297,4 +296,4 @@ Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0
```
opencode 将检测您是否正在使用 Wayland 并更喜欢 `wl-clipboard`，否则将尝试按以下顺序剪贴簿工具：`xclip` 和 `xsel`。
OpenCode 会检测你是否正在使用 Wayland 并优先使用 `wl-clipboard`，否则将按以下顺序尝试查找剪贴板工具：`xclip` 和 `xsel`。

99
packages/web/src/content/docs/zh-cn/tui.mdx
View File

@@ -1,25 +1,25 @@
---
title: TUI
description: 使用 opencode 终端用户界面。
description: 使用 OpenCode 终端用户界面。
---
import { Tabs, TabItem } from "@astrojs/starlight/components"
opencode 提供交互式终端介面或 TUI，以便使用 LLM 处理您的专案。
OpenCode 提供了一个交互式终端界面（TUI），用于配合 LLM 处理您的项目。
执行opencode启动当前目录的TUI。
运行 OpenCode 即可启动当前目录的 TUI。
```bash
opencode
```
或者您可以为特定的工作目录启动它。
或者您可以为指定的工作目录启动它。
```bash
opencode /path/to/project
```
进入TUI后，您可以查看消息进行提示。
进入 TUI 后，您可以输入消息进行提示。
```text
Give me a quick summary of the codebase.
@@ -45,25 +45,25 @@ How is auth handled in @packages/functions/src/api/index.ts?
## Bash 命令
以`!`开始一条消息以执行shell命令。
以 `!` 开头的消息会作为 shell 命令执行。
```bash frame="none"
!ls -la
```
命令的输出将作为工具结果添加到对话中。
命令的输出会作为工具结果添加到对话中。
---
## 命令
使用 opencode TUI 时，您可以输入 `/` 后跟命令名称来快速执行操作。例如：
使用 OpenCode TUI 时，您可以输入 `/` 后跟命令名称来快速执行操作。例如：
```bash frame="none"
/help
```
大多数命令还是以使用 `ctrl+x` 作为主键的键系结，其中 `ctrl+x` 是默认主键。 [了解更多](/docs/keybinds)。
大多数命令还支持以 `ctrl+x` 作为前导键的快捷键，其中 `ctrl+x` 是默认前导键。[了解更多](/docs/keybinds)。
以下是所有可用的斜杠命令：
@@ -71,7 +71,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
### connect
将提供商添加到 opencode。你可以从可用提供商中选择，并添加它们的 API 密钥。
将提供商添加到 OpenCode。允许您从可用的提供商中选择并添加其 API 密钥。
```bash frame="none"
/connect
@@ -93,7 +93,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
### details
切换工具执行详细信息。
切换工具执行详情的显示。
```bash frame="none"
/details
@@ -105,7 +105,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
### editor
开启外部编辑器来编写消息。使用`EDITOR`环境变量中设定的编辑器。 [了解更多](#editor-setup)。
打开外部编辑器来编写消息。使用 `EDITOR` 环境变量中设置的编辑器。[了解更多](#editor-setup)。
```bash frame="none"
/editor
@@ -117,7 +117,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
### exit
退出opencode。 _别名_：`/quit`、`/q`
退出 OpenCode。_别名_：`/quit`、`/q`
```bash frame="none"
/exit
@@ -129,7 +129,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
### export
将当前对话汇出到 Markdown 并在默认编辑器中开启。使用 `EDITOR` 环境变数中设定的编辑器。 [了解更多](#editor-setup)。
将当前对话导出为 Markdown 并在默认编辑器中打开。使用 `EDITOR` 环境变量中设置的编辑器。[了解更多](#editor-setup)。
```bash frame="none"
/export
@@ -141,7 +141,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
### help
显示帮助对话方块。
显示帮助对话框。
```bash frame="none"
/help
@@ -153,7 +153,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
### init
Create or update `AGENTS.md` file. [Learn more](/docs/rules).
创建或更新 `AGENTS.md` 文件。[了解更多](/docs/rules)。
```bash frame="none"
/init
@@ -189,14 +189,13 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
### redo
删除之前重做消除的讯息。仅在使用`/undo`后可用。
重做之前撤销的消息。仅在使用 `/undo` 后可用。
:::tip
任何文件更改也将被恢复。
所有文件更改也会被恢复。
:::
在内部，这使用 Git 来管理文件更改。所以你的专案**需要
是一个Git存储库**。
在内部，这使用 Git 来管理文件更改。因此您的项目**需要是一个 Git 仓库**。
```bash frame="none"
/redo
@@ -208,7 +207,7 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
### sessions
上市会话并在会话之间切换。 _别名_：`/resume`、`/continue`
列出会话并在会话之间切换。_别名_：`/resume`、`/continue`
```bash frame="none"
/sessions
@@ -220,7 +219,7 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
### share
共享当前会话。 [了解更多](/docs/share)。
分享当前会话。[了解更多](/docs/share)。
```bash frame="none"
/share
@@ -232,7 +231,7 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
### themes
列出可用的主题。
列出可用主题。
```bash frame="none"
/theme
@@ -244,10 +243,10 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
### thinking
切换对话中 thinking/reasoning 块的可视性。启用后，您可以看到支持扩展思考的模型的推理过程。
切换对话中思考/推理块的可见性。启用后，您可以看到支持扩展思考的模型的推理过程。
:::note
该命令仅控制是否**显示** - 不启用或取消模型的推理功能。要切换实际推理功能，请使用 `ctrl+t` 回圈切换模型变体。
此命令仅控制思考块是否**显示** — 它不会启用或禁用模型的推理能力。要切换实际的推理能力，请使用 `ctrl+t` 循环切换模型变体。
:::
```bash frame="none"
@@ -258,14 +257,13 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
### undo
撤消对话中的最后一条消息。删除最近的用户消息、所有后续响应以及任何文件更改。
撤销对话中的最后一条消息。移除最近的用户消息、所有后续响应以及所有文件更改。
:::tip
所做的任何文件更改也将被恢复。
所做的任何文件更改也会被还原。
:::
在内部，这使用 Git 来管理文件更改。所以你的专案**需要
是一个Git存储库**。
在内部，这使用 Git 来管理文件更改。因此您的项目**需要是一个 Git 仓库**。
```bash frame="none"
/undo
@@ -277,7 +275,7 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
### unshare
取消共享当前会话。 [了解更多](/docs/share#un-sharing)。
取消分享当前会话。[了解更多](/docs/share#un-sharing)。
```bash frame="none"
/unshare
@@ -301,8 +299,8 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
export EDITOR="code --wait"
```
要使其永久存在，请将其添加到您的 shell 配置文件中；
`~/.bashrc`、`~/.zshrc` 等
要使其永久生效，请将其添加到您的 shell 配置文件中；
`~/.bashrc`、`~/.zshrc` 等。
</TabItem>
@@ -315,8 +313,7 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
set EDITOR=code --wait
```
要使其永久化，请使用 **系统属性** > **环境
变量**。
要使其永久生效，请使用**系统属性** > **环境变量**。
</TabItem>
@@ -329,33 +326,33 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
$env:EDITOR = "code --wait"
```
要使其永久化，请将其添加到您的 PowerShell 配置文件中。
要使其永久生效，请将其添加到您的 PowerShell 配置文件中。
</TabItem>
</Tabs>
流行的编辑器选项包括：
常用的编辑器选项包括：
- `code` - Visual Studio Code
- `cursor` - 游标
- `windsurf` - 风帆冲浪
- `cursor` - Cursor
- `windsurf` - Windsurf
- `nvim` - Neovim 编辑器
- `vim` - Vim 编辑器
- `nano` - 奈米编辑器
- `notepad` - Windows 文章书
- `subl` - 崇高文字
- `nano` - Nano 编辑器
- `notepad` - Notepad（Windows 记事本）
- `subl` - Sublime Text
:::note
一些编辑器如 VS Code 需要以 `--wait` 标志启动。
某些编辑器（如 VS Code）需要以 `--wait` 标志启动。
:::
某些编辑器需要命令列参数才能在阻止模式下执行。 `--wait` 标志使编辑器程序阻塞直至关闭。
某些编辑器需要命令行参数才能以阻塞模式运行。`--wait` 标志使编辑器进程阻塞直到关闭。
---
## 配置
您可以使用 opencode 配置文件自定义 TUI 行为。
您可以通过 OpenCode 配置文件自定义 TUI 行为。
```json title="opencode.json"
{
@@ -371,20 +368,20 @@ Create or update `AGENTS.md` file. [Learn more](/docs/rules).
### 选项
- `scroll_acceleration` - 启用 macOS 式滚动加速以实现平滑、自然的滚动。启用后，滚动速度会随着快速滚动滚动而增加，并在较慢的移动时保持精确。 **此设定优先于 `scroll_speed` 并在启用时覆盖它。 **
- `scroll_speed` - 控制使用滚动控制器时 TUI 滚动的速度（简单：`1`）。默认为 `3`。 **注意：如果 `scroll_acceleration.enabled` 设置为 `true`，则忽略此设置。 **
- `scroll_acceleration` - 启用 macOS 风格的滚动加速，实现平滑、自然的滚动体验。启用后，快速滚动时速度会增加，慢速移动时保持精确。**此设置优先于 `scroll_speed`，启用时会覆盖它。**
- `scroll_speed` - 控制使用滚动命令时 TUI 的滚动速度（最小值：`1`）。默认为 `3`。**注意：如果 `scroll_acceleration.enabled` 设置为 `true`，则此设置会被忽略。**
---
## 自定义
您可以使用命令选项板（`ctrl+x h` 或 `/help`）自定义 TUI 查看的各个方面。这些设置在重新启动后仍然存在。
您可以使用命令面板（`ctrl+x h` 或 `/help`）自定义 TUI 视图的各个方面。这些设置在重启后仍会保留。
---
#### 用户名称显示
#### 用户名显示
切换您的用户名称是否出现在聊天消息中。通过以下方式访问：
切换您的用户名是否显示在聊天消息中。通过以下方式访问：
- 命令面板：搜索“用户名称”或“隐藏用户名称”
- 该设置会自动保留，放在 TUI 会话中被记住
- 命令面板：搜索 "username" 或 "hide username"
- 该设置会自动保存，并在各个 TUI 会话中保持记忆

62
packages/web/src/content/docs/zh-cn/web.mdx
View File

@@ -1,39 +1,39 @@
---
title: Web
description: 在浏览器中使用opencode。
description: 在浏览器中使用 OpenCode。
---
opencode 可以在浏览器中作为 Web 应用程序执行，消耗终端可以提供同样强大的 AI 编码体验。
OpenCode 可以作为 Web 应用在浏览器中运行，无需终端即可获得同样强大的 AI 编码体验。
![opencode Web - New Session](../../../assets/web/web-homepage-new-session.png)
![OpenCode Web - New Session](../../../assets/web/web-homepage-new-session.png)
## 入门
## 快速开始
绕过执行以下命令启动 Web 简介：
运行以下命令启动 Web 界面：
```bash
opencode web
```
这将在 `127.0.0.1` 上启动一个具有随机可用端口的本地服务器，并自动在默认浏览器中开启 opencode。
这会在 `127.0.0.1` 上启动一个本地服务器，使用随机可用端口，并自动在默认浏览器中打开 OpenCode。
:::caution
如果未设置`OPENCODE_SERVER_PASSWORD`，服务器将不安全。这对于本地使用来说很好，但应该针对网路访问进行设置。
如果未设置 `OPENCODE_SERVER_PASSWORD`，服务器将没有安全保护。本地使用没有问题，但在网络访问时应当设置密码。
:::
:::tip[Windows 用户]
For the best experience, run `opencode web` from [WSL](/docs/windows-wsl) rather than PowerShell. This ensures proper file system access and terminal integration.
为获得最佳体验，建议从 [WSL](/docs/windows-wsl) 而非 PowerShell 运行 `opencode web`。这可以确保正确的文件系统访问和终端集成。
:::
---
## 配置
您可以使用命令行标志或在[config file](/docs/config).conf 中配置Web服务器。
你可以通过命令行标志或[配置文件](/docs/config)来配置 Web 服务器。
### 端口
默认情况下，opencode 选择一个可用的端口。您可以指定一个端口：
默认情况下，OpenCode 会选择一个可用端口。你也可以指定端口：
```bash
opencode web --port 4096
@@ -41,13 +41,13 @@ opencode web --port 4096
### 主机名
默认情况下，服务器绑定到`127.0.0.1`（仅限本地主机）。要使opencode在您的网路上可访问：
默认情况下，服务器绑定到 `127.0.0.1`（仅限本地访问）。要使 OpenCode 在网络中可访问：
```bash
opencode web --hostname 0.0.0.0
```
使用`0.0.0.0`时，opencode将显示本地地址和网络地址：
使用 `0.0.0.0` 时，OpenCode 会同时显示本地地址和网络地址：
```
Local access: http://localhost:4096
@@ -56,15 +56,15 @@ opencode web --hostname 0.0.0.0
### mDNS 发现
启用 mDNS 使您的服务器在本地网上可以发现：
启用 mDNS 可以让你的服务器在本地网络中被自动发现：
```bash
opencode web --mdns
```
This automatically sets the hostname to `0.0.0.0` and advertises the server as `opencode.local`.
这会自动将主机名设置为 `0.0.0.0`，并将服务器广播为 `opencode.local`。
您可以自定义 mDNS 域名以在同一网路上执行多个示例：
你可以自定义 mDNS 域名，以便在同一网络中运行多个实例：
```bash
opencode web --mdns --mdns-domain myproject.local
@@ -72,61 +72,61 @@ opencode web --mdns --mdns-domain myproject.local
### CORS
允许CORS使用其他域（对于自定义前缀有用）：
要为 CORS 添加额外的允许域名（适用于自定义前端）：
```bash
opencode web --cors https://example.com
```
### 验证
### 身份验证
要保护访问，请使用 `OPENCODE_SERVER_PASSWORD` 环境变量设置密码：
要保护服务器访问，可以通过 `OPENCODE_SERVER_PASSWORD` 环境变量设置密码：
```bash
OPENCODE_SERVER_PASSWORD=secret opencode web
```
The username defaults to `opencode` but can be changed with `OPENCODE_SERVER_USERNAME`.
用户名默认为 `opencode`，可以通过 `OPENCODE_SERVER_USERNAME` 进行更改。
---
## 使用web界面
## 使用 Web 界面
启动后，web界面将提供对您的 opencode 会话的访问。
启动后，Web 界面提供对 OpenCode 会话的访问。
### 会话
从主页查看和管理您的会话。您可以查看活动会话并开始新会话。
在主页上查看和管理你的会话。你可以查看活跃的会话，也可以创建新的会话。
![opencode Web - Active Session](../../../assets/web/web-homepage-active-session.png)
![OpenCode Web - Active Session](../../../assets/web/web-homepage-active-session.png)
### 服务器状态
单击“查看服务器”可查看连接的服务器及其状态。
点击"See Servers"可以查看已连接的服务器及其状态。
![opencode Web - See Servers](../../../assets/web/web-homepage-see-servers.png)
![OpenCode Web - See Servers](../../../assets/web/web-homepage-see-servers.png)
---
## 连接终端
您可以将终端 TUI 连线到正在执行的 Web 服务器：
你可以将终端 TUI 连接到正在运行的 Web 服务器：
```bash
# Start the web server
# 启动 Web 服务器
opencode web --port 4096
# In another terminal, attach the TUI
# 在另一个终端中连接 TUI
opencode attach http://localhost:4096
```
这允许您同时使用 Web 界面和终端，共享相同的会话和状态。
这样你就可以同时使用 Web 界面和终端，共享相同的会话和状态。
---
## 配置文件
You can also configure server settings in your `opencode.json` config file:
你也可以在 `opencode.json` 配置文件中设置服务器选项：
```json
{
@@ -139,4 +139,4 @@ You can also configure server settings in your `opencode.json` config file:
}
```
命令行标志优先于配置文件设置。
命令行标志的优先级高于配置文件中的设置。

59
packages/web/src/content/docs/zh-cn/windows-wsl.mdx
View File

@@ -1,37 +1,37 @@
---
title: Windows (WSL)
description: 在 Windows 上通过 WSL 使用 opencode。
description: 通过 WSL 在 Windows 上运行 OpenCode 以获得最佳体验。
---
import { Steps } from "@astrojs/starlight/components"
虽然 opencode 可以直接在 Windows 上运行，但为了获得最佳体验，我们推荐使用 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install)。WSL 提供了一个与 opencode 功能无缝协作的 Linux 环境。
虽然 OpenCode 可以直接在 Windows 上运行，但我们推荐使用 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) 以获得最佳体验。WSL 提供了一个 Linux 环境，能够与 OpenCode 的各项功能无缝配合。
:::tip[为什么使用 WSL？]
WSL 提供更好的文件系统性能、完整的终端支持，以及与 opencode 依赖的开发工具的兼容性。
:::tip[为什么选择 WSL？]
WSL 提供更出色的文件系统性能、完整的终端支持，以及与 OpenCode 所依赖的开发工具的良好兼容性。
:::
---
## 设置
## 安装配置
<Steps>
1. **安装 WSL**
如果你还没有安装，请按照 Microsoft 官方指南 [安装 WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。
如果尚未安装，请参照 Microsoft 官方指南[安装 WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。
2. **在 WSL 中安装 opencode**
2. **在 WSL 中安装 OpenCode**
完成 WSL 设置后，打开 WSL 终端并使用任一[安装方式](/docs/)安装 opencode。
WSL 设置完成后，打开 WSL 终端，使用任一[安装方式](/docs/)安装 OpenCode。
```bash
curl -fsSL https://opencode.ai/install | bash
```
3. **从 WSL 使用 opencode**
3. **从 WSL 中使用 OpenCode**
进入你的项目目录（可通过 `/mnt/c/`、`/mnt/d/` 等访问 Windows 文件）并运行 opencode。
导航到你的项目目录（通过 `/mnt/c/`、`/mnt/d/` 等路径访问 Windows 文件），然后运行 OpenCode。
```bash
cd /mnt/c/Users/YourName/project
@@ -44,54 +44,53 @@ WSL 提供更好的文件系统性能、完整的终端支持，以及与 openco
## 桌面应用 + WSL 服务器
如果你想使用 opencode 桌面应用，但希望在 WSL 中运行服务器：
如果你希望使用 OpenCode 桌面应用，同时在 WSL 中运行服务器：
1. **在 WSL 中启动服务器**，并使用 `--hostname 0.0.0.0` 以允许外部连接：
1. **在 WSL 中启动服务器**，添加 `--hostname 0.0.0.0` 以允许外部连接：
```bash
opencode serve --hostname 0.0.0.0 --port 4096
```
2. **将桌面应用连接到** `http://localhost:4096`
2. **在桌面应用中连接到** `http://localhost:4096`
:::note
如果你的环境中 `localhost` 不可用，请改用 WSL 的 IP 地址连接（在 WSL 中执行：`hostname -I`），并使用 `http://<wsl-ip>:4096`。
如果 `localhost` 在你的环境中无法使用，请改用 WSL 的 IP 地址进行连接（在 WSL 中运行：`hostname -I`），使用 `http://<wsl-ip>:4096`。
:::
:::caution
使用 `--hostname 0.0.0.0` 时，请设置 `OPENCODE_SERVER_PASSWORD` 来保护服务器。
使用 `--hostname 0.0.0.0` 时，请设置 `OPENCODE_SERVER_PASSWORD` 以保护服务器安全。
:::
```bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve --hostname 0.0.0.0
```
:::
---
## Web 客户端 + WSL
在 Windows 上获得最佳 Web 体验：
要在 Windows 上获得最佳的 Web 体验：
1. **请在 WSL 终端中运行 `opencode web`**，而不是在 PowerShell 中运行：
1. **在 WSL 终端中运行 `opencode web`**，而非在 PowerShell 中运行：
```bash
opencode web --hostname 0.0.0.0
```
2. **在 Windows 浏览器中访问** `http://localhost:<port>`（opencode 会打印该 URL）
2. **在 Windows 浏览器中访问** `http://localhost:<port>`（OpenCode 会输出该 URL）
从 WSL 运行 `opencode web` 可以确保正确的文件系统访问和终端集成，同时仍可在 Windows 浏览器中访问。
从 WSL 中运行 `opencode web` 可确保正确的文件系统访问和终端集成，同时仍可通过 Windows 浏览器进行访问。
---
## 访问 Windows 文件
WSL 可以通过 `/mnt/` 目录访问你所有的 Windows 文件：
WSL 可以通过 `/mnt/` 目录访问你的所有 Windows 文件：
- `C:` drive → `/mnt/c/`
- `D:` drive → `/mnt/d/`
- 其他盘符同理
- `C:` 盘 → `/mnt/c/`
- `D:` 盘 → `/mnt/d/`
- 其他盘符以此类推...
示例：
@@ -101,13 +100,13 @@ opencode
```
:::tip
为了获得更流畅的体验，建议将仓库克隆或复制到 WSL 文件系统中（例如 `~/code/`），并在那里运行 opencode。
为了获得更流畅的体验，建议将仓库克隆或复制到 WSL 文件系统中（例如 `~/code/` 目录下），然后在该位置运行 OpenCode。
:::
---
## 提示
## 使用技巧
- 即使项目存放在 Windows 盘符中，也建议在 WSL 中运行 opencode，文件访问会更顺畅
- 可将 opencode 与 VS Code 的 [WSL 扩展](https://code.visualstudio.com/docs/remote/wsl)配合使用，形成一体化开发流程
- opencode 的配置和会话会保存在 WSL 环境中的 `~/.local/share/opencode/`
- 对于存储在 Windows 驱动器上的项目，在 WSL 中运行 OpenCode 即可无缝访问文件
- 搭配 VS Code 的 [WSL 扩展](https://code.visualstudio.com/docs/remote/wsl) 使用 OpenCode，打造一体化的开发工作流
- OpenCode 的配置和会话数据存储在 WSL 环境中的 `~/.local/share/opencode/`

205
packages/web/src/content/docs/zh-cn/zen.mdx
View File

@@ -1,6 +1,6 @@
---
title: Zen
description: 由 opencode 提供的精选模型列表。
description: 由 OpenCode 提供的精选模型列表。
---
import config from "../../../../config.mjs"
@@ -13,56 +13,47 @@ OpenCode Zen 是由 OpenCode 团队提供的一组经过测试和验证的模型
OpenCode Zen 目前处于测试阶段。
:::
Zen 的工作方式与 opencode 中的任何其他提供商相同。您登录 OpenCode Zen 并获得
你的API钥匙。它是**完全可选的**，你不需要使用它即可使用
opencode。
Zen 的工作方式与 OpenCode 中的任何其他提供商相同。你只需登录 OpenCode Zen 并获取你的 API 密钥。它是**完全可选的**，你无需使用它也能正常使用 OpenCode。
---
## 背景
市面上有很多模型，但其中只有少数几个
这些模型可以很好地用作编码代理。此外，大多数提供商都
配置非常不同；所以你会得到截然不同的效率和质量。
市面上有大量的模型，但其中只有少数能够很好地充当编码代理。此外，大多数提供商的配置方式差异很大，因此你获得的性能和质量也会截然不同。
:::tip
我们测试了一组与 opencode 配合良好的模型并提供商。
我们测试了一组与 OpenCode 配合良好的精选模型和提供商。
:::
因此，如果您通过 OpenRouter 之类的东西使用模型，您永远无法
确定您是否获得了您想要的模型的最佳版本。
所以如果你通过 OpenRouter 之类的服务使用模型，你永远无法确定是否获得了你想要的模型的最佳版本。
为了解决这个问题，我们做了几件事：
为了解决这个问题，我们做了以下几件事：
1. 我们测试了一组选定的模型，并与他们的团队讨论了如何
最好执行它们。
2. 然后我们与一些提供商合作以确保这些服务得到服务
正确。
3. 最后，我们对 model/provider 的组合进行了基准测试，总结了
并附上一份我们觉得不错的推荐清单。
1. 我们测试了一组精选的模型，并与它们的团队讨论了最佳运行方式。
2. 然后我们与几家提供商合作，确保这些模型能被正确地提供服务。
3. 最后，我们对模型与提供商的组合进行了基准测试，整理出了一份我们有信心推荐的列表。
OpenCode Zen 是一个AI网关，让您可以访问这些模型。
OpenCode Zen 是一个 AI 网关，让你可以访问这些模型。
---
## 它是如何运作的
## 工作原理
OpenCode Zen 的工作方式与 opencode 中的任何其他功能相同。
OpenCode Zen 的工作方式与 OpenCode 中的任何其他提供商相同。
1. 您登录 **<a href={console}>OpenCode Zen</a>**，添加您的账单
详细信息，然后复制您的 API 密钥。
2. 您在 TUI 中执行 `/connect` 命令，选择 OpenCode Zen，然后贴上 API 密钥。
3. 在 TUI 中执行 `/models` 以查看我们推荐的模型列表。
1. 登录 **<a href={console}>OpenCode Zen</a>**，添加你的账单信息，然后复制你的 API 密钥。
2. 在 TUI 中运行 `/connect` 命令，选择 OpenCode Zen，然后粘贴你的 API 密钥。
3. 在 TUI 中运行 `/models` 查看我们推荐的模型列表。
您需要按请求付费，并且您可以将积分添加到您的账户中。
你按请求付费，并且可以向你的账户中充值。
---
## 端点
您还可以通过以下 API 端点访问我们的模型。
你还可以通过以下 API 端点访问我们的模型。
| 模型 | 模型ID | 端点 | AI SDK 套件 |
| 模型 | 模型 ID | 端点 | AI SDK 包 |
| ------------------ | ------------------ | -------------------------------------------------- | --------------------------- |
| GPT 5.2 | gpt-5.2 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
| GPT 5.2 Codex | gpt-5.2-codex | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
@@ -82,10 +73,11 @@ OpenCode Zen 的工作方式与 opencode 中的任何其他功能相同。
| Claude Opus 4.1 | claude-opus-4-1 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
| Gemini 3 Pro | gemini-3-pro | `https://opencode.ai/zen/v1/models/gemini-3-pro` | `@ai-sdk/google` |
| Gemini 3 Flash | gemini-3-flash | `https://opencode.ai/zen/v1/models/gemini-3-flash` | `@ai-sdk/google` |
| MiniMax M2.5 | minimax-m2.5 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| MiniMax M2.5 Free | minimax-m2.5-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| MiniMax M2.1 | minimax-m2.1 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| MiniMax M2.1 Free | minimax-m2.1-free | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
| GLM 5 | glm-5 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| GLM 4.7 | glm-4.7 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| GLM 4.7 Free | glm-4.7-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| GLM 4.6 | glm-4.6 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| Kimi K2.5 | kimi-k2.5 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| Kimi K2.5 Free | kimi-k2.5-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
@@ -94,15 +86,13 @@ OpenCode Zen 的工作方式与 opencode 中的任何其他功能相同。
| Qwen3 Coder 480B | qwen3-coder | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| Big Pickle | big-pickle | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
opencode 配置中的 [model id](/docs/config/#models)
uses the format `opencode/<model-id>`. For example, for GPT 5.2 Codex, you would
use `opencode/gpt-5.2-codex` in your config.
在 OpenCode 配置中，[模型 ID](/docs/config/#models) 使用 `opencode/<model-id>` 格式。例如，对于 GPT 5.2 Codex，你需要在配置中使用 `opencode/gpt-5.2-codex`。
---
### 模型
您可以从以下位置获取可用模型及其元数据的完整列表：
你可以从以下地址获取可用模型及其元数据的完整列表：
```
https://opencode.ai/zen/v1/models
@@ -112,142 +102,135 @@ https://opencode.ai/zen/v1/models
## 定价
我们支持即用即付模式。以下是**每 100 万Tokens的价格**。
我们支持按量付费模式。以下是**每 100 万 Token** 的价格。
| 模型 | 输入 | 输出 | 缓存读取 | 缓存写入 |
| ---------------------------------- | ---------- | ---------- | ---------- | ---------- |
| -------------------------------- | ------ | ------ | -------- | -------- |
| Big Pickle | 免费 | 免费 | 免费 | - |
| MiniMax M2.1 Free | 免费 | 免费 | 免费 | - |
| MiniMax M2.1 | 0.30 美元 | 1.20 美元 | 0.10 美元 | - |
| GLM 4.7 Free | 免费 | 免费 | 免费 | - |
| GLM 4.7 | 0.60 美元 | 2.20 美元 | 0.10 美元 | - |
| GLM 4.6 | 0.60 美元 | 2.20 美元 | 0.10 美元 | - |
| MiniMax M2.5 Free | 免费 | 免费 | 免费 | - |
| MiniMax M2.5 | $0.30 | $1.20 | $0.06 | - |
| MiniMax M2.1 | $0.30 | $1.20 | $0.10 | - |
| GLM 5 | $1.00 | $3.20 | $0.20 | - |
| GLM 4.7 | $0.60 | $2.20 | $0.10 | - |
| GLM 4.6 | $0.60 | $2.20 | $0.10 | - |
| Kimi K2.5 Free | 免费 | 免费 | 免费 | - |
| Kimi K2.5 | 0.60 美元 | 3.00 美元 | 0.08 美元 | - |
| Kimi K2 Thinking | 0.40 美元 | 2.50 美元 | - | - |
| Kimi K2 | 0.40 美元 | 2.50 美元 | - | - |
| Qwen3 Coder 480B | 0.45 美元 | 1.50 美元 | - | - |
| Claude Sonnet 4.5（≤ 200K Tokens） | 3.00 美元 | 15.00 美元 | 0.30 美元 | 3.75 美元 |
| Claude Sonnet 4.5（> 200K Tokens） | 6.00 美元 | 22.50 美元 | 0.60 美元 | 7.50 美元 |
| Claude Sonnet 4（≤ 200K Tokens） | 3.00 美元 | 15.00 美元 | 0.30 美元 | 3.75 美元 |
| Claude Sonnet 4（> 200K Tokens） | 6.00 美元 | 22.50 美元 | 0.60 美元 | 7.50 美元 |
| Claude Haiku 4.5 | 1.00 美元 | 5.00 美元 | 0.10 美元 | 1.25 美元 |
| Claude Haiku 3.5 | 0.80 美元 | 4.00 美元 | 0.08 美元 | 1.00 美元 |
| Claude Opus 4.6（≤ 200K Tokens） | 5.00 美元 | 25.00 美元 | 0.50 美元 | 6.25 美元 |
| Claude Opus 4.6（> 200K Tokens） | 10.00 美元 | 37.50 美元 | 1.00 美元 | 12.50 美元 |
| Claude Opus 4.5 | 5.00 美元 | 25.00 美元 | 0.50 美元 | 6.25 美元 |
| Claude Opus 4.1 | 15.00 美元 | 75.00 美元 | 1.50 美元 | 18.75 美元 |
| Gemini 3 Pro（≤20万 Tokens） | 2.00 美元 | 12.00 美元 | 0.20 美元 | - |
| Gemini 3 Pro（>20万 Tokens） | 4.00 美元 | 18.00 美元 | 0.40 美元 | - |
| Gemini 3 Flash | 0.50 美元 | 3.00 美元 | 0.05 美元 | - |
| GPT 5.2 | 1.75 美元 | 14.00 美元 | 0.175 美元 | - |
| GPT 5.2 Codex | 1.75 美元 | 14.00 美元 | 0.175 美元 | - |
| GPT 5.1 | 1.07 美元 | 8.50 美元 | 0.107 美元 | - |
| GPT 5.1 Codex | 1.07 美元 | 8.50 美元 | 0.107 美元 | - |
| GPT 5.1 Codex Max | 1.25 美元 | 10.00 美元 | 0.125 美元 | - |
| GPT 5.1 Codex Mini | 0.25 美元 | 2.00 美元 | 0.025 美元 | - |
| GPT 5 | 1.07 美元 | 8.50 美元 | 0.107 美元 | - |
| GPT 5 Codex | 1.07 美元 | 8.50 美元 | 0.107 美元 | - |
| Kimi K2.5 | $0.60 | $3.00 | $0.08 | - |
| Kimi K2 Thinking | $0.40 | $2.50 | - | - |
| Kimi K2 | $0.40 | $2.50 | - | - |
| Qwen3 Coder 480B | $0.45 | $1.50 | - | - |
| Claude Sonnet 4.5 (≤ 200K Token) | $3.00 | $15.00 | $0.30 | $3.75 |
| Claude Sonnet 4.5 (> 200K Token) | $6.00 | $22.50 | $0.60 | $7.50 |
| Claude Sonnet 4 (≤ 200K Token) | $3.00 | $15.00 | $0.30 | $3.75 |
| Claude Sonnet 4 (> 200K Token) | $6.00 | $22.50 | $0.60 | $7.50 |
| Claude Haiku 4.5 | $1.00 | $5.00 | $0.10 | $1.25 |
| Claude Haiku 3.5 | $0.80 | $4.00 | $0.08 | $1.00 |
| Claude Opus 4.6 (≤ 200K Token) | $5.00 | $25.00 | $0.50 | $6.25 |
| Claude Opus 4.6 (> 200K Token) | $10.00 | $37.50 | $1.00 | $12.50 |
| Claude Opus 4.5 | $5.00 | $25.00 | $0.50 | $6.25 |
| Claude Opus 4.1 | $15.00 | $75.00 | $1.50 | $18.75 |
| Gemini 3 Pro (≤ 200K Token) | $2.00 | $12.00 | $0.20 | - |
| Gemini 3 Pro (> 200K Token) | $4.00 | $18.00 | $0.40 | - |
| Gemini 3 Flash | $0.50 | $3.00 | $0.05 | - |
| GPT 5.2 | $1.75 | $14.00 | $0.175 | - |
| GPT 5.2 Codex | $1.75 | $14.00 | $0.175 | - |
| GPT 5.1 | $1.07 | $8.50 | $0.107 | - |
| GPT 5.1 Codex | $1.07 | $8.50 | $0.107 | - |
| GPT 5.1 Codex Max | $1.25 | $10.00 | $0.125 | - |
| GPT 5.1 Codex Mini | $0.25 | $2.00 | $0.025 | - |
| GPT 5 | $1.07 | $8.50 | $0.107 | - |
| GPT 5 Codex | $1.07 | $8.50 | $0.107 | - |
| GPT 5 Nano | 免费 | 免费 | 免费 | - |
您可能会在您的使用历史记录中注意到*Claude Haiku 3.5*。这是一个[低成本模型](/docs/config/#models)，用于生成会话标题。
你可能会在使用记录中看到 _Claude Haiku 3.5_。这是一个[低成本模型](/docs/config/#models)，用于生成会话标题。
:::note
信用卡费用按成本转嫁（4.4% + 每笔交易 0.30 美元）；除此之外我们不收取任何费用。
信用卡手续费按成本转嫁（每笔交易 4.4% + $0.30）；除此之外我们不收取任何额外费用。
:::
免费模型：
免费模型说明：
- GLM 4.7 免费版本在 opencode 上限时提供。团队正在利用这段时间收集反馈并改进模型。
- Kimi K2.5 在 opencode 限时免费发布。团队正在利用这段时间收集反馈并改进模型。
- MiniMax M2.1 在 opencode 限时免费供应。团队正在利用这段时间收集反馈并改进模型。
- Big Pickle 是一个隐形模型，在 opencode 上限时免费。团队正在利用这个临时收集反馈并改进模型。
- Kimi K2.5 Free 在 OpenCode 上限时免费提供。团队正在利用这段时间收集反馈并改进模型。
- MiniMax M2.5 Free 在 OpenCode 上限时免费提供。团队正在利用这段时间收集反馈并改进模型。
- Big Pickle 是一个隐身模型，在 OpenCode 上限时免费提供。团队正在利用这段时间收集反馈并改进模型。
<a href={email}>如果您有任何疑问，请联络我们</a>。
如有任何疑问，请<a href={email}>联系我们</a>。
---
### 自动重新载入
### 自动充值
如果您的余额低于 5 美元，Zen 将自动充值 20 美元。
如果你的余额低于 $5，Zen 将自动充值 $20。
您可以更改自动充值金额。您还可以完全禁用自动重新载入。
你可以更改自动充值的金额，也可以完全禁用自动充值功能。
---
### 每月限额
### 月度限额
您还可以为整个工作区和每个工作区设置每月使用限制
你的团队成员。
你还可以为整个工作区以及团队中的每个成员设置月度使用限额。
例如，假设您将每月使用中断设置为 20 美元，Zen 将不会使用
一个月超过 20 美元。但如果你启用了自动重新加载，Zen 可能会结束
如果您的余额低于 5 美元，则向您收取超过 20 美元的费用。
例如，假设你将月度使用限额设为 $20，Zen 在一个月内的使用量将不会超过 $20。但如果你启用了自动充值，当余额低于 $5 时，Zen 可能会向你收取超过 $20 的费用。
---
## 隐私
我们所有的模型都在美国托管。我们的提供商遵循零保留政策，不会将您的数据用于模型训练，但以下情况除外：
我们所有的模型都托管在美国。我们的提供商遵循零保留政策，不会将你的数据用于模型训练，但以下情况除外：
- Big Pickle：在免费期间，收集可用于改进模型的数据。
- GLM 4.7 免费：在免费期间，收集可用于改进模型的数据。
- Kimi K2.5 免费：在免费期间，收集可用于改进模型的数据。
- MiniMax M2.1 免费：在免费期间，收集可用于改进模型的数据。
- OpenAI APIs: Requests are retained for 30 days in accordance with [OpenAI's Data Policies](https://platform.openai.com/docs/guides/your-data).
- Anthropic APIs: Requests are retained for 30 days in accordance with [Anthropic's Data Policies](https://docs.anthropic.com/en/docs/claude-code/data-usage).
- Big Pickle：在免费期间，收集的数据可能会被用于改进模型。
- Kimi K2.5 Free：在免费期间，收集的数据可能会被用于改进模型。
- MiniMax M2.5 Free：在免费期间，收集的数据可能会被用于改进模型。
- OpenAI API：请求会根据 [OpenAI 数据政策](https://platform.openai.com/docs/guides/your-data)保留 30 天。
- Anthropic API：请求会根据 [Anthropic 数据政策](https://docs.anthropic.com/en/docs/claude-code/data-usage)保留 30 天。
---
## 对于团队
## 团队版
Zen 也非常适合团队使用。您可以邀请您可以邀请队友，分配角色，管理团队使用的模型等。
Zen 也非常适合团队使用。你可以邀请队友、分配角色、管理团队使用的模型等。
:::note
作为测试版的一部分，工作空间目前对团队免费。
作为测试版的一部分，工作区功能目前对团队免费开放。
:::
作为测试版的一部分，管理工作空间目前对团队免费。我们将会
很快就会分享更多有关定价的细节。
作为测试版的一部分，管理工作区目前对团队免费。我们将很快公布更多定价详情。
---
### 角色
您可以邀请团队成员到您的工作区并分配角色：
你可以邀请团队成员加入你的工作区并分配角色：
- **管理员**：管理模型、成员、API 密钥和计费/账单
- **管理员**：管理模型、成员、API 密钥和账单
- **成员**：仅管理自己的 API 密钥
管理员还可以为每个成员设置每月支出限额，以控制成本。
管理员还可以为每个成员设置月度支出限额，以控制成本。
---
### 模型访问
管理员可以启用或禁用工作区的特定模型。对禁用模型发出的请求会返回错误。
管理员可以启用或禁用工作区中的特定模型。对已禁用模型发出的请求将返回错误。
这对于您想要禁用以下模型的情况很有帮助：
收集数据。
这在你想要禁用某个会收集数据的模型时非常有用。
---
### 使用你自己的密钥
### 自带密钥
你可以使用自己的 OpenAI 或 Anthropic API 密钥，同时继续使用 Zen 的其他模型。
你可以使用自己的 OpenAI 或 Anthropic API 密钥，同时仍然可以访问 Zen 中的其他模型。
使用你自己的 API 密钥时，Tokens 会直接由对应提供商计费，而不是由 Zen 计费。
当你使用自己的密钥时，Token 费用由提供商直接计费，而非通过 Zen 计费。
例如，你的组织可能已经有 OpenAI 或 Anthropic 的 API 密钥，
你希望优先使用它们，而不是 Zen 提供的密钥。
例如，你的组织可能已经拥有 OpenAI 或 Anthropic 的密钥，你希望使用它们而不是 Zen 提供的密钥。
---
## 为什么使用 Zen
## 目标
我们构建 OpenCode Zen 是为了：
我们创建 OpenCode Zen 的目的是：
1. **基准测试**最适合编码代理的 models/providers。
2. 可以优先使用 **高质量** 选项，而不是被迫降级性能或改用更便宜的提供商。
3. 通过按成本价计费传递任何**降价收益**，额外费用仅为处理费。
4. 通过可与其他编码代理一起使用实现 **无锁定**，你也始终可以把其他提供商与 opencode 组合使用。
1. 为编码代理**基准测试**最佳的模型和提供商组合。
2. 提供**最高质量**的选项，不降低性能或路由到更廉价的提供商。
3. 以成本价销售来传递任何**降价优惠**；唯一的加价仅用于覆盖我们的处理费用。
4. **无锁定**，允许你将其与任何其他编码代理配合使用，同时也始终允许你在 OpenCode 中使用任何其他提供商。

46
packages/web/src/content/docs/zh-tw/acp.mdx
View File

@@ -1,31 +1,31 @@
---
title: ACP 支援
description: 在任何 ACP 相容編輯器中使用 OpenCode。
description: 在任何相容 ACP 的編輯器中使用 OpenCode。
---
OpenCode 支援 [Agent Client Protocol](https://agentclientprotocol.com) 或 (ACP)，允許您直接在相容的編輯器和 IDE 中使用它。
OpenCode 支援 [Agent Client Protocol](https://agentclientprotocol.com)（ACP），允許你直接在相容的編輯器和 IDE 中使用它。
:::tip
有關支援 ACP 的編輯器和工具的列表，請查看 [ACP progress report](https://zed.dev/blog/acp-progress-report#available-now)。
有關支援 ACP 的編輯器和工具列表，請查看 [ACP 進展報告](https://zed.dev/blog/acp-progress-report#available-now)。
:::
ACP 是一種開放協議，用於標準化程式碼編輯器和 AI 程式碼代理之間的通訊。
ACP 是一個開放協議，用於標準化程式碼編輯器與 AI 編碼代理之間的通訊。
---
## 設定
要透過 ACP 使用 OpenCode，請將編輯器設定為執行 `opencode acp` 指令。
要透過 ACP 使用 OpenCode，請在編輯器中設定執行 `opencode acp` 命令。
該指令將 OpenCode 作為 ACP 相容的子程序啟動，透過 stdio 透過 JSON-RPC 與您的編輯器進行通訊。
該命令會將 OpenCode 作為相容 ACP 的子程序啟動，透過 stdio 上的 JSON-RPC 與編輯器進行通訊。
以下是支援 ACP 的流行編輯器的範例。
以下是支援 ACP 的常用編輯器的設定範例。
---
### Zed
新增到您的 [Zed](https://zed.dev) 設定 (`~/.config/zed/settings.json`)：
新增到你的 [Zed](https://zed.dev) 設定檔（`~/.config/zed/settings.json`）中：
```json title="~/.config/zed/settings.json"
{
@@ -38,9 +38,9 @@ ACP 是一種開放協議，用於標準化程式碼編輯器和 AI 程式碼代
}
```
要打開它，請使用 **命令面板** 中的 `agent: new thread` 操作。
開啟方式：在**命令面板**中執行 `agent: new thread` 操作。
您還可以透過編輯 `keymap.json` 來綁定鍵盤快速鍵：
你也可以透過編輯 `keymap.json` 來繫結鍵盤快速鍵：
```json title="keymap.json"
[
@@ -67,9 +67,9 @@ ACP 是一種開放協議，用於標準化程式碼編輯器和 AI 程式碼代
---
### JetBrains IDE
### JetBrains IDEs
根據 [文件](https://www.jetbrains.com/help/ai-assistant/acp.html) 新增到你的 [JetBrains IDE](https://www.jetbrains.com/) acp.json：
根據[文件](https://www.jetbrains.com/help/ai-assistant/acp.html)，將以下內容新增到你的 [JetBrains IDE](https://www.jetbrains.com/) 的 acp.json 中：
```json title="acp.json"
{
@@ -82,13 +82,13 @@ ACP 是一種開放協議，用於標準化程式碼編輯器和 AI 程式碼代
}
```
要打開它，請在 AI Chat 代理選擇器中使用新的「opencode」代理。
開啟方式：在 AI Chat 代理選擇器中選擇新的 'OpenCode' 代理。
---
### Avante.nvim
新增到您的 [Avante.nvim](https://github.com/yetone/avante.nvim) 設定：
新增到你的 [Avante.nvim](https://github.com/yetone/avante.nvim) 設定中：
```lua
{
@@ -121,7 +121,7 @@ ACP 是一種開放協議，用於標準化程式碼編輯器和 AI 程式碼代
### CodeCompanion.nvim
要將 OpenCode 用作 [CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim) 中的 ACP 代理，請將以下內容新增到 Neovim 設定中：
要在 [CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim) 中將 OpenCode 用作 ACP 代理，請將以下內容新增到你的 Neovim 設定中：
```lua
require("codecompanion").setup({
@@ -136,21 +136,21 @@ require("codecompanion").setup({
})
```
此設定將 CodeCompanion 設定為使用 OpenCode 作為聊天的 ACP 代理。
此設定將 CodeCompanion 設為使用 OpenCode 作為聊天的 ACP 代理。
如果您需要傳遞環境變數（如 `OPENCODE_API_KEY`），請參閱 CodeCompanion.nvim 文件中的 [設定適配器：環境變數](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key) 了解完整詳細資訊。
如果需要傳遞環境變數（如 `OPENCODE_API_KEY`），請參閱 CodeCompanion.nvim 文件中的[設定適配器：環境變數](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key)了解詳細資訊。
## 支援
OpenCode 透過 ACP 的工作方式與在終端機中的工作方式相同。支援所有功能：
OpenCode 透過 ACP 使用時與在終端機中使用的效果完全一致。所有功能均受支援：
:::note
目前不支援某些內建斜線指令，例如 `/undo` 和 `/redo`。
部分內建斜線命令（如 `/undo` 和 `/redo`）目前暫不支援。
:::
- 內建工具（檔案操作、終端機指令等）
- 自定義工具和斜線指令
- 內建工具（檔案操作、終端機命令等）
- 自訂工具和斜線命令
- 在 OpenCode 設定中設定的 MCP 伺服器
- `AGENTS.md` 的專案特定規則
- 自定義格式化程式和 linter
- 來自 `AGENTS.md` 的專案級規則
- 自訂格式化工具和程式碼檢查工具
- 代理和權限系統

224
packages/web/src/content/docs/zh-tw/agents.mdx
View File

@@ -3,133 +3,133 @@ title: 代理
description: 設定和使用專門的代理。
---
代理是專門的 AI 助理，可以針對特定任務和工作流程進行設定。它們允許您建立具有自定義提示、模型和工具存取權限的專用工具。
代理是專門的 AI 助手，可以針對特定任務和工作流程進行設定。它們允許您建立具有自訂提示詞、模型和工具存取權限的專用工具。
:::tip
使用計畫代理來分析程式碼並審閱建議，而無需進行任何程式碼變更。
使用 Plan 代理來分析程式碼和審查建議，而不會進行任何程式碼變更。
:::
您可以在工作階段期間在代理之間切換，或使用 `@` 提及來呼叫它們。
您可以在工作階段期間切換代理，或使用 `@` 提及來呼叫它們。
---
## 類型
opencode 中有兩種類型的代理；主要代理和子代理。
OpenCode 中有兩種類型的代理：主代理和子代理。
---
### 主要代理
### 主代理
主要代理是與您直接互動的主要助理。您可以使用 **Tab** 鍵或您設定的 `switch_agent` 鍵綁定循環切換它們。這些代理處理您的主要對話。工具存取是透過權限設定的 - 例如，「Build」啟用了所有工具，而「Plan」則受到限制。
主代理是您直接互動的主要助手。您可以使用 **Tab** 鍵或設定的 `switch_agent` 快速鍵來循環切換它們。這些代理處理您的主要對話。工具存取透過權限進行設定——例如，Build 啟用了所有工具，而 Plan 則受到限制。
:::tip
您可以在工作階段期間使用 **Tab** 鍵在主要代理之間切換。
您可以在工作階段期間使用 **Tab** 鍵在主代理之間切換。
:::
opencode 附帶兩個內建的主要代理：**Build** 和 **Plan**。我們將在下面看看這些。
OpenCode 內建了兩個主代理：**Build** 和 **Plan**。我們將在下面介紹它們。
---
### 子代理
子代理是主要代理可以呼叫來執行特定任務的專業助理。您也可以透過在訊息中 **@提及** 它們來手動呼叫它們。
子代理是主代理可以呼叫來執行特定任務的專業助手。您也可以透過在訊息中 **@ 提及**它們來手動呼叫。
opencode 附帶兩個內建子代理：**General** 和 **Explore**。我們將在下面看看這個。
OpenCode 內建了兩個子代理：**General** 和 **Explore**。我們將在下面介紹它們。
---
## 內建
## 內建代理
opencode 附帶兩個內建主代理和兩個內建子代理。
OpenCode 內建了兩個主代理和兩個子代理。
---
### 使用 Build (構建)
### 使用 Build
_模式_：`primary`
Build 是啟用所有工具的**預設**主要代理。這是用於需要完全存取檔案操作和系統指令的開發工作的標準代理。
Build 是啟用了所有工具的**預設**主代理。這是用於需要完全存取檔案操作和系統命令的開發工作的標準代理。
---
### 使用 Plan (計畫)
### 使用 Plan
_模式_：`primary`
專為規劃和分析而設計的受限代理。我們使用權限系統為您提供更多控制並防止意外變更。
預設情況下，以下所有項均設定為 `ask`：
一個專為規劃和分析設計的受限代理。我們使用權限系統來為您提供更多控制權，並防止意外變更。
預設情況下，以下所有項均設為 `ask`：
- `file edits`：所有寫入、修補和編輯
- `bash`：所有 bash 指令
- `file edits`：所有寫入、補丁和編輯
- `bash`：所有 bash 命令
當您希望 LLM 分析程式碼、建議變更或建立計畫而不對程式碼庫進行任何實際修改時，此代理非常有用。
當您希望 LLM 分析程式碼、建議變更或建立計畫，而不對程式碼庫進行任何實際修改時，此代理非常有用。
---
### 使用 General (一般)
### 使用 General
_模式_：`subagent`
用於研究複雜問題和執行多步驟任務的通用代理。具有完整的工具存取權限（待辦事項除外），因此可以在需要時變更檔案。使用它可以並行執行多個工作單元。
一個用於研究複雜問題和執行多步驟任務的通用代理。擁有完整的工具存取權限（todo 除外），因此可以在需要時修改檔案。可用於並行執行多個工作單元。
---
### 使用 Explore (探索)
### 使用 Explore
_模式_：`subagent`
用於探索程式碼庫的快速唯讀代理。無法修改檔案。當您需要按模式快速尋找檔案、搜尋程式碼中的關鍵字或回答有關程式碼庫的問題時，請使用此功能。
一個用於探索程式碼庫的快速唯讀代理。無法修改檔案。當您需要按模式快速查找檔案、搜尋程式碼中的關鍵字或回答有關程式碼庫的問題時，請使用此代理。
---
### 使用 Compact (壓縮)
### 使用 Compaction
_模式_：`primary`
隱藏的系統代理，將長上下文壓縮為較小的摘要。它會在需要時自動執行，並且無法在 UI 中選擇。
隱藏的系統代理，將長上下文壓縮為較小的摘要。它會在需要時自動執行，且無法在 UI 中選擇。
---
### 使用 Title (標題)
### 使用 Title
_模式_：`primary`
生成短工作階段標題的隱藏系統代理。它會自動執行，並且無法在 UI 中選擇。
隱藏的系統代理，用於產生簡短的工作階段標題。它會自動執行，且無法在 UI 中選擇。
---
### 使用 Summarize (摘要)
### 使用 Summary
_模式_：`primary`
建立工作階段摘要的隱藏系統代理。它會自動執行，並且無法在 UI 中選擇。
隱藏的系統代理，用於建立工作階段摘要。它會自動執行，且無法在 UI 中選擇。
---
## 用法
1. 對於主要代理，請在工作階段期間使用 **Tab** 鍵循環切換它們。您也可以使用設定的 `switch_agent` 鍵綁定。
1. 對於主代理，在工作階段期間使用 **Tab** 鍵循環切換。您也可以使用設定的 `switch_agent` 快速鍵。
2. 可以呼叫子代理：
- **自動**由主要代理根據其描述執行專門任務。
- 透過在訊息中 **@提及** 子代理手動進行。例如：
2. 子代理可以透過以下方式呼叫：
- 由主代理根據其描述**自動**呼叫以執行專門任務。
- 透過在訊息中 **@ 提及**子代理來手動呼叫。例如：
```txt frame="none"
@general help me search for this function
```
3. **工作階段之間導航**：當子代理建立自己的子工作階段時，您可以使用以下指令在父工作階段和所有子工作階段之間導航：
- **\<Leader>+Right**（或您設定的 `session_child_cycle` 鍵綁定）向前循環父級 → 子級 1 → 子級 2 → ... → 父級
- **\<Leader>+Left**（或您設定的 `session_child_cycle_reverse` 鍵綁定）向後循環父級 ← 子級 1 ← 子級 2 ← ... ← 父級
3. **工作階段間導覽**：當子代理建立自己的子工作階段時，您可以使用以下方式在父工作階段和所有子工作階段之間導覽：
- **\<Leader>+Right**（或設定的 `session_child_cycle` 快速鍵）向前循環：父工作階段 → 子工作階段1 → 子工作階段2 → ... → 父工作階段
- **\<Leader>+Left**（或設定的 `session_child_cycle_reverse` 快速鍵）向後循環：父工作階段 ← 子工作階段1 ← 子工作階段2 ← ... ← 父工作階段
這使您可以在主要對話和專門的子代理工作之間無縫切換。
這使您可以在主對話和專門的子代理工作之間無縫切換。
---
## 設定
您可以自定義內建代理或透過設定建立您自己的代理。可以透過兩種方式設定代理：
您可以自訂內建代理或透過設定建立自己的代理。代理可以透過兩種方式進行設定：
---
@@ -178,10 +178,10 @@ _模式_：`primary`
### Markdown
您也可以使用 Markdown 檔案定義代理。將它們放入：
您還可以使用 Markdown 檔案定義代理。將它們放在：
- 全域：`~/.config/opencode/agents/`
- 每個專案：`.opencode/agents/`
- 專案級：`.opencode/agents/`
```markdown title="~/.config/opencode/agents/review.md"
---
@@ -205,19 +205,19 @@ You are in code review mode. Focus on:
Provide constructive feedback without making direct changes.
```
Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理。
Markdown 檔案名稱即為代理名稱。例如，`review.md` 會建立一個名為 `review` 的代理。
---
## 選項
讓我們詳細看看這些設定選項。
讓我們詳細了解這些設定選項。
---
### 描述 (Description)
### 描述
使用 `description` 選項提供代理的作用以及何時使用它的簡要描述。
使用 `description` 選項提供代理的功能及使用場景的簡要描述。
```json title="opencode.json"
{
@@ -233,11 +233,11 @@ Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理
---
### 溫度 (Temperature)
### 溫度
使用 `temperature` 設定控制 LLM 回應的隨機性和創造性。
使用 `temperature` 設定控制 LLM 回應的隨機性和創造力。
較低的值使回應更加集中和確定，而較高的值則增加創造力和可變性。
較低的值使回應更加集中和確定，而較高的值則增加創造力和多樣性。
```json title="opencode.json"
{
@@ -252,11 +252,11 @@ Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理
}
```
溫度值的範圍通常為 0.0 到 1.0：
溫度值通常範圍為 0.0 到 1.0：
- **0.0-0.2**：非常集中且確定的回應，非常適合程式碼分析和規劃
- **0.3-0.5**：具有一定創造力的平衡回應，適合一般開發任務
- **0.6-1.0**：更有創意和多樣化的反應，有助於腦力激盪和探索
- **0.0-0.2**：非常集中和確定性的回應，適合程式碼分析和規劃
- **0.3-0.5**：平衡的回應，兼顧一定創造力，適合一般開發任務
- **0.6-1.0**：更有創造力和多樣性的回應，適合腦力激盪和探索
```json title="opencode.json"
{
@@ -276,15 +276,15 @@ Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理
}
```
如果未指定溫度，opencode 將使用特定於模型的預設值；大多數模型通常為 0，Qwen 模型為 0.55。
如果未指定溫度，OpenCode 將使用模型特定的預設值；大多數模型通常為 0，Qwen 模型為 0.55。
---
### 最大步數 (Steps)
### 最大步數
控制代理在被迫僅使用文字回應之前可以執行的最大代理迭代次數。這允許希望控制成本的使用者對代理操作設定限制。
控制代理在被強制以純文字回應之前可以執行的最大代理迭代次數。這允許希望控制成本的使用者對代理操作設定限制。
如果未設定，代理將繼續迭代，直到模型選擇停止或使用者中斷工作階段。
如果未設定此選項，代理將持續迭代，直到模型選擇停止或使用者中斷工作階段。
```json title="opencode.json"
{
@@ -298,7 +298,7 @@ Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理
}
```
當達到限制時，代理會收到特殊的系統提示，指示其回應其工作摘要和建議的剩餘任務。
當達到限制時，代理會收到一個特殊的系統提示詞，指示其回覆工作摘要和建議的剩餘任務。
:::caution
舊版 `maxSteps` 欄位已棄用。請改用 `steps`。
@@ -306,9 +306,9 @@ Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理
---
### 禁用 (Disable)
### 停用
設定為 `true` 以禁用代理。
設為 `true` 以停用代理。
```json title="opencode.json"
{
@@ -322,9 +322,9 @@ Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理
---
### 提示 (Prompt)
### 提示詞
使用 `prompt` 設定為此代理指定自定義系統提示檔案。提示檔案應包含特定於代理目的的說明。
使用 `prompt` 設定為代理指定自訂系統提示詞檔案。提示詞檔案應包含針對代理用途的具體指令。
```json title="opencode.json"
{
@@ -336,16 +336,16 @@ Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理
}
```
該路徑是相對於設定檔所在位置的。因此，這適用於全域 opencode 設定和專案特定設定。
此路徑相對於設定檔所在位置。因此它同時適用於全域 OpenCode 設定和專案級設定。
---
### 模型 (Model)
### 模型
使用 `model` 設定覆蓋此代理的模型。對於使用針對不同任務最佳化的不同模型很有用。例如，更快的規劃模型、更強大的實作模型。
使用 `model` 設定為代理覆寫模型。適用於針對不同任務使用不同的最佳化模型。例如，用更快的模型進行規劃，用更強大的模型進行實作。
:::tip
如果您不指定模型，主代理將使用 [全域設定的模型](/docs/config#models)，而子代理將使用呼叫子代理的主代理的模型。
如果您不指定模型，主代理將使用[全域設定的模型](/docs/config#models)，而子代理將使用呼叫它的主代理所使用的模型。
:::
```json title="opencode.json"
@@ -358,13 +358,13 @@ Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理
}
```
opencode 設定中的模型 ID 使用格式 `provider/model-id`。例如，如果您使用 [OpenCode Zen](/docs/zen)，則您將使用 `opencode/gpt-5.1-codex` 來表示 GPT 5.1 Codex。
OpenCode 設定中的模型 ID 使用 `provider/model-id` 格式。例如，如果您使用 [OpenCode Zen](/docs/zen)，則可以使用 `opencode/gpt-5.1-codex` 來表示 GPT 5.1 Codex。
---
### 工具 (Tools)
### 工具
使用 `tools` 設定控制此代理中可用的工具。您可以透過將特定工具設定為 `true` 或 `false` 來啟用或禁用特定工具。
使用 `tools` 設定控制代理中可用的工具。您可以透過將特定工具設為 `true` 或 `false` 來啟用或停用它們。
```json title="opencode.json" {3-6,9-12}
{
@@ -385,10 +385,10 @@ opencode 設定中的模型 ID 使用格式 `provider/model-id`。例如，如
```
:::note
特定於代理的設定會覆蓋全域設定。
代理級設定會覆寫全域設定。
:::
您也可以使用萬用字元同時控制多個工具。例如，要禁用 MCP 伺服器中的所有工具：
您還可以使用萬用字元同時控制多個工具。例如，要停用 MCP 伺服器中的所有工具：
```json title="opencode.json"
{
@@ -405,17 +405,17 @@ opencode 設定中的模型 ID 使用格式 `provider/model-id`。例如，如
}
```
[了解有關工具的更多資訊](/docs/tools)。
[了解更多關於工具的資訊](/docs/tools)。
---
### 權限 (Permissions)
### 權限
您可以設定權限來管理代理可以執行的操作。目前，`edit`、`bash` 和 `webfetch` 工具的權限可以設定為：
- `"ask"` — 執行工具之前提示批准
- `"allow"` — 未經批准允許所有操作
- `"deny"` — 禁用該工具
- `"ask"` — 執行工具前提示審批
- `"allow"` — 允許所有操作，無需審批
- `"deny"` — 停用該工具
```json title="opencode.json"
{
@@ -426,7 +426,7 @@ opencode 設定中的模型 ID 使用格式 `provider/model-id`。例如，如
}
```
您可以覆蓋每個代理的這些權限。
您可以按代理覆寫這些權限。
```json title="opencode.json" {3-5,8-10}
{
@@ -463,7 +463,7 @@ permission:
Only analyze code and suggest changes.
```
您可以設定特定 bash 指令的權限。
您可以為特定的 bash 命令設定權限。
```json title="opencode.json" {7}
{
@@ -481,7 +481,7 @@ Only analyze code and suggest changes.
}
```
這可以採用全域模式。
這可以使用 glob 模式。
```json title="opencode.json" {7}
{
@@ -498,8 +498,8 @@ Only analyze code and suggest changes.
}
```
您也可以使用 `*` 萬用字元來管理所有指令的權限。
由於最後一個匹配規則優先，因此將 `*` 萬用字元放在前面，將特定規則放在後面。
您還可以使用 `*` 萬用字元來管理所有命令的權限。
由於最後匹配的規則優先，請將 `*` 萬用字元放在前面，將具體規則放在後面。
```json title="opencode.json" {8}
{
@@ -517,13 +517,13 @@ Only analyze code and suggest changes.
}
```
[了解有關權限的更多資訊](/docs/permissions)。
[了解更多關於權限的資訊](/docs/permissions)。
---
### 模式 (Mode)
### 模式
使用 `mode` 設定控制代理的模式。 `mode` 選項用於確定如何使用代理。
使用 `mode` 設定控制代理的模式。`mode` 選項用於確定代理的使用方式。
```json title="opencode.json"
{
@@ -535,13 +535,13 @@ Only analyze code and suggest changes.
}
```
`mode` 選項可設定為 `primary`、`subagent` 或 `all`。如果未指定 `mode`，則預設為 `all`。
`mode` 選項可以設為 `primary`、`subagent` 或 `all`。如果未指定 `mode`，則預設為 `all`。
---
### 隱藏 (Hidden)
### 隱藏
使用 `@` 從 `hidden: true` 自動完成選單隱藏子代理。對於只能由其他代理透過任務工具以程式化方式呼叫的內部子代理很有用。
使用 `hidden: true` 將子代理從 `@` 自動補全選單中隱藏。適用於只應由其他代理透過 Task 工具以程式化方式呼叫的內部子代理。
```json title="opencode.json"
{
@@ -554,17 +554,17 @@ Only analyze code and suggest changes.
}
```
這僅影響自動完成選單中的使用者可見性。如果權限允許，模型仍然可以透過任務工具呼叫隱藏代理。
這僅影響自動補全選單中的使用者可見性。如果權限允許，模型仍然可以透過 Task 工具呼叫隱藏的代理。
:::note
僅適用於 `mode: subagent` 代理。
僅適用於 `mode: subagent` 的代理。
:::
---
### 任務權限 (Task Permissions)
### 任務權限
使用 `permission.task` 控制代理可以透過任務工具呼叫哪些子代理。使用 glob 模式進行靈活匹配。
使用 `permission.task` 控制代理可以透過 Task 工具呼叫哪些子代理。使用 glob 模式進行靈活匹配。
```json title="opencode.json"
{
@@ -583,21 +583,21 @@ Only analyze code and suggest changes.
}
```
當設定為 `deny` 時，子代理將從任務工具描述中完全刪除，因此模型不會嘗試呼叫它。
當設為 `deny` 時，子代理將從 Task 工具描述中完全移除，因此模型不會嘗試呼叫它。
:::tip
規則按順序評估，**最後匹配的規則獲勝**。在上面的範例中，`orchestrator-planner` 匹配 `*`（拒絕）和 `orchestrator-*`（允許），但由於 `orchestrator-*` 位於 `*` 之後，因此結果為 `allow`。
規則按順序評估，**最後匹配的規則優先**。在上面的範例中，`orchestrator-planner` 同時匹配 `*`（deny）和 `orchestrator-*`（allow），但由於 `orchestrator-*` 在 `*` 之後，所以結果為 `allow`。
:::
:::tip
使用者始終可以透過 `@` 自動完成選單直接呼叫任何子代理，即使代理的任務權限會拒絕它。
使用者始終可以透過 `@` 自動補全選單直接呼叫任何子代理，即使代理的任務權限會拒絕它。
:::
---
### 顏色 (Color)
### 顏色
使用 `color` 選項自定義代理在 UI 中的視覺外觀。這會影響代理在介面中的顯示方式。
使用 `color` 選項自訂代理在 UI 中的視覺外觀。這會影響代理在介面中的顯示方式。
使用有效的十六進位顏色（例如 `#FF5733`）或主題顏色：`primary`、`secondary`、`accent`、`success`、`warning`、`error`、`info`。
@@ -618,7 +618,7 @@ Only analyze code and suggest changes.
### Top P
使用 `top_p` 選項控制回應多樣性。控制隨機性的溫度替代方案。
使用 `top_p` 選項控制回應多樣性。這是控制隨機性的溫度替代方案。
```json title="opencode.json"
{
@@ -634,11 +634,11 @@ Only analyze code and suggest changes.
---
### 額外選項 (Extra)
### 其他選項
您在代理設定中指定的任何其他選項都將作為模型選項**直接**傳遞給供應商。這允許您使用特定於供應商的功能和參數。
您在代理設定中指定的任何其他選項都將作為模型選項**直接傳遞**給提供商。這允許您使用提供商特定的功能和參數。
例如，使用 OpenAI 的推理模型，您可以控制推理工作：
例如，使用 OpenAI 的推理模型時，您可以控制推理力度：
```json title="opencode.json" {6,7}
{
@@ -653,41 +653,41 @@ Only analyze code and suggest changes.
}
```
這些附加選項是特定於模型和供應商的。檢查供應商的文件以獲取可用參數。
這些附加選項是模型和提供商特定的。請查閱您的提供商文件以取得可用參數。
:::tip
執行 `opencode models` 查看可用模型的列表。
執行 `opencode models` 查看可用模型列表。
:::
---
## 建立代理
您可以使用以下指令建立新代理：
您可以使用以下命令建立新代理：
```bash
opencode agent create
```
此互動式指令將：
此互動式命令將：
1. 詢問代理保存在哪裡；全域或特定專案。
1. 詢問代理的儲存位置——全域或專案級。
2. 描述代理應該做什麼。
3. 生成適當的系統提示和標識符。
3. 產生合適的系統提示詞和識別碼。
4. 讓您選擇代理可以存取哪些工具。
5. 最後，使用代理設定建立一個 markdown 檔案。
5. 最後，建立一個包含代理設定的 Markdown 檔案。
---
## 使用案例
## 使用場景
以下是不同代理的一些常見使用案例。
以下是不同代理的一些常見使用場景。
- **Build 代理**：啟用所有工具的完整開發工作
- **Plan 代理**：分析規劃，不做改動
- **Plan 代理**：分析和規劃，不進行任何變更
- **Review 代理**：具有唯讀存取權限和文件工具的程式碼審查
- **Debug 代理**：專注於啟用 bash 和讀取工具的調查
- **Docs 代理**：使用檔案操作但不使用系統指令的文件編寫
- **Debug 代理**：專注於問題排查，啟用 bash 和讀取工具
- **Docs 代理**：文件編寫，具有檔案操作但不使用系統命令
---
@@ -723,7 +723,7 @@ Focus on:
---
### 安全稽核員
### 安全稽核代理
```markdown title="~/.config/opencode/agents/security-auditor.md"
---

266
packages/web/src/content/docs/zh-tw/cli.mdx
View File

@@ -1,17 +1,17 @@
---
title: 命令列介面
description: opencode CLI 選項和指令。
title: CLI
description: OpenCode CLI 選項和指令。
---
import { Tabs, TabItem } from "@astrojs/starlight/components"
預設情況下，OpenCode CLI 在不帶任何參數執行時啟動 [TUI](/docs/tui)。
OpenCode CLI 在不帶任何參數執行時，預設啟動 [TUI](/docs/tui)。
```bash
opencode
```
但它也接受本頁記錄的指令。這允許您以程式化方式與 OpenCode 互動。
但它也接受本頁面中記錄的指令，使您可以透過程式方式與 OpenCode 進行互動。
```bash
opencode run "Explain how closures work in JavaScript"
@@ -21,36 +21,36 @@ opencode run "Explain how closures work in JavaScript"
### tui
啟動 OpenCode TUI。
啟動 OpenCode 終端機使用者介面。
```bash
opencode [project]
```
#### 旗標 (Flags)
#### 旗標
| 旗標 | 簡寫 | 說明 |
| ------------ | ---- | ------------------------------------------------------------- |
| `--continue` | `-c` | 繼續上一個工作階段 |
| `--session` | `-s` | 繼續指定的工作階段 ID |
| `--fork` | | 繼續時分岔工作階段（與 `--continue` 或 `--session` 一起使用） |
| `--prompt` | | 使用的提示 |
| `--model` | `-m` | 使用的模型 (provider/model) |
| `--agent` | | 使用的代理 |
| `--session` | `-s` | 要繼續的工作階段 ID |
| `--fork` | | 繼續時分岔工作階段（與 `--continue` 或 `--session` 搭配使用） |
| `--prompt` | | 要使用的提示詞 |
| `--model` | `-m` | 要使用的模型，格式為 provider/model |
| `--agent` | | 要使用的代理 |
| `--port` | | 監聽連接埠 |
| `--hostname` | | 監聽的主機名稱 |
| `--hostname` | | 監聽主機名稱 |
---
## 指令
OpenCode CLI 還具有以下指令。
OpenCode CLI 還提供以下指令。
---
### agent
管理 OpenCode 代理。
管理 OpenCode 的代理。
```bash
opencode agent [command]
@@ -60,13 +60,13 @@ opencode agent [command]
### attach
將終端機連接到透過 `serve` 或 `web` 指令啟動的已執行的 OpenCode 後端伺服器。
將終端機連接到已透過 `serve` 或 `web` 指令啟動的 OpenCode 後端伺服器。
```bash
opencode attach [url]
```
這允許將 TUI 與遠端 OpenCode 後端一起使用。例如：
這允許將 TUI 與遠端 OpenCode 後端搭配使用。例如：
```bash
# Start the backend server for web/mobile access
@@ -79,21 +79,21 @@ opencode attach http://10.20.30.40:4096
#### 旗標
| 旗標 | 簡寫 | 說明 |
| ----------- | ---- | --------------------- |
| ----------- | ---- | ------------------- |
| `--dir` | | 啟動 TUI 的工作目錄 |
| `--session` | `-s` | 繼續指定的工作階段 ID |
| `--session` | `-s` | 要繼續的工作階段 ID |
---
#### create
使用自定義設定建立新代理。
使用自訂設定建立新的代理。
```bash
opencode agent create
```
此指令將指導您使用自定義系統提示和工具設定建立新代理。
此指令將引導您使用自訂系統提示詞和工具設定來建立新的代理。
---
@@ -109,7 +109,7 @@ opencode agent list
### auth
用於管理供應商的憑證和登入的指令。
管理供應商的憑證和登入資訊的指令。
```bash
opencode auth [command]
@@ -119,25 +119,25 @@ opencode auth [command]
#### login
OpenCode 由 [Models.dev](https://models.dev) 上的供應商列表提供支援，因此您可以使用 `opencode auth login` 為您想要使用的任何供應商設定 API 金鑰。它儲存在 `~/.local/share/opencode/auth.json` 中。
OpenCode 基於 [Models.dev](https://models.dev) 的供應商列表運作，因此您可以使用 `opencode auth login` 為任何想要使用的供應商設定 API 金鑰。金鑰儲存在 `~/.local/share/opencode/auth.json` 中。
```bash
opencode auth login
```
當 OpenCode 啟動時，它會從憑證檔案載入供應商。如果您的環境中定義了任何金鑰或專案中的 `.env` 檔案。
OpenCode 啟動時會從憑證檔案載入供應商資訊，同時也會載入環境變數或專案中 `.env` 檔案中定義的金鑰。
---
#### list
列出憑證檔案中儲存的所有經過身分驗證的供應商。
列出憑證檔案中儲存的所有已認證供應商。
```bash
opencode auth list
```
或者簡短的版本。
或使用簡寫版本。
```bash
opencode auth ls
@@ -147,7 +147,7 @@ opencode auth ls
#### logout
透過從憑證檔案中清除供應商，將您從供應商中登出。
從憑證檔案中清除供應商資訊以完成登出。
```bash
opencode auth logout
@@ -157,7 +157,7 @@ opencode auth logout
### github
管理 GitHub 代理以實現儲存庫自動化。
管理用於儲存庫自動化的 GitHub 代理。
```bash
opencode github [command]
@@ -173,13 +173,13 @@ opencode github [command]
opencode github install
```
這將設定必要的 GitHub Actions 工作流程並指導您完成設定過程。 [了解更多](/docs/github)。
此指令會設定必要的 GitHub Actions 工作流程並引導您完成設定過程。[了解更多](/docs/github)。
---
#### run
執行 GitHub 代理。這通常用在 GitHub Actions 中。
執行 GitHub 代理。通常在 GitHub Actions 中使用。
```bash
opencode github run
@@ -196,7 +196,7 @@ opencode github run
### mcp
管理模型上下文協議 (MCP) 伺服器。
管理 Model Context Protocol 伺服器。
```bash
opencode mcp [command]
@@ -212,7 +212,7 @@ opencode mcp [command]
opencode mcp add
```
此指令將指導您新增本地或遠端 MCP 伺服器。
此指令將引導您新增本地或遠端 MCP 伺服器。
---
@@ -224,7 +224,7 @@ opencode mcp add
opencode mcp list
```
或者使用簡短版本。
或使用簡寫版本。
```bash
opencode mcp ls
@@ -234,7 +234,7 @@ opencode mcp ls
#### auth
使用啟用 OAuth 的 MCP 伺服器進行身分驗證。
對支援 OAuth 的 MCP 伺服器進行認證。
```bash
opencode mcp auth [name]
@@ -242,13 +242,13 @@ opencode mcp auth [name]
如果您不提供伺服器名稱，系統將提示您從可用的支援 OAuth 的伺服器中進行選擇。
您還可以列出支援 OAuth 的伺服器及其身分驗證狀態。
您還可以列出支援 OAuth 的伺服器及其認證狀態。
```bash
opencode mcp auth list
```
或者使用簡短版本。
或使用簡寫版本。
```bash
opencode mcp auth ls
@@ -258,7 +258,7 @@ opencode mcp auth ls
#### logout
刪除 MCP 伺服器的 OAuth 憑證。
移除 MCP 伺服器的 OAuth 憑證。
```bash
opencode mcp logout [name]
@@ -268,7 +268,7 @@ opencode mcp logout [name]
#### debug
除錯 MCP 伺服器的 OAuth 連線問題。
偵錯 MCP 伺服器的 OAuth 連線問題。
```bash
opencode mcp debug <name>
@@ -284,11 +284,11 @@ opencode mcp debug <name>
opencode models [provider]
```
此指令以 `provider/model` 格式顯示您設定的供應商中可用的所有模型。
此指令以 `provider/model` 的格式顯示所有已設定供應商中可用的模型。
這對於確定 [你的設定](/docs/config/) 中使用的確切模型名稱很有用。
這對於確定在[設定檔](/docs/config/)中使用的確切模型名稱非常有用。
您可以選擇傳遞供應商 ID 以按該供應商篩選模型。
您可以選擇傳入供應商 ID 來按供應商篩選模型。
```bash
opencode models anthropic
@@ -297,11 +297,11 @@ opencode models anthropic
#### 旗標
| 旗標 | 說明 |
| ----------- | ---------------------------------------- |
| `--refresh` | 從 models.dev 刷新模型快取 |
| `--verbose` | 使用更詳細的模型輸出（包括成本等元資料） |
| ----------- | ------------------------------------------ |
| `--refresh` | 從 models.dev 重新整理模型快取 |
| `--verbose` | 使用更詳細的模型輸出（包含費用等中繼資料） |
使用 `--refresh` 旗標來更新快取的模型列表。當新模型已新增到供應商並且您希望在 OpenCode 中查看它們時，這非常有用。
使用 `--refresh` 旗標可以更新快取的模型列表。當供應商新增了模型並且您希望在 OpenCode 中看到它們時，此功能非常有用。
```bash
opencode models --refresh
@@ -311,19 +311,19 @@ opencode models --refresh
### run
透過直接傳遞提示以非互動模式執行 opencode。
以非互動模式執行 OpenCode，直接傳入提示詞。
```bash
opencode run [message..]
```
這對於撰寫指令碼、自動化，或者當您想要快速得到答案而不啟動完整的 TUI 時非常有用。例如：
這對於指令碼編寫、自動化或無需啟動完整 TUI 即可快速取得答案的情境非常有用。例如：
```bash "opencode run"
opencode run Explain the use of context in Go
```
您還可以附加到正在執行的 `opencode serve` 實例，以避免每次執行時 MCP 伺服器冷啟動時間：
您還可以連接到正在執行的 `opencode serve` 實例，以避免每次執行時 MCP 伺服器的冷啟動時間：
```bash
# Start a headless server in one terminal
@@ -335,47 +335,47 @@ opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
#### 旗標
| 旗標 | 短 | 說明 |
| ------------ | ---- | --------------------------------------------------------------- |
| `--command` | | 要執行的指令，使用訊息作為參數 |
| 旗標 | 簡寫 | 說明 |
| ------------ | ---- | -------------------------------------------------------------- |
| `--command` | | 要執行的指令，使用 message 作為參數 |
| `--continue` | `-c` | 繼續上一個工作階段 |
| `--session` | `-s` | 繼續指定的工作階段 ID |
| `--fork` | | 繼續時分岔工作階段（與 `--continue` 或 `--session` 一起使用） |
| `--session` | `-s` | 要繼續的工作階段 ID |
| `--fork` | | 繼續時分岔工作階段（與 `--continue` 或 `--session` 搭配使用） |
| `--share` | | 分享工作階段 |
| `--model` | `-m` | 使用的模型 (provider/model) |
| `--agent` | | 使用的代理 |
| `--file` | `-f` | 要附加到訊息的檔案 |
| `--format` | | 格式：預設 (formatted) 或 json (原始 JSON 事件) |
| `--title` | | 工作階段標題（如果未提供值，則使用截斷的提示） |
| `--attach` | | 連接到正在執行的 opencode 伺服器（例如，http://localhost:4096） |
| `--port` | | 本地伺服器的連接埠（預設為隨機連接埠） |
| `--model` | `-m` | 要使用的模型，格式為 provider/model |
| `--agent` | | 要使用的代理 |
| `--file` | `-f` | 附加到訊息的檔案 |
| `--format` | | 格式：default（格式化輸出）或 json（原始 JSON 事件） |
| `--title` | | 工作階段標題（未提供值時使用截斷的提示詞） |
| `--attach` | | 連接到正在執行的 opencode 伺服器（例如 http://localhost:4096） |
| `--port` | | 本地伺服器連接埠（預設為隨機連接埠） |
---
### serve
啟動無介面 opencode 伺服器以進行 API 存取。查看 [伺服器文件](/docs/server) 以獲取完整的 HTTP 介面。
啟動無介面的 OpenCode 伺服器以提供 API 存取。查看[伺服器文件](/docs/server)了解完整的 HTTP 介面。
```bash
opencode serve
```
這將啟動一個 HTTP 伺服器，該伺服器提供對 opencode 功能的 API 存取，而無需 TUI 介面。設定 `OPENCODE_SERVER_PASSWORD` 以啟用 HTTP 基本身分驗證（使用者名稱預設為 `opencode`）。
此指令啟動一個 HTTP 伺服器，提供對 OpenCode 功能的 API 存取，無需 TUI 介面。設定 `OPENCODE_SERVER_PASSWORD` 可啟用 HTTP 基本認證（使用者名稱預設為 `opencode`）。
#### 旗標
| 旗標 | 說明 |
| ------------ | -------------------------- |
| `--port` | 監聽連接埠 |
| `--hostname` | 監聽的主機名稱 |
| `--hostname` | 監聽主機名稱 |
| `--mdns` | 啟用 mDNS 探索 |
| `--cors` | 允許 CORS 的其他瀏覽器來源 |
| `--cors` | 允許 CORS 的額外瀏覽器來源 |
---
### session
管理 opencode 工作階段。
管理 OpenCode 工作階段。
```bash
opencode session [command]
@@ -385,7 +385,7 @@ opencode session [command]
#### list
列出所有 opencode 工作階段。
列出所有 OpenCode 工作階段。
```bash
opencode session list
@@ -393,16 +393,16 @@ opencode session list
##### 旗標
| 旗標 | 短 | 說明 |
| ------------- | ---- | ------------------------------ |
| 旗標 | 簡寫 | 說明 |
| ------------- | ---- | ------------------------------------- |
| `--max-count` | `-n` | 限制為最近 N 個工作階段 |
| `--format` | | 輸出格式：table 或 json(table) |
| `--format` | | 輸出格式：table 或 json（預設 table） |
---
### stats
顯示 opencode 工作階段的 Tokens 使用情況和成本統計資訊。
顯示 OpenCode 工作階段的 Token 用量和費用統計資訊。
```bash
opencode stats
@@ -411,35 +411,35 @@ opencode stats
#### 旗標
| 旗標 | 說明 |
| ----------- | -------------------------------------------------------- |
| `--days` | 顯示過去 N 天（所有時間）的統計數據 |
| `--tools` | 顯示的工具數量（全部） |
| `--models` | 顯示模型使用情況細分（預設隱藏）。傳遞一個數字來顯示前 N |
| `--project` | 按專案過濾（所有專案，空字串：當前專案） |
| ----------- | ---------------------------------------------------- |
| `--days` | 顯示最近 N 天的統計資訊（預設為所有時間） |
| `--tools` | 顯示的工具數量（預設為全部） |
| `--models` | 顯示模型用量明細（預設隱藏）。傳入數字可顯示前 N 個 |
| `--project` | 按專案篩選（預設為所有專案，傳入空字串表示當前專案） |
---
### export
將工作階段數據導出為 JSON。
將工作階段資料匯出為 JSON。
```bash
opencode export [sessionID]
```
如果您不提供工作階段 ID，系統將提示您從可用工作階段中進行選擇。
如果您不提供工作階段 ID，系統將提示您從可用的工作階段中進行選擇。
---
### import
從 JSON 檔案或 opencode 分享 URL 匯入工作階段數據。
從 JSON 檔案或 OpenCode 分享連結匯入工作階段資料。
```bash
opencode import <file>
```
您以從本地檔案或 opencode 分享 URL 匯入。
您可以從本地檔案或 OpenCode 分享連結匯入。
```bash
opencode import session.json
@@ -450,48 +450,48 @@ opencode import https://opncd.ai/s/abc123
### web
使用 Web 介面啟動無介面 opencode 伺服器。
啟動帶有 Web 介面的無介面 OpenCode 伺服器。
```bash
opencode web
```
這將啟動 HTTP 伺服器並打開網頁瀏覽器以透過 Web 介面存取 opencode。設定 `OPENCODE_SERVER_PASSWORD` 以啟用 HTTP 基本身分驗證（使用者名稱預設為 `opencode`）。
此指令啟動一個 HTTP 伺服器並開啟瀏覽器，透過 Web 介面存取 OpenCode。設定 `OPENCODE_SERVER_PASSWORD` 可啟用 HTTP 基本認證（使用者名稱預設為 `opencode`）。
#### 旗標
| 旗標 | 說明 |
| ------------ | -------------------------- |
| `--port` | 監聽連接埠 |
| `--hostname` | 監聽的主機名稱 |
| `--hostname` | 監聽主機名稱 |
| `--mdns` | 啟用 mDNS 探索 |
| `--cors` | 允許 CORS 的其他瀏覽器來源 |
| `--cors` | 允許 CORS 的額外瀏覽器來源 |
---
### acp
啟動 ACP (Agent Client Protocol) 伺服器。
啟動 ACP（Agent Client Protocol）伺服器。
```bash
opencode acp
```
此指令啟動一個 ACP 伺服器，該伺服器使用 nd-JSON 透過 stdin/stdout 進行通訊。
此指令啟動一個透過 stdin/stdout 使用 nd-JSON 進行通訊的 ACP 伺服器。
#### 旗標
| 旗標 | 說明 |
| ------------ | -------------- |
| ------------ | ------------ |
| `--cwd` | 工作目錄 |
| `--port` | 監聽連接埠 |
| `--hostname` | 監聽的主機名稱 |
| `--hostname` | 監聽主機名稱 |
---
### uninstall
解除安裝 opencode 並刪除所有相關檔案。
解除安裝 OpenCode 並刪除所有相關檔案。
```bash
opencode uninstall
@@ -499,30 +499,30 @@ opencode uninstall
#### 旗標
| 旗標 | 短 | 說明 |
| --------------- | ---- | -------------------------------- |
| 旗標 | 簡寫 | 說明 |
| --------------- | ---- | ------------------------------ |
| `--keep-config` | `-c` | 保留設定檔 |
| `--keep-data` | `-d` | 保留工作階段數據和快照 |
| `--dry-run` | | 顯示在不刪除的情況下將刪除的內容 |
| `--keep-data` | `-d` | 保留工作階段資料和快照 |
| `--dry-run` | | 顯示將被刪除的內容但不實際刪除 |
| `--force` | `-f` | 跳過確認提示 |
---
### upgrade
將 opencode 更新到最新版本或特定版本。
將 OpenCode 更新到最新版本或指定版本。
```bash
opencode upgrade [target]
```
升級到最新版本。
更新到最新版本。
```bash
opencode upgrade
```
升級到特定版本。
更新到指定版本。
```bash
opencode upgrade v0.1.48
@@ -532,71 +532,71 @@ opencode upgrade v0.1.48
| 旗標 | 簡寫 | 說明 |
| ---------- | ---- | ------------------------------------------ |
| `--method` | `-m` | 使用的安裝方法；curl、npm、pnpm、bun、brew |
| `--method` | `-m` | 使用的安裝方式：curl、npm、pnpm、bun、brew |
---
## 全域旗標
opencode CLI 採用以下全域旗標。
OpenCode CLI 接受以下全域旗標。
| 旗標 | 短 | 說明 |
| 旗標 | 簡寫 | 說明 |
| -------------- | ---- | ------------------------------------ |
| `--help` | `-h` | 顯示說明 |
| `--version` | `-v` | 列印版本號 |
| `--print-logs` | | 將記錄列印到 stderr |
| `--log-level` | | 記錄等級（debug, info, warn, error） |
| `--help` | `-h` | 顯示說明資訊 |
| `--version` | `-v` | 印出版本號 |
| `--print-logs` | | 將日誌輸出到 stderr |
| `--log-level` | | 日誌等級（DEBUG、INFO、WARN、ERROR） |
---
## 環境變數
可以使用環境變數設定 opencode。
OpenCode 可以透過環境變數進行設定。
| 變數 | 類型 | 說明 |
| ------------------------------------- | ------- | --------------------------------------------- |
| ------------------------------------- | ------- | ------------------------------------------- |
| `OPENCODE_AUTO_SHARE` | boolean | 自動分享工作階段 |
| `OPENCODE_GIT_BASH_PATH` | string | Windows 上 Git Bash 可執行檔案的路徑 |
| `OPENCODE_GIT_BASH_PATH` | string | Windows 上 Git Bash 可執行檔的路徑 |
| `OPENCODE_CONFIG` | string | 設定檔路徑 |
| `OPENCODE_CONFIG_DIR` | string | 設定目錄的路徑 |
| `OPENCODE_CONFIG_CONTENT` | string | 內聯 json 設定內容 |
| `OPENCODE_DISABLE_AUTOUPDATE` | boolean | 禁用自動更新檢查 |
| `OPENCODE_DISABLE_PRUNE` | boolean | 禁用舊數據的修剪 |
| `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | 禁用自動終端機標題更新 |
| `OPENCODE_PERMISSION` | string | 內聯 json 權限設定 |
| `OPENCODE_DISABLE_DEFAULT_PLUGINS` | boolean | 禁用預設外掛 |
| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | 禁用自動 LSP 伺服器下載 |
| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | 啟用實驗模型 |
| `OPENCODE_DISABLE_AUTOCOMPACT` | boolean | 禁用自動上下文壓縮 |
| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | 禁止從 `.claude` 讀取（提示+技巧） |
| `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | 禁用讀取 `~/.claude/CLAUDE.md` |
| `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | 禁用載入 `.claude/skills` |
| `OPENCODE_DISABLE_MODELS_FETCH` | boolean | 禁用從遠端來源獲取模型 |
| `OPENCODE_FAKE_VCS` | string | 用於測試目的的假 VCS 供應商 |
| `OPENCODE_DISABLE_FILETIME_CHECK` | boolean | 禁用檔案時間檢查以進行最佳化 |
| `OPENCODE_CLIENT` | string | 客戶端標識符（預設為 `cli`） |
| `OPENCODE_CONFIG_DIR` | string | 設定目錄路徑 |
| `OPENCODE_CONFIG_CONTENT` | string | 內嵌 JSON 設定內容 |
| `OPENCODE_DISABLE_AUTOUPDATE` | boolean | 停用自動更新檢查 |
| `OPENCODE_DISABLE_PRUNE` | boolean | 停用舊資料清理 |
| `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | 停用自動終端機標題更新 |
| `OPENCODE_PERMISSION` | string | 內嵌 JSON 權限設定 |
| `OPENCODE_DISABLE_DEFAULT_PLUGINS` | boolean | 停用預設外掛程式 |
| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | 停用 LSP 伺服器自動下載 |
| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | 啟用實驗性模型 |
| `OPENCODE_DISABLE_AUTOCOMPACT` | boolean | 停用自動上下文壓縮 |
| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | 停用讀取 `.claude`（提示詞 + 技能） |
| `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | 停用讀取 `~/.claude/CLAUDE.md` |
| `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | 停用載入 `.claude/skills` |
| `OPENCODE_DISABLE_MODELS_FETCH` | boolean | 停用從遠端來源擷取模型 |
| `OPENCODE_FAKE_VCS` | string | 用於測試目的的模擬 VCS 供應商 |
| `OPENCODE_DISABLE_FILETIME_CHECK` | boolean | 停用檔案時間檢查最佳化 |
| `OPENCODE_CLIENT` | string | 用戶端識別碼（預設為 `cli`） |
| `OPENCODE_ENABLE_EXA` | boolean | 啟用 Exa 網路搜尋工具 |
| `OPENCODE_SERVER_PASSWORD` | string | 為 `serve`/`web` 啟用基本身分驗證 |
| `OPENCODE_SERVER_USERNAME` | string | 覆蓋基本身分驗證使用者名稱（預設 `opencode`） |
| `OPENCODE_MODELS_URL` | string | 用於獲取模型設定的自定義 URL |
| `OPENCODE_SERVER_PASSWORD` | string | 為 `serve`/`web` 啟用基本認證 |
| `OPENCODE_SERVER_USERNAME` | string | 覆寫基本認證使用者名稱（預設為 `opencode`） |
| `OPENCODE_MODELS_URL` | string | 自訂模型設定擷取 URL |
---
### 實驗性的
### 實驗性功能
這些環境變數啟用可能會更改或刪除的實驗性功能。
這些環境變數用於啟用可能會變更或移除的實驗性功能。
| 變數 | 類型 | 說明 |
| ----------------------------------------------- | ------- | ----------------------------------- |
| ----------------------------------------------- | ------- | ------------------------------- |
| `OPENCODE_EXPERIMENTAL` | boolean | 啟用所有實驗性功能 |
| `OPENCODE_EXPERIMENTAL_ICON_DISCOVERY` | boolean | 啟用圖示探索 |
| `OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT` | boolean | 在 TUI 中禁用選擇時複製 |
| `OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS` | number | bash 指令的預設超時（以毫秒為單位） |
| `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | number | LLM 回應的最大輸出 tokens |
| `OPENCODE_EXPERIMENTAL_FILEWATCHER` | boolean | 為整個目錄啟用檔案觀察器 |
| `OPENCODE_EXPERIMENTAL_OXFMT` | boolean | 啟用 oxfmt 格式化程式 |
| `OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT` | boolean | 停用 TUI 中的選取即複製 |
| `OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS` | number | bash 指令的預設逾時時間（毫秒） |
| `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | number | LLM 回應的最大輸出 Token 數 |
| `OPENCODE_EXPERIMENTAL_FILEWATCHER` | boolean | 啟用整個目錄的檔案監看器 |
| `OPENCODE_EXPERIMENTAL_OXFMT` | boolean | 啟用 oxfmt 格式化器 |
| `OPENCODE_EXPERIMENTAL_LSP_TOOL` | boolean | 啟用實驗性 LSP 工具 |
| `OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER` | boolean | 禁用檔案觀察器 |
| `OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER` | boolean | 停用檔案監看器 |
| `OPENCODE_EXPERIMENTAL_EXA` | boolean | 啟用實驗性 Exa 功能 |
| `OPENCODE_EXPERIMENTAL_LSP_TY` | boolean | 啟用實驗性 LSP 類型檢查 |
| `OPENCODE_EXPERIMENTAL_MARKDOWN` | boolean | 啟用實驗性 Markdown 功能 |

100
packages/web/src/content/docs/zh-tw/commands.mdx
View File

@@ -1,21 +1,21 @@
---
title: 指令
description: 為重複任務建立自定義指令。
description: 為重複任務建立自訂指令。
---
自定義指令允許您指定在 TUI 中執行該指令時要執行的提示。
自訂指令允許您指定一個提示詞，當在 TUI 中執行該指令時會執行這個提示詞。
```bash frame="none"
/my-command
```
除了 `/init`、`/undo`、`/redo`、`/share`、`/help` 等內建指令之外，還有自定義指令。 [了解更多](/docs/tui#commands)。
自訂指令是 `/init`、`/undo`、`/redo`、`/share`、`/help` 等內建指令之外的補充。[了解更多](/docs/tui#commands)。
---
## 建立指令檔案
在 `commands/` 目錄中建立 markdown 檔案來定義自定義指令。
在 `commands/` 目錄中建立 markdown 檔案來定義自訂指令。
建立 `.opencode/commands/test.md`：
@@ -30,7 +30,7 @@ Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.
```
frontmatter 定義指令屬性。內容成為範本。
frontmatter 定義指令屬性，內容則成為範本。
透過輸入 `/` 後跟指令名稱來使用該指令。
@@ -42,13 +42,13 @@ frontmatter 定義指令屬性。內容成為範本。
## 設定
您 可以透過 opencode 設定或透過在 `commands/` 目錄中建立 markdown 檔案來新增自定義指令。
您可以透過 OpenCode 設定或在 `commands/` 目錄中建立 markdown 檔案來新增自訂指令。
---
### JSON
在 opencode [設定](/docs/config) 中使用 `command` 選項：
在 OpenCode [設定](/docs/config)中使用 `command` 選項：
```json title="opencode.jsonc" {4-12}
{
@@ -67,7 +67,7 @@ frontmatter 定義指令屬性。內容成為範本。
}
```
現在您可以在 TUI 中執行此指令：
現在您可以在 TUI 中執行這個指令：
```bash frame="none"
/test
@@ -77,10 +77,10 @@ frontmatter 定義指令屬性。內容成為範本。
### Markdown
您也可以使用 Markdown 檔案定義指令。將它們放入：
您還可以使用 markdown 檔案定義指令。將它們放在：
- 全域：`~/.config/opencode/commands/`
- 每個專案：`.opencode/commands/`
- 專案層級：`.opencode/commands/`
```markdown title="~/.config/opencode/commands/test.md"
---
@@ -93,7 +93,7 @@ Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.
```
Markdown 檔名成為指令名。例如，`test.md` 讓您執行：
markdown 檔案名稱即為指令名稱。例如，`test.md` 允許您執行：
```bash frame="none"
/test
@@ -101,15 +101,15 @@ Markdown 檔名成為指令名。例如，`test.md` 讓您執行：
---
## 提示設定
## 提示詞設定
自定義指令的提示支援幾個特殊的預留位置和語法。
自訂指令的提示詞支援多種特殊佔位符和語法。
---
### 參數 (Arguments)
### 參數
使用 `$ARGUMENTS` 預留位置將參數傳遞給指令。
使用 `$ARGUMENTS` 佔位符向指令傳遞參數。
```md title=".opencode/commands/component.md"
---
@@ -120,20 +120,20 @@ Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.
```
使用參數執行指令：
帶參數執行指令：
```bash frame="none"
/component Button
```
`$ARGUMENTS` 將替換為 `Button`。
`$ARGUMENTS` 將被替換為 `Button`。
您也可以使用位置參數存取各個參數：
您還可以使用位置參數存取各個參數：
- `$1` - 第一個參數
- `$2` - 第二個參數
- `$3` - 第三個參數
- 等等...
- 以此類推...
例如：
@@ -152,19 +152,19 @@ with the following content: $3
/create-file config.json src "{ \"key\": \"value\" }"
```
這取代了：
替換結果為：
- `$1` 與 `config.json`
- `$2` 與 `src`
- `$3` 與 `{ "key": "value" }`
- `$1` 替換為 `config.json`
- `$2` 替換為 `src`
- `$3` 替換為 `{ "key": "value" }`
---
### Shell 輸出
使用 _!`command`_ 將 [bash 指令](/docs/tui#bash-commands) 輸出注入到提示中。
使用 _!`command`_ 將 [bash 指令](/docs/tui#bash-commands)輸出注入到提示詞中。
例如，要建立分析測試覆蓋率的自定義指令：
例如，建立一個分析測試覆蓋率的自訂指令：
```md title=".opencode/commands/analyze-coverage.md"
---
@@ -190,13 +190,13 @@ Recent git commits:
Review these changes and suggest any improvements.
```
指令在專案的根目錄中執行，其輸出成為提示的一部分。
指令在專案的根目錄中執行，其輸出會成為提示詞的一部分。
---
### 檔案參考
### 檔案參照
使用 `@` 後跟檔名將檔案包含在指令中。
使用 `@` 後跟檔案名稱在指令中參照檔案。
```md title=".opencode/commands/review-component.md"
---
@@ -207,19 +207,19 @@ Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.
```
檔案內容會自動包含在提示中。
檔案內容會自動包含在提示詞中。
---
## 選項
讓我們詳細看看設定選項。
讓我們詳細了解各設定選項。
---
### 範本 (Template)
### Template
`template` 選項定義執行指令時將發送到 LLM 的提示。
`template` 選項定義執行指令時傳送給 LLM 的提示詞。
```json title="opencode.json"
{
@@ -235,9 +235,9 @@ Check for performance issues and suggest improvements.
---
### 描述 (Description)
### Description
使用 `description` 選項提供指令功能的簡要描述。
使用 `description` 選項提供指令功能的簡要說明。
```json title="opencode.json"
{
@@ -249,15 +249,15 @@ Check for performance issues and suggest improvements.
}
```
當您輸入指令時，這將在 TUI 中顯示為描述。
當您輸入指令時，這將在 TUI 中顯示為說明。
---
### 代理 (Agent)
### Agent
使用 `agent` 設定可選擇指定哪個 [代理](/docs/agents) 應執行此指令。
如果這是 [子代理](/docs/agents/#subagents)，該指令將預設觸發子代理呼叫。
要禁用此行為，請將 `subtask` 設定為 `false`。
使用 `agent` 設定可選擇指定由哪個[代理](/docs/agents)執行此指令。
如果這是一個[子代理](/docs/agents/#subagents)，該指令預設會觸發子代理呼叫。
要停用此行為，請將 `subtask` 設定為 `false`。
```json title="opencode.json"
{
@@ -269,15 +269,15 @@ Check for performance issues and suggest improvements.
}
```
這是一個**可選**設定選項。如果未指定，則預設為您當前的代理。
這是一個**可選的**設定選項。如果未指定，預設使用您當前的代理。
---
### 子任務 (Subtask)
### Subtask
使用 `subtask` 布林值強制指令觸發[子代理](/docs/agents/#subagents)呼叫。
如果您希望指令不污染您的主要上下文並且將**強制**代理充當子代理，那麼這非常有用，
即使 `mode` 在 [代理](/docs/agents) 設定上設定為 `primary`。
如果您希望指令不污染主要上下文，這會很有用，它會**強制**代理作為子代理執行，
即使[代理](/docs/agents)設定中的 `mode` 設定為 `primary`。
```json title="opencode.json"
{
@@ -289,11 +289,11 @@ Check for performance issues and suggest improvements.
}
```
這是一個**可選**設定選項。
這是一個**可選的**設定選項。
---
### 模型 (Model)
### Model
使用 `model` 設定覆寫此指令的預設模型。
@@ -307,16 +307,16 @@ Check for performance issues and suggest improvements.
}
```
這是一個**可選**設定選項。
這是一個**可選的**設定選項。
---
### 內建
## 內建指令
opencode 包含 `/init`、`/undo`、`/redo`、`/share`、`/help` 等內建指令； [了解更多](/docs/tui#commands)。
OpenCode 包含多個內建指令，如 `/init`、`/undo`、`/redo`、`/share`、`/help`；[了解更多](/docs/tui#commands)。
:::note
自定義指令可以覆寫內建指令。
自訂指令可以覆寫內建指令。
:::
如果您定義同名的自定義指令，它將覆寫內建指令。
如果您定義了同名的自訂指令，它將覆寫內建指令。

230
packages/web/src/content/docs/zh-tw/config.mdx
View File

@@ -1,15 +1,15 @@
---
title: 設定
description: 使用 opencode JSON 設定。
description: 使用 OpenCode JSON 設定。
---
您可以使用 JSON 設定檔設定 opencode。
您可以使用 JSON 設定檔來設定 OpenCode。
---
## 格式
opencode 支援 **JSON** 和 **JSONC**（帶註解的 JSON）格式。
OpenCode 支援 **JSON** 和 **JSONC**（帶註解的 JSON）格式。
```jsonc title="opencode.jsonc"
{
@@ -25,15 +25,15 @@ opencode 支援 **JSON** 和 **JSONC**（帶註解的 JSON）格式。
## 位置
您可以將設定放置在幾個不同的位置，它們有一個不同的優先順序。
您可以將設定放置在不同的位置，它們具有不同的優先順序。
:::note
設定檔**合併在一起**，而不是取代。
設定檔是**合併在一起**的，而不是替換。
:::
設定檔被合併在一起，而不是被取代。以下設定位置的設定被合併。僅當鍵值衝突時，後面的設定才會覆寫前面的設定。保留所有設定中的非衝突設定。
設定檔是合併在一起的，而不是被替換。來自以下設定位置的設定會被合併。後面的設定僅在鍵衝突時覆寫前面的設定。所有設定中的非衝突設定都會被保留。
例如，如果您的全域設定設定 `theme: "opencode"` 和 `autoupdate: true`，並且您的專案設定設定 `model: "anthropic/claude-sonnet-4-5"`，則最終設定將包括所有三個設定。
例如，如果您的全域設定設定了 `theme: "opencode"` 和 `autoupdate: true`，而您的專案設定設定了 `model: "anthropic/claude-sonnet-4-5"`，則最終設定將包含所有三個設定。
---
@@ -42,27 +42,27 @@ opencode 支援 **JSON** 和 **JSONC**（帶註解的 JSON）格式。
設定來源按以下順序載入（後面的來源覆寫前面的來源）：
1. **遠端設定**（來自 `.well-known/opencode`）- 組織預設值
2. **全域設定** (`~/.config/opencode/opencode.json`) - 使用者偏好設定
3. **自定義設定** (`OPENCODE_CONFIG` env var) - 自定義覆寫
4. **專案設定**（專案中的 `opencode.json`）- 專案特定的設定
5. **`.opencode` 目錄** - 代理、指令、外掛
6. **內聯設定** (`OPENCODE_CONFIG_CONTENT` env var) - 執行時覆寫
2. **全域設定**（`~/.config/opencode/opencode.json`）- 使用者偏好
3. **自訂設定**（`OPENCODE_CONFIG` 環境變數）- 自訂覆寫
4. **專案設定**（專案中的 `opencode.json`）- 專案特定設定
5. **`.opencode` 目錄** - 代理、指令、外掛程式
6. **內嵌設定**（`OPENCODE_CONFIG_CONTENT` 環境變數）- 執行時覆寫
這意味著專案設定可以覆寫全域預設值，全域設定可以覆寫遠端組織預設值。
:::note
`.opencode` 和 `~/.config/opencode` 目錄對子目錄使用**複數名稱**：`agents/`、`commands/`、`modes/`、`plugins/`、`skills/`、`tools/` 和 `themes/`。為了向後相容，也支援單數名稱（例如 `agent/`）。
`.opencode` 和 `~/.config/opencode` 目錄的子目錄使用**複數名稱**：`agents/`、`commands/`、`modes/`、`plugins/`、`skills/`、`tools/` 和 `themes/`。為了向後相容，也支援單數名稱（例如 `agent/`）。
:::
---
### 遠端
組織可以透過 `.well-known/opencode` 端點提供預設設定。當您向支援它的供應商進行身分驗證時，會自動取得該資訊。
組織可以透過 `.well-known/opencode` 端點提供預設設定。當您使用支援該功能的供應商進行身分驗證時，會自動擷取此設定。
首先載入遠端設定，作為基礎層。所有其他設定來源（全域、專案）都可以覆寫這些預設值。
遠端設定最先載入，作為基礎層。所有其他設定來源（全域、專案）都可以覆寫這些預設值。
例如，如果您的組織提供預設禁用的 MCP 伺服器：
例如，如果您的組織提供了預設停用的 MCP 伺服器：
```json title="Remote config from .well-known/opencode"
{
@@ -94,63 +94,63 @@ opencode 支援 **JSON** 和 **JSONC**（帶註解的 JSON）格式。
### 全域
將全域 opencode 設定放在 `~/.config/opencode/opencode.json` 中。使用全域設定來實現使用者範圍的偏好設定，例如主題、供應商或按鍵綁定。
將全域 OpenCode 設定放在 `~/.config/opencode/opencode.json` 中。使用全域設定來設定使用者層級的偏好，例如主題、供應商或快捷鍵。
全域設定覆寫遠端組織預設值。
---
### 每個專案
### 專案層級
在專案根目錄中新增 `opencode.json`。專案設定在標準設定檔中具有最高優先級 - 它覆寫全域設定和遠端設定。
在專案根目錄中新增 `opencode.json`。專案設定在標準設定檔中具有最高優先級——它會覆寫全域設定和遠端設定。
:::tip
將專案特定設定放在專案的根目錄中。
:::
當 opencode 啟動時，它會在當前目錄中尋找設定檔或遍歷到最近的 Git 目錄。
當 OpenCode 啟動時，它會在當前目錄中尋找設定檔，或向上遍歷到最近的 Git 目錄。
這也可以安全地簽入 Git 並使用與全域模式相同的模式。
該設定檔也可以安全地提交到 Git 中，並使用與全域設定相同的 Schema。
---
### 自定義路徑
### 自訂路徑
使用 `OPENCODE_CONFIG` 環境變數指定自定義設定檔路徑。
使用 `OPENCODE_CONFIG` 環境變數指定自訂設定檔路徑。
```bash
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"
```
自定義設定按優先順序在全域設定和專案設定之間載入。
自訂設定在優先順序中位於全域設定和專案設定之間載入。
---
### 自定義目錄
### 自訂目錄
使用 `OPENCODE_CONFIG_DIR` 環境變數指定自定義設定目錄。將在該目錄中搜尋代理、指令、模式和外掛，就像標準 `.opencode` 目錄一樣，並且應該遵循相同的結構。
使用 `OPENCODE_CONFIG_DIR` 環境變數指定自訂設定目錄。該目錄會像標準 `.opencode` 目錄一樣被搜尋代理、指令、模式和外掛程式，並且應遵循相同的結構。
```bash
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"
```
自定義目錄在全域設定和 `.opencode` 目錄之後載入，因此它**可以覆寫**它們的設定。
自訂目錄在全域設定和 `.opencode` 目錄之後載入，因此**可以覆寫**它們的設定。
---
## 架構
## Schema
設定檔具有在 [**`opencode.ai/config.json`**](https://opencode.ai/config.json) 中定義的架構。
設定檔具有在 [**`opencode.ai/config.json`**](https://opencode.ai/config.json) 中定義的 Schema。
您的編輯器應該能夠根據架構進行驗證和自動完成。
您的編輯器應該能夠基於該 Schema 進行驗證和自動補全。
---
### TUI
您可以透過 `tui` 選項設定特定於 TUI 的設定。
您可以透過 `tui` 選項設定 TUI 相關設定。
```json title="opencode.json"
{
@@ -168,16 +168,16 @@ opencode run "Hello world"
可用選項：
- `scroll_acceleration.enabled` - 啟用 macOS 風格的捲動加速。**優先於 `scroll_speed`。**
- `scroll_speed` - 自定義捲動速度倍數（預設值：`3`，最小值：`1`）。如果 `scroll_acceleration.enabled` 是 `true`，則忽略。
- `diff_style` - 控制差異顯示。 `"auto"` 適應終端機寬度，`"stacked"` 始終顯示單列。
- `scroll_speed` - 自訂捲動速度倍率（預設值：`3`，最小值：`1`）。如果 `scroll_acceleration.enabled` 為 `true`，則忽略此選項。
- `diff_style` - 控制差異呈現方式。`"auto"` 根據終端機寬度自適應，`"stacked"` 始終顯示單列。
[在此處了解有關使用 TUI 的更多資訊](/docs/tui)。
[在此了解更多關於 TUI 的資訊](/docs/tui)。
---
### 伺服器
您可以透過 `opencode serve` 選項為 `opencode web` 和 `server` 指令設定伺服器設定。
您可以透過 `server` 選項為 `opencode serve` 和 `opencode web` 指令設定伺服器設定。
```json title="opencode.json"
{
@@ -194,13 +194,13 @@ opencode run "Hello world"
可用選項：
- `port` - 監聽的連接埠。
- `hostname` - 要監聽的主機名稱。當 `mdns` 啟用且未設定主機名稱時，預設為 `0.0.0.0`。
- `mdns` - 啟用 mDNS 服務探索。這允許網路上的其他設備發現您的 opencode 伺服器。
- `mdnsDomain` - mDNS 服務的自定義網域名稱。預設為 `opencode.local`。對於在同一網路上執行多個實例很有用。
- `cors` - 從基於瀏覽器的客戶端使用 HTTP 伺服器時允許 CORS 的其他來源。值必須是完整來源（通訊協定+主機+可選連接埠），例如 `https://app.example.com`。
- `port` - 監聽連接埠。
- `hostname` - 監聽主機名稱。當 `mdns` 啟用且未設定主機名稱時，預設為 `0.0.0.0`。
- `mdns` - 啟用 mDNS 服務探索。這允許網路上的其他裝置發現您的 OpenCode 伺服器。
- `mdnsDomain` - mDNS 服務的自訂網域名稱。預設為 `opencode.local`。適用於在同一網路上執行多個實例的情境。
- `cors` - 從基於瀏覽器的用戶端使用 HTTP 伺服器時允許 CORS 的額外來源。值必須是完整的來源（通訊協定 + 主機 + 可選連接埠），例如 `https://app.example.com`。
[在此處了解有關伺服器的更多資訊](/docs/server)。
[在此了解更多關於伺服器的資訊](/docs/server)。
---
@@ -218,13 +218,13 @@ opencode run "Hello world"
}
```
[在此處了解有關工具的更多資訊](/docs/tools)。
[在此了解更多關於工具的資訊](/docs/tools)。
---
### 模型
您可以透過 `provider`、`model` 和 `small_model` 選項來設定要在 opencode 設定中使用的供應商和模型。
您可以透過 `provider`、`model` 和 `small_model` 選項在 OpenCode 設定中設定要使用的供應商和模型。
```json title="opencode.json"
{
@@ -235,7 +235,7 @@ opencode run "Hello world"
}
```
`small_model` 選項為標題生成等輕量級任務設定單獨的模型。預設情況下，如果您的供應商可以提供更便宜的模型，opencode 會嘗試使用更便宜的模型，否則它會退回到您的主模型。
`small_model` 選項為標題生成等輕量級任務設定單獨的模型。預設情況下，如果您的供應商有更便宜的模型可用，OpenCode 會嘗試使用該模型，否則會回退到您的主模型。
供應商選項可以包括 `timeout` 和 `setCacheKey`：
@@ -253,16 +253,16 @@ opencode run "Hello world"
}
```
- `timeout` - 請求超時以毫秒為單位（預設值：300000）。設定為 `false` 以禁用。
- `setCacheKey` - 確保始終為指定的供應商設定快取金鑰。
- `timeout` - 請求逾時時間，單位為毫秒（預設值：300000）。設定為 `false` 可停用逾時。
- `setCacheKey` - 確保始終為指定供應商設定快取金鑰。
您也可以設定 [本地模型](/docs/models#local)。 [了解更多](/docs/models)。
您還可以設定[本地模型](/docs/models#local)。[了解更多](/docs/models)。
---
#### 特定於供應商的選項
#### 供應商特定選項
某些供應商支援除通用 `timeout` 和 `apiKey` 設定之外的其他設定選項。
一些供應商支援除通用 `timeout` 和 `apiKey` 設定之外的額外設定選項。
##### Amazon Bedrock
@@ -283,21 +283,21 @@ Amazon Bedrock 支援 AWS 特定設定：
}
```
- `region` - Bedrock 的 AWS 區域（預設為 `AWS_REGION` env var 或 `us-east-1`）
- `profile` - 來自 `~/.aws/credentials` 的 AWS 命名設定檔（預設為 `AWS_PROFILE` env var）
- `endpoint` - VPC 終端節點的自定義終端節點 URL。這是使用 AWS 特定術語的通用 `baseURL` 選項的別名。如果兩者都指定，`endpoint` 優先。
- `region` - Bedrock 的 AWS 區域（預設為 `AWS_REGION` 環境變數或 `us-east-1`）
- `profile` - 來自 `~/.aws/credentials` 的 AWS 命名設定檔（預設為 `AWS_PROFILE` 環境變數）
- `endpoint` - VPC 端點的自訂端點 URL。這是通用 `baseURL` 選項使用 AWS 特定術語的別名。如果兩者都指定，`endpoint` 優先。
:::note
Bearer Token (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 優先於基於設定檔的身分驗證。詳情請參閱 [認證優先級](/docs/providers#authentication-precedence)。
Bearer Token（`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`）優先於基於設定檔的身分驗證。詳情請參見[認證優先級](/docs/providers#authentication-precedence)。
:::
[了解有關 Amazon Bedrock 設定的更多資訊](/docs/providers#amazon-bedrock)。
[了解更多關於 Amazon Bedrock 設定的資訊](/docs/providers#amazon-bedrock)。
---
### 主題
您可以透過 `theme` 選項在 opencode 設定中設定要使用的主題。
您可以透過 OpenCode 設定中的 `theme` 選項設定要使用的主題。
```json title="opencode.json"
{
@@ -306,7 +306,7 @@ Bearer Token (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 優先於基於設定
}
```
[在這裡了解更多](/docs/themes)。
[在此了解更多](/docs/themes)。
---
@@ -332,13 +332,13 @@ Bearer Token (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 優先於基於設定
}
```
您也可以使用 `~/.config/opencode/agents/` 或 `.opencode/agents/` 中的 markdown 檔案定義代理。 [在這裡了解更多](/docs/agents)。
您還可以使用 `~/.config/opencode/agents/` 或 `.opencode/agents/` 中的 Markdown 檔案定義代理。[在此了解更多](/docs/agents)。
---
### 預設代理
您可以使用 `default_agent` 選項設定預設代理。當沒有明確指定時，這將決定使用哪個代理。
您可以使用 `default_agent` 選項設定預設代理。當未明確指定代理時，將使用該預設代理。
```json title="opencode.json"
{
@@ -347,9 +347,9 @@ Bearer Token (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 優先於基於設定
}
```
預設代理必須是主代理（而不是子代理）。這可以是內建代理，例如 `"build"` 或 `"plan"`，或者您定義的 [自定義代理](/docs/agents)。如果指定的代理不存在或者是子代理，opencode 將退回到 `"build"` 並發出警告。
預設代理必須是主代理（不能是子代理）。可以是內建代理（如 `"build"` 或 `"plan"`），也可以是您定義的[自訂代理](/docs/agents)。如果指定的代理不存在或是子代理，OpenCode 將回退到 `"build"` 並發出警告。
此設定適用於所有介面：TUI、CLI (`opencode run`)、桌面應用程式和 GitHub Action。
此設定適用於所有介面：TUI、CLI（`opencode run`）、桌面應用程式和 GitHub Action。
---
@@ -364,19 +364,19 @@ Bearer Token (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 優先於基於設定
}
```
這需要：
該選項接受：
- `"manual"` - 允許透過指令手動分享（預設）
- `"auto"` - 自動分享新對話
- `"disabled"` - 完全禁用分享
- `"auto"` - 自動分享新工作階段
- `"disabled"` - 完全停用分享
預設情況下，分享設定為手動模式，您需要使用 `/share` 指令明確分享對話。
預設情況下，分享設定為手動模式，您需要使用 `/share` 指令明確分享工作階段。
---
### 指令
您可以透過 `command` 選項為重複任務設定自定義指令。
您可以透過 `command` 選項為重複任務設定自訂指令。
```jsonc title="opencode.jsonc"
{
@@ -396,13 +396,13 @@ Bearer Token (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 優先於基於設定
}
```
您也可以使用 `~/.config/opencode/commands/` 或 `.opencode/commands/` 中的 Markdown 檔案定義指令。 [在這裡了解更多](/docs/commands)。
您還可以使用 `~/.config/opencode/commands/` 或 `.opencode/commands/` 中的 Markdown 檔案定義指令。[在此了解更多](/docs/commands)。
---
### 按鍵綁定
### 快捷鍵
您可以透過 `keybinds` 選項自定義您的按鍵綁定。
您可以透過 `keybinds` 選項自訂快捷鍵。
```json title="opencode.json"
{
@@ -411,13 +411,13 @@ Bearer Token (`AWS_BEARER_TOKEN_BEDROCK` 或 `/connect`) 優先於基於設定
}
```
[在這裡了解更多](/docs/keybinds)。
[在此了解更多](/docs/keybinds)。
---
### 自動更新
opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoupdate` 選項禁用此功能。
OpenCode 啟動時會自動下載新版本。您可以使用 `autoupdate` 選項停用此功能。
```json title="opencode.json"
{
@@ -426,14 +426,14 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
如果您不想更新但希望在新版本可用時收到通知，請將 `autoupdate` 設定為 `"notify"`。
請注意，這僅在未使用 Homebrew 等套件管理器安裝時才有效。
如果您不想自動更新但希望在新版本可用時收到通知，可將 `autoupdate` 設定為 `"notify"`。
請注意，此功能僅在未透過 Homebrew 等套件管理器安裝時有效。
---
### 格式化程式
### 格式化器
您可以透過 `formatter` 選項設定程式碼格式化程式。
您可以透過 `formatter` 選項設定程式碼格式化器。
```json title="opencode.json"
{
@@ -453,15 +453,15 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
[在此處了解有關格式化程式的更多資訊](/docs/formatters)。
[在此了解更多關於格式化器的資訊](/docs/formatters)。
---
### 權限
預設情況下，opencode **允許所有操作**，無需明確批准。您可以使用 `permission` 選項更改此設定。
預設情況下，OpenCode **允許所有操作**，無需明確批准。您可以使用 `permission` 選項變更此行為。
例如，要確保 `edit` 和 `bash` 工具需要使用者批准：
例如，要讓 `edit` 和 `bash` 工具需要使用者確認：
```json title="opencode.json"
{
@@ -473,7 +473,7 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
[在此處了解有關權限的更多資訊](/docs/permissions)。
[在此了解更多關於權限的資訊](/docs/permissions)。
---
@@ -486,19 +486,21 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
"$schema": "https://opencode.ai/config.json",
"compaction": {
"auto": true,
"prune": true
"prune": true,
"reserved": 10000
}
}
```
- `auto` - 當上下文已滿時自動壓縮工作階段（預設值：`true`）。
- `prune` - 刪除舊工具輸出以節省 tokens（預設值：`true`）。
- `prune` - 刪除舊的工具輸出以節省 Token（預設值：`true`）。
- `reserved` - 壓縮時的 Token 緩衝區。保留足夠的窗口以避免壓縮過程中溢出。
---
### 觀察者 (Watcher)
### 檔案監看器
您可以透過 `watcher` 選項設定檔案觀察器忽略模式。
您可以透過 `watcher` 選項設定檔案監看器的忽略模式。
```json title="opencode.json"
{
@@ -509,7 +511,7 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
模式遵循 glob 語法。使用它可以從檔案監視中排除嘈雜的目錄。
模式遵循 glob 語法。使用此選項可以從檔案監看中排除頻繁變動的目錄。
---
@@ -524,15 +526,15 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
[在這裡了解更多](/docs/mcp-servers)。
[在此了解更多](/docs/mcp-servers)。
---
### 外掛
### 外掛程式
[外掛](/docs/plugins) 使用自定義工具、掛鉤和整合擴展 opencode。
[外掛程式](/docs/plugins)透過自訂工具、掛鉤和整合來擴展 OpenCode。
將外掛檔案放置在 `.opencode/plugins/` 或 `~/.config/opencode/plugins/` 中。您也可以透過 `plugin` 選項從 npm 載入外掛。
將外掛程式檔案放置在 `.opencode/plugins/` 或 `~/.config/opencode/plugins/` 中。您還可以透過 `plugin` 選項從 npm 載入外掛程式。
```json title="opencode.json"
{
@@ -541,13 +543,13 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
[在這裡了解更多](/docs/plugins)。
[在此了解更多](/docs/plugins)。
---
### 指示 (Instructions)
### 指示
您可以透過 `instructions` 選項設定您正在使用的模型的指示。
您可以透過 `instructions` 選項為所使用的模型設定指示。
```json title="opencode.json"
{
@@ -556,13 +558,13 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
這需要指示檔案的路徑和全域模式陣列。 [了解更多關於規則在這裡](/docs/rules)。
該選項接受指示檔案路徑和 glob 模式的陣列。[在此了解更多關於規則的資訊](/docs/rules)。
---
### 禁用供應商
### 停用供應商
您可以透過 `disabled_providers` 選項禁用自動載入的供應商。當您想要阻止載入某些供應商（即使其憑證可用）時，這非常有用。
您可以透過 `disabled_providers` 選項停用自動載入的供應商。當您希望阻止某些供應商被載入（即使其憑證可用）時，此選項非常有用。
```json title="opencode.json"
{
@@ -575,17 +577,17 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
`disabled_providers` 優先於 `enabled_providers`。
:::
`disabled_providers` 選項接受供應商 ID 陣列。當供應商被禁用時：
`disabled_providers` 選項接受供應商 ID 的陣列。當某個供應商被停用時：
- 即使設定了環境變數也不會載入。
- 即使透過 `/connect` 指令設定 API 金鑰，也不會載入它。
- 供應商的模型不會出現在模型選擇列表中。
- 即使設定了環境變數，也不會被載入。
- 即使透過 `/connect` 指令設定了 API 金鑰，也不會被載入。
- 該供應商的模型不會出現在模型選擇列表中。
---
### 啟用的供應商
### 啟用供應商
您可以透過 `enabled_providers` 選項指定供應商的允許清單。設定後，僅啟用指定的供應商，所有其他供應商將被忽略。
您可以透過 `enabled_providers` 選項指定允許使用的供應商白名單。設定後，僅啟用指定的供應商，所有其他供應商將被忽略。
```json title="opencode.json"
{
@@ -594,19 +596,19 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
當您想要限制 opencode 僅使用特定的供應商而不是一一禁用它們時，這非常有用。
當您希望限制 OpenCode 僅使用特定供應商，而不是逐一停用其他供應商時，此選項非常有用。
:::note
`disabled_providers` 優先於 `enabled_providers`。
:::
如果某個供應商同時出現在 `enabled_providers` 和 `disabled_providers` 中，則 `disabled_providers` 優先考慮向後相容性。
如果某個供應商同時出現在 `enabled_providers` 和 `disabled_providers` 中，為了向後相容，`disabled_providers` 優先。
---
### 實驗性的
### 實驗性功能
`experimental` 鍵包含正在積極開發的選項。
`experimental` 鍵包含正在積極開發中的選項。
```json title="opencode.json"
{
@@ -616,20 +618,20 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
```
:::caution
實驗選項不穩定。它們可能會更改或被刪除，恕不另行通知。
實驗性選項不穩定。它們可能會在不另行通知的情況下被變更或移除。
:::
---
## 變數
您可以在設定檔中使用變數替換來引用環境變數和檔案內容。
您可以在設定檔中使用變數替換來參照環境變數和檔案內容。
---
### 環境變數
使用 `{env:VARIABLE_NAME}` 替換環境變數：
使用 `{env:VARIABLE_NAME}` 來替換環境變數：
```json title="opencode.json"
{
@@ -646,13 +648,13 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
}
```
如果未設定環境變數，它將被替換為空字串。
如果環境變數未設定，它將被替換為空字串。
---
### 檔案
使用 `{file:path/to/file}` 替換檔案的內容：
使用 `{file:path/to/file}` 來替換檔案內容：
```json title="opencode.json"
{
@@ -670,11 +672,11 @@ opencode 將在啟動時自動下載任何新的更新。您可以使用 `autoup
檔案路徑可以是：
- 相對於設定檔目錄
- 或者以 `/` 或 `~` 開頭的絕對路徑
- 相對於設定檔所在目錄的路徑
- 以 `/` 或 `~` 開頭的絕對路徑
這些對於：
這些功能適用於：
- 將 API 金鑰等敏感數據保存在單獨的檔案中。
- 包含大型指示檔案，而不會弄亂您的設定。
- 跨多個設定檔共享通用設定片段。
- 將 API 金鑰等敏感資料保存在單獨的檔案中。
- 引入大型指示檔案而不會使設定變得雜亂。
- 在多個設定檔之間共享通用設定片段。

48
packages/web/src/content/docs/zh-tw/custom-tools.mdx
View File

@@ -1,30 +1,30 @@
---
title: 自定義工具
description: 建立 LLM 可以在 opencode 中呼叫的工具。
title: 自訂工具
description: 建立 LLM 可在 OpenCode 中呼叫的工具。
---
自定義工具是您建立的函式，LLM 可以在對話期間呼叫。它們與 opencode 的 [內建工具](/docs/tools) 一起工作，例如 `read`、`write` 和 `bash`。
自訂工具是您建立的函式，LLM 可以在對話過程中呼叫它們。它們與 OpenCode 的[內建工具](/docs/tools)（如 `read`、`write` 和 `bash`）協同工作。
---
## 建立工具
工具定義為 **TypeScript** 或 **JavaScript** 檔案。但是，工具定義可以呼叫用 **任何語言** 編寫的指令碼 - TypeScript 或 JavaScript 僅用於工具定義本身。
工具以 **TypeScript** 或 **JavaScript** 檔案的形式定義。不過，工具定義可以呼叫**任何語言**編寫的指令碼——TypeScript 或 JavaScript 僅用於工具定義本身。
---
### 位置
它們可以定義為：
工具可以在以下位置定義：
- 透過將它們放在專案的 `.opencode/tools/` 目錄中來本地進行。
- 或者在全域範圍內，將它們放置在 `~/.config/opencode/tools/` 中。
- 本地定義：將工具檔案放在專案的 `.opencode/tools/` 目錄中。
- 全域定義：將工具檔案放在 `~/.config/opencode/tools/` 中。
---
### 結構
建立工具的最簡單方法是使用 `tool()` 輔助程式，它提供類型安全和驗證。
建立工具最簡單的方式是使用 `tool()` 輔助函式，它提供型別安全和參數校驗。
```ts title=".opencode/tools/database.ts" {1}
import { tool } from "@opencode-ai/plugin"
@@ -41,13 +41,13 @@ export default tool({
})
```
**檔名**成為**工具名稱**。以上建立了一個 `database` 工具。
**檔案名稱**即為**工具名稱**。上面的範例建立了一個名為 `database` 的工具。
---
#### 每個檔案多個工具
#### 單檔案多工具
您也可以從單個檔案匯出多個工具。每個匯出都會成為**一個單獨的工具**，名稱為 **`<filename>_<exportname>`**：
您也可以從單個檔案中匯出多個工具。每個匯出都會成為**一個獨立的工具**，命名格式為 **`<filename>_<exportname>`**：
```ts title=".opencode/tools/math.ts"
import { tool } from "@opencode-ai/plugin"
@@ -75,13 +75,13 @@ export const multiply = tool({
})
```
這將建立兩個工具：`math_add` 和 `math_multiply`。
這會建立兩個工具：`math_add` 和 `math_multiply`。
---
### 參數 (Arguments)
### 參數
您可以使用 `tool.schema`（即 [Zod](https://zod.dev)）來定義參數類型。
您可以使用 `tool.schema`（即 [Zod](https://zod.dev)）來定義參數型別。
```ts "tool.schema"
args: {
@@ -89,7 +89,7 @@ args: {
}
```
您也可以直接匯入 [Zod](https://zod.dev) 並返回一個一般物件：
您也可以直接匯入 [Zod](https://zod.dev) 並回傳一個普通物件：
```ts {6}
import { z } from "zod"
@@ -108,9 +108,9 @@ export default {
---
### 上下文 (Context)
### 上下文
工具接收有關當前工作階段的上下文：
工具會接收當前工作階段的上下文資訊：
```ts title=".opencode/tools/project.ts" {8}
import { tool } from "@opencode-ai/plugin"
@@ -126,18 +126,18 @@ export default tool({
})
```
使用 `context.directory` 作為工作階段工作目錄。
使用 `context.worktree` 作為 git 工作樹根。
使用 `context.directory` 取得工作階段的工作目錄。
使用 `context.worktree` 取得 git worktree 根目錄。
---
## 範例
### 用 Python 編寫一個工具
### 用 Python 編寫工具
您可以用任何您想要的語言編寫工具。下面是一個使用 Python 將兩個數字相加的範例。
您可以使用任何語言編寫工具。以下範例展示了如何用 Python 實作兩數相加。
首先，將該工具建立為 Python 指令碼：
首先，建立一個 Python 指令碼作為工具：
```python title=".opencode/tools/add.py"
import sys
@@ -147,7 +147,7 @@ b = int(sys.argv[2])
print(a + b)
```
然後建立呼叫它的工具定義：
然後建立呼叫該指令碼的工具定義：
```ts title=".opencode/tools/python-add.ts" {10}
import { tool } from "@opencode-ai/plugin"
@@ -167,4 +167,4 @@ export default tool({
})
```
這裡我們使用 [`Bun.$`](https://bun.com/docs/runtime/shell) 公用程式來執行 Python 指令碼。
這裡我們使用 [`Bun.$`](https://bun.com/docs/runtime/shell) 工具函式來執行 Python 指令碼。

102
packages/web/src/content/docs/zh-tw/ecosystem.mdx
View File

@@ -1,76 +1,76 @@
---
title: 生態系統
description: 使用 opencode 構建的專案和整合。
description: 基於 OpenCode 建置的專案與整合。
---
基於 opencode 的社群專案集合。
基於 OpenCode 建置的社群專案合集。
:::note
想要將您的 opencode 相關專案添加到此列表中嗎？提交 PR。
想將您的 OpenCode 相關專案新增到此列表中？歡迎提交 PR。
:::
您也可以查看 [awesome-opencode](https://github.com/awesome-opencode/awesome-opencode) 和 [opencode.cafe](https://opencode.cafe)，這是一個聚合生態系統和社群的社群。
您還可以查看 [awesome-opencode](https://github.com/awesome-opencode/awesome-opencode) 和 [opencode.cafe](https://opencode.cafe)，這是一個聚合生態系統與社群資源的社群。
---
## 外掛
## 外掛程式
| 名稱 | 描述 |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [opencode-daytona](https://github.com/jamesmurdza/daytona/blob/main/guides/typescript/opencode/README.md) | 使用 git 同步和即時預覽在隔離的 Daytona 沙箱中自動執行 opencode 工作階段 |
| [opencode-helicone-session](https://github.com/H2Shami/opencode-helicone-session) | 自動注入 Helicone 工作階段標頭以進行請求分組 |
| [opencode-type-inject](https://github.com/nick-vi/opencode-type-inject) | 使用搜尋工具將 TypeScript/Svelte 類型自動注入到檔案讀取中 |
| [opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth) | 使用您的 ChatGPT Plus/Pro 訂閱而不是 API 額度 |
| [opencode-gemini-auth](https://github.com/jenslys/opencode-gemini-auth) | 使用您現有的 Gemini 計畫而不是 API 計費 |
| [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) | 使用 Antigravity 的免費模型代替 API 計費 |
| [opencode-devcontainers](https://github.com/athal7/opencode-devcontainers) | 具有淺層複製和自動分配連接埠的多分支開發容器隔離 |
| [opencode-google-antigravity-auth](https://github.com/shekohex/opencode-google-antigravity-auth) | Google Antigravity OAuth 外掛，支援 Google 搜尋和更強大的 API 處理 |
| [opencode-dynamic-context-pruning](https://github.com/Tarquinen/opencode-dynamic-context-pruning) | 透過修剪過時的工具輸出來最佳化代幣使用 |
| [opencode-websearch-cited](https://github.com/ghoulr/opencode-websearch-cited.git) | 為具有 Google Grounding 風格的受支援供應商添加原生網路搜尋支援 |
| [opencode-pty](https://github.com/shekohex/opencode-pty.git) | 使 AI 代理能夠在 PTY 中執行背景處理程序，並向其發送互動式輸入。 |
| [opencode-shell-strategy](https://github.com/JRedeker/opencode-shell-strategy) | 非互動式 shell 指令說明 - 防止依賴 TTY 的操作卡住 |
| [opencode-wakatime](https://github.com/angristan/opencode-wakatime) | 使用 Wakatime 追蹤 opencode 使用情況 |
| 名稱 | 說明 |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [opencode-daytona](https://github.com/jamesmurdza/daytona/blob/main/guides/typescript/opencode/README.md) | 在隔離的 Daytona 沙箱中自動執行 OpenCode 工作階段，支援 git 同步和即時預覽 |
| [opencode-helicone-session](https://github.com/H2Shami/opencode-helicone-session) | 自動注入 Helicone 工作階段標頭資訊，用於請求分組 |
| [opencode-type-inject](https://github.com/nick-vi/opencode-type-inject) | 透過搜尋工具自動將 TypeScript/Svelte 型別注入到檔案讀取中 |
| [opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth) | 使用您的 ChatGPT Plus/Pro 訂閱替代 API 額度 |
| [opencode-gemini-auth](https://github.com/jenslys/opencode-gemini-auth) | 使用您現有的 Gemini 方案替代 API 計費 |
| [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) | 使用 Antigravity 的免費模型替代 API 計費 |
| [opencode-devcontainers](https://github.com/athal7/opencode-devcontainers) | 多分支開發容器隔離，支援淺層複製和自動分配連接埠 |
| [opencode-google-antigravity-auth](https://github.com/shekohex/opencode-google-antigravity-auth) | Google Antigravity OAuth 外掛程式，支援 Google 搜尋及更強健的 API 處理 |
| [opencode-dynamic-context-pruning](https://github.com/Tarquinen/opencode-dynamic-context-pruning) | 透過修剪過時的工具輸出來最佳化 Token 使用 |
| [opencode-websearch-cited](https://github.com/ghoulr/opencode-websearch-cited.git) | 為受支援的供應商新增原生網頁搜尋支援，採用 Google grounded 風格 |
| [opencode-pty](https://github.com/shekohex/opencode-pty.git) | 使 AI 代理能夠在 PTY 中執行背景處理程序，並向其傳送互動式輸入 |
| [opencode-shell-strategy](https://github.com/JRedeker/opencode-shell-strategy) | 非互動式 shell 指令說明——防止依賴 TTY 的操作導致卡住 |
| [opencode-wakatime](https://github.com/angristan/opencode-wakatime) | 使用 Wakatime 追蹤 OpenCode 的使用情況 |
| [opencode-md-table-formatter](https://github.com/franlol/opencode-md-table-formatter/tree/main) | 清理 LLM 生成的 Markdown 表格 |
| [opencode-morph-fast-apply](https://github.com/JRedeker/opencode-morph-fast-apply) | 使用 Morph Fast Apply API 和惰性編輯標記將程式碼編輯速度提高 10 倍 |
| [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) | 背景代理、預先建置的 LSP/AST/MCP 工具、精選代理、相容 Claude Code |
| [opencode-notificator](https://github.com/panta82/opencode-notificator) | opencode 工作階段的桌面通知和聲音警報 |
| [opencode-notifier](https://github.com/mohak34/opencode-notifier) | 針對權限、完成和錯誤事件的桌面通知和聲音警報 |
| [opencode-zellij-namer](https://github.com/24601/opencode-zellij-namer) | 基於 opencode 上下文的 AI 支援的自動 Zellij 工作階段命名 |
| [opencode-skillful](https://github.com/zenobi-us/opencode-skillful) | 允許 opencode 代理透過技能發現和注入按需延遲載入提示 |
| [opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory) | 使用超級記憶體跨工作階段持久記憶體 |
| [@plannotator/opencode](https://github.com/backnotprop/plannotator/tree/main/apps/opencode-plugin) | 具有視覺註釋和私人/離線分享的互動式計畫審查 |
| [@openspoon/subtask2](https://github.com/spoons-and-mirrors/subtask2) | 將 opencode/指令擴展為具有精細流程控制的強大編排系統 |
| [opencode-scheduler](https://github.com/different-ai/opencode-scheduler) | 使用帶有 cron 語法的 launchd (Mac) 或 systemd (Linux) 安排重複作業 |
| [micode](https://github.com/vtemian/micode) | 結構化腦力激盪 → 計畫 → 實作具有會議連續性的工作流程 |
| [octto](https://github.com/vtemian/octto) | 用於透過多問題形式進行 AI 腦力激盪的互動式瀏覽器 UI |
| [opencode-background-agents](https://github.com/kdcokenny/opencode-background-agents) | 具有非同步委託和上下文持久性的 Claude Code 風格背景代理 |
| [opencode-notify](https://github.com/kdcokenny/opencode-notify) | opencode 的原生作業系統通知 – 了解任務何時完成 |
| [opencode-workspace](https://github.com/kdcokenny/opencode-workspace) | 捆綁的多代理編排工具 – 16 個組件，一次安裝 |
| [opencode-worktree](https://github.com/kdcokenny/opencode-worktree) | opencode 的零摩擦 git 工作樹 |
| [opencode-morph-fast-apply](https://github.com/JRedeker/opencode-morph-fast-apply) | 透過 Morph Fast Apply API 和惰性編輯標記實現 10 倍更快的程式碼編輯 |
| [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) | 背景代理、預建置的 LSP/AST/MCP 工具、精選代理，相容 Claude Code |
| [opencode-notificator](https://github.com/panta82/opencode-notificator) | OpenCode 工作階段的桌面通知和聲音提醒 |
| [opencode-notifier](https://github.com/mohak34/opencode-notifier) | 針對權限請求、任務完成和錯誤事件的桌面通知與聲音提醒 |
| [opencode-zellij-namer](https://github.com/24601/opencode-zellij-namer) | 基於 OpenCode 上下文的 AI 驅動自動 Zellij 工作階段命名 |
| [opencode-skillful](https://github.com/zenobi-us/opencode-skillful) | 允許 OpenCode 代理透過技能發現和注入按需延遲載入提示詞 |
| [opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory) | 使用 Supermemory 實現跨工作階段的持久記憶 |
| [@plannotator/opencode](https://github.com/backnotprop/plannotator/tree/main/apps/opencode-plugin) | 支援視覺化標註和私有/離線分享的互動式計畫審查 |
| [@openspoon/subtask2](https://github.com/spoons-and-mirrors/subtask2) | 將 OpenCode /commands 擴展為具有精細流程控制的強大編排系統 |
| [opencode-scheduler](https://github.com/different-ai/opencode-scheduler) | 使用 cron 語法透過 launchd (Mac) 或 systemd (Linux) 排程週期性任務 |
| [micode](https://github.com/vtemian/micode) | 結構化的腦力激盪 → 計畫 → 實作工作流程，支援工作階段連續性 |
| [octto](https://github.com/vtemian/octto) | 用於 AI 腦力激盪的互動式瀏覽器 UI，支援多問題表單 |
| [opencode-background-agents](https://github.com/kdcokenny/opencode-background-agents) | Claude Code 風格的背景代理，支援非同步委派和上下文持久化 |
| [opencode-notify](https://github.com/kdcokenny/opencode-notify) | OpenCode 的原生作業系統通知——隨時了解任務完成情況 |
| [opencode-workspace](https://github.com/kdcokenny/opencode-workspace) | 捆綁式多代理編排套件——16 個元件，一次安裝 |
| [opencode-worktree](https://github.com/kdcokenny/opencode-worktree) | OpenCode 的零摩擦 git worktree 管理 |
---
## 專案
| 名稱 | 描述 |
| 名稱 | 說明 |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| [kimaki](https://github.com/remorses/kimaki) | 用於控制 opencode 工作階段的 Discord 機器人，基於 SDK 構建 |
| [opencode.nvim](https://github.com/NickvanDyke/opencode.nvim) | Neovim 外掛，用於編輯器感知提示，基於 API 構建 |
| [portal](https://github.com/hosenur/portal) | 透過 Tailscale/VPN 實現 opencode 的行動優先 Web UI |
| [opencode plugin template](https://github.com/zenobi-us/opencode-plugin-template/) | 用於構建 opencode 外掛的範本 |
| [opencode.nvim](https://github.com/sudo-tee/opencode.nvim) | Neovim opencode 前端 - 基於終端機的 AI 程式碼代理 |
| [ai-sdk-provider-opencode-sdk](https://github.com/ben-vargas/ai-sdk-provider-opencode-sdk) | Vercel AI SDK 供應商，用於透過 @opencode-ai/sdk 使用 opencode |
| [OpenChamber](https://github.com/btriapitsyn/openchamber) | opencode 的 Web/桌面應用程式和 VS Code 擴充功能 |
| [OpenCode-Obsidian](https://github.com/mtymek/opencode-obsidian) | 在 Obsidian 的 UI 中嵌入 opencode 的 Obsidian 外掛 |
| [OpenWork](https://github.com/different-ai/openwork) | Claude Cowork 的開源替代方案，由 opencode 提供支援 |
| [ocx](https://github.com/kdcokenny/ocx) | opencode 擴充功能管理器具有可攜式、隔離的設定檔。 |
| [CodeNomad](https://github.com/NeuralNomadsAI/CodeNomad) | opencode 的桌面、Web、行動和遠端客戶端應用程式 |
| [kimaki](https://github.com/remorses/kimaki) | 用於控制 OpenCode 工作階段的 Discord 機器人，基於 SDK 建置 |
| [opencode.nvim](https://github.com/NickvanDyke/opencode.nvim) | Neovim 外掛程式，提供編輯器感知的提示詞，基於 API 建置 |
| [portal](https://github.com/hosenur/portal) | 透過 Tailscale/VPN 使用的行動優先 OpenCode Web UI |
| [opencode plugin template](https://github.com/zenobi-us/opencode-plugin-template/) | 用於建置 OpenCode 外掛程式的範本 |
| [opencode.nvim](https://github.com/sudo-tee/opencode.nvim) | OpenCode 的 Neovim 前端——基於終端機的 AI 編碼代理 |
| [ai-sdk-provider-opencode-sdk](https://github.com/ben-vargas/ai-sdk-provider-opencode-sdk) | Vercel AI SDK 供應商，用於透過 @opencode-ai/sdk 使用 OpenCode |
| [OpenChamber](https://github.com/btriapitsyn/openchamber) | OpenCode 的 Web / 桌面應用程式和 VS Code 擴充功能 |
| [OpenCode-Obsidian](https://github.com/mtymek/opencode-obsidian) | 將 OpenCode 嵌入 Obsidian UI 的 Obsidian 外掛程式 |
| [OpenWork](https://github.com/different-ai/openwork) | Claude Cowork 的開源替代方案，由 OpenCode 驅動 |
| [ocx](https://github.com/kdcokenny/ocx) | OpenCode 擴充功能管理器，支援可攜式的隔離設定 |
| [CodeNomad](https://github.com/NeuralNomadsAI/CodeNomad) | OpenCode 的桌面、Web、行動和遠端用戶端應用程式 |
---
## 代理
| 名稱 | 描述 |
| ----------------------------------------------------------------- | ---------------------------------------- |
| 名稱 | 說明 |
| ----------------------------------------------------------------- | ---------------------------------------------- |
| [Agentic](https://github.com/Cluster444/agentic) | 用於結構化開發的模組化 AI 代理和指令 |
| [opencode-agents](https://github.com/darrenhinde/opencode-agents) | 用於增強工作流程的設定、提示、代理和外掛 |
| [opencode-agents](https://github.com/darrenhinde/opencode-agents) | 用於增強工作流程的設定、提示詞、代理和外掛程式 |

86
packages/web/src/content/docs/zh-tw/enterprise.mdx
View File

@@ -1,47 +1,47 @@
---
title: 企業版
description: 在您的組織中安全地使用 opencode。
description: 在您的組織中安全地使用 OpenCode。
---
import config from "../../../../config.mjs"
export const email = `mailto:${config.email}`
opencode Enterprise 適用於希望確保其程式碼和資料永遠不會離開其基礎架構的組織。它可以透過使用與 SSO 和內部 AI 閘道整合的集中式設定來實現此目的。
OpenCode 企業版面向希望確保程式碼和資料始終留在自有基礎架構內的組織。它透過集中式設定與您的 SSO 和內部 AI 閘道整合來實現這一目標。
:::note
opencode 不儲存您的任何程式碼或上下文資料。
OpenCode 不會儲存您的任何程式碼或上下文資料。
:::
要開始使用 opencode Enterprise：
開始使用 OpenCode 企業版：
1. 與您的團隊進行內部試用。
2. **<a href={email}>聯絡我們</a>**討論定價和實作選項。
1. 在團隊內部進行試用。
2. **<a href={email}>聯絡我們</a>**，討論定價和實作方案。
---
## 試用
opencode 是開源的，不儲存您的任何程式碼或上下文資料，因此您的開發人員只需 [開始使用](/docs/) 並進行試用。
OpenCode 是開源的，不會儲存您的任何程式碼或上下文資料，因此您的開發人員可以直接[開始使用](/docs/)並進行試用。
---
### 資料處理
**opencode 不會儲存您的程式碼或上下文資料。** 所有處理都在本地進行或透過直接 API 呼叫您的 AI 供應商。
**OpenCode 不會儲存您的程式碼或上下文資料。**所有處理均在本地完成，或透過直接 API 呼叫傳送至您的 AI 供應商。
這意味著只要您使用您信任的供應商或內部 AI 閘道，您就可以安全使用 opencode。
這意味著，只要您使用的是信任的供應商或內部 AI 閘道，就可以安全地使用 OpenCode。
這裡唯一需要注意的是可選的 `/share` 功能。
唯一需要注意的是可選的 `/share` 功能。
---
#### 分享對話
如果使用者啟用 `/share` 功能，對話和與之關聯的資料將被發送到我們用於在 opencode.ai 上託管這些分享頁面的服務。
如果使用者啟用了 `/share` 功能，對話及其關聯資料將被傳送到我們用於在 opencode.ai 上託管共享頁面的服務。
資料當前透過我們的 CDN 邊緣網路提供服務，並快取在使用者附近的邊緣。
資料目前透過我們 CDN 的邊緣網路提供服務，並快取在靠近使用者的邊緣節點上。
我們建議您在試用時禁用此功能。
我們建議您在試用期間停用此功能。
```json title="opencode.json"
{
@@ -56,112 +56,110 @@ opencode 是開源的，不儲存您的任何程式碼或上下文資料，因
### 程式碼所有權
**您擁有 opencode 生成的所有程式碼。** 沒有授權限制或所有權聲明。
**您擁有 OpenCode 生成的所有程式碼。**不存在任何授權限制或所有權聲明。
---
## 定價
我們對 opencode Enterprise 使用按席位計費模式。如果您有自己的 LLM 閘道，我們不會對使用的 Tokens 收取費用。有關定價和實作選項的更多詳細資訊，請**<a href={email}>聯絡我們</a>**。
OpenCode 企業版採用按席位定價模型。如果您擁有自己的 LLM 閘道，我們不會對使用的 Token 收取費用。有關定價和實作方案的更多詳情，請**<a href={email}>聯絡我們</a>**。
---
## 部署
完成試用並準備好使用 opencode 後，請訪問：
您的組織，您可以**<a href={email}>聯絡我們</a>**進行討論
定價和實作選項。
完成試用並準備好在組織中使用 OpenCode 後，您可以**<a href={email}>聯絡我們</a>**，討論定價和實作方案。
---
### 中央設定
### 集中式設定
我們可以將 opencode 設定為為您的整個組織使用單一的中央設定。
我們可以為您的整個組織設定 OpenCode 的統一集中式設定。
這種集中式設定可以與您的 SSO 供應商整合，並確保所有使用者僅存取您的內部 AI 閘道。
該集中式設定可與您的 SSO 供應商整合，確保所有使用者僅存取您的內部 AI 閘道。
---
### 單一登入整合
### SSO 整合
透過中央設定，opencode 可以與您組織的 SSO 供應商整合以進行身分驗證。
透過集中式設定，OpenCode 可以與您組織的 SSO 供應商整合進行身分驗證。
這使得 opencode 能夠透過現有的身分管理系統取得內部 AI 閘道的憑證。
這使得 OpenCode 能夠透過您現有的身分管理系統取得內部 AI 閘道的憑證。
---
### 內部 AI 閘道
透過中央設定，opencode 還可以設定為僅使用您的內部 AI 閘道。
透過集中式設定，OpenCode 還可以被設定為僅使用您的內部 AI 閘道。
您還可以禁用所有其他 AI 供應商，確保所有請求都通過組織核准的基礎架構。
您還可以停用所有其他 AI 供應商，確保所有請求都經過組織核准的基礎架構。
---
### 自行託管
雖然我們建議禁用分享頁面以確保您的資料永遠不會離開您的組織，我們還可以幫助您在您的基礎架構上自行託管它們。
雖然我們建議停用共享頁面以確保您的資料始終不會離開組織，但我們也可以幫助您在自己的基礎架構上自行託管這些頁面。
目前這已在我們的路線圖上。如果您有興趣，**<a href={email}>讓我們知道</a>**。
此功能目前已列入我們的路線圖。如果您感興趣，請**<a href={email}>告訴我們</a>**。
---
## 常見問題
<details>
<summary>什麼是 opencode Enterprise？ </summary>
<summary>什麼是 OpenCode 企業版？</summary>
opencode Enterprise 適用於希望確保其程式碼和資料永遠不會離開其基礎架構的組織。它可以透過使用與 SSO 和內部 AI 閘道整合的集中式設定來實現此目的。
OpenCode 企業版面向希望確保程式碼和資料始終留在自有基礎架構內的組織。它透過集中式設定與您的 SSO 和內部 AI 閘道整合來實現這一目標。
</details>
<details>
<summary>如何開始使用 opencode Enterprise？ </summary>
<summary>如何開始使用 OpenCode 企業版？</summary>
只需與您的團隊進行內部試用即可。 opencode 預設情況下不儲存您的程式碼或上下文資料，因此可以輕鬆上手。
只需在團隊內部開始試用即可。OpenCode 預設不會儲存您的程式碼或上下文資料，因此可以輕鬆上手。
然後**<a href={email}>聯絡我們</a>**討論定價和實作選項。
然後**<a href={email}>聯絡我們</a>**，討論定價和實作方案。
</details>
<details>
<summary>企業定價如何運作？ </summary>
<summary>企業版定價如何運作？</summary>
我們提供按席位企業定價。如果您有自己的 LLM 閘道，我們不會對使用的 Tokens 收取費用。如需了解更多詳情，請**<a href={email}>聯絡我們</a>**，獲取根據您組織的需求客製化的報價。
我們提供按席位的企業版定價。如果您擁有自己的 LLM 閘道，我們不會對使用的 Token 收取費用。如需了解更多詳情，請**<a href={email}>聯絡我們</a>**，取得根據您組織需求訂製的報價。
</details>
<details>
<summary>opencode Enterprise 保證我的資料安全嗎？ </summary>
<summary>我的資料在 OpenCode 企業版中是否安全？</summary>
是的。 opencode 不儲存您的程式碼或上下文資料。所有處理都在本地進行或透過直接 API 呼叫您的 AI 供應商。透過中央設定和 SSO 整合，您的資料在組織的基礎架構中保持安全。
是的。OpenCode 不會儲存您的程式碼或上下文資料。所有處理均在本地完成，或透過直接 API 呼叫傳送至您的 AI 供應商。透過集中式設定和 SSO 整合，您的資料將安全地保留在組織的基礎架構內。
</details>
<details>
<summary>我們可以使用自己的私有 NPM Registry 嗎？ </summary>
<summary>我們可以使用自己的私有 NPM 註冊表嗎？</summary>
opencode 透過 Bun 的原生 `.npmrc` 檔案支援來支援私有 npm Registry。如果您的組織使用私有 Registry，例如 JFrog Artifactory、Nexus 或類似的 Registry，請確保開發人員在執行 opencode 之前經過身分驗證。
OpenCode 透過 Bun 原生的 `.npmrc` 檔案支援來支援私有 npm 註冊表。如果您的組織使用私有註冊表（例如 JFrog Artifactory、Nexus 或類似產品），請確保開發人員在執行 OpenCode 之前已完成身分驗證。
要使用您的私有 Registry 設定身分驗證：
要設定私有註冊表的身分驗證：
```bash
npm login --registry=https://your-company.jfrog.io/api/npm/npm-virtual/
```
這將建立帶有身分驗證詳細資訊的 `~/.npmrc`。 opencode 會自動讀取這個。
這會建立包含身分驗證資訊的 `~/.npmrc` 檔案。OpenCode 會自動識別並使用它。
:::caution
在執行 opencode 之前，您必須登入私有 Registry。
在執行 OpenCode 之前，您必須先登入私有註冊表。
:::
或者，您可以手動設定 `.npmrc` 檔案：
或者，您也可以手動設定 `.npmrc` 檔案：
```bash title="~/.npmrc"
registry=https://your-company.jfrog.io/api/npm/npm-virtual/
//your-company.jfrog.io/api/npm/npm-virtual/:_authToken=${NPM_AUTH_TOKEN}
```
開發人員必須在執行 opencode 之前登入私有 Registry，以確保可以從企業 Registry 安裝套件。
開發人員必須在執行 OpenCode 之前登入私有註冊表，以確保能夠從您的企業註冊表安裝套件。
</details>

97
packages/web/src/content/docs/zh-tw/formatters.mdx
View File

@@ -1,63 +1,64 @@
---
title: 格式化程式
description: opencode 使用特定於語言的格式化程式。
title: 格式化器
description: OpenCode 使用特定語言的格式化器。
---
使用特定於語言的格式化程式編寫或編輯檔案後，opencode 會自動格式化檔案。這可確保生成的程式碼遵循專案的程式碼風格。
OpenCode 會在檔案寫入或編輯後，自動使用特定語言的格式化器對其進行格式化。這確保了生成的程式碼遵循您專案的程式碼風格。
---
## 內建
## 內建格式化器
opencode 附帶了多個適用於流行語言和框架的內建格式化程式。下面是格式化程式、支援的檔案副檔名以及所需的指令或設定選項的列表。
OpenCode 內建了多種適用於主流語言和框架的格式化器。下表列出了各格式化器、支援的副檔名以及所需的指令或設定選項。
| 格式化程式 | 副檔名 | 要求 |
| -------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| gofmt | .go | `gofmt` 指令可用 |
| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | `mix` 指令可用 |
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, 和 [更多](https://prettier.io/docs/en/index.html) | `prettier` 中有 `package.json` 相依套件 |
| biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, 和 [更多](https://biomejs.dev/) | `biome.json(c)` 設定檔 |
| zig | .zig, .zon | `zig` 指令可用 |
| clang-format | .c, .cpp, .h, .hpp, .ino, 和 [更多](https://clang.llvm.org/docs/ClangFormat.html) | `.clang-format` 設定檔 |
| ktlint | .kt, .kts | `ktlint` 指令可用 |
| ruff | .py, .pyi | `ruff` 指令可用並設定完成 |
| rustfmt | .rs | `rustfmt` 指令可用 |
| cargofmt | .rs | `cargo fmt` 指令可用 |
| uv | .py, .pyi | `uv` 指令可用 |
| rubocop | .rb, .rake, .gemspec, .ru | `rubocop` 指令可用 |
| standardrb | .rb, .rake, .gemspec, .ru | `standardrb` 指令可用 |
| htmlbeautifier | .erb, .html.erb | `htmlbeautifier` 指令可用 |
| 格式化器 | 副檔名 | 要求 |
| -------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| air | .R | `air` 指令可用 |
| biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml 及[更多](https://biomejs.dev/) | `biome.json(c)` 設定檔 |
| cargofmt | .rs | `cargo fmt` 指令可用 |
| clang-format | .c, .cpp, .h, .hpp, .ino 及[更多](https://clang.llvm.org/docs/ClangFormat.html) | `.clang-format` 設定檔 |
| cljfmt | .clj, .cljs, .cljc, .edn | `cljfmt` 指令可用 |
| dart | .dart | `dart` 指令可用 |
| dfmt | .d | `dfmt` 指令可用 |
| ocamlformat | .ml, .mli | `ocamlformat` 指令可用，且存在 `.ocamlformat` 設定檔 |
| terraform | .tf, .tfvars | `terraform` 指令可用 |
| gleam | .gleam | `gleam` 指令可用 |
| gofmt | .go | `gofmt` 指令可用 |
| htmlbeautifier | .erb, .html.erb | `htmlbeautifier` 指令可用 |
| ktlint | .kt, .kts | `ktlint` 指令可用 |
| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | `mix` 指令可用 |
| nixfmt | .nix | `nixfmt` 指令可用 |
| shfmt | .sh, .bash | `shfmt` 指令可用 |
| pint | .php | `laravel/pint` 中有 `composer.json` 相依套件 |
| oxfmt (Experimental) | .js, .jsx, .ts, .tsx | `oxfmt` 中有 `package.json` 相依套件且啟用[實驗環境變數旗標](/docs/cli/#experimental) |
| ocamlformat | .ml, .mli | `ocamlformat` 指令可用且存在 `.ocamlformat` 設定檔 |
| ormolu | .hs | `ormolu` 指令可用 |
| oxfmt (Experimental) | .js, .jsx, .ts, .tsx | `package.json` 中有 `oxfmt` 相依套件，且設定了[實驗性環境變數旗標](/docs/cli/#experimental) |
| pint | .php | `composer.json` 中有 `laravel/pint` 相依套件 |
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml 及[更多](https://prettier.io/docs/en/index.html) | `package.json` 中有 `prettier` 相依套件 |
| rubocop | .rb, .rake, .gemspec, .ru | `rubocop` 指令可用 |
| ruff | .py, .pyi | `ruff` 指令可用且有相應設定 |
| rustfmt | .rs | `rustfmt` 指令可用 |
| shfmt | .sh, .bash | `shfmt` 指令可用 |
| standardrb | .rb, .rake, .gemspec, .ru | `standardrb` 指令可用 |
| terraform | .tf, .tfvars | `terraform` 指令可用 |
| uv | .py, .pyi | `uv` 指令可用 |
| zig | .zig, .zon | `zig` 指令可用 |
因此，如果您的專案的 `package.json` 中有 `prettier`，opencode 將自動使用它。
因此，如果您的專案 `package.json` 中包含 `prettier`，OpenCode 會自動使用它進行格式化。
---
## 它是如何運作的
## 工作原理
當 opencode 寫入或編輯檔案時，它：
當 OpenCode 寫入或編輯檔案時，它會：
1. 根據所有啟用的格式化程式檢查檔案副檔名。
2. 對檔案執行適當的格式化程式指令。
3. 自動套用格式變更。
1. 根據所有已啟用的格式化器檢查副檔名。
2. 對檔案執行相應的格式化指令。
3. 自動套用格式化變更。
此過程在背景進行，確保無需任何手動步驟即可維護您的程式碼樣式。
整個過程在背景完成，無需任何手動操作即可保持程式碼風格的一致性。
---
## 設定
您可以透過 opencode 設定中的 `formatter` 部分自定義格式化程式。
您可以透過 OpenCode 設定中的 `formatter` 部分自訂格式化器。
```json title="opencode.json"
{
@@ -66,22 +67,22 @@ opencode 附帶了多個適用於流行語言和框架的內建格式化程式
}
```
每個格式化程式設定支援以下內容：
每個格式化器的設定支援以下屬性：
| 屬性 | 類型 | 描述 |
| ------------- | ------ | ---------------------------------- |
| `disabled` | 布林值 | 將其設定為 `true` 以禁用格式化程式 |
| `command` | 字串[] | 格式化執行的指令 |
| `environment` | 物件 | 執行格式化程式時要設定的環境變數 |
| `extensions` | 字串[] | 此格式化程式應處理的檔案副檔名 |
| 屬性 | 型別 | 說明 |
| ------------- | -------- | ---------------------------- |
| `disabled` | boolean | 設為 `true` 可停用該格式化器 |
| `command` | string[] | 執行格式化的指令 |
| `environment` | object | 執行格式化器時設定的環境變數 |
| `extensions` | string[] | 該格式化器處理的副檔名 |
讓我們看一些例子。
下面來看一些範例。
---
### 禁用格式化程式
### 停用格式化器
要全域禁用**所有**格式化程式，請將 `formatter` 設定為 `false`：
要全域停用**所有**格式化器，將 `formatter` 設為 `false`：
```json title="opencode.json" {3}
{
@@ -90,7 +91,7 @@ opencode 附帶了多個適用於流行語言和框架的內建格式化程式
}
```
要禁用**特定**格式化程式，請將 `disabled` 設定為 `true`：
要停用**特定**格式化器，將 `disabled` 設為 `true`：
```json title="opencode.json" {5}
{
@@ -105,9 +106,9 @@ opencode 附帶了多個適用於流行語言和框架的內建格式化程式
---
### 自定義格式化程式
### 自訂格式化器
您可以覆寫內建格式化程式或透過指定指令、環境變數和檔案副檔名新增新格式化程式：
您可以透過指定指令、環境變數和副檔名來覆寫內建格式化器或新增新的格式化器：
```json title="opencode.json" {4-14}
{
@@ -128,4 +129,4 @@ opencode 附帶了多個適用於流行語言和框架的內建格式化程式
}
```
指令中的 **`$FILE` 預留位置** 將替換為正在格式化的檔案的路徑。
指令中的 **`$FILE` 佔位符**會被替換為待格式化檔案的路徑。

116
packages/web/src/content/docs/zh-tw/github.mdx
View File

@@ -1,43 +1,43 @@
---
title: GitHub
description: 在 GitHub Issues 和拉取請求中使用 opencode。
description: 在 GitHub Issue 和 Pull Request 中使用 OpenCode。
---
opencode 與您的 GitHub 工作流程整合。在評論中提及 `/opencode` 或 `/oc`，opencode 將在您的 GitHub Actions Runner 中執行任務。
OpenCode 可以與您的 GitHub 工作流程整合。在評論中提及 `/opencode` 或 `/oc`，OpenCode 就會在您的 GitHub Actions Runner 中執行任務。
---
## 功能
## 功能特性
- **分類問題**：要求 opencode 調查問題並向您解釋。
- **修復和實作**：要求 opencode 修復問題或實作功能。它將在一個新分支中工作並提交包含所有變更的 PR。
- **安全**：opencode 在 GitHub 的 Runner 中執行。
- **Issue 分類**：讓 OpenCode 調查某個 Issue 並為您做出解釋。
- **修復與實作**：讓 OpenCode 修復 Issue 或實作某個功能。它會在新分支中工作，並提交包含所有變更的 PR。
- **安全可靠**：OpenCode 在您自己的 GitHub Runner 中執行。
---
## 安裝
在 GitHub 儲存庫中的專案中執行以下指令：
在一個位於 GitHub 儲存庫中的專案裡執行以下指令：
```bash
opencode github install
```
這將引導您完成安裝 GitHub 應用程式、建立工作流程和設定 Secrets。
該指令會引導您完成 GitHub App 的安裝、工作流程的建立以及密鑰的設定。
---
### 手動設定
或者您可以手動設定。
您也可以手動進行設定。
1. **安裝 GitHub 應用程式**
1. **安裝 GitHub App**
前往 [**github.com/apps/opencode-agent**](https://github.com/apps/opencode-agent)。確保它已安裝在目標儲存庫上。
前往 [**github.com/apps/opencode-agent**](https://github.com/apps/opencode-agent)，確保已在目標儲存庫中安裝該應用程式。
2. **新增工作流程**
將以下工作流程檔案新增到儲存庫中的 `.github/workflows/opencode.yml` 中。確保在 `env` 中設定適當的 `model` 和所需的 API 金鑰。
將以下工作流程檔案新增到儲存庫的 `.github/workflows/opencode.yml` 中。請確保在 `env` 中設定合適的 `model` 及所需的 API 金鑰。
```yml title=".github/workflows/opencode.yml" {24,26}
name: opencode
@@ -73,21 +73,21 @@ opencode github install
# github_token: xxxx
```
3. **設定 Secrets**
3. **將 API 金鑰儲存到 Secrets 中**
在您的組織或專案的 **Settings** 中，展開左側的 **Secrets and variables**，然後選擇 **Actions**。並新增所需的 API 金鑰。
在您的組織或專案的 **Settings** 中，展開左側的 **Secrets and variables**，然後選擇 **Actions**，新增所需的 API 金鑰。
---
## 設定
- `model`：與 opencode 一起使用的模型。採用 `provider/model` 格式。這是**必需的**。
- `agent`: 使用的代理。必須是主要代理。如果未找到，則從設定退回到 `default_agent` 或 `"build"`。
- `share`：是否分享 opencode 工作階段。對於公共儲存庫，預設為 **true**。
- `prompt`：可選的自定義提示以覆寫預設行為。使用它來自定義 opencode 處理請求的方式。
- `token`：可選的 GitHub 存取權杖，用於執行建立評論、提交變更和打開拉取請求等操作。預設情況下，opencode 使用來自 opencode GitHub 應用程式的安裝存取權杖，因此提交、評論和拉取請求顯示為來自應用程式。
- `model`：OpenCode 使用的模型，格式為 `provider/model`。此項為**必填**。
- `agent`：要使用的代理，必須是主代理。如果未找到，則回退到設定中的 `default_agent`，若仍未找到則使用 `"build"`。
- `share`：是否共享 OpenCode 工作階段。對於公開儲存庫，預設為 **true**。
- `prompt`：可選的自訂提示詞，用於覆寫預設行為。可透過此項自訂 OpenCode 處理請求的方式。
- `token`：可選的 GitHub 存取權杖，用於執行建立評論、提交變更和建立 Pull Request 等操作。預設情況下，OpenCode 使用 OpenCode GitHub App 的安裝存取權杖，因此提交、評論和 Pull Request 會顯示為來自該應用程式。
或者，您可以使用 GitHub Action Runner 的 [內建 `GITHUB_TOKEN`](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token)，而無需安裝 opencode GitHub 應用程式。只需確保在您的工作流程中授予所需的權限：
您也可以使用 GitHub Action Runner 內建的 [`GITHUB_TOKEN`](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token)，而無需安裝 OpenCode GitHub App。只需確保在工作流程中授予所需的權限：
```yaml
permissions:
@@ -97,26 +97,26 @@ opencode github install
issues: write
```
**注意**：使用 `GITHUB_TOKEN` 時，opencode 執行的操作（如提交和評論）將不會觸發其他工作流程。
如果您願意，也可以使用[個人存取權杖](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)（PAT）。
---
## 支援的事件
opencode 可以由以下 GitHub 事件觸發：
OpenCode 可以由以下 GitHub 事件觸發：
| 事件類型 | 觸發條件 | 詳情 |
| ----------------------------- | ------------------------------ | --------------------------------------------------------------------------------------- |
| `issue_comment` | 對問題或 PR 發表評論 | 在評論中提及 `/opencode` 或 `/oc`。 opencode 讀取上下文並可以建立分支、打開 PR 或回覆。 |
| `pull_request_review_comment` | 對 PR 中的特定程式碼行進行評論 | 在檢查程式碼時提及 `/opencode` 或 `/oc`。 opencode 接收檔案路徑、行號和 diff 上下文。 |
| `issues` | 問題已打開或已編輯 | 建立或修改問題時自動觸發 opencode。需要 `prompt` 輸入。 |
| `pull_request` | PR 已開啟或已更新 | 當 PR 被開啟、同步或重新開啟時自動觸發 opencode。對於自動評論很有用。 |
| `schedule` | 基於 Cron 的排程 | 按排程執行 opencode。需要 `prompt` 輸入。輸出進入日誌和 PR（沒有可評論的問題）。 |
| `workflow_dispatch` | 從 GitHub UI 手動觸發 | 透過「Actions」標籤按需觸發 opencode。需要 `prompt` 輸入。輸出進入日誌和 PR。 |
| 事件類型 | 觸發方式 | 詳情 |
| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------- |
| `issue_comment` | 在 Issue 或 PR 上發表評論 | 在評論中提及 `/opencode` 或 `/oc`。OpenCode 會讀取上下文，並可建立分支、提交 PR 或回覆。 |
| `pull_request_review_comment` | 在 PR 中對特定程式碼行發表評論 | 在程式碼審查時提及 `/opencode` 或 `/oc`。OpenCode 會接收檔案路徑、行號和 diff 上下文。 |
| `issues` | Issue 被建立或編輯 | 在 Issue 建立或修改時自動觸發 OpenCode。需要提供 `prompt` 輸入。 |
| `pull_request` | PR 被建立或更新 | 在 PR 被開啟、同步或重新開啟時自動觸發 OpenCode。適用於自動化審查情境。 |
| `schedule` | 基於 Cron 的定時任務 | 按排程執行 OpenCode。需要提供 `prompt` 輸入。輸出會寫入日誌和 PR（沒有 Issue 可供評論）。 |
| `workflow_dispatch` | 從 GitHub UI 手動觸發 | 透過 Actions 分頁按需觸發 OpenCode。需要提供 `prompt` 輸入。輸出會寫入日誌和 PR。 |
### 排程範例
### 定時任務範例
按排程執行 opencode 以執行自動化任務：
按排程執行 OpenCode 以執行自動化任務：
```yaml title=".github/workflows/opencode-scheduled.yml"
name: Scheduled OpenCode Task
@@ -150,13 +150,13 @@ jobs:
If you find issues worth addressing, open an issue to track them.
```
對於排程事件，`prompt` 輸入是**必需的**，因為沒有註釋可從中提取指令。排程工作流程在沒有使用者上下文的情況下執行以進行權限檢查，因此如果您希望 opencode 建立分支或 PR，工作流程必須授予 `contents: write` 和 `pull-requests: write`。
對於定時事件，`prompt` 輸入為**必填**，因為沒有評論可供提取指令。定時工作流程在執行時沒有使用者上下文來進行權限檢查，因此如果您希望 OpenCode 建立分支或 PR，工作流程必須授予 `contents: write` 和 `pull-requests: write` 權限。
---
### 拉取請求範例
### Pull Request 範例
打開或更新 PR 時自動審閱：
在 PR 被建立或更新時自動進行審查：
```yaml title=".github/workflows/opencode-review.yml"
name: opencode-review
@@ -191,13 +191,13 @@ jobs:
- Suggest improvements
```
對於 `pull_request` 事件，如果未提供 `prompt`，opencode 將預設審閱拉取請求。
對於 `pull_request` 事件，如果未提供 `prompt`，OpenCode 將預設對該 Pull Request 進行審查。
---
### 問題分類範例
### Issue 分類範例
自動分類新問題。此範例過濾超過 30 天的帳號以減少垃圾訊息：
自動分類新建的 Issue。以下範例會過濾掉註冊不滿 30 天的帳戶以減少垃圾訊息：
```yaml title=".github/workflows/opencode-triage.yml"
name: Issue Triage
@@ -246,13 +246,13 @@ jobs:
Otherwise, do not comment.
```
對於 `issues` 事件，`prompt` 輸入是**必需的**，因為沒有評論可從中提取指令。
對於 `issues` 事件，`prompt` 輸入為**必填**，因為沒有評論可供提取指令。
---
## 自定義提示
## 自訂提示詞
覆寫預設提示，為您的工作流程自定義 opencode 的行為。
覆寫預設提示詞，以便為您的工作流程自訂 OpenCode 的行為。
```yaml title=".github/workflows/opencode.yml"
- uses: anomalyco/opencode/github@latest
@@ -265,57 +265,57 @@ jobs:
- Suggest improvements
```
這對於執行與您的專案相關的特定審閱標準、編碼標準或重點領域非常有用。
這對於在專案中實施特定的審查標準、編碼規範或關注重點非常有用。
---
## 範例
以下是如何在 GitHub 中使用 opencode 的一些範例。
以下是在 GitHub 中使用 OpenCode 的一些範例。
- **解釋一個問題**
- **解釋 Issue**
在 GitHub Issue 中添加此評論。
在 GitHub Issue 中新增以下評論：
```
/opencode explain this issue
```
opencode 將閱讀整個討論串，包括所有評論，並回覆並提供清晰的解釋。
OpenCode 會閱讀整個討論串（包括所有評論），並回覆一份清晰的解釋。
- **解決問題**
- **修復 Issue**
在 GitHub Issue 中，說：
在 GitHub Issue 中輸入：
```
/opencode fix this
```
opencode 將建立一個新分支，實作變更，並使用變更打開 PR。
OpenCode 會建立一個新分支，實作變更，並提交一個包含所有修改的 PR。
- **審閱 PR 並進行變更**
- **審查 PR 並進行修改**
在 GitHub PR 上留下以下評論。
在 GitHub PR 上留下以下評論：
```
Delete the attachment from S3 when the note is removed /oc
```
opencode 將實作請求的變更並將其推送到分支。
OpenCode 會實作所請求的變更並將其提交到同一個 PR 中。
- **查看特定程式碼行**
- **審查特定程式碼行**
直接在 PR 的「Files」標籤中的程式碼行上留下評論。 opencode 自動檢測檔案、行號和 diff 上下文以提供精確的回應。
在 PR 的「Files」分頁中直接對程式碼行留下評論。OpenCode 會自動偵測檔案、行號和 diff 上下文，從而提供精準的回應。
```
[Comment on specific lines in Files tab]
/oc add error handling here
```
opencode 將查看：
- 正在審閱的確切檔案
- 具體程式碼行
當您對特定程式碼行發表評論時，OpenCode 會接收到：
- 正在審查的具體檔案
- 特定的程式碼行
- 周圍的 diff 上下文
- 行號資訊
這允許更有針對性的請求，而無需手動指定檔案路徑或行號。
這樣您就可以提出更有針對性的請求，而無需手動指定檔案路徑或行號。

71
packages/web/src/content/docs/zh-tw/gitlab.mdx
View File

@@ -1,33 +1,33 @@
---
title: GitLab
description: 在 GitLab 問題和合併請求中使用 opencode。
description: 在 GitLab Issue 和合併請求中使用 OpenCode。
---
opencode 透過 GitLab CI/CD 管線或與 GitLab Duo 與您的 GitLab 工作流程整合。
OpenCode 透過 GitLab CI/CD 管線或 GitLab Duo 與您的 GitLab 工作流程整合。
在這兩種情況下，opencode 都將在您的 GitLab Runner 上執行。
在這兩種情況下，OpenCode 都將在您的 GitLab Runner 上執行。
---
## GitLab
## GitLab CI
opencode 在常規 GitLab 管線中工作。您可以將其構建為管線作為 [CI 組件](https://docs.gitlab.com/ee/ci/components/)
OpenCode 可以在常規的 GitLab 管線中執行。您可以將其作為 [CI 元件](https://docs.gitlab.com/ee/ci/components/) 整合到管線中。
在這裡，我們使用社群建立的 opencode CI/CD 組件 — [nagyv/gitlab-opencode](https://gitlab.com/nagyv/gitlab-opencode)。
這裡我們使用的是社群建立的 OpenCode CI/CD 元件 — [nagyv/gitlab-opencode](https://gitlab.com/nagyv/gitlab-opencode)。
---
### 功能
### 功能特性
- **每個作業使用自定義設定**：使用自定義設定目錄設定 opencode，例如 `./config/#custom-directory` 以啟用或禁用每個 opencode 呼叫的功能。
- **無狀態**：opencode 的狀態（訊息歷史記錄等）儲存在合併請求評論線程中，使其完全無狀態。
- **靈活**：CI 組件支援多種輸入來自定義其行為
- **按任務自訂設定**：使用自訂設定目錄來設定 OpenCode，例如 `./config/#custom-directory`，以便為每次 OpenCode 呼叫啟用或停用特定功能。
- **最小化設定**：CI 元件會在背景完成 OpenCode 的設定，您只需建立 OpenCode 設定和初始提示詞即可。
- **靈活可自訂**：CI 元件支援多種輸入參數來自訂其行為。
---
### 設定
1. 將 opencode 身分驗證 JSON 作為檔案類型 CI 環境變數儲存在 **Settings** > **CI/CD** > **Variables** 下。確保將它們標記為「Masked and hidden」。
1. 將您的 OpenCode 身分驗證 JSON 作為檔案類型的 CI 環境變數儲存在 **Settings** > **CI/CD** > **Variables** 下。請確保將其標記為「Masked and hidden」。
2. 將以下內容新增到您的 `.gitlab-ci.yml` 檔案中。
```yaml title=".gitlab-ci.yml"
@@ -40,40 +40,39 @@ opencode 在常規 GitLab 管線中工作。您可以將其構建為管線作為
message: "Your prompt here"
```
有關此組件的更多輸入和使用案例[查看文件](https://gitlab.com/explore/catalog/nagyv/gitlab-opencode)。
有關更多輸入參數和使用情境，請[查看該元件的文件](https://gitlab.com/explore/catalog/nagyv/gitlab-opencode)。
---
## GitLab Duo
opencode 與您的 GitLab 工作流程整合。
在評論中提及 `@opencode`，opencode 將在您的 GitLab CI 管線中執行任務。
OpenCode 與您的 GitLab 工作流程整合。
在評論中提及 `@opencode`，OpenCode 將在您的 GitLab CI 管線中執行任務。
---
### 功能
### 功能特性
- **分類問題**：要求 opencode 調查問題並向您解釋。
- **修復和實作**：要求 opencode 修復問題或實作功能。
它將建立一個新分支並提出包含變更的合併請求。
- **安全**：opencode 在您的 GitLab Runner 上執行。
- **Issue 分類**：讓 OpenCode 調查某個 Issue 並為您解釋。
- **修復與實作**：讓 OpenCode 修復 Issue 或實作某個功能。它會建立一個新分支，並提交包含變更的合併請求。
- **安全可靠**：OpenCode 在您的 GitLab Runner 上執行。
---
### 設定
opencode 在您的 GitLab CI/CD 管線中執行，您需要進行以下設定：
OpenCode 在您的 GitLab CI/CD 管線中執行，以下是設定所需的步驟：
:::tip
查看 [**GitLab 文件**](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) 以獲取最新說明。
請查看 [**GitLab 文件**](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) 取得最新說明。
:::
1. 設定您的 GitLab 環境
2. 設定 CI/CD
3. 取得 AI 模型供應商 API 金鑰
4. 建立服務帳號
3. 取得 AI 模型供應商的 API 金鑰
4. 建立服務帳戶
5. 設定 CI/CD 變數
6. 建立一個流程設定檔，這是一個範例：
6. 建立流程設定檔，以下是一個範例：
<details>
@@ -152,44 +151,44 @@ opencode 在您的 GitLab CI/CD 管線中執行，您需要進行以下設定：
</details>
詳細說明可以參考 [GitLab CLI 代理文件](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/)。
詳細說明請參考 [GitLab CLI agents 文件](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/)。
---
### 範例
以下是如何在 GitLab 中使用 opencode 的一些範例。
以下是在 GitLab 中使用 OpenCode 的一些範例。
:::tip
您可以設定使用與 `@opencode` 不同的觸發短語。
您可以設定使用不同於 `@opencode` 的觸發詞。
:::
- **解釋一個問題**
- **解釋 Issue**
在 GitLab 問題中添加此評論。
在 GitLab Issue 中新增以下評論。
```
@opencode explain this issue
```
opencode 將閱讀該問題並回覆並提供清晰的解釋。
OpenCode 會閱讀該 Issue 並回覆清晰的解釋。
- **解決問題**
- **修復 Issue**
在 GitLab 問題中，說：
在 GitLab Issue 中輸入：
```
@opencode fix this
```
opencode 將建立一個新分支，實作變更，並打開包含變更的合併請求。
OpenCode 會建立一個新分支，實作變更，並提交包含變更的合併請求。
- **審閱合併請求**
- **審查合併請求**
對 GitLab 合併請求留下以下評論。
在 GitLab 合併請求中留下以下評論。
```
@opencode review this merge request
```
opencode 將審閱合併請求並提供回饋。
OpenCode 會審查合併請求並提供回饋。

42
packages/web/src/content/docs/zh-tw/ide.mdx
View File

@@ -1,48 +1,48 @@
---
title: IDE
description: VS Code、Cursor 和其他 IDE 的 OpenCode 擴充功能
description: 適用於 VS Code、Cursor 及其他 IDE 的 OpenCode 擴充功能
---
OpenCode 與 VS Code、Cursor 或任何支援終端機的 IDE 整合。只需在終端機中執行 `opencode` 即可開始。
OpenCode 可與 VS Code、Cursor 或任何支援終端機的 IDE 整合。只需在終端機中執行 `opencode` 即可開始使用。
---
## 用法
- **快速啟動**：使用 `Cmd+Esc` (Mac) 或 `Ctrl+Esc` (Windows/Linux) 在分割終端機視圖中打開 OpenCode，或者聚焦現有終端機工作階段（如果已有終端機工作階段正在執行）。
- **新工作階段**：使用 `Cmd+Shift+Esc` (Mac) 或 `Ctrl+Shift+Esc` (Windows/Linux) 啟動新的 OpenCode 終端機工作階段，即使該工作階段已打開。您還可以單擊 UI 中的 OpenCode 按鈕。
- **上下文感知**：自動與 OpenCode 分享您當前的選擇或分頁。
- **檔案引用快速鍵**：使用 `Cmd+Option+K` (Mac) 或 `Alt+Ctrl+K` (Linux/Windows) 插入檔案引用。例如，`@File#L37-42`。
- **快速啟動**：使用 `Cmd+Esc`（Mac）或 `Ctrl+Esc`（Windows/Linux）在分割終端機視圖中開啟 OpenCode，如果已有終端機工作階段正在執行，則會自動聚焦到該工作階段。
- **新建工作階段**：使用 `Cmd+Shift+Esc`（Mac）或 `Ctrl+Shift+Esc`（Windows/Linux）啟動新的 OpenCode 終端機工作階段，即使已有工作階段在執行也會新建。您也可以點選介面中的 OpenCode 按鈕。
- **上下文感知**：自動將當前選取內容或分頁共享給 OpenCode。
- **檔案參照快捷鍵**：使用 `Cmd+Option+K`（Mac）或 `Alt+Ctrl+K`（Linux/Windows）插入檔案參照。例如 `@File#L37-42`。
---
## 安裝
要在 VS Code 和 Cursor、Windsurf、VSCodium 等流行 Fork 上安裝 OpenCode：
在 VS Code 及其常見分支（如 Cursor、Windsurf、VSCodium）上安裝 OpenCode：
1. 打開 VS Code
2. 打開整合終端機
3. 執行 `opencode` - 擴充功能會自動安裝
1. 開啟 VS Code
2. 開啟整合終端機
3. 執行 `opencode`——擴充功能將自動安裝
另一方面，如果您想在從 TUI 執行 `/editor` 或 `/export` 時使用自己的 IDE，則需要設定 `export EDITOR="code --wait"`。 [了解更多](/docs/tui/#editor-setup)。
如果您希望在 TUI 中執行 `/editor` 或 `/export` 時使用自己的 IDE，需要設定 `export EDITOR="code --wait"`。[了解更多](/docs/tui/#editor-setup)。
---
### 手動安裝
在擴充功能市集中搜尋 **OpenCode**，然後單擊 **安裝**。
在擴充功能商店中搜尋 **OpenCode**，然後點選 **Install**。
---
### 疑難排解
如果擴充功能無法自動安裝：
如果擴充功能未能自動安裝：
- 確保您在整合終端機中執行 `opencode`。
- 確認您的 IDE 的 CLI 已安裝：
- 對於 VS Code：`code` 指令
- 對於 Cursor：`cursor` 指令
- 對於 Windsurf：`windsurf` 指令
- 對於 VSCodium：`codium` 指令
- 如果沒有，請執行 `Cmd+Shift+P` (Mac) 或 `Ctrl+Shift+P` (Windows/Linux) 並搜尋「Shell Command: Install 'code' command in PATH」（或適用於您的 IDE 的等效指令）
- 確保 VS Code 有權安裝擴充功能
- 確保您是在整合終端機中執行的 `opencode`。
- 確認您的 IDE 對應的 CLI 指令已安裝：
- VS Code：`code` 指令
- Cursor：`cursor` 指令
- Windsurf：`windsurf` 指令
- VSCodium：`codium` 指令
- 如果未安裝，請按 `Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），搜尋「Shell Command: Install 'code' command in PATH」（或您的 IDE 對應的指令）
- 確保 VS Code 有權限安裝擴充功能

113
packages/web/src/content/docs/zh-tw/index.mdx
View File

@@ -7,25 +7,25 @@ import { Tabs, TabItem } from "@astrojs/starlight/components"
import config from "../../../../config.mjs"
export const console = config.console
[**OpenCode**](/) 是一個開源 AI 程式碼代理。它可用作基於終端機的介面、桌面應用程式或 IDE 擴充功能。
[**OpenCode**](/) 是一個開源的 AI 編碼代理。它提供終端機介面、桌面應用程式和 IDE 擴充功能等多種使用方式。
![具有 OpenCode 主題的 OpenCode TUI](../../../assets/lander/screenshot.png)
![使用 OpenCode 主題的 OpenCode TUI](../../../assets/lander/screenshot.png)
讓我們開始吧。
---
#### 先決條件
#### 前提條件
要在終端機中使用 OpenCode，您需要：
1. 現代終端機模擬器，例如：
1. 一款現代終端機模擬器，例如：
- [WezTerm](https://wezterm.org)，跨平台
- [Alacritty](https://alacritty.org)，跨平台
- [Ghostty](https://ghostty.org)，Linux 和 macOS
- [Kitty](https://sw.kovidgoyal.net/kitty/)，Linux 和 macOS
2. 您想要使用的 LLM 供應商的 API 金鑰。
2. 您想使用的 LLM 供應商的 API 金鑰。
---
@@ -37,7 +37,7 @@ export const console = config.console
curl -fsSL https://opencode.ai/install | bash
```
您也可以使用以下指令安裝：
您也可以使用以下方式安裝：
- **使用 Node.js**
@@ -79,9 +79,9 @@ curl -fsSL https://opencode.ai/install | bash
brew install anomalyco/tap/opencode
```
> 我們建議使用 OpenCode tap 來獲取最新版本。官方 `brew install opencode` formula 由 Homebrew 團隊維護，更新頻率較低。
> 我們推薦使用 OpenCode tap 以取得最新版本。官方的 `brew install opencode` formula 由 Homebrew 團隊維護，更新頻率較低。
- **在 Arch Linux 上使用 Paru**
- **在 Arch Linux 上安裝**
```bash
sudo pacman -S opencode # Arch Linux (Stable)
@@ -90,8 +90,8 @@ curl -fsSL https://opencode.ai/install | bash
#### Windows
:::tip[建議：使用 WSL]
為了在 Windows 上獲得最佳體驗，我們建議使用[適用於 Linux 的 Windows 子系統 (WSL)](/docs/windows-wsl)。它提供了更好的效能並與 OpenCode 的功能完全相容。
:::tip[推薦：使用 WSL]
為了在 Windows 上獲得最佳體驗，我們推薦使用 [Windows Subsystem for Linux (WSL)](/docs/windows-wsl)。它提供更好的效能，並完全相容 OpenCode 的所有功能。
:::
- **使用 Chocolatey**
@@ -124,18 +124,17 @@ curl -fsSL https://opencode.ai/install | bash
docker run -it --rm ghcr.io/anomalyco/opencode
```
目前正在支援使用 Bun 在 Windows 上安裝 OpenCode。
在 Windows 上透過 Bun 安裝 OpenCode 的支援目前正在開發中。
您還可以從 [Releases](https://github.com/anomalyco/opencode/releases) 獲取二進位檔案。
您也可以從 [Releases](https://github.com/anomalyco/opencode/releases) 頁面直接下載二進位檔案。
---
## 設定
借助 OpenCode，您可以透過設定 API 金鑰來使用任何 LLM 供應商。
透過 OpenCode，您可以設定 API 金鑰來使用任意 LLM 供應商。
如果您不熟悉使用 LLM 供應商，我們建議使用 [OpenCode Zen](/docs/zen)。
這是經過 OpenCode 團隊測試和驗證的精選模型列表。
如果您剛開始接觸 LLM 供應商，我們推薦使用 [OpenCode Zen](/docs/zen)。這是一組經過 OpenCode 團隊測試和驗證的精選模型。
1. 在 TUI 中執行 `/connect` 指令，選擇 opencode，然後前往 [opencode.ai/auth](https://opencode.ai/auth)。
@@ -143,7 +142,7 @@ curl -fsSL https://opencode.ai/install | bash
/connect
```
2. 登入，新增您的帳單詳細資訊，然後複製您的 API 金鑰。
2. 登入並新增帳單資訊，然後複製您的 API 金鑰。
3. 貼上您的 API 金鑰。
@@ -154,79 +153,79 @@ curl -fsSL https://opencode.ai/install | bash
└ enter
```
或者，您可以選擇其他供應商之一。[了解更多](/docs/providers#directory)。
您也可以選擇其他供應商。[了解更多](/docs/providers#directory)。
---
## 初始化
現在您已經設定了供應商，您可以導航到一個您想繼續工作的專案。
設定好供應商後，導覽到您想要處理的專案目錄。
```bash
cd /path/to/project
```
並執行 OpenCode。
然後執行 OpenCode。
```bash
opencode
```
接下來，透過執行以下指令來初始化專案的 OpenCode。
接下來，執行以下指令為專案初始化 OpenCode。
```bash frame="none"
/init
```
這將使 OpenCode 分析您的專案並在專案根目錄下建立 `AGENTS.md` 檔案。
OpenCode 會分析您的專案並在專案根目錄建立一個 `AGENTS.md` 檔案。
:::tip
您應該將專案的 `AGENTS.md` 檔案提交到 Git。
:::
這有助於 OpenCode 理解專案結構和使用的編碼模式。
這有助於 OpenCode 理解專案結構和編碼規範。
---
## 用法
## 使用
您現在已準備好使用 OpenCode 來處理您的專案。請隨意詢問任何事物！
現在您已經準備好使用 OpenCode 來處理專案了，儘管提問吧！
如果您不熟悉使用 AI 程式碼代理，以下是一些可能會有所幫助的範例。
如果您是第一次使用 AI 編碼代理，以下範例可能會對您有所幫助。
---
### 提出問題
### 提問
您可以用 OpenCode 向您解釋程式碼庫。
您可以讓 OpenCode 為您講解程式碼庫。
:::tip
使用`@`鍵模糊搜尋專案中的檔案。
使用 `@` 鍵可以模糊搜尋專案中的檔案。
:::
```txt frame="none" "@packages/functions/src/api/index.ts"
How is authentication handled in @packages/functions/src/api/index.ts
```
如果您沒有處理程式碼庫的一部分，這會很有幫助。
當您遇到不熟悉的程式碼時，這個功能非常有用。
---
### 新增功能
您可以用 OpenCode 向您的專案新增新功能。不過我們首先建議要求它制定一個計畫。
您可以讓 OpenCode 為專案新增新功能。不過我們建議先讓它制定一個計畫。
1. **制定計畫**
OpenCode 有一個*計畫模式*，該模式禁用其進行變更，而是建議*如何*實作該功能。
OpenCode 有一個*計畫模式*，該模式下它不會進行任何修改，而是建議*如何*實作該功能。
使用 **Tab** 鍵切換到它。您會在右下角看到一個指示符。
使用 **Tab** 鍵切換到計畫模式。您會在右下角看到模式指示器。
```bash frame="none" title="Switch to Plan mode"
<TAB>
```
現在讓我們描述一下我們想要它做什麼。
接下來描述您希望它做什麼。
```txt frame="none"
When a user deletes a note, we'd like to flag it as deleted in the database.
@@ -234,15 +233,15 @@ How is authentication handled in @packages/functions/src/api/index.ts
From this screen, the user can undelete a note or permanently delete it.
```
您需要為 OpenCode 提供足夠的詳細資訊以了解您想要的內容。這有幫助，就像與團隊中的初級開發人員交談一樣與它交談。
您需要提供足夠的細節，讓 OpenCode 理解您的需求。可以把它當作團隊中的一名初級開發者來溝通。
:::tip
為 OpenCode 提供大量上下文和範例，以幫助其理解您的想法。
為 OpenCode 提供充足的上下文和範例，幫助它理解您的需求。
:::
2. **迭代計畫**
一旦它為您提供了計畫，您可以提供回饋或新增更多詳細資訊。
當它給出計畫後，您可以提供回饋或補充更多細節。
```txt frame="none"
We'd like to design this new screen using a design I've used before.
@@ -250,20 +249,20 @@ How is authentication handled in @packages/functions/src/api/index.ts
```
:::tip
將影像拖放到終端機中以將其新增到提示中。
將圖片拖放到終端機中即可將其新增到提示詞中。
:::
OpenCode 可以掃描您提供的任何影像並將其新增到提示中。您可以透過將影像拖放到終端機中來完成此操作。
OpenCode 可以掃描您提供的圖片並將其新增到提示詞中。只需將圖片拖放到終端機視窗即可。
3. **建置功能**
一旦您對計畫感到滿意，請切換回*建置模式*，再次按 **Tab** 鍵。
當您對計畫滿意後，再次按 **Tab** 鍵切換回*建置模式*。
```bash frame="none"
<TAB>
```
並要求它做出改變。
然後讓它開始實施。
```bash frame="none"
Sounds good! Go ahead and make the changes.
@@ -271,9 +270,9 @@ How is authentication handled in @packages/functions/src/api/index.ts
---
### 做出改變
### 直接修改
對於更直接的變更，您可以要求 OpenCode 直接建置它，無需先審閱計畫。
對於比較簡單的修改，您可以直接讓 OpenCode 實施，無需先審查計畫。
```txt frame="none" "@packages/functions/src/settings.ts" "@packages/functions/src/notes.ts"
We need to add authentication to the /settings route. Take a look at how this is
@@ -281,37 +280,37 @@ handled in the /notes route in @packages/functions/src/notes.ts and implement
the same logic in @packages/functions/src/settings.ts
```
您需要確保提供大量詳細資訊，以便 OpenCode 做出正確的變更。
請確保提供足夠的細節，以便 OpenCode 做出正確的修改。
---
### 撤銷變更
### 復原修改
假設您要求 OpenCode 進行一些變更。
假設您讓 OpenCode 做了一些修改。
```txt frame="none" "@packages/functions/src/api/index.ts"
Can you refactor the function in @packages/functions/src/api/index.ts?
```
但你意識到這不是你想要的。您**可以撤銷**變更，使用 `/undo` 指令。
但您發現結果不是您想要的。您**可以使用** `/undo` 指令來復原修改。
```bash frame="none"
/undo
```
OpenCode 現在將復原您所做的變更並再次顯示您的原始訊息。
OpenCode 會還原所做的修改，並重新顯示您之前的訊息。
```txt frame="none" "@packages/functions/src/api/index.ts"
Can you refactor the function in @packages/functions/src/api/index.ts?
```
從這裡您可以調整提示並要求 OpenCode 重試。
您可以調整提示詞，讓 OpenCode 重新嘗試。
:::tip
您可以多次執行 `/undo` 以撤銷多項變更。
您可以多次執行 `/undo` 來復原多次修改。
:::
或者您**可以使用 `/redo` 指令重做**變更。
您也**可以使用** `/redo` 指令來重做修改。
```bash frame="none"
/redo
@@ -321,24 +320,24 @@ Can you refactor the function in @packages/functions/src/api/index.ts?
## 分享
您與 OpenCode 的對話可以[與您的團隊分享](/docs/share)。
您與 OpenCode 的對話可以[與團隊分享](/docs/share)。
```bash frame="none"
/share
```
這將建立目前對話的連結並將其複製到剪貼簿。
這會生成當前對話的連結並複製到剪貼簿。
:::note
預設情況下不分享對話。
對話預設不會被分享。
:::
這是帶有 OpenCode 的[範例對話](https://opencode.ai/s/4XP1fce5)。
這是一個與 OpenCode 的[範例對話](https://opencode.ai/s/4XP1fce5)。
---
## 自訂
## 個人化
就是這樣！您現在已經是使用 OpenCode 的專家了。
以上就是全部內容！您現在已經是 OpenCode 的使用高手了。
要使其成為您自己的，我們建議 [選擇一個主題](/docs/themes)、[自訂按鍵綁定](/docs/keybinds)、[設定程式碼格式化程式](/docs/formatters)、[建立自定義指令](/docs/commands) 或使用 [OpenCode 設定](/docs/config)。
要讓它更符合您的習慣，我們推薦[選擇一個主題](/docs/themes)、[自訂快捷鍵](/docs/keybinds)、[設定程式碼格式化器](/docs/formatters)、[建立自訂指令](/docs/commands)，或者探索 [OpenCode 設定](/docs/config)。

62
packages/web/src/content/docs/zh-tw/keybinds.mdx
View File

@@ -1,9 +1,9 @@
---
title: 按鍵綁定
description: 自定義您的按鍵綁定。
title: 快捷鍵
description: 自訂您的快捷鍵。
---
opencode 有一個按鍵綁定列表，您可以透過 opencode 設定進行自定義。
OpenCode 提供了一系列快捷鍵，您可以透過 OpenCode 設定進行自訂。
```json title="opencode.json"
{
@@ -105,19 +105,19 @@ opencode 有一個按鍵綁定列表，您可以透過 opencode 設定進行自
---
## Leader 鍵
## 前導鍵
opencode 對大多數按鍵綁定使用 `leader` 鍵。這可以避免終端機中的衝突。
OpenCode 的大多數快捷鍵使用 `leader`（前導鍵）。這可以避免與終端機中的其他快捷鍵衝突。
預設情況下，`ctrl+x` 是 Leader 鍵，大多數操作要求您先按 Leader 鍵，然後再按快速鍵。例如，要開始新工作階段，請先按 `ctrl+x`，然後按 `n`。
預設情況下，`ctrl+x` 是前導鍵，大多數操作需要您先按下前導鍵，然後再按對應的快捷鍵。例如，要新建一個工作階段，請先按 `ctrl+x`，然後按 `n`。
您不需要為鍵綁定使用 Leader 鍵，但我們建議您這樣做。
您不一定需要使用前導鍵來設定快捷鍵，但我們建議您這樣做。
---
## 禁用按鍵綁定
## 停用快捷鍵
您可以透過將鍵添加到您的設定中並使用值「none」來禁用鍵綁定。
您可以透過在設定中將對應的鍵值設定為 "none" 來停用某個快捷鍵。
```json title="opencode.json"
{
@@ -130,41 +130,41 @@ opencode 對大多數按鍵綁定使用 `leader` 鍵。這可以避免終端機
---
## 桌面提示快速鍵
## 桌面版提示詞輸入快捷鍵
opencode 桌面應用程式提示輸入支援常見的 Readline/Emacs 風格的文字編輯快速鍵。這些是內建的，目前無法透過 `opencode.json` 進行設定。
OpenCode 桌面應用程式的提示詞輸入框支援常見的 Readline/Emacs 風格文字編輯快捷鍵。這些快捷鍵為內建功能，目前無法透過 `opencode.json` 進行設定。
| 快速鍵 | 動作 |
| -------- | ------------------------- |
| `ctrl+a` | 移至當前行開頭 |
| `ctrl+e` | 移至當前行尾 |
| `ctrl+b` | 將游標向後移動一個字元 |
| `ctrl+f` | 將游標向前移動一個字元 |
| `alt+b` | 將游標向後移動一個字 |
| `alt+f` | 將游標向前移動一個字 |
| `ctrl+d` | 刪除游標下的字元 |
| `ctrl+k` | 刪除至行尾 |
| `ctrl+u` | 刪除至行首 |
| `ctrl+w` | 刪除前一個單字 |
| `alt+d` | 刪除下一個單字 |
| `ctrl+t` | 調換字元 |
| `ctrl+g` | 取消彈出視窗/中止執行回應 |
| 快捷鍵 | 操作 |
| -------- | --------------------------------- |
| `ctrl+a` | 移動到當前行的開頭 |
| `ctrl+e` | 移動到當前行的末尾 |
| `ctrl+b` | 游標向後移動一個字元 |
| `ctrl+f` | 游標向前移動一個字元 |
| `alt+b` | 游標向後移動一個單詞 |
| `alt+f` | 游標向前移動一個單詞 |
| `ctrl+d` | 刪除游標所在位置的字元 |
| `ctrl+k` | 刪除從游標到行尾的內容 |
| `ctrl+u` | 刪除從游標到行首的內容 |
| `ctrl+w` | 刪除前一個單詞 |
| `alt+d` | 刪除後一個單詞 |
| `ctrl+t` | 交換游標前後的字元 |
| `ctrl+g` | 取消彈出視窗 / 中止正在執行的回應 |
---
## Shift+Enter
預設情況下，某些終端機不發送帶有 Enter 的輔助鍵。您可能需要將終端機設定為發送 `Shift+Enter` 作為跳脫序列。
某些終端機預設不會發送帶修飾鍵的 Enter 鍵。您可能需要設定終端機將 `Shift+Enter` 作為跳脫序列發送。
### Windows Terminal
打開您的 `settings.json`：
開啟您的 `settings.json` 檔案，路徑為：
```
%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
```
將其添加到根級 `actions` 陣列：
將以下內容新增到根級 `actions` 陣列中：
```json
"actions": [
@@ -178,7 +178,7 @@ opencode 桌面應用程式提示輸入支援常見的 Readline/Emacs 風格的
]
```
將其添加到根級 `keybindings` 陣列：
將以下內容新增到根級 `keybindings` 陣列中：
```json
"keybindings": [
@@ -189,4 +189,4 @@ opencode 桌面應用程式提示輸入支援常見的 Readline/Emacs 風格的
]
```
儲存檔案並重新啟動 Windows Terminal 或打開新分頁。
儲存檔案並重新啟動 Windows Terminal，或開啟一個新分頁。

130
packages/web/src/content/docs/zh-tw/lsp.mdx
View File

@@ -1,71 +1,71 @@
---
title: LSP 伺服器
description: opencode 與您的 LSP 伺服器整合。
description: OpenCode 與您的 LSP 伺服器整合。
---
opencode 與您的語言伺服器協定 (LSP) 整合，以幫助 LLM 與您的程式碼庫互動。它使用診斷向 LLM 提供回饋。
OpenCode 與您的語言伺服器協定（LSP）整合，協助 LLM 與您的程式碼庫進行互動。它利用診斷資訊向 LLM 提供回饋。
---
## 內建
## 內建支援
opencode 附帶了多種適用於流行語言的內建 LSP 伺服器：
OpenCode 內建了多種適用於主流語言的 LSP 伺服器：
| LSP 伺服器 | 副檔名 | 要求 |
| ------------------ | ------------------------------------------------------------------- | ------------------------------------------------ |
| astro | .astro | Astro 專案自動安裝 |
| bash | .sh、.bash、.zsh、.ksh | 自動安裝 bash-language-server |
| clangd | .c、.cpp、.cc、.cxx、.c++、.h、.hpp、.hh、.hxx、.h++ | 自動安裝 C/C++ 專案 |
| csharp | .cs | `.NET SDK` 已安裝 |
| clojure-lsp | .clj、.cljs、.cljc、.edn | `clojure-lsp` 指令可用 |
| dart | .dart | `dart` 指令可用 |
| deno | .ts、.tsx、.js、.jsx、.mjs | `deno` 指令可用（自動檢測 deno.json/deno.jsonc） |
| elixir-ls | .ex、.exs | `elixir` 指令可用 |
| eslint | .ts、.tsx、.js、.jsx、.mjs、.cjs、.mts、.cts、.vue | `eslint` 專案中的相依套件 |
| fsharp | .fs、.fsi、.fsx、.fsscript | `.NET SDK` 已安裝 |
| gleam | .gleam | `gleam` 指令可用 |
| gopls | .go | `go` 指令可用 |
| hls | .hs、.lhs | `haskell-language-server-wrapper` 指令可用 |
| jdtls | .java | `Java SDK (version 21+)` 已安裝 |
| kotlin-ls | .kt、.kts | Kotlin 專案的自動安裝 |
| lua-ls | .lua | 自動安裝 Lua 專案 |
| nil | .nix | `nixd` 指令可用 |
| ocaml-lsp | .ml、.mli | `ocamllsp` 指令可用 |
| oxlint | .ts、.tsx、.js、.jsx、.mjs、.cjs、.mts、.cts、.vue、.astro、.svelte | `oxlint` 專案中的相依套件 |
| php intelephense | .php | PHP 專案的自動安裝 |
| prisma | .prisma | `prisma` 指令可用 |
| pyright | .py, .pyi | `pyright` 相依套件已安裝 |
| ruby-lsp (rubocop) | .rb、.rake、.gemspec、.ru | `ruby` 和 `gem` 指令可用 |
| rust-analyzer | .rs | `rust-analyzer` 指令可用 |
| sourcekit-lsp | .swift、.objc、.objcpp | `swift` 已安裝（`xcode` 在 macOS 上） |
| svelte | .svelte | Svelte 專案的自動安裝 |
| terraform-ls | .tf、.tfvars | 從 GitHub Releases 自動安裝 |
| tinymist | .typ、.typc | 從 GitHub Releases 自動安裝 |
| typescript | .ts、.tsx、.js、.jsx、.mjs、.cjs、.mts、.cts | `typescript` 專案中的相依套件 |
| vue | .vue | Vue 專案自動安裝 |
| yaml-ls | .yaml、.yml | 自動安裝 Red Hat yaml-language-server |
| zls | .zig、.zon | `zig` 指令可用 |
| ------------------ | ------------------------------------------------------------------- | ----------------------------------------------------- |
| astro | .astro | 為 Astro 專案自動安裝 |
| bash | .sh, .bash, .zsh, .ksh | 自動安裝 bash-language-server |
| clangd | .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++ | 為 C/C++ 專案自動安裝 |
| csharp | .cs | 需要已安裝 `.NET SDK` |
| clojure-lsp | .clj, .cljs, .cljc, .edn | 需要 `clojure-lsp` 指令可用 |
| dart | .dart | 需要 `dart` 指令可用 |
| deno | .ts, .tsx, .js, .jsx, .mjs | 需要 `deno` 指令可用（自動偵測 deno.json/deno.jsonc） |
| elixir-ls | .ex, .exs | 需要 `elixir` 指令可用 |
| eslint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue | 專案中需要 `eslint` 相依套件 |
| fsharp | .fs, .fsi, .fsx, .fsscript | 需要已安裝 `.NET SDK` |
| gleam | .gleam | 需要 `gleam` 指令可用 |
| gopls | .go | 需要 `go` 指令可用 |
| hls | .hs, .lhs | 需要 `haskell-language-server-wrapper` 指令可用 |
| jdtls | .java | 需要已安裝 `Java SDK (version 21+)` |
| kotlin-ls | .kt, .kts | 為 Kotlin 專案自動安裝 |
| lua-ls | .lua | 為 Lua 專案自動安裝 |
| nixd | .nix | 需要 `nixd` 指令可用 |
| ocaml-lsp | .ml, .mli | 需要 `ocamllsp` 指令可用 |
| oxlint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | 專案中需要 `oxlint` 相依套件 |
| php intelephense | .php | 為 PHP 專案自動安裝 |
| prisma | .prisma | 需要 `prisma` 指令可用 |
| pyright | .py, .pyi | 需要已安裝 `pyright` 相依套件 |
| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru | 需要 `ruby` 和 `gem` 指令可用 |
| rust | .rs | 需要 `rust-analyzer` 指令可用 |
| sourcekit-lsp | .swift, .objc, .objcpp | 需要已安裝 `swift`（macOS 上為 `xcode`） |
| svelte | .svelte | 為 Svelte 專案自動安裝 |
| terraform | .tf, .tfvars | 從 GitHub releases 自動安裝 |
| tinymist | .typ, .typc | 從 GitHub releases 自動安裝 |
| typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | 專案中需要 `typescript` 相依套件 |
| vue | .vue | 為 Vue 專案自動安裝 |
| yaml-ls | .yaml, .yml | 自動安裝 Red Hat yaml-language-server |
| zls | .zig, .zon | 需要 `zig` 指令可用 |
當檢測到上述檔案副檔名之一且滿足要求時，LSP 伺服器將自動啟用。
當偵測到上述檔案副檔名且滿足相應要求時，LSP 伺服器會自動啟用。
:::note
您可以透過將 `OPENCODE_DISABLE_LSP_DOWNLOAD` 環境變數設定為 `true` 來禁用自動 LSP 伺服器下載。
您可以將 `OPENCODE_DISABLE_LSP_DOWNLOAD` 環境變數設定為 `true` 來停用 LSP 伺服器的自動下載。
:::
---
## 它是如何運作的
## 工作原理
當 opencode 打開一個檔案時，它：
當 OpenCode 開啟一個檔案時，它會：
1. 根據所有啟用的 LSP 伺服器檢查檔案副檔名。
2. 如果尚未執行，則啟動相應的 LSP 伺服器。
1. 將檔案副檔名與所有已啟用的 LSP 伺服器進行比對。
2. 如果對應的 LSP 伺服器尚未執行，則自動啟動它。
---
## 設定
您可以透過 opencode 設定中的 `lsp` 部分自定義 LSP 伺服器。
您可以透過 OpenCode 設定檔中的 `lsp` 部分來自訂 LSP 伺服器。
```json title="opencode.json"
{
@@ -74,23 +74,23 @@ opencode 附帶了多種適用於流行語言的內建 LSP 伺服器：
}
```
每個 LSP 伺服器支援以下功能：
每個 LSP 伺服器支援以下設定項：
| 屬性 | 類型 | 描述 |
| ---------------- | ------ | ----------------------------------- |
| `disabled` | 布林值 | 將其設定為 `true` 以禁用 LSP 伺服器 |
| `command` | 字串[] | 啟動 LSP 伺服器的指令 |
| `extensions` | 字串[] | 此 LSP 伺服器應處理的檔案副檔名 |
| `env` | 物件 | 啟動伺服器時設定的環境變數 |
| `initialization` | 物件 | 發送到 LSP 伺服器的初始化選項 |
| ---------------- | -------- | --------------------------------- |
| `disabled` | boolean | 設定為 `true` 可停用該 LSP 伺服器 |
| `command` | string[] | 啟動 LSP 伺服器的指令 |
| `extensions` | string[] | 該 LSP 伺服器需要處理的檔案副檔名 |
| `env` | object | 啟動伺服器時設定的環境變數 |
| `initialization` | object | 傳送給 LSP 伺服器的初始化選項 |
讓我們看一些例子。
下面來看一些範例。
---
### 環境變數
啟動 LSP 伺服器時使用 `env` 屬性設定環境變數：
使用 `env` 屬性在啟動 LSP 伺服器時設定環境變數：
```json title="opencode.json" {5-7}
{
@@ -109,7 +109,7 @@ opencode 附帶了多種適用於流行語言的內建 LSP 伺服器：
### 初始化選項
使用 `initialization` 屬性將初始化選項傳遞給 LSP 伺服器。這些是在 LSP `initialize` 請求期間發送的伺服器特定設定：
使用 `initialization` 屬性向 LSP 伺服器傳遞初始化選項。這些是在 LSP `initialize` 請求期間傳送的伺服器特定設定：
```json title="opencode.json" {5-9}
{
@@ -127,14 +127,14 @@ opencode 附帶了多種適用於流行語言的內建 LSP 伺服器：
```
:::note
初始化選項因 LSP 伺服器而異。檢查 LSP 伺服器的文件以獲取可用選項。
初始化選項因 LSP 伺服器而異。請查閱您所使用的 LSP 伺服器的文件以了解可用選項。
:::
---
### 禁用 LSP 伺服器
### 停用 LSP 伺服器
要全域禁用**所有** LSP 伺服器，請將 `lsp` 設定為 `false`：
要全域停用**所有** LSP 伺服器，將 `lsp` 設定為 `false`：
```json title="opencode.json" {3}
{
@@ -143,7 +143,7 @@ opencode 附帶了多種適用於流行語言的內建 LSP 伺服器：
}
```
要禁用**特定** LSP 伺服器，請將 `disabled` 設定為 `true`：
要停用**特定的** LSP 伺服器，將 `disabled` 設定為 `true`：
```json title="opencode.json" {5}
{
@@ -158,9 +158,9 @@ opencode 附帶了多種適用於流行語言的內建 LSP 伺服器：
---
### 自定義 LSP 伺服器
### 自訂 LSP 伺服器
您可以透過指定指令和檔案副檔名來添加自定義 LSP 伺服器：
您可以透過指定指令和檔案副檔名來新增自訂 LSP 伺服器：
```json title="opencode.json" {4-7}
{
@@ -176,13 +176,13 @@ opencode 附帶了多種適用於流行語言的內建 LSP 伺服器：
---
## 附加資訊
## 補充資訊
### PHP Intelephense
PHP Intelephense 透過授權金鑰提供高級功能。您可以透過將（僅）金鑰放入位於以下位置的文字檔案中來提供授權金鑰：
PHP Intelephense 透過授權金鑰提供進階功能。您可以將授權金鑰單獨放在以下路徑的文字檔案中：
- 在 macOS/Linux 上：`$HOME/intelephense/license.txt`
- 在 Windows 上：`%USERPROFILE%/intelephense/license.txt`
- macOS/Linux：`$HOME/intelephense/license.txt`
- Windows：`%USERPROFILE%/intelephense/license.txt`
該檔案應僅包含授權金鑰，不包含其他內容。
該檔案應僅包含授權金鑰，不要新增其他任何內容。

158
packages/web/src/content/docs/zh-tw/mcp-servers.mdx
View File

@@ -1,29 +1,29 @@
---
title: MCP 伺服器
description: 添加本地和遠端 MCP 工具。
description: 新增本地和遠端 MCP 工具。
---
您可以使用「模型上下文協定」或 MCP 將外部工具添加到 opencode。 opencode 支援本地和遠端伺服器。
您可以透過 _Model Context Protocol_（MCP）為 OpenCode 新增外部工具。OpenCode 同時支援本地和遠端伺服器。
添加後，MCP 工具將自動與內建工具一起供 LLM 使用。
新增後，MCP 工具會自動與內建工具一起提供給 LLM 使用。
---
#### 注意事項
當您使用 MCP 伺服器時，它會添加到上下文中。如果您有很多工具，這會很快增加。因此，我們建議您謹慎選擇使用哪些 MCP 伺服器。
使用 MCP 伺服器時，它會佔用上下文空間。如果您啟用了大量工具，上下文消耗會迅速增加。因此，我們建議謹慎選擇要使用的 MCP 伺服器。
:::tip
MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些伺服器。
MCP 伺服器會佔用您的上下文空間，所以請謹慎選擇啟用哪些伺服器。
:::
某些 MCP 伺服器（例如 GitHub MCP 伺服器）往往會添加大量 tokens，並且很容易超出上下文限制。
某些 MCP 伺服器（例如 GitHub MCP 伺服器）往往會消耗大量 Token，很容易超出上下文限制。
---
## 啟用
您可以在 `mcp` 下的 [opencode 設定](https://opencode.ai/docs/config/) 中定義 MCP 伺服器。為每個 MCP 添加唯一的名稱。當提示 LLM 時，您可以透過名稱引用該 MCP。
您可以在 [OpenCode 設定](https://opencode.ai/docs/config/)的 `mcp` 欄位下定義 MCP 伺服器。為每個 MCP 指定一個唯一的名稱，在提示詞中可以透過該名稱來參照對應的 MCP。
```jsonc title="opencode.jsonc" {6}
{
@@ -40,15 +40,15 @@ MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些
}
```
您還可以透過將 `enabled` 設定為 `false` 來禁用伺服器。如果您想暫時禁用伺服器而不將其從設定中刪除，這非常有用。
您也可以將 `enabled` 設定為 `false` 來停用某個伺服器。當您想臨時停用某個伺服器而不將其從設定中移除時，這個選項非常有用。
---
### 覆寫遠端預設值
組織可以透過其 `.well-known/opencode` 端點提供預設 MCP 伺服器。這些伺服器可能預設被禁用，允許使用者選擇他們需要的伺服器。
組織可以透過其 `.well-known/opencode` 端點提供預設的 MCP 伺服器。這些伺服器可能預設處於停用狀態，允許使用者按需啟用。
要從組織的遠端設定啟用特定伺服器，請使用 `enabled: true` 將其添加到本地設定：
要啟用組織遠端設定中的某個伺服器，請在本地設定中新增該伺服器並設定 `enabled: true`：
```json title="opencode.json"
{
@@ -63,13 +63,13 @@ MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些
}
```
您的本地設定值會覆寫遠端預設值。有關更多詳細資訊，請參閱 [設定優先級](/docs/config#precedence-order)。
本地設定值會覆寫遠端預設值。詳情請參閱[設定優先順序](/docs/config#precedence-order)。
---
## 本地
使用 `type` 將本地 MCP 伺服器添加到 MCP 物件中的 `"local"`。
透過在 MCP 物件中將 `type` 設定為 `"local"` 來新增本地 MCP 伺服器。
```jsonc title="opencode.jsonc" {15}
{
@@ -88,9 +88,9 @@ MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些
}
```
該指令是本地 MCP 伺服器的啟動方式。您還可以傳入環境變數列表。
`command` 用於指定本地 MCP 伺服器的啟動指令。您還可以傳入一組環境變數。
例如，以下是添加測試 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 伺服器的方法。
例如，以下是新增測試用的 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 伺服器的方法。
```jsonc title="opencode.jsonc"
{
@@ -104,7 +104,7 @@ MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些
}
```
要使用它，我可以將 `use the mcp_everything tool` 添加到我的提示中。
要使用它，可以在提示詞中新增 `use the mcp_everything tool`。
```txt "mcp_everything"
use the mcp_everything tool to add the number 3 and 4
@@ -117,18 +117,18 @@ use the mcp_everything tool to add the number 3 and 4
以下是設定本地 MCP 伺服器的所有選項。
| 選項 | 類型 | 必填 | 描述 |
| ------------- | ------ | ---- | ------------------------------------------------------------------ |
| `type` | 字串 | 是 | MCP 伺服器連接類型，必須是 `"local"`。 |
| `command` | 陣列 | 是 | 執行 MCP 伺服器的指令和參數。 |
| ------------- | ------ | ---- | ----------------------------------------------------------------- |
| `type` | 字串 | 是 | MCP 伺服器連線類型，必須為 `"local"`。 |
| `command` | 陣列 | 是 | 執行 MCP 伺服器的指令及參數。 |
| `environment` | 物件 | | 執行伺服器時設定的環境變數。 |
| `enabled` | 布林值 | | 在啟動時啟用或禁用 MCP 伺服器。 |
| `timeout` | 數量 | | 從 MCP 伺服器獲取工具的超時（以毫秒為單位）。預設為 5000（5 秒）。 |
| `enabled` | 布林值 | | 啟動時啟用或停用該 MCP 伺服器。 |
| `timeout` | 數字 | | 從 MCP 伺服器取得工具的逾時時間（毫秒）。預設為 5000（即 5 秒）。 |
---
## 遠端
透過將 `type` 設定為 `"remote"` 添加遠端 MCP 伺服器。
透過將 `type` 設定為 `"remote"` 來新增遠端 MCP 伺服器。
```json title="opencode.json"
{
@@ -146,36 +146,36 @@ use the mcp_everything tool to add the number 3 and 4
}
```
`url` 是遠端 MCP 伺服器的 URL，使用 `headers` 選項您可以傳入標頭列表。
`url` 是遠端 MCP 伺服器的位址，透過 `headers` 選項可以傳入一組請求標頭。
---
#### 選項
| 選項 | 類型 | 必填 | 描述 |
| --------- | ------ | ---- | ------------------------------------------------------------------ |
| `type` | 字串 | 是 | MCP 伺服器連接類型，必須是 `"remote"`。 |
| --------- | ------ | ---- | ----------------------------------------------------------------- |
| `type` | 字串 | 是 | MCP 伺服器連線類型，必須為 `"remote"`。 |
| `url` | 字串 | 是 | 遠端 MCP 伺服器的 URL。 |
| `enabled` | 布林值 | | 在啟動時啟用或禁用 MCP 伺服器。 |
| `headers` | 物件 | | 隨請求一起發送的標頭。 |
| `oauth` | 物件 | | OAuth 身分驗證設定。請參閱下面的 [OAuth](#oauth) 部分。 |
| `timeout` | 數量 | | 從 MCP 伺服器獲取工具的超時（以毫秒為單位）。預設為 5000（5 秒）。 |
| `enabled` | 布林值 | | 啟動時啟用或停用該 MCP 伺服器。 |
| `headers` | 物件 | | 隨請求傳送的請求標頭。 |
| `oauth` | 物件 | | OAuth 身分驗證設定。詳見下方 [OAuth](#oauth) 部分。 |
| `timeout` | 數字 | | 從 MCP 伺服器取得工具的逾時時間（毫秒）。預設為 5000（即 5 秒）。 |
---
## OAuth
opencode 自動處理遠端 MCP 伺服器的 OAuth 身分驗證。當伺服器需要身分驗證時，opencode 將：
OpenCode 會自動處理遠端 MCP 伺服器的 OAuth 身分驗證。當伺服器需要身分驗證時，OpenCode 將：
1. 檢測 401 回應並啟動 OAuth 流程
2. 如果伺服器支援，請使用**動態客戶端註冊 (RFC 7591)**
3. 安全地儲存權杖以供將來的請求
1. 偵測 401 回應並啟動 OAuth 流程
2. 在伺服器支援的情況下使用**動態用戶端註冊（RFC 7591）**
3. 安全地儲存 Token 以供後續請求使用
---
### 自動
### 自動認證
對於大多數支援 OAuth 的 MCP 伺服器，不需要特殊設定。只需設定遠端伺服器：
對於大多數支援 OAuth 的 MCP 伺服器，無需特殊設定。只需設定遠端伺服器即可：
```json title="opencode.json"
{
@@ -189,13 +189,13 @@ opencode 自動處理遠端 MCP 伺服器的 OAuth 身分驗證。當伺服器
}
```
如果伺服器需要身分驗證，opencode 將在您第一次嘗試使用它時提示您進行身分驗證。如果沒有，您可以使用 `opencode mcp auth <server-name>` [手動觸發流程](#authenticating)。
如果伺服器需要身分驗證，OpenCode 會在您首次使用時提示您進行認證。您也可以使用 `opencode mcp auth <server-name>` [手動觸發認證流程](#authenticating)。
---
### 預先註冊
如果您有來自 MCP 伺服器供應商的客戶端憑證，則可以設定它們：
如果您已經從 MCP 伺服器提供商處取得了用戶端憑證，可以直接設定：
```json title="opencode.json" {7-11}
{
@@ -216,35 +216,35 @@ opencode 自動處理遠端 MCP 伺服器的 OAuth 身分驗證。當伺服器
---
### 進行身分驗證
### 身分驗證
您可以手動觸發身分驗證或管理憑證。
使用特定 MCP 伺服器進行身分驗證：
對特定 MCP 伺服器進行身分驗證：
```bash
opencode mcp auth my-oauth-server
```
列出所有 MCP 伺服器及其身分驗證狀態：
列出所有 MCP 伺服器及其認證狀態：
```bash
opencode mcp list
```
刪除儲存的憑證：
刪除已儲存的憑證：
```bash
opencode mcp logout my-oauth-server
```
`mcp auth` 指令將打開您的瀏覽器進行授權。授權後，opencode 會將權杖安全地儲存在 `~/.local/share/opencode/mcp-auth.json` 中。
`mcp auth` 指令會開啟瀏覽器進行授權。授權完成後，OpenCode 會將 Token 安全地儲存在 `~/.local/share/opencode/mcp-auth.json` 中。
---
#### 禁用 OAuth
#### 停用 OAuth
如果要禁用伺服器的自動 OAuth（例如，對於使用 API 金鑰的伺服器），請將 `oauth` 設定為 `false`：
如果您想為某個伺服器停用自動 OAuth（例如，該伺服器使用 API 金鑰而非 OAuth），可以將 `oauth` 設定為 `false`：
```json title="opencode.json" {7}
{
@@ -267,37 +267,37 @@ opencode mcp logout my-oauth-server
#### OAuth 選項
| 選項 | 類型 | 描述 |
| -------------- | --------------- | --------------------------------------------------- |
| `oauth` | Object \| false | OAuth 設定物件，或 `false` 以禁用 OAuth 自動檢測。 |
| `clientId` | String | OAuth 客戶端 ID。如果未提供，將嘗試動態客戶端註冊。 |
| `clientSecret` | String | OAuth 客戶端密鑰（如果授權伺服器需要）。 |
| `scope` | String | 授權期間請求的 OAuth 範圍。 |
| -------------- | --------------- | ------------------------------------------------------ |
| `oauth` | 物件 \| `false` | OAuth 設定物件，或設為 `false` 以停用 OAuth 自動偵測。 |
| `clientId` | 字串 | OAuth 用戶端 ID。如果未提供，將嘗試動態用戶端註冊。 |
| `clientSecret` | 字串 | OAuth 用戶端密鑰（如果授權伺服器要求提供）。 |
| `scope` | 字串 | 授權時請求的 OAuth 作用域。 |
#### 偵錯
如果遠端 MCP 伺服器無法進行身分驗證，您可以透過以下方式診斷問題：
如果遠端 MCP 伺服器身分驗證失敗，您可以透過以下方式診斷問題：
```bash
# View auth status for all OAuth-capable servers
# 查看所有支援 OAuth 的伺服器的認證狀態
opencode mcp auth list
# Debug connection and OAuth flow for a specific server
# 偵錯特定伺服器的連線和 OAuth 流程
opencode mcp debug my-oauth-server
```
`mcp debug` 指令顯示當前身分驗證狀態、測試 HTTP 連接並嘗試 OAuth 發現流程。
`mcp debug` 指令會顯示當前認證狀態、測試 HTTP 連線，並嘗試執行 OAuth 發現流程。
---
## 管理
您的 MCP 可作為 opencode 中的工具以及內建工具使用。因此，您可以像任何其他工具一樣透過 opencode 設定來管理它們。
您的 MCP 在 OpenCode 中作為工具使用，與內建工具並列。因此，您可以像管理其他工具一樣，透過 OpenCode 設定來管理它們。
---
### 全域
這意味著您可以全域啟用或禁用它們。
您可以全域啟用或停用 MCP 工具。
```json title="opencode.json" {14}
{
@@ -318,7 +318,7 @@ opencode mcp debug my-oauth-server
}
```
我們也可以使用 glob 模式來禁用所有匹配的 MCP。
也可以使用 glob 模式來停用所有符合條件的 MCP。
```json title="opencode.json" {14}
{
@@ -339,16 +339,16 @@ opencode mcp debug my-oauth-server
}
```
這裡我們使用 glob 模式 `my-mcp*` 來禁用所有 MCP。
這裡使用 glob 模式 `my-mcp*` 來停用所有 MCP。
---
### 每個代理
### 按代理設定
如果您有大量 MCP 伺服器，您可能只想為每個代理啟用它們並全域禁用它們。為此：
如果您有大量 MCP 伺服器，可以選擇全域停用它們，然後僅在特定代理中啟用。具體做法：
1. 全局禁用它作為工具。
2. 在您的 [代理設定](/docs/agents#tools) 中，啟用 MCP 伺服器作為工具。
1. 全域停用該工具。
2. 在[代理設定](/docs/agents#tools)中，將 MCP 伺服器作為工具啟用。
```json title="opencode.json" {11, 14-18}
{
@@ -377,14 +377,14 @@ opencode mcp debug my-oauth-server
#### Glob 模式
glob 模式使用簡單的正規表示式 globbing 模式：
glob 模式使用簡單的正規表示式萬用字元規則：
- `*` 匹配零個或多個任意字元（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等）
- `?` 恰好匹配一個字元
- 所有其他字元均按字面意思匹配
- `*` 比對零個或多個任意字元（例如，`"my-mcp*"` 比對 `my-mcp_search`、`my-mcp_list` 等）
- `?` 比對恰好一個字元
- 其他字元按字面值比對
:::note
MCP 伺服器工具以伺服器名稱作為前綴進行註冊，因此要禁用伺服器的所有工具，只需使用：
MCP 伺服器工具在註冊時以伺服器名稱作為前綴，因此要停用某個伺服器的所有工具，只需使用：
```
"mymcpservername_*": false
@@ -396,13 +396,13 @@ MCP 伺服器工具以伺服器名稱作為前綴進行註冊，因此要禁用
## 範例
以下是一些常見 MCP 伺服器的範例。如果您想記錄其他伺服器，您可以提交 PR。
以下是一些常見 MCP 伺服器的設定範例。如果您想記錄其他伺服器的用法，歡迎提交 PR。
---
### Sentry
添加 [Sentry MCP 伺服器](https://mcp.sentry.dev) 以與您的 Sentry 專案和問題進行互動。
新增 [Sentry MCP 伺服器](https://mcp.sentry.dev) 以與您的 Sentry 專案和問題進行互動。
```json title="opencode.json" {4-8}
{
@@ -417,15 +417,15 @@ MCP 伺服器工具以伺服器名稱作為前綴進行註冊，因此要禁用
}
```
添加設定後，使用 Sentry 進行身分驗證：
新增設定後，使用 Sentry 進行身分驗證：
```bash
opencode mcp auth sentry
```
這將打開一個瀏覽器視窗以完成 OAuth 流程並將 opencode 連接到您的 Sentry 帳號。
這會開啟瀏覽器視窗完成 OAuth 流程，將 OpenCode 連結到您的 Sentry 帳號。
通過身分驗證後，您可以在提示中使用 Sentry 工具來查詢問題、專案和錯誤資料。
認證完成後，您可以在提示詞中使用 Sentry 工具來查詢問題、專案和錯誤資料。
```txt "use sentry"
Show me the latest unresolved issues in my project. use sentry
@@ -435,7 +435,7 @@ Show me the latest unresolved issues in my project. use sentry
### Context7
添加 [Context7 MCP 伺服器](https://github.com/upstash/context7) 以搜尋文件。
新增 [Context7 MCP 伺服器](https://github.com/upstash/context7) 以搜尋文件。
```json title="opencode.json" {4-7}
{
@@ -449,7 +449,7 @@ Show me the latest unresolved issues in my project. use sentry
}
```
如果您註冊了免費帳號，則可以使用 API 金鑰並獲得更高的速率限制。
如果您註冊了免費帳號，可以使用 API 金鑰來取得更高的速率限制。
```json title="opencode.json" {7-9}
{
@@ -466,15 +466,15 @@ Show me the latest unresolved issues in my project. use sentry
}
```
這裡我們假設您設定了 `CONTEXT7_API_KEY` 環境變數。
這裡假設您已經設定了 `CONTEXT7_API_KEY` 環境變數。
將 `use context7` 添加到提示中以使用 Context7 MCP 伺服器。
在提示詞中新增 `use context7` 即可使用 Context7 MCP 伺服器。
```txt "use context7"
Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
```
或者，您可以將類似的內容添加到您的 [AGENTS.md](/docs/rules/)。
您也可以在 [AGENTS.md](/docs/rules/) 中新增類似的規則。
```md title="AGENTS.md"
When you need to search docs, use `context7` tools.
@@ -482,9 +482,9 @@ When you need to search docs, use `context7` tools.
---
### Vercel 的 Grep
### Grep by Vercel
添加 [Vercel 的 Grep](https://grep.app) MCP 伺服器以搜尋 GitHub 上的程式碼片段。
新增 [Grep by Vercel](https://grep.app) MCP 伺服器以搜尋 GitHub 上的程式碼片段。
```json title="opencode.json" {4-7}
{
@@ -498,13 +498,13 @@ When you need to search docs, use `context7` tools.
}
```
由於我們將 MCP 伺服器命名為 `gh_grep`，因此您可以將 `use the gh_grep tool` 添加到提示中以使代理使用它。
由於我們將 MCP 伺服器命名為 `gh_grep`，您可以在提示詞中新增 `use the gh_grep tool` 來讓代理使用它。
```txt "use the gh_grep tool"
What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
```
或者，您可以將類似的內容添加到您的 [AGENTS.md](/docs/rules/)。
您也可以在 [AGENTS.md](/docs/rules/) 中新增類似的規則。
```md title="AGENTS.md"
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.

85
packages/web/src/content/docs/zh-tw/models.mdx
View File

@@ -1,23 +1,23 @@
---
title: 模型
description: 配置 LLM 供應商和模型。
description: 設定 LLM 提供商和模型。
---
OpenCode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.dev) 來支援 **75+ LLM 供應商**，並且它支援執行本地模型。
OpenCode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.dev) 支援 **75+ LLM 提供商**，並支援執行本地模型。
---
## 供應商
## 提供商
預設情況下會預先載入大多數流行的供應商。如果您已透過 `/connect` 指令添加了供應商的憑證，那麼它們將在您啟動 OpenCode 時可用。
大多數熱門提供商已預設預先載入。如果您透過 `/connect` 指令新增了提供商的憑證，它們將在您啟動 OpenCode 時自動可用。
了解有關 [供應商](/docs/providers) 的更多資訊。
了解更多關於[提供商](/docs/providers)的資訊。
---
## 選擇模型
配置完供應商後，您可以透過輸入以下內容來選擇您想要的模型：
設定好提供商後，您可以透過輸入以下指令來選擇想要使用的模型：
```bash frame="none"
/models
@@ -27,15 +27,15 @@ OpenCode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.de
## 推薦模型
那裡有很多模型，每週都會有新模型問世。
市面上有非常多的模型，每週都有新模型發布。
:::tip
考慮使用我們推薦的模型之一。
建議使用我們推薦的模型。
:::
然而，既擅長生成程式碼又擅長工具呼叫的只有少數。
然而，真正擅長程式碼生成和工具呼叫的模型只有少數幾個。
以下是與 OpenCode 配合良好的幾個模型，排名不分先後。 （這不是詳盡的列表，也不一定是最新的）：
以下是與 OpenCode 配合良好的幾個模型，排名不分先後（此列表並非詳盡無遺，也不一定是最新的）：
- GPT 5.2
- GPT 5.1 Codex
@@ -46,10 +46,9 @@ OpenCode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.de
---
## 設定預設值
## 設定預設模型
要將其中之一設定為預設模型，您可以在您的
OpenCode 配置。
要將某個模型設為預設模型，可以在 OpenCode 設定中設定 `model` 欄位。
```json title="opencode.json" {3}
{
@@ -58,15 +57,15 @@ OpenCode 配置。
}
```
這裡完整的 ID 是 `provider_id/model_id`。例如，如果您使用 [OpenCode Zen](/docs/zen)，則您將使用 `opencode/gpt-5.1-codex` 來表示 GPT 5.1 Codex。
這裡完整的 ID 格式為 `provider_id/model_id`。例如，如果您使用 [OpenCode Zen](/docs/zen)，則 GPT 5.1 Codex 對應的值為 `opencode/gpt-5.1-codex`。
如果您配置了 [自定義供應商](/docs/providers#custom)，則 `provider_id` 是配置中 `provider` 部分的鍵，`model_id` 是 `provider.models` 中的鍵。
如果您設定了[自訂提供商](/docs/providers#custom)，`provider_id` 是設定中 `provider` 部分的鍵名，`model_id` 是 `provider.models` 中的鍵名。
---
## 配置模型
## 設定模型
您可以透過 config.json 全局配置模型的選項。
您可以透過設定檔全域設定模型的選項。
```jsonc title="opencode.jsonc" {7-12,19-24}
{
@@ -100,12 +99,12 @@ OpenCode 配置。
}
```
在這裡，我們為兩個內建模型配置全局設定：`gpt-5`（透過 `openai` 供應商存取時）和 `claude-sonnet-4-20250514`（透過 `anthropic` 供應商存取時）。
內建供應商和模型名稱可以在 [Models.dev](https://models.dev) 上找到。
這裡我們為兩個內建模型設定了全域選項：透過 `openai` 提供商存取的 `gpt-5`，以及透過 `anthropic` 提供商存取的 `claude-sonnet-4-20250514`。
內建的提供商和模型名稱可以在 [Models.dev](https://models.dev) 上查閱。
您還可以為您正在使用的任何代理配置這些選項。代理配置會覆寫此處的所有全局選項。 [了解更多](/docs/agents/#additional)。
您還可以為使用中的任何代理設定這些選項。代理設定會覆寫此處的全域選項。[了解更多](/docs/agents/#additional)。
您還可以定義擴展內建變體的自定義變體。變體允許您為同一模型配置不同的設定，而無需建立重複的項目：
您也可以定義擴展內建變體的自訂變體。變體允許您為同一個模型設定不同的選項，而無需建立重複的項目：
```jsonc title="opencode.jsonc" {6-21}
{
@@ -137,11 +136,11 @@ OpenCode 配置。
## 變體
許多模型支援具有不同配置的多種變體。OpenCode 附帶了流行供應商的內建預設變體。
許多模型支援具有不同設定的多種變體。OpenCode 為熱門提供商內建了預設變體。
### 內建變體
OpenCode 附帶了許多供應商的預設變體：
OpenCode 為許多提供商提供了預設變體：
**Anthropic**：
@@ -152,25 +151,25 @@ OpenCode 附帶了許多供應商的預設變體：
因模型而異，但大致如下：
- `none` - 沒有推理
- `minimal` - 最少的推理工作
- `low` - 推理工作量低
- `medium` - 中等推理工作量
- `high` - 高推理能力
- `xhigh` - 極高的推理能力
- `none` - 無推理
- `minimal` - 極少推理
- `low` - 低推理
- `medium` - 中等推理
- `high` - 高推理
- `xhigh` - 超高推理
**Google**:
**Google**：
- `low` - 降低工作量/Tokens 預算
- `high` - 更高的工作量/Tokens 預算
- `low` - 較低推理/Token 預算
- `high` - 較高推理/Token 預算
:::tip
該列表並不全面。許多其他供應商也有內建的預設值。
此列表並不全面，許多其他提供商也有內建的預設變體。
:::
### 自定義變體
### 自訂變體
您可以覆寫現有變體或添加您自己的變體：
您可以覆寫現有變體或新增自己的變體：
```jsonc title="opencode.jsonc" {7-18}
{
@@ -195,19 +194,19 @@ OpenCode 附帶了許多供應商的預設變體：
}
```
### 循環變體
### 切換變體
使用鍵綁定 `variant_cycle` 在變體之間快速切換。 [了解更多](/docs/keybinds)。
使用快捷鍵 `variant_cycle` 可以快速在變體之間切換。[了解更多](/docs/keybinds)。
---
## 載入模型
當 OpenCode 啟動時，它會按以下優先順序檢查模型：
OpenCode 啟動時，會按以下優先順序載入模型：
1. `--model` 或 `-m` 命令列旗標。格式與設定檔中的相同：`provider_id/model_id`。
1. `--model` 或 `-m` 命令列旗標。格式與設定檔中相同：`provider_id/model_id`。
2. OpenCode 配置中的模型列表。
2. OpenCode 設定中的 model 欄位。
```json title="opencode.json"
{
@@ -216,8 +215,8 @@ OpenCode 附帶了許多供應商的預設變體：
}
```
這裡的格式是 `provider/model`。
格式為 `provider/model`。
3. 最後使用的模型。
3. 上次使用的模型。
4. 第一個模型使用內部優先順序。
4. 按內部優先順序排列的第一個可用模型。

107
packages/web/src/content/docs/zh-tw/modes.mdx
View File

@@ -1,62 +1,60 @@
---
title: 模式
description: 不同的模式適用於不同的使用案例。
description: 不同模式適用於不同的使用情境。
---
:::caution
現在透過 opencode 設定中的 `agent` 選項配置模式。這
`mode` 選項現已棄用。 [了解更多](/docs/agents)。
模式現在透過 opencode 設定中的 `agent` 選項進行設定。`mode` 選項已廢棄。[了解更多](/docs/agents)。
:::
opencode 中的模式允許您自定義不同使用案例的行為、工具和提示。
opencode 中的模式允許您為不同的使用情境自訂行為、工具和提示詞。
它具有兩種內建模式：**建置 (Build)**和**計畫 (Plan)**。您可以自定義
這些或透過 opencode 設定配置您自己的。
opencode 自帶兩種內建模式：**build** 和 **plan**。您可以自訂這些模式，也可以透過 opencode 設定建立自己的模式。
您可以在工作階段期間在模式之間切換或在設定檔中配置它們。
您可以在工作階段中切換模式，也可以在設定檔中進行設定。
---
## 內建
## 內建模式
opencode 有兩種內建模式。
opencode 自帶兩種內建模式。
---
### 建置 (Build)
### Build
建置是啟用所有工具的**預設**模式。這是開發工作的標準模式，您需要完全存取檔案操作和系統指令。
Build 是啟用了所有工具的**預設**模式。這是進行開發工作的標準模式，您可以完全存取檔案操作和系統指令。
---
### 計畫 (Plan)
### Plan
專為規劃和分析而設計的受限模式。在計畫模式下，預設情況下禁用以下工具：
Plan 是一種為規劃和分析設計的受限模式。在 plan 模式下，以下工具預設被停用：
- `write` - 無法建立新檔案
- `edit` - 無法修改現有檔案，位於 `.opencode/plans/*.md` 的用於詳細說明計畫本身的檔案除外
- `patch` - 無法套用 Patch
- `edit` - 無法修改現有檔案，但位於 `.opencode/plans/*.md` 的檔案除外，用於詳細說明計畫本身
- `patch` - 無法套用補丁
- `bash` - 無法執行 shell 指令
當您希望 AI 分析程式碼、建議變更或建立計畫而不對程式碼庫進行任何實際修改時，此模式非常有用。
當您希望 AI 分析程式碼、提出修改建議或制定計畫，而不對程式碼庫進行任何實際更改時，此模式非常有用。
---
## 切換
您可以在工作階段期間使用 _Tab_ 鍵在模式之間切換。或者您配置的 `switch_mode` 鍵綁定。
您可以在工作階段中使用 _Tab_ 鍵切換模式，或者使用您設定的 `switch_mode` 快捷鍵。
另請參閱：[格式化程式](/docs/formatters) 有關程式碼格式配置的資訊。
另請參閱：[格式化工具](/docs/formatters)了解程式碼格式化設定的相關資訊。
---
## 設定
您可以自定義內建模式或透過配置建立自己的模式。可以透過兩種方式配置模式：
您可以自訂內建模式或透過設定建立自己的模式。模式可以透過兩種方式進行設定：
### JSON 配置
### JSON 設定
在 `opencode.json` 設定檔中配置模式：
在 `opencode.json` 設定檔中設定模式：
```json title="opencode.json"
{
@@ -83,9 +81,9 @@ opencode 有兩種內建模式。
}
```
### Markdown 配置
### Markdown 設定
您還可以使用 Markdown 檔案定義模式。將它們放入：
您還可以使用 Markdown 檔案定義模式。將檔案放置在以下位置：
- 全域：`~/.config/opencode/modes/`
- 專案：`.opencode/modes/`
@@ -110,15 +108,15 @@ You are in code review mode. Focus on:
Provide constructive feedback without making direct changes.
```
Markdown 檔名成為模式名稱（例如，`review.md` 建立 `review` 模式）。
Markdown 檔案名稱即為模式名稱（例如，`review.md` 建立一個名為 `review` 的模式）。
讓我們詳細看看這些配置選項。
下面讓我們詳細了解這些設定選項。
---
### 模型 (Model)
### 模型
使用 `model` 配置覆寫此模式的預設模型。對於使用針對不同任務最佳化的不同模型很有用。例如，更快的規劃模型、更強大的實作模型。
使用 `model` 設定可以覆寫該模式的預設模型。這對於針對不同任務使用不同模型非常有用。例如，規劃時使用更快的模型，實作時使用更強大的模型。
```json title="opencode.json"
{
@@ -132,9 +130,9 @@ Markdown 檔名成為模式名稱（例如，`review.md` 建立 `review` 模式
---
### 溫度 (Temperature)
### 溫度
使用 `temperature` 配置控制 AI 回應的隨機性和創造性。較低的值使回應更加集中和確定，而較高的值則增加創造力和可變性。
使用 `temperature` 設定控制 AI 回應的隨機性和創造性。較低的值使回應更加集中和確定性，較高的值則增加創造性和多樣性。
```json title="opencode.json"
{
@@ -151,9 +149,9 @@ Markdown 檔名成為模式名稱（例如，`review.md` 建立 `review` 模式
溫度值的範圍通常為 0.0 到 1.0：
- **0.0-0.2**：非常集中且確定的回應，非常適合程式碼分析和規劃
- **0.3-0.5**：具有一定創造力的平衡回應，適合一般開發任務
- **0.6-1.0**：更有創意和多樣化的反應，有助於腦力激盪和探索
- **0.0-0.2**：非常集中且確定性高的回應，適合程式碼分析和規劃
- **0.3-0.5**：兼顧穩定性與創造力的平衡型回應，適合一般開發任務
- **0.6-1.0**：更具創造性和多樣性的回應，適合腦力激盪和探索性工作
```json title="opencode.json"
{
@@ -173,13 +171,13 @@ Markdown 檔名成為模式名稱（例如，`review.md` 建立 `review` 模式
}
```
如果未指定溫度，opencode 將使用特定於模型的預設值（大多數模型通常為 0，Qwen 模型為 0.55）。
如果未指定溫度，opencode 將使用模型特定的預設值（大多數模型通常為 0，Qwen 模型為 0.55）。
---
### 提示 (Prompt)
### 提示詞
使用 `prompt` 配置為此模式指定自定義系統提示檔案。提示檔案應包含特定於該模式用途的指令。
使用 `prompt` 設定為模式指定自訂系統提示詞檔案。提示詞檔案應包含針對該模式用途的具體指令。
```json title="opencode.json"
{
@@ -191,14 +189,13 @@ Markdown 檔名成為模式名稱（例如，`review.md` 建立 `review` 模式
}
```
該路徑是相對於設定檔所在位置的。所以這適用於
全域 opencode 配置和專案特定配置。
此路徑相對於設定檔所在位置。因此，全域 opencode 設定和專案特定設定均可使用。
---
### 工具 (Tools)
### 工具
使用 `tools` 配置控制在此模式下可用的工具。您可以透過將特定工具設定為 `true` 或 `false` 來啟用或禁用特定工具。
使用 `tools` 設定控制該模式下可用的工具。您可以將特定工具設定為 `true` 或 `false` 來啟用或停用它們。
```json
{
@@ -223,7 +220,7 @@ Markdown 檔名成為模式名稱（例如，`review.md` 建立 `review` 模式
#### 可用工具
這裡是所有可以透過模式配置控制的工具。
以下是所有可透過模式設定控制的工具。
| 工具 | 描述 |
| ----------- | ---------------- |
@@ -234,18 +231,18 @@ Markdown 檔名成為模式名稱（例如，`review.md` 建立 `review` 模式
| `grep` | 搜尋檔案內容 |
| `glob` | 按模式尋找檔案 |
| `list` | 列出目錄內容 |
| `patch` | 對檔案套用 Patch |
| `patch` | 對檔案套用補丁 |
| `todowrite` | 管理待辦事項清單 |
| `todoread` | 閱讀待辦事項清單 |
| `webfetch` | 取得網頁內容 |
| `todoread` | 讀取待辦事項清單 |
| `webfetch` | 擷取網頁內容 |
---
## 自定義模式
## 自訂模式
您可以透過將自定義模式添加到配置來建立自己的自定義模式。以下是使用這兩種方法的範例：
您可以透過在設定中新增自訂模式來建立自己的模式。以下是兩種方式的範例：
### 使用 JSON 配置
### 使用 JSON 設定
```json title="opencode.json" {4-14}
{
@@ -268,7 +265,7 @@ Markdown 檔名成為模式名稱（例如，`review.md` 建立 `review` 模式
### 使用 Markdown 檔案
在 `.opencode/modes/` 中為專案特定模式建立模式檔案，在 `~/.config/opencode/modes/` 中為全域模式建立模式檔案：
在 `.opencode/modes/` 中建立專案特定的模式檔案，或在 `~/.config/opencode/modes/` 中建立全域模式檔案：
```markdown title=".opencode/modes/debug.md"
---
@@ -318,14 +315,14 @@ Priorities:
---
### 使用案例
### 使用情境
以下是不同模式的一些常見使用案例。
以下是不同模式的一些常見使用情境。
- **建置模式**：啟用所有工具的完整開發工作
- **計畫模式**：分析和計畫，無需變更
- **審閱模式**：使用唯讀存取權限和文件工具進行程式碼審閱
- **除錯模式**：專注於啟用 bash 和讀取工具的調查
- **文件模式**：使用檔案操作但不使用系統指令的文件編寫
- **Build 模式**：啟用所有工具的完整開發工作
- **Plan 模式**：分析和規劃，不做任何更改
- **Review 模式**：使用唯讀存取權限加文件工具進行程式碼審查
- **Debug 模式**：啟用 bash 和讀取工具，專注於問題排查
- **Docs 模式**：支援檔案操作但不支援系統指令的文件編寫
您可能還會發現不同的模型適用於不同的使用案例。
您可能還會發現不同的模型適用於不同的使用情境。

20
packages/web/src/content/docs/zh-tw/network.mdx
View File

@@ -1,15 +1,15 @@
---
title: 網路
description: 配置代理伺服器和自定義憑證。
description: 設定代理伺服器和自訂憑證。
---
opencode 支援企業網路環境的標準代理環境變數和自定義憑證。
OpenCode 支援標準代理環境變數和自訂憑證，適用於企業網路環境。
---
## 代理伺服器
opencode 遵循標準代理環境變數。
OpenCode 遵循標準代理環境變數。
```bash
# HTTPS proxy (recommended)
@@ -23,10 +23,10 @@ export NO_PROXY=localhost,127.0.0.1
```
:::caution
TUI 與本地 HTTP 伺服器通訊。您必須繞過此連接的代理以防止路由迴圈。
TUI 與本地 HTTP 伺服器進行通訊。您必須為此連線繞過代理，以防止路由迴圈。
:::
您可以使用 [CLI 旗標](/docs/cli#run) 配置伺服器的連接埠和主機名稱。
您可以使用 [CLI 旗標](/docs/cli#run)來設定伺服器的連接埠和主機名稱。
---
@@ -39,19 +39,19 @@ export HTTPS_PROXY=http://username:password@proxy.example.com:8080
```
:::caution
避免對密碼進行寫死。使用環境變數或安全憑證儲存區。
避免將密碼寫死在程式碼中。請使用環境變數或安全的憑證儲存方式。
:::
對於需要高級身分驗證（例如 NTLM 或 Kerberos）的代理，請考慮使用支援您的身分驗證方法的 LLM 閘道。
對於需要進階身分驗證（如 NTLM 或 Kerberos）的代理，建議使用支援相應身分驗證方式的 LLM 閘道。
---
## 自定義憑證
## 自訂憑證
如果您的企業使用自定義 CA 進行 HTTPS 連接，請配置 opencode 以信任它們。
如果您的企業使用自訂 CA 進行 HTTPS 連線，請設定 OpenCode 以信任這些憑證。
```bash
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```
這適用於代理連接和直接 API 存取。
此設定同時適用於代理連線和直接 API 存取。

92
packages/web/src/content/docs/zh-tw/permissions.mdx
View File

@@ -1,27 +1,27 @@
---
title: 權限
description: 控制哪些操作需要批准才能執行。
description: 控制哪些操作需要審批才能執行。
---
opencode 使用 `permission` 配置來決定給定的操作是否應自動執行、提示您或被阻止。
OpenCode 使用 `permission` 設定來決定某個操作是否應自動執行、提示您審批，還是被阻止。
從 `v1.1.1` 開始，舊版 `tools` 布林配置已被棄用，並已合併到 `permission` 中。仍支援舊的 `tools` 配置以實現向後相容性。
從 `v1.1.1` 開始，舊版 `tools` 布林設定已被廢棄，並已合併到 `permission` 中。舊版 `tools` 設定仍然支援，以保持向後相容。
---
## 操作
每個權限規則解析為以下之一：
每條權限規則解析為以下之一：
- `"allow"` — 未經批准執行
- `"ask"` — 提示批准
- `"allow"` — 無需審批直接執行
- `"ask"` — 提示審批
- `"deny"` — 阻止該操作
---
## 配置
## 設定
您可以全局設定權限（使用 `*`），並覆寫特定工具。
您可以全域設定權限（使用 `*`），並覆寫特定工具的權限。
```json title="opencode.json"
{
@@ -34,7 +34,7 @@ opencode 使用 `permission` 配置來決定給定的操作是否應自動執行
}
```
您還可以一次設定所有權限：
您還可以一次性設定所有權限：
```json title="opencode.json"
{
@@ -45,9 +45,9 @@ opencode 使用 `permission` 配置來決定給定的操作是否應自動執行
---
## 精細規則（物件語法）
## 細粒度規則（物件語法）
對於大多數權限，您可以使用物件根據工具輸入應用不同的操作。
對於大多數權限，您可以使用物件來根據工具輸入套用不同的操作。
```json title="opencode.json"
{
@@ -68,19 +68,19 @@ opencode 使用 `permission` 配置來決定給定的操作是否應自動執行
}
```
規則透過模式匹配進行評估，**最後匹配的規則獲勝**。常見的模式是將通用的 `"*"` 規則放在前面，然後再放置更具體的規則。
規則透過模式比對進行評估，**最後比對的規則優先**。常見做法是將萬用的 `"*"` 規則放在最前面，更具體的規則放在後面。
### 通配符
### 萬用字元
權限模式使用簡單的通配符匹配：
權限模式使用簡單的萬用字元比對：
- `*` 匹配零個或多個任意字元
- `?` 恰好匹配一個字元
- 所有其他字元均按字面意思匹配
- `*` 比對零個或多個任意字元
- `?` 精確比對一個字元
- 所有其他字元按字面值比對
### 主目錄展開
您可以在模式開頭使用 `~` 或 `$HOME` 來引用您的主目錄。這對於 [`external_directory`](#external-directories) 規則特別有用。
您可以在模式開頭使用 `~` 或 `$HOME` 來參照您的主目錄。這對於 [`external_directory`](#外部目錄) 規則特別有用。
- `~/projects/*` -> `/Users/username/projects/*`
- `$HOME/projects/*` -> `/Users/username/projects/*`
@@ -88,11 +88,11 @@ opencode 使用 `permission` 配置來決定給定的操作是否應自動執行
### 外部目錄
使用 `external_directory` 允許工具呼叫存取啟動 opencode 的工作目錄之外的路徑。這適用於任何採用路徑作為輸入的工具（例如 `read`、`edit`、`list`、`glob`、`grep` 和許多 `bash` 指令）。
使用 `external_directory` 允許工具呼叫存取 OpenCode 啟動時工作目錄之外的路徑。這適用於任何接受路徑作為輸入的工具（例如 `read`、`edit`、`list`、`glob`、`grep` 以及許多 `bash` 指令）。
主目錄展開（如 `~/...`）僅影響模式的編寫方式。它不會使外部路徑成為當前工作空間的一部分，因此仍必須透過 `external_directory` 允許工作目錄之外的路徑。
主目錄展開（如 `~/...`）僅影響模式的書寫方式。它不會將外部路徑納入當前工作空間，因此工作目錄之外的路徑仍然必須透過 `external_directory` 來允許。
例如，這允許存取 `~/projects/personal/` 下的所有內容：
例如，以下設定允許存取 `~/projects/personal/` 下的所有內容：
```json title="opencode.json"
{
@@ -105,7 +105,7 @@ opencode 使用 `permission` 配置來決定給定的操作是否應自動執行
}
```
此處允許的任何目錄都會繼承與當前工作空間相同的預設值。自 [`read` 預設為 `allow`](#defaults) 起，也允許讀取 `external_directory` 下的項目，除非被覆寫。當工具應限制在這些路徑中時添加顯式規則，例如在保留讀取的同時阻止編輯：
此處允許的任何目錄都會繼承與當前工作空間相同的預設值。由於 [`read` 預設為 `allow`](#預設值)，`external_directory` 下的項目也允許讀取，除非另行覆寫。當需要在這些路徑中限制某個工具時，請新增顯式規則，例如在保留讀取的同時阻止編輯：
```json title="opencode.json"
{
@@ -121,38 +121,38 @@ opencode 使用 `permission` 配置來決定給定的操作是否應自動執行
}
```
將列表重點放在受信任的路徑上，並根據其他工具的需要疊加額外的允許或拒絕規則（例如 `bash`）。
請將列表限定在受信任的路徑上，並根據需要為其他工具（例如 `bash`）疊加額外的允許或拒絕規則。
---
## 可用權限
opencode 權限由工具名稱和一些安全防護措施決定：
OpenCode 的權限以工具名稱為鍵，外加幾個安全防護項：
- `read` — 讀取檔案（與檔案路徑匹配）
- `read` — 讀取檔案（比對檔案路徑）
- `edit` — 所有檔案修改（涵蓋 `edit`、`write`、`patch`、`multiedit`）
- `glob` — 檔案通配符（匹配通配符模式）
- `grep` — 內容搜尋（匹配正規表示式模式）
- `list` — 列出目錄中的檔案（與目錄路徑匹配）
- `bash` — 執行 shell 指令（匹配 `git status --porcelain` 等解析指令）
- `task` — 啟動子代理（與子代理類型匹配）
- `skill` — 載入技能（與技能名稱匹配）
- `lsp` — 執行 LSP 查詢（當前非精細）
- `glob` — 檔案萬用字元比對（比對萬用字元模式）
- `grep` — 內容搜尋（比對正規表示式模式）
- `list` — 列出目錄中的檔案（比對目錄路徑）
- `bash` — 執行 shell 指令（比對解析後的指令，如 `git status --porcelain`）
- `task` — 啟動子代理（比對子代理類型）
- `skill` — 載入技能（比對技能名稱）
- `lsp` — 執行 LSP 查詢（目前不支援細粒度設定）
- `todoread`、`todowrite` — 讀取/更新待辦事項清單
- `webfetch` — 獲取 URL（與 URL 匹配）
- `websearch`、`codesearch` — 網頁/程式碼搜尋（與查詢匹配）
- `webfetch` — 擷取 URL（比對 URL）
- `websearch`、`codesearch` — 網頁/程式碼搜尋（比對查詢內容）
- `external_directory` — 當工具存取專案工作目錄之外的路徑時觸發
- `doom_loop` — 當相同的工具呼叫使用相同的輸入重複 3 次時觸發
- `doom_loop` — 當同一工具呼叫以相同輸入重複 3 次時觸發
---
## 預設值
如果您不指定任何內容，opencode 將從許可的預設值開始：
如果您未指定任何設定，OpenCode 將使用寬鬆的預設值：
- 大多數權限預設為 `"allow"`。
- `doom_loop` 和 `external_directory` 預設為 `"ask"`。
- `read` 是 `"allow"`，但 `.env` 檔案預設被拒絕：
- `read` 為 `"allow"`，但 `.env` 檔案預設被拒絕：
```json title="opencode.json"
{
@@ -169,24 +169,24 @@ opencode 權限由工具名稱和一些安全防護措施決定：
---
## 「問」(Ask) 的作用是什麼
## "Ask"的作用
當 opencode 提示批准時，UI 會提供三種結果：
當 OpenCode 提示審批時，介面提供三種選擇：
- `once` — 僅批准此請求
- `always` — 批准與建議模式匹配的未來請求（對於當前 opencode 工作階段的其餘部分）
- `once` — 僅批准本次請求
- `always` — 批准與建議模式比對的後續請求（在當前 OpenCode 工作階段的剩餘時間內有效）
- `reject` — 拒絕請求
`always` 將批准的模式集由該工具提供（例如，bash 批准通常將安全指令前綴（如 `git status*`）列入白名單）。
`always` 所批准的模式集合由工具提供（例如，bash 審批通常會將安全的指令前綴如 `git status*` 加入白名單）。
---
## 代理
您可以覆寫每個代理的權限。代理權限與全局配置合併，代理規則優先。 [了解更多](/docs/agents#permissions) 關於代理權限。
您可以為每個代理單獨覆寫權限。代理權限會與全域設定合併，且代理規則優先。[了解更多](/docs/agents#permissions)關於代理權限的內容。
:::note
有關更詳細的模式匹配範例，請參閱上面的 [精細規則（物件語法）](#granular-rules-object-syntax) 部分。
有關更詳細的模式比對範例，請參閱上方的[細粒度規則（物件語法）](#細粒度規則物件語法)部分。
:::
```json title="opencode.json"
@@ -217,7 +217,7 @@ opencode 權限由工具名稱和一些安全防護措施決定：
}
```
您還可以在 Markdown 中配置代理權限：
您還可以在 Markdown 中設定代理權限：
```markdown title="~/.config/opencode/agents/review.md"
---
@@ -233,5 +233,5 @@ Only analyze code and suggest changes.
```
:::tip
對帶有參數的指令使用模式匹配。 `"grep *"` 允許 `grep pattern file.txt`，而 `"grep"` 單獨會阻止它。像 `git status` 這樣的指令適用於預設行為，但在傳遞參數時需要顯式許可（如 `"git status *"`）。
對帶參數的指令使用模式比對。`"grep *"` 允許執行 `grep pattern file.txt`，而單獨的 `"grep"` 則會阻止它。像 `git status` 這樣的指令適用於預設行為，但在傳遞參數時需要顯式權限（如 `"git status *"`）。
:::

93
packages/web/src/content/docs/zh-tw/plugins.mdx
View File

@@ -1,21 +1,21 @@
---
title: 外掛
description: 編寫您自己的外掛來擴展 opencode。
description: 編寫自己的外掛來擴展 OpenCode。
---
外掛允許您透過掛鉤各種事件和自定義行為來擴展 opencode。您可以建立外掛來新增新功能、與外部服務整合或修改 opencode 的預設行為。
外掛允許您透過掛鉤各種事件和自訂行為來擴展 OpenCode。您可以建立外掛來新增新功能、整合外部服務，或修改 OpenCode 的預設行為。
例如，查看社群建立的[外掛](/docs/ecosystem#plugins)。
如需了解範例，請查看社群建立的[外掛](/docs/ecosystem#plugins)。
---
## 使用外掛
有兩種載入外掛的方法。
有兩種方式載入外掛。
---
### 從本地檔案
### 從本地檔案載入
將 JavaScript 或 TypeScript 檔案放置在外掛目錄中。
@@ -26,7 +26,7 @@ description: 編寫您自己的外掛來擴展 opencode。
---
### 來自 npm
### 從 npm 載入
在設定檔中指定 npm 套件。
@@ -37,43 +37,42 @@ description: 編寫您自己的外掛來擴展 opencode。
}
```
支援常規和範圍 npm 套件。
支援常規和帶作用域的 npm 套件。
瀏覽[生態系統](/docs/ecosystem#plugins)中的可用外掛。
---
### 外掛是如何安裝的
### 外掛的安裝方式
**npm 外掛** 在啟動時使用 Bun 自動安裝。套件及其相依套件快取在 `~/.cache/opencode/node_modules/` 中。
**npm 外掛**在啟動時使用 Bun 自動安裝。套件及其相依套件會快取在 `~/.cache/opencode/node_modules/` 中。
**本地外掛**直接從外掛目錄載入。要使用外部套件，您必須在設定目錄中建立 `package.json`（請參閱[相依性](#dependencies)），或將外掛發佈到 npm 和[將其添加到您的設定中](/docs/config#plugins)。
**本地外掛**直接從外掛目錄載入。如果需要使用外部套件，您必須在設定目錄中建立 `package.json`（參見[相依套件](#dependencies)），或者將外掛發布到 npm 並[將其新增到設定中](/docs/config#plugins)。
---
### 載入順序
外掛從所有來源載入，所有掛鉤按順序執行。載入順序為：
外掛從所有來源載入，所有鉤子按順序執行。載入順序為：
1. 全域設定 (`~/.config/opencode/opencode.json`)
2. 專案設定（`opencode.json`）
2. 專案設定 (`opencode.json`)
3. 全域外掛目錄 (`~/.config/opencode/plugins/`)
4. 專案外掛目錄 (`.opencode/plugins/`)
具有相同名稱和版本的重複 npm 套件將被載入一次。但是，本地外掛和名稱相似的 npm 外掛都是分開載入的。
名稱和版本相同的重複 npm 套件只會載入一次。但本地外掛和名稱相似的 npm 外掛會分別獨立載入。
---
## 建立一個外掛
## 建立外掛
外掛是一個 **JavaScript/TypeScript 模組**，它匯出一個或多個外掛
函式。每個函式接收一個上下文物件並返回一個掛鉤物件。
外掛是一個 **JavaScript/TypeScript 模組**，它匯出一個或多個外掛函式。每個函式接收一個上下文物件，並回傳一個鉤子物件。
---
### 相依性
### 相依套件
本地外掛和自定義工具可以使用外部 npm 套件。將 `package.json` 添加到您的設定目錄，其中包含您需要的相依套件。
本地外掛和自訂工具可以使用外部 npm 套件。在設定目錄中新增一個 `package.json`，列出所需的相依套件。
```json title=".opencode/package.json"
{
@@ -83,7 +82,7 @@ description: 編寫您自己的外掛來擴展 opencode。
}
```
opencode 在啟動時執行 `bun install` 來安裝這些。然後您的外掛和工具就可以匯入它們。
OpenCode 會在啟動時執行 `bun install` 來安裝這些相依套件。之後您的外掛和工具就可以匯入它們了。
```ts title=".opencode/plugins/my-plugin.ts"
import { escape } from "shescape"
@@ -113,13 +112,13 @@ export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
}
```
外掛函式接收：
外掛函式接收以下參數：
- `project`：當前專案資訊。
- `directory`：當前工作目錄。
- `worktree`：git 工作樹路徑。
- `client`：用於與 AI 互動的 opencode SDK 客戶端。
- `$`：Bun 的 [shell API](https://bun.com/docs/runtime/shell) 用於執行指令。
- `client`：用於與 AI 互動的 OpenCode SDK 用戶端。
- `$`：Bun 的 [Shell API](https://bun.com/docs/runtime/shell)，用於執行指令。
---
@@ -141,7 +140,7 @@ export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree
### 事件
外掛可以訂閱事件，如下面的範例部分所示。以下是可用的不同事件的列表。
外掛可以訂閱事件，如下方範例部分所示。以下是所有可用事件的列表。
#### 指令事件
@@ -188,7 +187,7 @@ export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree
- `session.status`
- `session.updated`
#### Todo 事件
#### 待辦事項事件
- `todo.updated`
@@ -211,13 +210,13 @@ export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree
## 範例
以下是一些可用於擴展 opencode 的外掛範例。
以下是一些可用於擴展 OpenCode 的外掛範例。
---
### 發送通知
### 傳送通知
當某些事件發生時發送通知：
在特定事件發生時傳送通知：
```js title=".opencode/plugins/notification.js"
export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
@@ -232,17 +231,17 @@ export const NotificationPlugin = async ({ project, client, $, directory, worktr
}
```
我們使用 `osascript` 在 macOS 上執行 AppleScript。這裡我們用它來發送通知。
這裡使用 `osascript` 在 macOS 上執行 AppleScript 來傳送通知。
:::note
如果您使用 opencode 桌面應用程式，它可以在回應準備就緒或工作階段出錯時自動發送系統通知。
如果您使用 OpenCode 桌面應用程式，它可以在回應就緒或工作階段出錯時自動傳送系統通知。
:::
---
### .env 保護
阻止 opencode 讀取 `.env` 檔案：
阻止 OpenCode 讀取 `.env` 檔案：
```javascript title=".opencode/plugins/env-protection.js"
export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
@@ -260,7 +259,7 @@ export const EnvProtection = async ({ project, client, $, directory, worktree })
### 注入環境變數
將環境變數注入所有 shell 執行（AI 工具和使用者終端機）：
將環境變數注入所有 Shell 執行（AI 工具和使用者終端機）：
```javascript title=".opencode/plugins/inject-env.js"
export const InjectEnvPlugin = async () => {
@@ -275,9 +274,9 @@ export const InjectEnvPlugin = async () => {
---
### 自定義工具
### 自訂工具
外掛還可以向 opencode 添加自定義工具：
外掛還可以為 OpenCode 新增自訂工具：
```ts title=".opencode/plugins/custom-tools.ts"
import { type Plugin, tool } from "@opencode-ai/plugin"
@@ -300,19 +299,19 @@ export const CustomToolsPlugin: Plugin = async (ctx) => {
}
```
`tool` 輔助程式建立一個 opencode 可以呼叫的自定義工具。它採用 Zod 模式函式並返回一個工具定義：
`tool` 輔助函式用於建立 OpenCode 可呼叫的自訂工具。它接受一個 Zod schema 函式，並回傳一個工具定義，包含：
- `description`：該工具的作用
- `args`：工具參數的 Zod 模式
- `execute`：呼叫工具時執行的函式
- `description`：工具的功能描述
- `args`：工具參數的 Zod schema
- `execute`：工具被呼叫時執行的函式
您的自定義工具將可與內建工具一起用於 opencode。
您的自訂工具將與內建工具一起在 OpenCode 中可用。
---
### 記錄
### 日誌記錄
使用 `client.app.log()` 而不是 `console.log` 進行結構化記錄：
使用 `client.app.log()` 代替 `console.log` 進行結構化日誌記錄：
```ts title=".opencode/plugins/my-plugin.ts"
export const MyPlugin = async ({ client }) => {
@@ -327,13 +326,13 @@ export const MyPlugin = async ({ client }) => {
}
```
等級：`debug`、`info`、`warn`、`error`。詳情請參閱 [SDK 文件](https://opencode.ai/docs/sdk)。
日誌層級：`debug`、`info`、`warn`、`error`。詳情請參閱 [SDK 文件](https://opencode.ai/docs/sdk)。
---
### 壓縮掛鉤
### 壓縮鉤子
自定義壓縮工作階段時包含的上下文：
自訂工作階段壓縮時包含的上下文：
```ts title=".opencode/plugins/compaction.ts"
import type { Plugin } from "@opencode-ai/plugin"
@@ -343,7 +342,7 @@ export const CompactionPlugin: Plugin = async (ctx) => {
"experimental.session.compacting": async (input, output) => {
// Inject additional context into the compaction prompt
output.context.push(`
## 自定義上下文
## Custom Context
Include any state that should persist across compaction:
- Current task status
@@ -355,9 +354,9 @@ Include any state that should persist across compaction:
}
```
`experimental.session.compacting` 掛鉤在 LLM 生成延續摘要之前觸發。使用它來注入預設壓縮提示會錯過的特定於域的上下文。
`experimental.session.compacting` 鉤子在 LLM 生成續接摘要之前觸發。使用它來注入預設壓縮提示詞可能遺漏的領域特定上下文。
您還可以透過設定 `output.prompt` 來完全替換壓縮提示：
您還可以透過設定 `output.prompt` 來完全替換壓縮提示詞：
```ts title=".opencode/plugins/custom-compaction.ts"
import type { Plugin } from "@opencode-ai/plugin"
@@ -382,4 +381,4 @@ Format as a structured prompt that a new agent can use to resume work.
}
```
當設定 `output.prompt` 時，它完全取代預設的壓縮提示。在這種情況下，`output.context` 陣列將被忽略。
當設定了 `output.prompt` 時，它會完全替換預設的壓縮提示詞。在這種情況下，`output.context` 陣列將被忽略。

565
packages/web/src/content/docs/zh-tw/providers.mdx
View File

File diff suppressed because it is too large Load Diff

72
packages/web/src/content/docs/zh-tw/rules.mdx
View File

@@ -1,9 +1,9 @@
---
title: 規則
description: 設定 opencode 的自定義指令。
description: 為 opencode 設定自訂指令。
---
您可以透過建立 `AGENTS.md` 檔案來提供 opencode 的自定義指令。這和 Cursor 的規則類似。它包含將包含在 LLM 上下文中的說明，以便為您的特定專案自定義其行為。
您可以透過建立 `AGENTS.md` 檔案來為 opencode 提供自訂指令。這類似於 Cursor 的規則功能。該檔案包含的指令會被納入 LLM 的上下文中，以便針對您的特定專案自訂其行為。
---
@@ -15,15 +15,15 @@ description: 設定 opencode 的自定義指令。
您應該將專案的 `AGENTS.md` 檔案提交到 Git。
:::
這將掃描您的專案及其所有內容，以了解該專案的內容並生成一個 `AGENTS.md` 檔案。這有助於 opencode 更好地導覽專案。
該指令會掃描您的專案及其所有內容，了解專案的用途，並據此產生一個 `AGENTS.md` 檔案。這有助於 opencode 更好地導覽您的專案。
如果您有現有的 `AGENTS.md` 檔案，這將嘗試添加到其中。
如果您已有 `AGENTS.md` 檔案，該指令會嘗試在其基礎上進行補充。
---
## 範例
您也可以手動建立此檔案。以下是您可以放入 `AGENTS.md` 檔案中的一些內容的範例。
您也可以手動建立此檔案。以下是一些可以放入 `AGENTS.md` 檔案中的內容範例。
```markdown title="AGENTS.md"
# SST v3 Monorepo Project
@@ -48,33 +48,33 @@ This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for
- Import shared modules using workspace names: `@my-app/core/example`
```
我們在此處添加特定於專案的說明，這將在您的團隊中共享。
我們在這裡新增了專案特定的指令，這些指令會在您的團隊中共享。
---
## 類型
opencode 還支援從多個位置讀取 `AGENTS.md` 檔案。這有不同的目的。
opencode 還支援從多個位置讀取 `AGENTS.md` 檔案，不同的位置有不同的用途。
### 專案
### 專案級
將 `AGENTS.md` 放置在專案根目錄中以獲取特定於專案的規則。這些僅適用於您在此目錄或其子目錄中工作時。
在專案根目錄放置一個 `AGENTS.md` 檔案，用於定義專案特定的規則。這些規則僅在您於該目錄或其子目錄中工作時生效。
### 全域
### 全域級
您還可以在 `~/.config/opencode/AGENTS.md` 檔案中包含全域規則。這適用於所有 opencode 工作階段。
您還可以在 `~/.config/opencode/AGENTS.md` 檔案中設定全域規則。這些規則會套用於所有 opencode 工作階段。
由於這未提交給 Git 或與您的團隊共享，因此我們建議使用它來指定 LLM 應遵循的任何個人規則。
由於該檔案不會被提交到 Git 或與團隊共享，我們建議用它來指定 LLM 應遵循的個人規則。
### Claude Code 相容性
對於從 Claude Code 遷移的使用者，opencode 支援 Claude Code 的檔案慣例作為備援：
對於從 Claude Code 遷移過來的使用者，OpenCode 支援 Claude Code 的檔案慣例作為備援方案：
- **專案規則**：專案目錄中的 `CLAUDE.md`（如果 `AGENTS.md` 不存在則使用）
- **全域規則**：`~/.claude/CLAUDE.md`（如果不存在 `~/.config/opencode/AGENTS.md` 則使用）
- **專案規則**：專案目錄中的 `CLAUDE.md`（在沒有 `AGENTS.md` 的情況下使用）
- **全域規則**：`~/.claude/CLAUDE.md`（在沒有 `~/.config/opencode/AGENTS.md` 的情況下使用）
- **技能**：`~/.claude/skills/` — 詳情請參閱[代理技能](/docs/skills/)
要禁用 Claude Code 相容性，請設定以下環境變數之一：
要停用 Claude Code 相容性，請設定以下環境變數之一：
```bash
export OPENCODE_DISABLE_CLAUDE_CODE=1 # Disable all .claude support
@@ -88,17 +88,17 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
當 opencode 啟動時，它會按以下順序尋找規則檔案：
1. **本地檔案**，從當前目錄向上遍歷 (`AGENTS.md`,`CLAUDE.md`)
2. **全域檔案** `~/.config/opencode/AGENTS.md`
3. **Claude Code 檔案** 位於 `~/.claude/CLAUDE.md`（除非禁用）
1. **本機檔案**，從當前目錄向上遍歷（`AGENTS.md`、`CLAUDE.md`）
2. **全域檔案**，位於 `~/.config/opencode/AGENTS.md`
3. **Claude Code 檔案**，位於 `~/.claude/CLAUDE.md`（除非已停用）
第一個匹配的檔案在每個類別中獲勝。例如，如果您同時擁有 `AGENTS.md` 和 `CLAUDE.md`，則僅使用 `AGENTS.md`。同樣，`~/.config/opencode/AGENTS.md` 優先於 `~/.claude/CLAUDE.md`。
在每個類別中，第一個符合的檔案優先。例如，如果您同時擁有 `AGENTS.md` 和 `CLAUDE.md`，則只會使用 `AGENTS.md`。同樣，`~/.config/opencode/AGENTS.md` 優先於 `~/.claude/CLAUDE.md`。
---
## 自定義指令
## 自訂指令
您可以在 `opencode.json` 或全域 `~/.config/opencode/opencode.json` 中指定自定義指令檔案。這允許您和您的團隊重複使用現有規則，而不必將它們複製到 AGENTS.md。
您可以在 `opencode.json` 或全域設定檔 `~/.config/opencode/opencode.json` 中指定自訂指令檔案。這允許您和團隊複用現有規則，而無需將它們複製到 AGENTS.md 中。
範例：
@@ -109,7 +109,7 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
}
```
您還可以使用遠端 URL 從 Web 載入指令。
您還可以使用遠端 URL 從網路載入指令。
```json title="opencode.json"
{
@@ -118,19 +118,19 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
}
```
遠端指令的獲取有 5 秒的超時時間。
遠端指令的擷取逾時時間為 5 秒。
所有指令檔案均與您的 `AGENTS.md` 檔案合併。
所有指令檔案都會與您的 `AGENTS.md` 檔案合併。
---
## 引用外部檔案
## 參照外部檔案
雖然 opencode 不會自動解析 `AGENTS.md` 中的檔案引用，但您可以透過兩種方式實現類似的功能：
雖然 opencode 不會自動解析 `AGENTS.md` 中的檔案參照，但您可以透過以下兩種方式實現類似的功能：
### 使用 opencode.json
推薦的方法是在 `instructions` 中使用 `opencode.json` 欄位：
建議的方式是使用 `opencode.json` 中的 `instructions` 欄位：
```json title="opencode.json"
{
@@ -139,9 +139,9 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
}
```
### AGENTS.md 中的手動說明
### 在 AGENTS.md 中手動指定
您可以透過在 `AGENTS.md` 中提供明確的指令來教 opencode 讀取外部檔案。這是一個實際的範例：
您可以在 `AGENTS.md` 中提供明確的指令，教 opencode 讀取外部檔案。以下是一個實際範例：
```markdown title="AGENTS.md"
# TypeScript Project Rules
@@ -168,13 +168,13 @@ For testing strategies and coverage requirements: @test/testing-guidelines.md
Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.
```
這種方法允許您：
這種方式允許您：
- 建立模組化、可重複使用的規則檔案
- 透過符號連結或 git 子模組在專案之間共享規則
- 保持 AGENTS.md 簡潔，同時參考詳細指南
- 確保 opencode 僅在特定任務需要時載入檔案
- 建立模組化、可複用的規則檔案
- 透過符號連結或 Git 子模組在專案之間共享規則
- 保持 AGENTS.md 簡潔，同時參照詳細的指南
- 確保 opencode 僅在特定任務需要時才載入檔案
:::tip
對於 Monorepos 或具有共享標準的專案，使用 `opencode.json` 和 glob 模式（如 `packages/*/AGENTS.md`）比手動指令更易於維護。
對於 monorepo 或具有共享標準的專案，使用 `opencode.json` 搭配 glob 模式（如 `packages/*/AGENTS.md`）比手動指定指令更易於維護。
:::

230
packages/web/src/content/docs/zh-tw/sdk.mdx
View File

@@ -1,15 +1,15 @@
---
title: SDK
description: opencode 伺服器的類型安全 JS 客戶端。
description: opencode 伺服器的型別安全 JS 用戶端。
---
import config from "../../../../config.mjs"
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
opencode JS/TS SDK 提供類型安全的客戶端用於與伺服器互動。
使用它以程式化方式構建整合和控制 opencode。
opencode JS/TS SDK 提供了一個型別安全的用戶端，用於與伺服器進行互動。
您可以用它來建構整合方案，並以程式化方式控制 opencode。
[了解更多](/docs/server) 關於伺服器如何工作。例如，查看社群構建的[專案](/docs/ecosystem#projects)。
[了解更多](/docs/server)關於伺服器的運作原理。如需範例，請查看社群建構的[專案](/docs/ecosystem#projects)。
---
@@ -23,9 +23,9 @@ npm install @opencode-ai/sdk
---
## 建立客戶端
## 建立用戶端
建立 opencode 的實例：
建立一個 opencode 實例：
```javascript
import { createOpencode } from "@opencode-ai/sdk"
@@ -33,23 +33,23 @@ import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()
```
這會同時啟動伺服器和客戶端
這會同時啟動伺服器和用戶端。
#### 選項
| 選項 | 類型 | 描述 | 預設 |
| ---------- | ------------- | ------------------------------ | ----------- |
| 選項 | 型別 | 描述 | 預設值 |
| ---------- | ------------- | -------------------------- | ----------- |
| `hostname` | `string` | 伺服器主機名稱 | `127.0.0.1` |
| `port` | `number` | 伺服器連接埠 | `4096` |
| `signal` | `AbortSignal` | 取消的中止訊號 | `undefined` |
| `timeout` | `number` | 伺服器啟動超時（以毫秒為單位） | `5000` |
| `signal` | `AbortSignal` | 用於取消操作的中止訊號 | `undefined` |
| `timeout` | `number` | 伺服器啟動逾時時間（毫秒） | `5000` |
| `config` | `Config` | 設定物件 | `{}` |
---
## 配置
## 設定
您可以傳遞設定物件來自定義行為。該實例仍然會選擇您的 `opencode.json`，但您可以覆寫或添加內聯設定：
您可以傳入一個設定物件來自訂行為。實例仍然會讀取您的 `opencode.json`，但您可以透過內嵌方式覆寫或新增設定：
```javascript
import { createOpencode } from "@opencode-ai/sdk"
@@ -67,9 +67,9 @@ console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()
```
## 僅限客戶端
## 僅用戶端模式
如果您已經有一個正在執行的 opencode 實例，您可以建立一個客戶端實例來連接到它：
如果您已經有一個正在執行的 opencode 實例，可以建立一個用戶端實例來連線：
```javascript
import { createOpencodeClient } from "@opencode-ai/sdk"
@@ -81,29 +81,29 @@ const client = createOpencodeClient({
#### 選項
| 選項 | 類型 | 描述 | 預設 |
| 選項 | 型別 | 描述 | 預設值 |
| --------------- | ---------- | ---------------------------- | ----------------------- |
| `baseUrl` | `string` | 伺服器的 URL | `http://localhost:4096` |
| `fetch` | `function` | 自定義 fetch 實作 | `globalThis.fetch` |
| `parseAs` | `string` | 回應解析方法 | `auto` |
| `responseStyle` | `string` | 返回樣式：`data` 或 `fields` | `fields` |
| `throwOnError` | `boolean` | 拋出錯誤而不是返回 | `false` |
| `baseUrl` | `string` | 伺服器 URL | `http://localhost:4096` |
| `fetch` | `function` | 自訂 fetch 實作 | `globalThis.fetch` |
| `parseAs` | `string` | 回應解析方式 | `auto` |
| `responseStyle` | `string` | 回傳風格：`data` 或 `fields` | `fields` |
| `throwOnError` | `boolean` | 拋出錯誤而非回傳錯誤 | `false` |
---
## 類型
## 型別
SDK 包含所有 API 類型的 TypeScript 定義。直接匯入它們：
SDK 包含所有 API 型別的 TypeScript 定義。您可以直接匯入它們：
```typescript
import type { Session, Message, Part } from "@opencode-ai/sdk"
```
所有類型均根據伺服器的 OpenAPI 規範生成，並可在 <a href={typesUrl}>types 檔案</a>中找到。
所有型別均根據伺服器的 OpenAPI 規範產生，可在<a href={typesUrl}>型別檔案</a>中查看。
---
## 錯誤
## 錯誤處理
SDK 可能會拋出錯誤，您可以捕捉並處理這些錯誤：
@@ -117,13 +117,85 @@ try {
---
## API
## 結構化輸出
SDK 透過類型安全的客戶端公開所有伺服器 API。
您可以透過指定帶有 JSON Schema 的 `format` 來請求模型回傳結構化的 JSON 輸出。模型會使用 `StructuredOutput` 工具回傳符合您 Schema 的經過驗證的 JSON。
### 基本用法
```typescript
const result = await client.session.prompt({
path: { id: sessionId },
body: {
parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
format: {
type: "json_schema",
schema: {
type: "object",
properties: {
company: { type: "string", description: "Company name" },
founded: { type: "number", description: "Year founded" },
products: {
type: "array",
items: { type: "string" },
description: "Main products",
},
},
required: ["company", "founded"],
},
},
},
})
// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }
```
### 輸出格式型別
| 型別 | 描述 |
| ------------- | --------------------------------------- |
| `text` | 預設值。標準文字回應（無結構化輸出） |
| `json_schema` | 回傳符合所提供 Schema 的經過驗證的 JSON |
### JSON Schema 格式
使用 `type: 'json_schema'` 時，需提供以下欄位：
| 欄位 | 型別 | 描述 |
| ------------ | --------------- | ------------------------------------- |
| `type` | `'json_schema'` | 必填。指定 JSON Schema 模式 |
| `schema` | `object` | 必填。定義輸出結構的 JSON Schema 物件 |
| `retryCount` | `number` | 選填。驗證重試次數（預設值：2） |
### 錯誤處理
如果模型在所有重試後仍無法產生有效的結構化輸出，回應中會包含 `StructuredOutputError`：
```typescript
if (result.data.info.error?.name === "StructuredOutputError") {
console.error("Failed to produce structured output:", result.data.info.error.message)
console.error("Attempts:", result.data.info.error.retries)
}
```
### 最佳實務
1. **在 Schema 屬性中提供清晰的描述**，幫助模型理解需要擷取的資料
2. **使用 `required`** 指定哪些欄位必須存在
3. **保持 Schema 簡潔** — 複雜的巢狀 Schema 可能會讓模型更難正確填充
4. **設定合適的 `retryCount`** — 對於複雜 Schema 可增加重試次數，對於簡單 Schema 可減少
---
### 全域
## API
SDK 透過型別安全的用戶端公開所有伺服器 API。
---
### Global
| 方法 | 描述 | 回應 |
| ----------------- | ------------------------ | ------------------------------------ |
@@ -140,11 +212,11 @@ console.log(health.data.version)
---
### 應用程式
### App
| 方法 | 描述 | 回應 |
| -------------- | ------------------ | ------------------------------------------- |
| `app.log()` | 寫入日誌項目 | `boolean` |
| `app.log()` | 寫入一筆日誌 | `boolean` |
| `app.agents()` | 列出所有可用的代理 | <a href={typesUrl}><code>Agent[]</code></a> |
---
@@ -152,7 +224,7 @@ console.log(health.data.version)
#### 範例
```javascript
// Write a log entry
// 寫入一筆日誌
await client.app.log({
body: {
service: "my-app",
@@ -161,18 +233,18 @@ await client.app.log({
},
})
// List available agents
// 列出可用的代理
const agents = await client.app.agents()
```
---
### 專案
### Project
| 方法 | 描述 | 回應 |
| ------------------- | ------------ | --------------------------------------------- |
| `project.list()` | 列出所有專案 | <a href={typesUrl}><code>Project[]</code></a> |
| `project.current()` | 獲取當前專案 | <a href={typesUrl}><code>Project</code></a> |
| `project.current()` | 取得當前專案 | <a href={typesUrl}><code>Project</code></a> |
---
@@ -188,28 +260,28 @@ const currentProject = await client.project.current()
---
### 路徑
### Path
| 方法 | 描述 | 回應 |
| ------------ | ------------ | ---------------------------------------- |
| `path.get()` | 獲取當前路徑 | <a href={typesUrl}><code>Path</code></a> |
| `path.get()` | 取得當前路徑 | <a href={typesUrl}><code>Path</code></a> |
---
#### 範例
```javascript
// Get current path information
// 取得當前路徑資訊
const pathInfo = await client.path.get()
```
---
### 配置
### Config
| 方法 | 描述 | 回應 |
| -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
| `config.get()` | 獲取設定資訊 | <a href={typesUrl}><code>Config</code></a> |
| `config.get()` | 取得設定資訊 | <a href={typesUrl}><code>Config</code></a> |
| `config.providers()` | 列出供應商和預設模型 | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
---
@@ -224,29 +296,29 @@ const { providers, default: defaults } = await client.config.providers()
---
### 工作階段
### Sessions
| 方法 | 描述 | 備註 |
| ---------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `session.list()` | 列出工作階段 | 返回 <a href={typesUrl}><code>Session[]</code></a> |
| `session.get({ path })` | 獲取工作階段 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.children({ path })` | 列出子工作階段 | 返回 <a href={typesUrl}><code>Session[]</code></a> |
| `session.create({ body })` | 建立工作階段 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.delete({ path })` | 刪除工作階段 | 返回 `boolean` |
| `session.update({ path, body })` | 更新工作階段屬性 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.init({ path, body })` | 分析應用程式並建立 `AGENTS.md` | 返回 `boolean` |
| `session.abort({ path })` | 中止正在執行的工作階段 | 返回 `boolean` |
| `session.share({ path })` | 分享工作階段 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.unshare({ path })` | 取消分享工作階段 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.summarize({ path, body })` | 工作階段摘要 | 返回 `boolean` |
| `session.messages({ path })` | 列出工作階段中的訊息 | 返回 `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]` |
| `session.message({ path })` | 獲取訊息詳情 | 返回 `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
| `session.prompt({ path, body })` | 發送提示訊息 | `body.noReply: true` 返回 UserMessage（僅上下文）。預設返回帶有 AI 回應的 <a href={typesUrl}><code>AssistantMessage</code></a> |
| `session.command({ path, body })` | 向工作階段發送指令 | 返回 `{ info: `<a href={typesUrl}><code>AssistantMessage</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
| `session.shell({ path, body })` | 執行 shell 指令 | 返回 <a href={typesUrl}><code>AssistantMessage</code></a> |
| `session.revert({ path, body })` | 還原訊息 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `session.unrevert({ path })` | 恢復已還原的訊息 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `postSessionByIdPermissionsByPermissionId({ path, body })` | 回覆權限請求 | 返回 `boolean` |
| ---------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session.list()` | 列出工作階段 | 回傳 <a href={typesUrl}><code>Session[]</code></a> |
| `session.get({ path })` | 取得工作階段 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `session.children({ path })` | 列出子工作階段 | 回傳 <a href={typesUrl}><code>Session[]</code></a> |
| `session.create({ body })` | 建立工作階段 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `session.delete({ path })` | 刪除工作階段 | 回傳 `boolean` |
| `session.update({ path, body })` | 更新工作階段屬性 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `session.init({ path, body })` | 分析應用程式並建立 `AGENTS.md` | 回傳 `boolean` |
| `session.abort({ path })` | 中止正在執行的工作階段 | 回傳 `boolean` |
| `session.share({ path })` | 分享工作階段 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `session.unshare({ path })` | 取消分享工作階段 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `session.summarize({ path, body })` | 摘要工作階段 | 回傳 `boolean` |
| `session.messages({ path })` | 列出工作階段中的訊息 | 回傳 `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]` |
| `session.message({ path })` | 取得訊息詳情 | 回傳 `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
| `session.prompt({ path, body })` | 傳送提示訊息 | `body.noReply: true` 回傳 UserMessage（僅注入上下文）。預設回傳帶有 AI 回應的 <a href={typesUrl}><code>AssistantMessage</code></a>。支援透過 `body.outputFormat` 使用[結構化輸出](#結構化輸出) |
| `session.command({ path, body })` | 向工作階段傳送指令 | 回傳 `{ info: `<a href={typesUrl}><code>AssistantMessage</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
| `session.shell({ path, body })` | 執行 shell 指令 | 回傳 <a href={typesUrl}><code>AssistantMessage</code></a> |
| `session.revert({ path, body })` | 還原訊息 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `session.unrevert({ path })` | 恢復已還原的訊息 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `postSessionByIdPermissionsByPermissionId({ path, body })` | 回覆權限請求 | 回傳 `boolean` |
---
@@ -281,28 +353,28 @@ await client.session.prompt({
---
### 檔案
### Files
| 方法 | 描述 | 回應 |
| ------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
| `find.text({ query })` | 搜尋檔案中的文字 | 具有 `path`, `lines`, `line_number`, `absolute_offset`, `submatches` 的匹配物件陣列 |
| `find.text({ query })` | 搜尋檔案中的文字 | 包含 `path`、`lines`、`line_number`、`absolute_offset`、`submatches` 的比對物件陣列 |
| `find.files({ query })` | 按名稱尋找檔案和目錄 | `string[]`（路徑） |
| `find.symbols({ query })` | 尋找工作區符號 | <a href={typesUrl}><code>Symbol[]</code></a> |
| `file.read({ query })` | 讀取檔案 | `{ type: "raw" \| "patch", content: string }` |
| `file.status({ query? })` | 獲取追蹤檔案的狀態 | <a href={typesUrl}><code>File[]</code></a> |
| `file.status({ query? })` | 取得已追蹤檔案的狀態 | <a href={typesUrl}><code>File[]</code></a> |
`find.files` 支援一些可選的查詢欄位：
`find.files` 支援以下選填的查詢欄位：
- `type`：`"file"` 或 `"directory"`
- `directory`：覆寫搜尋的專案根目錄
- `limit`：最大結果 (1–200)
- `limit`：最大結果數（1–200）
---
#### 範例
```javascript
// Search and read files
// 搜尋和讀取檔案
const textResults = await client.find.text({
query: { pattern: "function.*opencode" },
})
@@ -326,13 +398,13 @@ const content = await client.file.read({
| 方法 | 描述 | 回應 |
| ------------------------------ | ------------------ | --------- |
| `tui.appendPrompt({ body })` | 將文字附加到提示 | `boolean` |
| `tui.openHelp()` | 打開說明對話方塊 | `boolean` |
| `tui.openSessions()` | 打開工作階段選擇器 | `boolean` |
| `tui.openThemes()` | 打開主題選擇器 | `boolean` |
| `tui.openModels()` | 打開模型選擇器 | `boolean` |
| `tui.submitPrompt()` | 提交當前提示 | `boolean` |
| `tui.clearPrompt()` | 清除提示 | `boolean` |
| `tui.appendPrompt({ body })` | 向提示詞追加文字 | `boolean` |
| `tui.openHelp()` | 開啟說明對話框 | `boolean` |
| `tui.openSessions()` | 開啟工作階段選擇器 | `boolean` |
| `tui.openThemes()` | 開啟主題選擇器 | `boolean` |
| `tui.openModels()` | 開啟模型選擇器 | `boolean` |
| `tui.submitPrompt()` | 送出當前提示詞 | `boolean` |
| `tui.clearPrompt()` | 清除提示詞 | `boolean` |
| `tui.executeCommand({ body })` | 執行指令 | `boolean` |
| `tui.showToast({ body })` | 顯示 Toast 通知 | `boolean` |
@@ -341,7 +413,7 @@ const content = await client.file.read({
#### 範例
```javascript
// Control TUI interface
// 控制 TUI 介面
await client.tui.appendPrompt({
body: { text: "Add this to prompt" },
})
@@ -353,11 +425,11 @@ await client.tui.showToast({
---
### 授權
### Auth
| 方法 | 描述 | 回應 |
| ------------------- | ---------------- | --------- |
| `auth.set({ ... })` | 設定身分驗證憑證 | `boolean` |
| ------------------- | ------------ | --------- |
| `auth.set({ ... })` | 設定驗證憑證 | `boolean` |
---
@@ -372,11 +444,11 @@ await client.auth.set({
---
### 事件
### Events
| 方法 | 描述 | 回應 |
| ------------------- | -------------------- | -------------------- |
| `event.subscribe()` | 伺服器發送的事件串流 | 伺服器發送的事件串流 |
| `event.subscribe()` | 伺服器傳送的事件串流 | 伺服器傳送的事件串流 |
---

185
packages/web/src/content/docs/zh-tw/server.mdx
View File

@@ -6,7 +6,7 @@ description: 透過 HTTP 與 opencode 伺服器互動。
import config from "../../../../config.mjs"
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
`opencode serve` 指令執行一個無介面 HTTP 伺服器，該伺服器公開 opencode 客戶端可以使用的 OpenAPI 端點。
`opencode serve` 指令執行一個無介面的 HTTP 伺服器，暴露一個 OpenAPI 端點供 opencode 客戶端使用。
---
@@ -19,12 +19,12 @@ opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
#### 選項
| 旗標 | 描述 | 預設 |
| --------------- | ------------------------- | ---------------- |
| --------------- | ----------------------- | ---------------- |
| `--port` | 監聽連接埠 | `4096` |
| `--hostname` | 監聽的主機名稱 | `127.0.0.1` |
| `--mdns` | 啟用 mDNS 探索 | `false` |
| `--mdns-domain` | mDNS 服務的自定義網域名稱 | `opencode.local` |
| `--cors` | 允許的其他瀏覽器來源 | `[]` |
| `--mdns-domain` | mDNS 服務的自訂網域名稱 | `opencode.local` |
| `--cors` | 額外允許的瀏覽器來源 | `[]` |
`--cors` 可以多次傳遞：
@@ -34,9 +34,9 @@ opencode serve --cors http://localhost:5173 --cors https://app.example.com
---
### 身分驗證
### 認證
設定 `OPENCODE_SERVER_PASSWORD` 以使用 HTTP 基本身分驗證保護伺服器。使用者名稱預設為 `opencode`，或設定 `OPENCODE_SERVER_USERNAME` 來覆蓋它。這適用於 `opencode serve` 和 `opencode web`。
設定 `OPENCODE_SERVER_PASSWORD` 以使用 HTTP 基本認證保護伺服器。使用者名稱預設為 `opencode`，也可以設定 `OPENCODE_SERVER_USERNAME` 來覆蓋它。這適用於 `opencode serve` 和 `opencode web`。
```bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve
@@ -44,46 +44,43 @@ OPENCODE_SERVER_PASSWORD=your-password opencode serve
---
### 它是如何運作的
### 工作原理
當您執行 `opencode` 時，它會啟動 TUI 和伺服器。 TUI 是
與伺服器對話的客戶端。伺服器公開 OpenAPI 3.1 規範
端點。該端點還用於生成 [軟體開發套件](/docs/sdk)。
當你執行 `opencode` 時，它會啟動一個 TUI 和一個伺服器。TUI 是與伺服器通訊的客戶端。伺服器暴露一個 OpenAPI 3.1 規範端點。該端點也用於產生 [SDK](/docs/sdk)。
:::tip
使用 opencode 伺服器以程式化方式與 opencode 進行互動。
使用 opencode 伺服器以程式化方式與 opencode 互動。
:::
此架構讓 opencode 支援多個客戶端，並允許您以程式化方式與 opencode 進行互動。
這種架構讓 opencode 支援多個客戶端，並允許你以程式化方式與 opencode 互動。
您可以執行 `opencode serve` 來啟動獨立伺服器。如果您有
opencode TUI 執行，`opencode serve` 將啟動一個新伺服器。
你可以執行 `opencode serve` 來啟動一個獨立的伺服器。如果你已經在執行 opencode TUI，`opencode serve` 會啟動一個新的伺服器。
---
#### 連接到現有伺服器
當您啟動 TUI 時，它會隨機分配連接埠和主機名稱。您可以改為傳入 `--hostname` 和 `--port` [旗標](/docs/cli)。然後使用它連接到其伺服器。
當你啟動 TUI 時，它會隨機分配連接埠和主機名稱。你也可以傳入 `--hostname` 和 `--port` [旗標](/docs/cli)，然後用它來連接對應的伺服器。
[`/tui`](#tui) 端點可用於透過伺服器驅動 TUI。例如，您可以預填充或執行提示。此設定由 opencode [IDE](/docs/ide) 外掛使用。
[`/tui`](#tui) 端點可用於透過伺服器驅動 TUI。例如，你可以預填充或執行一個提示詞。此方式被 OpenCode [IDE](/docs/ide) 外掛所使用。
---
## 規格
## 規範
伺服器發布了 OpenAPI 3.1 規範，可以在以下位置查看：
伺服器發布了一個 OpenAPI 3.1 規範，可在以下位址查看：
```
http://<hostname>:<port>/doc
```
例如，`http://localhost:4096/doc`。使用規範生成客戶端或檢查請求和回應類型。或者在 Swagger 瀏覽器中查看它。
例如，`http://localhost:4096/doc`。使用該規範可以產生客戶端或檢查請求和回應類型，也可以在 Swagger 瀏覽器中查看。
---
## API
opencode 伺服器公開以下 API。
opencode 伺服器暴露以下 API。
---
@@ -91,8 +88,8 @@ opencode 伺服器公開以下 API。
| 方法 | 路徑 | 描述 | 回應 |
| ----- | ---------------- | ------------------------ | ------------------------------------ |
| `GET` | `/global/health` | 獲取伺服器健康狀態和版本 | `{ healthy: true, version: string }` |
| `GET` | `/global/event` | 獲取全域事件（SSE 串流） | 事件串流 |
| `GET` | `/global/health` | 取得伺服器健康狀態和版本 | `{ healthy: true, version: string }` |
| `GET` | `/global/event` | 取得全域事件（SSE 串流） | 事件串流 |
---
@@ -101,7 +98,7 @@ opencode 伺服器公開以下 API。
| 方法 | 路徑 | 描述 | 回應 |
| ----- | ------------------ | ------------ | --------------------------------------------- |
| `GET` | `/project` | 列出所有專案 | <a href={typesUrl}><code>Project[]</code></a> |
| `GET` | `/project/current` | 獲取當前專案 | <a href={typesUrl}><code>Project</code></a> |
| `GET` | `/project/current` | 取得當前專案 | <a href={typesUrl}><code>Project</code></a> |
---
@@ -109,8 +106,8 @@ opencode 伺服器公開以下 API。
| 方法 | 路徑 | 描述 | 回應 |
| ----- | ------- | ----------------------- | ------------------------------------------- |
| `GET` | `/path` | 獲取當前路徑 | <a href={typesUrl}><code>Path</code></a> |
| `GET` | `/vcs` | 獲取當前專案的 VCS 資訊 | <a href={typesUrl}><code>VcsInfo</code></a> |
| `GET` | `/path` | 取得當前路徑 | <a href={typesUrl}><code>Path</code></a> |
| `GET` | `/vcs` | 取得當前專案的 VCS 資訊 | <a href={typesUrl}><code>VcsInfo</code></a> |
---
@@ -118,15 +115,15 @@ opencode 伺服器公開以下 API。
| 方法 | 路徑 | 描述 | 回應 |
| ------ | ------------------- | ------------ | --------- |
| `POST` | `/instance/dispose` | 處置當前實例 | `boolean` |
| `POST` | `/instance/dispose` | 銷毀當前實例 | `boolean` |
---
### 配置
### 設定
| 方法 | 路徑 | 描述 | 回應 |
| ------- | ------------------- | -------------------- | ---------------------------------------------------------------------------------------- |
| `GET` | `/config` | 獲取設定資訊 | <a href={typesUrl}><code>Config</code></a> |
| `GET` | `/config` | 取得設定資訊 | <a href={typesUrl}><code>Config</code></a> |
| `PATCH` | `/config` | 更新設定 | <a href={typesUrl}><code>Config</code></a> |
| `GET` | `/config/providers` | 列出供應商和預設模型 | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
@@ -137,47 +134,47 @@ opencode 伺服器公開以下 API。
| 方法 | 路徑 | 描述 | 回應 |
| ------ | -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- |
| `GET` | `/provider` | 列出所有供應商 | `{ all: `<a href={typesUrl}>Provider[]</a>`, default: {...}, connected: string[] }` |
| `GET` | `/provider/auth` | 獲取供應商身分驗證方法 | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` |
| `GET` | `/provider/auth` | 取得供應商認證方式 | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` |
| `POST` | `/provider/{id}/oauth/authorize` | 使用 OAuth 授權供應商 | <a href={typesUrl}><code>ProviderAuthAuthorization</code></a> |
| `POST` | `/provider/{id}/oauth/callback` | 處理供應商的 OAuth 回調 | `boolean` |
| `POST` | `/provider/{id}/oauth/callback` | 處理供應商的 OAuth 回呼 | `boolean` |
---
### 工作階段
| 方法 | 路徑 | 描述 | 備註 |
| -------- | ---------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `GET` | `/session` | 列出所有工作階段 | 返回 <a href={typesUrl}><code>Session[]</code></a> |
| `POST` | `/session` | 建立新工作階段 | 正文：`{ parentID?, title? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/status` | 獲取所有工作階段的狀態 | 返回 `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` |
| `GET` | `/session/:id` | 獲取工作階段詳細資訊 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `DELETE` | `/session/:id` | 刪除工作階段及其所有數據 | 返回 `boolean` |
| `PATCH` | `/session/:id` | 更新工作階段屬性 | 正文：`{ title? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/children` | 獲取工作階段的子工作階段 | 返回 <a href={typesUrl}><code>Session[]</code></a> |
| `GET` | `/session/:id/todo` | 獲取工作階段的待辦事項清單 | 返回 <a href={typesUrl}><code>Todo[]</code></a> |
| `POST` | `/session/:id/init` | 分析應用程式並建立 `AGENTS.md` | 主體：`{ messageID, providerID, modelID }`，返回`boolean` |
| `POST` | `/session/:id/fork` | 在訊息中分岔現有工作階段 | 正文：`{ messageID? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `POST` | `/session/:id/abort` | 中止正在執行的工作階段 | 返回 `boolean` |
| `POST` | `/session/:id/share` | 分享工作階段 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `DELETE` | `/session/:id/share` | 取消分享工作階段 | 返回 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/diff` | 獲取本次工作階段的差異 | 查詢：`messageID?`，返回 <a href={typesUrl}><code>FileDiff[]</code></a> |
| `POST` | `/session/:id/summarize` | 工作階段摘要 | 主體：`{ providerID, modelID }`，返回`boolean` |
| `POST` | `/session/:id/revert` | 還原訊息 | 主體：`{ messageID, partID? }`，返回`boolean` |
| `POST` | `/session/:id/unrevert` | 恢復所有已還原的訊息 | 返回 `boolean` |
| `POST` | `/session/:id/permissions/:permissionID` | 回覆權限請求 | 主體：`{ response, remember? }`，返回`boolean` |
| 方法 | 路徑 | 描述 | 說明 |
| -------- | ---------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| `GET` | `/session` | 列出所有工作階段 | 回傳 <a href={typesUrl}><code>Session[]</code></a> |
| `POST` | `/session` | 建立新工作階段 | 請求主體：`{ parentID?, title? }`，回傳 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/status` | 取得所有工作階段的狀態 | 回傳 `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` |
| `GET` | `/session/:id` | 取得工作階段詳情 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `DELETE` | `/session/:id` | 刪除工作階段及其所有資料 | 回傳 `boolean` |
| `PATCH` | `/session/:id` | 更新工作階段屬性 | 請求主體：`{ title? }`，回傳 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/children` | 取得工作階段的子工作階段 | 回傳 <a href={typesUrl}><code>Session[]</code></a> |
| `GET` | `/session/:id/todo` | 取得工作階段的待辦事項清單 | 回傳 <a href={typesUrl}><code>Todo[]</code></a> |
| `POST` | `/session/:id/init` | 分析應用程式並建立 `AGENTS.md` | 請求主體：`{ messageID, providerID, modelID }`，回傳 `boolean` |
| `POST` | `/session/:id/fork` | 在某條訊息處分岔現有工作階段 | 請求主體：`{ messageID? }`，回傳 <a href={typesUrl}><code>Session</code></a> |
| `POST` | `/session/:id/abort` | 中止正在執行的工作階段 | 回傳 `boolean` |
| `POST` | `/session/:id/share` | 分享工作階段 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `DELETE` | `/session/:id/share` | 取消分享工作階段 | 回傳 <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/diff` | 取得本次工作階段的差異 | 查詢參數：`messageID?`，回傳 <a href={typesUrl}><code>FileDiff[]</code></a> |
| `POST` | `/session/:id/summarize` | 摘要工作階段 | 請求主體：`{ providerID, modelID }`，回傳 `boolean` |
| `POST` | `/session/:id/revert` | 還原訊息 | 請求主體：`{ messageID, partID? }`，回傳 `boolean` |
| `POST` | `/session/:id/unrevert` | 恢復所有已還原的訊息 | 回傳 `boolean` |
| `POST` | `/session/:id/permissions/:permissionID` | 回應權限請求 | 請求主體：`{ response, remember? }`，回傳 `boolean` |
---
### 訊息
| 方法 | 路徑 | 描述 | 備註 |
| ------ | --------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/session/:id/message` | 列出工作階段中的訊息 | 查詢：`limit?`，返回`{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
| `POST` | `/session/:id/message` | 發送訊息並等待回覆 | 主體：`{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`，返回`{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `GET` | `/session/:id/message/:messageID` | 獲取訊息詳情 | 返回`{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/prompt_async` | 非同步發送訊息（無需等待） | body：與`/session/:id/message`相同，返回`204 No Content` |
| `POST` | `/session/:id/command` | 執行斜線指令 | 主體：`{ messageID?, agent?, model?, command, arguments }`，返回`{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/shell` | 執行 shell 指令 | 主體：`{ agent, model?, command }`，返回`{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| 方法 | 路徑 | 描述 | 說明 |
| ------ | --------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/session/:id/message` | 列出工作階段中的訊息 | 查詢參數：`limit?`，回傳 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
| `POST` | `/session/:id/message` | 傳送訊息並等待回應 | 請求主體：`{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`，回傳 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `GET` | `/session/:id/message/:messageID` | 取得訊息詳情 | 回傳 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/prompt_async` | 非同步傳送訊息（不等待回應） | 請求主體：與 `/session/:id/message` 相同，回傳 `204 No Content` |
| `POST` | `/session/:id/command` | 執行斜線指令 | 請求主體：`{ messageID?, agent?, model?, command, arguments }`，回傳 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/shell` | 執行 shell 指令 | 請求主體：`{ agent, model?, command }`，回傳 `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
---
@@ -193,40 +190,40 @@ opencode 伺服器公開以下 API。
| 方法 | 路徑 | 描述 | 回應 |
| ----- | ------------------------ | -------------------- | ----------------------------------------------------------------------------------- |
| `GET` | `/find?pattern=<pat>` | 搜尋檔案中的文字 | 具有 `path`, `lines`, `line_number`, `absolute_offset`, `submatches` 的匹配物件陣列 |
| `GET` | `/find?pattern=<pat>` | 在檔案中搜尋文字 | 包含 `path`、`lines`、`line_number`、`absolute_offset`、`submatches` 的匹配物件陣列 |
| `GET` | `/find/file?query=<q>` | 按名稱尋找檔案和目錄 | `string[]`（路徑） |
| `GET` | `/find/symbol?query=<q>` | 尋找工作區符號 | <a href={typesUrl}><code>Symbol[]</code></a> |
| `GET` | `/file?path=<path>` | 列出檔案和目錄 | <a href={typesUrl}><code>FileNode[]</code></a> |
| `GET` | `/file/content?path=<p>` | 讀取檔案 | <a href={typesUrl}><code>FileContent</code></a> |
| `GET` | `/file/status` | 獲取追蹤檔案的狀態 | <a href={typesUrl}><code>File[]</code></a> |
| `GET` | `/file/status` | 取得已追蹤檔案的狀態 | <a href={typesUrl}><code>File[]</code></a> |
#### `/find/file` 查詢參數
- `query`（必需）- 搜尋字串（模糊匹配）
- `type`（可選）- 將結果限制為 `"file"` 或 `"directory"`
- `directory` (可選) — 覆寫搜尋的專案根目錄
- `limit`（可選）— 最大結果 (1–200)
- `dirs`（可選）- 舊旗標（`"false"` 僅返回檔案）
- `query`（必填）— 搜尋字串（模糊匹配）
- `type`（選填）— 將結果限制為 `"file"` 或 `"directory"`
- `directory`（選填）— 覆蓋搜尋的專案根目錄
- `limit`（選填）— 最大結果數（1–200）
- `dirs`（選填）— 舊版旗標（`"false"` 僅回傳檔案）
---
### 工具（實驗）
### 工具（實驗性）
| 方法 | 路徑 | 描述 | 回應 |
| ----- | ------------------------------------------- | ---------------------------- | -------------------------------------------- |
| `GET` | `/experimental/tool/ids` | 列出所有工具 ID | <a href={typesUrl}><code>ToolID</code></a> |
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | 列出具有模型 JSON 架構的工具 | <a href={typesUrl}><code>ToolList</code></a> |
| ----- | ------------------------------------------- | ---------------------------------- | -------------------------------------------- |
| `GET` | `/experimental/tool/ids` | 列出所有工具 ID | <a href={typesUrl}><code>ToolIDs</code></a> |
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | 列出指定模型的工具及其 JSON Schema | <a href={typesUrl}><code>ToolList</code></a> |
---
### LSP、格式化程式和 MCP
### LSP、格式化工具和 MCP
| 方法 | 路徑 | 描述 | 回應 |
| ------ | ------------ | ------------------- | -------------------------------------------------------- |
| `GET` | `/lsp` | 獲取 LSP 伺服器狀態 | <a href={typesUrl}><code>LSPStatus[]</code></a> |
| `GET` | `/formatter` | 獲取格式化程式狀態 | <a href={typesUrl}><code>FormatterStatus[]</code></a> |
| `GET` | `/mcp` | 獲取 MCP 伺服器狀態 | `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` |
| `POST` | `/mcp` | 動態添加 MCP 伺服器 | body: `{ name, config }`, 返回 MCP 狀態物件 |
| `GET` | `/lsp` | 取得 LSP 伺服器狀態 | <a href={typesUrl}><code>LSPStatus[]</code></a> |
| `GET` | `/formatter` | 取得格式化工具狀態 | <a href={typesUrl}><code>FormatterStatus[]</code></a> |
| `GET` | `/mcp` | 取得 MCP 伺服器狀態 | `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` |
| `POST` | `/mcp` | 動態新增 MCP 伺服器 | 請求主體：`{ name, config }`，回傳 MCP 狀態物件 |
---
@@ -238,45 +235,45 @@ opencode 伺服器公開以下 API。
---
### 記錄
### 日誌
| 方法 | 路徑 | 描述 | 回應 |
| ------ | ------ | --------------------------------------------------------- | --------- |
| `POST` | `/log` | 寫入日誌項目。正文：`{ service, level, message, extra? }` | `boolean` |
| ------ | ------ | ------------------------------------------------------------- | --------- |
| `POST` | `/log` | 寫入日誌項目。請求主體：`{ service, level, message, extra? }` | `boolean` |
---
### TUI
| 方法 | 路徑 | 描述 | 回應 |
| ------ | ----------------------- | ------------------------------------------- | ------------ |
| `POST` | `/tui/append-prompt` | 將文字附加到提示 | `boolean` |
| `POST` | `/tui/open-help` | 打開說明對話方塊 | `boolean` |
| `POST` | `/tui/open-sessions` | 打開工作階段選擇器 | `boolean` |
| `POST` | `/tui/open-themes` | 打開主題選擇器 | `boolean` |
| `POST` | `/tui/open-models` | 打開模型選擇器 | `boolean` |
| `POST` | `/tui/submit-prompt` | 提交當前提示 | `boolean` |
| `POST` | `/tui/clear-prompt` | 清除提示 | `boolean` |
| `POST` | `/tui/execute-command` | 執行指令 (`{ command }`) | `boolean` |
| `POST` | `/tui/show-toast` | 顯示 Toast (`{ title?, message, variant }`) | `boolean` |
| ------ | ----------------------- | ---------------------------------------------- | ------------ |
| `POST` | `/tui/append-prompt` | 向提示詞附加文字 | `boolean` |
| `POST` | `/tui/open-help` | 開啟說明對話框 | `boolean` |
| `POST` | `/tui/open-sessions` | 開啟工作階段選擇器 | `boolean` |
| `POST` | `/tui/open-themes` | 開啟主題選擇器 | `boolean` |
| `POST` | `/tui/open-models` | 開啟模型選擇器 | `boolean` |
| `POST` | `/tui/submit-prompt` | 提交當前提示詞 | `boolean` |
| `POST` | `/tui/clear-prompt` | 清除提示詞 | `boolean` |
| `POST` | `/tui/execute-command` | 執行指令（`{ command }`） | `boolean` |
| `POST` | `/tui/show-toast` | 顯示提示訊息（`{ title?, message, variant }`） | `boolean` |
| `GET` | `/tui/control/next` | 等待下一個控制請求 | 控制請求物件 |
| `POST` | `/tui/control/response` | 回應控制請求 (`{ body }`) | `boolean` |
| `POST` | `/tui/control/response` | 回應控制請求（`{ body }`） | `boolean` |
---
### 授權
### 認證
| 方法 | 路徑 | 描述 | 回應 |
| ----- | ----------- | ------------------------------------------ | --------- |
| `PUT` | `/auth/:id` | 設定身分驗證憑證。正文必須與供應商架構匹配 | `boolean` |
| ----- | ----------- | ---------------------------------------------- | --------- |
| `PUT` | `/auth/:id` | 設定認證憑證。請求主體必須匹配供應商的資料結構 | `boolean` |
---
### 事件
| 方法 | 路徑 | 描述 | 回應 |
| ----- | -------- | --------------------------------------------------------------------------- | -------------------- |
| `GET` | `/event` | 伺服器發送的事件串流。第一個活動是 `server.connected`，然後是事件匯流排事件 | 伺服器發送的事件串流 |
| ----- | -------- | --------------------------------------------------------------------- | ------------------ |
| `GET` | `/event` | 伺服器傳送事件串流。第一個事件是 `server.connected`，之後是匯流排事件 | 伺服器傳送事件串流 |
---
@@ -284,4 +281,4 @@ opencode 伺服器公開以下 API。
| 方法 | 路徑 | 描述 | 回應 |
| ----- | ------ | ---------------- | ----------------------------- |
| `GET` | `/doc` | OpenAPI 3.1 規範 | 具有 OpenAPI 規範的 HTML 頁面 |
| `GET` | `/doc` | OpenAPI 3.1 規範 | 包含 OpenAPI 規範的 HTML 頁面 |

73
packages/web/src/content/docs/zh-tw/share.mdx
View File

@@ -1,41 +1,41 @@
---
title: 分享
description: 分享您的 opencode 對話。
description: 分享您的 OpenCode 對話。
---
opencode 的共享功能允許您建立 opencode 對話的公共連結，以便您可以與團隊成員協作或從其他人那裡獲得幫助。
OpenCode 的分享功能允許您建立指向 OpenCode 對話的公開連結，方便與團隊成員協作或向他人尋求幫助。
:::note
任何知道連結的人都可以公開存取共享對話。
共享的對話對任何擁有連結的人都是公開可存取的。
:::
---
## 它是如何運作的
## 工作原理
當您共享對話時，opencode：
當您分享一段對話時，OpenCode 會：
1. 為您的工作階段建立唯一的公共 URL
2. 將您的對話歷史記錄同步到我們的伺服器
3. 透過可共享連結進行對話 — `opncd.ai/s/<share-id>`
1. 為您的工作階段建立一個唯一的公開 URL
2. 將您的對話歷史同步到我們的伺服器
3. 透過可分享的連結使對話可存取 — `opncd.ai/s/<share-id>`
---
## 模式
## 分享模式
opencode 支援三種控制對話共享方式的共享模式：
OpenCode 支援三種分享模式，用於控制對話的共享方式：
---
### 手動（預設）
### 手動模式（預設）
opencode 預設使用手動共享模式。工作階段不會自動共享，但您可以使用 `/share` 指令手動共享它們：
預設情況下，OpenCode 使用手動分享模式。工作階段不會自動共享，但您可以使用 `/share` 指令手動分享：
```
/share
```
這將生成一個唯一的 URL，並將其複製到您的剪貼簿。
這將產生一個唯一的 URL 並複製到您的剪貼簿。
要在[設定檔](/docs/config)中明確設定手動模式：
@@ -50,7 +50,7 @@ opencode 預設使用手動共享模式。工作階段不會自動共享，但
### 自動分享
您可以在 [設定檔](/docs/config) 中將 `share` 選項設定為 `"auto"` 來為所有新對話啟用自動共享：
您可以在[設定檔](/docs/config)中將 `share` 選項設定為 `"auto"`，為所有新對話啟用自動分享：
```json title="opencode.json"
{
@@ -59,13 +59,13 @@ opencode 預設使用手動共享模式。工作階段不會自動共享，但
}
```
啟用自動共享後，每個新對話都會自動共享並生成連結。
啟用自動分享後，每個新對話都會自動共享並產生連結。
---
### 已禁用
### 停用
您可以在 [設定檔](/docs/config) 中將 `share` 選項設定為 `"disabled"` 來完全禁用共享：
您可以在[設定檔](/docs/config)中將 `share` 選項設定為 `"disabled"`，完全停用分享功能：
```json title="opencode.json"
{
@@ -74,55 +74,54 @@ opencode 預設使用手動共享模式。工作階段不會自動共享，但
}
```
要在整個團隊中針對給定專案強制執行此操作，請將其添加到專案中的 `opencode.json` 並簽入 Git。
要在團隊中對特定專案強制執行此設定，請將其新增到專案的 `opencode.json` 檔案中並提交到 Git。
---
## 取消共享
## 取消分享
要停止共享對話並將其從公共存取中刪除：
要停止分享對話並將其從公開存取中移除：
```
/unshare
```
這將刪除共享連結並刪除與對話相關的數據。
這將移除分享連結並刪除與該對話相關的資料。
---
## 隱私
分享對話時需要記住一些事項。
分享對話時需要注意以下幾點。
---
### 資料保留
共享對話仍然可以存取，直到您明確取消共享。這
包括：
共享的對話在您明確取消分享之前將一直保持可存取狀態。這包括：
- 完整的對話歷史記錄
- 完整的對話歷史
- 所有訊息和回覆
- 工作階段元數據
- 工作階段中繼資料
---
### 建議
- 僅共享不包含敏感資訊的對話。
- 分享之前查看對話內容。
- 協作完成後取消共享對話。
- 避免與專有程式碼或機密數據共享對話。
- 對於敏感專案，完全禁用共享。
- 僅分享不包含敏感資訊的對話。
- 分享前請檢查對話內容。
- 協作完成後請取消分享。
- 避免分享包含專有程式碼或機密資料的對話。
- 對於敏感專案，請完全停用分享功能。
---
## 對於企業
## 企業版
對於企業部署，共享功能可以是：
對於企業部署，分享功能可以：
- **出於安全合規性完全禁用**
- **僅限**僅透過 SSO 進行身分驗證的使用者
- **在您自己的基礎架構上自行託管**
- 出於安全合規考量**完全停用**
- **限制**為僅通過 SSO 身分驗證的使用者可用
- **自行託管**在您自己的基礎架構上
[了解更多](/docs/enterprise) 關於在您的組織中使用 opencode。
[了解更多](/docs/enterprise)關於在您的組織中使用 OpenCode 的資訊。

98
packages/web/src/content/docs/zh-tw/skills.mdx
View File

@@ -1,60 +1,60 @@
---
title: 代理技能
description: 透過 SKILL.md 定義定義可重複使用行為
title: "代理技能"
description: "透過 SKILL.md 定義可重複使用的行為"
---
代理技能讓 opencode 從您的儲存庫或主目錄中發現可重複使用的指令。
技能透過原生 `skill` 工具按需載入 - 代理可以查看可用技能並可以在需要時載入完整內容。
代理技能讓 OpenCode 能夠從你的儲存庫或主目錄中發現可重複使用的指令。
技能透過原生的 `skill` 工具按需載入——代理可以查看可用技能，並在需要時載入完整內容。
---
## 放置檔案
每個技能名稱建立一個資料夾，並在其中放入 `SKILL.md`。
opencode 搜尋這些位置：
為每個技能名稱建立一個資料夾，並在其中放入 `SKILL.md`。
OpenCode 會搜尋以下位置：
- 專案設定：`.opencode/skills/<name>/SKILL.md`
- 全域設定：`~/.config/opencode/skills/<name>/SKILL.md`
- Claude 專案相容：`.claude/skills/<name>/SKILL.md`
- 專案 Claude 相容：`.claude/skills/<name>/SKILL.md`
- 全域 Claude 相容：`~/.claude/skills/<name>/SKILL.md`
- 專案代理相容：`.agents/skills/<name>/SKILL.md`
- 全域代理相容：`~/.agents/skills/<name>/SKILL.md`
---
## 了解發現
## 了解發現機制
對於專案本地路徑，opencode 將從當前工作目錄開始，直到到達 git 工作樹。
它載入 `skills/*/SKILL.md` 中任何匹配的 `.opencode/` 以及一路上任何匹配的 `.claude/skills/*/SKILL.md` 或 `.agents/skills/*/SKILL.md`。
對於專案本地路徑，OpenCode 會從當前工作目錄向上遍歷，直到到達 git 工作樹根目錄。
在此過程中，它會載入 `.opencode/` 中所有匹配的 `skills/*/SKILL.md`，以及匹配的 `.claude/skills/*/SKILL.md` 或 `.agents/skills/*/SKILL.md`。
全域定義也從 `~/.config/opencode/skills/*/SKILL.md`、`~/.claude/skills/*/SKILL.md` 和 `~/.agents/skills/*/SKILL.md` 載入。
全域定義也會從 `~/.config/opencode/skills/*/SKILL.md`、`~/.claude/skills/*/SKILL.md` 和 `~/.agents/skills/*/SKILL.md` 中載入。
---
## 撰寫 Frontmatter
## 撰寫 frontmatter
每個 `SKILL.md` 必須以 YAML frontmatter 開頭。
僅識別這些欄位：
僅識別以下欄位：
- `name`（必填）
- `description`（必填）
- `license`（可選）
- `compatibility`（可選）
- `metadata`（可選，字串到字串對應）
- `license`（選填）
- `compatibility`（選填）
- `metadata`（選填，字串到字串的映射）
未知的 frontmatter 欄位將被忽略。
未知的 frontmatter 欄位會被忽略。
---
## 驗證名稱
`name` 必須：
`name` 必須滿足：
- 長度為 1–64 個字元
- 為小寫字母數字並帶有單個連字號分隔符
- 僅包含小寫字母和數字，可用單個連字號分隔
- 不以 `-` 開頭或結尾
- 不包含連續 `--`
- 匹配包含 `SKILL.md` 的目錄名
- 不包含連續的 `--`
- 與包含 `SKILL.md` 的目錄名稱一致
等效的正規表示式：
@@ -66,14 +66,14 @@ opencode 搜尋這些位置：
## 遵循長度規則
`description` 必須是 1-1024 個字元。
保持足夠具體，以便代理能夠正確選擇。
`description` 必須為 1-1024 個字元。
請保持描述足夠具體，以便代理能夠正確選擇。
---
## 使用一個範例
## 使用範例
像這樣建立 `.opencode/skills/git-release/SKILL.md`：
建立 `.opencode/skills/git-release/SKILL.md`，內容如下：
```markdown
---
@@ -100,10 +100,10 @@ Ask clarifying questions if the target versioning scheme is unclear.
---
## 識別工具說明
## 識別工具描述
opencode 在 `skill` 工具描述中列出了可用的技能。
每個項目都包含技能名稱和描述：
OpenCode 會在 `skill` 工具描述中列出可用技能。
每個條目包含技能名稱和描述：
```xml
<available_skills>
@@ -122,9 +122,9 @@ skill({ name: "git-release" })
---
## 配置權限
## 設定權限
使用 `opencode.json` 中基於模式的權限控制代理可以存取哪些技能：
在 `opencode.json` 中使用基於模式的權限來控制代理可以存取哪些技能：
```json
{
@@ -139,21 +139,21 @@ skill({ name: "git-release" })
}
```
| 許可 | 行為 |
| ------- | -------------------------- |
| 權限 | 行為 |
| ------- | ------------------------ |
| `allow` | 技能立即載入 |
| `deny` | 技能對代理隱藏，存取被拒絕 |
| `ask` | 載入前提示使用者批准 |
| `deny` | 對代理隱藏技能，拒絕存取 |
| `ask` | 載入前提示使用者確認 |
模式支援通配符：`internal-*` 匹配 `internal-docs`、`internal-tools` 等。
模式支援萬用字元：`internal-*` 可匹配 `internal-docs`、`internal-tools` 等。
---
## 覆寫每個代理
## 按代理覆蓋權限
為特定代理授予與全域預設權限不同的權限。
為特定代理授予與全域預設值不同的權限。
**對於自定義代理**（在代理前言中）：
**自訂代理**（在代理 frontmatter 中）：
```yaml
---
@@ -163,7 +163,7 @@ permission:
---
```
**對於內建代理**（在 `opencode.json` 中）：
**內建代理**（在 `opencode.json` 中）：
```json
{
@@ -181,11 +181,11 @@ permission:
---
## 禁用技能工具
## 停用技能工具
完全禁用不應該使用技能的代理：
為不需要使用技能的代理完全停用技能功能：
**對於自定義代理**：
**自訂代理**：
```yaml
---
@@ -194,7 +194,7 @@ tools:
---
```
**對於內建代理**：
**內建代理**：
```json
{
@@ -208,15 +208,15 @@ tools:
}
```
禁用時，`<available_skills>` 部分將被完全省略。
停用後，`<available_skills>` 部分將被完全省略。
---
## 解決載入問題
## 排查載入問題
如果某項技能沒有顯示：
如果某個技能沒有顯示：
1. 驗證 `SKILL.md` 是否全部大寫拼寫
1. 確認 `SKILL.md` 檔案名稱全部為大寫字母
2. 檢查 frontmatter 是否包含 `name` 和 `description`
3. 確保技能名稱在所有位置都是唯一的
4. 檢查權限 - `deny` 的技能對代理隱藏
3. 確保技能名稱在所有位置中唯一
4. 檢查權限設定——設為 `deny` 的技能會對代理隱藏

90
packages/web/src/content/docs/zh-tw/themes.mdx
View File

@@ -3,65 +3,65 @@ title: 主題
description: 選擇內建主題或定義您自己的主題。
---
使用 opencode，您可以從多個內建主題之一中進行選擇，使用適合您的終端機主題的主題，或者定義您自己的自定義主題。
透過 OpenCode，您可以從多個內建主題中進行選擇，使用能自動適配終端機主題的主題，或者定義您自己的自訂主題。
預設情況下，opencode 使用我們自己的 `opencode` 主題。
預設情況下，OpenCode 使用我們自己的 `opencode` 主題。
---
## 終端機要求
為了使主題能夠正確顯示完整的調色盤，您的終端機必須支援**真彩色**（24 位元顏色）。大多數現代終端機預設支援此功能，但您可能需要啟用它：
為了使主題能夠正確顯示完整的調色盤，您的終端機必須支援**真彩色**（24 位元色）。大多數現代終端機預設支援此功能，但您可能需要手動啟用：
- **檢查支援**：執行 `echo $COLORTERM` - 它應該輸出 `truecolor` 或 `24bit`
- **啟用真彩色**：在 shell 設定檔中設定環境變數 `COLORTERM=truecolor`
- **終端機相容性**：確保您的終端機模擬器支援 24 位元顏色（大多數現代終端機，​​如 iTerm2、Alacritty、Kitty、Windows Terminal 和最新版本的 GNOME Terminal 都支援）
- **檢查支援情況**：執行 `echo $COLORTERM` — 輸出應為 `truecolor` 或 `24bit`
- **啟用真彩色**：在您的 shell 設定檔中設定環境變數 `COLORTERM=truecolor`
- **終端機相容性**：確保您的終端機模擬器支援 24 位元色（大多數現代終端機如 iTerm2、Alacritty、Kitty、Windows Terminal 以及較新版本的 GNOME Terminal 均已支援）
如果沒有真彩色支援，主題的顏色精度可能會降低或回退到最接近的 256 色近似值。
如果沒有真彩色支援，主題可能會出現色彩精度下降的情況，或者回退到最接近的 256 色近似值。
---
## 內建主題
opencode 附帶了幾個內建主題。
OpenCode 自帶多個內建主題。
| 名稱 | 描述 |
| ---------------------- | ------------------------------------------------------------------ |
| `system` | 適應您終端機的背景顏色 |
| `tokyonight` | 基於 [Tokyo Night](https://github.com/folke/tokyonight.nvim) 主題 |
| ---------------------- | ------------------------------------------------------------------- |
| `system` | 自動適配終端機的背景顏色 |
| `tokyonight` | 基於 [Tokyonight](https://github.com/folke/tokyonight.nvim) 主題 |
| `everforest` | 基於 [Everforest](https://github.com/sainnhe/everforest) 主題 |
| `ayu` | 基於 [Ayu](https://github.com/ayu-theme) 深色主題 |
| `ayu` | 基於 [Ayu](https://github.com/ayu-theme) 暗色主題 |
| `catppuccin` | 基於 [Catppuccin](https://github.com/catppuccin) 主題 |
| `catppuccin-macchiato` | 基於 [Catppuccin](https://github.com/catppuccin) 主題 |
| `gruvbox` | 基於 [Gruvbox](https://github.com/morhetz/gruvbox) 主題 |
| `kanagawa` | 基於 [Kanagawa](https://github.com/rebelot/kanagawa.nvim) 主題 |
| `nord` | 基於 [Nord](https://github.com/nordtheme/nord) 主題 |
| `matrix` | 駭客風格黑底綠主題 |
| `one-dark` | 基於 [One Dark](https://github.com/Th3Whit3Wolf/one-nvim) 深色主題 |
| `matrix` | 駭客風格的黑底綠字主題 |
| `one-dark` | 基於 [Atom One](https://github.com/Th3Whit3Wolf/one-nvim) Dark 主題 |
此外，我們還在不斷添加新主題。
我們還在不斷新增更多主題。
---
## 系統主題
`system` 主題旨在自動適應您終端機的配色方案。與使用固定顏色的傳統主題不同，_system_ 主題：
`system` 主題旨在自動適配您終端機的配色方案。與使用固定顏色的傳統主題不同，_system_ 主題具有以下特點：
- **生成灰階**：根據終端機的背景顏色建立自定義灰階，確保最佳對比度。
- **使用 ANSI 顏色**：利用標準 ANSI 顏色 (0-15) 進行語法高亮顯示和 UI 元素，尊重終端機的調色盤。
- **保留終端機預設設定**：使用 `none` 作為文字和背景顏色，以保持終端機的原生外觀。
- **產生灰階色階**：根據終端機的背景顏色建立自訂灰階色階，確保最佳對比度。
- **使用 ANSI 顏色**：利用標準 ANSI 顏色（0-15）進行語法高亮和 UI 元素渲染，遵循終端機的調色盤設定。
- **保留終端機預設值**：將文字和背景顏色設為 `none`，以保持終端機的原生外觀。
系統主題適合以下使用者：
- 希望 opencode 與其終端機的外觀相匹配
- 使用自定義終端機配色方案
- 希望所有終端機應用程式具有一致的外觀
- 希望 OpenCode 與終端機的外觀保持一致
- 使用了自訂終端機配色方案
- 偏好所有終端機應用程式擁有統一的視覺風格
---
## 使用主題
您可以透過使用 `/theme` 指令調出主題選擇來選擇主題。或者您可以在 [設定](/docs/config) 中指定它。
您可以透過 `/theme` 指令調出主題選擇介面來選擇主題，也可以在[設定](/docs/config)檔案中直接指定。
```json title="opencode.json" {3}
{
@@ -72,37 +72,37 @@ opencode 附帶了幾個內建主題。
---
## 自定義主題
## 自訂主題
opencode 支援靈活的基於 JSON 的主題系統，允許使用者輕鬆建立和自定義主題。
OpenCode 支援靈活的基於 JSON 的主題系統，讓使用者可以輕鬆建立和自訂主題。
---
### 階層
### 層級優先順序
主題按以下順序從多個目錄載入，其中後面的目錄覆寫前面的目錄：
主題按以下順序從多個目錄載入，後面的目錄會覆蓋前面的目錄：
1. **內建主題** - 這些主題嵌入在二進位檔案中
2. **使用者設定目錄** - 在 `~/.config/opencode/themes/*.json` 或 `$XDG_CONFIG_HOME/opencode/themes/*.json` 中定義
3. **專案根目錄** - 定義在 `<project-root>/.opencode/themes/*.json`
4. **當前工作目錄** - 在 `./.opencode/themes/*.json` 中定義
1. **內建主題** — 嵌入在二進位檔案中
2. **使用者設定目錄** — 定義在 `~/.config/opencode/themes/*.json` 或 `$XDG_CONFIG_HOME/opencode/themes/*.json`
3. **專案根目錄** — 定義在 `<project-root>/.opencode/themes/*.json`
4. **當前工作目錄** — 定義在 `./.opencode/themes/*.json`
如果多個目錄包含同名主題，則將使用優先順序較高的目錄中的主題。
如果多個目錄包含同名主題，將使用優先順序較高的目錄中的主題。
---
### 建立主題
要建立自定義主題，請在主題目錄之一中建立一個 JSON 檔案。
要建立自訂主題，請在上述任一主題目錄中建立一個 JSON 檔案。
對於使用者範圍的主題：
建立使用者級主題：
```bash no-frame
mkdir -p ~/.config/opencode/themes
vim ~/.config/opencode/themes/my-theme.json
```
以及針對特定專案的主題。
建立專案級主題：
```bash no-frame
mkdir -p .opencode/themes
@@ -113,34 +113,34 @@ vim .opencode/themes/my-theme.json
### JSON 格式
主題使用靈活的 JSON 格式，支援：
主題使用靈活的 JSON 格式，支援以下特性：
- **十六進位顏色**：`"#ffffff"`
- **ANSI 顏色**：`3` (0-255)
- **顏色參考**：`"primary"` 或自定義定義
- **深色/淺色版本**：`{"dark": "#000", "light": "#fff"}`
- **無顏色**：`"none"` - 使用終端機的預設顏色或透明
- **ANSI 顏色**：`3`（0-255）
- **顏色參考**：`"primary"` 或自訂定義的顏色名
- **深色/淺色變體**：`{"dark": "#000", "light": "#fff"}`
- **無顏色**：`"none"` — 使用終端機的預設顏色或透明背景
---
### 顏色定義
`defs` 部分是可選的，它允許您定義可在主題中引用的可重複使用顏色。
`defs` 部分是選填的，它允許您定義可在主題中重複引用的可重複使用顏色。
---
### 終端機預設值
特殊值 `"none"` 可用於任何顏色以繼承終端機的預設顏色。這對於建立與終端機配色方案無縫融合的主題特別有用：
特殊值 `"none"` 可用於任何顏色屬性，以繼承終端機的預設顏色。這在建立需要與終端機配色方案無縫融合的主題時特別有用：
- `"text": "none"` - 使用終端機的預設前景色
- `"background": "none"` - 使用終端機的預設背景顏色
- `"text": "none"` — 使用終端機的預設前景色
- `"background": "none"` — 使用終端機的預設背景色
---
### 範例
以下是自定義主題的範例：
以下是一個自訂主題的完整範例：
```json title="my-theme.json"
{

112
packages/web/src/content/docs/zh-tw/tools.mdx
View File

@@ -3,15 +3,15 @@ title: 工具
description: 管理 LLM 可以使用的工具。
---
工具允許 LLM 在您的程式碼庫中執行操作。 opencode 附帶了一組內建工具，但您可以使用 [自定義工具](/docs/custom-tools) 或 [MCP 伺服器](/docs/mcp-servers) 對其進行擴展。
工具允許 LLM 在您的程式碼庫中執行操作。OpenCode 自帶一組內建工具，您也可以透過[自訂工具](/docs/custom-tools)或 [MCP 伺服器](/docs/mcp-servers)來擴充它。
預設情況下，所有工具都是**啟用**並且不需要執行權限。您可以透過 [權限](/docs/permissions) 控制工具行為。
預設情況下，所有工具都是**啟用**的，且無需權限即可執行。您可以透過[權限](/docs/permissions)來控制工具的行為。
---
## 配置
## 設定
使用 `permission` 欄位控制工具行為。您可以允許、拒絕或要求批准每個工具。
使用 `permission` 欄位來控制工具行為。您可以對每個工具設定允許、拒絕或需要審批。
```json title="opencode.json"
{
@@ -24,7 +24,7 @@ description: 管理 LLM 可以使用的工具。
}
```
您還可以使用通配符同時控制多個工具。例如，要求 MCP 伺服器批准所有工具：
您還可以使用萬用字元同時控制多個工具。例如，要求某個 MCP 伺服器的所有工具都需要審批：
```json title="opencode.json"
{
@@ -35,13 +35,13 @@ description: 管理 LLM 可以使用的工具。
}
```
[了解更多](/docs/permissions) 關於配置權限。
[了解更多](/docs/permissions)關於設定權限的內容。
---
## 內建
## 內建工具
以下是 opencode 中可用的所有內建工具。
以下是 OpenCode 中所有可用的內建工具。
---
@@ -58,13 +58,13 @@ description: 管理 LLM 可以使用的工具。
}
```
該工具允許 LLM 執行 `npm install`、`git status` 等終端機指令或任何其他 shell 指令。
該工具允許 LLM 執行終端機指令，例如 `npm install`、`git status` 或其他任何 shell 指令。
---
### edit
使用精確的字串替換修改現有檔案。
透過精確的字串替換來修改現有檔案。
```json title="opencode.json" {4}
{
@@ -75,7 +75,7 @@ description: 管理 LLM 可以使用的工具。
}
```
該工具透過替換精確的文字匹配來對檔案執行精確編輯。這是 LLM 修改程式碼的主要方式。
該工具透過替換精確匹配的文字來對檔案進行編輯。這是 LLM 修改程式碼的主要方式。
---
@@ -92,17 +92,17 @@ description: 管理 LLM 可以使用的工具。
}
```
使用它允許 LLM 建立新檔案。如果現有檔案已經存在，它將覆蓋它們。
使用此工具允許 LLM 建立新檔案。如果檔案已存在，則會覆蓋現有檔案。
:::note
`write` 工具由 `edit` 權限控制，該權限涵蓋所有檔案修改（`edit`、`write`、`patch`、`multiedit`）。
`write` 工具由 `edit` 權限控制，該權限涵蓋所有檔案修改操作（`edit`、`write`、`patch`、`multiedit`）。
:::
---
### read
從程式碼庫中讀取檔案內容。
讀取程式碼庫中的檔案內容。
```json title="opencode.json" {4}
{
@@ -113,7 +113,7 @@ description: 管理 LLM 可以使用的工具。
}
```
該工具讀取檔案並返回其內容。它支援讀取大檔案的特定行範圍。
該工具讀取檔案並回傳其內容。它支援對大檔案讀取指定行範圍。
---
@@ -130,13 +130,13 @@ description: 管理 LLM 可以使用的工具。
}
```
在您的程式碼庫中快速進行內容搜尋。支援完整的正規表示式語法和檔案模式過濾。
在程式碼庫中快速搜尋內容。支援完整的正規表示式語法和檔案模式過濾。
---
### glob
透過模式匹配尋找檔案。
透過模式匹配查找檔案。
```json title="opencode.json" {4}
{
@@ -147,13 +147,13 @@ description: 管理 LLM 可以使用的工具。
}
```
使用 `**/*.js` 或 `src/**/*.ts` 等全域模式搜尋檔案。返回按修改時間排序的匹配檔案路徑。
使用 `**/*.js` 或 `src/**/*.ts` 等 glob 模式搜尋檔案。回傳按修改時間排序的匹配檔案路徑。
---
### list
列出給定路徑中的檔案和目錄。
列出指定路徑下的檔案和目錄。
```json title="opencode.json" {4}
{
@@ -164,16 +164,16 @@ description: 管理 LLM 可以使用的工具。
}
```
該工具列出目錄內容。它接受全域模式來過濾結果。
該工具用於列出目錄內容。它接受 glob 模式來過濾結果。
---
### lsp（實驗性）
與您配置的 LSP 伺服器互動，以獲得程式碼智慧功能，例如定義、引用、游標懸停資訊和呼叫階層。
與已設定的 LSP 伺服器互動，取得程式碼智慧功能，如定義跳轉、參考查找、懸停資訊和呼叫階層結構。
:::note
該工具僅在 `OPENCODE_EXPERIMENTAL_LSP_TOOL=true`（或 `OPENCODE_EXPERIMENTAL=true`）時可用。
該工具僅在設定 `OPENCODE_EXPERIMENTAL_LSP_TOOL=true`（或 `OPENCODE_EXPERIMENTAL=true`）時可用。
:::
```json title="opencode.json" {4}
@@ -187,13 +187,13 @@ description: 管理 LLM 可以使用的工具。
支援的操作包括 `goToDefinition`、`findReferences`、`hover`、`documentSymbol`、`workspaceSymbol`、`goToImplementation`、`prepareCallHierarchy`、`incomingCalls` 和 `outgoingCalls`。
要配置哪些 LSP 伺服器可用於您的專案，請參閱 [LSP 伺服器](/docs/lsp)。
要設定專案可用的 LSP 伺服器，請參閱 [LSP 伺服器](/docs/lsp)。
---
### patch
對檔案套用 Patch。
對檔案套用補丁。
```json title="opencode.json" {4}
{
@@ -204,17 +204,17 @@ description: 管理 LLM 可以使用的工具。
}
```
該工具將 Patch 檔案套用到您的程式碼庫。對於套用來自各種來源的差異和 Patch 很有用。
該工具將補丁檔案套用到您的程式碼庫中。適用於套用來自各種來源的 diff 和補丁。
:::note
`patch` 工具由 `edit` 權限控制，該權限涵蓋所有檔案修改（`edit`、`write`、`patch`、`multiedit`）。
`patch` 工具由 `edit` 權限控制，該權限涵蓋所有檔案修改操作（`edit`、`write`、`patch`、`multiedit`）。
:::
---
### skill
載入 [技能](/docs/skills)（`SKILL.md` 檔案）並在對話中返回其內容。
載入一個[技能](/docs/skills)（即 `SKILL.md` 檔案）並在對話中回傳其內容。
```json title="opencode.json" {4}
{
@@ -229,7 +229,7 @@ description: 管理 LLM 可以使用的工具。
### todowrite
在編碼工作階段期間管理待辦事項清單。
在編碼工作階段中管理待辦事項清單。
```json title="opencode.json" {4}
{
@@ -240,17 +240,17 @@ description: 管理 LLM 可以使用的工具。
}
```
建立和更新任務列表以追蹤複雜操作期間的進度。LLM 使用它來組織多步驟任務。
建立和更新任務清單以追蹤複雜操作的進度。LLM 使用此工具來組織多步驟任務。
:::note
預設情況下，子代理禁用此工具，但您可以手動啟用它。 [了解更多](/docs/agents/#permissions)
該工具預設對子代理停用，但您可以手動啟用。[了解更多](/docs/agents/#permissions)
:::
---
### todoread
閱讀現有的待辦事項清單。
讀取現有的待辦事項清單。
```json title="opencode.json" {4}
{
@@ -261,17 +261,17 @@ description: 管理 LLM 可以使用的工具。
}
```
讀取當前待辦事項清單狀態。LLM 用來追蹤哪些任務待處理或已完成。
讀取當前待辦事項清單的狀態。LLM 使用此工具來追蹤哪些任務待處理、哪些已完成。
:::note
預設情況下，子代理禁用此工具，但您可以手動啟用它。 [了解更多](/docs/agents/#permissions)
該工具預設對子代理停用，但您可以手動啟用。[了解更多](/docs/agents/#permissions)
:::
---
### webfetch
獲取網頁內容。
擷取網頁內容。
```json title="opencode.json" {4}
{
@@ -282,7 +282,7 @@ description: 管理 LLM 可以使用的工具。
}
```
允許 LLM 獲取和閱讀網頁。對於尋找文件或研究線上資源很有用。
允許 LLM 擷取並讀取網頁內容。適用於查閱文件或研究線上資源。
---
@@ -291,9 +291,9 @@ description: 管理 LLM 可以使用的工具。
在網路上搜尋資訊。
:::note
僅當使用 opencode 供應商或 `OPENCODE_ENABLE_EXA` 環境變數設定為任何真值（例如 `true` 或 `1`）時，此工具才可用。
該工具僅在使用 OpenCode 供應商時，或當 `OPENCODE_ENABLE_EXA` 環境變數設定為任意真值（例如 `true` 或 `1`）時可用。
要在啟動 opencode 時啟用：
在啟動 OpenCode 時啟用：
```bash
OPENCODE_ENABLE_EXA=1 opencode
@@ -310,19 +310,19 @@ OPENCODE_ENABLE_EXA=1 opencode
}
```
使用 Exa AI 執行網路搜尋以線上尋找相關資訊。對於研究主題、尋找時事或收集超出訓練數據截止範圍的資訊很有用。
使用 Exa AI 進行網路搜尋以查找相關資訊。適用於研究主題、了解時事動態或取得超出訓練資料截止日期的資訊。
不需要 API 金鑰 - 該工具無需身分驗證即可直接連接到 Exa AI 的託管 MCP 服務。
無需 API 金鑰——該工具無需身分驗證即可直接連接到 Exa AI 的託管 MCP 服務。
:::tip
當您需要尋找資訊（發現）時，請使用 `websearch`；當您需要從特定 URL 檢索內容（檢索）時，請使用 `webfetch`。
當您需要查找資訊（發現）時使用 `websearch`，當您需要從特定 URL 擷取內容（檢索）時使用 `webfetch`。
:::
---
### question
在執行過程中詢問使用者問題。
在執行過程中向使用者提問。
```json title="opencode.json" {4}
{
@@ -333,42 +333,42 @@ OPENCODE_ENABLE_EXA=1 opencode
}
```
該工具允許 LLM 在任務期間詢問使用者問題。它適用於：
該工具允許 LLM 在執行任務期間向使用者提問。適用於以下場景：
- 收集使用者偏好或要求
- 澄清不明確的指令
- 就實作選擇做出決策
- 提供選擇方向
- 收集使用者偏好或需求
- 釐清模糊的指令
- 取得實作方案的決策
- 提供方向選擇的選項
每個問題都包含標題、問題文字和選項列表。使用者可以從提供的選項中進行選擇或輸入自定義答案。當存在多個問題時，使用者可以在提交所有答案之前在這些問題之間導航。
每個問題包含標題、問題正文和選項清單。使用者可以從提供的選項中選擇，也可以輸入自訂答案。當有多個問題時，使用者可以在提交所有答案之前在各問題之間切換瀏覽。
---
## 自定義工具
## 自訂工具
自定義工具可讓您定義 LLM 可以呼叫的自己的函式。這些是在您的設定檔中定義的並且可以執行任意程式碼。
自訂工具允許您定義 LLM 可以呼叫的自訂函式。這些函式在您的設定檔中定義，可以執行任意程式碼。
[了解更多](/docs/custom-tools) 關於建立自定義工具。
[了解更多](/docs/custom-tools)關於建立自訂工具的內容。
---
## MCP 伺服器
MCP（模型上下文協定）伺服器允許您整合外部工具和服務。這包括資料庫存取、API 整合和第三方服務。
MCP（Model Context Protocol）伺服器允許您整合外部工具和服務，包括資料庫存取、API 整合和第三方服務。
[了解更多](/docs/mcp-servers) 關於配置 MCP 伺服器。
[了解更多](/docs/mcp-servers)關於設定 MCP 伺服器的內容。
---
## 內部結構
## 內部機制
在內部，`grep`、`glob` 和 `list` 等工具在底層使用 [ripgrep](https://github.com/BurntSushi/ripgrep)。預設情況下，ripgrep 遵循 `.gitignore` 模式，這意味著 `.gitignore` 中列出的檔案和目錄將從搜尋和列表中排除。
在內部，`grep`、`glob` 和 `list` 等工具底層使用 [ripgrep](https://github.com/BurntSushi/ripgrep)。預設情況下，ripgrep 遵循 `.gitignore` 中的模式，這意味著 `.gitignore` 中列出的檔案和目錄將被排除在搜尋和列表結果之外。
---
### 忽略模式
要包含通常會被忽略的檔案，請在專案根目錄中建立一個 `.ignore` 檔案。該檔案可以明確允許某些路徑。
要包含通常會被忽略的檔案，請在專案根目錄下建立一個 `.ignore` 檔案。該檔案可以明確允許某些路徑。
```text title=".ignore"
!node_modules/
@@ -376,4 +376,4 @@ MCP（模型上下文協定）伺服器允許您整合外部工具和服務。
!build/
```
例如，此 `.ignore` 檔案允許 ripgrep 在 `node_modules/`、`dist/` 和 `build/` 目錄中搜尋，即使它們列在 `.gitignore` 中。
例如，這個 `.ignore` 檔案允許 ripgrep 在 `node_modules/`、`dist/` 和 `build/` 目錄中進行搜尋，即使它們已在 `.gitignore` 中列出。

187
packages/web/src/content/docs/zh-tw/troubleshooting.mdx
View File

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

113
packages/web/src/content/docs/zh-tw/tui.mdx
View File

@@ -5,21 +5,21 @@ description: 使用 OpenCode 終端機使用者介面。
import { Tabs, TabItem } from "@astrojs/starlight/components"
OpenCode 提供了一個互動式終端機介面或 TUI，供您與 LLM 一起處理專案。
OpenCode 提供了一個互動式終端機介面（TUI），用於配合 LLM 處理您的專案。
執行 OpenCode 會啟動當前目錄的 TUI。
執行 OpenCode 即可啟動當前目錄的 TUI。
```bash
opencode
```
或者您可以為特定的工作目錄啟動它。
或者您可以為指定的工作目錄啟動它。
```bash
opencode /path/to/project
```
進入 TUI 後，您可以透過訊息進行提示。
進入 TUI 後，您可以輸入訊息進行提示。
```text
Give me a quick summary of the codebase.
@@ -29,29 +29,29 @@ 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 指令。
以 `!` 開頭的訊息會作為 shell 指令執行。
```bash frame="none"
!ls -la
```
指令的輸出將作為工具結果添加到對話中。
指令的輸出會作為工具結果新增到對話中。
---
@@ -63,7 +63,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
/help
```
大多數指令也有使用 `ctrl+x` 作為 Leader 鍵的按鍵綁定，其中 `ctrl+x` 是預設的 Leader 鍵。 [了解更多](/docs/keybinds)。
大多數指令還支援以 `ctrl+x` 作為前導鍵的快速鍵，其中 `ctrl+x` 是預設前導鍵。[了解更多](/docs/keybinds)。
以下是所有可用的斜線指令：
@@ -71,7 +71,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
### connect
將供應商添加到 OpenCode。允許您從可用的供應商中進行選擇並添加其 API 金鑰。
將供應商新增到 OpenCode。允許您從可用的供應商中選擇並新增其 API 金鑰。
```bash frame="none"
/connect
@@ -87,31 +87,31 @@ How is auth handled in @packages/functions/src/api/index.ts?
/compact
```
**按鍵綁定：** `ctrl+x c`
**快速鍵：** `ctrl+x c`
---
### details
切換工具執行詳細資訊。
切換工具執行詳情的顯示。
```bash frame="none"
/details
```
**按鍵綁定：** `ctrl+x d`
**快速鍵：** `ctrl+x d`
---
### editor
打開外部編輯器來撰寫訊息。使用 `EDITOR` 環境變數中設定的編輯器。 [了解更多](#editor-setup)。
開啟外部編輯器來撰寫訊息。使用 `EDITOR` 環境變數中設定的編輯器。[了解更多](#editor-setup)。
```bash frame="none"
/editor
```
**按鍵綁定：** `ctrl+x e`
**快速鍵：** `ctrl+x e`
---
@@ -123,31 +123,31 @@ How is auth handled in @packages/functions/src/api/index.ts?
/exit
```
**按鍵綁定：** `ctrl+x q`
**快速鍵：** `ctrl+x q`
---
### export
將當前對話導出到 Markdown 並在預設編輯器中打開。使用 `EDITOR` 環境變數中設定的編輯器。 [了解更多](#editor-setup)。
將當前對話匯出為 Markdown 並在預設編輯器中開啟。使用 `EDITOR` 環境變數中設定的編輯器。[了解更多](#editor-setup)。
```bash frame="none"
/export
```
**按鍵綁定：** `ctrl+x x`
**快速鍵：** `ctrl+x x`
---
### help
顯示說明對話方塊。
顯示說明對話框。
```bash frame="none"
/help
```
**按鍵綁定：** `ctrl+x h`
**快速鍵：** `ctrl+x h`
---
@@ -159,7 +159,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
/init
```
**按鍵綁定：** `ctrl+x i`
**快速鍵：** `ctrl+x i`
---
@@ -171,7 +171,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
/models
```
**按鍵綁定：** `ctrl+x m`
**快速鍵：** `ctrl+x m`
---
@@ -183,26 +183,25 @@ How is auth handled in @packages/functions/src/api/index.ts?
/new
```
**按鍵綁定：** `ctrl+x n`
**快速鍵：** `ctrl+x n`
---
### redo
重做之前撤銷的訊息。僅在使用 `/undo` 後可用。
重做之前復原的訊息。僅在使用 `/undo` 後可用。
:::tip
任何檔案變更也將被恢復。
所有檔案變更也會被恢復。
:::
在內部，這使用 Git 來管理檔案變更。所以你的專案**需要
是一個 Git 儲存庫**。
在內部，這使用 Git 來管理檔案變更。因此您的專案**需要是一個 Git 儲存庫**。
```bash frame="none"
/redo
```
**按鍵綁定：** `ctrl+x r`
**快速鍵：** `ctrl+x r`
---
@@ -214,7 +213,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
/sessions
```
**按鍵綁定：** `ctrl+x l`
**快速鍵：** `ctrl+x l`
---
@@ -226,28 +225,28 @@ How is auth handled in @packages/functions/src/api/index.ts?
/share
```
**按鍵綁定：** `ctrl+x s`
**快速鍵：** `ctrl+x s`
---
### themes
列出可用的主題。
列出可用主題。
```bash frame="none"
/theme
```
**按鍵綁定：** `ctrl+x t`
**快速鍵：** `ctrl+x t`
---
### thinking
切換對話中思考/推理區塊的可見性。啟用後，您可以看到支援擴展思考的模型的推理過程。
切換對話中思考/推理區塊的可見性。啟用後，您可以看到支援擴充思考的模型的推理過程。
:::note
該指令僅控制是否**顯示** - 它不啟用或禁用模型的推理功能。要切換實際推理功能，請使用 `ctrl+t` 循環切換模型變體。
此指令僅控制思考區塊是否**顯示** — 它不會啟用或停用模型的推理能力。要切換實際的推理能力，請使用 `ctrl+t` 循環切換模型變體。
:::
```bash frame="none"
@@ -258,20 +257,19 @@ How is auth handled in @packages/functions/src/api/index.ts?
### undo
撤銷對話中的最後一條訊息。刪除最近的使用者訊息、所有後續回應以及任何檔案變更。
復原對話中的最後一條訊息。移除最近的使用者訊息、所有後續回應以及所有檔案變更。
:::tip
所做的任何檔案變更也將被恢復。
所做的任何檔案變更也會被還原。
:::
在內部，這使用 Git 來管理檔案變更。所以你的專案**需要
是一個 Git 儲存庫**。
在內部，這使用 Git 來管理檔案變更。因此您的專案**需要是一個 Git 儲存庫**。
```bash frame="none"
/undo
```
**按鍵綁定：** `ctrl+x u`
**快速鍵：** `ctrl+x u`
---
@@ -301,8 +299,8 @@ How is auth handled in @packages/functions/src/api/index.ts?
export EDITOR="code --wait"
```
To make it permanent, add this to your shell profile;
`~/.bashrc`, `~/.zshrc`, etc.
要使其永久生效，請將其新增到您的 shell 設定檔中；
`~/.bashrc`、`~/.zshrc` 等。
</TabItem>
@@ -315,8 +313,7 @@ How is auth handled in @packages/functions/src/api/index.ts?
set EDITOR=code --wait
```
To make it permanent, use **System Properties** > **Environment
Variables**.
要使其永久生效，請使用**系統內容** > **環境變數**。
</TabItem>
@@ -329,12 +326,12 @@ How is auth handled in @packages/functions/src/api/index.ts?
$env:EDITOR = "code --wait"
```
To make it permanent, add this to your PowerShell profile.
要使其永久生效，請將其新增到您的 PowerShell 設定檔中。
</TabItem>
</Tabs>
流行的編輯器選項包括：
常用的編輯器選項包括：
- `code` - Visual Studio Code
- `cursor` - Cursor
@@ -342,20 +339,20 @@ How is auth handled in @packages/functions/src/api/index.ts?
- `nvim` - Neovim 編輯器
- `vim` - Vim 編輯器
- `nano` - Nano 編輯器
- `notepad` - Windows 記事本
- `notepad` - Notepad（Windows 記事本）
- `subl` - Sublime Text
:::note
某些編輯器（例如 VS Code）需要以 `--wait` 旗標啟動。
某些編輯器（如 VS Code）需要以 `--wait` 旗標啟動。
:::
某些編輯器需要命令列參數才能在阻止模式下執行。 `--wait` 旗標使編輯器處理程序阻塞直到關閉。
某些編輯器需要命令列參數才能以阻塞模式執行。`--wait` 旗標使編輯器程序阻塞直到關閉。
---
## 配置
## 設定
您可以透過 OpenCode 設定檔自定義 TUI 行為。
您可以透過 OpenCode 設定檔自訂 TUI 行為。
```json title="opencode.json"
{
@@ -371,20 +368,20 @@ How is auth handled in @packages/functions/src/api/index.ts?
### 選項
- `scroll_acceleration` - 啟用 macOS 風格的捲動加速，實現平滑、自然的捲動。啟用後，捲動速度會隨著快速捲動手勢而增加，並在較慢的移動時保持精確。 **此設定優先於 `scroll_speed`，並在啟用時覆寫它。**
- `scroll_speed` - 控制使用捲動指令時 TUI 捲動的速度（最小值：`1`）。預設為 `3`。 **注意：如果 `scroll_acceleration.enabled` 設定為 `true`，則忽略此設定。**
- `scroll_acceleration` - 啟用 macOS 風格的捲動加速，實現平滑、自然的捲動體驗。啟用後，快速捲動時速度會增加，慢速移動時保持精確。**此設定優先於 `scroll_speed`，啟用時會覆蓋它。**
- `scroll_speed` - 控制使用捲動指令時 TUI 的捲動速度（最小值：`1`）。預設為 `3`。**注意：如果 `scroll_acceleration.enabled` 設定為 `true`，則此設定會被忽略。**
---
## 自定義
## 自訂
您可以使用指令面板（`ctrl+x h` 或 `/help`）自定義 TUI 視圖的各個方面。這些設定在重新啟動後仍然存在。
您可以使用指令面板（`ctrl+x h` 或 `/help`）自訂 TUI 檢視的各個方面。這些設定在重新啟動後仍會保留。
---
#### 使用者名稱顯示
切換您的使用者名稱是否出現在聊天訊息中。透過以下方式存取：
切換您的使用者名稱是否顯示在聊天訊息中。透過以下方式存取：
- 指令面板：搜尋「使用者名稱」或「隱藏使用者名稱」
- 該設定會自動保留並在 TUI 工作階段中被記住
- 指令面板：搜尋「username」或「hide username」
- 該設定會自動儲存，並在各個 TUI 工作階段中保持記憶

60
packages/web/src/content/docs/zh-tw/web.mdx
View File

@@ -1,39 +1,39 @@
---
title: Web
description: 在瀏覽器中使用 opencode。
description: 在瀏覽器中使用 OpenCode。
---
opencode 可以在瀏覽器中作為 Web 應用程式執行，無需終端機即可提供同樣強大的 AI 程式碼體驗。
OpenCode 可以作為 Web 應用程式在瀏覽器中執行，無需終端機即可獲得同樣強大的 AI 編碼體驗。
![opencode Web - 新工作階段](../../../assets/web/web-homepage-new-session.png)
![OpenCode Web - New Session](../../../assets/web/web-homepage-new-session.png)
## 入門
## 快速開始
透過執行以下指令啟動 Web 介面：
執行以下指令啟動 Web 介面：
```bash
opencode web
```
這將在 `127.0.0.1` 上啟動一個具有隨機可用連接埠的本地伺服器，並自動在預設瀏覽器中打開 opencode。
這會在 `127.0.0.1` 上啟動一個本地伺服器，使用隨機可用連接埠，並自動在預設瀏覽器中開啟 OpenCode。
:::caution
如果未設定 `OPENCODE_SERVER_PASSWORD`，伺服器將不安全。這對於本地使用來說很好，但應該針對網路存取進行設定。
如果未設定 `OPENCODE_SERVER_PASSWORD`，伺服器將沒有安全保護。本地使用沒有問題，但在網路存取時應當設定密碼。
:::
:::tip[Windows 使用者]
為了獲得最佳體驗，請從 [WSL](/docs/windows-wsl) 而不是 PowerShell 執行 `opencode web`。這確保了正確的檔案系統存取和終端機整合。
為獲得最佳體驗，建議從 [WSL](/docs/windows-wsl) 而非 PowerShell 執行 `opencode web`。這可以確保正確的檔案系統存取和終端機整合。
:::
---
## 配置
## 設定
您可以使用命令列旗標或在 [設定檔](/docs/config) 中配置 Web 伺服器。
你可以透過命令列旗標或[設定檔](/docs/config)來設定 Web 伺服器。
### 連接埠
預設情況下，opencode 選擇一個可用連接埠。您可以指定一個連接埠：
預設情況下，OpenCode 會選擇一個可用連接埠。你也可以指定連接埠：
```bash
opencode web --port 4096
@@ -41,13 +41,13 @@ opencode web --port 4096
### 主機名稱
預設情況下，伺服器綁定到 `127.0.0.1`（僅限 localhost）。要使 opencode 在您的網路上可存取：
預設情況下，伺服器繫結到 `127.0.0.1`（僅限本地存取）。要使 OpenCode 在網路中可存取：
```bash
opencode web --hostname 0.0.0.0
```
當使用 `0.0.0.0` 時，opencode 將顯示本地位址和網路位址：
使用 `0.0.0.0` 時，OpenCode 會同時顯示本地位址和網路位址：
```
Local access: http://localhost:4096
@@ -56,15 +56,15 @@ opencode web --hostname 0.0.0.0
### mDNS 探索
啟用 mDNS 以使您的伺服器在本地網路上可探索：
啟用 mDNS 可以讓你的伺服器在本地網路中被自動探索：
```bash
opencode web --mdns
```
這會自動將主機名稱設定為 `0.0.0.0` 並將伺服器廣播為 `opencode.local`。
這會自動將主機名稱設定為 `0.0.0.0`，並將伺服器廣播為 `opencode.local`。
您可以自定義 mDNS 網域名稱以在同一網路上執行多個實例：
你可以自訂 mDNS 網域名稱，以便在同一網路中執行多個實例：
```bash
opencode web --mdns --mdns-domain myproject.local
@@ -72,7 +72,7 @@ opencode web --mdns --mdns-domain myproject.local
### CORS
允許 CORS 的其他域（對於自定義前端有用）：
要為 CORS 新增額外的允許網域（適用於自訂前端）：
```bash
opencode web --cors https://example.com
@@ -80,53 +80,53 @@ opencode web --cors https://example.com
### 身分驗證
要保護存取，請使用 `OPENCODE_SERVER_PASSWORD` 環境變數設定密碼：
要保護伺服器存取，可以透過 `OPENCODE_SERVER_PASSWORD` 環境變數設定密碼：
```bash
OPENCODE_SERVER_PASSWORD=secret opencode web
```
使用者名稱預設為 `opencode`，但可以使用 `OPENCODE_SERVER_USERNAME` 進行更改。
使用者名稱預設為 `opencode`，可以透過 `OPENCODE_SERVER_USERNAME` 進行更改。
---
## 使用 Web 介面
啟動後，Web 介面將提供對 opencode 工作階段的存取。
啟動後，Web 介面提供對 OpenCode 工作階段的存取。
### 工作階段
從主頁查看和管理您的工作階段。您可以查看活動工作階段並開始新工作階段。
在主頁上查看和管理你的工作階段。你可以查看進行中的工作階段，也可以建立新的工作階段。
![opencode Web - 活動工作階段](../../../assets/web/web-homepage-active-session.png)
![OpenCode Web - Active Session](../../../assets/web/web-homepage-active-session.png)
### 伺服器狀態
單擊「查看伺服器」可查看連接的伺服器及其狀態。
點擊「See Servers」可以查看已連線的伺服器及其狀態。
![opencode Web - 查看伺服器](../../../assets/web/web-homepage-see-servers.png)
![OpenCode Web - See Servers](../../../assets/web/web-homepage-see-servers.png)
---
## 連接終端機
您可以將終端機 TUI 連接到正在執行的 Web 伺服器：
你可以將終端機 TUI 連接到正在執行的 Web 伺服器：
```bash
# Start the web server
# 啟動 Web 伺服器
opencode web --port 4096
# In another terminal, attach the TUI
# 在另一個終端機中連接 TUI
opencode attach http://localhost:4096
```
這允許您同時使用 Web 介面和終端機，共享相同的工作階段和狀態。
這樣你就可以同時使用 Web 介面和終端機，共享相同的工作階段和狀態。
---
## 設定檔
您還可以在 `opencode.json` 設定檔中配置伺服器設定：
你也可以在 `opencode.json` 設定檔中設定伺服器選項：
```json
{
@@ -139,4 +139,4 @@ opencode attach http://localhost:4096
}
```
命令列旗標優先於設定檔設定。
命令列旗標的優先順序高於設定檔中的設定。

61
packages/web/src/content/docs/zh-tw/windows-wsl.mdx
View File

@@ -1,37 +1,37 @@
---
title: Windows (WSL)
description: 在 Windows 透過 WSL 使用 opencode。
description: 透過 WSL 在 Windows 上執行 OpenCode 以獲得最佳體驗。
---
import { Steps } from "@astrojs/starlight/components"
雖然 opencode 可以直接在 Windows 上執行，但為了獲得最佳體驗，我們建議使用 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install)。WSL 提供了可與 opencode 功能順暢配合的 Linux 環境。
雖然 OpenCode 可以直接在 Windows 上執行，但我們推薦使用 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) 以獲得最佳體驗。WSL 提供了一個 Linux 環境，能夠與 OpenCode 的各項功能無縫配合。
:::tip[為什麼要用 WSL？]
WSL 提供更好的檔案系統效能、完整的terminal支援，以及與 opencode 依賴之開發工具的相容性。
:::tip[為什麼選擇 WSL？]
WSL 提供更出色的檔案系統效能、完整的終端機支援，以及與 OpenCode 所依賴的開發工具的良好相容性。
:::
---
## 設定
## 安裝設定
<Steps>
1. **安裝 WSL**
如果你尚未安裝，請依照 Microsoft 官方指南[安裝 WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。
如果尚未安裝，請參照 Microsoft 官方指南[安裝 WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。
2. **在 WSL 中安裝 opencode**
2. **在 WSL 中安裝 OpenCode**
完成 WSL 設定後，打開 WSL terminal，並使用其中一種[安裝方式](/docs/)安裝 opencode。
WSL 設定完成後，開啟 WSL 終端機，使用任一[安裝方式](/docs/)安裝 OpenCode。
```bash
curl -fsSL https://opencode.ai/install | bash
```
3. **從 WSL 使用 opencode**
3. **從 WSL 中使用 OpenCode**
移動到你的專案目錄（可透過 `/mnt/c/`、`/mnt/d/` 等路徑存取 Windows 檔案），然後執行 opencode。
導航到你的專案目錄（透過 `/mnt/c/`、`/mnt/d/` 等路徑存取 Windows 檔案），然後執行 OpenCode。
```bash
cd /mnt/c/Users/YourName/project
@@ -44,54 +44,53 @@ WSL 提供更好的檔案系統效能、完整的terminal支援，以及與 open
## 桌面應用程式 + WSL 伺服器
如果你偏好使用 opencode 桌面應用程式，但希望在 WSL 內執行伺服器：
如果你希望使用 OpenCode 桌面應用程式，同時在 WSL 中執行伺服器：
1. **在 WSL 中啟動伺服器**，並使用 `--hostname 0.0.0.0` 允許外部連線：
1. **在 WSL 中啟動伺服器**，新增 `--hostname 0.0.0.0` 以允許外部連線：
```bash
opencode serve --hostname 0.0.0.0 --port 4096
```
2. **將桌面應用程式連線到** `http://localhost:4096`
2. **在桌面應用程式中連線到** `http://localhost:4096`
:::note
若你的環境中 `localhost` 無法使用，請改用 WSL 的 IP 位址連線（在 WSL 執行：`hostname -I`），並使用 `http://<wsl-ip>:4096`。
如果 `localhost` 在你的環境中無法使用，請改用 WSL 的 IP 位址進行連線（在 WSL 中執行：`hostname -I`），使用 `http://<wsl-ip>:4096`。
:::
:::caution
使用 `--hostname 0.0.0.0` 時，請設定 `OPENCODE_SERVER_PASSWORD` 來保護伺服器。
使用 `--hostname 0.0.0.0` 時，請設定 `OPENCODE_SERVER_PASSWORD` 以保護伺服器安全。
:::
```bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve --hostname 0.0.0.0
```
:::
---
## Web 用戶端 + WSL
## Web 客戶端 + WSL
在 Windows 上取得最佳 Web 體驗：
要在 Windows 上獲得最佳的 Web 體驗：
1. **請在 WSL terminal執行 `opencode web`**，而不是在 PowerShell 執行：
1. **在 WSL 終端機中執行 `opencode web`**，而非在 PowerShell 中執行：
```bash
opencode web --hostname 0.0.0.0
```
2. **在 Windows 瀏覽器中開啟** `http://localhost:<port>`（opencode 會輸出該 URL）
2. **在 Windows 瀏覽器中存取** `http://localhost:<port>`（OpenCode 會輸出該 URL）
從 WSL 執行 `opencode web` 可確保正確的檔案系統存取與terminal整合，同時仍可由 Windows 瀏覽器使用。
從 WSL 中執行 `opencode web` 可確保正確的檔案系統存取和終端機整合，同時仍可透過 Windows 瀏覽器進行存取。
---
## 存取 Windows 檔案
WSL 可透過 `/mnt/` 目錄存取你所有的 Windows 檔案：
WSL 可以透過 `/mnt/` 目錄存取你的所有 Windows 檔案：
- `C:` drive → `/mnt/c/`
- `D:` drive → `/mnt/d/`
- 其他磁碟機也相同
- `C:` 磁碟 → `/mnt/c/`
- `D:` 磁碟 → `/mnt/d/`
- 其他磁碟以此類推...
範例：
@@ -101,13 +100,13 @@ opencode
```
:::tip
為了更流暢的使用體驗，建議將你的儲存庫 clone 或複製到 WSL 檔案系統（例如 `~/code/`）中，再從那裡執行 opencode。
為了獲得更流暢的體驗，建議將儲存庫克隆或複製到 WSL 檔案系統中（例如 `~/code/` 目錄下），然後在該位置執行 OpenCode。
:::
---
## 提示
## 使用技巧
- 即使專案存放在 Windows 磁碟機上，也建議在 WSL 中執行 opencode，檔案存取會更順暢
- 可將 opencode 與 VS Code 的 [WSL 擴充套件](https://code.visualstudio.com/docs/remote/wsl)搭配使用，建立整合式開發流程
- opencode 的設定與工作階段會儲存在 WSL 環境中的 `~/.local/share/opencode/`
- 對於儲存在 Windows 磁碟上的專案，在 WSL 中執行 OpenCode 即可無縫存取檔案
- 搭配 VS Code 的 [WSL 擴充套件](https://code.visualstudio.com/docs/remote/wsl) 使用 OpenCode，打造一體化的開發工作流程
- OpenCode 的設定和工作階段資料儲存在 WSL 環境中的 `~/.local/share/opencode/`

168
packages/web/src/content/docs/zh-tw/zen.mdx
View File

@@ -1,66 +1,57 @@
---
title: Zen
description: opencode 提供的精選模型列表。
description: 由 OpenCode 提供的精選模型列表。
---
import config from "../../../../config.mjs"
export const console = config.console
export const email = `mailto:${config.email}`
OpenCode Zen 是 opencode 團隊提供的經過測試和驗證的模型列表。
OpenCode Zen 是由 OpenCode 團隊提供的一組經過測試和驗證的模型列表。
:::note
OpenCode Zen 目前處於測試階段。
:::
Zen 的工作方式與 opencode 中的任何其他供應商一樣。您登入 OpenCode Zen 並獲取
您的 API 金鑰。它是**完全可選的**，您不需要使用它即可使用
opencode。
Zen 的工作方式與 OpenCode 中的任何其他供應商相同。你只需登入 OpenCode Zen 並取得你的 API 金鑰。它是**完全選用的**，你無需使用它也能正常使用 OpenCode。
---
## 背景
市面上有很多模型，但其中只有少數幾個
這些模型可以很好地用作程式碼代理。此外，大多數供應商都
配置非常不同；所以你會得到截然不同的性能和質量。
市面上有大量的模型，但其中只有少數能夠很好地充當編碼代理。此外，大多數供應商的設定方式差異很大，因此你獲得的效能和品質也會截然不同。
:::tip
我們測試了一組精選的與 opencode 配合良好的模型和供應商。
我們測試了一組與 OpenCode 配合良好的精選模型和供應商。
:::
因此，如果您透過 OpenRouter 之類的東西使用模型，那麼您永遠無法
確定您是否獲得了您想要的模型的最佳版本。
所以如果你透過 OpenRouter 之類的服務使用模型，你永遠無法確定是否獲得了你想要的模型的最佳版本。
為了解決這個問題，我們做了幾件事：
為了解決這個問題，我們做了以下幾件事：
1. 我們測試了一組選定的模型，並與他們的團隊討論瞭如何
最好執行它們。
2. 然後我們與一些供應商合作以確保這些服務得到服務
正確。
3. 最後，我們對模型/供應商的組合進行了基準測試並提出了
並附上一份我們覺得不錯的推薦清單。
1. 我們測試了一組精選的模型，並與它們的團隊討論了最佳執行方式。
2. 然後我們與幾家供應商合作，確保這些模型能被正確地提供服務。
3. 最後，我們對模型與供應商的組合進行了基準測試，整理出了一份我們有信心推薦的列表。
OpenCode Zen 是一個 AI 閘道，可讓您存取這些模型。
OpenCode Zen 是一個 AI 閘道，讓你可以存取這些模型。
---
## 它是如何運作的
## 工作原理
OpenCode Zen 的工作方式與 opencode 中的任何其他供應商一樣。
OpenCode Zen 的工作方式與 OpenCode 中的任何其他供應商相同。
1. 您登入 **<a href={console}>OpenCode Zen</a>**，添加您的帳單
詳細資訊，然後複製您的 API 金鑰。
2. 您在 TUI 中執行 `/connect` 指令，選擇 OpenCode Zen，然後貼上您的 API 金鑰。
3. 在 TUI 中執行 `/models` 以查看我們推薦的模型列表。
1. 登入 **<a href={console}>OpenCode Zen</a>**，新增你的帳單資訊，然後複製你的 API 金鑰。
2. 在 TUI 中執行 `/connect` 指令，選擇 OpenCode Zen，然後貼上你的 API 金鑰。
3. 在 TUI 中執行 `/models` 查看我們推薦的模型列表。
您需要按請求付費，並且可以將點數添加到您的帳戶中。
你按請求付費，並且可以向你的帳戶中儲值。
---
## 端點
您還可以透過以下 API 端點存取我們的模型。
你還可以透過以下 API 端點存取我們的模型。
| 模型 | 模型 ID | 端點 | AI SDK 套件 |
| ------------------ | ------------------ | -------------------------------------------------- | --------------------------- |
@@ -82,10 +73,11 @@ OpenCode Zen 的工作方式與 opencode 中的任何其他供應商一樣。
| Claude Opus 4.1 | claude-opus-4-1 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
| Gemini 3 Pro | gemini-3-pro | `https://opencode.ai/zen/v1/models/gemini-3-pro` | `@ai-sdk/google` |
| Gemini 3 Flash | gemini-3-flash | `https://opencode.ai/zen/v1/models/gemini-3-flash` | `@ai-sdk/google` |
| MiniMax M2.5 | minimax-m2.5 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| MiniMax M2.5 Free | minimax-m2.5-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| MiniMax M2.1 | minimax-m2.1 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| MiniMax M2.1 Free | minimax-m2.1-free | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
| GLM 5 | glm-5 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| GLM 4.7 | glm-4.7 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| GLM 4.7 Free | glm-4.7-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| GLM 4.6 | glm-4.6 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| Kimi K2.5 | kimi-k2.5 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| Kimi K2.5 Free | kimi-k2.5-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
@@ -94,15 +86,13 @@ OpenCode Zen 的工作方式與 opencode 中的任何其他供應商一樣。
| Qwen3 Coder 480B | qwen3-coder | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
| Big Pickle | big-pickle | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
opencode 配置中的 [模型編號](/docs/config/#models)
使用格式 `opencode/<model-id>`。例如，對於 GPT 5.2 Codex，您將
在您的配置中使用 `opencode/gpt-5.2-codex`。
在 OpenCode 設定中，[模型 ID](/docs/config/#models) 使用 `opencode/<model-id>` 格式。例如，對於 GPT 5.2 Codex，你需要在設定中使用 `opencode/gpt-5.2-codex`。
---
### 模型
您可以從以下位置獲取可用模型及其元數據的完整列表：
你可以從以下位址取得可用模型及其中繼資料的完整列表：
```
https://opencode.ai/zen/v1/models
@@ -112,33 +102,34 @@ https://opencode.ai/zen/v1/models
## 定價
我們支援按用量付費模式。以下是**每 100 萬 Tokens 的價格**。
我們支援按量付費模式。以下是**每 100 萬 Token** 的價格。
| 模型 | 輸入 | 輸出 | 快取讀取 | 快取寫入 |
| --------------------------------- | ------ | ------ | -------- | -------- |
| Big Pickle | Free | Free | Free | - |
| MiniMax M2.1 Free | Free | Free | Free | - |
| -------------------------------- | ------ | ------ | -------- | -------- |
| Big Pickle | 免費 | 免費 | 免費 | - |
| MiniMax M2.5 Free | 免費 | 免費 | 免費 | - |
| MiniMax M2.5 | $0.30 | $1.20 | $0.06 | - |
| MiniMax M2.1 | $0.30 | $1.20 | $0.10 | - |
| GLM 4.7 Free | Free | Free | Free | - |
| GLM 5 | $1.00 | $3.20 | $0.20 | - |
| GLM 4.7 | $0.60 | $2.20 | $0.10 | - |
| GLM 4.6 | $0.60 | $2.20 | $0.10 | - |
| Kimi K2.5 Free | Free | Free | Free | - |
| Kimi K2.5 Free | 免費 | 免費 | 免費 | - |
| Kimi K2.5 | $0.60 | $3.00 | $0.08 | - |
| Kimi K2 Thinking | $0.40 | $2.50 | - | - |
| Kimi K2 | $0.40 | $2.50 | - | - |
| Qwen3 Coder 480B | $0.45 | $1.50 | - | - |
| Claude Sonnet 4.5 (≤ 200K tokens) | $3.00 | $15.00 | $0.30 | $3.75 |
| Claude Sonnet 4.5 (> 200K tokens) | $6.00 | $22.50 | $0.60 | $7.50 |
| Claude Sonnet 4 (≤ 200K tokens) | $3.00 | $15.00 | $0.30 | $3.75 |
| Claude Sonnet 4 (> 200K tokens) | $6.00 | $22.50 | $0.60 | $7.50 |
| Claude Sonnet 4.5 (≤ 200K Token) | $3.00 | $15.00 | $0.30 | $3.75 |
| Claude Sonnet 4.5 (> 200K Token) | $6.00 | $22.50 | $0.60 | $7.50 |
| Claude Sonnet 4 (≤ 200K Token) | $3.00 | $15.00 | $0.30 | $3.75 |
| Claude Sonnet 4 (> 200K Token) | $6.00 | $22.50 | $0.60 | $7.50 |
| Claude Haiku 4.5 | $1.00 | $5.00 | $0.10 | $1.25 |
| Claude Haiku 3.5 | $0.80 | $4.00 | $0.08 | $1.00 |
| Claude Opus 4.6 (≤ 200K tokens) | $5.00 | $25.00 | $0.50 | $6.25 |
| Claude Opus 4.6 (> 200K tokens) | $10.00 | $37.50 | $1.00 | $12.50 |
| Claude Opus 4.6 (≤ 200K Token) | $5.00 | $25.00 | $0.50 | $6.25 |
| Claude Opus 4.6 (> 200K Token) | $10.00 | $37.50 | $1.00 | $12.50 |
| Claude Opus 4.5 | $5.00 | $25.00 | $0.50 | $6.25 |
| Claude Opus 4.1 | $15.00 | $75.00 | $1.50 | $18.75 |
| Gemini 3 Pro (≤ 200K tokens) | $2.00 | $12.00 | $0.20 | - |
| Gemini 3 Pro (> 200K tokens) | $4.00 | $18.00 | $0.40 | - |
| Gemini 3 Pro (≤ 200K Token) | $2.00 | $12.00 | $0.20 | - |
| Gemini 3 Pro (> 200K Token) | $4.00 | $18.00 | $0.40 | - |
| Gemini 3 Flash | $0.50 | $3.00 | $0.05 | - |
| GPT 5.2 | $1.75 | $14.00 | $0.175 | - |
| GPT 5.2 Codex | $1.75 | $14.00 | $0.175 | - |
@@ -148,99 +139,90 @@ https://opencode.ai/zen/v1/models
| GPT 5.1 Codex Mini | $0.25 | $2.00 | $0.025 | - |
| GPT 5 | $1.07 | $8.50 | $0.107 | - |
| GPT 5 Codex | $1.07 | $8.50 | $0.107 | - |
| GPT 5 Nano | Free | Free | Free | - |
| GPT 5 Nano | 免費 | 免費 | 免費 | - |
您可能會在使用歷史記錄中注意到 _Claude Haiku 3.5_。這是一個 [低成本模型](/docs/config/#models)，用於生成工作階段標題。
你可能會在使用記錄中看到 _Claude Haiku 3.5_。這是一個[低成本模型](/docs/config/#models)，用於產生工作階段標題。
:::note
信用卡費用按成本轉嫁（4.4% + 每筆交易 0.30 美元）；除此之外我們不收取任何費用。
信用卡手續費按成本轉嫁（每筆交易 4.4% + $0.30）；除此之外我們不收取任何額外費用。
:::
免費模型：
免費模型說明：
- GLM 4.7 免費版在 opencode 上限時提供。團隊正在利用這段時間收集回饋並改進模型。
- Kimi K2.5 Free 在 opencode 上限時提供。團隊正在利用這段時間收集回饋並改進模型。
- MiniMax M2.1 免費版在 opencode 上限時提供。團隊正在利用這段時間收集回饋並改進模型。
- Big Pickle 是一個秘密模型，在 opencode 上限時免費。團隊正在利用這段時間收集回饋並改進模型。
- Kimi K2.5 Free 在 OpenCode 上限時免費提供。團隊正在利用這段時間收集回饋並改進模型。
- MiniMax M2.5 Free 在 OpenCode 上限時免費提供。團隊正在利用這段時間收集回饋並改進模型。
- Big Pickle 是一個隱身模型，在 OpenCode 上限時免費提供。團隊正在利用這段時間收集回饋並改進模型。
如果您有任何疑問，請<a href={email}>聯絡我們</a>。
如有任何疑問，請<a href={email}>聯絡我們</a>。
---
### 自動重新載入
### 自動儲值
如果您的餘額低於 5 美元，Zen 將自動加值 20 美元。
如果你的餘額低於 $5，Zen 將自動儲值 $20。
您可以更改自動加值金額。您還可以完全禁用自動重新載入。
你可以更改自動儲值的金額，也可以完全停用自動儲值功能。
---
### 每月限額
### 月度限額
您還可以為整個工作區和每個工作區設定每月使用限制
你的團隊的成員。
你還可以為整個工作區以及團隊中的每個成員設定月度使用限額。
例如，假設您將每月使用限額設定為 20 美元，Zen 將不會使用
一個月超過 20 美元。但如果你啟用了自動重新載入，Zen 可能會結束
如果您的餘額低於 5 美元，則向您收取超過 20 美元的費用。
例如，假設你將月度使用限額設為 $20，Zen 在一個月內的使用量將不會超過 $20。但如果你啟用了自動儲值，當餘額低於 $5 時，Zen 可能會向你收取超過 $20 的費用。
---
## 隱私
我們所有的模型都在美國託管。我們的供應商遵循零保留政策，不會將您的數據用於模型訓練，但以下情況除外：
我們所有的模型都託管在美國。我們的供應商遵循零保留政策，不會將你的資料用於模型訓練，但以下情況除外：
- Big Pickle：在免費期間，收集的數據可用於改進模型。
- GLM 4.7 免費：在免費期間，收集的數據可用於改進模型。
- Kimi K2.5 免費：在免費期間，收集的數據可用於改進模型。
- MiniMax M2.1 免費：在免費期間，收集的數據可用於改進模型。
- OpenAI API：根據 [OpenAI 的數據政策](https://platform.openai.com/docs/guides/your-data)，請求將保留 30 天。
- Anthropic API：根據 [Anthropic 的數據政策](https://docs.anthropic.com/en/docs/claude-code/data-usage)，請求將保留 30 天。
- Big Pickle：在免費期間，收集的資料可能會被用於改進模型。
- Kimi K2.5 Free：在免費期間，收集的資料可能會被用於改進模型。
- MiniMax M2.5 Free：在免費期間，收集的資料可能會被用於改進模型。
- OpenAI API：請求會根據 [OpenAI 資料政策](https://platform.openai.com/docs/guides/your-data)保留 30 天。
- Anthropic API：請求會根據 [Anthropic 資料政策](https://docs.anthropic.com/en/docs/claude-code/data-usage)保留 30 天。
---
## 對於團隊
## 團隊版
Zen 對團隊也很有效。您可以邀請隊友、分配角色、精選
您的團隊使用的模型等等。
Zen 也非常適合團隊使用。你可以邀請隊友、分配角色、管理團隊使用的模型等。
:::note
作為測試版的一部分，工作區目前對團隊免費。
作為測試版的一部分，工作區功能目前對團隊免費開放。
:::
作為測試版的一部分，管理工作區目前對團隊免費。我們將會
很快就會分享更多有關定價的細節。
作為測試版的一部分，管理工作區目前對團隊免費。我們將很快公布更多定價詳情。
---
### 角色
您可以邀請團隊成員到您的工作區並分配角色：
你可以邀請團隊成員加入你的工作區並分配角色：
- **管理員**：管理模型、成員、API 金鑰和計費
- **管理員**：管理模型、成員、API 金鑰和帳單
- **成員**：僅管理自己的 API 金鑰
管理員還可以為每個成員設定每月支出限額，以控制成本。
管理員還可以為每個成員設定月度支出限額，以控制成本。
---
### 模型存取
管理員可以啟用或禁用工作區的特定模型。對禁用模型發出的請求將返回錯誤。
管理員可以啟用或停用工作區中的特定模型。對已停用模型發出的請求將回傳錯誤。
這對於您想要禁用以下模型的情況很有用：
收集數據。
這在你想要停用某個會收集資料的模型時非常有用。
---
### 帶上你自己的金鑰
### 自帶金鑰
您可以使用自己的 OpenAI 或 Anthropic API 金鑰，同時仍然存取 Zen 中的其他模型。
你可以使用自己的 OpenAI 或 Anthropic API 金鑰，同時仍然可以存取 Zen 中的其他模型。
當您使用自己的金鑰時，Tokens 將由供應商直接計費，而不是由 Zen。
當你使用自己的金鑰時，Token 費用由供應商直接計費，而非透過 Zen 計費。
例如，您的組織可能已經擁有 OpenAI 或 Anthropic 的金鑰
你想使用它而不是 Zen 提供的。
例如，你的組織可能已經擁有 OpenAI 或 Anthropic 的金鑰，你希望使用它們而不是 Zen 提供的金鑰。
---
@@ -248,7 +230,7 @@ Zen 對團隊也很有效。您可以邀請隊友、分配角色、精選
我們建立 OpenCode Zen 的目的是：
1. **設定基準**編碼代理的最佳模型/供應商。
2. 可以使用**最高品質**選項，而不是降低性能或轉向更便宜的供應商。
3. 透過按成本價銷售來傳遞任何**價格下跌**；所以唯一的加價就是支付我們的處理費。
4. 透過允許您將其與任何其他編碼代理一起使用，**無鎖定**。並且始終允許您將任何其他供應商與 opencode 一起使用。
1. 為編碼代理**基準測試**最佳的模型和供應商組合。
2. 提供**最高品質**的選項，不降低效能或路由到更廉價的供應商。
3. 以成本價銷售來傳遞任何**降價優惠**；唯一的加價僅用於覆蓋我們的處理費用。
4. **無鎖定**，允許你將其與任何其他編碼代理配合使用，同時也始終允許你在 OpenCode 中使用任何其他供應商。