JRXML 生成代理

一个本地桌面应用程序，通过多轮自然语言对话帮助非技术用户创建 JasperReports 模板（JRXML）。

功能

• 多轮对话：通过对话优化报表 — 添加列、更改标题、添加汇总
• 自动验证：每次生成或修改后验证 JRXML（结构检查 + XSD 校验 + 像素级对比）
• 自动修正：验证失败时分析错误并自动修正（最多 5 次）
• 错误自增长知识库：修正案例指纹去重入库，避免重复犯错
• 模板检索：ChromaDB 语义搜索 JRXML 示例和中文文档
• 文件上传：对话框拖拽/粘贴/选择，支持图片、PDF、Word、Excel、文本
• 单据 OCR 识别：上传报表图片后自动提取字段（4 策略优先级 + 置信度）
• 批注检测：识别手写单据上的圈选和箭头标记
• 分层精确生成：3 阶段管线（骨架→精调→字段映射），Band 级窗口化防止内容丢失
• 多租户知识库：独立 KB 管理，含字段定义 + JRXML 模板 + ChromaDB 向量检索
• Java 渲染管线：JRXML → PNG 渲染 + SSIM 像素级对比
• 下载：导出经过验证的 JRXML 文件，含历史版本追溯

架构

前端 (Vue 3 + Vite, 端口 5173)
  │ Pinia stores (chat / session / kb)
  │ 9 components (Sidebar, ChatMessages, ProcessSection, UnifiedInput,
  │   SummaryCard, KbSelector, KbManager, StreamingMessage, NodeProgress)
  ▼ HTTP + SSE (Server-Sent Events)
后端 API (FastAPI, 端口 8000)
  │ REST + SSE 流式推送
  │ 包装 LangGraph Agent ──► agent/ (18 节点状态机)
  │   ├─ process_input (文件解析 + OCR + 批注检测)
  │   ├─ manage_context (token 计数 + 压缩)
  │   ├─ classify_intent (8 类意图识别)
  │   ├─ retrieve (RAG + 错误 KB + KB 模板搜索)
  │   ├─ generate / generate_skeleton → refine_layout → map_fields
  │   ├─ validate (XSD + 结构 + 像素对比)
  │   ├─ explain_error + correct_jrxml (自动修正循环, 最多 5 次)
  │   └─ modify_jrxml / consult / undo / reset / preview / finalize
  ├── backend/ 服务层
  │   ├─ llm (Anthropic SDK / OpenAI / Ollama)
  │   ├─ session (原子 JSON 持久化)
  │   ├─ validation (验证服务客户端)
  │   ├─ kb_manager / kb_parser / kb_searcher (多租户知识库)
  │   ├─ field_matcher (OCR↔KB 字段匹配)
  │   ├─ ocr_extractor / layout_analyzer / annotation_detector (OCR 管线)
  │   ├─ rag_adapter / error_kb / embeddings (向量检索)
  │   └─ file_parser / logger / jrxml_reorder
  ▼
FastAPI 验证服务 (:8001)
  └─ 结构检查 + XSD Schema + 最小内容校验

前置要求

• Python 3.11+
• JDK 21+（Java JRXML→PNG 渲染管线使用）
• Anthropic 兼容 API 密钥（MiniMax M2.7 等）

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境

cp .env.example .env

编辑 .env 配置 API 密钥和偏好设置。

3. 初始化知识库

python scripts/init_default_kb.py

4. 启动服务

一键启动（推荐）：双击 start.bat，自动启动验证服务、后端 API、前端开发服务器。停止用 stop.bat。

手动启动（需要三个终端）：

# 终端 1 — 验证服务（必须先启动）
python -m uvicorn validation_service.main:app --port 8001 --host 0.0.0.0

# 终端 2 — 后端 API（SSE + REST）
python -m uvicorn api_server:app --port 8000 --host 0.0.0.0

# 终端 3 — 前端开发服务器
cd frontend && npm install && npm run dev

浏览器打开 http://localhost:5173。

使用示例

第一轮 - 生成：

"创建员工名册，包含 employee_id、name、department 和 hire_date 字段"

第二轮 - 修改：

"在页脚添加页码"

第三轮 - 修改：

"将标题改为 '2024 员工目录' 并加粗"

每一轮自动验证和修正 JRXML。上传报表图片后自动触发 OCR 识别 + 分层精确生成。

项目结构

