OpenCode 进阶使用指南（第五章：最佳实践）

本文档是《OpenCode 进阶使用指南》的第五章总结了使用 OpenCode 的最佳实践和技巧预计阅读时间：30-40 分钟

高效提示词编写

5.1.1 提示词的核心原则

提示词（Prompt）是你与 AI 沟通的桥梁。好的提示词能让 AI 准确理解你的意图，给出高质量的结果。

原则一：具体明确

❌ 差的提示词：

复制代码

帮我优化代码

✅ 好的提示词：

diff 复制代码

优化 src/utils/dataProcessor.ts 中的 processData 函数：
- 输入数据量可能达到 10 万条记录
- 当前实现使用双重循环，时间复杂度 O(n²)
- 目标是降到 O(n log n) 或更低
- 保持现有接口不变
- 添加适当的类型定义

原则二：提供上下文

❌ 差的提示词：

css 复制代码

这个报错怎么解决？
[截图]

✅ 好的提示词：

javascript 复制代码

在运行测试时遇到错误：

错误信息：

TypeError: Cannot read property 'map' of undefined at UserList.render (src/components/UserList.tsx:45)

相关代码（src/components/UserList.tsx:40-50）：

const UserList: React.FC = () => {
  const { users } = useUsers();

  return (
    <div>
      {users.map(user => (  // 第 45 行报错
        <UserCard key={user.id} user={user} />
      ))}
    </div>
  );
};

useUsers hook（src/hooks/useUsers.ts）：

export const useUsers = () => {
  const [users, setUsers] = useState<User[]>();

  useEffect(() => {
    fetchUsers().then((data) => setUsers(data));
  }, []);

  return { users };
};

问题：组件渲染时 users 还未加载完成，为 undefined。

请给出修复方案，要求：

1. 处理加载状态
2. 处理错误状态
3. 保持 TypeScript 类型安全

原则三：结构化输出

明确要求 AI 的输出格式：

ini 复制代码

请分析这段代码的性能问题，按以下格式输出：

## 问题列表

1. [问题描述] - [严重程度：高/中/低]
   - 位置：[文件:行号]
   - 影响：[性能/内存/可读性]
   - 建议：[具体优化方案]

## 优化优先级

按影响程度和实现难度排序

## 代码示例

提供优化后的代码片段

原则四：迭代优化

不要期望一次提示就得到完美结果。采用迭代方式：

复制代码

第一轮：基本功能实现
第二轮：添加错误处理
第三轮：优化性能
第四轮：完善文档

5.1.2 提示词模板库

模板一：代码审查请求

markdown 复制代码

请审查以下代码，关注：
1. 代码规范和风格
2. 潜在 bug 和安全问题
3. 性能优化机会
4. 可维护性和可读性

文件：{{file_path}}
代码：{{code}}

请以清单形式列出所有问题，按严重程度排序。对于每个问题，提供：

- 问题描述
- 具体位置
- 修复建议
- 代码示例

模板二：功能开发请求

markdown 复制代码

请实现以下功能：

## 需求描述
{{feature_description}}

## 技术要求
- 技术栈：{{tech_stack}}
- 接口定义：{{api_spec}}
- 数据模型：{{data_model}}

## 验收标准
{{acceptance_criteria}}

## 约束条件
- 不要修改现有接口
- 保持向后兼容
- 添加单元测试

请按以下步骤执行：
1. 分析需求，提出实现方案
2. 等我确认后再开始编码
3. 实现功能
4. 编写测试
5. 生成文档

模板三：Bug 修复请求

markdown 复制代码

请修复以下 Bug：

## Bug 描述

{{bug_description}}

## 复现步骤

1. {{step_1}}
2. {{step_2}}
3. {{step_3}}

## 期望行为

{{expected_behavior}}

## 实际行为

{{actual_behavior}}

## 环境信息

- 浏览器：{{browser}}
- 版本：{{version}}
- 相关代码：{{file_path}}

## 错误日志

{{error_log}}

请：
1. 分析根本原因
2. 提供修复方案（先不执行）
3. 等我确认后执行修复
4. 验证修复结果

