常见问题

现象	原因	解决方案
liteflow.agent.workspace.root is required	未配置 workspace 根目录	配置 liteflow.agent.workspace.root
cannot create workspace root	根目录不可写	换到可写目录，或提前创建并授权
Missing API key: please configure liteflow.agent.openai.api-key	平台凭据未配置	配置对应平台的 api-key
多轮对话没有记忆	每次使用了不同 conversationId	传入稳定的 conversationId 或覆写 resolveConversationId()
重启后没有历史	memory 模式为 JVM 或 NONE	改为 LOCAL_FILE、REDIS 或 MYSQL
Redis 模式启动失败	Bean 名或类型不匹配	检查 bean-name、client-type 和 classpath 依赖
Shell 返回 command not allowed	命令不在白名单中	加入白名单或保持禁用
path escapes workspace	文件工具收到绝对路径或越界路径	使用相对路径
Skills root not found	skills 目录不存在	创建目录或关闭 skills
Declared skills not found	skills() 声明了不存在的技能	检查技能目录与 SKILL.md 的 name
没有收到流式事件	未注册 eventListener	使用 ExecuteOption.eventListener(...) 注册监听器
ctx() must be called during process()	在 process() 外调用了 ctx()	只在 process() 生命周期内调用
WHEN 中多 Agent 未并行	相同 (conversationId, agentKey) 导致串行	确保需要并行的 Agent 使用不同 agentKey
ctx().getChatUsage() 返回 null	本轮还没发生 reasoning step	在 handleReply() 中读取
listener 注册后链路失败	listener 中抛出异常或阻塞 I/O	listener 中只做轻量处理

运行时错误处理

Agent 实际调用大模型时，可能遇到 API 限流、网络超时、凭据失效等问题。这些异常会从 process() 内部向上抛出，最终体现在 LiteflowResponse 中：

LiteflowResponse response = flowExecutor.execute2Resp("deepseekChain", request,
        ExecuteOption.of().conversationId("chat-user-1"));

if (!response.isSuccess()) {
    Throwable cause = response.getCause();
    // 1. 记录 conversationId / requestId，便于结合 Re-Act 日志排查
    // 2. 根据异常类型决定降级策略：返回兜底文案、切换备用模型 Chain、或直接对上游报错
}

常见运行时异常：

类型	触发场景	建议处理
AgentConfigException	凭据缺失、workspace 不可写、skills 目录缺失等启动期/构建期问题	通常是配置问题，应快速失败而不是重试
模型 SDK 抛出的 4xx（401/403/429）	API key 无效、限流、配额耗尽	429 限流可由调用方做退避重试；401/403 需要排查凭据
模型 SDK 抛出的 5xx 或网络超时	模型平台故障、网络抖动	调用方可重试一次或切到备用平台 Chain
handleReply 中业务异常	解析回复时业务代码出错	建议在 handleReply 内自行 try/catch，避免影响 memory 保存

重试与记忆

对同一个 conversationId 重试会沿用上一轮的 memory。如果上一轮失败时模型已经写入了部分上下文，可能影响下次推理结果。需要严格幂等的场景，可以为重试请求改用新的 conversationId，或者将 liteflow.agent.session.memory.save-on-error 设为 false。