# AI Flow Backend - 进度追踪文件
# 每次AI会话结束时必须更新此文件
# 新的AI会话开始时必须首先阅读此文件

## 项目当前状态 (截至 2026-04-12)

### 已完成的核心功能
- **基础框架**: Cool Admin + Midway.js 初始化，权限系统(RBAC)，流程引擎(13种节点)，知识库
- **Agent Swarm 架构** (BE-100~102): Supervisor + Skill 注册表 + SSE对话 + 会话管理
- **视频划痕检测 5个Skill** (BE-110~116): 抽帧→检测→定位→选帧→报告，Workspace共享存储
- **Skill 提示词自定义** (BE-105): prompts/defaultPrompts/updatePrompts API
- **Agent 架构进化** (BE-130~138): skillType分类 + SKILL.md规范 + XML注入 + agent_info表 + Agent CRUD + Supervisor支持agentId + 接口模式/open/agent/run/invoke + 预置Agent
- **LangChain 1.x 升级** (BE-200~204): middleware(toolRetry/toolCallLimit/modelRetry) + MySQL Checkpointer(自定义实现) + Skill内部Agent middleware
- **身份证OCR Skill** (BE-300): 百度OCR API封装 + id_card_ocr Skill
- **LLM思考内容显示**: reasoning_content提取 + thinking字段持久化
- **自主决策Agent**: 启动时自动创建/同步包含所有Skill的Agent
- **LLM Tool Selector中间件**: 轻量LLM预筛选工具子集(工具数>=8时启用)
- **审核订单模块规划** (BE-400~410): audit模块架构设计完成，任务已拆分
- **文生图Skill** (BE-501): 豆包Seedream 5.0文本生成图片(compute)，支持多分辨率/宽高比/批量/风格
- **实时语音交互Skill** (BE-500): 豆包端到端实时语音大模型(compute)，二进制协议编解码+WebSocket连接管理+Socket.io桥接
- **前端语音对话集成**: Socket.io连接+麦克风PCM录音+TTS句子级缓冲播放+语音对话面板
- **DOCX生成Skill** (BE-503): 基于docx npm包，支持三条流水线(创建/编辑/应用模板)，corporate/academic/minimal/government四种预设

### 新增的Skill (共15个，含5个视频检测+10个新增)
| Skill | 标识 | 类型 | 状态 |
|-------|------|------|------|
| 视频抽帧 | video_frame_extractor | compute | ✅ |
| 旧伤检测 | damage_detector | multimodal | ✅ |
| 损伤定位 | damage_grounding | multimodal | ✅ |
| 最佳帧筛选 | best_frame_selector | multimodal | ✅ |
| 报告生成 | scratch_report | llm | ✅ |
| 身份证OCR | id_card_ocr | compute | ✅ |
| 购车发票OCR | vehicle_invoice_ocr | compute | ✅ |
| 增值税发票验证 | vat_invoice_verify | llm | ✅ |
| 文档解析 | doc_parser | compute | ✅ |
| 理赔审核 | claim_audit | llm | ✅ |
| ZIP解压 | zip_extractor | compute | ✅ |
| 文生图 | image_generator | compute | ✅ |
| 实时语音交互 | realtime_voice | compute | ✅ |
| PPT生成 | pptx_generator | compute | ✅ |
| DOCX生成 | docx_generator | compute | 🔨 |
| XLSX生成 | xlsx_generator | compute | 🔨 |

