Files

T

panda da79640259 fix: OCR字段提取集成修复 + 会话切换无限循环修复 + 一键启动脚本

- process_input 传入17个默认中文字段（修复空列表导致零字段提取）
- OCR提取结果自动注入 LLM 上下文
- save_session_node/load_session_node 持久化 session_id（修复切换会话无限 rerun）
- app.py 会话切换后显式设置 session_id（纵深防御）
- 新增 start.bat / stop.bat 一键启动/停止脚本
- 更新 CLAUDE.md + CODE_GUIDE.md 文档

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-20 10:17:05 +08:00

49 KiB

Raw Blame History

JRXML 生成代理 — 完整代码导读

读完本文档后，你将能够：理解项目架构、独立修改代码、添加新功能、调试常见问题。

项目是什么
启动与运行
架构全景图
数据总线：AgentState
状态机：graphpy
14 个节点详解：nodespy
LLM 调用层：llmpy
Prompt 系统：prompts
RAG 与向量搜索
错误自增长知识库
布局分析器
文件解析器 12b. OCR 单据字段提取器
验证服务
会话持久化
Streamlit UI：apppy
配置参考
如何添加新功能
调试指南

1. 项目是什么

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

技术栈：Streamlit（UI） + LangGraph（状态机） + LLM（MiniMax/OpenAI/Ollama） + ChromaDB（向量库） + FastAPI（验证微服务）

核心价值：让非技术人员通过自然语言创建 JasperReports 报表模板，无需手写 XML。

2. 启动与运行

环境准备

# 1. 安装依赖
pip install -r requirements.txt

# 2. 复制配置文件，填入 API Key
cp .env.example .env
# 编辑 .env，至少填 OPENAI_API_KEY

启动

一键启动（推荐）：双击 start.bat，自动打开两个窗口分别运行验证服务和 UI。停止用 stop.bat。

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

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

# 终端 2 — Streamlit UI
streamlit run app.py --server.port 8501

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

三个 LLM 后端

后端	配置	适用场景
Anthropic 兼容	`LLM_PROVIDER=anthropic`，`OPENAI_BASE_URL=https://api.minimaxi.com/anthropic`	当前默认，使用 MiniMax M2.7
OpenAI 兼容	`LLM_PROVIDER=openai`，`OPENAI_BASE_URL=https://api.openai.com/v1`	标准 OpenAI / 代理
Ollama 本地	`LLM_BACKEND=local`，`LOCAL_LLM_MODEL=qwen2.5-coder:7b`	离线使用

3. 架构全景图

┌──────────────────────────────────────────────────────────────┐
│                        app.py (Streamlit)                     │
│  聊天界面 │ 侧边栏(会话管理/文件上传/历史下载) │ 流式渲染     │
│  run_agent() → graph.stream(agent_state)                      │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                    agent/graph.py (LangGraph)                  │
│                                                               │
│  load_session → process_input → manage_context → save_snapshot│
│     → classify_intent                                         │
│        ├─ initial_generation → retrieve → generate            │
│        ├─ modify_report      → modify_jrxml                   │
│        ├─ consult_question   → handle_consult                 │
│        ├─ undo_modification  → handle_undo                    │
│        ├─ reset_session      → handle_reset                   │
│        └─ preview/export     → save_session (跳过验证)        │
│              │                                                │
│              ▼                                                │
│         save_session → validate                               │
│            pass ◄─── validate ─── fail                        │
│              │                    │                           │
│              │              explain_error                     │
│              │                    │                           │
│              │              correct_jrxml                     │
│              │                    │                           │
│              │           (retry < 3) ────┘                    │
│              ▼                                                │
│          finalize → END                                       │
└──────────────────────────┬───────────────────────────────────┘
                           │
          ┌────────────────┼──────────────────┐
          ▼                ▼                  ▼
   ┌──────────┐   ┌──────────────┐   ┌───────────────┐
   │backend/  │   │prompts/      │   │validation_    │
   │llm.py    │   │loader.py     │   │service/main.py│
   │logger.py │   │*.md (7个     │   │(FastAPI,      │
   │rag_      │   │Prompt模板)   │   │独立进程)      │
   │adapter.py│   └──────────────┘   └───────────────┘
   │error_kb  │
   │.py       │
   │embeddings│
   │.py       │
   │layout_   │
   │analyzer  │
   │.py       │
   │ocr_      │
   │extractor │
   │.py       │
   │file_     │
   │parser.py │
   │validation│
   │.py       │
   │session.py│
   └──────────┘

关键设计决策

LLM 调用不经过 LangChain：backend/llm.py 直接使用 Anthropic SDK 和 OpenAI SDK，仅 Ollama 保留 langchain-ollama 包装。所有 LLM 调用通过 _LLMLoggingWrapper 自动记录输入输出到 logs/llm.log。
Prompt 热重载：prompts/loader.py 每次都从磁盘读取 .md 文件，修改 Prompt 无需重启。
流式输出：生成节点使用 get_stream_writer() 发送 custom 事件，UI 通过 stream_mode=["updates", "custom"] 捕获逐字输出。
验证服务独立进程：FastAPI 运行在 8001 端口，主进程通过 HTTP 调用。这样可以把 Java 编译验证加进去而不影响 UI 进程。
结构化日志：backend/logger.py 提供 JSON 格式化日志，trace_id 通过 contextvars 贯穿全链路，LLM 调用与业务日志分离。

4. 数据总线：AgentState

agent/state.py — 只有 23 个字段的定义，不包含任何逻辑。

