agent_jrxml/ROADMAP.md

改进路线图

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

1. Prompt 拆分 ✓

• 创建 prompts/ 目录
• 7 个 prompt 各拆为独立 .md 文件
• nodes.py 改为从文件加载
• 支持热重载（文件变更无需重启）

2. 修复无效代码 ✓

• backend/llm.py — get_num_tokens() 修复为正确 API
• backend/embeddings.py — 修复 docstring 函数名不一致
• backend/llm.py — 统一 LLM 接口基类 _BaseLLM

---

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

3. 流式输出 + 节点平铺 ✓

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

4. 错误自增长知识库 ✓

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

5. 文件上传支持 ✓

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

6. A4 图片模板识别 ✓

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

7. 会话历史 JRXML 下载 ✓

• agent/state.py — 新增 jrxml_versions 字段
• agent/nodes.py — finalize 节点追加版本记录
• app.py — 侧边栏"历史版本"折叠区，每版本独立下载按钮

8. 预览功能修复 ✓

• 根因：preview_report 路由到 save_session → validate 触发不必要的验证修正循环
• 修复：route_after_save — 预览/导出意图跳过验证直接 finalize

---

阶段三：细节修复

9. Ctrl+C 修复 ✓

• app.py — 注入 JS 拦截裸 c 键，保留 Ctrl+C 复制行为

---

阶段四：可观测性

10. 结构化日志系统 ✓

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

---

执行顺序建议

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

阶段一立即可做，无外部依赖。阶段二是主要工作量。阶段三是收尾。阶段四是可观测性基础。