Agent 使用指南

约 3894 个字 119 行代码 预计阅读时间 14 分钟

本章目标

本章介绍 AI 编程 Agent 的基本使用方法，并以 OpenCode 作为主要示例。阅读本章后，你应该能够理解如何给 Agent 提供有效上下文、如何使用计划模式、如何管理长会话、何时使用子 Agent 和 Skills，以及如何查阅 OpenCode 的具体配置方式。

AI Agent 不只是一个问答工具。它可以读取项目文件、搜索代码、运行命令、编辑文件、调用子 Agent、加载 Skills，并根据工具返回结果继续修正方案。因此，使用 Agent 的重点不是写一句“万能 Prompt”，而是把任务拆清楚、把上下文给准确、把权限和验证边界讲明白。

1. 从 Chatbot 到 Coding Agent

Agent 的工作循环

传统聊天机器人通常只根据用户输入生成回答，而 Coding Agent 会主动使用工具完成任务。它的工作过程更接近一个初级开发者：先理解需求，再读取资料，必要时运行命令，最后给出修改或结论。

一个典型的 Agent 工作循环是：

1. 理解任务目标
2. 查找或读取必要上下文
3. 制定计划
4. 调用工具执行操作
5. 观察工具输出
6. 修正方案
7. 汇报结果或继续迭代

这也意味着，Agent 的效果通常取决于四件事：

• 它是否知道你的真实目标
• 它是否看到了正确的上下文
• 它是否有明确的操作边界
• 它是否有可验证的完成标准

警惕 vibe slopping

所谓 vibe slopping，指的是只凭感觉不断让 Agent 生成和修改代码，却逐渐失去对代码行为、设计取舍和风险边界的掌控，是过度 vibe coding 带来的结果。使用 Agent 时，应该始终知道它改了什么、为什么这样改、是否符合项目约束，以及如何验证结果。对于重要修改，务必阅读 diff、运行测试，并要求 Agent 解释关键实现选择。真正有效的 Agent 使用方式，应该始终保持对项目的掌控感。

以 OpenCode 为例

OpenCode 是一个开源 AI 编程 Agent，支持 TUI、CLI、Web、IDE 等使用方式。日常最常用的是终端 TUI。本教程的相关 Agent 概念将以 OpenCode 为例，总体的核心思想和使用方式在任何 Agent 应用中都可以迁移。

OpenCode 中常见的 Agent 能力包括：

能力	作用
Build Agent	默认开发模式，适合实际修改代码、运行命令、完成任务
Plan Agent	计划模式，适合只分析和制定方案
@general	通用子 Agent，适合复杂研究或多步任务
@explore	只读探索代码库，适合搜索文件、理解结构
AGENTS.md	项目级规则和长期上下文
Skills	可复用的任务说明和领域知识
MCP	接入外部工具、文档、服务或数据库

启动 OpenCode：

opencode

在指定项目中启动：

opencode /path/to/project

注意 Workspace 安全

Agent 具有读取、搜索、运行命令和编辑文件的能力，可能会对当前 workspace 做出未预料到的操作。对于重要项目，推荐在容器、临时副本或隔离环境中运行 Agent；在开始前及时备份重要文件，并通过权限配置限制高风险操作，例如删除文件、覆盖配置、修改密钥相关文件或执行不可逆命令。正确的权限管理可以降低误操作带来的风险，避免造成不可逆的损失。

2. 正确的提问方式

一次说清楚任务

好的 Prompt 不一定很长，但应该减少 Agent 需要猜测的部分。最基本的任务描述应该包含：

• 背景：这是一个什么项目，相关功能是什么
• 目标：希望 Agent 完成什么
• 现象：当前行为和期望行为分别是什么
• 线索：可能相关的文件、日志、命令、截图或 profiling 结果
• 边界：是否允许修改文件、运行命令、联网、安装依赖
• 验证：如何判断任务完成

性能优化

不推荐：

优化一下这个程序。

推荐：

这个程序的功能是 XXX，目前在 XXX 处遇到了性能瓶颈。
期望提升约 X% 的性能。perf 结果如下：
...
请先分析可能的优化路径，并说明每种方案的风险。先不要修改代码。

文件引用和命令输出

OpenCode TUI 支持用 @ 引用文件。输入 @ 后可以模糊搜索当前项目文件，文件内容会自动加入对话上下文。

请解释 @src/main.cpp 中程序入口的执行流程。

也可以在消息开头使用 ! 执行 shell 命令，并把命令输出加入上下文：

!git status --short

不要滥用命令输出

不要把超长日志、完整构建输出或大量无关文件一次性塞给 Agent。先截取关键错误、关键路径和最小复现信息，通常效果更好。

