详细使用说明（Usage Guide）

August 20, 2026 · View on GitHub

本指南介绍如何完整使用 deepseek-multi-agent-plugin：从安装、配置 Agent 团队，到用命令行 / Python API / HTTP 服务 / MCP stdio 服务四种方式运行多智能体协作任务，再到接入真实 LLM（DeepSeek、OpenAI 或任意兼容端点）。

相关文档：

协作策略详解 — 6 种策略的流程、参数与选型

Python API 参考 — 全部类与函数的签名说明

HTTP 服务接口 — 四个端点的请求/响应协议

依赖	用途	安装方式
PyYAML	加载 `.yaml` / `.yml` 配置文件	`pip install pyyaml`
pytest	运行测试	`pip install pytest`

2. 快速开始（30 秒上手）

不需要任何 API Key，用两个内置演示 Agent 跑一场辩论：

deepseek-multi-agent run --demo --strategy debate --rounds 2 \
  --prompt "AI 安全当前最重要的问题是什么？"

输出会依次展示：每轮各 Agent 的观点、裁判的最终结论。加 --json 可输出完整结构化结果：

deepseek-multi-agent run --demo --strategy consensus --json --prompt "帮我选个技术栈"

--demo 注册了两个 mock Agent（alpha、beta），适合先跑通流程、理解策略行为。

3. 配置 Agent 团队

团队配置可以写在一个 YAML 或 JSON 文件里，命令行、Python API、HTTP 服务都能复用。

3.1 YAML 示例

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

3.2 Agent 字段说明

字段	必填	说明
`name`	是	唯一标识，出现在所有记录与内存中
`kind`	否	`mock` / `echo` / `http` / `deepseek` / `openai` / `custom` / `cli` / `fallback`；省略时若提供 `handler` 则视为 `custom`，否则为 `mock`
`role`	否	角色描述（自由文本，仅作元信息）
`system_prompt`	否	系统提示词，每次 LLM 调用都会前置
`model`	否	模型名，如 `deepseek-chat`、`deepseek-reasoner`、`gpt-4o-mini`
`temperature`	否	采样温度 0–2
`max_tokens`	否	最大生成 token 数
`capabilities`	否	逗号分隔的能力标签（如 `research,analysis`）；supervisor 按能力为任务路由 agent，见第 4 节
`api_key`	否	显式 API Key；缺省读环境变量（见第 8 节）
`base_url`	否	覆盖默认 API 地址（可指向任何 OpenAI 兼容端点）
`retries`	否	429/5xx/连接错误的指数退避重试次数（默认 2，尊重 `Retry-After`）
`cache`	否	`true` 时启用进程内 LLM 响应缓存（LRU + TTL）
`timeout`	否	单次 LLM 调用超时（秒，默认 60）；cli agent 的子进程超时（秒，默认 300）
`message_template`	mock 用	模板字符串，支持 `{msg}` 与 `{name}` 占位符
`url`	http 用	接收 `{"message": ...}` JSON 的端点地址
`handler`	custom 用	Python 可调用对象（仅代码中可用，YAML 无法序列化）
`backends`	fallback 用	后备 agent 列表，按顺序尝试，首个成功者生效（仅代码中可用）
`command`	cli 用	可执行文件路径或 PATH 中的命令名（必填）
`args`	cli 用	传给命令的参数列表（默认 `[]`，不含消息本身）
`cwd`	cli 用	子进程工作目录（可选）
`encoding`	cli 用	stdout/stderr 解码编码（默认 `utf-8`）

3.3 运行配置

coordinator 段只提供默认值，运行时（CLI 参数 / HTTP 请求字段 / run() 关键字）可以覆盖：

字段	默认	说明
`strategy`	`auto`	协作策略，见 strategies.md
`rounds`	3	轮数（broadcast/debate 使用）
`timeout_seconds`	15	每个并行阶段的总超时（秒）
`budget`	—	每次 run 的默认预算，见第 6.6 节

3.4 上下文压缩与效率开关

上下文压缩默认全部关闭；不配置任何开关时，行为与旧版本完全一致。配置放在 coordinator.context 下，或通过 CLI 的 --context-window / --context-max-chars 临时开启：

coordinator:
  context:
    window: 6          # 可选：只保留最近 6 条历史消息（原始 prompt 始终保留、不截断）
    max_chars: 2000    # 可选：每条历史消息保留前 2000 个字符并追加省略号 "…"
    hide_own: false    # 可选：辩论中辩手看不到自己之前的旧发言
  cache: false         # 可选：启用进程内 LLM 响应缓存

