social-app/docs/plans/2026-03-04-agent-hard-reset-design.md

# Agent 后端硬切重构设计

## 目标

- 一次性移除现有 Agent 运行时代码、测试和旧文档契约，避免新旧方案并存。
- 仅从后端重新设计 Agent 体系，不依赖前端实现细节。
- 新方案必须满足以下六项要求：
  1. 配置层可通过 `.env` 驱动 LLM API Key。
  2. 对话与 resume 通过 Celery 队列处理，不阻塞 Web 主线程。
  3. `v1/agent` 仅负责路由组织与服务调用，核心逻辑在 `core/agent`。
  4. 按 CrewAI 官方模型组织 Agent/Task/Crew/Flow/Tools。
  5. 按 AG-UI 协议输出事件，优先使用 `ag-ui-crewai` 适配库。
  6. 使用 LiteLLM 统计每次 LLM 调用的 token 和 cost。

## 设计原则

- 单一职责：HTTP 层只做协议和鉴权，编排与执行下沉到核心层。
- 异步优先：长耗时推理、工具调用、恢复流程全部异步化。
- 协议优先：AG-UI 作为唯一事件契约，不维护自定义事件方言。
- 可观测性优先：每次 run、每次 stage、每次 LLM 调用可追踪。
- 配置单一来源：所有密钥和模型配置只走 `core.config.settings`。

## 目标架构

### 1) 分层

- `backend/src/v1/agent/`
  - `router.py`: 暴露 HTTP/SSE 接口。
  - `schemas.py`: 请求/响应 DTO 和输入校验。
  - `dependencies.py`: DI 装配。
  - `service.py`: 薄服务，仅调用 `core/agent` 应用服务。
- `backend/src/core/agent/`
  - `application/`: run/resume 应用服务。
  - `domain/`: run 状态机、resume 幂等语义、错误模型。
  - `infrastructure/crewai/`: CrewAI Agent/Task/Crew/Flow 装配与执行。
  - `infrastructure/agui/`: AG-UI 事件映射与 SSE 序列化。
  - `infrastructure/litellm/`: LiteLLM 客户端与 usage/cost 拦截器。
  - `infrastructure/queue/`: Celery task producer/consumer。

### 1.1) 配置来源与合并策略

- Agent 运行配置由两部分组成：
  - 数据库存量配置：`system_agents`（每种 agent_type 对应 llm 与 llm_config）。
  - 静态模板配置：`backend/src/core/config/static/crewai/*.yaml`（角色描述、任务模板、workflow、tools）。
- 合并策略：
  - `llm` 与 `llm_config` 以 `system_agents` 为准。
  - prompt 模板、task 描述、flow stage、tool 白名单以 static/crewai 为准。
  - 若任一 agent_type 在 `system_agents` 缺失，运行前失败并返回受控错误。

### 2) 核心运行链路

1. `POST /api/v1/agent/runs` 只负责参数校验和鉴权。
2. 路由调用 `AgentRunAppService.enqueue_run()`，写入 run 记录并投递 Celery。
3. Worker 执行 `run_agent_task`：
   - 读取 run 上下文。
   - 构建 CrewAI `Agent/Task/Crew/Flow`。
   - 通过 `ag-ui-crewai` 将执行事件转为 AG-UI 标准事件。
   - 每次 LLM 调用由 LiteLLM 中间层记录 token/cost。
4. 事件落库并发布到事件通道（Redis Stream/Channel）。
5. SSE 接口从事件通道读取并持续推送，直到 `RUN_FINISHED` 或 `RUN_ERROR`。

### 3) Resume 链路

1. `POST /api/v1/agent/runs/{run_id}/resume` 校验 `interrupt_id` 与决策 payload。
2. 调用 `enqueue_resume()` 投递 `resume_agent_task`。
3. Worker 在事务内做并发控制：
   - `run_id + interrupt_id` 幂等锁。
   - 过期校验与状态迁移。
4. 恢复后继续 CrewAI Flow，事件按 AG-UI 继续输出。

### 4) Session 状态持久化

- 使用 `sessions.state_snapshot` 作为运行态单一快照来源。
- 快照至少包含：
  - run 上下文（thread_id、run_id、stage）
  - pending_tool_calls（tool_call_id、tool_name、args、status、expires_at）
  - correlation 索引（tool_call_id -> message_id / step_id）
- 所有中断/恢复均以 `state_snapshot` 事务更新为准，避免内存态漂移。

### 5) 会话与消息落库模型

- 会话主表：`sessions`
  - 新建 run 时写入：`id/user_id/session_type/status=running/last_activity_at`。
  - 运行中持续更新：`status`、`last_activity_at`、`message_count`、`total_tokens`、`total_cost`、`state_snapshot`。
  - 运行结束更新：
    - 成功：`status=completed`
    - 失败：`status=failed`
- 消息表：`messages`
  - 用户输入落库为 `role=user`（每次 run 开始时先写入）。
  - 模型输出落库为 `role=assistant`（按最终聚合文本落库，保留 metadata 记录增量信息）。
  - 工具调用结果落库为 `role=tool`，并写入 `tool_name` 与 `metadata.tool_call_id`。
  - `seq` 由每个 `session_id` 内单调递增分配，满足 `uq_messages_session_seq`。
