OpenCode 进阶使用指南（第一章：Agent 模式）

目标读者：有一定 OpenCode 使用经验的开发者

预计阅读时间：60-90 分钟

---

目录

1. 序章：从一个想法说起
2. [第一章：Agent 模式------AI 能自己干活了](#第一章：Agent 模式——AI 能自己干活了 "#%E7%AC%AC%E4%B8%80%E7%AB%A0agent-%E6%A8%A1%E5%BC%8Fai-%E8%83%BD%E8%87%AA%E5%B7%B1%E5%B9%B2%E6%B4%BB%E4%BA%86")
3. 第二章：Skills 系统------把经验变成工具(输出中)
4. 第三章：MCP 集成------AI 能用的工具越来越多了(输出中)
5. 第四章：企业级功能------团队一起用怎么办(输出中)
6. 第五章：最佳实践------怎么才能用得爽(输出中)

---

序章：从一个想法说起

你有没有想过，如果有一个程序员，它不仅能理解你的需求，还能自己动手写代码、改 bug、做测试，甚至能操作浏览器、操作 GitHub、操作数据库......那会是什么体验？

这就是 OpenCode 想要做的事情。它不是一个简单的问答工具，而是一个真正的"AI 程序员"。

OpenCode 是什么

OpenCode 是一个开源的 AI 编程助手，运行在终端里。它能：

• 理解代码：读代码、分析代码、解释代码
• 生成代码：写新功能、改旧代码、重构架构
• 执行操作：运行命令、操作文件、连接外部工具
• 自动化：批量处理、多步骤任务、持续集成

简单来说，它就是一个能听懂你说话的"程序员同事"。

OpenCode 的核心价值

对于个人开发者：

• 提高编码效率 2-5 倍
• 减少重复性劳动
• 快速学习新技术
• 降低 bug 率

对于团队：

• 统一代码规范
• 沉淀团队经验
• 加速新人上手
• 提升代码质量

对于企业：

• 降低开发成本
• 加速项目交付
• 确保代码安全
• 满足合规要求

OpenCode 的架构

要理解 OpenCode 的强大之处，我们先看看它的整体架构：

┌─────────────────────────────────────────┐
│           用户界面层 (CLI/TUI)            │
│    - 命令行交互 / 终端界面 / Web 界面     │
├─────────────────────────────────────────┤
│           AI 引擎层 (LLM)                │
│    - Claude / GPT / Gemini / Ollama      │
├─────────────────────────────────────────┤
│           核心能力层                      │
│    - Agent 系统 / Skills 系统 / MCP 系统  │
├─────────────────────────────────────────┤
│           工具集成层                      │
│    - 文件系统 / Git / 浏览器 / API / DB   │
└─────────────────────────────────────────┘

用户界面层：你输入命令的地方，可以是命令行、终端界面或者 Web。

AI 引擎层：真正"思考"的地方，支持多种大语言模型。

核心能力层：OpenCode 的核心竞争力，包括 Agent、Skills、MCP 三大系统。

工具集成层：连接外部世界的能力，让 AI 能操作真实的环境。

为什么需要进阶学习

基础使用 OpenCode，就像是你刚认识一个新同事，只会让他"帮我看看这段代码"。进阶学习，则是学会如何让这个同事真正参与到你的工作中：

• Agent 模式：让 AI 自主完成复杂任务
• Skills 系统：让 AI 拥有你的团队经验
• MCP 集成：让 AI 能使用各种专业工具
• 企业级功能：让 AI 能安全地服务整个团队

这篇文章，就是带你从"会用"走向"用好"的完整指南。

学习路径建议

初学者路径（1-2 周）

1. 阅读快速入门版

   • 了解 OpenCode 全貌
   • 掌握基础使用方法
   • 时间：2-3 小时

2. 实践 Agent 模式

   • 完成 3-5 个实际任务
   • 熟悉命令和流程
   • 时间：3-5 天

进阶者路径（2-4 周）

1. 深入学习 Skills 系统

   • 阅读第二章完整版
   • 创建 2-3 个自己的 Skill
   • 时间：1 周

2. 掌握 MCP 集成

   • 阅读第三章完整版
   • 配置常用 MCP
   • 尝试开发简单 MCP
   • 时间：1-2 周

专家路径（1-2 个月）

1. 企业级部署

   • 阅读第四章完整版
   • 规划企业级架构
   • 实施部署
   • 时间：2-4 周

2. 精通最佳实践

   • 阅读第五章完整版
   • 优化团队工作流
   • 沉淀团队知识
   • 时间：持续优化

---

第一章：Agent 模式------AI 能自己干活了

1.1 什么是 Agent 模式

1.1.1 传统模式 vs Agent 模式

我们先来对比一下两种使用方式。

传统模式（对话模式）：

你：这段代码有 bug，帮我看看
AI：问题在第 15 行，应该改成 xxx
你：（复制粘贴）改好了吗？
AI：还有第 23 行
你：（复制粘贴）现在呢？
AI：第 37 行也有问题
你：（内心崩溃）...

Agent 模式：

你：把项目里所有 bug 都修好
AI：好的，我来处理
      ↓
AI：（自动读取文件 → 分析问题 → 修改代码 → 验证修复 → 提交结果）
      ↓
AI：已修复 23 处问题，这是修改摘要...

看出区别了吗？

传统模式是"你指挥，AI 建议"。你得一步步告诉 AI 做什么，它才能帮你。

Agent 模式是"你定目标，AI 执行"。你只需要说"把项目里所有 bug 都修好"，AI 会自己规划步骤、执行操作、验证结果。

1.1.2 Agent 模式的核心能力

Agent 模式之所以强大，是因为它具备以下能力：

自主决策能力：

• 分析任务复杂度
• 规划执行步骤
• 选择最佳方案
• 处理异常情况

多步骤执行能力：

• 连续执行多个操作
• 根据中间结果调整策略
• 自动验证每一步的结果
• 失败时自动重试或报告

工具使用能力：

• 读取文件系统
• 执行 shell 命令
• 运行测试
• 操作 Git

上下文感知能力：

• 理解项目结构
• 记住之前的操作
• 保持任务连贯性
• 处理依赖关系

1.1.3 Agent 模式的底层原理

OpenCode 的 Agent 系统是如何工作的？我们来看看它的内部机制：

ReAct 框架（Reasoning + Acting）：

Agent 模式的核心是一个叫做 ReAct 的框架。ReAct = Reasoning（推理）+ Acting（行动）。

工作流程是这样的：

1. 思考（Thought）：AI 分析问题，决定下一步做什么
2. 行动（Action）：AI 执行具体的操作（读文件、改代码、运行命令）
3. 观察（Observation）：AI 观察执行结果
4. 循环：根据观察结果，再次思考、行动、观察

这个过程会不断循环，直到任务完成。

工具调用机制：

OpenCode 给 AI 提供了一系列"工具"，每个工具都有：

• 名字（name）
• 描述（description）
• 参数（parameters）
• 返回值（return value）

比如"读文件"工具：

{
  "name": "read_file",
  "description": "读取指定文件的内容",
  "parameters": {
    "path": {
      "type": "string",
      "description": "文件路径"
    }
  }
}

AI 想读文件时，会生成这样的调用：

{
  "tool": "read_file",
  "params": {
    "path": "src/utils.ts"
  }
}

OpenCode 收到调用后，执行实际的操作，把结果返回给 AI。

上下文管理：

Agent 模式需要管理大量的上下文信息：

• 任务目标
• 执行历史
• 当前状态
• 中间结果
• 错误信息

OpenCode 通过精心设计的提示词（Prompt）和上下文压缩技术，确保 AI 能在有限的上下文窗口内高效工作。

1.2 如何开启 Agent 模式

1.2.1 tab 切换

最简单的方式是在启动 OpenCode

opencode

当前是 plan 模式，只能对话

按 tab 切换 build 模式

1.3 Agent 模式的实际应用场景

1.3.1 场景一：批量重构代码

背景 ：你接手了一个老项目，里面到处都是 var，你想全部改成 let 或 const。

传统做法：

1. 用 IDE 的全局搜索替换
2. 手动检查每个替换是否正确
3. 发现有的地方不该改，手动恢复
4. 测试有没有引入新 bug

耗时：2-4 小时

Agent 模式做法：

> 帮我把项目中所有 var 改成 let 或 const。要求：
> 1. 只改 src 目录下的 .ts 和 .js 文件
> 2. 对于可能被重新赋值的变量用 let，其他的用 const
> 3. 改完后运行测试，确保没有引入新 bug
> 4. 生成一个修改报告，告诉我改了哪些文件

AI 的执行过程：

1. 扫描 src 目录，找到所有 .ts 和 .js 文件
2. 逐个文件分析，识别所有 var 声明
3. 分析每个变量的使用情况，判断用 let 还是 const
4. 执行替换
5. 运行测试套件
6. 如果有失败，回滚并报告
7. 生成修改报告

耗时：5-10 分钟（你喝茶的时间）

修改报告示例：

✅ 批量重构完成

📊 统计信息：
- 扫描文件：127 个
- 修改文件：34 个
- 替换 var：156 处
  - 改为 let：89 处
  - 改为 const：67 处

🧪 测试结果：
- 测试通过：156 项
- 测试失败：0 项

📁 修改的文件（部分）：
- src/utils/helper.ts: 12 处
- src/components/Button.tsx: 8 处
- src/pages/Home/index.tsx: 15 处
...

💡 建议：
已自动提交到 git 分支 "refactor/var-to-let-const"
建议人工复查后合并到主分支

1.3.2 场景二：自动生成测试用例

背景 ：你写了一个核心函数 calculateTotal，需要补测试用例。

传统做法：

1. 理解函数逻辑
2. 想各种边界情况
3. 手写测试代码
4. 运行测试，发现漏了某些情况
5. 补充测试

耗时：30-60 分钟

Agent 模式做法：

> 为 src/utils/calculateTotal.ts 中的 calculateTotal 函数生成完整的 Jest 测试用例。
> 要求：
> 1. 覆盖正常输入、边界情况、异常输入
> 2. 测试用例要有清晰的描述
> 3. 使用 describe 和 it 组织测试结构
> 4. 运行测试确保能通过

AI 的执行过程：

1. 读取 calculateTotal.ts，理解函数逻辑
2. 分析函数参数和返回值
3. 设计测试用例：
   • 正常情况：常规输入
   • 边界情况：空数组、极大值、负数
   • 异常情况：非数字输入、null、undefined
4. 生成测试文件 calculateTotal.test.ts
5. 运行测试，确保通过

生成的测试代码示例：

import { calculateTotal } from './calculateTotal';

describe('calculateTotal', () => {
  describe('正常输入', () => {
    it('应该正确计算一组正数的总和', () => {
      expect(calculateTotal([1, 2, 3])).toBe(6);
      expect(calculateTotal([10, 20, 30])).toBe(60);
    });

    it('应该正确处理小数', () => {
      expect(calculateTotal([0.1, 0.2])).toBeCloseTo(0.3);
    });
  });

  describe('边界情况', () => {
    it('空数组应该返回 0', () => {
      expect(calculateTotal([])).toBe(0);
    });

    it('单元素数组应该返回该元素', () => {
      expect(calculateTotal([42])).toBe(42);
    });

    it('应该正确处理负数', () => {
      expect(calculateTotal([-1, -2, 3])).toBe(0);
    });

    it('应该正确处理极大值', () => {
      expect(calculateTotal([Number.MAX_SAFE_INTEGER])).toBe(
        Number.MAX_SAFE_INTEGER,
      );
    });
  });

  describe('异常输入', () => {
    it('传入非数组应该抛出错误', () => {
      expect(() => calculateTotal('not an array')).toThrow(
        'Input must be an array',
      );
    });

    it('数组中包含非数字应该抛出错误', () => {
      expect(() => calculateTotal([1, 'two', 3])).toThrow(
        'All elements must be numbers',
      );
    });

    it('传入 null 应该抛出错误', () => {
      expect(() => calculateTotal(null)).toThrow('Input cannot be null');
    });
  });
});

耗时：2-3 分钟

1.3.3 场景三：自动化 Bug 修复

背景：项目里 ESLint 报了一堆错误，有些是代码风格问题，有些是潜在 bug。

传统做法：

1. 运行 ESLint，看到一堆错误
2. 逐个文件手动修复
3. 有些问题不知道怎么修，查文档
4. 修了 2 小时后，发现还有 100 多个错误

耗时：数小时，且很痛苦

Agent 模式做法：

> 修复项目中所有 ESLint 错误。要求：
> 1. 优先修复潜在 bug（如 unused-vars, no-undef）
> 2. 代码风格问题（如 indentation, quotes）自动修复
> 3. 对于无法自动修复的，列出文件和行号，并说明原因
> 4. 修复后运行测试，确保没有破坏功能
> 5. 生成修复报告

AI 的执行过程：

1. 运行 ESLint，获取所有错误列表
2. 分类错误：
   • 潜在 bug（高优先级）
   • 代码风格（中优先级）
   • 其他（低优先级）
3. 逐个文件修复：
   • 对于简单问题（如缺少分号），直接修改
   • 对于复杂问题（如逻辑错误），生成修复建议
4. 运行测试套件
5. 生成详细报告

修复报告示例：

🔧 ESLint 自动修复完成

📊 统计信息：
- 总错误数：234
- 已修复：198
- 需人工确认：36

✅ 已修复的问题：
- unused-vars: 45 处
- no-trailing-spaces: 67 处
- quotes: 34 处
- semi: 52 处

⚠️ 需人工确认的问题：
1. src/core/payment.ts:23
   问题：no-undef 'processPayment'
   说明：使用了未定义的变量，可能拼写错误或缺少导入

2. src/utils/encryption.ts:45
   问题：security/detect-object-injection
   说明：动态对象属性访问，可能存在安全风险

🧪 测试结果：
- 测试通过：156 项
- 测试失败：0 项

💾 已保存到分支：fix/eslint-issues-20260115

耗时：5-10 分钟

1.3.4 场景四：多步骤复杂任务

背景：你需要实现一个新功能：用户上传头像，系统自动压缩、生成缩略图、保存到云存储、更新数据库。

传统做法：

1. 写图片处理代码
2. 集成云存储 SDK
3. 更新数据库逻辑
4. 写测试
5. 联调测试
6. 发现各种问题，反复修改

耗时：1-2 天

Agent 模式做法：

> 帮我实现用户头像上传功能。需求：
> 1. 前端：支持拖拽上传，显示预览，限制 5MB
> 2. 后端：接收文件，验证格式（jpg/png），压缩到 500KB 以下
> 3. 生成缩略图（100x100）
> 4. 上传到 AWS S3
> 5. 更新数据库 users 表的 avatar_url 字段
> 6. 返回图片 URL
> 7. 写完整的单元测试
>
> 技术栈：React + Node.js + TypeScript + AWS SDK + Jest

AI 的执行过程：

1. 分析需求，规划实现步骤
2. 创建前端组件：AvatarUploader.tsx
3. 创建后端接口：uploadAvatar.ts
4. 实现图片处理逻辑
5. 集成 AWS S3
6. 更新数据库操作
7. 生成单元测试
8. 创建接口文档

生成的主要文件：

├── src/
│   ├── components/
│   │   └── AvatarUploader/
│   │       ├── index.tsx          # 上传组件
│   │       ├── styles.module.css  # 样式
│   │       └── index.test.tsx     # 组件测试
│   ├── api/
│   │   └── uploadAvatar.ts        # 上传接口
│   ├── utils/
│   │   ├── imageProcessor.ts      # 图片处理
│   │   └── s3Client.ts           # S3 客户端
│   └── database/
│       └── userRepository.ts      # 用户数据操作
├── tests/
│   └── uploadAvatar.test.ts       # 接口测试
└── docs/
    └── avatar-upload-api.md       # API 文档

耗时：15-30 分钟（AI 生成代码，你审查代码）

1.4 Agent 模式的高级配置

1.4.1 执行策略配置

你可以配置 Agent 的执行策略：

{
  "agent": {
    "execution": {
      "mode": "step_by_step",
      "max_steps": 50,
      "auto_confirm": false,
      "rollback_on_error": true
    }
  }
}

mode：执行模式

• step_by_step：每步都询问确认
• batch：批量执行，完成后汇报
• auto：全自动，只在关键点询问

max_steps：最大执行步数，防止无限循环

auto_confirm：是否自动确认低风险操作

rollback_on_error：出错时是否自动回滚

1.4.2 工具权限控制

控制 Agent 可以使用哪些工具：

{
  "agent": {
    "tools": {
      "read_file": "allow",
      "write_file": "ask",
      "execute_shell": "deny",
      "git_commit": "ask"
    }
  }
}

权限级别：

• allow：直接允许
• ask：每次询问
• deny：禁止使用

1.4.3 上下文管理

配置上下文窗口的使用策略：

{
  "agent": {
    "context": {
      "max_files": 20,
      "max_lines_per_file": 100,
      "compression": true,
      "preserve_history": true
    }
  }
}

max_files：同时加载的最大文件数

max_lines_per_file：每个文件加载的最大行数

compression：是否压缩上下文

preserve_history：是否保留完整执行历史

1.5 Agent 模式的最佳实践

1.5.1 任务拆解原则

大任务拆小任务：

❌ 不好：

> 帮我把这个老项目全部重构了

✅ 好：

> 第一步：把项目中所有 var 改成 let/const
> 第二步：给所有函数加上类型定义
> 第三步：把类组件改成函数组件

每个任务要有明确的目标和验收标准：

> 给 src/utils 目录下所有工具函数添加 JSDoc 注释。
> 验收标准：
> 1. 每个函数都要有 @param 和 @returns
> 2. 复杂逻辑要有 @example
> 3. 运行 npm run docs:check 不报错

1.5.2 风险控制策略

原则一：备份先行

让 AI 大改之前，确保代码已提交：

git add .
git commit -m "backup before AI refactoring"

或者创建新分支：

git checkout -b ai-refactor-branch

原则二：逐步确认

对于重要操作，使用 step_by_step 模式：

> /agent config mode step_by_step
> 帮我把数据库操作封装成 Repository 模式

这样 AI 每做一步都会问你确认。

原则三：review 机制

养成看 git diff 的习惯：

git diff --stat
git diff src/utils/helper.ts

原则四：测试驱动

让 AI 改完代码后必须跑测试：

> 修改代码并确保所有测试通过
> 如果测试失败，回滚修改并报告问题

1.5.3 常见问题与解决方案

问题一：AI 执行太慢

原因：

• 任务太大，需要很多步骤
• 网络延迟，API 调用慢
• 上下文太长，处理慢

解决：

• 拆分任务，减少步骤数
• 使用本地模型（如 Ollama）
• 精简上下文，只加载必要文件

问题二：AI 理解错需求

原因：

• 需求描述不清楚
• 缺少上下文
• 歧义性语言

解决：

• 写更详细的需求文档
• 提供示例代码
• 使用更精确的术语

问题三：AI 改了不该改的代码

原因：

• 范围限制不明确
• 模式匹配太宽泛
• 缺少约束条件

解决：

• 明确指定修改范围（文件、目录、函数）
• 使用白名单/黑名单
• 设置保护目录（如 node_modules, .git）

问题四：AI 陷入死循环

原因：

• 任务目标不清晰
• 依赖关系复杂
• 错误处理不当

解决：

• 设置 max_steps 限制
• 使用 /stop 强制停止
• 简化任务目标

1.6 Agent 模式的底层实现细节

1.6.1 提示词工程（Prompt Engineering）

OpenCode 的 Agent 系统使用精心设计的提示词来引导 AI：

系统提示词（System Prompt）：

你是一个专业的软件开发助手。你可以使用以下工具：

1. read_file(path): 读取文件内容
2. write_file(path, content): 写入文件
3. execute_shell(command): 执行 shell 命令
4. run_test(pattern): 运行测试
5. git_operation(action, ...): Git 操作

工作流程：
1. 理解用户需求
2. 制定执行计划
3. 逐步执行
4. 验证结果
5. 报告完成情况

约束：
- 每次只执行一个操作
- 等待操作结果后再继续
- 遇到错误立即报告
- 不确定时询问用户

任务提示词（Task Prompt）：

任务：批量修改代码
目标：把项目中所有 var 改成 let/const
范围：src/目录下的.ts文件
约束：
- 不改 node_modules
- 不改配置文件
- 保持原有功能

请按以下步骤执行：
1. 扫描 src/目录，列出所有.ts文件
2. 逐个文件分析 var 的使用情况
3. 生成修改方案
4. 执行修改
5. 运行测试验证

1.6.2 工具调用协议

OpenCode 使用 JSON-RPC 风格的协议进行工具调用：

请求格式：

{
  "id": "req-001",
  "method": "read_file",
  "params": {
    "path": "src/utils.ts",
    "offset": 1,
    "limit": 50
  }
}

响应格式：

{
  "id": "req-001",
  "result": {
    "content": "export function add(a: number, b: number) {\n  return a + b;\n}",
    "lines": 3,
    "path": "src/utils.ts"
  },
  "error": null
}

错误响应：

{
  "id": "req-001",
  "result": null,
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "文件不存在: src/utils.ts"
  }
}

