HaHafeng
371e1c069c
Implement the full QPER intelligent analysis pipeline: - Phase E+: Block-based standardization for all 7 R tools, DynamicReport renderer, Word export enhancement - Phase Q: LLM intent parsing with dynamic Zod validation against real column names, ClarificationCard component, DataProfile is_id_like tagging - Phase P: ConfigLoader with Zod schema validation and hot-reload API, DecisionTableService (4-dimension matching), FlowTemplateService with EPV protection, PlannedTrace audit output - Phase R: ReflectionService with statistical slot injection, sensitivity analysis conflict rules, ConclusionReport with section reveal animation, conclusion caching API, graceful R error classification End-to-end test: 40/40 passed across two complete analysis scenarios. Co-authored-by: Cursor <cursoragent@cursor.com>
401 lines
17 KiB
Markdown
401 lines
17 KiB
Markdown
# SSA-Pro 智能化差距分析与演进路线图
|
||
|
||
> **文档版本：** v1.0
|
||
> **创建日期：** 2026-02-20
|
||
> **基准文档：** `00-系统设计/SSA-Pro 理想状态与智能化愿景设计.md`
|
||
> **当前状态：** Phase 2A 前端集成完成，多步骤工作流端到端通过
|
||
> **文档目的：** 明确当前系统与理想智能化之间的差距，规划演进路径
|
||
|
||
---
|
||
|
||
## 1. 执行摘要
|
||
|
||
### 核心结论
|
||
|
||
**当前系统已搭好"四肢"（R 执行 + SSE 实时进度 + 前端展示 + Word/R 导出），但缺少"大脑"（LLM 意图理解 + 决策表规划 + 论文级结论生成）。**
|
||
|
||
| 维度 | 当前状态 | 理想状态 | 差距 |
|
||
|------|---------|---------|------|
|
||
| 用户输入 | 用户需了解变量名和分析意图 | 用自然语言描述临床问题即可 | 🔴 大 |
|
||
| 方法选择 | 硬编码 if/else 规则 | 决策表四维匹配 + LLM 兜底 | 🔴 大 |
|
||
| 流程规划 | 从零拼装步骤列表 | 预定义流程模板 + 数据驱动调整 | 🔴 大 |
|
||
| 执行引擎 | 顺序执行，各步独立 | 结果串联 + 护栏降级 + 可中断 | 🟡 中 |
|
||
| 结果输出 | 数值表格 + 基础图表 | 论文级综合结论 + 方法学说明 | 🔴 大 |
|
||
|
||
### 智能化等级评估
|
||
|
||
```
|
||
L1 单方法执行 ████████████████████ 100% ✅ 已完成（2026-02-19）
|
||
L2 智能选方法 ███████░░░░░░░░░░░░░ 35% 🟡 有规则匹配，缺决策表和 LLM
|
||
L3 数据自适应 ████░░░░░░░░░░░░░░░░ 20% 🔴 护栏在 R 内部，未与规划联动
|
||
L4 流程编排 ████████░░░░░░░░░░░░ 40% 🟡 多步骤能跑，缺模板和串联
|
||
L5 论文级输出 ███░░░░░░░░░░░░░░░░░ 15% 🔴 缺 LLM 结论生成
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 五大核心组件差距详析
|
||
|
||
### 2.1 意图理解器 (Intent Parser) — 完成度 20%
|
||
|
||
**理想状态：**
|
||
- LLM 从用户自然语言中提取四维信息：Goal / Y_Type / X_Type / Design
|
||
- 不确定时主动追问澄清（展示选择卡片）
|
||
- 支持模糊输入："有没有效"、"帮我分析一下"
|
||
|
||
**当前实现：**
|
||
- `WorkflowPlannerService.parseUserIntent()` — 正则匹配关键词
|
||
- "相关" → correlation，"影响" → regression，"比较" → comparison
|
||
- 变量名通过正则从用户文本中提取，与 DataProfile 变量列表交叉匹配
|
||
- 变量类型通过 DataProfile 判断（categorical / numeric）
|
||
|
||
**差距明细：**
|
||
|
||
| 能力 | 理想 | 当前 | 状态 |
|
||
|------|------|------|------|
|
||
| Goal 分类 | Difference / Association / Prediction / Description | 关键词硬编码 | 🔴 |
|
||
| Y/X 类型提取 | LLM 自动识别结局变量和自变量 | 正则提取变量名 | 🟡 |
|
||
| Design 识别 | 独立 / 配对 / 重复测量 | 不支持 | 🔴 |
|
||
| 模糊理解 | "有没有效" → 差异比较 | 需要用户说"比较" | 🔴 |
|
||
| 追问澄清 | 展示选择卡片让用户确认 | 不追问，直接猜测 | 🔴 |
|
||
| 多目标识别 | 识别多个分析目标并分拆 | 不支持 | 🔴 |
|
||
|
||
**关键缺失文件/服务：**
|
||
- `IntentParserService`（LLM 驱动的意图解析，替代当前的 `parseUserIntent` 方法）
|
||
- 前端追问卡片组件（当 AI 不确定时展示选项）
|
||
|
||
---
|
||
|
||
### 2.2 数据诊断器 (Data Diagnostician) — 完成度 30%
|
||
|
||
**理想状态：**
|
||
- 独立的"数据体检报告"模块
|
||
- 检测项：正态性、方差齐性、缺失比例、异常值、样本量、分组平衡性
|
||
- 诊断结果直接传递给路径规划器，影响方法选择
|
||
|
||
**当前实现：**
|
||
- Python `DataProfileService`：变量类型推断、缺失率、基本统计量、唯一值
|
||
- R `guardrails.R`：在方法执行时检查正态性（Shapiro-Wilk）和方差齐性（Levene）
|
||
- 前端 `DataProfileCard` + `DataProfileModal`：展示数据概况
|
||
|
||
**差距明细：**
|
||
|
||
| 检测项 | 理想 | 当前 | 状态 |
|
||
|--------|------|------|------|
|
||
| 变量类型推断 | 自动识别 | Python DataProfile ✅ | ✅ |
|
||
| 缺失值统计 | 占比 + 建议处理策略 | 有占比，无处理建议 | 🟡 |
|
||
| 正态性检验 | 独立模块，结果传递给 Planner | R 内部执行，不回传 | 🔴 |
|
||
| 方差齐性 | 独立模块，结果传递给 Planner | R 内部执行，不回传 | 🔴 |
|
||
| 异常值检测 | IQR 方法 + 可视化标注 | 不检测 | 🔴 |
|
||
| 样本量评估 | 功效分析建议 | 不评估 | 🔴 |
|
||
| 分组平衡性 | 各组比例 + 提示不平衡 | 不检测 | 🔴 |
|
||
| 诊断→规划联动 | 自动影响方法选择 | 完全割裂 | 🔴 |
|
||
|
||
**关键问题：**
|
||
- 数据诊断（Python DataProfile）和统计前提检查（R guardrails）是两个独立系统
|
||
- R 护栏在执行时发现正态性不满足时自动降级（如 T→Wilcoxon），但不通知 Planner
|
||
- Planner 做规划时不知道数据特征，全凭变量类型硬编码选方法
|
||
|
||
---
|
||
|
||
### 2.3 路径规划器 (Pathway Planner) — 完成度 15%
|
||
|
||
**理想状态：**
|
||
- 决策表匹配：(Goal, Y_Type, X_Type, Design) → 精准选工具
|
||
- 流程模板：预定义标准分析流程（如"两组差异比较 = 清洗 → 描述 → 正态检验 → [T/U] → 效应量 → 可视化"）
|
||
- 数据驱动调整：根据诊断结果动态修改流程
|
||
- 生成完整的 SAP（统计分析计划）供用户确认
|
||
|
||
**当前实现：**
|
||
- `WorkflowPlannerService.generateSteps()` — 硬编码 if/else 链
|
||
- 如果 `analysisType === 'comparison'` 且 Y 是连续 → 加 T 检验步骤
|
||
- 总是先加描述性统计步骤
|
||
- 输出 `WorkflowPlan { title, steps[] }` 结构
|
||
|
||
**差距明细：**
|
||
|
||
| 能力 | 理想 | 当前 | 状态 |
|
||
|------|------|------|------|
|
||
| 决策表匹配 | 四维精准匹配 | 硬编码 if/else | 🔴 |
|
||
| 流程模板 | 5-8 个预定义模板 | 无模板概念 | 🔴 |
|
||
| 数据驱动调整 | 诊断结果影响规划 | 不参考诊断结果 | 🔴 |
|
||
| SAP 生成 | 结构化计划文档 | 简单步骤列表 | 🔴 |
|
||
| 敏感性分析 | 自动添加补充分析 | 不支持 | 🔴 |
|
||
| 效应量步骤 | 自动包含 | 不支持 | 🔴 |
|
||
| 可视化步骤 | 自动规划图表 | 不支持（R 内部生成） | 🟡 |
|
||
|
||
**关键缺失文件/服务：**
|
||
- `DecisionTableService` — 决策表加载和四维匹配
|
||
- `FlowTemplateService` — 流程模板管理
|
||
- 决策表 Excel 配置文件
|
||
- 流程模板配置文件
|
||
|
||
---
|
||
|
||
### 2.4 流程执行器 (Workflow Executor) — 完成度 40%
|
||
|
||
**理想状态：**
|
||
- 按 SAP 定义的顺序执行多个方法
|
||
- 上一步输出作为下一步输入（结果串联）
|
||
- 护栏检查失败时自动降级方法
|
||
- 每步实时反馈中间结果
|
||
- 用户可暂停/跳过/取消
|
||
|
||
**当前实现：**
|
||
- `WorkflowExecutorService.executeWorkflow()` — 顺序遍历 steps 数组
|
||
- 每步独立调用 R 服务（通过 `RClientService`）
|
||
- SSE 实时推送 `step_start` / `step_complete` / `workflow_complete`
|
||
- 前端实时展示执行日志和结果（terminal-box + 结果卡片）
|
||
|
||
**差距明细：**
|
||
|
||
| 能力 | 理想 | 当前 | 状态 |
|
||
|------|------|------|------|
|
||
| 顺序执行 | ✅ | ✅ | ✅ |
|
||
| SSE 实时反馈 | ✅ | ✅ | ✅ |
|
||
| 步骤级结果展示 | ✅ | ✅ | ✅ |
|
||
| 结果串联 | 上步输出 → 下步输入 | 各步独立执行 | 🔴 |
|
||
| 护栏降级 | 失败时自动切换方法 | 不支持 | 🔴 |
|
||
| 暂停/跳过/取消 | 用户可控 | 一旦开始无法中断 | 🔴 |
|
||
| 错误恢复 | 某步失败提供重试选项 | 失败则标记 failed | 🟡 |
|
||
| 步骤间数据共享 | 共享清洗后数据集 | 每步重新加载原始数据 | 🔴 |
|
||
|
||
**这是完成度最高的组件**，架构基础已就位，需要补充的是上层能力。
|
||
|
||
---
|
||
|
||
### 2.5 结论生成器 (Conclusion Generator) — 完成度 15%
|
||
|
||
**理想状态：**
|
||
- 论文级综合结论，包含 6 个要素：
|
||
1. 样本描述（纳入/排除）
|
||
2. 主要结果（核心统计量 + P 值）
|
||
3. 效应解读（效应量含义）
|
||
4. 敏感性分析（结果稳健性）
|
||
5. 方法学说明（为什么选这个方法）
|
||
6. 局限性声明（数据处理说明）
|
||
- LLM 生成自然语言结论
|
||
|
||
**当前实现：**
|
||
- `ConclusionGeneratorService` 存在但功能有限
|
||
- 前端展示：统计量数值、P 值、效应量（数字形式）
|
||
- Word 导出：executive_summary + 各步骤统计量表格
|
||
|
||
**差距明细：**
|
||
|
||
| 结论要素 | 理想 | 当前 | 状态 |
|
||
|----------|------|------|------|
|
||
| 样本描述 | "共纳入 186 例，剔除 14 例..." | 无 | 🔴 |
|
||
| 主要结果 | LLM 自然语言描述 | 数字展示（P=0.015） | 🔴 |
|
||
| 效应解读 | "中等程度效应" | 数字展示（r=0.52） | 🔴 |
|
||
| 敏感性分析 | "T 检验得到一致结论" | 不支持 | 🔴 |
|
||
| 方法学说明 | "因不满足正态性..." | 无 | 🔴 |
|
||
| 局限性声明 | 自动生成 | 无 | 🔴 |
|
||
| 多步骤整合 | 综合所有步骤生成报告 | 各步骤独立展示 | 🟡 |
|
||
| 可发表质量 | 直接用于论文 | 需大量人工整理 | 🔴 |
|
||
|
||
**关键缺失：**
|
||
- LLM 结论生成 Prompt（调用 GPT/DeepSeek 生成论文级文字）
|
||
- 结果解读模板（"填空题"式结论模板）
|
||
- 多步骤结果整合逻辑
|
||
|
||
---
|
||
|
||
## 3. 已完成的基础设施（不需要重做）
|
||
|
||
在规划演进路径之前，确认以下基础已就位，无需重复建设：
|
||
|
||
| 基础设施 | 状态 | 说明 |
|
||
|----------|------|------|
|
||
| R 统计引擎 | ✅ | Docker 部署，7 个工具，plumber API |
|
||
| Node.js 后端框架 | ✅ | 路由、Service 架构、SSE |
|
||
| 前端 V11 UI | ✅ | 三栏布局、对话式交互、结果展示 |
|
||
| SSE 实时通信 | ✅ | 前后端消息格式已对齐 |
|
||
| 数据上传 + OSS | ✅ | 文件上传、预签名 URL |
|
||
| Python 数据质量 | ✅ | 变量类型推断、基础统计 |
|
||
| R 代码导出 | ✅ | 多步骤聚合导出 |
|
||
| Word 报告导出 | ✅ | docx 库，多步骤报告 |
|
||
| R 护栏系统 | ✅ | 正态性、方差齐性检查（R 内部） |
|
||
| Block-based 协议 | 📋 | 规范已制定，待实施（2.5 天） |
|
||
|
||
---
|
||
|
||
## 4. 演进路线图
|
||
|
||
### 4.1 推荐路径（按投入产出比排序）
|
||
|
||
```
|
||
当前状态（Phase 2A 完成，L1-L2 之间）
|
||
│
|
||
│ ① LLM 意图理解 + 决策表匹配 (~5天)
|
||
│ - IntentParserService: LLM 提取 Goal/Y/X/Design
|
||
│ - DecisionTableService: 四维 → 工具精准匹配
|
||
│ - 前端追问卡片组件
|
||
▼
|
||
L2 完成: 智能选方法
|
||
│ 「用户不再需要知道 T 检验、卡方检验是什么」
|
||
│
|
||
│ ② 流程模板 + 结果串联 (~3天)
|
||
│ - FlowTemplateService: 5-8 个预定义流程
|
||
│ - 步骤间数据共享机制
|
||
│ - 敏感性分析自动添加
|
||
▼
|
||
L4 完成: 流程编排
|
||
│ 「从单方法跃迁到完整统计分析流程」
|
||
│
|
||
│ ③ LLM 结论生成 (~3天)
|
||
│ - ConclusionService: LLM 综合解读
|
||
│ - 结论模板体系
|
||
│ - 方法学说明自动生成
|
||
▼
|
||
L5 完成: 论文级输出
|
||
│ 「结果可直接复制到论文中」
|
||
│
|
||
│ ④ 数据诊断→规划联动 + 追问机制 (~5天)
|
||
│ - DataDiagnosticService: 异常值/样本量/平衡性
|
||
│ - 诊断结果传递给 Planner
|
||
│ - 护栏结果回传机制
|
||
▼
|
||
L3 完成: 数据自适应
|
||
│ 「系统自动根据数据特征调整方法」
|
||
│
|
||
│ ⑤ 高级交互 (~3天)
|
||
│ - 执行暂停/跳过/取消
|
||
│ - 步骤失败自动降级
|
||
│ - 用户修改 SAP 后重新执行
|
||
▼
|
||
理想状态: 完全智能化统计分析系统
|
||
```
|
||
|
||
### 4.2 各阶段详细任务
|
||
|
||
#### 阶段 ①：LLM 意图理解 + 决策表匹配（~5 天）
|
||
|
||
| 任务 | 层级 | 预估 | 说明 |
|
||
|------|------|------|------|
|
||
| 设计 Intent Prompt | 后端 | 4h | 提取 Goal/Y/X/Design + 置信度 |
|
||
| 实现 IntentParserService | 后端 | 6h | LLM 调用 + 结构化输出 + Zod 校验 |
|
||
| 设计决策表 Excel 模板 | 配置 | 3h | 四维匹配规则 + 10 个工具映射 |
|
||
| 实现 DecisionTableService | 后端 | 6h | Excel 加载 + 四维匹配逻辑 |
|
||
| 重构 WorkflowPlannerService | 后端 | 4h | 集成 Intent + DecisionTable |
|
||
| 前端追问卡片组件 | 前端 | 4h | 当置信度低时展示选项 |
|
||
| 联调测试 | 全栈 | 4h | 多场景测试 |
|
||
|
||
#### 阶段 ②：流程模板 + 结果串联（~3 天）
|
||
|
||
| 任务 | 层级 | 预估 | 说明 |
|
||
|------|------|------|------|
|
||
| 定义 5 个流程模板 | 配置 | 3h | 差异/关联/描述/回归/基线表 |
|
||
| 实现 FlowTemplateService | 后端 | 4h | 模板加载 + 参数填充 |
|
||
| 步骤间数据共享 | 后端+R | 6h | 清洗后数据缓存 + 传递 |
|
||
| 自动添加敏感性分析 | 后端 | 3h | 主要分析 + 替代方法 |
|
||
| 自动添加效应量步骤 | 后端 | 2h | Cohen's d / r |
|
||
| 联调测试 | 全栈 | 4h | 完整流程测试 |
|
||
|
||
#### 阶段 ③：LLM 结论生成（~3 天）
|
||
|
||
| 任务 | 层级 | 预估 | 说明 |
|
||
|------|------|------|------|
|
||
| 设计结论生成 Prompt | 后端 | 4h | 6 要素结论模板 |
|
||
| 实现 ConclusionService | 后端 | 6h | LLM 调用 + 流式输出 |
|
||
| 设计解读模板配置 | 配置 | 3h | 每种工具的"填空题"模板 |
|
||
| 前端论文结论展示 | 前端 | 4h | Markdown 渲染 + 复制 |
|
||
| Word 报告增强 | 前端 | 3h | 纳入论文级结论 |
|
||
| 联调测试 | 全栈 | 3h | |
|
||
|
||
#### 阶段 ④：数据诊断→规划联动（~5 天）
|
||
|
||
| 任务 | 层级 | 预估 | 说明 |
|
||
|------|------|------|------|
|
||
| 实现异常值检测 | Python/R | 4h | IQR 方法 + 可视化标注 |
|
||
| 实现样本量评估 | Python/R | 3h | 功效分析建议 |
|
||
| 实现分组平衡性检测 | Python | 2h | 各组比例 + 提示 |
|
||
| 诊断结果传递给 Planner | 后端 | 4h | DataDiagnosis → PlannerInput |
|
||
| R 护栏结果回传机制 | 后端+R | 6h | 护栏结果影响后续步骤 |
|
||
| 前端诊断报告增强 | 前端 | 4h | 问题列表 + 建议 + 评分 |
|
||
| 前端追问机制 | 前端 | 4h | 不确定时展示选择卡片 |
|
||
| 联调测试 | 全栈 | 4h | |
|
||
|
||
#### 阶段 ⑤：高级交互（~3 天）
|
||
|
||
| 任务 | 层级 | 预估 | 说明 |
|
||
|------|------|------|------|
|
||
| 执行暂停/跳过/取消 | 后端+前端 | 6h | SSE 控制消息 |
|
||
| 步骤失败自动降级 | 后端 | 4h | T 检验失败 → Wilcoxon |
|
||
| SAP 修改后重新执行 | 前端+后端 | 6h | 用户编辑步骤 → 重新规划 |
|
||
| 联调测试 | 全栈 | 4h | |
|
||
|
||
---
|
||
|
||
## 5. 工时与里程碑
|
||
|
||
| 阶段 | 核心目标 | 工时 | 智能等级 |
|
||
|------|---------|------|---------|
|
||
| Block-based 重构 | 结果渲染标准化 | 2.5天 | 基础设施 |
|
||
| ① LLM 意图 + 决策表 | 用户不需要知道方法名 | 5天 | → L2 |
|
||
| ② 流程模板 + 串联 | 从单方法到完整流程 | 3天 | → L4 |
|
||
| ③ LLM 结论生成 | 论文级输出 | 3天 | → L5 |
|
||
| ④ 数据诊断联动 | 全自动方法调整 | 5天 | → L3 |
|
||
| ⑤ 高级交互 | 可中断 + 降级 | 3天 | 完善 |
|
||
| **合计** | **理想状态** | **~21.5天** | **L5** |
|
||
|
||
### 里程碑时间线（预估）
|
||
|
||
```
|
||
2026-02-21 ─── Block-based 重构开始
|
||
2026-02-24 ─── Block-based 完成 ✓ 基础设施就绪
|
||
2026-02-25 ─── 阶段① 开始：LLM 意图 + 决策表
|
||
2026-03-01 ─── 阶段① 完成 ✓ L2 智能选方法
|
||
2026-03-02 ─── 阶段② 开始：流程模板 + 串联
|
||
2026-03-05 ─── 阶段② 完成 ✓ L4 流程编排
|
||
2026-03-06 ─── 阶段③ 开始：LLM 结论生成
|
||
2026-03-10 ─── 阶段③ 完成 ✓ L5 论文级输出
|
||
2026-03-11 ─── 阶段④ 开始：数据诊断联动
|
||
2026-03-17 ─── 阶段④ 完成 ✓ L3 数据自适应
|
||
2026-03-18 ─── 阶段⑤ 开始：高级交互
|
||
2026-03-21 ─── 阶段⑤ 完成 ✓ 理想状态
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 成功标准
|
||
|
||
### 用户体验验证
|
||
|
||
| 测试场景 | 当前表现 | 目标表现 |
|
||
|----------|---------|---------|
|
||
| 用户说"有没有效" | ❌ 无法理解 | ✅ AI 识别为差异比较 |
|
||
| 用户不知道该用什么方法 | ❌ 必须指定 | ✅ AI 自动选择 |
|
||
| 数据不满足正态性 | 🟡 R 内部降级，用户不知 | ✅ 规划时就选非参数方法 |
|
||
| 分析结果 | 🟡 P 值 + 数字 | ✅ "两组差异显著(P<0.001)，中等效应" |
|
||
| 导出报告 | 🟡 需大量整理 | ✅ 可直接用于论文 |
|
||
|
||
### 智能化评分卡
|
||
|
||
| 能力 | 权重 | 当前评分 | 目标评分 |
|
||
|------|------|---------|---------|
|
||
| 意图理解 | 25% | 2/10 | 8/10 |
|
||
| 方法选择 | 20% | 3/10 | 9/10 |
|
||
| 流程规划 | 20% | 2/10 | 8/10 |
|
||
| 执行引擎 | 15% | 6/10 | 9/10 |
|
||
| 结论生成 | 20% | 1/10 | 8/10 |
|
||
| **加权总分** | **100%** | **2.7/10** | **8.4/10** |
|
||
|
||
---
|
||
|
||
## 7. 风险与依赖
|
||
|
||
| 风险 | 概率 | 影响 | 应对策略 |
|
||
|------|------|------|---------|
|
||
| LLM 意图提取准确率不足 | 中 | 高 | 低置信度时追问用户，而非猜测 |
|
||
| 决策表覆盖率不足 | 中 | 中 | RAG 工具检索作为兜底方案 |
|
||
| LLM 结论生成"幻觉" | 中 | 高 | 基于模板+真实数据填充，而非自由生成 |
|
||
| 步骤间数据串联复杂度 | 中 | 中 | 先实现缓存共享，不做复杂依赖图 |
|
||
| 流程模板无法覆盖长尾场景 | 低 | 中 | 预留"自定义流程"入口 |
|
||
|
||
---
|
||
|
||
**文档维护者：** SSA 架构团队
|
||
**最后更新：** 2026-02-20
|
||
**下一步行动：** 确认优先级后，从 Block-based 重构 → 阶段 ① 开始执行
|