class AgentState(TypedDict, total=False):
    # ── 核心字段 ──
    conversation_history: List[dict]    # 当前工作对话（可能被压缩）
    current_jrxml: str                 # 当前正在处理的 JRXML
    user_input: str                    # 用户本轮输入
    status: str                        # "pass" | "fail" | ""
    error_msg: str                     # 验证错误信息
    natural_explanation: str           # 错误的人话解释
    retry_count: int                   # 当前修正尝试次数
    user_modification_request: str     # 修改请求文本
    final_jrxml: str                   # 最终通过的 JRXML
    stage: str                         # 当前阶段
    retrieved_context: str             # 从 RAG 检索到的上下文

    # ── 上下文压缩 ──
    full_conversation_history: List[dict]  # 完整对话（永不丢失）
    compressed_history: str               # 早期对话的摘要
    current_token_count: int              # 当前 token 估算值

    # ── 会话持久化 ──
    session_id: str        # UUID 前 12 位
    session_name: str      # 用户第一条消息的前 50 字
    created_at: str        # ISO 时间戳
    updated_at: str        # ISO 时间戳

    # ── 意图与撤销 ──
    intent: str              # 8 种意图之一
    history_states: List[dict]  # 快照栈，用于撤销

    # ── 版本历史 ──
    jrxml_versions: List[dict]  # [{ts, jrxml, intent, label, status}]

    # ── 错误知识库 ──
    last_error_case: dict   # {error_msg, bad_jrxml, correction_prompt}

    # ── 失败上下文传递 ──
    pending_failure_context: dict  # 重试耗尽后暂存失败信息，下次用户输入时自动注入

    # ── OCR 单据字段提取 ──
    ocr_extraction_result: dict   # OCR字段提取结果（来自 OcrExtractor）
    uploaded_file_path: str        # 上传图片的临时路径

数据流向：每个节点函数接收 state，修改后返回 state（实际上是 dict）。LangGraph 自动合并返回值到全局状态。

注意 total=False 意味着所有字段都是可选的，实际使用中不需要初始化全部字段。

5. 状态机：graph.py

agent/graph.py 是系统的"骨架"，定义了节点如何连接。核心是两个部分：

5.1 路由函数

路由函数是条件分支的判断逻辑，每个返回一个字符串决定下一个节点：

def route_by_intent(state) -> Literal["retrieve", "modify_jrxml", ...]:
    intent = state.get("intent", "initial_generation")
    if intent == "initial_generation":     return "retrieve"
    elif intent == "modify_report":        return "modify_jrxml"
    elif intent in ("preview_report", ...):return "save_session"  # 跳过生成
    elif intent == "consult_question":     return "handle_consult"
    ...

def route_after_validate(state) -> Literal["finalize", "explain_error"]:
    return "finalize" if state.get("status") == "pass" else "explain_error"

def route_after_correct(state) -> Literal["validate", "finalize"]:
    return "validate" if state.get("retry_count", 0) < MAX_RETRY else "finalize"

MAX_RETRY 默认为 3（.env 中配置）。重试耗尽后进入 finalize，finalize 会将失败上下文写入 pending_failure_context，下次用户输入时 process_input 自动注入。


**关键路由逻辑**：
- `route_by_intent`：8 种意图分叉，是整个系统的"交通枢纽"
- `route_after_save`：预览/导出意图**跳过验证**直通 finalize（这是修复预览问题的关键）
- `route_after_correct`：重试次数 < 3 则继续验证循环，否则认输

### 5.2 图构建

