本文档是《OpenCode 进阶使用指南》的第五章总结了使用 OpenCode 的最佳实践和技巧预计阅读时间：30-40 分钟
目录
高效提示词编写
5.1.1 提示词的核心原则
提示词（Prompt）是你与 AI 沟通的桥梁。好的提示词能让 AI 准确理解你的意图，给出高质量的结果。
原则一：具体明确
❌ 差的提示词：
帮我优化代码
✅ 好的提示词：
优化 src/utils/dataProcessor.ts 中的 processData 函数：
- 输入数据量可能达到 10 万条记录
- 当前实现使用双重循环，时间复杂度 O(n²)
- 目标是降到 O(n log n) 或更低
- 保持现有接口不变
- 添加适当的类型定义
原则二：提供上下文
❌ 差的提示词：
这个报错怎么解决？
[截图]
✅ 好的提示词：
在运行测试时遇到错误：
错误信息：
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 的输出格式：
请分析这段代码的性能问题，按以下格式输出：
## 问题列表
1. [问题描述] - [严重程度：高/中/低]
- 位置：[文件:行号]
- 影响：[性能/内存/可读性]
- 建议：[具体优化方案]
## 优化优先级
按影响程度和实现难度排序
## 代码示例
提供优化后的代码片段
原则四：迭代优化
不要期望一次提示就得到完美结果。采用迭代方式：
第一轮：基本功能实现
第二轮：添加错误处理
第三轮：优化性能
第四轮：完善文档
5.1.2 提示词模板库
模板一：代码审查请求
请审查以下代码，关注：
1. 代码规范和风格
2. 潜在 bug 和安全问题
3. 性能优化机会
4. 可维护性和可读性
文件：{{file_path}}
代码：{{code}}
请以清单形式列出所有问题，按严重程度排序。对于每个问题，提供：
- 问题描述
- 具体位置
- 修复建议
- 代码示例
模板二：功能开发请求
请实现以下功能：
## 需求描述
{{feature_description}}
## 技术要求
- 技术栈：{{tech_stack}}
- 接口定义：{{api_spec}}
- 数据模型：{{data_model}}
## 验收标准
{{acceptance_criteria}}
## 约束条件
- 不要修改现有接口
- 保持向后兼容
- 添加单元测试
请按以下步骤执行：
1. 分析需求，提出实现方案
2. 等我确认后再开始编码
3. 实现功能
4. 编写测试
5. 生成文档
模板三：Bug 修复请求
请修复以下 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 上下文管理技巧
引用文件：
# 引用单个文件
@src/components/Button.tsx 帮我审查这个组件
# 引用多个文件
@src/utils/helpers.ts @src/types/index.ts 分析类型定义
# 引用特定函数
@formatDate 函数帮我优化性能
# 引用代码行范围
@src/App.tsx:100-150 这段逻辑有问题
保持上下文连贯：
# 第一次请求
> 分析 src/api/users.ts 的接口设计
# AI 分析完成...
# 第二次请求（基于之前的分析）
> 基于刚才的分析，帮我重构这些接口
> 要求保持 RESTful 规范
# AI 理解上下文，基于之前的分析进行重构
清理上下文：
当对话太长，上下文混乱时：
> /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 │
│ - 添加变更日志 │
└─────────────────────────────────────────────────────────┘
详细示例：
# ========== 步骤 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 代码审查工作流
自动化审查流程：
# 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 人工确认后合并
审查清单模板：
# .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 重构工作流
安全重构流程：
# 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 消耗：
# ❌ 低效：提供整个大文件
> 分析 src/App.tsx 的问题
[AI 读取 500 行代码，消耗大量 token]
# ✅ 高效：只提供相关部分
> 分析 src/App.tsx 第 100-150 行的 useEffect
[AI 只读取 50 行，token 消耗减少 90%]
使用缓存：
# 启用上下文缓存
> /context cache enable
# 缓存常用查询结果
> 记住这个项目的架构：MVC + Repository + Service
[AI 缓存架构信息，后续询问时直接使用]
# 后续对话
> 基于我们项目的架构，新功能应该放在哪一层？
[AI 使用缓存的架构信息，无需重复解释]
批量处理：
# ❌ 低效：逐个文件处理
> 审查 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 | 质量最高 |
并发执行：
# 并行执行独立任务
> 同时执行：
> 1. 生成组件代码
> 2. 生成测试代码
> 3. 生成 Storybook 文档
[AI 并行执行 3 个任务，总时间减少 60%]
预热机制：
# 对于企业部署，保持 AI 连接池
# 避免冷启动延迟
opencode serve --keep-alive --min-instances 2
5.3.3 资源使用优化
上下文窗口管理：
{
"context": {
"max_tokens": 4000,
"compression": true,
"summary_threshold": 2000,
"eviction_policy": "lru"
}
}
文件加载策略：
# 只加载必要的文件
> 分析时只加载：
> - src/api/users.ts
> - src/services/userService.ts
> - src/types/user.ts
> 不加载其他无关文件
# 使用文件摘要
> 加载 src/large-file.ts 的摘要（前 50 行 + 函数列表）
安全实践
5.4.1 代码安全
敏感信息保护：
# 自动检测敏感信息
> /security scan
扫描中...
⚠️ 发现潜在敏感信息：
- src/config.ts:15 - 疑似 API Key
- src/utils/auth.ts:23 - 硬编码密码
建议：
1. 使用环境变量
2. 添加到 .gitignore
3. 轮换已泄露的凭证
安全编码规范：
# .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 数据安全
本地数据处理：
# 优先使用本地模型处理敏感数据
opencode config ai.provider local
opencode config ai.model codellama-34b
# 敏感数据脱敏后再发送给云端 AI
> /security mask
已启用数据脱敏：
- API Keys: sk-***...***
- 邮箱: ***@***.com
- 手机号: 138****8888
审计日志：
# 记录所有 AI 操作
opencode config audit.enabled true
opencode config audit.level verbose
# 查看审计日志
opencode audit log --user zhangsan --since 2026-01-01
5.4.3 权限控制
最小权限原则：
{
"permissions": {
"read": ["src/**", "docs/**"],
"write": ["src/components/**", "src/utils/**"],
"deny": ["src/config/secrets/**", ".env*", "**/node_modules/**"]
}
}
操作确认：
# 危险操作需要确认
> /agent config confirm_destructive true
> 删除 src/old-module（危险操作）
⚠️ 即将删除 src/old-module 目录及其所有内容
确认执行吗？(y/N):
团队协作规范
5.5.1 代码规范
提交信息规范：
# 使用 Skill 规范提交信息
> /skill use conventional-commit
> 我要提交刚才的用户注册功能
AI：生成提交信息：
git commit -m "feat(auth): 实现用户注册功能
- 添加邮箱注册接口
- 实现邮箱验证流程
- 添加密码强度校验
- 集成 reCAPTCHA 防机器人
Closes #123"
代码风格统一：
# .opencode/config.yaml
code_style:
formatter: prettier
linter: eslint
rules:
printWidth: 100
tabWidth: 2
useTabs: false
semi: true
singleQuote: true
5.5.2 知识共享
Skills 共享规范：
skills/
├── README.md # Skills 说明文档
├── CONTRIBUTING.md # 贡献指南
├── CODE_OF_CONDUCT.md # 行为准则
└── skills/
├── skill-name/
│ ├── SKILL.md # 技能定义
│ ├── CHANGELOG.md # 变更日志
│ └── examples/ # 使用示例
文档模板：
# Skill: {{name}}
## 功能描述
{{description}}
## 维护者
- 主维护者：{{primary_maintainer}}
- 备份维护者：{{backup_maintainer}}
## 使用场景
{{usage_scenarios}}
## 版本历史
| 版本 | 日期 | 变更内容 | 作者 |
| ----- | ---------- | -------- | ---------- |
| 1.0.0 | 2026-01-15 | 初始版本 | {{author}} |
## 反馈渠道
- Issue: {{issue_url}}
- 讨论: {{discussion_url}}
5.5.3 培训与推广
新人入职培训：
# 第 1 天：基础使用
> 欢迎使用 OpenCode！让我带你快速上手：
> 1. 基础对话功能
> 2. Agent 模式使用
> 3. 常用 Skills 介绍
# 第 3 天：进阶功能
> 今天学习进阶功能：
> 1. 自定义 Skills
> 2. MCP 集成
> 3. 工作流设计
# 第 7 天：实践项目
> 完成一个小项目，实际应用所学
定期分享会：
- 每周：使用技巧分享
- 每月：最佳实践案例
- 每季度：效率提升复盘
常见问题解决方案
5.6.1 AI 理解错误
症状：AI 没有理解需求，给出错误的结果
解决方案：
# 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 或不符合规范
解决方案：
# 1. 添加约束条件
> 生成代码时请注意：
> - 必须处理所有错误情况
> - 使用 TypeScript 严格模式
> - 添加完整的类型定义
> - 遵循团队 ESLint 规则
# 2. 要求测试
> 生成代码后，同时生成：
> 1. 单元测试（覆盖所有分支）
> 2. 集成测试
> 3. 运行测试并确保通过
# 3. 代码审查
> /skill use code-review
> 审查刚才生成的代码
# 4. 迭代改进
> 基于审查意见，修复以下问题：
> 1. 缺少错误处理
> 2. 变量命名不清晰
> 3. 重复代码需要提取
5.6.3 性能问题
症状：AI 响应慢，或者生成的代码性能差
解决方案：
# 优化 AI 响应
> /context clear # 清理上下文
> /model set haiku # 切换到更快的模型
# 优化生成代码
> 优化这段代码的性能：
> - 当前时间复杂度 O(n²)
> - 目标是 O(n log n)
> - 数据量：100万条记录
> - 使用空间换时间策略
5.6.4 安全问题
症状：担心代码安全或数据泄露
解决方案：
# 1. 启用安全检查
> /security enable
# 2. 扫描代码
> /security scan src/
# 3. 使用本地模型
> /model use local
# 4. 脱敏处理
> /security mask enable
进阶技巧
5.7.1 自定义指令
创建快捷指令：
# ~/.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
使用：
> /review src/components/Button.tsx
> /test
> /fix
> /doc
> /commit
5.7.2 管道操作
链式调用：
# 生成代码 → 审查 → 测试
> /agent run "生成用户管理功能" \
| /skill use code-review \
| /agent run "修复审查发现的问题" \
| /agent run "运行测试"
5.7.3 条件执行
智能工作流：
> /workflow run deploy
检查条件：
- 代码审查通过？是
- 所有测试通过？是
- 安全检查通过？是
执行部署：
✓ 构建成功
✓ 测试通过
✓ 部署到生产
✓ 健康检查通过
部署完成！
5.7.4 批量操作
多项目处理：
# 为所有项目添加相同的配置
> /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 辅助开发的道路上越走越远！