ContextPolicy 字段：

字段	默认	说明
`window`	`None`	历史窗口，只保留最近 N 条历史消息；原始 prompt 永远保留在首位且不被窗口丢弃
`max_chars`	`None`	逐条截断，每条历史消息保留前 N 个字符并追加省略号 `…`
`hide_own_statements`	`False`	辩论中过滤辩手自己之前的 assistant 发言（按 agent 名识别）

各策略的瘦身点（仅压缩输入，final 结论永不截断）：

策略	瘦身点
`broadcast`	`rounds>1` 时回喂消息按 `max_chars` 截断，prompt 前缀保留
`sequential`	传给下一棒的 transcript 按 `max_chars` 截断，prompt 前缀保留
`debate`	每轮按策略为每位辩手生成定制 context（窗口/截断/隐藏己方旧发言）；裁判输入截断
`supervisor`	report 步骤的工人结果汇总按 `max_chars` 截断
`consensus`	投票候选 ballot 按 `max_chars` 截断
`relay`	传给下一棒的草稿按 `max_chars` 截断

CLI 开关示例：

# 保留最近 2 条历史、每条历史消息截断到 50 字符，并输出 usage 摘要
deepseek-multi-agent run --demo --strategy debate --rounds 2 \
  --context-window 2 --context-max-chars 50 --usage \
  --prompt "AI 安全当前最重要的问题是什么？"

# 启用进程内响应缓存（线程安全 LRU，默认 128 条）
deepseek-multi-agent run --demo --strategy debate --rounds 2 --cache \
  --prompt "帮我选个技术栈"

--usage 在非 JSON 模式下会于 == FINAL == 之后打印 meta.usage 摘要（total / agents / cache_hits）；JSON 模式下 meta.usage 直接包含在结果中。 LLM 响应缓存命中时不发起 HTTP 请求，usage 标记为 cache_hit，对应 meta.usage.cache_hits 计数增加。mock / echo / http / cli / custom agent 不参与缓存。

4. 六种协作策略速览

策略	中文名	一句话说明	适用场景
`broadcast`	广播讨论	所有 Agent 并行回答，`rounds>1` 时把上轮汇总回喂	头脑风暴、平行观点收集
`sequential`	顺序流水线	按指定顺序逐个发言，每人看到完整历史	分析→设计→实现→评审的流水线
`debate`	多轮辩论	先辩 N 轮，再由裁判综合出最终结论	需要对抗与收敛的决策
`supervisor`	主管-下属	主管分解子任务，工人并行执行，主管汇总报告	复杂任务拆解与并行执行
`consensus`	提案-投票	每人提案，全员投票多数胜出，平票由裁判裁决	需要多数共识的选择题
`relay`	接力迭代	按顺序轮流打磨同一份草稿，无改进即提前收敛	初稿→润色→审校的文稿打磨

策略的完整流程、参数与示例输出见协作策略详解。

5. 命令行工具

5.1 `run` — 运行协作任务

deepseek-multi-agent run --prompt "任务描述" [选项]

选项	说明
`--prompt`	任务提示词（必填）
`--strategy`	`auto`（默认）/ `broadcast` / `sequential` / `debate` / `supervisor` / `consensus` / `relay`
`--rounds`	轮数，默认 3
`--judge`	裁判 Agent 名（debate/consensus）
`--order`	逗号分隔的发言顺序（sequential/relay），如 `--order critic,researcher`
`--workers`	逗号分隔的 supervisor 工人 Agent，如 `--workers w1,w2`
`--timeout`	每阶段超时秒数
`--config`	YAML/JSON 配置文件
`--demo`	使用两个内置 mock Agent
`--agents`	逗号分隔的 mock Agent 名，如 `--agents a,b,c`
`--json`	输出完整 JSON（含每轮记录与元信息）

示例：

# 用配置文件里的 DeepSeek 团队跑主管模式
deepseek-multi-agent run --config example_config.yaml --strategy supervisor \
  --prompt "为校园社团设计一个招新方案" --json

# 指定流水线顺序
deepseek-multi-agent run --demo --strategy sequential --order critic,researcher \
  --prompt "评审这个方案"

# 三个 mock Agent 跑共识
deepseek-multi-agent run --agents 产品,研发,运营 --strategy consensus --prompt "Q3 做什么功能？"

5.2 `agents` — 查看团队

deepseek-multi-agent agents --config example_config.yaml
# {"name": "researcher", "role": "研究员", "provider": "deepseek", "model": "deepseek-chat", ...}

deepseek-multi-agent agents --config example_config.yaml --json
# [{"name": "researcher", ...}, {"name": "critic", ...}]

