# Agent Team — Product Requirements Document

**Date**: 2026-03-04
**Status**: Draft

---

## 1. Overview

Agent Team 是一个本地部署的多 agent 协作平台。用户可以创建多个 AI agent，将它们组织成部门群，通过类似群聊的界面协作完成复杂任务。默认支持 DeepSeek，同时支持 Kimi、Ollama 等模型提供商。

用户可以从「人才市场」一键雇佣社区分享的团队模板，也可以将自己的团队（含经验、知识库、skills）打包发布到 GitHub 供他人使用。

---

## 2. 核心概念

### Agent
每个 agent 是一个目录，包含两个 MD 文件：

```
agents/
  legal-director/
    AGENT.md      # 技术配置：provider、model、skills、description
    SOUL.md       # system prompt：角色人格、行为准则
    memory/       # agent 自动沉淀的经验知识
      contracts.md
      cases.md
```

**AGENT.md 格式**：
```yaml
---
name: legal-director
description: 法律总监，负责合同审查、法律风险评估和诉讼策略
provider: deepseek          # deepseek | kimi | ollama | openai（默认 deepseek）
model: deepseek-chat        # 对应 provider 的模型名
api_key_env: DEEPSEEK_API_KEY
skills:
  - pdf-processing
  - web-search
---
```

**SOUL.md 格式**：纯 Markdown，即 system prompt 正文。

