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

5.3 KiB

Raw Blame History

SSA-Pro 架构诊断与复合工具扩展方案

文档性质： 架构诊断总结与 Phase Deploy 扩充计划

诊断对象： 经典队列研究分析流程（Table 1, Table 2, Table 3）的实现缺口

核心结论： 🌟 诊断完全正确！ 架构与 AI 均无问题，核心缺口在于缺少“多变量聚合”的复合 R 工具 (Macro-Tool)。采用 gtsummary 填补此缺口，是四两拨千斤的神来之笔。

1. 团队诊断结果复盘与高度认可

团队提出的诊断击中了医疗 AI 统计分析的最核心痛点：“原子工具”与“临床真实工作流”的错位。

我们当前的误区：把 10 个工具全部做成了“验证单一假设”的原子工具（如：只查一个变量的 T 检验）。
临床的真实诉求：“一键出 Table 1”。一张表里包含了 20 个变量的描述、分布检验、T 检验、Wilcoxon、卡方检验，甚至 Fisher 检验。
破局解法：新建复合工具 ST_BASELINE_TABLE，把复杂的循环、判断、拼表工作，全部下沉到 R 引擎内部去完成，释放 LLM 的规划压力。

2. 核心利器：ST_BASELINE_TABLE 的设计与实现

团队提出的用 R 语言的 gtsummary 包来实现表 1 和表 2，是极其专业的选择。gtsummary 是目前全球医学统计界公认的“顶流制表神器”。

2.1 R 端开发要求 (仅需 6-8 小时)

R 开发工程师只需做一层很薄的 Wrapper，gtsummary::tbl_summary() 会自动完成绝大部分工作：

# ST_BASELINE_TABLE 伪代码示例
library(gtsummary)

run_tool <- function(input) {
df <- load_data(input$data_source)

# 核心一行代码：按分组变量 (by) 统计所有传入的分析变量
# gtsummary 会自动判断是连续还是分类，自动选 T检验或卡方
table_obj <- df %>%
select(all_of(c(input$params$group_var, input$params$analyze_vars))) %>%
tbl_summary(by = input$params$group_var, missing = "ifany") %>%
add_p() # 自动执行统计检验并添加 P 值

# 将 gtsummary 对象转换为标准前端 report_blocks
# ...
}

能力覆盖：

✅ 自动处理连续与分类变量。
✅ 自动处理正态与非正态的检验降级。
✅ 自动计算期望频数并切换 Fisher。
✅ 完美对应 表1（基线比较，group_var=暴露因素） 和 表2（单因素筛选，group_var=结局指标）。

3. 规划层 (Planner) 的流程模板升级

基于这个强大的复合工具，我们立刻可以在 flow_templates.json 中配置一个秒杀市面所有竞品的**“队列研究全家桶”**。

"cohort_study_standard": {
"name": "经典队列研究全套分析 (Table 1-3)",
"steps": [
{
"order": 1,
"role": "baseline_table",
"tool": "ST_BASELINE_TABLE",
"name": "表1: 组间基线特征比较",
"params_mapping": {
"group_var": "{{exposure_var}}", // 暴露/分组变量
"analyze_vars": "{{all_covariates}}"
}
},
{
"order": 2,
"role": "univariate_screen",
"tool": "ST_BASELINE_TABLE",
"name": "表2: 结局指标单因素分析",
"params_mapping": {
"group_var": "{{outcome_var}}", // 结局变量
"analyze_vars": "{{all_covariates}}"
}
},
{
"order": 3,
"role": "multivariate_reg",
"tool": "ST_LOGISTIC_BINARY",
"name": "表3: 结局多因素 Logistic 回归",
"params_mapping": {
"outcome_var": "{{outcome_var}}",
"predictors": "{{exposure_var}} + {{significant_covariates}}" // 纳入表2中P<0.05的变量
}
}
]
}

4. 对系统价值的深远影响

Planner (大模型) 压力骤降：LLM 不再需要像写循环一样生成 20 个分析步骤。它只需要提取出【结局变量】、【分组变量】和【协变量列表】即可。这使得规划的准确率无限逼近 100%。
完美契合《统计分析报告.docx》：
- Table 1 -> 对应 Step 1
- Table 2 -> 对应 Step 2
- Table 3 -> 对应 Step 3
  这标志着我们的 AI 从“答题机器”变成了真正掌握科研 SOP 的“高级数据分析师”。
用户体验魔法化：用户只需一句话输入（“这批队列数据，结局是生存状态，主要看吸烟的影响，帮我出一套完整报告”），系统就会直接扔出 3 张可以直接放进 SCI 论文的超长三线表。

5. 决议与后续行动

团队的这个诊断极其精辟，强烈同意纳入 Phase Deploy 阶段执行。

Action Items:

R 工程师：将研究 gtsummary 包作为 P0 级任务，本周内用 6-8 小时将其封装为 ST_BASELINE_TABLE，并测试其提取 report_blocks 表格结构的能力。
后端工程师：在决策表中加入 cohort_study_standard 流程模板。
前端工程师：准备好能够支持横向滚动、拥有复杂表头（Span Header）的高级三线表组件，以迎接 Table 1 这种包含大量数据的巨型表格。

5.3 KiB Raw Blame History Unescape Escape