openJiuwen Core Java 控制器事件流与任务流:com.openjiuwen.core.controller.modules 完全解读
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) 的执行约束与流程:
- 事件类型校验:只接受
InputEvent,传入其他Event实现直接抛出IllegalArgumentException。 - 输入格式校验:输入数据只允许一条
DataFrame.TextDataFrame;出现文件输入(FileDataFrame)、JSON 输入(JsonDataFrame)或多段文本输入时抛出AGENT_CONTROLLER_RUNTIME_ERROR。 - 上下文组装:从
TaskManager读取当前任务清单(task id、description、status),与用户输入一起按固定模板格式化为UserMessage,写入ModelContext。模型系统提示词为固定的「任务管理助手」角色描述,其核心原则是"任务化一切"——任何用户请求都优先转化为一个任务。 - 模型调用:首轮模型调用使用
IntentToolkits.getOpenaiToolSchemas(config.getIntentTypeList())限定可用工具;后续补轮调用放开为全部工具定义。上下文读取固定最多取最近 50 条消息。 - 工具调用解析:每个 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() 的处理流程:
- 若识别器未初始化,先调用
initRecognizer(); - 调用
recognizer.recognize(event, session)得到List<Intent>; - 为每个意图创建一个虚拟线程(经
OpenJiuwenExecutors.newThread),在线程内按意图类型执行对应的任务操作; - 在所有线程执行完成后返回(
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 执行流程(源码级)
- scheduleLoop():定期读取所有
SUBMITTED任务(TaskFilter.builder().status(SUBMITTED).build()); - 为每个待执行任务查找会话、检查并发上限,并通过
OpenJiuwenExecutors.newThread(..., true)在虚拟线程(JDK 21;JDK 17 回退平台线程)中调用executeTaskWrapper(); - executeTaskWrapper() 负责超时看门狗、异常包装和完成信号检查:
- 若
ControllerConfig.taskTimeout非空,调度器会为任务启动一个 watchdog 线程,在超时后interrupt()执行线程并把任务标记为失败(见 TaskScheduler.java#L166-L206); - 异常统一经
handleTaskExecutionFailure()把任务置为FAILED并发布TASK_FAILED事件。
- 若
- executeTask() 取出
Task、构造TaskExecutorDependencies、从注册表实例化执行器、把任务状态更新为WORKING,然后持续消费ControllerOutputChunk:- payload 类型为
task_completion→ 状态改COMPLETED,发布TaskCompletionEvent,终止消费; - payload 类型为
task_interaction→ 状态改INPUT_REQUIRED,发布TaskInteractionEvent,终止消费; - payload 类型为
task_failed→ 状态改FAILED,发布TaskFailedEvent,终止消费; - 其他类型(如
processing)→ 继续消费。
- payload 类型为
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 的源码可以看出整个模块的装配关系:
- init():
Controller.init(card, config, abilityManager, contextEngine)内部创建TaskManager、EventQueue、TaskScheduler三个核心对象(见 Controller.java#L70-L85); - setEventHandler():绑定事件处理器并完成五类依赖注入(config、contextEngine、taskScheduler、taskManager、abilityManager);
- addTaskExecutor():把执行器 builder 注册进
taskScheduler共享的注册表,返回this支持链式调用; - start()/stop():启动事件队列与任务调度器,或顺序停止;
- 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与模型获取函数。
十二、测试覆盖与可靠性保障
仓库为该模块提供了完整的测试矩阵,可作为理解行为语义的补充证据:
- 事件流:EventQueueTest.java、EventHandlerTest.java;
- 意图识别:IntentRecognizerTest.java、IntentToolkitsTest.java;
- 意图路由:EventHandlerWithIntentRecognitionPythonParityTest.java,覆盖全部意图分支与三类事件类型检查;
- 任务存储:TaskManagerTest.java、TaskManagerSessionIsolationTest.java;
- 执行器:TaskExecutorTest.java、TaskExecutorRegistryTest.java;
- 调度器:TaskSchedulerTest.java。
这些测试同时以 Python 版本的 ControllerBasePythonParityTest、ControllerTaskManagerPythonParityTest 等命名标注了与 openJiuwen Python 实现的语义对齐,表明 Java 版在行为上保持了跨语言的一致性。
十三、扩展实践建议
- 自定义事件处理器:继承
EventHandler并实现四个handle*方法即可替换默认实现;由Controller.setEventHandler()完成依赖注入,无需自行组装TaskManager/TaskScheduler。 - 新增任务类型:继承
TaskExecutor实现executeAbility()(返回Iterator<ControllerOutputChunk>),通过controller.addTaskExecutor("type", deps -> new Executor(deps))注册;执行器产出的ControllerOutputPayload类型决定任务的最终状态。 - 输出流式化:执行器中持续
yieldControllerOutputChunk,调度器会把每个 chunk 写入会话流(session.writeStream(chunk)),从而天然支持流式输出。 - 会话状态恢复:启用
enable_task_persistence后,任务树会在会话中断后自动保存并在下次进入时恢复,配合TaskManagerState.toMap()/fromMap()实现中断恢复。
参考文档
- modules.README.md(关联文档)
- modules 子文档目录:
EventHandler.md、EventHandlerInput.md、EventHandlerWithIntentRecognition.md、EventQueue.md、IntentRecognizer.md、IntentToolkits.md、TaskExecutor.md、TaskExecutorDependencies.md、TaskExecutorRegistry.md、TaskFilter.md、TaskManager.md、TaskManagerState.md、TaskScheduler.md - Controller.md(控制器总览)
- ControllerConfig.md(配置说明)