sdaduanbilei/agent-team

Fork 0

sdaduanbilei 9e279a0627 fix

2026-03-05 17:34:49 +08:00

5.8 KiB

Raw Permalink Blame History

AGENTS.md — Agent Team 开发指南

本文档为在此代码库中工作的 AI agent 提供开发规范和操作指南。

1. 项目概述

Agent Team 是一个本地部署的多 agent 协作平台。用户创建 AI agent 团队，通过类似 Discord 的群聊界面协作完成复杂任务。

技术栈

后端: Go + Echo + go-openai
前端: React 19 + TypeScript + Tailwind v4 + Zustand + Monaco Editor
存储: 纯文件系统（无数据库）

目录结构

agent-team/
├── agents/           # agent 配置目录
│   └── <name>/
│       ├── AGENT.md  # YAML frontmatter 配置
│       ├── SOUL.md   # system prompt
│       └── memory/   # 经验沉淀
├── skills/           # 全局 skills (agentskills.io 标准)
├── rooms/            # 群数据
├── cmd/server/       # Go 后端入口
├── internal/         # 核心逻辑
│   ├── agent/        # agent 加载、memory 管理
│   ├── skill/       # skill 发现、加载
│   ├── room/         # 群 orchestration
│   ├── llm/          # OpenAI 兼容客户端
│   ├── hub/          # GitHub 人才市场
│   └── api/          # HTTP + WebSocket
└── web/              # React 前端
    └── src/
        ├── components/
        ├── store.ts
        └── types.ts

2. 构建与运行命令

后端 (Go)

# 运行
go run cmd/server/main.go

# 构建
go build ./...

# 测试（当前无测试文件）
go test ./...

前端 (React)

# 安装依赖
cd web && npm install

# 开发服务器
npm run dev

# 生产构建
npm run build

# Lint
npm run lint

# 运行单文件 lint
npx eslint src/components/ChatView.tsx

# TypeScript 检查
npx tsc --noEmit

环境变量

# 后端需要
export DEEPSEEK_API_KEY=your_key
# 或其他 provider: OPENAI_API_KEY, KIMI_API_KEY, OLLAMA_HOST

3. 代码风格规范

Go (后端)

命名约定

包名: 简短小写 (如 agent, room, llm)
结构体: PascalCase (如 Agent, Config, Room)
变量/函数: camelCase (如 Load, SaveMemory, client)
常量: 混合大小写，根据作用域决定

错误处理

使用 fmt.Errorf("context: %w", err) 包装错误
避免裸 panic()，返回 error
WebSocket 错误记录日志但不中断服务

Import 顺序（标准库 → 第三方）

import (
    "bytes"
    "context"
    "fmt"
    "os"
    "path/filepath"
    "strings"

    "github.com/sdaduanbilei/agent-team/internal/llm"
    "gopkg.in/yaml.v3"
)

YAML Frontmatter 解析

AGENT.md 使用 --- 包裹 YAML 配置
使用 gopkg.in/yaml.v3 解析

React/TypeScript (前端)

命名约定

组件文件: PascalCase (如 ChatView.tsx, RoomSidebar.tsx)
工具文件: camelCase (如 store.ts, utils.ts)
类型文件: PascalCase (如 types.ts)

Import 顺序

// React/库
import { create } from 'zustand'
import React from 'react'

// 类型
import type { Room, Message, AgentInfo } from './types'

// 组件
import ChatView from './components/ChatView'

// 样式/资源
import './App.css'

类型定义 (web/src/types.ts)

使用 TypeScript 原生类型
优先使用 type 而非 interface（简单对象）
使用 export type 联合类型

组件规范

函数式组件，React 19
事件处理使用箭头函数或 useCallback
避免内联对象作为 props

状态管理 (Zustand)

单一 store (store.ts)
使用 set() 和 get() 操作状态
异步操作使用 async/await

Tailwind CSS

使用 v4 语法 (无需配置文件)
工具类优先
自定义样式使用 @theme 块

ESLint 配置 (web/eslint.config.js)

@eslint/js
typescript-eslint
react-hooks
react-refresh

4. API 与通信

REST API 前缀

/api/rooms          # 群列表
/api/rooms/:id      # 群详情
/api/agents         # agent 列表
/api/skills         # skill 列表
/api/hub            # 人才市场

WebSocket 消息格式

// 客户端发送
{ type: 'user_message', content: '...', room_id: '...' }

// 服务端推送
{ type: 'agent_message', agent: '...', role: 'master'|'member', content: '...', streaming: true }
{ type: 'room_status', status: 'pending'|'thinking'|'working', active_agent?: '...', action?: '...' }
{ type: 'tasks_update', content: '# Tasks\n- [x] ...' }
{ type: 'workspace_file', filename: '...' }

5. 关键设计原则

一切皆 MD — agent 配置、soul、memory、tasks、history 全部是 Markdown 文件
Context 隔离 — 每个 agent 的 LLM 调用独立，master 只看摘要，子 agent 只看自己的任务
agentskills.io 标准 — skill 格式遵循开放标准
OpenAI 兼容接口 — 所有 provider 统一用 go-openai，只改 BaseURL
纯文件系统存储 — 无数据库，rooms/agents/skills 直接读写磁盘

6. 已知限制

当前 无测试文件，如有添加测试的需求，建议使用:
- Go: testing 标准库
- React: Vitest + React Testing Library
前端暂无单元测试覆盖

7. 常用操作示例

创建新 agent

在 agents/<name>/ 创建目录
添加 AGENT.md (YAML frontmatter + 内容)
添加 SOUL.md (system prompt)
重启后端服务

添加新 skill

在 skills/<name>/ 创建目录
添加 SKILL.md (agentskills.io 格式)
前端自动通过 API 加载

调试前端

cd web
npm run dev
# 访问 http://localhost:5173

调试后端

DEEPSEEK_API_KEY=xxx go run cmd/server/main.go
# API: http://localhost:8080/api

8. 相关文档

PRD.md — 完整产品需求
plan.md — 开发进度与待办事项
README.md — 项目简介

5.8 KiB Raw Permalink Blame History Unescape Escape