docs(ssa): Complete intelligent dialogue and tool system architecture design
Architecture Design: - Add intent recognition and dialogue architecture design (Intent Router + DataContext) - Add tool system planning (4-layer 7-tool fusion solution: READ/INTERACT/THINK/ACT) - Add 4-layer 7-tool implementation mechanism details (Conversation Layer LLM + Node.js orchestration) Development Plan (v1.2): - Create 6-phase development plan (134h/22 days) for intelligent dialogue system - Add 8 architectural constraints (C1-C8): no Function Calling, Postgres-Only cache, streaming output, context guard, Zod dynamic validation - Correct Session Blackboard to use CacheFactory (Postgres-Only, no Redis) Status Updates: - Update SSA module status: QPER complete + dialogue architecture design complete - Update system-level status: add SSA architecture design milestone Other: - R tools minor fixes (chi_square, correlation, logistic_binary, mann_whitney, t_test_paired) - Frontend AIA chat workspace style adjustment Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
911
docs/03-业务模块/SSA-智能统计分析/04-开发计划/11-智能对话与工具体系开发计划.md
Normal file
911
docs/03-业务模块/SSA-智能统计分析/04-开发计划/11-智能对话与工具体系开发计划.md
Normal file
@@ -0,0 +1,911 @@
|
||||
# SSA-Pro 智能对话与工具体系开发计划
|
||||
|
||||
> **文档版本：** v1.2
|
||||
> **创建日期：** 2026-02-21
|
||||
> **最后更新：** 2026-02-22（v1.2 — 新增实现规范与约束：6 条审查建议 + Postgres-Only 缓存修正）
|
||||
> **文档类型：** 开发计划 (Development Plan)
|
||||
> **前置设计：**
|
||||
> - `00-系统设计/SSA-Pro 意图识别与对话架构设计.md`
|
||||
> - `00-系统设计/SSA-Pro 工具体系规划方案（团队讨论稿）.md`（v3.1 融合方案）
|
||||
> - `00-系统设计/SSA-Pro 四层七工具实现机制详解.md`（v1.1 三层架构 + 对话层 LLM）
|
||||
> **前置计划：** `04-开发计划/10-QPER架构开发计划-智能化主线.md`（Phase E+/Q/P/R 已完成）
|
||||
> **目标：** 将 SSA 从"统计分析执行器"升级为"数据感知的统计顾问"
|
||||
|
||||
---
|
||||
|
||||
## 1. 文档概要
|
||||
|
||||
### 1.1 背景
|
||||
|
||||
QPER 主线（Phase E+ → Q → P → R）已完成闭环，系统具备了完整的"接单→规划→执行→结论"能力。但当前系统存在两个核心问题：
|
||||
|
||||
1. **无对话能力** — 用户每条消息都被当作分析请求，无法自由探索数据、咨询方法
|
||||
2. **工具体系单一** — 仅有 R 执行工具，缺少数据查看、方法咨询、用户交互等非执行类工具
|
||||
|
||||
本计划基于已定型的两份设计文档，制定从设计到代码落地的具体开发任务。
|
||||
|
||||
### 1.2 与 QPER 主线计划的关系
|
||||
|
||||
```
|
||||
QPER 主线计划（10-QPER架构开发计划）
|
||||
├── Phase E+ ✅ 已完成
|
||||
├── Phase Q ✅ 已完成
|
||||
├── Phase P ✅ 已完成
|
||||
├── Phase R ✅ 已完成
|
||||
├── Phase Deploy 📋 待启动 ← 本计划的前置条件
|
||||
└── Phase Q+ 📋 → 吸收进本计划 Phase I（DataContext + 变量字典）
|
||||
|
||||
本计划（11-智能对话与工具体系开发计划）
|
||||
├── Phase I Session 黑板 + READ 层工具
|
||||
├── Phase II 意图路由器 + 统一对话入口
|
||||
├── Phase III method_consult + ask_user 标准化
|
||||
├── Phase IV THINK + ACT 层工具封装
|
||||
├── Phase V 反思编排 + 高级特性
|
||||
└── Phase VI 集成测试 + 可观测性
|
||||
```
|
||||
|
||||
**关键决策：**
|
||||
- Phase Deploy **必须先于**本计划启动，因为 R 工具数量从 7 扩展到 11 是 method_consult 和 analysis_plan 的基础
|
||||
- Phase Q+（变量字典 + 变量选择面板）**吸收进**本计划 Phase I，因为变量字典是 DataContext 的 Layer 3
|
||||
- QPER 透明化（Pipeline 可观测性）**部分融入**本计划 Phase VI
|
||||
|
||||
### 1.3 核心原则（贯穿全计划）
|
||||
|
||||
| # | 原则 | 约束 |
|
||||
|---|------|------|
|
||||
| 1 | **领域知识可配置化** | 所有 Prompt、决策表、流程模板、工具注册表、叙事模板均由 JSON/数据库驱动，不写死在 TypeScript 中 |
|
||||
| 2 | **QPER 不动** | QPER 四层的底层 Service 保持不变，新工具封装为 Tool 接口调用已有 Service |
|
||||
| 3 | **渐进式改造** | 每个 Phase 独立可交付、可验收，不依赖后续 Phase |
|
||||
| 4 | **安全梯度** | READ 层随时调用，ACT 层需确认，降低 LLM 决策风险 |
|
||||
| 5 | **Token 敏感** | Session 黑板注入 LLM 前做裁剪，R 原始输出不入 LLM |
|
||||
|
||||
---
|
||||
|
||||
## 2. 现有资产盘点
|
||||
|
||||
### 2.1 可直接复用（改造程度：低）
|
||||
|
||||
| 现有组件 | 对应新工具/模块 | 复用方式 |
|
||||
|----------|----------------|---------|
|
||||
| `DataProfileService`（Python） | `get_data_overview` | 封装为 Tool 接口，追加 PICO 推断字段 |
|
||||
| `ClarificationCard`（前端） | `ask_user` | 标准化后端输入/输出接口 |
|
||||
| `WorkflowExecutorService` | `run_step` | 已是傻瓜式执行器，直接封装 |
|
||||
| `ConfigLoader` + Zod Schema | 新工具注册表 | 扩展工具描述字段 |
|
||||
| `SSE 基础设施` | 全链路事件推送 | 扩展事件类型 |
|
||||
| `ssaStore.ts`（Zustand） | 前端状态扩展 | 扩展 DataContext 和意图状态 |
|
||||
|
||||
### 2.2 需要扩展（改造程度：中）
|
||||
|
||||
| 现有组件 | 改造内容 |
|
||||
|----------|---------|
|
||||
| `DataProfileService` | 新增单列查询 API（`get_variable_detail`） |
|
||||
| `DecisionTableService` | 封装为 `method_consult` Tool 接口，追加 LLM 推理补充 |
|
||||
| `FlowTemplateService` + `QueryService` | 合并封装为 `analysis_plan` Tool |
|
||||
| `ReflectionService` | 新增 `interpret` 模式（结果解读） |
|
||||
| `workflow.routes.ts` | 新增统一对话入口 `/api/ssa/chat` |
|
||||
|
||||
### 2.3 需要新建
|
||||
|
||||
| 新组件 | 位置 | 职责 |
|
||||
|--------|------|------|
|
||||
| `SessionBlackboardService` | `backend/services/` | Session 黑板生命周期管理 |
|
||||
| `IntentRouterService` | `backend/services/` | 意图分类（规则 + LLM 混合） |
|
||||
| `ChatService` | `backend/services/` | 非 analyze 意图的 LLM 对话处理 |
|
||||
| `ToolRegistryService` | `backend/services/` | 7 工具注册 + 阶段性可见性控制 |
|
||||
| `tool_definitions.json` | `backend/config/` | 7 工具的 LLM 描述（JSON 驱动） |
|
||||
| `intent_rules.json` | `backend/config/` | 意图识别规则（JSON 驱动） |
|
||||
|
||||
### 2.4 已有违规项（需在开发中修正）
|
||||
|
||||
| 违规 | 位置 | 修正计划 |
|
||||
|------|------|---------|
|
||||
| `AVAILABLE_TOOLS` 硬编码常量 | `WorkflowPlannerService.ts` | Phase IV 中改为读取 `tools_registry.json` |
|
||||
|
||||
---
|
||||
|
||||
## 3. 开发计划总览
|
||||
|
||||
```
|
||||
Phase Deploy（前置，37h / 5.5 天）
|
||||
┌────────────────────────────────────┐
|
||||
│ R 工具补齐 11 个 + 部署上线 │
|
||||
└────────────────┬───────────────────┘
|
||||
│ 完成后启动
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 本计划开发阶段 │
|
||||
│ │
|
||||
│ Phase I ──→ Phase II ────→ Phase III ──→ Phase IV ──→ Phase V │
|
||||
│ Session黑板 对话层LLM核心 方法咨询 THINK+ACT 反思编排 │
|
||||
│ + READ层 + 意图路由器 + ask_user 工具封装 + 高级特性│
|
||||
│ (30h/5天) + 统一对话入口 (20h/3天) (21h/3天) (18h/3天) │
|
||||
│ (35h/5.5天) │
|
||||
│ ──→ Phase VI（集成测试, 10h/2天） │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
|
||||
总工时（不含 Phase Deploy）：134h ≈ 22 天
|
||||
含 Phase Deploy：171h ≈ 27.5 天
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Phase I — Session 黑板 + READ 层（30h / 5 天）
|
||||
|
||||
> **目标：让系统能"看懂数据"并陪用户聊天，即使不能跑分析，用户也能感受到 AI 的价值。**
|
||||
> **产出：** `get_data_overview` + `get_variable_detail` + Session 黑板 + DataContext 前端展示
|
||||
> **吸收：** 原 QPER 计划的 Phase Q+（变量字典 + 变量选择面板，20h）
|
||||
|
||||
### 任务清单
|
||||
|
||||
| # | 任务 | 工时 | 产出 | 依赖 |
|
||||
|---|------|------|------|------|
|
||||
| I-1 | **SessionBlackboardService 设计与实现** | 5h | Session 黑板 CRUD + CacheFactory（Postgres-Only，参见 §16.4）+ sessionId 索引 + TTL 过期 | 无 |
|
||||
| I-2 | **SessionBlackboard 类型定义** | 1.5h | `SessionBlackboard` interface + Zod Schema 校验 | 无 |
|
||||
| I-3 | **get_data_overview 工具实现** | 5h | 封装 DataProfileService + PICO 推断字段 + 写入 Session 黑板 | I-1, I-2 |
|
||||
| I-4 | **get_variable_detail 工具实现** | 4h | DataProfileService 单列查询 API（Python 侧新增）+ Tool 接口 | I-1 |
|
||||
| I-5 | **DataContext 前端状态扩展** | 3h | ssaStore 新增 dataContext 字段 + DataContextCard 组件 | I-3 |
|
||||
| I-6 | **PICO 推断 Prompt 模板** | 2h | `pico_inference_prompt.json` + Few-Shot 示例 + Seed 脚本 | I-3 |
|
||||
| I-7 | **变量字典前端面板** | 4h | VariableDictionaryPanel 组件（AI 推断 + 用户编辑/确认） | I-3, I-5 |
|
||||
| I-8 | **数据上传后自动触发 get_data_overview** | 2h | 上传回调中调用 + SSE 推送 DataContext 就绪事件 | I-3 |
|
||||
| I-9 | **Token 控制策略实现** | 2h | Session 黑板注入 LLM 前的裁剪函数（变量字典裁剪、qperTrace 滑动窗口） | I-1 |
|
||||
| I-10 | **Phase I 联调测试** | 1.5h | 上传数据 → DataContext 自动生成 → 前端展示数据全貌 + 变量字典 | 全部 |
|
||||
|
||||
### 配置化要求
|
||||
|
||||
| 配置项 | 文件 | 方法学团队可编辑 |
|
||||
|--------|------|:---:|
|
||||
| PICO 推断 Prompt | `pico_inference_prompt.json` 或 DB Prompt 表 | ✅ |
|
||||
| 变量类型推断规则 | `variable_inference_rules.json` | ✅ |
|
||||
| Token 裁剪阈值 | `session_config.json`（变量数阈值、滑动窗口大小） | ✅ |
|
||||
|
||||
### 验收标准
|
||||
|
||||
```
|
||||
✅ 上传 CSV 后 3 秒内，前端展示 DataContext 卡片（统计摘要 + PICO 推断 + 变量列表）
|
||||
✅ 点击任意变量 → 展示单变量详情（分布图 + 统计量 + 异常值）
|
||||
✅ PICO 推断标记为 "AI 推断"，用户可编辑确认后标记为 "已确认"
|
||||
✅ 变量字典支持用户修改 label、type、role，修改后写回 Session 黑板
|
||||
✅ Session 黑板数据在同一会话内持久有效，刷新页面后可恢复（CacheFactory，生产环境 Postgres 持久化）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Phase II — 对话层 LLM + 意图路由器 + 统一对话入口（35h / 5.5 天）
|
||||
|
||||
> **目标：构建对话层 LLM 基础设施 + 意图路由，让系统具备多轮连贯对话能力。**
|
||||
> **产出：** 对话层 LLM 核心（System Prompt + 对话历史 + 上下文组装）+ `IntentRouterService` + `/api/ssa/chat` 统一入口 + `ChatService`
|
||||
> **核心认知：对话层 LLM 是系统的大脑和嘴巴（详见《四层七工具实现机制详解》第 1-4 章），不是简单的"调一次 LLM API"。**
|
||||
|
||||
### 任务清单
|
||||
|
||||
| # | 任务 | 工时 | 产出 | 依赖 |
|
||||
|---|------|------|------|------|
|
||||
| **对话层 LLM 基础设施** | | | | |
|
||||
| II-1 | **ConversationService 核心实现** | 5h | 对话层 LLM 的核心服务：System Prompt 动态组装 + DataContext 注入 + 工具输出注入 + LLM 调用 + 流式/完整回复 | Phase I |
|
||||
| II-2 | **对话历史管理** | 3h | 消息历史存储（内存/DB） + 滑动窗口裁剪（根据 Token 预算动态调整窗口大小） + 关键事件摘要压缩 | Phase I |
|
||||
| II-3 | **System Prompt 架构实现** | 4h | 基础角色（固定） + DataContext 注入（动态） + 意图指令（按意图切换） + 工具输出注入（按需） + 分析结果注入（discuss 时） — 六段式动态组装 | II-1 |
|
||||
| II-4 | **System Prompt 模板（全意图）** | 3h | DB Prompt 表：`base_system`（基础角色）+ `chat_instruction` / `explore_instruction` / `consult_instruction` / `analyze_instruction` / `discuss_instruction` / `feedback_instruction`（6 个意图指令段）+ Seed 脚本 | 无 |
|
||||
| **意图路由器** | | | | |
|
||||
| II-5 | **意图识别规则引擎** | 3h | `intent_rules.json` 规则定义 + 规则匹配器（关键词 + 上下文状态） | Phase I |
|
||||
| II-6 | **IntentRouterService 实现** | 4h | 混合路由（规则优先 + LLM 兜底）+ 意图分类输出 | II-5 |
|
||||
| II-7 | **Intent Router Prompt 模板** | 1.5h | `intent_router_prompt.json` + Few-Shot 示例 + Seed 脚本 | 无 |
|
||||
| **统一对话入口 + 基础意图处理** | | | | |
|
||||
| II-8 | **统一对话 API `/api/ssa/chat`** | 3h | 新路由：接收消息 → IntentRouter 分类 → ConversationService 组装上下文 → 分发到对应 Handler → 对话层 LLM 生成回复 | II-1, II-6 |
|
||||
| II-9 | **ChatService — chat 意图处理** | 2h | ConversationService(DataContext) → 对话层 LLM 直接回复 | II-8 |
|
||||
| II-10 | **ChatService — explore 意图处理** | 2.5h | 调用 READ 工具获取数据 → 工具输出注入 ConversationService → 对话层 LLM 生成数据解读 | II-8 |
|
||||
| II-11 | **前端对话入口统一** | 2h | SSAChatPane 消息统一走 `/api/ssa/chat`，按意图渲染不同回复类型 | II-8 |
|
||||
| II-12 | **Phase II 联调测试** | 2h | 多轮对话连贯性验证 + 各意图场景验证 + 降级验证（LLM 不可用时规则兜底） | 全部 |
|
||||
|
||||
### 意图分发逻辑
|
||||
|
||||
```
|
||||
/api/ssa/chat 收到消息
|
||||
→ IntentRouterService.classify(message, sessionContext)
|
||||
→ chat → ChatService.handleChat() → 直接 LLM 回复
|
||||
→ explore → ChatService.handleExplore() → DataProfile + LLM 解读
|
||||
→ consult → Phase III: method_consult 路径
|
||||
→ analyze → 转发到现有 /api/ssa/workflow/plan（QPER 入口）
|
||||
→ discuss → Phase V: write_report(interpret) 路径
|
||||
→ feedback → Phase V: 反思编排路径
|
||||
```
|
||||
|
||||
### ConversationService 核心架构
|
||||
|
||||
```
|
||||
每次对话请求的处理流程：
|
||||
|
||||
用户消息
|
||||
→ IntentRouterService.classify() → 意图分类
|
||||
→ ConversationService.buildContext():
|
||||
├── 加载 base_system Prompt（固定角色）
|
||||
├── 注入 DataContext（从 Session 黑板，带 Token 裁剪）
|
||||
├── 注入意图指令段（按 intent 选择对应 Prompt 段）
|
||||
├── 注入工具输出（如有工具调用，结构化 JSON 作为上下文）
|
||||
├── 注入分析结果（discuss/feedback 时，从 Session 黑板取 stepResults 摘要）
|
||||
└── 加载对话历史（滑动窗口，5-10 轮）
|
||||
→ LLM.call(assembledPrompt)
|
||||
→ 回复返回前端 + 消息存入对话历史
|
||||
```
|
||||
|
||||
### 配置化要求
|
||||
|
||||
| 配置项 | 文件 | 方法学团队可编辑 |
|
||||
|--------|------|:---:|
|
||||
| 意图识别规则（关键词 + 上下文条件） | `intent_rules.json` | ✅ |
|
||||
| Intent Router Prompt | `intent_router_prompt.json` 或 DB Prompt 表 | ✅ |
|
||||
| 基础角色 System Prompt | DB Prompt 表 `base_system` | ✅ |
|
||||
| 6 个意图指令段 | DB Prompt 表 `chat_instruction` / `explore_instruction` / `consult_instruction` / `analyze_instruction` / `discuss_instruction` / `feedback_instruction` | ✅ |
|
||||
| 意图→可见工具映射 | `intent_tool_visibility.json` | ✅ |
|
||||
| 对话历史窗口配置 | `session_config.json`（窗口大小、Token 上限） | IT 团队 |
|
||||
|
||||
### 验收标准
|
||||
|
||||
```
|
||||
✅ "这个数据有多少样本？" → 识别为 chat → 对话层 LLM 带 DataContext 直接回复
|
||||
✅ "帮我看看各组的样本分布" → 识别为 explore → 工具输出注入 → 对话层 LLM 生成数据解读
|
||||
✅ "对 BMI 和血压做相关分析" → 识别为 analyze → 转入 QPER 流水线
|
||||
✅ LLM 不可用时 → 规则引擎兜底 → 正确识别明确意图
|
||||
✅ 无法判断时 → 默认 chat（最安全的兜底）
|
||||
✅ 多轮对话连贯性：用户说"刚才那个变量" → LLM 从对话历史正确解析为 BMI
|
||||
✅ 意图切换衔接：consult → analyze 时，LLM 自然衔接"好的，我来按之前讨论的方案执行"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Phase III — method_consult + ask_user 标准化（20h / 3 天）
|
||||
|
||||
> **目标：系统能给用户推荐分析方法（不执行），并在不确定时主动提问。**
|
||||
> **产出：** `method_consult` 工具 + `ask_user` 标准化接口 + consult 意图处理
|
||||
|
||||
### 任务清单
|
||||
|
||||
| # | 任务 | 工时 | 产出 | 依赖 |
|
||||
|---|------|------|------|------|
|
||||
| III-1 | **method_consult Tool 实现** | 5h | 封装 DecisionTableService 四维匹配 + LLM 推理补充 + 返回推荐/替代/前提 | Phase I |
|
||||
| III-2 | **method_consult Prompt 模板** | 2h | `method_consult_prompt.json` + 方法推荐 Few-Shot | 无 |
|
||||
| III-3 | **ask_user 后端接口标准化** | 4h | 统一输入/输出 Schema + 请求-响应模式（Node.js 生成卡片 → 前端渲染 → 用户选择 → 恢复流程） | Phase I |
|
||||
| III-4 | **ask_user 前端组件增强** | 3h | ClarificationCard 升级：支持单选/多选/自由文本、上下文说明、标准化样式 | III-3 |
|
||||
| III-5 | **consult 意图处理（对话层 LLM 集成）** | 3h | method_consult 返回匹配结果 → 注入 ConversationService → 对话层 LLM 生成完整方法推荐（理由+前提+替代） → ask_user 确认 → 可转入 analyze | III-1, III-3, Phase II |
|
||||
| III-6 | **ToolRegistryService 骨架** | 2h | 7 工具注册表 + `tool_definitions.json` + 阶段性可见性查询 API | 无 |
|
||||
| III-7 | **Phase III 联调测试** | 1h | consult 场景端到端 + ask_user 确认流程 | 全部 |
|
||||
|
||||
### 配置化要求
|
||||
|
||||
| 配置项 | 文件 | 方法学团队可编辑 |
|
||||
|--------|------|:---:|
|
||||
| 方法推荐 Prompt | `method_consult_prompt.json` 或 DB Prompt 表 | ✅ |
|
||||
| 工具定义（名称、描述、层级、参数） | `tool_definitions.json` | ✅ |
|
||||
| 意图→工具可见性映射 | `intent_tool_visibility.json` | ✅ |
|
||||
|
||||
### 验收标准
|
||||
|
||||
```
|
||||
✅ "我想比较两组差异，应该用什么方法？" → method_consult → 推荐 T 检验 + 理由 + 前提 + 替代方案
|
||||
✅ method_consult 输出不触发执行，用户确认后才转入 analyze
|
||||
✅ ask_user 渲染为标准化选择卡片（单选/多选/自由文本）
|
||||
✅ PICO 确认流程：get_data_overview → LLM 推断 → ask_user 确认 → 写入 Session 黑板
|
||||
✅ 工具注册表可通过热更新 API 重载
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Phase IV — THINK + ACT 层工具封装（21h / 3 天）
|
||||
|
||||
> **目标：将已有 QPER 底层 Service 封装为标准 Tool 接口，挂载到新工具体系上。**
|
||||
> **产出：** `analysis_plan` + `run_step` + `write_report`(generate) 工具封装 + AVAILABLE_TOOLS 配置化修正
|
||||
|
||||
### 任务清单
|
||||
|
||||
| # | 任务 | 工时 | 产出 | 依赖 |
|
||||
|---|------|------|------|------|
|
||||
| IV-1 | **analysis_plan Tool 封装** | 4h | 封装 Q 层参数提取 + P 层 FlowTemplate 填充 → 输出有序步骤列表 | Phase I, Phase III |
|
||||
| IV-2 | **run_step Tool 封装** | 3h | 封装 WorkflowExecutorService + data_source 自动注入（从 Session 黑板取 dataOssKey） | Phase I |
|
||||
| IV-3 | **write_report Tool 封装（generate 模式）** | 3h | 封装 ReflectionService → 论文级报告生成 | Phase I |
|
||||
| IV-4 | **analyze 意图完整链路对接（对话层 LLM 集成）** | 4h | IntentRouter(analyze) → analysis_plan → 对话层 LLM 生成方案说明 → ask_user(确认方案) → run_step ×N（每步对话层 LLM 播报进展） → write_report → 对话层 LLM 生成总结 | IV-1, IV-2, IV-3, Phase II |
|
||||
| IV-5 | **AVAILABLE_TOOLS 配置化修正** | 2h | WorkflowPlannerService 中的硬编码常量改为读取 tools_registry.json | 无 |
|
||||
| IV-6 | **阶段性工具可见性实现** | 2h | ToolRegistryService 根据当前意图/阶段过滤可用工具列表，注入 LLM 上下文 | III-6 |
|
||||
| IV-7 | **analysis_plan 前端审查面板** | 2h | 展示分析方案 → 用户确认/修改 → 确认后触发执行 | IV-1, IV-4 |
|
||||
| IV-8 | **Phase IV 联调测试** | 1h | analyze 意图完整旅程验证 | 全部 |
|
||||
|
||||
### data_source 自动注入流程
|
||||
|
||||
```
|
||||
run_step 被调用
|
||||
→ ToolOrchestrator 拦截
|
||||
→ 从 SessionBlackboard 取出 dataOssKey
|
||||
→ 生成预签名 URL
|
||||
→ 注入 params.data_source = { type: 'oss', oss_url: signedUrl }
|
||||
→ POST 给 R 服务
|
||||
→ LLM 和 analysis_plan 全程不感知 data_source
|
||||
```
|
||||
|
||||
> 注：`WorkflowExecutorService.resolveDataSource()` 已有此逻辑，run_step 封装时直接复用。
|
||||
|
||||
### 验收标准
|
||||
|
||||
```
|
||||
✅ "对 BMI 和血压做相关分析" → analyze → analysis_plan → 用户确认 → run_step → write_report
|
||||
✅ analysis_plan 输出确定的 tool_code + params，run_step 傻瓜式转发
|
||||
✅ data_source 由 Session 黑板自动注入，LLM 上下文中不出现文件路径
|
||||
✅ WorkflowPlannerService.AVAILABLE_TOOLS 读取 JSON，不再硬编码
|
||||
✅ 不同阶段 LLM 看到的工具列表不同（数据探索阶段看不到 run_step）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Phase V — 反思编排 + 高级特性（18h / 3 天）
|
||||
|
||||
> **目标：系统具备自修复能力和结果深度解读能力。**
|
||||
> **产出：** 双轨反思机制 + write_report(interpret) + discuss 意图处理 + feedback 意图处理
|
||||
|
||||
### 任务清单
|
||||
|
||||
| # | 任务 | 工时 | 产出 | 依赖 |
|
||||
|---|------|------|------|------|
|
||||
| V-1 | **错误分类器实现** | 3h | run_step 返回 error → 分类为"可自愈"(参数级) 或"不可自愈"(方法级) | Phase IV |
|
||||
| V-2 | **自动反思（静默重试）** | 3h | 可自愈错误 → 注入错误日志 + DataContext → LLM 修正参数 → 重试（MAX 2 次） | V-1 |
|
||||
| V-3 | **手动反思（用户驱动）** | 3h | feedback 意图 → 注入完整 qperTrace → LLM 分析 → 新 analysis_plan → 重新执行 | V-1, Phase IV |
|
||||
| V-4 | **write_report interpret 模式** | 3h | ReflectionService 扩展：接收用户问题 + 已有结果 → LLM 深度解读 | Phase IV |
|
||||
| V-5 | **discuss 意图处理（对话层 LLM 集成）** | 2h | 检测最近有分析结果 → 分析结果注入 ConversationService → 对话层 LLM 深度解读 | V-4, Phase II |
|
||||
| V-6 | **反思 Prompt 模板** | 2h | `reflection_prompt.json`（自动修正 + 手动反思两套 Prompt） | 无 |
|
||||
| V-7 | **Phase V 联调测试** | 2h | 自动重试场景 + 用户不满意场景 + 结果解读场景 | 全部 |
|
||||
|
||||
### 双轨反思流程
|
||||
|
||||
```
|
||||
触发路径 1 — 自动（用户无感知）：
|
||||
run_step → error("Column 'BP' not found")
|
||||
→ 错误分类器 → 可自愈（列名拼写）
|
||||
→ 注入 {error, dataOverview.columns} → LLM 修正 → 重试
|
||||
→ 成功 → 用户看到正常结果
|
||||
|
||||
触发路径 2 — 手动（用户驱动）：
|
||||
用户: "结果不对，p 值不应该这么大"
|
||||
→ IntentRouter → feedback
|
||||
→ 注入 qperTrace(最近 3 条，摘要压缩) → LLM 分析原因
|
||||
→ ask_user("建议：1)换非参数 2)排除极值 3)合并亚组")
|
||||
→ 用户选择 → 新 analysis_plan → run_step → write_report
|
||||
```
|
||||
|
||||
### 配置化要求
|
||||
|
||||
| 配置项 | 文件 | 方法学团队可编辑 |
|
||||
|--------|------|:---:|
|
||||
| 错误分类映射（R 报错关键词 → 分类） | `error_classification.json` | ✅ |
|
||||
| 自动修正 Prompt | `auto_fix_prompt.json` 或 DB Prompt 表 | ✅ |
|
||||
| 手动反思 Prompt | `manual_reflection_prompt.json` 或 DB Prompt 表 | ✅ |
|
||||
| 结果解读 Prompt | `interpret_prompt.json` 或 DB Prompt 表 | ✅ |
|
||||
|
||||
### 验收标准
|
||||
|
||||
```
|
||||
✅ run_step 列名错误 → 自动修正并重试 → 用户无感知看到正常结果
|
||||
✅ 超过 2 次重试 → 停止重试 → 报告用户并建议替代方案
|
||||
✅ 用户说"结果不对" → feedback 意图 → 注入 QPER 记录 → 新方案 → 重新执行
|
||||
✅ 用户说"p 值说明什么" → discuss 意图 → 带分析结果的深度解读
|
||||
✅ interpret 模式不重新跑分析，只解读已有结果
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Phase VI — 集成测试 + 可观测性（10h / 2 天）
|
||||
|
||||
> **目标：全链路验证 + 开发者调试支持 + 文档更新。**
|
||||
> **产出：** 端到端测试脚本 + QPER 透明化面板 + 文档更新
|
||||
|
||||
### 任务清单
|
||||
|
||||
| # | 任务 | 工时 | 产出 | 依赖 |
|
||||
|---|------|------|------|------|
|
||||
| VI-1 | **端到端测试脚本** | 3h | 覆盖 6 种意图的自动化测试 + 7 工具调用链验证 | Phase V |
|
||||
| VI-2 | **QPER + Tool 可观测性面板** | 4h | 开发者面板：意图分类日志、工具调用链、Session 黑板状态、LLM Prompt/Response 可查看 | Phase V |
|
||||
| VI-3 | **文档更新** | 2h | 更新模块状态文档 + README + API 文档 | Phase V |
|
||||
| VI-4 | **回归测试** | 1h | 确认原有 QPER 流程未被破坏 | 全部 |
|
||||
|
||||
### 验收标准
|
||||
|
||||
```
|
||||
✅ 6 种意图场景全部自动化验证通过
|
||||
✅ 7 个工具调用链（典型调用链场景 1-5）端到端通过
|
||||
✅ 开发者面板可查看：IntentRouter 分类结果 + 工具调用序列 + Session 黑板快照
|
||||
✅ 原有 QPER 直接调用路径（/api/ssa/workflow/plan）仍然可用
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 工时与里程碑
|
||||
|
||||
### 10.1 工时汇总
|
||||
|
||||
| Phase | 名称 | 工时 | 日历天 | 里程碑 | v1.1 变更 |
|
||||
|-------|------|------|--------|--------|----------|
|
||||
| **前置** | **Phase Deploy（R 工具补齐）** | **37h** | **5.5 天** | R 工具 7→11，生产环境可用 | 不变 |
|
||||
| **I** | **Session 黑板 + READ 层** | **30h** | **5 天** | 系统能看懂数据 | 不变 |
|
||||
| **II** | **对话层 LLM + 意图路由器 + 统一对话入口** | **35h** | **5.5 天** | 系统能连贯对话 + 区分意图 | **+11h**：新增 ConversationService(5h) + 对话历史管理(3h) + System Prompt 架构(4h) + 全意图 Prompt 模板(3h)；chat/explore 工时因依赖 ConversationService 而减少 |
|
||||
| **III** | **method_consult + ask_user** | **20h** | **3 天** | 系统能推荐方法、主动提问 | 不变（consult 对话层集成已含在 III-5） |
|
||||
| **IV** | **THINK + ACT 工具封装** | **21h** | **3 天** | 新工具体系挂载 QPER | **+1h**：IV-4 analyze 链路增加对话层 LLM 进展播报 |
|
||||
| **V** | **反思编排 + 高级特性** | **18h** | **3 天** | 自修复 + 结果解读 | 不变 |
|
||||
| **VI** | **集成测试 + 可观测性** | **10h** | **2 天** | 全链路验证 + 开发者调试 | 不变 |
|
||||
| | **本计划合计** | **134h** | **~22 天** | **智能对话 + 工具体系上线** | **+12h** |
|
||||
| | **含 Phase Deploy 总计** | **171h** | **~27.5 天** | **完整系统升级** | **+12h** |
|
||||
|
||||
### 10.2 里程碑时间线
|
||||
|
||||
```
|
||||
Week 1 ──────────────────────────────────
|
||||
Day 1-5.5: Phase Deploy（R 工具补齐 + 部署）
|
||||
✅ 里程碑 0：R 工具 11 个全部上线
|
||||
|
||||
Week 2 ──────────────────────────────────
|
||||
Day 6-10: Phase I（Session 黑板 + READ 层 + DataContext 前端）
|
||||
✅ 里程碑 1：数据上传后展示 DataContext 全貌 + 变量字典
|
||||
|
||||
Week 3 ──────────────────────────────────
|
||||
Day 11-15.5: Phase II（对话层 LLM 基础设施 + 意图路由器 + chat/explore）
|
||||
✅ 里程碑 2A：多轮连贯对话能力上线（对话层 LLM + System Prompt + 对话历史）
|
||||
|
||||
Week 4 ──────────────────────────────────
|
||||
Day 16-18: Phase III（method_consult + ask_user 标准化）
|
||||
Day 19-21: Phase IV（THINK + ACT 工具封装 + analyze 完整链路）
|
||||
✅ 里程碑 2B：系统能区分 6 种意图，支持自由对话 + 方法咨询 + 完整分析链路
|
||||
|
||||
Week 5 ──────────────────────────────────
|
||||
Day 22-24: Phase V（反思编排 + discuss + feedback）
|
||||
✅ 里程碑 3：7 工具 + 4 层架构 + 对话层 LLM 完整上线
|
||||
|
||||
Week 5-6 ──────────────────────────────
|
||||
Day 25-26: Phase VI（集成测试 + 可观测性 + 文档）
|
||||
✅ 里程碑 4：全系统验收完成
|
||||
|
||||
Week 6 后 ──────────────────────────────
|
||||
收集用户反馈，评估意图识别准确率 + 对话连贯性
|
||||
评估是否需要 RAG 增强 method_consult
|
||||
评估 LLM Function Calling 模式预研（Phase 4+ 方向）
|
||||
```
|
||||
|
||||
### 10.3 里程碑验收条件
|
||||
|
||||
| 里程碑 | 核心验收 | 用户可感知变化 |
|
||||
|--------|---------|---------------|
|
||||
| **M0** | 11 个 R 工具全部通过单元测试 | 更多分析类型可用 |
|
||||
| **M1** | 上传数据 → 自动展示数据全貌 + PICO 推断 + 变量字典 | "系统读懂了我的数据" |
|
||||
| **M2A** | 多轮对话连贯 + 对话层 LLM System Prompt 完整 + 意图识别准确 | "像和一个记住之前聊过什么的统计专家对话" |
|
||||
| **M2B** | 自由对话 + 数据探索 + 方法咨询 + 主动提问 + 完整分析链路 | "全流程 AI 陪伴" |
|
||||
| **M3** | 完整分析旅程：探索→咨询→确认→执行→报告→解读→反思 | "结果不满意可以反思重来" |
|
||||
| **M4** | 自动化测试通过 + 开发者面板可用 + 文档齐全 | 团队可维护和扩展 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 新增配置文件清单
|
||||
|
||||
> **约束：一切业务逻辑靠读 JSON/数据库驱动，绝不写死在 TypeScript 的 if-else 和常量对象中。**
|
||||
|
||||
### 11.1 新增 JSON 配置文件
|
||||
|
||||
| 文件 | 位置 | 用途 | Owner | Phase |
|
||||
|------|------|------|-------|-------|
|
||||
| `tool_definitions.json` | `backend/config/` | 7 工具的 LLM 描述（名称、参数 Schema、触发说明） | 方法学团队 | III |
|
||||
| `intent_rules.json` | `backend/config/` | 意图识别规则（关键词、上下文条件、优先级） | 方法学团队 | II |
|
||||
| `intent_tool_visibility.json` | `backend/config/` | 意图→可见工具映射 | 方法学团队 | II |
|
||||
| `session_config.json` | `backend/config/` | Token 控制阈值（变量数裁剪、滑动窗口大小、摘要长度） | IT 团队 | I |
|
||||
| `error_classification.json` | `backend/config/` | R 报错关键词→错误分类映射 | 方法学团队 | V |
|
||||
| `variable_inference_rules.json` | `backend/config/` | 变量类型/角色推断规则（列名模式、数据特征） | 方法学团队 | I |
|
||||
|
||||
### 11.2 新增/更新 Prompt 模板（DB 管理）
|
||||
|
||||
| Prompt | 用途 | Seed 脚本 | Phase |
|
||||
|--------|------|-----------|-------|
|
||||
| `pico_inference` | PICO 推断 | `seed-ssa-pico-prompt.ts` | I |
|
||||
| `intent_router` | 意图分类 | `seed-ssa-intent-router-prompt.ts` | II |
|
||||
| `base_system` | 对话层 LLM 基础角色（固定段） | `seed-ssa-conversation-prompts.ts` | II |
|
||||
| `chat_instruction` | chat 意图指令段 | `seed-ssa-conversation-prompts.ts` | II |
|
||||
| `explore_instruction` | explore 意图指令段 | `seed-ssa-conversation-prompts.ts` | II |
|
||||
| `consult_instruction` | consult 意图指令段 | `seed-ssa-conversation-prompts.ts` | II |
|
||||
| `analyze_instruction` | analyze 意图指令段 | `seed-ssa-conversation-prompts.ts` | II |
|
||||
| `discuss_instruction` | discuss 意图指令段 | `seed-ssa-conversation-prompts.ts` | II |
|
||||
| `feedback_instruction` | feedback 意图指令段 | `seed-ssa-conversation-prompts.ts` | II |
|
||||
| `method_consult` | 方法推荐 | `seed-ssa-method-consult-prompt.ts` | III |
|
||||
| `auto_fix` | 自动错误修正 | `seed-ssa-auto-fix-prompt.ts` | V |
|
||||
| `manual_reflection` | 手动反思 | `seed-ssa-reflection-prompt.ts`（扩展） | V |
|
||||
| `interpret` | 结果解读 | `seed-ssa-interpret-prompt.ts` | V |
|
||||
|
||||
### 11.3 Zod Schema 校验
|
||||
|
||||
每个 JSON 配置文件都必须有对应的 Zod Schema，在 `ConfigLoader.load()` 时严格校验。参考已有的 `config/schemas.ts` 模式扩展。
|
||||
|
||||
---
|
||||
|
||||
## 12. 新增代码目录规划
|
||||
|
||||
```
|
||||
backend/src/modules/ssa/
|
||||
├── services/
|
||||
│ ├── SessionBlackboardService.ts # 🆕 Phase I：Session 黑板管理
|
||||
│ ├── ConversationService.ts # 🆕 Phase II：对话层 LLM 核心（System Prompt 组装 + LLM 调用）
|
||||
│ ├── ConversationHistoryService.ts # 🆕 Phase II：对话历史管理（存储 + 滑动窗口裁剪）
|
||||
│ ├── IntentRouterService.ts # 🆕 Phase II：意图分类
|
||||
│ ├── ChatService.ts # 🆕 Phase II：非 analyze 意图的对话处理（依赖 ConversationService）
|
||||
│ ├── ToolRegistryService.ts # 🆕 Phase III：工具注册 + 阶段性可见性
|
||||
│ ├── ToolOrchestratorService.ts # 🆕 Phase IV：工具编排（data_source 注入等）
|
||||
│ ├── ErrorClassifierService.ts # 🆕 Phase V：错误分类
|
||||
│ ├── QueryService.ts # 已有，不变
|
||||
│ ├── DecisionTableService.ts # 已有，Phase III 封装为 method_consult
|
||||
│ ├── FlowTemplateService.ts # 已有，Phase IV 封装为 analysis_plan 内部
|
||||
│ ├── WorkflowPlannerService.ts # 已有，Phase IV 修正 AVAILABLE_TOOLS
|
||||
│ ├── WorkflowExecutorService.ts # 已有，Phase IV 封装为 run_step
|
||||
│ ├── ReflectionService.ts # 已有，Phase V 新增 interpret 模式
|
||||
│ ├── ConclusionGeneratorService.ts # 已有，不变
|
||||
│ ├── DataProfileService.ts # 已有，Phase I 新增单列查询
|
||||
│ └── DataParserService.ts # 已有，不变
|
||||
├── config/
|
||||
│ ├── ConfigLoader.ts # 已有，扩展加载新配置
|
||||
│ ├── schemas.ts # 已有，扩展新 Schema
|
||||
│ ├── tools_registry.json # 已有（R 工具注册表）
|
||||
│ ├── decision_tables.json # 已有
|
||||
│ ├── flow_templates.json # 已有
|
||||
│ ├── tool_definitions.json # 🆕 Phase III：7 个 Agent 工具定义
|
||||
│ ├── intent_rules.json # 🆕 Phase II：意图识别规则
|
||||
│ ├── intent_tool_visibility.json # 🆕 Phase II：意图→工具映射
|
||||
│ ├── session_config.json # 🆕 Phase I：Token 控制配置
|
||||
│ ├── error_classification.json # 🆕 Phase V：错误分类映射
|
||||
│ └── variable_inference_rules.json # 🆕 Phase I：变量推断规则
|
||||
├── routes/
|
||||
│ ├── chat.routes.ts # 🆕 Phase II：统一对话入口
|
||||
│ ├── workflow.routes.ts # 已有，保持兼容
|
||||
│ ├── config.routes.ts # 已有，扩展热更新范围
|
||||
│ └── ...
|
||||
└── types/
|
||||
├── tool.types.ts # 🆕 Phase I：Tool 接口定义
|
||||
├── session.types.ts # 🆕 Phase I：SessionBlackboard 类型
|
||||
├── intent.types.ts # 🆕 Phase II：意图类型定义
|
||||
├── query.types.ts # 已有
|
||||
└── reflection.types.ts # 已有
|
||||
|
||||
frontend-v2/src/modules/ssa/
|
||||
├── components/
|
||||
│ ├── DataContextCard.tsx # 🆕 Phase I：数据全貌展示卡片
|
||||
│ ├── VariableDictionaryPanel.tsx # 🆕 Phase I：变量字典面板
|
||||
│ ├── AnalysisPlanReview.tsx # 🆕 Phase IV：分析方案审查面板
|
||||
│ ├── DevPanel.tsx # 🆕 Phase VI：开发者调试面板
|
||||
│ ├── ClarificationCard.tsx # 已有，Phase III 标准化增强
|
||||
│ └── ...
|
||||
├── stores/
|
||||
│ └── ssaStore.ts # 已有，Phase I 扩展 dataContext 字段
|
||||
└── types/
|
||||
└── index.ts # 已有，扩展新类型
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. 风险管理
|
||||
|
||||
| 风险 | 概率 | 影响 | 应对 |
|
||||
|------|------|------|------|
|
||||
| 意图识别准确率不足 | 中 | 高 | 混合路由（规则 + LLM）+ 默认兜底为 chat（最安全）；收集误分类日志，持续优化规则 |
|
||||
| Session 黑板内存泄漏 | 中 | 中 | 使用 `CacheFactory`（Postgres-Only，参见 §16.4）+ TTL 过期策略（默认 2h）；监控内存占用 |
|
||||
| Token 成本过高 | 中 | 中 | Token 控制三原则（stepResults 清旧、qperTrace 滑窗、R 原始输出不入 LLM） |
|
||||
| DataContext 注入导致 LLM 上下文过长 | 低 | 中 | 变量字典裁剪策略（≤20 全注入、>20 只注入 confirmed、>50 只注入 PICO 相关） |
|
||||
| 新旧 API 并存导致混乱 | 中 | 低 | `/api/ssa/chat` 为新统一入口；`/api/ssa/workflow/plan` 保留为内部调用；前端统一走新入口 |
|
||||
| Phase Deploy 延期影响本计划启动 | 低 | 高 | Phase I 不依赖 Phase Deploy（只需已有 7 个 R 工具），可并行启动 |
|
||||
| PICO 推断准确率不足 | 中 | 中 | 始终标记为"AI 推断"，必须经 ask_user 确认才生效；错误推断不影响系统可用性 |
|
||||
|
||||
### 回退策略
|
||||
|
||||
| 层级 | 正常路径 | 降级路径 | 触发条件 |
|
||||
|------|---------|---------|---------|
|
||||
| **意图路由** | LLM 分类 | 规则引擎兜底 | LLM 超时/不可用 |
|
||||
| **chat/explore** | LLM(DataContext) 对话 | 返回 DataContext 结构化摘要（无 LLM 解读） | LLM 超时/不可用 |
|
||||
| **method_consult** | 决策表 + LLM 推理 | 仅决策表匹配结果（无 LLM 补充推理） | LLM 超时/不可用 |
|
||||
| **analysis_plan** | 正常规划 | 回退到 WorkflowPlannerService 硬编码逻辑 | 决策表 + 模板均无匹配 |
|
||||
| **反思（自动）** | LLM 修正参数 | 直接报告错误给用户 | 重试 2 次仍失败 |
|
||||
| **Session 黑板** | CacheFactory（Postgres/Memory） | 每次从 DataProfileService 重新生成（慢但可用） | 缓存过期或丢失 |
|
||||
|
||||
---
|
||||
|
||||
## 14. 验收场景总览
|
||||
|
||||
### 场景 1：完整分析旅程（覆盖 7 工具 + 6 意图）
|
||||
|
||||
```
|
||||
用户上传数据
|
||||
→ [自动] get_data_overview → DataContext 卡片展示
|
||||
用户: "这个数据有什么特点？"
|
||||
→ [chat] LLM(DataContext) → "您的数据有 200 行 15 列..."
|
||||
用户: "帮我看看 BMI 这个变量"
|
||||
→ [explore] get_variable_detail("bmi") → 分布图 + 统计量
|
||||
用户: "你觉得结局变量是什么？"
|
||||
→ [explore] LLM 推断 PICO → ask_user 确认 → 写入 Session
|
||||
用户: "我想比较两组差异，应该用什么方法？"
|
||||
→ [consult] method_consult → 推荐 T 检验 + 理由 + 前提
|
||||
用户: "好的，按这个方案执行"
|
||||
→ [analyze] analysis_plan → 用户确认 → run_step ×N → write_report
|
||||
用户: "p 值 0.03 说明什么？"
|
||||
→ [discuss] write_report(interpret) → 深度解读
|
||||
用户: "能不能换个方法试试？"
|
||||
→ [feedback] 反思编排 → 新方案 → 重新执行
|
||||
```
|
||||
|
||||
### 场景 2：纯数据探索（不做分析）
|
||||
|
||||
```
|
||||
用户上传数据 → DataContext 展示
|
||||
用户: "有多少缺失值？" → [chat] 回答
|
||||
用户: "age 的分布？" → [explore] 变量详情
|
||||
用户: "哪些变量可能是混杂因素？" → [chat] LLM 基于 DataContext 推理
|
||||
用户: "谢谢，我先了解这些" → [chat] 结束
|
||||
```
|
||||
|
||||
### 场景 3：LLM 不可用降级
|
||||
|
||||
```
|
||||
用户: "比较两组血压差异"
|
||||
→ IntentRouter LLM 不可用 → 规则引擎识别 "比较" → analyze
|
||||
→ 转入 QPER（Q 层有自己的 LLM 降级到正则）
|
||||
→ 系统功能不中断，退化为 QPER 主线水平
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 15. 与 QPER 主线计划的关系映射
|
||||
|
||||
| QPER 主线计划内容 | 本计划处理方式 | Phase |
|
||||
|-------------------|---------------|-------|
|
||||
| Phase Deploy（R 工具补齐 37h） | **前置条件，先于本计划执行** | 前置 |
|
||||
| Phase Q+（变量字典 + 变量选择面板 20h） | **吸收进 Phase I**（DataContext + 变量字典面板） | I |
|
||||
| QPER 透明化（Pipeline 可观测性） | **部分融入 Phase VI**（开发者面板） | VI |
|
||||
| 核心原则"领域知识可配置化" | **贯穿全计划**，每个 Phase 有配置化要求 | 全部 |
|
||||
| 会话状态机 ExecutionStatus | **扩展**：新增意图路由相关状态 | II |
|
||||
| QPER 级 SSE 事件类型 | **扩展**：新增意图分类、DataContext 就绪等事件 | I, II |
|
||||
| 回退策略表 | **扩展**：新增意图路由、Session 黑板等降级路径 | 全部 |
|
||||
|
||||
---
|
||||
|
||||
## 16. 实现规范与约束（v1.2 新增）
|
||||
|
||||
> **来源：** 架构审查 6 条建议（3 预警 + 3 盲区），经逐条验证和裁定后形成以下实现规范。
|
||||
> **强制性：** ✅ 必须遵守，开发阶段代码审查时检查。
|
||||
> **核心背景：** 平台为 **Postgres-Only** 架构（无 Redis），缓存统一使用 `CacheFactory`（`memory` / `postgres`），参见 `docs/04-开发规范/08-云原生开发规范.md`。
|
||||
|
||||
### 16.1 预警 W1：禁止向对话层 LLM 传递 Function Calling tools 参数
|
||||
|
||||
**状态：** ✅ 完全接受
|
||||
|
||||
**问题：** 如果在调用对话层 LLM 时传入 `tools`（OpenAI Function Calling 格式），LLM 将绕过 Node.js 编排层自行决定调用哪个工具，与 Node.js 集中编排的架构冲突。
|
||||
|
||||
**规范：**
|
||||
|
||||
```typescript
|
||||
// ✅ 正确：Node.js 编排层决定工具调用，LLM 只负责语言生成
|
||||
const response = await llm.chat(messages, {
|
||||
// 不传 tools / function_call 参数
|
||||
});
|
||||
|
||||
// ❌ 禁止：让 LLM 自行决定工具调用
|
||||
const response = await llm.chat(messages, {
|
||||
tools: toolDefinitions, // ← 禁止！
|
||||
tool_choice: 'auto', // ← 禁止！
|
||||
});
|
||||
```
|
||||
|
||||
**影响范围：** `ConversationService`、`ChatService`、所有调用对话层 LLM 的代码
|
||||
**检查时机：** Phase II 代码审查
|
||||
**例外：** `IntentRouterService` 的 LLM 兜底分类可以使用 `response_format: { type: 'json_object' }` 约束输出格式，但不使用 `tools`
|
||||
|
||||
### 16.2 预警 W2：System Prompt 膨胀控制
|
||||
|
||||
**状态：** ⚠️ 接受（需精细化）
|
||||
|
||||
**问题：** 六段式 System Prompt（base_system + DataContext + 意图指令 + 工具输出 + 分析结果 + 对话历史）可能超出 Token 上限，导致 LLM 质量下降或请求失败。
|
||||
|
||||
**规范：**
|
||||
|
||||
| 控制策略 | 阈值（可配置） | 实现位置 |
|
||||
|---------|--------------|---------|
|
||||
| DataContext 裁剪 | 变量 ≤20 全注入；>20 只注入 confirmed；>50 只注入 PICO 相关 | `session_config.json` |
|
||||
| 对话历史滑动窗口 | 默认 5-10 轮（按 Token 预算动态调整，非固定轮数） | `session_config.json` |
|
||||
| 工具输出摘要 | 单次工具输出 ≤500 Token，超出自动截取 top-N 关键字段 | `session_config.json` |
|
||||
| 分析结果注入 | 仅 discuss/feedback 时注入，且只取 stepResults 摘要（不含 R 原始输出） | 硬规则 |
|
||||
| **总 Token 预算** | System Prompt ≤ 4000 Token（可配置上限），超出按优先级裁剪：对话历史 > 工具输出 > DataContext | `session_config.json` |
|
||||
| **位置优化** | 关键指令放在 System Prompt 开头和结尾（LLM 注意力 U 型分布） | `ConversationService` |
|
||||
|
||||
**配置项扩展（`session_config.json`）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"systemPromptTokenBudget": 4000,
|
||||
"dataContextTruncation": {
|
||||
"fullInjectThreshold": 20,
|
||||
"confirmedOnlyThreshold": 50
|
||||
},
|
||||
"conversationWindowSize": { "min": 3, "max": 10 },
|
||||
"toolOutputMaxTokens": 500,
|
||||
"truncationPriority": ["conversationHistory", "toolOutput", "dataContext"]
|
||||
}
|
||||
```
|
||||
|
||||
**影响范围：** `ConversationService.buildContext()`、`session_config.json`
|
||||
**检查时机：** Phase II 任务 II-3（System Prompt 架构实现）
|
||||
|
||||
### 16.3 预警 W3：对话层 LLM 必须使用流式输出
|
||||
|
||||
**状态：** ✅ 完全接受
|
||||
|
||||
**问题：** 对话层 LLM 的回复可能较长（方法推荐、结果解读等场景），非流式模式下用户等待 5-15 秒无反馈，体验差。
|
||||
|
||||
**规范：**
|
||||
|
||||
- `ConversationService` 默认使用 `LLMAdapter.chatStream()` 而非 `chat()`
|
||||
- 通过现有 SSE 基础设施实时推送 LLM 输出 chunk 到前端
|
||||
- 前端 `SSAChatPane` 使用已有的 `AIStreamChat` 组件渲染流式回复
|
||||
|
||||
**实现要点：**
|
||||
|
||||
```typescript
|
||||
// ConversationService 核心调用方式
|
||||
async *generateReply(context: ConversationContext): AsyncGenerator<StreamChunk> {
|
||||
const messages = this.buildMessages(context);
|
||||
yield* this.llmAdapter.chatStream(messages, { /* options */ });
|
||||
}
|
||||
```
|
||||
|
||||
**平台支持：** `LLMAdapter.chatStream()` 已就绪（`backend/src/common/llm/adapters/types.ts`），前端 `AIStreamChat` 已支持流式渲染。
|
||||
**影响范围：** `ConversationService`、`ChatService`、前端 `SSAChatPane`
|
||||
**检查时机：** Phase II 任务 II-1（ConversationService 核心实现）
|
||||
|
||||
### 16.4 盲区 B1：Session 黑板必须使用 Postgres 缓存（Postgres-Only 架构）
|
||||
|
||||
**状态：** ⚠️ 部分接受（修正：无 Redis，使用 Postgres）
|
||||
|
||||
**问题：** Session 黑板如果使用纯内存 `Map` 存储，多实例部署时数据不共享，容器重启后丢失。
|
||||
|
||||
**重要修正：** 平台为 **Postgres-Only** 架构（参见 `docs/04-开发规范/08-云原生开发规范.md`），**无 Redis**。缓存统一通过 `CacheFactory` 管理，支持 `memory`（本地开发）和 `postgres`（生产环境）。
|
||||
|
||||
**规范：**
|
||||
|
||||
```typescript
|
||||
// ✅ 正确：使用平台 CacheFactory（遵循云原生开发规范）
|
||||
import { CacheFactory } from '@/common/cache/CacheFactory';
|
||||
|
||||
export class SessionBlackboardService {
|
||||
private cache = CacheFactory.getInstance(); // 自动选择 memory / postgres
|
||||
|
||||
async get(sessionId: string): Promise<SessionBlackboard | null> {
|
||||
return this.cache.get(`ssa:session:${sessionId}`);
|
||||
}
|
||||
|
||||
async set(sessionId: string, data: SessionBlackboard, ttl?: number): Promise<void> {
|
||||
await this.cache.set(`ssa:session:${sessionId}`, data, ttl ?? 7200); // 默认 2h TTL
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ 禁止：自建内存 Map（违反云原生规范 §2 "内存缓存 ❌"）
|
||||
const sessionCache = new Map<string, SessionBlackboard>(); // ← 禁止！
|
||||
```
|
||||
|
||||
**环境切换：**
|
||||
|
||||
| 环境 | `CACHE_TYPE` | 实际存储 |
|
||||
|------|-------------|---------|
|
||||
| 本地开发 | `memory`（默认） | 内存 Map，单实例足够 |
|
||||
| 生产部署 | `postgres` | `platform_schema.app_cache` 表 |
|
||||
|
||||
**注意：** 无需新建任务，Phase I 任务 I-1（SessionBlackboardService 设计与实现）按此规范使用 `CacheFactory` 即可。
|
||||
**影响范围：** `SessionBlackboardService`
|
||||
**检查时机：** Phase I 代码审查
|
||||
|
||||
### 16.5 盲区 B2：数据依赖意图必须有上下文守卫
|
||||
|
||||
**状态：** ✅ 完全接受
|
||||
|
||||
**问题：** `explore`、`analyze`、`discuss`、`feedback` 四个意图依赖已上传的数据（DataContext），但用户可能在未上传数据时就发出这些意图的消息（如"帮我分析一下"），此时系统不应崩溃或给出空结果。
|
||||
|
||||
**规范：**
|
||||
|
||||
```typescript
|
||||
// IntentRouterService 中的上下文守卫
|
||||
const DATA_DEPENDENT_INTENTS = ['explore', 'analyze', 'discuss', 'feedback'] as const;
|
||||
|
||||
function applyContextGuard(intent: Intent, session: SessionBlackboard | null): Intent {
|
||||
if (DATA_DEPENDENT_INTENTS.includes(intent) && !session?.dataOverview) {
|
||||
return {
|
||||
type: 'chat',
|
||||
metadata: {
|
||||
guardTriggered: true,
|
||||
originalIntent: intent,
|
||||
guidanceMessage: 'need_data_upload' // 触发引导语
|
||||
}
|
||||
};
|
||||
}
|
||||
return { type: intent };
|
||||
}
|
||||
```
|
||||
|
||||
**用户体验：** 当守卫触发时，对话层 LLM 收到 `guidanceMessage: 'need_data_upload'`，自然回复："您还没有上传数据，上传 CSV/Excel 后我就能帮您分析了。您也可以先问我统计方法相关的问题。"
|
||||
|
||||
**配置化：** 守卫映射（哪些意图需要哪些上下文前置条件）放入 `intent_rules.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"contextGuards": {
|
||||
"explore": { "requires": ["dataOverview"] },
|
||||
"analyze": { "requires": ["dataOverview"] },
|
||||
"discuss": { "requires": ["dataOverview", "latestStepResults"] },
|
||||
"feedback": { "requires": ["dataOverview", "latestStepResults"] }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**影响范围：** `IntentRouterService`、`intent_rules.json`
|
||||
**检查时机：** Phase II 任务 II-6（IntentRouterService 实现）
|
||||
|
||||
### 16.6 盲区 B3：LLM 输出 Zod 动态校验模式扩展
|
||||
|
||||
**状态：** ⚠️ 部分接受（Q 层已有，需扩展到其他 LLM 输出点）
|
||||
|
||||
**问题：** LLM 可能生成不存在的列名、不合法的统计方法等幻觉参数，需要用 Zod 校验拦截。
|
||||
|
||||
**现状：** Q 层 `QueryService` 已有 `createDynamicIntentSchema(validColumns)`，用 `z.enum` 动态校验列名。
|
||||
|
||||
**规范 — 需要新增 Zod 校验的 LLM 输出点：**
|
||||
|
||||
| LLM 输出点 | 校验内容 | Phase |
|
||||
|-----------|---------|-------|
|
||||
| Q 层 `QueryService` | 列名 `z.enum(validColumns)` | ✅ 已有 |
|
||||
| `IntentRouterService` LLM 兜底 | 意图类型 `z.enum(['chat','explore','consult','analyze','discuss','feedback'])` | II |
|
||||
| `method_consult` LLM 补充推理 | 方法名 `z.enum(registeredMethods)` — 从 `decision_tables.json` 动态提取 | III |
|
||||
| `ConversationService`（自动修正）| 修正后的参数列名 `z.enum(validColumns)` | V |
|
||||
|
||||
**不需要 Zod 校验的工具（模板驱动）：**
|
||||
|
||||
| 工具 | 原因 |
|
||||
|-----|------|
|
||||
| `analysis_plan` | 输出来自 `FlowTemplateService` 模板填充，非 LLM 自由生成 |
|
||||
| `run_step` | 参数来自 `analysis_plan` 输出，傻瓜式转发 |
|
||||
| `write_report` | 输出为自然语言报告，无结构化参数需校验 |
|
||||
|
||||
**实现模式：** 复用 Q 层的动态 Schema 工厂模式：
|
||||
|
||||
```typescript
|
||||
// 通用模式：从运行时数据构建 Zod Schema
|
||||
function createDynamicSchema<T>(validValues: T[]) {
|
||||
return z.enum(validValues as [T, ...T[]]);
|
||||
}
|
||||
```
|
||||
|
||||
**影响范围：** `IntentRouterService`、`method_consult` Tool、`ConversationService`（自动修正）
|
||||
**检查时机：** Phase II / III / V 各自代码审查
|
||||
|
||||
---
|
||||
|
||||
## 17. 附录：架构约束速查表
|
||||
|
||||
> **开发时快速参考，无需回查全文。**
|
||||
|
||||
| # | 约束 | 违反后果 | 检查阶段 |
|
||||
|---|------|---------|---------|
|
||||
| C1 | 对话层 LLM **禁止** 传入 `tools` / `function_call` 参数 | LLM 绕过编排层自行调用工具，失控 | Phase II |
|
||||
| C2 | System Prompt 总 Token ≤ 4000（可配置），超出按优先级裁剪 | LLM 注意力稀释，回复质量下降 | Phase II |
|
||||
| C3 | 对话层 LLM 默认使用 `chatStream()` 流式输出 | 用户等待 5-15 秒无反馈，体验差 | Phase II |
|
||||
| C4 | Session 黑板使用 `CacheFactory`（**Postgres-Only**，无 Redis） | 多实例数据不共享 / 违反云原生规范 | Phase I |
|
||||
| C5 | 数据依赖意图（explore/analyze/discuss/feedback）必须有上下文守卫 | 未上传数据时系统崩溃或空结果 | Phase II |
|
||||
| C6 | LLM 输出涉及枚举值（列名、方法名、意图类型）必须 Zod 动态校验 | LLM 幻觉参数导致下游工具失败 | Phase II/III/V |
|
||||
| C7 | **Postgres-Only 架构**：禁止引入 Redis 等外部缓存依赖 | 增加运维复杂度，违反平台规范 | 全 Phase |
|
||||
| C8 | R 原始输出 **不入** LLM 上下文 | Token 浪费，可能触发上下文超限 | Phase IV/V |
|
||||
|
||||
---
|
||||
|
||||
**文档维护者：** SSA 架构团队
|
||||
**创建日期：** 2026-02-21
|
||||
**最后更新：** 2026-02-22（v1.2 — 新增实现规范与约束：6 条审查建议 + Postgres-Only 缓存修正）
|
||||
**下一步行动：**
|
||||
1. Phase Deploy 启动（R 工具补齐，5.5 天）
|
||||
2. Phase Deploy 完成后立即启动 Phase I（Session 黑板 + READ 层）
|
||||
3. Phase I 和 Phase Deploy 可考虑部分并行（Phase I 不依赖新 R 工具）
|
||||
|
||||
### 变更日志
|
||||
|
||||
| 版本 | 日期 | 变更内容 |
|
||||
|------|------|---------|
|
||||
| v1.0 | 2026-02-21 | 初版：6 Phase 开发计划，122h/20 天 |
|
||||
| v1.1 | 2026-02-21 | **新增对话层 LLM 基础设施**：① Phase II 新增 ConversationService 核心实现(5h) + 对话历史管理(3h) + System Prompt 架构实现(4h) + 全意图 Prompt 模板(3h)；② Phase II 名称改为"对话层 LLM + 意图路由器 + 统一对话入口"，24h→35h；③ Phase IV analyze 链路增加对话层 LLM 进展播报(+1h)；④ Prompt 模板清单从 7 个扩展为 13 个（新增 base_system + 6 个意图指令段）；⑤ 新增 ConversationService.ts + ConversationHistoryService.ts；⑥ 总工时 122h→134h，27.5 天含 Deploy |
|
||||
| v1.2 | 2026-02-22 | **新增实现规范与约束（§16-§17）**：① 6 条架构审查建议（3 预警 W1-W3 + 3 盲区 B1-B3）转化为实现规范；② 修正 Session 黑板缓存策略为 Postgres-Only（无 Redis，遵循平台云原生规范）；③ 新增架构约束速查表（8 条 C1-C8）；④ 无新增工时（规范融入已有任务） |
|
||||
Reference in New Issue
Block a user