openJiuwen Core Java 控制器事件流与任务流:com.openjiuwen.core.controller.modules 完全解读

原创2026-10-12 13:49:491,761 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 工作流多智能体工具调用MCP 服务Agent 记忆RAG后端Agent 沙箱

openJiuwen Core Java 控制器事件流与任务流:com.openjiuwen.core.controller.modules 完全解读

导读

com.openjiuwen.core.controller.modules 是 openJiuwen Core Java 版控制器(Controller)的运行时基础设施包,负责将用户的输入事件转化为可调度、可暂停、可取消、可恢复的后台任务,并把任务执行结果以流式事件回写给会话。本文以该包的官方 API 文档为主线,结合仓库源码(modules 包实现、Controller、ControllerConfig)与单元测试,系统讲解事件队列分发、LLM 意图识别、任务存储索引、执行器注册与调度器虚拟线程执行的全链路原理,并给出可直接落地的配置参数与扩展方式。读完本文,你将掌握如何在 openJiuwen 控制器中接入自定义 EventHandler、注册按 taskType 区分的 TaskExecutor,以及理解任务从 SUBMITTED 到终态的生命周期是如何被调度器驱动完成的。

一、两条主线:事件流与任务流

modules.README.md 开宗明义:该子包同时覆盖事件流和任务流两条主线:

  • 事件流:由 EventQueue 负责输入/结果事件的订阅与同步分发,EventHandler 及其默认实现 EventHandlerWithIntentRecognition 负责消费事件;
  • 任务流:由 TaskManager 与 TaskScheduler 负责任务生命周期——存储、索引、状态更新、调度执行。

两者通过 EventQueue.publishEvent() 串接:调度器把任务的完成/交互/失败信号包装成事件重新发布回 EventQueue,事件处理器再把结果写入会话流,从而形成「输入 → 意图 → 任务 → 执行 → 事件回写」的完整闭环。

用户输入(InputEvent)
      │
      ▼
EventQueue.publishEvent() ──同步分发──► EventHandler.handleInput()
                                              │ IntentRecognizer 识别意图
                                              ▼
                                   EventHandlerWithIntentRecognition
                                      按意图创建/暂停/恢复/取消任务
                                              │
                                              ▼
                                     TaskManager.addTask() (SUBMITTED)
                                              │
                                              ▼
                                    TaskScheduler.scheduleLoop()
                               (虚拟线程执行 TaskExecutor)
                                              │
                  ┌───────────────────────────┴───────────────────────────┐
                  ▼                                                       ▼
        updateTaskStatus(COMPLETED/FAILED/INPUT_REQUIRED)         EventQueue.publishEvent()
                  │                                                       │
                  ▼                                                       ▼
         all_tasks_processed 完成信号                               EventHandler 写回会话流

二、EventQueue:基于 topic 的同步事件分发器

2.1 核心机制

EventQueue 是控制器内部的同步事件分发器(源码:EventQueue.java)。它按以下格式生成 topic:

{agentId}_{sessionId}_{eventType}

