# 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）

**适用场景**:
- 快速生成代码片段
- 内联代码补全
- 需要快速决策的开发流程

**安装方式**:
```bash
# 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 的高级功能

**安装方式**:
```bash
# 项目级别（推荐）
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 中的使用**:
```bash
# 自动加载
# 处理 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:
```bash
npm install -g @zeromicro/mcp-zero
```

2. 配置 Claude Desktop:
```json
{
  "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` 工具:
   ```bash
   goctl api go -api user.api -dir .
   ```
4. 生成文件结构:
   ```
   .
   ├── user.api
   ├── etc/
   ├── internal/
   │   ├── handler/
   │   ├── logic/
   │   ├── svc/
   │   └── types/
   └── main.go
   ```
5. 解释生成的代码结构

**高级功能**:
```markdown
# 子代理使用示例
/zero-skills 分析项目架构

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

---

### 场景 3: Cursor/Windsurf 用户

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

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

**优点**:
- IDE 原生体验
- 快速建议 + 深度知识
- 灵活使用

**配置示例**:

`.cursorrules`:
```markdown
<!-- 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](https://github.com/zeromicro/ai-context)** - 工作流层
- **[zero-skills GitHub](https://github.com/zeromicro/zero-skills)** - 知识层
- **[mcp-zero GitHub](https://github.com/zeromicro/mcp-zero)** - 执行层
- **[go-zero 官方文档](https://go-zero.dev)** - 框架文档
- **[Agent Skills 规范](https://agentskills.io/)** - 技能规范

---

## 📝 总结

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

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

---

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

### 概述

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

---

### 一、生成基础代码

```bash
# 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 参数不足

❌ 错误：
```go
db, err := gorm.Open(mysql.Open(dsn))
```

✅ 正确：
```go
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
```

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

❌ 错误：
```go
func (s *ServiceContext) Close() error {
    if s.DB != nil {
        return s.DB.Close() // *gorm.DB 没有 Close 方法
    }
    return nil
}
```

✅ 正确：
```go
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

```go
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`

#### 标准模板

```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
    └── ...
```