base/AI-TOOLS-INTEGRATION.md

Go-Zero AI 工具集成指南

本文档详细说明 zero-skills、ai-context 和 mcp-zero 三个工具如何配合使用。

---

📊 三件套概览

工具	用途	大小	最适合工具	角色
ai-context	工作流指令和决策树	~5KB	GitHub Copilot, Cursor, Windsurf	工作流层
zero-skills	完整知识库	~40KB	Claude Code，深度学习	知识层
mcp-zero	运行时工具（goctl 命令）	MCP Server	Claude Desktop/Code	执行层

---

🎯 架构协作图

┌─────────────────────────────────────────────────────────────┐
│                     AI 助手                                  │
│  (Claude Code, GitHub Copilot, Cursor, 等)                  │
└────────────┬─────────────────────┬──────────────────────────┘
             │                     │
             ├─ 工作流层 ──────────┤
             │  ai-context         │  "做什么" - 快速决策
             │  (~5KB)             │  每次交互都加载
             │                     │
             ├─ 知识层 ────────────┤
             │  zero-skills        │  "如何和为什么" - 详细模式
             │  (~40KB)            │  需要时加载
             │                     │
             └─ 执行层 ────────────┘
                mcp-zero             "执行" - 运行 goctl 命令
                (MCP Server)          生成实际代码文件

---

📦 工具详细说明

1. ai-context - 工作流层

定位: 快速决策工具，回答"做什么"

功能:

• 提供简洁的工作流指导
• 帮助 AI 快速做出开发决策
• 每次交互都加载，轻量级（~5KB）

适用场景:

• 快速生成代码片段
• 内联代码补全
• 需要快速决策的开发流程

安装方式:

# GitHub Copilot
git clone https://github.com/zeromicro/ai-context.git .github/copilot-instructions.md

# Cursor
git clone https://github.com/zeromicro/ai-context.git .cursorrules

# Windsurf
git clone https://github.com/zeromicro/ai-context.git .windsurfrules

使用特点:

• ⚡ 快速加载
• 📝 简洁的决策树
• 🎯 适合日常开发

---

2. zero-skills - 知识层

定位: 深度知识库，回答"如何和为什么"

功能:

• 完整的 go-zero 模式指南
• 三层架构（Handler → Logic → Model）详解
• 正确和错误示例对比
• 生产级最佳实践

适用场景:

• 深度学习和理解 go-zero
• 复杂的微服务架构设计
• 代码审查和问题排查
• 需要 AI Code 的高级功能

安装方式:

# 项目级别（推荐）
git clone https://github.com/zeromicro/zero-skills.git .claude/skills/zero-skills

# 个人级别
git clone https://github.com/zeromicro/zero-skills.git ~/.claude/skills/zero-skills

在 Claude Code 中的使用:

# 自动加载
# 处理 go-zero 文件（.api, .proto, go.mod）时自动加载

# 手动调用
/zero-skills

# 带参数调用
/zero-skills 创建用户管理 API

# 检查可用性
What skills are available?

使用特点:

• 📚 完整知识库（~40KB）
• 🎓 需要时加载，按需获取
• 🔍 详细模式和示例
• 🤖 支持子代理和动态上下文

---

3. mcp-zero - 执行层

定位: 代码执行工具，负责"执行"

功能:

• 执行 goctl 命令生成代码
• 生成实际的项目文件
• MCP Server 协议集成

适用场景:

• 自动化代码生成
• 批量创建服务文件
• Claude Desktop/Code 环境使用

安装方式:

1. 安装 MCP Server:

npm install -g @zeromicro/mcp-zero

2. 配置 Claude Desktop:

{
  "mcpServers": {
    "mcp-zero": {
      "command": "node",
      "args": ["C:\\Users\\YourUser\\AppData\\Roaming\\npm\\node_modules\\@zeromicro\\mcp-zero\\dist\\index.js"],
      "env": {
        "GOCTL_PATH": "/path/to/goctl"
      }
    }
  }
}

使用特点:

• ⚙️ 执行 goctl 命令
• 📁 生成实际代码文件
• 🔌 MCP 协议集成

---

🚀 使用场景

