docs/plan/technical-design/side-task.md
Rama main · réplica de lectura del repositorio original.
# 边路任务（Side Task）技术方案
> 版本: v2.0 | 更新时间: 2026-07-04
---
## 1. 需求背景
### 1.1 问题描述
当前用户在桌面端进行主任务对话时，如果临时需要执行一个独立的操作（如部署、代码提交推送等），只有两种方式：
1. **在当前会话中直接发送指令**——但这会污染主任务上下文，部署日志、git 输出等无关信息会混入对话历史，影响后续 Agent 的理解和判断。
2. **手动创建一个新会话**——这会导致会话列表充满大量一次性临时会话，管理混乱。
缺少一种"临时、隔离、即用即抛"的任务执行通道。
### 1.2 核心需求
| 需求项 | 说明 |
|--------|------|
| **边路发起** | 用户在主任务对话过程中，通过 UI 手动发起一个边路任务 |
| **上下文隔离** | 边路任务的执行过程和结果不写入主任务上下文，不影响主任务的历史消息 |
| **多轮对话** | 边路任务支持多轮对话，用户可以追加回复，Agent 执行完整的 Think-Act-Observe 循环 |
| **完整工具循环** | 边路任务走完整的 Agent Loop（Think-Act-Observe 多轮），支持 shell、git 等工具调用 |
| **并行执行** | 边路任务异步执行，不阻塞主任务继续运行 |
| **配置继承** | 边路任务复用当前主任务的 Agent、模型和工作区配置，用户不可修改 |
| **上下文可选继承** | 用户每次可选择是否让边路任务感知主任务的对话历史摘要（帮助边路 Agent 理解背景） |
| **Tab 式 UI** | 边路任务作为中央区域的 Tab 管理，与文件预览、Diff 对比等 Tab 并列，不新增独立面板 |
### 1.3 边界说明
| 要做的 | 不做的 |
|--------|--------|
| 用户在 UI 上手动发起边路任务 | Agent 在对话中通过工具调用发起边路任务 |
| 边路任务走完整 Agent Loop（Think-Act-Observe） | 仅做单次 LLM 调用不执行工具 |
| 边路任务结果展示在独立 Tab 中 | 边路任务结果注入主任务上下文 |
| 边路任务支持多轮对话（用户可追加回复） | — |
| 复用主任务 Agent/模型/工作区 | 允许在边路任务中切换 Agent/模型 |
| 边路任务使用独立 session 存储，`session_type = 'side_task'` | 边路任务消息写回主会话 |
| 边路任务 Tab 可关闭，关闭后数据保留 | 关闭 Tab 时删除会话数据 |
| 桌面端（Electron）支持 | 管理后台（Admin）支持边路任务 |
---
## 2. 需求描述
### 2.1 用户故事
> 作为开发者，我在主任务对话中让 Agent 帮我开发功能时，想临时让 Agent 执行一次 `git add . && git commit -m "xxx" && git push`。我希望这个操作不影响当前对话上下文，不污染会话列表，可以追加对话直到任务完成，完成后关闭 Tab 即消失。
### 2.2 交互流程
```
用户在聊天界面（主任务 Tab）
│
├── 点击工具栏「+ 边路任务」按钮
│ │
│ └── 创建新的「边路任务」Tab（如 "[边路] git 提交"）
│ │
│ ├── Tab 内展示：历史消息区域 + 输入框
│ │
│ ├── 首条消息发送时：
│ │ ├── ☑️ 继承主任务上下文（checkbox，默认勾选，发送后隐藏）
│ │ └── 后端创建 side_task 子会话，启动 Agent 执行
│ │
│ ├── 边路任务异步执行，实时流式展示
│ ├── 主任务 Tab 不受影响，可切换到主 Tab 继续对话
│ │
│ ├── 边路任务完成后：
│ │ ├── 用户可以追加回复（继续多轮对话）
│ │ └── 追加消息走标准 send_message 流程（用 side_session_id）
│ │
│ └── 用户关闭 Tab → Tab 移除，会话数据保留在 DB
│
└── 所有边路任务 Tab 与文件预览/Diff Tab 并列显示在 Tab Bar
```
### 2.3 核心用例
1. **代码提交推送**：主任务开发完后，边路任务执行 `git add/commit/push`
2. **部署操作**：主任务开发完成后，边路任务执行构建和部署命令
3. **快速查询**：临时查一个不相关的信息，不想混入主对话上下文
4. **文件清理 / 辅助操作**：整理工作区文件、运行脚本等
---
## 3. 技术选型
### 3.1 整体思路
边路任务本质是一个**用户手动触发的、独立会话的、Tab 内展示的 Agent 对话**。创建时特殊处理（关联父会话 + 可选继承上下文），后续消息复用现有的 `send_message` → `handleSendMessage` 标准流程。
与现有概念对比：
| 维度 | 普通会话 | 子智能体（DelegateTool） | 边路任务（新增） |
|------|---------|------------------------|-----------------|
| 触发方 | 用户新建 | 主 Agent 工具调用 | 用户点击工具栏按钮 |
| UI 形态 | 会话列表切换 | **只读中央 Tab**（`subagent`） | **中央 Tab 管理** |
| 结果去向 | 写入自身 session | 注入主对话上下文（tool_result） | 仅在边路 Tab 展示 |
| 上下文 | 完整历史 | 主 Agent 编写的 prompt | **可选继承**主任务摘要 |
| 多轮对话 | 支持 | 单轮（用完即弃，不可追问） | **支持** |
| 会话类型 | `main` | `subagent` | `side_task` |
| 消息可见性 | 会话列表 | **只读 Tab + 右侧子代理列表** | **Tab 内，不在会话列表** |
### 3.2 复用策略
| 组件 | 复用方式 |
|------|---------|
| `AgentLoop` | 直接复用，`execute()` 执行边路任务 |
| `HarnessService.buildContext()` | 复用，构建边路任务的 `AgentExecutionContext` |
| `agentExecutor` 线程池 | 复用，边路任务提交到同一线程池 |
| `StreamingWsHandler.handleSendMessage()` | 复用，后续多轮消息走标准流程 |
| `Session` / `Message` 表 | 复用，边路任务创建独立 session 记录 |
| 前端 `useCenterTabs` | 扩展，新增 `side_task` Tab 类型 |
| 前端 `ChatPanel` | 参考实现新的 `SideChatPanel`，复用 message 渲染组件 |
| 前端 `sessionStore` | 扩展，支持按 sessionId 存取消息缓存 |
### 3.3 不做的新增
- **不新增执行引擎**：边路任务完全复用 `AgentLoop`
- **不修改 PromptEngine**：边路任务的 system prompt 沿用主 Agent 配置
- **不新增数据库表**：复用 `session` 和 `message` 表，通过 `session_type` 字段区分
- **不新增 WS 事件类型用于后续消息**：后续多轮消息直接用标准 `send_message`
---
## 4. 架构设计
### 4.1 整体架构
```
┌──────────────────────────────────────────────────────────────────────┐
│ 桌面端 (Electron + Vue 3) │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ CenterTabBar │ │
│ │ ┌────────┬──────────────────────┬──────────┬───────────────┐ │ │
│ │ │ 聊天 │ [边路] git 提交 ✕ │ main.ts │ package.json │ │ │
│ │ │ (主) │ (side_task tab) │ (file) │ (file) │ │ │
│ │ └────────┴──────────────────────┴──────────┴───────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ CenterTabContainer │ │
│ │ │ │
│ │ activeTab === 'chat' → ChatPanel (主任务，不变) │ │
│ │ activeTab === 'file' → FileViewer (文件，不变) │ │
│ │ activeTab === 'diff' → FileDiffViewer (Diff，不变) │ │
│ │ activeTab === 'side_task' → SideChatPanel (边路对话，新增) │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ WebSocket (订阅 parentSessionId + 各 sideSessionId) │
└───────────┼──────────────────────────────────────────────────────────┘
│
┌───────────┼──────────────────────────────────────────────────────────┐
│ 后端 │ │
│ │ │
│ ┌────────┴──────────────────────────────────────────────────────┐ │
│ │ StreamingWsHandler │ │
│ │ ┌───────────────────────────────────────┐ │ │
│ │ │ handleCreateSideSession (新增) │ 创建子会话 │ │
│ │ │ → 创建 side_task session │ +首条消息执行 │ │
│ │ │ → 保存首条 USER 消息 │ │ │
│ │ │ → 异步启动 Agent Loop │ │ │
│ │ └───────────────────────────────────────┘ │ │
│ │ ┌───────────────────────────────────────┐ │ │
│ │ │ handleSendMessage (已有，不改动) │ 后续多轮消息 │ │
│ │ │ → 按 sessionId 路由到普通或边路会话 │ 走标准流程 │ │
│ │ └───────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ HarnessService │ │
│ │ - executeFromEvent() (已有，边路后续消息复用) │ │
│ │ - executeSideFirstMessage() (新增，首条消息 + inheritContext) │ │
│ │ - buildContext() (改为 public) │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Session 表 (复用) │ │
│ │ - session_type = 'side_task' │ │
│ │ - parent_session_id → 主会话 ID │ │
│ │ - inherit_context (JSONB/config 字段) │ │
│ └──────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
```
### 4.2 执行时序
#### 首条消息（创建边路任务）
```
用户 前端 后端
│ │ │
│── 新建边路任务Tab ──>│ │
│ │ 创建 Tab (type=side_task) │
│ │ │
│── 输入并发送 ───────>│ │
│ │ WS: create_side_session ──────>│
│ │ {parentSessionId, │
│ │ content, inheritContext} │
│ │ │── 创建 side_task session
│ │ │── 保存 USER 消息到子会话
│ │ │── 若 inheritContext:
│ │ │ 生成父会话上下文摘要
│ │ │── 提交 agentExecutor
│ │ │
│ │<── side_session_created ───────│
│ │ {sideSessionId} │
│ │ │
│ │ 订阅 sideSessionId ────────────>│
│ │ │
│ │<── content_delta ──────────────│ (标准事件，用sideSessionId)
│ │<── tool_call_start ────────────│
│ │<── tool_call_result ───────────│
│ │<── ... │
│ │<── session_status(COMPLETED) ──│
│ │ │
│ 用户查看结果 <──────│ │
```
#### 后续消息（多轮对话）
```
用户 前端 后端
│ │ │
│── 在边路Tab中 ──────>│ │
│ 追加回复 │ │
│ │ WS: send_message ─────────────>│
│ │ {sessionId: sideSessionId, │
│ │ data: {content}} │
│ │ │── handleSendMessage()（标准流程）
│ │ │ 校验 session 存在
│ │ │ 保存 USER 消息
│ │ │ 启动 Agent Loop
│ │ │
│ │<── content_delta ──────────────│ (标准事件)
│ │<── tool_call_start ────────────│
│ │<── session_status(COMPLETED) ──│
```
---
## 5. 实现步骤
### 模块 A：数据库变更
#### A1. session 表扩展
边路任务复用现有的 `session` 表。需要 `parent_session_id` 和 `session_type` 字段（如 V040 子智能体方案已增加则可跳过 ALTER）。
**迁移脚本** `V041__add_side_task_support.sql`：
```sql
-- 1. 确保 session_type 支持 'side_task' 值
-- 若 V040 已执行，parent_session_id 和 session_type 已存在
ALTER TABLE `session`
MODIFY COLUMN `session_type` VARCHAR(20) DEFAULT 'main'
COMMENT '会话类型: main/subagent/side_task';
-- 2. 确认 phase 字段可为 NULL（边路任务不使用 phase 中间状态）
-- V040 应已处理，若未处理则执行：
-- ALTER TABLE `session`
-- MODIFY COLUMN `phase` VARCHAR(20) DEFAULT NULL
-- COMMENT '任务阶段，边路任务/子智能体会话不使用';
-- 3. 边路任务是否需要 inheritContext 标记？
-- 方式 A：存入 config 字段（JSONB）— 无需新列
-- 方式 B：冗余到 parent_session_id（NULL = 不继承，有值 = 继承）
-- 推荐方式 A，利用已有的 config 字段
-- side_task 的首条消息通过 system prompt 注入上下文摘要，
-- 后续消息不再注入（由 DB 中的消息历史自然继承）
```
**说明**：
- 边路任务 session 使用 `status` 字段（ACTIVE/COMPLETED/FAILED），不设置 `phase` 字段
- `inheritContext` 仅在**首条消息**时生效，通过 system prompt 注入。后续消息的上下文由 side_task session 自身的消息历史提供
- 边路任务 message 写入 `message` 表，通过 `session_id` 关联到边路任务会话
**注意**：此模块依赖 V040 迁移。如果 V040 尚未执行，需将上述 ALTER 合并到 V040 迁移脚本中。
---
### 模块 B：后端核心逻辑
#### B1. HarnessService — 新增 `executeSideFirstMessage()` 方法
**文件**：`backend/src/main/java/cn/etarch/mao/harness/core/HarnessService.java`
**修改内容**：
1. 将 `buildContext()` 方法改为 `public`（若 V040 子智能体方案尚未执行）
2. 新增 `executeSideFirstMessage()` 方法：
```java
/**
* 执行边路任务的首条消息。与主任务并行，使用独立的子会话。
* 首条消息支持注入主任务上下文摘要（仅一次），后续消息走标准 executeFromEvent() 流程。
*
* @param parentSessionId 主任务会话 ID
* @param sideSessionId 边路任务子会话 ID
* @param inheritContext 是否注入主任务上下文摘要
* @param listener 边路任务的事件监听器
* @param cancelFlag 取消标志
*/
public void executeSideFirstMessage(Long parentSessionId,
Long sideSessionId,
boolean inheritContext,
AgentEventListener listener,
AtomicBoolean cancelFlag) {
// 1. 构建边路任务上下文（复用 buildContext）
AgentExecutionContext context = buildContext(sideSessionId);
// 2. 如果选择继承主任务上下文，注入摘要到 system prompt（仅首条消息）
if (inheritContext) {
String contextSummary = generateContextSummary(parentSessionId);
if (contextSummary != null && !contextSummary.isBlank()) {
String enrichedSystemPrompt = context.getSystemPrompt()
+ "\n\n<主任务背景摘要>\n"
+ contextSummary
+ "\n</主任务背景摘要>\n"
+ "以上是主任务的最近对话摘要，本次边路任务的结果不需要反馈到主任务。";
context.setSystemPrompt(enrichedSystemPrompt);
}
}
// 3. 持久化回调：写入边路任务子会话
AgentLoop.MessagePersistenceCallback persistenceCallback =
new AgentLoop.MessagePersistenceCallback() {
@Override
public void onSaveAssistantMessage(String content, String thinkingContent,
List<ChatRequest.ToolCall> toolCalls,
ChatUsage usage) {
// ... 同子智能体方案的 createSubPersistenceCallback 逻辑
String toolCallsJson = null;
if (toolCalls != null && !toolCalls.isEmpty()) {
try {
toolCallsJson = objectMapper.writeValueAsString(toolCalls);
} catch (JsonProcessingException e) {
log.warn("Failed to serialize tool calls for side task", e);
}
}
int tokenCount = usage != null ? usage.getTotalTokens() : 0;
Long modelId = context.getModelConfig() != null
? context.getModelConfig().getId() : null;
sessionService.saveMessage(sideSessionId, "ASSISTANT",
content, thinkingContent, null, toolCallsJson,
tokenCount, modelId);
}
@Override
public void onSaveToolMessage(String toolCallId, String content) {
sessionService.saveMessage(sideSessionId, "TOOL",
content, null, toolCallId, null, 0, null);
}
};
// 4. 执行 Agent Loop
agentLoop.execute(context, listener, persistenceCallback);
if (cancelFlag != null) {
agentLoop.removeCancelFlag(sideSessionId);
}
}
/**
* 生成主任务上下文摘要。
* 取最近若干条消息的摘要，帮助边路 Agent 理解主任务背景。
*/
private String generateContextSummary(Long parentSessionId) {
try {
List<Message> messages = sessionService.getMessages(parentSessionId);
if (messages.isEmpty()) return null;
int fromIndex = Math.max(0, messages.size() - 10);
List<Message> recentMessages = messages.subList(fromIndex, messages.size());
StringBuilder sb = new StringBuilder();
sb.append("以下是主任务最近的对话摘要：\n\n");
for (Message msg : recentMessages) {
String role = msg.getRole();
String content = msg.getContent();
if (content != null && !content.isBlank()) {
String truncated = content.length() > 300
? content.substring(0, 300) + "..."
: content;
sb.append("[").append(role).append("]: ").append(truncated).append("\n");
}
}
return sb.toString();
} catch (Exception e) {
log.warn("Failed to generate context summary for side task", e);
return null;
}
}
```
**说明**：`inheritContext` 仅在首条消息时生效。后续消息通过 `executeFromEvent()` 走标准流程，buildContext 从 DB 加载 side_task session 自身的消息历史，不会再注入主任务摘要。
#### B2. StreamingWsHandler — 新增 `handleCreateSideSession` 方法
**文件**：`backend/src/main/java/cn/etarch/mao/session/ws/StreamingWsHandler.java`
**修改内容**：
1. 在 `handleTextMessage()` 的 switch 中新增 case：
```java
case "create_side_session" -> handleCreateSideSession(userId, root);
case "cancel_side_task" -> handleCancelSideTask(userId, root);
```
2. 新增 `handleCreateSideSession()` 方法：
```java
/**
* 创建边路任务会话并执行首条消息。
* 后续消息复用 handleSendMessage() 标准流程（sessionId = sideSessionId）。
*/
private void handleCreateSideSession(Long userId, JsonNode root) {
Long parentSessionId = getLong(root, "sessionId");
if (parentSessionId == null) return;
JsonNode data = root.get("data");
if (data == null || !data.has("content")) return;
String content = data.get("content").asText();
boolean inheritContext = data.has("inheritContext") && data.get("inheritContext").asBoolean();
// 1. 校验主会话存在
Session parentSession;
try {
parentSession = sessionService.getSession(parentSessionId);
} catch (Exception e) {
registry.send(userId, WsEvent.of("error", parentSessionId,
Map.of("message", "主会话不存在")));
return;
}
// 2. 确认用户订阅了主会话
registry.subscribe(userId, parentSessionId);
// 3. 创建边路任务子会话
Session sideSession = new Session();
sideSession.setUserId(userId);
sideSession.setAgentId(parentSession.getAgentId());
sideSession.setTitle("[边路] " + (content.length() > 30
? content.substring(0, 30) + "..." : content));
sideSession.setExecutionMode(parentSession.getExecutionMode());
sideSession.setWorkspace(parentSession.getWorkspace());
sideSession.setPermissionLevel(parentSession.getPermissionLevel());
sideSession.setModelId(parentSession.getModelId());
sideSession.setIsGit(parentSession.getIsGit());
sideSession.setPlatform(parentSession.getPlatform());
sideSession.setShellPath(parentSession.getShellPath());
sideSession.setOsVersion(parentSession.getOsVersion());
sideSession.setStatus("ACTIVE");
sideSession.setParentSessionId(parentSessionId);
sideSession.setSessionType("side_task");
sessionService.save(sideSession);
Long sideSessionId = sideSession.getId();
log.info("Created side task session {} for parent session {}, userId={}, inheritContext={}",
sideSessionId, parentSessionId, userId, inheritContext);
// 4. 保存首条 USER 消息
sessionService.saveMessage(sideSessionId, "USER", content,
null, null, null, 0, null);
// 5. 通知前端会话已创建（前端随后订阅该 sideSessionId）
registry.send(userId, WsEvent.of("side_session_created", parentSessionId,
Map.of("sideSessionId", sideSessionId, "title", sideSession.getTitle())));
// 6. 注册取消标志
AtomicBoolean cancelFlag = agentLoop.registerCancelFlag(sideSessionId);
// 7. 异步执行首条消息
agentExecutor.submit(() -> {
try {
// 通过标准事件通知执行状态（sessionId = sideSessionId，前端需订阅方可见）
registry.send(userId, WsEvent.of("session_status", sideSessionId,
Map.of("phase", "RUNNING")));
WsStreamingEventListener listener = new WsStreamingEventListener(
registry, activityService, sessionTodoMapper, sessionService,
sideSessionId, userId, null);
harnessService.executeSideFirstMessage(
parentSessionId, sideSessionId,
inheritContext, listener, cancelFlag);
if (cancelFlag.get()) {
sessionService.updateField(sideSessionId, "status", "CANCELLED");
registry.send(userId, WsEvent.of("session_status", sideSessionId,
Map.of("phase", "CANCELLED")));
} else {
sessionService.updateField(sideSessionId, "status", "COMPLETED");
registry.send(userId, WsEvent.of("session_status", sideSessionId,
Map.of("phase", "COMPLETED")));
}
} catch (Exception e) {
log.error("Side task execution failed for sideSession {}", sideSessionId, e);
sessionService.updateField(sideSessionId, "status", "FAILED");
registry.send(userId, WsEvent.of("error", sideSessionId,
Map.of("message", e.getMessage() != null ? e.getMessage() : "未知错误")));
} finally {
agentLoop.removeCancelFlag(sideSessionId);
}
});
}
```
**关键设计**：
- 首条消息使用 `create_side_session` 事件（专用逻辑：创建会话 + 注入上下文 + 执行）
- **后续消息使用标准的 `send_message` 事件**，`sessionId = sideSessionId`
- `handleSendMessage()` 看到 sideSessionId 不等于主会话 ID，会为其建立独立的 `sessionLock`，**不会阻塞主任务**
- 所有流式事件（`content_delta`、`tool_call_start` 等）使用 `sessionId = sideSessionId` 路由
3. 新增 `handleCancelSideTask()` 方法：
```java
private void handleCancelSideTask(Long userId, JsonNode root) {
Long sideSessionId = getLong(root, "sideSessionId");
if (sideSessionId == null) return;
// 复用现有的 cancel 机制
AtomicBoolean flag = cancelFlags.get(sideSessionId);
if (flag != null) {
flag.set(true);
}
Future<?> future = runningTasks.get(sideSessionId);
if (future != null) {
future.cancel(false);
}
shellSessionManager.closeByConversation(sideSessionId);
}
```
#### B3. StreamingWsHandler.handleSendMessage() — 确认边路会话兼容性
**文件**：`backend/src/main/java/cn/etarch/mao/session/ws/StreamingWsHandler.java`
**无需修改**。`handleSendMessage()` 按 `sessionId` 查找 session、校验状态、加锁执行。因为边路任务的 `sessionLock` 按 `sideSessionId` 建立，与主任务的 `sessionLock(parentSessionId)` 完全独立，天然支持并行。
**唯一需要注意的场景**：边路任务正在执行中（phase = RUNNING），用户又发了一条消息。此时 `handleSendMessage()` 中的校验会拒绝。解决方案：
- 边路任务也使用消息队列（`sessionQueueMessages`），若 busy 则入队
- 或前端判断 sideSession 的 phase，如 busy 则将消息入队
- 推荐复用消息队列机制，无需改动 `handleSendMessage()`
#### B4. SessionService — 新增方法
**文件**：`backend/src/main/java/cn/etarch/mao/session/service/SessionService.java`
**修改内容**：
1. 新增 `updateField()` 方法：
```java
/**
* 更新 session 单个字段。
* 边路任务使用此方法更新 status，避免触发 updatePhase() 中的自动消费等逻辑。
*/
public void updateField(Long sessionId, String field, Object value) {
LambdaUpdateWrapper<Session> wrapper = new LambdaUpdateWrapper<Session>()
.eq(Session::getId, sessionId);
switch (field) {
case "status" -> wrapper.set(Session::getStatus, (String) value);
case "phase" -> wrapper.set(Session::getPhase, (String) value);
default -> throw new IllegalArgumentException("Unsupported field: " + field);
}
sessionMapper.update(null, wrapper);
}
```
2. 新增 `save()` 方法（如不存在）：
```java
public void save(Session session) {
sessionMapper.insert(session);
}
```
3. 修改 `saveMessage()`：跳过边路任务子会话的标题自动生成：
```java
// saveMessage() 中
if (!"subagent".equals(session.getSessionType())
&& !"side_task".equals(session.getSessionType())) {
// 现有标题自动生成逻辑
}
```
---
### 模块 C：前端实现
#### C1. Tab 类型扩展
**文件**：`desktop/src/types/file-browser.ts`
**修改内容**：扩展 `Tab` 类型支持 `side_task`：
```typescript
export interface Tab {
id: string // 'chat' | 'file:xxx' | 'diff:xxx' | 'side:123'
type: 'chat' | 'file' | 'diff' | 'side_task'
title: string
filePath?: string
fileChange?: FileChange
/** 边路任务子会话 ID（仅 type === 'side_task' 时有效） */
sideSessionId?: number
}
```
#### C2. useCenterTabs — 新增边路任务 Tab 管理方法
**文件**：`desktop/src/composables/useCenterTabs.ts`
**修改内容**：新增方法：
```typescript
/**
* 打开边路任务 Tab。如果已存在则直接激活。
*/
function openSideTaskTab(sideSessionId: number, title: string) {
const state = getSessionState()
const id = 'side:' + sideSessionId
const existing = state.tabs.find(t => t.id === id)
if (existing) {
state.activeTabId = id
return
}
const newTab: Tab = { id, type: 'side_task', title, sideSessionId }
state.tabs.push(newTab)
state.activeTabId = id
}
/**
* 关闭边路任务 Tab。
* 注意：关闭 Tab 不删除 session 数据，只是从 Tab 栏移除。
* 通过 side_session_list 仍可重新打开。
*/
function closeSideTaskTab(sideSessionId: number) {
const id = 'side:' + sideSessionId
closeTab(id)
}
```
`closeTab()` 方法已有关闭逻辑，但需确认它不阻止 `side:` 前缀的 Tab 关闭：
```typescript
// closeTab() 中，当前逻辑：
if (tabId === 'chat') return // can't close chat tab
// side_task Tab 不在禁止关闭范围，无需修改
```
#### C3. 新增组件：SideChatPanel
**文件**：`desktop/src/components/chat/SideChatPanel.vue`
**新建**。这是边路任务的对话界面，渲染在 `side_task` 类型 Tab 中。
**设计思路**：由于 `ChatPanel` 与当前活跃主会话（`sessionStore.activeSession`）深度绑定，不便直接复用。`SideChatPanel` 是一个**轻量版 ChatPanel**，接收 `sideSessionId` prop，独立管理自身消息状态和流式渲染。
```vue
<template>
<div class="side-chat-panel">
<!-- 首条消息提示（如果还未发送过消息） -->
<div v-if="messages.length === 0 && !sending" class="side-chat-empty">
<p>边路任务：独立的对话通道，不影响主任务上下文</p>
<div class="inherit-toggle">
<el-checkbox v-model="inheritContext">
继承主任务上下文（让 Agent 了解主任务背景）
</el-checkbox>
</div>
</div>
<!-- 消息列表（复用主任务的消息展示组件） -->
<div class="messages" ref="messagesContainer">
<MessageBubble
v-for="msg in messages"
:key="msg.id"
:message="msg"
:show-time="true"
/>
</div>
<!-- 输入框 -->
<div class="input-area">
<el-input
v-model="inputText"
type="textarea"
:rows="2"
placeholder="输入边路任务的指令..."
:disabled="sending"
@keydown.enter.exact="handleSend"
/>
<el-button
type="primary"
:disabled="!canSend"
:loading="sending"
@click="handleSend"
>
发送
</el-button>
</div>
</div>
</template>
<script setup lang="ts">
import { ref, computed, onMounted, onUnmounted, watch, nextTick } from 'vue'
import { useSessionStore } from '@/stores/session'
import { useStreamWS } from '@/composables/useStreamWS'
import type { ChatMessage } from '@/types/chat'
import MessageBubble from './MessageBubble.vue'
const props = defineProps<{
sideSessionId: number
}>()
const sessionStore = useSessionStore()
const { send, subscribe, unsubscribe } = useStreamWS()
// 首条消息特殊处理
const inheritContext = ref(true) // 默认勾选
const isFirstMessage = ref(true) // 是否尚未发送过首条消息
const sending = ref(false)
const inputText = ref('')
// 消息列表：从 sessionStore 获取该 sideSession 的消息
const messages = computed<ChatMessage[]>(() => {
return sessionStore.getMessages(String(props.sideSessionId))
})
const canSend = computed(() => inputText.value.trim().length > 0 && !sending.value)
onMounted(() => {
// 订阅边路任务会话的 WS 事件
subscribe(String(props.sideSessionId))
})
onUnmounted(() => {
unsubscribe(String(props.sideSessionId))
})
function handleSend() {
if (!canSend.value) return
const content = inputText.value.trim()
if (isFirstMessage.value) {
// 首条消息：使用 create_side_session
send({
type: 'create_side_session',
sessionId: Number(sessionStore.activeSessionId),
data: { content, inheritContext: inheritContext.value }
})
isFirstMessage.value = false
inheritContext.value = false // 后续消息不再需要
} else {
// 后续消息：使用标准 send_message
send({
type: 'send_message',
sessionId: props.sideSessionId,
data: { content, eventId: crypto.randomUUID() }
})
}
sending.value = true
inputText.value = ''
// sending 在收到 session_status(COMPLETED/FAILED/CANCELLED) 后重置
}
</script>
```
**说明**：
- `SideChatPanel` 不自己维护消息列表，而是从 `sessionStore` 读取对应 sessionId 的消息
- 流式事件（`content_delta`、`tool_call_start` 等）通过 sessionStore 的 `appendDelta()` / `appendToolCallStart()` 等方法处理——这些方法按 sessionId 操作，边路任务会自动使用 `sideSessionId`
- 消息组件（`MessageBubble`）完全复用
#### C4. CenterTabContainer — 新增 side_task 渲染分支
**文件**：`desktop/src/components/center/CenterTabContainer.vue`
**修改内容**：在 `KeepAlive` 中新增 `side_task` 类型的分支：
```vue
<template>
<div class="center-tab-container">
<KeepAlive :max="20">
<ChatPanel v-if="activeTabId === 'chat'" />
<FileViewer
v-else-if="activeTab?.type === 'file'"
:key="activeTabId"
:file-path="activeTab.filePath || ''"
:provider="fileProvider"
/>
<FileDiffViewer
v-else-if="activeTab?.type === 'diff' && activeTab.fileChange"
:key="activeTabId"
:change="activeTab.fileChange"
/>
<!-- 新增 -->
<SideChatPanel
v-else-if="activeTab?.type === 'side_task' && activeTab.sideSessionId != null"
:key="activeTabId"
:side-session-id="activeTab.sideSessionId"
/>
</KeepAlive>
</div>
</template>
<script setup lang="ts">
// ... 现有 imports ...
import SideChatPanel from '../chat/SideChatPanel.vue'
// ...
</script>
```
#### C5. TaskView — 集成边路任务入口
**文件**：`desktop/src/views/task/TaskView.vue`
**修改内容**：
1. 在模板中增加「+ 边路任务」按钮（放在 Tab Bar 区域）：
```vue
<!-- 在 CenterTabBar 旁边增加按钮 -->
<div class="tab-bar-actions">
<el-button size="small" @click="handleNewSideTask" :icon="Plus">
边路任务
</el-button>
</div>
```
2. 新增 `handleNewSideTask()` 方法：
```typescript
function handleNewSideTask() {
// 创建一个占位 Tab（尚未关联真实 sideSessionId）
// 用户在 Tab 中输入并发送首条消息时，后端才创建 side_session
const { openSideTaskTab } = useCenterTabs(activeSessionIdRef)
// 使用临时 ID，首条消息发送后更新为真实 sideSessionId
const tempId = Date.now()
openSideTaskTab(tempId, '边路任务')
}
```
**更优方案**：直接在 `SideChatPanel` 内部管理 Tab 标题更新。`SideChatPanel` 在收到 `side_session_created` 事件后，调用 `useCenterTabs` 更新对应 Tab 的 `sideSessionId` 和 `title`。
- 创建临时 Tab（`side:temp_xxx`）
- 收到 `side_session_created` 后，更新 Tab 的 `id` 为 `side:真实ID` 并更新 `title`
**简化方案**（推荐）：不创建占位 Tab，而是 `handleNewSideTask()` 直接调用后端创建边路会话（REST API 或 WS），获取 sideSessionId 后再打开 Tab。但这意味着会话创建和首条消息是分开的。
**最终推荐方案**：用户点击「+ 边路任务」→ 前端立即发送 `create_side_session` 请求（content 为空）→ 后端创建空 side_task session → 返回 sideSessionId → 前端打开 Tab → 用户在 Tab 中发送消息（复用 send_message）。
但这样首条消息还需要处理 inheritContext。如果将 inheritContext 存入 side_task session 的 config 字段，`buildContext` 时自动检测并注入摘要，就无需在首条消息时特殊处理。
**最终推荐方案优化**：
1. 点击「+ 边路任务」→ WS `create_side_session`（带 content 和 inheritContext）→ 后端创建 session + 保存 USER + 执行
2. 创建后 Tab 出现，首条消息已在执行
3. 后续消息：WS `send_message`（sessionId = sideSessionId）
这让入口更简洁——点击后直接输入首条消息内容。
调整 `handleNewSideTask()`：
```typescript
function handleNewSideTask() {
// 弹出输入对话框或直接打开 Tab 让用户输入
// 简化方案：直接打开 Tab，Tab 中有输入框
const tempId = 'side:new_' + Date.now()
openSideTaskTab(0, '边路任务') // sideSessionId 为 0 表示"待创建"
// SideChatPanel 检测到 sideSessionId 为 0 时显示初始输入界面
}
```
#### C6. sessionStore — 确保边路任务消息独立缓存
**文件**：`desktop/src/stores/session.ts`
**现有能力已够**：`sessionMessages` 是按 sessionId 的 Map，`getMessages(sessionId)` 返回指定会话的消息。边路任务的消息通过 `sideSessionId` 存取，与主会话完全隔离，无需额外修改。
**可能需要微调**：
- `appendDelta()` 方法内部调用 `ensureStreamingAssistantMessage()`，该方法按 `sid` 操作——正确
- `appendToolCallStart()` / `updateToolCallResult()` 同上
- `sessionStreaming` / `sessionThinking` 等 streaming 状态也是按 sessionId 的 Map——自然支持多会话
#### C7. useStreamWS — 确保订阅机制支持边路任务
**文件**：`desktop/src/composables/useStreamWS.ts`
**无需修改**，现有机制已支持：
- `subscribe(sessionId)` / `unsubscribe(sessionId)` — `SideChatPanel` 在 `onMounted` 时订阅 `sideSessionId`
- `routeEvent()` 按传入的 `sessionId` 路由事件——边路任务事件会路由到正确的 session
---
### 模块 D：WebSocket 事件协议
#### D1. 客户端 → 服务端
| type | 说明 | 字段 | 使用场景 |
|------|------|------|---------|
| `create_side_session` | 创建边路任务并发送首条消息 | `sessionId`(parent), `data: { content, inheritContext }` | 首条消息 |
| `send_message` | 边路任务后续消息（复用标准协议） | `sessionId`(side), `data: { content, eventId }` | 后续多轮消息 |
| `cancel_side_task` | 取消边路任务 | `sideSessionId` | 用户取消 |
#### D2. 服务端 → 客户端（新增事件）
| type | 说明 | 字段 |
|------|------|------|
| `side_session_created` | 边路任务会话已创建 | `sessionId`(parent), `data: { sideSessionId, title }` |
**注意**：边路任务的流式事件（`content_delta`、`tool_call_start`、`tool_call_result`、`session_status` 等）复用**标准事件类型**，使用 `sessionId = sideSessionId` 路由。前端通过订阅 sideSessionId 接收这些事件，`routeEvent()` 无需修改。
---
## 6. 落地清单
### 6.1 后端
| # | 任务 | 文件 | 类型 | 依赖 |
|---|------|------|------|------|
| B1 | 数据库迁移脚本 | `V041__add_side_task_support.sql` | 新增 | V040（或合并） |
| B2 | `HarnessService.executeSideFirstMessage()` | `HarnessService.java` | 新增方法 | B1 |
| B3 | `HarnessService.generateContextSummary()` | `HarnessService.java` | 新增方法 | - |
| B4 | `HarnessService.buildContext()` 改为 public | `HarnessService.java` | 修改 | - |
| B5 | `StreamingWsHandler.handleCreateSideSession()` | `StreamingWsHandler.java` | 新增方法 | B2 |
| B6 | `StreamingWsHandler.handleCancelSideTask()` | `StreamingWsHandler.java` | 新增方法 | - |
| B7 | `SessionService.updateField()` | `SessionService.java` | 新增方法 | - |
| B8 | `SessionService.save()` | `SessionService.java` | 新增方法 | - |
| B9 | `saveMessage()` 跳过边路任务标题生成 | `SessionService.java` | 修改 | B1 |
### 6.2 前端
| # | 任务 | 文件 | 类型 | 依赖 |
|---|------|------|------|------|
| F1 | `Tab` 类型扩展（新增 `side_task`） | `desktop/src/types/file-browser.ts` | 修改 | - |
| F2 | `useCenterTabs` 新增 `openSideTaskTab()` / `closeSideTaskTab()` | `desktop/src/composables/useCenterTabs.ts` | 新增方法 | F1 |
| F3 | `SideChatPanel` 组件 | `desktop/src/components/chat/SideChatPanel.vue` | 新增组件 | F2 |
| F4 | `CenterTabContainer` 新增 `side_task` 渲染分支 | `desktop/src/components/center/CenterTabContainer.vue` | 修改 | F3 |
| F5 | `useStreamWS` 新增 `create_side_session` 发送方法 | `desktop/src/composables/useStreamWS.ts` | 新增方法 | - |
| F6 | `useStreamWS` 新增 `side_session_created` 事件处理 | `desktop/src/composables/useStreamWS.ts` | 新增 | - |
| F7 | `TaskView` 新增「+ 边路任务」入口 | `desktop/src/views/task/TaskView.vue` | 修改 | F2 |
### 6.3 建议实现顺序
```
模块 A (数据库) → 模块 B (后端) → 模块 C (前端)
后端：
B1 → B4 → B2/B3 → B5/B6 → B7/B8/B9
前端（无后端依赖的部分可以先做）：
F1 → F2 → F5/F6 → F3 → F4 → F7
```
---
## 7. 关键设计决策
| # | 决策 | 理由 |
|---|------|------|
| 1 | 边路任务作为 Tab 管理，复用 `useCenterTabs` | 与文件预览/Diff 对比统一交互范式，不引入新的 UI 模式 |
| 2 | 首条消息用专用 `create_side_session` 事件，后续复用 `send_message` | 首条需要创建会话 + 注入上下文；后续走标准流程最大化复用 |
| 3 | 流式事件使用标准事件类型 + sideSessionId 路由 | 不添加冗余的 `side_*` 事件前缀，前端通过 sessionId 自然隔离 |
| 4 | 边路任务使用独立 session（`session_type = 'side_task'`） | 复用现有 session/message 基础设施，不新增表 |
| 5 | 边路任务结果不写回主会话 | 核心需求：隔离上下文 |
| 6 | 上下文继承仅首条消息生效，通过 system prompt 注入摘要 | 首条消息后的上下文由边路任务自身的历史消息提供 |
| 7 | 复用主任务 Agent/模型/工作区，不可修改 | 简化 UI 和实现 |
| 8 | 边路任务与主任务并行执行 | sessionLock 按 sessionId 隔离，天然并行 |
| 9 | 支持多轮对话 | 用户在边路 Tab 中可追加回复，走标准 send_message 流程 |
| 10 | 关闭 Tab 不删除会话数据 | 用户可以重新打开；数据在 DB 中保留 |
---
## 8. 风险与缓解
| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 边路任务与主任务并发操作同一文件 | 产生文件冲突 | `SideChatPanel` 中给出提示"主任务可能正在操作文件" |
| 边路任务工具调用需审批（LOCAL 模式） | 因等待审批而卡住 | 继承主会话 permissionLevel；审批 UI 需标注来源为边路任务 |
| 边路任务执行中用户再次发送消息 | handleSendMessage 检测到 RUNNING 拒绝 | 复用消息队列机制，busy 时入队等待 |
| 边路任务 session 数据膨胀 | DB 中堆积大量 side_task session | 后续增加清理策略：关闭主会话时级联清理子会话；或定期清理超过 N 天的 side_task |
| KeepAlive 缓存过多 Tab | 内存占用增长 | `KeepAlive :max="20"` 限制已有；边路任务 Tab 数量由用户控制 |
| 边路任务 Tab 内 WS 订阅未取消 | 内存泄漏、多余事件 | `SideChatPanel.onUnmounted()` 调用 unsubscribe |
---
## 9. 不做清单
以下需求明确**不在本方案范围内**：
| 不做的事项 | 原因 |
|-----------|------|
| Agent 通过工具调用发起边路任务 | 用户明确只需"用户手动触发" |
| 边路任务结果注入主任务上下文 | 核心需求要求"不影响主任务上下文" |
| 边路任务允许切换 Agent/模型/工作区 | 简化设计，定位为快捷操作 |
| 管理后台支持边路任务 | 仅桌面端用户场景 |
| 边路任务保存为模板/快捷指令 | 后续可扩展，本方案不做 |
| 边路任务支持图片输入 | 部署/提交等场景不需要图片 |
| 边路任务 Tab 关闭后 session 仍出现在会话列表 | 边路任务仅通过 Tab 访问，`session_type = 'side_task'` 的会话不在主会话列表 API 中返回 |
| 多个边路任务 Tab 间切换保留完整的对话状态 | `KeepAlive` + `sessionStore` 的按 sessionId 缓存已支持 |