agentic_huge_data_base / wiki
页面 jcode · 7.1 多智能体角色与会话派生·DeepWiki 中文全文译文
DeepWiki 中文译文 / jcode / 7.1

7.1 · 多智能体角色与会话派生（Swarm Roles and Session Spawning）

代理式研究运行时 · 聚焦本章的模块关系、源码依据与实现要点。

项目jcode 章节7.1 状态全文译文 模块接口与服务契约、界面与交互、智能体运行时、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录jcode DeepWiki 原始章节Swarm Roles and Session Spawning 上一章7 下一章7.2
源码线索
  • src/protocol_tests.rs
  • src/server/client_actions.rs
  • src/server/client_comm.rs
  • src/server/client_lifecycle.rs
  • src/server/client_session.rs
  • src/server/client_state.rs
  • src/server/comm_control.rs
  • src/server/comm_control_tests.rs
  • src/server/comm_control_tests/assign_blocked.rs
  • src/server/comm_control_tests/assign_less_loaded.rs
模块标签
  • 接口与服务契约
  • 界面与交互
  • 智能体运行时
  • 测试、发布与运维
  • 工作流与编排

章节正文

多智能体角色与会话派生

原始 DeepWiki 页面https://deepwiki.com/1jehuang/jcode/7.1-swarm-roles-and-session-spawning

Swarm 角色与会话生成

相关源文件

本章引用的主要源码文件：

  • src/protocol_tests.rs
  • src/server/client_actions.rs
  • src/server/client_comm.rs
  • src/server/client_lifecycle.rs
  • src/server/client_session.rs
  • src/server/client_state.rs
  • src/server/comm_control.rs
  • src/server/comm_control_tests.rs
  • src/server/comm_control_tests/assign_blocked.rs
  • src/server/comm_control_tests/assign_less_loaded.rs
  • src/server/comm_control_tests/assign_ready_agent.rs
  • src/server/comm_control_tests/assign_task.rs
  • src/server/comm_control_tests/await_any.rs
  • src/server/comm_control_tests/await_disconnect.rs
  • src/server/comm_control_tests/await_late_joiners.rs
  • src/server/comm_control_tests/await_reload_deadline.rs
  • src/server/comm_control_tests/await_reload_final.rs
  • src/server/comm_plan.rs
  • src/server/comm_session.rs
  • src/server/comm_sync.rs
  • src/server/debug_session_admin.rs
  • src/server/headless.rs
  • src/server/swarm.rs
  • src/tool/bash_tests.rs
  • src/tool/communicate.rs
  • src/tui/backend.rs

本文档描述了 jcode 集群系统的协调层。内容涵盖：代理如何被分类为不同角色、集群成员的生命周期、有头（UI）和无头（后台）会话的生成机制，以及集群中维护的共享状态。

集群角色

集群基于协调器和代理之间的主要区分来运作。这种层级结构确保计划生成和高级编排是集中式的，而执行则是分布式的。

角色职责
协调器管理 VersionedPlan 的权威会话。它是唯一允许调用 handle_comm_spawn 来创建新代理的角色 src/server/comm_session.rs:27-52。
代理执行单元，接收来自协调器的任务分配。代理通过 update_member_status 向集群报告状态变更 src/server/comm_control.rs:14-15，并可以通过黑板共享上下文 src/server/client_comm.rs:5-7。
SwarmMember 状态机

集群中的每个参与者都通过 SwarmMember 结构体进行跟踪 src/server/client_lifecycle.rs:41-44。status 字段控制代理的可用性，并通过 broadcast_swarm_status 广播给所有成员 src/server/comm_session.rs:8-9。

状态描述
spawned会话已初始化，但客户端进程（TUI 或无头）尚未连接 src/server/comm_session.rs:217-220。
ready会话已连接且空闲，等待任务 src/server/comm_control.rs:42-43。
running代理正在处理提示或执行工具 src/server/comm_session.rs:179-180。
blocked代理正在等待依赖项（例如，另一个代理的输出或计划更新）src/server/comm_control.rs:172-173。
completed分配的任务已成功完成 src/server/comm_control.rs:42-43。
failed代理在执行过程中遇到不可恢复的错误 src/server/comm_session.rs:12-13。
stopped会话通过 handle_comm_stop 手动终止 src/server/comm_session.rs:27。
crashed会话心跳超时或进程意外退出 src/server/client_session.rs:90-93。

来源：src/server/client_lifecycle.rs:41-44, src/server/comm_session.rs:27-220, src/server/comm_control.rs:31-45, src/server/swarm.rs:146-153