```python
def build_graph():
    workflow = StateGraph(AgentState)

    # 注册节点
    workflow.add_node("load_session", load_session_node)
    workflow.add_node("process_input", process_input)
    # ... 14 个节点

    # 连线
    workflow.set_entry_point("load_session")
    workflow.add_edge("load_session", "process_input")       # 固定边
    workflow.add_conditional_edges("classify_intent", route_by_intent, {...})  # 条件边

    return workflow.compile()

边的类型：

add_edge(from, to) — 固定边，无条件跳转
add_conditional_edges(from, router, mapping) — 条件边，router 返回值 → mapping 中的目标节点

5.3 完整流程图

                      ┌──────────────┐
                      │ load_session │  ← 入口
                      └──────┬───────┘
                             │
                      ┌──────▼───────┐
                      │process_input │
                      └──────┬───────┘
                             │
                      ┌──────▼───────┐
                      │manage_context│  ← token 超阈值时压缩早期对话
                      └──────┬───────┘
                             │
                      ┌──────▼───────┐
                      │save_snapshot │  ← 保存快照供撤销
                      └──────┬───────┘
                             │
                      ┌──────▼───────┐
                      │classify_intent│ ← LLM 判断用户要做什么
                      └──────┬───────┘
                             │
        ┌────────┬────────┬──┴──┬────────┬────────┐
        ▼        ▼        ▼     ▼        ▼        ▼
    retrieve  modify  save_  handle_  handle_  handle_
              _jrxml  session consult  undo     reset
        │        │               │       │        │
        ▼        │               │       ▼        │
    generate     │               │    save_session │
        │        │               │       │        │
        └───┬────┘               │       ▼        │
            │                    │    finalize     │
            ▼                    │                 │
       save_session ◄───────────┘                 │
            │                                      │
            ├── preview/export? ──► finalize       │
            │                                      │
            ▼                                      │
        validate ◄────────────────────────────────┘
         │     │
     pass     fail
         │     │
         │     ▼
         │  explain_error
         │     │
         │     ▼
         │  correct_jrxml
         │     │
         │     ├── retry < 3? ──► validate (循环)
         │     │
         │     └── retry >= 3? ──► finalize (放弃)
         │
         ▼
     finalize ──► END

6. 14 个节点详解：nodes.py

agent/nodes.py 是系统的"血肉"，每个节点实现一个处理步骤。

6.1 process_input — 记录输入 + 自动注入失败上下文 + OCR 字段提取

def process_input(state: AgentState) -> Dict:
    user_input = state.get("user_input", "")
    # 追加到全量历史（始终记录原始消息）
    state["full_conversation_history"].append({"role": "user", "content": user_input, "ts": _now_iso()})

    # 自动注入上次失败上下文
    pending = state.get("pending_failure_context", {})
    if pending and pending.get("error_msg"):
        failure_note = (
            f"[系统提示] 上次生成失败，以下是失败详情，请基于此修正：\n"
            f"失败原因: {pending['error_msg']}\n"
            f"上次失败的输出:\n{pending.get('bad_jrxml', '（无输出）')}"
        )
        user_input = f"{failure_note}\n\n---\n用户新输入:\n{user_input}"
        state["pending_failure_context"] = {}  # 用完即清

    # 追加到工作历史（含注入后的内容）
    state["conversation_history"].append({"role": "user", "content": user_input})

    # OCR 单据字段精确提取（处理上传的图片文件）
    uploaded_path = state.get("uploaded_file_path", "")
    if uploaded_path and Path(uploaded_path).is_file():
        if suffix in (".png", ".jpg", ".jpeg", ".bmp", ".webp"):
            extractor = OcrExtractor()
            ocr_result = extractor.extract(uploaded_path, [
                "发票代码", "发票号码", "开票日期", "合计金额", "校验码",
                "价税合计", "总金额", "日期", "金额", "数量", "单价", "税率",
                "购买方名称", "销售方名称", "货物名称", "规格型号",
                "不含税金额", "税额",
            ])
            if ocr_result.get("ocr_available"):
                state["ocr_extraction_result"] = ocr_result
                # 将提取到的字段注入 LLM 上下文
                non_empty = [f for f in extracted_fields if f.get("field_value")]
                if non_empty:
                    ocr_context = "[OCR 单据字段提取结果]\n" + ...
                    user_input = f"{ocr_context}\n\n{user_input}"

    # 重置本轮字段
    state["retry_count"] = 0
    state["user_modification_request"] = user_input

注意：

维护了两个对话历史 — conversation_history 可能被压缩，full_conversation_history 永不丢失
失败上下文注入仅影响工作历史，全量历史保留原始消息
OCR 字段提取在 process_input 阶段自动执行，提取到的字段值同时存入 ocr_extraction_result 和注入到 user_input 前缀供 LLM 使用
session_id 已包含在持久化字段中，避免切换会话时的无限 rerun bug

6.2 manage_context — 上下文压缩

当 token 数超过 CONTEXT_MAX_TOKENS（默认 6000），将最早期的对话轮次送去 LLM 摘要压缩。

if token_count > CONTEXT_MAX_TOKENS:
    recent = full_history[-CONTEXT_KEEP_RECENT:]   # 最近 4 轮保留完整
    older = full_history[:-CONTEXT_KEEP_RECENT:]   # 更早的送去压缩
    # LLM 生成摘要
    state["compressed_history"] = summary
    state["conversation_history"] = recent  # 替换为压缩后的

Token 计数：使用 tiktoken（gpt-4o 编码器），不管实际用什么模型。回退方案是 字符数 / 2.5。

6.3 save_state_snapshot — 保存快照

每次请求前保存当前报表状态到 history_states 栈，最多保留 10 个快照，供 handle_undo 恢复。

6.4 classify_intent — 意图分类

调用 LLM 将用户输入分为 8 种意图：

意图	含义	路由目标
`initial_generation`	新建报表	`retrieve` → `generate`
`modify_report`	修改现有报表	`modify_jrxml`
`preview_report`	预览报表	`save_session`（跳过验证）
`export_pdf`	导出 PDF	`save_session`（跳过验证）
`export_jrxml`	下载 JRXML	`save_session`（跳过验证）
`undo_modification`	撤销修改	`handle_undo`
`consult_question`	咨询问题	`handle_consult`
`reset_session`	重置会话	`handle_reset`

兜底策略：有现有报表 → modify_report，无 → initial_generation。

6.5 retrieve — 语义检索

def retrieve(state):
    context = search_chunks(user_input, k=5)    # RAG 向量搜索
    if error_msg:
        error_context = search_error_cases(error_msg, k=2)  # 错误知识库
        context = f"{context}\n\n[历史错误修正案例]\n{error_context}"
    state["retrieved_context"] = context

搜索两个 ChromaDB 集合：

jrxml_chunks — 预构建的 JRXML 模板知识库（rag 子模块产出）
jrxml_error_cases — 自动积累的错误修正案例

6.6 generate — 流式生成 JRXML

def generate(state):
    writer = get_stream_writer()  # LangGraph 流式写入器
    llm = get_llm()
    prompt = load_prompt("initial_generation").format(
        context=state.get("retrieved_context", ""),
        user_request=state.get("user_input", ""),
    )
    full = []
    for chunk in llm.stream(prompt):        # 流式逐字生成
        full.append(chunk)
        writer({"type": "stream", "node": "generate", "text": chunk})  # 发送到 UI
    jrxml = _extract_jrxml("".join(full))
    state["current_jrxml"] = jrxml

流式原理：writer() 发送的事件通过 LangGraph 的 custom 流到达 UI，在 app.py 中被捕获并逐字渲染。

6.7 modify_jrxml — 流式修改 JRXML

结构与 generate 相同，但 Prompt 不同：传入 current_jrxml + conversation_history + modification_request。同时在 full_conversation_history 中记录修改前后的对话对。

6.8 validate — 验证 JRXML

def validate(state):
    jrxml = state.get("current_jrxml", "")
    if not jrxml:
        return fail("没有 JRXML 内容可供验证")
    if len(jrxml.strip()) < 200:  # 过短不可能是合法报表
        return fail(f"JRXML 内容过短（{len(jrxml.strip())} 字符）")

    result = validate_jrxml(jrxml)  # HTTP POST 到 localhost:8001
    state["status"] = "pass" if result.get("valid") else "fail"
    state["error_msg"] = result.get("error", "")

    # 关键：如果是修正后通过的，将错误案例记录到知识库
    if result.get("valid") and state.get("retry_count", 0) > 0:
        record_error(case["error_msg"], case["bad_jrxml"], good_jrxml, ...)

200 字符阈值：最小合法 JRXML 骨架约 500+ 字符，200 字符以下不可能是完整报表。错误入库条件：valid=True AND retry_count > 0 — 意味着这个错误之前不存在于知识库，经过修正才成功。

6.9 explain_error — 错误转人话

将技术性验证错误（如 "字段 'amount' 未声明"）转为自然语言解释，帮助用户理解问题。

6.10 correct_jrxml — 自动修正

def correct_jrxml(state):
    # 保存修正前状态（供 validate 判断是否入库）
    state["last_error_case"] = {"error_msg": ..., "bad_jrxml": ..., "correction_prompt": prompt}

    # 流式生成修正后的 JRXML
    for chunk in llm.stream(prompt):
        writer({"type": "stream", "node": "correct_jrxml", "text": chunk})

    state["retry_count"] += 1  # 关键：递增重试计数

6.11 finalize — 完成

def finalize(state):
    if status == "pass":
        state["final_jrxml"] = jrxml
        versions.append({ts, jrxml, intent, label, status})  # 仅成功时入版本历史
    else:
        # 验证未通过：记录失败上下文，下次输入时自动注入
        state["pending_failure_context"] = {error_msg, bad_jrxml, retry_count, ts}
        # 不覆盖 final_jrxml，保留上一次成功的版本

关键：只有 status == "pass" 时才写入 jrxml_versions 和 final_jrxml。失败时记录 pending_failure_context 供下一轮 process_input 自动注入。

6.12 handle_consult / handle_undo / handle_reset

三个简单节点：

handle_consult：调用 LLM 回答问题，不走报表流程
handle_undo：从 history_states 弹出最近快照恢复
handle_reset：清空所有报表状态，保留会话

6.13 _extract_jrxml — XML 提取

从 LLM 响应中提取纯 JRXML。处理五种情况：

def _extract_jrxml(text):
    # 1. Markdown 代码块: ```xml ... ``` → 提取内部内容
    #    - 内容为空时回退（避免 LLM 输出空代码块）
    # 2. 完整 JasperReport 标签: <?xml ... </jasperReport>
    # 3. 直接以 <?xml 或 <jasperReport 开头
    # 4. 文本中嵌入的 XML 片段（最后一个回退）
    # 5. 兜底：直接返回原文本

7. LLM 调用层：llm.py

backend/llm.py 是整个系统唯一调用 LLM 的地方。核心设计是 _BaseLLM 抽象基类：

class _BaseLLM:
    def invoke(self, prompt: str) -> Any:       # 同步调用，返回含 .content 的对象
        raise NotImplementedError
    def stream(self, prompt: str):              # 流式调用，返回 Iterator[str]
        raise NotImplementedError

7.1 日志包装器

所有 LLM 实例都通过 _LLMLoggingWrapper 包装，自动记录：

请求 prompt（完整内容，截断 10000 字符）
响应内容（完整内容，截断 10000 字符）
调用耗时（毫秒）
模型名称、后端、调用来源（caller 参数）

日志输出到 logs/llm.log（独立于业务日志）。

7.2 三个实现

MiniMaxLLM（LLM_PROVIDER=anthropic）：

使用原始 anthropic SDK（from anthropic import Anthropic）
API Key 优先读 ANTHROPIC_API_KEY，fallback OPENAI_API_KEY
invoke() 遍历 resp.content 找 type == "text" 的 block
stream() 使用 client.messages.stream() + s.text_stream

OpenAIWrapper（LLM_PROVIDER=openai）：

使用 langchain-openai 的 ChatOpenAI
标准 OpenAI 兼容端点，配置 base_url 即可对接任何代理

OllamaWrapper（LLM_BACKEND=local）：

使用 langchain-ollama 的 ChatOllama
本地运行，无需网络

7.3 调用约定

所有节点统一使用，传入 caller 参数标识调用来源：

llm = get_llm(caller="classify_intent")
# 同步
resp = llm.invoke(prompt)
text = resp.content.strip()
# 流式
for chunk in llm.stream(prompt):
    writer({"type": "stream", "node": "generate", "text": chunk})

8. Prompt 系统：prompts/

8.1 加载机制

prompts/loader.py 实现了热重载——每次调用 load_prompt() 都从磁盘读取：

def load_prompt(name: str) -> str:
    filepath = _PROMPTS_DIR / _NAME_MAP[name]   # e.g. prompts/intent_classify.md
    text = filepath.read_text(encoding="utf-8").strip()
    # 去除可能的 markdown frontmatter (--- ... ---)
    return text

这意味着你可以直接编辑 prompts/*.md，下次请求立即生效，无需重启。

8.2 7 个 Prompt 文件

文件	调用节点	占位符	用途
`intent_classify.md`	classify_intent	`{has_report}`, `{user_input}`	8 分类意图识别
`initial_generation.md`	generate	`{context}`, `{user_request}`	首次生成 JRXML
`modification.md`	modify_jrxml	`{current_jrxml}`, `{conversation_history}`, `{modification_request}`	修改现有 JRXML
`correction.md`	correct_jrxml	`{current_jrxml}`, `{error_msg}`, `{explanation}`	修正验证错误
`explain_error.md`	explain_error	`{error_msg}`, `{jrxml_snippet}`	技术错误转人话
`compression.md`	manage_context	`{conversation_text}`	对话摘要压缩
`consult.md`	handle_consult	`{question}`	咨询问答

8.3 Prompt 模板写法

所有 Prompt 使用 Python str.format() 语法，占位符用 {variable_name}。文件中可以包含 markdown 格式、代码示例、Few-shot 示例等。

9. RAG 与向量搜索

9.1 架构

rag/ (git submodule — 独立的知识库构建管线)
  ├── jrxml_source/          # 107 个 JRXML 模板
  ├── batch_chunker.py       # 模板分块
  ├── embed_chunks.py        # 向量化
  └── import_to_chroma.py    # 导入 ChromaDB
         │
         ▼ 产出
  db/chroma/jrxml_chunks/    # ChromaDB 集合
         │
         ▼ 消费
  backend/rag_adapter.py     # RAGSearcher 单例
         │
         ▼ 调用
  agent/nodes.py → retrieve() → search_chunks()

9.2 RAGSearcher 类

class RAGSearcher:
    def __init__(self):
        # 懒加载：model 和 client 在首次使用时才初始化
        self._model = None      # SentenceTransformer
        self._client = None     # chromadb.PersistentClient
        self._collection = None # ChromaDB collection

    def search(self, query, k=5) -> list[dict]:
        query_embedding = self.model.encode(query, normalize_embeddings=True)
        results = self.collection.query(query_embeddings=[...], n_results=k)
        return [{id, content, metadata, distance}, ...]

    def search_as_context(self, query, k=5) -> str:
        # 将搜索结果拼接成可直接注入 Prompt 的字符串

9.3 关键细节

模型懒加载：SentenceTransformer 加载需要几秒，只在首次查询时初始化
GPU 支持：通过 RAG_USE_GPU 和 RAG_USE_FP16 环境变量控制
全局单例：_get_searcher() 保证只加载一次模型
容错：如果 ChromaDB 集合不存在，返回空字符串，不影响主流程

10. 错误自增长知识库

backend/error_kb.py — 自动积累修正成功的错误案例，下次遇到相似错误时提供参考。

10.1 错误指纹

def _make_fingerprint(error_msg: str) -> str:
    text = error_msg.lower()
    text = re.sub(r'\$f\{[^}]+\}', '$f{<FIELD>}', text)   # 变量名 → <FIELD>
    text = re.sub(r"'[^']*'", "'<VALUE>'", text)          # 字符串 → <VALUE>
    text = re.sub(r'"<VALUE>"', '"<VALUE>"', text)
    text = re.sub(r'\b\d+\b', '<NUM>', text)              # 数字 → <NUM>
    return hashlib.md5(text.encode()).hexdigest()[:16]

目的：相同结构的错误（只是字段名不同）产生相同指纹，避免重复记录。例如 "字段 'amount' 未声明" 和 "字段 'total' 未声明" 的指纹相同。

10.2 数据流

correct_jrxml 节点
  │ 保存 last_error_case = {error_msg, bad_jrxml, correction_prompt}
  ▼
validate 节点 (pass 且 retry_count > 0)
  │ record_error(error_msg, bad_jrxml, good_jrxml, prompt)
  ▼
ErrorKB.record()
  │ 检查指纹 → 不存在则写入 ChromaDB collection "jrxml_error_cases"
  ▼
下次请求时
retrieve 节点
  │ search_error_cases(error_msg)
  ▼
注入 Prompt 作为参考案例

10.3 存储结构

ChromaDB 中每条记录：

id: 错误指纹（MD5 前 16 位）
document: JSON 字符串，含 error, bad_jrxml_snippet, good_jrxml_snippet, correction_prompt, model, tools
metadata: fingerprint, error_keywords, recorded_at, retry_success

11. 布局分析器

backend/layout_analyzer.py — 处理用户上传的图片/PDF，识别报表布局结构。

11.1 三种处理路径

上传图片
  │
  ├─ A4 比例 (0.686~0.728) + OCR 元素 ≥2
  │    └─ template_type = "full_a4"
  │       完整布局描述 → 生成整张报表
  │
  ├─ 非 A4 比例 + OCR 元素 ≥1
  │    └─ template_type = "partial_rows"
  │       ├─ 有现有 JRXML → match_rows_to_jrxml() → 定位修改
  │       └─ 无现有 JRXML → 按 A4 模板生成
  │
  └─ 无 OCR 元素 / OCR 不可用 / OCR 不可用
       └─ template_type = "unknown"
          ├─ 有 OCR 但非 A4 → 告知 LLM 图片尺寸 + 请根据文字描述生成
          └─ 无 OCR        → 告知 LLM OCR 不可用 + 请严格根据用户描述推断

11.2 核心函数

def analyze_layout(file_path) -> dict:
    # 1. 加载图片 (PIL / pdfplumber / PyMuPDF)
    # 2. 判定 A4 比例: exact(±3%) / close(±8%) / not_a4
    # 3. EasyOCR (优先) / PaddleOCR (回退) 提取文字元素 → [{x, y, w, h, font_size, text}]
    # 4. 行分组: Y 轴容差聚类
    # 5. 生成文本描述
    # 返回: {template_type, rows, description, ...}

def match_rows_to_jrxml(layout_result, current_jrxml) -> dict:
    # 1. 解析 JRXML 中的 band 结构
    # 2. 对每行 OCR 文字，计算与每个 band 的文本相似度
    # 3. 相似度 > 0.3 → 匹配成功
    # 返回: {matched_rows, unmatched_rows, description}

def analyze_and_inject(file_path, base_prompt, current_jrxml) -> str:
    # 根据 template_type 路由到不同的 Prompt 注入策略

11.3 JRXML Section 解析

def _parse_jrxml_sections(jrxml):
    # 先尝试 ElementTree 结构化解析
    # 遍历所有 section tag (title, detail, pageHeader 等)
    #   找到其下的 band 子元素
    #   提取 band 的 text_content 作为匹配目标
    # 失败则回退到正则: r'<(title|...|groupFooter)>\s*(<band[^>]*>.*?</band>)\s*</\1>'

11.4 依赖

EasyOCR（推荐）：pip install easyocr，Windows 兼容性好，支持中文+英文。
PaddleOCR（回退）：仅在 EasyOCR 不可用时尝试，Windows 下需额外安装 paddlepaddle。

12. 文件解析器

backend/file_parser.py — 统一的多格式文件解析入口。

def parse_file(file_path, file_type="") -> dict:
    # 返回: {text, file_type, method, error}

    # 分发到:
    # .png/.jpg/.jpeg/.bmp/.webp → _parse_image()
    # .pdf                         → _parse_pdf()
    # .docx                        → _parse_docx()
    # 其他                         → _parse_text()  (UTF-8 / GBK)

各解析器的回退链

图片：EasyOCR（ch_sim+en）→ PaddleOCR → 仅返回元信息 + 安装提示
PDF：pdfplumber → PyMuPDF → 失败
DOCX：python-docx（含表格内容提取）→ 失败
文本：UTF-8 → GBK → 失败

12b. OCR 单据字段提取器

backend/ocr_extractor.py — 两阶段精确提取单据图像中的字段值。

12b.1 数据模型

@dataclass
class OcrTextElement:        # OCR 文本元素，含精确坐标
    text: str
    x_min, y_min, x_max, y_max: float
    confidence: float = 1.0
    # 属性: center_x, center_y, width, height, bbox

@dataclass
class ExtractedField:        # 提取的字段结果
    field_name: str
    field_value: str
    bbox: list[float]
    confidence: float
    extraction_method: str    # exact_match / kv_pair / regex / table_match / none

@dataclass
class ExtractionResult:      # 完整提取结果
    file_path: str
    image_size: tuple
    fields: list[ExtractedField]
    all_elements: list[OcrTextElement]
    errors: list[str]
    ocr_available: bool

12b.2 两阶段流水线

阶段1 — 文档分析 (_analyze_document):

加载图片 → _ocr_elements_enhanced() → EasyOCR(ch_sim+en) → PaddleOCR 回退
按 OCR_CONFIDENCE_THRESHOLD (默认 0.5) 过滤低置信度元素
返回按 (y, x) 排序的 OcrTextElement 列表

阶段2 — 字段提取 (_extract_field): 按优先级尝试 4 种策略：

精确键值对 (_exact_kv_match, conf=0.95/0.85): 同一元素中 "字段名: 值" 模式
模糊键值对 (_fuzzy_kv_match, conf=0.75/0.60): 相邻元素匹配，同行/下一行搜索
正则模式 (_regex_match, conf=0.70/0.60): 12 种预定义模式 (发票代码/号码/金额/日期等)
表格结构 (_table_match, conf=0.55): 行列分组 + 表头匹配

12b.3 集成点

process_input: 检测到上传图片后自动调用，传入 17 个默认中文字段
结果注入: 提取到的字段值自动拼入 user_input 前缀（[OCR 单据字段提取结果]）
结果展示: app.py 总结卡片中 "🔍 OCR 单据字段提取结果" 折叠区

12b.4 回退能力

任一 OCR 引擎不可用时静默回退，不影响主流程
两种复用路径: extract() (全流程) 和 extract_from_layout_result() (复用已有布局分析)
便捷函数: extract_ocr_fields(), extract_from_layout()

13. 验证服务

validation_service/main.py — 独立的 FastAPI 进程，提供 JRXML 验证。

13.1 三级验证

@app.post("/validate")
async def validate_jrxml(req: ValidationRequest):
    # 第一级：结构检查 (_check_structural_issues)
    #   - XML 是否可解析
    #   - $F{field} 引用的字段是否在 <field> 中声明
    #   - <queryString> 是否包含 SELECT
    #   - pageWidth/pageHeight/name 属性是否存在

    # 第二级：最小内容检查 (_check_minimum_content)  ← v3 新增
    #   - 至少 1 个 <band> 元素
    #   - 至少 1 个 <textField> 或 <staticText> 元素（防止空壳 JRXML 通过验证）

    # 第三级：XSD Schema 校验 (_validate_xsd)
    #   - 需要 validation_service/schemas/jasperreport_7_0_6.xsd
    #   - 文件缺失时跳过

13.2 通信方式

backend/validation.py 通过 HTTP POST 调用：

def validate_jrxml(jrxml_text):
    with httpx.Client(timeout=30.0) as client:
        resp = client.post("http://localhost:8001/validate", json={"jrxml": jrxml_text})
        return resp.json()  # {valid: bool, error: str}

14. 会话持久化

backend/session.py — 基于 JSON 文件的简单 CRUD，每个会话一个文件。

create_session(name, agent_state) → dict        # 新建 {session_id}.json
load_session(session_id) → dict | None          # 读取
save_session(session_id, agent_state, name)      # 更新
list_all_sessions() → list[dict]                 # 列出（不含 agent_state）
delete_session(session_id) → bool               # 删除文件
generate_session_id() → str                     # UUID hex[:12]

存储位置：./sessions/{session_id}.json

文件结构：

{
  "session_id": "a1b2c3d4e5f6",
  "session_name": "生成一个销售报表",
  "created_at": "2026-05-19T10:30:00.000Z",
  "updated_at": "2026-05-19T10:35:00.000Z",
  "agent_state": { /* 完整的 AgentState dict */ }
}

15. 日志系统：logger.py

backend/logger.py 提供结构化日志能力，是整个系统的"黑匣子"。

15.1 架构设计

backend/logger.py
  ├── JsonFormatter        JSON 单行格式化，自动收集 extra 字段
  ├── get_logger(name)     获取 logger（name="llm" → llm.log，其他 → app.log）
  ├── generate_trace_id()  生成 16 位 hex trace_id
  ├── set_trace_id(tid)    通过 contextvars 设置当前请求的 trace_id
  └── get_trace_id()       获取当前 trace_id（自动跨线程/协程传播）

15.2 日志文件

文件	对应 logger	内容
`logs/app.log`	`get_logger("agent")`, `get_logger("app")`, `get_logger("session")`, `get_logger("validation")`	节点流转、路由决策、用户交互、会话操作、验证结果
`logs/llm.log`	`get_logger("llm")`	LLM 请求 prompt、响应内容、耗时、异常

15.3 日志格式

每条日志是单行 JSON：

{
  "timestamp": "2026-05-19T23:05:22.877+08:00",
  "level": "INFO",
  "logger": "jrxml.agent",
  "trace_id": "b29010ab4a014249",
  "message": "[节点入口] classify_intent",
  "module": "nodes",
  "function": "wrapper",
  "line": 53,
  "extra": {
    "node": "classify_intent",
    "phase": "entry",
    "state": {
      "session_id": "681e55231bab",
      "intent": "",
      "has_jrxml": false,
      "retry_count": 0
    }
  }
}

15.4 trace_id 机制

每次在 app.py 的 run_agent() 中调用 set_trace_id(generate_trace_id())，后续所有节点、路由、LLM 调用都自动带上同一个 trace_id。通过 grep "b29010ab4a014249" logs/*.log 可还原一次请求的完整链路。

15.5 `@log_node` 装饰器

agent/nodes.py 中 17 个节点均使用 @log_node("节点名") 装饰器，自动记录：

入口日志 — 节点开始执行时的 state 摘要
出口日志 — 节点完成时的 state 摘要 + 耗时 (duration_ms)
异常日志 — 节点抛异常时的错误信息 + state 摘要

15.6 `@_log_route` 装饰器

agent/graph.py 中 8 个路由函数均使用 @_log_route("路由名")，自动记录每次路由决策（from → to）。

15.7 日志分析示例

# 按 trace_id 追踪一次完整请求
jq 'select(.trace_id=="b29010ab4a014249")' logs/app.log

# 统计各节点平均耗时
jq 'select(.extra.phase=="exit") | {node: .extra.node, ms: .extra.duration_ms}' logs/app.log | jq -s 'group_by(.node) | map({node: .[0].node, avg_ms: (map(.ms) | add / length)})'

# 查看所有 LLM 调用耗时
jq 'select(.extra.direction=="response") | {caller: .extra.caller, ms: .extra.duration_ms}' logs/llm.log

16. Streamlit UI：app.py

app.py 是整个系统的入口，约 560 行。分为几个区域：

16.1 组件树

st.set_page_config (wide layout)

├── st.components.v1.html  (Ctrl+C 修复 — JS 拦截裸 'c' 键)

├── 侧边栏 (with st.sidebar)
│   ├── 会话管理 (selectbox + 新建/删除按钮)
│   ├── 快捷操作 (预览/撤销/重置按钮)
│   ├── 文件上传 (file_uploader + 解析 + 布局分析)
│   ├── 配置信息 (LLM backend/model/retry)
│   └── 下载区域 (最新 JRXML + 历史版本)
│
├── 标题 ("JRXML 报表生成器")
│
├── 聊天历史 (st.session_state.messages)
│   └── 按 msg["type"] 渲染: jrxml/error_explanation/success/consult/markdown
│
└── 聊天输入 (st.chat_input)
    └── 触发 run_agent(full_prompt)

16.2 run_agent() — 核心渲染函数

def run_agent(user_input):
    # 1. 准备状态：设置 user_input，重置 retry_count
    # 2. 创建 UI 占位符（实时更新）：
    #    - progress_placeholder    → 实时节点进度（每个节点完成后立即刷新）
    #    - streaming_placeholder   → 流式文本（逐字追加）
    #    - summary_placeholder     → 总结卡片
    # 3. 初始提示："⏳ 正在分析您的需求..."
    # 4. 遍历 graph.stream(state, stream_mode=["updates", "custom"])
    #    - mode == "updates"  → 记录 executed_nodes + 立即调用 _render_progress()
    #    - mode == "custom"   → 逐字追加到 stream_text 并渲染到 streaming_placeholder
    # 5. 清除临时占位（progress + streaming）
    # 6. 渲染总结卡片：用 agent_state（完整状态）而非 node_state（仅含变更字段）

16.3 文件上传流程

用户选择文件
  ↓
app.py 侧边栏: file_uploader.on_change
  ↓
创建临时文件 → parse_file(tmp_path)  (EasyOCR → PaddleOCR 回退)
  ↓ (如果是图片/PDF)
analyze_layout(tmp_path)
  ↓
template_type?
  ├─ full_a4     → parsed_text = layout["description"]
  ├─ partial_rows + 有 JRXML → match_rows_to_jrxml() → 修改定位描述
  ├─ partial_rows + 无 JRXML → layout["description"]
  └─ unknown     → 区分有/无 OCR，告诉 LLM 图片尺寸 + 文字描述引导  ← v3 新增
  ↓
存入 st.session_state.uploaded_files
  ↓
用户发送消息时 → 拼接 "[上传文件: xxx]\n{text}" + "用户需求:\n{prompt}"
  ↓
清空 uploaded_files

16.4 流式渲染细节

# 在 graph.stream 循环中:
elif mode == "custom":
    cd = data
    if cd.get("type") == "stream":
        stream_text += cd.get("text", "")           # 累积文本
        streaming_placeholder.code(stream_text, language="xml")  # 逐字刷新

这里 streaming_placeholder.code() 每次都会被覆盖，显示累积到当前的所有文本，产生"逐字打字"的视觉效果。

16.5 Ctrl+C 修复

Streamlit 默认会在非输入元素上按 c 键清除缓存。注入 JS 拦截裸 c 键（不含 Ctrl/Alt/Meta）：

parent.addEventListener('keydown', function(e) {
    if (e.key === 'c' && !e.ctrlKey && !e.metaKey && !e.altKey) {
        // 检查焦点不在 input/textarea/contentEditable
        e.stopImmediatePropagation();
        e.preventDefault();
    }
}, true);  // true = 捕获阶段，先于 Streamlit 自己的处理器

17. 配置参考

所有配置通过 .env 文件管理。完整配置项：

变量	默认值	说明
`LLM_BACKEND`	`cloud`	`cloud` 或 `local`
`LLM_PROVIDER`	`openai`	`openai` 或 `anthropic`
`LLM_MODEL`	`MiniMax-M2.7`	云端模型名
`LOCAL_LLM_MODEL`	`qwen2.5-coder:7b`	Ollama 模型名
`OPENAI_API_KEY`	—	API 密钥（Anthropic 模式的 fallback）
`ANTHROPIC_API_KEY`	—	Anthropic 兼容 API 密钥（优先）
`OPENAI_BASE_URL`	`https://api.openai.com/v1`	OpenAI API 端点
`ANTHROPIC_BASE_URL`	`https://api.minimaxi.com/anthropic`	Anthropic 兼容端点
`EMBED_BACKEND`	`local`	`local` 或 `cloud`
`RAG_EMBED_MODEL`	`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`	嵌入模型
`RAG_CHROMA_PATH`	`./db/chroma`	ChromaDB 存储路径
`RAG_COLLECTION_NAME`	`jrxml_chunks`	ChromaDB 集合名
`RAG_USE_GPU`	`true`	GPU 加速
`RAG_USE_FP16`	`true`	半精度推理
`VALIDATION_SERVICE_URL`	`http://localhost:8001/validate`	验证服务地址
`MAX_RETRY`	`3`	最大自动修正次数
`CONTEXT_MAX_TOKENS`	`6000`	触发压缩的 token 阈值
`CONTEXT_KEEP_RECENT`	`4`	压缩时保留最近 N 轮
`SESSIONS_DIR`	`./sessions`	会话文件目录
`HISTORY_MAX_SNAPSHOTS`	`10`	撤销快照栈深度
`LOG_DIR`	`./logs`	日志目录
`LOG_LEVEL`	`DEBUG`	日志级别 (DEBUG/INFO/WARNING/ERROR)