5.3 `serve` — 启动 HTTP 服务

deepseek-multi-agent serve --config example_config.yaml --port 8000
deepseek-plugin-runner --port 8000 --demo        # 等价的旧命令名

接口协议见 HTTP 服务接口。

6. Python API

6.1 最小示例

from deepseek_multi_agent_plugin import AgentCoordinator, AgentFactory

coord = AgentCoordinator()
coord.register_agent(AgentFactory.create_agent('mock', 'a', message_template='A说: {msg}'))
coord.register_agent(AgentFactory.create_agent('mock', 'b', message_template='B说: {msg}'))

result = coord.run("今天中午吃什么？", strategy="debate", rounds=1)
print(result["final"])   # 最终结论
print(result["rounds"])  # 完整过程

6.2 从配置文件构建

from deepseek_multi_agent_plugin import build_coordinator

coord = build_coordinator(path="example_config.yaml")
result = coord.run("设计一个插件架构", strategy="supervisor")

6.3 共享记忆

每次 run 都会把提示词和各 Agent 的发言写入协调器共享的 MessageStore：

print(coord.memory.all())          # 全部消息
print(coord.memory.to_chat())      # 转成 OpenAI chat 格式
coord.memory.clear()               # 清空

6.4 错误与超时

某个 Agent 抛异常：该 Agent 的响应记为 {"error": "..."}，不影响其他 Agent。
并行阶段整体超时：未完成的 Agent 记为 {"error": "timeout"}。
run_timeout：整个 run 的运行级截止时间，到点后未开始的 agent 调用直接取消，不再无限等待（配合预算的 max_seconds 使用效果相同）。
run() 会忽略策略不认识的额外关键字参数（如给 broadcast 传 judge），方便统一调用。

6.5 预算（Budget）

run() 接受 budget 参数（dict 或 BudgetManager），每次 agent 调用前先预留额度，超预算立即中止剩余调用并抛 BudgetExceeded：

result = coord.run("写一份竞品分析", strategy="supervisor",
                   budget={"max_calls": 20, "max_tokens": 100000,
                           "max_cost": 0.5, "max_seconds": 120})
print(result["meta"]["budget"])   # 预算用量快照

字段	说明
`max_calls`	agent 调用次数上限（含在途调用）
`max_tokens`	prompt + completion token 总量上限
`max_cost`	成本上限（按用量估算）
`max_seconds`	run 时长上限，等效于 `run_timeout`

也可以在配置 coordinator.budget 或 AgentCoordinator(budget=...) 设置默认预算，被单次 run(budget=...) 覆盖。预算防止 supervisor 分解、辩论、重试组合时成本失控。

6.6 运行历史（RunHistory）

把每次协作任务的结果摘要持久化为 JSONL，服务重启后仍可查询：

from deepseek_multi_agent_plugin import AgentCoordinator, AgentFactory, DeepseekAdapter, RunHistory

coord = AgentCoordinator()
coord.register_agent(AgentFactory.create_agent('mock', 'a', message_template='A: {msg}'))
history = RunHistory('runs.jsonl')
adapter = DeepseekAdapter(coord, history=history)

adapter.handle_harness_event({'type': 'run', 'prompt': '任务', 'strategy': 'broadcast'})
print(history.recent(5))   # 最近 5 条记录，最新在前

HTTP 与 MCP 服务用 --history FILE 启动即可（见 HTTP 服务接口、 MCP 服务器）。

完整签名与说明见 Python API 参考。

7. HTTP 服务

python -m deepseek_multi_agent_plugin.adapters.http --port 8000 --demo
# 旧路径 python -m deepseek_multi_agent_plugin.adapter_server 仍然可用

curl -s localhost:8000/health
curl -s localhost:8000/agents
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 -X POST localhost:8000/register -H "Content-Type: application/json" -d \
  '{"type": "register", "agents": [{"name": "w1", "kind": "echo"}]}'

服务支持四级角色令牌鉴权（readonly / user / operator / admin）与会话管理（--session-ttl / --max-sessions），协议详见 HTTP 服务接口。

8. 接入真实 LLM

8.1 DeepSeek 官方 API

export DEEPSEEK_API_KEY=sk-xxxxxxxx          # Windows: set DEEPSEEK_API_KEY=sk-xxxxxxxx

# 配置里写 kind: deepseek 即可，模型默认为 deepseek-chat
agents:
  - name: analyst
    kind: deepseek
    model: deepseek-chat
    system_prompt: 你是一名资深分析师。

8.2 OpenAI / 任意兼容端点