会话生成

会话生成由 handle_comm_spawn 处理 src/server/comm_session.rs:27。它通过 SwarmSpawnMode 枚举支持两种不同的模式：有头（可见的 TUI 窗口）和无头（后台代理运行时）src/server/client_lifecycle.rs:67-88。

有头会话（可见）

有头会话通过启动一个新的终端窗口来生成，该窗口以 resume 模式运行 jcode 二进制文件 src/server/comm_session.rs:107-113。

  1. 准备：prepare_visible_spawn_session 创建一个新的 Session 对象，设置工作目录，并将其保存到磁盘 src/server/comm_session.rs:171-211。
  2. 启动：系统使用 spawn_visible_session_window 通过 spawn_resume_in_new_terminal_with_provider 调用平台特定的终端模拟器 src/server/comm_session.rs:89-114。
  3. 启动注入：如果提供了 startup_message，则通过 persist_headed_startup_message 保存 src/server/comm_session.rs:146-152。TUI 客户端在启动时从 client-input- 文件中读取此消息。
无头会话（后台）

无头会话完全在服务器进程内运行，没有 TUI。

  1. 创建：create_headless_session 在内存中初始化一个 Agent src/server/comm_session.rs:9。
  2. 执行：服务器直接调用 process_message_streaming_mpsc，绕过 Unix 套接字协议进行内部消息传递 src/server/comm_session.rs:1。
  3. 通信：无头代理使用内部 MPSC 通道（event_tx）向集群的其他部分发送 ServerEvent 通知 src/server/comm_session.rs:217-230。
会话生成流程

以下图表将新代理的自然语言请求与负责生命周期的代码实体连接起来。

标题：集群生成逻辑流程

jcode · 会话生成流程 · 图 1
jcode · 会话生成流程 · 图 1

来源：src/server/comm_session.rs:1-230, src/server/client_lifecycle.rs:41-88

共享上下文与 VersionedPlan

集群维护一个共享状态，以防止重复工作并确保一致性。

VersionedPlan

VersionedPlan 结构体是集群目标的权威来源，在 swarm_plans 注册表中进行跟踪 src/server/comm_control.rs:58-59。

  • 参与者：一个 HashSet，包含当前计划中涉及的 session_id src/server/comm_control.rs:91-115。
  • 项：一个 PlanItem 列表，每个项通过 assigned_to 分配给特定代理，并通过 SwarmTaskProgress 进行跟踪 src/server/comm_control.rs:95-106。
  • 同步：对计划的任何修改都会触发 broadcast_swarm_plan，该操作将完整的更新状态发送给所有参与者 src/server/comm_control.rs:11-12。
共享上下文（黑板）

shared_context 是一个键值存储，按 swarm_id 进行分区 src/server/client_lifecycle.rs:41。

  • 共享：代理使用 handle_comm_share 将发现或文件内容发布到黑板 src/server/client_comm.rs:6-7。
  • 读取：代理使用 handle_comm_read 检索特定键，或使用 handle_comm_read_context 获取整个上下文历史 src/server/client_comm.rs:6-7, src/server/comm_sync.rs:29-31。
  • 访问控制：协调器和 worktree_manager 角色具有读取完整上下文的更高权限 src/server/comm_sync.rs:100-114。

标题：共享状态数据流

jcode · 共享上下文（黑板） · 图 2
jcode · 共享上下文（黑板） · 图 2

来源：src/server/client_comm.rs:1-9, src/server/comm_control.rs:58-115, src/server/client_lifecycle.rs:41-61

生命周期与清理

当会话结束或服务器重新加载时，集群必须协调其状态。

  • 会话清除：handle_clear_session 从集群和计划参与者中移除旧的 session_id，并用一个新的代理替换它，同时保留调试标志和集群成员身份 src/server/client_session.rs:123-146。
  • 冲突跟踪：服务器跟踪 files_touched_by_session，以检测多个代理是否正在编辑同一个文件 src/server/client_lifecycle.rs:138。
  • 过期任务清理：refresh_swarm_task_staleness 监控 SwarmTaskProgress 的心跳。如果代理在 JCODE_SWARM_TASK_STALE_AFTER_SECS 内未能签到，其任务状态将被移至 running_stale src/server/swarm.rs:165-187。
  • 强制停止：协调器可以使用带有 force: true 参数的 handle_comm_stop 来终止工作会话并移除其中断队列 src/server/comm_session.rs:142-155。

来源：src/server/client_session.rs:123-197, src/server/comm_session.rs:142-205, src/server/swarm.rs:165-187