# 改进路线图

## 阶段一：代码质量（低风险，快速交付）

### 1. Prompt 拆分 ✓
- [x] 创建 `prompts/` 目录
- [x] 7 个 prompt 各拆为独立 `.md` 文件
- [x] `nodes.py` 改为从文件加载
- [x] 支持热重载（文件变更无需重启）

### 2. 修复无效代码 ✓
- [x] `backend/llm.py` — `get_num_tokens()` 修复为正确 API
- [x] `backend/embeddings.py` — 修复 docstring 函数名不一致
- [x] `backend/llm.py` — 统一 LLM 接口基类 `_BaseLLM`

---

## 阶段二：用户体验（核心改造）

### 3. 流式输出 + 节点平铺 ✓
- [x] `backend/llm.py` — LLM 工厂支持 `stream()` 统一接口
- [x] `agent/nodes.py` — generate/modify/correct 节点使用流式 + `get_stream_writer()`
- [x] `app.py` — 使用 `stream_mode=["updates", "custom"]` 捕获流式事件
- [x] 节点状态平铺（处理过程 expander 逐节点展示）
- [x] 流式完成后节点自动折叠
- [x] 完成后单独展示「总结卡片」

### 4. 错误自增长知识库 ✓
- [x] `backend/error_kb.py` — ErrorKB 类（ChromaDB 持久化）
- [x] 错误指纹去重（标准化 + MD5）
- [x] `correct_jrxml` — 保存修正前状态到 `last_error_case`
- [x] `validate` — 修正成功时自动记录（仅新错误，自动去重）
- [x] `retrieve` — 搜索错误知识库，注入历史修正案例
- [x] 记录内容：错误 + 修正前后 JRXML + prompt + 工具链 + 模型

### 5. 文件上传支持 ✓
- [x] `backend/file_parser.py` — 统一解析接口
  - [x] 图片 → PIL 元信息 + PaddleOCR（可选安装后自动识别）
  - [x] PDF → pdfplumber / PyMuPDF 文本提取
  - [x] DOCX → python-docx 文本提取
  - [x] 纯文本 (.txt/.csv/.json/.xml) → 直接读取
- [x] `can_use_vision()` — 根据模型名判断是否支持原生多模态
- [x] `app.py` — 侧边栏文件上传组件（多文件，可移除）
- [x] 上传文本自动注入下一条消息前缀

### 6. A4 图片模板识别 ✓
- [x] `backend/layout_analyzer.py` — 完整布局分析模块
- [x] A4 比例判定：exact(±3%) / close(±8%) / not_a4 三档
- [x] PaddleOCR 布局分析：逐元素提取坐标(x,y,w,h)、字号、文本
- [x] 行分组：Y 轴容差自动聚类
- [x] 结构化输出：`图片模板共 X 行，第 1 行有 Y 个元素，其中元素 a 长...高...字体...内容是...`
- [x] 检测门槛：≥2 个 OCR 元素 + A4 比例 → 标记为模板
- [x] `app.py` — 上传图片/PDF 时自动触发布局分析，替换为布局描述

### 7. 会话历史 JRXML 下载 ✓
- [x] `agent/state.py` — 新增 `jrxml_versions` 字段
- [x] `agent/nodes.py` — `finalize` 节点追加版本记录
- [x] `app.py` — 侧边栏"历史版本"折叠区，每版本独立下载按钮

### 8. 预览功能修复 ✓
- [x] 根因：`preview_report` 路由到 `save_session` → `validate` 触发不必要的验证修正循环
- [x] 修复：`route_after_save` — 预览/导出意图跳过验证直接 `finalize`

---

## 阶段三：细节修复

### 9. Ctrl+C 修复 ✓
- [x] `app.py` — 注入 JS 拦截裸 `c` 键，保留 Ctrl+C 复制行为

---

## 阶段四：可观测性

### 10. 结构化日志系统 ✓
- [x] `backend/logger.py` — 集中日志配置模块
  - [x] JSON 格式化（每行一条记录，便于 jq/pandas 分析）
  - [x] 请求级 trace_id（contextvars 自动传播，一次用户请求贯穿全链路）
  - [x] 独立 LLM 日志文件 `logs/llm.log`（记录完整 prompt 和 response）
  - [x] 时区：UTC+8（中国时区）
  - [x] 日志轮转（单文件 10MB，保留 5 备份）
- [x] `backend/llm.py` — `_LLMLoggingWrapper` 包装所有 LLM 后端
  - [x] 记录每次 invoke/stream 的请求 prompt、响应内容、耗时、模型、调用来源
  - [x] 异常时也记录完整 prompt
- [x] `agent/nodes.py` — `@log_node` 装饰器覆盖 17 个节点
  - [x] 入口/出口/异常三个阶段的日志
  - [x] 自动记录 state 关键字段摘要（session_id、intent、status、jrxml_length 等）
  - [x] 每个节点耗时（duration_ms）
- [x] `agent/graph.py` — `@_log_route` 装饰器覆盖 8 个路由函数
  - [x] 记录每次路由决策（来源 → 目标）
- [x] `app.py` — 用户交互日志
  - [x] 收到用户输入（含上传文件信息）
  - [x] 代理执行开始/完成（含最终 intent、status、jrxml_length）
  - [x] 异常时记录错误详情
  - [x] 会话新建/切换/删除操作日志
