Files

HaHafeng 371e1c069c feat(ssa): Complete QPER architecture - Query, Planner, Execute, Reflection layers

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>

2026-02-21 18:15:53 +08:00

6.5 KiB

Raw Blame History

架构与产品委员会综合评估报告：SSA-Pro 人机协同 (HITL) 交互增强与 Phase Q+ 演进规划

文档版本： v2.0 (完整整合版)

创建日期： 2026-02-20

核心裁决： 🌟 极度赞同 (Highly Recommended)。引入“变量字典”与“变量筛选”两大专家协同功能，不仅填补了 AI 临床背景知识的短板，且通过划分为独立的 Phase Q+ 子阶段，完美平衡了“追求极致体验”与“保障核心交付”的矛盾。

第一部分：业务需求评估 (为什么要引入人机协同？)

在纯自动化的 QPER 流程中，AI 缺乏临床先验知识。将选择权和定义权适度交还给医生，是对医学专业性的最大尊重。

💡 增强点一：用户主导的变量选择 (Variable Selection)

业务痛点：医院导出的原始数据往往包含上百列。如果任由 AI 自由发挥，极易把无关变量（如 Patient_ID、病床号）纳入模型，导致多重共线性或过拟合。
协同价值：医生最清楚哪些是核心指标，哪些是干扰项。
UX 设计建议 (穿梭框/卡片交互)：
在 Q 层处理时，弹出“变量筛选控制台”。
🤖 AI: "我已解析您的数据（共 56 个变量）。为了提高准确度，请确认您本次研究关注的核心变量："
- [AI 智能预选] (AI 根据 Prompt 自动勾选最相关的 5 个变量)
- [展开全部列表微调] (用户可手动增删)

💡 增强点二：建立变量说明与数据字典 (Data Dictionary)

业务痛点：临床数据列名极不规范（如 grp 为 1 和 2，AI 根本不知道哪个是治疗组）。
协同价值 (AI-Assisted Codebook)：
坚决避免让用户手动填写 100 列的表单。采用 “AI 先猜，用户微调” 模式：
1. Python DataProfiler 读取数据后，后台静默调用 LLM 猜测变量含义。
2. 弹出 “变量数据字典确认表” 给用户审阅：
  - age -> AI猜: 患者年龄 -> 用户确认 ✅
  - grp -> AI猜: 分组 (1, 2) -> 用户补充 ✍️: 1=新药, 2=安慰剂
3. 这个经过用户确认的字典，将成为后续 Planner 和 Critic 的黄金上下文 (Golden Context)。

第二部分：架构演进决议 (为什么剥离为 Phase Q+ ?)

虽然上述想法极佳，但在项目实施初期，如果将重度前端交互（表格编辑、状态回传）与核心后端 AI 逻辑耦合，会导致严重的单点阻塞。

因此，委员会决议：将这两个人机交互检查点作为独立增强任务，归入 Phase Q+ 阶段。

剥离的战略意义：

解耦后端AI与前端UI的依赖：让后端可以先行打磨 LLM 从自然语言中提取 [Goal, X, Y, Design] 的核心纯逻辑（Phase Q）。
确立 AI 的“智商基线 (Baseline)”：只有先让 AI 在没有任何人类帮助的情况下硬跑，才能摸清意图识别的真实准确率；之后加上 Phase Q+ 的人工辅助，才能量化“人机协同的提升价值”。

第三部分：Phase Q+ 在状态机中的精确占位

在未来的 Phase Q+ 中，这两个人机检查点将像“拦截器（Interceptor）”一样，无缝插入现有的 ExecutionStatus 状态机中。

stateDiagram-v2
[*] --> UPLOADING: 上传文件
UPLOADING --> PROFILING: Python Tool C 探查

%% Phase Q+ 新增节点 1  
PROFILING \--\> DICT\_EDITING: 🆕 (Phase Q+) 拦截  
note right of DICT\_EDITING  
    展示数据字典表格  
    用户编辑含义/纠正类型  
    点击确认后放行  
end note  
  
DICT\_EDITING \--\> PENDING\_INTENT: 放行  
PENDING\_INTENT \--\> PARSING\_INTENT: 用户输入自然语言  
  
%% Phase Q+ 新增节点 2  
PARSING\_INTENT \--\> VARIABLE\_CONFIRMING: 🆕 (Phase Q+) 拦截  
note right of VARIABLE\_CONFIRMING  
    AI 已预选 X/Y 变量  
    展示变量穿梭框面板  
    用户微调纳入排除  
end note  
  
VARIABLE\_CONFIRMING \--\> PLANNING: 放行  
PLANNING \--\> EXECUTING: E 层接管

架构向后兼容性：在 Phase Q+ 开发完成前，系统状态将直接从 PROFILING -> PENDING_INTENT，以及 PARSING_INTENT -> PLANNING 自动流转，底层架构基建完全一致。

第四部分：研发实施路线图 (Revised Roadmap)

基于这个决议，QPER 计划被拆解得更加平滑、颗粒度更细：

阶段	核心任务	性质	验证目标
Phase Q (主线)	IntentParser (意图解析), DataProfiler (自动探查)	后端 + AI 主导	证明 LLM 能盲猜出 Goal, X, Y 槽位。
Phase P (主线)	Planner (决策表匹配)	后端 + 规则主导	证明系统能基于槽位选对 100% 正确的统计工具。
Phase E (主线)	Executor (R 服务执行)	后端 + R 主导	证明 R 引擎能跑通、护栏能拦截。
Phase R (主线)	Reflection (自动报错重试)	后端 + AI 主导	证明系统具备遇到错误自动修改参数的能力。
---	---	---	---
Phase Q+ (增强)	变量字典面板、变量纳入确认卡片	前端体验主导	让 AI 从“可用”变为“好用”，注入临床背景知识。
Phase E+ (增强)	Block-based 动态多区块渲染	前端体验主导	支持多图多表的完美富文本展示。

第五部分：给开发团队的当前实操建议

为了在当前（无 Phase Q+ 的情况下）顺利推进核心 Phase Q 的开发，请后端团队采用以下**“默认放行策略”**：

DataProfiler 接口契约保持不变：
DataProfiler 依然需要输出一个标准的 DataProfile JSON。在目前的 Phase Q 阶段，这个 JSON 直接由后端传给 IntentParser；在未来的 Phase Q+ 阶段，这个 JSON 只是中间先发给前端修改，修改完再发给 IntentParser。
IntentParser 的容错增强：
因为当前没有人类帮 AI 筛选无关变量，Prompt 中必须加强指令：“请自动忽略如 ID、姓名、病床号等明显的非分析变量。”

结语

不要试图让 AI 彻底取代临床医生的判断。最好的系统是用 AI 去做繁琐的计算，而把关键的**“定义权”和“特征选择权”通过优雅的 UI 还给医生。请团队立刻将精力砸向纯逻辑的 Q-P-E-R 主线闭环**。当核心链路通畅的那一天，就是我们从容增加 Phase Q+ 人机协同面板的完美时机！

6.5 KiB Raw Blame History Unescape Escape