Agent Team System

01系统概述

构建一套基于 Go 的多 Agent 协作框架，模拟"私人工作团队"的运作方式：

• Max — Team Lead（私人助理）：面向用户对话，负责需求理解、任务拆解、方案确认、进度追踪
• Worker Agent（专项员工）：Leo（码农）、Ada（架构师）、Ray（测试）、Sam（运维），各自拥有独立工具集
• 星型通信拓扑：Worker 之间不直接通信，全部通过 Team Lead 中转

设计原则

02系统架构

03核心模块

04Agent 角色定义

05任务生命周期

5.1 状态机

5.2 任务 DAG

Max 将用户需求拆解为多个 Task 节点，通过 DependsOn 字段声明依赖关系，形成 DAG：

Task{ID: "T1", Agent: "Ada",  Desc: "设计接口方案"}
Task{ID: "T2", Agent: "Leo",  Desc: "实现代码",   DependsOn: ["T1"]}
Task{ID: "T3", Agent: "Ray",  Desc: "编写测试",   DependsOn: ["T2"]}
Task{ID: "T4", Agent: "Leo",  Desc: "修复测试失败", DependsOn: ["T3"]}  // 条件触发

5.3 调度规则

• 无依赖的任务并行派发
• 有依赖的任务等上游 Done 后自动触发
• 上游产出物（Artifact）自动注入下游任务上下文
• 任务失败时 Max 决策：重试 / 跳过 / 上报用户

06通信机制

6.1 拓扑：星型

6.2 消息类型

6.3 实现方式

// 中心消息总线
type MessageBus struct {
    inbox    chan Message           // 所有消息汇聚于此
    subs     map[string]chan Message // agentID → 该 agent 的收件箱
}

// 发送消息
func (b *MessageBus) Send(msg Message) {
    b.subs[msg.To] <- msg
}

// Agent 监听自己的收件箱
func (a *Agent) listen() {
    for msg := range a.inbox {
        a.handleMessage(msg)
    }
}

07Tool & MCP 集成

7.1 Tool 接口

type Tool interface {
    Name() string
    Description() string
    Parameters() json.RawMessage    // JSON Schema
    Execute(ctx context.Context, params json.RawMessage) (ToolResult, error)
}

type ToolResult struct {
    Content  string
    IsError  bool
}

7.2 内置工具清单

7.3 Skill 层

Skill 是 Tool 之上的可复用工作流模板，由 Prompt 模板 + 工具子集 + I/O 契约 组成。Agent 激活 skill 后，按专用 prompt 和受限工具集执行，产出结构化结果。

type Skill struct {
    Name          string           // "code_review" / "bug_triage"
    Description   string
    Prompt        string           // 针对该 skill 的专用 prompt 模板
    RequiredTools []string         // 需要的工具列表
    InputSchema   json.RawMessage  // 输入参数 JSON Schema
    OutputSchema  json.RawMessage  // 输出结构 JSON Schema
    Timeout       time.Duration
}

type SkillRegistry struct {
    skills map[string]*Skill
}

func (r *SkillRegistry) Load(path string) error          // 从 YAML 加载
func (r *SkillRegistry) ForAgent(agent *Agent) []*Skill   // 返回 agent 可用的 skill
func (r *SkillRegistry) Get(name string) *Skill           // 按名称查找

7.5 MCP 集成

每个 Agent 可独立连接自己的 MCP Server，通过标准 MCP 协议（JSON-RPC over stdio）通信：

type MCPServer struct {
    Name    string
    Command string              // e.g. "npx @anthropic/gitnexus-mcp"
    Args    []string
    Env     map[string]string
}

type MCPClient struct {
    proc    *exec.Cmd
    stdin   io.WriteCloser
    stdout  *bufio.Reader
    tools   []Tool              // 通过 tools/list 动态发现
}

// Agent 初始化时连接 MCP
func (a *Agent) initMCP() {
    for _, srv := range a.config.MCPServers {
        client := NewMCPClient(srv)
        client.Connect()
        // MCP 发现的工具自动合并到 agent 工具集
        a.tools = append(a.tools, client.Tools()...)
    }
}

7.6 Tool 权限矩阵

08安全与权限模型

AllowedCommands: [
  "go build", "go test", "go vet",
  "git diff", "git status", "git log",
  "grep", "find", "wc"
]

09核心接口定义（Go）