1.6.3 状态机模型

Agent 的执行过程可以用状态机来描述：

[Start]
  ↓
[Analyzing] ← 分析任务
  ↓
[Planning] ← 制定计划
  ↓
[Executing] ← 执行操作
  ↓
[Observing] ← 观察结果
  ↓
  ├─ 成功 → [Executing] (继续下一步)
  ├─ 失败 → [ErrorHandling] → [Executing] (重试) 或 [Reporting] (放弃)
  └─ 完成 → [Reporting]
              ↓
           [End]

每个状态都有明确的进入条件和退出动作。

1.6.4 记忆机制

Agent 需要记住之前的信息：

短期记忆：当前会话的上下文

{
  "session_id": "sess-abc123",
  "current_task": "refactor codebase",
  "steps_completed": 5,
  "steps_total": 12,
  "modified_files": ["src/utils/helper.ts", "src/components/Button.tsx"],
  "errors": []
}

长期记忆：跨会话的学习

{
  "user_preferences": {
    "code_style": "standard",
    "test_framework": "jest",
    "max_line_length": 100
  },
  "common_patterns": {
    "api_endpoint_structure": "...",
    "error_handling_pattern": "..."
  }
}

1.7 小结

Agent 模式是 OpenCode 最强大的功能之一。它让 AI 从"建议者"变成了"执行者"，真正参与到开发工作中。

核心要点：

1. Agent 模式 = AI 自主执行多步骤任务
2. 开启方式：tab 切换致 build 模式
3. 适合场景：批量操作、复杂任务、重复性劳动
4. 风险控制：备份、逐步确认、review、测试
5. 底层原理：ReAct 框架 + 工具调用 + 上下文管理

下一步学习：掌握 Agent 模式后，建议学习 Skills 系统，把常用的 Agent 任务封装成可复用的技能。

---