例如 agent-123_session-456_input。subscribe(String agentId, String sessionId) 会为同一个 agent/session 对一次性订阅五类事件,并把每类事件绑定到 EventHandler 对应的处理方法上(源码中实际订阅的订阅映射见 EventQueue.java#L85-L121):

事件类型 绑定的处理器方法
INPUT eventHandler.handleInput(input)
TASK_INTERACTION eventHandler.handleTaskInteraction(input)
TASK_COMPLETION eventHandler.handleTaskCompletion(input)
TASK_FAILED eventHandler.handleTaskFailed(input)
FOLLOW_UP eventHandler.handleFollowUp(input)

EventQueue 的关键状态包括 config(事件队列配置)、eventHandler(当前控制器绑定的事件处理器)、subscriptions(topic 到 TopicSubscription 的映射,使用 ConcurrentHashMap)以及 running(AtomicBoolean 运行标记)。

2.2 同步分发与错误语义

  • 同步分发保证顺序:publishEvent() 会构造 EventHandlerInput 并同步调用目标订阅处理器,一直阻塞到处理器执行结束,从而保证事件处理顺序(源码见 EventQueue.java#L165-L191)。
  • 无订阅即丢弃:如果找不到 topic 对应的订阅,事件会被丢弃并记录 warning,而不是排队等待。
  • 异常包装:处理器抛出的普通异常会被包装成 AGENT_CONTROLLER_EVENT_HANDLER_ERROR;订阅失败则包装成 AGENT_CONTROLLER_EVENT_QUEUE_ERROR(与文档描述一致,源码见 EventQueue.java#L116-L120)。
  • 异步入口:源码额外提供了 publishEventAsync(),通过 CompletableFuture.runAsync 实现 fire-and-forget 异步分发,作为同步 publishEvent() 的补充。

2.3 生命周期管理

start() 将队列标记为运行状态;stop() 停止队列并清空所有 topic 订阅;unsubscribe(agentId, sessionId) 取消五类事件的订阅;unsubscribeAll() 等价于 stop()。这些方法由上层 Controller.start()/stop()/cleanup() 在会话生命周期中驱动(见 Controller.java#L260-L274)。

三、EventHandler 与 EventHandlerInput:事件处理入口抽象

3.1 EventHandler 抽象基类

EventHandler 是控制器事件处理器的抽象基类(源码:EventHandler.java),定义了四类事件的统一处理接口:

方法 返回 说明
handleInput(EventHandlerInput inputs) Map<String, Object> 处理输入事件
handleTaskInteraction(EventHandlerInput inputs) Map<String, Object> 处理任务交互事件
handleTaskCompletion(EventHandlerInput inputs) Map<String, Object> 处理任务完成事件
handleTaskFailed(EventHandlerInput inputs) Map<String, Object> 处理任务失败事件

依赖注入:基类通过 setter 注入 config(ControllerConfig)、contextEngine(ContextEngine)、abilityManager(业务能力管理器)、taskManager、taskScheduler 五个运行时依赖。Controller.setEventHandler() 会在绑定处理器时完成上述注入,因此业务实现通常不需要自己管理生命周期(见 Controller.java#L146-L153)。

四个 handle* 方法都是抽象方法,具体控制器需要根据自己的任务模型实现事件路由逻辑。基类还提供了默认的 handleFollowUp()(返回 {"status": "not_supported"})、prepareRound()、waitCompletion() 与 onAbort() 等扩展入口。

3.2 EventHandlerInput 不可变入参

EventHandlerInput 是传给事件处理器的不可变入参对象(源码:EventHandlerInput.java),仅包含两个字段:

字段 类型 说明
event Event 当前待处理的控制器事件
session AgentSessionApi 当前会话对象,用于读写流、状态和 sessionId

该类型只有 getter 没有 setter,构造完成后事件和会话引用不再变化。EventQueue.publishEvent() 在同步分发事件前会统一构造该对象并传给处理器(见 EventQueue.java#L176)。

四、意图识别:IntentRecognizer 与 IntentToolkits

4.1 IntentRecognizer:LLM tool calling 驱动的意图解析

IntentRecognizer 负责把 InputEvent 中的用户输入转换为 Intent 列表(源码:IntentRecognizer.java)。其依赖包括:

依赖 类型 作用
config ControllerConfig 提供 intentLlmId、intentConfidenceThreshold 与允许的意图类型列表
taskManager TaskManager 读取当前任务列表并拼接到用户提示中
contextEngine ContextEngine 获取当前会话对应的 ModelContext
abilityManager Object 构造时注入的能力管理器(公开方法不直接使用)
modelProvider ModelProvider 按模型 ID 和会话延迟获取 Model 实例

ModelProvider 是一个函数式接口,只暴露 getModel(String modelId, AgentSessionApi session),作用是解耦 IntentRecognizer 与上层运行器实现(源码见 IntentRecognizer.java#L90-L93)。

recognize(Event event, AgentSessionApi session) 的执行约束与流程:

  1. 事件类型校验:只接受 InputEvent,传入其他 Event 实现直接抛出 IllegalArgumentException。
  2. 输入格式校验:输入数据只允许一条 DataFrame.TextDataFrame;出现文件输入(FileDataFrame)、JSON 输入(JsonDataFrame)或多段文本输入时抛出 AGENT_CONTROLLER_RUNTIME_ERROR。
  3. 上下文组装:从 TaskManager 读取当前任务清单(task id、description、status),与用户输入一起按固定模板格式化为 UserMessage,写入 ModelContext。模型系统提示词为固定的「任务管理助手」角色描述,其核心原则是"任务化一切"——任何用户请求都优先转化为一个任务。
  4. 模型调用:首轮模型调用使用 IntentToolkits.getOpenaiToolSchemas(config.getIntentTypeList()) 限定可用工具;后续补轮调用放开为全部工具定义。上下文读取固定最多取最近 50 条消息。
  5. 工具调用解析:每个 tool call 的参数先解析为 Map<String, Object>,再交给 IntentToolkits.dispatch(...) 生成 Intent 与工具消息;工具消息同样回写到 ModelContext,从而支持多轮工具调用的循环。

模型调用失败、工具参数解析失败和输入格式违规都会被包装成 StatusCode.AGENT_CONTROLLER_RUNTIME_ERROR;如果 ContextEngine 中不存在当前会话的 ModelContext,方法会创建它,若创建失败则要求调用方先创建上下文。

4.2 IntentToolkits:工具 schema 与 Intent 工厂

IntentToolkits(源码:IntentToolkits.java)提供两类能力:向模型暴露 OpenAI 风格的 function tool schema,以及把工具参数转换为结构化的 Intent。构造方法 IntentToolkits(Event event, double confidenceThreshold) 会绑定当前事件对象、记录置信度阈值并立即构建工具 schema 索引。

8 个内置工具与对应意图:

工具名 生成意图 关键参数
create_task CREATE_TASK task_description,生成随机任务 ID
pause_task PAUSE_TASK task_id
cancel_task CANCEL_TASK task_id
resume_task RESUME_TASK task_id
unknown_task UNKNOWN_TASK question_for_user 澄清问题
create_dependent_task CONTINUE_TASK task_description、dependent_task_ids
modify_task MODIFY_TASK task_id、new_task_description
supplement_task SUPPLEMENT_TASK task_id、supplement_info

实现细节与约束:

  • 每个工具 schema 的参数都带 additionalProperties = false,因此 schema 不接受额外字段;必填参数通过 required 数组声明(见 IntentToolkits.java#L286-L304)。
  • 所有公开的意图创建方法都会先检查 confidence:低于阈值时统一回退到 UNKNOWN_TASK 并附带"请澄清是要创建新任务还是修改现有任务"的澄清提示(lowConfidenceIntent(...))。
  • createDependentTask(...) 生成的 Intent 类型是 CONTINUE_TASK,不是独立的 CREATE_DEPENDENT_TASK 枚举项。
  • modifyTask(...) 会创建新的随机 targetTaskId,并把原任务 ID 放入依赖列表,即"修改 = 基于原任务生成新版本任务"。
  • 工具 schema 构建时每个参数都有详细的中英文描述,例如 confidence 定义为 0-1.0 的操作置信度评分。

dispatch(String toolName, Map<String, Object> arguments) 按工具名选择对应创建方法并转换参数;结果以 record IntentResult(Intent intent, String message) 封装——intent 是结构化意图,message 是描述性说明(如"Task ID: xxx, Current Status: Created and submitted for execution"),可写回上下文供模型感知。

4.3 意图类型与任务状态的枚举全貌

意图类型定义于 IntentType.java:CREATE_TASK、PAUSE_TASK、RESUME_TASK、CONTINUE_TASK、SUPPLEMENT_TASK、CANCEL_TASK、MODIFY_TASK、UNKNOWN_TASK。

任务状态定义于 TaskStatus.java:SUBMITTED(已提交待调度)、WORKING(执行中)、PAUSED(已暂停)、INPUT_REQUIRED(等待输入)、COMPLETED(已完成)、CANCELED(已取消)、FAILED(失败)。

五、EventHandlerWithIntentRecognition:默认事件处理器的意图路由

EventHandlerWithIntentRecognition 继承自 EventHandler,是控制器默认的事件处理器实现(源码:EventHandlerWithIntentRecognition.java)。它通过构造方法接收 IntentRecognizer.ModelProvider,并在依赖注入完成后由 initRecognizer() 创建 IntentRecognizer。

5.1 handleInput:多意图并发驱动

handleInput() 的处理流程:

  1. 若识别器未初始化,先调用 initRecognizer();
  2. 调用 recognizer.recognize(event, session) 得到 List<Intent>;
  3. 为每个意图创建一个虚拟线程(经 OpenJiuwenExecutors.newThread),在线程内按意图类型执行对应的任务操作;
  4. 在所有线程执行完成后返回(t.join()),因此一个输入事件可以一次驱动多个任务操作。

5.2 意图路由对照表

意图类型 处理方式(源码实现)
CREATE_TASK 新建 Task,默认 taskType = "default_task_type"、优先级 1、contextId = sessionId_taskId,状态设为 SUBMITTED 并提交给 TaskManager
PAUSE_TASK 调用 TaskScheduler.pauseTask(targetTaskId)
RESUME_TASK 查找目标任务,仅当其状态为 PAUSED 时改回 SUBMITTED
CONTINUE_TASK 合并依赖任务的输入事件和相关 ModelContext 消息(以 JsonDataFrame 附加),再创建新的 SUBMITTED 任务
SUPPLEMENT_TASK 暂停目标任务,把补充信息以"任务补充信息"段落追加到描述后重新提交(状态置为 SUBMITTED)
CANCEL_TASK 调用 TaskScheduler.cancelTask(targetTaskId)
MODIFY_TASK 先取消目标任务,再更新描述、把当前输入事件追加到任务 inputs 并重新提交
UNKNOWN_TASK 向会话流写入 clarification_prompt 澄清提示

约束提醒:当前实现要求 MODIFY_TASK 和 SUPPLEMENT_TASK 的 targetTaskId 指向已存在任务;如果调用方构造的 Intent 不满足这个约束,更新不会生效(目标任务找不到时静默跳过)。

5.3 完成/交互/失败事件的回写

  • handleTaskInteraction:仅接受 TaskInteractionEvent,把 interaction 写入会话流;
  • handleTaskCompletion:仅接受 TaskCompletionEvent,把 result 写入会话流;
  • handleTaskFailed:仅接受 TaskFailedEvent,把 error_message 写入会话流。

三者都会做严格的事件类型检查(instanceof),类型不匹配时抛出 AGENT_CONTROLLER_RUNTIME_ERROR。单元测试(EventHandlerWithIntentRecognitionTest.java 与 EventHandlerWithIntentRecognitionPythonParityTest.java)覆盖了创建、暂停、恢复、取消、补充、修改和未知意图分支,以及三类事件的类型检查。

六、TaskManager 与 TaskManagerState:任务存储与索引核心

6.1 内部索引结构

TaskManager 是控制器任务子系统的核心存储与索引层(源码:TaskManager.java),内部维护五类索引:

成员 类型 说明
tasks Map<String, Task> 任务主存储
priorityIndex Map<Integer, List<String>> 优先级到任务 ID 列表的索引
parentToChildren Map<String, Set<String>> 父任务到子任务集合的映射
childToParent Map<String, String> 子任务到父任务的反向映射
rootTasks Set<String> 根任务集合

所有公开读写方法都通过 ReentrantLock 保护;setOnTaskSubmitted(Runnable) 允许注册"任务进入 SUBMITTED"的回调,TaskScheduler 正是利用它实现提交即唤醒调度(见 TaskScheduler.java#L97)。

6.2 主要方法与语义

方法 说明
addTask(Task) / addTask(List<Task>) 新增任务并更新优先级和父子关系索引;拒绝重复 taskId
getTask(TaskFilter) 按过滤条件查询并返回深拷贝结果
popTask(TaskFilter) 查询并移除任务;支持 highest 优先级(取数值最大的优先级)
updateTask(Task) / updateTask(List<Task>) 更新已有任务,必要时同步调整索引和父子关系
removeTask(TaskFilter) 按过滤条件删除任务
getChildTask(...) 查询子任务,可递归展开
updateTaskStatus(...) 更新任务状态,可连带更新子任务,失败时写入错误消息
setPriority(...) 更新任务优先级,可连带子任务

关键语义:

  • 删除父任务时,如果某个子任务不在同一批删除列表中,removeTaskInternal() 会把该子任务提升为根任务,避免孤儿任务。
  • 对外返回的任务对象均为 Task.copy() 结果,因此调用方修改查询结果不会直接污染内部状态,除非再调用 updateTask() 提交回去。
  • 并发安全由 ReentrantLock 保证;单元测试(TaskManagerTest.java、TaskManagerSessionIsolationTest.java)覆盖了并发新增、读取、更新、删除、弹出和优先级调整场景。

6.3 TaskManagerState:可序列化快照

TaskManagerState(源码:TaskManagerState.java)是 TaskManager 的可序列化快照对象,字段与索引一一对应(tasks、priorityIndex、parentToChildren、childrenToParent、rootTasks)。

  • toMap() 把 tasks 进一步序列化为 taskId -> task.toMap() 的结构,便于保存到会话状态;
  • fromMap() 把 priority_index 的键从字符串转回整数,并把 root_tasks 恢复为 Set,内部递归调用 Task.fromMap()。

Controller 在会话进入时通过 session.getState("controller") 恢复任务状态,在会话结束(cleanup())时通过 session.updateState() 保存;当 ControllerConfig.enableTaskPersistence = true 时启用持久化(见 Controller.java#L193-L253)。

七、TaskFilter:组合式任务查询条件

TaskFilter(源码:TaskFilter.java)描述任务查询条件,所有字段可选、可组合:

字段 类型 说明
taskId String 或 List<String> 单个或多个任务 ID
sessionId String 按会话过滤
userId String 按 task.metadata.user_id 过滤
priority Integer 或 "highest" 数值优先级,或请求最高优先级任务
status TaskStatus 按任务状态过滤
withChildren boolean 命中任务后是否把子任务一并带出(递归收集)
isRoot boolean 仅匹配根任务

常用工厂方法:byTaskId(...)、byTaskIds(...)、bySessionId(...)、byStatus(...)、byRoot()、byHighestPriority()、builder()。

约束与语义:

  • builder().build() 要求至少设置一个主过滤条件,否则抛出 AGENT_CONTROLLER_TASK_PARAM_ERROR;
  • priority = "highest" 只适合 TaskManager.popTask();getTask() 和 removeTask() 都会对该值抛错;
  • withChildren = true 时,TaskManager 会把命中任务的子任务递归收集到结果中。

八、TaskExecutor 体系:执行器抽象、依赖注入与注册表

8.1 TaskExecutor 抽象基类

TaskExecutor 是任务执行器抽象基类(源码:TaskExecutor.java)。不同 taskType 的业务逻辑需要继承它,并实现任务执行、暂停和取消能力:

方法 返回 说明
executeAbility(String taskId, AgentSessionApi session) Iterator<ControllerOutputChunk> 执行任务并持续产出输出块(抽象方法)
canPause(...) PauseCheckResult 判断任务是否允许暂停并说明原因
pause(...) boolean 执行暂停操作
canCancel(...) CancelCheckResult 判断任务是否允许取消并说明原因
cancel(...) boolean 执行取消操作

嵌套记录类型 PauseCheckResult(boolean canPause, String reason) 与 CancelCheckResult(boolean canCancel, String reason) 封装暂停/取消前的检查结果与失败原因。

关键机制:

  • TaskScheduler 会在任务真正启动后把具体执行器实例记录进 runningTasks,之后暂停和取消流程会复用同一个执行器实例;
  • 执行器产出的 ControllerOutputChunk 决定任务最终状态:TASK_COMPLETION、TASK_INTERACTION 和 TASK_FAILED 三类 payload 会驱动调度器更新 TaskStatus 并发布对应事件。

8.2 TaskExecutorDependencies:依赖打包

TaskExecutorDependencies(源码:TaskExecutorDependencies.java)把构造 TaskExecutor 所需的五个依赖打包为单个对象:config、abilityManager、contextEngine、taskManager、eventQueue。该类型只有 getter 没有 setter,依赖关系在构造后保持稳定。TaskScheduler.executeTask() 会在实例化执行器前构造该对象(见 TaskScheduler.java#L221-L224)。

8.3 TaskExecutorRegistry:taskType 到执行器的注册表

TaskExecutorRegistry(源码:TaskExecutorRegistry.java)维护 taskType -> builder 映射:

方法 说明
addTaskExecutor(String taskType, Function<TaskExecutorDependencies, TaskExecutor> builder) 注册或覆盖某个 taskType 的执行器构造器
removeTaskExecutor(String taskType) 移除构造器,不存在时直接忽略
getTaskExecutor(String taskType, dependencies) 按 taskType 创建新执行器实例;未注册时抛出 AGENT_CONTROLLER_TASK_EXECUTION_ERROR

要点:

  • 同一 taskType 重复注册时,后注册的 builder 会覆盖前一个(单元测试 TaskExecutorRegistryTest.java 已确认);
  • getTaskExecutor() 每次都会重新调用 builder,因此每次取回的都是新实例而非缓存对象;
  • 调度器和 Controller.addTaskExecutor() 共享同一个注册表实例(见 Controller.java#L162-L168)。

九、TaskScheduler:虚拟线程驱动的任务调度器

TaskScheduler(源码:TaskScheduler.java)负责周期扫描 SUBMITTED 任务,并为每个任务创建 TaskExecutor、驱动执行输出、更新任务状态,以及处理暂停、取消和完成信号。

9.1 执行流程(源码级)

  1. scheduleLoop():定期读取所有 SUBMITTED 任务(TaskFilter.builder().status(SUBMITTED).build());
  2. 为每个待执行任务查找会话、检查并发上限,并通过 OpenJiuwenExecutors.newThread(..., true) 在虚拟线程(JDK 21;JDK 17 回退平台线程)中调用 executeTaskWrapper();
  3. executeTaskWrapper() 负责超时看门狗、异常包装和完成信号检查:
    • 若 ControllerConfig.taskTimeout 非空,调度器会为任务启动一个 watchdog 线程,在超时后 interrupt() 执行线程并把任务标记为失败(见 TaskScheduler.java#L166-L206);
    • 异常统一经 handleTaskExecutionFailure() 把任务置为 FAILED 并发布 TASK_FAILED 事件。
  4. executeTask() 取出 Task、构造 TaskExecutorDependencies、从注册表实例化执行器、把任务状态更新为 WORKING,然后持续消费 ControllerOutputChunk:
    • payload 类型为 task_completion → 状态改 COMPLETED,发布 TaskCompletionEvent,终止消费;
    • payload 类型为 task_interaction → 状态改 INPUT_REQUIRED,发布 TaskInteractionEvent,终止消费;
    • payload 类型为 task_failed → 状态改 FAILED,发布 TaskFailedEvent,终止消费;
    • 其他类型(如 processing)→ 继续消费。

9.2 提交唤醒与完成信号

  • notifyTaskSubmitted():TaskManager.setOnTaskSubmitted 注册的回调会在任务进入 SUBMITTED 时唤醒调度循环;通过 AtomicBoolean wakeupPending 合并并发通知,突发提交最多触发一次立即扫描,周期调度仍作为兜底(见 TaskScheduler.java#L129-L146)。
  • areAllTasksCompleted():只把 SUBMITTED 和 WORKING 视为活跃状态,因此暂停、取消、失败和输入等待都允许会话收到完成信号。
  • ensureSessionCompletionSignal():当会话下无活跃任务时,向会话流写入 all_tasks_processed 结束块;ControllerConfig.suppressCompletionSignal = true 可关闭该信号。

9.3 暂停与取消语义

pauseTask(taskId):要求会话和执行器都存在,先调用 executor.canPause()/pause(),再中断虚拟线程并把状态改为 PAUSED;任一前置条件不满足(任务不在运行中、不允许暂停)都返回 false。

cancelTask(taskId):同样先做检查再中断线程并置为 CANCELED;额外处理了两种边界——任务还在 SUBMITTED(未启动)时直接取消成功,任务已在 CANCELED/COMPLETED/FAILED 终态时返回 false。

9.4 调度配置与停止语义

start() 使用 scheduleWithFixedDelay 按 scheduleInterval 周期执行调度循环,并注册 TaskManager 的任务提交回调;stop() 会取消调度任务、打断全部运行中的任务线程(最多等待 5 秒 join)、清空 runningTasks 与活跃会话映射(见 TaskScheduler.java#L620-L682)。runningTasks 中的 RunningTaskEntry(执行器 + 线程)会在任务结束、暂停或取消后被移除,避免旧执行器被后续任务误用。

十、ControllerConfig:控制器关键配置参数

控制器行为由 ControllerConfig.java 配置。与本文讨论的事件流/任务流直接相关的参数如下:

JSON 属性 Java 字段 默认值 说明
max_concurrent_tasks maxConcurrentTasks OpenJiuwenExecutors.defaultTaskConcurrency() 最大并发任务数(JDK 17 平台线程模式生效)
schedule_interval scheduleInterval 1.0(秒) 调度扫描周期;setter 校验必须 >= 0.1
task_timeout taskTimeout null 任务超时秒数;非空时启动 watchdog,超时后中断并标记失败;必须为正数
default_task_priority defaultTaskPriority 1 默认任务优先级
enable_task_persistence enableTaskPersistence false 是否将 TaskManagerState 保存到会话状态
event_queue_size eventQueueSize 10000 事件队列容量
event_timeout eventTimeout 300.0(秒) 事件处理超时
enable_intent_recognition enableIntentRecognition false 是否启用意图识别
intent_llm_id intentLlmId "" 意图识别使用的模型 ID
intent_confidence_threshold intentConfidenceThreshold 0.7 意图置信度阈值,范围 [0.0, 1.0];低于阈值回退 UNKNOWN_TASK
intent_type_list intentTypeList ["create_task","pause_task","resume_task","cancel_task","unknown_task"] 首轮模型调用允许的工具列表
suppress_completion_signal suppressCompletionSignal false 是否抑制 all_tasks_processed 完成信号
stream_first_frame_timeout streamFirstFrameTimeout 30.0(秒) 流式首帧超时

十一、Controller 集成:完整调用链

从 Controller.java 的源码可以看出整个模块的装配关系:

  1. init():Controller.init(card, config, abilityManager, contextEngine) 内部创建 TaskManager、EventQueue、TaskScheduler 三个核心对象(见 Controller.java#L70-L85);
  2. setEventHandler():绑定事件处理器并完成五类依赖注入(config、contextEngine、taskScheduler、taskManager、abilityManager);
  3. addTaskExecutor():把执行器 builder 注册进 taskScheduler 共享的注册表,返回 this 支持链式调用;
  4. start()/stop():启动事件队列与任务调度器,或顺序停止;
  5. stream():完整会话流程为「恢复 TaskManager 状态 → 注册会话到调度器 → 订阅事件 → 发布 InputEvent → 读取会话流直到所有任务完成 → 保存状态 → 取消订阅与清理」(见 Controller.java#L327-L382)。
// 装配示意(结合源码推导的典型用法)
Controller controller = new Controller();
controller.init(card, config, abilityManager, contextEngine);
controller.setEventHandler(new EventHandlerWithIntentRecognition(modelProvider::getModel));
controller.addTaskExecutor("my_task_type", deps -> new MyTaskExecutor(deps));
controller.start();

说明:EventHandlerWithIntentRecognition 内部创建的 IntentRecognizer 通过 ModelProvider 按 config.getIntentLlmId() 获取模型,因此接入时需要提供 intentLlmId 与模型获取函数。

十二、测试覆盖与可靠性保障

仓库为该模块提供了完整的测试矩阵,可作为理解行为语义的补充证据:

这些测试同时以 Python 版本的 ControllerBasePythonParityTest、ControllerTaskManagerPythonParityTest 等命名标注了与 openJiuwen Python 实现的语义对齐,表明 Java 版在行为上保持了跨语言的一致性。

十三、扩展实践建议

  • 自定义事件处理器:继承 EventHandler 并实现四个 handle* 方法即可替换默认实现;由 Controller.setEventHandler() 完成依赖注入,无需自行组装 TaskManager/TaskScheduler。
  • 新增任务类型:继承 TaskExecutor 实现 executeAbility()(返回 Iterator<ControllerOutputChunk>),通过 controller.addTaskExecutor("type", deps -> new Executor(deps)) 注册;执行器产出的 ControllerOutputPayload 类型决定任务的最终状态。
  • 输出流式化:执行器中持续 yield ControllerOutputChunk,调度器会把每个 chunk 写入会话流(session.writeStream(chunk)),从而天然支持流式输出。
  • 会话状态恢复:启用 enable_task_persistence 后,任务树会在会话中断后自动保存并在下次进入时恢复,配合 TaskManagerState.toMap()/fromMap() 实现中断恢复。

参考文档

登录后查看全文
agent-core-java