agent_jrxml/CLAUDE.md

# CLAUDE.md — JRXML 生成代理

## 项目概述

一个**本地桌面应用**，通过自然语言多轮对话帮助非技术用户创建 JasperReports 模板（JRXML 文件）。核心技术栈：Vue 3 前端 + FastAPI SSE 后端 + LangGraph 状态机 + LLM 生成/修改 + 自动验证修正循环。

**一句话**：用户用中文描述报表需求 → LLM 生成 JRXML → 自动验证 → 失败则自动修正(最多5次) → 重试耗尽后失败上下文自动注入下一轮 → 返回可编译的 JRXML 文件。

## 启动命令

**方式 1 — 一键启动（Windows）**：双击 `start.bat`，自动打开三个窗口分别运行验证服务、后端 API、前端开发服务器。停止用 `stop.bat`。

**方式 2 — 手动启动**：
```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 run dev
```

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

## 当前配置（.env）

- **OCR**: PaddleOCR（精确识别首选，ppocr-v4）→ EasyOCR（回退，ch_sim+en），两者均未安装时仅返回图片元信息
- **LLM**: `cloud` / `anthropic` → MiniMax Anthropic 兼容 API (`MiniMax-M2.7`)
  - Base URL: `https://api.minimaxi.com/anthropic`
  - 认证: Anthropic SDK 自动读取 `ANTHROPIC_API_KEY`（fallback `OPENAI_API_KEY`）
- **嵌入模型**: `local` / `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`
- **向量库**: ChromaDB 持久化在 `./db/chroma`
- **验证服务**: FastAPI `localhost:8001`
- **日志**: JSON 格式化，`logs/app.log` + `logs/llm.log`，中国时区 (UTC+8)
- **MAX_RETRY**: 5

## 架构

```
前端 (Vue 3 + Vite, 端口 5173)
  │ src/
  │ ├── api/client.ts        SSE 客户端 + fetch 封装
  │ ├── stores/chat.ts       Pinia: 消息/流式/节点进度
  │ ├── stores/session.ts    Pinia: 会话管理
  │ ├── stores/kb.ts         Pinia: KB 状态管理（多租户知识库）
  │ ├── components/
  │ │   ├── Sidebar.vue       会话列表 + 下载 + 历史版本
  │ │   ├── ChatMessages.vue  消息列表渲染
  │ │   ├── ProcessSection.vue 过程折叠区（替代 StreamingMessage + NodeProgress）
  │ │   ├── UnifiedInput.vue  统一输入框（文本+文件拖拽/粘贴/芯片，含 .jrxml）
  │ │   ├── SummaryCard.vue   结果摘要卡片（含耗时）
  │ │   ├── KbSelector.vue    KB 下拉选择器（对话中切换知识库）
  │ │   └── KbManager.vue     KB 管理面板（创建/上传/构建/删除）
  │ └── utils/format.ts      工具函数
  │
  ▼ HTTP + SSE (Server-Sent Events)
  │
api_server.py (FastAPI, 端口 8000)
  │ POST /api/sessions/{id}/chat  → SSE 流式响应
  │ CRUD /api/sessions/...        → 会话管理
  │ POST /api/upload              → 文件上传
  │ GET  /api/download/...        → JRXML 下载
  │ GET  /api/health, /api/config
  │
  │ 包装 LangGraph Agent（不变）──► agent/
  ▼
validation_service/ (FastAPI, 端口 8001) — 不变
```

## 关键文件映射

| 文件 | 职责 | 修改频率 |
|------|------|---------|
| `api_server.py` | FastAPI SSE 后端，REST API + 流式推送 | **高** |
| `frontend/src/` | Vue 3 聊天 UI（替代旧 app.py） | **高** |
| `agent/state.py` | AgentState 类型定义（~28 字段） | 低 |
| `agent/nodes.py` | 18 个工作流节点 + 流式生成 + 错误记录 | **高** |
| `agent/graph.py` | 状态图编译 + 路由函数 + node_start 回调 | 中 |
| `prompts/loader.py` | Prompt 加载器（从 .md 文件热重载） | 低 |
| `prompts/*.md` | 10 个独立 Prompt 模板 | **高** |
| `backend/llm.py` | LLM 工厂，统一 `_BaseLLM` 接口（invoke + stream）+ `_LLMLoggingWrapper` | 中 |
| `backend/logger.py` | 集中日志模块：JSON 格式化 + trace_id + 独立 llm.log | 低 |
| `backend/rag_adapter.py` | RAGSearcher 单例，语义搜索接口 | 中 |
| `backend/error_kb.py` | ErrorKB — 错误指纹去重 + ChromaDB 持久化 + 语义检索 | 中 |
| `backend/file_parser.py` | 文件解析: PDF/DOCX/XLSX/XLS/DOC/图片(EasyOCR→PaddleOCR回退)/文本 | 中 |
| `backend/layout_analyzer.py` | A4模板分析: 比例检测/EasyOCR→PaddleOCR元素提取/行分组/JRXML行匹配/布局schema提取 | 中 |
| `backend/ocr_extractor.py` | OCR字段精确提取: 4策略(exact→kv_pair→regex→table_match) + 置信度 | 中 |
| `backend/annotation_detector.py` | 批注检测: 圈选(cv2 HoughCircles) + 箭头(HoughLinesP聚类) + OCR关联 + LLM格式化 | 中 |
| `backend/embeddings.py` | 嵌入模型工厂 (HuggingFace/OpenAI) | 低 |
| `backend/validation.py` | 验证服务 HTTP 客户端 | 低 |
| `backend/session.py` | 会话 JSON 文件 CRUD（含 kb_id） | 低 |
| `backend/kb_manager.py` | 用户+知识库 CRUD（多租户，原子 JSON 持久化） | 中 |
| `backend/kb_searcher.py` | 知识库隔离搜索 + 模板检索（per-KB ChromaDB） | 中 |
| `backend/kb_parser.py` | KB 解析管道：文件解析→字段提取→chunk切割→向量嵌入 | 中 |
| `backend/field_matcher.py` | OCR↔KB 字段匹配：Embedding 粗筛 + LLM 精确确认 | 中 |
| `agent/datasource.py` | 数据源模式解析：$P{{xxx}} 参数 vs JDBC 直连 | 低 |
| `agent/jrxml_windower.py` | JRXML Band 级窗口化引擎：拆解/切分/重组/元素计数校验 | 中 |
| `validation_service/main.py` | FastAPI 验证服务 | 低 |
| `scripts/init_default_kb.py` | 多租户默认 KB 初始化（默认用户 + 预置 KB） | 低 |

