Opencode 智能体 (Agent) 与 AGENTS.md 实战教程
📚 分类: OpenCode 核心概念 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 Opencode 编辑器
你将学到什么
完成本教程后，你将能够：
- [ ] 理解 Opencode 中“智能体 (Agent)”的核心作用
- [ ] 掌握
AGENTS.md文件的创建与使用方法，让 AI 记住你的项目规范 - [ ] 了解 “Big Pickle” 是什么以及它的应用场景
- [ ] 学会配置 MCP 协议，让 AI 连接 GitHub、数据库等外部工具
最终效果
你将理解 Opencode 的核心运作机制：它不是一个简单的代码补全工具，而是一个由“智能体”驱动的开发环境。通过配置 AGENTS.md 和 MCP，你将能让 AI 助手自动理解你的项目架构、编码风格，并能直接操作外部服务，从而大幅提升开发效率。
前置准备
在开始前，请确认你的环境满足以下条件：
| 检查项 | 要求 | 验证方法 |
|---|---|---|
| Opencode | 已安装最新版 | 在终端运行 opencode --version |
| 一个项目 | 任意代码项目 | 准备一个你熟悉的项目文件夹 |
1. 打开你的项目
📝 操作：
# 进入你的项目目录
$ cd /path/to/your-project
# 使用 Opencode 打开项目
$ opencode .✅ 验证：Opencode 编辑器窗口应该成功打开，并显示你的项目文件列表。
第 1 步：认识智能体 (Agent) 并创建 AGENTS.md
🎯 目标：创建一个 AGENTS.md 文件，这是让 AI 智能体记住你项目“规矩”的关键。
在 Opencode 中，Agent (智能体) 是一个能感知上下文、规划任务并执行操作的 AI 单元。当你向它提问时，它首先会读取项目根目录下的 AGENTS.md 文件，以此了解项目的“规则”。
📝 操作：
在 Opencode 的终端中，运行以下命令：
bash$ touch AGENTS.md // 创建一个空白的 AGENTS.md 文件使用 Opencode 打开并编辑
AGENTS.md文件。写入以下内容作为示例，你可以根据你的项目修改。markdown# 项目规范 ## 技术栈 - 前端：Vue 3 + Vite - 后端：Node.js + Express - 数据库：PostgreSQL ## 编码风格 - 使用 ES6 模块语法 (import/export) - 前端组件使用 Vue 3 组合式 API (Composition API) - 所有 API 路由使用 `/api/v1/` 前缀 ## 常用指令 - 本地开发：`npm run dev` - 运行测试：`npm run test` - 构建项目：`npm run build`
🤔 为什么要这样做？
AGENTS.md 相当于给 AI 智能体的一份“员工手册”。没有它，每次提问你都需要重复“请使用 Vue 3 的组合式 API”。有了它，AI 会自动读取并遵守这些规则，大大减少沟通成本。
✅ 验证：
- 保存
AGENTS.md文件。 - 在 Opencode 的聊天框中，询问 AI：“请介绍一下这个项目的前端框架是什么？”
💡 预期结果：AI 会回答：“根据项目规范，前端使用的是 Vue 3 + Vite。” 这说明它已经成功读取了 AGENTS.md 中的内容。
第 2 步：了解 Big Pickle 模型
🎯 目标：理解什么是 “Big Pickle” 以及它和普通模型的区别。
在 Opencode 社区，你可能会听到 “Big Pickle” 这个词。它不是一个产品名称，而是一个社区俗称，通常指代 Opencode 内部经过特别调优、能够处理极其复杂任务的大型 AI 模型。
📝 操作：
- 打开 Opencode 的设置界面。
- 找到 “模型 (Model)” 或 “AI Provider” 设置区域。
- 查看可用的模型列表。通常，名称中带有
large、max或类似标识的模型，就可以被理解为 “Big Pickle” 类型的模型。
🤔 为什么要这样做？
可以把 “Big Pickle” 想象成一个“超级智能体”。普通的 Agent 能处理“帮我写一个函数”这样的任务，而 “Big Pickle” 擅长处理：
- 理解整个代码库的架构。
- 执行跨多个文件的复杂重构。
- 同时管理文件操作、终端命令和代码生成。
⚠️ 注意：具体的模型名称会随 Opencode 版本更新而变化。请以官方文档的最新 “Model List” 为准。
✅ 验证：了解即可，无需额外操作。你只需要知道，当你的任务非常复杂时，可以切换到更强的模型来获得更好的效果。
第 3 步：配置 MCP 协议连接外部工具
🎯 目标：让 AI 智能体能够通过 MCP 协议连接 GitHub、数据库等外部服务。
MCP (Model Context Protocol) 是一个开放标准，让 AI 模型能够以统一的方式连接各种外部数据源和工具。Opencode 全面支持此协议。
📝 操作：
在 Opencode 中，找到配置文件。通常是项目根目录下的
.opencode/config.json或通过设置界面访问。在配置文件中，找到
mcpServers字段（如果不存在，手动添加）。添加一个 MCP 服务器配置。以下是一个连接 GitHub 的示例：
jsonc// .opencode/config.json { "mcpServers": { "github": { // MCP 服务器的启动命令 "command": "npx", // 启动参数 "args": [ "-y", "@modelcontextprotocol/server-github" ], // 环境变量，用于认证 "env": { "GITHUB_TOKEN": "<你的 GitHub 个人访问令牌>" } } } }💡 提示：你需要先获取一个 GitHub Personal Access Token，并授予
repo和issues等权限。保存配置文件并重启 Opencode。
✅ 验证：
在 Opencode 的聊天框中输入：“列出我 GitHub 账号下最新的 3 个 Issue”。
💡 预期结果：AI 会调用你配置的 GitHub MCP 服务器，查询并返回结果。这证明 AI 已经成功连接到了 GitHub。
⚠️ 常见错误：
- 连接失败：检查
GITHUB_TOKEN是否正确，以及网络是否通畅。 - 找不到命令：确保
npx命令在你的系统 PATH 中可用。如果不行，尝试全局安装npm install -g @modelcontextprotocol/server-github。
进阶技巧（可选）
- 连接数据库：你可以配置 MCP 连接到 PostgreSQL 或 MySQL，让 AI 直接查询数据库结构并生成 ORM 代码。
- 连接 Slack：配置 Slack MCP，让 AI 总结团队讨论，并直接转化为代码需求。
常见问题 (FAQ)
Q1: 我运行 /init 后没有生成 AGENTS.md 文件，怎么办？A: 手动创建一个即可。AGENTS.md 只是一个约定俗成的文件名，Opencode 会自动识别。你也可以在配置文件中指定其他文件名。
Q2: “Big Pickle” 是官方术语吗？A: 不是。它是社区对 Opencode 内部最强模型的昵称。官方文档中通常不会直接使用这个词，而是会列出具体的模型名称，如 gpt-4-turbo 或 claude-3-opus。
Q3: 如何找到更多可用的 MCP 服务器？A: 可以在 npm 上搜索 @modelcontextprotocol/server-* 或查看 Opencode 的官方文档和社区论坛。
总结
恭喜你完成了本教程！🎉
回顾一下我们今天学到的核心内容：
- 智能体 (Agent)：Opencode 的核心，它能理解上下文并执行任务。
AGENTS.md：项目的“员工手册”，让 AI 记住你的项目规范，无需重复指令。- Big Pickle：社区对高性能 AI 模型的昵称，用于处理复杂任务。
- MCP 协议：连接外部世界的桥梁，让 AI 能够操作 GitHub、数据库等工具。
下一步
如果你想继续深入，建议学习：
- 📖 [Opencode 核心模式：Plan 与 Build 详解]（学习如何规划大型任务）
- 📖 [Opencode 进阶配置 - 打造最适合你的 AI 编程环境]（深入学习配置文件）
💡 练习任务：尝试为你的项目编写一份
AGENTS.md文件，并配置一个 MCP 服务器（例如连接 GitHub）。这是将理论付诸实践的最佳方式。
## 相关文档
- [OpenCode 工具系统实战教程：从内置到扩展](/docs/gao-ji-pei-zhi/opencode-gong-ju-xi-tong-shi-zhan-jiao-cheng-cong-nei-zhi-dao-kuo-zhan.html)
- [OpenCode 规则编写实战教程：让 AI 助手稳定遵循你的项目约定](/docs/gao-ji-pei-zhi/opencode-gui-ze-bian-xie-shi-zhan-jiao-cheng-rang-ai-zhu-shou-wen-ding-zun-xun-ni-de-xiang-mu-yue-di.html)