agent_jrxml/README.md

JRXML 生成代理

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

功能

• 多轮聊天：通过对话优化报表 -- 添加列、更改标题、添加汇总
• 自动验证：每次生成或修改后都会验证 JRXML
• 自动修正：如果验证失败，代理会分析错误并自动修正（最多 3 次）
• 模板检索：使用 Chroma 向量数据库检索相关的 JRXML 示例以获得更好的生成效果
• 文件上传：支持图片（OCR识别）、PDF、Word、Excel、文本文件等
• 聊天粘贴/拖拽：支持直接在对话框中 Ctrl+V 粘贴或拖拽文件（图片/PDF/Excel/Word）
• 单据OCR识别：上传报表单据图片后自动提取所有字段（4策略优先级 + 置信度评分）
• 批注检测：识别手写单据上的圈选和箭头标记，自动定位用户要修改的字段
• 分层精确生成：A4 报表图片先提取布局 schema，再分 3 阶段（骨架→精调→字段映射）生成，避免 OCR 元素过多导致 prompt 溢出
• 下载：导出已验证的、可供 JasperReports 使用的 JRXML 文件

架构

前端 (Vue 3 + Vite, 端口 5173)
  │ 聊天界面 + SSE 流式显示 + 文件上传/粘贴/拖拽
  ▼ HTTP + SSE
后端 API (FastAPI, 端口 8000)
  │ REST 接口 + SSE 流式推送
  │ 包装 LangGraph Agent ──► agent/
  │   ├─ retrieve (Chroma/embeddings)
  │   ├─ generate / generate_skeleton → refine_layout → map_fields (分层生成)
  │   ├─ validate (FastAPI service)
  │   ├─ explain + correct (auto-fix loop)
  │   └─ modify (multi-turn edits)
  ▼
FastAPI 验证服务 (:8001)
  └─ Structural checks + XSD schema validation

前置要求

• Python 3.11+
• 完整的编译验证需要：JDK 21 + JasperReports 7.0.6
• OpenAI 兼容的 API 密钥（或本地 Ollama）

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境

cp .env.example .env

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

3. 初始化知识库

python scripts/init_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。

验证服务（当前限制）

由于完整的 JasperReports 7.0.6 编译需要 JDK 21，当前的验证执行以下检查：

1. 结构检查：字段声明一致性、SQL 查询存在性、页面尺寸、报表名称
2. XSD schema 验证：如果 validation_service/schemas/jasperreport_7_0_6.xsd 可用

要进行完整的编译验证，请将 jasper-validator.jar 放在 validation_service/ 目录并更新 main.py。

测试

pytest tests/test_validation.py -v
pytest tests/test_agent.py -v
pytest tests/ -v

项目结构

jrxml-agent/
  api_server.py              FastAPI SSE 后端（REST + 流式推送）
  start.bat                  一键启动脚本
  stop.bat                   一键停止脚本
  frontend/                  Vue 3 + Vite 前端（聊天 UI）
    src/
      api/client.ts           SSE 客户端 + fetch 封装
      stores/                 Pinia 状态管理（chat + session）
      components/             聊天界面组件（6 个）
  agent/
    state.py                 AgentState 定义（28 字段）
    nodes.py                图节点（generate, generate_skeleton, refine_layout 等，18 节点）
    graph.py                LangGraph 状态机（含分层生成路由）
  backend/
    llm.py                  LLM 工厂（Anthropic SDK / OpenAI / Ollama）
    logger.py               集中日志模块（JSON + trace_id）
    embeddings.py           嵌入模型工厂
    validation.py           验证服务客户端
    rag_adapter.py          RAG 语义搜索适配器
    error_kb.py             错误自增长知识库
    file_parser.py          文件解析器（PDF/DOCX/XLSX/XLS/DOC/图片/文本）
    layout_analyzer.py      A4 模板布局分析（含布局 schema 提取）
    ocr_extractor.py        OCR 字段精确提取（4 策略 + 置信度）
    annotation_detector.py  批注检测（圈选 + 箭头 + OCR 关联）
    session.py              会话持久化 CRUD
  prompts/
    loader.py               Prompt 加载器（热重载）
    *.md                    10 个 Prompt 模板文件
  validation_service/
    main.py                 FastAPI 验证服务器
    validate.bat            Windows 启动器
  data/
    sample_templates/       知识库的 JRXML 模板
    corrections/            错误修正案例
  logs/
    app.log                 应用日志（节点流转、路由、用户交互）
    llm.log                 LLM 调用日志（完整 prompt / response）
  scripts/
    init_kb.py              Chroma 知识库初始化脚本
  tests/
    test_validation.py      验证服务测试
    test_agent.py           代理集成测试
    test_e2e_ocr.py         OCR 端到端测试
    test_ocr_extraction.py  OCR 字段提取单元测试
    test_annotation_detector.py 批注检测测试
    test_file_parser_formats.py 多格式解析测试
    test_layered_generation.py 分层生成测试
  requirements.txt
  .env.example
  README.md

环境变量

变量	描述	默认值
LLM_BACKEND	cloud 或 local	cloud
LLM_PROVIDER	openai 或 anthropic	openai
OPENAI_API_KEY	API 密钥（OpenAI 或 MiniMax）	-
OPENAI_BASE_URL	API 基础 URL	https://api.openai.com/v1
ANTHROPIC_API_KEY	Anthropic 兼容 API 密钥（优先）	-
ANTHROPIC_BASE_URL	Anthropic 兼容 Base URL	https://api.minimaxi.com/anthropic
LLM_MODEL	模型名称	MiniMax-M2.7
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	Chroma 存储位置	./db/chroma
MAX_RETRY	自动修正尝试次数	3
CONTEXT_MAX_TOKENS	上下文压缩阈值	6000
LOG_DIR	日志目录	./logs
LOG_LEVEL	日志级别	DEBUG
SESSIONS_DIR	会话持久化目录	./sessions