**memory/**：agent 每次完成任务后自动更新，下次执行时注入 context，实现经验积累。

### Skill
遵循 [agentskills.io](https://agentskills.io) 开放标准：

```
skills/
  pdf-processing/
    SKILL.md          # YAML frontmatter + 指令
    scripts/          # 可执行脚本（可选）
    references/       # 参考文档（可选）
```

技能三层渐进加载：
1. 启动时加载所有 skill 的 name + description（~100 tokens/skill）
2. agent 激活某 skill 时加载完整 SKILL.md
3. 按需加载 scripts/references 中的文件

### 群（Room）
群是 agent 协作的场所，分两种类型：

| 类型 | 成员构成 | 用途 |
|------|---------|------|
| 部门群 | 用户 + 1个master + N个子agent | 部门内任务协作 |
| Leader 群 | 用户 + 多个部门master | 跨部门大项目协调 |

群数据全部以文件存储，无数据库：
```
rooms/
  legal-dept/
    room.md           # 群配置（成员、类型）
    tasks.md          # 当前 todolist
    history/          # 任务执行历史
      2026-03-04-contract-review.md
    workspace/        # 群产出文件
      合同分析报告.md
```

### Master Agent
每个群有一个 master agent，职责：
1. 接收用户任务，理解意图
2. 感知群内所有成员的能力（系统自动注入成员 description）
3. 拆分任务，生成 tasks.md，分配给合适的子 agent
4. 检查子 agent 的输出，提出修改意见
5. 迭代直到满意，汇总结果给用户

### 团队包（Team Package）
团队是可打包、可分享的完整单元：

```
legal-team/
  team.md             # 团队介绍、作者、标签、版本
  agents/
    legal-director/
      AGENT.md
      SOUL.md
      memory/         # 沉淀的经验（可随团队分享）
  skills/             # 团队专属 skills
    contract-review/
      SKILL.md
  knowledge/          # 知识库
    law-references.md
```

---

## 3. 功能需求

### 3.1 Agent 管理
- 前端提供 MD 编辑器，直接编辑 `AGENT.md` 和 `SOUL.md`
- 保存时后端写入对应目录（`agents/<name>/`）
- 支持创建、编辑、删除 agent
- 不使用传统表单，所有配置通过 MD 文件维护

### 3.2 Skill 管理
- 前端展示已安装的 skills 列表（读取 `skills/` 目录）
- 支持查看 skill 详情（SKILL.md 内容）
- 支持上传/创建新 skill（创建目录 + SKILL.md）
- Skills 全局共享，所有 agent 均可使用

### 3.3 群管理
- 创建部门群：选择 master agent + 添加子 agent 成员
- 创建 Leader 群：选择多个部门 master agent
- 群列表侧边栏实时显示每个群的状态：
  - `pending` — 空闲，等待用户输入
  - `thinking` — Master 正在分析任务、制定计划
  - `working · <agent名> 正在...` — 子 agent 执行中（详细版）
- 每个群独立的消息历史和工作空间

### 3.4 群聊交互
- Discord 风格三栏布局（见第 5 节）
- 用户发送消息 → master 接收并处理
- Master 在群内 @ 子 agent 分配任务
- 子 agent 回复执行结果（流式输出）
- Master 检查结果，必要时要求修改（显示 review 状态）
- 最终 master 汇总回复用户
- 消息区分角色：用户（右对齐蓝色）/ master（金色边框+王冠）/ 子agent（灰色+头像）

### 3.5 Context 管理
每个 agent 的 LLM 调用相互隔离，避免 token 爆炸：
- Master context：用户消息 + 自己的消息 + 子 agent 结果摘要
- 子 agent context：master 分配的任务指令 + 自己的历史回复
- 超出 token 阈值时自动压缩旧消息为摘要
- 任务完成后经验写入 `memory/*.md`，替代历史记录

### 3.6 LLM 支持
每个 agent 独立配置 provider + model，内置 provider 列表：

| Provider | base_url | 默认模型 |
|----------|----------|---------|
| `deepseek`（默认） | `https://api.deepseek.com/v1` | `deepseek-chat` |
| `kimi` | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` |
| `ollama` | `http://localhost:11434/v1` | `qwen2.5` |
| `openai` | `https://api.openai.com/v1` | `gpt-4o` |

所有 provider 均通过 OpenAI 兼容接口调用，`provider` 字段自动映射 base_url，也可手动覆盖。

### 3.7 人才市场
- 页面展示可雇佣的团队列表
- 支持输入 GitHub repo URL（`username/repo`）一键雇佣
- 雇佣流程：git clone → 解压 agents/ + skills/ 到本地 → 自动建群
- 发布流程：将本地团队目录推送到 GitHub，添加 topic `agent-team`
- 社区团队通过 GitHub topic `agent-team` 聚合发现

---

## 4. 前端设计

### 整体布局（Discord 风格三栏）

```
┌──────────┬──────────────────────────────┬────────────────────┐
│          │  法律顾问部门                  │  Members           │
│  群列表  │  ────────────────────────    │  👑 法律总监 thinking│
│          │                              │  ● 合同律师 working  │
│ ● 法律部 │   Master: 我来拆分任务...     │  ● 合规专员 pending  │
│   working│   @合同律师 请起草合同        │  ──────────────────│
│ ○ 研究部 │                              │  Tasks             │
│   pending│   合同律师: 正在起草... ▌    │  ☑ 分析合同风险    │
│          │                              │  ○ 起草修改意见    │
│ ◈ Leader │                              │  ──────────────────│
│   群     │                              │  产物              │
│          │                              │  📄 合同分析.md    │
│          │                              │  📄 风险报告.md    │
│          │                              │                    │
│          │  ┌──────────────────────┐   │  [Skills][History] │
│          │  │ 输入消息...    [发送] │   │  [Workspace]       │
└──────────┴──────────────────────────────┴────────────────────┘
```

### 左侧群列表
- 群名 + 类型图标（部门群 / Leader 群）
- 实时状态 badge

### 中间聊天区
- 流式消息气泡，角色样式区分
- Master 消息带王冠图标，金色边框
- 子 agent 消息带头像（名字首字母）

### 右侧面板
默认展示三个区块：
- **Members** — 成员列表 + 实时状态
- **Tasks** — `tasks.md` 渲染的 todolist
- **产物** — workspace 最新文件列表，可点击预览

底部三个按钮（点击弹出抽屉）：
- `Skills` — 群内可用 skills
- `History` — 任务执行历史（MD 文件列表）
- `Workspace` — 完整工作空间文件树

### Agent / Skill 管理页
- 通过左侧导航切换到管理页
- MD 编辑器（Monaco Editor）直接编辑 AGENT.md / SOUL.md
- Skill 列表 + 详情查看

---

## 5. 技术架构

### 后端（Go）
```
cmd/server/main.go
internal/
  agent/      # agent 配置加载、运行时、memory 管理
  skill/      # skill 发现、metadata 解析、激活
  room/       # 群管理、消息路由、orchestration
  llm/        # OpenAI 兼容客户端封装（provider 映射）
  hub/        # 人才市场：GitHub clone、团队安装
  api/        # HTTP handlers + WebSocket
```

关键依赖：
- `github.com/sashabaranov/go-openai` — LLM 调用
- `github.com/labstack/echo` — HTTP 框架
- `gopkg.in/yaml.v3` — YAML frontmatter 解析

### 前端（React + TypeScript）
```
web/src/
  components/
    Chat/         # 群聊界面（三栏布局）
    Editor/       # Monaco MD 编辑器
    RoomPanel/    # 右侧面板（Members/Tasks/产物）
    Market/       # 人才市场页面
  stores/         # Zustand 状态管理
```

关键依赖：
- React + TypeScript
- shadcn/ui — UI 组件
- Zustand — 状态管理
- Monaco Editor — MD 编辑器
- WebSocket — 实时消息

### 通信协议（WebSocket）
```json
{ "type": "user_message",  "room_id": "legal-dept", "content": "..." }
{ "type": "agent_message", "agent": "legal-director", "role": "master", "content": "...", "streaming": true }
{ "type": "task_assign",   "from": "legal-director", "to": "contract-lawyer", "task": "..." }
{ "type": "review",        "from": "legal-director", "target": "contract-lawyer", "feedback": "..." }
{ "type": "room_status",   "room_id": "legal-dept", "status": "working", "agent": "合同律师", "action": "正在起草合同" }
{ "type": "tasks_update",  "room_id": "legal-dept", "content": "# Tasks\n- [x] ..." }
{ "type": "workspace_file","room_id": "legal-dept", "filename": "合同分析.md", "content": "..." }
```

### 存储（纯文件系统，无数据库）
```
agent-team/
├── agents/           # agent 配置
├── skills/           # 全局 skills
├── rooms/            # 群数据
├── teams/            # 本地团队模板缓存
├── cmd/server/
├── internal/
├── web/
└── go.mod
```

---

## 6. Master Orchestration 流程

```
用户消息
    ↓
Master 收到（context 注入：群成员能力 + memory）
    ↓
Master 分析任务，更新 tasks.md，生成执行计划
    ↓
Master @ 子agent 分配子任务（并行或串行）
    ↓
子 agent 执行（context：任务指令 + 自身 memory）
    ↓
Master review 结果
    ├── 不满意 → 提出 feedback，要求修改 → 回到上一步
    └── 满意 → 汇总结果，写入 workspace，更新 memory，回复用户
```

Master context 注入格式：
```xml
<team_members>
  <member>
    <name>contract-lawyer</name>
    <description>合同律师，专注合同起草、审查和风险识别</description>
  </member>
</team_members>
```

---

## 7. MVP 范围

**包含**：
- Agent 创建/编辑（Monaco MD 编辑器，无表单）
- Skill 展示和加载（agentskills.io 标准）
- 部门群 + Leader 群
- 群实时状态（pending / thinking / working · agent名）
- Discord 风格三栏群聊界面（流式消息）
- 右侧面板：Members + Tasks + 产物 + 抽屉按钮
- Master orchestration（分配 + review 迭代）
- Context 隔离 + token 压缩
- Agent memory 自动沉淀
- DeepSeek（默认）+ Kimi + Ollama + OpenAI
- 人才市场：GitHub 一键雇佣团队
- 团队打包发布（推送 GitHub + topic）

**不包含（后续迭代）**：
- Skill 脚本执行沙箱
- 用户认证
- 消息搜索