@PostMapping(value = "/chat/stream", produces = "text/event-stream")
public SseEmitter chatStream(@RequestBody @Valid AgentChatRequest request) {
    String modelRef = normalizeAndValidateModelRef(request.getModelRef());
    String sessionId = SessionId.of(CallerSourceEnum.WEB, request.getSessionId()).value();
    return agentChatService.chatStreamWithMetrics(
            request.getMessage(), sessionId, request.getPromptTemplateName(), request.getDeviceId(), modelRef);
}

Flux<Event> events = agent.stream(userMsg, STREAM_OPTIONS)
        .contextWrite(ctx -> writeAgentContext(ctx, resolved))
        .doOnNext(event -> { /* 累积输出文本 */ })
        .doOnComplete(() -> {
            AgentChatMetrics metrics = buildMetrics(resolved.getChatUsageRef().get(),
                    resolved.getChatUsageTurns(), System.currentTimeMillis() - start, modelName);
            resolved.getMetricsRef().set(metrics);
        });
return new AgentChatStream(traceId, events);

<modules>
    <module>promo-smart-agent-api</module>       <!-- 对外 DTO/接口，无业务 -->
    <module>promo-smart-agent-core</module>      <!-- 核心：Agent/Cron/Session/业务 -->
    <module>promo-smart-agent-interfaces</module> <!-- HTTP/飞书/A2A 接入，打包入口 -->
</modules>

/**
 * Agent 对话 Service
 * <p>封装流式推送和同步调用逻辑，与 HTTP 层解耦。
 * 所有方法均接收 promptTemplateName，透传至 AgentSessionManager 以确保模板切换运行时生效。</p>
 */