OpenCode TUI 参考：

• File references
• Bash commands

3. 计划后执行

复杂任务先做计划

复杂任务不建议直接让 Agent 修改文件。更稳妥的流程是：

1. 先让 Agent 阅读相关文件
2. 要求它总结现状
3. 要求它提出计划
4. 你确认计划
5. 再允许它执行修改

用 Plan 和 Build 分工

OpenCode 提供 Plan 和 Build 两个内置主 Agent。

Agent	适合场景
Plan	分析、阅读、制定方案，不希望直接修改代码时使用
Build	实际开发、编辑文件、运行命令时使用

在 TUI 中按 Tab 可以在 Agent 之间切换。进入 Plan 后，可以这样要求：

请先阅读相关代码并给出实现计划，不要修改文件。
计划中需要说明：需要修改的文件、行为变化、测试方式和风险点。

确认计划后，再切回 Build，并明确允许执行：

计划可以，按这个方案做最小修改。修改后运行相关测试，并说明验证结果。

OpenCode Agents 参考：

• OpenCode Agents

4. 上下文管理

上下文里有什么

上下文是 Agent 当前能看到的信息。它通常包括：

• 系统提示词、用户偏好
• 用户输入、对话历史
• 项目规则文件
• 读取的文件
• 工具的输出
• 子 Agent 返回的总结
• 当前任务状态和部分结果
• 已加载 Skills 的内容
• MCP 工具描述和返回结果

上下文窗口是有限的。读入大量无关文件、粘贴完整日志、让 Agent 不断试错，都会挤占上下文并降低后续表现。

正确的管理方式包括：

• 只给当前任务必要的信息
• 用文件引用代替大段复制粘贴
• 长日志只保留关键错误片段
• 无关任务之间开启新会话
• 长任务中及时压缩上下文
• 将大量探索任务交给子 Agent

上下文污染

如果同一会话中反复纠错、尝试多个失败方向，Agent 可能会受到历史失败方案干扰。此时与其继续修补，不如总结当前结论后开启新会话。

压缩、清理和分叉会话

OpenCode 提供 /compact 压缩当前会话上下文，别名是 /summarize。

/compact

更推荐带上压缩要求：

/compact 请重点保留：已经修改的文件、未解决的问题、测试命令、失败日志、接下来要做的计划。

也可以在 opencode.json 中配置自动压缩：

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

如果当前任务已经结束，应该使用 /new 或 /clear 开启新会话。如果需要保留原会话内容并创建分支，可以使用 /fork 复制一份完整历史到新的会话中。

OpenCode 参考：

• OpenCode TUI Commands
• OpenCode Compaction Config

5. 项目规则与长期上下文

把稳定规则写下来

Agent 每次进入项目时都需要知道一些稳定信息，例如构建命令、测试命令、项目结构和代码风格。如果每次都靠对话临时补充，容易遗漏，也会浪费上下文。

项目规则文件适合记录：

• 项目是什么
• 目录结构如何组织
• 如何构建、测试、格式化
• 代码风格和命名约定
• 常见开发流程
• 项目特有的坑
• 哪些行为需要避免

项目规则文件不适合写：

• 大段教程
• 通用编程常识
• 频繁变化的信息
• 文件逐个说明
• 与大多数任务无关的长文档

用 AGENTS.md 固化项目约定

OpenCode 使用 AGENTS.md 作为项目规则文件。第一次使用时可以运行：

/init

OpenCode 会分析项目并创建或更新 AGENTS.md。建议将项目级 AGENTS.md 提交到 Git。

示例：

# Project Rules

## Build and Test

- Install dependencies with `pnpm install`.
- Run unit tests with `pnpm test`.
- Run lint with `pnpm lint`.

## Code Style

- Use TypeScript strict mode.
- Prefer existing utilities before adding new helpers.
- Do not introduce new dependencies without asking.

## Workflow

- For multi-file changes, explain the plan before editing.
- After code changes, run the most relevant tests.
- Never read `.env` or files under `secrets/`.

OpenCode 也支持全局规则：

~/.config/opencode/AGENTS.md

项目规则适合团队共享，全局规则适合个人偏好。

OpenCode Rules 参考：

• OpenCode Rules

6. 拆分大型任务

把大目标拆成小交付

不要把“实现完整系统”作为一个单次任务交给 Agent。任务越大，Agent 越容易在后半段忘记前面的约束，或者为了完成目标引入过度设计。

大型任务可以拆成以下阶段：

1. 需求澄清
2. 代码结构探索
3. 实现计划
4. 核心功能实现
5. 测试补充
6. 文档更新
7. 代码审查
8. 性能或安全复查

