agent_jrxml/docs/conversation-scenarios.md

对话场景遍历文档

从 agent/graph.py 状态图递归遍历生成，覆盖所有用户意图 → 节点路径 → 退出条件。 最后更新: 2026-05-24

---

状态图总览

                        ┌──────────────────────────────────────────────────┐
                        │              修正循环 (最多 MAX_RETRY=5 次)       │
                        │    ┌─────────┐    ┌──────────────┐    ┌────────┐ │
                        │    │ validate │───→│ explain_error│───→│correct │ │
                        │    └────┬─────┘    └──────────────┘    │_jrxml  │ │
                        │         │ pass                          └───┬────┘ │
                        │         ▼                                   │      │
                        │    ┌─────────┐                         retry<5  │
                        │    │finalize │◄────────────────────────────────┘ │
                        │    └─────────┘  retry>=5                        │
                        └──────────────────────────────────────────────────┘

load_session ──→ process_input ──→ manage_context ──→ save_state_snapshot
                                                           │
                                                           ▼
                                                    classify_intent
                                                           │
              ┌────────────┬──────────┬────────┬───────────┼───────────┬──────────┐
              ▼            ▼          ▼        ▼           ▼           ▼          ▼
         retrieve    modify_jrxml  save_   handle_     handle_     handle_    (兜底)
         (新建报表)   (修改报表)   session  consult     undo        reset
              │            │       (预览)  (咨询)      (撤销)      (重置)
     ┌────────┴────┐       │          │        │           │           │
     ▼             ▼       │          │        │           │           │
  generate    generate_    │          │        │           │           │
  (1-shot)    skeleton     │          │        │           │           │
     │             │        │          │        │           │           │
     │        refine_       │          │        │           │           │
     │        layout        │          │        │           │           │
     │             │        │          │        │           │           │
     │        map_fields    │          │        │           │           │
     │             │        │          │        │           │           │
     └──────┬──────┘        │          │        │           │           │
            ▼               ▼          ▼        ▼           ▼           ▼
         save_session ◄─────┴──────────┘    finalize ◄─── finalize ◄── finalize
            │                                     ▲
            │ (预览/导出跳过验证)                    │
            ├───────────────────────────────────────┘
            │ (其他意图走验证)
            ▼
         validate ──→ explain_error ──→ correct_jrxml ──→ validate (循环)
            │ pass                                     │ retry>=MAX
            ▼                                          ▼
         finalize ────────────────────────────────→ finalize

---

节点详细清单

每个节点标注了 代码行号 (agent/nodes.py 或 agent/graph.py)、前驱节点 (predecessors)、后继节点 (successors)。

1. load_session — 加载会话

属性	值
代码位置	agent/nodes.py:77
前驱	(入口节点, graph entry_point)
后继	process_input (固定边 graph.py:198)
功能	从 sessions/{session_id}.json 磁盘加载状态，注入 agent_state。不从磁盘覆盖 session_id。
LLM	否

2. process_input — 处理用户输入

属性	值
代码位置	agent/nodes.py:98
前驱	load_session (graph.py:198)
后继	manage_context (graph.py:199)
功能	文件解析（PDF/DOCX/XLSX/图片/文本）→ OCR 字段提取 → 批注检测 → 模板 JRXML 解析。注入 ocr_extraction_result、layout_schema、ocr_elements、uploaded_template_jrxml。
LLM	否（OCR 用 PaddleOCR/EasyOCR）

3. manage_context — 上下文管理

属性	值
代码位置	agent/nodes.py:143
前驱	process_input (graph.py:199)
后继	save_state_snapshot (graph.py:200)
功能	Token 计数 → 对话压缩（超限时 LLM 压缩为摘要）→ compressed_history。
LLM	是（压缩时调 LLM）

4. save_state_snapshot — 状态快照

