qzl
50 lines
2.8 KiB
Markdown
50 lines
2.8 KiB
Markdown
# 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 7 `multimodal`；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
|
||
|
||
1. 路由接收 AG-UI 请求并解析输入文本/附件。
|
||
2. `agui_adapter` 生成内部命令并触发编排器三阶段执行。
|
||
3. 每阶段产出内部事件，经 `event_bridge` 映射为 AG-UI 标准事件。
|
||
4. `service` 在事务内写入 `messages` 并更新 `sessions` 汇总字段。
|
||
5. 流式事件向外输出，顺序与 `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 顺序推进”执行策略。
|