## 关键约定

1. **LLM 调用接口**: 所有节点通过 `get_llm().invoke(prompt)` 同步调用，或用 `get_llm().stream(prompt)` 流式调用。三个后端（Anthropic/OpenAI/Ollama）通过 `_BaseLLM` 统一接口。

2. **流式生成**: generate/modify_jrxml/correct_jrxml 使用 `get_stream_writer()` 发射自定义事件，UI 通过 `stream_mode=["updates", "custom"]` 捕获逐字输出。

3. **JRXML 提取**: `_extract_jrxml()` 处理 LLM 响应 —— 去掉 markdown 代码块标记，提取 XML 内容。

4. **状态持久化**: 每个会话存为 `sessions/{session_id}.json`，LangGraph 节点间通过 AgentState dict 传递。

5. **Token 计数**: 使用 `tiktoken` (gpt-4o encoder) 估算，不管实际模型是什么。

6. **RAG 子模块**: `rag/` 是一个独立的 git submodule，其内部的生成产物 (`models/`, `embeddings/`, `chroma_db/`, `jrxml_source_chunks/`) 不在 git 中。

## Prompt 模板位置

所有 Prompt 在 `prompts/` 目录，`.md` 文件可直接编辑，无需重启应用：

| 文件 | 用途 |
|------|------|
| `prompts/intent_classify.md` | 8 分类意图识别 |
| `prompts/initial_generation.md` | 首次生成 JRXML |
| `prompts/modification.md` | 修改现有 JRXML |
| `prompts/correction.md` | 自动修正错误 |
| `prompts/explain_error.md` | 错误转人话 |
| `prompts/compression.md` | 对话压缩摘要 |
| `prompts/consult.md` | 咨询解答 |
| `prompts/skeleton_generation.md` | 分层生成-骨架 |
| `prompts/refine_layout.md` | 分层生成-精调 |
| `prompts/field_mapping.md` | 分层生成-字段映射 |

## 新增功能 (v2)

### 流式输出 + 节点平铺
- LLM 生成时逐字展示 XML（不再是空白等待）
- 节点以"处理过程"折叠区展开，不相互覆盖
- 完成后自动折叠，展示总结卡片

### 错误自增长知识库
- `backend/error_kb.py` — ChromaDB 集合 `jrxml_error_cases`
- 错误指纹去重（标准化 + MD5）：相同结构错误不重复录入
- 记录内容：错误信息 + 修正前后 JRXML + 修正 prompt + 工具链
- `retrieve` 节点自动注入历史修正案例
- 流程：correct_jrxml 保存 last_error_case → validate 通过时自动入库

### 文件上传
- **对话区域上传（v3）**: `st.file_uploader` 位于聊天输入框上方，支持图片/PDF/DOCX/XLSX/文本
- **粘贴/拖拽（v3）**: 全局 paste/drop 事件监听 + `sessionStorage` + 轮询桥接组件，Ctrl+V 粘贴或拖拽文件到页面任意位置
- **文件预览芯片（v3）**: 上传后显示在对话区域，可逐文件移除（自动清理临时文件）
- 侧边栏多文件上传（可逐文件移除，向后兼容保留）
- 支持: PDF(pdfplumber+PIL) / DOCX(python-docx) / XLSX(openpyxl, v3) / 图片(PIL+EasyOCR优先→PaddleOCR回退) / 纯文本
- 上传文本自动注入下一条消息前缀
- 根据 `can_use_vision()` 判断是否走原生多模态（当前 MiniMax 不支持）

### 对话区域文件粘贴/拖拽技术方案（v3）
- `st.html()` 注入全局 paste/drop/dragover 监听器 → 文件转 base64 → 写入 `sessionStorage`
- `components.html(height=0)` 桥接组件每 800ms 轮询 `sessionStorage` → `Streamlit.setComponentValue` 回传 Python
- Python 解码 base64 → 临时文件 → `parse_file` + `analyze_layout` 双层 OCR 解析
- 上限：单文件 20MB，单次最多 10 个文件

### A4 模板识别
- `backend/layout_analyzer.py` — 三种处理路径：
  - **完整 A4**: 比例匹配 + OCR 元素 → 全量布局描述
  - **行片段 + 有现有报表**: 行匹配到 JRXML section → 定位修改
  - **行片段 + 无现有报表**: 按 A4 模板生成完整报表
