Skip to content

Latest commit

 

History

History
536 lines (381 loc) · 13.8 KB

LAB-01-opencode-quickstart.md

File metadata and controls

536 lines (381 loc) · 13.8 KB

LAB-01: OpenCode 快速上手指南

掌握 AI 辅助开发的核心操作

1. 实验概述

学习目标

完成本实验后，你将能够：

  1. 认识 OpenCode 界面和三种内置模式（explore/plan/build）
  2. 使用 /init 命令快速理解任意项目
  3. 用 @ 语法精确引用文件进行分析或修改
  4. 创建和调用自定义 Agent 完成专项任务
  5. 完成「分析 → 计划 → 实现 → 审查」完整工作流

预计时间

30-40 分钟（含所有练习）

前置条件

  • ✅ 已完成 LAB-00（OpenCode 安装）
  • ✅ OpenCode 可以正常启动（在终端输入 opencode 能进入 TUI 界面）
  • ✅ 已配置至少一个可用模型（默认使用 qwen3.5-plus）

重要提示：本实验是 LAB-02 到 LAB-14 的基础，建议在开始任何其他实验前完成。后续所有实验都会默认你已掌握本手册的操作。

2. 认识 OpenCode 界面

2.1 启动 OpenCode

OpenCode 支持两种启动方式：

方式一：交互模式（推荐）

opencode
  • 进入 TUI（终端用户界面）
  • 适合持续开发、多轮对话
  • 支持 Tab 切换模式、/commands 等交互功能

方式二：单次运行

opencode run "你的任务描述"
  • 执行完任务后立即退出
  • 适合脚本调用、快速任务
  • 可在 CI/CD 中使用

本手册所有练习均使用交互模式。现在请运行 opencode 进入 TUI 界面。

2.2 三种内置模式

OpenCode 内置三种工作模式，适用于不同场景：

模式 权限 适用场景 典型用途
explore 只读（不可修改文件） 理解代码、分析架构 阅读陌生项目、分析 bug 原因
plan 只读 + 制定方案 设计方案、技术评审 功能实现方案、重构计划
build 完整权限（读写文件 + 运行命令） 实现功能、修复 bug 添加新功能、优化代码

切换模式的方法：

  • TUI 中：按 Tab 键在三种模式间循环切换
  • Prompt 中：直接在指令中指定，例如「请用 explore 模式分析...」

默认进入的是 build 模式。新手建议先用 explore 模式理解项目，再用 build 模式进行修改。

2.3 模型选择

OpenCode 支持多个模型，可根据任务类型选择：

在 TUI 中切换模型：

# 在 TUI 中输入
/models
# 然后用上下键选择，回车确认

推荐配置：

任务类型 推荐模型 说明
通用任务 qwen3.5-plus 支持 thinking，适合大多数场景
代码优化 qwen3-coder-plus 专为编码任务优化
快速查询 glm-5 或 glm-4.7 响应更快，适合简单问题

本手册默认使用 qwen3.5-plus。如果启动时没有可用模型，请先配置 API Key。

3. 核心操作一：/init 快速理解项目

3.1 什么是 /init

/init 是 OpenCode 的项目初始化命令。

它的作用：

  • 扫描项目文件结构
  • 识别技术栈（语言、框架、依赖）
  • 生成 AGENTS.md 文件（项目上下文文档）
  • 后续所有 Prompt 都会自动读取 AGENTS.md 作为背景

这是开始任何新项目时的第一步！ 运行 /init 后，AI 会「读懂」你的项目。

3.2 使用方法

# 1. 进入你的项目目录
cd your-project

# 2. 启动 OpenCode
opencode

# 3. 在 TUI 中输入
/init

运行后你会看到：

  • 项目结构分析进度条
  • 识别到的技术栈（如 Node.js + Express + PostgreSQL）
  • 生成的 AGENTS.md 文件路径

AGENTS.md 包含什么：

  • 项目概述
  • 目录结构说明
  • 技术栈和依赖
  • 关键文件说明
  • 开发注意事项

3.3 实战练习

现在请跟随以下步骤操作：

# 步骤 1：克隆练习项目（返回上级目录执行）
cd ..
git clone https://github.com/MicrosoftLearning/mslearn-github-copilot-dev.git

# 步骤 2：进入项目目录
cd mslearn-github-copilot-dev

# 步骤 3：启动 OpenCode
opencode

# 步骤 4：在 TUI 中输入
/init

验收检查：

  • AGENTS.md 文件已在项目根目录生成
  • 文件内容包含项目技术栈描述
  • OpenCode 提示初始化完成

提示：用 Read 工具或编辑器打开 AGENTS.md，查看 AI 是如何理解这个项目的。

4. 核心操作二：三种模式实战

4.1 Explore 模式：理解代码

explore 模式是「只读」模式，AI 会分析代码但不做任何修改。