5.1.3 上下文管理技巧

引用文件：

bash 复制代码

# 引用单个文件
@src/components/Button.tsx 帮我审查这个组件

# 引用多个文件
@src/utils/helpers.ts @src/types/index.ts 分析类型定义

# 引用特定函数
@formatDate 函数帮我优化性能

# 引用代码行范围
@src/App.tsx:100-150 这段逻辑有问题

保持上下文连贯：

bash 复制代码

# 第一次请求
> 分析 src/api/users.ts 的接口设计

# AI 分析完成...

# 第二次请求（基于之前的分析）
> 基于刚才的分析，帮我重构这些接口
> 要求保持 RESTful 规范

# AI 理解上下文，基于之前的分析进行重构

清理上下文：

当对话太长，上下文混乱时：

bash 复制代码

> /context clear
上下文已清理。之前的对话历史将不再影响后续回答。

> /context summary
当前上下文摘要：
- 正在处理：用户管理系统重构
- 相关文件：src/api/users.ts, src/services/userService.ts
- 上次操作：接口分析

工作流设计

5.2.1 日常开发工作流

标准开发流程：

复制代码

┌─────────────────────────────────────────────────────────┐
│                    开发流程（AI 辅助）                    │
├─────────────────────────────────────────────────────────┤
│  1. 需求理解                                              │
│     ↓ 使用对话模式讨论需求                                 │
│     - 与 AI 讨论业务逻辑                                   │
│     - 确定技术方案                                        │
│     - 识别潜在风险                                        │
│                                                           │
│  2. 技术设计                                              │
│     ↓ 生成设计文档                                        │
│     - 让 AI 帮助设计架构                                   │
│     - 生成接口定义                                        │
│     - 定义数据模型                                        │
│                                                           │
│  3. 编码实现                                              │
│     ↓ 切换 Agent 模式                                     │
│     - 生成代码框架                                        │
│     - 实现业务逻辑                                        │
│     - 编写单元测试                                        │
│                                                           │
│  4. 代码审查                                              │
│     ↓ 使用 Skills                                         │
│     - 自动代码审查                                        │
│     - 人工复核                                            │
│     - 修复问题                                            │
│                                                           │
│  5. 测试验证                                              │
│     ↓ 运行测试套件                                        │
│     - 单元测试                                            │
│     - 集成测试                                            │
│     - AI 辅助调试                                         │
│                                                           │
│  6. 文档更新                                              │
│     ↓ 自动生成文档                                        │
│     - API 文档                                            │
│     - 更新 README                                         │
│     - 添加变更日志                                        │
└─────────────────────────────────────────────────────────┘

详细示例：

bash 复制代码

# ========== 步骤 1: 需求理解 ==========
> 我要实现一个用户注册功能，需求如下：
> 1. 支持邮箱注册
> 2. 需要邮箱验证
> 3. 密码要求：8位以上，包含大小写字母和数字
> 4. 防止机器人注册
>
> 请帮我分析这个需求，包括：
> - 涉及哪些模块
> - 可能的技术方案
> - 需要注意的安全问题

AI：分析完成，建议...

# ========== 步骤 2: 技术设计 ==========
> 基于刚才的分析，帮我设计技术方案：
> 1. 生成 API 接口文档（OpenAPI 格式）
> 2. 设计数据库表结构
> 3. 设计前端表单组件

AI：生成设计文档...

# ========== 步骤 3: 编码实现 ==========
> /agent on
> 请按照设计文档实现用户注册功能：
> 1. 先实现后端 API（Node.js + Express）
> 2. 再实现前端表单（React + TypeScript）
> 3. 最后实现邮箱验证逻辑
>
> 每完成一个模块告诉我，我确认后再继续

AI：[实现后端 API]
用户：确认，继续

AI：[实现前端表单]
用户：确认，继续

AI：[实现邮箱验证]
用户：确认，完成

# ========== 步骤 4: 代码审查 ==========
> /skill use code-review
> 审查刚才实现的用户注册功能

AI：[自动审查报告]

