qzl/social-app

Fork 0

Files

T

qzl ce6388595b chore: snapshot local dev updates before merge

2026-02-25 17:04:17 +08:00

25 KiB

Raw Blame History

Backend Agent Chat Core (CrewAI + AG-UI) Implementation Plan

实施建议：按任务顺序执行，每个任务先测试失败再实现通过。

Goal: 为后端新增基于 AG-UI 协议的 Agent Chat 核心能力，使用 CrewAI 三阶段模型链路，支持成本追踪、会话落库、多模态输入与 ASR。

Architecture: 采用分层架构：v1/agent_chat 作为 AG-UI 协议边界，core/agent_chat 承担编排与能力层，models + repository 承担持久化。所有调用以 sessions.id 作为链路标识，并在调用级与会话级记录 token/cost。

Tech Stack: FastAPI, Pydantic, SQLAlchemy, Alembic, CrewAI, AG-UI 官方 CrewAI 集成与 Python SDK, DashScope Python SDK, Supabase Storage, pytest。

Replaces: docs/plans/PLAN-agent-chat-crewai-ag-ui-2026-02-25.md

Scope

In Scope
- CrewAI 三阶段链路：Intent -> Execution -> Organization
- LLM 成本采集与会话级聚合
- llm_factory、llms、sessions、messages 四张核心表
- AG-UI 协议路由与事件映射
- CrewAI 模板与静态配置
- 图片/音频/文本文档输入支持
- FunASR 工具接入 fun-asr-realtime-2025-11-07
Out of Scope
- 前端 UI 改造
- 新增向量数据库与长期记忆系统
- 多租户账单结算系统

Acceptance Criteria

AG-UI 路由可完成文本和附件会话，并输出标准事件流。
三阶段模型可配置替换，并在会话中完整落库模型链路。
每次调用记录 token/cost，会话聚合成本可审计。
llm_factory 初始包含 6 厂商，llms 初始包含 2 模型。
CrewAI agents/tasks/workflow 模板可按配置加载并执行。
ASR 工具可将音频转换文本并参与回答。
单测 + 集成 + E2E 通过，覆盖率达到仓库要求。

Requirement Traceability Matrix

Requirement	Description	Tasks	Tests
R1	三阶段模型（意图/执行/整理）	Task 5	`backend/tests/unit/core/agent_chat/test_orchestrator_pipeline.py`
R2	LLM 与工具调用成本采集（统一写入 messages）	Task 5, Task 8	`backend/tests/unit/core/agent_chat/test_cost_tracker.py`, `backend/tests/integration/test_agent_chat_session_persistence.py`
R3	`llm_factory` + `llms` 表	Task 2, Task 3	`backend/tests/integration/test_agent_chat_migration.py`, `backend/tests/integration/test_agent_chat_seed_data.py`
R4	`sessions` + `messages` 会话与历史落库	Task 2, Task 8	`backend/tests/integration/test_agent_chat_session_persistence.py`
R5	AG-UI 协议路由与事件	Task 6	`backend/tests/unit/core/agent_chat/test_agui_adapter.py`, `backend/tests/integration/test_agent_chat_routes.py`
R6	三阶段 prompt/llm/tools 静态配置	Task 4	`backend/tests/unit/core/agent_chat/test_crewai_template_loader.py`
R7	CrewAI templates 加载并供编排执行	Task 4, Task 5	`backend/tests/unit/core/agent_chat/test_crewai_template_loader.py`, `backend/tests/unit/core/agent_chat/test_orchestrator_pipeline.py`
R8	图片/音频/文档输入支持	Task 7	`backend/tests/unit/core/agent_chat/test_multimodal.py`, `backend/tests/e2e/test_agent_chat_flow.py`
R9	FunASR 工具接入 qwen 模型	Task 7	`backend/tests/unit/core/agent_chat/test_asr_fun_asr_tool.py`, `backend/tests/e2e/test_agent_chat_flow.py`

Data Model Design

llm_factory (LLM 厂商表)

继承 TimestampMixin + SoftDeleteMixin。

