6.1 代码生成与重构

从零创建项目、添加功能、重构代码——OpenCode 的 Agent 能力在这些场景下才能真正发挥价值。

这一节在讲什么？

前面五章我们学了 OpenCode 的原理、安装、配置、交互、模型选择和 MCP 扩展。从这一章开始，我们进入实战——看看 OpenCode 在真实开发场景中怎么用。这一节聚焦三个最常见的编码场景：从零创建项目、添加功能、代码重构。每个场景我们都会给出完整的操作流程和对话示例，帮你建立"遇到这种任务，该怎么跟 OpenCode 说"的直觉。

从零创建项目

用 OpenCode 从零创建项目，推荐的工作流是"Plan → Build → 验证"三步走：

第一步：Plan 模式规划

按 Tab 切换到 Plan 模式，描述你想要的项目：

我想创建一个 REST API 项目，使用 Express + TypeScript + Prisma + PostgreSQL，
需要以下功能：
1. 用户注册和登录（JWT 认证）
2. 文章 CRUD
3. 评论功能
帮我规划一下项目结构和实现方案

AI 会分析你的需求，给出项目结构、技术选型、实现步骤的方案。你审查方案后，可以补充细节或调整方向：

项目结构看起来不错，但我还想加一个：
4. 文章搜索功能（用 Elasticsearch）
另外，认证部分我想用 refresh token，不只是 access token

第二步：Build 模式执行

方案确认后，按 Tab 切回 Build 模式，让 AI 开始创建项目：

方案没问题，开始创建项目吧

AI 会依次执行：

初始化项目（npm init、安装依赖）
创建项目目录结构
编写配置文件（tsconfig.json、.env、prisma/schema.prisma）
编写核心代码（路由、控制器、中间件）
运行类型检查，确认没有错误

第三步：验证

运行一下类型检查和 lint，确保项目没有问题

如果发现问题，让 AI 修复：

类型检查有 2 个错误，帮我修复

添加功能

在已有项目中添加功能，关键是给 AI 足够的上下文——让它知道项目结构、现有代码风格、相关文件的位置。

场景：给 Express API 添加分页功能

给 @src/routes/articles.ts 的 GET /articles 接口添加分页功能，
支持 page 和 limit 参数，默认 page=1, limit=20。
参考 @src/routes/users.ts 里的分页实现方式

这个提示词做了三件事：

明确了要修改的文件（@src/routes/articles.ts）
描述了具体需求（分页，参数，默认值）
提供了参考实现（@src/routes/users.ts）

AI 会：

读取 src/routes/articles.ts，了解当前实现
读取 src/routes/users.ts，了解分页的实现方式
按照相同的风格修改 src/routes/articles.ts
运行类型检查确认没有错误

审查 AI 的修改：

AI 修改完代码后，你应该审查它的修改——不要盲目接受。在对话区你可以看到变更摘要，也可以让 AI 展示详细的 diff：

展示一下你刚才的修改详情

如果修改不符合预期，用 /undo 撤销：

/undo

然后补充信息让 AI 重新修改：

分页逻辑不对，应该用 cursor-based pagination 而不是 offset-based，
因为我们的数据量很大，offset 在后面的页会很慢

代码重构

代码重构是最需要 Plan 模式的场景——因为重构通常涉及多个文件，直接 Build 可能导致大面积修改出错。

场景：提取公共逻辑到工具函数

我发现 @src/services/ 下的多个服务都有重复的错误处理逻辑，
帮我找出这些重复代码，提取到一个公共的错误处理模块中

Plan 模式下的 AI 回答：

我分析了 src/services/ 目录下的文件，发现以下重复的错误处理模式：

1. user.service.ts 第 45-52 行：try-catch 包裹数据库操作，catch 中返回 { error: message }
2. article.service.ts 第 67-74 行：相同的 try-catch 模式
3. comment.service.ts 第 33-40 行：相同的 try-catch 模式

建议的重构方案：
1. 创建 src/utils/asyncHandler.ts，封装 try-catch 逻辑
2. 修改三个 service 文件，使用 asyncHandler 替代重复的 try-catch
3. 运行测试确认重构没有引入错误

是否按此方案执行？