属性	值
代码位置	agent/nodes.py:191
前驱	manage_context (graph.py:200)
后继	classify_intent (graph.py:201)
功能	深拷贝当前状态 → 推入 history_states 列表。最多保留 5 个快照。撤销时恢复到最新快照。
LLM	否

5. classify_intent — 意图分类

属性	值
代码位置	agent/nodes.py:200
前驱	save_state_snapshot (graph.py:201)
后继	6 路条件分发 (graph.py:204-215)
功能	LLM 分类用户意图为 8 种之一。prompt: prompts/intent_classify.md。
LLM	是
路由函数	route_by_intent (graph.py:67)

分类逻辑与路由目标:

意图值	路由目标	说明
initial_generation	→ retrieve	新建报表
modify_report	→ modify_jrxml	修改现有报表
preview_report	→ save_session	预览（跳过生成）
export_pdf	→ save_session	导出 PDF（跳过生成）
export_jrxml	→ save_session	下载 JRXML（跳过生成）
consult_question	→ handle_consult	咨询问答
undo_modification	→ handle_undo	撤销
reset_session	→ handle_reset	重置
未知/兜底	有 current_jrxml → modify_jrxml; 无 → retrieve

6. retrieve — RAG/知识库检索

属性	值
代码位置	agent/nodes.py:442
前驱	classify_intent (graph.py:204-215, intent=initial_generation)
后继	条件分发: generate_skeleton 或 generate (graph.py:218-224)
功能	① ErrorKB 检索历史修正案例 → ② KB 模板检索 → ③ KB 字段定义检索。注入 retrieved_context、kb_template_jrxml、kb_fields。
LLM	否（向量搜索 + 字段匹配）
路由函数	route_after_retrieve (graph.py:94)

路由逻辑 (route_after_retrieve, graph.py:94-99):

• layout_schema.total_rows > 0 → generate_skeleton (3 阶段)
• 否则 → generate (1-shot)

7. generate — 1-shot 生成

属性	值
代码位置	agent/nodes.py:578
前驱	retrieve (graph.py:218-224, 无 layout_schema 时)
后继	save_session (graph.py:227-231)
功能	LLM 一次生成完整 JRXML。注入 OCR 上下文 + 模板上下文。流式输出。截断时续写（最多 3 轮）。
LLM	是
Prompt	prompts/initial_generation.md

8. generate_skeleton — 骨架生成（3 阶段-1）

属性	值
代码位置	agent/nodes.py:657
前驱	retrieve (graph.py:218-224, 有 layout_schema 时)
后继	refine_layout (固定边 graph.py:233)
功能	压缩布局 schema → LLM 生成骨架 JRXML。字段用 $F{field_N} 占位。流式输出 + 续写。
LLM	是
Prompt	prompts/skeleton_generation.md

9. refine_layout — 坐标精调（3 阶段-2）

属性	值
代码位置	agent/nodes.py:879
前驱	generate_skeleton (graph.py:233)
后继	map_fields (固定边 graph.py:234)
功能	① decompose_jrxml() 拆解为 header + bands → ② 每个 band 窗口化（>4000 字符切分）→ ③ 逐窗口 LLM 精调坐标 → ④ reassemble_jrxml() 重组 → ⑤ validate_element_count() 校验（>10% 回退）。header 完全不发给 LLM。
LLM	是（N 次，N = band 窗口数）
Prompt	prompts/refine_layout.md

10. map_fields — 字段映射（3 阶段-3）

属性	值
代码位置	agent/nodes.py:978
前驱	refine_layout (graph.py:234)
后继	save_session (graph.py:235-239)
功能	纯程序化正则替换 $F{field_N} → OCR 真实字段名。_sanitize_field_name() 净化非 ASCII 字符。零 LLM 调用。
LLM	否

11. modify_jrxml — 修改报表

属性	值
代码位置	agent/nodes.py:1022
前驱	classify_intent (graph.py:204-215, intent=modify_report)
后继	save_session (graph.py:242-246)
功能	基于现有 JRXML + 用户修改描述 + OCR 上下文 + 模板上下文 → LLM 修改。流式输出 + 续写。空响应守卫。
LLM	是
Prompt	prompts/modification.md