- [x] `backend/session.py` — 会话创建/删除日志
- [x] `backend/validation.py` — 验证完成/连接失败日志
- [x] `.env.example` — 新增 `LOG_DIR`、`LOG_LEVEL` 配置项
- [x] `.gitignore` — 新增 `logs/` 忽略规则

---

## 执行顺序建议

```
1. Prompt 拆分 ──► 2. 无效代码修复
                        │
                        ▼
              3. 流式输出 + 节点平铺
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    4. 错误自增长   5. 文件上传   7. 下载历史
          │             │
          ▼             ▼
    6. A4 模板识别  8. 预览修复
                        │
                        ▼
                 9. Ctrl+C 修复
                        │
                        ▼
               10. 结构化日志系统
```

---

## 阶段五：OCR 与智能上传 (v3/v4) ✓

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

### 12. 多模态聊天输入 ✓
- [x] `app.py` — `st.chat_input` 替换为 `st_multimodal_chatinput`
- [x] 支持 Ctrl+V 粘贴文件 + 拖拽 + 文件按钮
- [x] `_process_uploaded_file()` — 提取共享文件处理逻辑（消除 ~70 行重复代码）
- [x] 剪贴板文件 base64 解码 + MIME type → 扩展名推断

### 13. 多格式文件支持 ✓
- [x] `backend/file_parser.py` — 新增 XLSX (openpyxl)、XLS (xlrd)、DOC (olefile)
- [x] 侧边栏上传器类型列表中新增 xlsx/xls/doc
- [x] 单元测试: `tests/test_file_parser_formats.py` (4 tests)

### 14. 批注检测 ✓
- [x] `backend/annotation_detector.py` — 圈选 + 箭头 + OCR 关联
- [x] 圆圈检测: 红色通道增强 → HoughCircles
- [x] 箭头检测: Canny → HoughLinesP → 线段聚类 → 端点方向判定
- [x] `format_annotation_context()` — 批注结果格式化为中文提示
- [x] `process_input` 节点在 OCR 提取后自动运行批注检测
- [x] `annotation_result` 字段持久化到 AgentState + 会话文件
- [x] 单元测试: `tests/test_annotation_detector.py` (7 tests)

### 15. OCR 上下文 LLM 注入 ✓
- [x] `prompts/modification.md` — 新增 `{ocr_context}` 占位符
- [x] `modify_jrxml` + `generate` 节点注入 OCR 上下文
- [x] OCR 上下文包含: 结构化字段、全部文本元素（含坐标）、批注检测结果

---

## 阶段六：分层精确生成 (v5) ✓

### 16. 布局 Schema 提取 ✓
- [x] `backend/layout_analyzer.py` — 新增 `extract_layout_schema()` 函数（+107 行）
- [x] X 坐标聚类列检测（avg_width * 0.5 阈值）
- [x] 区域分类：标题/表头/数据/表尾（启发式算法）
- [x] `schema_text` 紧凑中文描述（列定义 + 区域 + 宽度分类）
- [x] 空行/单行/双行边界情况处理
- [x] 单元测试: `tests/test_layered_generation.py::TestExtractLayoutSchema` (9 tests)

### 17. 3 阶段生成管线 ✓
- [x] Phase 1: `generate_skeleton` — 压缩布局 schema → 骨架 JRXML (`$F{field_N}` 占位)
- [x] Phase 2: `refine_layout` — 采样坐标（表头+首行数据+末行）→ 像素级位置精调
- [x] Phase 3: `map_fields` — OCR 字段名 → 替换占位符为真实字段名
- [x] 中间阶段跳过验证（仅最终 mapped 结果进入 validate 循环）
- [x] 流式输出支持（每阶段逐字生成）
- [x] 单元测试: `tests/test_layered_generation.py::TestIntegration` (4 tests)

### 18. 路由与状态 ✓
- [x] `agent/graph.py` — 新增 `route_after_retrieve()` 条件路由
- [x] `layout_schema.total_rows > 0` → 3 阶段，否则 → 原有 1-shot
- [x] `agent/state.py` — 新增 `layout_schema: dict` 和 `ocr_elements: list`
- [x] 会话持久化支持（`save_session_node` / `load_session_node`）
- [x] 文本请求和其他意图零行为变更
- [x] 单元测试: `tests/test_layered_generation.py::TestRouting` (4 tests)

### 19. Prompt 模板 ✓
- [x] `prompts/skeleton_generation.md` — 骨架生成 prompt
- [x] `prompts/refine_layout.md` — 布局精调 prompt
- [x] `prompts/field_mapping.md` — 字段映射 prompt
- [x] `prompts/loader.py` — 注册 3 个新模板（热重载）

### 20. UI 集成 ✓
- [x] `app.py` — 上传 A4 图片时自动调用 `extract_layout_schema()`
- [x] 新增节点标签：`🏗 生成骨架` / `📐 精调布局` / `🏷 映射字段`
- [x] 3 个新节点的详情渲染

---

阶段一立即可做，无外部依赖。阶段二是主要工作量。阶段三是收尾。阶段四是可观测性基础。阶段五是 OCR 智能增强和用户体验改进。阶段六解决 A4 报表图片 OCR 元素过多（数百个）导致 LLM prompt 超长的问题。