ai-chatbot/docs/Agent真正变聪明-系统级整改清单-2026-03-16.md

# Agent 真正变聪明：系统级整改清单（2026-03-16）

> 目标：不是继续给 Agent 打零散补丁，而是把它从“很多聪明 patch 的组合体”，升级成“统一、稳定、可解释、可扩展的对话智能系统”。
>
> 适用范围：
> - `app/(chat)/api/chat/route.ts`
> - `lib/ai/auto-agent-graph.ts`
> - `lib/ai/smart-analyzer.ts`
> - `lib/ai/conversation-state-protocol.ts`
> - `lib/ai/conversation-*`
> - `lib/ai/runtime/*`
> - `lib/video-agent/*`
> - 画布上下文、图片工作流、视频工作流

---

## 0. 先说结论

### 0.1 现在 Agent 为什么“看起来不聪明”

不是单纯模型不够强，而是系统层面还有 5 个根问题：

1. **任务边界不稳定**
   - 新任务、继续任务、只聊天、只看图、只要提示词、直接执行，经常互相串。

2. **上下文污染严重**
   - 当前输入、历史图片、画布图片、上一轮 workflow、长期记忆，经常一起灌给模型。
   - 结果就是用户说一句“你好”，系统也可能把它理解成“继续上一轮修图”。

3. **理解层和执行层没完全解耦**
   - 一部分逻辑已经进 protocol / subagent / runtime。
   - 但还有不少判断仍然散在 `chat/route.ts`，导致行为不稳定、修改成本高。

4. **模型链路不够统一**
   - planner、analyzer、最终回复、图片执行、视频执行并不是同一套稳定规则。
   - 之前就出现过：Agent 默认模型是豆包，但最终对话回复走了别的供应商。

5. **超时退化不够“保正确”**
   - 一旦 `runAutoAgentGraph`、图像总结、Provider 流式返回超时，系统容易退化成“还能跑，但不对题”。

### 0.2 我们这次整改的目标

这次不是“继续修 10 个 bug”，而是把 Agent 升级成：

- **先判断任务，再选择上下文**
- **先选正确路线，再决定模型和工具**
- **宁可简单，也不跑偏**
- **即使失败，也要明确告诉用户为什么失败**

---

## 1. 这次整改的总原则

### 1.1 一个原则：先判任务，再喂上下文

以后不能再用“把所有上下文先塞给模型，再让模型自己判断”的方式。

要改成：

1. 先判断这轮是：
   - 新任务
   - 连续任务
   - 只分析
   - 只要提示词
   - 直接执行
   - 聊天寒暄
2. 再按这个任务类型，裁剪要喂给模型的上下文

### 1.2 一个原则：执行型和对话型必须分开

以后要明确分两类：

- **对话型回合**
  - 聊天
  - 看图分析
  - 提示词整理
  - 澄清确认

- **执行型回合**
  - 生图
  - 修图
  - 生视频
  - 分镜确认执行

对话型回合不能轻易被旧工作流拖进执行型链路。

### 1.3 一个原则：失败也要“可解释”

以后不允许再出现这几种体验：

- 用户发了消息，看起来“没反应”
- 数据库里只存了 keepalive
- 模型报错了，但前端没显示
- 回退了，但用户不知道系统为什么回退

---

## 2. 总体架构目标

目标架构：

1. **Task Boundary Layer**
2. **Context Pruning Layer**
3. **Conversation State Protocol**
4. **Planner / Subagent Layer**
5. **Execution Gate Layer**
6. **Persistence / Event Layer**
7. **Frontend Projection Layer**

一句话解释：

- **边界层**决定“你这轮到底要干嘛”
- **裁剪层**决定“该给模型看哪些上下文”
- **协议层**负责统一状态读写
- **子代理层**负责专业领域判断
- **执行门控层**负责确认、取消、修改、超时回退
- **事件层**负责可追踪
- **前端层**负责把系统理解结果明确展示给用户

---

## 3. 五大整改块

---

## 3.1 任务理解层

### 3.1.1 目标

让 Agent 先稳定判断：

- 这是新任务还是继续任务
- 这是对话型还是执行型
- 这是只分析、只要提示词、还是直接执行

### 3.1.2 当前问题

当前系统虽然已经有：

- `conversation-action-resolver`
- `smart-analyzer`
- `skill-router`
- `auto-agent-graph`

但这几层对“任务边界”的定义还不完全统一。

典型问题：

1. “你好”被旧图片 workflow 拖成连续修图
2. “帮我写这张图的提示词”被拖成生图/修图流程
3. 用户只是问“这个图怎么写提示词”，系统却提前进入执行链

