ooderAgent：什么才算「真 Agent」

/** L1 传输端口：所有方法不得抛异常，失败一律返回 false 或记日志，由上层决定降级 */
public interface MqttTransportPort {
    boolean connect(String brokerUrl, String clientId, String user, String pwd);
    boolean publish(String topic, String payload);
    boolean subscribe(String topicFilter);
    void addHandler(BiConsumer<String, String> handler);
    void disconnect();
}

public class A2AMessage {
    private String messageId;        // 幂等键
    private String conversationId;   // 归属会话
    private String sceneGroupId;     // 组播分组
    private String fromAgentId;
    private String toAgentId;        // 执行体：谁干
    private String targetNodeId;     // 目标节点：发给谁（与 toAgentId 语义分离）
    private A2AMessageType messageType;  // TASK_REQUEST / TASK_RESPONSE / DATA_REQUEST ...
    private Object payload;
    private Map<String, Object> headers; // headers.requestId 用于请求-响应关联
}

// 定向：只投递到目标节点的收件箱
mqttTransport.subscribe(MqttEventTransport.targetedTopic(localNodeId));   // ooder/node/{nodeId}/inbox
// 组播：按场景组广播
mqttTransport.publish("ooder/event/A2A/" + group, wrapPayload(message));   // ooder/event/A2A/{group}

String targetNodeId = resolveTargetNodeId(message);   // 显式 targetNodeId → 目录 nodeId
if (targetNodeId == null || targetNodeId.isEmpty()) {
    log.warn("[A2A-MQTT] 定向投递跳过：无法解析目标节点（agent={}）", message.getToAgentId());
    return false;
}

@Override
public void registerHandler(String agentId, A2AMessageHandler handler) {
    if (agentId == null || agentId.isEmpty() || handler == null) return;
    handlers.put(agentId, handler);
    if (routeAgent != null) {
        try { routeAgent.registerAgent(agentId, null, handler); }
        catch (Exception e) { log.warn("[A2A] 路由登记失败（handler 已注册，非致命）", e); }
    }
}

@Bean
public ApplicationListener<ApplicationReadyEvent> a2aReadyRefresh(
        ObjectProvider<A2AProtocolService> ps, ObjectProvider<AgentDirectoryPort> dir,
        A2AMessageRouter router) {
    return evt -> {
        A2AProtocolService svc = ps.getIfAvailable();
        if (svc != null) svc.refreshHandlersFromDirectory();          // 注册执行端
        AgentDirectoryPort d = dir.getIfAvailable();
        if (d != null) d.listAgents().forEach(router::registerAgent); // 填充 capability/role 索引
    };
}

public class AgentDescriptor {
    private String agentId;      // 身份（Agent Card: identity）
    private String name;
    private String role;         // 角色路由
    private String sceneGroupId; // 场景范围（组织归属）
    private String nodeId;       // 触达地址（Agent Card: endpoint 的最小形态）
    private boolean online;      // 生命周期 / 在线
    private List<String> capabilities;  // Agent Card: skills / capabilities
}

public interface AgentDirectoryPort {
    List<AgentDescriptor> listAgents();
    AgentDescriptor find(String agentId);
    boolean isOnline(String agentId);
}

@PostMapping("/agents")               // 注册：agentId + 场景 + 角色 + 能力 + nodeId
@GetMapping("/agents")                // 列举：同时返回“协议层视角”（目录端口）与场景目录计数
@DeleteMapping("/agents/{agentId}")   // 注销：目录 + 协议栈 handler + 名册 三者同步
@PostMapping("/dispatch")             // 派发：toAgentId / targetNodeId / messageType / payload

acm.unregisterAgent(agentId);
a2aProtocolService.unregisterHandler(agentId);  // 停止消费
rosterStore.remove(agentId);                    // 移出持久化名册

public enum HumanOperation {
    DELEGATE_H2H("DELEGATE_H2H", "委托他人", true, "ri-user-shared-line"),
    DELEGATE_H2A("DELEGATE_H2A", "委托Agent", true, "ri-robot-line"),
    DELEGATE_H2T("DELEGATE_H2T", "委托Task",  true, "ri-task-line"),
    INTERVENE_EXCEPTION("INTERVENE_EXCEPTION", "例外介入", false, "ri-error-warning-line");
    // 第三个参数 = 是否要求 DESIGNER 定义（不在 operations 白名单内即拒绝执行）
}

// POST /api/studio/chat/human-op
// {operation:"DELEGATE_H2A", activityId, processInstId, delegateContext:{targetId}}
{
  "h2aDispatch": {
    "dispatched": true,
    "agentId": "fin.voucher",
    "executor": "UnifiedCollaborationService.createCollaborationTask(AGENT)",
    "todoId": "todo-...-58c5",
    "remoteTaskId": "A2A-561f476bf5a8409b"
  }
}

switch (effective) {
    case ESCALATE_HUMAN:                       // 不放行 + 发布升级人工信号
        log.warn("[BuildConfirmManager] 用户交互超时（{}s），升级人工（不放行）", timeoutSeconds);
        signalEscalation(entry, "confirm_timeout");
        return false;
    case AUTO_CONFIRM: return true;            // 显式列举，新增枚举值不会被静默当作放行
    default:           return true;
}

// 面板依据流程定义声明的操作白名单渲染，未声明即不出现（责任边界由 DESIGNER 决定）
const opOrder = ['DELEGATE_H2H', 'DELEGATE_H2A', 'DELEGATE_H2T'];
const visible = declaredOperations.filter(
  op => opOrder.includes(op) || baseOps.includes(op)
);

// GET /api/studio/a2a/agents
{
  "viaDirectoryPort": [
    { "agentId": "fin.voucher", "name": "凭证导入 Agent", "role": "voucher",
      "sceneGroupId": "voucher-fill-scene", "nodeId": "studio-8104",
      "online": true, "capabilities": ["voucher.import", "voucher.fill"] }
  ],
  "viaDirectoryPortCount": 1,
  "sceneDirectoryCount": 1
}