Auto-Finance/.agents/docs/plans/agent 改造计划.md

last_reviewed

last_reviewed
2026-06-12

Agent 改造计划

总体目标

改变交互范式，从"用户点击驱动"转向"AI 对话驱动"。用户通过文件上传和聊天窗口与 AI 交互，减少繁琐的点击操作。

实施阶段

第一步：统一文件上传入口（已完成）

完成日期：2026-06-12

变更内容：

• 合并 PDF 和图片上传入口为单一上传区
• 后端 /api/files 接口返回统一文件列表（含 name、type、size 字段）
• 前端 allFiles 单一数组管理所有上传文件
• 手机扫码上传逻辑保留，暂不改动
• 配置表单保持不变

修改文件：

• src/web/app.py — /api/files 接口改造
• src/web/templates/index.html — 合并上传区域
• src/web/static/js/index.js — 统一文件管理逻辑
• src/web/README.md — 文档更新

第二步：移除配置表单，config.json 自动解析（已完成）

完成日期：2026-06-12

变更内容：

• 移除前端配置表单区域，不再展示账号、密码、姓名等输入框
• 用户通过统一上传入口上传 config.json，前端自动解析并存入 sessionConfig 对象
• 文件选择器 accept 增加 .json 支持
• 处理流程从 sessionConfig 读取配置，不再依赖 DOM 输入框
• 配置同步到表格的逻辑改为从 sessionConfig 读取

修改文件：

• src/web/templates/index.html — 移除配置表单，accept 增加 .json
• src/web/static/js/index.js — sessionConfig 对象、parseConfigFile()、移除 handleConfigUpload()，同步逻辑改为读取 sessionConfig
• src/web/README.md — 文档更新

第三步：聊天窗口替换日志终端（已完成）

完成日期：2026-06-12

变更内容：

• 暗色终端风格的日志窗口替换为 AI 聊天风格的聊天窗口
• SSE 日志以聊天气泡形式逐条展示，支持 processing/success/error/done 四种消息类型
• 处理中显示打字指示器动画（三个跳动圆点）
• 提交财务系统时也使用聊天窗口反馈进度

修改文件：

• src/web/templates/index.html — 日志窗口替换为聊天窗口
• src/web/static/css/index.css — 聊天样式（气泡、头像、打字动画）
• src/web/static/js/index.js — addChatMessage()、addTypingIndicator()、SSE 消息转为聊天气泡
• src/web/README.md — 文档更新

第四步：AI 对话驱动流程（已完成）

完成日期：2026-06-12

前面实现了 AI 前端对话窗口搭建，思考过程传输，文档识别，自动化报销信息填报，但是当前的系统架构本质是还是没有容错的固定流程。

架构方案：混合校验

采用规则校验器 + LLM 语义校验的混合方案：

1. 规则校验器（src/doc/validator.py）：定义硬性必填字段清单，快速判断完整性
2. LLM 语义校验（src/doc/llm_extractor.py）：对通过规则校验的数据做语义级二次判断
3. Agent 协调器（src/agent/orchestrator.py）：管理多轮对话状态机，协调校验流程

状态机

idle -> extracting -> validating -> awaiting_supplement -> (回到extracting)
                                        |
                                   (完整) -> ready_to_submit -> submitting -> done
                                        |
                                   (用户强制) -> submitting

修改文件清单

文件	变更类型	说明
src/doc/validator.py	新增	规则校验器
src/agent/orchestrator.py	新增	Agent 协调器
src/agent/__init__.py	新增	包初始化
src/doc/llm_extractor.py	修改	新增 validate_semantic_completeness()
src/doc/prompt.py	修改	新增校验提示词
src/doc/prompts/validation_system.md	新增	语义校验提示词
src/web/app.py	修改	SSE 协议扩展、Agent API 端点
src/web/templates/index.html	修改	引入 agent.js
src/web/static/js/chat.js	无改动	复用现有聊天模块
src/web/static/js/process.js	修改	处理 Agent 事件
src/web/static/js/agent.js	新增	Agent 交互模块
src/web/static/css/index.css	修改	Agent 请求面板样式

新增 API 端点

端点	方法	说明
/api/agent/state/<session_id>	GET	获取 Agent 会话状态
/api/agent/process/<session_id>	POST	启动 Agent 多轮处理
/api/agent/supplement/<session_id>	POST	用户补充文件后重新分析
/api/agent/force-submit/<session_id>	POST	强制提交，跳过校验

SSE 新增事件类型

事件类型	说明
agent_state_change	Agent 状态变更
agent_request_supplement	请求用户上传补充材料
agent_ready	信息完整，可以提交
agent_error	Agent 错误
agent_supplement_received	收到用户补充文件
agent_force_submit	用户强制提交