### 3.1.3 必做改造

#### A. 新增统一任务边界分类器

建议新增：

- `lib/ai/runtime/task-boundary-classifier.ts`

输出统一结构：

```ts
type TaskBoundaryDecision = {
  taskType:
    | "greeting"
    | "chat"
    | "analysis_only"
    | "prompt_only"
    | "execution_image"
    | "execution_video"
    | "workflow_followup";
  taskMode: "new" | "continue" | "revise" | "confirm" | "cancel";
  shouldUseCanvasContext: boolean;
  shouldUseHistoryImages: boolean;
  shouldUseWorkflowMemory: boolean;
  shouldAllowExecution: boolean;
  confidence: number;
  reason: string;
};
```

#### B. 明确任务优先级规则

优先级必须写死在系统里，不能全靠模型猜：

1. `prompt_only` > `workflow_followup`
2. `analysis_only` > `execution_image`
3. `greeting` > 任意旧 workflow
4. `confirm/cancel/revise` > 普通分析
5. 当前上传图 > 历史图 > 画布背景图

#### C. 给“非执行任务”开快路径

以下场景应该直接走快路径：

- 纯打招呼
- 只要提示词
- 只看图分析
- 只问建议

这些回合不应该再先跑完整 `runAutoAgentGraph`。

### 3.1.4 落点文件

- `app/(chat)/api/chat/route.ts`
- `lib/ai/conversation-action-resolver.ts`
- `lib/ai/smart-analyzer.ts`
- `lib/ai/runtime/task-boundary-classifier.ts`（新增）

### 3.1.5 验收标准

- “你好”永远不被识别为连续修图/连续生图
- “帮我写这张图的提示词”永远不直接触发执行
- “按照刚才那个提示词，再生成 4 张”会稳定识别为连续生图执行

---

## 3.2 记忆层

### 3.2.1 目标

让 Agent 的记忆从“混在一起”变成“分层可控”。

### 3.2.2 当前问题

现在虽然已经有：

- `promptMemory`
- `imageWorkflowMemory`
- `storyboardPreferenceMemory`
- `threadState`
- `workingState`

但问题是：

1. 历史 workflow 容易污染当前回合
2. 画布上下文太大，容易把简单任务拖重
3. “当前相关记忆”和“长期偏好记忆”还没完全分层

### 3.2.3 必做改造

#### A. 拆成 4 层记忆

1. **Turn Memory**
   - 当前回合输入
   - 当前上传图片
   - 当前画布选中

2. **Task Memory**
   - 当前任务工作流状态
   - 当前任务目标图
   - 当前任务优化提示词

3. **Session Memory**
   - 当前会话最近 3~5 个高相关任务摘要

4. **Preference Memory**
   - 用户长期偏好
   - 常用比例
   - 常用宫格
   - 常用确认习惯

#### B. 增加“记忆衰减/降权”机制

如果旧 workflow 满足任一条件，应自动降权：

- 超过 N 轮未继续
- 当前上传了新图
- 当前任务类型和旧任务类型冲突
- 用户显式说“重新来 / 新开一个 / 别按刚才那个”

#### C. 建立 relevance score

建议新增：

- `lib/ai/runtime/memory-relevance.ts`

对候选记忆打分：

- 当前上传图命中：+100
- 当前选中图命中：+90
- 显式引用“上一张 / 第三张 / 这个提示词”：+80
- 同类任务：+40
- 同会话最近 3 轮：+20
- 超过 10 轮未使用：-50

以后只把 top-k 记忆喂给 Planner。

### 3.2.4 落点文件

- `lib/ai/conversation-memory-composer.ts`
- `lib/ai/conversation-thread-state-builder.ts`
- `lib/ai/runtime/agent-thread-state.ts`
- `lib/ai/runtime/memory-relevance.ts`（新增）

### 3.2.5 验收标准

- 同一会话里，旧图不再轻易干扰新上传图任务
- 简单聊天不再带上大段无关画布上下文
- “继续上一个提示词”仍然能稳定命中

---

## 3.3 路由层

### 3.3.1 目标

让 Planner、Analyzer、最终回复模型、执行模型之间的职责彻底清晰。

### 3.3.2 当前问题

现在的问题不是“没有路由”，而是“路由规则不够统一”：

1. planner 模型和 reply 模型曾经不一致
2. analyzer 有时会被别的 provider 抢走
3. 生图/修图/视频执行模型与对话模型混杂
4. provider 报错或额度不足时，回退不够统一