- PaddleOCR（可选安装）提供精确元素位置/字号
- 行分组：Y 轴容差自动聚类；行匹配：文本相似度搜索 JRXML band

### 会话历史下载
- `AgentState.jrxml_versions` 追踪每次生成/修改的版本
- 侧边栏"历史版本"折叠区，每版本独立下载按钮

### 预览修复
- `route_after_save` 新增意图判断：预览/导出跳过验证直通 finalize

### Ctrl+C 修复
- JS 注入拦截 Streamlit 裸 `c` 键清缓存，保留 Ctrl+C 复制

### 结构化日志系统
- `backend/logger.py` — JSON 格式化 + trace_id + 国际时区
- `_LLMLoggingWrapper` — 包装所有 LLM 后端，记录完整 prompt/response
- `@log_node` / `@_log_route` — 装饰器自动记录节点和路由
- 日志分离: `logs/app.log` (业务) + `logs/llm.log` (AI 调用)

## 新增功能 (v3/v4)

### OCR 单据字段精确提取 (v3)
- `backend/ocr_extractor.py` — 4 策略优先级提取: exact_match → kv_pair → regex → table_match
- PaddleOCR 首次识别后将原始结果（含所有文本元素 + bbox坐标）持久化
- `_format_ocr_context()` — 将 OCR 结果（字段 + 原始元素坐标）格式化为 LLM prompt 注入
- OCR 结果在 `modify_jrxml` 和 `generate` 节点中自动注入 prompt
- `process_input` 节点在上传图片时自动触发 OCR 字段提取
- 结果持久化到会话文件（`save_session_node` / `load_session_node`）

### 多模态聊天输入 + 多格式文件 (v4)
- `app.py` — `st.chat_input` 替换为 `st_multimodal_chatinput`（支持 Ctrl+V 粘贴 + 拖拽 + 文件按钮）
- `_process_uploaded_file()` — 提取共享文件处理逻辑（侧边栏 + 聊天共用，消除 ~70 行重复代码）
- 新增文件格式支持: XLSX (openpyxl)、XLS (xlrd)、DOC (olefile)
- 剪贴板粘贴文件通过 base64 解码 + MIME type → 扩展名推断
- 侧边栏上传器类型列表中新增 xlsx/xls/doc

### 批注检测 (v4)
- `backend/annotation_detector.py` — 识别用户在手写单据上的圈选和箭头标记
- **圆圈检测**: 红色通道增强 → HoughCircles → 圆形度验证
- **箭头检测**: Canny边缘 → HoughLinesP → 线段方向聚类 → 端点边缘密度判定方向
- **OCR 关联**: 批注与附近 OCR 文本元素关联（15% 图片尺寸内）
- **LLM 注入**: `format_annotation_context()` 将批注结果格式化为中文提示
- `process_input` 节点在 OCR 提取后自动运行批注检测
- `annotation_result` 字段持久化到 AgentState + 会话文件

### OCR 上下文提示增强 (v3/v4)
- `prompts/modification.md` — 新增 `{ocr_context}` 占位符
- `modify_jrxml` 节点 — 将 OCR 上下文注入 modification prompt
- OCR 上下文包含: 结构化字段、全部文本元素（含坐标）、批注检测结果

## 新增功能 (v5)

### 分层精确生成
- 解决 A4 报表图片 OCR 元素过多（数百个）导致 LLM prompt 超长的问题
- **3 阶段管线**（仅对 `initial_generation` + 有布局 schema 时触发）:
  1. `generate_skeleton` — 压缩的布局 schema → 骨架 JRXML (`$F{field_N}` 占位)
  2. `refine_layout` — 采样坐标（表头+首行数据+末行）→ 像素级位置精调
  3. `map_fields` — OCR 字段名 → 替换占位符
- `backend/layout_analyzer.py` — 新增 `extract_layout_schema()`: 列聚类 + 区域分类 + schema_text
- `agent/graph.py` — 新增 `route_after_retrieve()`: 有 schema 走 3 阶段，无 schema 走原有 1-shot
- `prompts/` — 新增 `skeleton_generation.md`, `refine_layout.md`, `field_mapping.md`
- 文本请求和所有其他意图零行为变更

## 已知注意点