# ========== 步骤 5: 测试验证 ==========
> 运行所有测试，确保通过

AI：✓ 所有测试通过

# ========== 步骤 6: 文档更新 ==========
> 更新相关文档：
> 1. 更新 API 文档
> 2. 更新 README 的使用说明
> 3. 添加变更日志

AI：文档已更新

5.2.2 代码审查工作流

自动化审查流程：

bash 复制代码

# 1. 提交代码前自动审查
pre-commit:
  - id: opencode-review
    name: AI Code Review
    entry: opencode review --skill company-code-review --staged
    language: system
    pass_filenames: false

# 2. PR 创建时自动审查
.on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    steps:
      - uses: opencode-ai/review-action@v1
        with:
          skill: company-code-review
          notify: slack://#code-review

# 3. 人工复核
# 审查报告会作为 PR 评论
# Reviewer 人工确认后合并

审查清单模板：

yaml 复制代码

# .opencode/review-checklist.yaml
checklist:
  code_quality:
    - name: 代码风格
      description: 是否符合团队代码规范
      severity: warning

    - name: 命名规范
      description: 变量、函数、类命名是否清晰
      severity: warning

  functionality:
    - name: 边界处理
      description: 是否处理了边界情况
      severity: error

    - name: 错误处理
      description: 是否有完善的错误处理
      severity: error

  performance:
    - name: 算法复杂度
      description: 时间/空间复杂度是否合理
      severity: warning

    - name: 资源泄漏
      description: 是否有内存/连接泄漏
      severity: error

  security:
    - name: 输入验证
      description: 用户输入是否经过验证
      severity: error

    - name: 敏感信息
      description: 是否泄露了敏感信息
      severity: critical

5.2.3 重构工作流

安全重构流程：

bash 复制代码

# 1. 准备阶段
# 1.1 确保代码已提交
git add .
git commit -m "chore: backup before refactoring"

# 1.2 创建重构分支
git checkout -b refactor/extract-service

# 2. 分析阶段
> 分析 src/modules/order 模块，识别需要重构的代码：
> 1. 找出重复代码
> 2. 找出过长函数
> 3. 找出圈复杂度过高的代码
> 4. 生成重构建议报告

AI：[生成分析报告]

# 3. 规划阶段
> 基于分析报告，制定重构计划：
> 1. 按优先级排序重构项
> 2. 制定每步的验证方案
> 3. 估算工作量

AI：[生成重构计划]

用户：确认计划，开始执行

# 4. 执行阶段（分步进行）
> /agent on
> /agent config mode step_by_step

> 执行重构计划第 1 步：提取重复代码到工具函数

AI：[执行中...]
AI：第 1 步完成，修改了：
- src/modules/order/utils.ts: 新增 3 个工具函数
- src/modules/order/service.ts: 删除重复代码，调用工具函数

用户：查看 git diff，确认无误
用户：运行测试，全部通过
用户：继续下一步

AI：[执行第 2 步...]
...

# 5. 验证阶段
> 运行完整测试套件，确保没有破坏功能

AI：✓ 所有测试通过
✓ 代码覆盖率未下降
✓ 没有新的 ESLint 错误

# 6. 完成阶段
> 生成重构总结报告

git add .
git commit -m "refactor(order): 重构订单模块

- 提取 3 个重复工具函数
- 拆分 2 个过长的处理函数
- 降低平均圈复杂度从 15 到 8
- 所有测试通过

Refactoring guided by OpenCode AI"

git push origin refactor/extract-service

# 7. 创建 PR，请求审查

性能优化

5.3.1 AI 调用优化

减少 Token 消耗：

bash 复制代码

# ❌ 低效：提供整个大文件
> 分析 src/App.tsx 的问题
[AI 读取 500 行代码，消耗大量 token]

# ✅ 高效：只提供相关部分
> 分析 src/App.tsx 第 100-150 行的 useEffect
[AI 只读取 50 行，token 消耗减少 90%]

使用缓存：

bash 复制代码

# 启用上下文缓存
> /context cache enable

