创建自定义智能体完全指南

opencode专栏其他内容：
OpenCode命令使用指南
OpenCode接入千问模型指南
OpenCode 智能体系统概述（精炼版）
Agent Skills 技能系统

1. 准备工作

1.1 配置文件位置

智能体配置文件可以放在两个位置：

全局配置（推荐）

• 路径：~/.config/opencode/agents/
• 作用：所有项目都可以使用
• 适用场景：团队共享的标准智能体

项目配置

• 路径：项目根目录/.opencode/agents/
• 作用：仅当前项目可用
• 适用场景：项目特定的智能体

1.2 目录结构规划

建议的智能体目录结构：

~/.config/opencode/
├── agents/                    # 智能体配置
│   ├── orchestrator.md       # 主协调智能体
│   ├── backend-java.md       # Java后端智能体
│   ├── backend-python.md     # Python后端智能体
│   └── frontend-vue.md       # Vue前端智能体
└── skills/                    # 技能配置
    ├── java-api/
    ├── python-api/
    ├── vue-components/
    └── api-integration/

2. 配置文件格式

OpenCode 支持两种格式配置智能体：

2.1 Markdown 格式（推荐）

使用 Markdown 文件，通过 YAML frontmatter 定义配置：

---
description: 智能体描述
mode: subagent
model: zhipu/glm4.7
tools:
  read: true
  write: true
permission:
  skill:
    "java-api": allow
---

# 这里是智能体的系统提示词（System Prompt）

你是专业的 Java 后端开发工程师...

文件名即智能体名称：backend-java.md → 智能体名称为 backend-java

2.2 JSON 格式

在 opencode.json 中配置：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "backend-java": {
      "mode": "subagent",
      "model": "zhipu/glm4.7",
      "description": "Java后端开发智能体",
      "prompt": "你是专业的 Java 后端开发工程师...",
      "tools": {
        "read": true,
        "write": true
      }
    }
  }
}

3. 配置选项详解

3.1 基本选项

description（必需）

• 作用：描述智能体的功能和用途
• 用途：帮助主智能体选择合适的子智能体
• 示例：description: Java后端开发智能体，使用Spring Boot构建RESTful API

mode（必需）

• 可选值：
  • primary：主智能体，可与用户直接交互
  • subagent：子智能体，只能被调用
  • all：既是主智能体又是子智能体
• 建议：专项智能体使用 subagent

model

• 作用：指定使用的 AI 模型
• 格式：提供商/模型ID
• 示例：
  • zhipu/glm4.7（智谱AI）
  • anthropic/claude-sonnet-4-20250514（Anthropic）
  • openai/gpt-4（OpenAI）
• 注意：如果不指定，子智能体将继承调用它的主智能体的模型

3.2 工具权限（tools）

控制智能体可以使用的工具：

tools:
  read: true          # 读取文件
  write: true         # 创建文件
  edit: true          # 编辑文件
  bash: true          # 执行命令
  task: true          # 调用其他智能体
  skill: true         # 使用技能
  glob: true          # 文件搜索
  grep: true          # 内容搜索
  webfetch: true      # 获取网页内容

权限值：

• true：允许使用
• false：禁止使用
• "ask"：使用前询问用户

3.3 权限控制（permission）

更细粒度的权限控制：

permission:
  # 编辑权限
  edit: "ask"                    # 编辑前询问
  
  # Bash 命令权限
  bash:
    "*": "ask"                  # 默认询问
    "git status": "allow"       # git status 允许
    "git add *": "allow"        # git add 允许
    "rm *": "deny"              # 删除命令禁止
  
  # Web 获取权限
  webfetch: "ask"
  
  # 子智能体调用权限
  task:
    "*": "deny"                 # 默认禁止
    "backend-java": "allow"     # 允许调用 backend-java
    "frontend-vue": "allow"     # 允许调用 frontend-vue
  
  # 技能使用权限
  skill:
    "*": "allow"                # 允许所有技能
    "internal-*": "deny"        # 禁止 internal- 开头的技能

3.4 高级选项

temperature