12. handle_consult — 咨询解答

属性	值
代码位置	agent/nodes.py:261
前驱	classify_intent (graph.py:204-215, intent=consult_question)
后继	finalize (固定边 graph.py:280)
功能	LLM 回答 JasperReports 相关知识问题。回答写入 conversation_history。
LLM	是
Prompt	prompts/consult.md

13. handle_undo — 撤销

属性	值
代码位置	agent/nodes.py:281
前驱	classify_intent (graph.py:204-215, intent=undo_modification)
后继	save_session (graph.py:249-253)
功能	从 history_states 弹出最近快照，恢复 current_jrxml、conversation_history、status。无快照时提示"无可撤销状态"。
LLM	否

14. handle_reset — 重置

属性	值
代码位置	agent/nodes.py:309
前驱	classify_intent (graph.py:204-215, intent=reset_session)
后继	finalize (固定边 graph.py:281)
功能	清空所有状态到 create_initial_state() 默认值（保留 session_id、session_name）。
LLM	否

15. save_session — 保存会话

属性	值
代码位置	agent/nodes.py:325
前驱	generate、map_fields、modify_jrxml、handle_undo、classify_intent(预览/导出)
后继	条件分发: validate 或 finalize (graph.py:256-260)
功能	原子持久化会话 JSON (tempfile + os.replace)。序列化 agent_state 到 sessions/{session_id}.json。
LLM	否
路由函数	route_after_save (graph.py:118)

路由逻辑 (route_after_save, graph.py:118-123):

• intent in (preview_report, export_pdf, export_jrxml) → finalize (跳过验证)
• 其他 → validate

16. validate — 验证

属性	值
代码位置	agent/nodes.py:1235
前驱	save_session (graph.py:256-260)、correct_jrxml (graph.py:273-277)
后继	条件分发: finalize 或 explain_error (graph.py:263-267)
功能	① 结构检查（字段引用一致性/SQL 存在/pageWidth/pageHeight/name）→ ② XSD 校验（可选）→ ③ 像素对比（有上传图片时 Java 渲染 JRXML→PNG + OpenCV SSIM）。
LLM	否
路由函数	route_after_validate (graph.py:127)

路由逻辑 (route_after_validate, graph.py:127-131):

• status == "pass" → finalize
• status == "fail" → explain_error

17. explain_error — 错误解释

属性	值
代码位置	agent/nodes.py:1310
前驱	validate (graph.py:263-267, status=fail)
后继	correct_jrxml (graph.py:268-272)
功能	LLM 将编译错误翻译为自然语言解释。注入 natural_explanation。
LLM	是
Prompt	prompts/explain_error.md

18. correct_jrxml — 自动修正

属性	值
代码位置	agent/nodes.py:1355
前驱	explain_error (graph.py:268-272)
后继	条件分发: validate 或 finalize (graph.py:273-277)
功能	基于错误解释 + OCR 上下文 + 模板上下文 → LLM 修正 JRXML。注入 last_error_case。去重检测（输入输出相同则 retry_count+=2）。
LLM	是
Prompt	prompts/correction.md
路由函数	route_after_correct (graph.py:139)

路由逻辑 (route_after_correct, graph.py:139-143):

• retry_count >= MAX_RETRY (默认5) → finalize (放弃修正)
• retry_count < MAX_RETRY → validate (重新验证)

19. finalize — 最终处理

属性	值
代码位置	agent/nodes.py:1452
前驱	validate(pass)、correct_jrxml(retry>=MAX)、handle_consult、handle_reset、save_session(预览/导出)
后继	END (graph.py:284)
功能	记录 jrxml_versions 版本历史。验证通过时设置 final_jrxml。失败时记录 pending_failure_context 供下次输入自动注入。
LLM	否

---

路由函数索引

