docs: update all project documentation to reflect current codebase
- README.md: complete overhaul — project structure, architecture, env vars, test listing, Java/JDBC pipeline - CLAUDE.md: fix field count (~28→~40), migrate Streamlit references to Vue 3, update known issues - frontend/README.md: add missing StreamingMessage.vue and NodeProgress.vue components
This commit is contained in:
@@ -75,7 +75,7 @@ validation_service/ (FastAPI, 端口 8001) — 不变
|
||||
|------|------|---------|
|
||||
| `api_server.py` | FastAPI SSE 后端,REST API + 流式推送 | **高** |
|
||||
| `frontend/src/` | Vue 3 聊天 UI(替代旧 app.py) | **高** |
|
||||
| `agent/state.py` | AgentState 类型定义(~28 字段) | 低 |
|
||||
| `agent/state.py` | AgentState 类型定义(~40 字段) | 低 |
|
||||
| `agent/nodes.py` | 18 个工作流节点 + 流式生成 + 错误记录 | **高** |
|
||||
| `agent/graph.py` | 状态图编译 + 路由函数 + node_start 回调 | 中 |
|
||||
| `prompts/loader.py` | Prompt 加载器(从 .md 文件热重载) | 低 |
|
||||
@@ -145,20 +145,17 @@ validation_service/ (FastAPI, 端口 8001) — 不变
|
||||
- `retrieve` 节点自动注入历史修正案例
|
||||
- 流程:correct_jrxml 保存 last_error_case → validate 通过时自动入库
|
||||
|
||||
### 文件上传
|
||||
- **对话区域上传(v3)**: `st.file_uploader` 位于聊天输入框上方,支持图片/PDF/DOCX/XLSX/文本
|
||||
- **粘贴/拖拽(v3)**: 全局 paste/drop 事件监听 + `sessionStorage` + 轮询桥接组件,Ctrl+V 粘贴或拖拽文件到页面任意位置
|
||||
- **文件预览芯片(v3)**: 上传后显示在对话区域,可逐文件移除(自动清理临时文件)
|
||||
### 文件上传(已迁移至 Vue 3 前端)
|
||||
- **对话区域上传**: `UnifiedInput.vue` 统一输入框支持文本 + 文件拖拽/粘贴/选择按钮,支持图片/PDF/DOCX/XLSX/文本/`.jrxml`
|
||||
- **文件预览芯片**: 上传后显示在对话区域,可逐文件移除(自动清理临时文件)
|
||||
- 侧边栏多文件上传(可逐文件移除,向后兼容保留)
|
||||
- 支持: PDF(pdfplumber+PIL) / DOCX(python-docx) / XLSX(openpyxl, v3) / 图片(PIL+EasyOCR优先→PaddleOCR回退) / 纯文本
|
||||
- 支持: PDF(pdfplumber+PIL) / DOCX(python-docx) / XLSX(openpyxl) / 图片(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 个文件
|
||||
### 对话区域文件粘贴/拖拽 (v3, 已迁移至 Vue 3)
|
||||
|
||||
原 Streamlit 方案(`st.html()` 注入 + `sessionStorage` 桥接)已废弃。当前由 `UnifiedInput.vue` 原生处理 paste/drop/dragover 事件,通过 `stores/chat.ts` 上传文件到 `/api/upload`,`_process_files()` 在 `api_server.py` 中统一处理。
|
||||
|
||||
### A4 模板识别
|
||||
- `backend/layout_analyzer.py` — 三种处理路径:
|
||||
@@ -175,9 +172,6 @@ validation_service/ (FastAPI, 端口 8001) — 不变
|
||||
### 预览修复
|
||||
- `route_after_save` 新增意图判断:预览/导出跳过验证直通 finalize
|
||||
|
||||
### Ctrl+C 修复
|
||||
- JS 注入拦截 Streamlit 裸 `c` 键清缓存,保留 Ctrl+C 复制
|
||||
|
||||
### 结构化日志系统
|
||||
- `backend/logger.py` — JSON 格式化 + trace_id + 国际时区
|
||||
- `_LLMLoggingWrapper` — 包装所有 LLM 后端,记录完整 prompt/response
|
||||
@@ -194,12 +188,11 @@ validation_service/ (FastAPI, 端口 8001) — 不变
|
||||
- `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, 已迁移至 Vue 3)
|
||||
|
||||
原 Streamlit `st_multimodal_chatinput` 组件已废弃。当前由 `UnifiedInput.vue` 实现粘贴/拖拽/文件选择,`api_server.py:_process_files()` 统一处理上传文件(含 `.jrxml` 模板提取)。
|
||||
|
||||
新增文件格式支持: XLSX (openpyxl)、XLS (xlrd)、DOC (olefile)
|
||||
|
||||
### 批注检测 (v4)
|
||||
- `backend/annotation_detector.py` — 识别用户在手写单据上的圈选和箭头标记
|
||||
@@ -233,7 +226,6 @@ validation_service/ (FastAPI, 端口 8001) — 不变
|
||||
- **环境变量优先级**: `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` 存在。
|
||||
@@ -244,10 +236,10 @@ validation_service/ (FastAPI, 端口 8001) — 不变
|
||||
- **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 按钮。
|
||||
- **粘贴/拖拽**: `UnifiedInput.vue` 原生处理 paste/drop 事件,单文件上限 20MB。文件通过 `/api/upload` 上传至 `uploads/` 目录。
|
||||
- **torchvision**: `transformers` 库的懒加载需要 `torchvision`,已作为依赖安装。
|
||||
- **opencv-python-headless**: 批注检测(圈选/箭头)依赖,通过 `pip install -r requirements.txt` 安装。
|
||||
- **st-multimodal-chatinput**: Streamlit 聊天输入增强组件,替代 `st.chat_input`,支持粘贴/拖拽文件。返回 base64 编码文件内容。
|
||||
- **前端文件输入**: `UnifiedInput.vue` 原生处理文本输入 + 文件拖拽/粘贴/选择,替代原 Streamlit `st-multimodal-chatinput` 组件。
|
||||
- **xlwt**: 仅在测试中使用(生成 .xls 测试文件)。
|
||||
- **分层精确生成**: 3 阶段管线仅在 `layout_schema.total_rows > 0` 时触发。文本请求和 `modify_report` 等意图不受影响,走原有 `generate` 节点。中间阶段(骨架/精调)跳过验证,只有最终 mapped 结果进入 `validate`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user