AgentSkillsCN

go-agent-development

Go Agent开发指南，涵盖Agent架构设计、心跳机制、任务执行、日志上报、升级流程、与Dispatch模块交互。当用户开发构建机Agent、实现任务执行逻辑、处理Agent通信或进行Go语言开发时使用。

SKILL.md
--- frontmatter
name: go-agent-development
description: Go Agent 开发指南，涵盖 Agent 架构设计、心跳机制、任务执行、日志上报、升级流程、与 Dispatch 模块交互。当用户开发构建机 Agent、实现任务执行逻辑、处理 Agent 通信或进行 Go 语言开发时使用。
core_files:
  - "src/agent/agent/src/pkg/"
  - "src/agent/agent-slim/"
related_skills:
  - dispatch-module-architecture
  - agent-module-architecture
token_estimate: 2500

Go Agent 开发

Quick Reference

code
Go 版本：1.19+
进程组成：DevopsDaemon（守护进程） + DevopsAgent（主进程）
核心包：api/（API 调用）| config/（配置）| job/（任务）| pipeline/（流水线）
日志：logs.Debug/Info/Error/WithError

最简示例

go
// API 调用
func AgentStartup() (*httputil.DevopsResult, error) {
    url := buildUrl("/ms/environment/api/buildAgent/agent/thirdPartyAgent/startup")
    startInfo := &ThirdPartyAgentStartInfo{
        HostName:      systemutil.GetHostName(),
        HostIp:        systemutil.GetAgentIp(),
        DetectOs:      systemutil.GetOsName(),
        MasterVersion: config.AgentVersion,
    }
    return httputil.NewHttpClient().Post(url).Body(startInfo, false).
        SetHeaders(config.GAgentConfig.GetAuthHeaderMap()).Execute(nil).IntoDevopsResult()
}

When to Use

  • •开发构建机 Agent
  • •实现任务执行逻辑
  • •处理 Agent 与后端通信
  • •编写 Go 工具函数

When NOT to Use

  • •后端 Kotlin/Java 开发 → 使用 backend-microservice-development
  • •调度模块业务逻辑 → 使用 dispatch-module-architecture

项目结构

code
src/agent/
├── agent/                 # 主代理
│   └── src/pkg/
│       ├── api/           # API 调用
│       ├── config/        # 配置管理
│       ├── collector/     # 数据采集
│       ├── job/           # 任务执行
│       └── util/          # 工具函数
├── agent-slim/            # 轻量版代理
└── common/                # 通用库

命名规范

go
// 包命名：小写单词，不使用下划线
package api
package config

// 结构体：PascalCase
type ThirdPartyAgentStartInfo struct {
    HostName      string `json:"hostname"`
    HostIp        string `json:"hostIp"`
}

// 常量：驼峰命名
const (
    KeyProjectId     = "devops.project.id"
    KeyAgentId       = "devops.agent.id"
)

// 枚举
type BuildJobType string
const (
    AllBuildType    BuildJobType = "ALL"
    DockerBuildType BuildJobType = "DOCKER"
)

配置管理

go
type AgentConfig struct {
    Gateway           string
    ProjectId         string
    AgentId           string
    SecretKey         string
    ParallelTaskCount int
}

var GAgentConfig *AgentConfig

func GetGateWay() string {
    return GAgentConfig.Gateway
}

错误处理

go
// 标准错误检查
if err != nil {
    logs.WithError(err).Error("agent startup failed")
    return
}

// 重试模式
for {
    _, err = job.AgentStartup()
    if err == nil {
        break
    }
    logs.WithError(err).Error("retry startup")
    time.Sleep(5 * time.Second)
}

// Panic 恢复
defer func() {
    if err := recover(); err != nil {
        logs.Error("panic recovered: ", err)
    }
}()

日志规范

go
logs.Debug("debug message")
logs.Info("info message")
logs.Infof("formatted: %s", data)
logs.Error("error message")
logs.WithError(err).Error("with error context")

并发模式

go
// 启动 goroutine
go collector.Collect()
go cron.CleanJob()

// 使用 defer 清理
defer config.EBus.Unsubscribe(config.IpEvent, eBusId)

// Channel 通信
done := make(chan bool)
go func() {
    // do work
    done <- true
}()
<-done

HTTP 客户端

go
httputil.NewHttpClient().
    Post(url).
    Body(data, false).
    SetHeaders(headers).
    Execute(nil).
    IntoDevopsResult()

Checklist

开发 Agent 功能前确认：

  • • 使用标准错误处理模式
  • • 添加适当的日志记录
  • • goroutine 有 panic 恢复
  • • 网络调用有重试机制
  • • 资源使用 defer 清理