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>
17 KiB
17 KiB
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 个要素：
- 样本描述（纳入/排除）
- 主要结果（核心统计量 + P 值）
- 效应解读（效应量含义）
- 敏感性分析（结果稳健性）
- 方法学说明（为什么选这个方法）
- 局限性声明（数据处理说明）
- 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 重构 → 阶段 ① 开始执行