审查方案后，切到 Build 模式执行：

方案没问题，开始重构吧

场景：从 JavaScript 迁移到 TypeScript

这是一个更复杂的重构场景——涉及大量文件的修改：

我想把这个项目从 JavaScript 迁移到 TypeScript。
先帮我规划一下迁移步骤，不要直接修改代码

AI 会给出分步骤的迁移方案：

安装 TypeScript 和类型定义
创建 tsconfig.json
修改构建脚本
逐个文件添加类型（从入口文件开始）
修复类型错误
运行测试确认

你可以逐步执行，每完成一步让 AI 做下一步：

第一步完成了，开始第二步

/undo 和 /redo 的使用

/undo 和 /redo 是代码生成和重构场景中最常用的命令：

/undo：撤销 AI 的最后一次修改

/undo

使用场景：

AI 的修改不符合预期
AI 修改了不该修改的文件
你想调整需求后让 AI 重新修改

/undo 会回退到修改前的状态，并重新显示你之前的消息——你可以修改消息后重新发送。

/redo：重做之前撤销的修改

/redo

使用场景：

你撤销后发现 AI 的修改其实是对的
你撤销后想对比修改前后的差异

多步撤销：OpenCode 支持多步撤销——你可以连续 /undo 多次，回退到更早的状态。

代码生成的最佳实践

1. 描述需求要具体

❌ 差的描述：
"帮我写一个登录功能"

✅ 好的描述：
"给 @src/routes/auth.ts 添加 POST /auth/login 接口，
接收 email 和 password，使用 bcrypt 验证密码，
成功返回 JWT token（有效期 24 小时），失败返回 401"

2. 提供参考实现

"按照 @src/routes/users.ts 的风格实现这个接口"

AI 会模仿参考文件的代码风格、错误处理方式、命名规范，保持项目的一致性。

3. 复杂任务先 Plan

"先不要修改代码，帮我规划一下实现方案"

Plan 模式让你在 AI 动手之前审查方案，避免不必要的 /undo。

4. 审查 AI 的每一次修改

"展示一下你修改了哪些文件，每个文件改了什么"

不要盲目接受 AI 的修改——即使 AI 大部分时候是对的，它也可能引入 bug、安全漏洞或不符合项目规范的代码。

常见误区

误区一：AI 生成的代码不审查直接用

这是最危险的错误。AI 生成的代码可能包含安全漏洞（SQL 注入、XSS）、性能问题（N+1 查询）、逻辑错误（边界条件未处理）。每次 AI 修改代码后，你应该审查 diff——至少看一眼改了什么、为什么改。

误区二：一次让 AI 做太多事

❌ 差的做法：
"帮我重构整个项目，把所有回调改成 async/await，
把所有 var 改成 const/let，把所有 require 改成 import"

这种"大杂烩"式的需求，AI 很容易遗漏或混淆。拆分成多个小任务：

✅ 好的做法：
任务 1："把 @src/routes/ 下的回调改成 async/await"
任务 2："把 @src/services/ 下的 var 改成 const/let"
任务 3："把 @src/ 下的 require 改成 import"

误区三：不给 AI 参考实现

如果你不提供参考实现，AI 会用自己的"默认风格"写代码——这可能跟你的项目风格不一致。用 @ 引用现有文件作为参考，让 AI 模仿项目的代码风格。

误区四：/undo 之后不调整需求直接重试

/undo 后直接重新发送相同的消息，AI 很可能会给出相同的（错误的）修改。你应该分析 AI 为什么修改错了，然后调整需求——补充上下文、明确约束、提供参考实现——再重新发送。

小结

这一节我们实战了三个最常见的编码场景：从零创建项目（Plan → Build → 验证三步走）、添加功能（精准描述需求 + 提供参考实现）、代码重构（Plan 模式审查方案 + 逐步执行）。核心原则是"具体描述需求、提供参考实现、审查 AI 修改、复杂任务先 Plan"。下一节我们看调试与问题排查场景。

6.1 代码生成与重构 ​

这一节在讲什么？ ​

从零创建项目 ​

添加功能 ​

代码重构 ​

/undo 和 /redo 的使用 ​

代码生成的最佳实践 ​

常见误区 ​

小结 ​