|
|
@@ -0,0 +1,418 @@
|
|
|
+# 普通聊天 + 任务流水线（意图路由）设计方案
|
|
|
+
|
|
|
+> 状态：设计稿，未实施
|
|
|
+> 日期：2026-10-20
|
|
|
+> 范围：`ai-server/src/main/java/com/zsjz/ai/module/agent/`（意图识别、闲聊/任务流水线）
|
|
|
+> 关联需求：在现有「数据分析」AI 流水线之外，新增一条同时承接**普通聊天**与**任务执行**的流水线，由意图识别按条消息自动路由。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 0. 需求口径
|
|
|
+
|
|
|
+用户原话中的「人物」按同音词「任务」理解（已确认："任务。"）。要新增**一条** AI 流水线，同时承接：
|
|
|
+
|
|
|
+- **普通聊天**：问候、感谢、能力询问、与案件数据无关的一般问答；
|
|
|
+- **任务执行**：工作区文件读写/检索、执行命令、执行 Python 脚本、批量文件处理等。
|
|
|
+
|
|
|
+该流水线与现有数据分析流水线并存，按意图**逐条消息自动路由**。分类失败、超时、未知意图一律回落到**数据分析流水线**（保持现状，fail-safe）。现有数据分析 agent 的 67 个业务工具、提示词、SSE 契约全部不动。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 1. 现状结论（决定了改法）
|
|
|
+
|
|
|
+- `IntentMiddleware` 只做三件事：调 LLM 分类、往输入追加 `<intent-analysis>` 合成消息、发 `intent` SSE 帧；**不改变执行路径**。所有意图都走同一个 `HarnessAgent`、同一套工具。
|
|
|
+- `AgentChatServiceImpl#doStreamLocked` 是唯一调用 `AgentService.getOrCreateAgent` 的地方，路由改造点单一。
|
|
|
+- `IntentEnum` 目前是死代码（`fromCode` 无调用方），`IntentResult` 注释、`prompts/intent-recognition.txt` 里还留着旧的二分类 `《闲聊或无关指令》/《可能的数据分析请求》` 和已不存在的 `response` 字段。
|
|
|
+- `IntentProperties.timeoutSeconds/maxTokens` 从未生效；`IntentService.safeAnalyze` 的 `.block()` 没有超时，模型卡住会阻塞整条流。
|
|
|
+- AgentScope 2.0.1 Harness 自带以下工具（已从 jar 核实）：
|
|
|
+ - 文件：`read_file`、`write_file`、`edit_file`、`grep_files`、`glob_files`、`list_files`；
|
|
|
+ - 命令：`execute`（仅当文件系统是 `AbstractSandboxFilesystem` 时注册，`LocalFilesystemSpec` 满足）；
|
|
|
+ - 构建器开关：`disableShellTool()`、`disableMemoryTools()`、`enableTaskList(boolean)`、`toolsConfig(...)`；
|
|
|
+ - `LocalFilesystemSpec`：`project(Path)`（同时设置 shell cwd 与路径策略根）、`mode(LocalFsMode)`、`addRoot(Path)`、`executeTimeoutSeconds(int)`、`maxOutputBytes(int)`、`env(...)`、`inheritEnv(boolean)`。
|
|
|
+- 现有数据分析 agent 也挂了 `LocalFilesystemSpec`，所以它本来就有 shell/文件工具。新流水线的价值是：**去掉 55 个业务工具 + 数据 render 契约，换成任务型提示词与更严格的路径边界**。
|
|
|
+- 已有独立流水线的成熟先例是 AI 研判（`InsightController` + `InsightAgentFactory` + 静态 prompt），但它按 endpoint 隔离，不是按意图。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 总体架构
|
|
|
+
|
|
|
+```
|
|
|
+POST /chat/stream
|
|
|
+ ├─ 会话/附件/模型解析（沿用现有逻辑）
|
|
|
+ ├─ ChatIntentRouter.route(modelId, sessionId, question)
|
|
|
+ │ └─ IntentService.safeAnalyze → LlmService.chatAs（超时/关思考/fail-open）
|
|
|
+ │ ├─ data_query / schema_explore / etl_clean / visualization / null
|
|
|
+ │ │ → DataAnalysisPipeline（现有 HarnessAgent + AgentService 实例池）
|
|
|
+ │ └─ task_execute / general_chat
|
|
|
+ │ → TaskPipeline（TaskAgentFactory：文件/命令/Python + 任务提示词）
|
|
|
+ ├─ 事件流头部注入 intent CustomEvent（code/label/pipeline/enhanced/entities）
|
|
|
+ └─ 原 SSE 转换、工具事件聚合、assistant 落库、心跳、取消处理全部复用
|
|
|
+```
|
|
|
+
|
|
|
+两条流水线都返回 `Flux<AgentEvent>`，因此 `AgentChatServiceImpl` 里那一大段事件→SSE 的转换代码**一行不改**。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 意图层改造
|
|
|
+
|
|
|
+### 3.1 `IntentEnum`（新增枚举值与流水线归属）
|
|
|
+
|
|
|
+```java
|
|
|
+DATA_QUERY("data_query", "数据查询", DATA_ANALYSIS)
|
|
|
+SCHEMA_EXPLORE("schema_explore", "表结构探索", DATA_ANALYSIS)
|
|
|
+ETL_CLEAN("etl_clean", "数据处理", DATA_ANALYSIS)
|
|
|
+VISUALIZATION("visualization", "图表可视化", DATA_ANALYSIS)
|
|
|
+TASK_EXECUTE("task_execute", "任务执行", TASK)
|
|
|
+GENERAL_CHAT("general_chat", "通用问答", TASK)
|
|
|
+
|
|
|
+// 宽松归一：去《》/空白/大小写，先匹配 code 再匹配 label；未知返回 null。
|
|
|
+// 不要回落 GENERAL_CHAT，否则未知意图会被误送任务流水线。
|
|
|
+public static IntentEnum fromAny(String raw)
|
|
|
+```
|
|
|
+
|
|
|
+`IntentEnum.fromCode` 保留（兼容），新增 `fromAny` 供路由使用。
|
|
|
+
|
|
|
+### 3.2 `IntentResult` + 提示词
|
|
|
+
|
|
|
+- `IntentResult.intent` 的语义改为 **code**（`data_query` 等），修掉过期的 `《...》` 注释。
|
|
|
+- 重写 `prompts/intent-recognition.txt`：
|
|
|
+ - 6 个标签，写清每条流水线的判定边界；
|
|
|
+ - 明确规则：最新输入为主、历史只补指代；**拿不准 → `data_query`**；纯问候/能力询问 → `general_chat`；只有明确的文件/命令/脚本操作才 `task_execute`；
|
|
|
+ - 删除 `《》` 强制要求、删除旧二分类段落和 `response` 字段；
|
|
|
+ - 移除 `{format}` 占位（schema 交给 `LlmService.chatAs` 追加），只保留 `{multi_turn}`。
|
|
|
+- 数据结构仍走 `@JsonPropertyDescription` 生成 schema。
|
|
|
+
|
|
|
+### 3.3 `IntentService` 改造
|
|
|
+
|
|
|
+- 注入 `LlmService`，用 `chatAs(request, IntentResult.class)` 替换自建 `ReActAgent`：
|
|
|
+ - `enableThinking(false)`（分类任务不需要思考，避免 reasoning 吃掉 token）；
|
|
|
+ - `maxTokens(props.maxTokens)`、`timeout(Duration.ofSeconds(props.timeoutSeconds))` —— 这两个配置终于生效；
|
|
|
+ - 任何异常/解析失败 → `null`（fail-open）。
|
|
|
+- 返回新 record `IntentDecision(IntentEnum intent, String enhanced, List<String> entities)`；`fromAny` 为 null 时返回 null。
|
|
|
+
|
|
|
+### 3.4 `IntentMiddleware`（只保留为回滚路径）
|
|
|
+
|
|
|
+- 改为消费 `IntentDecision`，渲染时用 `label`，`intent` 帧仍下发中文 label（前端兼容）。
|
|
|
+- `AgentService.buildAgent` 中**条件挂载**：
|
|
|
+
|
|
|
+```java
|
|
|
+if (!etlProperties.getIntent().isRouteEnabled()) {
|
|
|
+ b.middleware(new IntentMiddleware(intentService, etlProperties.getIntent(), modelId));
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+- 路由开启时中间件不挂载，避免每轮分类两次。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 路由层
|
|
|
+
|
|
|
+新增 `module/agent/intent/ChatIntentRouter.java`：
|
|
|
+
|
|
|
+```java
|
|
|
+public record RouteResult(IntentDecision decision, ChatPipeline pipeline) {}
|
|
|
+
|
|
|
+public RouteResult route(Long modelId, Long sessionId, String question) {
|
|
|
+ if (!intentEnabled || !routeEnabled) return new RouteResult(null, dataPipeline);
|
|
|
+ IntentDecision d = intentService.safeAnalyze(modelId, sessionId, question);
|
|
|
+ if (d == null) return new RouteResult(null, dataPipeline);
|
|
|
+ ChatPipeline p = d.intent().pipeline() == PipelineType.TASK ? taskPipeline : dataPipeline;
|
|
|
+ return new RouteResult(d, p);
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+`intent` 帧由 `IntentFrames.of(decision)` 统一生成：
|
|
|
+
|
|
|
+```json
|
|
|
+{"type":"intent","code":"task_execute","label":"任务执行","intent":"任务执行",
|
|
|
+ "pipeline":"task","enhanced":"...","entities":[]}
|
|
|
+```
|
|
|
+
|
|
|
+保留 `intent` = label 是前端兼容做法；新增 `code/label/pipeline` 供 UI 精确展示。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 流水线抽象
|
|
|
+
|
|
|
+新增 `module/agent/pipeline/`：
|
|
|
+
|
|
|
+```java
|
|
|
+public interface ChatPipeline {
|
|
|
+ PipelineType type(); // DATA_ANALYSIS / TASK
|
|
|
+ Flux<AgentEvent> stream(ChatPipelineContext ctx);
|
|
|
+}
|
|
|
+
|
|
|
+public record ChatPipelineContext(
|
|
|
+ Long sessionId, Long caseId, Long modelId, Long agentRowId,
|
|
|
+ String userId, SkillFilter skillFilter,
|
|
|
+ String userText, List<Msg> messages, IntentDecision intent) {}
|
|
|
+```
|
|
|
+
|
|
|
+### 5.1 `DataAnalysisPipeline`
|
|
|
+
|
|
|
+把现有 `doStreamLocked` 里的 agent 获取 + `RuntimeContext` 构建搬进来，行为保持不变：
|
|
|
+
|
|
|
+```java
|
|
|
+HarnessAgent agent = agentService.getOrCreateAgent(ctx.caseId(), ctx.agentRowId(), ctx.modelId());
|
|
|
+RuntimeContext rc = RuntimeContext.builder()
|
|
|
+ .userId(ctx.userId())
|
|
|
+ .sessionId(String.valueOf(ctx.sessionId()))
|
|
|
+ .put(SkillFilter.class, ctx.skillFilter())
|
|
|
+ .build();
|
|
|
+return agent.streamEvents(ctx.messages(), rc);
|
|
|
+```
|
|
|
+
|
|
|
+### 5.2 `TaskPipeline`
|
|
|
+
|
|
|
+```java
|
|
|
+HarnessAgent agent = taskAgentFactory.getOrCreate(ctx.userId(), ctx.caseId(), ctx.modelId());
|
|
|
+RuntimeContext rc = RuntimeContext.builder()
|
|
|
+ .userId(ctx.userId())
|
|
|
+ .sessionId(ctx.sessionId() + "-task") // 与数据流水线隔离记忆槽
|
|
|
+ .put(SkillFilter.class, ctx.skillFilter())
|
|
|
+ .build();
|
|
|
+return agent.streamEvents(ctx.messages(), rc);
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 任务流水线（`module/agent/task/`）
|
|
|
+
|
|
|
+### 6.1 `TaskAgentFactory`
|
|
|
+
|
|
|
+沿用 `InsightAgentFactory` + `AgentInstancePool` 的模式：
|
|
|
+
|
|
|
+- 池 key：`task-u{userId}-w{caseId}-m{modelId}`；上限 32，空闲 30 分钟回收；构建在锁外。
|
|
|
+- 工作区：`WorkspaceManagerFactory.resolveAgentDataPath(cwd, userId, caseId, 9528L)`（固定虚拟 agent id，避免和真实 `agent.row_id` 冲突）。
|
|
|
+- 构建：
|
|
|
+
|
|
|
+```java
|
|
|
+HarnessAgent.builder()
|
|
|
+ .name("task-agent").description("通用聊天与任务执行助手")
|
|
|
+ .sysPrompt(taskPromptBuilder.build(caseId))
|
|
|
+ .maxIters(props.getMaxIters()) // 默认 20
|
|
|
+ .model(model).agentId("task-agent")
|
|
|
+ .workspace(workspace)
|
|
|
+ .filesystem(new LocalFilesystemSpec()
|
|
|
+ .isolationScope(IsolationScope.USER)
|
|
|
+ .project(workspace) // shell cwd = 工作区；ROOTED 路径策略根
|
|
|
+ .mode(LocalFsMode.ROOTED)
|
|
|
+ .executeTimeoutSeconds(props.getShellTimeoutSeconds())
|
|
|
+ .maxOutputBytes(props.getMaxOutputBytes())
|
|
|
+ .addRoot(attachmentRoot(userId, caseId))) // 允许读本案附件
|
|
|
+ .toolkit(new Toolkit()) // 空业务工具
|
|
|
+ .enableMetaTool(false) // 不要 reset_equipped_tools
|
|
|
+ .enableTaskList(true) // todo_write，多步任务可规划
|
|
|
+ .disableMemoryTools() // 去掉 memory_*/session_*，避免与后缀 sessionId 冲突
|
|
|
+ .stateStore(agentStateStore);
|
|
|
+if (!props.isShellEnabled()) builder.disableShellTool();
|
|
|
+if (props.isSkillsEnabled() && 用户技能目录存在) builder.skillRepository(...);
|
|
|
+```
|
|
|
+
|
|
|
+### 6.2 工具清单（全部是 Harness 内置，无需新写 `@Tool`）
|
|
|
+
|
|
|
+| 工具 | 来源 | 用途 |
|
|
|
+|---|---|---|
|
|
|
+| `read_file` / `write_file` / `edit_file` | FilesystemTool | 文件读写改 |
|
|
|
+| `grep_files` / `glob_files` / `list_files` | FilesystemTool | 文件检索 |
|
|
|
+| `execute` | ShellExecuteTool | 命令、`python xxx.py`、批量文件操作 |
|
|
|
+| `todo_write` | enableTaskList | 多步任务清单 |
|
|
|
+
|
|
|
+**Python 策略**：v1 不注册 `execute_python`（它绑定案件 DuckDB 快照、属于数据分析语义）；Python 脚本用 `execute` 执行。若后续需要结构化 Python 工具，再加一个工作区 cwd 的 `run_python`，不依赖案件库。
|
|
|
+
|
|
|
+### 6.3 工作区与安全边界
|
|
|
+
|
|
|
+- `project(workspace)` + `LocalFsMode.ROOTED`：绝对路径只能落在工作区、project、`addRoot` 内；`..`/越界抛 `SecurityException`。
|
|
|
+- `addRoot` 只加 `{user.dir}/QingJian/chat-attachments/{userId}/{caseId}`，让任务 agent 能处理附件；不暴露整个仓库。
|
|
|
+- **环境变量不要全量继承**：`inheritEnv` 默认 false；显式注入最小集合 `PATH/SystemRoot/SystemDrive/TEMP/TMP/COMSPEC/HOME/USERPROFILE/LANG/PYTHONIOENCODING`，避免把数据库密码等进程环境泄露给模型。
|
|
|
+- `shell-enabled` 配置开关：关闭时 `disableShellTool()`，任务流水线退化为只读/写文件。
|
|
|
+- 提示词层再加一道：禁止删除/覆盖前不确认、禁止访问工作区外路径、失败如实报告。
|
|
|
+- 说明：现有数据分析 agent 本来就有 shell 能力，本次不新增攻击面；但把任务链路作为一等功能后，建议后续接 `SandboxFilesystemSpec`（Docker）做 OS 级隔离。本期先做路径/环境/开关三层约束。
|
|
|
+
|
|
|
+### 6.4 提示词 `prompts/task-agent.txt`
|
|
|
+
|
|
|
+要点：
|
|
|
+
|
|
|
+1. 角色：清鉴工作区里的通用任务助手；
|
|
|
+2. 能力清单与工具使用优先级（有专用文件工具就不要用 shell）；
|
|
|
+3. 工作区规则：相对路径、禁止越界、附件路径可直接读；
|
|
|
+4. 行为规则：闲聊直接回答不调工具；任务先规划再执行；删除/覆盖先确认；不编造执行结果；
|
|
|
+5. 数据查询类问题（查案件库/统计业务数据）不在职责内，提示用户换数据分析模式——作为误路由的兜底；
|
|
|
+6. 输出：中文 Markdown，结束时说明"做了什么/产物在哪/如何验证"。
|
|
|
+
|
|
|
+### 6.5 记忆隔离
|
|
|
+
|
|
|
+- 两条流水线共用 `AgentStateStore` 实例，但 `RuntimeContext.sessionId` 不同：数据用 `{sessionId}`，任务用 `{sessionId}-task`。
|
|
|
+- 原因：若共用槽位，数据链路的 `execute_sql` 等 tool_use 消息会被任务 agent 加载，而任务 agent 没有这些工具，部分厂商会直接拒绝请求。
|
|
|
+- 代价：任务 agent 不直接看到数据链路的 agent 记忆；靠意图增强的 `enhanced` 问题 + DB 历史（分类器每次都读）补上下文。任务流水线首版不生成 followup 建议（`FollowupMiddleware` 只挂在数据 agent 上）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 7. `AgentChatServiceImpl#doStreamLocked` 改造顺序
|
|
|
+
|
|
|
+```java
|
|
|
+// 1. 会话/附件（不变）
|
|
|
+// 2. 模型解析（不变）+ 显式校验模型存在（新增 AgentModelMapper.selectById）
|
|
|
+// 3. 意图路由（新增）：RouteResult route = chatIntentRouter.route(...)
|
|
|
+// 4. 用户消息落库（从原位置后移：分类历史不再包含本轮问题）
|
|
|
+// 5. 组装 msgs：用户消息 +（有决策时）<intent-analysis> 合成消息
|
|
|
+// 6. modelChanged 回写（模型已校验，可安全回写）
|
|
|
+// 7. events = intent 帧 + route.pipeline().stream(ctx)
|
|
|
+// 8. 原 SSE 事件转换/落库/心跳/取消逻辑保持不变
|
|
|
+```
|
|
|
+
|
|
|
+注意：
|
|
|
+
|
|
|
+- `IntentMiddleware` 里原来的 synthetic 消息注入逻辑抽成 `IntentMessages.analysis(decision)`，两条流水线共用。
|
|
|
+- `agentRowId`、`RuntimeContext`、`SkillFilter` 的获取方式不变；`SkillFilter` 放进 `ChatPipelineContext`。
|
|
|
+- 数据流水线的池 key、工具装配、提示词追加全部不变。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 8. 前端改动（最小集）
|
|
|
+
|
|
|
+- `src/ai/api/types.ts`：`SseIntentData` 增加 `code? / label? / pipeline?: 'data' | 'task'`。
|
|
|
+- `src/ai/components/StreamStatusBar.vue`：`raw = intent.label || intent.intent`；tooltip 增加流水线名称；标签逻辑不变。
|
|
|
+- `src/ai/utils/constants.ts`：`TOOL_LABELS` 增加
|
|
|
+ `read_file/write_file/edit_file/grep_files/glob_files/list_files/execute/todo_write` 等中文标签（否则时间线显示原始英文工具名）。
|
|
|
+- `chatStream.ts` 已整对象存 `message.intent`，无需改；`sse.ts` 已转发 `intent`，无需改。
|
|
|
+- 不加新页面、不加新模式选择器；用户无感知，只在状态栏看到"任务执行/通用问答"标签。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 9. 配置
|
|
|
+
|
|
|
+```yaml
|
|
|
+etl:
|
|
|
+ intent:
|
|
|
+ enabled: true
|
|
|
+ route-enabled: true # false = 完全回到现状（中间件分类 + 单一流水线）
|
|
|
+ timeout-seconds: 5
|
|
|
+ history-turns: 3
|
|
|
+ max-tokens: 512
|
|
|
+ task-agent:
|
|
|
+ enabled: true
|
|
|
+ max-iters: 20
|
|
|
+ pool-max: 32
|
|
|
+ idle-timeout-minutes: 30
|
|
|
+ shell-enabled: true
|
|
|
+ shell-timeout-seconds: 120
|
|
|
+ max-output-bytes: 100000
|
|
|
+ skills-enabled: true
|
|
|
+```
|
|
|
+
|
|
|
+`IntentProperties` 增加 `routeEnabled`（Java 默认 false，yaml 显式开 true）；`EtlProperties` 增加 `taskAgent`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 10. 文件改动清单
|
|
|
+
|
|
|
+**新增**
|
|
|
+
|
|
|
+- `module/agent/intent/IntentDecision.java`
|
|
|
+- `module/agent/intent/IntentFrames.java`（intent 帧 + `<intent-analysis>` 渲染）
|
|
|
+- `module/agent/intent/ChatIntentRouter.java`
|
|
|
+- `module/agent/pipeline/ChatPipeline.java`
|
|
|
+- `module/agent/pipeline/PipelineType.java`
|
|
|
+- `module/agent/pipeline/ChatPipelineContext.java`
|
|
|
+- `module/agent/pipeline/DataAnalysisPipeline.java`
|
|
|
+- `module/agent/pipeline/TaskPipeline.java`
|
|
|
+- `module/agent/task/TaskAgentFactory.java`
|
|
|
+- `module/agent/task/TaskAgentProperties.java`
|
|
|
+- `module/agent/task/TaskPromptBuilder.java`
|
|
|
+- `src/main/resources/prompts/task-agent.txt`
|
|
|
+
|
|
|
+**修改**
|
|
|
+
|
|
|
+- `intent/IntentEnum.java`、`IntentResult.java`、`IntentService.java`、`IntentMiddleware.java`、`IntentProperties.java`
|
|
|
+- `config/EtlProperties.java`
|
|
|
+- `service/AgentService.java`（条件挂载中间件）
|
|
|
+- `service/impl/AgentChatServiceImpl.java`（路由 + 模型校验 + 消息顺序）
|
|
|
+- `src/main/resources/application.yaml`
|
|
|
+- 前端 `types.ts`、`StreamStatusBar.vue`、`constants.ts`
|
|
|
+
|
|
|
+**测试**
|
|
|
+
|
|
|
+- 新增 `intent/IntentEnumTest`、`intent/IntentServiceTest`（mock LlmService）、`intent/ChatIntentRouterTest`、`task/TaskPromptBuilderTest`、`task/TaskAgentFactoryTest`
|
|
|
+- 回归 `service/AgentExpertTest`（若断言了中间件装配）、`tools/AgentToolRegistryTest`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 11. 实施步骤
|
|
|
+
|
|
|
+1. 意图层：`IntentEnum/IntentResult/IntentService/IntentDecision/IntentFrames` + 提示词重写 + 单测。
|
|
|
+2. 抽流水线：`ChatPipeline/DataAnalysisPipeline`，`AgentChatServiceImpl` 先只走数据流水线，跑全量测试确认**零行为变化**。
|
|
|
+3. 任务链路：`TaskAgentFactory/TaskPromptBuilder/TaskAgentProperties` + 配置 + 单测（断言 `LocalFilesystemSpec.getProject()/getMode()/getAdditionalRoots()`、shell 开关）。
|
|
|
+4. 接路由：`ChatIntentRouter` + `doStreamLocked` 改造 + `AgentService` 条件中间件 + intent 帧。
|
|
|
+5. 前端：类型、状态栏标签、工具中文名。
|
|
|
+6. 配置开关与冒烟：数据分析 / 闲聊 / 任务（建文件、执行命令、跑 Python）/ 附件处理 / 回滚。
|
|
|
+7. `mvn -pl ai-server test`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 12. 测试与验收
|
|
|
+
|
|
|
+**单元**
|
|
|
+
|
|
|
+- `fromAny("data_query")`、`fromAny("《数据查询》")`、未知 → null。
|
|
|
+- 路由：6 个意图 → 预期 pipeline；null → data；`route-enabled=false` 时不调用 `IntentService`。
|
|
|
+- `IntentService`：正常返回决策、LLM 抛异常 → null、未知 code → null。
|
|
|
+- 任务提示词：含工作区规则/工具优先级/数据问题兜底，不含 SQL 契约。
|
|
|
+- 任务工厂：路径策略、shell 开关、附件根。
|
|
|
+
|
|
|
+**手工冒烟（SSE）**
|
|
|
+
|
|
|
+| 输入 | 期望 |
|
|
|
+|---|---|
|
|
|
+| `案件里有多少人？` | `intent=data_query`，数据流水线，SQL 工具 |
|
|
|
+| `你好` | `intent=general_chat`，任务流水线，不调工具，快速返回 |
|
|
|
+| `在当前工作区建 test.txt 写入 hello` | `intent=task_execute`，`write_file` 工具事件 |
|
|
|
+| `执行 python 脚本 demo.py` | `task_execute`，`execute` 工具事件 |
|
|
|
+| `统计附件 CSV 的金额分布` | `data_query`，数据流水线（execute_python） |
|
|
|
+| `把附件 CSV 按性别拆成两个文件` | `task_execute`，任务流水线 |
|
|
|
+| `route-enabled=false` 重启后 `你好` | 回到现状（中间件分类 + 数据 agent），intent 帧仍正常 |
|
|
|
+
|
|
|
+**回滚**
|
|
|
+
|
|
|
+- 一个配置项 `etl.intent.route-enabled=false` 即可完全回到当前行为；数据流水线代码虽被抽取，但 agent 构建、工具、提示词、SSE 全部保持原样。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 13. 风险与应对
|
|
|
+
|
|
|
+1. **误分类**：分类器拿不准时强制 `data_query`；任务提示词对数据问题有兜底话术；后续可再加请求级手动指定（本期按确认不做）。
|
|
|
+2. **Shell 安全**：路径策略 + 最小环境变量 + 超时/输出上限 + `shell-enabled` 开关 + 提示词约束；现有数据 agent 本就有 shell，不新增面。生产如需强隔离，后续切 `SandboxFilesystemSpec`（Docker）。
|
|
|
+3. **记忆串台**：任务用 `-task` 后缀的独立记忆槽，避免跨工具集的历史污染；代价是跨流水线上下文依赖 `enhanced` 改写。
|
|
|
+4. **意图识别延迟**：改用 `LlmService` 并加 5s 超时、关闭思考，失败直接回落，不阻塞主链路。
|
|
|
+5. **兼容性**：intent 帧保留 `intent` 中文字段，新增 `code/label/pipeline`，老前端不受影响。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 14. 本期不做
|
|
|
+
|
|
|
+- 会话级手动切换/锁定流水线（按确认走自动路由）。
|
|
|
+- 任务流水线的 followup 建议。
|
|
|
+- 任务工作区的文件浏览/下载 UI。
|
|
|
+- Docker/OS 级沙箱。
|
|
|
+- 把 `pipeline` 持久化进消息 metadata（可作为后续增强）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 附：关键代码位置索引
|
|
|
+
|
|
|
+| 主题 | 位置 |
|
|
|
+|---|---|
|
|
|
+| 意图分类入口 | `module/agent/intent/IntentService.java` |
|
|
|
+| 意图中间件 | `module/agent/intent/IntentMiddleware.java` |
|
|
|
+| 意图提示词 | `src/main/resources/prompts/intent-recognition.txt` |
|
|
|
+| agent 装配/中间件挂载 | `module/agent/service/AgentService.java`（`buildAgent`） |
|
|
|
+| 流式主链路 | `module/agent/service/impl/AgentChatServiceImpl.java`（`doStreamLocked`） |
|
|
|
+| SSE 事件转换 | 同上（`stream` / `doStreamLocked` 内 `concatMap`） |
|
|
|
+| 独立流水线先例 | `module/agent/insight/agent/InsightAgentFactory.java` |
|
|
|
+| 实例池 | `module/agent/service/AgentInstancePool.java` |
|
|
|
+| 工作区路径 | `module/agent/WorkspaceManagerFactory.java` |
|
|
|
+| Python 执行 | `module/agent/python/PythonExecutor.java` |
|
|
|
+| 附件存储根 | `module/agent/attachment/ChatAttachmentService.java`（`baseDir`） |
|
|
|
+| 前端 intent 渲染 | `ai-electron/frontend/src/ai/components/StreamStatusBar.vue` |
|
|
|
+| 前端工具标签 | `ai-electron/frontend/src/ai/utils/constants.ts` |
|
|
|
+| 前端 SSE 类型 | `ai-electron/frontend/src/ai/api/types.ts` |
|