- **环境变量优先级**: `backend/llm.py` 使用 `load_dotenv(override=True)` 确保 `.env` 值**始终覆盖**系统环境变量。曾因系统级 `ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic` 覆盖 `.env` 中的 MiniMax URL，导致 401 认证失败。新增 LLM 相关环境变量时，必须在 `.env` 中显式设置 `ANTHROPIC_*` 变量（而非仅设 `OPENAI_*` fallback），否则残留的系统环境变量会污染请求目标。
- **Anthropic SDK**: 使用原始 `anthropic` 包（非 `langchain-anthropic`），因为需要直连 MiniMax 兼容端点。API Key 优先读 `ANTHROPIC_API_KEY`，fallback `OPENAI_API_KEY`。Anthropic SDK 会自动将 key 放入 `x-api-key` header。
- **MiniMax 模型名称**: `MiniMax-M2.7`（不是 `minimax-2.7`），大小写敏感。
- **Streamlit headless**: Windows 下必须设 `STREAMLIT_SERVER_HEADLESS=true` 跳过邮箱采集提示。
- **日志分析**: 通过 `trace_id` 字段可追踪一次请求的全链路。LLM 调用日志在 `logs/llm.log`，包含完整 prompt 和 response（各截断 10000 字符）。
- **验证服务结构检查**: 字段引用一致性 (`$F{field}` vs `<field>` 声明)、SQL SELECT 存在性、pageWidth/pageHeight/name 属性。
- **XSD 校验可选**: 需要 `validation_service/schemas/jasperreport_7_0_6.xsd` 存在。
- **rag 子模块**: 内部有独立的管线脚本（`batch_chunker.py` → `embed_chunks.py` → `import_to_chroma.py`），通常不需要在主项目中运行。
- **OCR 引擎**: 优先 PaddleOCR 2.9.x（精确识别，`pip install paddleocr`），回退 EasyOCR 1.7+。两者均未安装时仅返回图片元信息。PaddlePaddle 3.x 在 Windows 上有 ONEDNN bug，固定在 2.6.x。
- **OCR 字段提取**: `process_input` 自动检测上传图片，调用 `OcrExtractor` 提取常见中文字段（发票代码/号码/金额/日期等），提取结果自动注入 LLM 上下文。
- **会话持久化**: `session_id` 现已包含在 `save_session_node` 的持久化字段中，避免切换会话时因 `session_id` 丢失导致的无限 rerun bug。`create_session` 存盘前强制写入 `agent_state["session_id"] = sid`。`load_session_node` 不从磁盘覆盖 `session_id`。切换会话增加 `_last_switched_to` 哨兵防止重复触发。
- **MAX_RETRY**: 默认 5 次。重试耗尽后 `pending_failure_context` 记录失败信息，下次用户输入时自动注入。
- **验证最小内容检查**: 验证服务额外检查至少 1 个 `<band>` + 1 个 `<textField>` 或 `<staticText>`，拦截空壳 JRXML。
- **XLSX 支持 (v3)**: 需要 `openpyxl>=3.1.0`（已加入 requirements.txt）。表格按工作表逐行读取，单元格用 `|` 分隔。
- **粘贴功能限制**: 文件以 base64 编码在 sessionStorage 中传递，单文件上限 20MB。大文件建议使用 file_uploader 按钮。
- **torchvision**: `transformers` 库的懒加载需要 `torchvision`，已作为依赖安装。
- **opencv-python-headless**: 批注检测（圈选/箭头）依赖，通过 `pip install -r requirements.txt` 安装。
- **st-multimodal-chatinput**: Streamlit 聊天输入增强组件，替代 `st.chat_input`，支持粘贴/拖拽文件。返回 base64 编码文件内容。
- **xlwt**: 仅在测试中使用（生成 .xls 测试文件）。
- **分层精确生成**: 3 阶段管线仅在 `layout_schema.total_rows > 0` 时触发。文本请求和 `modify_report` 等意图不受影响，走原有 `generate` 节点。中间阶段（骨架/精调）跳过验证，只有最终 mapped 结果进入 `validate`。

## 新增功能 (v6)

### 5-Issue Fix — 图片解析 Bug + 前端功能补全

**Fix 1 — 图片后缀 dot 缺失**: `file_parser.py` 后缀规范化（`"jpg"` → `".jpg"`），`api_server.py` 使用 `Path.suffix` 替代 `rsplit`。所有图片上传之前均因后缀不匹配回退到文本解析器，OCR/布局分析从未实际触发。

**Fix 2 — Vue 前端功能补全**:
- `ProcessSection.vue` 替代 `StreamingMessage.vue` + `NodeProgress.vue`，使用 `<details>`/`<summary>` 原生可折叠区域
- `Sidebar.vue` 新增历史版本下载列表（`jrxml_versions` 索引下载）
- `UnifiedInput.vue` 已集成文件拖拽/粘贴/芯片/移除（v5 已完成）

**Fix 3 — OCR 两层日志**: `agent/nodes.py` 新增 `_log_ocr_layers()` — `[内容层]` OCR 文本+字段提取，`[位置层]` 布局 schema 列×行+区域分类，`[合并]` 管线选择（3阶段 vs 单阶段）

**Fix 4 — 全过程流式输出+自动折叠**:
- `api_server.py` `node_start` 事件携带 `step_index`
- `chat.ts` 新增 `ProcessSection[]` 模型：per-section stream routing、完成自动折叠、运行中自动展开
- `ProcessSection.vue` 渲染步骤编号/标签/耗时/内容（XML 代码高亮）

**Fix 5 — 消息耗时显示**: `api_server.py` `agent_complete` 事件新增 `total_duration_ms`，`SummaryCard.vue` 显示总耗时，`chat.ts` 暴露 `lastDurationMs` + `formatDuration()`


## 已安装的 Claude Code 插件/Skills

| 插件 | 来源 | 关键 Skill |
|------|------|-----------|
| `superpowers` | `obra/superpowers-marketplace` | `tdd-workflow`（红-绿-重构）、`verification-loop`（修复验证）、`systematic-debugging`（根因分析） |
| `example-skills` | `anthropics/skills` | `webapp-testing`（Playwright E2E 浏览器自动化）、`skill-creator` |

**测试工作流**：需求澄清 → TDD 红-绿-重构 → `webapp-testing` 浏览器验证 → `verification-loop` 确认 → 提交。

**E2E 测试前置条件**：Chrome 已安装 (`C:\Program Files\Google\Chrome\Application\chrome.exe`)，Playwright MCP Bridge 扩展需手动安装。

