📖 扩展点速查
# 组件的基本声明
对话与工具调用组件继承 com.yomahub.liteflow.agent.harness.component.HarnessAgentComponent。process() 由框架管理，通常只需覆写下列入口。Jev 选择组件的独立入口见下方“Jev 选择组件”一节。
| 方法 | 用途 |
|---|---|
model() | 必须实现，选择模型平台和模型 ID |
systemPrompt() | 必须实现，声明固定职责 |
userPrompt(context) | 必须实现，为本次调用提供输入 |
tools() | 注册 Java 业务工具，默认空列表 |
mcpClients() | 注册 MCP 客户端，默认空列表 |
enableShellTool() | 默认 true；纯对话组件可返回 false |
skillFilter() | 默认允许全部技能，可返回 SkillFilter.only(...) |
structuredOutputType()／structuredOutputSchema() | 指定 Java 类型或 JSON Schema，二选一 |
permissionContext() | 配置工具权限；需要审批时设置 ASK 规则 |
confirmationHandler() | 提供组件级确认处理器，也可注册 Spring Bean |
subagents() | 声明子代理，本地后端不启用 |
enablePlanMode() | 默认 false，按需开启计划模式 |
agentKey() | 默认当前 nodeId，组件运行期间保持稳定 |
resolveConversationId(slot) | 自定义会话解析，通常用 ExecuteOption 即可 |
# 按需求定制
| 需求 | 入口 |
|---|---|
| 保留各节点结果、读取 Token 用量 | handleReply(reply, context)；调用 super 保留默认结果写入，context.getChatUsage() 获取用量 |
| 当前调用添加业务数据 | customizeRuntimeContext(builder, context)；不要覆盖会话身份 |
| 当前调用调整提示词 | transformSystemPrompt(prompt, context) |
| 给模型固定参考资料 | additionalContextFiles() 返回工作区相对路径列表 |
| 调整循环上限 | maxIterations() 返回正整数；默认 -1 使用全局配置 |
| 调整请求超时／重试 | modelExecutionConfig()、toolExecutionConfig() 返回 ExecutionConfig；有副作用的工具重试需业务幂等 |
| 使用备用模型 | fallbackModel() 返回解析后的 Model |
| 按调用切换模型 | routingModels() 先登记候选，routeModel(defaultModel, context) 返回其中一个实例 |
| 技能仓库扩展 | skillRepositoryRegistrations()；dynamicSkillsEnabled() 默认 true，设 false 固定技能集合 |
| 交付生成的文件 | customizeHarness(builder) 配置应用实现的 ArtifactDeliveryTarget，启用 deliver_artifact；下载接口由应用实现 |
| 添加调用拦截 | middlewares() 返回中间件列表 |
通常只需覆写对应方法。自定义 builder 时修改并返回原 builder，保留框架装配的存储、工具和文件系统。模型由运行时关闭，共享 MCP 客户端由应用管理。
# Jev 选择组件
liteflow-agent-jev 的组件继承 com.yomahub.liteflow.agent.jev.JevSwitchComponent。processSwitch() 由框架实现，直接返回 LiteFlow 选择分支需要的 ID。
| 方法 | 用途 |
|---|---|
state() | 必须实现，提供本次用户问题及相关业务上下文，支持字符串、可序列化为 JSON 对象的业务数据或数组 |
instructions() | 必须实现，返回非空白字符串，定义判断任务、规则和优先级，可根据本次上下文动态生成 |
choices() | 必须实现，返回目标 ID 到判断说明的 Map，ID 在当前 .to(...) 中必须唯一 |
minConfidence() | 按需覆写；默认读取 liteflow.agent.jev.min-confidence |
onDecision(result) | 接收完整的 JevChoiceResult，可写入本次流程上下文 |
state() 和 instructions() 都必须实现，不能二选一。用户输入“我想退款”放在 state() 中；“根据客户当前诉求选择处理分支”放在 instructions() 中。前者提供待判断的数据，后者说明如何判断。
结果提供 model()、choice()、confidence() 和不可变的 probabilities()。低置信度与均不适用的有效结果也会进入回调；组件实例可能并发复用，不要把本次输入和结果存到实例字段中。示例见编写 Jev 选择组件。
# Jev 布尔判断组件
liteflow-agent-jev 的布尔判断组件继承 com.yomahub.liteflow.agent.jev.JevBooleanComponent，自 2.16.3 起提供。processBoolean() 由框架实现，按 Noul 概率与阈值返回 boolean，供 IF、WHILE 及 AND／OR／NOT 使用。
| 方法 | 用途 |
|---|---|
state() | 必须实现，提供本次待判断的内容，支持字符串、可序列化为 JSON 对象的业务数据或数组 |
instructions() | 必须实现，返回非空白字符串，定义是非判断标准，高概率代表“是” |
probabilityThreshold() | 按需覆写；默认读取 liteflow.agent.jev.noul-threshold（默认 0.5），概率达到阈值（含）走 true 分支 |
onDecision(result) | 接收完整的 JevNoulResult，可写入本次流程上下文 |
结果提供 model() 和 probability()；Noul 没有独立的置信度字段，概率接近阈值时应视为不确定。鉴权、超时等调用故障抛出 JevInvocationException，不会伪装成 false。示例见编写 Jev 布尔组件。
# LiteFlowAgentContext
通过方法参数取得当前调用上下文，不再使用旧版 ctx()。
| 方法 | 内容 |
|---|---|
getSlot() | 当前 LiteFlow Slot |
getConversationId()、getAgentKey() | 当前会话和 Agent 标识 |
getChainId()、getNodeId() | 当前链与节点 |
getRequestId()、getTraceId() | 请求与追踪标识 |
getDeadline()、isCancelled() | 执行截止时间与取消状态 |
getChatUsage() | 本次累计模型用量，可能为空 |
getUsedSkills() | 本次已成功加载的技能 |
getOutputSpec() | 本次输出类型声明 |
# 构建声明与单次调用
模型、工具和中间件等声明在构建运行时时装配，不随每次请求重新创建。当前输入放在 userPrompt(context)，动态系统提示词放在 transformSystemPrompt(prompt, context)。
customizeRuntimeContext(builder, context) 用于添加业务数据，不能改写框架的会话身份，也不要设置 userId。已构建的配置对象发生变化时，不会自动重建所有运行时资源。