@Slf4j @Service @RequiredArgsConstructor
public class AgentChatService {

@PostConstruct
public void init() {
    int ttlMinutes = agentProperties.getMainAgent().getCacheTtlMinutes();
    sessionCache = CacheBuilder.newBuilder()
            .expireAfterAccess(ttlMinutes, TimeUnit.MINUTES)
            .build(new CacheLoader<String, ReActAgent>() {
                @Override public ReActAgent load(String cacheKey) {
                    return createAndRestore(cacheKey);   // ← miss 时建 Agent
                }
            });
}

for (String toolAgentRef : props.getToolAgentRefs()) {
    toolAgentRegistry.registerInto(toolAgentRef, session, toolkit);   // 子 Agent → 工具
}
AgentBuildUtils.registerMcpClients(props.getMcpServers(), toolkit, COMPONENT_NAME, mcpRegistry);
for (AgentConfigCustomizer customizer : customizers) {
    customizer.registerTools(toolkit, context);   // 编码扩展点
}
ReActAgent.Builder builder = ReActAgent.builder()
        .name(props.getName()).sysPrompt(sysPrompt).model(model)
        .toolkit(toolkit).memory(memory).maxIters(props.getMaxIters())
        .hooks(List.of(new McpToolLoggingHook(), new ChatUsageCollectorHook()));
return builder.build();

@Data @Component
@ConfigurationProperties(prefix = "agentscope")
public class AgentProperties {
    private List<ModelProperties> models = ...;
    private List<SessionProperties> sessions = ...;
    private List<MemoryProperties> memories = ...;
    private MainAgentProperties mainAgent;
    private List<ToolAgentProperties> toolAgents = ...;
}

@PostConstruct
public void init() {
    List<ModelProperties> configs = allModelConfigs();
    for (ModelProperties props : configs) {
        Model model = buildModel(props);
        models.put(props.getName(), model);
        if (props.isDefaultModel()) {
            if (defaultModel != null) {
                throw new IllegalStateException("... multiple models marked as default=true");
            }
            defaultModel = model;
            defaultModelName = props.getName();
        }
    }
}

public void registerInto(String name, Session session, Toolkit toolkit) {
    ToolAgentEntry entry = getEntry(name);
    Model model = modelRegistry.get(entry.props.getModel());
    SubAgentConfig subAgentConfig = SubAgentConfig.builder()
            .toolName(entry.props.getName())
            .description(enhanceDescription(...))
            .session(session)
            .forwardEvents(entry.props.isForwardEvents())
            .build();
    toolkit.registration()
            .subAgent(() -> { /* 用配置里 sysPrompt/model/skills build 出 ReActAgent */ }, subAgentConfig)
            .apply();
}

public enum CallerSourceEnum {
    WEB("web", "Web端", false),
    FEISHU("feishu", "飞书", false),
    FEISHU_GROUP("feishu_group", "飞书群", true),
    CRON("cron", "定时任务", false),
    A2A("a2a", "A2A Agent间调用", false);
    private final String code; private final String desc; private final boolean group;

public static SessionId of(CallerSourceEnum source, String... parts) {
    String raw = String.join("_", parts);
    for (CallerSourceEnum existing : CallerSourceEnum.values()) {
        if (raw.startsWith(existing.getCode() + DELIMITER)) {   // 已带前缀就复用（幂等）
            return new SessionId(raw, existing);
        }
    }
    return new SessionId(source.getCode() + DELIMITER + raw, source);
}

public void saveState(String sessionId, String promptTemplateName, String modelRef) {
    String cacheKey = buildTemplateCacheKey(sessionId, resolved.resolvedName, modelRef);
    ReActAgent agent = sessionCache.getIfPresent(cacheKey);   // L1
    if (agent == null) return;
    Memory memory = agent.getMemory();
    if (memory != null) {
        memory.saveTo(mainSession, sessionId);                // → L2 Session 持久化
    }
}

EventDispatcher dispatcher = EventDispatcher.newBuilder("", "")
    .onP2MessageReceiveV1(new ImService.P2MessageReceiveV1Handler() {
        @Override public void handle(P2MessageReceiveV1 event) {
            feishuMessageHandler.handle(event, botCode);   // ← 消息进入主链路
        }
    }).build();
Client wsClient = new Client.Builder(appId, bot.getAppSecret()).eventHandler(dispatcher).build();
wsClient.start();   // 主动 outbound 连接飞书，无需公网 URL

@Slf4j @Component
public class CronBundleTool implements BundleTool {
    @Override public String name() { return "bundle-cron"; }
    @Override public List<CallerSourceEnum> channels() {
        return List.of(CallerSourceEnum.FEISHU, CallerSourceEnum.FEISHU_GROUP, CallerSourceEnum.CRON);
    }
    @Tool(description = "Create a scheduled task. taskName...; cronExpr: cron expression ...")
    public CronResult cronCreate(AgentContext ctx, @ToolParam(name = "taskName") String taskName /*...*/) {
        // ...
    }
}

for (CronTaskPO task : tasks) {
    String idempotencyRedisKey = IDEMPOTENCY_KEY_PREFIX + task.getId() + ":" + idempotencyKey;
    Boolean acquired = stringRedisTemplate.opsForValue()
            .setIfAbsent(idempotencyRedisKey, "1", Duration.ofMinutes(2));
    if (!Boolean.TRUE.equals(acquired)) continue;   // 锁已存在 → 跳过
    cronTaskExecutor.submitTask(task, CronTriggerType.SCHEDULED);
}

public <T extends HookEvent> Mono<T> onEvent(T event) {
    if (!(event instanceof PostReasoningEvent reasoningEvent)) return Mono.just(event);
    ChatUsage usage = reasoningEvent.getReasoningMessage() != null
            ? reasoningEvent.getReasoningMessage().getChatUsage() : null;
    if (usage == null) return Mono.just(event);
    return Mono.deferContextual(ctxView -> {
        if (ctxView.hasKey(USAGE_REF_KEY)) {                 // 上层注入的 ref
            AtomicReference<ChatUsage> ref = ctxView.get(USAGE_REF_KEY);
            ref.accumulateAndGet(usage, ChatUsageCollectorHook::accumulate);   // 累加总量
        }
        return Mono.just(event);
    });
}

// CronTaskServiceImpl.java:261
private void verifyOwnership(String operatorId, CronTaskPO task) {
    if (task == null) throw new BizException(ErrorCode.TASK_NOT_FOUND);
    if (!operatorId.equals(ownerId)) throw new BizException(ErrorCode.TASK_NOT_FOUND);
}
private void verifyActive(CronTaskPO task) {
    if (task.getTaskStatus() != CronTaskStatus.ACTIVE.getCode()) throw new BizException(ErrorCode.TASK_EXPIRED);
}

// AgentChatService.java:285
} catch (Exception e) {
    log.error("[AgentChatService] Agent 调用异常, sessionId={}", sessionId, e);
    try { emitter.send(SseEmitter.event().data("[ERROR] " + userFacingErrorMessage(e))); }
    catch (IOException ignored) { }
    emitter.completeWithError(e);
}