# 缓存常用查询结果
> 记住这个项目的架构：MVC + Repository + Service
[AI 缓存架构信息，后续询问时直接使用]

# 后续对话
> 基于我们项目的架构，新功能应该放在哪一层？
[AI 使用缓存的架构信息，无需重复解释]

批量处理：

bash 复制代码

# ❌ 低效：逐个文件处理
> 审查 src/components/Button.tsx
> 审查 src/components/Input.tsx
> 审查 src/components/Modal.tsx

# ✅ 高效：批量处理
> 审查 src/components/*.tsx，生成汇总报告
[AI 一次性处理所有文件，复用上下文]

5.3.2 响应速度优化

模型选择策略：

任务类型	推荐模型	说明
简单问答	Claude Haiku	响应快，成本低
代码生成	Claude Sonnet	平衡速度和质量
复杂分析	Claude Opus	质量最高，较慢
快速审查	GPT-3.5 Turbo	响应极快
深度重构	GPT-4	质量最高

并发执行：

bash 复制代码

# 并行执行独立任务
> 同时执行：
> 1. 生成组件代码
> 2. 生成测试代码
> 3. 生成 Storybook 文档

[AI 并行执行 3 个任务，总时间减少 60%]

预热机制：

bash 复制代码

# 对于企业部署，保持 AI 连接池
# 避免冷启动延迟

opencode serve --keep-alive --min-instances 2

5.3.3 资源使用优化

上下文窗口管理：

json 复制代码

{
  "context": {
    "max_tokens": 4000,
    "compression": true,
    "summary_threshold": 2000,
    "eviction_policy": "lru"
  }
}

文件加载策略：

bash 复制代码

# 只加载必要的文件
> 分析时只加载：
> - src/api/users.ts
> - src/services/userService.ts
> - src/types/user.ts
> 不加载其他无关文件

# 使用文件摘要
> 加载 src/large-file.ts 的摘要（前 50 行 + 函数列表）

安全实践

5.4.1 代码安全

敏感信息保护：

bash 复制代码

# 自动检测敏感信息
> /security scan
扫描中...
⚠️ 发现潜在敏感信息：
  - src/config.ts:15 - 疑似 API Key
  - src/utils/auth.ts:23 - 硬编码密码

建议：
  1. 使用环境变量
  2. 添加到 .gitignore
  3. 轮换已泄露的凭证

安全编码规范：

yaml 复制代码

# .opencode/skills/secure-coding/SKILL.md
security_rules:
  input_validation:
    - rule: '所有用户输入必须验证'
      severity: error

    - rule: '防止 SQL 注入，使用参数化查询'
      severity: error

    - rule: '防止 XSS，转义输出内容'
      severity: error

  authentication:
    - rule: '密码必须哈希存储（bcrypt/Argon2）'
      severity: error

    - rule: '使用 JWT 时设置过期时间'
      severity: warning

  authorization:
    - rule: '所有接口必须验证权限'
      severity: error

    - rule: '实施最小权限原则'
      severity: warning

5.4.2 数据安全

本地数据处理：

bash 复制代码

# 优先使用本地模型处理敏感数据
opencode config ai.provider local
opencode config ai.model codellama-34b

# 敏感数据脱敏后再发送给云端 AI
> /security mask
已启用数据脱敏：
- API Keys: sk-***...***
- 邮箱: ***@***.com
- 手机号: 138****8888

审计日志：

bash 复制代码

# 记录所有 AI 操作
opencode config audit.enabled true
opencode config audit.level verbose

# 查看审计日志
opencode audit log --user zhangsan --since 2026-01-01

5.4.3 权限控制

最小权限原则：

json 复制代码

{
  "permissions": {
    "read": ["src/**", "docs/**"],
    "write": ["src/components/**", "src/utils/**"],
    "deny": ["src/config/secrets/**", ".env*", "**/node_modules/**"]
  }
}

操作确认：

bash 复制代码

# 危险操作需要确认
> /agent config confirm_destructive true

> 删除 src/old-module（危险操作）
⚠️ 即将删除 src/old-module 目录及其所有内容
确认执行吗？(y/N):

团队协作规范

5.5.1 代码规范

提交信息规范：

bash 复制代码

# 使用 Skill 规范提交信息
> /skill use conventional-commit

> 我要提交刚才的用户注册功能
AI：生成提交信息：

git commit -m "feat(auth): 实现用户注册功能

- 添加邮箱注册接口
- 实现邮箱验证流程
- 添加密码强度校验
- 集成 reCAPTCHA 防机器人

Closes #123"

代码风格统一：

yaml 复制代码

# .opencode/config.yaml
code_style:
  formatter: prettier
  linter: eslint
  rules:
    printWidth: 100
    tabWidth: 2
    useTabs: false
    semi: true
    singleQuote: true

5.5.2 知识共享

Skills 共享规范：

bash 复制代码

skills/
├── README.md              # Skills 说明文档
├── CONTRIBUTING.md        # 贡献指南
├── CODE_OF_CONDUCT.md     # 行为准则
└── skills/
    ├── skill-name/
    │   ├── SKILL.md       # 技能定义
    │   ├── CHANGELOG.md   # 变更日志
    │   └── examples/      # 使用示例

文档模板：

markdown 复制代码

# Skill: {{name}}

## 功能描述

{{description}}

## 维护者

- 主维护者：{{primary_maintainer}}
- 备份维护者：{{backup_maintainer}}

## 使用场景

{{usage_scenarios}}

## 版本历史

| 版本  | 日期       | 变更内容 | 作者       |
| ----- | ---------- | -------- | ---------- |
| 1.0.0 | 2026-01-15 | 初始版本 | {{author}} |

## 反馈渠道

- Issue: {{issue_url}}
- 讨论: {{discussion_url}}

5.5.3 培训与推广

新人入职培训：

bash 复制代码

# 第 1 天：基础使用
> 欢迎使用 OpenCode！让我带你快速上手：
> 1. 基础对话功能
> 2. Agent 模式使用
> 3. 常用 Skills 介绍

# 第 3 天：进阶功能
> 今天学习进阶功能：
> 1. 自定义 Skills
> 2. MCP 集成
> 3. 工作流设计

# 第 7 天：实践项目
> 完成一个小项目，实际应用所学

定期分享会：

每周：使用技巧分享
每月：最佳实践案例
每季度：效率提升复盘

常见问题解决方案

5.6.1 AI 理解错误

症状：AI 没有理解需求，给出错误的结果

解决方案：

bash 复制代码

# 1. 补充更多上下文
> 补充说明：
> - 这个函数用于处理用户上传的 Excel 文件
> - 文件可能包含 1-10 万行数据
> - 需要处理中文表头
> - 输出格式是 JSON

# 2. 提供示例
> 输入示例：
> ```csv
> 姓名,年龄,城市
> 张三,25,北京
> 李四,30,上海
> ```
>
> 期望输出：
> ```json
> [{"name": "张三", "age": 25, "city": "北京"}, ...]
> ```

# 3. 分步说明
> 请按以下步骤实现：
> 步骤 1：读取文件
> 步骤 2：解析表头
> 步骤 3：转换数据
> 步骤 4：输出 JSON

5.6.2 代码质量问题

症状：AI 生成的代码有 bug 或不符合规范

解决方案：

bash 复制代码

# 1. 添加约束条件
> 生成代码时请注意：
> - 必须处理所有错误情况
> - 使用 TypeScript 严格模式
> - 添加完整的类型定义
> - 遵循团队 ESLint 规则

# 2. 要求测试
> 生成代码后，同时生成：
> 1. 单元测试（覆盖所有分支）
> 2. 集成测试
> 3. 运行测试并确保通过

# 3. 代码审查
> /skill use code-review
> 审查刚才生成的代码

# 4. 迭代改进
> 基于审查意见，修复以下问题：
> 1. 缺少错误处理
> 2. 变量命名不清晰
> 3. 重复代码需要提取

5.6.3 性能问题

症状：AI 响应慢，或者生成的代码性能差

解决方案：

bash 复制代码

# 优化 AI 响应
> /context clear  # 清理上下文
> /model set haiku  # 切换到更快的模型

# 优化生成代码
> 优化这段代码的性能：
> - 当前时间复杂度 O(n²)
> - 目标是 O(n log n)
> - 数据量：100万条记录
> - 使用空间换时间策略

5.6.4 安全问题

症状：担心代码安全或数据泄露

解决方案：

bash 复制代码

# 1. 启用安全检查
> /security enable

# 2. 扫描代码
> /security scan src/

# 3. 使用本地模型
> /model use local

# 4. 脱敏处理
> /security mask enable

进阶技巧

5.7.1 自定义指令

创建快捷指令：

bash 复制代码

# ~/.opencode/aliases.yaml
aliases:
  review: skill use code-review
  test: agent run "运行所有测试"
  fix: agent run "修复所有 ESLint 错误"
  doc: skill use generate-docs
  commit: skill use conventional-commit

使用：

bash 复制代码

> /review src/components/Button.tsx
> /test
> /fix
> /doc
> /commit

5.7.2 管道操作

链式调用：

bash 复制代码

# 生成代码 → 审查 → 测试
> /agent run "生成用户管理功能" \
  | /skill use code-review \
  | /agent run "修复审查发现的问题" \
  | /agent run "运行测试"

5.7.3 条件执行

智能工作流：

bash 复制代码

> /workflow run deploy
检查条件：
- 代码审查通过？是
- 所有测试通过？是
- 安全检查通过？是

执行部署：
✓ 构建成功
✓ 测试通过
✓ 部署到生产
✓ 健康检查通过

部署完成！

5.7.4 批量操作

多项目处理：

bash 复制代码

# 为所有项目添加相同的配置
> /batch run --projects "proj1,proj2,proj3" \
  "添加 .editorconfig 文件"

# 批量审查
> /batch review --pattern "src/**/*.ts" \
  --output report.md