Field	Type	Constraints	Description
id	UUID	PK, auto	主键
name	String(50)	UNIQUE, NOT NULL	厂商名称：qwen/minimax/kimi/deepseek/doubao/zai
request_url	String(255)	NOT NULL	API 请求 URL
avatar	String(255)	NULL	厂商图标 CDN URL
created_at	DateTime	NOT NULL, DEFAULT now	创建时间
updated_at	DateTime	NOT NULL	更新时间
deleted_at	DateTime	NULL	软删除时间

llms (大模型表)

继承 TimestampMixin + SoftDeleteMixin。

Field	Type	Constraints	Description
id	UUID	PK, auto	主键
factory_id	UUID	FK -> llm_factory(id), NOT NULL	关联厂商
model_code	String(50)	UNIQUE, NOT NULL	模型代码：qwen3.5-flash、deepseek-v3.2
created_at	DateTime	NOT NULL, DEFAULT now	创建时间
updated_at	DateTime	NOT NULL	更新时间
deleted_at	DateTime	NULL	软删除时间

sessions (会话表)

继承 TimestampMixin + SoftDeleteMixin。表示一个完整的对话会话。

Field	Type	Constraints	Description
id	UUID	PK, auto	主键
user_id	UUID	FK -> users(id), NOT NULL	关联用户
title	String(255)	NULL	会话标题（首条消息摘要）
status	Enum	DEFAULT 'pending'	状态：pending/running/completed/failed
last_activity_at	DateTime	NOT NULL	最近活跃时间（首页排序）
message_count	Integer	DEFAULT 0, CHECK >= 0	消息数量冗余字段
total_tokens	Integer	DEFAULT 0, CHECK >= 0	会话总 token 冗余字段
total_cost	Decimal(12,6)	DEFAULT 0, CHECK >= 0	会话总成本冗余字段
created_at	DateTime	NOT NULL, DEFAULT now	创建时间
updated_at	DateTime	NOT NULL	更新时间
deleted_at	DateTime	NULL	软删除时间

Indexes:

idx_sessions_user_created: (user_id, created_at DESC)
idx_sessions_user_last_activity: (user_id, last_activity_at DESC)

messages (对话历史表)

继承 TimestampMixin + SoftDeleteMixin。表示会话中的单条对话记录（一对多）。

Field	Type	Constraints	Description
id	UUID	PK, auto	主键
session_id	UUID	FK -> sessions(id), NOT NULL	关联会话
seq	Integer	NOT NULL	会话内顺序号（唯一：session_id + seq）
role	Enum	NOT NULL	角色：user/assistant/system/tool
content	Text	NOT NULL	对话内容
model_code	String(50)	NULL	使用的模型代码
tool_name	String(100)	NULL	若为工具结果消息，记录工具名
input_tokens	Integer	DEFAULT 0, CHECK >= 0	输入 token 数
output_tokens	Integer	DEFAULT 0, CHECK >= 0	输出 token 数
cost	Decimal(12,6)	DEFAULT 0, CHECK >= 0	本条成本
currency	String(3)	DEFAULT 'USD'	货币单位
latency_ms	Integer	NULL	本条耗时（毫秒）
metadata	JSONB	NULL	扩展字段（工具调用、附件信息等）
created_at	DateTime	NOT NULL, DEFAULT now	创建时间
updated_at	DateTime	NOT NULL	更新时间
deleted_at	DateTime	NULL	软删除时间

Indexes:

idx_messages_session_created: (session_id, created_at DESC)
idx_messages_session_role: (session_id, role)
uq_messages_session_seq: UNIQUE(session_id, seq)

LLM Seed Configuration

配置文件位置：backend/src/core/config/static/agent_chat/llm_catalog.yaml
此文件作为 init_data.py 的唯一种子源，包含 llm_factory 与 llms 初始化数据。