每一步都应该有明确产出。例如“只总结调用链，不修改文件”“只写测试，不修实现”“只审查 diff，不做修改”。

在 OpenCode 中分阶段推进

在 OpenCode 中，可以结合 Plan、Build 和子 Agent 拆分任务。

第一步只探索：

@explore 请找出和登录流程相关的文件，并总结调用链。不要修改文件。

第二步制定计划：

请基于刚才的分析，给出修复登录超时问题的计划。列出需要修改的文件、测试策略和风险点。不要修改文件。

第三步执行：

按计划做最小修改，并运行相关测试。不要改动无关文件。

OpenCode 中也可以用 CLI 继续已有会话：

opencode --continue
opencode --session <session-id>

CLI 参考：

• OpenCode CLI

---

7. 子 Agent

什么时候交给子 Agent

子 Agent 适合处理会产生大量中间信息的任务。它拥有独立上下文，可以在自己的上下文中搜索、阅读、分析，最终只把结论返回给主会话。

适合使用子 Agent 的场景：

• 大量代码搜索
• 阅读多个文件后总结架构
• 调研第三方库或外部文档
• 分析多个可能原因
• 审查当前改动
• 只需要结论，不需要完整中间过程

是否应该使用子 Agent？

如果只需要结论，不需要完整中间过程或详细推理，通常适合交给子 Agent。

OpenCode 内置子 Agent

OpenCode 内置两个常用子 Agent：

子 Agent	作用
@general	通用子 Agent，适合复杂研究和多步任务
@explore	快速只读探索代码库，不能修改文件

示例：

@explore 请搜索这个项目中所有处理 checkpoint 的代码路径，只返回文件列表和职责总结，不要修改文件。

也可以在主 Agent 的提示词中说明何时调用对应的子 Agent；主 Agent 会根据子 Agent 的描述自动调用。

子 Agent 会创建 child session。OpenCode 默认支持在父子会话之间导航：

操作	默认快捷键
进入第一个子会话	Ctrl+X 后按 Down
在子会话间切换	Right / Left
返回父会话	Up

OpenCode Agents 参考：

• OpenCode Agents

8. Skills

什么时候需要 Skill

Skills 用于复用某类任务的说明、流程或领域知识。它和普通 Prompt 最大的区别是按需加载：Agent 平时只知道 Skill 的名称和描述，只有需要时才加载完整内容。

适合做成 Skill 的内容：

• 反复使用的分析流程
• 项目或团队的操作 SOP
• 某类文档的写作规范
• benchmark 审查标准
• release checklist
• 实验记录格式

不适合做成 Skill 的内容：

• 每次会话都必须知道的核心项目规则
• 只用一次的临时说明
• 需要外部系统能力的功能本身

Skills 和 MCP 的区别：

对比	Skills	MCP
主要作用	知识复用、流程复用	能力扩展、外部工具连接
形式	Markdown 文件	本地或远程服务器
成本	按需加载，token 较省	工具定义可能占用上下文
适合场景	SOP、规范、分析流程	数据库、GitHub、Sentry、文档搜索

Skill 的目录和字段

OpenCode 会从多个位置发现 Skills：

• .opencode/skills/<name>/SKILL.md
• ~/.config/opencode/skills/<name>/SKILL.md
• .claude/skills/<name>/SKILL.md
• ~/.claude/skills/<name>/SKILL.md
• .agents/skills/<name>/SKILL.md
• ~/.agents/skills/<name>/SKILL.md

一个 Skill 的基本结构是：

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

OpenCode 识别的 SKILL.md frontmatter 字段包括：

字段	必需	说明
name	是	Skill 名称，必须和目录名匹配
description	是	功能和使用场景
license	否	许可证
compatibility	否	环境兼容性说明
metadata	否	自定义元数据

示例：

---
name: benchmark-review
description: Review benchmark results and check whether performance claims are supported by evidence
license: MIT
compatibility: opencode
metadata:
  audience: hpc-learners
---

## What I do

Use this skill when reviewing benchmark or performance optimization results.

Check:

1. Whether baseline and optimized versions are comparable.
2. Whether hardware, compiler flags, input size and thread count are recorded.
3. Whether the result includes repeated runs.
4. Whether the conclusion is supported by data.
5. Whether the optimization changes program behavior.

Ask for missing benchmark context if necessary.

Tip

Agent 本身也很擅长构建 Skill，可以直接通过详细描述需求让 Agent 帮你创建 Skill。

OpenCode Skills 参考：

• OpenCode Agent Skills

9. MCP 与外部工具

MCP 适合连接外部系统

MCP 是 Model Context Protocol，用来把外部工具连接到 Agent。它适合让 Agent 查询外部系统，而不是把大量信息手动复制到 Prompt 中。

