deepseek-multi-agent-plugin

多智能体协同插件：定义一支 Agent 团队（DeepSeek / OpenAI 兼容 LLM、HTTP 服务、外部 CLI 命令或纯 Python 逻辑）， 再用内置的协作策略（广播、流水线、辩论、主管-下属、共识投票）让它们一起完成任务。

A multi-agent collaboration plugin for the DeepSeek ecosystem: define a team of agents (DeepSeek/OpenAI-compatible LLMs, HTTP services, external CLI commands or plain Python handlers) and run them together with built-in collaboration strategies: broadcast, sequential, debate, supervisor, consensus and relay.

📚 详细使用文档：使用指南 · 策略详解 · API 参考 · HTTP 接口 · MCP 服务器 · 部署指南 · 示例代码

特性 / Features

• 6 种开箱即用的协作策略：广播讨论、顺序流水线（chain-of-agents）、多轮辩论（含裁判）、主管-下属（任务分解与并行执行）、提案-投票共识、接力迭代（草稿打磨）。
• 灵活的 Agent 定义：mock / echo / http / deepseek / openai / custom / cli 七种后端，LLM 调用仅依赖标准库（OpenAI 兼容 /chat/completions 协议）。
• 共享对话记忆：所有策略共享一个线程安全的 MessageStore，每个 Agent 都能看到讨论全程；辩论上下文带发言人标签（[agent]: ...），LLM 能分清谁说了什么。
• 会话隔离：事件可携带 session_id，每个会话获得独立的 Agent 注册表与对话记忆，并发任务互不污染。
• 健壮的并行执行：每个阶段的超时与异常都按 Agent 捕获，不会让单个 Agent 拖垮整个协作；超时不再阻塞等待慢 Agent；LLM 调用对 429/5xx 与网络抖动自动指数退避重试。
• Token 用量统计与结构化输出：按 Agent 累计 usage（prompt/completion/total tokens，汇总进 meta.usage）；Agent.chat() 支持 response_format（如 JSON 模式）透传。
• 上下文压缩 / 响应缓存 / Token 计量：ContextPolicy 支持历史窗口、逐条截断、辩论中隐藏己方旧发言（默认关闭，不改变既有行为）；进程内线程安全 LRU 响应缓存（--cache）；meta.usage 汇总为 total / agents / cache_hits。
• 可观测性：每次协作自动生成 Trace（span 记录每个 Agent 调用的耗时/状态/错误，task 记录策略步骤），meta.run_id 可在 HTTP /runs/{id} 与 MCP runs 工具中回查；/status 汇总各 Agent 的成功/超时/错误计数与健康度。
• HTTP 服务鉴权：--token（或环境变量 DS_AGENT_TOKEN）启用 Authorization: Bearer <token> 校验；请求体大小 / Content-Type / prompt 校验与并发限流。
• 四种使用方式：Python API、命令行（deepseek-multi-agent）、HTTP 适配服务（可对接 DeepSeek Harness 等外部系统）、MCP stdio 服务（供 DSH / Codex / Claude 等 MCP 宿主调用）。
• 零运行时依赖（可选安装 PyYAML 以支持 YAML 配置），测试与 CI 完整。

架构 / Architecture

                      +-----------------------------+
                      |   AgentCoordinator          |
                      |   - agent registry          |
                      |   - shared MessageStore     |
                      |   - strategy dispatch       |
                      +-------------+---------------+
                                    |
              +---------------------+----------------------+
              |                    |                       |
      +-------v--------+  +--------v--------+   +---------v---------+
      |  strategies    |  |  Agent          |   |  DeepseekAdapter  |
      |  broadcast     |  |  - handler      |   |  HTTP /run events |
      |  sequential    |  |  - provider     |   |  CLI / server     |
      |  debate        |  |  - role/system  |   +---------+---------+
      |  supervisor    |  |  - memory       |             |
      |  consensus     |  +--------+--------+             |
      +-------+--------+           |                      |
              |                    |                      |
              v                    v                      v
        shared memory      DeepSeek/OpenAI HTTP      JSON over HTTP
                          or any callable backend   (harness integration)

快速开始 / Quickstart

# 安装（无需任何运行时依赖）
pip install deepseek-multi-agent-plugin
# 或从 Git 安装固定版本：pip install git+https://github.com/Li3NGa/deepseek-multi-agent-plugin@v1.0.0

# 用两个内置 mock Agent 跑一场辩论，无需 API Key
deepseek-multi-agent run --demo --strategy debate --rounds 2 \
  --prompt "AI 安全当前最重要的问题是什么？"

# 完整 JSON 输出
deepseek-multi-agent run --demo --strategy consensus --json --prompt "帮我选个技术栈"

# 使用 YAML 配置的 DeepSeek 团队（需要 DEEPSEEK_API_KEY）
deepseek-multi-agent run --config example_config.yaml --strategy supervisor \
  --prompt "为校园社团设计一个招新方案"