场景 1: GitHub Copilot 用户

工具组合: 仅 ai-context

工作流程:

用户编辑代码
    ↓
加载 ai-context
    ↓
AI 提供快速建议
    ↓
用户手动运行 goctl 命令

优点:

• 快速内联建议
• 工作流指导
• 无需额外配置

限制:

• 无代码执行能力
• 需手动运行 goctl 命令

示例使用:

# .github/copilot-instructions.md

<!-- ai-context 内容 -->
当编辑 go-zero 文件时，遵循以下流程：
1. 先定义 .api 文件类型和路由
2. 使用 goctl 生成代码
3. 在 internal/logic/ 实现业务逻辑
4. 使用 sqlx 进行数据库操作

---

场景 2: Claude Code 用户（最佳体验）⭐

工具组合: zero-skills + mcp-zero

工作流程:

用户发起请求
    ↓
加载 zero-skills (知识层)
    ↓
AI 调用 mcp-zero 工具 (执行层)
    ↓
执行 goctl 命令生成代码
    ↓
返回生成的文件和说明

优点:

• 来自模式指南的深度知识
• 通过 goctl 自动生成代码
• 实时项目数据的动态上下文
• 复杂任务的子代理工作流

完整示例:

用户: /zero-skills 创建用户管理 API

AI 处理:

1. 加载 zero-skills 的 rest-api-patterns.md
2. 了解三层架构要求
3. 调用 mcp-zero 的 generate_api 工具:

   goctl api go -api user.api -dir .
   

4. 生成文件结构:

   .
   ├── user.api
   ├── etc/
   ├── internal/
   │   ├── handler/
   │   ├── logic/
   │   ├── svc/
   │   └── types/
   └── main.go
   

5. 解释生成的代码结构

高级功能:

# 子代理使用示例
/zero-skills 分析项目架构

AI 将:
1. Fork 子代理
2. 只读分析项目文件
3. 返回架构分析报告

---

场景 3: Cursor/Windsurf 用户

工具组合: ai-context + zero-skills 链接

工作流程:

用户在 IDE 中编码
    ↓
加载 ai-context (快速决策)
    ↓
必要时链接到 zero-skills (深度知识)
    ↓
AI 提供建议和指导

优点:

• IDE 原生体验
• 快速建议 + 深度知识
• 灵活使用

配置示例:

.cursorrules:

<!-- ai-context 内容 -->
当使用 go-zero 框架时：
- 遵循三层架构: Handler → Logic → Model
- 使用 goctl 生成代码
- 使用 httpx.Error() 处理错误

<!-- 链接到 zero-skills -->
详情参考: .claude/skills/zero-skills/references/rest-api-patterns.md

---

🔗 工具间的协作示例

示例 1: 创建完整的 REST API

用户请求: "创建用户管理的 REST API"

三件套协作:

Step 1: ai-context 决策 (工作流层)
------------------------------------
决定创建流程:
1. 定义 .api 文件
2. 生成代码
3. 实现业务逻辑

Step 2: zero-skills 指导 (知识层)
------------------------------------
生成 user.api 内容参考:
- 类型定义结构
- 路由定义规范
- handler 命名约定
- 验证规则

Step 3: mcp-zero 执行 (执行层)
------------------------------------
执行命令:
goctl api go -api user.api -dir .

