欢迎来到 OpenCode 系列 的最后一篇！在前两篇文章中，我们分别深入了 OpenCode 的内部架构和安装部署与插件开发。架构再精巧、配置再完善，如果不会用、用不好，一切都是空谈。本文的目标只有一个——让你成为 OpenCode 的 10 倍效率用户。
你将学到：Agent 模式 vs Chat 模式、Shell/File/LSP 工具最佳实践、自定义 Skills 编写、6 个高频踩坑修复、OpenCode vs Claude Code vs Codex vs Cursor 对比分析。这些内容来自真实的 GitHub Issues 和社区讨论，每一个踩坑都有对应的复现场景和修复方案。
在开始之前，建议你手边有一个已经安装好 OpenCode 的项目。如果你还没有安装，参考本系列第二篇文章。本文所有示例都基于 OpenCode v1.17 版本。不同版本之间的行为差异会在文中注明。
| 系列篇 | 标题 | 内容 |
|---|---|---|
| #1 | 架构源码分析 | Effect-TS、Session、Agent Loop |
| #2 | 部署与插件开发 | 安装、配置、插件系统、MCP |
| #3 (本文) | 实战指南 | 工作流、Skills、踩坑、对比 |
Agent 模式（opencode）自动执行工具，适合复杂编码、重构和多文件修改。Chat 模式（opencode chat）需手动确认，适合概念讨论和代码审查。实战建议：先用 Chat 模式讨论方案，确认方向后切换到 Agent 模式执行。代码审查工作流：git diff main --stat | opencode review。
一个高效的工作流循环是：方案设计（Chat 模式）→ 代码执行（Agent 模式）→ 结果验证（Chat 模式）。举例来说，当你要重构一个模块时，先在 Chat 模式下描述你的重构方案，让 AI 帮你分析影响范围。确认方案可行后切换到 Agent 模式执行实际的重构代码。执行完成后切回 Chat 模式审查 diff 和运行测试。
代码审查是你的第二个核心工作流。通过 git diff main --stat | opencode review 可以自动审查当前分支与 main 分支的差异。OpenCode 会逐文件分析修改，检查潜在 bug、类型错误、安全问题和代码风格违规。审查结果以 Markdown 格式输出，可以直接贴在 PR 描述中。
OpenCode 内置 13 个工具。Shell 工具最强大也最危险，建议设置 bash = "ask"。文件编辑使用搜索-替换模式，精准且可审计。LSP 集成自动检测语法错误和类型问题。搜索工具使用高效索引机制，对大型项目也能毫秒级返回。
Shell 工具的最佳实践是：永远不要给予 allow 权限。至少设置 ask，这样每次 Shell 执行前都会弹窗确认。生产环境建议更严格——只允许白名单命令（npm run *、git *、npx tsc 等），其他全部 deny。特别要禁止 rm -rf、sudo、git push --force 等危险操作。
文件编辑使用搜索-替换（Search-Replace）模式，与 OpenCode 的 diff 视图集成。每次编辑会生成结构化 diff，你可以逐行审查后再确认。这种模式比逐行插入更精确且可审计。LSP 工具通过检测项目中的 tsconfig.json 或 pyproject.toml 自动启用，提供实时的类型检查和语法提示。
| 工具 | 权限建议 | 说明 |
|---|---|---|
| Shell | ask | 最危险，严格控制白名单 |
| File Edit | allow | 搜索-替换模式，安全可控 |
| LSP | allow | 只读操作，无安全风险 |
| Search | allow | 索引搜索，毫秒级返回 |
| Web | ask | HTTP 请求，注意数据泄露 |
Skills 是 预定义指令模板，TOML 格式放在 .opencode/skills/ 目录下。每个 Skill 包含名称、描述和执行指令，支持参数传递。可串联成复合工作流，如「修复 Bug」Skill 涵盖定位 → 修复 → 测试 → 提交四步。还可定义快捷命令简化常用操作。
编写一个好的 Skill 需要关注三个要素：明确的名称和描述（让 AI 知道何时使用）、清晰的步骤分解（每个步骤都有可执行的动作）、合理的参数设计（让用户可以传入关键信息）。例如「添加 API 端点」Skill 可以接受端点路径、方法和描述作为参数，自动生成路由代码、控制器逻辑和测试用例。
Skills 支持参数传递，通过 [[params]] 数组定义参数，每个参数有 name、description、required 和可选的 default。多个 Skills 还可以通过 [[skills]] 数组串联成复合流水线，例如「完整发布流程」Skill 可以按照构建→测试→打包→发布的顺序执行四个子 Skills。
6 个真实高频问题：① Provider 报错 "No provider found"——需手动安装 @ai-sdk/* 包。② Token 超限——设置 max_tokens 和 auto_compaction。③ 权限拒绝——用细粒度 Agent 权限覆盖。④ WSL 跨平台——项目放在 WSL ext4 文件系统。⑤ 插件加载失败——检查 engines 兼容性和 exports 字段。⑥ Session 丢失——用 opencode session list 管理。
Provider 报错是最常见的入门问题。OpenCode 默认只内置了 Anthropic 和 OpenAI 的 Provider，其他 Provider（如 Google、Groq）需要手动安装对应的 @ai-sdk/* 包。例如使用 Google 需要 npm install -g @ai-sdk/google。安装后还需要通过环境变量设置 API Key。
Token 超限在长时间会话中频繁发生。解决方案是设置 auto_compaction = true，当上下文达到 max_tokens 的 80% 时自动压缩历史消息。压缩策略会保留最近的完整消息，对较早的消息进行摘要化处理。如果压缩后仍然超限，compaction_target 参数控制压缩后的目标 Token 数量。
OpenCode：完全开源、30+ Provider、Skills + 插件、MCP 原生支持。最适合需要模型自由、深度定制、终端工作流的团队。Claude Code：对 Claude 模型优化最好。Codex：与 OpenAI 深度绑定。Cursor：IDE 内嵌编码体验最佳。现实建议：多个工具同时使用，各取所长。
选型决策的第一步是明确你的约束条件：如果你使用 Windows 且不想折腾 WSL，Cursor 是最省心的选择（原生 Windows 支持）。如果你的团队深度绑定 Anthropic 生态，Claude Code 提供最佳模型集成。如果你需要模型自由度和 CI/CD 集成，OpenCode 是唯一选择。如果你只需要在 VSCode 中偶尔使用 AI 辅助，Cursor 或 GitHub Copilot 更合适。
实际生产中，很多团队采用"混合策略"：日常编码在 Cursor 中完成（利用其 IDE 集成优势），CI/CD 审查用 OpenCode（自动化脚本），复杂重构用 Claude Code（深度推理能力）。工具本身不冲突，关键是为每个场景选择最合适的工具。
| 工具 | 开源 | Provider | 场景 |
|---|---|---|---|
| OpenCode | ✅ MIT | 30+ | CI/CD、终端工作流 |
| Claude Code | ❌ | 仅 Anthropic | 深度推理 |
| Codex | ❌ | 仅 OpenAI | OpenAI 生态 |
| Cursor | ❌ | 多模型 | IDE 内嵌编码 |
多模型策略：fast（gpt-5-mini 做搜索）+ coding（Claude Sonnet 编码）+ review（Claude Opus 审查）三级路由。对话中 /agent fast 随时切换。性能优化：确保 .gitignore 生效、限制搜索范围、设置步骤限制。团队协作：Skills 和配置纳入 Git 仓库，个人偏好存全局配置。
性能优化的第一原则是减少 Agent 的"盲目搜索"。OpenCode 的搜索工具默认会遍历项目中的所有文件（排除 .gitignore 中的目录）。对于大型项目，通过 search.exclude_patterns 排除 dist/、.next/、coverage/ 等非源码目录可以显著提升搜索速度。设置 search.max_results = 30 限制每次搜索的结果数量，避免 Agent 处理过多无关结果。
团队协作方面，推荐在 Git 仓库中维护 .opencode/skills/ 目录，每个团队成员都能使用相同的 Skills 模板。.opencode/config.toml 中的 Agent 定义和权限模板也纳入版本控制。个人偏好（主题、编辑器设置）放在 ~/.opencode/config.toml 全局配置中。API Key 永远通过环境变量传入，以 .env 文件或 CI secrets 的方式管理。