# 自动化记忆与 Agent 重构设计（v3）

## 1. 目标

本次重构目标是把现有“router + worker”双阶段执行，收敛为更直接、可控、低 token 成本的执行链路。

明确目标：

1. 去除 `router agent`，由 `worker` 直接处理用户消息；
2. `worker` 模型从 `deepseek-chat` 切换为 `qwen3.5-30b-a3b`；
3. 关闭 `worker` 思考模式（thinking/reasoning off）；
4. 上下文策略从“今天+昨天”改为“向前回溯直到累计 20 条用户消息”；
5. 引入专用 `memory agent`，负责记忆提取，模型为 `qwen3.5-flash`；
6. 保持 `/api/v1/agent`、SSE、history 兼容演进，不引入第二运行时。

## 2. 非目标

1. 不新增独立部署的执行系统；
2. 不引入复杂 DSL 编排；
3. 不在本阶段改造前端交互形态；
4. 不做跨域业务逻辑重写（仅围绕 agent 执行链路和 memory 提取职责）。

## 3. 总体架构

### 3.1 重构后链路

```text
API/Scheduler Trigger
  -> Context Window Resolver (last 20 user messages)
  -> Executor Dispatch
       -> Worker Executor (qwen3.5-30b-a3b, thinking off)
       -> Memory Executor (qwen3.5-flash, thinking off)
  -> Tool Authorization
  -> Persistence + Redis Stream
  -> SSE/History Consumers
```

### 3.2 核心变化

1. 删除 router 阶段，缩短调用链路与阶段状态；
2. 把“意图识别”内聚到 worker 提示词与执行策略；
3. 把“记忆提取”从通用 worker 中剥离为独立 memory executor；
4. 上下文装配改为固定规模策略，降低输入 token 波动。

## 4. 执行角色与职责边界

### 4.1 Worker Executor（主对话执行器）

- 模型：`qwen3.5-30b-a3b`
- 配置：`thinking=off`
- 职责：
  - 处理用户请求；
  - 在单次推理中完成意图判断、工具决策、结果回复；
  - 遵守工具白名单与安全约束。

### 4.2 Memory Executor（记忆提取执行器）

- 模型：`qwen3.5-flash`
- 配置：`thinking=off`
- 职责：
  - 从对话中提取稳定记忆候选；
  - 产出结构化记忆写入/遗忘建议；
  - 不承担通用对话和复杂工具编排。

### 4.3 工具权限边界

统一规则：

`effective_tools = declared_tools ∩ profile_allowlist ∩ system_allowlist`

- worker 默认可调用通用工具子集；
- memory 默认仅允许 `memory_write`、`memory_forget`；
- 拒绝调用必须落审计（原因、工具名、请求上下文摘要）。

## 5. 上下文窗口策略（替代 today_yesterday）

### 5.1 策略定义

窗口规则：从当前待处理消息向前回溯，直到累计到 20 条 `role=user` 消息。

细则：

1. 计数对象仅为 `role=user`；
2. 为保持语义连续，窗口中保留相关 assistant/tool/system 消息；
3. 若历史不足 20 条用户消息，返回全部可用历史；
4. 当前用户消息默认计入 20 条统计。

### 5.2 伪代码

```text
collect_context(messages, current_message_id, n=20):
  included = []
  user_count = 0

  for msg in reverse(messages up to current_message_id):
    included.append(msg)
    if msg.role == "user":
      user_count += 1
    if user_count >= n:
      break

  return reverse(included)
```

### 5.3 预期收益

1. 输入 token 成本更稳定，不再受日期边界放大；
2. router 去除后仍可控住 worker 输入规模；
3. 在高频会话下显著降低上下文冗余。

## 6. 去除 Router 后的意图识别设计

去掉 router 后，必须在 worker 内完成“识别 + 决策 + 执行”。本节给出可落地方案。

### 6.1 方案 A：复用 RouterAgentOutput 语义到 Worker Prompt

做法：把原 router 的标签、判定规则、优先级放进 worker system prompt，让 worker先做内部意图归类，再进入执行。

优点：

1. 迁移风险低，行为连续性强；
2. 便于快速下线 router；
3. 对现有回归样本复用程度高。

不足：

1. 提示词偏长；
2. 分类与执行耦合，调试颗粒度较粗。

### 6.2 方案 B：重写 Worker-Native 轻量意图识别提示词

做法：定义最小标签集（示例：`chat | tool_call | memory_write | memory_forget | reject`）和明确优先级规则，直接服务 worker 执行。

优点：

1. prompt 更短，token 更省；
2. 更匹配“20 条用户消息窗口”策略；
3. 长期维护成本更低。

不足：

1. 需要重建回归集与阈值；
2. 初期存在行为漂移风险。