jaspersoft/
  api_server.py                 FastAPI SSE 后端（REST + 流式推送）
  start.bat / stop.bat          一键启停脚本
  start.py                      Python 启动器

  agent/                        LangGraph 工作流引擎
    state.py                    AgentState 类型定义（~40 字段）
    nodes.py                    18 个工作流节点实现
    graph.py                    状态图编译 + 9 个路由函数
    datasource.py               数据源模式解析（参数 vs JDBC）
    jrxml_windower.py           Band 级拆解/切分/重组引擎

  backend/                      后端服务层
    llm.py                      LLM 工厂（Anthropic SDK / OpenAI / Ollama）
    logger.py                   结构化 JSON 日志（trace_id + UTC+8）
    validation.py               验证服务 HTTP 客户端
    session.py                  会话 JSON 原子持久化 CRUD
    embeddings.py               嵌入模型工厂（HuggingFace / OpenAI）
    rag_adapter.py              RAG 语义搜索适配器
    error_kb.py                 错误自增长知识库（指纹去重 + ChromaDB）
    file_parser.py              多格式文件解析（PDF/DOCX/XLSX/XLS/DOC/图片/文本）
    layout_analyzer.py          A4 模板布局分析（布局 schema 提取 + 列聚类）
    ocr_extractor.py            OCR 字段精确提取（4 策略 + 置信度）
    annotation_detector.py      批注检测（圈选 + 箭头 + OCR 关联）
    kb_manager.py               多租户知识库 CRUD（用户 + KB）
    kb_parser.py                KB 解析管道（解析→chunk→embed）
    kb_searcher.py              Per-KB ChromaDB 搜索适配器
    field_matcher.py            OCR↔KB 字段匹配（Embedding + LLM 两阶段）
    jrxml_reorder.py            JRXML 元素重排序（XSD sequence 合规）

  prompts/                      LLM Prompt 模板（热重载）
    loader.py                   Prompt 加载器
    *.md                        10 个 Prompt 模板文件

  frontend/                     Vue 3 + Vite 前端
    src/
      api/client.ts             SSE 客户端 + fetch 封装
      stores/
        chat.ts                 Pinia: 消息/流式/节点进度
        session.ts              Pinia: 会话管理
        kb.ts                   Pinia: 知识库状态
      components/
        Sidebar.vue             会话列表 + 下载 + 历史版本
        ChatMessages.vue        消息列表渲染
        ProcessSection.vue      过程折叠区（<details>/<summary>）
        StreamingMessage.vue    流式消息显示
        NodeProgress.vue        节点进度指示器
        UnifiedInput.vue        统一输入框（文本 + 文件拖拽/粘贴/芯片）
        SummaryCard.vue         结果摘要卡片（含耗时）
        KbSelector.vue          KB 下拉选择器
        KbManager.vue           KB 管理面板（上传/构建/删除）

  validation_service/           独立验证服务（端口 8001）
    main.py                     FastAPI 验证端点
    schemas/
      jasperreport_7_0_6.xsd   JasperReports XSD Schema

  lib/java/                     Java JRXML 渲染管线
    JrxmlRenderer.java          JRXML → PNG 渲染器
    JrxmlDebug.java             诊断工具
    JrxmlGen.java               参考：程序化 JasperDesign
    jasperreports-6.21.0.jar   核心 JasperReports 库

  tests/                        Python 测试（19 文件, ~385 测试）
    test_session.py             会话 CRUD（27）
    test_ocr_extraction.py      OCR 字段提取（49）
    test_jrxml_windower.py      Band 窗口化（28）
    test_api_integration.py     API 集成（25）
    test_error_kb.py            错误 KB（24）
    test_programmatic_map_fields.py  字段映射（20）
    test_layered_generation.py  分层生成（19）
    test_annotation_detector.py 批注检测（7）
    test_validation.py          验证服务（6）
    test_file_parser_formats.py 文件解析（4）
    test_e2e_ocr.py             OCR E2E（3）
    test_agent.py / test_kb_*.py /

  data/
    sample_templates/           JRXML 样本模板
    corrections/                错误修正案例

  scripts/
    init_default_kb.py          多租户默认知识库初始化

环境变量

变量	描述	默认值
LLM_BACKEND	LLM 后端: cloud / local	cloud
LLM_PROVIDER	云端提供商: anthropic / openai	anthropic
ANTHROPIC_API_KEY	Anthropic 兼容 API 密钥（优先）	-
ANTHROPIC_BASE_URL	Anthropic 兼容 Base URL	https://api.minimaxi.com/anthropic
OPENAI_API_KEY	OpenAI 兼容 API 密钥（fallback）	-
OPENAI_BASE_URL	OpenAI 兼容 Base URL	https://api.openai.com/v1
LLM_MODEL	模型名称	MiniMax-M2.7
LLM_MAX_TOKENS	默认 max_tokens（各节点可覆盖）	8192
LOCAL_LLM_MODEL	Ollama 模型	qwen2.5-coder:7b
EMBED_BACKEND	嵌入模型后端: local / cloud	local
LOCAL_EMBED_MODEL	本地嵌入模型	Qwen/Qwen3-Embedding-0.6B
VALIDATION_SERVICE_URL	验证服务端点	http://localhost:8001/validate
CHROMA_PERSIST_DIR	ChromaDB 持久化目录	./db/chroma
MAX_RETRY	自动修正最大尝试次数	5
CONTEXT_MAX_TOKENS	上下文压缩阈值	6000
CONTEXT_KEEP_RECENT	保留最近 N 轮对话	4
SESSIONS_DIR	会话持久化目录	./sessions
LOG_DIR	日志目录	./logs
LOG_LEVEL	日志级别	DEBUG
HISTORY_MAX_SNAPSHOTS	状态快照保留数	10
OCR_USE_GPU	OCR GPU 加速	false
OCR_CONFIDENCE_THRESHOLD	OCR 置信度最低阈值	0.5
RAG_EMBED_MODEL	RAG 嵌入模型	paraphrase-multilingual-MiniLM-L12-v2
RAG_JRXML_SOURCE	JRXML 模板源目录	./rag/jrxml_source
RAG_COLLECTION_NAME	ChromaDB 集合名	jrxml_chunks

测试

# 全部单元 + 集成测试
cd D:\Idea Project\jaspersoft && python -m pytest tests/ -v

# 仅 E2E 测试（需要前端 dev server 运行）
cd frontend && npx playwright test