企业官网建设流程全解析

JiuwenSwarm 架构深度剖析：从 Gateway 到 AgentServer 的多智能体系统通信设计全景

【免费下载链接】jiuwenswarmJiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.项目地址: https://gitcode.com/gh_mirrors/ji/jiuwenswarm

JiuwenSwarm 是构建在 openJiuwen 之上的开源 AI Agent 框架，其核心架构采用Gateway（网关）与 AgentServer（智能体服务）双进程拆分设计，通过 WebSocket 与统一 E2A 协议完成多智能体系统通信。本文带你完整看懂这套多智能体系统的通信设计全景。

总览：一套框架，两个进程

JiuwenSwarm 启动入口 jiuwenswarm/app.py 只做一件事：用一条命令拉起两个独立进程——

两个进程共享同一个用户工作区~/.jiuwenswarm，但职责完全解耦：

• AgentServer 专注"思考"：运行 agent、会话、技能、工具，对外只暴露一个 WebSocket 服务端（jiuwenswarm/server/agent_ws_server.py）；
• Gateway 专注"连接"：对接网页、TUI、飞书/钉钉/Telegram 等各类 IM 频道，把消息统一转发给 AgentServer。

💡 这种拆分带来了三个好处：独立扩缩容（AgentServer 可远程部署）、故障隔离（渠道掉线不影响智能体运行）、多实例隔离（通过--dotenv参数支持单机多实例）。

Gateway：多频道消息的流量网关

Gateway 内部由四个核心组件协作，源码位于 jiuwenswarm/gateway/：

1. ChannelManager：频道生命周期管家

jiuwenswarm/gateway/channel_manager/channel_manager.py 负责所有 Channel 的注册、注销与查找，并提供统一的出队派发循环：把 AgentServer 的响应投递回对应的频道。每个频道由ChannelKey（频道类型 + 用户 ID）唯一标识，新增一个 IM 平台只需实现一个 Channel 并注册进来。

2. MessageHandler：消息路由与预处理

jiuwenswarm/gateway/message_handler/message_handler.py 是所有入站消息的中枢：解析斜杠命令、@提及意图、会话归属，并把消息封装后交给 AgentServer 客户端。

3. AgentServerClient：WebSocket 长连接客户端

jiuwenswarm/gateway/routing/agent_client.py 是 Gateway 侧的 WebSocket 客户端，负责：

• 断线重连与连接诊断（ws_diagnostics）
• 流式响应分片接收与非流式请求超时控制
• 消息体大小限制保护（AGENT_WS_MAX_MESSAGE_BYTES）

4. 定时任务与心跳：从被动到主动

• Cron 调度器（jiuwenswarm/gateway/cron/）：解析 cron 表达式、持久化任务，到点后通过 WebSocket 远程触发 AgentServer执行——即使你不在聊天窗口里，智能体也会按时干活；
• 心跳代理（jiuwenswarm/gateway/heartbeat/proxy.py）：维持周期性唤醒，让智能体具备"主动问候/提醒"能力。

AgentServer：智能体运行时与 WebSocket 服务端

AgentServer 进程只做两件事：启动JiuWenSwarm 智能体运行时，以及AgentWebSocketServer。后者（jiuwenswarm/server/agent_ws_server.py）是整套通信设计的关键：

• 接收 Gateway 封装好的请求，路由到对应会话（session map）与 agent；
• 通过流式 chunk把模型输出、工具调用、计划变更等实时推回 Gateway；
• 内置热池（agent_warm_pool）、会话历史管理、断点恢复等运行时能力；
• 通过 hook 机制（AgentServerHookEvents）向扩展开放生命周期事件。

所有运行时能力模块集中在 jiuwenswarm/server/runtime/，包括 agent_adapter、session、skill、mcp、debug_trace 等子目录，职责边界清晰。

E2A 协议：Gateway 与 AgentServer 的通用语言

两个进程之间传输的不是裸 JSON，而是统一的E2A（Everything to Agent）信封协议，模型定义在 jiuwenswarm/common/e2a/models.py：

• E2AEnvelope：请求信封，携带身份来源（用户/系统/智能体）、鉴权信息、文件引用等；
• E2AProvenance：记录消息出处——ACP、A2A 等外部协议进入后都会归一化为 E2A，并记录转换器与转换时间；
• 流式编码：jiuwenswarm/common/e2a/wire_codec.py 定义了响应分片与完整响应的序列化格式。

这个设计的精髓在于**"协议归一"**：无论你是从网页、IM 频道，还是通过 ACP/A2A 协议接入的第三方智能体发起请求，AgentServer 看到的都是同一种 E2A 信封。完整协议约定可参考官方文档 docs/zh/E2A-protocol.md。

Swarm 多智能体团队：声明式装配的通信骨干

JiuwenSwarm 的多智能体能力集中在 jiuwenswarm/agents/swarm/，其设计文档 jiuwenswarm/agents/swarm/DESIGN.md 描述了完整的通信装配链路：

请求 (mode, role, channel, session, config) │ ▼ enrich_team_spec_for_swarm() ← assembly.py：注册 provider、构建上下文 │ ▼ TeamAgentSpec ├─ agents["leader"] : DeepAgentSpec └─ agents["teammate"] : DeepAgentSpec ├─ rails / tools / subagents │ ▼ provider 工厂 build_xxx(params, ctx) ← providers/*.py │ ▼ 运行对象 (Rail / Tool / SubAgentConfig)

三个关键设计原则：

1. 纯声明式装配：团队成员（leader / teammate）的能力全部由RailSpec/BuiltinToolSpec/SubAgentSpec声明，配置即能力；
2. 成员共享配置源：创建团队无需先构建单智能体，leader 与队友直接共享同一份配置源；
3. 跨进程靠 seed 重建：成员 spawn、分布式部署、热恢复时，通过build_context_seed序列化种子 + 本地工厂重建运行上下文——这正是"分布式 Team"能跨机器通信的基础。

AutoHarness 双层架构：能力如何被注入

智能体的"骨架"能力由 AutoHarness 提供双层架构：底层是可复用的 rail/tool/sub-agent 工厂，上层是面向场景的装配层，整体结构见下图（详见 docs/zh/AutoHarness.md）：

开放生态：ACP / A2A 接入第三方智能体

JiuwenSwarm 的 Gateway 不只是消息网关，还是智能体互联的中枢：

• ACP 通道（jiuwenswarm/gateway/channel_manager/protocol/acp/）：通过 stdio 协议桥接外部编码智能体（如 IDE 内智能体），你日常使用的智能体也能被纳入 Swarm 协同；
• A2A 代理（jiuwenswarm/gateway/routing/third_agent.py 与 jiuwenswarm/extensions/agent_client/）：把外部 Agent 注册为团队成员，统一经 E2A 信封与内部团队通信。

小结：这套架构解决了什么问题

如果你想动手实践，可以从 docs/zh/Quickstart.md 开始安装体验，再对照 jiuwenswarm/app.py 的双进程启动逻辑，你会发现"多智能体系统通信"并没有想象中那么神秘——拆分进程、统一协议、声明式装配，就是 JiuwenSwarm 给出的简洁答案。🚀

【免费下载链接】jiuwenswarmJiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.项目地址: https://gitcode.com/gh_mirrors/ji/jiuwenswarm