### 6.3 推荐路线：A -> B 两阶段

1. 第一阶段（稳定迁移）：先落地方案 A，确保 router 去除后行为不突变；
2. 第二阶段（成本优化）：基于线上样本收敛到方案 B，压缩提示词和标签集。

该路线兼顾了“短期稳定”和“中期降本”。

## 7. 数据模型与配置约定

### 7.1 Execution Profile（精简版）

建议收敛为：

```json
{
  "name": "chat_default",
  "executor": "worker",
  "model": {
    "name": "qwen3.5-30b-a3b",
    "thinking": "off"
  },
  "history_policy": {
    "mode": "last_n_user_messages",
    "n": 20,
    "include_current_user_message": true
  }
}
```

memory profile 示例：

```json
{
  "name": "automation_memory_default",
  "executor": "memory",
  "model": {
    "name": "qwen3.5-flash",
    "thinking": "off"
  },
  "history_policy": {
    "mode": "last_n_user_messages",
    "n": 20,
    "include_current_user_message": true
  },
  "tool_policy": {
    "mode": "intersection",
    "allowlist": ["memory_write", "memory_forget"]
  }
}
```

### 7.2 兼容字段策略

- 历史 `enable_router` 字段保留读取兼容，写入路径不再依赖；
- 新任务默认不再产出 router 配置；
- 执行路径仅依据 `executor` 与 profile 配置。

### 7.3 Metadata 扩展建议

建议标准字段：

- `origin: "chat" | "automation"`
- `executor: "worker" | "memory"`
- `execution_profile_name: string`
- `hidden_from_user: boolean`

用于用户可见性隔离与全链路审计。

## 8. 协议影响与文档更新

按照“协议先行”原则，先更新 `docs/protocols/`：

1. `docs/protocols/agent/sse-events.md`
   - step 枚举从 `router|worker|memory` 收敛为 `worker|memory`；
   - 对旧客户端声明：`router` 事件可能不再出现。

2. `docs/protocols/agent/run-agent-input.md`
   - 增加 `history_policy.mode=last_n_user_messages` 语义与边界规则。

3. `docs/protocols/agent/api-endpoints.md`
   - 说明执行阶段由后端 profile 决定；
   - 不要求前端显式传入 router 或 executor 控制参数。

## 9. 迁移计划

### 阶段 1：协议与配置就绪

1. 完成协议文档更新；
2. 增加 profile 新字段和兼容读取逻辑；
3. 新建任务默认 profile 切到 worker/memory 双执行器模型。

### 阶段 2：执行链路切换

1. 下线 router 运行路径；
2. worker 切换 `qwen3.5-30b-a3b` + thinking off；
3. 上下文装配切为“20 条用户消息策略”。

### 阶段 3：memory agent 接管记忆提取

1. memory executor 切换 `qwen3.5-flash`；
2. 自动记忆任务全量走 memory executor；
3. 对比提取质量与成本，完成灰度放量。

### 阶段 4：优化与收敛

1. worker 意图识别从方案 A 迭代到方案 B；
2. 清理 router 相关遗留代码和配置分支；
3. 固化观测指标与报警阈值。

## 10. 测试与验收

### 10.1 单元测试

1. `last_n_user_messages` 窗口截取逻辑；
2. 工具交集授权逻辑；
3. profile 解析与兼容字段读取；
4. memory 输出结构校验。

### 10.2 集成测试

1. 无 router 情况下 worker 正常执行；
2. SSE/history 在 `worker|memory` 阶段下可稳定消费；
3. 自动记忆任务完整链路可执行；
4. hidden 消息对用户不可见但审计可见。

### 10.3 验收指标

P0：

1. router 下线后核心对话流程零阻断；
2. 平均输入 token 相比 today_yesterday 明显下降；
3. 工具调用越权率为 0。

P1：

1. memory 提取质量不低于现网基线；
2. 延迟与成本达到预期区间；
3. 协议兼容无前端回归。

## 11. 风险与回滚

主要风险：

1. worker 内聚识别导致误判率短期上升；
2. 20 条用户消息窗口在极端长任务中可能信息不足；
3. memory 轻量模型在复杂语义下提取质量波动。

回滚策略：

1. 保留 profile 级灰度开关，支持按租户/任务类型回切旧模型；
2. 上下文策略支持临时扩容（20 -> 25）作为应急参数；
3. memory agent 保留质量兜底阈值，低置信度结果不落库。

---

本版文档确立了清晰的一次性架构方向：

- router 从执行链路中移除；
- worker 直连用户消息并承担意图识别；
- memory 由专用 agent 执行；
- 上下文按 20 条用户消息定长回溯，控制 token 成本；
- 在兼容现有协议消费方式的前提下完成演进。