export OPENAI_API_KEY=sk-xxxxxxxx

agents:
  - name: assistant
    kind: openai
    model: gpt-4o-mini
  - name: local_llm
    kind: openai
    base_url: http://localhost:8000/v1
    api_key: dummy,                     # 本地服务通常忽略 key
    model: qwen2.5-72b-instruct

提示：kind: deepseek 与 kind: openai 走同一套 OpenAI 兼容协议，区别只是默认地址、默认模型和环境变量名。任何实现 POST /chat/completions 的服务都可以通过 base_url 接入。

8.3 外部 agent CLI 桥接（kind: cli）

任何能读取命令行参数并从 stdout 返回结果的外部程序（codex CLI、任意 CLI 工具）都可以作为团队一员：handler 会执行 command + args + [消息]，按退出码与输出返回内容。

agents:
  - name: codex_worker
    kind: cli
    command: codex
    args: [exec, --skip-git-repo-check]
    timeout: 600

消息会作为最后一个参数追加，适合 codex exec "<prompt>" 这类一次性执行模式；
退出码 0 且 stdout 非空时返回 stdout；stdout 为空则返回 stderr；非 0 退出码或超时会记录为 {"error": ...}，不会中断协作；
command 也可以是 PATH 中的命令名（如 codex），cwd 可指定工作目录。

8.4 代码中直接构造 LLM Agent

from deepseek_multi_agent_plugin import Agent

agent = Agent(
    "coder",
    provider="deepseek",
    system_prompt="你是一名资深 Python 工程师。",
    model="deepseek-chat",
    temperature=0.2,
    api_key="sk-xxx",          # 或省略，读 DEEPSEEK_API_KEY 环境变量
)

8.5 预算与速率提示

辩论 N 轮 × M 个 Agent ≈ M×N 次 LLM 调用，另加 1 次裁判调用；supervisor 为 2 次主管调用 + 工人调用。
每轮辩论都会携带历史上下文，轮数过多时注意 token 消耗；MessageStore 可设 capacity 截断。
组合策略 + 重试容易成本失控，生产环境建议每次 run 带 budget（见 6.5 节）。
provider 失败可用 FallbackAgent 建后备链（primary 失败自动切 backup），见 README Agents 一节。

9. 与 DeepSeek Harness 集成

DeepseekAdapter 把 JSON 事件翻译成协调器调用，HTTP 服务就是它的一个外壳。任何能发 HTTP 请求的系统（包括 Harness 工作流）都可以直接使用：

from deepseek_multi_agent_plugin import AgentCoordinator, DeepseekAdapter

adapter = DeepseekAdapter(AgentCoordinator())
result = adapter.handle_harness_event({
    "type": "run",
    "prompt": "写一份竞品分析",
    "strategy": "supervisor",
    "rounds": 3,
})

支持的事件：run（执行任务）、agents（列出团队）、status（健康状态）、register（动态注册）。事件字段与返回值格式见 HTTP 服务接口中的协议表。

10. 常见问题（FAQ）

Q1：提示 missing API key？

deepseek Agent 需要 DEEPSEEK_API_KEY 环境变量（或配置里的 api_key），openai Agent 需要 OPENAI_API_KEY。用 --demo 或 mock Agent 则不需要任何 key。

Q2：YAML 配置报错 PyYAML is required？

pip install pyyaml

或把配置写成 JSON 文件（标准库即可解析）。

Q3：debate / consensus 报错 needs at least two agents？

这两个策略需要至少 2 个 Agent；单 Agent 请用 broadcast。

Q4：某个 Agent 一直超时？

用 --timeout / timeout_seconds 调大并行阶段超时；单次 LLM 调用超时用 Agent 的 timeout 字段。

Q5：如何清空历史记忆？

coord.memory.clear()

Q6：HTTP 服务怎么暴露到外网？

服务自带 Bearer 令牌鉴权（--token 或分角色 --role，见 HTTP 服务接口第 2 节），但不含 TLS——公网部署请置于反向代理（Nginx/Caddy）之后，或用 mTLS 终结 TLS。

Q7：会话越来越多，内存会涨吗？

启动时设 --session-ttl 900 --max-sessions 100：过期会话惰性清理，容量满时按 LRU 淘汰；GET /sessions 查看统计，POST /sessions/cleanup 强制清理。

11. 相关文档

协作策略详解
Python API 参考
HTTP 服务接口
示例代码：demo_strategies.py（全策略演示，无需 Key）、demo_deepseek_team.py（真实 LLM 团队）、run_http_server.py（HTTP 服务）