18. 如何添加新功能

18.1 添加新的意图类型

假设要添加"导出 Excel"功能：

prompts/intent_classify.md — 在意图列表中加入 export_excel
agent/nodes.py — 在 classify_intent 的 valid_intents 列表中加入 "export_excel"
agent/graph.py — 在 route_by_intent 中添加 elif intent == "export_excel": return "save_session"
app.py — 侧边栏添加快捷按钮
如果 Excel 导出的逻辑复杂，可以新增节点 handle_export_excel

18.2 添加新的 LLM 后端

在 backend/llm.py 的 get_llm() 中添加新的 provider：

elif provider == "my_provider":
    class MyProviderLLM(_BaseLLM):
        def invoke(self, prompt):
            # 实现同步调用
        def stream(self, prompt):
            # 实现流式调用
    return MyProviderLLM()

18.3 添加新的文件格式支持

在 backend/file_parser.py 中：

在 parsers dict 中添加文件后缀映射
实现对应的 _parse_xxx() 函数
在 app.py 的 file_uploader 的 type 参数中加入新后缀

18.4 添加新的验证规则

在 validation_service/main.py 的 _check_structural_issues() 中添加检查逻辑，返回描述问题的人类可读字符串即可。

18.5 修改 Prompt

直接编辑 prompts/*.md，保存后立即生效。Prompt 使用 Python str.format() 占位符，变量名必须与节点中 .format() 的参数名一致。

19. 调试指南

19.1 常见问题

Q: 验证服务连接失败

无法连接到验证服务 (http://localhost:8001/validate)

→ 确认终端 1 已启动验证服务：python -m uvicorn validation_service.main:app --port 8001

Q: Anthropic API 返回 401 → 检查 .env 中 OPENAI_API_KEY 是否已设置。注意：Anthropic 模式也使用 OPENAI_API_KEY 环境变量。

Q: 流式输出不工作 → 确认 LLM 后端的 stream() 方法正确实现了 yield。检查 get_stream_writer() 是否在 LangGraph 节点的顶层调用（不能在嵌套函数中）。

Q: ChromaDB 搜索返回空 → 检查 ChromaDB 集合是否存在：chromadb.PersistentClient(path="./db/chroma").list_collections() → 如果 jrxml_chunks 不存在，需要在 rag/ 子模块中运行管线。

Q: OCR 未安装 / 图片无法识别文字

(如需 OCR 文字识别，请安装: pip install easyocr)

→ 推荐安装 EasyOCR（Windows 兼容性好）：pip install easyocr → PaddleOCR 可选回退：pip install paddlepaddle paddleocr（Windows 下可能需额外配置）

Q: 修改了 nodes.py 但不生效 → Streamlit 有热重载，保存文件后刷新浏览器即可。如果改的是 Prompt 文件，下次请求自动生效，无需做任何操作。

19.2 日志调试

项目已集成结构化日志系统（详见第 15 章）。调试时：

# 实时查看日志
tail -f logs/app.log | jq .
tail -f logs/llm.log | jq .

# 按 trace_id 追踪一次完整请求
jq 'select(.trace_id=="abc123")' logs/app.log

# 查看最近 5 次 LLM 调用
tail -5 logs/llm.log | jq '{caller: .extra.caller, model: .extra.model, ms: .extra.duration_ms}'

# 查看错误日志
jq 'select(.level=="ERROR")' logs/app.log

也可直接在 Streamlit 终端（终端 2）添加 print() 快速调试。

19.3 状态检查

在 app.py 的 run_agent() 完成后，st.session_state.agent_state 包含最新状态。可以通过 Streamlit 的 st.write() 临时打印：

# 在 run_agent() 的最终处理中
st.json(state)  # 打印完整状态（调试用，记得删除）

19.4 关键数据点

调试时最常需要检查的数据：

检查点	位置	含义
`state["intent"]`	classify_intent 后	意图分类是否正确
`state["retrieved_context"]`	retrieve 后	检索到了什么模板
`state["status"]`	validate 后	验证通过/失败
`state["error_msg"]`	validate 后	具体错误是什么
`state["retry_count"]`	correct_jrxml 后	修正了几次
`state["conversation_history"][-1]`	生成后	LLM 最后输出了什么
`state["compressed_history"]`	manage_context 后	压缩摘要内容

附录：文件清单

文件	行数	角色
`app.py`	~530	Streamlit UI 入口
`agent/state.py`	~40	状态类型定义
`agent/nodes.py`	~523	14 个工作流节点
`agent/graph.py`	~232	状态图编译 + 路由
`backend/llm.py`	~105	LLM 工厂 (3 个后端)
`backend/rag_adapter.py`	~156	ChromaDB 语义搜索
`backend/error_kb.py`	~226	错误知识库
`backend/embeddings.py`	~49	嵌入模型工厂
`backend/file_parser.py`	~194	多格式文件解析
`backend/layout_analyzer.py`	~495	A4 模板布局分析
`backend/ocr_extractor.py`	~797	OCR 单据字段精确提取 (两阶段+4策略)
`backend/validation.py`	~27	验证服务 HTTP 客户端
`backend/session.py`	~113	会话 JSON CRUD
`prompts/loader.py`	~54	Prompt 热重载
`prompts/*.md` (7 个)	—	Prompt 模板
`validation_service/main.py`	~130	FastAPI 验证服务
`tests/test_ocr_extraction.py`	~543	OCR 提取器单元测试 (48 项)
`start.bat`	—	一键启动脚本 (Windows)
`stop.bat`	—	一键停止脚本 (Windows)
`.env.example`	~62	配置模板
`requirements.txt`	~32	Python 依赖

49 KiB Raw Blame History Unescape Escape