### 模型渠道管理 (Neta Monorepo, 2026-04-12)
- **netaclaw_model_channel Entity**: 渠道表(name唯一/supplier/baseUrl/apiKey/models JSON/status)
- **NetaClawModelChannelService**: page/add/update/delete/info/allModels/testConnection/resolveForAgent
- **Admin Controller**: 7个端点 /admin/netaclaw/model_channel/*
- **运行时桥接**: agent.ts 中 channelId 解析，动态覆盖 model/apiKey/baseUrl
- **系统参数**: model_suppliers(9供应商) + model_capabilities(6能力类型)
- **数据库菜单**: ID=157, parentId=112(Agent管理), /agent/model-channel

### 新增的数据库表
- `agent_info` — Agent定义(name/label/systemPrompt/skills/modelConfig/status)
- `agent_checkpoints` + `agent_checkpoint_writes` — LangGraph状态持久化
- `audit_order` — 审核订单主表(宽表)
- `audit_order_detail` — 审核步骤明细
- `audit_config` — 审核规则配置
- `data_drug_catalog` — 商业健康险创新药目录主表
- `data_drug_category` — 创新药ATC分类(树形)
- `data_drug_item` — 创新药品条目
- `data_medical_catalog` — 国家医保药品目录主表
- `data_medical_category` — 医保药品ATC分类(树形)
- `data_medical_item` — 医保药品条目
- `notification_user` — 通知平台用户映射
- `notification_message_log` — 通知发送日志
- `netaclaw_model_channel` — 模型渠道管理(供应商/URL/密钥/模型列表/状态)

### 新增的模块
- `src/modules/audit/` — 审核订单管理(entity/service/controller)
- `src/modules/notification/` — 通知服务(飞书通知/用户映射/发送日志)
- `src/modules/data/` — 数据服务(创新药目录/医保药品管理)

### Token追踪 & 上下文管理 (Phase 1 完成)
- **TokenTracker**: `service/token_tracker.ts` — 收集 supervisor/selector/skill 三层 token 消耗，含 apiCalls 计数
- **Skill token 上报**: 4个 isComputeOnly Skill (damage_detector/damage_grounding/best_frame_selector/scratch_report) 在每次 callVisionAPI 后通过 `skillProgressEmitter.emitTokenUsage()` 上报
- **Progressive SSE**: 新增 `token_update` SSE 事件，每次 Skill API 调用后实时推送 token 汇总到前端
- **前端展示**: message-item 显示每条消息的 token 统计(入/出/总/调用次数)，chat.vue 显示实时执行中 token 和会话累计
- **待验证**: 需要实际运行 Agent 对话确认 token 数据正确采集

### 待开发 (按优先级)
- 实时语音交互端到端测试验证(TTS句子级播放已修复，待用户测试)
- **通知模块** (03-12): notification模块 + 飞书通知发送 + 通讯录同步 + Agent Skill + 开放HTTP接口
- **数据服务模块** (03-26): data模块 + 商业健康险创新药(BE-600) + 医保药品管理(BE-601)
- Phase 2: 上下文管理改造 (Checkpointer主导 + summarizationMiddleware)
- BE-400~410: 审核订单模块后端实现(Entity/Service/API/Skill/预置Agent)
- BE-504: XLSX生成Skill (xlsx_generator) - 4个工具 create/read/edit/validate
- BE-201: 接口模式responseFormat结构化输出
- BE-300 passes验证: 身份证OCR端到端测试
- BE-500/BE-501: 实时语音+文生图Skill端到端验证

## 历史会话摘要 (精简版)

| 日期 | 会话 | 主要完成 |
|------|------|---------|
| 02-21 | #1~#5 | 上下文工程初始化 + Agent Swarm架构(BE-100~102) + 视频划痕5个Skill(BE-110~116) |
| 02-24 | #6~#8 | Agent文档补全 + 架构进化规划(BE-130~138) + 全部后端实现 + Bug修复5个 |
| 02-27 | #9 | LangChain 1.x升级分析 + middleware(BE-200/202) + MySQL Checkpointer(BE-203/204) |
| 02-28 | #10 | 身份证OCR Skill(BE-300) + Skill描述编辑 + Skill结果展示 |
| 03-05 | #11 | LLM思考显示 + 自主决策Agent + Tool Selector中间件 |
| 03-06 | #12 | 审核订单模块架构规划(BE-400~410任务拆分) |
| 03-10 | #13~#14 | 文生图Skill(image_generator) + 实时语音交互Skill(realtime_voice) + 前端语音对话集成 + Skill配置面板改进 + 上下文工程文档更新 |
| 03-26 | #15 | 上下文工程文档更新：新增数据服务模块(BE-600/601)文档，INDEX/数据库README/CLAUDE.md/feature_list/progress全量更新 |
| 03-26 | #16 | MiniMax Skills集成：新增 pptx_generator Skill(BE-502)，基于PptxGenJS，支持5种幻灯片类型+主题配色+页码徽章 |
| 03-26 | #17 | MiniMax Skills集成第二弹：新增 docx_generator Skill(BE-503)，基于docx npm包，支持三条流水线(创建/编辑/应用模板)，corporate/academic/minimal/government四种预设，TypeScript编译零错误 |
| 03-27 | #18 | MiniMax Skills集成第三弹：新增 pdf_generator Skill(BE-505)，pdfkit(正文)+puppeteer-core(封面)+pdf-lib(合并)+ejs(模板)，15种封面风格，支持CREATE/FILL/REFORMAT三种模式，集成测试通过 |
| 04-12 | #19 | Neta Monorepo 模型渠道管理：Entity+Service+Controller+管理页面+级联选择器+Agent/Skill编辑改造+运行时桥接，10个功能提交+1个Bug修复 |

## 关键Bug修复记录
1. LLM URL重复拼接: apiUrl含/chat/completions → ChatOpenAI再追加导致404 → 去掉末尾
2. AgentInfoService Singleton scope: Event(singleton)注入Service(request) → 加@Scope(Singleton)
3. MySQL Checkpointer ER_TOO_LONG_KEY: VARCHAR(255)×4 > 3072 → VARCHAR(128)
4. MySQL Checkpointer ER_WRONG_VALUE_COUNT: Uint8Array展开 → Buffer.from()转换
5. FlowConfigService初始化时序: onServerReady时未初始化 → 直接SQL查询绕过