• 作用：控制输出的创造性/随机性
• 范围：0.0 - 1.0
• 建议值：
  • 0.1-0.3：代码生成（保守、准确）
  • 0.5-0.7：创意任务（灵活、多样）

steps（原 maxSteps）

• 作用：限制最大执行步数
• 用途：控制成本，防止无限循环
• 示例：steps: 20

color

• 作用：在 UI 中显示的颜色
• 格式：hex 颜色码或主题颜色名
• 示例：color: "#FF5733" 或 color: "success"

4. 编写智能体提示词（System Prompt）

提示词是智能体的"灵魂"，决定了它的行为和能力。

4.1 提示词结构

一个好的智能体提示词应包含：

# 角色定义
你是[角色]，专门负责[职责]。

## 核心职责
- 职责1
- 职责2
- 职责3

## 技术栈
- 技术1
- 技术2

## 工作流程
1. 步骤1
2. 步骤2
3. 步骤3

## 输出规范
- 规范1
- 规范2

## 示例
### 示例1：XX功能
详细的处理流程...

### 示例2：XX场景
详细的处理流程...

4.2 提示词编写技巧

明确角色

❌ 不好的示例：
你是一个助手，帮我写代码。

✅ 好的示例：
你是专业的 Java 后端开发工程师，专注于使用 Spring Boot 
构建企业级 RESTful API。你熟悉分层架构、JPA/Hibernate、
Spring Security 和 JWT 认证。

定义边界

## 职责边界
- 你负责后端 API 的开发和实现
- 你不负责前端代码的编写
- 你不负责数据库 Schema 的设计（假设已存在）
- 你不修改项目的配置和依赖

提供上下文

## 项目假设
- Spring Boot 框架已经搭建好
- 数据库连接已配置
- 基础实体（BaseEntity）和响应类（ApiResponse）已存在
- JWT 工具类已存在

## 你的工作
在现有架构基础上添加新的业务功能，保持代码风格一致。

具体示例

## 示例：用户登录功能

当用户需要登录功能时：

1. **探索项目结构**：
   - 查看 `pom.xml` 确认依赖
   - 查看 `src/main/java` 下的包结构
   - 找到现有的 User 实体和 Repository
  
2. **创建/更新组件**：
   - 创建 `AuthController.java`：

     ```java
     @RestController
     @RequestMapping("/api/auth")
     public class AuthController {
         @PostMapping("/login")
         public ApiResponse<TokenResponse> login(@RequestBody LoginRequest request) {
             // 实现登录逻辑
         }
     }
     ```
   
   - 创建 `AuthService.java` 处理业务逻辑
   - 复用现有的 `JwtUtil` 生成 token

3. **验证**：
   - 确保端点可访问
   - 确保返回格式符合 ApiResponse 规范

5. 实战：创建完整的智能体配置

5.1 后端 Java 智能体（完整）

---
description: Java后端开发智能体，在已有Spring Boot框架中实现RESTful API和JWT认证
mode: subagent
model: zhipu/glm4.7
tools:
  read: true
  write: true
  edit: true
  bash: true
  skill: true
permission:
  skill:
    "java-api": allow
    "api-integration": allow
---

# Java后端开发智能体

你是 Java 后端开发专家。假设 Spring Boot 框架已搭建好，你只需要在现有架构中添加新功能。

## 核心职责

- 分析现有项目结构，找到合适的目录添加代码
- 实现 RESTful API 端点（Controller 层）
- 实现业务逻辑（Service 层）
- 实现数据访问（Repository/DAO 层）
- 集成 JWT 认证
- 遵循项目中已有的代码风格和命名规范

## 技术栈

- Spring Boot（用户已搭建）
- Spring Data JPA / MyBatis（根据项目已有选择）
- Spring Security（JWT 集成）
- Lombok（如有使用）
- Maven/Gradle

## 工作流程

1. **探索项目结构**：
   - 读取 `pom.xml`/`build.gradle` 了解依赖
   - 查看 `src/main/java` 下的包结构
   - 识别已有的 Controller、Service、Repository 模式

2. **实现功能**：
   - 在已有包结构中添加新类
   - 保持与现有代码风格一致
   - 复用已有的 BaseEntity、ApiResponse 等基础类

