openJiuwen agent-core-java 持久化团队(Persistent Team)生命周期解析:从提示词契约到运行时实现
openJiuwen agent-core-java 持久化团队(Persistent Team)生命周期解析:从提示词契约到运行时实现
持久化团队是 openJiuwen agent-core-java 中 AgentTeams 多智能体协作框架的核心生命周期模式之一:团队在完成当前一轮任务后不销毁成员,而是自动进入待命状态,等待用户下发新指令。本文以仓库中的持久化团队提示词模板为主线,结合 AgentTeamPolicy 的模板装配、TeamCompletionHandler 的完成检测与 TeamRuntimeManager 的暂停/销毁分流,完整讲解持久化团队"创建 → 运行 → 收尾 → 待命 → 恢复"的闭环,并与临时团队(Temporary Team)的销毁语义做对比,帮助你在实际项目中正确选择团队生命周期并落地多轮交互场景。
一、模板正文:持久化团队的收尾契约
关联文档 lifecycle_persistent.md(英文版) 是一份注入 Leader 系统提示词的生命周期行为契约,全文如下:
## Team Nature: Persistent Team
This is a persistent team that continues running and awaits new instructions after completing current tasks.
After all tasks are done:
1. Summarize the current round of work results
2. Do not close members or dissolve the team
3. The team will automatically enter standby mode, awaiting new tasks from the user
**Wrap up efficiently**: Use `send_message(to="*")` to broadcast the round summary and standby notice once. Do not address members individually, and do not reply to members' acknowledgements/thanks — avoid pointless back-and-forth courtesies.
仓库同时维护了语义完全对齐的中文版 lifecycle_persistent.md(中文版):
## 团队性质:长期团队
本团队为长期团队,完成当前任务后继续保持运行等待新指令。
完成所有任务后:
1. 汇总当前轮次的工作成果
2. 不要关闭成员或解散团队
3. 团队将自动进入待命状态,等待用户下发新任务
**收尾要高效**:用 `send_message(to="*")` 一次性广播本轮总结与待命通知,不要逐个成员致意,也不要回复成员的致谢/确认消息,避免无意义的来回寒暄。
这份契约定义了持久化团队区别于临时团队的三条核心收尾语义:
- 汇总本轮工作成果:Leader 需要把当前轮次的产出、结论整理成总结;
- 不解散任何成员:既不调用
shutdown_member关闭成员,也不调用clean_team解散团队——成员、任务看板与团队状态全部保留; - 自动进入待命状态:系统在检测到任务全部完成后,会将团队运行态置为 PAUSED,等待用户下一次下发指令。
与之对照,临时团队模板 lifecycle_temporary.md(英文版) 则要求收尾时"汇总成果 → 用 shutdown_member 关闭所有成员 → 用 clean_team 解散团队",两者在收尾动作上形成鲜明的生命周期分叉。
二、模板如何进入系统提示词:装配机制与选择逻辑
持久化团队模板不是由 LLM 直接读取的独立文档,而是由框架在构建系统提示词时按条件注入的 lifecycle_section。装配入口在 AgentTeamPolicy.java 的 buildTeamPolicy 方法中:
String lifecycleSection = "";
if (builder.role == TeamRole.LEADER) {
String lifecycleName =
Objects.equals(builder.lifecycle, "persistent") ? "lifecycle_persistent" : "lifecycle_temporary";
lifecycleSection = loadTemplate(lifecycleName, language);
}
这里有两个关键设计(对应 AgentTeamPolicy.java#L128-L133):
- 仅 Leader 消费生命周期模板:
lifecycle是否等于字符串"persistent"只影响 Leader 的系统提示词。Teammate 的 system prompt 中{{lifecycle_section}}为空,因为收尾动作(广播总结、关闭/保留成员、解散/待命)完全由 Leader 主导执行。 - 二选一的映射关系:
lifecycle == "persistent"时加载lifecycle_persistent,否则(包括默认值)加载lifecycle_temporary。字符串匹配采用精确的Objects.equals,因此"Persistent"这类大小写变体不会被识别为持久化团队。
装配的壳模板是语言无关的 system_prompt.md:
{{member_name_section}}{{role_policy}}{{workflow_section}}{{lifecycle_section}}
{{persona_label}}: {{persona}}{{team_info_section}}{{team_members_section}}{{base_prompt_section}}
{{lifecycle_section}} 由生命周期模板正文填充,{{workflow_section}} 则由 leader_workflow.md / leader_workflow_predefined.md / leader_workflow_hybrid.md 按 teamMode 注入。关于模板目录的组织规则、占位符语义与双装配路径,prompts/CLAUDE.md 有完整的说明:生命周期模板属于"语言相关模板",必须 cn/ 与 en/ 成对存在;所有语义变更需要同时同步两种语言文件,且模板正文只认 {{placeholder}} 双花括号占位符。
三、配置入口:如何创建一个持久化团队
在 Java 侧,团队由 LeaderTeammateAgentTeam 的 Builder 构建。生命周期通过 lifecycle(String) 配置,且默认值是临时团队:
private String lifecycle = LIFECYCLE_TEMPORARY; // 默认 "temporary"
常量定义见 LeaderTeammateAgentTeam.java#L69-L81:
public static final String LIFECYCLE_TEMPORARY = "temporary";
public static final String LIFECYCLE_PERSISTENT = "persistent";
一个典型的持久化团队构建示例(示意,参照 AgentTeamE2eExampleSupport.java 的构建方式):
LeaderTeammateAgentTeam team = LeaderTeammateAgentTeam.builder()
.teamName("research-team")
.description("多轮研究协作团队")
.lifecycle(LeaderTeammateAgentTeam.LIFECYCLE_PERSISTENT) // 关键:持久化
.spawnMode(LeaderTeammateAgentTeam.SPAWN_MODE_INPROCESS)
.storage(LeaderTeammateAgentTeam.STORAGE_SQLITE)
.build();
// 启动一轮任务并消费流式输出
Iterator<Object> chunks = team.stream(Map.of("input", "第一轮任务"), session);
构建完成后,团队规格中的 lifecycle 字段被持久化为 "persistent",并在运行时被多个模块读取(详见后文)。Builder 在 build() 时会自动生成 Leader 成员规格,并将团队模式解析为 default / predefined / hybrid 之一(见 LeaderTeammateAgentTeam.java#L711-L734)。
四、运行时状态机:CREATED → RUNNING → PAUSED
持久化团队的运行状态由枚举 TeamLifecycle.java 描述,共四个状态:
public enum TeamLifecycle {
CREATED, // 构建完成、尚未启动
RUNNING, // 正在执行当前轮次任务
PAUSED, // 本轮完成、待命等待新指令
COMPLETED // 团队生命周期结束(如已被解散)
}
测试 TeamLifecycleCompatibilityTest.java 验证了关键的状态迁移前提:
persistentTeam_lifecycleIsCreatedBeforeStart:持久化团队TeamAgentSpec构建后,上下文生命周期为CREATED,启动后迁移到RUNNING;temporaryTeam_defaultLifecycle:未显式配置lifecycle时,TeamAgentSpec.getLifecycle()默认返回"temporary";persistentTeam_memberReadyToReadyIsValid:持久化模式下成员状态允许READY → READY自转换——成员在待命期间保持就绪状态而不退出,这正是持久化团队"成员不关闭"语义在状态机层的体现。
五、完成检测与自动待命:TeamCompletionHandler 与 TeamRuntimeManager 的分工
持久化团队"任务全部完成后自动进入待命状态"并非提示词的自欺,而是由协调内核在运行时强制执行。核心链路分为两步。
5.1 完成检测:TeamCompletionHandler
TeamCompletionHandler.java 在 Leader 空闲的 POLL_TASK 轮询节拍上评估团队完成条件。其 onPollTask 方法(TeamCompletionHandler.java#L109-L143)逻辑如下:
- 仅当角色是 LEADER 且当前没有进行中的轮次/Agent 在跑时才评估;
- 调用
TeamBackend.isTeamCompleted()获取完成快照TeamCompletionSnapshot(包含成员数、任务数、是否已删除); - 采用上升沿守卫(
isTeamCompletedEmitted字段),保证每个完成周期只发射一次TEAM_COMPLETED事件,避免轮询节拍反复触发; - 关键分叉:若团队生命周期为
"persistent"且团队未被删除,则调用lifecycle.concludeCompletedRound(memberCount, taskCount)关闭 Leader 流;临时团队则不做此操作,而是由 Leader 按照提示词调用clean_team自行拆除。
该方法上方的类注释(TeamCompletionHandler.java#L29-L52)解释了为何选择在轮询节拍而非成员状态事件上评估:协调内核的自过滤会丢弃 Leader 自身的成员状态变更事件,Leader 无法感知自己的 settle,周期性的空闲节拍是可靠的 Leader-idle 钩子。
5.2 流关闭与运行时暂停:TeamLifecycleController 与 TeamRuntimeManager
concludeCompletedRound 定义在 TeamLifecycleController.java 中:
public interface TeamLifecycleController {
void shutdownSelf(); // 团队被解散时,非 Leader 成员放弃自己的循环
void concludeCompletedRound(int memberCount, int taskCount); // 结束已完成持久化团队的 Leader 流
}
其作用正如接口注释所述:发出团队完成标记块后关闭 Leader 流,使 Runner 的 finalize 阶段可以暂停持久化团队(而 shutdownSelf 则用于团队被解散时让成员退出循环——这对应临时团队的销毁路径)。
随后,TeamRuntimeManager.java 的 finalizeRoundLocked 方法(TeamRuntimeManager.java#L76-L92)根据生命周期做出运行时分流:
if (isPersistent(current.getAgent())) {
pauseRuntime(current.getAgent(), activation.teamName(), activation.sessionId());
current.setState(RuntimeState.PAUSED);
Loggers.AGENT.info("finalize: pausing persistent team {} session {}",
activation.teamName(), activation.sessionId());
return;
}
stopRuntime(current.getAgent(), activation.teamName(), activation.sessionId());
entries.remove(activation.teamName(), current);
Loggers.AGENT.info("finalize: stopping temporary team {} session {}",
activation.teamName(), activation.sessionId());
其中 isPersistent 的判断依据就是规格中的生命周期字段(TeamRuntimeManager.java#L191-L193):
private static boolean isPersistent(TeamAgent agent) {
return "persistent".equalsIgnoreCase(agent.getSpec().getLifecycle());
}
结果对比一目了然:
| 生命周期 | 完成后动作 | 运行时状态 | 成员与数据 |
|---|---|---|---|
persistent |
暂停(pauseRuntime + CoordinationManager.pause) |
RuntimeState.PAUSED |
成员、任务、看板全部保留 |
temporary |
停止(stopRuntime)并注销运行时条目 |
从注册表移除 | 由 Leader 按提示词用 shutdown_member + clean_team 拆除 |
六、高效收尾语义:为什么广播用 send_message(to="*")
模板中特别强调"用 send_message(to="*") 一次性广播本轮总结与待命通知,不要逐个成员致意,也不要回复成员的致谢/确认消息"。这与 send_message 工具的实际语义紧密相关。工具说明 send_message.md 明确规定:
to="*"是广播:发布到团队频道,每个成员都可见,适合全局决策、约束变更或必须所有人知晓的公告;- 广播开销与团队规模线性增长:一条消息行 + 每个目标一条事件,因此只用于全体公告;
- 覆盖所有人的 multicast 被禁止:当收件人恰好覆盖除自己外的所有成员时,工具会直接拒绝,强制使用
"*"——因为全员 multicast 只是更昂贵的广播; - Teammate 的纯文本输出对其他 Agent 和用户不可见,必须通过
send_message通信;而 Leader 的纯文本输出直接展示给用户,所以 Leader 回复用户不需要该工具。
由此可以理解收尾模板的设计动机:收尾场景的听众是"所有成员 + 用户",天然匹配广播语义;逐个成员单播在消息量和事件数上呈线性放大,而回复成员的致谢又会产生一轮毫无信息量的往返消息,拖慢团队进入待命状态。因此"一次广播、不做寒暄"既是提示词层面的效率约定,也与工具的计费语义(消息行 × 目标数)完全一致。
七、多轮交互闭环:待命之后如何接收新指令
持久化团队的核心价值是支持多轮任务复用同一支团队。待命(PAUSED)之后,通过 LeaderTeammateAgentTeam 的对外 API 恢复执行:
stream(Map<String, Object> inputs, Object session):以流式方式驱动一轮团队执行,接收输入并返回输出块迭代器(LeaderTeammateAgentTeam.java#L389-L391);resumeForNewSession(String sessionId):为团队切换/恢复到一个新会话,继续复用同一批成员与任务看板(LeaderTeammateAgentTeam.java#L400-L403);recoverForExistingSession(String sessionId)与recoverTeam():从已有会话或崩溃现场恢复团队;interact(String message)/deliverInput(String content)/broadcast(String content)/dispatchTask(String query):团队级交互入口;destroyTeam(boolean isForceEnabled):显式销毁团队——持久化团队虽然默认不销毁,但应用层在业务结束后仍可主动调用它回收资源(LeaderTeammateAgentTeam.java#L442-L456)。
在 TeamRuntimeManager.java 内部,恢复逻辑由 reactivate 实现(TeamRuntimeManager.java#L155-L166):若团队处于 ACTIVE 则拒绝重复激活;若处于 PAUSED 且会话相同,则重置为 ACTIVE 并记录 RESUME_FROM_PAUSE 激活动作;若会话不同则走 switchSession 重建 Agent 并注册新会话。
一个典型的多轮交互闭环为:
build(持久化团队) → stream(第一轮任务) → 自动检测完成 → concludeCompletedRound
→ finalizeRound 置 PAUSED → 用户下发第二轮任务 → stream(第二轮任务) → ...
→ 业务结束 → destroyTeam(显式回收)
八、与临时团队的选择建议
综合模板契约、运行时行为与工具语义,两种生命周期的适用场景可以归纳为:
- 持久化团队(
lifecycle("persistent")):适合需要保持上下文与成员协作关系、跨轮次持续服务的场景,例如长期运营的客服团队、持续迭代的研发小组、需要复用任务看板和成员经验的多次任务。代价是需要应用层在业务终局时主动destroyTeam回收资源。 - 临时团队(默认
temporary):适合一次性任务、用完即毁的场景,例如单次问答、一次性代码评审。Leader 按 lifecycle_temporary.md 的指引,先shutdown_member逐个关闭成员(等待成员真正进入SHUTDOWN状态,必要时以force=true兜底,见 shutdown_member.md),再调用clean_team级联删除团队、成员与任务记录(任何成员未处于SHUTDOWN时clean_team会失败,见 clean_team.md)。
最后提醒两个容易踩坑的细节:一是生命周期字符串在模板装配处是大小写敏感的精确匹配("persistent"),但运行时 isPersistent 使用 equalsIgnoreCase,两处判断口径不完全一致,配置时统一使用 LeaderTeammateAgentTeam.LIFECYCLE_PERSISTENT 常量最稳妥;二是生命周期模板只对 Leader 生效,不要期望通过修改该模板来约束 Teammate 的收尾行为——Teammate 的行为由 teammate_policy.md 定义,分层设计详见 prompts/CLAUDE.md 的 Prompt Layering 约定。