#	路由函数	代码位置	条件	分支
R1	route_by_intent	graph.py:67	state.intent	6 路: retrieve / modify_jrxml / save_session / handle_consult / handle_undo / handle_reset
R2	route_after_retrieve	graph.py:94	layout_schema.total_rows > 0	2 路: generate_skeleton / generate
R3	route_after_generate	graph.py:103	无条件	save_session
R4	route_after_modify	graph.py:108	无条件	save_session
R5	route_after_undo	graph.py:113	无条件	save_session
R6	route_after_save	graph.py:118	intent in (preview, export)	2 路: finalize / validate
R7	route_after_validate	graph.py:127	status == "pass"	2 路: finalize / explain_error
R8	route_after_explain	graph.py:133	无条件	correct_jrxml
R9	route_after_correct	graph.py:139	retry_count >= MAX_RETRY	2 路: finalize / validate

---

完整对话场景

场景 1: 新建报表 — 1-shot（无布局 schema）

触发: intent=initial_generation + 无图片/无结构化布局

用户示例: "帮我生成一个销售报表"、"生成一个包含客户名和金额的表格"

  load_session                 nodes.py:77
→ process_input                nodes.py:98
→ manage_context               nodes.py:143
→ save_state_snapshot          nodes.py:191
→ classify_intent              nodes.py:200   意图=initial_generation
  └─ R1: route_by_intent       graph.py:67    → retrieve
→ retrieve                     nodes.py:442
  └─ R2: route_after_retrieve  graph.py:94    layout_schema 为空 → generate
→ generate                     nodes.py:578    LLM 1-shot 生成完整 JRXML
  └─ R3: route_after_generate  graph.py:103   → save_session
→ save_session                 nodes.py:325    持久化到磁盘
  └─ R6: route_after_save      graph.py:118   intent=initial_generation → validate
→ validate                     nodes.py:1235   结构检查 + XSD + 像素对比
  └─ R7: route_after_validate  graph.py:127
       ├─ status=pass → finalize              nodes.py:1452 → END ✓
       └─ status=fail → explain_error         nodes.py:1310
                         └─ R8 → correct_jrxml nodes.py:1355
                                  └─ R9:
                                     retry<5  → validate (循环)
                                     retry>=5 → finalize → END ✗

LLM 调用: classify_intent + generate + 最多 5× (explain_error + correct_jrxml) 退出好结局: final_jrxml 有值, status=pass 退出坏结局: pending_failure_context 有值, retry_count=5

---

场景 2: 新建报表 — 3 阶段分层生成（有布局 schema）

触发: intent=initial_generation + 上传图片 + OCR 提取到 layout_schema.total_rows > 0

用户示例: 上传销售单图片 → "根据这个模板生成报表"

  load_session                 nodes.py:77
→ process_input                nodes.py:98    OCR提取 + 布局分析
→ manage_context               nodes.py:143
→ save_state_snapshot          nodes.py:191
→ classify_intent              nodes.py:200   意图=initial_generation
  └─ R1: route_by_intent       graph.py:67    → retrieve
→ retrieve                     nodes.py:442   KB检索模板+字段
  └─ R2: route_after_retrieve  graph.py:94    layout_schema.total_rows>0 → generate_skeleton
→ generate_skeleton            nodes.py:657   阶段1: 骨架JRXML ($F{field_N}占位)
→ refine_layout                nodes.py:879   阶段2: Band级窗口化坐标精调
→ map_fields                   nodes.py:978   阶段3: 程序化字段映射
  └─ R3: route_after_generate  graph.py:103   → save_session
→ save_session                 nodes.py:325
  └─ R6: route_after_save      graph.py:118   → validate
→ validate                     nodes.py:1235
  └─ R7                        同场景1的验证循环

内容保护:

• refine_layout: header (field/param/queryString) 完全不发给 LLM
• refine_layout: 每窗口 ~4000 字符, LLM 无法重写整个报表
• map_fields: 纯正则替换, 零 LLM, 100% 确定性
• validate_element_count(): 每阶段后校验, >10% 变化回退