生成文件:
├── user.api
├── etc/user-api.yaml
├── internal/handler/*.go
├── internal/logic/*.go
├── internal/svc/servicecontext.go
├── internal/types/types.go
└── user.go

---

示例 2: 修复数据库连接问题

用户请求: "数据库连接失败，怎么排查"

三件套协作:

Step 1: ai-context 决策
------------------------------------
分析可能的错误原因:
- 连接字符串错误
- 数据库服务未启动
- 防火墙阻止
- 驱动问题

Step 2: zero-skills 深度分析
------------------------------------
从 database-patterns.md 获取:
- 正确的连接字符串格式
- ServiceContext 注入方法
- sqlx 配置方式
- 错误处理最佳实践

Step 3: 提供解决方案
------------------------------------
参考配置:
```go
// internal/svc/servicecontext.go
type ServiceContext struct {
    Config config.Config
    SqlConn sqlx.SqlConn
}

func NewServiceContext(c config.Config) *ServiceContext {
    return &ServiceContext{
        Config:  c,
        SqlConn: sqlx.NewMysql(c.Database.DataSource),
    }
}

检查清单:

• 数据库服务运行状态
• 连接字符串格式
• 防火墙设置
• sqlx 导入正确

---

## 📋 快速参考

### 工具选择决策树

开始 │ ├─ 使用什么 AI 工具？ │ ├─ GitHub Copilot → 使用 ai-context │ ├─ Cursor/Windsurf → 使用 ai-context + zero-skills │ └─ Claude Code → 使用 zero-skills + mcp-zero │ └─ 任务类型？ ├─ 快速代码片段 → ai-context ├─ 深度学习/参考 → zero-skills └─ 生成项目文件 → mcp-zero

### 命令速查

```bash
# ai-context 安装
git clone https://github.com/zeromicro/ai-context.git .github/copilot-instructions.md

# zero-skills 安装（项目级）
git clone https://github.com/zeromicro/zero-skills.git .claude/skills/zero-skills

# zero-skills 安装（个人级）
git clone https://github.com/zeromicro/zero-skills.git ~/.claude/skills/zero-skills

# mcp-zero 安装
npm install -g @zeromicro/mcp-zero

# 手动调用 zero-skills
/zero-skills
/zero-skills 创建用户管理 API

---

💡 最佳实践

1. Claude Code 环境推荐配置

项目级 zero-skills + mcp-zero

为什么:

• 自动加载，无需手动触发
• 完整知识库 + 代码执行
• 支持高级功能（子代理、动态上下文）

2. 多工具环境配置

~/.claude/skills/zero-skills        # 所有项目可用
~/.claude/skills/ai-context        # 可选
项目/.github/copilot-instructions.md # Copilot 专用
项目/.cursorrules                   # Cursor 专用

3. 性能优化

• 轻量级需求: 仅用 ai-context（5KB）
• 深度学习: zero-skills（40KB，按需加载）
• 代码生成: 配合 mcp-zero 执行层

---

🔗 相关资源

• ai-context GitHub - 工作流层
• zero-skills GitHub - 知识层
• mcp-zero GitHub - 执行层
• go-zero 官方文档 - 框架文档
• Agent Skills 规范 - 技能规范

---

📝 总结

层级	工具	作用	大小
工作流层	ai-context	快速决策"做什么"	~5KB
知识层	zero-skills	深度知识"如何和为什么"	~40KB
执行层	mcp-zero	执行代码生成	MCP Server

核心思想: 根据不同的 AI 工具和任务需求，灵活组合三件套，实现最高效的开发体验。

---

📦 Go-Zero + GORM 模块开发实战指南

概述

使用 GORM 替代默认的 sqlx 时，goctl 生成的代码需要手动修复多处问题。本文档记录了用户模块开发过程中遇到的坑点和解决方案。

---

一、生成基础代码

# 1. 生成 API 定义
goctl api go -api user.api -dir backend

# 2. 生成 model 代码（如果使用 sqlx）
goctl model mysql ddl -src user.sql -dir backend/model

注意： 使用 GORM 时，goctl model 生成的代码可能不适用，需要手动定义 Model 和 CRUD 方法。

---

二、修复 ServiceContext (GORM 初始化)

文件：backend/internal/svc/servicecontext.go

常见错误 1：gorm.Open 参数不足

❌ 错误：

db, err := gorm.Open(mysql.Open(dsn))

✅ 正确：

db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})

常见错误 2：DB.Close() 方法不存在

❌ 错误：

func (s *ServiceContext) Close() error {
    if s.DB != nil {
        return s.DB.Close() // *gorm.DB 没有 Close 方法
    }
    return nil
}

✅ 正确：

func (s *ServiceContext) Close() error {
    if s.DB != nil {
        sqlDB, err := s.DB.DB() // 获取底层 *sql.DB
        if err != nil {
            return err
        }
        return sqlDB.Close()
    }
    return nil
}

完整的 NewServiceContext

func NewServiceContext(c config.Config) *ServiceContext {
    dsn := "user:password@tcp(host:port)/dbname?charset=utf8mb4&parseTime=true&loc=Local"
    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
    if err != nil {
        panic("Failed to connect database: " + err.Error())
    }

    // 自动迁移（必须在启动时调用）
    err = db.AutoMigrate(&model.User{})
    if err != nil {
        panic("Failed to migrate database: " + err.Error())
    }

    return &ServiceContext{
        Config: c,
        DB:     db,
        // ...其他字段
    }
}

---

三、实现 Model 层 (CRUD 操作)

关键点： goctl 生成的 Logic 文件会引用 model.FindOne、model.Insert 等方法，但默认的 model 包只包含实体定义，缺少这些 CRUD 方法。

需要手动创建：backend/model/<module>_model.go

标准模板

package model

import (
    "context"
    "errors"
    "gorm.io/gorm"
)

var (
    ErrNotFound = errors.New("record not found")
)

// Insert 插入记录
func Insert(ctx context.Context, db *gorm.DB, record interface{}) (int64, error) {
    result := db.WithContext(ctx).Create(record)
    if result.Error != nil {
        return 0, result.Error
    }
    return record.(*User).Id, nil // 根据实际结构体调整
}

// FindOne 根据ID查询
func FindOne(ctx context.Context, db *gorm.DB, id int64) (*User, error) {
    var user User
    result := db.WithContext(ctx).First(&user, id)
    if result.Error != nil {
        if errors.Is(result.Error, gorm.ErrRecordNotFound) {
            return nil, ErrNotFound
        }
        return nil, result.Error
    }
    return &user, nil
}

// FindOneByXxx 根据唯一字段查询
func FindOneByEmail(ctx context.Context, db *gorm.DB, email string) (*User, error) {
    var user User
    result := db.WithContext(ctx).Where("email = ?", email).First(&user)
    if result.Error != nil {
        if errors.Is(result.Error, gorm.ErrRecordNotFound) {
            return nil, ErrNotFound
        }
        return nil, result.Error
    }
    return &user, nil
}

// Update 更新记录
func Update(ctx context.Context, db *gorm.DB, user *User) error {
    return db.WithContext(ctx).Save(user).Error
}

// Delete 删除记录
func Delete(ctx context.Context, db *gorm.DB, id int64) error {
    return db.WithContext(ctx).Delete(&User{}, id).Error
}

// FindList 分页查询列表
func FindList(ctx context.Context, db *gorm.DB, page, pageSize int64, keyword string, status int64) ([]User, int64, error) {
    var users []User
    var total int64

    query := db.WithContext(ctx).Model(&User{})

    // 关键字搜索
    if keyword != "" {
        query = query.Where("username LIKE ? OR email LIKE ?",
            "%"+keyword+"%", "%"+keyword+"%")
    }

    // 状态筛选
    if status > 0 {
        query = query.Where("status = ?", status)
    }

    // 统计总数
    if err := query.Count(&total).Error; err != nil {
        return nil, 0, err
    }

    // 分页
    offset := (page - 1) * pageSize
    if offset < 0 {
        offset = 0
    }

    err := query.Offset(int(offset)).Limit(int(pageSize)).Find(&users).Error
    if err != nil {
        return nil, 0, err
    }

    return users, total, nil
}

---

四、开发清单

• 修复 gorm.Open 调用，添加 &gorm.Config{}
• 修复 Close() 方法，使用 db.DB().Close()
• 在 NewServiceContext 中添加 AutoMigrate
• 为每个模块手动创建 <module>_model.go
• 实现 Insert, FindOne, Update, Delete, FindList
• 定义 ErrNotFound 用于逻辑层判断

---

五、参考文件结构

backend/
├── model/
│   ├── user_entity.go      # 实体定义
│   └── user_model.go       # CRUD 方法 (手动添加)
├── internal/
│   └── svc/
│       └── servicecontext.go  # GORM 初始化
└── internal/logic/user/
    ├── createuserlogic.go  # 引用 model.Insert
    ├── getuserlogic.go     # 引用 model.FindOne
    └── ...