## 更新 (v7 — 2026-05-22)

### 会话持久化 & 多轮对话记忆修复

**原子写入** (`backend/session.py`): `save_session` 改用 tempfile + os.replace 原子写入，防止进程崩溃时 JSON 截断导致会话损坏。

**graph.stream 状态修复** (`api_server.py`): LangGraph 的 `graph.stream()`
只产出事件，不修改传入的 `agent_state`。`_run_graph_sync` 改为手动收集每个节点的
返回 dict 并 `agent_state.update()`，确保 done 事件到达时 agent_state 已是完整状态。
此修复解决了第二次请求时 `current_jrxml` 为空、导致多轮对话"失忆"的问题。

**save_session 调用时机**: 从 `stream_and_save` 末尾移至 `_sse_generator` 中 done 分支
（yield `agent_complete` 之前），消除前端 `refreshFromApi()` 的竞态。

### OCR 管线打通

**uploaded_file_path 传递** (`api_server.py`): `_process_files` 返回的 `uploaded_paths`
注入 `agent_state["uploaded_file_path"]`，使 `process_input` 节点的 `OcrExtractor` 字段
精确提取和 `annotation_detector` 批注检测得以触发。此前 `uploaded_file_path` 始终为空，
第二层 OCR 从未执行。

### 前端体验改进

**下载区常驻** (`Sidebar.vue`): 下载区域始终可见，无文件时显示灰色"暂无下载文件"，
生成完成后自动出现下载链接。

**侧边栏自动刷新** (`stores/session.ts`, `App.vue`): 新增 `refreshFromApi()` 方法，
`agent_complete` 后自动从 API 重新加载会话状态，下载按钮无需手动刷新即可出现。

**节点进度完整展示** (`api_server.py`): 移除 `node_complete` 事件的 SKIP_NODES 过滤，
所有节点（包括加载会话等内部节点）的 start/complete 事件均正常发送，前端可看到
完整流转（running → done）。

### modification_request 宽松化

原有 `status == "pass"` 条件去除：只要 `current_jrxml` 存在即设置
`user_modification_request`，确保修改意图的请求能携带完整上下文。

## 更新 (v8 — 2026-05-22)

### Prompt 花括号转义修复

**问题**: `skeleton_generation.md` 中 `$F{field_1}` 是给 LLM 看的占位字段名指令，
但 Python `.format()` 把 `{field_1}` 当作格式化占位符，因缺少对应 kwarg 抛出 `KeyError: 'field_1'`。
所有图片上传触发的 `generate_skeleton` 节点均因此崩溃。

**修复**: 3 个 prompt 文件中 6 处 `{field_N}` / `{...}` 转义为 `{{field_N}}` / `{{...}}`：
- `prompts/skeleton_generation.md` — `$F{field_1}` → `$F{{field_1}}`
- `prompts/field_mapping.md` — 4 处
- `prompts/refine_layout.md` — 1 处

Python 将 `{{` 输出为字面量 `{`，LLM 看到的内容不变。

## 更新 (v9 — 2026-05-22)

### 测试基础设施全面补齐

**单元测试** (76 测试):
- `tests/test_session.py` — 27 测试：会话 CRUD、原子写入、唯一 ID、损坏 JSON 跳过
- `tests/test_error_kb.py` — 24 测试：指纹去重、关键词提取（中/英/JRXML）、ErrorKB CRUD、搜索、统计
- `tests/test_agent.py` — 5 个软断言强化为严格断言（`status`/`current_jrxml` 存在性检查）
- 已有测试：`test_ocr_extraction.py`（49）、`test_layered_generation.py`（19）、`test_validation.py`（6）、`test_file_parser_formats.py`（4）、`test_annotation_detector.py`（7）、`test_e2e_ocr.py`（3）

**集成测试** (25 测试, `tests/test_api_integration.py`):
- FastAPI TestClient 全覆盖：健康检查、配置、会话 CRUD、文件上传、下载、Chat SSE、安全边界（路径穿越/非法 JSON/大 payload）
- Mock LangGraph graph 避免真实 LLM 调用

**E2E 测试** (8 测试, `frontend/tests/e2e/main-flows.spec.ts`):
- Playwright 浏览器自动化：页面加载、侧边栏、会话管理、聊天流程、输入 UX
- 全量 API Mock（`page.route`）无需后端运行
- 配置: `frontend/playwright.config.ts`, `npm run test:e2e`

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