LLM 调用: classify_intent + generate_skeleton + N×refine_layout(N=band窗口数) + 可能的修正循环

---

场景 3: 修改已有报表

触发: intent=modify_report（已有 current_jrxml）

用户示例: "把标题字体改大"、"在底部加合计行"、"删除第三列"

  load_session → process_input → manage_context → save_state_snapshot
→ classify_intent              nodes.py:200   意图=modify_report
  └─ R1: route_by_intent       graph.py:67    → modify_jrxml
→ modify_jrxml                 nodes.py:1022  LLM修改现有JRXML
  └─ R4: route_after_modify    graph.py:108   → save_session
→ save_session                 nodes.py:325
  └─ R6: route_after_save      graph.py:118   → validate
→ (同场景1的验证循环)

特殊逻辑: correct_jrxml 去重检测: 输入输出相同 → retry_count += 2

---

场景 4: 预览 / 导出（跳过验证）

触发: intent in (preview_report, export_pdf, export_jrxml)

用户示例: "预览报表"、"导出 PDF"、"下载 JRXML"

  load_session → process_input → manage_context → save_state_snapshot
→ classify_intent              nodes.py:200   意图=preview/export
  └─ R1: route_by_intent       graph.py:67    → save_session
→ save_session                 nodes.py:325
  └─ R6: route_after_save      graph.py:118   intent=preview/export → finalize
→ finalize                     nodes.py:1452  → END ✓

LLM 调用: 仅 classify_intent (1次) 跳过: generate / modify_jrxml / validate / correct_jrxml

---

场景 5: 咨询问答

触发: intent=consult_question

用户示例: "JasperReports 里 $F 和 $P 有什么区别？"、"怎么设置页脚？"

  load_session → process_input → manage_context → save_state_snapshot
→ classify_intent              nodes.py:200   意图=consult_question
  └─ R1: route_by_intent       graph.py:67    → handle_consult
→ handle_consult               nodes.py:261   LLM回答
→ finalize                     nodes.py:1452  → END ✓

LLM 调用: classify_intent + handle_consult (2次)

---

场景 6: 撤销

触发: intent=undo_modification

用户示例: "撤销"、"回退"、"恢复到修改前"

  load_session → process_input → manage_context → save_state_snapshot
→ classify_intent              nodes.py:200   意图=undo_modification
  └─ R1: route_by_intent       graph.py:67    → handle_undo
→ handle_undo                  nodes.py:281   恢复history_states快照
  └─ R5: route_after_undo      graph.py:113   → save_session
→ save_session                 nodes.py:325
  └─ R6 → validate → (验证循环)

LLM 调用: 仅 classify_intent (1次) 特殊: 无快照时提示"无可撤销状态"，不改变当前状态

---

场景 7: 重置

触发: intent=reset_session

用户示例: "重置"、"重新开始"、"清空对话"

  load_session → process_input → manage_context → save_state_snapshot
→ classify_intent              nodes.py:200   意图=reset_session
  └─ R1: route_by_intent       graph.py:67    → handle_reset
→ handle_reset                 nodes.py:309   清空到初始状态
→ finalize                     nodes.py:1452  → END ✓

LLM 调用: 仅 classify_intent (1次)

---

场景 8: 兜底路由（未知意图）

触发: LLM 分类返回非标准意图

  load_session → ... → classify_intent → [未知意图]
  └─ R1 fallback (graph.py:87-90):
       ├─ state有current_jrxml → modify_jrxml (走修改路径, →场景3)
       └─ state无current_jrxml → retrieve      (走生成路径, →场景1/2)

---

AgentState 字段速查