适合使用 MCP 的场景：

• 查询外部文档
• 连接 GitHub 或 GitLab
• 查询数据库
• 查看 Sentry、监控或日志
• 连接内部工具

但 MCP 也有成本。每个 MCP server 暴露的工具描述都可能进入上下文。如果启用过多 MCP，可能快速占满上下文，降低 Agent 的回答质量。

只启用必要 MCP

不要把所有 MCP 默认打开。按任务启用最相关的 MCP，通常比“工具越多越好”更稳定。

在 OpenCode 中配置 MCP

OpenCode 支持 local 和 remote MCP。

配置示例：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

使用时可以在 Prompt 中明确指定：

请使用 context7 查询这个库的最新 API 用法，然后对照当前代码给出修改建议。

也可以用 CLI 管理 MCP：

opencode mcp add
opencode mcp list
opencode mcp auth <name>
opencode mcp logout <name>

OpenCode MCP 参考：

• OpenCode MCP servers

10. OpenCode 命令速查

本节只列出常用入口。更完整的命令和快捷键请看官方文档。

10.1 TUI Slash 命令

命令	作用
/connect	添加或配置 LLM 提供商
/init	创建或更新 AGENTS.md
/models	列出并切换模型
/new / /clear	开始新会话
/sessions / /resume / /continue	列出并切换会话
/compact / /summarize	压缩当前会话上下文
/undo	撤销最后一条消息及其文件修改
/redo	重做已撤销的消息和文件修改
/details	切换工具执行详情显示
/thinking	切换 reasoning block 显示
/themes	切换主题
/editor	使用外部编辑器撰写消息
/export	导出当前对话为 Markdown
/help	显示帮助
/exit / /quit / /q	退出 OpenCode

参考：

• OpenCode TUI Commands

10.2 CLI 命令

命令	作用
opencode	启动 TUI
opencode [project]	在指定项目中启动 TUI
opencode run "task"	非交互运行一次任务
opencode auth login	登录或添加提供商凭证
opencode auth list / opencode auth ls	列出已认证提供商
opencode auth logout	删除提供商凭证
opencode models	列出可用模型
opencode agent list	列出 Agent
opencode mcp add	添加 MCP 服务器
opencode mcp list / opencode mcp ls	查看 MCP 服务器
opencode stats	查看 token 和成本统计

参考：

• OpenCode CLI

10.3 常用快捷键

快捷键	作用
Enter	发送消息
Ctrl+Enter / Shift+Enter	换行
Escape	中断当前响应
Tab	切换 Agent
Ctrl+X 后按 n	新建会话
Ctrl+X 后按 l	会话列表
Ctrl+X 后按 m	模型列表
Ctrl+X 后按 u	撤销消息和文件修改
Ctrl+X 后按 r	重做
Ctrl+X 后按 c	压缩上下文
Ctrl+X 后按 b	切换侧边栏
Ctrl+X 后按 t	主题列表
Ctrl+P	命令面板

参考：

• OpenCode Keybinds

---

11. 配置参考

11.1 配置文件位置

OpenCode 支持 JSON 和 JSONC 配置。

常见位置：

位置	作用
~/.config/opencode/opencode.json	用户全局配置
opencode.json	项目配置
~/.config/opencode/tui.json	用户全局 TUI 配置
tui.json	项目 TUI 配置
.opencode/	项目级 agents、commands、plugins、skills、themes 等

OpenCode 的配置是合并的，不是简单替换。后加载的配置会覆盖冲突字段，但不会删除非冲突字段。

参考：

• OpenCode Config

11.2 模型与提供商

添加提供商最简单的方式是在 TUI 中运行：

/connect

也可以使用 CLI：

opencode auth login
opencode models

模型配置示例：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.1-codex",
  "small_model": "opencode/gpt-5.1-nano"
}

参考：

• OpenCode Providers
• OpenCode Models

11.3 权限配置

权限控制属于安全边界，建议按项目显式配置。OpenCode 权限动作包括：

动作	含义
allow	直接允许
ask	执行前询问
deny	禁止执行

示例：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny",
      "git push*": "deny"
    },
    "edit": "ask"
  }
}

如果使用自动批准模式：

opencode --auto

显式 deny 规则仍会生效。

参考：

• OpenCode Permissions

12. 其他参考

不同 Agent 工具的交互细节不同，但很多使用原则是相通的：明确目标、控制上下文、先计划再执行、审查 diff、运行测试，并保持对代码修改的掌控感。下面这些资料可以作为延伸阅读参考。

• Claude Code Best Practice
• Best practices - Codex | OpenAI Developers