qzl
2.8 KiB
2.8 KiB
Agent Chat Gap Closure Design
Goal: 在不重做已完成任务的前提下，按既定 Task 顺序补齐 Agent Chat Core 的缺口，实现可验证、可审计的端到端闭环。
Current State
- 已完成：Task 2/3/4 的核心数据层、静态配置、模板加载；Task 6/7 的部分骨架（
event_bridge、v1/agent_chat、storage_adapter、asr_fun_asr）。 - 未完成或缺口：Task 1 的 spike 结论文档；Task 5 编排与成本追踪；Task 6
agui_adapter与缺失测试；Task 7multimodal；Task 8 会话审计与 recent 规则；Task 9 E2E 与运行文档闭环。
Design Decisions
- 以“缺口优先”方式执行：仅新增/修改缺失能力，已稳定模块不重构。
- 严格遵循顺序：Task 1 -> 5 -> 6 -> 7 -> 8 -> 9。
- 每个 Task 均采用 TDD：先写失败测试，再做最小实现，通过后再小步重构。
- 统一事件与持久化顺序：以
session.id + seq为唯一顺序锚点，避免流式输出与落库顺序漂移。 - 工具调用成本仍归集到
messages(role=tool)，会话总成本由增量聚合维护。
Component Plan
- Task 1: 新增 spike notes，记录 CrewAI/AG-UI/FunASR 依赖可用性与兜底策略。
- Task 5: 新增
orchestrator.py、cost_tracker.py、events.py，完成三阶段执行与 usage/cost 归一。 - Task 6: 新增
agui_adapter.py，对接现有event_bridge.py与v1/agent_chat/service.py。 - Task 7: 新增
multimodal.py，衔接附件校验、存储元数据、ASR 文本提取。 - Task 8: 增强会话标题策略、recent session 查询、审计字段与限流保护。
- Task 9: 补齐 E2E 与 runbook，执行 bootstrap gate + 分层测试验证。
Data Flow
- 路由接收 AG-UI 请求并解析输入文本/附件。
agui_adapter生成内部命令并触发编排器三阶段执行。- 每阶段产出内部事件，经
event_bridge映射为 AG-UI 标准事件。 service在事务内写入messages并更新sessions汇总字段。- 流式事件向外输出，顺序与
messages.seq保持一致。
Error Handling
- 配置/模板错误：启动前校验并快速失败，返回可追踪错误码。
- 第三方调用错误（LLM/ASR/Storage）：记录标准化失败事件与审计元数据，不泄露敏感信息。
- 持久化冲突：对
session_id + seq冲突执行有限重试并记录告警。
Testing Strategy
- Unit：
cost_tracker、orchestrator、agui_adapter、multimodal、title strategy。 - Integration：
agent_chat路由、事件落库、recent session 选择、会话成本聚合。 - E2E：文本、图片+文本、音频+ASR、文档问答、首页最近会话默认选中。
Approval Note
该设计基于用户确认的“仅按未完成 Task 顺序推进”执行策略。