### 3.3.3 必做改造

#### A. 明确 4 类模型槽位

统一定义：

1. `plannerModel`
2. `analyzerModel`
3. `replyModel`
4. `executionModel`

而不是所有地方都混着叫“当前模型”。

#### B. Agent 模式默认规则

在 `selectedChatModel = auto` 或进入 Agent 模式时：

- `plannerModel` = Agent 默认模型
- `analyzerModel` = Agent 默认模型优先，多模态能力不足时再回退
- `replyModel` = Agent 默认模型
- `executionModel` = 按任务类型路由

#### C. Provider 健康与额度状态缓存

建议新增：

- `lib/ai/runtime/provider-health.ts`

缓存内容：

- 最近错误类型
- 最近额度不足
- 最近超时率
- 最近 5 分钟成功率

如果某 provider 连续报：

- `quota not enough`
- `403`
- `timeout`

则在短时间内直接降级，避免用户连续踩坑。

### 3.3.4 落点文件

- `app/(chat)/api/chat/route.ts`
- `lib/ai/model-router.ts`
- `lib/ai/smart-analyzer.ts`
- `lib/ai/auto-agent-graph.ts`
- `lib/ai/runtime/provider-health.ts`（新增）

### 3.3.5 验收标准

- Agent 模式不会再出现“规划走豆包、回复走别家”的错位
- 上游 provider 额度不足时，能快速回退或明确报错
- 对话模型、执行模型职责清晰

---

## 3.4 执行层

### 3.4.1 目标

让执行系统遵守：

- 该确认时必须确认
- 该取消时必须停
- 该提示时只提示，不执行
- 该失败时明确失败

### 3.4.2 当前问题

虽然我们已经做了很多 protocol / workflow 事件：

- clarification
- storyboard confirm
- revision
- cancel
- execution started/completed
- video generation started/completed/failed

但执行层还存在 3 个结构问题：

1. 快路径不够多
2. timeout fallback 仍偏重
3. “对话型输出”和“执行型输出”没有完全剥离

### 3.4.3 必做改造

#### A. 建立 execution policy gate

建议新增：

- `lib/ai/runtime/execution-policy-gate.ts`

统一做这些判定：

- 当前回合是否允许执行
- 当前回合是否必须先确认
- 当前回合是否应该只输出提示词
- 当前回合是否应该只对话

#### B. 扩展 fast-path 列表

必须内建以下快路径：

1. greeting fast-path
2. prompt-only fast-path
3. analysis-only fast-path
4. confirmation fast-path
5. cancel fast-path

#### C. timeout 退化策略升级

以后 timeout 退化规则应改成：

- `execute` 超时 → 不自动换任务类型
- `planner` 超时 → 退到简单规则，但不跨任务边界
- `provider` 超时 → 直接明确告诉用户该 provider 超时

一句话：

**退化后可以更笨，但不能更错。**

### 3.4.4 落点文件

- `lib/ai/runtime/middlewares/human-confirmation-gate.ts`
- `lib/ai/runtime/execution-policy-gate.ts`（新增）
- `app/(chat)/api/chat/route.ts`
- `lib/video-agent/storyboard-chat-followup.ts`

### 3.4.5 验收标准

- “只要提示词”绝不执行生图
- “确认开始生成”绝不只回复聊天
- provider 报错时前端总能看到明确原因

---

## 3.5 前端交互层

### 3.5.1 目标

让用户知道 Agent 当前理解成了什么，而不是靠猜。

### 3.5.2 当前问题

现在前端可见性还不够：

1. 用户不知道系统把这轮理解成聊天、分析还是执行
2. 用户不知道系统到底引用了哪张图
3. 用户不知道系统为什么突然继续上一轮任务
4. 用户不知道系统为什么没执行

### 3.5.3 必做改造

#### A. 增加“本轮理解摘要”

建议在输入框附近或 assistant 第一段里展示：

- 本轮类型：`聊天 / 分析 / 提示词 / 生图 / 修图 / 视频`
- 目标来源：`当前上传 / 画布选中 / 历史结果 / 上一轮提示词`
- 是否会执行：`仅分析 / 待确认 / 直接执行`

#### B. 增加“任务切换提示”

当系统从旧 workflow 切到新任务时，前端明确显示：

- “已识别为新任务，不继续沿用上一轮修图流程”

当系统继续旧任务时，显示：

- “已继续上一轮修图流程”

#### C. 协议调试面板继续升级

当前已有 `ProtocolDebugPanel`，建议继续加：

