249 lines
5.8 KiB
Markdown
249 lines
5.8 KiB
Markdown
# 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)
|
||
```bash
|
||
# 运行
|
||
go run cmd/server/main.go
|
||
|
||
# 构建
|
||
go build ./...
|
||
|
||
# 测试（当前无测试文件）
|
||
go test ./...
|
||
```
|
||
|
||
### 前端 (React)
|
||
```bash
|
||
# 安装依赖
|
||
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
|
||
```
|
||
|
||
### 环境变量
|
||
```bash
|
||
# 后端需要
|
||
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 顺序**（标准库 → 第三方）
|
||
```go
|
||
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 顺序**
|
||
```typescript
|
||
// 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 消息格式
|
||
```typescript
|
||
// 客户端发送
|
||
{ 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. 关键设计原则
|
||
|
||
1. **一切皆 MD** — agent 配置、soul、memory、tasks、history 全部是 Markdown 文件
|
||
2. **Context 隔离** — 每个 agent 的 LLM 调用独立，master 只看摘要，子 agent 只看自己的任务
|
||
3. **agentskills.io 标准** — skill 格式遵循开放标准
|
||
4. **OpenAI 兼容接口** — 所有 provider 统一用 go-openai，只改 BaseURL
|
||
5. **纯文件系统存储** — 无数据库，rooms/agents/skills 直接读写磁盘
|
||
|
||
---
|
||
|
||
## 6. 已知限制
|
||
|
||
- 当前 **无测试文件**，如有添加测试的需求，建议使用:
|
||
- Go: `testing` 标准库
|
||
- React: Vitest + React Testing Library
|
||
- 前端暂无单元测试覆盖
|
||
|
||
---
|
||
|
||
## 7. 常用操作示例
|
||
|
||
### 创建新 agent
|
||
1. 在 `agents/<name>/` 创建目录
|
||
2. 添加 `AGENT.md` (YAML frontmatter + 内容)
|
||
3. 添加 `SOUL.md` (system prompt)
|
||
4. 重启后端服务
|
||
|
||
### 添加新 skill
|
||
1. 在 `skills/<name>/` 创建目录
|
||
2. 添加 `SKILL.md` (agentskills.io 格式)
|
||
3. 前端自动通过 API 加载
|
||
|
||
### 调试前端
|
||
```bash
|
||
cd web
|
||
npm run dev
|
||
# 访问 http://localhost:5173
|
||
```
|
||
|
||
### 调试后端
|
||
```bash
|
||
DEEPSEEK_API_KEY=xxx go run cmd/server/main.go
|
||
# API: http://localhost:8080/api
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 相关文档
|
||
|
||
- [PRD.md](./docs/plans/PRD.md) — 完整产品需求
|
||
- [plan.md](./docs/plans/plan.md) — 开发进度与待办事项
|
||
- [README.md](./README.md) — 项目简介
|