factories:
  - name: qwen
    request_url: https://dashscope.aliyuncs.com/compatible-mode/v1
    avatar: https://cdn.simpleicons.org/alibabacloud/FF6A00
  - name: minimax
    request_url: https://api.minimax.chat/v1
    avatar: https://cdn.simpleicons.org/minimax/1A1A1A
  - name: kimi
    request_url: https://api.moonshot.cn/v1
    avatar: https://cdn.simpleicons.org/moonrepo/3B82F6
  - name: deepseek
    request_url: https://api.deepseek.com/v1
    avatar: https://cdn.simpleicons.org/deepseek/4D6BFE
  - name: doubao
    request_url: https://ark.cn-beijing.volces.com/api/v3
    avatar: https://cdn.simpleicons.org/volkswagen/001E50
  - name: zai
    request_url: https://api.z.ai/v1
    avatar: https://cdn.simpleicons.org/zotero/CC2936

llms:
  - model_code: qwen3.5-flash
    factory_id: qwen
  - model_code: deepseek-v3.2
    factory_id: deepseek

说明：llms.factory_id 在配置中使用厂商 name 作为逻辑标识；init_data.py 先 upsert llm_factory(name, request_url, avatar)，再按 name 解析真实数据库 llm_factory.id 填充 llms.factory_id。

Attachment Storage Policy

用户上传附件与 AI 生成附件均保存到 Supabase Storage（对象存储），不存数据库二进制。
建议 bucket：agent-chat-attachments（私有桶，签名 URL 短时访问）。
路径规范：agent-chat/{user_id}/{session_id}/{message_seq}/{sha256}.{ext}。
访问规范：后端仅保存 object_path，读取时签发短时 URL（默认 10 分钟）。
生命周期：
- 原始附件保留 30 天（可配置）。
- 超期由定时任务清理对象并同步标记 messages.metadata.attachments[].expired=true。
安全规范：
- 仅后端 service_role 可写对象。
- 前端不得直传 service_role；如需直传使用受限 upload token。
- 所有附件写入前必须完成 MIME/大小校验并记录 checksum_sha256。
数据库存储位置：messages.metadata.attachments[]，保存以下元数据：
- object_path
- mime_type
- size
- checksum_sha256
- origin（user_upload/assistant_output）
- preview_text（可选，截断）

Environment Variables Policy

.env.example 不新增任何厂商 API 变量（qwen/minimax/kimi/deepseek/doubao/zai 均不写入）。
.env.example 仅保留通用基础设施变量（本需求新增仅限存储相关）：
- SOCIAL_STORAGE__PROVIDER=supabase
- SOCIAL_STORAGE__BUCKET=agent-chat-attachments
- SOCIAL_STORAGE__SIGNED_URL_TTL_SECONDS=600
- SOCIAL_STORAGE__MAX_FILE_SIZE_MB=20
- SOCIAL_STORAGE__RETENTION_DAYS=30
厂商密钥与 Base URL 通过部署平台密文配置注入，运行时统一由 Settings() 读取。

CrewAI Template Configuration

