ZNJJ-api-server/docs/langgraph-minimal-slice.md

LangGraph 最小开发纵切

状态：仅用于本地开发和测试 日期：2026-07-27

启用

在被 Git 忽略的 .env.local 中配置：

ZNJJ_ENVIRONMENT=development
AGENT_BACKEND=langgraph
LANGGRAPH_CHECKPOINTER=memory

LLM_API_KEY=...
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=...
LLM_TIMEOUT_SECONDS=60
LLM_MAX_RETRIES=2

不设置 AGENT_BACKEND 时默认使用 FastGPT。

当前调用链

/chat
  -> ChatBackend
  -> LangGraphBackend
  -> StateGraph
  -> generate_response
  -> OpenAI-compatible LLM
  -> ChatResult
  -> 现有非流式/SSE API Adapter

InMemorySaver 使用 sessionId 作为 thread_id，同一进程内同一 session 可以恢复 turn_count 等图状态；不同 session 相互隔离。

当前已有能力

• FastGPT/LangGraph 后端配置切换。
• 最小 Pydantic Settings 和条件化启动校验。
• 实际使用 LangGraph StateGraph。
• 开发/测试使用 InMemorySaver。
• OpenAI-compatible LLM 节点。
• 非流式 /chat 适配。
• 通过完整结果桥接现有 SSE；formUpdate 先于文本发送。
• Fake LLM 下的多轮 thread 隔离测试。

明确限制

当前图只有一个模型节点，目的是尽早建立可执行骨架。以下尚未实现：

• 领域状态、输入事件和确定性路由节点；
• 状态码枚举及迁移合法性校验；
• 单车/双车拍照状态机；
• 字段提取、验证和真实 formUpdate；
• 模型 token 级流式输出；
• PostgreSQL checkpointer；
• session 并发、版本和幂等；
• /set_info、/get_info 的业务状态迁移。

因此：

• LANGGRAPH_CHECKPOINTER=postgres 当前会启动失败；
• staging/production 禁止使用 memory checkpointer；
• /set_info、/get_info、/delete_session 暂时仍需要 FastGPT 配置；
• 不得把当前 LangGraph backend 接入生产流量。

下一步

直接在现有图中加入 Phase 5 的纯确定性骨架：

1. AccidentState、输入事件和状态枚举；
2. state prefix parser 与迁移 validator；
3. normalize_input、route_phase；
4. 单车/双车拍照事件推进；
5. 无回复和澄清计数；
6. 对应参数化 Graph 测试。

这些节点完成后再接 PostgreSQL 和业务状态 repository。