案例研究

5.8.1 案例：前端团队效率提升

背景：

团队规模：15 人
技术栈：React + TypeScript
痛点：代码审查耗时、重复性工作多

实施过程：

Week 1-2：工具部署
- 部署 OpenCode 企业版
- 配置团队 Skills
- 培训团队成员
Week 3-4：流程优化
- 建立代码审查 Skill
- 配置 CI/CD 集成
- 创建组件生成模板
Week 5-8：全面使用
- 所有成员日常使用
- 收集反馈优化
- 沉淀更多 Skills

效果：

指标	实施前	实施后	提升
代码审查时间	2 小时/PR	30 分钟/PR	75% ↓
组件开发时间	4 小时	1.5 小时	62% ↓
Bug 率	5%	2%	60% ↓
文档覆盖率	40%	85%	112% ↑

5.8.2 案例：遗留系统重构

背景：

10 年老系统，代码债务严重
技术栈：jQuery + PHP
目标：迁移到 React + Node.js

实施策略：

分析阶段（1 个月）
- AI 分析现有代码结构
- 识别核心业务逻辑
- 制定迁移计划
重构阶段（3 个月）
- 使用 Agent 模式批量重构
- 逐步替换旧模块
- 保持功能兼容
验证阶段（1 个月）
- 自动化测试覆盖
- 灰度发布
- 监控和回滚

成果：

代码量减少 40%
性能提升 3 倍
维护成本降低 60%

总结

本章总结了使用 OpenCode 的最佳实践，涵盖：

高效提示词编写 - 如何与 AI 有效沟通
工作流设计 - 标准化的开发流程
性能优化 - 提升响应速度和降低成本
安全实践 - 保护代码和数据安全
团队协作 - 规范化和知识共享
问题排查 - 常见问题的解决方案
进阶技巧 - 提高工作效率的技巧
案例研究 - 真实的应用案例

掌握这些最佳实践，你将能够更高效、更安全、更专业地使用 OpenCode。

记住：

AI 是助手，不是替代品
始终保持批判性思维
重视安全和隐私
持续学习和优化

文档信息

字数：约 6,500 字
适用版本：OpenCode 2.0+

（第五章完）

祝你在 AI 辅助开发的道路上越走越远！