- 计量落库：每次 LLM 调用的 usage/cost 先写消息级，再聚合更新到 session 级。

## 六项要求落地映射

### 要求 1: `.env` 驱动 LLM API Key

- 新增 `LLMSettings` 到 `core.config.settings.Settings`，统一定义：
  - `SOCIAL_LLM__PROVIDER_KEYS__DASHSCOPE`
  - `SOCIAL_LLM__PROVIDER_KEYS__MINIMAX`
  - `SOCIAL_LLM__PROVIDER_KEYS__MOONSHOT`
  - `SOCIAL_LLM__PROVIDER_KEYS__DEEPSEEK`
  - `SOCIAL_LLM__PROVIDER_KEYS__ARK`
  - `SOCIAL_LLM__PROVIDER_KEYS__ZAI`
- 禁止 `os.environ` 直接读取密钥。

### 要求 2: 对话和 resume 走 Celery

- Web 层不直接执行编排。
- `run`/`resume` 一律入队，Worker 处理，Web 仅做事件流转发。
- 加入任务级超时、重试、死信策略。

### 要求 3: v1 仅路由与调用

- `v1/agent/service.py` 仅保留应用服务调用和错误映射。
- 任何编排、状态机、工具执行逻辑禁止进入 `v1`。

### 要求 4: CrewAI 官方流程

- 采用 CrewAI 原生对象：`Agent`、`Task`、`Crew`、`Flow`。
- tools 通过 CrewAI Tool 机制注册，不做平行实现。
- 任务模板与 agent 配置集中化（静态模板 + 运行时拼装）。
- 配置拼装明确依赖 `system_agents + static/crewai`，不再使用双套来源。

### 要求 5: AG-UI + ag-ui-crewai

- 事件集遵循 AG-UI 协议，生命周期闭环：
  - `RUN_STARTED`
  - 流式消息和工具事件
  - 终态 `RUN_FINISHED` 或 `RUN_ERROR`
- 优先引入 `ag-ui-crewai` 做 CrewAI 到 AG-UI 的桥接，避免重复造轮子。

### 要求 6: LiteLLM token/cost 统计

- 所有 LLM 调用通过 LiteLLM 统一出入口。
- 按调用粒度记录：`input_tokens`、`output_tokens`、`total_tokens`、`cost`、`currency`。
- 按 run 粒度聚合并落库，支持后续计费和审计。

## 数据与可观测性

- 保留现有 Agent 相关表结构，不在本次硬切做数据库破坏性变更。
- 新增事件日志与调用指标落点（如已有字段不足，后续增量迁移）。
- 日志使用结构化字段：`run_id`、`task_id`、`stage`、`tool_name`、`llm_model`、`latency_ms`。
- 持久化原则：run/resume 的关键状态变更必须可重放，禁止仅保存在内存。

## 事务边界

- `run` 入口事务：创建或加载 `session` + 写入用户消息。
- `worker` 执行事务（可分阶段短事务）：
  - 阶段开始：更新 `session.status/state_snapshot`。
  - LLM 返回：写 assistant/tool 消息 + 更新 token/cost 聚合。
  - 中断：写 `pending_tool_calls` 到 `state_snapshot` 并提交。
  - 完成：更新终态 `session.status` 并提交。
- `resume` 事务：校验 `interrupt_id` 与 ownership，CAS 更新 `state_snapshot`，然后进入后续执行事务。

## 错误处理与安全

- API Key 缺失启动即失败，不进入运行态。
- 外部工具入参统一白名单和 schema 校验。
- resume 决策必须鉴权与会话所有权校验。
- 错误响应遵循 RFC 7807，避免泄漏敏感上下文。

## 工具调用与恢复语义

- 工具分三类：
  - 前端工具：由 `RunAgentInput.tools` 提供能力声明，触发 interrupt，由客户端执行并回传 result。
  - 后端工具（需审批）：先 interrupt 给前端审批；审批通过后由后端执行，不由前端执行。
  - 后端工具（直执）：后端直接执行。
- 一致性约束：
  - 每个 tool_result 必须携带 `tool_call_id`。
  - 后端仅接受当前 `state_snapshot.pending_tool_calls` 中存在且状态合法的 `tool_call_id`。
  - 若收到未知/已消费/过期 `tool_call_id`，立即产出 `RUN_ERROR` 并记录审计日志。

## 测试策略

- 单元测试：
  - 配置解析与 key 解析
  - run/resume 状态机与幂等
  - LiteLLM usage 聚合
- 集成测试：
  - API 入队
  - Worker 消费
  - SSE 事件顺序与终态
- E2E：
  - run 成功链路
  - interrupt + resume 链路
  - tool 调用链路

## 迁移策略

- 阶段 0（本次）：硬切删除旧代码、旧测试、旧文档契约。
- 阶段 1：搭建新架构骨架和最小可运行 run 流程。
- 阶段 2：接入 CrewAI + ag-ui-crewai + LiteLLM 完整链路。
- 阶段 3：补齐可观测性、压测与稳定性治理。

## 验收标准

- 后端仓库不存在旧 `v1/agent` 和 `core/agent` 旧实现。
- 所有 Agent 相关旧测试与旧文档契约已移除。
- 新方案设计文档明确覆盖六项要求并可进入实现阶段。