# 仅 E2E（需要前端 dev server）
cd frontend && npx playwright test
```

### Bug 修复: create_session 参数缺失

`backend/session.py` — `create_session()` 新增可选参数 `session_id: Optional[str] = None`。
`api_server.py:507` 调用 `create_session(session_id=session_id)` 时之前会抛出 `TypeError`。

## 更新 (v10 — 2026-05-23)

### 5-Fix — 生成可靠性全面加固

**问题诊断**: 上传车辆历史卡片图片后，`map_fields` 节点 LLM 返回 0 字符，导致 ~11,500 字符的骨架 JRXML 被空字符串覆盖，修正循环无法恢复，最终输出 934 字符的占位桩（与原始图片内容完全不符）。

**Fix 1 — 空响应保护**: 所有 5 个生成节点（`generate_skeleton`, `refine_layout`, `map_fields`, `modify_jrxml`, `correct_jrxml`）增加空响应守卫。LLM 返回空字符串时拒绝更新 `current_jrxml`，保留前一有效版本。

**Fix 2 — max_tokens 扩容**: `backend/llm.py` — `max_tokens` 从 4096 → 8192。MiniMax-M2.7 支持最大 131K 输出 token，8192 在生成复杂 JRXML（通常 5000-15000 字符）时提供充裕空间。

**Fix 3 — 快照回退**: 5 个生成节点在 LLM 输出 JRXML 短于 200 字符时，回退到生成前的 `prev_jrxml` 版本，防止 LLM 输出无意义短文本污染状态。

**Fix 4 — 修正循环注入 OCR 上下文**: `correct_jrxml` 节点将 OCR 提取结果（`ocr_context`）和布局 schema（`layout_schema_text`）注入修正 prompt。此前修正节点"盲修"——只看到 JRXML 和编译错误，不理解原始单据的字段结构和布局意图。

**Fix 5 — 滚动续写机制**: 当 LLM 输出因 `max_tokens` 限制被截断（JRXML 不以 `</jasperReport>` 结尾），自动发送续写请求（附最后 800 字符锚点），最多 3 轮（1 正常 + 2 续写）。

- `backend/llm.py` — `MiniMaxLLM.stream()` 捕获 `stop_reason`，`_LLMLoggingWrapper` 在 `max_tokens` 截断时记录 WARNING
- `agent/nodes.py` — 新增 `_generate_with_continuation()` 辅助函数，5 个生成节点全部重构使用
- `_extract_jrxml()` — 正则表达式支持命名空间前缀 JRXML（`<\w+:jasperReport`）
- 内容去重：续写文本直接拼接，依赖 `_extract_jrxml` 提取完整 XML

**MAX_RETRY 调整**: 默认值从 3 → 5（环境变量 `MAX_RETRY`），配合续写机制确保复杂报表有充分修正机会。

**JRXML 提取命名空间兼容**: `_extract_jrxml()` 和 `_generate_with_continuation()` 的完整性检查统一支持 `</ns0:jasperReport>` 等命名空间前缀闭合标签。

## 更新 (v11 — 2026-05-23)

### Java 渲染管线 + 像素级对比

**目标**: 将 JRXML 渲染为 PNG 图片，与用户上传的原始图片进行 SSIM（结构相似性）像素级对比。

**Java 依赖** (`lib/java/`):
| JAR | 用途 |
|-----|------|
| `jasperreports-6.21.0.jar` (5.8MB) | 核心库，**必须用 6.x**（7.x 仅支持 Jackson XML 格式） |
| `commons-digester-2.1.jar` | XML 解析（6.x 使用 Digester 2.x） |
| `commons-logging-1.3.5.jar`, `commons-collections4-4.5.0.jar`, `commons-beanutils-1.10.1.jar`, `commons-lang3-3.17.0.jar` | 基础依赖 |
| `itext-2.1.7.jar` | PDF 生成 |
| `jfreechart-1.5.5.jar` | 图表 |
| `ecj-3.38.0.jar` | Eclipse JDT 编译器（报表表达式编译） |

**Java 工具** (`lib/java/`):
| 文件 | 用途 |
|------|------|
| `JrxmlRenderer.java` | JRXML → PNG 渲染器 |
| `JrxmlDebug.java` | 诊断：SAX/JRXmlLoader/compile 三层测试 |
| `JrxmlGen.java` | 参考：程序化构建 JasperDesign → 序列化为 XML |

**Python 渲染封装** (`agent/nodes.py`):
- `_render_jrxml_to_png(jrxml, output_path, scale)` — 调用 Java `JrxmlRenderer`
- `_compute_pixel_similarity(rendered_png, reference_image)` — OpenCV + scikit-image SSIM 对比

**像素对比流程**: validate 节点 XSD 通过 → 有 `uploaded_file_path` → Java 渲染 → SSIM 对比 → SSIM < 0.4 且 diff > 60% → 标记 fail → 注入 correct_jrxml 修正上下文

**手动渲染**: `java -cp ".;jasperreports-6.21.0.jar;..." JrxmlRenderer input.jrxml output.png 2.0`

### 内容保真度 + 修正去重 (v10 补充)

- `_check_ocr_fidelity(jrxml, state)` — OCR 字段名/元素数/列数三重检查
- `correct_jrxml` 去重检测：输入输出相同 → `retry_count += 2`
- `prompts/correction.md` — 一次只修复第1个错误 + 输出不可与输入相同 + 命名空间严格指定
- `prompts/skeleton_generation.md`, `prompts/modification.md` — 明确命名空间约束

### consult_answer 前端显示修复

- `api_server.py` — `agent_complete` SSE 事件新增 `consult_answer` 字段

## 更新 (v12 — 2026-05-23)

### 多租户知识库系统

**核心架构**：用户自行维护多套知识库，每套 KB 拥有独立的文件存储、JSON 元数据和 ChromaDB 向量集合。会话可绑定不同 KB，LLM 基于 KB 中的字段定义和 JRXML 模板生成报表。

**存储架构**：
```
kb_data/
├── users.json                    # 用户注册表
└── {user_id}/
    ├── profile.json
    └── {kb_id}/
        ├── meta.json             # KB 元数据 + 字段定义 + 模板索引
        ├── raw/                  # 原始上传文件
        ├── chunks.json           # RAG chunks（含 JRXML 模板完整文本）
        └── chroma/               # KB 专属 ChromaDB