适用场景：

  • 第一次阅读陌生项目
  • 分析 bug 原因
  • 理解某模块的工作流程
  • 评估技术债务

Prompt 示例：

@src/app.py 请用 explore 模式分析这个文件的函数调用链，
说明 request 是如何被处理的，不要修改任何文件。

哪些实验会用到：

  • LAB-02：代码结构分析
  • LAB-08：遗留系统理解
  • LAB-13：架构评估

注意：在 explore 模式下尝试修改文件会被拒绝。

4.2 Plan 模式：制定方案

plan 模式会分析需求并制定实现方案，但不执行修改。

适用场景：

  • 设计新功能实现方案
  • 制定重构计划
  • 技术选型评估
  • Code Review 前的方案设计

Prompt 示例：

请用 plan 模式为以下需求制定实现方案：
「在用户服务中添加邮箱验证功能」

请输出：
1. 需要修改的文件列表
2. 每个文件的修改点
3. 需要添加的新文件
4. 测试方案

哪些实验会用到：

  • LAB-07：技术方案设计
  • LAB-12/13：SDD（软件设计文档）生成

提示：plan 模式输出的方案可以直接作为 commit message 或 PR 描述。

4.3 Build 模式：执行实现

build 模式是最常用的模式，AI 会直接修改文件、运行命令、完成任务。

适用场景：

  • 添加新功能
  • 修复 bug
  • 代码重构
  • 生成测试用例

Prompt 示例：

@src/services/UserService.cs 请在第 45 行添加空引用检查，
如果 user 为 null 则抛出 UserNotFoundException。
修改后请运行测试验证。

哪些实验会用到：

  • LAB-03 到 LAB-14 几乎所有的实现任务

重要：build 模式会真实修改文件，建议在修改前先备份或用 git 跟踪变更。

5. 核心操作三：文件引用（@ 语法）

5.1 基本用法

在 Prompt 中使用 @文件名 可以引用特定文件，让 AI 精确理解你要讨论的内容。

三种引用方式：

# 方式 1：引用单个文件
@src/app.py 请分析这个文件的入口逻辑

# 方式 2：引用目录（会递归包含所有子文件）
@src/components/ 请分析这个目录下所有组件的结构

# 方式 3：同时引用多个文件
@src/app.py @src/config.js 请分析这两个文件的依赖关系

注意：文件路径是相对于当前工作目录的。OpenCode 会提供自动补全。

5.2 为什么要用 @ 引用

对比两种 Prompt 写法：

❌ 不好的 Prompt：

请修复用户服务的 bug

✅ 好的 Prompt：

@Services/UserService.cs 请修复第 45 行的空引用 bug，
当 GetUserById 返回 null 时应该抛出异常而不是继续执行。

使用 @ 引用的好处：

  • AI 能精确理解你要讨论的文件
  • 避免 AI 分析错误的文件
  • 减少 token 消耗（只加载相关文件）
  • 提高回答的准确性和针对性

5.3 在实验中的应用

大量使用 @ 语法的实验：

  • LAB-06：精准定位 bug
  • LAB-09/10/11：专项审查（代码质量、性能、安全）
  • LAB-12/13：基于具体文件的方案设计

技巧：在 explore 模式下用 @目录/ 分析整体结构，在 build 模式下用 @具体文件 精确修改。

6. 核心操作四：自定义 Agent

6.1 什么是自定义 Agent

自定义 Agent 是预设了特定角色和行为的 AI 助手。

特点：

  • 通过创建 .opencode/agent/<name>.md 文件定义
  • 用 @<name> 在 Prompt 中调用
  • 每个 Agent 有特定的职责和输出格式
  • 可以复用团队的最佳实践

例如：创建一个专门做 Code Review 的 Agent，每次调用都会按固定格式输出审查报告。

6.2 创建 Agent

Agent 文件格式：

---
mode: subagent
---

# 角色
你是代码审查专家，负责审查代码质量。

# 审查维度
1. 代码可读性（命名、注释、函数长度）
2. 潜在 bug（空引用、资源泄漏、边界条件）
3. 最佳实践（DRY、SOLID、错误处理）

# 输出格式
请用表格输出审查结果：
| 文件 | 行号 | 问题 | 严重程度 | 建议修复 |
|------|------|------|----------|----------|

# 约束
- 只审查业务逻辑，不审查配置和测试文件
- 严重程度分三级：高/中/低

文件命名规则：

  • 文件名：.opencode/agent/<agent-name>.md
  • 调用名：@<agent-name>（去掉 .md 后缀）
  • 例如：.opencode/agent/code-reviewer.md → 调用时用 @code-reviewer

注意：mode: subagent 表示这是一个子 Agent，会被主 Agent 调用。

6.3 调用 Agent

调用示例：

