fix: logo 右半部分从 CODING 改为 CODE
去掉难以正确渲染的 N 和 G 字母，右半部分简化为 CODE（4 字母）， 与左半部分 AIR 组合为 AIR CODE。
This commit is contained in:
airlongdian
156
packages/web/src/content/docs/zh-cn/acp.mdx
Normal file
156
packages/web/src/content/docs/zh-cn/acp.mdx
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
title: ACP 支持
|
||||
description: 在任何兼容 ACP 的编辑器中使用 OpenCode。
|
||||
---
|
||||
|
||||
OpenCode 支持 [Agent Client Protocol](https://agentclientprotocol.com)（ACP），允许你直接在兼容的编辑器和 IDE 中使用它。
|
||||
|
||||
:::tip
|
||||
有关支持 ACP 的编辑器和工具列表，请查看 [ACP 进展报告](https://zed.dev/blog/acp-progress-report#available-now)。
|
||||
:::
|
||||
|
||||
ACP 是一个开放协议，用于标准化代码编辑器与 AI 编码代理之间的通信。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
要通过 ACP 使用 OpenCode，请在编辑器中配置运行 `opencode acp` 命令。
|
||||
|
||||
该命令会将 OpenCode 作为兼容 ACP 的子进程启动，通过 stdio 上的 JSON-RPC 与编辑器进行通信。
|
||||
|
||||
以下是支持 ACP 的常用编辑器的配置示例。
|
||||
|
||||
---
|
||||
|
||||
### Zed
|
||||
|
||||
添加到你的 [Zed](https://zed.dev) 配置文件（`~/.config/zed/settings.json`）中：
|
||||
|
||||
```json title="~/.config/zed/settings.json"
|
||||
{
|
||||
"agent_servers": {
|
||||
"OpenCode": {
|
||||
"command": "opencode",
|
||||
"args": ["acp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
打开方式：在**命令面板**中执行 `agent: new thread` 操作。
|
||||
|
||||
你也可以通过编辑 `keymap.json` 来绑定键盘快捷键：
|
||||
|
||||
```json title="keymap.json"
|
||||
[
|
||||
{
|
||||
"bindings": {
|
||||
"cmd-alt-o": [
|
||||
"agent::NewExternalAgentThread",
|
||||
{
|
||||
"agent": {
|
||||
"custom": {
|
||||
"name": "OpenCode",
|
||||
"command": {
|
||||
"command": "opencode",
|
||||
"args": ["acp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### JetBrains IDEs
|
||||
|
||||
根据[文档](https://www.jetbrains.com/help/ai-assistant/acp.html)，将以下内容添加到你的 [JetBrains IDE](https://www.jetbrains.com/) 的 acp.json 中：
|
||||
|
||||
```json title="acp.json"
|
||||
{
|
||||
"agent_servers": {
|
||||
"OpenCode": {
|
||||
"command": "/absolute/path/bin/opencode",
|
||||
"args": ["acp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
打开方式：在 AI Chat 代理选择器中选择新的 'OpenCode' 代理。
|
||||
|
||||
---
|
||||
|
||||
### Avante.nvim
|
||||
|
||||
添加到你的 [Avante.nvim](https://github.com/yetone/avante.nvim) 配置中：
|
||||
|
||||
```lua
|
||||
{
|
||||
acp_providers = {
|
||||
["opencode"] = {
|
||||
command = "opencode",
|
||||
args = { "acp" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果需要传递环境变量：
|
||||
|
||||
```lua {6-8}
|
||||
{
|
||||
acp_providers = {
|
||||
["opencode"] = {
|
||||
command = "opencode",
|
||||
args = { "acp" },
|
||||
env = {
|
||||
OPENCODE_API_KEY = os.getenv("OPENCODE_API_KEY")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CodeCompanion.nvim
|
||||
|
||||
要在 [CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim) 中将 OpenCode 用作 ACP 代理，请将以下内容添加到你的 Neovim 配置中：
|
||||
|
||||
```lua
|
||||
require("codecompanion").setup({
|
||||
interactions = {
|
||||
chat = {
|
||||
adapter = {
|
||||
name = "opencode",
|
||||
model = "claude-sonnet-4",
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
此配置将 CodeCompanion 设置为使用 OpenCode 作为聊天的 ACP 代理。
|
||||
|
||||
如果需要传递环境变量（如 `OPENCODE_API_KEY`），请参阅 CodeCompanion.nvim 文档中的[配置适配器：环境变量](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key)了解详细信息。
|
||||
|
||||
## 支持
|
||||
|
||||
OpenCode 通过 ACP 使用时与在终端中使用的效果完全一致。所有功能均受支持：
|
||||
|
||||
:::note
|
||||
部分内置斜杠命令（如 `/undo` 和 `/redo`）目前暂不支持。
|
||||
:::
|
||||
|
||||
- 内置工具（文件操作、终端命令等）
|
||||
- 自定义工具和斜杠命令
|
||||
- 在 OpenCode 配置中配置的 MCP 服务器
|
||||
- 来自 `AGENTS.md` 的项目级规则
|
||||
- 自定义格式化工具和代码检查工具
|
||||
- 代理和权限系统
|
||||
754
packages/web/src/content/docs/zh-cn/agents.mdx
Normal file
754
packages/web/src/content/docs/zh-cn/agents.mdx
Normal file
@@ -0,0 +1,754 @@
|
||||
---
|
||||
title: 代理
|
||||
description: 配置和使用专门的代理。
|
||||
---
|
||||
|
||||
代理是专门的 AI 助手，可以针对特定任务和工作流程进行配置。它们允许您创建具有自定义提示词、模型和工具访问权限的专用工具。
|
||||
|
||||
:::tip
|
||||
使用 Plan 代理来分析代码和审查建议，而不会进行任何代码更改。
|
||||
:::
|
||||
|
||||
您可以在会话期间切换代理，或使用 `@` 提及来调用它们。
|
||||
|
||||
---
|
||||
|
||||
## 类型
|
||||
|
||||
OpenCode 中有两种类型的代理：主代理和子代理。
|
||||
|
||||
---
|
||||
|
||||
### 主代理
|
||||
|
||||
主代理是您直接交互的主要助手。您可以使用 **Tab** 键或配置的 `switch_agent` 快捷键来循环切换它们。这些代理处理您的主要对话。工具访问通过权限进行配置——例如，Build 启用了所有工具，而 Plan 则受到限制。
|
||||
|
||||
:::tip
|
||||
您可以在会话期间使用 **Tab** 键在主代理之间切换。
|
||||
:::
|
||||
|
||||
OpenCode 内置了两个主代理：**Build** 和 **Plan**。我们将在下面介绍它们。
|
||||
|
||||
---
|
||||
|
||||
### 子代理
|
||||
|
||||
子代理是主代理可以调用来执行特定任务的专业助手。您也可以通过在消息中 **@ 提及**它们来手动调用。
|
||||
|
||||
OpenCode 内置了三个子代理：**General**、**Explore** 和 **Scout**。我们将在下面介绍它们。
|
||||
|
||||
---
|
||||
|
||||
## 内置代理
|
||||
|
||||
OpenCode 内置了两个主代理和三个子代理。
|
||||
|
||||
---
|
||||
|
||||
### 使用 Build
|
||||
|
||||
_模式_：`primary`
|
||||
|
||||
Build 是启用了所有工具的**默认**主代理。这是用于需要完全访问文件操作和系统命令的开发工作的标准代理。
|
||||
|
||||
---
|
||||
|
||||
### 使用 Plan
|
||||
|
||||
_模式_：`primary`
|
||||
|
||||
一个专为规划和分析设计的受限代理。我们使用权限系统来为您提供更多控制权，并防止意外更改。
|
||||
默认情况下，以下所有项均设置为 `ask`：
|
||||
|
||||
- `file edits`：所有写入、补丁和编辑
|
||||
- `bash`：所有 bash 命令
|
||||
|
||||
当您希望 LLM 分析代码、建议更改或创建计划，而不对代码库进行任何实际修改时，此代理非常有用。
|
||||
|
||||
---
|
||||
|
||||
### 使用 General
|
||||
|
||||
_模式_：`subagent`
|
||||
|
||||
一个用于研究复杂问题和执行多步骤任务的通用代理。拥有完整的工具访问权限（todo 除外），因此可以在需要时修改文件。可用于并行运行多个工作单元。
|
||||
|
||||
---
|
||||
|
||||
### 使用 Explore
|
||||
|
||||
_模式_：`subagent`
|
||||
|
||||
一个用于探索代码库的快速只读代理。无法修改文件。当您需要按模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时，请使用此代理。
|
||||
|
||||
---
|
||||
|
||||
### 使用 Scout
|
||||
|
||||
_模式_：`subagent`
|
||||
|
||||
一个用于外部文档和依赖研究的只读代理。当您需要将某个依赖仓库克隆到 OpenCode 的托管缓存中、检查库的源代码，或在不修改工作区的情况下将本地代码与 upstream 实现进行交叉对照时，请使用此代理。
|
||||
|
||||
---
|
||||
|
||||
### 使用 Compaction
|
||||
|
||||
_模式_：`primary`
|
||||
|
||||
隐藏的系统代理，将长上下文压缩为较小的摘要。它会在需要时自动运行，且无法在 UI 中选择。
|
||||
|
||||
---
|
||||
|
||||
### 使用 Title
|
||||
|
||||
_模式_：`primary`
|
||||
|
||||
隐藏的系统代理，用于生成简短的会话标题。它会自动运行，且无法在 UI 中选择。
|
||||
|
||||
---
|
||||
|
||||
### 使用 Summary
|
||||
|
||||
_模式_：`primary`
|
||||
|
||||
隐藏的系统代理，用于创建会话摘要。它会自动运行，且无法在 UI 中选择。
|
||||
|
||||
---
|
||||
|
||||
## 用法
|
||||
|
||||
1. 对于主代理，在会话期间使用 **Tab** 键循环切换。您也可以使用配置的 `switch_agent` 快捷键。
|
||||
|
||||
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 ← ... ← 父会话
|
||||
|
||||
这使您可以在主对话和专门的子代理工作之间无缝切换。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
您可以自定义内置代理或通过配置创建自己的代理。代理可以通过两种方式进行配置：
|
||||
|
||||
---
|
||||
|
||||
### JSON
|
||||
|
||||
在 `opencode.json` 配置文件中配置代理：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"agent": {
|
||||
"build": {
|
||||
"mode": "primary",
|
||||
"model": "anthropic/claude-sonnet-4-20250514",
|
||||
"prompt": "{file:./prompts/build.txt}",
|
||||
"tools": {
|
||||
"write": true,
|
||||
"edit": true,
|
||||
"bash": true
|
||||
}
|
||||
},
|
||||
"plan": {
|
||||
"mode": "primary",
|
||||
"model": "anthropic/claude-haiku-4-20250514",
|
||||
"tools": {
|
||||
"write": false,
|
||||
"edit": false,
|
||||
"bash": false
|
||||
}
|
||||
},
|
||||
"code-reviewer": {
|
||||
"description": "Reviews code for best practices and potential issues",
|
||||
"mode": "subagent",
|
||||
"model": "anthropic/claude-sonnet-4-20250514",
|
||||
"prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
|
||||
"tools": {
|
||||
"write": false,
|
||||
"edit": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Markdown
|
||||
|
||||
您还可以使用 Markdown 文件定义代理。将它们放在：
|
||||
|
||||
- 全局：`~/.config/opencode/agents/`
|
||||
- 项目级：`.opencode/agents/`
|
||||
|
||||
```markdown title="~/.config/opencode/agents/review.md"
|
||||
---
|
||||
description: Reviews code for quality and best practices
|
||||
mode: subagent
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
temperature: 0.1
|
||||
tools:
|
||||
write: false
|
||||
edit: false
|
||||
bash: false
|
||||
---
|
||||
|
||||
You are in code review mode. Focus on:
|
||||
|
||||
- Code quality and best practices
|
||||
- Potential bugs and edge cases
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
|
||||
Provide constructive feedback without making direct changes.
|
||||
```
|
||||
|
||||
Markdown 文件名即为代理名称。例如，`review.md` 会创建一个名为 `review` 的代理。
|
||||
|
||||
---
|
||||
|
||||
## 选项
|
||||
|
||||
让我们详细了解这些配置选项。
|
||||
|
||||
---
|
||||
|
||||
### 描述
|
||||
|
||||
使用 `description` 选项提供代理的功能及使用场景的简要描述。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"review": {
|
||||
"description": "Reviews code for best practices and potential issues"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这是一个**必需的**配置选项。
|
||||
|
||||
---
|
||||
|
||||
### 温度
|
||||
|
||||
使用 `temperature` 配置控制 LLM 响应的随机性和创造力。
|
||||
|
||||
较低的值使响应更加集中和确定，而较高的值则增加创造力和多样性。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"plan": {
|
||||
"temperature": 0.1
|
||||
},
|
||||
"creative": {
|
||||
"temperature": 0.8
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
温度值通常范围为 0.0 到 1.0：
|
||||
|
||||
- **0.0-0.2**：非常集中和确定性的响应，适合代码分析和规划
|
||||
- **0.3-0.5**：平衡的响应，兼顾一定创造力，适合一般开发任务
|
||||
- **0.6-1.0**：更有创造力和多样性的响应，适合头脑风暴和探索
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"analyze": {
|
||||
"temperature": 0.1,
|
||||
"prompt": "{file:./prompts/analysis.txt}"
|
||||
},
|
||||
"build": {
|
||||
"temperature": 0.3
|
||||
},
|
||||
"brainstorm": {
|
||||
"temperature": 0.7,
|
||||
"prompt": "{file:./prompts/creative.txt}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果未指定温度，OpenCode 将使用模型特定的默认值；大多数模型通常为 0，Qwen 模型为 0.55。
|
||||
|
||||
---
|
||||
|
||||
### 最大步数
|
||||
|
||||
控制代理在被强制以纯文本响应之前可以执行的最大代理迭代次数。这允许希望控制成本的用户对代理操作设置限制。
|
||||
|
||||
如果未设置此选项，代理将持续迭代，直到模型选择停止或用户中断会话。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"quick-thinker": {
|
||||
"description": "Fast reasoning with limited iterations",
|
||||
"prompt": "You are a quick thinker. Solve problems with minimal steps.",
|
||||
"steps": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
当达到限制时，代理会收到一个特殊的系统提示词，指示其回复工作摘要和建议的剩余任务。
|
||||
|
||||
:::caution
|
||||
旧版 `maxSteps` 字段已弃用。请改用 `steps`。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### 禁用
|
||||
|
||||
设置为 `true` 以禁用代理。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"review": {
|
||||
"disable": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 提示词
|
||||
|
||||
使用 `prompt` 配置为代理指定自定义系统提示词文件。提示词文件应包含针对代理用途的具体指令。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"review": {
|
||||
"prompt": "{file:./prompts/code-review.txt}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
此路径相对于配置文件所在位置。因此它同时适用于全局 OpenCode 配置和项目级配置。
|
||||
|
||||
---
|
||||
|
||||
### 模型
|
||||
|
||||
使用 `model` 配置为代理覆盖模型。适用于针对不同任务使用不同的优化模型。例如，用更快的模型进行规划，用更强大的模型进行实现。
|
||||
|
||||
:::tip
|
||||
如果您不指定模型，主代理将使用[全局配置的模型](/docs/config#models)，而子代理将使用调用它的主代理所使用的模型。
|
||||
:::
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"plan": {
|
||||
"model": "anthropic/claude-haiku-4-20250514"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
OpenCode 配置中的模型 ID 使用 `provider/model-id` 格式。例如，如果您使用 [OpenCode Zen](/docs/zen)，则可以使用 `opencode/gpt-5.1-codex` 来表示 GPT 5.1 Codex。
|
||||
|
||||
---
|
||||
|
||||
### 工具
|
||||
|
||||
使用 `tools` 配置控制代理中可用的工具。您可以通过将特定工具设置为 `true` 或 `false` 来启用或禁用它们。
|
||||
|
||||
```json title="opencode.json" {3-6,9-12}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"write": true,
|
||||
"bash": true
|
||||
},
|
||||
"agent": {
|
||||
"plan": {
|
||||
"tools": {
|
||||
"write": false,
|
||||
"bash": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
代理级配置会覆盖全局配置。
|
||||
:::
|
||||
|
||||
您还可以使用通配符同时控制多个工具。例如，要禁用 MCP 服务器中的所有工具：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"agent": {
|
||||
"readonly": {
|
||||
"tools": {
|
||||
"mymcp_*": false,
|
||||
"write": false,
|
||||
"edit": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[了解更多关于工具的信息](/docs/tools)。
|
||||
|
||||
---
|
||||
|
||||
### 权限
|
||||
|
||||
您可以配置权限来管理代理可以执行的操作。目前，`edit`、`bash` 和 `webfetch` 工具的权限可以配置为：
|
||||
|
||||
- `"ask"` — 运行工具前提示审批
|
||||
- `"allow"` — 允许所有操作，无需审批
|
||||
- `"deny"` — 禁用该工具
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "deny"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
您可以按代理覆盖这些权限。
|
||||
|
||||
```json title="opencode.json" {3-5,8-10}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "deny"
|
||||
},
|
||||
"agent": {
|
||||
"build": {
|
||||
"permission": {
|
||||
"edit": "ask"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
您还可以在 Markdown 代理中设置权限。
|
||||
|
||||
```markdown title="~/.config/opencode/agents/review.md"
|
||||
---
|
||||
description: Code review without edits
|
||||
mode: subagent
|
||||
permission:
|
||||
edit: deny
|
||||
bash:
|
||||
"*": ask
|
||||
"git diff": allow
|
||||
"git log*": allow
|
||||
"grep *": allow
|
||||
webfetch: deny
|
||||
---
|
||||
|
||||
Only analyze code and suggest changes.
|
||||
```
|
||||
|
||||
您可以为特定的 bash 命令设置权限。
|
||||
|
||||
```json title="opencode.json" {7}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"agent": {
|
||||
"build": {
|
||||
"permission": {
|
||||
"bash": {
|
||||
"git push": "ask",
|
||||
"grep *": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这可以使用 glob 模式。
|
||||
|
||||
```json title="opencode.json" {7}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"agent": {
|
||||
"build": {
|
||||
"permission": {
|
||||
"bash": {
|
||||
"git *": "ask"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
您还可以使用 `*` 通配符来管理所有命令的权限。
|
||||
由于最后匹配的规则优先，请将 `*` 通配符放在前面，将具体规则放在后面。
|
||||
|
||||
```json title="opencode.json" {8}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"agent": {
|
||||
"build": {
|
||||
"permission": {
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git status *": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[了解更多关于权限的信息](/docs/permissions)。
|
||||
|
||||
---
|
||||
|
||||
### 模式
|
||||
|
||||
使用 `mode` 配置控制代理的模式。`mode` 选项用于确定代理的使用方式。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"review": {
|
||||
"mode": "subagent"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`mode` 选项可以设置为 `primary`、`subagent` 或 `all`。如果未指定 `mode`，则默认为 `all`。
|
||||
|
||||
---
|
||||
|
||||
### 隐藏
|
||||
|
||||
使用 `hidden: true` 将子代理从 `@` 自动补全菜单中隐藏。适用于只应由其他代理通过 Task 工具以编程方式调用的内部子代理。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"internal-helper": {
|
||||
"mode": "subagent",
|
||||
"hidden": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这仅影响自动补全菜单中的用户可见性。如果权限允许，模型仍然可以通过 Task 工具调用隐藏的代理。
|
||||
|
||||
:::note
|
||||
仅适用于 `mode: subagent` 的代理。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### 任务权限
|
||||
|
||||
使用 `permission.task` 控制代理可以通过 Task 工具调用哪些子代理。使用 glob 模式进行灵活匹配。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"orchestrator": {
|
||||
"mode": "primary",
|
||||
"permission": {
|
||||
"task": {
|
||||
"*": "deny",
|
||||
"orchestrator-*": "allow",
|
||||
"code-reviewer": "ask"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
当设置为 `deny` 时，子代理将从 Task 工具描述中完全移除，因此模型不会尝试调用它。
|
||||
|
||||
:::tip
|
||||
规则按顺序评估，**最后匹配的规则优先**。在上面的示例中，`orchestrator-planner` 同时匹配 `*`（deny）和 `orchestrator-*`（allow），但由于 `orchestrator-*` 在 `*` 之后，所以结果为 `allow`。
|
||||
:::
|
||||
|
||||
:::tip
|
||||
用户始终可以通过 `@` 自动补全菜单直接调用任何子代理，即使代理的任务权限会拒绝它。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### 颜色
|
||||
|
||||
使用 `color` 选项自定义代理在 UI 中的视觉外观。这会影响代理在界面中的显示方式。
|
||||
|
||||
使用有效的十六进制颜色（例如 `#FF5733`）或主题颜色：`primary`、`secondary`、`accent`、`success`、`warning`、`error`、`info`。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"creative": {
|
||||
"color": "#ff6b6b"
|
||||
},
|
||||
"code-reviewer": {
|
||||
"color": "accent"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Top P
|
||||
|
||||
使用 `top_p` 选项控制响应多样性。这是控制随机性的温度替代方案。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"brainstorm": {
|
||||
"top_p": 0.9
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
值范围从 0.0 到 1.0。较低的值更加集中，较高的值更加多样化。
|
||||
|
||||
---
|
||||
|
||||
### 其他选项
|
||||
|
||||
您在代理配置中指定的任何其他选项都将作为模型选项**直接传递**给提供商。这允许您使用提供商特定的功能和参数。
|
||||
|
||||
例如，使用 OpenAI 的推理模型时，您可以控制推理力度：
|
||||
|
||||
```json title="opencode.json" {6,7}
|
||||
{
|
||||
"agent": {
|
||||
"deep-thinker": {
|
||||
"description": "Agent that uses high reasoning effort for complex problems",
|
||||
"model": "openai/gpt-5",
|
||||
"reasoningEffort": "high",
|
||||
"textVerbosity": "low"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这些附加选项是模型和提供商特定的。请查阅您的提供商文档以获取可用参数。
|
||||
|
||||
:::tip
|
||||
运行 `opencode models` 查看可用模型列表。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 创建代理
|
||||
|
||||
您可以使用以下命令创建新代理：
|
||||
|
||||
```bash
|
||||
opencode agent create
|
||||
```
|
||||
|
||||
此交互式命令将：
|
||||
|
||||
1. 询问代理的保存位置——全局或项目级。
|
||||
2. 描述代理应该做什么。
|
||||
3. 生成合适的系统提示词和标识符。
|
||||
4. 让您选择代理可以访问哪些工具。
|
||||
5. 最后，创建一个包含代理配置的 Markdown 文件。
|
||||
|
||||
---
|
||||
|
||||
## 使用场景
|
||||
|
||||
以下是不同代理的一些常见使用场景。
|
||||
|
||||
- **Build 代理**：启用所有工具的完整开发工作
|
||||
- **Plan 代理**：分析和规划，不进行任何更改
|
||||
- **Review 代理**：具有只读访问权限和文档工具的代码审查
|
||||
- **Debug 代理**：专注于问题排查，启用 bash 和读取工具
|
||||
- **Docs 代理**：文档编写，具有文件操作但不使用系统命令
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
以下是一些您可能会觉得有用的示例代理。
|
||||
|
||||
:::tip
|
||||
您有想要分享的代理吗？[提交 PR](https://github.com/anomalyco/opencode)。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### 文档代理
|
||||
|
||||
```markdown title="~/.config/opencode/agents/docs-writer.md"
|
||||
---
|
||||
description: Writes and maintains project documentation
|
||||
mode: subagent
|
||||
tools:
|
||||
bash: false
|
||||
---
|
||||
|
||||
You are a technical writer. Create clear, comprehensive documentation.
|
||||
|
||||
Focus on:
|
||||
|
||||
- Clear explanations
|
||||
- Proper structure
|
||||
- Code examples
|
||||
- User-friendly language
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 安全审计代理
|
||||
|
||||
```markdown title="~/.config/opencode/agents/security-auditor.md"
|
||||
---
|
||||
description: Performs security audits and identifies vulnerabilities
|
||||
mode: subagent
|
||||
tools:
|
||||
write: false
|
||||
edit: false
|
||||
---
|
||||
|
||||
You are a security expert. Focus on identifying potential security issues.
|
||||
|
||||
Look for:
|
||||
|
||||
- Input validation vulnerabilities
|
||||
- Authentication and authorization flaws
|
||||
- Data exposure risks
|
||||
- Dependency vulnerabilities
|
||||
- Configuration security issues
|
||||
```
|
||||
617
packages/web/src/content/docs/zh-cn/cli.mdx
Normal file
617
packages/web/src/content/docs/zh-cn/cli.mdx
Normal file
@@ -0,0 +1,617 @@
|
||||
---
|
||||
title: CLI
|
||||
description: OpenCode CLI 选项和命令。
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from "@astrojs/starlight/components"
|
||||
|
||||
OpenCode CLI 在不带任何参数运行时，默认启动 [TUI](/docs/tui)。
|
||||
|
||||
```bash
|
||||
opencode
|
||||
```
|
||||
|
||||
但它也接受本页面中记录的命令，使您可以通过编程方式与 OpenCode 进行交互。
|
||||
|
||||
```bash
|
||||
opencode run "Explain how closures work in JavaScript"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### tui
|
||||
|
||||
启动 OpenCode 终端用户界面。
|
||||
|
||||
```bash
|
||||
opencode [project]
|
||||
```
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 简写 | 描述 |
|
||||
| ---------------------------------------- | ---- | --------------------------------------------------------- |
|
||||
| <nobr><code>{"--continue"}</code></nobr> | `-c` | 继续上一个会话 |
|
||||
| <nobr><code>{"--session"}</code></nobr> | `-s` | 要继续的会话 ID |
|
||||
| <nobr><code>{"--fork"}</code></nobr> | | 继续时分叉会话（与 `--continue` 或 `--session` 配合使用） |
|
||||
| <nobr><code>{"--prompt"}</code></nobr> | | 要使用的提示词 |
|
||||
| <nobr><code>{"--model"}</code></nobr> | `-m` | 要使用的模型，格式为 provider/model |
|
||||
| <nobr><code>{"--agent"}</code></nobr> | | 要使用的代理 |
|
||||
| <nobr><code>{"--port"}</code></nobr> | | 监听端口 |
|
||||
| <nobr><code>{"--hostname"}</code></nobr> | | 监听主机名 |
|
||||
|
||||
---
|
||||
|
||||
## 命令
|
||||
|
||||
OpenCode CLI 还提供以下命令。
|
||||
|
||||
---
|
||||
|
||||
### agent
|
||||
|
||||
管理 OpenCode 的代理。
|
||||
|
||||
```bash
|
||||
opencode agent [command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### attach
|
||||
|
||||
将终端连接到已通过 `serve` 或 `web` 命令启动的 OpenCode 后端服务器。
|
||||
|
||||
```bash
|
||||
opencode attach [url]
|
||||
```
|
||||
|
||||
这允许将 TUI 与远程 OpenCode 后端配合使用。例如：
|
||||
|
||||
```bash
|
||||
# Start the backend server for web/mobile access
|
||||
opencode web --port 4096 --hostname 0.0.0.0
|
||||
|
||||
# In another terminal, attach the TUI to the running backend
|
||||
opencode attach http://10.20.30.40:4096
|
||||
```
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 简写 | 描述 |
|
||||
| ---------------------------------------- | ---- | ------------------------------------------------------------------- |
|
||||
| <nobr><code>{"--dir"}</code></nobr> | | 启动 TUI 的工作目录 |
|
||||
| <nobr><code>{"--continue"}</code></nobr> | `-c` | 继续上一个会话 |
|
||||
| <nobr><code>{"--session"}</code></nobr> | `-s` | 要继续的会话 ID |
|
||||
| <nobr><code>{"--fork"}</code></nobr> | | 继续时派生会话（与 `--continue` 或 `--session` 一起使用） |
|
||||
| <nobr><code>{"--password"}</code></nobr> | `-p` | 基本认证密码（默认使用 `OPENCODE_SERVER_PASSWORD`） |
|
||||
| <nobr><code>{"--username"}</code></nobr> | `-u` | 基本认证用户名（默认使用 `OPENCODE_SERVER_USERNAME` 或 `opencode`） |
|
||||
|
||||
---
|
||||
|
||||
#### create
|
||||
|
||||
使用自定义配置创建新的代理。
|
||||
|
||||
```bash
|
||||
opencode agent create
|
||||
```
|
||||
|
||||
此命令将引导您使用自定义系统提示词和工具配置来创建新的代理。
|
||||
|
||||
---
|
||||
|
||||
#### list
|
||||
|
||||
列出所有可用的代理。
|
||||
|
||||
```bash
|
||||
opencode agent list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### auth
|
||||
|
||||
管理提供商的凭据和登录信息的命令。
|
||||
|
||||
```bash
|
||||
opencode auth [command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### login
|
||||
|
||||
OpenCode 基于 [Models.dev](https://models.dev) 的提供商列表运行，因此您可以使用 `opencode auth login` 为任何想要使用的提供商配置 API 密钥。密钥存储在 `~/.local/share/opencode/auth.json` 中。
|
||||
|
||||
```bash
|
||||
opencode auth login
|
||||
```
|
||||
|
||||
OpenCode 启动时会从凭据文件加载提供商信息，同时也会加载环境变量或项目中 `.env` 文件中定义的密钥。
|
||||
|
||||
---
|
||||
|
||||
#### list
|
||||
|
||||
列出凭据文件中存储的所有已认证提供商。
|
||||
|
||||
```bash
|
||||
opencode auth list
|
||||
```
|
||||
|
||||
或使用简写版本。
|
||||
|
||||
```bash
|
||||
opencode auth ls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### logout
|
||||
|
||||
从凭据文件中清除提供商信息以完成登出。
|
||||
|
||||
```bash
|
||||
opencode auth logout
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### github
|
||||
|
||||
管理用于仓库自动化的 GitHub 代理。
|
||||
|
||||
```bash
|
||||
opencode github [command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### install
|
||||
|
||||
在您的仓库中安装 GitHub 代理。
|
||||
|
||||
```bash
|
||||
opencode github install
|
||||
```
|
||||
|
||||
此命令会设置必要的 GitHub Actions 工作流并引导您完成配置过程。[了解更多](/docs/github)。
|
||||
|
||||
---
|
||||
|
||||
#### run
|
||||
|
||||
运行 GitHub 代理。通常在 GitHub Actions 中使用。
|
||||
|
||||
```bash
|
||||
opencode github run
|
||||
```
|
||||
|
||||
##### 标志
|
||||
|
||||
| 标志 | 描述 |
|
||||
| ------------------------------------- | ------------------------------ |
|
||||
| <nobr><code>{"--event"}</code></nobr> | 用于运行代理的 GitHub 模拟事件 |
|
||||
| <nobr><code>{"--token"}</code></nobr> | GitHub 个人访问令牌 |
|
||||
|
||||
---
|
||||
|
||||
### mcp
|
||||
|
||||
管理 Model Context Protocol 服务器。
|
||||
|
||||
```bash
|
||||
opencode mcp [command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### add
|
||||
|
||||
将 MCP 服务器添加到您的配置中。
|
||||
|
||||
```bash
|
||||
opencode mcp add
|
||||
```
|
||||
|
||||
此命令将引导您添加本地或远程 MCP 服务器。
|
||||
|
||||
---
|
||||
|
||||
#### list
|
||||
|
||||
列出所有已配置的 MCP 服务器及其连接状态。
|
||||
|
||||
```bash
|
||||
opencode mcp list
|
||||
```
|
||||
|
||||
或使用简写版本。
|
||||
|
||||
```bash
|
||||
opencode mcp ls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### auth
|
||||
|
||||
对支持 OAuth 的 MCP 服务器进行认证。
|
||||
|
||||
```bash
|
||||
opencode mcp auth [name]
|
||||
```
|
||||
|
||||
如果您不提供服务器名称，系统将提示您从可用的支持 OAuth 的服务器中进行选择。
|
||||
|
||||
您还可以列出支持 OAuth 的服务器及其认证状态。
|
||||
|
||||
```bash
|
||||
opencode mcp auth list
|
||||
```
|
||||
|
||||
或使用简写版本。
|
||||
|
||||
```bash
|
||||
opencode mcp auth ls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### logout
|
||||
|
||||
移除 MCP 服务器的 OAuth 凭据。
|
||||
|
||||
```bash
|
||||
opencode mcp logout [name]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### debug
|
||||
|
||||
调试 MCP 服务器的 OAuth 连接问题。
|
||||
|
||||
```bash
|
||||
opencode mcp debug <name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### models
|
||||
|
||||
列出已配置提供商的所有可用模型。
|
||||
|
||||
```bash
|
||||
opencode models [provider]
|
||||
```
|
||||
|
||||
此命令以 `provider/model` 的格式显示所有已配置提供商中可用的模型。
|
||||
|
||||
这对于确定在[配置文件](/docs/config/)中使用的确切模型名称非常有用。
|
||||
|
||||
您可以选择传入提供商 ID 来按提供商筛选模型。
|
||||
|
||||
```bash
|
||||
opencode models anthropic
|
||||
```
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 描述 |
|
||||
| --------------------------------------- | ---------------------------------------- |
|
||||
| <nobr><code>{"--refresh"}</code></nobr> | 从 models.dev 刷新模型缓存 |
|
||||
| <nobr><code>{"--verbose"}</code></nobr> | 使用更详细的模型输出（包含费用等元数据） |
|
||||
|
||||
使用 `--refresh` 标志可以更新缓存的模型列表。当提供商新增了模型并且您希望在 OpenCode 中看到它们时，此功能非常有用。
|
||||
|
||||
```bash
|
||||
opencode models --refresh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### run
|
||||
|
||||
以非交互模式运行 OpenCode，直接传入提示词。
|
||||
|
||||
```bash
|
||||
opencode run [message..]
|
||||
```
|
||||
|
||||
这对于脚本编写、自动化或无需启动完整 TUI 即可快速获取答案的场景非常有用。例如：
|
||||
|
||||
```bash "opencode run"
|
||||
opencode run Explain the use of context in Go
|
||||
```
|
||||
|
||||
您还可以连接到正在运行的 `opencode serve` 实例，以避免每次运行时 MCP 服务器的冷启动时间：
|
||||
|
||||
```bash
|
||||
# Start a headless server in one terminal
|
||||
opencode serve
|
||||
|
||||
# In another terminal, run commands that attach to it
|
||||
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
|
||||
```
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 简写 | 描述 |
|
||||
| ---------------------------------------- | ---- | ------------------------------------------------------------------- |
|
||||
| <nobr><code>{"--command"}</code></nobr> | | 要运行的命令，使用 message 作为参数 |
|
||||
| <nobr><code>{"--continue"}</code></nobr> | `-c` | 继续上一个会话 |
|
||||
| <nobr><code>{"--session"}</code></nobr> | `-s` | 要继续的会话 ID |
|
||||
| <nobr><code>{"--fork"}</code></nobr> | | 继续时分叉会话（与 `--continue` 或 `--session` 配合使用） |
|
||||
| <nobr><code>{"--share"}</code></nobr> | | 分享会话 |
|
||||
| <nobr><code>{"--model"}</code></nobr> | `-m` | 要使用的模型，格式为 provider/model |
|
||||
| <nobr><code>{"--agent"}</code></nobr> | | 要使用的代理 |
|
||||
| <nobr><code>{"--file"}</code></nobr> | `-f` | 附加到消息的文件 |
|
||||
| <nobr><code>{"--format"}</code></nobr> | | 格式：default（格式化输出）或 json（原始 JSON 事件） |
|
||||
| <nobr><code>{"--title"}</code></nobr> | | 会话标题（未提供值时使用截断的提示词） |
|
||||
| <nobr><code>{"--attach"}</code></nobr> | | 连接到正在运行的 opencode 服务器（例如 http://localhost:4096） |
|
||||
| <nobr><code>{"--password"}</code></nobr> | `-p` | 基本认证密码（默认使用 `OPENCODE_SERVER_PASSWORD`） |
|
||||
| <nobr><code>{"--username"}</code></nobr> | `-u` | 基本认证用户名（默认使用 `OPENCODE_SERVER_USERNAME` 或 `opencode`） |
|
||||
| <nobr><code>{"--dir"}</code></nobr> | | 运行目录，或附加时远程服务器上的路径 |
|
||||
| <nobr><code>{"--variant"}</code></nobr> | | 模型变体（特定于提供商的推理级别） |
|
||||
| <nobr><code>{"--thinking"}</code></nobr> | | 显示思考块 |
|
||||
| <nobr><code>{"--port"}</code></nobr> | | 本地服务器端口（默认为随机端口） |
|
||||
|
||||
---
|
||||
|
||||
### serve
|
||||
|
||||
启动无界面的 OpenCode 服务器以提供 API 访问。查看[服务器文档](/docs/server)了解完整的 HTTP 接口。
|
||||
|
||||
```bash
|
||||
opencode serve
|
||||
```
|
||||
|
||||
此命令启动一个 HTTP 服务器，提供对 OpenCode 功能的 API 访问，无需 TUI 界面。设置 `OPENCODE_SERVER_PASSWORD` 可启用 HTTP 基本认证（用户名默认为 `opencode`）。
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 描述 |
|
||||
| ---------------------------------------- | -------------------------- |
|
||||
| <nobr><code>{"--port"}</code></nobr> | 监听端口 |
|
||||
| <nobr><code>{"--hostname"}</code></nobr> | 监听主机名 |
|
||||
| <nobr><code>{"--mdns"}</code></nobr> | 启用 mDNS 发现 |
|
||||
| <nobr><code>{"--cors"}</code></nobr> | 允许 CORS 的额外浏览器来源 |
|
||||
|
||||
---
|
||||
|
||||
### session
|
||||
|
||||
管理 OpenCode 会话。
|
||||
|
||||
```bash
|
||||
opencode session [command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### list
|
||||
|
||||
列出所有 OpenCode 会话。
|
||||
|
||||
```bash
|
||||
opencode session list
|
||||
```
|
||||
|
||||
##### 标志
|
||||
|
||||
| 标志 | 简写 | 描述 |
|
||||
| ----------------------------------------- | ---- | ------------------------------------- |
|
||||
| <nobr><code>{"--max-count"}</code></nobr> | `-n` | 限制为最近 N 个会话 |
|
||||
| <nobr><code>{"--format"}</code></nobr> | | 输出格式：table 或 json（默认 table） |
|
||||
|
||||
---
|
||||
|
||||
### stats
|
||||
|
||||
显示 OpenCode 会话的 Token 用量和费用统计信息。
|
||||
|
||||
```bash
|
||||
opencode stats
|
||||
```
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 描述 |
|
||||
| --------------------------------------- | ------------------------------------------------------ |
|
||||
| <nobr><code>{"--days"}</code></nobr> | 显示最近 N 天的统计信息（默认为所有时间） |
|
||||
| <nobr><code>{"--tools"}</code></nobr> | 显示的工具数量（默认为全部） |
|
||||
| <nobr><code>{"--models"}</code></nobr> | 显示模型用量明细（默认隐藏）。传入数字可显示前 N 个 |
|
||||
| <nobr><code>{"--project"}</code></nobr> | 按项目筛选（默认为所有项目，传入空字符串表示当前项目） |
|
||||
|
||||
---
|
||||
|
||||
### export
|
||||
|
||||
将会话数据导出为 JSON。
|
||||
|
||||
```bash
|
||||
opencode export [sessionID]
|
||||
```
|
||||
|
||||
如果您不提供会话 ID，系统将提示您从可用的会话中进行选择。
|
||||
|
||||
---
|
||||
|
||||
### import
|
||||
|
||||
从 JSON 文件或 OpenCode 分享链接导入会话数据。
|
||||
|
||||
```bash
|
||||
opencode import <file>
|
||||
```
|
||||
|
||||
您可以从本地文件或 OpenCode 分享链接导入。
|
||||
|
||||
```bash
|
||||
opencode import session.json
|
||||
opencode import https://opncd.ai/s/abc123
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### web
|
||||
|
||||
启动带有 Web 界面的无界面 OpenCode 服务器。
|
||||
|
||||
```bash
|
||||
opencode web
|
||||
```
|
||||
|
||||
此命令启动一个 HTTP 服务器并打开浏览器，通过 Web 界面访问 OpenCode。设置 `OPENCODE_SERVER_PASSWORD` 可启用 HTTP 基本认证（用户名默认为 `opencode`）。
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 描述 |
|
||||
| ---------------------------------------- | -------------------------- |
|
||||
| <nobr><code>{"--port"}</code></nobr> | 监听端口 |
|
||||
| <nobr><code>{"--hostname"}</code></nobr> | 监听主机名 |
|
||||
| <nobr><code>{"--mdns"}</code></nobr> | 启用 mDNS 发现 |
|
||||
| <nobr><code>{"--cors"}</code></nobr> | 允许 CORS 的额外浏览器来源 |
|
||||
|
||||
---
|
||||
|
||||
### acp
|
||||
|
||||
启动 ACP（Agent Client Protocol）服务器。
|
||||
|
||||
```bash
|
||||
opencode acp
|
||||
```
|
||||
|
||||
此命令启动一个通过 stdin/stdout 使用 nd-JSON 进行通信的 ACP 服务器。
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 描述 |
|
||||
| ---------------------------------------- | ---------- |
|
||||
| <nobr><code>{"--cwd"}</code></nobr> | 工作目录 |
|
||||
| <nobr><code>{"--port"}</code></nobr> | 监听端口 |
|
||||
| <nobr><code>{"--hostname"}</code></nobr> | 监听主机名 |
|
||||
|
||||
---
|
||||
|
||||
### uninstall
|
||||
|
||||
卸载 OpenCode 并删除所有相关文件。
|
||||
|
||||
```bash
|
||||
opencode uninstall
|
||||
```
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 简写 | 描述 |
|
||||
| ------------------------------------------- | ---- | ------------------------------ |
|
||||
| <nobr><code>{"--keep-config"}</code></nobr> | `-c` | 保留配置文件 |
|
||||
| <nobr><code>{"--keep-data"}</code></nobr> | `-d` | 保留会话数据和快照 |
|
||||
| <nobr><code>{"--dry-run"}</code></nobr> | | 显示将被删除的内容但不实际删除 |
|
||||
| <nobr><code>{"--force"}</code></nobr> | `-f` | 跳过确认提示 |
|
||||
|
||||
---
|
||||
|
||||
### upgrade
|
||||
|
||||
将 OpenCode 更新到最新版本或指定版本。
|
||||
|
||||
```bash
|
||||
opencode upgrade [target]
|
||||
```
|
||||
|
||||
更新到最新版本。
|
||||
|
||||
```bash
|
||||
opencode upgrade
|
||||
```
|
||||
|
||||
更新到指定版本。
|
||||
|
||||
```bash
|
||||
opencode upgrade v0.1.48
|
||||
```
|
||||
|
||||
#### 标志
|
||||
|
||||
| 标志 | 简写 | 描述 |
|
||||
| -------------------------------------- | ---- | ------------------------------------------ |
|
||||
| <nobr><code>{"--method"}</code></nobr> | `-m` | 使用的安装方式：curl、npm、pnpm、bun、brew |
|
||||
|
||||
---
|
||||
|
||||
## 全局标志
|
||||
|
||||
OpenCode CLI 接受以下全局标志。
|
||||
|
||||
| 标志 | 简写 | 描述 |
|
||||
| ------------------------------------------ | ---- | ------------------------------------ |
|
||||
| <nobr><code>{"--help"}</code></nobr> | `-h` | 显示帮助信息 |
|
||||
| <nobr><code>{"--version"}</code></nobr> | `-v` | 打印版本号 |
|
||||
| <nobr><code>{"--print-logs"}</code></nobr> | | 将日志输出到 stderr |
|
||||
| <nobr><code>{"--log-level"}</code></nobr> | | 日志级别（DEBUG、INFO、WARN、ERROR） |
|
||||
|
||||
---
|
||||
|
||||
## 环境变量
|
||||
|
||||
OpenCode 可以通过环境变量进行配置。
|
||||
|
||||
| 变量 | 类型 | 描述 |
|
||||
| ------------------------------------- | ------- | --------------------------------------- |
|
||||
| `OPENCODE_AUTO_SHARE` | boolean | 自动分享会话 |
|
||||
| `OPENCODE_GIT_BASH_PATH` | string | Windows 上 Git Bash 可执行文件的路径 |
|
||||
| `OPENCODE_CONFIG` | string | 配置文件路径 |
|
||||
| `OPENCODE_TUI_CONFIG` | string | TUI 配置文件路径 |
|
||||
| `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_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_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_LSP_TOOL` | boolean | 启用实验性 LSP 工具 |
|
||||
| `OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER` | boolean | 禁用文件监听器 |
|
||||
| `OPENCODE_EXPERIMENTAL_EXA` | boolean | 启用实验性 Exa 功能 |
|
||||
| `OPENCODE_EXPERIMENTAL_LSP_TY` | boolean | 为 python 文件启用 TY LSP |
|
||||
| `OPENCODE_EXPERIMENTAL_PLAN_MODE` | boolean | 启用计划模式 |
|
||||
| `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` | boolean | 启用后台子代理任务 |
|
||||
| `OPENCODE_EXPERIMENTAL_EVENT_SYSTEM` | boolean | 启用实验性事件系统 |
|
||||
| `OPENCODE_EXPERIMENTAL_NATIVE_LLM` | boolean | 启用原生 LLM 请求路径 |
|
||||
| `OPENCODE_EXPERIMENTAL_PARALLEL` | boolean | 启用并行 Web 搜索执行 |
|
||||
| `OPENCODE_EXPERIMENTAL_SCOUT` | boolean | 启用 Scout 子代理 |
|
||||
| `OPENCODE_EXPERIMENTAL_WORKSPACES` | boolean | 启用工作区支持 |
|
||||
322
packages/web/src/content/docs/zh-cn/commands.mdx
Normal file
322
packages/web/src/content/docs/zh-cn/commands.mdx
Normal file
@@ -0,0 +1,322 @@
|
||||
---
|
||||
title: 命令
|
||||
description: 为重复任务创建自定义命令。
|
||||
---
|
||||
|
||||
自定义命令允许你指定一个提示词，当在 TUI 中执行该命令时会运行这个提示词。
|
||||
|
||||
```bash frame="none"
|
||||
/my-command
|
||||
```
|
||||
|
||||
自定义命令是 `/init`、`/undo`、`/redo`、`/share`、`/help` 等内置命令之外的补充。[了解更多](/docs/tui#commands)。
|
||||
|
||||
---
|
||||
|
||||
## 创建命令文件
|
||||
|
||||
在 `commands/` 目录中创建 markdown 文件来定义自定义命令。
|
||||
|
||||
创建 `.opencode/commands/test.md`：
|
||||
|
||||
```md title=".opencode/commands/test.md"
|
||||
---
|
||||
description: Run tests with coverage
|
||||
agent: build
|
||||
model: anthropic/claude-3-5-sonnet-20241022
|
||||
---
|
||||
|
||||
Run the full test suite with coverage report and show any failures.
|
||||
Focus on the failing tests and suggest fixes.
|
||||
```
|
||||
|
||||
frontmatter 定义命令属性，内容则成为模板。
|
||||
|
||||
通过输入 `/` 后跟命令名称来使用该命令。
|
||||
|
||||
```bash frame="none"
|
||||
"/test"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
你可以通过 OpenCode 配置或在 `commands/` 目录中创建 markdown 文件来添加自定义命令。
|
||||
|
||||
---
|
||||
|
||||
### JSON
|
||||
|
||||
在 OpenCode [配置](/docs/config)中使用 `command` 选项：
|
||||
|
||||
```json title="opencode.jsonc" {4-12}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"command": {
|
||||
// This becomes the name of the command
|
||||
"test": {
|
||||
// This is the prompt that will be sent to the LLM
|
||||
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
|
||||
// This is shown as the description in the TUI
|
||||
"description": "Run tests with coverage",
|
||||
"agent": "build",
|
||||
"model": "anthropic/claude-3-5-sonnet-20241022"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
现在你可以在 TUI 中运行这个命令：
|
||||
|
||||
```bash frame="none"
|
||||
/test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Markdown
|
||||
|
||||
你还可以使用 markdown 文件定义命令。将它们放在：
|
||||
|
||||
- 全局：`~/.config/opencode/commands/`
|
||||
- 项目级：`.opencode/commands/`
|
||||
|
||||
```markdown title="~/.config/opencode/commands/test.md"
|
||||
---
|
||||
description: Run tests with coverage
|
||||
agent: build
|
||||
model: anthropic/claude-3-5-sonnet-20241022
|
||||
---
|
||||
|
||||
Run the full test suite with coverage report and show any failures.
|
||||
Focus on the failing tests and suggest fixes.
|
||||
```
|
||||
|
||||
markdown 文件名即为命令名。例如，`test.md` 允许你运行：
|
||||
|
||||
```bash frame="none"
|
||||
/test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 提示词配置
|
||||
|
||||
自定义命令的提示词支持多种特殊占位符和语法。
|
||||
|
||||
---
|
||||
|
||||
### 参数
|
||||
|
||||
使用 `$ARGUMENTS` 占位符向命令传递参数。
|
||||
|
||||
```md title=".opencode/commands/component.md"
|
||||
---
|
||||
description: Create a new component
|
||||
---
|
||||
|
||||
Create a new React component named $ARGUMENTS with TypeScript support.
|
||||
Include proper typing and basic structure.
|
||||
```
|
||||
|
||||
带参数运行命令：
|
||||
|
||||
```bash frame="none"
|
||||
/component Button
|
||||
```
|
||||
|
||||
`$ARGUMENTS` 将被替换为 `Button`。
|
||||
|
||||
你还可以使用位置参数访问各个参数：
|
||||
|
||||
- `$1` - 第一个参数
|
||||
- `$2` - 第二个参数
|
||||
- `$3` - 第三个参数
|
||||
- 以此类推...
|
||||
|
||||
例如：
|
||||
|
||||
```md title=".opencode/commands/create-file.md"
|
||||
---
|
||||
description: Create a new file with content
|
||||
---
|
||||
|
||||
Create a file named $1 in the directory $2
|
||||
with the following content: $3
|
||||
```
|
||||
|
||||
运行命令：
|
||||
|
||||
```bash frame="none"
|
||||
/create-file config.json src "{ \"key\": \"value\" }"
|
||||
```
|
||||
|
||||
替换结果为：
|
||||
|
||||
- `$1` 替换为 `config.json`
|
||||
- `$2` 替换为 `src`
|
||||
- `$3` 替换为 `{ "key": "value" }`
|
||||
|
||||
---
|
||||
|
||||
### Shell 输出
|
||||
|
||||
使用 _!`command`_ 将 [bash 命令](/docs/tui#bash-commands)输出注入到提示词中。
|
||||
|
||||
例如，创建一个分析测试覆盖率的自定义命令：
|
||||
|
||||
```md title=".opencode/commands/analyze-coverage.md"
|
||||
---
|
||||
description: Analyze test coverage
|
||||
---
|
||||
|
||||
Here are the current test results:
|
||||
!`npm test`
|
||||
|
||||
Based on these results, suggest improvements to increase coverage.
|
||||
```
|
||||
|
||||
或者查看最近的更改：
|
||||
|
||||
```md title=".opencode/commands/review-changes.md"
|
||||
---
|
||||
description: Review recent changes
|
||||
---
|
||||
|
||||
Recent git commits:
|
||||
!`git log --oneline -10`
|
||||
|
||||
Review these changes and suggest any improvements.
|
||||
```
|
||||
|
||||
命令在项目的根目录中运行，其输出会成为提示词的一部分。
|
||||
|
||||
---
|
||||
|
||||
### 文件引用
|
||||
|
||||
使用 `@` 后跟文件名在命令中引用文件。
|
||||
|
||||
```md title=".opencode/commands/review-component.md"
|
||||
---
|
||||
description: Review component
|
||||
---
|
||||
|
||||
Review the component in @src/components/Button.tsx.
|
||||
Check for performance issues and suggest improvements.
|
||||
```
|
||||
|
||||
文件内容会自动包含在提示词中。
|
||||
|
||||
---
|
||||
|
||||
## 选项
|
||||
|
||||
让我们详细了解各配置选项。
|
||||
|
||||
---
|
||||
|
||||
### Template
|
||||
|
||||
`template` 选项定义执行命令时发送给 LLM 的提示词。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"test": {
|
||||
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这是一个**必需的**配置选项。
|
||||
|
||||
---
|
||||
|
||||
### Description
|
||||
|
||||
使用 `description` 选项提供命令功能的简要描述。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"test": {
|
||||
"description": "Run tests with coverage"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
当你输入命令时，这将在 TUI 中显示为描述。
|
||||
|
||||
---
|
||||
|
||||
### Agent
|
||||
|
||||
使用 `agent` 配置可选地指定由哪个[代理](/docs/agents)执行此命令。
|
||||
如果这是一个[子代理](/docs/agents/#subagents)，该命令默认会触发子代理调用。
|
||||
要禁用此行为，请将 `subtask` 设置为 `false`。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"review": {
|
||||
"agent": "plan"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这是一个**可选的**配置选项。如果未指定，默认使用你当前的代理。
|
||||
|
||||
---
|
||||
|
||||
### Subtask
|
||||
|
||||
使用 `subtask` 布尔值强制命令触发[子代理](/docs/agents/#subagents)调用。
|
||||
如果你希望命令不污染主要上下文，这会很有用，它会**强制**代理作为子代理运行，
|
||||
即使[代理](/docs/agents)配置中的 `mode` 设置为 `primary`。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"analyze": {
|
||||
"subtask": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这是一个**可选的**配置选项。
|
||||
|
||||
---
|
||||
|
||||
### Model
|
||||
|
||||
使用 `model` 配置覆盖此命令的默认模型。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"analyze": {
|
||||
"model": "anthropic/claude-3-5-sonnet-20241022"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这是一个**可选的**配置选项。
|
||||
|
||||
---
|
||||
|
||||
## 内置命令
|
||||
|
||||
opencode 包含多个内置命令，如 `/init`、`/undo`、`/redo`、`/share`、`/help`；[了解更多](/docs/tui#commands)。
|
||||
|
||||
:::note
|
||||
自定义命令可以覆盖内置命令。
|
||||
:::
|
||||
|
||||
如果你定义了同名的自定义命令，它将覆盖内置命令。
|
||||
683
packages/web/src/content/docs/zh-cn/config.mdx
Normal file
683
packages/web/src/content/docs/zh-cn/config.mdx
Normal file
@@ -0,0 +1,683 @@
|
||||
---
|
||||
title: 配置
|
||||
description: 使用 OpenCode JSON 配置。
|
||||
---
|
||||
|
||||
您可以使用 JSON 配置文件来配置 OpenCode。
|
||||
|
||||
---
|
||||
|
||||
## 格式
|
||||
|
||||
OpenCode 支持 **JSON** 和 **JSONC**（带注释的 JSON）格式。
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"model": "anthropic/claude-sonnet-4-5",
|
||||
"autoupdate": true,
|
||||
"server": {
|
||||
"port": 4096,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 位置
|
||||
|
||||
您可以将配置放置在不同的位置，它们具有不同的优先级顺序。
|
||||
|
||||
:::note
|
||||
配置文件是**合并在一起**的，而不是替换。
|
||||
:::
|
||||
|
||||
配置文件是合并在一起的，而不是被替换。来自以下配置位置的设置会被合并。后面的配置仅在键冲突时覆盖前面的配置。所有配置中的非冲突设置都会被保留。
|
||||
|
||||
例如，如果您的全局配置设置了 `autoupdate: true`，而您的项目配置设置了 `model: "anthropic/claude-sonnet-4-5"`，则最终配置将包含这两个设置。
|
||||
|
||||
---
|
||||
|
||||
### 优先级顺序
|
||||
|
||||
配置源按以下顺序加载（后面的源覆盖前面的源）：
|
||||
|
||||
1. **远程配置**（来自 `.well-known/opencode`）- 组织默认值
|
||||
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/`）。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### 远程
|
||||
|
||||
组织可以通过 `.well-known/opencode` 端点提供默认配置。当您使用支持该功能的提供商进行身份验证时，会自动获取此配置。
|
||||
|
||||
远程配置最先加载，作为基础层。所有其他配置源（全局、项目）都可以覆盖这些默认值。
|
||||
|
||||
例如，如果您的组织提供了默认禁用的 MCP 服务器：
|
||||
|
||||
```json title="Remote config from .well-known/opencode"
|
||||
{
|
||||
"mcp": {
|
||||
"jira": {
|
||||
"type": "remote",
|
||||
"url": "https://jira.example.com/mcp",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
您可以在本地配置中启用特定服务器：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"mcp": {
|
||||
"jira": {
|
||||
"type": "remote",
|
||||
"url": "https://jira.example.com/mcp",
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 全局
|
||||
|
||||
将全局 OpenCode 配置放在 `~/.config/opencode/opencode.json` 中。使用全局配置来设置用户级别的偏好，例如主题、提供商或快捷键。
|
||||
|
||||
全局配置覆盖远程组织默认值。
|
||||
|
||||
---
|
||||
|
||||
### 项目级
|
||||
|
||||
在项目根目录中添加 `opencode.json`。项目配置在标准配置文件中具有最高优先级——它会覆盖全局配置和远程配置。
|
||||
|
||||
:::tip
|
||||
将项目特定配置放在项目的根目录中。
|
||||
:::
|
||||
|
||||
当 OpenCode 启动时，它会在当前目录中查找配置文件，或向上遍历到最近的 Git 目录。
|
||||
|
||||
该配置文件也可以安全地提交到 Git 中，并使用与全局配置相同的 Schema。
|
||||
|
||||
---
|
||||
|
||||
### 自定义路径
|
||||
|
||||
使用 `OPENCODE_CONFIG` 环境变量指定自定义配置文件路径。
|
||||
|
||||
```bash
|
||||
export OPENCODE_CONFIG=/path/to/my/custom-config.json
|
||||
opencode run "Hello world"
|
||||
```
|
||||
|
||||
自定义配置在优先级顺序中位于全局配置和项目配置之间加载。
|
||||
|
||||
---
|
||||
|
||||
### 自定义目录
|
||||
|
||||
使用 `OPENCODE_CONFIG_DIR` 环境变量指定自定义配置目录。该目录会像标准 `.opencode` 目录一样被搜索代理、命令、模式和插件，并且应遵循相同的结构。
|
||||
|
||||
```bash
|
||||
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
|
||||
opencode run "Hello world"
|
||||
```
|
||||
|
||||
自定义目录在全局配置和 `.opencode` 目录之后加载，因此**可以覆盖**它们的设置。
|
||||
|
||||
---
|
||||
|
||||
## Schema
|
||||
|
||||
配置文件具有在 [**`opencode.ai/config.json`**](https://opencode.ai/config.json) 中定义的 Schema。
|
||||
|
||||
您的编辑器应该能够基于该 Schema 进行验证和自动补全。
|
||||
|
||||
---
|
||||
|
||||
### TUI
|
||||
|
||||
您可以通过 `tui` 选项配置 TUI 相关设置。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tui": {
|
||||
"scroll_speed": 3,
|
||||
"scroll_acceleration": {
|
||||
"enabled": true
|
||||
},
|
||||
"diff_style": "auto"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
可用选项：
|
||||
|
||||
- `scroll_acceleration.enabled` - 启用 macOS 风格的滚动加速。**优先于 `scroll_speed`。**
|
||||
- `scroll_speed` - 自定义滚动速度倍率（默认值：`3`，最小值：`1`）。如果 `scroll_acceleration.enabled` 为 `true`，则忽略此选项。
|
||||
- `diff_style` - 控制差异渲染方式。`"auto"` 根据终端宽度自适应，`"stacked"` 始终显示单列。
|
||||
|
||||
[在此了解更多关于 TUI 的信息](/docs/tui)。
|
||||
|
||||
---
|
||||
|
||||
### 服务器
|
||||
|
||||
您可以通过 `server` 选项为 `opencode serve` 和 `opencode web` 命令配置服务器设置。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"server": {
|
||||
"port": 4096,
|
||||
"hostname": "0.0.0.0",
|
||||
"mdns": true,
|
||||
"mdnsDomain": "myproject.local",
|
||||
"cors": ["http://localhost:5173"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
可用选项：
|
||||
|
||||
- `port` - 监听端口。
|
||||
- `hostname` - 监听主机名。当 `mdns` 启用且未设置主机名时，默认为 `0.0.0.0`。
|
||||
- `mdns` - 启用 mDNS 服务发现。这允许网络上的其他设备发现您的 OpenCode 服务器。
|
||||
- `mdnsDomain` - mDNS 服务的自定义域名。默认为 `opencode.local`。适用于在同一网络上运行多个实例的场景。
|
||||
- `cors` - 从基于浏览器的客户端使用 HTTP 服务器时允许 CORS 的额外来源。值必须是完整的来源（协议 + 主机 + 可选端口），例如 `https://app.example.com`。
|
||||
|
||||
[在此了解更多关于服务器的信息](/docs/server)。
|
||||
|
||||
---
|
||||
|
||||
### 工具
|
||||
|
||||
您可以通过 `tools` 选项管理 LLM 可以使用的工具。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"write": false,
|
||||
"bash": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[在此了解更多关于工具的信息](/docs/tools)。
|
||||
|
||||
---
|
||||
|
||||
### 模型
|
||||
|
||||
您可以通过 `provider`、`model` 和 `small_model` 选项在 OpenCode 配置中设置要使用的提供商和模型。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {},
|
||||
"model": "anthropic/claude-sonnet-4-5",
|
||||
"small_model": "anthropic/claude-haiku-4-5"
|
||||
}
|
||||
```
|
||||
|
||||
`small_model` 选项为标题生成等轻量级任务配置单独的模型。默认情况下，如果您的提供商有更便宜的模型可用，OpenCode 会尝试使用该模型，否则会回退到您的主模型。
|
||||
|
||||
提供商选项可以包括 `timeout` 和 `setCacheKey`：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"anthropic": {
|
||||
"options": {
|
||||
"timeout": 600000,
|
||||
"setCacheKey": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `timeout` - 请求超时时间，单位为毫秒（默认值：300000）。设置为 `false` 可禁用超时。
|
||||
- `setCacheKey` - 确保始终为指定提供商设置缓存键。
|
||||
|
||||
您还可以配置[本地模型](/docs/models#local)。[了解更多](/docs/models)。
|
||||
|
||||
---
|
||||
|
||||
#### 提供商特定选项
|
||||
|
||||
一些提供商支持除通用 `timeout` 和 `apiKey` 设置之外的额外配置选项。
|
||||
|
||||
##### Amazon Bedrock
|
||||
|
||||
Amazon Bedrock 支持 AWS 特定配置：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"amazon-bedrock": {
|
||||
"options": {
|
||||
"region": "us-east-1",
|
||||
"profile": "my-aws-profile",
|
||||
"endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `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)。
|
||||
:::
|
||||
|
||||
[了解更多关于 Amazon Bedrock 配置的信息](/docs/providers#amazon-bedrock)。
|
||||
|
||||
---
|
||||
|
||||
### 主题
|
||||
|
||||
您可以通过 OpenCode 配置中的 `theme` 选项设置要使用的主题。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"theme": ""
|
||||
}
|
||||
```
|
||||
|
||||
[在此了解更多](/docs/themes)。
|
||||
|
||||
---
|
||||
|
||||
### 代理
|
||||
|
||||
您可以通过 `agent` 选项为特定任务配置专用代理。
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"agent": {
|
||||
"code-reviewer": {
|
||||
"description": "Reviews code for best practices and potential issues",
|
||||
"model": "anthropic/claude-sonnet-4-5",
|
||||
"prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
|
||||
"tools": {
|
||||
// Disable file modification tools for review-only agent
|
||||
"write": false,
|
||||
"edit": false,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
您还可以使用 `~/.config/opencode/agents/` 或 `.opencode/agents/` 中的 Markdown 文件定义代理。[在此了解更多](/docs/agents)。
|
||||
|
||||
---
|
||||
|
||||
### 默认代理
|
||||
|
||||
您可以使用 `default_agent` 选项设置默认代理。当未明确指定代理时，将使用该默认代理。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"default_agent": "plan"
|
||||
}
|
||||
```
|
||||
|
||||
默认代理必须是主代理（不能是子代理）。可以是内置代理（如 `"build"` 或 `"plan"`），也可以是您定义的[自定义代理](/docs/agents)。如果指定的代理不存在或是子代理，OpenCode 将回退到 `"build"` 并发出警告。
|
||||
|
||||
此设置适用于所有界面：TUI、CLI（`opencode run`）、桌面应用和 GitHub Action。
|
||||
|
||||
---
|
||||
|
||||
### 分享
|
||||
|
||||
您可以通过 `share` 选项配置[分享](/docs/share)功能。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"share": "manual"
|
||||
}
|
||||
```
|
||||
|
||||
该选项接受：
|
||||
|
||||
- `"manual"` - 允许通过命令手动分享（默认）
|
||||
- `"auto"` - 自动分享新会话
|
||||
- `"disabled"` - 完全禁用分享
|
||||
|
||||
默认情况下，分享设置为手动模式，您需要使用 `/share` 命令显式分享会话。
|
||||
|
||||
---
|
||||
|
||||
### 命令
|
||||
|
||||
您可以通过 `command` 选项为重复任务配置自定义命令。
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"command": {
|
||||
"test": {
|
||||
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
|
||||
"description": "Run tests with coverage",
|
||||
"agent": "build",
|
||||
"model": "anthropic/claude-haiku-4-5",
|
||||
},
|
||||
"component": {
|
||||
"template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
|
||||
"description": "Create a new component",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
您还可以使用 `~/.config/opencode/commands/` 或 `.opencode/commands/` 中的 Markdown 文件定义命令。[在此了解更多](/docs/commands)。
|
||||
|
||||
---
|
||||
|
||||
### 快捷键
|
||||
|
||||
您可以通过 `keybinds` 选项自定义快捷键。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"keybinds": {}
|
||||
}
|
||||
```
|
||||
|
||||
[在此了解更多](/docs/keybinds)。
|
||||
|
||||
---
|
||||
|
||||
### 自动更新
|
||||
|
||||
OpenCode 启动时会自动下载新版本。您可以使用 `autoupdate` 选项禁用此功能。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"autoupdate": false
|
||||
}
|
||||
```
|
||||
|
||||
如果您不想自动更新但希望在新版本可用时收到通知，可将 `autoupdate` 设置为 `"notify"`。
|
||||
请注意，此功能仅在未通过 Homebrew 等包管理器安装时有效。
|
||||
|
||||
---
|
||||
|
||||
### 格式化程序
|
||||
|
||||
您可以通过 `formatter` 选项配置代码格式化程序。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"formatter": {
|
||||
"prettier": {
|
||||
"disabled": true
|
||||
},
|
||||
"custom-prettier": {
|
||||
"command": ["npx", "prettier", "--write", "$FILE"],
|
||||
"environment": {
|
||||
"NODE_ENV": "development"
|
||||
},
|
||||
"extensions": [".js", ".ts", ".jsx", ".tsx"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[在此了解更多关于格式化程序的信息](/docs/formatters)。
|
||||
|
||||
---
|
||||
|
||||
### 权限
|
||||
|
||||
默认情况下，OpenCode **允许所有操作**，无需明确批准。您可以使用 `permission` 选项更改此行为。
|
||||
|
||||
例如，要让 `edit` 和 `bash` 工具需要用户确认：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "ask",
|
||||
"bash": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[在此了解更多关于权限的信息](/docs/permissions)。
|
||||
|
||||
---
|
||||
|
||||
### 压缩
|
||||
|
||||
您可以通过 `compaction` 选项控制上下文压缩行为。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"compaction": {
|
||||
"auto": true,
|
||||
"prune": false,
|
||||
"reserved": 10000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `auto` - 当上下文已满时自动压缩会话（默认值：`true`）。
|
||||
- `prune` - 删除旧的工具输出以节省 Token（默认值：`false`）。
|
||||
- `reserved` - 压缩时的 Token 缓冲区。保留足够的窗口以避免压缩过程中溢出。
|
||||
|
||||
---
|
||||
|
||||
### 文件监视器
|
||||
|
||||
您可以通过 `watcher` 选项配置文件监视器的忽略模式。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"watcher": {
|
||||
"ignore": ["node_modules/**", "dist/**", ".git/**"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
模式遵循 glob 语法。使用此选项可以从文件监视中排除频繁变动的目录。
|
||||
|
||||
---
|
||||
|
||||
### MCP 服务器
|
||||
|
||||
您可以通过 `mcp` 选项配置要使用的 MCP 服务器。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {}
|
||||
}
|
||||
```
|
||||
|
||||
[在此了解更多](/docs/mcp-servers)。
|
||||
|
||||
---
|
||||
|
||||
### 插件
|
||||
|
||||
[插件](/docs/plugins)通过自定义工具、钩子和集成来扩展 OpenCode。
|
||||
|
||||
将插件文件放置在 `.opencode/plugins/` 或 `~/.config/opencode/plugins/` 中。您还可以通过 `plugin` 选项从 npm 加载插件。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
|
||||
}
|
||||
```
|
||||
|
||||
[在此了解更多](/docs/plugins)。
|
||||
|
||||
---
|
||||
|
||||
### 指令
|
||||
|
||||
您可以通过 `instructions` 选项为所使用的模型配置指令。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
|
||||
}
|
||||
```
|
||||
|
||||
该选项接受指令文件路径和 glob 模式的数组。[在此了解更多关于规则的信息](/docs/rules)。
|
||||
|
||||
---
|
||||
|
||||
### 禁用提供商
|
||||
|
||||
您可以通过 `disabled_providers` 选项禁用自动加载的提供商。当您希望阻止某些提供商被加载（即使其凭据可用）时，此选项非常有用。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"disabled_providers": ["openai", "gemini"]
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
`disabled_providers` 优先于 `enabled_providers`。
|
||||
:::
|
||||
|
||||
`disabled_providers` 选项接受提供商 ID 的数组。当某个提供商被禁用时：
|
||||
|
||||
- 即使设置了环境变量，也不会被加载。
|
||||
- 即使通过 `/connect` 命令配置了 API 密钥，也不会被加载。
|
||||
- 该提供商的模型不会出现在模型选择列表中。
|
||||
|
||||
---
|
||||
|
||||
### 启用提供商
|
||||
|
||||
您可以通过 `enabled_providers` 选项指定允许使用的提供商白名单。设置后，仅启用指定的提供商，所有其他提供商将被忽略。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"enabled_providers": ["anthropic", "openai"]
|
||||
}
|
||||
```
|
||||
|
||||
当您希望限制 OpenCode 仅使用特定提供商，而不是逐一禁用其他提供商时，此选项非常有用。
|
||||
|
||||
:::note
|
||||
`disabled_providers` 优先于 `enabled_providers`。
|
||||
:::
|
||||
|
||||
如果某个提供商同时出现在 `enabled_providers` 和 `disabled_providers` 中，为了向后兼容，`disabled_providers` 优先。
|
||||
|
||||
---
|
||||
|
||||
### 实验性功能
|
||||
|
||||
`experimental` 键包含正在积极开发中的选项。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"experimental": {}
|
||||
}
|
||||
```
|
||||
|
||||
:::caution
|
||||
实验性选项不稳定。它们可能会在不另行通知的情况下被更改或移除。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 变量
|
||||
|
||||
您可以在配置文件中使用变量替换来引用环境变量和文件内容。
|
||||
|
||||
---
|
||||
|
||||
### 环境变量
|
||||
|
||||
使用 `{env:VARIABLE_NAME}` 来替换环境变量：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"model": "{env:OPENCODE_MODEL}",
|
||||
"provider": {
|
||||
"anthropic": {
|
||||
"models": {},
|
||||
"options": {
|
||||
"apiKey": "{env:ANTHROPIC_API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果环境变量未设置，它将被替换为空字符串。
|
||||
|
||||
---
|
||||
|
||||
### 文件
|
||||
|
||||
使用 `{file:path/to/file}` 来替换文件内容：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"instructions": ["./custom-instructions.md"],
|
||||
"provider": {
|
||||
"openai": {
|
||||
"options": {
|
||||
"apiKey": "{file:~/.secrets/openai-key}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
文件路径可以是：
|
||||
|
||||
- 相对于配置文件所在目录的路径
|
||||
- 以 `/` 或 `~` 开头的绝对路径
|
||||
|
||||
这些功能适用于：
|
||||
|
||||
- 将 API 密钥等敏感数据保存在单独的文件中。
|
||||
- 引入大型指令文件而不会使配置变得杂乱。
|
||||
- 在多个配置文件之间共享通用配置片段。
|
||||
196
packages/web/src/content/docs/zh-cn/custom-tools.mdx
Normal file
196
packages/web/src/content/docs/zh-cn/custom-tools.mdx
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
title: 自定义工具
|
||||
description: 创建 LLM 可在 opencode 中调用的工具。
|
||||
---
|
||||
|
||||
自定义工具是你创建的函数，LLM 可以在对话过程中调用它们。它们与 opencode 的[内置工具](/docs/tools)（如 `read`、`write` 和 `bash`）协同工作。
|
||||
|
||||
---
|
||||
|
||||
## 创建工具
|
||||
|
||||
工具以 **TypeScript** 或 **JavaScript** 文件的形式定义。不过，工具定义可以调用**任何语言**编写的脚本——TypeScript 或 JavaScript 仅用于工具定义本身。
|
||||
|
||||
---
|
||||
|
||||
### 位置
|
||||
|
||||
工具可以在以下位置定义：
|
||||
|
||||
- 本地定义：将工具文件放在项目的 `.opencode/tools/` 目录中。
|
||||
- 全局定义：将工具文件放在 `~/.config/opencode/tools/` 中。
|
||||
|
||||
---
|
||||
|
||||
### 结构
|
||||
|
||||
创建工具最简单的方式是使用 `tool()` 辅助函数，它提供类型安全和参数校验。
|
||||
|
||||
```ts title=".opencode/tools/database.ts" {1}
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
|
||||
export default tool({
|
||||
description: "Query the project database",
|
||||
args: {
|
||||
query: tool.schema.string().describe("SQL query to execute"),
|
||||
},
|
||||
async execute(args) {
|
||||
// Your database logic here
|
||||
return `Executed query: ${args.query}`
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**文件名**即为**工具名称**。上面的示例创建了一个名为 `database` 的工具。
|
||||
|
||||
---
|
||||
|
||||
#### 单文件多工具
|
||||
|
||||
你也可以从单个文件中导出多个工具。每个导出都会成为**一个独立的工具**，命名格式为 **`<filename>_<exportname>`**：
|
||||
|
||||
```ts title=".opencode/tools/math.ts"
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
|
||||
export const add = tool({
|
||||
description: "Add two numbers",
|
||||
args: {
|
||||
a: tool.schema.number().describe("First number"),
|
||||
b: tool.schema.number().describe("Second number"),
|
||||
},
|
||||
async execute(args) {
|
||||
return args.a + args.b
|
||||
},
|
||||
})
|
||||
|
||||
export const multiply = tool({
|
||||
description: "Multiply two numbers",
|
||||
args: {
|
||||
a: tool.schema.number().describe("First number"),
|
||||
b: tool.schema.number().describe("Second number"),
|
||||
},
|
||||
async execute(args) {
|
||||
return args.a * args.b
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
这会创建两个工具：`math_add` 和 `math_multiply`。
|
||||
|
||||
---
|
||||
|
||||
#### 与内置工具的名称冲突
|
||||
|
||||
自定义工具通过工具名称进行索引。如果自定义工具使用了与内置工具相同的名称，则优先使用自定义工具。
|
||||
|
||||
例如，这个文件取代了内置的bash工具：
|
||||
|
||||
```ts title=".opencode/tools/bash.ts"
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
|
||||
export default tool({
|
||||
description: "Restricted bash wrapper",
|
||||
args: {
|
||||
command: tool.schema.string(),
|
||||
},
|
||||
async execute(args) {
|
||||
return `blocked: ${args.command}`
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
:::note
|
||||
除非你有意替换内置工具，否则最好用独特的名字。如果你想禁用内置工具但不想覆盖它，使用 [权限](/docs/permissions).
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### 参数
|
||||
|
||||
你可以使用 `tool.schema`（即 [Zod](https://zod.dev)）来定义参数类型。
|
||||
|
||||
```ts "tool.schema"
|
||||
args: {
|
||||
query: tool.schema.string().describe("SQL query to execute")
|
||||
}
|
||||
```
|
||||
|
||||
你也可以直接导入 [Zod](https://zod.dev) 并返回一个普通对象：
|
||||
|
||||
```ts {6}
|
||||
import { z } from "zod"
|
||||
|
||||
export default {
|
||||
description: "Tool description",
|
||||
args: {
|
||||
param: z.string().describe("Parameter description"),
|
||||
},
|
||||
async execute(args, context) {
|
||||
// Tool implementation
|
||||
return "result"
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 上下文
|
||||
|
||||
工具会接收当前会话的上下文信息：
|
||||
|
||||
```ts title=".opencode/tools/project.ts" {8}
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
|
||||
export default tool({
|
||||
description: "Get project information",
|
||||
args: {},
|
||||
async execute(args, context) {
|
||||
// Access context information
|
||||
const { agent, sessionID, messageID, directory, worktree } = context
|
||||
return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
使用 `context.directory` 获取会话的工作目录。
|
||||
使用 `context.worktree` 获取 git worktree 根目录。
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 用 Python 编写工具
|
||||
|
||||
你可以使用任何语言编写工具。以下示例展示了如何用 Python 实现两数相加。
|
||||
|
||||
首先，创建一个 Python 脚本作为工具：
|
||||
|
||||
```python title=".opencode/tools/add.py"
|
||||
import sys
|
||||
|
||||
a = int(sys.argv[1])
|
||||
b = int(sys.argv[2])
|
||||
print(a + b)
|
||||
```
|
||||
|
||||
然后创建调用该脚本的工具定义：
|
||||
|
||||
```ts title=".opencode/tools/python-add.ts" {10}
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import path from "path"
|
||||
|
||||
export default tool({
|
||||
description: "Add two numbers using Python",
|
||||
args: {
|
||||
a: tool.schema.number().describe("First number"),
|
||||
b: tool.schema.number().describe("Second number"),
|
||||
},
|
||||
async execute(args, context) {
|
||||
const script = path.join(context.worktree, ".opencode/tools/add.py")
|
||||
const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
这里我们使用 [`Bun.$`](https://bun.com/docs/runtime/shell) 工具函数来运行 Python 脚本。
|
||||
78
packages/web/src/content/docs/zh-cn/ecosystem.mdx
Normal file
78
packages/web/src/content/docs/zh-cn/ecosystem.mdx
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: 生态系统
|
||||
description: 基于 OpenCode 构建的项目与集成。
|
||||
---
|
||||
|
||||
基于 OpenCode 构建的社区项目合集。
|
||||
|
||||
:::note
|
||||
想将您的 OpenCode 相关项目添加到此列表中？欢迎提交 PR。
|
||||
:::
|
||||
|
||||
您还可以查看 [awesome-opencode](https://github.com/awesome-opencode/awesome-opencode) 和 [opencode.cafe](https://opencode.cafe)，这是一个聚合生态系统与社区资源的社区。
|
||||
|
||||
---
|
||||
|
||||
## 插件
|
||||
|
||||
| 名称 | 描述 |
|
||||
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| [opencode-daytona](https://github.com/daytonaio/daytona/tree/main/libs/opencode-plugin) | 在隔离的 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-vibeguard](https://github.com/inkdust2021/opencode-vibeguard) | 在调用 LLM 之前将机密/PII 替换为 VibeGuard 风格的占位符；并在本地恢复 |
|
||||
| [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-plugin](https://github.com/morphllm/opencode-morph-plugin) | 通过 Morph 提供 Fast Apply 编辑、WarpGrep 代码搜索和上下文压缩 |
|
||||
| [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 管理 |
|
||||
| [opencode-sentry-monitor](https://github.com/stolinski/opencode-sentry-monitor) | 使用 Sentry AI Monitoring 追踪和调试您的 AI 代理 |
|
||||
|
||||
---
|
||||
|
||||
## 项目
|
||||
|
||||
| 名称 | 描述 |
|
||||
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
|
||||
| [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) | 用于增强工作流的配置、提示词、代理和插件 |
|
||||
165
packages/web/src/content/docs/zh-cn/enterprise.mdx
Normal file
165
packages/web/src/content/docs/zh-cn/enterprise.mdx
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
title: 企业版
|
||||
description: 在您的组织中安全地使用 OpenCode。
|
||||
---
|
||||
|
||||
import config from "../../../../config.mjs"
|
||||
export const email = `mailto:${config.email}`
|
||||
|
||||
OpenCode 企业版面向希望确保代码和数据始终留在自有基础设施内的组织。它通过集中式配置与您的 SSO 和内部 AI 网关集成来实现这一目标。
|
||||
|
||||
:::note
|
||||
OpenCode 不会存储您的任何代码或上下文数据。
|
||||
:::
|
||||
|
||||
开始使用 OpenCode 企业版：
|
||||
|
||||
1. 在团队内部进行试用。
|
||||
2. **<a href={email}>联系我们</a>**，讨论定价和实施方案。
|
||||
|
||||
---
|
||||
|
||||
## 试用
|
||||
|
||||
OpenCode 是开源的，不会存储您的任何代码或上下文数据，因此您的开发人员可以直接[开始使用](/docs/)并进行试用。
|
||||
|
||||
---
|
||||
|
||||
### 数据处理
|
||||
|
||||
**OpenCode 不会存储您的代码或上下文数据。**所有处理均在本地完成，或通过直接 API 调用发送至您的 AI 提供商。
|
||||
|
||||
这意味着，只要您使用的是信任的提供商或内部 AI 网关，就可以安全地使用 OpenCode。
|
||||
|
||||
唯一需要注意的是可选的 `/share` 功能。
|
||||
|
||||
---
|
||||
|
||||
#### 分享对话
|
||||
|
||||
如果用户启用了 `/share` 功能，对话及其关联数据将被发送到我们用于在 opencode.ai 上托管共享页面的服务。
|
||||
|
||||
数据目前通过我们 CDN 的边缘网络提供服务，并缓存在靠近用户的边缘节点上。
|
||||
|
||||
我们建议您在试用期间禁用此功能。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"share": "disabled"
|
||||
}
|
||||
```
|
||||
|
||||
[了解更多关于分享的信息](/docs/share)。
|
||||
|
||||
---
|
||||
|
||||
### 代码所有权
|
||||
|
||||
**您拥有 OpenCode 生成的所有代码。**不存在任何许可限制或所有权声明。
|
||||
|
||||
---
|
||||
|
||||
## 定价
|
||||
|
||||
OpenCode 企业版采用按席位定价模型。如果您拥有自己的 LLM 网关，我们不会对使用的 Token 收取费用。有关定价和实施方案的更多详情，请**<a href={email}>联系我们</a>**。
|
||||
|
||||
---
|
||||
|
||||
## 部署
|
||||
|
||||
完成试用并准备好在组织中使用 OpenCode 后，您可以**<a href={email}>联系我们</a>**，讨论定价和实施方案。
|
||||
|
||||
---
|
||||
|
||||
### 集中式配置
|
||||
|
||||
我们可以为您的整个组织设置 OpenCode 的统一集中式配置。
|
||||
|
||||
该集中式配置可与您的 SSO 提供商集成，确保所有用户仅访问您的内部 AI 网关。
|
||||
|
||||
---
|
||||
|
||||
### SSO 集成
|
||||
|
||||
通过集中式配置，OpenCode 可以与您组织的 SSO 提供商集成进行身份验证。
|
||||
|
||||
这使得 OpenCode 能够通过您现有的身份管理系统获取内部 AI 网关的凭据。
|
||||
|
||||
---
|
||||
|
||||
### 内部 AI 网关
|
||||
|
||||
通过集中式配置，OpenCode 还可以被配置为仅使用您的内部 AI 网关。
|
||||
|
||||
您还可以禁用所有其他 AI 提供商，确保所有请求都经过组织批准的基础设施。
|
||||
|
||||
---
|
||||
|
||||
### 自托管
|
||||
|
||||
虽然我们建议禁用共享页面以确保您的数据始终不会离开组织，但我们也可以帮助您在自己的基础设施上自行托管这些页面。
|
||||
|
||||
此功能目前已列入我们的路线图。如果您感兴趣，请**<a href={email}>告诉我们</a>**。
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
<details>
|
||||
<summary>什么是 OpenCode 企业版？</summary>
|
||||
|
||||
OpenCode 企业版面向希望确保代码和数据始终留在自有基础设施内的组织。它通过集中式配置与您的 SSO 和内部 AI 网关集成来实现这一目标。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>如何开始使用 OpenCode 企业版？</summary>
|
||||
|
||||
只需在团队内部开始试用即可。OpenCode 默认不存储您的代码或上下文数据，因此可以轻松上手。
|
||||
|
||||
然后**<a href={email}>联系我们</a>**，讨论定价和实施方案。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>企业版定价如何运作？</summary>
|
||||
|
||||
我们提供按席位的企业版定价。如果您拥有自己的 LLM 网关，我们不会对使用的 Token 收取费用。如需了解更多详情，请**<a href={email}>联系我们</a>**，获取根据您组织需求定制的报价。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>我的数据在 OpenCode 企业版中是否安全？</summary>
|
||||
|
||||
是的。OpenCode 不会存储您的代码或上下文数据。所有处理均在本地完成，或通过直接 API 调用发送至您的 AI 提供商。通过集中式配置和 SSO 集成，您的数据将安全地保留在组织的基础设施内。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>我们可以使用自己的私有 NPM 注册表吗？</summary>
|
||||
|
||||
OpenCode 通过 Bun 原生的 `.npmrc` 文件支持来支持私有 npm 注册表。如果您的组织使用私有注册表（例如 JFrog Artifactory、Nexus 或类似产品），请确保开发人员在运行 OpenCode 之前已完成身份验证。
|
||||
|
||||
要设置私有注册表的身份验证：
|
||||
|
||||
```bash
|
||||
npm login --registry=https://your-company.jfrog.io/api/npm/npm-virtual/
|
||||
```
|
||||
|
||||
这会创建包含身份验证信息的 `~/.npmrc` 文件。OpenCode 会自动识别并使用它。
|
||||
|
||||
:::caution
|
||||
在运行 OpenCode 之前，您必须先登录私有注册表。
|
||||
:::
|
||||
|
||||
或者，您也可以手动配置 `.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 之前登录私有注册表，以确保能够从您的企业注册表安装软件包。
|
||||
|
||||
</details>
|
||||
132
packages/web/src/content/docs/zh-cn/formatters.mdx
Normal file
132
packages/web/src/content/docs/zh-cn/formatters.mdx
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: 格式化工具
|
||||
description: OpenCode 使用特定语言的格式化工具。
|
||||
---
|
||||
|
||||
OpenCode 会在文件写入或编辑后，自动使用特定语言的格式化工具对其进行格式化。这确保了生成的代码遵循你项目的代码风格。
|
||||
|
||||
---
|
||||
|
||||
## 内置格式化工具
|
||||
|
||||
OpenCode 内置了多种适用于主流语言和框架的格式化工具。下表列出了各格式化工具、支持的文件扩展名以及所需的命令或配置选项。
|
||||
|
||||
| 格式化工具 | 扩展名 | 要求 |
|
||||
| -------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| 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` 命令可用 |
|
||||
|
||||
因此，如果你的项目 `package.json` 中包含 `prettier`，OpenCode 会自动使用它进行格式化。
|
||||
|
||||
---
|
||||
|
||||
## 工作原理
|
||||
|
||||
当 OpenCode 写入或编辑文件时，它会：
|
||||
|
||||
1. 根据所有已启用的格式化工具检查文件扩展名。
|
||||
2. 对文件运行相应的格式化命令。
|
||||
3. 自动应用格式化更改。
|
||||
|
||||
整个过程在后台完成，无需任何手动操作即可保持代码风格的一致性。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
你可以通过 OpenCode 配置中的 `formatter` 部分自定义格式化工具。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"formatter": {}
|
||||
}
|
||||
```
|
||||
|
||||
每个格式化工具的配置支持以下属性：
|
||||
|
||||
| 属性 | 类型 | 描述 |
|
||||
| ------------- | -------- | ------------------------------ |
|
||||
| `disabled` | boolean | 设为 `true` 可禁用该格式化工具 |
|
||||
| `command` | string[] | 执行格式化的命令 |
|
||||
| `environment` | object | 运行格式化工具时设置的环境变量 |
|
||||
| `extensions` | string[] | 该格式化工具处理的文件扩展名 |
|
||||
|
||||
下面来看一些示例。
|
||||
|
||||
---
|
||||
|
||||
### 禁用格式化工具
|
||||
|
||||
要全局禁用**所有**格式化工具，将 `formatter` 设为 `false`：
|
||||
|
||||
```json title="opencode.json" {3}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"formatter": false
|
||||
}
|
||||
```
|
||||
|
||||
要禁用**特定**格式化工具，将 `disabled` 设为 `true`：
|
||||
|
||||
```json title="opencode.json" {5}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"formatter": {
|
||||
"prettier": {
|
||||
"disabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 自定义格式化工具
|
||||
|
||||
你可以通过指定命令、环境变量和文件扩展名来覆盖内置格式化工具或添加新的格式化工具：
|
||||
|
||||
```json title="opencode.json" {4-14}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"formatter": {
|
||||
"prettier": {
|
||||
"command": ["npx", "prettier", "--write", "$FILE"],
|
||||
"environment": {
|
||||
"NODE_ENV": "development"
|
||||
},
|
||||
"extensions": [".js", ".ts", ".jsx", ".tsx"]
|
||||
},
|
||||
"custom-markdown-formatter": {
|
||||
"command": ["deno", "fmt", "$FILE"],
|
||||
"extensions": [".md"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
命令中的 **`$FILE` 占位符**会被替换为待格式化文件的路径。
|
||||
321
packages/web/src/content/docs/zh-cn/github.mdx
Normal file
321
packages/web/src/content/docs/zh-cn/github.mdx
Normal file
@@ -0,0 +1,321 @@
|
||||
---
|
||||
title: GitHub
|
||||
description: 在 GitHub Issue 和 Pull Request 中使用 OpenCode。
|
||||
---
|
||||
|
||||
OpenCode 可以与你的 GitHub 工作流集成。在评论中提及 `/opencode` 或 `/oc`，OpenCode 就会在你的 GitHub Actions 运行器中执行任务。
|
||||
|
||||
---
|
||||
|
||||
## 功能特性
|
||||
|
||||
- **问题分类**：让 OpenCode 调查某个 Issue 并为你做出解释。
|
||||
- **修复与实现**：让 OpenCode 修复 Issue 或实现某个功能。它会在新分支中工作，并提交包含所有变更的 PR。
|
||||
- **安全可靠**：OpenCode 在你自己的 GitHub 运行器中运行。
|
||||
|
||||
---
|
||||
|
||||
## 安装
|
||||
|
||||
在一个位于 GitHub 仓库中的项目里运行以下命令：
|
||||
|
||||
```bash
|
||||
opencode github install
|
||||
```
|
||||
|
||||
该命令会引导你完成 GitHub App 的安装、工作流的创建以及密钥的配置。
|
||||
|
||||
---
|
||||
|
||||
### 手动设置
|
||||
|
||||
你也可以手动进行设置。
|
||||
|
||||
1. **安装 GitHub App**
|
||||
|
||||
前往 [**github.com/apps/opencode-agent**](https://github.com/apps/opencode-agent)，确保已在目标仓库中安装该应用。
|
||||
|
||||
2. **添加工作流**
|
||||
|
||||
将以下工作流文件添加到仓库的 `.github/workflows/opencode.yml` 中。请确保在 `env` 中设置合适的 `model` 及所需的 API 密钥。
|
||||
|
||||
```yml title=".github/workflows/opencode.yml" {24,26}
|
||||
name: opencode
|
||||
|
||||
on:
|
||||
issue_comment:
|
||||
types: [created]
|
||||
pull_request_review_comment:
|
||||
types: [created]
|
||||
|
||||
jobs:
|
||||
opencode:
|
||||
if: |
|
||||
contains(github.event.comment.body, '/oc') ||
|
||||
contains(github.event.comment.body, '/opencode')
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-depth: 1
|
||||
persist-credentials: false
|
||||
|
||||
- name: Run OpenCode
|
||||
uses: anomalyco/opencode/github@latest
|
||||
env:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
with:
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
# share: true
|
||||
# github_token: xxxx
|
||||
```
|
||||
|
||||
3. **将 API 密钥存储到 Secrets 中**
|
||||
|
||||
在你的组织或项目的 **Settings** 中，展开左侧的 **Secrets and variables**，然后选择 **Actions**，添加所需的 API 密钥。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
- `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 App。只需确保在工作流中授予所需的权限：
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: write
|
||||
pull-requests: write
|
||||
issues: write
|
||||
```
|
||||
|
||||
如果你愿意，也可以使用[个人访问令牌](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)（PAT）。
|
||||
|
||||
---
|
||||
|
||||
## 支持的事件
|
||||
|
||||
OpenCode 可以由以下 GitHub 事件触发：
|
||||
|
||||
| 事件类型 | 触发方式 | 详情 |
|
||||
| ----------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `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 以执行自动化任务：
|
||||
|
||||
```yaml title=".github/workflows/opencode-scheduled.yml"
|
||||
name: Scheduled OpenCode Task
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: "0 9 * * 1" # Every Monday at 9am UTC
|
||||
|
||||
jobs:
|
||||
opencode:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: write
|
||||
pull-requests: write
|
||||
issues: write
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
- name: Run OpenCode
|
||||
uses: anomalyco/opencode/github@latest
|
||||
env:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
with:
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
prompt: |
|
||||
Review the codebase for any TODO comments and create a summary.
|
||||
If you find issues worth addressing, open an issue to track them.
|
||||
```
|
||||
|
||||
对于定时事件，`prompt` 输入为**必填**，因为没有评论可供提取指令。定时工作流在运行时没有用户上下文来进行权限检查，因此如果你希望 OpenCode 创建分支或 PR，工作流必须授予 `contents: write` 和 `pull-requests: write` 权限。
|
||||
|
||||
---
|
||||
|
||||
### Pull Request 示例
|
||||
|
||||
在 PR 被创建或更新时自动进行审查：
|
||||
|
||||
```yaml title=".github/workflows/opencode-review.yml"
|
||||
name: opencode-review
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened, ready_for_review]
|
||||
|
||||
jobs:
|
||||
review:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
pull-requests: read
|
||||
issues: read
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: anomalyco/opencode/github@latest
|
||||
env:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
with:
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
use_github_token: true
|
||||
prompt: |
|
||||
Review this pull request:
|
||||
- Check for code quality issues
|
||||
- Look for potential bugs
|
||||
- Suggest improvements
|
||||
```
|
||||
|
||||
对于 `pull_request` 事件，如果未提供 `prompt`，OpenCode 将默认对该 Pull Request 进行审查。
|
||||
|
||||
---
|
||||
|
||||
### Issue 分类示例
|
||||
|
||||
自动分类新建的 Issue。以下示例会过滤掉注册不满 30 天的账户以减少垃圾信息：
|
||||
|
||||
```yaml title=".github/workflows/opencode-triage.yml"
|
||||
name: Issue Triage
|
||||
|
||||
on:
|
||||
issues:
|
||||
types: [opened]
|
||||
|
||||
jobs:
|
||||
triage:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: write
|
||||
pull-requests: write
|
||||
issues: write
|
||||
steps:
|
||||
- name: Check account age
|
||||
id: check
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const user = await github.rest.users.getByUsername({
|
||||
username: context.payload.issue.user.login
|
||||
});
|
||||
const created = new Date(user.data.created_at);
|
||||
const days = (Date.now() - created) / (1000 * 60 * 60 * 24);
|
||||
return days >= 30;
|
||||
result-encoding: string
|
||||
|
||||
- uses: actions/checkout@v6
|
||||
if: steps.check.outputs.result == 'true'
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
- uses: anomalyco/opencode/github@latest
|
||||
if: steps.check.outputs.result == 'true'
|
||||
env:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
with:
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
prompt: |
|
||||
Review this issue. If there's a clear fix or relevant docs:
|
||||
- Provide documentation links
|
||||
- Add error handling guidance for code examples
|
||||
Otherwise, do not comment.
|
||||
```
|
||||
|
||||
对于 `issues` 事件，`prompt` 输入为**必填**，因为没有评论可供提取指令。
|
||||
|
||||
---
|
||||
|
||||
## 自定义提示词
|
||||
|
||||
覆盖默认提示词，以便为你的工作流自定义 OpenCode 的行为。
|
||||
|
||||
```yaml title=".github/workflows/opencode.yml"
|
||||
- uses: anomalyco/opencode/github@latest
|
||||
with:
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
prompt: |
|
||||
Review this pull request:
|
||||
- Check for code quality issues
|
||||
- Look for potential bugs
|
||||
- Suggest improvements
|
||||
```
|
||||
|
||||
这对于在项目中实施特定的审查标准、编码规范或关注重点非常有用。
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
以下是在 GitHub 中使用 OpenCode 的一些示例。
|
||||
|
||||
- **解释 Issue**
|
||||
|
||||
在 GitHub Issue 中添加以下评论：
|
||||
|
||||
```
|
||||
/opencode explain this issue
|
||||
```
|
||||
|
||||
OpenCode 会阅读整个讨论串（包括所有评论），并回复一份清晰的解释。
|
||||
|
||||
- **修复 Issue**
|
||||
|
||||
在 GitHub Issue 中输入：
|
||||
|
||||
```
|
||||
/opencode fix this
|
||||
```
|
||||
|
||||
OpenCode 会创建一个新分支，实现变更，并提交一个包含所有修改的 PR。
|
||||
|
||||
- **审查 PR 并进行修改**
|
||||
|
||||
在 GitHub PR 上留下以下评论：
|
||||
|
||||
```
|
||||
Delete the attachment from S3 when the note is removed /oc
|
||||
```
|
||||
|
||||
OpenCode 会实现所请求的变更并将其提交到同一个 PR 中。
|
||||
|
||||
- **审查特定代码行**
|
||||
|
||||
在 PR 的 "Files" 选项卡中直接对代码行留下评论。OpenCode 会自动检测文件、行号和 diff 上下文，从而提供精准的响应。
|
||||
|
||||
```
|
||||
[Comment on specific lines in Files tab]
|
||||
/oc add error handling here
|
||||
```
|
||||
|
||||
当你对特定代码行发表评论时，OpenCode 会接收到：
|
||||
- 正在审查的具体文件
|
||||
- 特定的代码行
|
||||
- 周围的 diff 上下文
|
||||
- 行号信息
|
||||
|
||||
这样你就可以提出更有针对性的请求，而无需手动指定文件路径或行号。
|
||||
194
packages/web/src/content/docs/zh-cn/gitlab.mdx
Normal file
194
packages/web/src/content/docs/zh-cn/gitlab.mdx
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
title: GitLab
|
||||
description: 在 GitLab issue 和合并请求中使用 OpenCode。
|
||||
---
|
||||
|
||||
OpenCode 通过 GitLab CI/CD 流水线或 GitLab Duo 与你的 GitLab 工作流集成。
|
||||
|
||||
在这两种情况下，OpenCode 都将在你的 GitLab Runner 上运行。
|
||||
|
||||
---
|
||||
|
||||
## GitLab CI
|
||||
|
||||
OpenCode 可以在常规的 GitLab 流水线中运行。你可以将其作为 [CI 组件](https://docs.gitlab.com/ee/ci/components/) 集成到流水线中。
|
||||
|
||||
这里我们使用的是社区创建的 OpenCode CI/CD 组件 — [nagyv/gitlab-opencode](https://gitlab.com/nagyv/gitlab-opencode)。
|
||||
|
||||
---
|
||||
|
||||
### 功能特性
|
||||
|
||||
- **按任务自定义配置**：使用自定义配置目录来配置 OpenCode，例如 `./config/#custom-directory`，以便为每次 OpenCode 调用启用或禁用特定功能。
|
||||
- **最小化配置**：CI 组件会在后台完成 OpenCode 的设置，你只需创建 OpenCode 配置和初始提示词即可。
|
||||
- **灵活可定制**：CI 组件支持多种输入参数来自定义其行为。
|
||||
|
||||
---
|
||||
|
||||
### 设置
|
||||
|
||||
1. 将你的 OpenCode 身份验证 JSON 作为文件类型的 CI 环境变量存储在 **Settings** > **CI/CD** > **Variables** 下。请确保将其标记为 "Masked and hidden"。
|
||||
2. 将以下内容添加到你的 `.gitlab-ci.yml` 文件中。
|
||||
|
||||
```yaml title=".gitlab-ci.yml"
|
||||
include:
|
||||
- component: $CI_SERVER_FQDN/nagyv/gitlab-opencode/opencode@2
|
||||
inputs:
|
||||
config_dir: ${CI_PROJECT_DIR}/opencode-config
|
||||
auth_json: $OPENCODE_AUTH_JSON # The variable name for your OpenCode authentication JSON
|
||||
command: optional-custom-command
|
||||
message: "Your prompt here"
|
||||
```
|
||||
|
||||
有关更多输入参数和使用场景，请[查看该组件的文档](https://gitlab.com/explore/catalog/nagyv/gitlab-opencode)。
|
||||
|
||||
---
|
||||
|
||||
## GitLab Duo
|
||||
|
||||
OpenCode 与你的 GitLab 工作流集成。
|
||||
在评论中提及 `@opencode`，OpenCode 将在你的 GitLab CI 流水线中执行任务。
|
||||
|
||||
---
|
||||
|
||||
### 功能特性
|
||||
|
||||
- **问题分类**：让 OpenCode 调查某个 issue 并为你解释。
|
||||
- **修复与实现**：让 OpenCode 修复 issue 或实现某个功能。它会创建一个新分支，并提交包含更改的合并请求。
|
||||
- **安全可靠**：OpenCode 在你的 GitLab Runner 上运行。
|
||||
|
||||
---
|
||||
|
||||
### 设置
|
||||
|
||||
OpenCode 在你的 GitLab CI/CD 流水线中运行，以下是设置所需的步骤：
|
||||
|
||||
:::tip
|
||||
请查看 [**GitLab 文档**](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) 获取最新说明。
|
||||
:::
|
||||
|
||||
1. 配置你的 GitLab 环境
|
||||
2. 设置 CI/CD
|
||||
3. 获取 AI 模型提供商的 API 密钥
|
||||
4. 创建服务账户
|
||||
5. 配置 CI/CD 变量
|
||||
6. 创建流程配置文件，以下是一个示例：
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Flow configuration</summary>
|
||||
|
||||
```yaml
|
||||
image: node:22-slim
|
||||
commands:
|
||||
- echo "Installing opencode"
|
||||
- npm install --global opencode-ai
|
||||
- echo "Installing glab"
|
||||
- export GITLAB_TOKEN=$GITLAB_TOKEN_OPENCODE
|
||||
- apt-get update --quiet && apt-get install --yes curl wget gpg git && rm --recursive --force /var/lib/apt/lists/*
|
||||
- curl --silent --show-error --location "https://raw.githubusercontent.com/upciti/wakemeops/main/assets/install_repository" | bash
|
||||
- apt-get install --yes glab
|
||||
- echo "Configuring glab"
|
||||
- echo $GITLAB_HOST
|
||||
- echo "Creating OpenCode auth configuration"
|
||||
- mkdir --parents ~/.local/share/opencode
|
||||
- |
|
||||
cat > ~/.local/share/opencode/auth.json << EOF
|
||||
{
|
||||
"anthropic": {
|
||||
"type": "api",
|
||||
"key": "$ANTHROPIC_API_KEY"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
- echo "Configuring git"
|
||||
- git config --global user.email "opencode@gitlab.com"
|
||||
- git config --global user.name "OpenCode"
|
||||
- echo "Testing glab"
|
||||
- glab issue list
|
||||
- echo "Running OpenCode"
|
||||
- |
|
||||
opencode run "
|
||||
You are an AI assistant helping with GitLab operations.
|
||||
|
||||
Context: $AI_FLOW_CONTEXT
|
||||
Task: $AI_FLOW_INPUT
|
||||
Event: $AI_FLOW_EVENT
|
||||
|
||||
Please execute the requested task using the available GitLab tools.
|
||||
Be thorough in your analysis and provide clear explanations.
|
||||
|
||||
<important>
|
||||
Please use the glab CLI to access data from GitLab. The glab CLI has already been authenticated. You can run the corresponding commands.
|
||||
|
||||
If you are asked to summarize an MR or issue or asked to provide more information then please post back a note to the MR/Issue so that the user can see it.
|
||||
You don't need to commit or push up changes, those will be done automatically based on the file changes you make.
|
||||
</important>
|
||||
"
|
||||
- git checkout --branch $CI_WORKLOAD_REF origin/$CI_WORKLOAD_REF
|
||||
- echo "Checking for git changes and pushing if any exist"
|
||||
- |
|
||||
if ! git diff --quiet || ! git diff --cached --quiet || [ --not --zero "$(git ls-files --others --exclude-standard)" ]; then
|
||||
echo "Git changes detected, adding and pushing..."
|
||||
git add .
|
||||
if git diff --cached --quiet; then
|
||||
echo "No staged changes to commit"
|
||||
else
|
||||
echo "Committing changes to branch: $CI_WORKLOAD_REF"
|
||||
git commit --message "Codex changes"
|
||||
echo "Pushing changes up to $CI_WORKLOAD_REF"
|
||||
git push https://gitlab-ci-token:$GITLAB_TOKEN@$GITLAB_HOST/gl-demo-ultimate-dev-ai-epic-17570/test-java-project.git $CI_WORKLOAD_REF
|
||||
echo "Changes successfully pushed"
|
||||
fi
|
||||
else
|
||||
echo "No git changes detected, skipping push"
|
||||
fi
|
||||
variables:
|
||||
- ANTHROPIC_API_KEY
|
||||
- GITLAB_TOKEN_OPENCODE
|
||||
- GITLAB_HOST
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
详细说明请参考 [GitLab CLI agents 文档](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/)。
|
||||
|
||||
---
|
||||
|
||||
### 示例
|
||||
|
||||
以下是在 GitLab 中使用 OpenCode 的一些示例。
|
||||
|
||||
:::tip
|
||||
你可以配置使用不同于 `@opencode` 的触发词。
|
||||
:::
|
||||
|
||||
- **解释 issue**
|
||||
|
||||
在 GitLab issue 中添加以下评论。
|
||||
|
||||
```
|
||||
@opencode explain this issue
|
||||
```
|
||||
|
||||
OpenCode 会阅读该 issue 并回复清晰的解释。
|
||||
|
||||
- **修复 issue**
|
||||
|
||||
在 GitLab issue 中输入：
|
||||
|
||||
```
|
||||
@opencode fix this
|
||||
```
|
||||
|
||||
OpenCode 会创建一个新分支，实现更改，并提交包含更改的合并请求。
|
||||
|
||||
- **审查合并请求**
|
||||
|
||||
在 GitLab 合并请求中留下以下评论。
|
||||
|
||||
```
|
||||
@opencode review this merge request
|
||||
```
|
||||
|
||||
OpenCode 会审查合并请求并提供反馈。
|
||||
199
packages/web/src/content/docs/zh-cn/go.mdx
Normal file
199
packages/web/src/content/docs/zh-cn/go.mdx
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
title: Go
|
||||
description: 低成本的开源编程模型订阅服务。
|
||||
---
|
||||
|
||||
import config from "../../../../config.mjs"
|
||||
export const console = config.console
|
||||
export const email = `mailto:${config.email}`
|
||||
|
||||
OpenCode Go 是一项低成本的订阅服务 —— **首月 5 美元**，之后 **每月 10 美元** —— 让你能够稳定地访问流行的开源编程模型。
|
||||
|
||||
Go 的工作方式与 OpenCode 中的任何其他提供商（provider）一样。订阅 OpenCode Go 后你将获得 API 密钥。它是 **完全可选** 的，并非使用 OpenCode 所必需的条件。
|
||||
|
||||
它主要为国际用户设计，模型托管在美国、欧盟和新加坡，以确保稳定的全球访问。
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
开源模型现在变得非常强大。在编程任务中，它们的性能已接近专有模型。由于许多提供商都可以提供具有竞争力的服务，它们通常要便宜得多。
|
||||
|
||||
然而，获得可靠、低延迟的访问可能很困难。各提供商在质量和可用性方面参差不齐。
|
||||
|
||||
:::tip
|
||||
我们测试了一组经过精选且与 OpenCode 配合良好的模型和提供商。
|
||||
:::
|
||||
|
||||
为了解决这个问题，我们做了以下几件事：
|
||||
|
||||
1. 我们测试了一组精选的开源模型，并与他们的团队探讨了如何以最佳方式运行它们。
|
||||
2. 随后我们与一些提供商合作，以确保正确提供这些服务。
|
||||
3. 最后，我们对模型和提供商的组合进行了基准测试（benchmark），得出了一份我们乐于推荐的列表。
|
||||
|
||||
OpenCode Go 让你能够访问这些模型，**首月只需 5 美元**，之后 **每月 10 美元**。
|
||||
|
||||
---
|
||||
|
||||
## 工作原理
|
||||
|
||||
OpenCode Go 的工作方式与 OpenCode 中的其他提供商一样。
|
||||
|
||||
1. 登录 **<a href={console}>OpenCode Zen</a>**，订阅 Go，然后复制你的 API 密钥。
|
||||
2. 在 TUI 中运行 `/connect` 命令，选择 `OpenCode Go`，然后粘贴你的 API 密钥。
|
||||
3. 在 TUI 中运行 `/models` 以查看通过 Go 可用的模型列表。
|
||||
|
||||
:::note
|
||||
每个工作空间只能有一名成员订阅 OpenCode Go。
|
||||
:::
|
||||
|
||||
当前支持的模型列表包括：
|
||||
|
||||
- **GLM-5**
|
||||
- **GLM-5.1**
|
||||
- **Kimi K2.5**
|
||||
- **Kimi K2.6**
|
||||
- **MiMo-V2.5**
|
||||
- **MiMo-V2.5-Pro**
|
||||
- **MiniMax M2.5**
|
||||
- **MiniMax M2.7**
|
||||
- **MiniMax M3**
|
||||
- **Qwen3.6 Plus**
|
||||
- **Qwen3.7 Plus**
|
||||
- **Qwen3.7 Max**
|
||||
- **DeepSeek V4 Pro**
|
||||
- **DeepSeek V4 Flash**
|
||||
|
||||
随着我们进行测试和添加新模型，该列表可能会发生变化。
|
||||
|
||||
---
|
||||
|
||||
## 使用限制
|
||||
|
||||
OpenCode Go 包含以下限制：
|
||||
|
||||
- **5 小时限制** — 12 美元使用额度
|
||||
- **每周限制** — 30 美元使用额度
|
||||
- **每月限制** — 60 美元使用额度
|
||||
|
||||
限制以美元价值定义。这意味着你的实际请求数取决于你所使用的模型。较便宜的模型（如 DeepSeek V4 Flash）允许更多请求，而较高成本的模型（如 GLM-5.1）允许较少请求。
|
||||
|
||||
下表提供了基于典型 Go 使用模式的预估请求数：
|
||||
|
||||
| Model | 每 5 小时请求数 | 每周请求数 | 每月请求数 |
|
||||
| ----------------- | --------------- | ---------- | ---------- |
|
||||
| GLM-5.1 | 880 | 2,150 | 4,300 |
|
||||
| GLM-5 | 1,150 | 2,880 | 5,750 |
|
||||
| Kimi K2.6 | 1,150 | 2,880 | 5,750 |
|
||||
| Kimi K2.5 | 1,850 | 4,630 | 9,250 |
|
||||
| MiMo-V2.5 | 30,100 | 75,200 | 150,400 |
|
||||
| MiMo-V2.5-Pro | 3,250 | 8,150 | 16,300 |
|
||||
| MiniMax M3 | 3,200 | 8,000 | 16,000 |
|
||||
| MiniMax M2.7 | 3,400 | 8,500 | 17,000 |
|
||||
| MiniMax M2.5 | 6,300 | 15,900 | 31,800 |
|
||||
| Qwen3.7 Max | 950 | 2,390 | 4,770 |
|
||||
| Qwen3.7 Plus | 4,300 | 10,800 | 21,600 |
|
||||
| Qwen3.6 Plus | 3,300 | 8,200 | 16,300 |
|
||||
| DeepSeek V4 Pro | 3,450 | 8,550 | 17,150 |
|
||||
| DeepSeek V4 Flash | 31,650 | 79,050 | 158,150 |
|
||||
|
||||
预估值基于观察到的平均请求模式：
|
||||
|
||||
- GLM-5/5.1 — 每次请求 700 个输入 token，52,000 个缓存 token，150 个输出 token
|
||||
- Kimi K2.5/K2.6 — 每次请求 870 个输入 token，55,000 个缓存 token，200 个输出 token
|
||||
- DeepSeek V4 Pro — 每次请求 750 个输入 token，82,000 个缓存 token，290 个输出 token
|
||||
- DeepSeek V4 Flash — 每次请求 790 个输入 token，68,000 个缓存 token，280 个输出 token
|
||||
- MiMo-V2.5 — 每次请求 830 个输入 token，71,500 个缓存 token，295 个输出 token
|
||||
- MiMo-V2.5-Pro — 每次请求 790 个输入 token，86,000 个缓存 token，305 个输出 token
|
||||
- MiniMax M3 — 每次请求 510 个输入 token，56,000 个缓存 token，190 个输出 token
|
||||
- MiniMax M2.7/M2.5 — 每次请求 300 个输入 token，55,000 个缓存 token，125 个输出 token
|
||||
- Qwen3.7 Max — 每次请求 420 个输入 token，66,000 个缓存 token，200 个输出 token
|
||||
- Qwen3.7 Plus — 每次请求 500 个输入 token，57,000 个缓存 token，190 个输出 token
|
||||
- Qwen3.6 Plus — 每次请求 500 个输入 token，57,000 个缓存 token，190 个输出 token
|
||||
|
||||
预估值还基于以下每 1M tokens 的价格：
|
||||
|
||||
| 模型 | 输入 | 输出 | 缓存读取 | 缓存写入 |
|
||||
| ---------------------------- | ----- | ----- | -------- | -------- |
|
||||
| GLM-5.1 | $1.40 | $4.40 | $0.26 | - |
|
||||
| GLM-5 | $1.00 | $3.20 | $0.20 | - |
|
||||
| Kimi K2.6 | $0.95 | $4.00 | $0.16 | - |
|
||||
| Kimi K2.5 | $0.60 | $3.00 | $0.10 | - |
|
||||
| MiMo V2.5 | $0.14 | $0.28 | $0.0028 | - |
|
||||
| MiMo V2.5 Pro | $1.74 | $3.48 | $0.0145 | - |
|
||||
| MiniMax M3 | $0.30 | $1.20 | $0.06 | - |
|
||||
| MiniMax M2.7 | $0.30 | $1.20 | $0.06 | $0.375 |
|
||||
| MiniMax M2.5 | $0.30 | $1.20 | $0.06 | $0.375 |
|
||||
| Qwen3.7 Max | $2.50 | $7.50 | $0.50 | $3.125 |
|
||||
| Qwen3.7 Plus (≤ 256K tokens) | $0.40 | $1.60 | $0.04 | $0.50 |
|
||||
| Qwen3.7 Plus (> 256K tokens) | $1.20 | $4.80 | $0.12 | $1.50 |
|
||||
| Qwen3.6 Plus (≤ 256K tokens) | $0.50 | $3.00 | $0.05 | $0.625 |
|
||||
| Qwen3.6 Plus (> 256K tokens) | $2.00 | $6.00 | $0.20 | $2.50 |
|
||||
| DeepSeek V4 Pro | $1.74 | $3.48 | $0.0145 | - |
|
||||
| DeepSeek V4 Flash | $0.14 | $0.28 | $0.0028 | - |
|
||||
|
||||
你可以在 **<a href={console}>控制台</a>** 中跟踪你当前的使用情况。
|
||||
|
||||
:::tip
|
||||
如果你达到了使用限制，你可以继续使用免费模型。
|
||||
:::
|
||||
|
||||
使用限制可能会随着我们从早期使用和反馈中学习而发生变化。
|
||||
|
||||
---
|
||||
|
||||
### 超出限制的使用
|
||||
|
||||
如果你的 Zen 余额中还有积分，可以在控制台中启用 **使用余额（Use balance）** 选项。启用后，当你达到使用限制时，Go 会回退使用你的 Zen 余额，而不是拦截请求。
|
||||
|
||||
---
|
||||
|
||||
## API 端点
|
||||
|
||||
你也可以通过以下 API 端点访问 Go 模型。
|
||||
|
||||
| 模型 | 模型 ID | 端点 | AI SDK 包 |
|
||||
| ----------------- | ----------------- | ------------------------------------------------ | --------------------------- |
|
||||
| GLM-5.1 | glm-5.1 | `https://opencode.ai/zen/go/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| GLM-5 | glm-5 | `https://opencode.ai/zen/go/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Kimi K2.5 | kimi-k2.5 | `https://opencode.ai/zen/go/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Kimi K2.6 | kimi-k2.6 | `https://opencode.ai/zen/go/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| DeepSeek V4 Pro | deepseek-v4-pro | `https://opencode.ai/zen/go/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| DeepSeek V4 Flash | deepseek-v4-flash | `https://opencode.ai/zen/go/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| MiMo-V2.5 | mimo-v2.5 | `https://opencode.ai/zen/go/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| MiMo-V2.5-Pro | mimo-v2.5-pro | `https://opencode.ai/zen/go/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| MiniMax M3 | minimax-m3 | `https://opencode.ai/zen/go/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| MiniMax M2.7 | minimax-m2.7 | `https://opencode.ai/zen/go/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| MiniMax M2.5 | minimax-m2.5 | `https://opencode.ai/zen/go/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Qwen3.7 Max | qwen3.7-max | `https://opencode.ai/zen/go/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Qwen3.7 Plus | qwen3.7-plus | `https://opencode.ai/zen/go/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Qwen3.6 Plus | qwen3.6-plus | `https://opencode.ai/zen/go/v1/messages` | `@ai-sdk/anthropic` |
|
||||
|
||||
你 OpenCode 配置中的 [模型 ID](/docs/config/#models) 使用 `opencode-go/<model-id>` 格式。例如，对于 Kimi K2.6，你将在配置中使用 `opencode-go/kimi-k2.6`。
|
||||
|
||||
---
|
||||
|
||||
### 模型
|
||||
|
||||
你可以从以下地址获取可用模型及其元数据的完整列表：
|
||||
|
||||
```
|
||||
https://opencode.ai/zen/go/v1/models
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 隐私保护
|
||||
|
||||
该方案主要面向国际用户，模型托管在 US、EU 和 Singapore，以提供稳定的全球访问。我们的提供商遵循零保留政策，不会将您的数据用于模型训练。
|
||||
|
||||
---
|
||||
|
||||
## 目标
|
||||
|
||||
我们创建 OpenCode Go 的目的是：
|
||||
|
||||
1. 通过低成本订阅让更多人能够 **无门槛地** 使用 AI 编程。
|
||||
2. 为最佳开源编程模型提供 **可靠的** 访问。
|
||||
3. 精选经过 **测试和基准评估**，适合编程 Agent 使用的模型。
|
||||
4. **无锁定（no lock-in）**，允许你与 OpenCode 一起使用任何其他提供商。
|
||||
48
packages/web/src/content/docs/zh-cn/ide.mdx
Normal file
48
packages/web/src/content/docs/zh-cn/ide.mdx
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: IDE
|
||||
description: 适用于 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 终端会话，即使已有会话在运行也会新建。你也可以点击界面中的 OpenCode 按钮。
|
||||
- **上下文感知**：自动将当前选中内容或标签页共享给 OpenCode。
|
||||
- **文件引用快捷键**：使用 `Cmd+Option+K`（Mac）或 `Alt+Ctrl+K`（Linux/Windows）插入文件引用。例如 `@File#L37-42`。
|
||||
|
||||
---
|
||||
|
||||
## 安装
|
||||
|
||||
在 VS Code 及其常见分支（如 Cursor、Windsurf、VSCodium）上安装 OpenCode：
|
||||
|
||||
1. 打开 VS Code
|
||||
2. 打开集成终端
|
||||
3. 运行 `opencode`——扩展将自动安装
|
||||
|
||||
如果你希望在 TUI 中执行 `/editor` 或 `/export` 时使用自己的 IDE，需要设置 `export EDITOR="code --wait"`。[了解更多](/docs/tui/#editor-setup)。
|
||||
|
||||
---
|
||||
|
||||
### 手动安装
|
||||
|
||||
在扩展商店中搜索 **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 有权限安装扩展
|
||||
343
packages/web/src/content/docs/zh-cn/index.mdx
Normal file
343
packages/web/src/content/docs/zh-cn/index.mdx
Normal file
@@ -0,0 +1,343 @@
|
||||
---
|
||||
title: 简介
|
||||
description: 开始使用 OpenCode。
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from "@astrojs/starlight/components"
|
||||
import config from "../../../../config.mjs"
|
||||
export const console = config.console
|
||||
|
||||
[**OpenCode**](/) 是一个开源的 AI 编码代理。它提供终端界面、桌面应用和 IDE 扩展等多种使用方式。
|
||||
|
||||
|
||||
|
||||
让我们开始吧。
|
||||
|
||||
---
|
||||
|
||||
#### 前提条件
|
||||
|
||||
要在终端中使用 OpenCode，你需要：
|
||||
|
||||
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 密钥。
|
||||
|
||||
---
|
||||
|
||||
## 安装
|
||||
|
||||
安装 OpenCode 最简单的方法是通过安装脚本。
|
||||
|
||||
```bash
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
```
|
||||
|
||||
你也可以使用以下方式安装：
|
||||
|
||||
- **使用 Node.js**
|
||||
|
||||
<Tabs>
|
||||
|
||||
<TabItem label="npm">
|
||||
```bash
|
||||
npm install -g opencode-ai
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Bun">
|
||||
```bash
|
||||
bun install -g opencode-ai
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="pnpm">
|
||||
```bash
|
||||
pnpm install -g opencode-ai
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Yarn">
|
||||
```bash
|
||||
yarn global add opencode-ai
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
- **在 macOS 和 Linux 上使用 Homebrew**
|
||||
|
||||
```bash
|
||||
brew install anomalyco/tap/opencode
|
||||
```
|
||||
|
||||
> 我们推荐使用 OpenCode tap 以获取最新版本。官方的 `brew install opencode` formula 由 Homebrew 团队维护，更新频率较低。
|
||||
|
||||
- **在 Arch Linux 上安装**
|
||||
|
||||
```bash
|
||||
sudo pacman -S opencode # Arch Linux (Stable)
|
||||
paru -S opencode-bin # Arch Linux (Latest from AUR)
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
:::tip[推荐：使用 WSL]
|
||||
为了在 Windows 上获得最佳体验，我们推荐使用 [Windows Subsystem for Linux (WSL)](/docs/windows-wsl)。它提供更好的性能，并完全兼容 OpenCode 的所有功能。
|
||||
:::
|
||||
|
||||
- **使用 Chocolatey**
|
||||
|
||||
```bash
|
||||
choco install opencode
|
||||
```
|
||||
|
||||
- **使用 Scoop**
|
||||
|
||||
```bash
|
||||
scoop install opencode
|
||||
```
|
||||
|
||||
- **使用 NPM**
|
||||
|
||||
```bash
|
||||
npm install -g opencode-ai
|
||||
```
|
||||
|
||||
- **使用 Mise**
|
||||
|
||||
```bash
|
||||
mise use -g github:anomalyco/opencode
|
||||
```
|
||||
|
||||
- **使用 Docker**
|
||||
|
||||
```bash
|
||||
docker run -it --rm ghcr.io/anomalyco/opencode
|
||||
```
|
||||
|
||||
在 Windows 上通过 Bun 安装 OpenCode 的支持目前正在开发中。
|
||||
|
||||
你也可以从 [Releases](https://github.com/anomalyco/opencode/releases) 页面直接下载二进制文件。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
通过 OpenCode，你可以配置 API 密钥来使用任意 LLM 提供商。
|
||||
|
||||
如果你刚开始接触 LLM 提供商，我们推荐使用 [OpenCode Zen](/docs/zen)。这是一组经过 OpenCode 团队测试和验证的精选模型。
|
||||
|
||||
1. 在 TUI 中运行 `/connect` 命令，选择 opencode，然后前往 [opencode.ai/auth](https://opencode.ai/auth)。
|
||||
|
||||
```txt
|
||||
/connect
|
||||
```
|
||||
|
||||
2. 登录并添加账单信息，然后复制你的 API 密钥。
|
||||
|
||||
3. 粘贴你的 API 密钥。
|
||||
|
||||
```txt
|
||||
┌ API key
|
||||
│
|
||||
│
|
||||
└ enter
|
||||
```
|
||||
|
||||
你也可以选择其他提供商。[了解更多](/docs/providers#directory)。
|
||||
|
||||
---
|
||||
|
||||
## 初始化
|
||||
|
||||
配置好提供商后，导航到你想要处理的项目目录。
|
||||
|
||||
```bash
|
||||
cd /path/to/project
|
||||
```
|
||||
|
||||
然后运行 OpenCode。
|
||||
|
||||
```bash
|
||||
opencode
|
||||
```
|
||||
|
||||
接下来，运行以下命令为项目初始化 OpenCode。
|
||||
|
||||
```bash frame="none"
|
||||
/init
|
||||
```
|
||||
|
||||
OpenCode 会分析你的项目并在项目根目录创建一个 `AGENTS.md` 文件。
|
||||
|
||||
:::tip
|
||||
你应该将项目的 `AGENTS.md` 文件提交到 Git。
|
||||
:::
|
||||
|
||||
这有助于 OpenCode 理解项目结构和编码规范。
|
||||
|
||||
---
|
||||
|
||||
## 使用
|
||||
|
||||
现在你已经准备好使用 OpenCode 来处理项目了，尽管提问吧！
|
||||
|
||||
如果你是第一次使用 AI 编码代理，以下示例可能会对你有所帮助。
|
||||
|
||||
---
|
||||
|
||||
### 提问
|
||||
|
||||
你可以让 OpenCode 为你讲解代码库。
|
||||
|
||||
:::tip
|
||||
使用 `@` 键可以模糊搜索项目中的文件。
|
||||
:::
|
||||
|
||||
```txt frame="none" "@packages/functions/src/api/index.ts"
|
||||
How is authentication handled in @packages/functions/src/api/index.ts
|
||||
```
|
||||
|
||||
当你遇到不熟悉的代码时，这个功能非常有用。
|
||||
|
||||
---
|
||||
|
||||
### 添加功能
|
||||
|
||||
你可以让 OpenCode 为项目添加新功能。不过我们建议先让它制定一个计划。
|
||||
|
||||
1. **制定计划**
|
||||
|
||||
OpenCode 有一个*计划模式*，该模式下它不会进行任何修改，而是建议*如何*实现该功能。
|
||||
|
||||
使用 **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.
|
||||
Then create a screen that shows all the recently deleted notes.
|
||||
From this screen, the user can undelete a note or permanently delete it.
|
||||
```
|
||||
|
||||
你需要提供足够的细节，让 OpenCode 理解你的需求。可以把它当作团队中的一名初级开发者来沟通。
|
||||
|
||||
:::tip
|
||||
为 OpenCode 提供充足的上下文和示例，帮助它理解你的需求。
|
||||
:::
|
||||
|
||||
2. **迭代计划**
|
||||
|
||||
当它给出计划后，你可以提供反馈或补充更多细节。
|
||||
|
||||
```txt frame="none"
|
||||
We'd like to design this new screen using a design I've used before.
|
||||
[Image #1] Take a look at this image and use it as a reference.
|
||||
```
|
||||
|
||||
:::tip
|
||||
将图片拖放到终端中即可将其添加到提示词中。
|
||||
:::
|
||||
|
||||
OpenCode 可以扫描你提供的图片并将其添加到提示词中。只需将图片拖放到终端窗口即可。
|
||||
|
||||
3. **构建功能**
|
||||
|
||||
当你对计划满意后，再次按 **Tab** 键切换回*构建模式*。
|
||||
|
||||
```bash frame="none"
|
||||
<TAB>
|
||||
```
|
||||
|
||||
然后让它开始实施。
|
||||
|
||||
```bash frame="none"
|
||||
Sounds good! Go ahead and make the changes.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 直接修改
|
||||
|
||||
对于比较简单的修改，你可以直接让 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
|
||||
handled in the /notes route in @packages/functions/src/notes.ts and implement
|
||||
the same logic in @packages/functions/src/settings.ts
|
||||
```
|
||||
|
||||
请确保提供足够的细节，以便 OpenCode 做出正确的修改。
|
||||
|
||||
---
|
||||
|
||||
### 撤销修改
|
||||
|
||||
假设你让 OpenCode 做了一些修改。
|
||||
|
||||
```txt frame="none" "@packages/functions/src/api/index.ts"
|
||||
Can you refactor the function in @packages/functions/src/api/index.ts?
|
||||
```
|
||||
|
||||
但你发现结果不是你想要的。你**可以使用** `/undo` 命令来撤销修改。
|
||||
|
||||
```bash frame="none"
|
||||
/undo
|
||||
```
|
||||
|
||||
OpenCode 会还原所做的修改，并重新显示你之前的消息。
|
||||
|
||||
```txt frame="none" "@packages/functions/src/api/index.ts"
|
||||
Can you refactor the function in @packages/functions/src/api/index.ts?
|
||||
```
|
||||
|
||||
你可以调整提示词，让 OpenCode 重新尝试。
|
||||
|
||||
:::tip
|
||||
你可以多次运行 `/undo` 来撤销多次修改。
|
||||
:::
|
||||
|
||||
你也**可以使用** `/redo` 命令来重做修改。
|
||||
|
||||
```bash frame="none"
|
||||
/redo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 分享
|
||||
|
||||
你与 OpenCode 的对话可以[与团队分享](/docs/share)。
|
||||
|
||||
```bash frame="none"
|
||||
/share
|
||||
```
|
||||
|
||||
这会生成当前对话的链接并复制到剪贴板。
|
||||
|
||||
:::note
|
||||
对话默认不会被分享。
|
||||
:::
|
||||
|
||||
这是一个与 OpenCode 的[示例对话](https://opencode.ai/s/4XP1fce5)。
|
||||
|
||||
---
|
||||
|
||||
## 个性化
|
||||
|
||||
以上就是全部内容！你现在已经是 OpenCode 的使用高手了。
|
||||
|
||||
要让它更符合你的习惯，我们推荐[选择一个主题](/docs/themes)、[自定义快捷键](/docs/keybinds)、[配置代码格式化工具](/docs/formatters)、[创建自定义命令](/docs/commands)，或者探索 [OpenCode 配置](/docs/config)。
|
||||
194
packages/web/src/content/docs/zh-cn/keybinds.mdx
Normal file
194
packages/web/src/content/docs/zh-cn/keybinds.mdx
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
title: 快捷键
|
||||
description: 自定义您的快捷键。
|
||||
---
|
||||
|
||||
OpenCode 提供了一系列快捷键，您可以通过 `tui.json` 进行自定义。
|
||||
|
||||
```json title="tui.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/tui.json",
|
||||
"keybinds": {
|
||||
"leader": "ctrl+x",
|
||||
"app_exit": "ctrl+c,ctrl+d,<leader>q",
|
||||
"editor_open": "<leader>e",
|
||||
"theme_list": "<leader>t",
|
||||
"sidebar_toggle": "<leader>b",
|
||||
"scrollbar_toggle": "none",
|
||||
"username_toggle": "none",
|
||||
"status_view": "<leader>s",
|
||||
"tool_details": "none",
|
||||
"session_export": "<leader>x",
|
||||
"session_new": "<leader>n",
|
||||
"session_list": "<leader>l",
|
||||
"session_timeline": "<leader>g",
|
||||
"session_fork": "none",
|
||||
"session_rename": "none",
|
||||
"session_share": "none",
|
||||
"session_unshare": "none",
|
||||
"session_interrupt": "escape",
|
||||
"session_compact": "<leader>c",
|
||||
"session_child_first": "<leader>down",
|
||||
"session_child_cycle": "<leader>right",
|
||||
"session_child_cycle_reverse": "<leader>left",
|
||||
"session_parent": "<leader>up",
|
||||
"messages_page_up": "pageup,ctrl+alt+b",
|
||||
"messages_page_down": "pagedown,ctrl+alt+f",
|
||||
"messages_line_up": "ctrl+alt+y",
|
||||
"messages_line_down": "ctrl+alt+e",
|
||||
"messages_half_page_up": "ctrl+alt+u",
|
||||
"messages_half_page_down": "ctrl+alt+d",
|
||||
"messages_first": "ctrl+g,home",
|
||||
"messages_last": "ctrl+alt+g,end",
|
||||
"messages_next": "none",
|
||||
"messages_previous": "none",
|
||||
"messages_copy": "<leader>y",
|
||||
"messages_undo": "<leader>u",
|
||||
"messages_redo": "<leader>r",
|
||||
"messages_last_user": "none",
|
||||
"messages_toggle_conceal": "<leader>h",
|
||||
"model_list": "<leader>m",
|
||||
"model_cycle_recent": "f2",
|
||||
"model_cycle_recent_reverse": "shift+f2",
|
||||
"model_cycle_favorite": "none",
|
||||
"model_cycle_favorite_reverse": "none",
|
||||
"variant_cycle": "ctrl+t",
|
||||
"variant_list": "none",
|
||||
"command_list": "ctrl+p",
|
||||
"agent_list": "<leader>a",
|
||||
"agent_cycle": "tab",
|
||||
"agent_cycle_reverse": "shift+tab",
|
||||
"input_clear": "ctrl+c",
|
||||
"input_paste": "ctrl+v",
|
||||
"input_submit": "return",
|
||||
"input_newline": "shift+return,ctrl+return,alt+return,ctrl+j",
|
||||
"input_move_left": "left,ctrl+b",
|
||||
"input_move_right": "right,ctrl+f",
|
||||
"input_move_up": "up",
|
||||
"input_move_down": "down",
|
||||
"input_select_left": "shift+left",
|
||||
"input_select_right": "shift+right",
|
||||
"input_select_up": "shift+up",
|
||||
"input_select_down": "shift+down",
|
||||
"input_line_home": "ctrl+a",
|
||||
"input_line_end": "ctrl+e",
|
||||
"input_select_line_home": "ctrl+shift+a",
|
||||
"input_select_line_end": "ctrl+shift+e",
|
||||
"input_visual_line_home": "alt+a",
|
||||
"input_visual_line_end": "alt+e",
|
||||
"input_select_visual_line_home": "alt+shift+a",
|
||||
"input_select_visual_line_end": "alt+shift+e",
|
||||
"input_buffer_home": "home",
|
||||
"input_buffer_end": "end",
|
||||
"input_select_buffer_home": "shift+home",
|
||||
"input_select_buffer_end": "shift+end",
|
||||
"input_delete_line": "ctrl+shift+d",
|
||||
"input_delete_to_line_end": "ctrl+k",
|
||||
"input_delete_to_line_start": "ctrl+u",
|
||||
"input_backspace": "backspace,shift+backspace",
|
||||
"input_delete": "ctrl+d,delete,shift+delete",
|
||||
"input_undo": "ctrl+-,super+z",
|
||||
"input_redo": "ctrl+.,super+shift+z",
|
||||
"input_word_forward": "alt+f,alt+right,ctrl+right",
|
||||
"input_word_backward": "alt+b,alt+left,ctrl+left",
|
||||
"input_select_word_forward": "alt+shift+f,alt+shift+right",
|
||||
"input_select_word_backward": "alt+shift+b,alt+shift+left",
|
||||
"input_delete_word_forward": "alt+d,alt+delete,ctrl+delete",
|
||||
"input_delete_word_backward": "ctrl+w,ctrl+backspace,alt+backspace",
|
||||
"history_previous": "up",
|
||||
"history_next": "down",
|
||||
"terminal_suspend": "ctrl+z",
|
||||
"terminal_title_toggle": "none",
|
||||
"tips_toggle": "<leader>h",
|
||||
"display_thinking": "none"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前导键
|
||||
|
||||
OpenCode 的大多数快捷键使用 `leader`（前导键）。这可以避免与终端中的其他快捷键冲突。
|
||||
|
||||
默认情况下，`ctrl+x` 是前导键，大多数操作需要您先按下前导键，然后再按对应的快捷键。例如，要新建一个会话，请先按 `ctrl+x`，然后按 `n`。
|
||||
|
||||
您不一定需要使用前导键来设置快捷键，但我们建议您这样做。
|
||||
|
||||
---
|
||||
|
||||
## 禁用快捷键
|
||||
|
||||
您可以通过将键值添加到 `tui.json` 并设置为 "none" 来禁用某个快捷键。
|
||||
|
||||
```json title="tui.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/tui.json",
|
||||
"keybinds": {
|
||||
"session_compact": "none"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 桌面版提示词输入快捷键
|
||||
|
||||
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` | 取消弹出窗口 / 中止正在运行的响应 |
|
||||
|
||||
---
|
||||
|
||||
## Shift+Enter
|
||||
|
||||
某些终端默认不会发送带修饰键的 Enter 键。您可能需要配置终端将 `Shift+Enter` 作为转义序列发送。
|
||||
|
||||
### Windows Terminal
|
||||
|
||||
打开您的 `settings.json` 文件，路径为：
|
||||
|
||||
```
|
||||
%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
|
||||
```
|
||||
|
||||
将以下内容添加到根级 `actions` 数组中：
|
||||
|
||||
```json
|
||||
"actions": [
|
||||
{
|
||||
"command": {
|
||||
"action": "sendInput",
|
||||
"input": "\u001b[13;2u"
|
||||
},
|
||||
"id": "User.sendInput.ShiftEnterCustom"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
将以下内容添加到根级 `keybindings` 数组中：
|
||||
|
||||
```json
|
||||
"keybindings": [
|
||||
{
|
||||
"keys": "shift+enter",
|
||||
"id": "User.sendInput.ShiftEnterCustom"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
保存文件并重启 Windows Terminal，或打开一个新标签页。
|
||||
208
packages/web/src/content/docs/zh-cn/lsp.mdx
Normal file
208
packages/web/src/content/docs/zh-cn/lsp.mdx
Normal file
@@ -0,0 +1,208 @@
|
||||
---
|
||||
title: LSP 服务器
|
||||
description: OpenCode 与你的 LSP 服务器集成。
|
||||
---
|
||||
|
||||
OpenCode 可以与语言服务器协议（LSP）服务器集成，将诊断信息作为 agent 的反馈。
|
||||
|
||||
---
|
||||
|
||||
## 内置支持
|
||||
|
||||
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+)` |
|
||||
| julials | .jl | 需要安装 `julia` and `LanguageServer.jl` |
|
||||
| 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 默认关闭。启用后，当检测到上述文件扩展名且满足相应要求时，服务器会启动。
|
||||
|
||||
:::note
|
||||
你可以将 `OPENCODE_DISABLE_LSP_DOWNLOAD` 环境变量设置为 `true` 来禁用 LSP 服务器的自动下载。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 工作原理
|
||||
|
||||
启用 LSP 且 opencode 打开文件时，它会：
|
||||
|
||||
1. 将文件扩展名与所有已启用的 LSP 服务器进行匹配。
|
||||
2. 如果对应的 LSP 服务器尚未运行，则自动启动它。
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
LSP 可以通过语言服务器诊断帮助 agent 发现并修复问题。这对某些项目很有用，但并不总是带来净收益。
|
||||
|
||||
语言服务器可能与项目不同步、占用较多内存、随版本或项目表现不同，并拖慢 agent 工作流。在许多项目中，更好的做法是让 agent 直接运行 lint、typecheck 或其他诊断类 CLI 工具，这样错误会进入 agent 循环，同时避免这些权衡。将这些命令记录在 `AGENTS.md` 或 skills 等指令文件中，让 agent 知道该运行什么。当你的项目能从额外的语言服务器反馈中受益时再启用 LSP。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
你可以通过 opencode 配置文件中的 `lsp` 部分来启用并自定义 LSP 服务器。
|
||||
|
||||
要启用所有内置 LSP 服务器，请将 `lsp` 设置为 `true`。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"lsp": true
|
||||
}
|
||||
```
|
||||
|
||||
使用对象可以在保持内置服务器启用的同时配置覆盖项或自定义服务器。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"lsp": {}
|
||||
}
|
||||
```
|
||||
|
||||
每个 LSP 服务器支持以下配置项：
|
||||
|
||||
| 属性 | 类型 | 描述 |
|
||||
| ---------------- | -------- | --------------------------------- |
|
||||
| `disabled` | boolean | 设置为 `true` 可禁用该 LSP 服务器 |
|
||||
| `command` | string[] | 启动 LSP 服务器的命令 |
|
||||
| `extensions` | string[] | 该 LSP 服务器需要处理的文件扩展名 |
|
||||
| `env` | object | 启动服务器时设置的环境变量 |
|
||||
| `initialization` | object | 发送给 LSP 服务器的初始化选项 |
|
||||
|
||||
下面来看一些示例。
|
||||
|
||||
---
|
||||
|
||||
### 环境变量
|
||||
|
||||
使用 `env` 属性在启动 LSP 服务器时设置环境变量：
|
||||
|
||||
```json title="opencode.json" {5-7}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"lsp": {
|
||||
"rust": {
|
||||
"env": {
|
||||
"RUST_LOG": "debug"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 初始化选项
|
||||
|
||||
使用 `initialization` 属性向 LSP 服务器传递初始化选项。这些是在 LSP `initialize` 请求期间发送的服务器特定设置：
|
||||
|
||||
```json title="opencode.json" {5-9}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"lsp": {
|
||||
"typescript": {
|
||||
"initialization": {
|
||||
"preferences": {
|
||||
"importModuleSpecifierPreference": "relative"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
初始化选项因 LSP 服务器而异。请查阅你所使用的 LSP 服务器的文档以了解可用选项。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### 禁用 LSP 服务器
|
||||
|
||||
如果省略 `lsp`，所有 LSP 服务器都会被禁用。如果另一个配置启用了 LSP，可将 `lsp` 设置为 `false` 来禁用所有 LSP 服务器：
|
||||
|
||||
```json title="opencode.json" {3}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"lsp": false
|
||||
}
|
||||
```
|
||||
|
||||
要禁用**特定的** LSP 服务器，将 `disabled` 设置为 `true`：
|
||||
|
||||
```json title="opencode.json" {5}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"lsp": {
|
||||
"typescript": {
|
||||
"disabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 自定义 LSP 服务器
|
||||
|
||||
你可以通过指定命令和文件扩展名来添加自定义 LSP 服务器：
|
||||
|
||||
```json title="opencode.json" {4-7}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"lsp": {
|
||||
"custom-lsp": {
|
||||
"command": ["custom-lsp-server", "--stdio"],
|
||||
"extensions": [".custom"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 补充信息
|
||||
|
||||
### PHP Intelephense
|
||||
|
||||
PHP Intelephense 通过许可证密钥提供高级功能。你可以将许可证密钥单独放在以下路径的文本文件中：
|
||||
|
||||
- macOS/Linux：`$HOME/intelephense/license.txt`
|
||||
- Windows：`%USERPROFILE%/intelephense/license.txt`
|
||||
|
||||
该文件应仅包含许可证密钥，不要添加其他任何内容。
|
||||
511
packages/web/src/content/docs/zh-cn/mcp-servers.mdx
Normal file
511
packages/web/src/content/docs/zh-cn/mcp-servers.mdx
Normal file
@@ -0,0 +1,511 @@
|
||||
---
|
||||
title: MCP 服务器
|
||||
description: 添加本地和远程 MCP 工具。
|
||||
---
|
||||
|
||||
你可以通过 _Model Context Protocol_（MCP）为 OpenCode 添加外部工具。OpenCode 同时支持本地和远程服务器。
|
||||
|
||||
添加后，MCP 工具会自动与内置工具一起提供给 LLM 使用。
|
||||
|
||||
---
|
||||
|
||||
#### 注意事项
|
||||
|
||||
使用 MCP 服务器时，它会占用上下文空间。如果你启用了大量工具，上下文消耗会迅速增加。因此，我们建议谨慎选择要使用的 MCP 服务器。
|
||||
|
||||
:::tip
|
||||
MCP 服务器会占用你的上下文空间，所以请谨慎选择启用哪些服务器。
|
||||
:::
|
||||
|
||||
某些 MCP 服务器（例如 GitHub MCP 服务器）往往会消耗大量 Token，很容易超出上下文限制。
|
||||
|
||||
---
|
||||
|
||||
## 启用
|
||||
|
||||
你可以在 [OpenCode 配置](https://opencode.ai/docs/config/)的 `mcp` 字段下定义 MCP 服务器。为每个 MCP 指定一个唯一的名称，在提示词中可以通过该名称来引用对应的 MCP。
|
||||
|
||||
```jsonc title="opencode.jsonc" {6}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"name-of-mcp-server": {
|
||||
// ...
|
||||
"enabled": true,
|
||||
},
|
||||
"name-of-other-mcp-server": {
|
||||
// ...
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
你也可以将 `enabled` 设置为 `false` 来禁用某个服务器。当你想临时禁用某个服务器而不将其从配置中移除时，这个选项非常有用。
|
||||
|
||||
---
|
||||
|
||||
### 覆盖远程默认值
|
||||
|
||||
组织可以通过其 `.well-known/opencode` 端点提供默认的 MCP 服务器。这些服务器可能默认处于禁用状态，允许用户按需启用。
|
||||
|
||||
要启用组织远程配置中的某个服务器，请在本地配置中添加该服务器并设置 `enabled: true`：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"jira": {
|
||||
"type": "remote",
|
||||
"url": "https://jira.example.com/mcp",
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
本地配置值会覆盖远程默认值。详情请参阅[配置优先级](/docs/config#precedence-order)。
|
||||
|
||||
---
|
||||
|
||||
## 本地
|
||||
|
||||
通过在 MCP 对象中将 `type` 设置为 `"local"` 来添加本地 MCP 服务器。
|
||||
|
||||
```jsonc title="opencode.jsonc" {15}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-local-mcp-server": {
|
||||
"type": "local",
|
||||
// Or ["bun", "x", "my-mcp-command"]
|
||||
"command": ["npx", "-y", "my-mcp-command"],
|
||||
"enabled": true,
|
||||
"environment": {
|
||||
"MY_ENV_VAR": "my_env_var_value",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`command` 用于指定本地 MCP 服务器的启动命令。你还可以传入一组环境变量。
|
||||
|
||||
例如，以下是添加测试用的 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 服务器的方法。
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"mcp_everything": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
要使用它，可以在提示词中添加 `use the mcp_everything tool`。
|
||||
|
||||
```txt "mcp_everything"
|
||||
use the mcp_everything tool to add the number 3 and 4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 选项
|
||||
|
||||
以下是配置本地 MCP 服务器的所有选项。
|
||||
|
||||
| 选项 | 类型 | 必填 | 描述 |
|
||||
| ------------- | ------ | ---- | ----------------------------------------------------------------- |
|
||||
| `type` | 字符串 | 是 | MCP 服务器连接类型，必须为 `"local"`。 |
|
||||
| `command` | 数组 | 是 | 运行 MCP 服务器的命令及参数。 |
|
||||
| `environment` | 对象 | | 运行服务器时设置的环境变量。 |
|
||||
| `enabled` | 布尔值 | | 启动时启用或禁用该 MCP 服务器。 |
|
||||
| `timeout` | 数字 | | 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。 |
|
||||
|
||||
---
|
||||
|
||||
## 远程
|
||||
|
||||
通过将 `type` 设置为 `"remote"` 来添加远程 MCP 服务器。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-remote-mcp": {
|
||||
"type": "remote",
|
||||
"url": "https://my-mcp-server.com",
|
||||
"enabled": true,
|
||||
"headers": {
|
||||
"Authorization": "Bearer MY_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`url` 是远程 MCP 服务器的地址，通过 `headers` 选项可以传入一组请求头。
|
||||
|
||||
---
|
||||
|
||||
#### 选项
|
||||
|
||||
| 选项 | 类型 | 必填 | 描述 |
|
||||
| --------- | ------ | ---- | ----------------------------------------------------------------- |
|
||||
| `type` | 字符串 | 是 | MCP 服务器连接类型，必须为 `"remote"`。 |
|
||||
| `url` | 字符串 | 是 | 远程 MCP 服务器的 URL。 |
|
||||
| `enabled` | 布尔值 | | 启动时启用或禁用该 MCP 服务器。 |
|
||||
| `headers` | 对象 | | 随请求发送的请求头。 |
|
||||
| `oauth` | 对象 | | OAuth 身份验证配置。详见下方 [OAuth](#oauth) 部分。 |
|
||||
| `timeout` | 数字 | | 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。 |
|
||||
|
||||
---
|
||||
|
||||
## OAuth
|
||||
|
||||
OpenCode 会自动处理远程 MCP 服务器的 OAuth 身份验证。当服务器需要身份验证时，OpenCode 将：
|
||||
|
||||
1. 检测 401 响应并启动 OAuth 流程
|
||||
2. 在服务器支持的情况下使用**动态客户端注册（RFC 7591）**
|
||||
3. 安全地存储 Token 以供后续请求使用
|
||||
|
||||
---
|
||||
|
||||
### 自动认证
|
||||
|
||||
对于大多数支持 OAuth 的 MCP 服务器，无需特殊配置。只需配置远程服务器即可：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-oauth-server": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.example.com/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果服务器需要身份验证，OpenCode 会在你首次使用时提示你进行认证。你也可以使用 `opencode mcp auth <server-name>` [手动触发认证流程](#authenticating)。
|
||||
|
||||
---
|
||||
|
||||
### 预注册
|
||||
|
||||
如果你已经从 MCP 服务器提供商处获得了客户端凭据，可以直接配置：
|
||||
|
||||
```json title="opencode.json" {7-11}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-oauth-server": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.example.com/mcp",
|
||||
"oauth": {
|
||||
"clientId": "{env:MY_MCP_CLIENT_ID}",
|
||||
"clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
|
||||
"scope": "tools:read tools:execute"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 身份验证
|
||||
|
||||
你可以手动触发身份验证或管理凭据。
|
||||
|
||||
对特定 MCP 服务器进行身份验证：
|
||||
|
||||
```bash
|
||||
opencode mcp auth my-oauth-server
|
||||
```
|
||||
|
||||
列出所有 MCP 服务器及其认证状态：
|
||||
|
||||
```bash
|
||||
opencode mcp list
|
||||
```
|
||||
|
||||
删除已存储的凭据：
|
||||
|
||||
```bash
|
||||
opencode mcp logout my-oauth-server
|
||||
```
|
||||
|
||||
`mcp auth` 命令会打开浏览器进行授权。授权完成后，OpenCode 会将 Token 安全地存储在 `~/.local/share/opencode/mcp-auth.json` 中。
|
||||
|
||||
---
|
||||
|
||||
#### 禁用 OAuth
|
||||
|
||||
如果你想为某个服务器禁用自动 OAuth（例如，该服务器使用 API 密钥而非 OAuth），可以将 `oauth` 设置为 `false`：
|
||||
|
||||
```json title="opencode.json" {7}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-api-key-server": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.example.com/mcp",
|
||||
"oauth": false,
|
||||
"headers": {
|
||||
"Authorization": "Bearer {env:MY_API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### OAuth 选项
|
||||
|
||||
| 选项 | 类型 | 描述 |
|
||||
| -------------- | --------------- | ------------------------------------------------------ |
|
||||
| `oauth` | 对象 \| `false` | OAuth 配置对象，或设为 `false` 以禁用 OAuth 自动检测。 |
|
||||
| `clientId` | 字符串 | OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。 |
|
||||
| `clientSecret` | 字符串 | OAuth 客户端密钥（如果授权服务器要求提供）。 |
|
||||
| `scope` | 字符串 | 授权时请求的 OAuth 作用域。 |
|
||||
|
||||
#### 调试
|
||||
|
||||
如果远程 MCP 服务器身份验证失败，你可以通过以下方式诊断问题：
|
||||
|
||||
```bash
|
||||
# 查看所有支持 OAuth 的服务器的认证状态
|
||||
opencode mcp auth list
|
||||
|
||||
# 调试特定服务器的连接和 OAuth 流程
|
||||
opencode mcp debug my-oauth-server
|
||||
```
|
||||
|
||||
`mcp debug` 命令会显示当前认证状态、测试 HTTP 连接，并尝试执行 OAuth 发现流程。
|
||||
|
||||
---
|
||||
|
||||
## 管理
|
||||
|
||||
你的 MCP 在 OpenCode 中作为工具使用，与内置工具并列。因此，你可以像管理其他工具一样，通过 OpenCode 配置来管理它们。
|
||||
|
||||
---
|
||||
|
||||
### 全局
|
||||
|
||||
你可以全局启用或禁用 MCP 工具。
|
||||
|
||||
```json title="opencode.json" {14}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-mcp-foo": {
|
||||
"type": "local",
|
||||
"command": ["bun", "x", "my-mcp-command-foo"]
|
||||
},
|
||||
"my-mcp-bar": {
|
||||
"type": "local",
|
||||
"command": ["bun", "x", "my-mcp-command-bar"]
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"my-mcp-foo": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
也可以使用 glob 模式来禁用所有匹配的 MCP。
|
||||
|
||||
```json title="opencode.json" {14}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-mcp-foo": {
|
||||
"type": "local",
|
||||
"command": ["bun", "x", "my-mcp-command-foo"]
|
||||
},
|
||||
"my-mcp-bar": {
|
||||
"type": "local",
|
||||
"command": ["bun", "x", "my-mcp-command-bar"]
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"my-mcp*": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这里使用 glob 模式 `my-mcp*` 来禁用所有 MCP。
|
||||
|
||||
---
|
||||
|
||||
### 按代理配置
|
||||
|
||||
如果你有大量 MCP 服务器，可以选择全局禁用它们，然后仅在特定代理中启用。具体做法：
|
||||
|
||||
1. 全局禁用该工具。
|
||||
2. 在[代理配置](/docs/agents#tools)中，将 MCP 服务器作为工具启用。
|
||||
|
||||
```json title="opencode.json" {11, 14-18}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-mcp": {
|
||||
"type": "local",
|
||||
"command": ["bun", "x", "my-mcp-command"],
|
||||
"enabled": true
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"my-mcp*": false
|
||||
},
|
||||
"agent": {
|
||||
"my-agent": {
|
||||
"tools": {
|
||||
"my-mcp*": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Glob 模式
|
||||
|
||||
glob 模式使用简单的正则通配符规则：
|
||||
|
||||
- `*` 匹配零个或多个任意字符（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等）
|
||||
- `?` 匹配恰好一个字符
|
||||
- 其他字符按字面值匹配
|
||||
|
||||
:::note
|
||||
MCP 服务器工具在注册时以服务器名称作为前缀，因此要禁用某个服务器的所有工具，只需使用：
|
||||
|
||||
```
|
||||
"mymcpservername_*": false
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
以下是一些常见 MCP 服务器的配置示例。如果你想记录其他服务器的用法，欢迎提交 PR。
|
||||
|
||||
---
|
||||
|
||||
### Sentry
|
||||
|
||||
添加 [Sentry MCP 服务器](https://mcp.sentry.dev) 以与你的 Sentry 项目和问题进行交互。
|
||||
|
||||
```json title="opencode.json" {4-8}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"sentry": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.sentry.dev/mcp",
|
||||
"oauth": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
添加配置后，使用 Sentry 进行身份验证：
|
||||
|
||||
```bash
|
||||
opencode mcp auth sentry
|
||||
```
|
||||
|
||||
这会打开浏览器窗口完成 OAuth 流程，将 OpenCode 连接到你的 Sentry 账户。
|
||||
|
||||
认证完成后，你可以在提示词中使用 Sentry 工具来查询问题、项目和错误数据。
|
||||
|
||||
```txt "use sentry"
|
||||
Show me the latest unresolved issues in my project. use sentry
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Context7
|
||||
|
||||
添加 [Context7 MCP 服务器](https://github.com/upstash/context7) 以搜索文档。
|
||||
|
||||
```json title="opencode.json" {4-7}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"context7": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.context7.com/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你注册了免费账户，可以使用 API 密钥来获得更高的速率限制。
|
||||
|
||||
```json title="opencode.json" {7-9}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"context7": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.context7.com/mcp",
|
||||
"headers": {
|
||||
"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这里假设你已经设置了 `CONTEXT7_API_KEY` 环境变量。
|
||||
|
||||
在提示词中添加 `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/) 中添加类似的规则。
|
||||
|
||||
```md title="AGENTS.md"
|
||||
When you need to search docs, use `context7` tools.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Grep by Vercel
|
||||
|
||||
添加 [Grep by Vercel](https://grep.app) MCP 服务器以搜索 GitHub 上的代码片段。
|
||||
|
||||
```json title="opencode.json" {4-7}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"gh_grep": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.grep.app"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
由于我们将 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/) 中添加类似的规则。
|
||||
|
||||
```md title="AGENTS.md"
|
||||
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
|
||||
```
|
||||
222
packages/web/src/content/docs/zh-cn/models.mdx
Normal file
222
packages/web/src/content/docs/zh-cn/models.mdx
Normal file
@@ -0,0 +1,222 @@
|
||||
---
|
||||
title: 模型
|
||||
description: 配置 LLM 提供商和模型。
|
||||
---
|
||||
|
||||
OpenCode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.dev) 支持 **75+ LLM 提供商**，并支持运行本地模型。
|
||||
|
||||
---
|
||||
|
||||
## 提供商
|
||||
|
||||
大多数热门提供商已默认预加载。如果你通过 `/connect` 命令添加了提供商的凭据，它们将在你启动 OpenCode 时自动可用。
|
||||
|
||||
了解更多关于[提供商](/docs/providers)的信息。
|
||||
|
||||
---
|
||||
|
||||
## 选择模型
|
||||
|
||||
配置好提供商后，你可以通过输入以下命令来选择想要使用的模型：
|
||||
|
||||
```bash frame="none"
|
||||
/models
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 推荐模型
|
||||
|
||||
市面上有非常多的模型，每周都有新模型发布。
|
||||
|
||||
:::tip
|
||||
建议使用我们推荐的模型。
|
||||
:::
|
||||
|
||||
然而，真正擅长代码生成和工具调用的模型只有少数几个。
|
||||
|
||||
以下是与 OpenCode 配合良好的几个模型，排名不分先后（此列表并非详尽无遗，也不一定是最新的）：
|
||||
|
||||
- GPT 5.2
|
||||
- GPT 5.1 Codex
|
||||
- Claude Opus 4.5
|
||||
- Claude Sonnet 4.5
|
||||
- Minimax M2.1
|
||||
- Gemini 3 Pro
|
||||
|
||||
---
|
||||
|
||||
## 设置默认模型
|
||||
|
||||
要将某个模型设为默认模型，可以在 OpenCode 配置中设置 `model` 字段。
|
||||
|
||||
```json title="opencode.json" {3}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"model": "lmstudio/google/gemma-3n-e4b"
|
||||
}
|
||||
```
|
||||
|
||||
这里完整的 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` 中的键名。
|
||||
|
||||
---
|
||||
|
||||
## 配置模型
|
||||
|
||||
你可以通过配置文件全局配置模型的选项。
|
||||
|
||||
```jsonc title="opencode.jsonc" {7-12,19-24}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"openai": {
|
||||
"models": {
|
||||
"gpt-5": {
|
||||
"options": {
|
||||
"reasoningEffort": "high",
|
||||
"textVerbosity": "low",
|
||||
"reasoningSummary": "auto",
|
||||
"include": ["reasoning.encrypted_content"],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
"anthropic": {
|
||||
"models": {
|
||||
"claude-sonnet-4-5-20250929": {
|
||||
"options": {
|
||||
"thinking": {
|
||||
"type": "enabled",
|
||||
"budgetTokens": 16000,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
这里我们为两个内置模型配置了全局设置：通过 `openai` 提供商访问的 `gpt-5`，以及通过 `anthropic` 提供商访问的 `claude-sonnet-4-20250514`。
|
||||
内置的提供商和模型名称可以在 [Models.dev](https://models.dev) 上查阅。
|
||||
|
||||
你还可以为使用中的任何代理配置这些选项。代理配置会覆盖此处的全局选项。[了解更多](/docs/agents/#additional)。
|
||||
|
||||
你也可以定义扩展内置变体的自定义变体。变体允许你为同一个模型配置不同的设置，而无需创建重复的条目：
|
||||
|
||||
```jsonc title="opencode.jsonc" {6-21}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"opencode": {
|
||||
"models": {
|
||||
"gpt-5": {
|
||||
"variants": {
|
||||
"high": {
|
||||
"reasoningEffort": "high",
|
||||
"textVerbosity": "low",
|
||||
"reasoningSummary": "auto",
|
||||
},
|
||||
"low": {
|
||||
"reasoningEffort": "low",
|
||||
"textVerbosity": "low",
|
||||
"reasoningSummary": "auto",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 变体
|
||||
|
||||
许多模型支持具有不同配置的多种变体。OpenCode 为热门提供商内置了默认变体。
|
||||
|
||||
### 内置变体
|
||||
|
||||
OpenCode 为许多提供商提供了默认变体：
|
||||
|
||||
**Anthropic**：
|
||||
|
||||
- `high` - 高思考预算（默认）
|
||||
- `max` - 最大思考预算
|
||||
|
||||
**OpenAI**：
|
||||
|
||||
因模型而异，但大致如下：
|
||||
|
||||
- `none` - 无推理
|
||||
- `minimal` - 极少推理
|
||||
- `low` - 低推理
|
||||
- `medium` - 中等推理
|
||||
- `high` - 高推理
|
||||
- `xhigh` - 超高推理
|
||||
|
||||
**Google**：
|
||||
|
||||
- `low` - 较低推理/Token 预算
|
||||
- `high` - 较高推理/Token 预算
|
||||
|
||||
:::tip
|
||||
此列表并不全面，许多其他提供商也有内置的默认变体。
|
||||
:::
|
||||
|
||||
### 自定义变体
|
||||
|
||||
你可以覆盖现有变体或添加自己的变体：
|
||||
|
||||
```jsonc title="opencode.jsonc" {7-18}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"openai": {
|
||||
"models": {
|
||||
"gpt-5": {
|
||||
"variants": {
|
||||
"thinking": {
|
||||
"reasoningEffort": "high",
|
||||
"textVerbosity": "low",
|
||||
},
|
||||
"fast": {
|
||||
"disabled": true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 切换变体
|
||||
|
||||
使用快捷键 `variant_cycle` 可以快速在变体之间切换。[了解更多](/docs/keybinds)。
|
||||
|
||||
---
|
||||
|
||||
## 加载模型
|
||||
|
||||
OpenCode 启动时，会按以下优先顺序加载模型：
|
||||
|
||||
1. `--model` 或 `-m` 命令行标志。格式与配置文件中相同：`provider_id/model_id`。
|
||||
|
||||
2. OpenCode 配置中的 model 字段。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"model": "anthropic/claude-sonnet-4-20250514"
|
||||
}
|
||||
```
|
||||
|
||||
格式为 `provider/model`。
|
||||
|
||||
3. 上次使用的模型。
|
||||
|
||||
4. 按内部优先级排列的第一个可用模型。
|
||||
57
packages/web/src/content/docs/zh-cn/network.mdx
Normal file
57
packages/web/src/content/docs/zh-cn/network.mdx
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: 网络
|
||||
description: 配置代理和自定义证书。
|
||||
---
|
||||
|
||||
OpenCode 支持标准代理环境变量和自定义证书，适用于企业网络环境。
|
||||
|
||||
---
|
||||
|
||||
## 代理
|
||||
|
||||
OpenCode 遵循标准代理环境变量。
|
||||
|
||||
```bash
|
||||
# HTTPS proxy (recommended)
|
||||
export HTTPS_PROXY=https://proxy.example.com:8080
|
||||
|
||||
# HTTP proxy (if HTTPS not available)
|
||||
export HTTP_PROXY=http://proxy.example.com:8080
|
||||
|
||||
# Bypass proxy for local server (required)
|
||||
export NO_PROXY=localhost,127.0.0.1
|
||||
```
|
||||
|
||||
:::caution
|
||||
TUI 与本地 HTTP 服务器进行通信。你必须为此连接绕过代理，以防止路由循环。
|
||||
:::
|
||||
|
||||
你可以使用 [CLI 标志](/docs/cli#run)来配置服务器的端口和主机名。
|
||||
|
||||
---
|
||||
|
||||
### 身份验证
|
||||
|
||||
如果你的代理需要基本身份验证，请在 URL 中包含凭据。
|
||||
|
||||
```bash
|
||||
export HTTPS_PROXY=http://username:password@proxy.example.com:8080
|
||||
```
|
||||
|
||||
:::caution
|
||||
避免将密码硬编码在代码中。请使用环境变量或安全的凭据存储方式。
|
||||
:::
|
||||
|
||||
对于需要高级身份验证（如 NTLM 或 Kerberos）的代理，建议使用支持相应身份验证方式的 LLM 网关。
|
||||
|
||||
---
|
||||
|
||||
## 自定义证书
|
||||
|
||||
如果你的企业使用自定义 CA 进行 HTTPS 连接，请配置 OpenCode 以信任这些证书。
|
||||
|
||||
```bash
|
||||
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
|
||||
```
|
||||
|
||||
此配置同时适用于代理连接和直接 API 访问。
|
||||
235
packages/web/src/content/docs/zh-cn/permissions.mdx
Normal file
235
packages/web/src/content/docs/zh-cn/permissions.mdx
Normal file
@@ -0,0 +1,235 @@
|
||||
---
|
||||
title: 权限
|
||||
description: 控制哪些操作需要审批才能运行。
|
||||
---
|
||||
|
||||
OpenCode 使用 `permission` 配置来决定某个操作是否应自动运行、提示你审批，还是被阻止。
|
||||
|
||||
从 `v1.1.1` 开始，旧版 `tools` 布尔配置已被弃用，并已合并到 `permission` 中。旧版 `tools` 配置仍然支持，以保持向后兼容。
|
||||
|
||||
---
|
||||
|
||||
## 操作
|
||||
|
||||
每条权限规则解析为以下之一：
|
||||
|
||||
- `"allow"` — 无需审批直接运行
|
||||
- `"ask"` — 提示审批
|
||||
- `"deny"` — 阻止该操作
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
你可以全局设置权限（使用 `*`），并覆盖特定工具的权限。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"*": "ask",
|
||||
"bash": "allow",
|
||||
"edit": "deny"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
你还可以一次性设置所有权限：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": "allow"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 细粒度规则（对象语法）
|
||||
|
||||
对于大多数权限，你可以使用对象来根据工具输入应用不同的操作。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git *": "allow",
|
||||
"npm *": "allow",
|
||||
"rm *": "deny",
|
||||
"grep *": "allow"
|
||||
},
|
||||
"edit": {
|
||||
"*": "deny",
|
||||
"packages/web/src/content/docs/*.mdx": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
规则通过模式匹配进行评估，**最后匹配的规则优先**。常见做法是将通配的 `"*"` 规则放在最前面，更具体的规则放在后面。
|
||||
|
||||
### 通配符
|
||||
|
||||
权限模式使用简单的通配符匹配：
|
||||
|
||||
- `*` 匹配零个或多个任意字符
|
||||
- `?` 精确匹配一个字符
|
||||
- 所有其他字符按字面值匹配
|
||||
|
||||
### 主目录展开
|
||||
|
||||
你可以在模式开头使用 `~` 或 `$HOME` 来引用你的主目录。这对于 [`external_directory`](#外部目录) 规则特别有用。
|
||||
|
||||
- `~/projects/*` -> `/Users/username/projects/*`
|
||||
- `$HOME/projects/*` -> `/Users/username/projects/*`
|
||||
- `~` -> `/Users/username`
|
||||
|
||||
### 外部目录
|
||||
|
||||
使用 `external_directory` 允许工具调用访问 OpenCode 启动时工作目录之外的路径。这适用于任何接受路径作为输入的工具（例如 `read`、`edit`、`glob`、`grep` 以及许多 `bash` 命令）。
|
||||
|
||||
主目录展开（如 `~/...`）仅影响模式的书写方式。它不会将外部路径纳入当前工作空间，因此工作目录之外的路径仍然必须通过 `external_directory` 来允许。
|
||||
|
||||
例如，以下配置允许访问 `~/projects/personal/` 下的所有内容：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"external_directory": {
|
||||
"~/projects/personal/**": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
此处允许的任何目录都会继承与当前工作空间相同的默认值。由于 [`read` 默认为 `allow`](#默认值)，`external_directory` 下的条目也允许读取，除非另行覆盖。当需要在这些路径中限制某个工具时，请添加显式规则，例如在保留读取的同时阻止编辑：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"external_directory": {
|
||||
"~/projects/personal/**": "allow"
|
||||
},
|
||||
"edit": {
|
||||
"~/projects/personal/**": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
请将列表限定在受信任的路径上，并根据需要为其他工具（例如 `bash`）叠加额外的允许或拒绝规则。
|
||||
|
||||
---
|
||||
|
||||
## 可用权限
|
||||
|
||||
OpenCode 的权限以工具名称为键，外加几个安全防护项：
|
||||
|
||||
- `read` — 读取文件（匹配文件路径）
|
||||
- `edit` — 所有文件修改（涵盖 `edit`、`write`、`patch`）
|
||||
- `glob` — 文件通配（匹配通配模式）
|
||||
- `grep` — 内容搜索（匹配正则表达式模式）
|
||||
- `bash` — 运行 shell 命令（匹配解析后的命令，如 `git status --porcelain`）
|
||||
- `task` — 启动子代理（匹配子代理类型）
|
||||
- `skill` — 加载技能（匹配技能名称）
|
||||
- `lsp` — 运行 LSP 查询（当前不支持细粒度配置）
|
||||
- `webfetch` — 获取 URL（匹配 URL）
|
||||
- `websearch` — 网页搜索（匹配查询内容）
|
||||
- `external_directory` — 当工具访问项目工作目录之外的路径时触发
|
||||
- `doom_loop` — 当同一工具调用以相同输入重复 3 次时触发
|
||||
|
||||
---
|
||||
|
||||
## 默认值
|
||||
|
||||
如果你未指定任何配置，OpenCode 将使用宽松的默认值：
|
||||
|
||||
- 大多数权限默认为 `"allow"`。
|
||||
- `doom_loop` 和 `external_directory` 默认为 `"ask"`。
|
||||
- `read` 为 `"allow"`，但 `.env` 文件默认被拒绝：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"permission": {
|
||||
"read": {
|
||||
"*": "allow",
|
||||
"*.env": "deny",
|
||||
"*.env.*": "deny",
|
||||
"*.env.example": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## "Ask"的作用
|
||||
|
||||
当 OpenCode 提示审批时，界面提供三种选择：
|
||||
|
||||
- `once` — 仅批准本次请求
|
||||
- `always` — 批准与建议模式匹配的后续请求（在当前 OpenCode 会话的剩余时间内有效）
|
||||
- `reject` — 拒绝请求
|
||||
|
||||
`always` 所批准的模式集合由工具提供（例如，bash 审批通常会将安全的命令前缀如 `git status*` 加入白名单）。
|
||||
|
||||
---
|
||||
|
||||
## 代理
|
||||
|
||||
你可以为每个代理单独覆盖权限。代理权限会与全局配置合并，且代理规则优先。[了解更多](/docs/agents#permissions)关于代理权限的内容。
|
||||
|
||||
:::note
|
||||
有关更详细的模式匹配示例，请参阅上方的[细粒度规则（对象语法）](#细粒度规则对象语法)部分。
|
||||
:::
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git *": "allow",
|
||||
"git commit *": "deny",
|
||||
"git push *": "deny",
|
||||
"grep *": "allow"
|
||||
}
|
||||
},
|
||||
"agent": {
|
||||
"build": {
|
||||
"permission": {
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git *": "allow",
|
||||
"git commit *": "ask",
|
||||
"git push *": "deny",
|
||||
"grep *": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
你还可以在 Markdown 中配置代理权限：
|
||||
|
||||
```markdown title="~/.config/opencode/agents/review.md"
|
||||
---
|
||||
description: Code review without edits
|
||||
mode: subagent
|
||||
permission:
|
||||
edit: deny
|
||||
bash: ask
|
||||
webfetch: deny
|
||||
---
|
||||
|
||||
Only analyze code and suggest changes.
|
||||
```
|
||||
|
||||
:::tip
|
||||
对带参数的命令使用模式匹配。`"grep *"` 允许执行 `grep pattern file.txt`，而单独的 `"grep"` 则会阻止它。像 `git status` 这样的命令适用于默认行为，但在传递参数时需要显式权限（如 `"git status *"`）。
|
||||
:::
|
||||
388
packages/web/src/content/docs/zh-cn/plugins.mdx
Normal file
388
packages/web/src/content/docs/zh-cn/plugins.mdx
Normal file
@@ -0,0 +1,388 @@
|
||||
---
|
||||
title: 插件
|
||||
description: 编写自己的插件来扩展 OpenCode。
|
||||
---
|
||||
|
||||
插件允许你通过挂钩各种事件和自定义行为来扩展 OpenCode。你可以创建插件来添加新功能、集成外部服务，或修改 OpenCode 的默认行为。
|
||||
|
||||
如需了解示例，请查看社区创建的[插件](/docs/ecosystem#plugins)。
|
||||
|
||||
---
|
||||
|
||||
## 使用插件
|
||||
|
||||
有两种方式加载插件。
|
||||
|
||||
---
|
||||
|
||||
### 从本地文件加载
|
||||
|
||||
将 JavaScript 或 TypeScript 文件放置在插件目录中。
|
||||
|
||||
- `.opencode/plugins/` - 项目级插件
|
||||
- `~/.config/opencode/plugins/` - 全局插件
|
||||
|
||||
这些目录中的文件会在启动时自动加载。
|
||||
|
||||
---
|
||||
|
||||
### 从 npm 加载
|
||||
|
||||
在配置文件中指定 npm 包。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
|
||||
}
|
||||
```
|
||||
|
||||
支持常规和带作用域的 npm 包。
|
||||
|
||||
浏览[生态系统](/docs/ecosystem#plugins)中的可用插件。
|
||||
|
||||
---
|
||||
|
||||
### 插件的安装方式
|
||||
|
||||
**npm 插件**在启动时使用 Bun 自动安装。包及其依赖项会缓存在 `~/.cache/opencode/node_modules/` 中。
|
||||
|
||||
**本地插件**直接从插件目录加载。如果需要使用外部包，你必须在配置目录中创建 `package.json`（参见[依赖项](#dependencies)），或者将插件发布到 npm 并[将其添加到配置中](/docs/config#plugins)。
|
||||
|
||||
---
|
||||
|
||||
### 加载顺序
|
||||
|
||||
插件从所有来源加载，所有钩子按顺序执行。加载顺序为：
|
||||
|
||||
1. 全局配置 (`~/.config/opencode/opencode.json`)
|
||||
2. 项目配置 (`opencode.json`)
|
||||
3. 全局插件目录 (`~/.config/opencode/plugins/`)
|
||||
4. 项目插件目录 (`.opencode/plugins/`)
|
||||
|
||||
名称和版本相同的重复 npm 包只会加载一次。但本地插件和名称相似的 npm 插件会分别独立加载。
|
||||
|
||||
---
|
||||
|
||||
## 创建插件
|
||||
|
||||
插件是一个 **JavaScript/TypeScript 模块**，它导出一个或多个插件函数。每个函数接收一个上下文对象，并返回一个钩子对象。
|
||||
|
||||
---
|
||||
|
||||
### 依赖项
|
||||
|
||||
本地插件和自定义工具可以使用外部 npm 包。在配置目录中添加一个 `package.json`，列出所需的依赖项。
|
||||
|
||||
```json title=".opencode/package.json"
|
||||
{
|
||||
"dependencies": {
|
||||
"shescape": "^2.1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
OpenCode 会在启动时运行 `bun install` 来安装这些依赖项。之后你的插件和工具就可以导入它们了。
|
||||
|
||||
```ts title=".opencode/plugins/my-plugin.ts"
|
||||
import { escape } from "shescape"
|
||||
|
||||
export const MyPlugin = async (ctx) => {
|
||||
return {
|
||||
"tool.execute.before": async (input, output) => {
|
||||
if (input.tool === "bash") {
|
||||
output.args.command = escape(output.args.command)
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 基本结构
|
||||
|
||||
```js title=".opencode/plugins/example.js"
|
||||
export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
|
||||
console.log("Plugin initialized!")
|
||||
|
||||
return {
|
||||
// Hook implementations go here
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
插件函数接收以下参数：
|
||||
|
||||
- `project`：当前项目信息。
|
||||
- `directory`：当前工作目录。
|
||||
- `worktree`：git 工作树路径。
|
||||
- `client`：用于与 AI 交互的 OpenCode SDK 客户端。
|
||||
- `$`：Bun 的 [Shell API](https://bun.com/docs/runtime/shell)，用于执行命令。
|
||||
|
||||
---
|
||||
|
||||
### TypeScript 支持
|
||||
|
||||
对于 TypeScript 插件，你可以从插件包中导入类型：
|
||||
|
||||
```ts title="my-plugin.ts" {1}
|
||||
import type { Plugin } from "@opencode-ai/plugin"
|
||||
|
||||
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
|
||||
return {
|
||||
// Type-safe hook implementations
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 事件
|
||||
|
||||
插件可以订阅事件，如下方示例部分所示。以下是所有可用事件的列表。
|
||||
|
||||
#### 命令事件
|
||||
|
||||
- `command.executed`
|
||||
|
||||
#### 文件事件
|
||||
|
||||
- `file.edited`
|
||||
- `file.watcher.updated`
|
||||
|
||||
#### 安装事件
|
||||
|
||||
- `installation.updated`
|
||||
|
||||
#### LSP 事件
|
||||
|
||||
- `lsp.client.diagnostics`
|
||||
- `lsp.updated`
|
||||
|
||||
#### 消息事件
|
||||
|
||||
- `message.part.removed`
|
||||
- `message.part.updated`
|
||||
- `message.removed`
|
||||
- `message.updated`
|
||||
|
||||
#### 权限事件
|
||||
|
||||
- `permission.asked`
|
||||
- `permission.replied`
|
||||
|
||||
#### 服务器事件
|
||||
|
||||
- `server.connected`
|
||||
|
||||
#### 会话事件
|
||||
|
||||
- `session.created`
|
||||
- `session.compacted`
|
||||
- `session.deleted`
|
||||
- `session.diff`
|
||||
- `session.error`
|
||||
- `session.idle`
|
||||
- `session.status`
|
||||
- `session.updated`
|
||||
|
||||
#### 待办事项事件
|
||||
|
||||
- `todo.updated`
|
||||
|
||||
#### Shell 事件
|
||||
|
||||
- `shell.env`
|
||||
|
||||
#### 工具事件
|
||||
|
||||
- `tool.execute.after`
|
||||
- `tool.execute.before`
|
||||
|
||||
#### TUI 事件
|
||||
|
||||
- `tui.prompt.append`
|
||||
- `tui.command.execute`
|
||||
- `tui.toast.show`
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
以下是一些可用于扩展 OpenCode 的插件示例。
|
||||
|
||||
---
|
||||
|
||||
### 发送通知
|
||||
|
||||
在特定事件发生时发送通知：
|
||||
|
||||
```js title=".opencode/plugins/notification.js"
|
||||
export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
|
||||
return {
|
||||
event: async ({ event }) => {
|
||||
// Send notification on session completion
|
||||
if (event.type === "session.idle") {
|
||||
await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这里使用 `osascript` 在 macOS 上运行 AppleScript 来发送通知。
|
||||
|
||||
:::note
|
||||
如果你使用 OpenCode 桌面应用，它可以在响应就绪或会话出错时自动发送系统通知。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### .env 保护
|
||||
|
||||
阻止 OpenCode 读取 `.env` 文件：
|
||||
|
||||
```javascript title=".opencode/plugins/env-protection.js"
|
||||
export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
|
||||
return {
|
||||
"tool.execute.before": async (input, output) => {
|
||||
if (input.tool === "read" && output.args.filePath.includes(".env")) {
|
||||
throw new Error("Do not read .env files")
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 注入环境变量
|
||||
|
||||
将环境变量注入所有 Shell 执行（AI 工具和用户终端）：
|
||||
|
||||
```javascript title=".opencode/plugins/inject-env.js"
|
||||
export const InjectEnvPlugin = async () => {
|
||||
return {
|
||||
"shell.env": async (input, output) => {
|
||||
output.env.MY_API_KEY = "secret"
|
||||
output.env.PROJECT_ROOT = input.cwd
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 自定义工具
|
||||
|
||||
插件还可以为 OpenCode 添加自定义工具：
|
||||
|
||||
```ts title=".opencode/plugins/custom-tools.ts"
|
||||
import { type Plugin, tool } from "@opencode-ai/plugin"
|
||||
|
||||
export const CustomToolsPlugin: Plugin = async (ctx) => {
|
||||
return {
|
||||
tool: {
|
||||
mytool: tool({
|
||||
description: "This is a custom tool",
|
||||
args: {
|
||||
foo: tool.schema.string(),
|
||||
},
|
||||
async execute(args, context) {
|
||||
const { directory, worktree } = context
|
||||
return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
|
||||
},
|
||||
}),
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`tool` 辅助函数用于创建 OpenCode 可调用的自定义工具。它接受一个 Zod schema 函数，并返回一个工具定义，包含：
|
||||
|
||||
- `description`：工具的功能描述
|
||||
- `args`：工具参数的 Zod schema
|
||||
- `execute`：工具被调用时执行的函数
|
||||
|
||||
你的自定义工具将与内置工具一起在 OpenCode 中可用。
|
||||
|
||||
:::note
|
||||
如果插件工具与内置工具使用相同的名称，则优先使用插件工具。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### 日志记录
|
||||
|
||||
使用 `client.app.log()` 代替 `console.log` 进行结构化日志记录：
|
||||
|
||||
```ts title=".opencode/plugins/my-plugin.ts"
|
||||
export const MyPlugin = async ({ client }) => {
|
||||
await client.app.log({
|
||||
body: {
|
||||
service: "my-plugin",
|
||||
level: "info",
|
||||
message: "Plugin initialized",
|
||||
extra: { foo: "bar" },
|
||||
},
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
日志级别：`debug`、`info`、`warn`、`error`。详情请参阅 [SDK 文档](https://opencode.ai/docs/sdk)。
|
||||
|
||||
---
|
||||
|
||||
### 压缩钩子
|
||||
|
||||
自定义会话压缩时包含的上下文：
|
||||
|
||||
```ts title=".opencode/plugins/compaction.ts"
|
||||
import type { Plugin } from "@opencode-ai/plugin"
|
||||
|
||||
export const CompactionPlugin: Plugin = async (ctx) => {
|
||||
return {
|
||||
"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
|
||||
- Important decisions made
|
||||
- Files being actively worked on
|
||||
`)
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`experimental.session.compacting` 钩子在 LLM 生成续接摘要之前触发。使用它来注入默认压缩提示词可能遗漏的领域特定上下文。
|
||||
|
||||
你还可以通过设置 `output.prompt` 来完全替换压缩提示词：
|
||||
|
||||
```ts title=".opencode/plugins/custom-compaction.ts"
|
||||
import type { Plugin } from "@opencode-ai/plugin"
|
||||
|
||||
export const CustomCompactionPlugin: Plugin = async (ctx) => {
|
||||
return {
|
||||
"experimental.session.compacting": async (input, output) => {
|
||||
// Replace the entire compaction prompt
|
||||
output.prompt = `
|
||||
You are generating a continuation prompt for a multi-agent swarm session.
|
||||
|
||||
Summarize:
|
||||
1. The current task and its status
|
||||
2. Which files are being modified and by whom
|
||||
3. Any blockers or dependencies between agents
|
||||
4. The next steps to complete the work
|
||||
|
||||
Format as a structured prompt that a new agent can use to resume work.
|
||||
`
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
当设置了 `output.prompt` 时，它会完全替换默认的压缩提示词。在这种情况下，`output.context` 数组将被忽略。
|
||||
1949
packages/web/src/content/docs/zh-cn/providers.mdx
Normal file
1949
packages/web/src/content/docs/zh-cn/providers.mdx
Normal file
File diff suppressed because it is too large
Load Diff
180
packages/web/src/content/docs/zh-cn/rules.mdx
Normal file
180
packages/web/src/content/docs/zh-cn/rules.mdx
Normal file
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: 规则
|
||||
description: 为 opencode 设置自定义指令。
|
||||
---
|
||||
|
||||
您可以通过创建 `AGENTS.md` 文件来为 opencode 提供自定义指令。这类似于 Cursor 的规则功能。该文件包含的指令会被纳入 LLM 的上下文中，以便针对您的特定项目自定义其行为。
|
||||
|
||||
---
|
||||
|
||||
## 初始化
|
||||
|
||||
要创建新的 `AGENTS.md` 文件，您可以在 opencode 中运行 `/init` 命令。
|
||||
|
||||
:::tip
|
||||
您应该将项目的 `AGENTS.md` 文件提交到 Git。
|
||||
:::
|
||||
|
||||
该命令会扫描您的项目及其所有内容，了解项目的用途，并据此生成一个 `AGENTS.md` 文件。这有助于 opencode 更好地导航您的项目。
|
||||
|
||||
如果您已有 `AGENTS.md` 文件，该命令会尝试在其基础上进行补充。
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
您也可以手动创建此文件。以下是一些可以放入 `AGENTS.md` 文件中的内容示例。
|
||||
|
||||
```markdown title="AGENTS.md"
|
||||
# SST v3 Monorepo Project
|
||||
|
||||
This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
|
||||
|
||||
## Project Structure
|
||||
|
||||
- `packages/` - Contains all workspace packages (functions, core, web, etc.)
|
||||
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
|
||||
- `sst.config.ts` - Main SST configuration with dynamic imports
|
||||
|
||||
## Code Standards
|
||||
|
||||
- Use TypeScript with strict mode enabled
|
||||
- Shared code goes in `packages/core/` with proper exports configuration
|
||||
- Functions go in `packages/functions/`
|
||||
- Infrastructure should be split into logical files in `infra/`
|
||||
|
||||
## Monorepo Conventions
|
||||
|
||||
- Import shared modules using workspace names: `@my-app/core/example`
|
||||
```
|
||||
|
||||
我们在这里添加了项目特定的指令，这些指令会在您的团队中共享。
|
||||
|
||||
---
|
||||
|
||||
## 类型
|
||||
|
||||
opencode 还支持从多个位置读取 `AGENTS.md` 文件，不同的位置有不同的用途。
|
||||
|
||||
### 项目级
|
||||
|
||||
在项目根目录放置一个 `AGENTS.md` 文件，用于定义项目特定的规则。这些规则仅在您在该目录或其子目录中工作时生效。
|
||||
|
||||
### 全局级
|
||||
|
||||
您还可以在 `~/.config/opencode/AGENTS.md` 文件中设置全局规则。这些规则会应用于所有 opencode 会话。
|
||||
|
||||
由于该文件不会被提交到 Git 或与团队共享，我们建议用它来指定 LLM 应遵循的个人规则。
|
||||
|
||||
### Claude Code 兼容性
|
||||
|
||||
对于从 Claude Code 迁移过来的用户，OpenCode 支持 Claude Code 的文件约定作为回退方案：
|
||||
|
||||
- **项目规则**：项目目录中的 `CLAUDE.md`（在没有 `AGENTS.md` 的情况下使用）
|
||||
- **全局规则**：`~/.claude/CLAUDE.md`（在没有 `~/.config/opencode/AGENTS.md` 的情况下使用）
|
||||
- **技能**：`~/.claude/skills/` — 详情请参阅[代理技能](/docs/skills/)
|
||||
|
||||
要禁用 Claude Code 兼容性，请设置以下环境变量之一：
|
||||
|
||||
```bash
|
||||
export OPENCODE_DISABLE_CLAUDE_CODE=1 # Disable all .claude support
|
||||
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
|
||||
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`（除非已禁用）
|
||||
|
||||
在每个类别中，第一个匹配的文件优先。例如，如果您同时拥有 `AGENTS.md` 和 `CLAUDE.md`，则只会使用 `AGENTS.md`。同样，`~/.config/opencode/AGENTS.md` 优先于 `~/.claude/CLAUDE.md`。
|
||||
|
||||
---
|
||||
|
||||
## 自定义指令
|
||||
|
||||
您可以在 `opencode.json` 或全局配置文件 `~/.config/opencode/opencode.json` 中指定自定义指令文件。这允许您和团队复用现有规则，而无需将它们复制到 AGENTS.md 中。
|
||||
|
||||
示例：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
|
||||
}
|
||||
```
|
||||
|
||||
您还可以使用远程 URL 从网络加载指令。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
|
||||
}
|
||||
```
|
||||
|
||||
远程指令的获取超时时间为 5 秒。
|
||||
|
||||
所有指令文件都会与您的 `AGENTS.md` 文件合并。
|
||||
|
||||
---
|
||||
|
||||
## 引用外部文件
|
||||
|
||||
虽然 opencode 不会自动解析 `AGENTS.md` 中的文件引用，但您可以通过以下两种方式实现类似的功能：
|
||||
|
||||
### 使用 opencode.json
|
||||
|
||||
推荐的方式是使用 `opencode.json` 中的 `instructions` 字段：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
|
||||
}
|
||||
```
|
||||
|
||||
### 在 AGENTS.md 中手动指定
|
||||
|
||||
您可以在 `AGENTS.md` 中提供明确的指令，教 opencode 读取外部文件。以下是一个实际示例：
|
||||
|
||||
```markdown title="AGENTS.md"
|
||||
# TypeScript Project Rules
|
||||
|
||||
## External File Loading
|
||||
|
||||
CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
|
||||
|
||||
Instructions:
|
||||
|
||||
- Do NOT preemptively load all references - use lazy loading based on actual need
|
||||
- When loaded, treat content as mandatory instructions that override defaults
|
||||
- Follow references recursively when needed
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
For TypeScript code style and best practices: @docs/typescript-guidelines.md
|
||||
For React component architecture and hooks patterns: @docs/react-patterns.md
|
||||
For REST API design and error handling: @docs/api-standards.md
|
||||
For testing strategies and coverage requirements: @test/testing-guidelines.md
|
||||
|
||||
## General Guidelines
|
||||
|
||||
Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.
|
||||
```
|
||||
|
||||
这种方式允许您：
|
||||
|
||||
- 创建模块化、可复用的规则文件
|
||||
- 通过符号链接或 Git 子模块在项目之间共享规则
|
||||
- 保持 AGENTS.md 简洁，同时引用详细的指南
|
||||
- 确保 opencode 仅在特定任务需要时才加载文件
|
||||
|
||||
:::tip
|
||||
对于 monorepo 或具有共享标准的项目，使用 `opencode.json` 配合 glob 模式（如 `packages/*/AGENTS.md`）比手动指定指令更易于维护。
|
||||
:::
|
||||
463
packages/web/src/content/docs/zh-cn/sdk.mdx
Normal file
463
packages/web/src/content/docs/zh-cn/sdk.mdx
Normal file
@@ -0,0 +1,463 @@
|
||||
---
|
||||
title: SDK
|
||||
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。
|
||||
|
||||
[了解更多](/docs/server)关于服务器的工作原理。如需示例，请查看社区构建的[项目](/docs/ecosystem#projects)。
|
||||
|
||||
---
|
||||
|
||||
## 安装
|
||||
|
||||
从 npm 安装 SDK：
|
||||
|
||||
```bash
|
||||
npm install @opencode-ai/sdk
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 创建客户端
|
||||
|
||||
创建一个 opencode 实例：
|
||||
|
||||
```javascript
|
||||
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` | 配置对象 | `{}` |
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
你可以传入一个配置对象来自定义行为。实例仍然会读取你的 `opencode.json`，但你可以通过内联方式覆盖或添加配置：
|
||||
|
||||
```javascript
|
||||
import { createOpencode } from "@opencode-ai/sdk"
|
||||
|
||||
const opencode = await createOpencode({
|
||||
hostname: "127.0.0.1",
|
||||
port: 4096,
|
||||
config: {
|
||||
model: "anthropic/claude-3-5-sonnet-20241022",
|
||||
},
|
||||
})
|
||||
|
||||
console.log(`Server running at ${opencode.server.url}`)
|
||||
|
||||
opencode.server.close()
|
||||
```
|
||||
|
||||
## 仅客户端模式
|
||||
|
||||
如果你已经有一个正在运行的 opencode 实例，可以创建一个客户端实例来连接它：
|
||||
|
||||
```javascript
|
||||
import { createOpencodeClient } from "@opencode-ai/sdk"
|
||||
|
||||
const client = createOpencodeClient({
|
||||
baseUrl: "http://localhost:4096",
|
||||
})
|
||||
```
|
||||
|
||||
#### 选项
|
||||
|
||||
| 选项 | 类型 | 描述 | 默认值 |
|
||||
| --------------- | ---------- | ---------------------------- | ----------------------- |
|
||||
| `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 定义。你可以直接导入它们：
|
||||
|
||||
```typescript
|
||||
import type { Session, Message, Part } from "@opencode-ai/sdk"
|
||||
```
|
||||
|
||||
所有类型均根据服务器的 OpenAPI 规范生成，可在<a href={typesUrl}>类型文件</a>中查看。
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
SDK 可能会抛出错误，你可以捕获并处理这些错误：
|
||||
|
||||
```typescript
|
||||
try {
|
||||
await client.session.get({ path: { id: "invalid-id" } })
|
||||
} catch (error) {
|
||||
console.error("Failed to get session:", (error as Error).message)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 结构化输出
|
||||
|
||||
你可以通过指定带有 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 }` |
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
const health = await client.global.health()
|
||||
console.log(health.data.version)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### App
|
||||
|
||||
| 方法 | 描述 | 响应 |
|
||||
| -------------- | ------------------ | ------------------------------------------- |
|
||||
| `app.log()` | 写入一条日志 | `boolean` |
|
||||
| `app.agents()` | 列出所有可用的代理 | <a href={typesUrl}><code>Agent[]</code></a> |
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
// Write a log entry
|
||||
await client.app.log({
|
||||
body: {
|
||||
service: "my-app",
|
||||
level: "info",
|
||||
message: "Operation completed",
|
||||
},
|
||||
})
|
||||
|
||||
// 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> |
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
// List all projects
|
||||
const projects = await client.project.list()
|
||||
|
||||
// Get current project
|
||||
const currentProject = await client.project.current()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Path
|
||||
|
||||
| 方法 | 描述 | 响应 |
|
||||
| ------------ | ------------ | ---------------------------------------- |
|
||||
| `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.providers()` | 列出提供商和默认模型 | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
const config = await client.config.get()
|
||||
|
||||
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>。支持通过 `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` |
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
// Create and manage sessions
|
||||
const session = await client.session.create({
|
||||
body: { title: "My session" },
|
||||
})
|
||||
|
||||
const sessions = await client.session.list()
|
||||
|
||||
// Send a prompt message
|
||||
const result = await client.session.prompt({
|
||||
path: { id: session.id },
|
||||
body: {
|
||||
model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
|
||||
parts: [{ type: "text", text: "Hello!" }],
|
||||
},
|
||||
})
|
||||
|
||||
// Inject context without triggering AI response (useful for plugins)
|
||||
await client.session.prompt({
|
||||
path: { id: session.id },
|
||||
body: {
|
||||
noReply: true,
|
||||
parts: [{ type: "text", text: "You are a helpful assistant." }],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Files
|
||||
|
||||
| 方法 | 描述 | 响应 |
|
||||
| ------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
|
||||
| `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` 支持以下可选查询字段：
|
||||
|
||||
- `type`：`"file"` 或 `"directory"`
|
||||
- `directory`：覆盖搜索的项目根目录
|
||||
- `limit`：最大结果数（1–200）
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
// Search and read files
|
||||
const textResults = await client.find.text({
|
||||
query: { pattern: "function.*opencode" },
|
||||
})
|
||||
|
||||
const files = await client.find.files({
|
||||
query: { query: "*.ts", type: "file" },
|
||||
})
|
||||
|
||||
const directories = await client.find.files({
|
||||
query: { query: "packages", type: "directory", limit: 20 },
|
||||
})
|
||||
|
||||
const content = await client.file.read({
|
||||
query: { path: "src/index.ts" },
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### TUI
|
||||
|
||||
| 方法 | 描述 | 响应 |
|
||||
| ------------------------------ | ---------------- | --------- |
|
||||
| `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` |
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
// Control TUI interface
|
||||
await client.tui.appendPrompt({
|
||||
body: { text: "Add this to prompt" },
|
||||
})
|
||||
|
||||
await client.tui.showToast({
|
||||
body: { message: "Task completed", variant: "success" },
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Auth
|
||||
|
||||
| 方法 | 描述 | 响应 |
|
||||
| ------------------- | ------------ | --------- |
|
||||
| `auth.set({ ... })` | 设置认证凭据 | `boolean` |
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
await client.auth.set({
|
||||
path: { id: "anthropic" },
|
||||
body: { type: "api", key: "your-api-key" },
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Events
|
||||
|
||||
| 方法 | 描述 | 响应 |
|
||||
| ------------------- | ------------------ | ------------------ |
|
||||
| `event.subscribe()` | 服务器发送的事件流 | 服务器发送的事件流 |
|
||||
|
||||
---
|
||||
|
||||
#### 示例
|
||||
|
||||
```javascript
|
||||
// Listen to real-time events
|
||||
const events = await client.event.subscribe()
|
||||
for await (const event of events.stream) {
|
||||
console.log("Event:", event.type, event.properties)
|
||||
}
|
||||
```
|
||||
284
packages/web/src/content/docs/zh-cn/server.mdx
Normal file
284
packages/web/src/content/docs/zh-cn/server.mdx
Normal file
@@ -0,0 +1,284 @@
|
||||
---
|
||||
title: 服务器
|
||||
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 服务器，暴露一个 OpenAPI 端点供 opencode 客户端使用。
|
||||
|
||||
---
|
||||
|
||||
### 用法
|
||||
|
||||
```bash
|
||||
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
|
||||
```
|
||||
|
||||
#### 选项
|
||||
|
||||
| 标志 | 描述 | 默认值 |
|
||||
| --------------- | --------------------- | ---------------- |
|
||||
| `--port` | 监听端口 | `4096` |
|
||||
| `--hostname` | 监听的主机名 | `127.0.0.1` |
|
||||
| `--mdns` | 启用 mDNS 发现 | `false` |
|
||||
| `--mdns-domain` | mDNS 服务的自定义域名 | `opencode.local` |
|
||||
| `--cors` | 额外允许的浏览器来源 | `[]` |
|
||||
|
||||
`--cors` 可以多次传递：
|
||||
|
||||
```bash
|
||||
opencode serve --cors http://localhost:5173 --cors https://app.example.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 认证
|
||||
|
||||
设置 `OPENCODE_SERVER_PASSWORD` 以使用 HTTP 基本认证保护服务器。用户名默认为 `opencode`，也可以设置 `OPENCODE_SERVER_USERNAME` 来覆盖它。这适用于 `opencode serve` 和 `opencode web`。
|
||||
|
||||
```bash
|
||||
OPENCODE_SERVER_PASSWORD=your-password opencode serve
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 工作原理
|
||||
|
||||
当你运行 `opencode` 时，它会启动一个 TUI 和一个服务器。TUI 是与服务器通信的客户端。服务器暴露一个 OpenAPI 3.1 规范端点。该端点也用于生成 [SDK](/docs/sdk)。
|
||||
|
||||
:::tip
|
||||
使用 opencode 服务器以编程方式与 opencode 交互。
|
||||
:::
|
||||
|
||||
这种架构让 opencode 支持多个客户端，并允许你以编程方式与 opencode 交互。
|
||||
|
||||
你可以运行 `opencode serve` 来启动一个独立的服务器。如果你已经在运行 opencode TUI，`opencode serve` 会启动一个新的服务器。
|
||||
|
||||
---
|
||||
|
||||
#### 连接到现有服务器
|
||||
|
||||
当你启动 TUI 时，它会随机分配端口和主机名。你也可以传入 `--hostname` 和 `--port` [标志](/docs/cli)，然后用它来连接对应的服务器。
|
||||
|
||||
[`/tui`](#tui) 端点可用于通过服务器驱动 TUI。例如，你可以预填充或运行一个提示词。此方式被 OpenCode [IDE](/docs/ide) 插件所使用。
|
||||
|
||||
---
|
||||
|
||||
## 规范
|
||||
|
||||
服务器发布了一个 OpenAPI 3.1 规范，可在以下地址查看：
|
||||
|
||||
```
|
||||
http://<hostname>:<port>/doc
|
||||
```
|
||||
|
||||
例如，`http://localhost:4096/doc`。使用该规范可以生成客户端或检查请求和响应类型，也可以在 Swagger 浏览器中查看。
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
opencode 服务器暴露以下 API。
|
||||
|
||||
---
|
||||
|
||||
### 全局
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ----- | ---------------- | ------------------------ | ------------------------------------ |
|
||||
| `GET` | `/global/health` | 获取服务器健康状态和版本 | `{ healthy: true, version: string }` |
|
||||
| `GET` | `/global/event` | 获取全局事件（SSE 流） | 事件流 |
|
||||
|
||||
---
|
||||
|
||||
### 项目
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ----- | ------------------ | ------------ | --------------------------------------------- |
|
||||
| `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>Path</code></a> |
|
||||
| `GET` | `/vcs` | 获取当前项目的 VCS 信息 | <a href={typesUrl}><code>VcsInfo</code></a> |
|
||||
|
||||
---
|
||||
|
||||
### 实例
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ------ | ------------------- | ------------ | --------- |
|
||||
| `POST` | `/instance/dispose` | 销毁当前实例 | `boolean` |
|
||||
|
||||
---
|
||||
|
||||
### 配置
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ------- | ------------------- | -------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `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}>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` |
|
||||
|
||||
---
|
||||
|
||||
### 会话
|
||||
|
||||
| 方法 | 路径 | 描述 | 说明 |
|
||||
| -------- | ---------------------------------------- | -------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `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` | 异步发送消息（不等待响应） | 请求体：与 `/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>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>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> |
|
||||
|
||||
#### `/find/file` 查询参数
|
||||
|
||||
- `query`（必需）— 搜索字符串（模糊匹配）
|
||||
- `type`（可选）— 将结果限制为 `"file"` 或 `"directory"`
|
||||
- `directory`（可选）— 覆盖搜索的项目根目录
|
||||
- `limit`（可选）— 最大结果数（1–200）
|
||||
- `dirs`（可选）— 旧版标志（`"false"` 仅返回文件）
|
||||
|
||||
---
|
||||
|
||||
### 工具（实验性）
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ----- | ------------------------------------------- | ---------------------------------- | -------------------------------------------- |
|
||||
| `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
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ------ | ------------ | ------------------- | -------------------------------------------------------- |
|
||||
| `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 状态对象 |
|
||||
|
||||
---
|
||||
|
||||
### 代理
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ----- | -------- | ------------------ | ------------------------------------------- |
|
||||
| `GET` | `/agent` | 列出所有可用的代理 | <a href={typesUrl}><code>Agent[]</code></a> |
|
||||
|
||||
---
|
||||
|
||||
### 日志
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ------ | ------ | ----------------------------------------------------------- | --------- |
|
||||
| `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` |
|
||||
| `GET` | `/tui/control/next` | 等待下一个控制请求 | 控制请求对象 |
|
||||
| `POST` | `/tui/control/response` | 响应控制请求（`{ body }`） | `boolean` |
|
||||
|
||||
---
|
||||
|
||||
### 认证
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ----- | ----------- | -------------------------------------------- | --------- |
|
||||
| `PUT` | `/auth/:id` | 设置认证凭据。请求体必须匹配提供商的数据结构 | `boolean` |
|
||||
|
||||
---
|
||||
|
||||
### 事件
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ----- | -------- | ----------------------------------------------------------------- | ---------------- |
|
||||
| `GET` | `/event` | 服务器发送事件流。第一个事件是 `server.connected`，之后是总线事件 | 服务器发送事件流 |
|
||||
|
||||
---
|
||||
|
||||
### 文档
|
||||
|
||||
| 方法 | 路径 | 描述 | 响应 |
|
||||
| ----- | ------ | ---------------- | ----------------------------- |
|
||||
| `GET` | `/doc` | OpenAPI 3.1 规范 | 包含 OpenAPI 规范的 HTML 页面 |
|
||||
127
packages/web/src/content/docs/zh-cn/share.mdx
Normal file
127
packages/web/src/content/docs/zh-cn/share.mdx
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
title: 分享
|
||||
description: 分享您的 OpenCode 对话。
|
||||
---
|
||||
|
||||
OpenCode 的分享功能允许您创建指向 OpenCode 对话的公开链接，方便与团队成员协作或向他人寻求帮助。
|
||||
|
||||
:::note
|
||||
共享的对话对任何拥有链接的人都是公开可访问的。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 工作原理
|
||||
|
||||
当您分享一段对话时，OpenCode 会：
|
||||
|
||||
1. 为您的会话创建一个唯一的公开 URL
|
||||
2. 将您的对话历史同步到我们的服务器
|
||||
3. 通过可分享的链接使对话可访问 — `opncd.ai/s/<share-id>`
|
||||
|
||||
---
|
||||
|
||||
## 分享模式
|
||||
|
||||
OpenCode 支持三种分享模式，用于控制对话的共享方式：
|
||||
|
||||
---
|
||||
|
||||
### 手动模式（默认）
|
||||
|
||||
默认情况下，OpenCode 使用手动分享模式。会话不会自动共享，但您可以使用 `/share` 命令手动分享：
|
||||
|
||||
```
|
||||
/share
|
||||
```
|
||||
|
||||
这将生成一个唯一的 URL 并复制到您的剪贴板。
|
||||
|
||||
要在[配置文件](/docs/config)中显式设置手动模式：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"share": "manual"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 自动分享
|
||||
|
||||
您可以在[配置文件](/docs/config)中将 `share` 选项设置为 `"auto"`，为所有新对话启用自动分享：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"share": "auto"
|
||||
}
|
||||
```
|
||||
|
||||
启用自动分享后，每个新对话都会自动共享并生成链接。
|
||||
|
||||
---
|
||||
|
||||
### 禁用
|
||||
|
||||
您可以在[配置文件](/docs/config)中将 `share` 选项设置为 `"disabled"`，完全禁用分享功能：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"share": "disabled"
|
||||
}
|
||||
```
|
||||
|
||||
要在团队中对特定项目强制执行此设置，请将其添加到项目的 `opencode.json` 文件中并提交到 Git。
|
||||
|
||||
---
|
||||
|
||||
## 取消分享
|
||||
|
||||
要停止分享对话并将其从公开访问中移除：
|
||||
|
||||
```
|
||||
/unshare
|
||||
```
|
||||
|
||||
这将移除分享链接并删除与该对话相关的数据。
|
||||
|
||||
---
|
||||
|
||||
## 隐私
|
||||
|
||||
分享对话时需要注意以下几点。
|
||||
|
||||
---
|
||||
|
||||
### 数据留存
|
||||
|
||||
共享的对话在您明确取消分享之前将一直保持可访问状态。这包括：
|
||||
|
||||
- 完整的对话历史
|
||||
- 所有消息和回复
|
||||
- 会话元数据
|
||||
|
||||
---
|
||||
|
||||
### 建议
|
||||
|
||||
- 仅分享不包含敏感信息的对话。
|
||||
- 分享前请检查对话内容。
|
||||
- 协作完成后请取消分享。
|
||||
- 避免分享包含专有代码或机密数据的对话。
|
||||
- 对于敏感项目，请完全禁用分享功能。
|
||||
|
||||
---
|
||||
|
||||
## 企业版
|
||||
|
||||
对于企业部署，分享功能可以：
|
||||
|
||||
- 出于安全合规考虑**完全禁用**
|
||||
- **限制**为仅通过 SSO 身份验证的用户可用
|
||||
- **自托管**在您自己的基础设施上
|
||||
|
||||
[了解更多](/docs/enterprise)关于在您的组织中使用 OpenCode 的信息。
|
||||
222
packages/web/src/content/docs/zh-cn/skills.mdx
Normal file
222
packages/web/src/content/docs/zh-cn/skills.mdx
Normal file
@@ -0,0 +1,222 @@
|
||||
---
|
||||
title: "代理技能"
|
||||
description: "通过 SKILL.md 定义可复用的行为"
|
||||
---
|
||||
|
||||
代理技能让 OpenCode 能够从你的仓库或主目录中发现可复用的指令。
|
||||
技能通过原生的 `skill` 工具按需加载——代理可以查看可用技能，并在需要时加载完整内容。
|
||||
|
||||
---
|
||||
|
||||
## 放置文件
|
||||
|
||||
为每个技能名称创建一个文件夹，并在其中放入 `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`
|
||||
- 项目代理兼容：`.agents/skills/<name>/SKILL.md`
|
||||
- 全局代理兼容：`~/.agents/skills/<name>/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` 中加载。
|
||||
|
||||
---
|
||||
|
||||
## 编写 frontmatter
|
||||
|
||||
每个 `SKILL.md` 必须以 YAML frontmatter 开头。
|
||||
仅识别以下字段：
|
||||
|
||||
- `name`（必填）
|
||||
- `description`（必填）
|
||||
- `license`（可选）
|
||||
- `compatibility`（可选）
|
||||
- `metadata`（可选，字符串到字符串的映射）
|
||||
|
||||
未知的 frontmatter 字段会被忽略。
|
||||
|
||||
---
|
||||
|
||||
## 验证名称
|
||||
|
||||
`name` 必须满足：
|
||||
|
||||
- 长度为 1–64 个字符
|
||||
- 仅包含小写字母和数字，可用单个连字符分隔
|
||||
- 不以 `-` 开头或结尾
|
||||
- 不包含连续的 `--`
|
||||
- 与包含 `SKILL.md` 的目录名称一致
|
||||
|
||||
等效的正则表达式：
|
||||
|
||||
```text
|
||||
^[a-z0-9]+(-[a-z0-9]+)*$
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 遵循长度规则
|
||||
|
||||
`description` 必须为 1-1024 个字符。
|
||||
请保持描述足够具体，以便代理能够正确选择。
|
||||
|
||||
---
|
||||
|
||||
## 使用示例
|
||||
|
||||
创建 `.opencode/skills/git-release/SKILL.md`，内容如下：
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: git-release
|
||||
description: Create consistent releases and changelogs
|
||||
license: MIT
|
||||
compatibility: opencode
|
||||
metadata:
|
||||
audience: maintainers
|
||||
workflow: github
|
||||
---
|
||||
|
||||
## What I do
|
||||
|
||||
- Draft release notes from merged PRs
|
||||
- Propose a version bump
|
||||
- Provide a copy-pasteable `gh release create` command
|
||||
|
||||
## When to use me
|
||||
|
||||
Use this when you are preparing a tagged release.
|
||||
Ask clarifying questions if the target versioning scheme is unclear.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 识别工具描述
|
||||
|
||||
OpenCode 会在 `skill` 工具描述中列出可用技能。
|
||||
每个条目包含技能名称和描述：
|
||||
|
||||
```xml
|
||||
<available_skills>
|
||||
<skill>
|
||||
<name>git-release</name>
|
||||
<description>Create consistent releases and changelogs</description>
|
||||
</skill>
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
代理通过调用工具来加载技能：
|
||||
|
||||
```
|
||||
skill({ name: "git-release" })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置权限
|
||||
|
||||
在 `opencode.json` 中使用基于模式的权限来控制代理可以访问哪些技能：
|
||||
|
||||
```json
|
||||
{
|
||||
"permission": {
|
||||
"skill": {
|
||||
"*": "allow",
|
||||
"pr-review": "allow",
|
||||
"internal-*": "deny",
|
||||
"experimental-*": "ask"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 权限 | 行为 |
|
||||
| ------- | ------------------------ |
|
||||
| `allow` | 技能立即加载 |
|
||||
| `deny` | 对代理隐藏技能，拒绝访问 |
|
||||
| `ask` | 加载前提示用户确认 |
|
||||
|
||||
模式支持通配符：`internal-*` 可匹配 `internal-docs`、`internal-tools` 等。
|
||||
|
||||
---
|
||||
|
||||
## 按代理覆盖权限
|
||||
|
||||
为特定代理授予与全局默认值不同的权限。
|
||||
|
||||
**自定义代理**（在代理 frontmatter 中）：
|
||||
|
||||
```yaml
|
||||
---
|
||||
permission:
|
||||
skill:
|
||||
"documents-*": "allow"
|
||||
---
|
||||
```
|
||||
|
||||
**内置代理**（在 `opencode.json` 中）：
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"plan": {
|
||||
"permission": {
|
||||
"skill": {
|
||||
"internal-*": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 禁用技能工具
|
||||
|
||||
为不需要使用技能的代理完全禁用技能功能：
|
||||
|
||||
**自定义代理**：
|
||||
|
||||
```yaml
|
||||
---
|
||||
tools:
|
||||
skill: false
|
||||
---
|
||||
```
|
||||
|
||||
**内置代理**：
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"plan": {
|
||||
"tools": {
|
||||
"skill": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
禁用后，`<available_skills>` 部分将被完全省略。
|
||||
|
||||
---
|
||||
|
||||
## 排查加载问题
|
||||
|
||||
如果某个技能没有显示：
|
||||
|
||||
1. 确认 `SKILL.md` 文件名全部为大写字母
|
||||
2. 检查 frontmatter 是否包含 `name` 和 `description`
|
||||
3. 确保技能名称在所有位置中唯一
|
||||
4. 检查权限设置——设为 `deny` 的技能会对代理隐藏
|
||||
369
packages/web/src/content/docs/zh-cn/themes.mdx
Normal file
369
packages/web/src/content/docs/zh-cn/themes.mdx
Normal file
@@ -0,0 +1,369 @@
|
||||
---
|
||||
title: 主题
|
||||
description: 选择内置主题或定义您自己的主题。
|
||||
---
|
||||
|
||||
通过 OpenCode，您可以从多个内置主题中进行选择，使用能自动适配终端主题的主题，或者定义您自己的自定义主题。
|
||||
|
||||
默认情况下，OpenCode 使用我们自己的 `opencode` 主题。
|
||||
|
||||
---
|
||||
|
||||
## 终端要求
|
||||
|
||||
为了使主题能够正确显示完整的调色板，您的终端必须支持**真彩色**（24 位色）。大多数现代终端默认支持此功能，但您可能需要手动启用：
|
||||
|
||||
- **检查支持情况**：运行 `echo $COLORTERM` — 输出应为 `truecolor` 或 `24bit`
|
||||
- **启用真彩色**：在您的 shell 配置文件中设置环境变量 `COLORTERM=truecolor`
|
||||
- **终端兼容性**：确保您的终端模拟器支持 24 位色（大多数现代终端如 iTerm2、Alacritty、Kitty、Windows Terminal 以及较新版本的 GNOME Terminal 均已支持）
|
||||
|
||||
如果没有真彩色支持，主题可能会出现色彩精度下降的情况，或者回退到最接近的 256 色近似值。
|
||||
|
||||
---
|
||||
|
||||
## 内置主题
|
||||
|
||||
OpenCode 自带多个内置主题。
|
||||
|
||||
| 名称 | 描述 |
|
||||
| ---------------------- | ------------------------------------------------------------------- |
|
||||
| `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_ 主题具有以下特点：
|
||||
|
||||
- **生成灰度色阶**：根据终端的背景颜色创建自定义灰度色阶，确保最佳对比度。
|
||||
- **使用 ANSI 颜色**：利用标准 ANSI 颜色（0-15）进行语法高亮和 UI 元素渲染，遵循终端的调色板设置。
|
||||
- **保留终端默认值**：将文本和背景颜色设为 `none`，以保持终端的原生外观。
|
||||
|
||||
系统主题适合以下用户：
|
||||
|
||||
- 希望 OpenCode 与终端的外观保持一致
|
||||
- 使用了自定义终端配色方案
|
||||
- 偏好所有终端应用程序拥有统一的视觉风格
|
||||
|
||||
---
|
||||
|
||||
## 使用主题
|
||||
|
||||
您可以通过 `/theme` 命令调出主题选择界面来选择主题，也可以在 `tui.json` 文件中直接指定。
|
||||
|
||||
```json title="tui.json" {3}
|
||||
{
|
||||
"$schema": "https://opencode.ai/tui.json",
|
||||
"theme": "tokyonight"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自定义主题
|
||||
|
||||
OpenCode 支持灵活的基于 JSON 的主题系统，让用户可以轻松创建和自定义主题。
|
||||
|
||||
---
|
||||
|
||||
### 层级优先级
|
||||
|
||||
主题按以下顺序从多个目录加载，后面的目录会覆盖前面的目录：
|
||||
|
||||
1. **内置主题** — 嵌入在二进制文件中
|
||||
2. **用户配置目录** — 定义在 `~/.config/opencode/themes/*.json` 或 `$XDG_CONFIG_HOME/opencode/themes/*.json`
|
||||
3. **项目根目录** — 定义在 `<project-root>/.opencode/themes/*.json`
|
||||
4. **当前工作目录** — 定义在 `./.opencode/themes/*.json`
|
||||
|
||||
如果多个目录包含同名主题，将使用优先级较高的目录中的主题。
|
||||
|
||||
---
|
||||
|
||||
### 创建主题
|
||||
|
||||
要创建自定义主题，请在上述任一主题目录中创建一个 JSON 文件。
|
||||
|
||||
创建用户级主题：
|
||||
|
||||
```bash no-frame
|
||||
mkdir -p ~/.config/opencode/themes
|
||||
vim ~/.config/opencode/themes/my-theme.json
|
||||
```
|
||||
|
||||
创建项目级主题：
|
||||
|
||||
```bash no-frame
|
||||
mkdir -p .opencode/themes
|
||||
vim .opencode/themes/my-theme.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### JSON 格式
|
||||
|
||||
主题使用灵活的 JSON 格式，支持以下特性：
|
||||
|
||||
- **十六进制颜色**：`"#ffffff"`
|
||||
- **ANSI 颜色**：`3`（0-255）
|
||||
- **颜色引用**：`"primary"` 或自定义定义的颜色名
|
||||
- **深色/浅色变体**：`{"dark": "#000", "light": "#fff"}`
|
||||
- **无颜色**：`"none"` — 使用终端的默认颜色或透明背景
|
||||
|
||||
---
|
||||
|
||||
### 颜色定义
|
||||
|
||||
`defs` 部分是可选的，它允许您定义可在主题中重复引用的可复用颜色。
|
||||
|
||||
---
|
||||
|
||||
### 终端默认值
|
||||
|
||||
特殊值 `"none"` 可用于任何颜色属性，以继承终端的默认颜色。这在创建需要与终端配色方案无缝融合的主题时特别有用：
|
||||
|
||||
- `"text": "none"` — 使用终端的默认前景色
|
||||
- `"background": "none"` — 使用终端的默认背景色
|
||||
|
||||
---
|
||||
|
||||
### 示例
|
||||
|
||||
以下是一个自定义主题的完整示例：
|
||||
|
||||
```json title="my-theme.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/theme.json",
|
||||
"defs": {
|
||||
"nord0": "#2E3440",
|
||||
"nord1": "#3B4252",
|
||||
"nord2": "#434C5E",
|
||||
"nord3": "#4C566A",
|
||||
"nord4": "#D8DEE9",
|
||||
"nord5": "#E5E9F0",
|
||||
"nord6": "#ECEFF4",
|
||||
"nord7": "#8FBCBB",
|
||||
"nord8": "#88C0D0",
|
||||
"nord9": "#81A1C1",
|
||||
"nord10": "#5E81AC",
|
||||
"nord11": "#BF616A",
|
||||
"nord12": "#D08770",
|
||||
"nord13": "#EBCB8B",
|
||||
"nord14": "#A3BE8C",
|
||||
"nord15": "#B48EAD"
|
||||
},
|
||||
"theme": {
|
||||
"primary": {
|
||||
"dark": "nord8",
|
||||
"light": "nord10"
|
||||
},
|
||||
"secondary": {
|
||||
"dark": "nord9",
|
||||
"light": "nord9"
|
||||
},
|
||||
"accent": {
|
||||
"dark": "nord7",
|
||||
"light": "nord7"
|
||||
},
|
||||
"error": {
|
||||
"dark": "nord11",
|
||||
"light": "nord11"
|
||||
},
|
||||
"warning": {
|
||||
"dark": "nord12",
|
||||
"light": "nord12"
|
||||
},
|
||||
"success": {
|
||||
"dark": "nord14",
|
||||
"light": "nord14"
|
||||
},
|
||||
"info": {
|
||||
"dark": "nord8",
|
||||
"light": "nord10"
|
||||
},
|
||||
"text": {
|
||||
"dark": "nord4",
|
||||
"light": "nord0"
|
||||
},
|
||||
"textMuted": {
|
||||
"dark": "nord3",
|
||||
"light": "nord1"
|
||||
},
|
||||
"background": {
|
||||
"dark": "nord0",
|
||||
"light": "nord6"
|
||||
},
|
||||
"backgroundPanel": {
|
||||
"dark": "nord1",
|
||||
"light": "nord5"
|
||||
},
|
||||
"backgroundElement": {
|
||||
"dark": "nord1",
|
||||
"light": "nord4"
|
||||
},
|
||||
"border": {
|
||||
"dark": "nord2",
|
||||
"light": "nord3"
|
||||
},
|
||||
"borderActive": {
|
||||
"dark": "nord3",
|
||||
"light": "nord2"
|
||||
},
|
||||
"borderSubtle": {
|
||||
"dark": "nord2",
|
||||
"light": "nord3"
|
||||
},
|
||||
"diffAdded": {
|
||||
"dark": "nord14",
|
||||
"light": "nord14"
|
||||
},
|
||||
"diffRemoved": {
|
||||
"dark": "nord11",
|
||||
"light": "nord11"
|
||||
},
|
||||
"diffContext": {
|
||||
"dark": "nord3",
|
||||
"light": "nord3"
|
||||
},
|
||||
"diffHunkHeader": {
|
||||
"dark": "nord3",
|
||||
"light": "nord3"
|
||||
},
|
||||
"diffHighlightAdded": {
|
||||
"dark": "nord14",
|
||||
"light": "nord14"
|
||||
},
|
||||
"diffHighlightRemoved": {
|
||||
"dark": "nord11",
|
||||
"light": "nord11"
|
||||
},
|
||||
"diffAddedBg": {
|
||||
"dark": "#3B4252",
|
||||
"light": "#E5E9F0"
|
||||
},
|
||||
"diffRemovedBg": {
|
||||
"dark": "#3B4252",
|
||||
"light": "#E5E9F0"
|
||||
},
|
||||
"diffContextBg": {
|
||||
"dark": "nord1",
|
||||
"light": "nord5"
|
||||
},
|
||||
"diffLineNumber": {
|
||||
"dark": "nord2",
|
||||
"light": "nord4"
|
||||
},
|
||||
"diffAddedLineNumberBg": {
|
||||
"dark": "#3B4252",
|
||||
"light": "#E5E9F0"
|
||||
},
|
||||
"diffRemovedLineNumberBg": {
|
||||
"dark": "#3B4252",
|
||||
"light": "#E5E9F0"
|
||||
},
|
||||
"markdownText": {
|
||||
"dark": "nord4",
|
||||
"light": "nord0"
|
||||
},
|
||||
"markdownHeading": {
|
||||
"dark": "nord8",
|
||||
"light": "nord10"
|
||||
},
|
||||
"markdownLink": {
|
||||
"dark": "nord9",
|
||||
"light": "nord9"
|
||||
},
|
||||
"markdownLinkText": {
|
||||
"dark": "nord7",
|
||||
"light": "nord7"
|
||||
},
|
||||
"markdownCode": {
|
||||
"dark": "nord14",
|
||||
"light": "nord14"
|
||||
},
|
||||
"markdownBlockQuote": {
|
||||
"dark": "nord3",
|
||||
"light": "nord3"
|
||||
},
|
||||
"markdownEmph": {
|
||||
"dark": "nord12",
|
||||
"light": "nord12"
|
||||
},
|
||||
"markdownStrong": {
|
||||
"dark": "nord13",
|
||||
"light": "nord13"
|
||||
},
|
||||
"markdownHorizontalRule": {
|
||||
"dark": "nord3",
|
||||
"light": "nord3"
|
||||
},
|
||||
"markdownListItem": {
|
||||
"dark": "nord8",
|
||||
"light": "nord10"
|
||||
},
|
||||
"markdownListEnumeration": {
|
||||
"dark": "nord7",
|
||||
"light": "nord7"
|
||||
},
|
||||
"markdownImage": {
|
||||
"dark": "nord9",
|
||||
"light": "nord9"
|
||||
},
|
||||
"markdownImageText": {
|
||||
"dark": "nord7",
|
||||
"light": "nord7"
|
||||
},
|
||||
"markdownCodeBlock": {
|
||||
"dark": "nord4",
|
||||
"light": "nord0"
|
||||
},
|
||||
"syntaxComment": {
|
||||
"dark": "nord3",
|
||||
"light": "nord3"
|
||||
},
|
||||
"syntaxKeyword": {
|
||||
"dark": "nord9",
|
||||
"light": "nord9"
|
||||
},
|
||||
"syntaxFunction": {
|
||||
"dark": "nord8",
|
||||
"light": "nord8"
|
||||
},
|
||||
"syntaxVariable": {
|
||||
"dark": "nord7",
|
||||
"light": "nord7"
|
||||
},
|
||||
"syntaxString": {
|
||||
"dark": "nord14",
|
||||
"light": "nord14"
|
||||
},
|
||||
"syntaxNumber": {
|
||||
"dark": "nord15",
|
||||
"light": "nord15"
|
||||
},
|
||||
"syntaxType": {
|
||||
"dark": "nord7",
|
||||
"light": "nord7"
|
||||
},
|
||||
"syntaxOperator": {
|
||||
"dark": "nord9",
|
||||
"light": "nord9"
|
||||
},
|
||||
"syntaxPunctuation": {
|
||||
"dark": "nord4",
|
||||
"light": "nord0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
341
packages/web/src/content/docs/zh-cn/tools.mdx
Normal file
341
packages/web/src/content/docs/zh-cn/tools.mdx
Normal file
@@ -0,0 +1,341 @@
|
||||
---
|
||||
title: 工具
|
||||
description: 管理 LLM 可以使用的工具。
|
||||
---
|
||||
|
||||
工具允许 LLM 在您的代码库中执行操作。OpenCode 自带一组内置工具，您也可以通过[自定义工具](/docs/custom-tools)或 [MCP 服务器](/docs/mcp-servers)来扩展它。
|
||||
|
||||
默认情况下，所有工具都是**启用**的，且无需权限即可运行。您可以通过[权限](/docs/permissions)来控制工具的行为。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
使用 `permission` 字段来控制工具行为。您可以对每个工具设置允许、拒绝或需要审批。
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "deny",
|
||||
"bash": "ask",
|
||||
"webfetch": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
您还可以使用通配符同时控制多个工具。例如，要求某个 MCP 服务器的所有工具都需要审批：
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"mymcp_*": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[了解更多](/docs/permissions)关于配置权限的内容。
|
||||
|
||||
---
|
||||
|
||||
## 内置工具
|
||||
|
||||
以下是 OpenCode 中所有可用的内置工具。
|
||||
|
||||
---
|
||||
|
||||
### bash
|
||||
|
||||
在项目环境中执行 shell 命令。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"bash": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
该工具允许 LLM 运行终端命令，例如 `npm install`、`git status` 或其他任何 shell 命令。
|
||||
|
||||
---
|
||||
|
||||
### edit
|
||||
|
||||
通过精确的字符串替换来修改现有文件。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
该工具通过替换精确匹配的文本来对文件进行编辑。这是 LLM 修改代码的主要方式。
|
||||
|
||||
---
|
||||
|
||||
### write
|
||||
|
||||
创建新文件或覆盖现有文件。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
使用此工具允许 LLM 创建新文件。如果文件已存在，则会覆盖现有文件。
|
||||
|
||||
:::note
|
||||
`write` 工具由 `edit` 权限控制，该权限涵盖所有文件修改操作（`edit`、`write`、`patch`）。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### read
|
||||
|
||||
读取代码库中的文件内容。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"read": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
该工具读取文件并返回其内容。它支持对大文件读取指定行范围。
|
||||
|
||||
---
|
||||
|
||||
### grep
|
||||
|
||||
使用正则表达式搜索文件内容。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"grep": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在代码库中快速搜索内容。支持完整的正则表达式语法和文件模式过滤。
|
||||
|
||||
---
|
||||
|
||||
### glob
|
||||
|
||||
通过模式匹配查找文件。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"glob": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
使用 `**/*.js` 或 `src/**/*.ts` 等 glob 模式搜索文件。返回按修改时间排序的匹配文件路径。
|
||||
|
||||
---
|
||||
|
||||
### lsp（实验性）
|
||||
|
||||
与已配置的 LSP 服务器交互，获取代码智能功能，如定义跳转、引用查找、悬停信息和调用层次结构。
|
||||
|
||||
:::note
|
||||
该工具仅在设置 `OPENCODE_EXPERIMENTAL_LSP_TOOL=true`（或 `OPENCODE_EXPERIMENTAL=true`）时可用。
|
||||
:::
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"lsp": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
支持的操作包括 `goToDefinition`、`findReferences`、`hover`、`documentSymbol`、`workspaceSymbol`、`goToImplementation`、`prepareCallHierarchy`、`incomingCalls` 和 `outgoingCalls`。
|
||||
|
||||
要配置项目可用的 LSP 服务器，请参阅 [LSP 服务器](/docs/lsp)。
|
||||
|
||||
---
|
||||
|
||||
### patch
|
||||
|
||||
对文件应用补丁。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
该工具将补丁文件应用到您的代码库中。适用于应用来自各种来源的 diff 和补丁。
|
||||
|
||||
:::note
|
||||
`patch` 工具由 `edit` 权限控制，该权限涵盖所有文件修改操作（`edit`、`write`、`patch`）。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### skill
|
||||
|
||||
加载一个[技能](/docs/skills)（即 `SKILL.md` 文件）并在对话中返回其内容。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"skill": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### todowrite
|
||||
|
||||
在编码会话中管理待办事项列表。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"todowrite": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
创建和更新任务列表以跟踪复杂操作的进度。LLM 使用此工具来组织多步骤任务。
|
||||
|
||||
:::note
|
||||
该工具默认对子代理禁用，但您可以手动启用。[了解更多](/docs/agents/#permissions)
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### webfetch
|
||||
|
||||
获取网页内容。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"webfetch": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
允许 LLM 获取并读取网页内容。适用于查阅文档或研究在线资源。
|
||||
|
||||
---
|
||||
|
||||
### websearch
|
||||
|
||||
在网络上搜索信息。
|
||||
|
||||
:::note
|
||||
该工具仅在使用 OpenCode 提供商时，或当 `OPENCODE_ENABLE_EXA` 环境变量设置为任意真值（例如 `true` 或 `1`）时可用。
|
||||
|
||||
在启动 OpenCode 时启用：
|
||||
|
||||
```bash
|
||||
OPENCODE_ENABLE_EXA=1 opencode
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"websearch": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
使用 Exa AI 进行网络搜索以查找相关信息。适用于研究主题、了解时事动态或获取超出训练数据截止日期的信息。
|
||||
|
||||
无需 API 密钥——该工具无需身份验证即可直接连接到 Exa AI 的托管 MCP 服务。
|
||||
|
||||
:::tip
|
||||
当您需要查找信息（发现）时使用 `websearch`，当您需要从特定 URL 获取内容（检索）时使用 `webfetch`。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### question
|
||||
|
||||
在执行过程中向用户提问。
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"question": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
该工具允许 LLM 在执行任务期间向用户提问。适用于以下场景：
|
||||
|
||||
- 收集用户偏好或需求
|
||||
- 澄清模糊的指令
|
||||
- 获取实现方案的决策
|
||||
- 提供方向选择的选项
|
||||
|
||||
每个问题包含标题、问题正文和选项列表。用户可以从提供的选项中选择，也可以输入自定义答案。当有多个问题时，用户可以在提交所有答案之前在各问题之间切换浏览。
|
||||
|
||||
---
|
||||
|
||||
## 自定义工具
|
||||
|
||||
自定义工具允许您定义 LLM 可以调用的自定义函数。这些函数在您的配置文件中定义，可以执行任意代码。
|
||||
|
||||
[了解更多](/docs/custom-tools)关于创建自定义工具的内容。
|
||||
|
||||
---
|
||||
|
||||
## MCP 服务器
|
||||
|
||||
MCP（Model Context Protocol）服务器允许您集成外部工具和服务，包括数据库访问、API 集成和第三方服务。
|
||||
|
||||
[了解更多](/docs/mcp-servers)关于配置 MCP 服务器的内容。
|
||||
|
||||
---
|
||||
|
||||
## 内部机制
|
||||
|
||||
在内部，`grep` 和 `glob` 等工具底层使用 [ripgrep](https://github.com/BurntSushi/ripgrep)。默认情况下，ripgrep 遵循 `.gitignore` 中的模式，这意味着 `.gitignore` 中列出的文件和目录将被排除在搜索和列表结果之外。
|
||||
|
||||
---
|
||||
|
||||
### 忽略模式
|
||||
|
||||
要包含通常会被忽略的文件，请在项目根目录下创建一个 `.ignore` 文件。该文件可以显式允许某些路径。
|
||||
|
||||
```text title=".ignore"
|
||||
!node_modules/
|
||||
!dist/
|
||||
!build/
|
||||
```
|
||||
|
||||
例如，这个 `.ignore` 文件允许 ripgrep 在 `node_modules/`、`dist/` 和 `build/` 目录中进行搜索，即使它们已在 `.gitignore` 中列出。
|
||||
299
packages/web/src/content/docs/zh-cn/troubleshooting.mdx
Normal file
299
packages/web/src/content/docs/zh-cn/troubleshooting.mdx
Normal file
@@ -0,0 +1,299 @@
|
||||
---
|
||||
title: 故障排除
|
||||
description: 常见问题及其解决方法。
|
||||
---
|
||||
|
||||
要调试 OpenCode 的问题，请先检查其存储在磁盘上的日志和本地数据。
|
||||
|
||||
---
|
||||
|
||||
## 日志
|
||||
|
||||
日志文件写入位置：
|
||||
|
||||
- **macOS/Linux**: `~/.local/share/opencode/log/`
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.local\share\opencode\log`
|
||||
|
||||
日志文件以时间戳命名（例如 `2025-01-09T123456.log`），并保留最近的 10 个日志文件。
|
||||
|
||||
你可以通过 `--log-level` 命令行选项设置日志级别以获取更详细的调试信息。例如：`opencode --log-level DEBUG`。
|
||||
|
||||
---
|
||||
|
||||
## 存储
|
||||
|
||||
OpenCode 将会话数据和其他应用数据存储在磁盘上：
|
||||
|
||||
- **macOS/Linux**: `~/.local/share/opencode/`
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.local\share\opencode`
|
||||
|
||||
该目录包含：
|
||||
|
||||
- `auth.json` - 身份验证数据，如 API 密钥、OAuth Token
|
||||
- `log/` - 应用日志
|
||||
- `project/` - 项目特定数据，如会话和消息数据
|
||||
- 如果项目位于 Git 仓库中，则存储在 `./<project-slug>/storage/`
|
||||
- 如果不是 Git 仓库，则存储在 `./global/storage/`
|
||||
|
||||
---
|
||||
|
||||
## 桌面应用
|
||||
|
||||
OpenCode Desktop 会在后台运行一个本地 OpenCode 服务器（即 `opencode-cli` 附属进程）。大多数问题是由插件异常、缓存损坏或错误的服务器设置引起的。
|
||||
|
||||
### 快速检查
|
||||
|
||||
- 完全退出并重新启动应用。
|
||||
- 如果应用显示错误页面，请点击**重新启动**并复制错误详情。
|
||||
- 仅限 macOS：`OpenCode` 菜单 -> **Reload Webview**（当 UI 空白或冻结时有效）。
|
||||
|
||||
---
|
||||
|
||||
### 禁用插件
|
||||
|
||||
如果桌面应用在启动时崩溃、卡住或行为异常，请先禁用插件。
|
||||
|
||||
#### 检查全局配置
|
||||
|
||||
打开你的全局配置文件，查找 `plugin` 键。
|
||||
|
||||
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc`（或 `~/.config/opencode/opencode.json`）
|
||||
- **macOS/Linux**（旧版安装）: `~/.local/share/opencode/opencode.jsonc`
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.config\opencode\opencode.jsonc`
|
||||
|
||||
如果你配置了插件，请通过移除该键或将其设置为空数组来临时禁用它们：
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"plugin": [],
|
||||
}
|
||||
```
|
||||
|
||||
#### 检查插件目录
|
||||
|
||||
OpenCode 还可以从磁盘加载本地插件。临时将这些插件移走（或重命名文件夹），然后重新启动桌面应用：
|
||||
|
||||
- **全局插件**
|
||||
- **macOS/Linux**: `~/.config/opencode/plugins/`
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.config\opencode\plugins`
|
||||
- **项目插件**（仅当你使用了项目级配置时）
|
||||
- `<your-project>/.opencode/plugins/`
|
||||
|
||||
如果应用恢复正常，请逐个重新启用插件，找出导致问题的那个。
|
||||
|
||||
---
|
||||
|
||||
### 清除缓存
|
||||
|
||||
如果禁用插件没有帮助（或插件安装卡住了），请清除缓存以便 OpenCode 重新构建。
|
||||
|
||||
1. 完全退出 OpenCode Desktop。
|
||||
2. 删除缓存目录：
|
||||
|
||||
- **macOS**: Finder -> `Cmd+Shift+G` -> 粘贴 `~/.cache/opencode`
|
||||
- **Linux**: 删除 `~/.cache/opencode`（或运行 `rm -rf ~/.cache/opencode`）
|
||||
- **Windows**: 按 `WIN+R` 并粘贴 `%USERPROFILE%\.cache\opencode`
|
||||
|
||||
3. 重新启动 OpenCode Desktop。
|
||||
|
||||
---
|
||||
|
||||
### 修复服务器连接问题
|
||||
|
||||
OpenCode Desktop 可以启动自己的本地服务器（默认行为），也可以连接到你配置的服务器 URL。
|
||||
|
||||
如果你看到**"Connection Failed"**对话框（或应用始终停留在启动画面），请检查自定义服务器 URL。
|
||||
|
||||
#### 清除桌面默认服务器 URL
|
||||
|
||||
在主页面上，点击服务器名称（带有状态指示点）以打开服务器选择器。在**默认服务器**部分，点击**清除**。
|
||||
|
||||
#### 从配置中移除 `server.port` / `server.hostname`
|
||||
|
||||
如果你的 `opencode.json(c)` 包含 `server` 部分，请临时移除该部分并重新启动桌面应用。
|
||||
|
||||
#### 检查环境变量
|
||||
|
||||
如果你在环境中设置了 `OPENCODE_PORT`，桌面应用将尝试使用该端口作为本地服务器端口。
|
||||
|
||||
- 取消设置 `OPENCODE_PORT`（或选择一个空闲端口）并重新启动。
|
||||
|
||||
---
|
||||
|
||||
### Linux: Wayland / X11 问题
|
||||
|
||||
在 Linux 上，某些 Wayland 设置可能会导致窗口空白或合成器错误。
|
||||
|
||||
- 如果你使用 Wayland 且应用出现空白或崩溃，请尝试使用 `OC_ALLOW_WAYLAND=1` 启动。
|
||||
- 如果情况变得更糟，请移除该设置并尝试在 X11 会话下启动。
|
||||
|
||||
---
|
||||
|
||||
### Windows: WebView2 运行时
|
||||
|
||||
在 Windows 上，OpenCode Desktop 需要 Microsoft Edge **WebView2 Runtime**。如果应用打开后是空白窗口或无法启动，请安装或更新 WebView2 后重试。
|
||||
|
||||
---
|
||||
|
||||
### Windows: 常见性能问题
|
||||
|
||||
如果你在 Windows 上遇到性能缓慢、文件访问问题或终端问题，请尝试使用 [WSL (Windows Subsystem for Linux)](/docs/windows-wsl)。WSL 提供了一个 Linux 环境，能更好地与 OpenCode 的功能兼容。
|
||||
|
||||
---
|
||||
|
||||
### 通知不显示
|
||||
|
||||
OpenCode Desktop 仅在以下情况下显示系统通知：
|
||||
|
||||
- 在操作系统设置中已为 OpenCode 启用通知，且
|
||||
- 应用窗口未处于焦点状态。
|
||||
|
||||
---
|
||||
|
||||
### 重置桌面应用存储（最后手段）
|
||||
|
||||
如果应用无法启动且你无法从 UI 内部清除设置，请重置桌面应用的保存状态。
|
||||
|
||||
1. 退出 OpenCode Desktop。
|
||||
2. 找到并删除以下文件（它们位于 OpenCode Desktop 应用数据目录中）：
|
||||
|
||||
- `opencode.settings.dat`（桌面默认服务器 URL）
|
||||
- `opencode.global.dat` 和 `opencode.workspace.*.dat`（UI 状态，如最近的服务器/项目）
|
||||
|
||||
快速找到该目录：
|
||||
|
||||
- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support`（然后搜索上述文件名）
|
||||
- **Linux**: 在 `~/.local/share` 下搜索上述文件名
|
||||
- **Windows**: 按 `WIN+R` -> `%APPDATA%`（然后搜索上述文件名）
|
||||
|
||||
---
|
||||
|
||||
## 获取帮助
|
||||
|
||||
如果你遇到 OpenCode 的问题：
|
||||
|
||||
1. **在 GitHub 上报告问题**
|
||||
|
||||
报告 Bug 或请求功能的最佳方式是通过我们的 GitHub 仓库：
|
||||
|
||||
[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
|
||||
|
||||
在创建新 Issue 之前，请先搜索已有的 Issue，看看你的问题是否已被报告。
|
||||
|
||||
2. **加入我们的 Discord**
|
||||
|
||||
如需实时帮助和社区讨论，请加入我们的 Discord 服务器：
|
||||
|
||||
[**opencode.ai/discord**](https://opencode.ai/discord)
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
以下是一些常见问题及其解决方法。
|
||||
|
||||
---
|
||||
|
||||
### OpenCode 无法启动
|
||||
|
||||
1. 检查日志中的错误消息
|
||||
2. 尝试使用 `--print-logs` 运行以在终端中查看输出
|
||||
3. 使用 `opencode upgrade` 确保你使用的是最新版本
|
||||
|
||||
---
|
||||
|
||||
### 身份验证问题
|
||||
|
||||
1. 尝试在 TUI 中使用 `/connect` 命令重新进行身份验证
|
||||
2. 检查你的 API 密钥是否有效
|
||||
3. 确保你的网络允许连接到提供商的 API
|
||||
|
||||
---
|
||||
|
||||
### 模型不可用
|
||||
|
||||
1. 检查你是否已通过提供商的身份验证
|
||||
2. 验证配置中的模型名称是否正确
|
||||
3. 某些模型可能需要特定的访问权限或订阅
|
||||
|
||||
如果你遇到 `ProviderModelNotFoundError`，很可能是在某处错误地引用了模型。
|
||||
模型应按如下方式引用：`<providerId>/<modelId>`
|
||||
|
||||
示例：
|
||||
|
||||
- `openai/gpt-4.1`
|
||||
- `openrouter/google/gemini-2.5-flash`
|
||||
- `opencode/kimi-k2`
|
||||
|
||||
要查看你有权访问哪些模型，请运行 `opencode models`
|
||||
|
||||
---
|
||||
|
||||
### ProviderInitError
|
||||
|
||||
如果你遇到 ProviderInitError，很可能是配置无效或已损坏。
|
||||
|
||||
要解决此问题：
|
||||
|
||||
1. 首先，按照[提供商指南](/docs/providers)验证你的提供商是否已正确设置
|
||||
2. 如果问题仍然存在，请尝试清除已存储的配置：
|
||||
|
||||
```bash
|
||||
rm -rf ~/.local/share/opencode
|
||||
```
|
||||
|
||||
在 Windows 上，按 `WIN+R` 并删除：`%USERPROFILE%\.local\share\opencode`
|
||||
|
||||
3. 在 TUI 中使用 `/connect` 命令重新与提供商进行身份验证。
|
||||
|
||||
---
|
||||
|
||||
### AI_APICallError 和提供商包问题
|
||||
|
||||
如果你遇到 API 调用错误，可能是由于提供商包过期导致的。OpenCode 会根据需要动态安装提供商包（OpenAI、Anthropic、Google 等）并将它们缓存到本地。
|
||||
|
||||
要解决提供商包问题：
|
||||
|
||||
1. 清除提供商包缓存：
|
||||
|
||||
```bash
|
||||
rm -rf ~/.cache/opencode
|
||||
```
|
||||
|
||||
在 Windows 上，按 `WIN+R` 并删除：`%USERPROFILE%\.cache\opencode`
|
||||
|
||||
2. 重新启动 OpenCode 以重新安装最新的提供商包
|
||||
|
||||
这将强制 OpenCode 下载最新版本的提供商包，通常可以解决模型参数和 API 变更带来的兼容性问题。
|
||||
|
||||
---
|
||||
|
||||
### 在 Linux 上复制/粘贴不可用
|
||||
|
||||
Linux 用户需要安装以下剪贴板工具之一，复制/粘贴功能才能正常工作：
|
||||
|
||||
**对于 X11 系统：**
|
||||
|
||||
```bash
|
||||
apt install -y xclip
|
||||
# or
|
||||
apt install -y xsel
|
||||
```
|
||||
|
||||
**对于 Wayland 系统：**
|
||||
|
||||
```bash
|
||||
apt install -y wl-clipboard
|
||||
```
|
||||
|
||||
**对于无头环境：**
|
||||
|
||||
```bash
|
||||
apt install -y xvfb
|
||||
# and run:
|
||||
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
|
||||
export DISPLAY=:99.0
|
||||
```
|
||||
|
||||
OpenCode 会检测你是否正在使用 Wayland 并优先使用 `wl-clipboard`，否则将按以下顺序尝试查找剪贴板工具：`xclip` 和 `xsel`。
|
||||
426
packages/web/src/content/docs/zh-cn/tui.mdx
Normal file
426
packages/web/src/content/docs/zh-cn/tui.mdx
Normal file
@@ -0,0 +1,426 @@
|
||||
---
|
||||
title: TUI
|
||||
description: 使用 OpenCode 终端用户界面。
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from "@astrojs/starlight/components"
|
||||
|
||||
OpenCode 提供了一个交互式终端界面（TUI），用于配合 LLM 处理您的项目。
|
||||
|
||||
运行 OpenCode 即可启动当前目录的 TUI。
|
||||
|
||||
```bash
|
||||
opencode
|
||||
```
|
||||
|
||||
或者您可以为指定的工作目录启动它。
|
||||
|
||||
```bash
|
||||
opencode /path/to/project
|
||||
```
|
||||
|
||||
进入 TUI 后，您可以输入消息进行提示。
|
||||
|
||||
```text
|
||||
Give me a quick summary of the codebase.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文件引用
|
||||
|
||||
您可以使用 `@` 在消息中引用文件。这会在当前工作目录中进行模糊文件搜索。
|
||||
|
||||
:::tip
|
||||
您还可以使用 `@` 来引用消息中的文件。
|
||||
:::
|
||||
|
||||
```text "@packages/functions/src/api/index.ts"
|
||||
How is auth handled in @packages/functions/src/api/index.ts?
|
||||
```
|
||||
|
||||
文件的内容会自动添加到对话中。
|
||||
|
||||
---
|
||||
|
||||
## Bash 命令
|
||||
|
||||
以 `!` 开头的消息会作为 shell 命令执行。
|
||||
|
||||
```bash frame="none"
|
||||
!ls -la
|
||||
```
|
||||
|
||||
命令的输出会作为工具结果添加到对话中。
|
||||
|
||||
---
|
||||
|
||||
## 命令
|
||||
|
||||
使用 OpenCode TUI 时，您可以输入 `/` 后跟命令名称来快速执行操作。例如：
|
||||
|
||||
```bash frame="none"
|
||||
/help
|
||||
```
|
||||
|
||||
大多数命令还支持以 `ctrl+x` 作为前导键的快捷键，其中 `ctrl+x` 是默认前导键。[了解更多](/docs/keybinds)。
|
||||
|
||||
以下是所有可用的斜杠命令：
|
||||
|
||||
---
|
||||
|
||||
### connect
|
||||
|
||||
将提供商添加到 OpenCode。允许您从可用的提供商中选择并添加其 API 密钥。
|
||||
|
||||
```bash frame="none"
|
||||
/connect
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### compact
|
||||
|
||||
压缩当前会话。_别名_：`/summarize`
|
||||
|
||||
```bash frame="none"
|
||||
/compact
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x c`
|
||||
|
||||
---
|
||||
|
||||
### details
|
||||
|
||||
切换工具执行详情的显示。
|
||||
|
||||
```bash frame="none"
|
||||
/details
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x d`
|
||||
|
||||
---
|
||||
|
||||
### editor
|
||||
|
||||
打开外部编辑器来编写消息。使用 `EDITOR` 环境变量中设置的编辑器。[了解更多](#editor-setup)。
|
||||
|
||||
```bash frame="none"
|
||||
/editor
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x e`
|
||||
|
||||
---
|
||||
|
||||
### exit
|
||||
|
||||
退出 OpenCode。_别名_：`/quit`、`/q`
|
||||
|
||||
```bash frame="none"
|
||||
/exit
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x q`
|
||||
|
||||
---
|
||||
|
||||
### export
|
||||
|
||||
将当前对话导出为 Markdown 并在默认编辑器中打开。使用 `EDITOR` 环境变量中设置的编辑器。[了解更多](#editor-setup)。
|
||||
|
||||
```bash frame="none"
|
||||
/export
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x x`
|
||||
|
||||
---
|
||||
|
||||
### help
|
||||
|
||||
显示帮助对话框。
|
||||
|
||||
```bash frame="none"
|
||||
/help
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x h`
|
||||
|
||||
---
|
||||
|
||||
### init
|
||||
|
||||
创建或更新 `AGENTS.md` 文件。[了解更多](/docs/rules)。
|
||||
|
||||
```bash frame="none"
|
||||
/init
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x i`
|
||||
|
||||
---
|
||||
|
||||
### models
|
||||
|
||||
列出可用模型。
|
||||
|
||||
```bash frame="none"
|
||||
/models
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x m`
|
||||
|
||||
---
|
||||
|
||||
### new
|
||||
|
||||
开始新的会话。_别名_：`/clear`
|
||||
|
||||
```bash frame="none"
|
||||
/new
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x n`
|
||||
|
||||
---
|
||||
|
||||
### redo
|
||||
|
||||
重做之前撤销的消息。仅在使用 `/undo` 后可用。
|
||||
|
||||
:::tip
|
||||
所有文件更改也会被恢复。
|
||||
:::
|
||||
|
||||
在内部，这使用 Git 来管理文件更改。因此您的项目**需要是一个 Git 仓库**。
|
||||
|
||||
```bash frame="none"
|
||||
/redo
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x r`
|
||||
|
||||
---
|
||||
|
||||
### sessions
|
||||
|
||||
列出会话并在会话之间切换。_别名_：`/resume`、`/continue`
|
||||
|
||||
```bash frame="none"
|
||||
/sessions
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x l`
|
||||
|
||||
---
|
||||
|
||||
### share
|
||||
|
||||
分享当前会话。[了解更多](/docs/share)。
|
||||
|
||||
```bash frame="none"
|
||||
/share
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x s`
|
||||
|
||||
---
|
||||
|
||||
### themes
|
||||
|
||||
列出可用主题。
|
||||
|
||||
```bash frame="none"
|
||||
/themes
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x t`
|
||||
|
||||
---
|
||||
|
||||
### thinking
|
||||
|
||||
切换对话中思考/推理块的可见性。启用后，您可以看到支持扩展思考的模型的推理过程。
|
||||
|
||||
:::note
|
||||
此命令仅控制思考块是否**显示** — 它不会启用或禁用模型的推理能力。要切换实际的推理能力，请使用 `ctrl+t` 循环切换模型变体。
|
||||
:::
|
||||
|
||||
```bash frame="none"
|
||||
/thinking
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### undo
|
||||
|
||||
撤销对话中的最后一条消息。移除最近的用户消息、所有后续响应以及所有文件更改。
|
||||
|
||||
:::tip
|
||||
所做的任何文件更改也会被还原。
|
||||
:::
|
||||
|
||||
在内部，这使用 Git 来管理文件更改。因此您的项目**需要是一个 Git 仓库**。
|
||||
|
||||
```bash frame="none"
|
||||
/undo
|
||||
```
|
||||
|
||||
**快捷键：** `ctrl+x u`
|
||||
|
||||
---
|
||||
|
||||
### unshare
|
||||
|
||||
取消分享当前会话。[了解更多](/docs/share#un-sharing)。
|
||||
|
||||
```bash frame="none"
|
||||
/unshare
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 编辑器设置
|
||||
|
||||
`/editor` 和 `/export` 命令都使用 `EDITOR` 环境变量中指定的编辑器。
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Linux/macOS">
|
||||
```bash
|
||||
# Example for nano or vim
|
||||
export EDITOR=nano
|
||||
export EDITOR=vim
|
||||
|
||||
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
|
||||
# include --wait
|
||||
export EDITOR="code --wait"
|
||||
```
|
||||
|
||||
要使其永久生效，请将其添加到您的 shell 配置文件中；
|
||||
`~/.bashrc`、`~/.zshrc` 等。
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Windows (CMD)">
|
||||
```bash
|
||||
set EDITOR=notepad
|
||||
|
||||
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
|
||||
# include --wait
|
||||
set EDITOR=code --wait
|
||||
```
|
||||
|
||||
要使其永久生效，请使用**系统属性** > **环境变量**。
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Windows (PowerShell)">
|
||||
```powershell
|
||||
$env:EDITOR = "notepad"
|
||||
|
||||
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
|
||||
# include --wait
|
||||
$env:EDITOR = "code --wait"
|
||||
```
|
||||
|
||||
要使其永久生效，请将其添加到您的 PowerShell 配置文件中。
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
常用的编辑器选项包括：
|
||||
|
||||
- `code` - Visual Studio Code
|
||||
- `cursor` - Cursor
|
||||
- `windsurf` - Windsurf
|
||||
- `nvim` - Neovim 编辑器
|
||||
- `vim` - Vim 编辑器
|
||||
- `nano` - Nano 编辑器
|
||||
- `notepad` - Notepad（Windows 记事本）
|
||||
- `subl` - Sublime Text
|
||||
|
||||
:::note
|
||||
某些编辑器（如 VS Code）需要以 `--wait` 标志启动。
|
||||
:::
|
||||
|
||||
某些编辑器需要命令行参数才能以阻塞模式运行。`--wait` 标志使编辑器进程阻塞直到关闭。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
您可以通过 `tui.json`（或 `tui.jsonc`）自定义 TUI 行为。
|
||||
|
||||
```json title="tui.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/tui.json",
|
||||
"theme": "opencode",
|
||||
"leader_timeout": 2000,
|
||||
"keybinds": {
|
||||
"leader": "ctrl+x",
|
||||
"command_list": "ctrl+p"
|
||||
},
|
||||
"scroll_speed": 3,
|
||||
"scroll_acceleration": {
|
||||
"enabled": false
|
||||
},
|
||||
"diff_style": "auto",
|
||||
"mouse": true,
|
||||
"attention": {
|
||||
"enabled": true,
|
||||
"notifications": true,
|
||||
"sound": true,
|
||||
"volume": 0.4,
|
||||
"sound_pack": "opencode.default",
|
||||
"sounds": {
|
||||
"error": "./sounds/error.mp3"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这与 `opencode.json` 是分开的；`opencode.json` 用于配置服务器和运行时行为。
|
||||
|
||||
`keybinds` 会与内置默认值合并，因此你只需要配置想要修改的快捷键。
|
||||
|
||||
### 选项
|
||||
|
||||
- `theme` - 设置 UI 主题。[了解更多](/docs/themes)。
|
||||
- `keybinds` - 自定义键盘快捷键。[了解更多](/docs/keybinds)。
|
||||
- `leader_timeout` - 控制按下 leader key 后 OpenCode 等待后续按键的时间。默认为 `2000`。
|
||||
- `scroll_acceleration.enabled` - 启用 macOS 风格的滚动加速，让滚动更平滑自然。启用后，快速滚动时速度会增加，慢速移动时仍保持精确。**此设置优先于 `scroll_speed`，启用时会覆盖它。**
|
||||
- `scroll_speed` - 控制使用滚动命令时 TUI 的滚动速度（最小值：`0.001`，支持小数）。默认为 `3`。**注意：如果 `scroll_acceleration.enabled` 设置为 `true`，则此设置会被忽略。**
|
||||
- `diff_style` - 控制 diff 的显示方式。`"auto"` 会根据终端宽度自适应，`"stacked"` 始终显示单列布局。
|
||||
- `mouse` - 在 TUI 中启用或禁用鼠标捕获（默认：`true`）。禁用后，终端原生的鼠标选择和滚动行为会保留下来。
|
||||
- `attention` - 配置 TUI 桌面通知和声音。默认禁用。
|
||||
|
||||
使用 `OPENCODE_TUI_CONFIG` 可以加载自定义的 TUI 配置文件路径。
|
||||
|
||||
### Attention
|
||||
|
||||
当 OpenCode 需要你处理问题、批准权限请求、查看会话错误，或想告知会话已完成时，TUI 可以通过声音和桌面通知提醒你。设置 `attention.enabled` 后会启用这些提醒；内置事件触发时会播放声音。桌面通知只会在终端窗口未聚焦时发送，并且不会用于 subagent 事件。
|
||||
|
||||
- `enabled` - 开启 Attention 的所有通知和声音。默认为 `false`。
|
||||
- `notifications` - 启用 Attention 后，允许 TUI 通过终端发送桌面通知。默认为 `true`。
|
||||
- `sound` - 启用 Attention 后，允许播放提示音。默认为 `true`。
|
||||
- `volume` - 默认提示音音量，范围从 `0` 到 `1`。默认为 `0.4`。
|
||||
- `sound_pack` - 要使用的 sound pack ID。默认为 `opencode.default`。
|
||||
- `sounds` - 为 `default`、`question`、`permission`、`error`、`done` 或 `subagent_done` 指定自定义声音文件。路径可以是绝对路径、`file://` URL，或相对于 `tui.json` 的路径。
|
||||
|
||||
---
|
||||
|
||||
## 自定义
|
||||
|
||||
您可以使用命令面板（`ctrl+x h` 或 `/help`）自定义 TUI 视图的各个方面。这些设置在重启后仍会保留。
|
||||
|
||||
---
|
||||
|
||||
#### 用户名显示
|
||||
|
||||
切换您的用户名是否显示在聊天消息中。通过以下方式访问：
|
||||
|
||||
- 命令面板：搜索 "username" 或 "hide username"
|
||||
- 该设置会自动保存，并在各个 TUI 会话中保持记忆
|
||||
142
packages/web/src/content/docs/zh-cn/web.mdx
Normal file
142
packages/web/src/content/docs/zh-cn/web.mdx
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: Web
|
||||
description: 在浏览器中使用 OpenCode。
|
||||
---
|
||||
|
||||
OpenCode 可以作为 Web 应用在浏览器中运行，无需终端即可获得同样强大的 AI 编码体验。
|
||||
|
||||
|
||||
|
||||
## 快速开始
|
||||
|
||||
运行以下命令启动 Web 界面：
|
||||
|
||||
```bash
|
||||
opencode web
|
||||
```
|
||||
|
||||
这会在 `127.0.0.1` 上启动一个本地服务器，使用随机可用端口，并自动在默认浏览器中打开 OpenCode。
|
||||
|
||||
:::caution
|
||||
如果未设置 `OPENCODE_SERVER_PASSWORD`，服务器将没有安全保护。本地使用没有问题，但在网络访问时应当设置密码。
|
||||
:::
|
||||
|
||||
:::tip[Windows 用户]
|
||||
为获得最佳体验，建议从 [WSL](/docs/windows-wsl) 而非 PowerShell 运行 `opencode web`。这可以确保正确的文件系统访问和终端集成。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
你可以通过命令行标志或[配置文件](/docs/config)来配置 Web 服务器。
|
||||
|
||||
### 端口
|
||||
|
||||
默认情况下，OpenCode 会选择一个可用端口。你也可以指定端口：
|
||||
|
||||
```bash
|
||||
opencode web --port 4096
|
||||
```
|
||||
|
||||
### 主机名
|
||||
|
||||
默认情况下，服务器绑定到 `127.0.0.1`（仅限本地访问）。要使 OpenCode 在网络中可访问：
|
||||
|
||||
```bash
|
||||
opencode web --hostname 0.0.0.0
|
||||
```
|
||||
|
||||
使用 `0.0.0.0` 时，OpenCode 会同时显示本地地址和网络地址：
|
||||
|
||||
```
|
||||
Local access: http://localhost:4096
|
||||
Network access: http://192.168.1.100:4096
|
||||
```
|
||||
|
||||
### mDNS 发现
|
||||
|
||||
启用 mDNS 可以让你的服务器在本地网络中被自动发现：
|
||||
|
||||
```bash
|
||||
opencode web --mdns
|
||||
```
|
||||
|
||||
这会自动将主机名设置为 `0.0.0.0`，并将服务器广播为 `opencode.local`。
|
||||
|
||||
你可以自定义 mDNS 域名，以便在同一网络中运行多个实例：
|
||||
|
||||
```bash
|
||||
opencode web --mdns --mdns-domain myproject.local
|
||||
```
|
||||
|
||||
### CORS
|
||||
|
||||
要为 CORS 添加额外的允许域名（适用于自定义前端）：
|
||||
|
||||
```bash
|
||||
opencode web --cors https://example.com
|
||||
```
|
||||
|
||||
### 身份验证
|
||||
|
||||
要保护服务器访问，可以通过 `OPENCODE_SERVER_PASSWORD` 环境变量设置密码：
|
||||
|
||||
```bash
|
||||
OPENCODE_SERVER_PASSWORD=secret opencode web
|
||||
```
|
||||
|
||||
用户名默认为 `opencode`，可以通过 `OPENCODE_SERVER_USERNAME` 进行更改。
|
||||
|
||||
---
|
||||
|
||||
## 使用 Web 界面
|
||||
|
||||
启动后，Web 界面提供对 OpenCode 会话的访问。
|
||||
|
||||
### 会话
|
||||
|
||||
在主页上查看和管理你的会话。你可以查看活跃的会话，也可以创建新的会话。
|
||||
|
||||
|
||||
|
||||
### 服务器状态
|
||||
|
||||
点击"See Servers"可以查看已连接的服务器及其状态。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 连接终端
|
||||
|
||||
你可以将终端 TUI 连接到正在运行的 Web 服务器：
|
||||
|
||||
```bash
|
||||
# 启动 Web 服务器
|
||||
opencode web --port 4096
|
||||
|
||||
# 在另一个终端中连接 TUI
|
||||
opencode attach http://localhost:4096
|
||||
```
|
||||
|
||||
这样你就可以同时使用 Web 界面和终端，共享相同的会话和状态。
|
||||
|
||||
---
|
||||
|
||||
## 配置文件
|
||||
|
||||
你也可以在 `opencode.json` 配置文件中设置服务器选项：
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"port": 4096,
|
||||
"hostname": "0.0.0.0",
|
||||
"mdns": true,
|
||||
"cors": ["https://example.com"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
命令行标志的优先级高于配置文件中的设置。
|
||||
112
packages/web/src/content/docs/zh-cn/windows-wsl.mdx
Normal file
112
packages/web/src/content/docs/zh-cn/windows-wsl.mdx
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: Windows (WSL)
|
||||
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 提供了一个 Linux 环境，能够与 OpenCode 的各项功能无缝配合。
|
||||
|
||||
:::tip[为什么选择 WSL？]
|
||||
WSL 提供更出色的文件系统性能、完整的终端支持，以及与 OpenCode 所依赖的开发工具的良好兼容性。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 安装配置
|
||||
|
||||
<Steps>
|
||||
|
||||
1. **安装 WSL**
|
||||
|
||||
如果尚未安装，请参照 Microsoft 官方指南[安装 WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。
|
||||
|
||||
2. **在 WSL 中安装 OpenCode**
|
||||
|
||||
WSL 设置完成后，打开 WSL 终端，使用任一[安装方式](/docs/)安装 OpenCode。
|
||||
|
||||
```bash
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
```
|
||||
|
||||
3. **从 WSL 中使用 OpenCode**
|
||||
|
||||
导航到你的项目目录（通过 `/mnt/c/`、`/mnt/d/` 等路径访问 Windows 文件），然后运行 OpenCode。
|
||||
|
||||
```bash
|
||||
cd /mnt/c/Users/YourName/project
|
||||
opencode
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## 桌面应用 + WSL 服务器
|
||||
|
||||
如果你希望使用 OpenCode 桌面应用，同时在 WSL 中运行服务器：
|
||||
|
||||
1. **在 WSL 中启动服务器**，添加 `--hostname 0.0.0.0` 以允许外部连接：
|
||||
|
||||
```bash
|
||||
opencode serve --hostname 0.0.0.0 --port 4096
|
||||
```
|
||||
|
||||
2. **在桌面应用中连接到** `http://localhost:4096`
|
||||
|
||||
:::note
|
||||
如果 `localhost` 在你的环境中无法使用，请改用 WSL 的 IP 地址进行连接（在 WSL 中运行：`hostname -I`），使用 `http://<wsl-ip>:4096`。
|
||||
:::
|
||||
|
||||
:::caution
|
||||
使用 `--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 体验：
|
||||
|
||||
1. **在 WSL 终端中运行 `opencode web`**，而非在 PowerShell 中运行：
|
||||
|
||||
```bash
|
||||
opencode web --hostname 0.0.0.0
|
||||
```
|
||||
|
||||
2. **在 Windows 浏览器中访问** `http://localhost:<port>`（OpenCode 会输出该 URL）
|
||||
|
||||
从 WSL 中运行 `opencode web` 可确保正确的文件系统访问和终端集成，同时仍可通过 Windows 浏览器进行访问。
|
||||
|
||||
---
|
||||
|
||||
## 访问 Windows 文件
|
||||
|
||||
WSL 可以通过 `/mnt/` 目录访问你的所有 Windows 文件：
|
||||
|
||||
- `C:` 盘 → `/mnt/c/`
|
||||
- `D:` 盘 → `/mnt/d/`
|
||||
- 其他盘符以此类推...
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
cd /mnt/c/Users/YourName/Documents/project
|
||||
opencode
|
||||
```
|
||||
|
||||
:::tip
|
||||
为了获得更流畅的体验，建议将仓库克隆或复制到 WSL 文件系统中（例如 `~/code/` 目录下），然后在该位置运行 OpenCode。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 使用技巧
|
||||
|
||||
- 对于存储在 Windows 驱动器上的项目，在 WSL 中运行 OpenCode 即可无缝访问文件
|
||||
- 搭配 VS Code 的 [WSL 扩展](https://code.visualstudio.com/docs/remote/wsl) 使用 OpenCode，打造一体化的开发工作流
|
||||
- OpenCode 的配置和会话数据存储在 WSL 环境中的 `~/.local/share/opencode/`
|
||||
296
packages/web/src/content/docs/zh-cn/zen.mdx
Normal file
296
packages/web/src/content/docs/zh-cn/zen.mdx
Normal file
@@ -0,0 +1,296 @@
|
||||
---
|
||||
title: Zen
|
||||
description: 由 OpenCode 提供的精选模型列表。
|
||||
---
|
||||
|
||||
import config from "../../../../config.mjs"
|
||||
export const console = config.console
|
||||
export const email = `mailto:${config.email}`
|
||||
|
||||
OpenCode Zen 是由 OpenCode 团队提供的一组经过测试和验证的模型。
|
||||
|
||||
Zen 的工作方式与 OpenCode 中的任何其他提供商相同。你登录 OpenCode Zen 并获取 API 密钥。它是**完全可选的**，即使不用它，你也可以照常使用 OpenCode。
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
现在市面上有大量模型，但其中只有少数模型适合作为编码代理使用。此外，大多数提供商的配置方式差异很大，因此你获得的性能和质量也会非常不同。
|
||||
|
||||
:::tip
|
||||
我们测试了一组与 OpenCode 配合良好的精选模型和提供商。
|
||||
:::
|
||||
|
||||
所以，如果你通过 OpenRouter 之类的服务使用模型，你无法确定自己拿到的是否是目标模型的最佳版本。
|
||||
|
||||
为了解决这个问题，我们做了几件事：
|
||||
|
||||
1. 我们测试了一组选定的模型，并与它们的团队讨论了如何以最佳方式运行这些模型。
|
||||
2. 然后我们与几家提供商合作，确保这些模型被正确提供。
|
||||
3. 最后，我们对模型和提供商的组合进行了基准测试，并整理出了一份我们认为值得推荐的列表。
|
||||
|
||||
OpenCode Zen 是一个 AI 网关，让你可以访问这些模型。
|
||||
|
||||
---
|
||||
|
||||
## 工作原理
|
||||
|
||||
OpenCode Zen 的工作方式与 OpenCode 中的任何其他提供商相同。
|
||||
|
||||
1. 登录 **<a href={console}>OpenCode Zen</a>**，添加你的账单信息，然后复制你的 API 密钥。
|
||||
2. 在 TUI 中运行 `/connect` 命令，选择 OpenCode Zen，然后粘贴你的 API 密钥。
|
||||
3. 在 TUI 中运行 `/models`，查看我们推荐的模型列表。
|
||||
|
||||
你按请求付费，也可以向账户充值。
|
||||
|
||||
---
|
||||
|
||||
## 端点
|
||||
|
||||
你也可以通过以下 API 端点访问我们的模型。
|
||||
|
||||
| 模型 | 模型 ID | 端点 | AI SDK 包 |
|
||||
| ---------------------- | ---------------------- | ---------------------------------------------------- | --------------------------- |
|
||||
| GPT 5.5 | gpt-5.5 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.5 Pro | gpt-5.5-pro | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.4 | gpt-5.4 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.4 Pro | gpt-5.4-pro | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.4 Mini | gpt-5.4-mini | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.4 Nano | gpt-5.4-nano | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.3 Codex | gpt-5.3-codex | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.3 Codex Spark | gpt-5.3-codex-spark | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| 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` |
|
||||
| GPT 5.1 | gpt-5.1 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 Codex | gpt-5.1-codex | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 Codex Max | gpt-5.1-codex-max | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 Codex Mini | gpt-5.1-codex-mini | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 | gpt-5 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 Codex | gpt-5-codex | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 Nano | gpt-5-nano | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| Claude Fable 5 | claude-fable-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.8 | claude-opus-4-8 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.7 | claude-opus-4-7 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.6 | claude-opus-4-6 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.5 | claude-opus-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.1 | claude-opus-4-1 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Sonnet 4.6 | claude-sonnet-4-6 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Sonnet 4.5 | claude-sonnet-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Sonnet 4 | claude-sonnet-4 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Haiku 4.5 | claude-haiku-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Haiku 3.5 | claude-3-5-haiku | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Gemini 3.5 Flash | gemini-3.5-flash | `https://opencode.ai/zen/v1/models/gemini-3.5-flash` | `@ai-sdk/google` |
|
||||
| Gemini 3.1 Pro | gemini-3.1-pro | `https://opencode.ai/zen/v1/models/gemini-3.1-pro` | `@ai-sdk/google` |
|
||||
| Gemini 3 Flash | gemini-3-flash | `https://opencode.ai/zen/v1/models/gemini-3-flash` | `@ai-sdk/google` |
|
||||
| Qwen3.7 Max | qwen3.7-max | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Qwen3.7 Plus | qwen3.7-plus | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Qwen3.6 Plus | qwen3.6-plus | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Qwen3.5 Plus | qwen3.5-plus | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| DeepSeek V4 Pro | deepseek-v4-pro | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| DeepSeek V4 Flash | deepseek-v4-flash | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| MiniMax M2.7 | minimax-m2.7 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| MiniMax M2.5 | minimax-m2.5 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| GLM 5.1 | glm-5.1 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| GLM 5 | glm-5 | `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.6 | kimi-k2.6 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Grok Build 0.1 | grok-build-0.1 | `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` |
|
||||
| MiMo-V2.5 Free | mimo-v2.5-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| North Mini Code Free | north-mini-code-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Nemotron 3 Ultra Free | nemotron-3-ultra-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| DeepSeek V4 Flash Free | deepseek-v4-flash-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
|
||||
在你的 OpenCode 配置中，[模型 ID](/docs/config/#models) 使用 `opencode/<model-id>` 格式。例如，对于 GPT 5.5，你需要在配置中使用 `opencode/gpt-5.5`。
|
||||
|
||||
---
|
||||
|
||||
### 模型
|
||||
|
||||
你可以从以下地址获取可用模型及其元数据的完整列表：
|
||||
|
||||
```
|
||||
https://opencode.ai/zen/v1/models
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 定价
|
||||
|
||||
我们支持按量付费模式。以下是**每 1M tokens** 的价格。
|
||||
|
||||
| 模型 | 输入 | 输出 | 缓存读取 | 缓存写入 |
|
||||
| --------------------------------- | ------ | ------- | -------- | -------- |
|
||||
| Big Pickle | Free | Free | Free | - |
|
||||
| DeepSeek V4 Flash Free | Free | Free | Free | - |
|
||||
| MiMo-V2.5 Free | Free | Free | Free | - |
|
||||
| North Mini Code Free | Free | Free | Free | - |
|
||||
| Nemotron 3 Ultra Free | Free | Free | Free | - |
|
||||
| MiniMax M2.7 | $0.30 | $1.20 | $0.06 | $0.375 |
|
||||
| MiniMax M2.5 | $0.30 | $1.20 | $0.06 | $0.375 |
|
||||
| GLM 5.1 | $1.40 | $4.40 | $0.26 | - |
|
||||
| GLM 5 | $1.00 | $3.20 | $0.20 | - |
|
||||
| Kimi K2.5 | $0.60 | $3.00 | $0.10 | - |
|
||||
| Kimi K2.6 | $0.95 | $4.00 | $0.16 | - |
|
||||
| Qwen3.7 Max | $2.50 | $7.50 | $0.50 | $3.125 |
|
||||
| Qwen3.7 Plus | $0.40 | $1.60 | $0.04 | $0.50 |
|
||||
| Qwen3.6 Plus | $0.50 | $3.00 | $0.05 | $0.625 |
|
||||
| Qwen3.5 Plus | $0.20 | $1.20 | $0.02 | $0.25 |
|
||||
| DeepSeek V4 Pro | $1.74 | $3.48 | $0.145 | - |
|
||||
| DeepSeek V4 Flash | $0.14 | $0.28 | $0.028 | - |
|
||||
| Grok Build 0.1 | $1.00 | $2.00 | $0.20 | - |
|
||||
| Claude Fable 5 | $10.00 | $50.00 | $1.00 | $12.50 |
|
||||
| Claude Opus 4.8 | $5.00 | $25.00 | $0.50 | $6.25 |
|
||||
| Claude Opus 4.7 | $5.00 | $25.00 | $0.50 | $6.25 |
|
||||
| Claude Opus 4.6 | $5.00 | $25.00 | $0.50 | $6.25 |
|
||||
| Claude Opus 4.5 | $5.00 | $25.00 | $0.50 | $6.25 |
|
||||
| Claude Opus 4.1 | $15.00 | $75.00 | $1.50 | $18.75 |
|
||||
| Claude Sonnet 4.6 | $3.00 | $15.00 | $0.30 | $3.75 |
|
||||
| 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 |
|
||||
| Gemini 3.5 Flash | $1.50 | $9.00 | $0.15 | - |
|
||||
| Gemini 3.1 Pro (≤ 200K tokens) | $2.00 | $12.00 | $0.20 | - |
|
||||
| Gemini 3.1 Pro (> 200K tokens) | $4.00 | $18.00 | $0.40 | - |
|
||||
| Gemini 3 Flash | $0.50 | $3.00 | $0.05 | - |
|
||||
| GPT 5.5 (≤ 272K tokens) | $5.00 | $30.00 | $0.50 | - |
|
||||
| GPT 5.5 (> 272K tokens) | $10.00 | $45.00 | $1.00 | - |
|
||||
| GPT 5.5 Pro | $30.00 | $180.00 | $30.00 | - |
|
||||
| GPT 5.4 (≤ 272K tokens) | $2.50 | $15.00 | $0.25 | - |
|
||||
| GPT 5.4 (> 272K tokens) | $5.00 | $22.50 | $0.50 | - |
|
||||
| GPT 5.4 Pro | $30.00 | $180.00 | $30.00 | - |
|
||||
| GPT 5.4 Mini | $0.75 | $4.50 | $0.075 | - |
|
||||
| GPT 5.4 Nano | $0.20 | $1.25 | $0.02 | - |
|
||||
| GPT 5.3 Codex Spark | $1.75 | $14.00 | $0.175 | - |
|
||||
| GPT 5.3 Codex | $1.75 | $14.00 | $0.175 | - |
|
||||
| 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 | $0.05 | $0.40 | $0.005 | - |
|
||||
|
||||
你可能会在使用记录中看到 _Claude Haiku 3.5_。这是一个[低成本模型](/docs/config/#models)，用于生成会话标题。
|
||||
|
||||
:::note
|
||||
信用卡手续费按成本转嫁（每笔交易 4.4% + $0.30）；除此之外我们不会额外收费。
|
||||
:::
|
||||
|
||||
免费模型：
|
||||
|
||||
- DeepSeek V4 Flash Free 目前在 OpenCode 上限时免费提供。团队正在利用这段时间收集反馈并改进模型。
|
||||
- MiMo-V2.5 Free 目前在 OpenCode 上限时免费提供。团队正在利用这段时间收集反馈并改进模型。
|
||||
- North Mini Code Free 目前在 OpenCode 上限时免费提供。团队正在利用这段时间收集反馈并改进模型。
|
||||
- Nemotron 3 Ultra Free 目前在 OpenCode 上限时免费提供。团队正在利用这段时间收集反馈并改进模型。
|
||||
- Big Pickle 是一个隐身模型，目前在 OpenCode 上限时免费提供。团队正在利用这段时间收集反馈并改进模型。
|
||||
|
||||
如果你有任何问题，请<a href={email}>联系我们</a>。
|
||||
|
||||
---
|
||||
|
||||
### 自动充值
|
||||
|
||||
如果你的余额低于 $5，Zen 将自动充值 $20。
|
||||
|
||||
你可以更改自动充值金额，也可以完全禁用自动充值。
|
||||
|
||||
---
|
||||
|
||||
### 月度限额
|
||||
|
||||
你还可以为整个工作区以及团队中的每位成员设置月度使用限额。
|
||||
|
||||
例如，假设你将月度使用限额设置为 $20，那么 Zen 在一个月内的使用金额不会超过 $20。但如果你启用了自动充值，当余额低于 $5 时，Zen 最终向你收取的金额可能会超过 $20。
|
||||
|
||||
---
|
||||
|
||||
### 已弃用模型
|
||||
|
||||
| 模型 | 弃用日期 |
|
||||
| ------------------ | -------------- |
|
||||
| GPT 5.2 Codex | July 23, 2026 |
|
||||
| GPT 5.1 Codex | July 23, 2026 |
|
||||
| GPT 5.1 Codex Max | July 23, 2026 |
|
||||
| GPT 5.1 Codex Mini | July 23, 2026 |
|
||||
| GPT 5 Codex | July 23, 2026 |
|
||||
| Claude Sonnet 4 | June 15, 2026 |
|
||||
| GLM 5 | May 14, 2026 |
|
||||
| MiniMax M2.1 | March 15, 2026 |
|
||||
| GLM 4.7 | March 15, 2026 |
|
||||
| GLM 4.6 | March 15, 2026 |
|
||||
| Gemini 3 Pro | March 9, 2026 |
|
||||
| Kimi K2 Thinking | March 6, 2026 |
|
||||
| Kimi K2 | March 6, 2026 |
|
||||
| Claude Haiku 3.5 | Feb 16, 2026 |
|
||||
| Qwen3 Coder 480B | Feb 6, 2026 |
|
||||
|
||||
---
|
||||
|
||||
## 隐私
|
||||
|
||||
我们所有模型都托管在 US。我们的提供商遵循零保留政策，不会将你的数据用于模型训练，但以下情况除外：
|
||||
|
||||
- Big Pickle：在免费期间，收集的数据可能会被用于改进模型。
|
||||
- DeepSeek V4 Flash Free：在免费期间，收集的数据可能会被用于改进模型。
|
||||
- MiMo-V2.5 Free：在免费期间，收集的数据可能会被用于改进模型。
|
||||
- North Mini Code Free：在免费期间，收集的数据可能会被用于改进模型。
|
||||
- Nemotron 3 Ultra Free（NVIDIA 免费端点）：仅供试用 — 请勿提交个人或机密数据。出于安全目的以及为改进 NVIDIA 产品和服务，系统会记录你的使用情况。出于改进目的而记录的会话数据不会与你的身份或任何持久标识符相关联。有关我们数据处理实践的更多信息，请参阅我们的[隐私政策](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf)。与此端点进行交互，即表示你同意我们收集、记录和使用此类信息，并同意 [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf)。
|
||||
- OpenAI APIs：请求会根据 [OpenAI's Data Policies](https://platform.openai.com/docs/guides/your-data) 保留 30 天。
|
||||
- Anthropic APIs：请求会根据 [Anthropic's Data Policies](https://docs.anthropic.com/en/docs/claude-code/data-usage) 保留 30 天。
|
||||
|
||||
---
|
||||
|
||||
## 团队
|
||||
|
||||
Zen 也非常适合团队使用。你可以邀请队友、分配角色、管理团队使用的模型，等等。
|
||||
|
||||
:::note
|
||||
作为测试版的一部分，工作区目前对团队免费开放。
|
||||
:::
|
||||
|
||||
作为测试版的一部分，团队目前可以免费管理工作区。我们很快会分享更多定价细节。
|
||||
|
||||
---
|
||||
|
||||
### 角色
|
||||
|
||||
你可以邀请队友加入工作区并分配角色：
|
||||
|
||||
- **Admin**：管理模型、成员、API 密钥和账单
|
||||
- **Member**：仅管理自己的 API 密钥
|
||||
|
||||
Admin 还可以为每位成员设置月度支出限额，以便控制成本。
|
||||
|
||||
---
|
||||
|
||||
### 模型访问
|
||||
|
||||
Admin 可以为工作区启用或禁用特定模型。向已禁用模型发出的请求会返回错误。
|
||||
|
||||
这在你想禁用会收集数据的模型时很有用。
|
||||
|
||||
---
|
||||
|
||||
### 自带密钥
|
||||
|
||||
你可以使用自己的 OpenAI 或 Anthropic API 密钥，同时仍然访问 Zen 中的其他模型。
|
||||
|
||||
当你使用自己的密钥时，tokens 由提供商直接计费，而不是由 Zen 计费。
|
||||
|
||||
例如，你的组织可能已经拥有 OpenAI 或 Anthropic 的密钥，并且你想使用它，而不是使用 Zen 提供的密钥。
|
||||
|
||||
---
|
||||
|
||||
## 目标
|
||||
|
||||
我们创建 OpenCode Zen，是为了：
|
||||
|
||||
1. 为编码代理**基准测试**最佳模型和提供商。
|
||||
2. 提供**最高质量**的选项，而不是降低性能或路由到更便宜的提供商。
|
||||
3. 通过按成本销售来传递任何**降价**；因此唯一的加价只是为了覆盖我们的处理费用。
|
||||
4. 保持**无锁定**，允许你将它与任何其他编码代理一起使用。同时也始终允许你在 OpenCode 中使用任何其他提供商。
|
||||
Reference in New Issue
Block a user