字段	类型	写节点	读节点
intent	str	classify_intent	R1 route_by_intent, R6 route_after_save
current_jrxml	str	generate, generate_skeleton, refine_layout, map_fields, modify_jrxml, correct_jrxml, handle_undo	validate, save_session, finalize
user_input	str	process_input	classify_intent, manage_context
user_modification_request	str	process_input	modify_jrxml
conversation_history	list	process_input, finalize, handle_consult	manage_context, classify_intent, modify_jrxml
full_conversation_history	list	process_input	manage_context
compressed_history	str	manage_context	modify_jrxml, handle_consult
retry_count	int	correct_jrxml, validate	R7 route_after_correct
status	str	validate	R7 route_after_validate, finalize
error_msg	str	validate	explain_error, finalize
natural_explanation	str	explain_error	correct_jrxml
final_jrxml	str	finalize	(用户下载)
jrxml_versions	list	finalize	(前端展示)
last_error_case	dict	correct_jrxml	retrieve
pending_failure_context	dict	finalize	process_input (下次)
layout_schema	dict	process_input	R2 route_after_retrieve, generate_skeleton
ocr_elements	list	process_input	refine_layout, generate_skeleton
ocr_extraction_result	dict	process_input	map_fields, modify_jrxml, correct_jrxml
history_states	list	save_state_snapshot	handle_undo
kb_id	str	process_input	retrieve
kb_fields	list	retrieve	generate_skeleton
uploaded_template_jrxml	str	process_input	generate, generate_skeleton, modify_jrxml, correct_jrxml

---

LLM 调用统计

场景	classify	生成节点	窗口数	修正循环	总计(最小~最大)
1-shot 生成	1	generate=1	-	0~5×2	2 ~ 12
3 阶段生成	1	skeleton+refine×N	N	0~5×2	2+N ~ 12+N
修改报表	1	modify=1	-	0~5×2	2 ~ 12
预览/导出	1	-	-	-	1
咨询	1	consult=1	-	-	2
撤销	1	-	-	-	1
重置	1	-	-	-	1

N = band 窗口数。销售单.jrxml (73k 字符) 拆解后 N≈17。

---

修正循环流程

validate ──fail──→ explain_error ──→ correct_jrxml
    ▲                                      │
    │         retry_count < MAX_RETRY(5)    │
    └──────────────────────────────────────┘
                     │
                     │ retry_count >= 5
                     ▼
                  finalize (放弃, 记录pending_failure_context)

修正轮次推进:

1. validate 失败 → status="fail", error_msg 有值
2. explain_error → LLM 翻译错误 → natural_explanation 有值
3. correct_jrxml → LLM 修正 → retry_count += 1。去重检测：输入输出相同 → retry_count += 2
4. route_after_correct → retry<5 → 回到 validate; retry>=5 → finalize

失败上下文 (pending_failure_context): 重试耗尽后记录 {error_msg, bad_jrxml, retry_count, ts}，下次用户消息时 process_input 自动注入到 prompt。

---

边定义索引（graph.py 全部边）

类型	源节点	目标节点	位置
固定边	load_session	process_input	line 198
固定边	process_input	manage_context	line 199
固定边	manage_context	save_state_snapshot	line 200
固定边	save_state_snapshot	classify_intent	line 201
条件边	classify_intent	retrieve / modify_jrxml / save_session / handle_consult / handle_undo / handle_reset	lines 204-215
条件边	retrieve	generate / generate_skeleton	lines 218-224
条件边	generate	save_session	lines 227-231
固定边	generate_skeleton	refine_layout	line 233
固定边	refine_layout	map_fields	line 234
条件边	map_fields	save_session	lines 235-239
条件边	modify_jrxml	save_session	lines 242-246
条件边	handle_undo	save_session	lines 249-253
条件边	save_session	validate / finalize	lines 256-260
条件边	validate	finalize / explain_error	lines 263-267
条件边	explain_error	correct_jrxml	lines 268-272
条件边	correct_jrxml	validate / finalize	lines 273-277
固定边	handle_consult	finalize	line 280
固定边	handle_reset	finalize	line 281
固定边	finalize	END	line 284