# 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) — 项目简介