panda
573ce012e7
- README.md: complete overhaul — project structure, architecture, env vars, test listing, Java/JDBC pipeline - CLAUDE.md: fix field count (~28→~40), migrate Streamlit references to Vue 3, update known issues - frontend/README.md: add missing StreamingMessage.vue and NodeProgress.vue components
240 lines
10 KiB
Markdown
240 lines
10 KiB
Markdown
# 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. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 配置 API 密钥和偏好设置。
|
||
|
||
### 3. 初始化知识库
|
||
|
||
```bash
|
||
python scripts/init_default_kb.py
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
**一键启动（推荐）**：双击 `start.bat`，自动启动验证服务、后端 API、前端开发服务器。停止用 `stop.bat`。
|
||
|
||
**手动启动**（需要三个终端）：
|
||
|
||
```bash
|
||
# 终端 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 |
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 全部单元 + 集成测试
|
||
cd D:\Idea Project\jaspersoft && python -m pytest tests/ -v
|
||
|
||
# 仅 E2E 测试（需要前端 dev server 运行）
|
||
cd frontend && npx playwright test
|
||
```
|