opencode
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWhen to Use This Skill
何时使用此技能
Load this skill when the user:
- Asks about OpenCode installation, setup, or configuration
- Mentions opencode.ai commands like /init, /connect, /undo
- Needs help with AGENTS.md or custom commands
- Asks about TUI features, mode switching, or tools
- Wants to create agents, skills, or custom commands
- References opencode configuration (opencode.json)
- Is working on a project with .opencode directory
This skill provides specialized knowledge for OpenCode workflows.
当用户出现以下情况时加载此技能:
- 询问OpenCode的安装、设置或配置相关问题
- 提及opencode.ai命令如/init、/connect、/undo
- 需要AGENTS.md或自定义命令相关帮助
- 询问TUI功能、模式切换或工具相关内容
- 想要创建Agent、技能或自定义命令
- 涉及opencode配置文件(opencode.json)
- 正在处理包含.opencode目录的项目
此技能为OpenCode工作流提供专业知识支持。
OpenCode Agent Guide
OpenCode Agent指南
Quick Start
快速开始
Installation
安装
bash
undefinedbash
undefinedRecommended: Install script
推荐方式:安装脚本
curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://opencode.ai/install | bash
Or use npm
或使用npm
npm install -g opencode-ai
npm install -g opencode-ai
Or use Homebrew (macOS/Linux)
或使用Homebrew(macOS/Linux)
brew install anomalyco/tap/opencode
[Source: https://opencode.ai/docs]brew install anomalyco/tap/opencode
[来源: https://opencode.ai/docs]Setup
设置
bash
undefinedbash
undefinedNavigate to your project
进入你的项目目录
cd /path/to/project
cd /path/to/project
Start OpenCode
启动OpenCode
opencode
opencode
Configure your AI provider
配置AI提供商
/connect
/connect
Initialize project (creates AGENTS.md)
初始化项目(创建AGENTS.md)
/init
[Source: https://opencode.ai/docs]
**Essential commands**: /init, /help, /exit, /new, /sessions [Source: https://opencode.ai/docs/tui]
**File references**: `@path/to/file` - fuzzy file search and content injection [Source: https://opencode.ai/docs]
**Bash commands**: `!npm install` - execute shell commands directly [Source: https://opencode.ai/docs]
**Undo/redo**: /undo (Git-based), /redo restore changes [Source: https://opencode.ai/docs/tui]/init
[来源: https://opencode.ai/docs]
**核心命令**:/init、/help、/exit、/new、/sessions [来源: https://opencode.ai/docs/tui]
**文件引用**:`@path/to/file` - 模糊文件搜索与内容注入 [来源: https://opencode.ai/docs]
**Bash命令**:`!npm install` - 直接执行Shell命令 [来源: https://opencode.ai/docs]
**撤销/重做**:/undo(基于Git)、/redo恢复更改 [来源: https://opencode.ai/docs/tui]Core Usage Patterns
核心使用模式
File References
文件引用
@filename # Fuzzy search single file
@src/components/*.tsx # Pattern matching
@path/to/file.ts:42 # Line-specific referenceUse @ for fuzzy file matching. Agent reads file content automatically [Source: https://opencode.ai/docs]
@filename # 模糊搜索单个文件
@src/components/*.tsx # 模式匹配
@path/to/file.ts:42 # 指定行的引用使用@进行模糊文件匹配,Agent会自动读取文件内容 [来源: https://opencode.ai/docs]
Bash Commands
Bash命令
!npm install # Run npm commands
!git status && git diff # Chain commands
!`git log --oneline -5` # Output injection in custom commandsExecute shell commands. Use workdir parameter instead of cd patterns [Source: https://opencode.ai/docs/tools]
!npm install # 运行npm命令
!git status && git diff # 链式命令
!`git log --oneline -5` # 在自定义命令中注入输出执行Shell命令,使用workdir参数替代cd模式 [来源: https://opencode.ai/docs/tools]
Agent Switching
Agent切换
- Tab key: Switch between Build mode (default) and Plan mode [Source: https://opencode.ai/docs/agents]
- @subagent: Invoke subagents (General, Explore) via @mention [Source: https://opencode.ai/docs/agents]
- Ctrl+x: Default leader key for shortcuts [Source: https://opencode.ai/docs/tui]
- Tab键:在Build模式(默认)和Plan模式之间切换 [来源: https://opencode.ai/docs/agents]
- @subagent:通过@提及调用子Agent(General、Explore) [来源: https://opencode.ai/docs/agents]
- Ctrl+x:快捷键的默认引导键 [来源: https://opencode.ai/docs/tui]
TUI Commands
TUI命令
Session: /sessions, /new, /exit, /share, /unshare [Source: https://opencode.ai/docs/tui]
Configuration: /connect, /models, /editor, /themes [Source: https://opencode.ai/docs/tui]
View: /compact, /details, /thinking [Source: https://opencode.ai/docs/tui]
Git: /undo, /redo, /export, /import [Source: https://opencode.ai/docs/tui]
Help: /help, /init (creates AGENTS.md) [Source: https://opencode.ai/docs/tui]
会话:/sessions、/new、/exit、/share、/unshare [来源: https://opencode.ai/docs/tui]
配置:/connect、/models、/editor、/themes [来源: https://opencode.ai/docs/tui]
视图:/compact、/details、/thinking [来源: https://opencode.ai/docs/tui]
Git:/undo、/redo、/export、/import [来源: https://opencode.ai/docs/tui]
帮助:/help、/init(创建AGENTS.md) [来源: https://opencode.ai/docs/tui]
CLI Usage
CLI使用
Default: starts TUI. Non-interactive: [Source: https://opencode.ai/docs/cli]
opencodeopencode run <prompt>Commands: agent, attach, auth, github, mcp, models, run, serve, session, stats, export, import, web [Source: https://opencode.ai/docs/cli]
Global flags: --help, --version, --print-logs, --log-level [Source: https://opencode.ai/docs/cli]
Environment: OPENCODE_AUTO_SHARE, OPENCODE_CONFIG, OPENCODE_DISABLE_CLAUDE_CODE [Source: https://opencode.ai/docs/cli]
命令:agent、attach、auth、github、mcp、models、run、serve、session、stats、export、import、web [来源: https://opencode.ai/docs/cli]
全局标志:--help、--version、--print-logs、--log-level [来源: https://opencode.ai/docs/cli]
环境变量:OPENCODE_AUTO_SHARE、OPENCODE_CONFIG、OPENCODE_DISABLE_CLAUDE_CODE [来源: https://opencode.ai/docs/cli]
Configuration
配置
Files: (project), (global) [Source: https://opencode.ai/docs]
.opencode/opencode.json~/.config/opencode/config.jsonBasic opencode.json structure:
json
{
"agents": {
"default": {
"model": "provider/model",
"temperature": 0.7
}
},
"tools": {
"bash": {
"permissions": "allow"
}
}
}[Source: https://opencode.ai/docs/agents]
Initial setup: /connect command configures connection [Source: https://opencode.ai/docs]
Agent config: tools, permissions, model, temperature [Source: https://opencode.ai/docs/agents]
Claude compatibility: Reads CLAUDE.md when AGENTS.md not present [Source: https://opencode.ai/docs/rules]
For advanced configuration (remote config, plugins, formatters), see CONFIGURATION.md
配置文件:(项目级)、(全局级) [来源: https://opencode.ai/docs]
.opencode/opencode.json~/.config/opencode/config.jsonopencode.json基础结构:
json
{
"agents": {
"default": {
"model": "provider/model",
"temperature": 0.7
}
},
"tools": {
"bash": {
"permissions": "allow"
}
}
}初始设置:/connect命令用于配置连接 [来源: https://opencode.ai/docs]
Agent配置项:tools、permissions、model、temperature [来源: https://opencode.ai/docs/agents]
Claude兼容性:当AGENTS.md不存在时,会读取CLAUDE.md [来源: https://opencode.ai/docs/rules]
高级配置(远程配置、插件、格式化工具)请查看 CONFIGURATION.md
Custom Commands
自定义命令
Location: or [Source: https://opencode.ai/docs/commands]
.opencode/commands/~/.config/opencode/commands/Format: Markdown with YAML frontmatter [Source: https://opencode.ai/docs/commands]
markdown
---
description: Run tests with coverage
agent: Build
template: |
!npm run test -- --coverage && !npm run lint
$ARGUMENTS
---格式:带YAML前置元数据的Markdown文件 [来源: https://opencode.ai/docs/commands]
markdown
---
description: 运行带覆盖率的测试
agent: Build
template: |
!npm run test -- --coverage && !npm run lint
$ARGUMENTS
---Test Runner
测试运行器
Run tests and lint. Arguments passed directly.
**Arguments**: $ARGUMENTS (all), $1, $2, $3 (positional) [Source: https://opencode.ai/docs/commands]
**Shell injection**: `!`command`` - injects output into command template [Source: https://opencode.ai/docs/commands]
**File references**: @filename in commands [Source: https://opencode.ai/docs/commands]
**Config options**: template, description, agent, subtask, model [Source: https://opencode.ai/docs/commands]运行测试与代码检查。参数将直接传递。
**参数**:$ARGUMENTS(所有参数)、$1、$2、$3(位置参数) [来源: https://opencode.ai/docs/commands]
**Shell注入**:`!`command`` - 将输出注入到命令模板中 [来源: https://opencode.ai/docs/commands]
**文件引用**:命令中可使用@filename [来源: https://opencode.ai/docs/commands]
**配置选项**:template、description、agent、subtask、model [来源: https://opencode.ai/docs/commands]Agents
Agent
Modes: Build (default), Plan - switch with Tab key [Source: https://opencode.ai/docs/agents]
Subagents: General, Explore - invoke via @mention [Source: https://opencode.ai/docs/agents]
Configuration: JSON or Markdown files in [Source: https://opencode.ai/docs/agents]
.opencode/agents/Options: description, temperature, max_steps, disable, prompt, model, tools, permissions, mode, hidden, task_permissions, color, top_p [Source: https://opencode.ai/docs/agents]
Creation: [Source: https://opencode.ai/docs/agents]
opencode agent create <name>Switching: Tab key cycles between Build mode and Plan mode; @subagent invokes subagents [Source: https://opencode.ai/docs/agents]
模式:Build(默认)、Plan - 使用Tab键切换 [来源: https://opencode.ai/docs/agents]
子Agent:General、Explore - 通过@提及调用 [来源: https://opencode.ai/docs/agents]
配置文件:目录下的JSON或Markdown文件 [来源: https://opencode.ai/docs/agents]
.opencode/agents/配置选项:description、temperature、max_steps、disable、prompt、model、tools、permissions、mode、hidden、task_permissions、color、top_p [来源: https://opencode.ai/docs/agents]
创建方式: [来源: https://opencode.ai/docs/agents]
opencode agent create <name>切换方式:Tab键在Build模式和Plan模式之间循环切换;@subagent调用子Agent [来源: https://opencode.ai/docs/agents]
Tools
工具
Built-in tools:
- - Execute shell commands
bash - - Edit files in place
edit - - Write new files
write - - Read file contents
read - - Search file contents
grep - - Find files by pattern
glob - - List directory contents
list - - Language Server Protocol (experimental)
lsp - - Apply patches
patch - - Load agent skills
skill - - Task management
todowrite/todoread - - Fetch web content
webfetch - - Interactive prompts [Source: https://opencode.ai/docs/tools]
question
Permissions: allow, deny, ask per tool [Source: https://opencode.ai/docs/tools]
Custom tools: Configure in opencode.json [Source: https://opencode.ai/docs/tools]
MCP servers: External tool integrations [Source: https://opencode.ai/docs/tools]
Ignore patterns: .ignore file in project root [Source: https://opencode.ai/docs/tools]
Best practices: Use workdir param instead of cd patterns. Batch independent tool calls. Prefer grep over bash grep [Source: https://opencode.ai/docs/tools]
内置工具:
- - 执行Shell命令
bash - - 原地编辑文件
edit - - 写入新文件
write - - 读取文件内容
read - - 搜索文件内容
grep - - 按模式查找文件
glob - - 列出目录内容
list - - 语言服务器协议(实验性)
lsp - - 应用补丁
patch - - 加载Agent技能
skill - - 任务管理
todowrite/todoread - - 获取网页内容
webfetch - - 交互式提示 [来源: https://opencode.ai/docs/tools]
question
权限:每个工具可设置allow、deny、ask [来源: https://opencode.ai/docs/tools]
自定义工具:在opencode.json中配置 [来源: https://opencode.ai/docs/tools]
MCP服务器:外部工具集成 [来源: https://opencode.ai/docs/tools]
忽略模式:项目根目录下的.ignore文件 [来源: https://opencode.ai/docs/tools]
最佳实践:使用workdir参数替代cd模式。批量执行独立工具调用。优先使用grep而非bash grep [来源: https://opencode.ai/docs/tools]
Skills System
技能系统
Format: SKILL.md with YAML frontmatter [Source: https://opencode.ai/docs/skills]
Locations: , , , [Source: https://opencode.ai/docs/skills]
.opencode/skills/<name>/~/.config/opencode/skills/<name>/.claude/skills/<name>/~/.claude/skills/<name>/Frontmatter: name (req), description (req), license (opt), compatibility (opt), metadata (opt) [Source: https://opencode.ai/docs/skills]
Name validation: 1-64 chars, lowercase alphanumeric with hyphens, regex: [Source: https://opencode.ai/docs/skills]
^[a-z0-9]+(-[a-z0-9]+)*$Description: 1-1024 characters [Source: https://opencode.ai/docs/skills]
Discovery: Walks up from CWD to git worktree, loads from global configs [Source: https://opencode.ai/docs/skills]
Loading: skill tool loads by name [Source: https://opencode.ai/docs/skills]
Permissions: pattern-based allow/deny/ask [Source: https://opencode.ai/docs/skills]
格式:带YAML前置元数据的SKILL.md文件 [来源: https://opencode.ai/docs/skills]
存储位置:、、、 [来源: https://opencode.ai/docs/skills]
.opencode/skills/<name>/~/.config/opencode/skills/<name>/.claude/skills/<name>/~/.claude/skills/<name>/前置元数据:name(必填)、description(必填)、license(可选)、compatibility(可选)、metadata(可选) [来源: https://opencode.ai/docs/skills]
名称验证:1-64个字符,小写字母数字加连字符,正则: [来源: https://opencode.ai/docs/skills]
^[a-z0-9]+(-[a-z0-9]+)*$描述要求:1-1024个字符 [来源: https://opencode.ai/docs/skills]
发现机制:从当前工作目录向上遍历到Git工作区,同时从全局配置加载 [来源: https://opencode.ai/docs/skills]
加载方式:通过skill工具按名称加载 [来源: https://opencode.ai/docs/skills]
权限:基于模式的allow/deny/ask设置 [来源: https://opencode.ai/docs/skills]
Rules and AGENTS.md
规则与AGENTS.md
AGENTS.md: Project root file created by /init command [Source: https://opencode.ai/docs/rules]
Types: Project (local), Global (~/.config/opencode/AGENTS.md), Claude Code Compatible [Source: https://opencode.ai/docs/rules]
Custom instructions: instructions field in opencode.json [Source: https://opencode.ai/docs/rules]
External refs: Reference external files from AGENTS.md [Source: https://opencode.ai/docs/rules]
Precedence: local AGENTS.md > global AGENTS.md > Claude CLAUDE.md [Source: https://opencode.ai/docs/rules]
AGENTS.md:由/init命令在项目根目录创建的文件 [来源: https://opencode.ai/docs/rules]
类型:项目级(本地)、全局级(~/.config/opencode/AGENTS.md)、Claude Code兼容版 [来源: https://opencode.ai/docs/rules]
自定义指令:opencode.json中的instructions字段 [来源: https://opencode.ai/docs/rules]
外部引用:可在AGENTS.md中引用外部文件 [来源: https://opencode.ai/docs/rules]
优先级:本地AGENTS.md > 全局AGENTS.md > Claude CLAUDE.md [来源: https://opencode.ai/docs/rules]
Common Workflows
常见工作流
Add a New Feature
添加新功能
1. Switch to Plan mode (Tab key)
2. Plan: "Add user authentication to /settings route. Check @src/notes.ts for reference"
3. Review and iterate on the plan
4. Switch to Build mode (Tab key)
5. Build: "Go ahead and implement"
6. Test: !npm test
7. Commit: !git add . && git commit -m "feat: add authentication"1. 切换到Plan模式(Tab键)
2. 规划:"为/settings路由添加用户认证。参考@src/notes.ts"
3. 审阅并迭代规划方案
4. 切换到Build模式(Tab键)
5. 构建:"开始实现"
6. 测试:!npm test
7. 提交:!git add . && git commit -m "feat: add authentication"Debug an Issue
调试问题
1. Identify error location: @src/api/error.ts:42
2. Check related files: @src/components/*
3. Run with debug output: !npm run dev -- --verbose
4. Add breakpoints based on error
5. Test fix: !npm run test -- --watch
6. If issue persists: /undo to revert, refine prompt1. 定位错误位置:@src/api/error.ts:42
2. 检查相关文件:@src/components/*
3. 带调试输出运行:!npm run dev -- --verbose
4. 根据错误添加断点
5. 测试修复:!npm run test -- --watch
6. 若问题仍存在:使用/undo撤销更改,优化提示词Git Workflow
Git工作流
!git status
@path/to/changed/file.ts
!git add . && git commit -m "message"Use /undo to revert changes via Git, /redo to restore [Source: https://opencode.ai/docs/tui]
!git status
@path/to/changed/file.ts
!git add . && git commit -m "message"使用/undo通过Git撤销更改,/redo恢复更改 [来源: https://opencode.ai/docs/tui]
Multi-Mode Task
多模式任务
@plan-agent: Create implementation plan
Tab to Build mode, execute plan@plan-agent: 创建实现规划
按Tab键切换到Build模式,执行规划Custom Command Workflow
自定义命令工作流
Create command in .opencode/commands/
Use @file references for context
Use $ARGUMENTS for user input
Test with /help command在.opencode/commands/目录下创建命令
使用@file引用获取上下文
使用$ARGUMENTS接收用户输入
通过/help命令测试