@code-reviewer 请审查我刚才的修改，关注代码质量
和潜在 bug，输出审查报告。

完整工作流：

  1. 创建 Agent 文件
  2. 重启 OpenCode（或重新加载配置）
  3. 在 Prompt 中用 @agent-name 调用
  4. Agent 按预设角色和格式输出

提示：Agent 文件修改后需要重启 OpenCode 才会生效。

6.4 课程中的自定义 Agent 一览

Agent 名称 定义实验 主要用途
@code-reviewer LAB-09 代码质量审查
@performance-auditor LAB-10 性能问题分析
@security-auditor LAB-11 安全漏洞扫描
@spec-writer LAB-12/13 SDD 文档生成

后续实验会详细说明每个 Agent 的具体用法。本实验只需了解如何创建和调用。

7. 综合练习：完整工作流

7.1 练习目标

用一个完整的小任务串联所有操作： /init → explore → plan → build → 自定义 Agent 审查

7.2 练习步骤

提示：以下步骤只给任务目标，具体 Prompt 请自己编写。

步骤 1：克隆练习项目

cd ..
git clone https://github.com/MicrosoftLearning/mslearn-github-copilot-dev.git
cd mslearn-github-copilot-dev

步骤 2：运行 /init

opencode
# 在 TUI 中输入 /init

步骤 3：用 explore 模式分析项目结构

  • 切换到 explore 模式
  • 编写 Prompt 分析项目的整体结构和技术栈
  • 记录项目的入口文件和核心模块

步骤 4：用 @ 引用核心文件分析一个模块

  • 用 @目录/ 或 @文件 引用你认为重要的模块
  • 分析该模块的功能和依赖关系

步骤 5：用 plan 模式为一个小改动制定方案

  • 切换到 plan 模式
  • 提出一个小改动需求（如：添加日志功能、修改某个函数）
  • 让 AI 输出实现方案

步骤 6：用 build 模式执行改动

  • 切换到 build 模式
  • 根据刚才的方案执行修改
  • 验证修改是否成功

步骤 7：创建 @code-reviewer Agent，审查刚才的改动

  • 创建 .opencode/agent/code-reviewer.md
  • 重启 OpenCode
  • 调用 @code-reviewer 审查你的修改

7.3 验收标准

完成本实验后，请确认：

  • /init 成功生成 AGENTS.md 文件
  • 能说出三种模式的区别和适用场景
  • 能用 @ 语法引用文件（单文件、目录、多文件）
  • 成功创建并调用一个自定义 Agent
  • 完成完整的「分析 → 计划 → 实现 → 审查」工作流

建议：将本实验的练习项目保留，后续 LAB-02 到 LAB-14 可以作为参考对比。

8. 快速参考卡（附录）

常用命令速查

命令 作用
/init 初始化项目，生成 AGENTS.md
/models 切换模型
/help 查看所有可用命令
/clear 清空对话历史
Tab 键 在三种模式间切换

三种模式对比

模式 一句话说明
explore 只读分析，理解代码但不修改
plan 制定方案，输出计划但不执行
build 完整执行，修改文件 + 运行命令

@ 引用语法速查

@file.py          # 引用单个文件
@src/             # 引用整个目录
@a.py @b.py       # 引用多个文件
@agent-name       # 调用自定义 Agent

Agent 文件位置和格式

位置： .opencode/agent/<name>.md

格式：

---
mode: subagent
---

# 角色
你的角色定义...

# 约束
你的行为约束...

# 输出格式
你的输出格式要求...

5 个常用 Prompt 模板

1. 分析项目（用 explore 模式）

请用 explore 模式分析这个项目，说明：
1. 项目的技术栈和架构
2. 入口文件在哪里
3. 核心模块有哪些

2. 添加功能（用 build 模式）

@相关文件 请添加以下功能：
[功能描述]

要求：
1. 遵循现有代码风格
2. 添加必要的错误处理
3. 修改后运行测试验证

3. 修复 bug（用 build 模式）

@相关文件 第 X 行存在 [问题描述] 的 bug，
请修复并确保不影响其他功能。

4. 代码审查（用自定义 Agent）

@code-reviewer 请审查 [文件或 commit]，
关注代码质量、潜在 bug 和最佳实践。

5. 生成文档（用 build 模式）

@相关文件 请为这个模块生成 README 文档，
包括功能说明、使用示例和 API 文档。

建议：将这些模板保存到你的笔记中，后续实验中可以直接复用。

实验完成检查

恭喜你完成 LAB-01！请最后确认：

  • 已理解三种模式的区别和使用场景
  • 能熟练使用 /init 初始化项目
  • 能用 @ 语法精确引用文件
  • 知道如何创建和调用自定义 Agent
  • 完成综合练习中的所有步骤

下一步： 开始 LAB-02（代码结构分析），体验 AI 如何帮你理解复杂项目。