9.1 Agent 接口

type Agent interface {
    // 基础信息
    ID() string
    Role() AgentRole

    // 生命周期
    Start(ctx context.Context) error
    Stop() error

    // 任务处理
    HandleTask(task *Task) (*TaskResult, error)

    // 消息处理
    HandleMessage(msg Message) error
}

type AgentRole string

const (
    RoleMax AgentRole = "max"    // Team Lead
    RoleLeo AgentRole = "leo"    // Coder
    RoleAda AgentRole = "ada"    // Architect
    RoleRay AgentRole = "ray"    // Tester
    RoleSam AgentRole = "sam"    // Ops
)

9.2 Task 定义

type Task struct {
    ID          string
    Type        AgentRole          // 应该由哪种角色处理
    Title       string
    Description string
    DependsOn   []string           // 前置任务 ID
    Artifacts   []Artifact         // 上游产出物
    Status      TaskStatus
    AssignedTo  string             // Agent ID
    Result      *TaskResult
    CreatedAt   time.Time
    UpdatedAt   time.Time
}

type TaskStatus int

const (
    TaskCreated    TaskStatus = iota
    TaskPlanned                       // 已纳入 DAG
    TaskApproved                      // 用户确认通过
    TaskDispatched                    // 已分配给 Agent
    TaskRunning                       // Agent 执行中
    TaskDone                          // 执行完成
    TaskFailed                        // 执行失败
)

type Artifact struct {
    Name    string                // "design_doc" / "code_diff" / "test_report"
    Type    string                // "text" / "file" / "json"
    Content string
}

9.3 AgentConfig

type AgentConfig struct {
    Role         AgentRole
    SystemPrompt string
    Model        string             // "claude-opus-4-7" / "claude-sonnet-4-6" / "claude-haiku-4-5"
    Tools        []Tool
    MCPServers   []MCPServerConfig
    Constraints  AgentConstraints
}

type AgentConstraints struct {
    AllowedDirs     []string        // 可访问的目录
    AllowedCommands []string        // shell 白名单
    MaxTokens       int             // 单次调用最大 token
    Timeout         time.Duration   // 任务超时时间
}

9.4 Skill Engine

type SkillEngine struct {
    registry *SkillRegistry
}

// 激活 skill：注入 prompt、限制工具集、执行、校验输出
func (e *SkillEngine) Execute(ctx context.Context, agent *Agent, skillName string, input json.RawMessage) (*SkillResult, error)

type SkillResult struct {
    SkillName string
    Output    json.RawMessage   // 符合 OutputSchema 的结构化结果
    ToolCalls []ToolCallRecord  // 执行过程中的工具调用记录
    Usage     TokenUsage
}

9.5 LLM Router

type LLMRouter interface {
    Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
}

type ChatRequest struct {
    Model    string
    Messages []Message
    Tools    []ToolDefinition
    System   string
}

type ChatResponse struct {
    Content   string
    ToolCalls []ToolCall
    Usage     TokenUsage
}

9.6 Scheduler

type Scheduler struct {
    tasks    map[string]*Task
    agents   map[AgentRole]*Agent
    bus      *MessageBus
    gate     *ApprovalGate
}

func (s *Scheduler) Submit(dag *TaskDAG) error     // 提交任务 DAG
func (s *Scheduler) OnTaskDone(taskID string) error // 任务完成回调，触发下游
func (s *Scheduler) GetStatus() *DAGStatus          // 获取整体进度

10典型工作流

场景 A：新功能开发

场景 B：Bug 排查与修复

场景 C：代码重构

11技术选型

12后续规划

Phase 1 — MVP 优先

• 实现 Agent Runtime + Scheduler + MessageBus
• 实现 Max + Leo 两个 Agent
• 内置基础工具（read_file / write_file / run_shell）
• CLI 交互界面
• 基本的 Approval Gate

Phase 2 — 完善

• 增加 Ada / Ray / Sam Agent
• MCP 集成
• Skill 引擎 + 内置 Skill（code_review / bug_triage / test_coverage_analysis）
• 任务 DAG 可视化
• 审计日志

Phase 3 — 增强

• Web UI
• 多项目/多工作区支持
• Agent 记忆与学习（跨会话持久化）
• 自定义 Agent 类型（通过配置文件）
• 自定义 Skill（用户通过 YAML 定义私有 skill）
• 成本监控（token 用量统计）