模板目录：backend/src/core/config/static/agent_chat/crewai/
约定文件：
- agents.yaml：intent/execution/organization 三个 agent 的 role/goal/backstory/default_model
- tasks.yaml：三阶段 task 描述、输入映射、输出 schema
- workflow.yaml：阶段顺序、短路规则、重试策略、超时策略
- ../tools.yaml：可调用工具白名单与参数 schema（位于 agent_chat 根配置）
- prompts/*.md：各阶段 prompt 模板

CrewAI <-> AG-UI Event Bridge

适配入口：backend/src/core/agent_chat/agui_adapter.py。
AG-UI 适配来源：优先使用 ag-ui-protocol/ag-ui 官方仓库中的 integrations/crewai 与 Python SDK（以官方发布版本为准，避免自定义协议漂移）。
运行流程：
1. 接收 AG-UI 请求并转为内部命令。
2. CrewAI 每个阶段通过回调产出内部事件（start/progress/tool/final/error）。
3. agui_adapter.py 将内部事件映射为 AG-UI 事件（message.delta/tool.started/tool.completed/run.completed/run.failed）。
4. service.py 在同一事务边界内写入 messages（含模型、token、cost、tool 信息），并增量更新 sessions 汇总字段。
5. 事件流输出与 DB 落库共用 session.id + message.seq 保证顺序一致。

Session and Cost Rules

Title 生成
- 在首条 user 消息写入后同步生成 sessions.title。
- 策略：取首条用户消息前 24 个可见字符，去空白与换行，不调用额外 LLM。
- 若首条消息为空或仅附件：兜底为 新对话 YYYY-MM-DD HH:MM。
工具调用记账
- 工具调用不单独建表，统一写入 messages（role=tool，并在 metadata.tool 记录 name/status/args_digest）。
- 若工具内部触发 LLM，请将 input_tokens/output_tokens/cost 写入该条 tool message。
- 会话级成本采用增量聚合：sessions.total_cost = sum(messages.cost)。
- 失败调用也可记成本（例如上游已计费但业务失败），通过 metadata.tool.status 区分。
首页“最近打开会话”选择
- 定义：最近一次有消息或工具活动的会话（按 sessions.last_activity_at DESC）。
- 查询：WHERE user_id=:uid AND deleted_at IS NULL ORDER BY last_activity_at DESC LIMIT 1。
- 会话列表同样按 last_activity_at DESC 分页，默认高亮首条结果。

Naming and File Convention

文档命名统一：docs/plans/YYYY-MM-DD-<topic>-plan.md
本计划文件：docs/plans/2026-02-25-agent-chat-crewai-ag-ui-plan.md
配置目录统一：backend/src/core/config/static/agent_chat/
术语约定：代码实体统一使用 AgentChatSession、AgentChatMessage，避免与 SQLAlchemy Session 混淆。

Milestones

M1: Spike 完成，依赖与接口可用
M2: 数据层落地（表、迁移、种子）
M3: 编排层与成本追踪可运行
M4: AG-UI 事件流打通
M5: 多模态 + ASR 打通
M6: 全链路验证 + 文档门禁

Task 1: Spike 与接口基线确认

Files:

Modify: docs/plans/2026-02-25-agent-chat-crewai-ag-ui-plan.md
Create: docs/plans/2026-02-25-agent-chat-crewai-ag-ui-spike-notes.md

Step 1: 写兼容性验证用例（文档化）

验证点：crewai、AG-UI 官方 CrewAI 集成与 Python SDK、DashScope FunASR SDK 返回 usage 字段可得性。

Step 2: 运行最小可用验证命令

Run: uv run python -m pip show crewai
Expected: 能看到版本信息；若无则列入依赖安装任务。

Step 3: 记录替代策略

若 AG-UI 官方 CrewAI 集成不可用，保留最小自定义事件映射适配层（仅实现标准事件，不扩展私有字段）。

Step 4: 提交 spike 结论到 notes

Task 2: 数据模型与迁移（llm_factory, llms, sessions, messages）

Files:

Create: backend/src/models/llm_factory.py
Create: backend/src/models/llm.py
Create: backend/src/models/agent_chat_session.py
Create: backend/src/models/agent_chat_message.py
Modify: backend/src/models/__init__.py
Create: backend/alembic/versions/<timestamp>_create_agent_chat_core_tables.py
Modify: backend/alembic/env.py
Test: backend/tests/integration/test_agent_chat_migration.py

Step 1: 先写失败的迁移测试

覆盖：建表成功、索引存在、降级可回滚。

Step 2: 运行测试确认失败

Run: uv run pytest backend/tests/integration/test_agent_chat_migration.py -v
Expected: FAIL（缺少模型或迁移）。

Step 3: 实现 ORM 与 Alembic 迁移

llm_factory：唯一 name，新增 request_url、avatar，并继承 TimestampMixin + SoftDeleteMixin。
llms：关联 factory_id，仅保留 model_code，并继承 TimestampMixin + SoftDeleteMixin。
sessions：使用 id 作为链路标识，状态为 pending/running/completed/failed，维护 last_activity_at、message_count、total_tokens、total_cost。
messages：按 session_id + seq 一对多存储对话历史，记录单条模型与 token/cost；工具调用统一写 role=tool + metadata.tool。

Step 4: 重新运行测试确认通过

Run: uv run pytest backend/tests/integration/test_agent_chat_migration.py -v
Expected: PASS。

Task 3: 初始化种子数据

Files:

Create: backend/src/core/config/static/agent_chat/llm_catalog.yaml
Modify: backend/src/core/initialization/init_data.py
Test: backend/tests/integration/test_agent_chat_seed_data.py

Step 1: 写失败测试

断言 llm_catalog.yaml 可被加载，且 factories 包含 name/request_url/avatar。
断言 llms 仅包含 model_code/factory_id（逻辑标识）。
断言落库后 llm_factory 包含：qwen,minimax,kimi,deepseek,doubao,zai。
断言落库后 llms 包含：qwen3.5-flash,deepseek-v3.2 且能正确关联到厂商。

Step 2: 跑测试确认失败

Run: uv run pytest backend/tests/integration/test_agent_chat_seed_data.py -v
Expected: FAIL。

Step 3: 实现种子插入逻辑（幂等）

从 backend/src/core/config/static/agent_chat/llm_catalog.yaml 读取初始化数据。
先 upsert llm_factory(name, request_url, avatar)，再解析逻辑 factory_id 写入 llms.factory_id。

Step 4: 再跑测试确认通过

Run: uv run pytest backend/tests/integration/test_agent_chat_seed_data.py -v
Expected: PASS。

Task 4: 静态配置与 CrewAI 模板加载器

Files:

Create: backend/src/core/config/static/agent_chat/crewai/agents.yaml
Create: backend/src/core/config/static/agent_chat/crewai/tasks.yaml
Create: backend/src/core/config/static/agent_chat/crewai/workflow.yaml
Create: backend/src/core/config/static/agent_chat/crewai/prompts/intent.md
Create: backend/src/core/config/static/agent_chat/crewai/prompts/execution.md
Create: backend/src/core/config/static/agent_chat/crewai/prompts/organization.md
Create: backend/src/core/config/static/agent_chat/tools.yaml
Create: backend/src/core/agent_chat/crewai/template_loader.py
Modify: backend/src/core/config/settings.py
Test: backend/tests/unit/core/agent_chat/test_crewai_template_loader.py

Step 1: 写模板加载器失败测试

覆盖：模板缺失、workflow 非法阶段、非法工具、合法加载。

Step 2: 运行测试确认失败

Run: uv run pytest backend/tests/unit/core/agent_chat/test_crewai_template_loader.py -v
Expected: FAIL。

Step 3: 实现配置文件与加载器

支持按任务阶段加载 agent/task/workflow/prompt 与工具白名单。

Step 4: 运行测试确认通过

Run: uv run pytest backend/tests/unit/core/agent_chat/test_crewai_template_loader.py -v
Expected: PASS。

Task 5: CrewAI 编排与成本追踪

Files:

Create: backend/src/core/agent_chat/orchestrator.py
Create: backend/src/core/agent_chat/cost_tracker.py
Create: backend/src/core/agent_chat/events.py
Test: backend/tests/unit/core/agent_chat/test_cost_tracker.py
Test: backend/tests/unit/core/agent_chat/test_orchestrator_pipeline.py

Step 1: 写失败测试（成本计算与阶段顺序）

验证调用级 usage 记录、会话级 total_cost 聚合。

Step 2: 运行测试确认失败

Run: uv run pytest backend/tests/unit/core/agent_chat/test_cost_tracker.py backend/tests/unit/core/agent_chat/test_orchestrator_pipeline.py -v
Expected: FAIL。

Step 3: 实现最小可用编排

Intent/Execution/Organization 三阶段串行。
每阶段记录 model_id/factory_id/tokens/cost。

Step 4: 运行测试确认通过

Run: uv run pytest backend/tests/unit/core/agent_chat/test_cost_tracker.py backend/tests/unit/core/agent_chat/test_orchestrator_pipeline.py -v
Expected: PASS。

Task 6: AG-UI 路由与事件映射

Files:

Create: backend/src/core/agent_chat/agui_adapter.py
Create: backend/src/core/agent_chat/event_bridge.py
Create: backend/src/v1/agent_chat/schemas.py
Create: backend/src/v1/agent_chat/service.py
Create: backend/src/v1/agent_chat/dependencies.py
Create: backend/src/v1/agent_chat/router.py
Modify: backend/src/v1/router.py
Test: backend/tests/unit/core/agent_chat/test_agui_adapter.py
Test: backend/tests/unit/core/agent_chat/test_event_bridge.py
Test: backend/tests/integration/test_agent_chat_routes.py
Test: backend/tests/integration/test_agent_chat_event_persistence.py

Step 1: 写失败测试（事件映射）

覆盖 message.delta/tool.started/tool.completed/run.completed/run.failed。

Step 2: 写失败测试（路由集成）

覆盖鉴权、正常会话、错误返回、事件与 messages.seq 顺序一致。

Step 3: 运行测试确认失败

Run: uv run pytest backend/tests/unit/core/agent_chat/test_agui_adapter.py backend/tests/integration/test_agent_chat_routes.py -v
Expected: FAIL。

Step 4: 实现适配与路由

AG-UI 请求转换为内部 command。
使用 AG-UI 官方 CrewAI 集成 SDK 接收/发送标准事件，CrewAI 回调事件通过 event_bridge.py 统一转换。
内部事件转换为 AG-UI 事件流。
在 service.py 中同事务写入 messages 并更新 sessions.last_activity_at/message_count/total_tokens/total_cost。

Step 5: 运行测试确认通过

Run: uv run pytest backend/tests/unit/core/agent_chat/test_agui_adapter.py backend/tests/unit/core/agent_chat/test_event_bridge.py backend/tests/integration/test_agent_chat_routes.py backend/tests/integration/test_agent_chat_event_persistence.py -v
Expected: PASS。

Task 7: 多模态输入与 ASR 工具

Files:

Create: backend/src/core/agent_chat/multimodal.py
Create: backend/src/core/agent_chat/storage_adapter.py
Create: backend/src/core/agent_chat/tools/asr_fun_asr.py
Test: backend/tests/unit/core/agent_chat/test_multimodal.py
Test: backend/tests/unit/core/agent_chat/test_storage_adapter.py
Test: backend/tests/unit/core/agent_chat/test_asr_fun_asr_tool.py

Step 1: 写失败测试（文件校验与解析）

覆盖图片/音频/文档 MIME、大小、异常分支。
覆盖附件对象存储路径生成、签名 URL 获取与元数据回写 messages.metadata.attachments。

Step 2: 写失败测试（ASR 工具）

覆盖 DashScope SDK 请求构造、响应解析、超时降级。

Step 3: 运行测试确认失败

Run: uv run pytest backend/tests/unit/core/agent_chat/test_multimodal.py backend/tests/unit/core/agent_chat/test_storage_adapter.py backend/tests/unit/core/agent_chat/test_asr_fun_asr_tool.py -v
Expected: FAIL。

Step 4: 实现最小可用功能

音频走 DashScope Python SDK（fun-asr-realtime-2025-11-07，qwen）。
输出统一 AttachmentContext 结构。
附件二进制写入 Supabase Storage 私有桶 agent-chat-attachments，数据库仅写元数据。

Step 5: 运行测试确认通过

Run: uv run pytest backend/tests/unit/core/agent_chat/test_multimodal.py backend/tests/unit/core/agent_chat/test_storage_adapter.py backend/tests/unit/core/agent_chat/test_asr_fun_asr_tool.py -v
Expected: PASS。

Task 8: 会话落库、可观测性与安全约束

Files:

Modify: backend/src/v1/agent_chat/service.py
Modify: backend/src/core/agent_chat/orchestrator.py
Test: backend/tests/unit/core/agent_chat/test_session_title_strategy.py
Test: backend/tests/integration/test_agent_chat_session_recent_selection.py
Test: backend/tests/integration/test_agent_chat_session_persistence.py

Step 1: 写失败测试（sessions 写入）

断言 session.id 链路可追踪、title/status/last_activity_at、消息与工具成本明细均入库。
用例 A（title 生成）：首条用户消息自动生成 title，超过长度截断，空文本回退 新对话 YYYY-MM-DD HH:MM。
用例 B（工具成本聚合）：工具调用写 role=tool 消息，sessions.total_cost = sum(messages.cost)，失败调用可记费。
用例 C（最近会话选择）：同一用户多个会话按 last_activity_at DESC 返回首页默认会话。

Step 2: 运行测试确认失败

Run: uv run pytest backend/tests/integration/test_agent_chat_session_persistence.py -v
Expected: FAIL。

Step 3: 实现持久化与审计字段写入

禁止明文存储密钥与敏感音频原始数据。
新增路由级限流与滥用保护策略（按用户或 token）。
附件审计日志记录拒绝原因（MIME、大小、扩展名、解析失败）。

Step 4: 运行测试确认通过

Run: uv run pytest backend/tests/integration/test_agent_chat_session_persistence.py -v
Expected: PASS。

Task 9: 全链路验证与文档更新

Files:

Create: backend/tests/e2e/test_agent_chat_flow.py
Create: backend/tests/e2e/test_agent_chat_recent_session_home.py
Modify: .env.example
Modify: docs/runtime/runtime-runbook.md

Step 1: 写 E2E 失败测试

场景：文本、图片+文本、音频+ASR、文档问答、最近会话首页默认选中。

Step 2: 运行 E2E 确认失败

Run: uv run pytest backend/tests/e2e/test_agent_chat_flow.py -v
Expected: FAIL（功能未完全联通）。

Step 3: 修补缺口直至通过

Step 3.1: 更新环境变量样例

仅新增存储相关变量到 .env.example，不新增任何厂商 API 变量。

Step 4: 全量回归验证

Run: bash infra/scripts/app-up.sh (or docker compose run --rm init-job bootstrap for production)
Run: uv run pytest backend/tests/unit/core/agent_chat -v
Run: uv run pytest backend/tests/integration -k agent_chat -v
Run: uv run pytest backend/tests/e2e/test_agent_chat_flow.py -v
Expected: 全部 PASS。

Step 5: 供应链与安全检查

Run: uv run pip check
Run: uv run pytest backend/tests/integration -k security -v
Expected: 依赖冲突为 0，关键安全测试通过。

Dependency Graph

Task 1 -> Task 2/4（先确认依赖与接口）
Task 2 -> Task 3/5/8（数据层先行）
Task 4 -> Task 5（编排依赖静态配置与 CrewAI 模板）
Task 5 -> Task 6/7（路由与多模态依赖编排核心）
Task 6 + Task 7 + Task 8 -> Task 9（全链路验证）

Risk Controls

AG-UI 官方 CrewAI 集成版本波动：固定版本并保留 agui_adapter.py 最小兜底映射。
usage 字段不一致：cost_tracker.py 保留 raw_usage 并标准化。
附件安全：严格 MIME/大小限制，禁止敏感原文落库。
路由滥用风险：对 agent_chat 接口增加限流与失败惩罚策略。
供应链风险：新增依赖必须完成许可证和漏洞扫描。
延迟风险：三阶段支持短路策略（简单意图可跳过整理阶段）。

Verification Checklist

Alembic upgrade/downgrade 成功
init-data 幂等且种子完整
AG-UI 事件流字段符合标准
sessions 审计字段完整
多模态与 ASR 路径可用
覆盖率与关键测试通过

25 KiB Raw Blame History Unescape Escape

Backend Agent Chat Core (CrewAI + AG-UI) Implementation Plan

Scope

Acceptance Criteria

Requirement Traceability Matrix

Data Model Design

llm_factory (LLM 厂商表)

llms (大模型表)

sessions (会话表)

messages (对话历史表)

LLM Seed Configuration

Attachment Storage Policy

Environment Variables Policy

CrewAI Template Configuration

CrewAI <-> AG-UI Event Bridge

Session and Cost Rules

Naming and File Convention

Milestones

Task 1: Spike 与接口基线确认

Task 2: 数据模型与迁移（llm_factory, llms, sessions, messages）

Task 3: 初始化种子数据

Task 4: 静态配置与 CrewAI 模板加载器

Task 5: CrewAI 编排与成本追踪

Task 6: AG-UI 路由与事件映射

Task 7: 多模态输入与 ASR 工具

Task 8: 会话落库、可观测性与安全约束

Task 9: 全链路验证与文档更新

Dependency Graph

Risk Controls

Verification Checklist

25 KiB

Raw Blame History