panda
067880bf2e
新增: - backend/logger.py — 集中日志模块 (JSON格式 + trace_id + 独立llm.log) - @log_node / @_log_route 装饰器覆盖17个节点和8个路由 改进: - backend/llm.py — _LLMLoggingWrapper 自动记录LLM输入输出 - backend/llm.py — API Key优先读ANTHROPIC_API_KEY，模型名改为MiniMax-M2.7 - backend/llm.py — get_llm() 新增caller参数标识调用来源 - backend/validation.py — 新增验证结果/连接失败日志 - backend/session.py — 新增会话创建/删除日志 - app.py — 新增用户交互日志 (输入/执行/异常/会话操作) - app.py — 提前导入torchvision抑制transformers懒加载报错 - .env.example — 新增LOG_DIR/LOG_LEVEL/ANTHROPIC_API_KEY等配置项 - .gitignore — 新增logs/和db/忽略规则 文档: - ROADMAP.md — 新增阶段四: 可观测性 - README.md — 补充日志架构/LLM配置/项目结构 - CLAUDE.md — 同步最新配置/日志/MAX_RETRY(3) - CODE_GUIDE.md — 新增第15章日志系统，更新架构图/LLM/配置
166 lines
5.0 KiB
Markdown
166 lines
5.0 KiB
Markdown
# JRXML 生成代理
|
||
|
||
一个本地桌面应用程序，帮助非技术用户通过多轮自然语言对话创建 JasperReports 模板（JRXML）。
|
||
|
||
## 功能
|
||
|
||
- **多轮聊天**：通过对话优化报表 -- 添加列、更改标题、添加汇总
|
||
- **自动验证**：每次生成或修改后都会验证 JRXML
|
||
- **自动修正**：如果验证失败，代理会分析错误并自动修正（最多 3 次）
|
||
- **模板检索**：使用 Chroma 向量数据库检索相关的 JRXML 示例以获得更好的生成效果
|
||
- **下载**：导出已验证的、可供 JasperReports 使用的 JRXML 文件
|
||
|
||
## 架构
|
||
|
||
```
|
||
Streamlit 界面 (app.py)
|
||
|
|
||
LangGraph 代理 (agent/)
|
||
|-- retrieve (Chroma/embeddings)
|
||
|-- generate (LLM)
|
||
|-- validate (FastAPI service)
|
||
|-- explain + correct (auto-fix loop)
|
||
|-- modify (multi-turn edits)
|
||
|
|
||
FastAPI 验证服务 (:8001)
|
||
|-- Structural checks (field references, SQL, page dimensions)
|
||
|-- XSD schema validation (if jasperreport.xsd available)
|
||
```
|
||
|
||
## 前置要求
|
||
|
||
- Python 3.11+
|
||
- 完整的编译验证需要：JDK 21 + JasperReports 7.0.6
|
||
- OpenAI 兼容的 API 密钥（或本地 Ollama）
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 配置您的 API 密钥和偏好设置。
|
||
|
||
### 3. 初始化知识库
|
||
|
||
```bash
|
||
python scripts/init_kb.py
|
||
```
|
||
|
||
### 4. 启动验证服务
|
||
|
||
在一个终端中运行：
|
||
```bash
|
||
python -m uvicorn validation_service.main:app --port 8001
|
||
```
|
||
|
||
### 5. 启动 Streamlit 界面
|
||
|
||
在另一个终端中运行：
|
||
```bash
|
||
streamlit run app.py
|
||
```
|
||
|
||
在浏览器中打开 http://localhost:8501。
|
||
|
||
## 使用示例
|
||
|
||
第一轮 - 生成：
|
||
> "创建员工名册，包含 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`。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
pytest tests/test_validation.py -v
|
||
pytest tests/test_agent.py -v
|
||
pytest tests/ -v
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
jrxml-agent/
|
||
app.py Streamlit 聊天界面
|
||
agent/
|
||
state.py AgentState 定义
|
||
nodes.py 图节点（generate, validate, modify 等）
|
||
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/图片）
|
||
layout_analyzer.py A4 模板布局分析
|
||
session.py 会话持久化 CRUD
|
||
prompts/
|
||
loader.py Prompt 加载器（热重载）
|
||
*.md 7 个 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 代理集成测试
|
||
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 |
|