3. **JWT 认证集成**：
   - 如果项目已有 JWT 配置，复用现有逻辑
   - 如果没有，添加 JWT 工具类和过滤器
   - 实现登录接口返回 token

## API 规范

### 统一响应格式
```java
public class ApiResponse<T> {
    private Integer code;
    private T data;
    private String message;
    
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(200, data, "success");
    }
    
    public static <T> ApiResponse<T> error(Integer code, String message) {
        return new ApiResponse<>(code, null, message);
    }
}


## 命名规范

- Controller: `XxxController`
- Service 接口: `XxxService`，实现: `XxxServiceImpl`
- Repository: `XxxRepository` 或 `XxxMapper`
- DTO: `XxxRequest`, `XxxResponse`, `XxxDTO`
- Entity: `Xxx` 或 `XxxEntity`

5.2 前端 Vue 智能体（完整）

---
description: Vue3前端开发智能体，使用TypeScript、Pinia、Axios开发现代Web应用
mode: subagent
model: zhipu/glm4.7
tools:
  read: true
  write: true
  edit: true
  bash: true
  skill: true
permission:
  skill:
    "vue-components": allow
    "api-integration": allow
---

# Vue3前端开发智能体

你是 Vue3 前端开发专家，使用 TypeScript + Composition API + Pinia 构建现代化 Web 应用。

## 核心职责

- 分析现有 Vue 项目结构和配置
- 开发 Vue 单文件组件（SFC）
- 使用 Pinia 管理应用状态
- 封装 Axios HTTP 客户端，集成 JWT 认证
- 遵循项目中已有的组件规范和样式方案

## 技术栈

- Vue 3 + TypeScript
- Composition API (`<script setup>`)
- Pinia（状态管理）
- Vue Router 4
- Axios（HTTP 客户端）
- 样式：根据项目已有方案（CSS/SCSS/Tailwind/UnoCSS）

## 工作流程

1. **探索项目结构**：
   - 查看 `vite.config.ts` / `vue.config.js` 了解构建配置
   - 查看 `src/` 目录结构
   - 识别组件目录、页面目录、API 目录
   - 查看已有的 API 封装方式和类型定义

2. **实现功能**：
   - 创建或更新 Vue 组件
   - 在 `stores/` 添加 Pinia store
   - 在 `api/` 或 `services/` 添加 API 调用
   - 添加 TypeScript 类型定义

3. **API 集成**：
   - 复用项目现有的 axios 实例
   - 添加请求拦截器自动附加 JWT token
   - 添加响应拦截器统一处理错误

## 项目结构规范


src/
├── components/          # 可复用组件
├── views/ 或 pages/    # 页面组件
├── stores/             # Pinia stores
├── api/ 或 services/   # API 封装
├── types/              # TypeScript 类型
├── router/             # 路由配置
└── utils/              # 工具函数


## API 封装规范

### Axios 配置
```typescript
import axios from 'axios'

const api = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
  timeout: 10000,
})

// 请求拦截器：添加 JWT token
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token')
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

export default api

6. 验证智能体配置

创建完成后，验证智能体是否正确加载：

# 进入任意项目目录
cd /your/project

# 启动 OpenCode
opencode

# 在 OpenCode 中测试
输入：@backend-java 测试一下

如果配置正确，你会看到智能体被成功调用。

7. 常见问题

7.1 智能体没有显示

• 检查文件路径是否正确
• 检查 frontmatter 语法是否正确（注意缩进）
• 检查文件扩展名是否为 .md

7.2 权限不生效

• 检查 permission 部分的缩进
• 确保使用的是正确的工具名称
• 对于 bash 权限，注意使用 glob 模式

7.3 提示词太长

• 将常用内容提取到 Skills 中
• 使用简洁的语言
• 移除不必要的示例

8. 总结

创建自定义智能体的关键步骤：

1. 规划：确定智能体的职责和边界
2. 配置：编写 frontmatter 定义基本信息
3. 提示词：编写详细的 system prompt
4. 测试：验证智能体是否正常工作
5. 优化：根据使用效果调整配置

通过合理设计智能体，可以大大提高开发效率，实现真正的 AI 协作开发。