- 当前任务边界摘要
- 当前记忆裁剪摘要
- 当前模型槽位摘要（planner / reply / execution）
- 当前 provider 健康状态

### 3.5.4 落点文件

- `components/chat.tsx`
- `components/protocol-debug-panel.tsx`
- `components/canvas/CanvasChatPanel.tsx`

### 3.5.5 验收标准

- 用户能看见“系统理解成什么”
- 用户能看见“为什么这轮不执行”
- debug 时能看见模型和 workflow 生命周期

---

## 4. 实施顺序（必须按这个顺序）

### P0：先止血

1. greeting fast-path
2. prompt-only fast-path
3. stream provider 错误明确回显
4. Agent 模式 replyModel 跟随 Agent 默认模型

> 这几项已经部分落地，但要继续收边并补测试。

### P1：统一任务边界

1. `task-boundary-classifier`
2. 统一 taskType / taskMode / allowExecution
3. 对 route 中旧 heuristics 收口

### P2：统一记忆裁剪

1. relevance scoring
2. session/task/preference 记忆分层
3. 旧 workflow 自动降权

### P3：统一模型链路

1. planner / analyzer / reply / execution 四槽位
2. provider health cache
3. 额度不足/超时自动降级

### P4：统一前端解释性

1. 本轮理解摘要
2. 任务切换提示
3. 调试面板生命周期摘要

---

## 5. 开发清单（可直接排期）

### 5.1 任务理解层

- [ ] 新增 `lib/ai/runtime/task-boundary-classifier.ts`
- [ ] 把 `conversation-action-resolver` 和 `smart-analyzer` 结果统一映射到 `taskType`
- [ ] 增加 `taskMode`：`new/continue/revise/confirm/cancel`
- [ ] 增加 fast-path 优先级表

### 5.2 记忆层

- [ ] 新增 `memory-relevance.ts`
- [ ] `composeConversationMemory` 支持 top-k 裁剪
- [ ] 为 workflow memory 增加过期/降权规则
- [ ] 为 prompt-only / analysis-only 场景建立独立上下文模板

### 5.3 路由层

- [ ] 统一 planner / analyzer / reply / execution 槽位
- [ ] Agent replyModel 跟随 Agent 默认模型
- [ ] provider health 状态缓存
- [ ] 上游 quota / timeout 短时熔断

### 5.4 执行层

- [ ] 新增 `execution-policy-gate.ts`
- [ ] clarification / prompt-only / analysis-only 全部走快路径
- [ ] timeout fallback 改成“保正确优先”
- [ ] 错误统一映射为用户可理解消息

### 5.5 前端层

- [ ] 增加“本轮理解摘要”
- [ ] 增加“任务切换提示”
- [ ] Protocol Debug 增加模型槽位摘要
- [ ] Protocol Debug 增加上下文裁剪摘要

---

## 6. 这次整改完成后，用户体验应该变成什么样

### 场景 1：用户说“你好”

系统行为：

- 识别为 `greeting`
- 不读取旧修图 workflow
- 不做大规模图像分析
- 1 秒内稳定回复

### 场景 2：用户上传图片，说“帮我写这张图的提示词”

系统行为：

- 识别为 `prompt_only`
- 只分析当前图片
- 不进入生图/修图执行链
- 输出提示词
- 把提示词写入 prompt memory

### 场景 3：用户说“按刚才那个提示词再来 4 张”

系统行为：

- 识别为 `image_generation_followup`
- 复用上一轮提示词和参数
- 明确出图数量为 4
- 进入执行链

### 场景 4：用户说“修改第 3 镜头，再确认”

系统行为：

- 识别为 `workflow_followup + revise`
- 只进入 storyboard revision 子链路
- 不误切普通生图

---

## 7. 最后一句话

我们现在已经有：

- protocol
- subagent
- workflow event
- image/video memory
- debug stream

所以真正差的不是“没有 Agent”，而是：

> **还没有把任务边界、记忆裁剪、模型链路、执行门控做成统一系统。**

这份整改清单的目标，就是把 Agent 模式从：

**很多聪明 patch**

升级成：

**真正稳定的统一 Agent Runtime**

---

## 8. 建议的下一步执行顺序

如果马上开工，建议按下面顺序推进：

1. 先做 **`task-boundary-classifier`**
2. 再做 **memory relevance / context pruning**
3. 再做 **provider health + model slot unification**
4. 最后做 **前端理解摘要**

因为只有先把任务边界做对，后面的“更聪明”才不会继续建立在错误理解之上。