```

**新增后端模块**：

| 文件 | 职责 |
|------|------|
| `backend/kb_manager.py` | 用户+KB CRUD：create_user/list_users/create_kb/list_kbs/get_kb/delete_kb/update_kb_meta/get_kb_raw_dir/get_kb_chroma_path。原子 JSON 写入（tempfile + os.replace） |
| `backend/kb_parser.py` | KB 解析管道：`parse_jrxml_fields()` XML 提取参数/字段/查询 → `process_file_for_kb()` 处理多种格式（jrxml/zip/tar/pdf/docx/xlsx/md） → `chunk_file_results()` 切割 → `build_kb_from_files()` 全管线（parse→chunk→embed→update meta） |
| `backend/kb_searcher.py` | `KBChromaSearcher` 类：per-KB ChromaDB 懒连接。`search()` 语义搜索、`search_templates()` 仅搜索 JRXML 模板 chunk、`add_chunks()` 向量写入。全局 searcher 缓存 `_searchers: dict` |
| `backend/field_matcher.py` | OCR↔KB 字段匹配：1) Embedding 粗筛（余弦相似度 top-3）2) LLM 精确确认。返回 `{"工单号": "billNo", ...}` 映射 |
| `agent/datasource.py` | 数据源模式：`resolve_datasource_mode()` 检测用户意图 → `"parameter"`（默认 $P{xxx}）或 `"jdbc"`（SQL 直连）。未配置 DB 时生成反问消息 |
| `scripts/init_default_kb.py` | 默认 KB 初始化：创建默认用户 → 解析 `rag/jrxml_source/` 下的 17 个 JRXML + 16 个 MD → chunk + embed → ChromaDB |

**新增 API 端点**（api_server.py）：

```
POST   /api/users                        # 创建用户
GET    /api/users                        # 用户列表
GET    /api/users/{user_id}              # 用户详情
DELETE /api/users/{user_id}              # 删除用户
GET    /api/users/{user_id}/kbs          # KB 列表
POST   /api/users/{user_id}/kbs          # 创建 KB
GET    /api/kbs/{kb_id}                  # KB 详情
DELETE /api/kbs/{kb_id}                  # 删除 KB
POST   /api/kbs/{kb_id}/upload           # 上传文件到 KB
POST   /api/kbs/{kb_id}/build            # 构建 KB（chunk→embed）
GET    /api/kbs/{kb_id}/status           # KB 状态
GET    /api/kbs/{kb_id}/fields           # KB 字段+模板列表
GET    /api/kbs/{kb_id}/search?q=&type=  # KB 语义搜索
PUT    /api/sessions/{session_id}/kb     # 绑定会话-KB
GET    /api/sessions/{session_id}/kb     # 获取会话绑定的 KB
```

**三条模板获取路径**：

1. **管理页预上传**：用户上传文件到 KB → 解析管道 → chunks + ChromaDB → 对话选择 KB → retrieve 节点从 KB 检索
2. **对话框即时上传**：用户拖入 `.jrxml` → `_parse_jrxml_file()` → 注入 `agent_state["uploaded_template_jrxml"]` → 生成节点直接使用该模板
3. **口头引用模板**：用户说"根据标准结算单模板" → `_detect_template_intent()` 正则匹配 → `retrieve()` 在 KB 中搜索模板 → 注入 `kb_template_jrxml`

**模板上下文注入**：所有 6 个生成节点（generate/generate_skeleton/refine_layout/map_fields/modify_jrxml/correct_jrxml）通过 `_build_template_context(state)` 获取模板上下文，优先级：聊天上传 > KB 检索 > KB 字段定义。6 个 prompt 模板全部新增 `{template_context}` 占位符。

**前端新增**：

| 文件 | 职责 |
|------|------|
| `stores/kb.ts` | Pinia store：用户列表、KB 列表、当前选择、字段/模板缓存、CRUD 操作、会话绑定 |
| `components/KbSelector.vue` | 对话顶部 KB 下拉选择器 + 管理按钮 |
| `components/KbManager.vue` | 模态面板：创建 KB、上传文件（支持 .jrxml/.md/.xlsx/.docx/.pdf/.csv/.zip 等）、构建、删除 |

**API Server 增强**：
- `_process_files()` 检测 `.jrxml` 文件 → 提取参数/字段/查询/页面尺寸 → 注入 `uploaded_template_jrxml` + `uploaded_template_params`
- `agent/state.py` 新增 10 个字段：`kb_id`, `kb_fields`, `kb_field_mapping`, `uploaded_template_jrxml`, `uploaded_template_params`, `kb_template_jrxml`, `kb_template_name`, `datasource_mode`, `db_config`

**字段匹配管线**（`_match_ocr_to_kb` → 尚未集成到节点）：OCR 提取中文字段名 → `match_ocr_to_kb()` 两阶段匹配 → 结果为 `{"工单号": "billNo"}` → `format_field_mapping_context()` 注入 prompt → LLM 使用 `$P{billNo}` 而非 `$P{工单号}`

## 更新 (v13 — 2026-05-24)

### 3 阶段管道内容丢失修复 — Band 级窗口化 + 程序化字段映射

**问题**：`generate_skeleton` 生成 34k 字符骨架 JRXML → `refine_layout` 将完整 34k 发给 LLM → LLM 重新生成简化版（~3k 字符，丢失 91.5%）。`map_fields` 同样存在字段映射时内容丢失问题。

**根因**：LLM 看到完整 JRXML 时倾向于"重新生成"而非"在原基础上修改坐标/字段名"。提示词调控无法可靠解决。

**修复方案**（按用户要求 — 程序化节点控制，不靠 LLM 提示词）：

#### `refine_layout`：Band 级窗口化 LLM 精调

新增 `agent/jrxml_windower.py` — JRXML 拆解/切分/重组引擎：

| 函数 | 用途 |
|------|------|
| `decompose_jrxml()` | ET 安全解析 → 分离 header（field 声明/queryString 等，不发给 LLM）+ 所有 band |
| `split_band_into_windows()` | 超过 4000 字符的 band 在元素闭合标签处切分为多个窗口 |
| `reassemble_band_windows()` | 合并同一 band 的多个窗口结果 |
| `reassemble_jrxml()` | header + 所有修改后 band + footer → 完整 JRXML |
| `count_elements()` | 正则计数 textField/staticText/field（兼容命名空间前缀） |
| `validate_element_count()` | 校验元素数变化，>10% 回退到前一版本 |

**LLM 每次只看到 ~2-4k 字符片段**，无法"重写整个报表"。header 部分完全不发给 LLM，原样保留。

#### `map_fields`：完全程序化替换（零 LLM 调用）

`_programmatic_map_fields()` — 纯正则替换 `$F{field_N}` → OCR 真实字段名，100% 确定性。

`_sanitize_field_name()` — 非 ASCII 字符（中文/日文）转义为 `_uXXXX_` Unicode 码点格式，确保 JRXML 合法。

#### 新增测试

| 文件 | 用例数 | 覆盖 |
|------|--------|------|
| `tests/test_jrxml_windower.py` | 28 | 拆解/往返重组/窗口切分/元素计数/命名空间/多 section 多 band |
| `tests/test_programmatic_map_fields.py` | 20 | 字段声明替换/引用替换/中文转义/坐标保留/部分映射/空字段跳过 |

完整测试套件（385 项）无回归。

## 更新 (v14 — 2026-05-24)

### max_tokens per-node + 修正循环死锁修复

**问题 A — max_tokens 自限**: `backend/llm.py` 硬编码 `max_tokens=8192`。MiniMax M2.7 的 reasoning token 吃光 8192 输出预算后骨架生成为空（0 个可见字符）。其他节点（correct_jrxml/modify_jrxml）输入 68K+ 字符时输出也被截断。

**问题 B — ns:field 命名空间前缀正则失配**: `_programmatic_map_fields()` 正则 `<field\b` 匹配不到 `<ns0:field name="field_1">`，导致字段声明保持占位符但引用被替换为 OCR 字段名，校验报"used in expressions but not declared"。

**问题 C — 验证服务 502 修正死循环**: 验证服务（port 8001）未启动时，`validate_jrxml()` 返回 502。错误消息被当作 JRXML 校验错误送入 `explain_error → correct_jrxml`，LLM 尝试"修复"网络错误产出 HTML/markdown 等垃圾，循环 5 轮直到 retry_count 耗尽。

**问题 D — correct_jrxml 从未写回 current_jrxml**: 修正后的 JRXML 只写入 `conversation_history`，从不更新 `state["current_jrxml"]`，导致每轮 validate 看到同一份原始 JRXML，修正完全无效。这是 5 轮 jrxml_length 始终 4441 不变的根本原因。

**修复方案**:

#### 1. per-node max_tokens（`backend/llm.py` + `agent/nodes.py`）
- `get_llm(caller, max_tokens=None)` — 新增可选 `max_tokens` 参数，透传到 `_build_raw_llm`
- `MiniMaxLLM.__init__()` — 存储 `self._max_tokens`
- `LLM_MAX_TOKENS` 环境变量覆盖默认 8192
- 5 个生成节点 max_tokens 提升到 32768：`generate`, `generate_skeleton`, `refine_layout`, `modify_jrxml`, `correct_jrxml`
- `generate_skeleton` 空响应自动重试（max_tokens=65536）

#### 2. ns:field 正则修复（`agent/nodes.py:548`）
- `<field\b` → `<[\w:]*field\b` 兼容 `<ns0:field>`, `<field>` 等所有命名空间前缀

#### 3. 验证服务不可用防护
- `backend/validation.py` — 区分 ConnectError/HTTPStatusError(5xx)：返回 `service_unavailable: True`
- `agent/nodes.py:validate` — 透传 `state["service_unavailable"]`
- `agent/graph.py:route_after_validate` — `service_unavailable` 时直接 `finalize`，不进入修正循环

#### 4. correct_jrxml 输出合法性守卫
- 新增 JRXML 有效性检查：输出不含 `<jasperReport` 且不含 `<?xml` 时，回退到前一版本
- **Bug 修复**: `state["current_jrxml"] = jrxml` 写回修正结果

#### 5. 连续输出提取增强
- `_strip_continuation_wrapper()` — 剥离续写响应中 LLM 重新添加的 markdown 代码块和自然语言前缀
- `_extract_jrxml()` — 逐一检查多个 markdown 代码块，跳过非 JRXML 片段
- `_generate_with_continuation()` — 续写轮次自动应用 `_strip_continuation_wrapper`

#### 新增环境变量

| 变量 | 描述 | 默认值 |
|------|------|--------|
| `LLM_MAX_TOKENS` | 默认 max_tokens（各节点可覆盖） | 8192 |