# 启动 HTTP 适配服务
deepseek-multi-agent serve --config example_config.yaml --port 8000

协作策略 / Collaboration strategies

策略名也可用 auto：1 个 Agent 时自动选 broadcast，存在名为 supervisor 的 Agent 时选 supervisor，否则选 debate。

定义 Agent / Defining agents

LLM Agent 还支持 role、system_prompt、model、temperature、max_tokens、base_url 等参数。

配置文件 / Configuration

example_config.yaml（本项目根目录）演示了一个由 DeepSeek 支撑的三人辩论团队：

coordinator:
  strategy: debate
  rounds: 3
  timeout_seconds: 30
agents:
  - name: researcher
    kind: deepseek
    role: 研究员
    system_prompt: 你是一名严谨的研究员，擅长收集信息并给出有依据的分析。
    model: deepseek-chat
    temperature: 0.3
  - name: critic
    kind: deepseek
    role: 批评家
    system_prompt: 你是一名挑剔的批评家，善于发现方案中的漏洞与风险。
    model: deepseek-chat
    temperature: 0.7
  - name: judge
    kind: deepseek
    role: 裁判
    system_prompt: 你是一名公正的裁判，会综合各方观点给出最终结论。
    model: deepseek-chat
    temperature: 0.2

Python API

from deepseek_multi_agent_plugin import AgentCoordinator, AgentFactory

# 组建团队
coord = AgentCoordinator()
coord.register_agent(AgentFactory.create_agent('deepseek', 'researcher',
    system_prompt='你是一名严谨的研究员'))
coord.register_agent(AgentFactory.create_agent('deepseek', 'critic',
    system_prompt='你是一名挑剔的批评家'))

# 跑一场 2 轮辩论
result = coord.run("AI 安全最重要的问题是什么？", strategy="debate", rounds=2)
print(result["final"])        # 裁判的最终结论
print(result["rounds"])       # 完整过程记录

# 或从配置文件构建
from deepseek_multi_agent_plugin import build_coordinator
coord = build_coordinator(path="example_config.yaml")

HTTP 适配服务 / HTTP adapter

python -m deepseek_multi_agent_plugin.adapter_server --port 8000 --demo
# 或：deepseek-plugin-runner --port 8000 --demo

curl -s localhost:8000/health
# {"status": "ok"}

curl -s -X POST localhost:8000/run -H "Content-Type: application/json" -d \
  '{"type": "run", "prompt": "你好", "strategy": "debate", "rounds": 1}'

# 会话隔离：携带 session_id 的事件路由到该会话独立的注册表与记忆
curl -s -X POST localhost:8000/run -H "Content-Type: application/json" -d \
  '{"type": "run", "prompt": "你好", "strategy": "debate", "rounds": 1, "session_id": "task-42"}'

curl -s localhost:8000/agents
curl -s -X POST localhost:8000/register -H "Content-Type: application/json" -d \
  '{"type": "register", "agents": [{"name": "w1", "kind": "echo"}]}'

# 启用鉴权（--token 或环境变量 DS_AGENT_TOKEN）后，请求需携带
# -H "Authorization: Bearer <token>"，否则返回 401

与 DeepSeek Harness 集成 / Integration with the DeepSeek Harness

DeepseekAdapter.handle_harness_event(event) 把外部事件翻译成协调器调用：

from deepseek_multi_agent_plugin import AgentCoordinator, DeepseekAdapter, build_coordinator

coord = build_coordinator(path="example_config.yaml")
adapter = DeepseekAdapter(coord)
result = adapter.handle_harness_event({
    "type": "run",
    "prompt": "设计一个插件架构",
    "strategy": "supervisor",
    "rounds": 3,
})

支持的事件类型：run、agents、status、register。HTTP 适配服务即基于此接口实现， 因此任何能发起 HTTP 请求的系统（包括 DeepSeek Harness 的工作流）都可以直接调用本插件。

文档 / Documentation

详细使用说明都在 docs/ 目录，从 使用指南 开始：

Docker 部署 / Docker deployment

docker compose up -d --build

镜像通过 HOST、PORT、CONFIG、DEEPSEEK_API_KEY、DS_AGENT_TOKEN 环境变量配置，健康检查与完整部署说明见 docs/deployment.md。

MCP 集成 / MCP integration

python -m deepseek_multi_agent_plugin.mcp_server --config example_config.yaml

通过 stdio JSON-RPC 把 run / agents / register / status 四个工具暴露给 DSH、Codex、Claude Code 等 MCP 宿主，让其他 agent 直接驱动本插件的多智能体协作， 详见 docs/mcp.md。

可直接运行的示例代码在 examples/：

开发与测试 / Development

pip install -e .[dev]
pytest -q

GitHub Actions CI 会在 Python 3.10 / 3.11 / 3.12 上运行全部测试。

License

MIT License. See LICENSE.