agent-team/docs/plans/PRD.md

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 格式：

---
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 开放标准：

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）

{ "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 注入格式：

<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 脚本执行沙箱
• 用户认证
• 消息搜索