Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ssa): Complete Phase 2A frontend integration - multi-step workflow end-to-end

Browse Source 
Phase 2A: WorkflowPlannerService, WorkflowExecutorService, Python data quality, 6 bug fixes, DescriptiveResultView, multi-step R code/Word export, MVP UI reuse. V11 UI: Gemini-style, multi-task, single-page scroll, Word export. Architecture: Block-based rendering consensus (4 block types). New R tools: chi_square, correlation, descriptive, logistic_binary, mann_whitney, t_test_paired. Docs: dev summary, block-based plan, status updates, task list v2.0.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
HaHafeng
2026-02-20 23:09:27 +08:00
parent 23b422f758
commit 428a22adf2
62 changed files with 15416 additions and 299 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
docs/03-业务模块/SSA-智能统计分析/06-开发记录/2026-02-20-Phase2A-前端集成与多步骤工作流开发总结.md Normal file
View File

@@ -0,0 +1,187 @@
# SSA-Pro 2026-02-20 开发总结：Phase 2A 前端集成与多步骤工作流
> **版本：** v1.0
> **日期：** 2026-02-20
> **编写：** AI 开发助手
> **状态：** ✅ Phase 2A 前端集成完成 + Block-based 架构方案达成共识
---
## 1. 开发目标
本日核心目标是 **Phase 2A 智能核心前端集成**，将后端多步骤工作流（Workflow）功能端到端打通到前端 UI，并解决集成过程中发现的所有 Bug。
---
## 2. 完成工作清单
### 2.1 Python 数据质量服务集成
| 任务 | 状态 | 说明 |
|------|------|------|
| CSV 直传 Python 端点 | ✅ 完成 | 新增 `/api/ssa/data-profile-csv` 端点，Python 直接解析 CSV |
| 端口配置修复 | ✅ 修复 | 默认端口从 8081 修正为 8000 |
| 环境变量补充 | ✅ 完成 | `backend/.env` 新增 `EXTRACTION_SERVICE_URL` |
| 文件格式智能检测 | ✅ 完成 | `DataProfileService` 自动检测 JSON/CSV 调用不同端点 |
### 2.2 多步骤工作流前端集成
| 任务 | 状态 | 说明 |
|------|------|------|
| 意图识别增强 | ✅ 完成 | `WorkflowPlannerService` 正则提取变量名 + 变量类型判断 |
| 统计工具智能选择 | ✅ 完成 | 根据变量类型（分类/连续）正确选择统计方法 |
| SSE 实时进度 | ✅ 完成 | 前后端 SSE 消息格式对齐，支持 `connected`/`step_start`/`step_complete` |
| 工作流执行触发 | ✅ 修复 | SSE 连接时自动触发 `executeWorkflow`，解决"卡在调用R引擎"问题 |
### 2.3 前端 UI 修复与优化
| 任务 | 状态 | 说明 |
|------|------|------|
| SAP 按钮误显示 | ✅ 修复 | 移除数据上传后自动显示分析计划的逻辑 |
| 数据质量报告位置 | ✅ 修复 | 移至 `messages.map` 循环前，紧跟数据上传 |
| 分析计划 undefined | ✅ 修复 | 前后端 `WorkflowPlan` 接口对齐 |
| 复用 MVP 设计 | ✅ 完成 | 多步骤模式复用 MVP 单步骤的 UI 组件风格 |
| CSS 布局混乱 | ✅ 修复 | 移除 `position: absolute`，修复 padding 双重叠加 |
| 滚动不可用 | ✅ 修复 | 移除 `.terminal-box` 的 `max-width` 限制 |
### 2.4 多步骤结果展示
| 任务 | 状态 | 说明 |
|------|------|------|
| 执行日志 | ✅ 完成 | MVP 风格 terminal-box + TraceLogItem，显示 `[步骤 N] 工具名 → 状态` |
| 统计结果渲染 | ✅ 完成 | 各步骤独立显示统计量、P值、效应量、置信区间 |
| 分组统计表 | ✅ 完成 | `group_stats` 渲染为 sci-table |
| 回归系数表 | ✅ 完成 | `coefficients` 渲染为专用表格 |
| 描述性统计 | ✅ 完成 | 专用 `DescriptiveResultView` 组件，处理 `variables`+`by_group` |
| 图表显示 | ✅ 完成 | `plots` base64 图片渲染 |
### 2.5 导出功能
| 任务 | 状态 | 说明 |
|------|------|------|
| R 代码导出 | ✅ 完成 | 多步骤模式聚合所有步骤的 `reproducible_code` |
| Word 报告导出 | ✅ 完成 | `exportWorkflowReport` 完整报告：摘要+各步骤详情+描述性统计 |
| 描述性统计导出修复 | ✅ 修复 | 正确解析 `variables` 对象中数值/分类变量并生成表格 |
### 2.6 架构讨论与规划
| 任务 | 状态 | 说明 |
|------|------|------|
| Block-based 协议评估 | ✅ 完成 | 评估并认可 `SSA-Pro 动态结果渲染与通信协议规范.md` |
| 开发计划编写 | ✅ 完成 | `08-Block-based动态结果渲染开发计划.md` |
---
## 3. 关键 Bug 修复详情
### Bug #1：CSV 文件解析失败
**现象**：后端报错 `"Unexpected token 's', "sex,smoke,"... is not valid JSON"`
**根因**：`DataProfileService` 从 OSS 下载 CSV 文件后，尝试 `JSON.parse()` 解析
**修复**：新增文件类型检测逻辑，CSV 文件直接以字符串形式发送到 Python 新端点 `/api/ssa/data-profile-csv`
### Bug #2：统计方法选择错误
**现象**：分析 `sex` 与 `Yqol`（分类变量 0/1）的关系，推荐 T 检验而非卡方/Logistic
**根因**：`WorkflowPlannerService` 未提取具体变量名，也未检查变量类型
**修复**：重写 `parseUserIntent` 和 `generateSteps`，基于正则提取变量名 + `DataProfile` 变量类型判断
### Bug #3：SSE 执行卡死
**现象**：前端显示"正在调用云端 R 引擎"但无进展，后端日志显示执行正常
**根因**：SSE stream 路由仅注册监听器，未触发 `executeWorkflow`
**修复**：`/:workflowId/stream` 路由在客户端连接时异步触发工作流执行
### Bug #4：结果数据丢失
**现象**：执行日志正常但结果区域为空，导出按钮不显示
**根因**：`WorkflowExecutorService` 只展开 `response.data.results`，丢失 `plots`、`reproducible_code` 等字段
**修复**：将 `plots`、`result_table`、`reproducible_code`、`trace_log`、`warnings` 全部注入 `step.result`
### Bug #5：描述性统计显示异常
**现象**：描述性统计只显示几个数字，不是表格
**根因**：R 服务返回 `{ summary, variables: { "varName": {...} } }` 嵌套结构，前端未正确解析
**修复**：创建 `DescriptiveResultView` 专用组件，正确遍历 `variables` 对象生成数值/分类变量表格
### Bug #6：Word 报告缺少描述性统计
**现象**：导出 Word 报告无描述性统计内容
**根因**：`exportWorkflowReport` 未处理描述性统计的 `variables` 对象结构
**修复**：添加 `classifyExportVar` 辅助函数，遍历 `variables` 生成 docx 表格行
---
## 4. 修改文件清单
### 后端 (backend)
| 文件 | 修改类型 | 说明 |
|------|---------|------|
| `services/DataProfileService.ts` | 增强 | CSV 直传 Python、文件类型检测 |
| `services/WorkflowPlannerService.ts` | 重写 | 意图解析、变量类型判断、工具选择 |
| `services/WorkflowExecutorService.ts` | 修复 | result 字段完整传递 |
| `routes/workflow.routes.ts` | 修复 | SSE 触发执行 |
| `.env` | 新增 | `EXTRACTION_SERVICE_URL` |
### Python 服务 (extraction_service)
| 文件 | 修改类型 | 说明 |
|------|---------|------|
| `main.py` | 新增 | `/api/ssa/data-profile-csv` 端点 |
### 前端 (frontend-v2)
| 文件 | 修改类型 | 说明 |
|------|---------|------|
| `components/SSAChatPane.tsx` | 修复 | SAP 显示逻辑、DataProfile 位置、工作流调用 |
| `components/SSAWorkspacePane.tsx` | 重构 | 复用 MVP 设计、DescriptiveResultView、多步骤渲染 |
| `components/SSACodeModal.tsx` | 增强 | 多步骤 R 代码聚合 |
| `hooks/useWorkflow.ts` | 修复 | SSE 消息兼容处理 |
| `hooks/useAnalysis.ts` | 增强 | `exportWorkflowReport` + 描述性统计导出 |
| `types/index.ts` | 扩展 | SSE 消息类型定义 |
| `styles/ssa-workspace.css` | 修复 | 布局、滚动、间距 |
---
## 5. 架构决策
### 达成共识：Block-based 动态结果渲染
经过讨论，团队就以下架构方向达成共识：
1. **采用 Block-based 协议**：R 工具输出标准化的 `report_blocks` 数组
2. **4 种 Block 类型**：`markdown`、`table`、`image`、`key_value`
3. **Node.js 零维护**：直接透传 `report_blocks`，不做字段映射
4. **前端单一组件**：`DynamicReport.tsx` 动态渲染所有工具的结果
5. **渐进式迁移**：新旧协议并存，逐步替换
详见 `04-开发计划/08-Block-based动态结果渲染开发计划.md`
---
## 6. 当前状态总结
| 维度 | 状态 |
|------|------|
| Phase 2A 后端 | ✅ 100%（多步骤工作流、意图识别、SSE 进度） |
| Phase 2A 前端 | ✅ 100%（UI 集成、结果展示、导出功能） |
| 数据质量服务 | ✅ Python 服务正常调用 |
| 端到端流程 | ✅ 上传 → 质量报告 → 多步骤规划 → 执行 → 结果 → 导出 |
| Block-based 重构 | 📋 计划已制定，待开始 |
---
## 7. 下一步计划
1. **Block-based 动态渲染实施**（~2.5 天）
- Phase 1：前端 `DynamicReport.tsx` + R 辅助函数库
- Phase 2：7 个 R 工具逐一改造
- Phase 3：清理旧的自定义渲染代码
2. **更多统计工具前端验证**
- 卡方检验、相关分析、回归分析的多步骤联合执行测试
---
**文档结束**

94
docs/03-业务模块/SSA-智能统计分析/06-开发记录/SSA-Pro MVP 智能化增强指南.md Normal file
View File

@@ -0,0 +1,94 @@
# **SSA-Pro MVP 智能化增强指南：基于理想愿景的资产提取**
**文档版本：** v1.0
**创建日期：** 2026-02-20
**文档定位：** 作为《00-MVP开发计划总览》的高级补充包。
**核心主旨：** 摒弃“重型流程引擎”的代码包袱，全面吸收《理想状态与智能化愿景设计》中的“智能交互与决策”灵魂。
## **1\. 总体评估：愿景文档的闪光点在哪里？**
《SSA-Pro 理想状态与智能化愿景设计》精准指出了传统统计软件的通病——**“逼迫用户做统计学决策”**。它提出系统应该具备：意图理解、数据诊断、决策表匹配、以及综合结论生成。
这四个要素**完全不需要复杂的底层引擎支持**，它们属于\*\*认知层（Cognitive Layer）\*\*的能力。我们完全可以把它们吸收进现有的 SSA-Planner (智能规划师) 和 SSA-Critic (结果解读) 模块中。
## **2\. 五大可落地的“愿景精华”与 MVP 补充方案**
### **💡 精华一：从“选方法”到“翻译临床意图” (Clinical Intent Translation)**
* **愿景痛点**：医生不会说“给我做个 T 检验”，只会说“这药对高血压有效吗”。
* **MVP 现状**：现有的 RAG 检索过于依赖工具名（如用户没提到 T检验，可能检索不到）。
* **如何低成本补入 MVP**：
* **行动**：在 MVP 的 Phase 1（大脑与咨询）中，强化 Query Rewriter (查询重写器) 的 Prompt。
* **具体做法**：教 LLM 建立【临床黑话 \-\> 统计术语】的映射字典。
* 遇到“有效/无效、优于、比...好” ![][image1] 映射为“差异分析、优效检验”。
* 遇到“危险因素、风险、有没有关系” ![][image1] 映射为“相关性分析、回归分析”。
* **价值**：代码 0 增加，仅靠调优 Prompt，就能让系统具备“听懂医生人话”的顶级智能感。
### **💡 精华二：用“决策表”替代“AI的瞎猜” (Decision Table Driven)**
* **愿景痛点**：完全依赖大模型（LLM）去选方法，容易产生幻觉，选错工具。
* **MVP 现状**：原计划由 LLM 阅读 10 个工具的描述，自己决定用哪个。
* **如何低成本补入 MVP**：
* **行动**：在 Config Center (配置中台) 的 Excel 表格中，强制加入**决策要素树**。
* **具体做法**：在导入的 tools\_library.xlsx 中，除了工具名字，增加三列硬性约束：
1. **X 变量要求**（如：二分类）
2. **Y 变量要求**（如：连续数值）
3. **实验设计**（如：独立/配对）
* 在 PlannerService 生成方案时，不让 LLM 自由发挥，而是让 LLM 提取用户数据的 X/Y 特征，去**严格匹配**这个决策表。
* **价值**：用最原始的“规则引擎”约束 AI，让方法选择的准确率达到 100%。
### **💡 精华三：用“场景宏工具”实现“一键全流程” (Macro-Tools for Scenarios)**
* **愿景痛点**：用户想要的是“全部分析完”，而不是一个个跑工具。
* **MVP 现状**：我们的底层是执行单节点 R 代码。
* **如何低成本补入 MVP**：
* **行动**：**降维打击！绝对不要做 Node.js 的流程引擎。** 我们用 R 语言写“套餐脚本”。
* **具体做法**：在 MVP 的 10 个工具中，保留 8 个单点工具（如 T检验、卡方），**额外新增 2 个“宏工具 (Macro-Tools)”**：
* ST\_MACRO\_RCT\_EFFICACY (临床试验疗效一键包：内部包含 Table1 画表 \+ 缺失值填补 \+ 主效应 T检验 \+ 结论汇总)。
* 这个宏工具在系统看来，依然只是\*\*“一个 R 脚本”\*\*，但它内部执行了完整的流程。
* **价值**：满足了理想愿景中“完整流程编排”的需求，却把长达 18 天的引擎开发周期，缩短为 R 工程师 1 天写一个长脚本的成本。
### **💡 精华四：前置的数据诊断与自适应 (Data Diagnosis & Adaptation)**
* **愿景痛点**：数据格式不对，直接跑会报错。
* **MVP 现状**：现有的“统计护栏”是在 R 执行时报错降级。
* **如何低成本补入 MVP**：
* **行动**：在 Planner 阶段增加轻量级的“数据诊断警告”。
* **具体做法**：在 Planner 读取到数据 Schema 后，如果发现用户想做 T 检验，但 Y 变量的类型是 String（可能包含了 "mmol/L" 等单位）。
* Planner 在生成的 SAP 卡片上提前亮黄灯：*“警告：您的结局变量当前为文本型，系统将在执行前尝试自动提取数值。若提取失败可能报错。”*
* **价值**：将后置的报错提前到前置的“诊断”，给用户极强的安全感。
### **💡 精华五：论文级的结论生成 (Publication-Ready Interpretation)**
* **愿景痛点**：系统只输出冷冰冰的 P 值，距离真正的报告还差最后一步。
* **MVP 现状**：现有的 Critic 会解释 P 值。
* **如何低成本补入 MVP**：
* **行动**：升级 Critic Agent 的输出模板。
* **具体做法**：把经典的医学报告规范（如 CONSORT 规范、STROBE 规范关于统计方法的描述要求）注入到 Critic 的 System Prompt 中。
* 强制要求 Critic 的输出结构包含：
1. **方法学描述**（可直接复制到论文 Method 部分，如："Continuous variables were expressed as mean ± SD..."）
2. **核心结论**
3. **临床意义提示**
* **价值**：真正实现了愿景中提到的“输出可直接用于论文”，产品价值瞬间翻倍。
## **3\. 补充进 《00-MVP开发计划总览》 的具体 Action Items**
为了将这些精华落地，建议在现有的 MVP 开发计划中补充以下任务（**不需要修改架构，也不增加过多工时**）：
| 原 MVP 阶段 | 需补充的任务项 (源自愿景) | 负责人 | 增加工时预估 |
| :---- | :---- | :---- | :---- |
| **Phase 1: 大脑与咨询** | **M1.4** Excel 配置表中增加 X/Y 变量类型与实验设计的“决策表”字段。 | 统计专家 | \+0.5 天 |
| **Phase 1: 大脑与咨询** | **B1.5** 优化 Planner Prompt，使其能把临床意图（如“对比疗效”）映射为统计术语。 | 后端开发 | \+1 天 |
| **Phase 2: 四肢与执行** | **R2.4** 在 10 个工具指标外，编写 1-2 个包含多步操作的 **“场景宏工具 (Macro R Script)”**。 | R 开发 | \+1.5 天 |
| **Phase 3: 合体与交付** | **B3.1** 优化 Critic Prompt，强制按学术期刊规范输出“方法学说明”和“综合报告”。 | 后端/专家 | \+0.5 天 |
## **4\. 总结：给理想主义者的致敬**
这套增强方案是对原愿景文档最好的回应：
**“我们完全认同您提出的所有智能化用户体验（意图识别、智能诊断、流程包、论文级报告），并且我们找到了无需重建底层引擎，用极低成本在 MVP 阶段就能实现它们的方法。”**
[image1]: <data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABMAAAAXCAYAAADpwXTaAAAAX0lEQVR4XmNgGAWjYCQAeXn50+hiZAOgYU/QxcgGcnJy2kA8HV2cbAB03SwgDkIXB0lIkomnAfF1oBHM1DBsERCfRzGMHCCPy5ukAmgETEAXJwvIUzFpMMpTM9GOcAAAmV0cRTlI2MMAAAAASUVORK5CYII=>

95
docs/03-业务模块/SSA-智能统计分析/06-开发记录/SSA-Pro Prompt体系与专家配置边界梳理.md Normal file
View File

@@ -0,0 +1,95 @@
# **SSA-Pro Prompt 体系与专家配置边界梳理**
**文档版本：** v1.0
**创建日期：** 2026-02-20
**核心目的：** 划定 AI 工程师（写 Prompt）与统计专家（写配置）的工作边界，明确系统各环节的控制权归属。
## **1\. 核心理念：骨架与血肉的分离**
在 SSA-Pro 中，我们绝对不能让统计专家直接去维护一长串包含 \<thinking\>、{ "type": "json" } 等晦涩指令的原始 Prompt。这会让专家崩溃，也会导致 JSON 输出格式极易被改坏。
最佳实践是 **动态 Prompt 注入 (Dynamic Prompt Injection)**：
* **AI 工程师（Prompt 工程师）**：负责维护 **Prompt 模板（骨架）**，控制 AI 的角色、思考链和严格的 JSON 输出结构。
* **统计专家（业务专家）**：在配置中台中维护 **统计学规则（血肉）**。
* **运行时**：Node.js 后端将专家的配置提取出来，像填空题一样塞进 Prompt 模板中发送给 LLM。
## **2\. 全链路 Prompt 梳理 (何处需要 Prompt?)**
SSA-Pro 全流程共有 **3 个核心环节** 需要大模型介入，因此对应 **3 个核心 Prompt**：
### **环节一：意图重写器 (Query Rewriter Prompt)**
* **作用**：将医生口语（“看两个药的效果差异”）翻译成统计学黑话（“差异性分析，T检验”），用于向量库高精度检索。
* **Prompt 骨架 (AI 工程师)**：规定必须输出 3-5 个同义词的 JSON 数组。
* **专家配置注入 (配置中台)**：专家在后台配置 **“同义词/黑话字典”**。
* **举例**：System Prompt \= "你是一个检索翻译官。请参考以下专家提供的字典：{{Expert\_Dictionary}}，将用户输入翻译为标准术语。"
### **环节二：智能规划师 (SSA-Planner Prompt) ⭐ 最核心**
* **作用**：根据用户数据列名（Schema），从检索到的 Top-5 工具中挑出 1 个，并生成参数映射计划 (SAP)。
* **Prompt 骨架 (AI 工程师)**：
* 设定角色：“你是一位顶尖的生物统计学家。”
* 强制要求：“你必须输出包含 tool\_code, reasoning, params 的 JSON，并先在 \<thought\> 标签中思考。”
* **专家配置注入 (配置中台)**：
* 注入检索到的工具定义：{{Tool\_Name}}, {{Usage\_Context\_Rules}}, {{Data\_Type\_Requirements}}。
* **专家真正写的是**：“T检验要求因变量为连续数值，自变量为二分类。”这句话会被原封不动塞进 Prompt 里，指导 AI 决策。
### **环节三：结果解读审查员 (SSA-Critic Prompt)**
* **作用**：将 R 跑出来的冰冷 JSON 结果（如 p\_value: 0.04），写成可以放在论文里的标准段落。
* **Prompt 骨架 (AI 工程师)**：规定输出 Markdown 格式，规定必须包含“结论”、“统计量”、“P值”三个小节。
* **专家配置注入 (配置中台)**：
* 注入 **“解释规范与禁用词”**（例如：专家在后台配置“严禁使用‘证明了’一词，必须用‘具有统计学意义’”）。
* 注入 R 执行的真实结果 {{R\_Output\_JSON}}。
## **3\. 统计配置中台：到底要配置什么？ (Config Center Inventory)**
理清了 Prompt，我们再来看 **配置中台 (Admin)** 里，统计专家到底要填哪些东西。
配置中台不仅服务于 LLM (Prompt)，还服务于底层的 R 引擎 (Executor)。
### **📊 专家需要配置的 5 大核心模块：**
#### **A. 语义与决策配置 (供 Planner Prompt 消费)**
1. **工具名称与描述**：例如 独立样本 T 检验，用于比较两组独立样本的均值差异。（用于 RAG 检索）
2. **决策要素表 (Decision Table)**：
* 专家勾选：X变量=分类，Y变量=连续数值。
* *(后端会自动把这些勾选项翻译成自然语言，塞进 Planner Prompt 中当作判别规则)*。
#### **B. 话术与规范配置 (供 Critic Prompt 消费)**
3. **解释模板与禁忌语**：
* 专家填写：当 P \< 0.05 时，话术模板为：{X} 对 {Y} 存在显著影响 (P={P\_value})。
#### **C. 严谨性配置 (直接供 R Executor 消费，与 Prompt 无关！)**
4. **统计护栏规则 (Guardrails)**：
* 专家配置：必须执行 Shapiro-Wilk 检验，阈值 P \< 0.05 时，触发 Switch\_To\_Wilcoxon 动作。
* **⚠️ 注意**：这些护栏规则 **绝对不要** 放到 Prompt 里让大模型去判断。这些规则是直接存为 JSON，发给 R Docker，由 R 代码强逻辑执行的。
#### **D. 资产生成配置 (直接供 R Executor 消费)**
5. **R 代码片段模板 (Glue Template)**：
* 专家在后台贴入一段带 {{group\_var}} 占位符的 R 代码。这是用户最后下载的白盒代码。
## **4\. 总结：两者的黄金边界**
为了方便团队理解，请记住这个表格：
| 资产类型 | 谁来写？ | 存在哪里？ | 最终被谁执行/阅读？ |
| :---- | :---- | :---- | :---- |
| **System Prompt 模板 (骨架)** | AI 工程师 / 后端 | 数据库 prompt\_templates 表 | 传给大模型 (DeepSeek) |
| **工具适用条件/数据类型要求** | 统计专家 | 配置中台 (Excel/Web) | 被塞进 Prompt，传给大模型 |
| **统计护栏 (如正态性 P\<0.05 降级)** | 统计专家 | 配置中台 (Excel/Web) | 传给 R 服务，**由 R 代码强执行** |
| **可复现的 R 代码模板** | 统计专家 | 配置中台 (Excel/Web) | 传给 R 服务，拼接后提供给用户下载 |
| **论文结论解释规范** | 统计专家 | 配置中台 (Excel/Web) | 被塞进 Critic Prompt，传给大模型 |
### **💡 最终建议**
**配置中台（哪怕 MVP 阶段只是一个 Excel 表），是承载统计专家智慧的唯一载体。** 专家只需要在这个 Excel 里用人话填表。
后端代码会负责把这个 Excel 解析拆分：一部分用来拼装 Prompt 让 AI 变聪明，另一部分以 JSON 形式发给 R 引擎让计算变严谨。

172
docs/03-业务模块/SSA-智能统计分析/06-开发记录/SSA-Pro 动态结果渲染与通信协议规范.md Normal file
View File

@@ -0,0 +1,172 @@
# **SSA-Pro 动态结果渲染与通信协议规范**
**文档版本：** v1.0
**创建日期：** 2026-02-20
**解决痛点：** 统一 100+ 种统计工具的输出格式，实现后端免维护、前端动态渲染。
**核心思想：** R 端输出的不是“数据”，而是“UI 渲染区块 (Blocks)”。
## **1\. 核心架构思想：区块化 (Block-based Architecture)**
借鉴 Notion 和 Jupyter Notebook 的设计思想，我们将所有可能的统计输出抽象为**有限的几种“基础积木（Blocks）”**。
不论是 T 检验、生存分析还是复杂的回归模型，其输出结果最终都可以拆解为以下 4 种基础类型的组合：
1. **text / markdown**: 用于 AI 解读、简单结论、警告提示。
2. **table**: 用于三线表、矩阵、数据框。
3. **image**: 用于所有的可视化图表。
4. **key\_value**: 用于展示核心统计量（如 P 值、t 值等高亮卡片）。
## **2\. JSON 通信协议定义 (The Universal Protocol)**
R 服务最终返回给 Node.js，Node.js 再原封不动透传给前端的 JSON 结构，**必须**是如下的标准协议：
{
"status": "success",
"trace\_log": \[ ...执行日志... \],
"reproducible\_code": "library(ggplot2)...",
// ⭐ 核心变革：统一的 blocks 数组
"report\_blocks": \[
{
"type": "markdown",
"content": "\*\*AI 解读：\*\* 结果表明新药组的血压下降幅度显著大于对照组..."
},
{
"type": "table",
"title": "Table 1\. 组间差异比较",
"data": {
"headers": \["Group", "N", "Median \[IQR\]", "P-Value"\],
"rows": \[
\["Drug", "60", "14.5 \[12.1-16.8\]", "\< 0.001 \*\*"\],
\["Placebo", "60", "8.2 \[6.5-10.4\]", ""\]
\]
},
"footer": "Note: IQR \= Interquartile Range; \*\* P \< 0.01"
},
{
"type": "image",
"title": "Figure 1\. 血压下降值分布",
"format": "base64",
"src": "iVBORw0KGgoAAAANSUhEUgAAAAE...", // base64 字符串
"caption": "箱线图展示了两组的分布情况"
},
{
"type": "key\_value",
"title": "核心指标",
"items": \[
{"label": "W Statistic", "value": "2845.5"},
{"label": "Effect Size (r)", "value": "0.45", "status": "warning"}
\]
}
\]
}
## **3\. R 端的开发规范 (如何吐出这个协议？)**
R 工程师在封装 Wrapper 时，不需要关心前端怎么画图，只需要把结果打包成上述的 list。
**R 代码示例 (以 T 检验为例)：**
run\_tool \<- function(input) {
\# ... 执行计算 res \<- t.test(...) ...
\# ... 画图并转 base64 ...
\# 统一打包为 Blocks
report\_blocks \<- list(
list(
type \= "markdown",
content \= sprintf("独立样本 T 检验结果显示，P值为 %.3f。", res$p.value)
),
list(
type \= "table",
title \= "描述统计与检验结果",
data \= list(
headers \= c("统计量", "数值"),
rows \= list(
c("t 值", round(res$statistic, 2)),
c("自由度 df", round(res$parameter, 2)),
c("P 值", res$p.value)
)
)
),
list(
type \= "image",
title \= "均值差异对比图",
format \= "base64",
src \= base64\_image\_string
)
)
return(list(
status \= "success",
trace\_log \= logs,
report\_blocks \= report\_blocks, \# 直接返回 Blocks 数组
reproducible\_code \= code\_str
))
}
## **4\. 前端的动态渲染策略 (Dynamic Renderer)**
前端彻底解放。**前端不需要写 TTestResult.tsx 或 AnovaResult.tsx，只需要写一个 DynamicReport.tsx。**
前端只需遍历 report\_blocks 数组，根据 type 挂载对应的基础组件即可。
**React 伪代码：**
// 1\. 准备基础积木组件
const MarkdownBlock \= ({ content }) \=\> \<ReactMarkdown\>{content}\</ReactMarkdown\>;
const SciTableBlock \= ({ title, data, footer }) \=\> (
\<div\>
\<h4\>{title}\</h4\>
\<table className="sci-table"\>
\<thead\>\<tr\>{data.headers.map(h \=\> \<th\>{h}\</th\>)}\</tr\>\</thead\>
\<tbody\>{data.rows.map(row \=\> \<tr\>{row.map(cell \=\> \<td\>{cell}\</td\>)}\</tr\>)}\</tbody\>
\</table\>
{footer && \<p\>{footer}\</p\>}
\</div\>
);
const ImageBlock \= ({ title, src, caption }) \=\> (
\<div\>
\<h4\>{title}\</h4\>
\<img src={\`data:image/png;base64,${src}\`} alt={title} /\>
\<p\>{caption}\</p\>
\</div\>
);
// 2\. 核心动态渲染器
export const DynamicReport \= ({ blocks }) \=\> {
return (
\<div className="report-container space-y-8"\>
{blocks.map((block, index) \=\> {
switch (block.type) {
case 'markdown':
return \<MarkdownBlock key={index} {...block} /\>;
case 'table':
return \<SciTableBlock key={index} {...block} /\>;
case 'image':
return \<ImageBlock key={index} {...block} /\>;
case 'key\_value':
return \<KeyValueBlock key={index} {...block} /\>;
default:
return \<div key={index}\>未知的区块类型: {block.type}\</div\>;
}
})}
\</div\>
);
};
## **5\. Node.js 的角色 (Zero-Maintenance)**
通过这套协议，Node.js 后端变成了绝对的 **“零维护 (Zero-Maintenance)”** 状态。
如果未来 R 团队新增了第 101 个工具（比如一个极度复杂的神经网络模型，返回 5 张表、10 张图），Node.js 的代码 **一行都不需要改**！因为它只负责把 R 返回的 JSON 原样抛给 React。
## **6\. 总结：多表多图的终极解法**
* **问：如何展示多表多图？**
* **答：R 脚本往 report\_blocks 数组里不断 push 即可。想展示几张就 push 几个 image block。**
这种“协议化、区块化”的设计，是现代 SaaS 平台（如飞书、Notion、Jupyter）的基石架构。它赋予了 R 团队极大的排版自由度，同时彻底保护了前端和后端的架构稳定性。

68
docs/03-业务模块/SSA-智能统计分析/06-开发记录/SSA-Pro 智能化演进路径评估报告.md Normal file
View File

@@ -0,0 +1,68 @@
# **SSA-Pro 智能化演进路径评估：Tool Calling vs Agentic Code Gen**
**评估目标：** 对比「工具调用范式 (Tool Calling)」与「靶向动态代码生成范式 (Agentic Code Gen)」在临床科研场景下的真实用户价值差异。 **核心结论：** 对于 90% 的标准临床科研需求，工具调用范式能在“合规性”和“可复现性”上提供绝对保障，是 MVP 的不二之选。而引入“错误反馈与动态自愈”的代码生成范式，是应对极度复杂/脏数据的未来终极形态（V2.0 目标）。
## **1\. 概念对齐与场景设定**
* **路线 A（Tool Calling / 专家静态工具库模式）**：系统内置 100+ 经过严格验证的 R 脚本（含宏脚本）。LLM 负责“听懂人话、提取列名、排兵布阵（串联 5 个工具）、填入静态的 JSON 参数”，R 引擎负责“傻瓜式执行”。**代码本体绝对不允许被修改。**
* **路线 B（Agentic Code Gen / 靶向动态自愈模式 \- 研发团队的终极设想）**：系统把 100+ 脚本作为基座。LLM 负责“理解意图、串联工具”。如果直接运行报错，系统会将**错误日志 (Error Log) 和数据片段**反馈给 LLM，LLM 像真实的程序员一样，**针对性地修改这 100 个工具中的代码细节或参数**（例如：自动补写一段剔除极端值的 R 代码），反复试错，直到顺利跑出结果。
## **2\. 核心命题解答：用户的感知差异大吗？**
**结论：在“成功跑通”的情况下，用户感知差异不大；但在“遇到异常数据”时，路线 B 展现出极强的韧性，而路线 A 具有极高的合规安全性。**
### **2.1 临床医生的“第一性原理”需求是什么？**
医生使用统计软件（无论是 SPSS 还是未来的 AI 工具）的终极目的只有三个：
1. **拿到经得起审稿人推敲的 P 值。**
2. **拿到可以直接贴进 SCI 论文的图表（三线表、KM曲线、森林图）。**
3. **不用自己去记复杂的统计学前提条件（如方差齐性）。**
### **2.2 场景模拟：“我的数据里有几个病人的血压值录入成了‘未知’，帮我做个 T 检验”**
* **如果是路线 A (组合工具)**：LLM 生成了 JSON。R 引擎调用固定脚本，读到“未知”这个字符串时，严格报错。系统提示用户：“您的数据存在非法字符，请清洗后再试”。（体验略有挫折，但绝对严谨）。
* **如果是路线 B (靶向自愈代码)**：LLM 生成了代码并执行 \-\> R 引擎报错 Error: non-numeric argument \-\> LLM 拿到报错，立刻反应过来，**动态修改代码**，加上一句 df \<- df\[df$血压 \!= '未知', \] \-\> 再次执行 \-\> 成功出结果。（体验极佳，AI 自动擦屁股）。
**【用户感知与隐患对比】**
* **体验上**：路线 B 像一个真正的高级助理，帮医生把脏活累活干完了。
* **隐患上**：路线 B 悄悄剔除了样本，如果这不符合医学上的“意向性分析 (ITT) 原则”，擅自删数据会构成学术不端。而路线 A 强制报错，逼迫医生自己决定怎么处理缺失值，保住了学术红线。
## **3\. 系统性对比矩阵 (Systematic Evaluation)**
基于团队对路线 B 的深刻理解，我们从商业产品必须考虑的五个维度进行深度对比：
| 评估维度 | 路线 A：Tool Calling (当前计划) | 路线 B：Agentic Code Gen (团队终极愿景) | 谁更满足医疗场景？ |
| :---- | :---- | :---- | :---- |
| **结果的权威性与合规度** | **极高**。底层是统计算法专家千锤百炼的代码，P 值绝对可靠。 | **中等**。大模型动态改代码，可能为了“让程序不报错”而采用错误的统计妥协（如暴力删数据）。 | 🏆 **路线 A 胜** (医疗是容错率为0的行业) |
| **可复现性 (Reproducibility)** | **100%**。昨天跑和今天跑，调用的工具和底层代码绝对一致。 | **较低**。LLM 的纠错路径可能每次不同，导致生成的修正代码不一致，P 值微调。 | 🏆 **路线 A 胜** (科研最讲究可复现) |
| **异常自愈与韧性 (Self-healing)** | **较弱**。遇到预设之外的脏数据，只能中断并报错给用户。 | **极强**。LLM 能够根据 Error Log 靶向修改代码，自动克服各种奇怪的运行时错误。 | 🏆 **路线 B 胜** (极其惊艳的技术能力) |
| **审计与排错成本** | **极低**。如果是由于工具 Bug，明确指向 ST\_T\_TEST 的某一行。 | **极高**。动态生成的孤品代码，报错后难以定位是 LLM 改错了还是数据有问题。 | 🏆 **路线 A 胜** |
| **响应延迟 (Latency)** | **极快** (毫秒级推理 JSON \+ 单次运行即出结果)。 | **很慢** (如果陷入报错-\>修代码-\>再跑的循环，可能需要数十秒甚至数分钟)。 | 🏆 **路线 A 胜** |
## **4\. 路线 A 能满足大部分需求吗？**
**能，能满足 90% 以上的标准临床科研需求。**
医学统计是一门**高度标准化、八股文化**的学科。全球顶尖的医学期刊（如 Lancet, JAMA）对统计方法的报告都有严格的规范（如 CONSORT 声明）。
* 基线总是 Table 1。
* 疗效对比总是 T 检验/卡方/非参数。
* 风险因素总是 Logistic 回归或 Cox 回归。
* 生存分析总是 KM 曲线加 Log-rank。
这 100+ 个工具，本质上就是医学统计学的“元素周期表”。只要 LLM 的“智商”足够高，能准确地在元素周期表里挑选出正确的元素并排列组合（比如：清洗 \-\> PSM匹配 \-\> Table1 \-\> Cox回归），就足以应对绝大多数医生的日常科研。
## **5\. 结论与团队沟通建议**
不要觉得“做工具调用”就是低级。团队设想的“基于错误反馈靶向修改代码”是非常成熟且高级的 Agentic 思维，这绝对是数据科学 AI 的未来。
**但真正的医疗产品价值，不仅在于底层技术有多“炫技”，更在于给用户的交付物有多“靠谱”。** \#\#\# 对团队的最终融合建议：
1. **MVP 阶段（现在）**：死磕 **路线 A (Tool Calling)**。把 100 个工具的入参、出参、护栏打磨到极致。让 Planner (LLM) 变成一个最聪明的“全科主任医师”，精准地给患者（数据）开出正确的“检查单（工具组合）”。
2. **V2.0 阶段（未来的路线 B 融合）**：采用\*\*“受限的自愈生成”\*\*。
* **在数据清洗（Data Wrangling）环节**：允许使用路线 B。当数据格式不对时，让 LLM 根据 Error Log 动态生成 R 代码去清洗数据。
* **在核心统计检验（Core Stats）环节**：依然死守路线 A。绝对禁止 LLM 动态修改计算 P 值的核心函数逻辑。
您可以告诉团队：**“排列组合 5 个高级工具，对用户来说魔法感已经拉满；而把你们设想的‘动态纠错修改’能力，克制地用在外围的数据清洗上，这是我们在【极客技术】与【医疗严谨性】之间找到的最完美的平衡点。”**

58
docs/03-业务模块/SSA-智能统计分析/06-开发记录/SSA-Pro 智能化演进阶梯.md Normal file
View File

@@ -0,0 +1,58 @@
# **SSA-Pro 智能化演进阶梯：从工具调用到代码智能的必由之路**
**核心观点：** Phase 2（工具调用与编排）不仅是 MVP 的交付目标，更是通往 Phase 3（动态代码自愈与生成）**不可逾越的绝对基础**。没有 Phase 2 的基建，Phase 3 就是空中楼阁。
## **一、 为什么 Phase 2 是 Phase 3 的地基？**
如果你想让大模型（LLM）在 Phase 3 能够“看到报错 \-\> 动态修改 R 代码 \-\> 重新执行”，你必须在 Phase 2 提前把以下 **三大基础设施** 彻底跑通。而这三大设施，只有在“固定工具调用”的模式下，才能最低成本地搭建出来：
### **1\. 稳如泰山的“执行沙箱与错误捕获管道” (The Execution Sandbox)**
* **在 Phase 3 中**：LLM 需要根据 Error Log 来修代码。
* **Phase 2 要填的坑**：R 容器报错时，Node.js 能不能精准捕获到 stderr？能不能把冗长的 R 报错提炼成 LLM 能看懂的精简 JSON？如果沙箱崩溃了，能不能一秒钟重启？
* **结论**：如果我们在 Phase 2 连**固定代码**的报错抓取和网络通信都没玩明白，直接上**动态代码**，一旦卡死，你连是 Docker 挂了还是 LLM 写了死循环都分不清。
### **2\. LLM 的“路由与编排智商” (Orchestration Intelligence)**
* **在 Phase 3 中**：LLM 需要自己构思数据处理的完整逻辑链。
* **Phase 2 要填的坑**：我们先用 100 个固定工具来“考试”。面对用户的复杂需求，LLM 能不能正确地挑出 \[缺失值填补\] \-\> \[PSM 匹配\] \-\> \[T检验\] 这 3 个工具，并把顺序排对？参数能不能传对？
* **结论**：如果 LLM 连现成的 100 个积木都拼不对，你指望它直接凭空捏造（写代码）出一个完美的城堡？先在 Phase 2 把 LLM 的 **“流程编排能力 (Planning)”** 训练到 100% 准确，是进入 Phase 3 的及格线。
### **3\. 建立“黄金数据集” (Golden Dataset for Fine-tuning)**
* **在 Phase 3 中**：LLM 需要以这 100 个专家脚本为“知识库”进行学习和微调。
* **Phase 2 要填的坑**：在 Phase 2 真实上线后，我们会收集到成千上万次医生真实调用的日志。我们知道了“在什么样的数据集下，调用什么样的工具，搭配什么样的参数，最终成功跑出了结果”。
* **结论**：这些 Phase 2 沉淀下来的成功调用记录，就是未来训练我们自己 **专属医学代码大模型 (Medical Coder LLM)** 无价的“黄金数据集”。没有 Phase 2 的数据投喂，Phase 3 的模型就是“没有临床经验的医学生”。
## **二、 SSA-Pro 演进路线图 (The Crawl-Walk-Run Strategy)**
理清了基础之后，我们团队的路线图就变得极其清晰、极具战斗力，并且前后逻辑完美自洽：
### **🏃‍♂️ 第一阶段：爬行期 (Phase 1/2) \- 当前 MVP 目标**
* **核心动作**：将 100 个 R 脚本封装为标准 API（原子工具 \+ 宏工具）。
* **AI 角色**：**高级接线员 / 调度枢纽 (Dispatcher)**。
* **机制**：LLM 纯靠 Prompt 识别意图 \-\> 填入 JSON 参数 \-\> 触发固定工具执行。
* **商业价值**：快速上线，证明产品逻辑，用 100% 正确的统计结果获取第一批种子医生的信任。
### **🚶‍♂️ 第二阶段：行走期 (Phase 2.5) \- 探索性边界突破**
* **核心动作**：引入\*\*“受限的自愈生成”\*\*（就是之前我建议的过渡方案）。
* **AI 角色**：**数据清洗实习生 (Data Wrangler)**。
* **机制**：核心的统计检验（跑 P 值）依然强制调用那 100 个死工具。但是，如果医生上传的数据格式很奇葩，允许 LLM **动态生成一段数据清洗的 R 代码 (dplyr)**，跑通后再喂给核心工具。
* **商业价值**：系统开始具备处理非标脏数据的能力，韧性大幅增强。
### **🏃‍♂️ 第三阶段：奔跑期 (Phase 3\) \- 团队的终极 Agent 愿景**
* **核心动作**：全面拥抱 **Self-healing Agentic Workflow (自愈型智能体工作流)**。
* **AI 角色**：**全能数据科学家 (AI Data Scientist)**。
* **机制**：LLM 把那 100 个脚本吸收入向量知识库。用户下达复杂指令，LLM 组合脚本 \-\> 动态修改内部代码逻辑 \-\> 在安全沙箱执行 \-\> 遇到错误 \-\> 提取 Error Log \-\> 结合数据自动重写代码 \-\> 直到跑通并输出报告。
* **商业价值**：成为真正的“统计学超级大脑”，技术壁垒深不可测，彻底甩开市面上的套壳竞品。
## **三、 结语：给团队的强心剂**
你的这句反问：*“换句话说，Phase 2 是 Phase 3的基础，我们得先把调用工具玩明白，把调用工具顺序弄清楚，后面才是 Phase 3动态修改代码来改进，对吗？”*
这句话就是你们团队从\*\*“理想主义的极客”**蜕变为**“兼具极客精神与工程手腕的顶尖团队”\*\*的标志！
饭要一口一口吃，路要一步一步走。把 Phase 2 这个地基打得坚如磐石，你们梦寐以求的 Phase 3 终极智能体，自然会水到渠成！现在，请全军出击，拿下 Phase 2！🚀

544
docs/03-业务模块/SSA-智能统计分析/06-开发记录/SSA-Pro 架构审查反馈与智能化路径讨论.md Normal file
View File

@@ -0,0 +1,544 @@
# SSA-Pro 架构审查反馈与智能化路径讨论
**文档类型：** 审查反馈与讨论纪要
**反馈对象：**
- 《架构审查报告：SSA-Pro 愿景与落地策略》
- 《SSA-Pro MVP 智能化增强指南》
**反馈日期：** 2026-02-20
**核心立场：** 🟢 认可务实策略的价值，🔴 但必须纠正一个根本性的理解偏差
---
## 🔴 关键澄清：100个 R 代码的真正用途
> **这是整个讨论中最重要的一点，必须首先澄清。**
### 审查报告的理解（工具调用范式）
```
100个 R 脚本 = 100个"工具"
系统工作方式：
用户提问 → LLM 选择工具 → 填入参数 → 调用执行 → 返回结果
本质：这是一个"高级版的 SPSS 菜单"，只是用 AI 帮你选菜单项
```
### 我们真正想要的（代码智能范式）
```
100个 R 脚本 = 知识库 / 参考模板 / 可学习的范例
系统工作方式：
用户提问 → LLM 理解意图 → LLM 诊断数据特征
→ LLM 从知识库检索相关代码
→ LLM 根据数据特征 **动态修改/组合/生成** 代码
→ 执行生成的代码 → LLM 解读结果
→ 根据结果决定下一步 → 继续修改/生成代码...
本质：这是一个"AI 统计学家 + AI 程序员"，能够针对用户的具体情况定制分析
```
### 两种范式的本质区别
| 维度 | 工具调用范式 | 代码智能范式 |
|------|-------------|-------------|
| **R 代码角色** | 被调用的固定函数 | 被学习的知识库 |
| **LLM 角色** | 参数填充器 | **代码理解者 + 改写者** |
| **适应性** | 只能处理参数化场景 | 能处理任意数据形态 |
| **灵活性** | 固定的输入输出格式 | 动态适应用户需求 |
| **智能化程度** | Level 2（智能工具箱） | **Level 3（智能助手）** |
### 具体场景对比
```
场景：用户有3组数据，样本量不等，想比较差异
工具调用范式：
────────────────
系统：查表 → 3组 → 调用 ANOVA 工具 → 传参数 → 执行
问题：如果数据不满足方差齐性呢？工具没有处理逻辑！
结果：要么报错，要么输出错误结果
代码智能范式：
────────────────
LLM 思考：
1. 3组比较 → 参考知识库中的 anova.R 模板
2. 用户说样本量不等 → 需要先检验方差齐性
3. 从知识库找到 levene_test.R 的代码片段
4. 组合代码：先做 Levene 检验
5. 根据 Levene 结果：
- 方差齐 → 使用标准 ANOVA
- 方差不齐 → 修改代码使用 Welch's ANOVA
6. 生成完整的、适应用户数据的 R 代码
7. 执行 → 解读结果 → 决定是否需要事后检验
8. 如果需要 → 继续生成事后检验代码...
结果：完整、正确、适应用户数据的分析流程
```
### 产品定位确认
> **我们的目标是 Level 3：颠覆性的智能分析助手**
>
> 不是做一个"比 SPSS 好用一点"的工具，
> 而是要做一个"让不懂统计的医生也能完成专业分析"的 AI 助手。
>
> **这是我们讨论所有技术方案的前提。**
---
## 一、前言：我们讨论的核心目标
在深入讨论技术方案之前，我想先明确一个根本性问题：
> **SSA-Pro 的核心价值是什么？**
答案应该是：**让不懂统计的医生，能够完成专业级的统计分析。**
这意味着系统需要具备：
1. **理解能力** —— 听懂医生的"人话"
2. **判断能力** —— 自动选择正确的方法
3. **规划能力** —— 动态规划分析路径
4. **执行能力** —— 可靠地完成计算
5. **表达能力** —— 输出可用于论文的结论
如果我们的方案只解决了 1、2、4、5，但丧失了 **3（规划能力）**，那么我们做的就是一个"高级自动化工具"，而不是"智能分析助手"。
**这是本次讨论的核心关切。**
---
## 二、对审查文档的逐项反馈
### 2.1 完全认可的观点 ✅
| # | 审查观点 | 我的评价 | 认可理由 |
|---|---------|---------|---------|
| 1 | "流程执行引擎"的技术复杂度被低估 | ✅ 完全认可 | 中间数据传输、错误回滚、断点续传确实是工程难题 |
| 2 | MVP 阶段不应陷入"引擎陷阱" | ✅ 完全认可 | MVP 的首要目标是快速交付可感知价值 |
| 3 | 精华一：临床意图翻译 | ✅ 完全认可 | 成本极低（改 Prompt），价值极高 |
| 4 | 精华二：决策表驱动 | ✅ 完全认可 | 这正是愿景中强调的"四维匹配" |
| 5 | 精华四：前置数据诊断 | ✅ 完全认可 | 把后置报错变成前置预警，体验极佳 |
| 6 | 精华五：论文级结论生成 | ✅ 完全认可 | 升级 Critic Prompt，直接提升产品价值 |
**小结：** 这些建议都是"低成本、高价值"的优化，可以立即采纳。
---
### 2.2 部分认可，但有保留的观点 🟡
#### 观点："用宏工具完全替代流程引擎"
**我的评价：** 🟡 **部分认可**
**认可的部分：**
- 宏工具确实是一种务实的降维方案
- 在 MVP 阶段可以快速交付"一键分析"的体验
- 性能优越（一次 R 进程内完成，无 IO 损耗）
**保留的部分：**
| 问题 | 说明 |
|------|------|
| **宏工具是"固定套餐"** | 用户的数据千变万化，预设的流程不可能覆盖所有情况 |
| **丧失"动态规划"能力** | 这是愿景中最核心的"智能"体现 |
| **用户无法干预中间步骤** | 愿景强调"人机协同"，宏工具做不到 |
**具体案例说明：**
```
宏工具能处理的场景（理想情况）：
────────────────────────────────
用户："分析这批临床试验数据"
系统：→ 调用 ST_MACRO_RCT_PIPELINE
→ 执行固定流程：Table1 → 缺失值填补 → T检验 → 森林图
→ 输出完整报告
✅ 完美！
宏工具处理不了的场景（现实情况）：
────────────────────────────────
用户："分析这批数据，但我的分组有3组，而且有协变量需要调整"
系统：→ 调用 ST_MACRO_RCT_PIPELINE
→ 宏工具内部写死的是 T检验（适用于2组）
→ 无法动态切换为 ANOVA（适用于3组）
→ 无法自动添加协变量调整
❌ 失败，或输出错误结果！
```
**这正是"自动化"与"智能化"的本质区别：**
| 维度 | 自动化（宏工具） | 智能化（动态规划） |
|------|-----------------|-------------------|
| 流程 | 预先固定 | 根据数据动态生成 |
| 方法 | 脚本编写时确定 | 执行时根据数据特征选择 |
| 用户干预 | 不支持 | 每一步可确认/修改/跳过 |
| 适应性 | 只能处理"标准情况" | 能处理各种边缘情况 |
---
### 2.3 不认可的观点 🔴
#### 观点："宏工具 = 实现智能化愿景"
**我的评价：** 🔴 **不认可**
**原因：**
愿景文档中描述的核心智能是"**分析路径规划师（Pathway Planner）**"：
> "系统像一位经验丰富的统计学家，根据您的研究目标和数据特征，自动规划最优的分析路径。"
这要求系统能够：
1. **动态生成**分析流程（而非使用预设模板）
2. **根据数据特征**调整每一步的方法
3. **让用户确认**每一步后再执行
而宏工具的本质是：
1. **预先编写好**的固定流程
2. **脚本内部硬编码**的方法选择
3. **一次性执行完毕**，用户无法干预
**打个比方：**
| 比喻 | 宏工具 | 动态规划 |
|------|--------|---------|
| 餐厅 | 套餐（A套餐、B套餐） | 自助餐 + 厨师现做 |
| 旅行 | 跟团游（固定行程） | 私人定制 + 导游随时调整 |
| 分析 | 固定模板报告 | AI 根据数据定制分析路径 |
**如果我们只做宏工具，用户会说："这和 SPSS 的批处理有什么区别？"**
---
## 三、对"智能化"的重新定义与分级
为了让讨论更加具体，我建议将"智能化"分为三个层级：
### 3.1 智能化分级模型
```
Level 3: 真·智能分析助手（愿景终态）
┌─────────────────────────────────────────────────────────────┐
│ 动态规划 + 分步执行 + 人机协同 + 自适应调整 │
│ 用户："分析这批数据" → 系统规划5步 → 每步确认 → 执行 │
└─────────────────────────────────────────────────────────────┘
▲
│
Level 2: 智能工具箱（审查建议）
┌─────────────────────────────────────────────────────────────┐
│ 意图理解 + 方法选择 + 宏工具套餐 + 论文输出 │
│ 用户："分析这批数据" → 系统选套餐 → 一键执行 → 输出报告 │
└─────────────────────────────────────────────────────────────┘
▲
│
Level 1: 自动化工具（传统软件）
┌─────────────────────────────────────────────────────────────┐
│ 用户选方法 + 填参数 + 点执行 + 看结果 │
│ 用户："我要做T检验" → 填参数 → 执行 → 看P值 │
└─────────────────────────────────────────────────────────────┘
```
### 3.2 各方案对应的智能化层级
| 方案 | 智能化层级 | 与竞品差距 |
|------|-----------|-----------|
| 当前 MVP（已完成部分） | Level 1.5 | 略优于 SPSS |
| 审查建议（宏工具方案） | Level 2 | 明显优于 SPSS |
| 愿景设计（动态规划） | Level 3 | 颠覆性领先 |
### 3.3 我的核心问题
> **我们要做 Level 2 还是 Level 3？**
>
> - 如果目标是 Level 2，审查建议完全足够
> - 如果目标是 Level 3，审查建议是过渡方案，不是终态
---
## 四、重新思考：基于代码智能范式的实现路径
> **注意：原有的"宏工具"方案基于工具调用范式，与我们的目标不兼容。以下是基于代码智能范式的新思路。**
### 4.1 核心能力建设
要实现代码智能范式，需要构建以下核心能力：
| 能力 | 描述 | 技术方案 |
|------|------|---------|
| **代码知识库** | 100+ R 代码模板，结构化存储 | RAG + 向量检索 |
| **代码理解** | LLM 理解 R 代码的功能和参数 | 代码注释 + Few-shot |
| **代码生成** | LLM 根据需求修改/组合代码 | Prompt Engineering |
| **代码执行** | 安全执行 LLM 生成的代码 | R 沙箱环境 |
| **结果解读** | LLM 解读统计结果 | 专业 Prompt |
### 4.2 建议的验证路径
在全面开发之前，建议先做 **Proof of Concept（概念验证）**：
```
POC 目标：验证 LLM 能否根据数据特征，从知识库检索并修改 R 代码
POC 场景：
─────────
输入：
- 用户问题："比较两组患者的疗效差异"
- 数据特征：两组、连续变量、样本量各 50、非正态分布
期望输出：
- LLM 从知识库检索 t_test.R 和 wilcoxon.R
- LLM 判断：非正态 → 选择 wilcoxon
- LLM 修改代码：填入正确的变量名
- 生成可执行的 R 脚本
- 执行并返回结果
验证标准：
- 方法选择正确率 > 90%
- 生成代码可执行率 > 95%
- 结果解读准确率 > 90%
```
### 4.3 分阶段实现建议
| 阶段 | 目标 | 核心能力 | 时间 |
|------|------|---------|------|
| **POC** | 验证技术可行性 | 单步代码生成 + 执行 | 1 周 |
| **MVP** | 基础智能分析 | 多步规划 + 代码生成 | 2-3 周 |
| **V1.1** | 增强人机协同 | 分步确认 + 修改建议 | 2 周 |
| **V2.0** | 完整智能助手 | 自动纠错 + 多轮对话 | 3-4 周 |
### 4.4 可保留的审查建议
虽然"宏工具"方案不适用，但以下建议与范式无关，可以保留：
| 建议 | 价值 | 是否采纳 |
|------|------|---------|
| 精华一：临床意图翻译 | 提升意图理解 | ✅ 采纳 |
| 精华四：前置数据诊断 | 提升用户体验 | ✅ 采纳 |
| 精华五：论文级结论生成 | 提升输出价值 | ✅ 采纳 |
| 精华二：决策表驱动 | 🟡 需改造 | 改为"知识库元数据" |
| 精华三：宏工具 | ❌ 与目标不兼容 | 不采纳 |
---
## 五、需要讨论的关键问题
在继续开发之前，我希望团队能够明确回答以下问题：
### 5.1 产品定位（已确认）
> **✅ 产品定位已明确：Level 3 —— 颠覆性的智能分析助手**
| 问题 | 我们的答案 |
|------|-----------|
| SSA-Pro 的目标是什么？ | **Level 3：颠覆性的智能助手** |
| 我们与竞品的差异化在哪里？ | **AI 动态规划分析路径 + 动态生成代码** |
| 用户愿意为什么付费？ | **解决"不会统计"的根本问题** |
| 100个 R 代码的用途？ | **知识库，供 LLM 学习和改写，不是固定工具** |
### 5.2 技术路径问题
| 问题 | 我的建议 |
|------|---------|
| MVP 是否采用宏工具方案？ | ✅ 采用（作为快速交付手段） |
| 宏工具是否是终态？ | ❌ 不是（后续需要演进到轻量级编排） |
| 何时开始 V1.1 的设计？ | 建议 MVP 发布后立即开始 |
### 5.3 资源投入问题
| 问题 | 需要团队确认 |
|------|-------------|
| R 工程师是否有能力编写宏工具脚本？ | 需要确认 |
| 前端是否有余力预埋分步展示 UI？ | 需要确认 |
| MVP 的交付时间是否有压力？ | 需要确认 |
---
## 六、总结与行动建议
### 6.1 我的核心观点
1. **审查建议存在根本性的理解偏差** —— 他们理解的是"工具调用"范式，而我们要做的是"代码智能"范式
2. **100个 R 代码是"知识库"，不是"工具箱"** —— LLM 要能理解、修改、组合这些代码
3. **智能化的核心是"动态生成"** —— LLM 根据数据特征动态修改代码，而不是调用固定工具
4. **宏工具方案与我们的目标不兼容** —— 它锁死了系统在 Level 2，无法演进到 Level 3
5. **我们需要重新设计技术架构** —— 基于"代码智能"范式，而非"工具调用"范式
### 6.2 建议的行动
| 行动 | 负责人 | 优先级 |
|------|--------|--------|
| **统一团队对"代码智能"范式的理解** | 全体 | 🔴 最高 |
| 重新设计系统架构（基于代码智能范式） | 架构师 | 🔴 最高 |
| 评估 LLM 代码生成/修改能力的可行性 | AI 工程师 | 🟡 高 |
| 采纳审查建议中与范式无关的精华（意图翻译、论文输出） | 开发团队 | 🟢 中 |
### 6.3 一句话总结
> **审查建议基于"工具调用"范式，而我们要做的是"代码智能"范式。**
>
> **我们的目标是：LLM 理解 R 代码知识库，根据用户数据动态修改/生成代码，实现真正的智能分析。**
>
> **不着急开发，但要把路想清楚。智能化是核心，否则这次开发就没有意义。**
---
## 七、代码智能范式的核心架构
既然我们明确了要做"代码智能"范式，那么系统架构需要重新设计：
### 7.1 核心架构图
```
┌─────────────────────────────────────────────────────────────────────────┐
│ SSA-Pro 代码智能架构 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ 用户自然语言 │───────▶│ 意图理解层 (LLM) │ │
│ │ "比较两组疗效" │ │ • 解析研究目的 │ │
│ └─────────────────┘ │ • 识别分析类型 │ │
│ │ • 提取关键变量 │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ 用户数据 │───────▶│ 数据诊断层 (LLM + R) │ │
│ │ (CSV/Excel) │ │ • 变量类型识别 │ │
│ └─────────────────┘ │ • 数据分布检测 │ │
│ │ • 缺失值/异常值诊断 │ │
│ │ • 统计前提检验 │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 路径规划层 (LLM) │ │
│ │ │ │
│ │ 输入：意图 + 数据特征 │ │
│ │ 输出：分析路径（多步骤） │ │
│ │ │ │
│ │ 步骤1: 描述性统计 │ │
│ │ 步骤2: 正态性检验 │ │
│ │ 步骤3: 方差齐性检验 │ │
│ │ 步骤4: T检验 或 秩和检验（动态） │ │
│ │ 步骤5: 效应量计算 │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ R 代码知识库 │◀──────│ 代码生成层 (LLM) │ │
│ │ (100+ 模板) │ 检索 │ │ │
│ │ │───────▶│ • 从知识库检索相关代码 │ │
│ │ • t_test.R │ │ • 根据数据特征修改代码 │ │
│ │ • anova.R │ │ • 组合多个代码片段 │ │
│ │ • wilcoxon.R │ │ • 生成完整可执行 R 脚本 │ │
│ │ • ... │ │ │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 执行层 (R Runtime) │ │
│ │ │ │
│ │ 执行 LLM 生成的代码 │ │
│ │ 返回结果（数值 + 图表） │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 结果解读层 (LLM) │ │
│ │ │ │
│ │ • 解读统计结果 │ │
│ │ • 判断是否需要下一步分析 │ │
│ │ • 生成论文级结论 │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 循环判断 │ │
│ │ │ │
│ │ 需要继续？──是──▶ 返回代码生成层 │ │
│ │ │ │ │
│ │ 否 │ │
│ │ ▼ │ │
│ │ 输出完整报告 │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 7.2 与"工具调用"范式的关键区别
| 环节 | 工具调用范式 | 代码智能范式 |
|------|-------------|-------------|
| **方法选择** | 从预设列表选择 | LLM 根据数据特征决定 |
| **参数填充** | 固定参数模板 | LLM 动态生成参数 |
| **代码执行** | 调用固定函数 | 执行 LLM 生成的代码 |
| **异常处理** | 预设的分支逻辑 | LLM 实时判断并调整 |
| **流程控制** | 线性或预设 DAG | LLM 动态决定下一步 |
### 7.3 技术可行性评估（需讨论）
| 能力 | 当前 LLM 水平 | 风险 | 缓解措施 |
|------|-------------|------|---------|
| 理解 R 代码 | ✅ 很强 | 低 | - |
| 修改 R 代码 | ✅ 较强 | 中 | 代码审查 + 沙箱执行 |
| 生成正确 R 代码 | 🟡 中等 | 中高 | 知识库约束 + 结果校验 |
| 解读统计结果 | ✅ 很强 | 低 | - |
| 动态决策下一步 | ✅ 较强 | 中 | 明确的决策规则 |
### 7.4 需要解决的关键技术问题
1. **代码知识库的组织方式** —— 如何让 LLM 高效检索相关代码？
2. **代码生成的准确性** —— 如何确保生成的代码是正确的？
3. **执行安全性** —— 如何在沙箱中安全执行 LLM 生成的代码？
4. **错误恢复** —— 如果生成的代码执行失败，如何让 LLM 自动修复？
5. **人机协同点** —— 在哪些环节需要用户确认？
---
## 八、附录：智能化能力达成对照表
| 智能化能力 | 愿景要求 | 工具调用范式 | 代码智能范式 |
|-----------|---------|-------------|-------------|
| 理解医生意图 | ✅ | ✅ 可达成 | ✅ 可达成 |
| 自动选择方法 | ✅ | 🟡 有限（预设列表） | ✅ 动态决策 |
| 动态规划流程 | ✅ | ❌ 固定流程 | ✅ **LLM 动态规划** |
| 适应数据特征 | ✅ | ❌ 固定参数 | ✅ **LLM 修改代码** |
| 分步展示过程 | ✅ | ❌ 一次输出 | ✅ 可分步展示 |
| 用户可干预步骤 | ✅ | ❌ 不支持 | ✅ 支持 |
| 论文级输出 | ✅ | ✅ 可达成 | ✅ 可达成 |
**工具调用范式达成率：40%（3/7 核心能力）**
**代码智能范式达成率：100%（7/7 核心能力）**
---
## 九、结语
本文档的核心目的是**统一团队对 SSA-Pro 智能化方向的理解**。
### 我们必须达成的共识：
1. **产品定位**：Level 3 颠覆性智能助手，不是 Level 2 智能工具箱
2. **技术范式**：代码智能范式，不是工具调用范式
3. **R 代码定位**：知识库 / 参考模板，不是固定工具
4. **LLM 角色**：代码理解者 + 改写者 + 决策者，不是参数填充器
5. **核心能力**：动态规划 + 动态生成，不是固定套餐
### 下一步讨论议题：
1. 代码智能范式的技术可行性验证（Proof of Concept）
2. R 代码知识库的组织与检索方案
3. LLM 代码生成的准确性保障机制
4. 人机协同的交互设计
---
*文档结束*
*不着急开发，先把路想清楚。智能化是核心，否则这次开发就没有意义。*
*期待与团队的深入讨论！*

76
docs/03-业务模块/SSA-智能统计分析/06-开发记录/架构审查报告：Phase 2A 核心开发计划 .md Normal file
View File

@@ -0,0 +1,76 @@
# **架构审查报告：Phase 2A 智能化核心开发计划**
**审查对象：** 《07-Phase2A-智能化核心开发计划.md》
**审查时间：** 2026-02-20
**审查结论：** 🌟 **极度卓越 (S级计划)**。战略聚焦精准，架构切分合理。准予作为下阶段最高优先级执行，但需注意防范三大工程暗礁。
## **一、 架构师的高度赞同 (What You Did Exceptionally Well)**
### **1\. 极其明智的“断舍离” (Postponing the Config Center)**
把“配置中台”和“100个工具的量产”延后，是整个计划最亮眼的一笔。
在核心编排逻辑（Orchestration）跑通之前，去开发配置中台的 UI 是纯粹的浪费。在 Phase 2A 阶段，**“配置即代码 (Configuration as Code)”** 是最佳实践。直接用 TypeScript/JSON 文件来硬编码这 7 个工具的配置，速度最快，修改成本最低。
### **2\. 五大组件的精妙解耦 (The 5-Component Agentic Pipeline)**
你们将原本耦合的 Planner 拆分成了 Data Profiler \-\> Intent Parser \-\> Tool Router \-\> Plan Generator \-\> Result Synthesizer。
这是教科书级别的 **大模型工作流 (LLM Workflow) 设计**！大模型在处理单一、确定性任务时幻觉极低。将一个庞大的 Prompt 拆分成 5 个职能单一的微型 Prompt，是保证系统每次都能输出稳定 SAP 计划的唯一解。
### **3\. 完美的“7 剑客”工具选型 (The Golden 7 Tools)**
选出的 7 个工具（基线表、正态、T检验、秩和、卡方、相关、线回）不是随便挑的，它们恰好构成了一个完整的\*\*“临床基线分析 \+ 单因素推断”\*\*的业务闭环。如果能把这 7 个串联好，已经能解决医学研究生 60% 的毕业论文统计需求。
## **二、 工程暗礁与避坑预警 (Critical Warnings & Gotchas)**
计划虽好，但在具体写代码时，这 5 大组件和多工具串联极容易在以下三个地方“翻车”：
### **🚨 暗礁 1：Result Synthesizer 的“上下文爆炸” (Context Window Blowup)**
* **计划描述**：将多个工具的执行结果收集起来，交给 Result Synthesizer (LLM) 生成综合结论。
* **潜在灾难**：R 语言跑出来的原始 JSON 可能极大。比如做线性回归，如果把几百个残差值（Residuals）或者巨大的离群值数组都打包成 JSON 发给大模型，会导致 LLM Token 超载，响应极慢甚至直接报错。
* **架构强制要求**：
在封装这 7 个 R 工具时，**必须严格限制 R 脚本的输出规模**。R 脚本返回的 JSON 只能包含：P值、统计量 (t/F/chi-sq)、置信区间、核心系数 和 前端渲染图表所需的精简坐标点。**绝对禁止返回包含原始全量数据的长数组。**
### **🚨 暗礁 2：Data Profiler 的“Node.js 内存刺客” (The Node.js OOM Trap)**
* **计划描述**：Data Profiler 需要提取数据特征（如均值、缺失率）。
* **潜在灾难**：如果由后端的 Node.js 去遍历解析 50MB 的 CSV 来算均值和缺失率，Node.js 极易发生 OOM（内存溢出）导致容器崩溃。
* **架构强制要求 (已修正为 Python 方案)**：
不要在 Node.js 里做重度数据探测！**强烈建议复用团队现有的“工具C (Python 智能数据清洗模块)”** 来充当 Data Profiler 的物理执行层。
工作流应该是：用户上传数据 \-\> Node.js 调起 **Tool C 的 Python 微服务** 执行高并发的数据探测 \-\> 快速返回各列的数据类型、缺失率、枚举值分类 \-\> 将这个轻量级的 Schema JSON 喂给 LLM 规划师。
*(注：Tool C 的 Pandas/Polars 在处理数十 MB CSV 的 I/O 和基础统计上，性能远超 R，且完全复用了团队已有的异步架构与性能优化资产，完美实现了“Python 主内搞数据，R 主外做统计”的分工。)*
### **🚨 暗礁 3：多工具编排中的“半路崩盘” (Partial Failure Handling)**
* **计划描述**：Plan Generator 制定好顺序（如：正态检验 \-\> T检验），然后依次执行。
* **潜在灾难**：如果第一步“基线表”跑成功了，第二步“T检验”因为某个极端数据报错了，整个流程是全部崩溃，还是能保留基线表的结果？
* **架构强制要求**：
在设计流程执行器（Executor）时，必须采用 **“容错管道 (Fault-Tolerant Pipeline)”**。
任何一个工具报错，不应该导致整个 Workspace 崩溃。系统应该能在右侧 UI 渲染出：
✅ 基线表 (执行成功, 点击查看)
❌ T检验 (执行失败: 方差为0, 点击查看原因)
让用户依然能拿到部分成果，这才是顶级商业软件的体验。
## **三、 对 Phase 2A 代码落地的一点补充建议**
为了配合 V11 双屏前端原型的“魔法效果”，建议在后端的串联逻辑中加入 **“Server-Sent Events (SSE) 状态推送”**：
当后端正在顺序执行这 7 个工具时，不要让前端傻等 10 秒钟。后端执行完一个工具，就通过 SSE 往前端推一个状态：
1. {"status": "running", "step": "ST\_TABLE1", "msg": "正在绘制基线特征表..."}
2. {"status": "running", "step": "ST\_NORMALITY", "msg": "正在执行 Shapiro-Wilk 正态性检验..."}
3. {"status": "completed", "final\_report": {...}}
前端接收到这些状态后，就能在 V11 原型的 ExecutionViewer（那个黑色的终端日志框）里一行行打出逼真的执行日志，**这不仅安抚了用户的等待焦虑，更把系统的“专业AI感”直接拉满**。
## **四、 总结**
你们的 Phase 2A 计划是一份直指问题核心的“作战地图”。
去掉了“配表”的枯燥，直面“AI 编排”的挑战，并且聪明地联动了已有的 Python 资产。只要在数据探测和结果回传上做好**数据量的裁剪（卡死 Token 上限）**，这个 Phase 2A 交付后，SSA-Pro 将真正在技术上具备叫板主流数据分析 AI Agent 的底气。
**同意按此计划全面打响 Phase 2A 战役！祝团队旗开得胜！**

80
docs/03-业务模块/SSA-智能统计分析/06-开发记录/架构审查报告：SSA-Pro 愿景与落地策略.md Normal file
View File

@@ -0,0 +1,80 @@
# **架构委员会独立审查报告：SSA-Pro 智能化愿景与落地策略**
**审查对象：** 《SSA-Pro 理想状态与智能化愿景设计》、《愿景与开发计划对比分析》
**审查时间：** 2026-02-20
**核心裁决：** 🟢 愿景极度认可，🔴 反对开发计划的推翻重来。建议采用“宏工具（Macro-Tool）降维打击”策略。
## **1\. 核心审查结论 (Executive Summary)**
1. **愿景评估 (Vision)**：提出“医生要的是完整流程，而不是单个统计工具”的洞察**极其精准**，这是 SSA-Pro 未来能在市场上降维打击竞品的**核心壁垒**。
2. **差距评估 (Gap)**：文档中指出的现有 MVP 计划与理想状态的差距是客观存在的（单节点执行 vs 多节点编排）。
3. **落地路径评估 (Execution) \- 🚨 警告**：文档建议“新增 Phase 1.5，耗时 12-18 天开发流程执行引擎”，**我作为架构师坚决反对**。在底层原子工具（T检验、卡方等）尚未经受生产环境大规模数据考验时，去构建一个复杂的 DAG（有向无环图）流程编排引擎，会导致项目陷入无底洞，MVP 交付将遥遥无期。
## **2\. 为什么坚决反对现在做“流程执行引擎”？(架构风险剖析)**
团队文档中低估了“多方法流程编排 (Workflow Orchestration)”的技术复杂度：
1. **状态爆炸与数据流转 (Data Pipeline)**：
* 如果 Node.js 作为流程引擎，执行 A(数据清洗) \-\> B(特征筛选) \-\> C(T检验)。这意味着 R 容器执行完 A 后，要将几百 MB 的中间态数据回传给 Node/OSS，Node 再传给步骤 B的 R 容器。这会带来巨大的 IO 延迟和序列化灾难。
2. **错误处理灾难 (Error Recovery)**：
* 流程走到第 4 步报错了，怎么回滚？UI 上怎么展示？用户修改参数后，是从第 4 步断点续传，还是从头重跑？
3. **前端 UI 极度复杂化**：
* 我们刚刚通过 V11 稳定了双屏 UI，如果引入流程节点，右侧面板需要变成类似 ComfyUI 或 Coze 的节点连线界面，工作量是按“月”计算的。
## **3\. 破局之道：以“大工具 (Macro-Tool)”降维打击**
我们既要满足用户的终极愿景（一键生成论文级完整报告），又要保住现有的工程架构（单方法执行）。
**解决思路：将“流程编排的复杂度”从 Node.js / 前端下沉到 R 代码内部。**
不要在 Node.js 中编排流程，而是定义一批 **“复合型宏工具 (Macro-Tools)”**。
### **举个例子对比：**
* **愿景文档的思路（沉重的引擎）**：
Node.js 引擎调度 \-\> 调用基础基线表工具 \-\> 等待 \-\> 调用缺失值填补工具 \-\> 等待 \-\> 调用T检验工具 \-\> 等待 \-\> 调用多因素回归工具 \-\> 合并输出。
* **架构师建议的思路（轻量级宏工具）**：
1. 在配置中台中，除了配置基础的“T检验 (ST\_T\_TEST)”，新增一个超级工具叫 **“RCT 临床试验全流程标准分析 (ST\_MACRO\_RCT\_PIPELINE)”**。
2. 这个超级工具对应一段长达 200 行的 R 脚本 (rct\_pipeline.R)。
3. 这段 R 脚本在**一次容器运行中**，顺序执行：画 Table 1 \-\> 数据清洗 \-\> 分组比较 \-\> 敏感性分析 \-\> 统一输出为 Markdown 或一个巨大的 JSON。
4. Node.js 和前端**完全不需要改架构**，在它们眼里，这依然只是一次普通的“工具调用”。
### **这种方案的巨大红利：**
| 维度 | 构建通用流程引擎 (不推荐) | 构建 R 宏工具脚本 (推荐) |
| :---- | :---- | :---- |
| **开发工时** | 3 \- 4 周 (前后端全改) | **2 \- 3 天** (写几段 R 聚合脚本即可) |
| **性能损耗** | 极高 (不断的容器启停和 IO) | **极低** (一次 R 进程内全内存计算) |
| **智能理解** | LLM 需要输出复杂的 DAG JSON | LLM 只需要路由到该“宏工具” |
| **用户体验** | 看到复杂的节点执行 | 点击执行后，一键输出终极报告 (符合预期) |
## **4\. 对现有开发计划的微调建议 (Action Items)**
**结论：不要推翻原有的 《00-MVP开发计划总览.md》，原计划完全有效，只需做以下三点微调：**
### **调整 1：扩展“配置中台”的概念 (Phase 1\)**
在开发基础统计工具（T检验、卡方等）的同时，由数据分析师/R工程师编写 3-4 个\*\*“场景化宏脚本”\*\*。例如：
* ST\_SCENARIO\_SURVIVAL (生存分析标准全流程：KM曲线 \+ Log-rank \+ 单因素Cox \+ 多因素Cox)
* ST\_SCENARIO\_CLINICAL\_TRIAL (临床试验疗效评估标准流程：Table1 \+ 主效应检验 \+ 亚组森林图)
### **调整 2：增强 Planner 智能体的路由能力 (Phase 2\)**
修改 Planner (大模型) 的 System Prompt：
"当用户的问题非常具体且单一（如：比较这两列的均值），请推荐基础统计工具（如 ST\_T\_TEST）。当用户的问题是一个宏大的研究目标（如：看看新药有没有效、帮我分析这批高血压数据），请直接推荐场景化宏工具（如 ST\_SCENARIO\_CLINICAL\_TRIAL）。"
### **调整 3：UI 展示层的包容性 (与 V11 完美契合)**
V11 的双屏 UI 已经完美支持这种宏大结果的展示。宏工具执行完毕后，返回的是一个包含了多个表格和多张图表的复杂 JSON。右侧工作区利用 ResultViewer 顺序渲染这些组件即可，这正是双屏设计大显身手的地方。
## **5\. 架构师致团队的总结寄语**
向提出智能化愿景的团队成员致敬！你们看到了星辰大海。
但软件工程的艺术在于\*\*“用最简单的结构解决最复杂的问题”**。我们通过**把复杂的流程固化为 R 脚本模板（宏工具）\*\*，成功地避免了造一个沉重的 Node.js 工作流引擎的陷阱。
**无需推翻重来！请团队按照原定 MVP 计划继续冲刺，只需在 R 代码库中增加几个“全家桶套餐”级别的脚本，我们就能在 MVP 阶段交付你们渴望的“智能化愿景”！**

140
docs/03-业务模块/SSA-智能统计分析/06-开发记录/终极架构共识与智能化演进备忘录 (1).md Normal file
View File

@@ -0,0 +1,140 @@
# **SSA-Pro 终极架构共识与智能化演进备忘录**
**文档性质：** 架构争论复盘与终极演进路线图
**审查对象：** 团队反馈文档《SSA-Pro 架构审查反馈与智能化路径讨论》
**审查时间：** 2026-02-20
**核心定调：** 🟢 完全认同团队的终极愿景；🔴 对“动态执行生成代码”的安全与稳健性提出最高级别警告；🤝 提出“受限代码生成”作为完美桥梁。
## **一、 架构师的“认错”与全面致敬 (What I Completely Agree With)**
首先，我要向团队致敬。你们指出的核心分歧点——**“高级版的 SPSS 菜单（Tool Calling）” vs “真正的 AI 数据分析师（Code Intelligence）”**，一针见血。
1. **认同“静态参数的局限性”**：
你们是对的。临床数据极其肮脏和复杂（需要衍生变量、按条件过滤、合并清洗）。如果只依赖简单的 JSON 参数映射，一旦用户说“帮我把年龄大于 60 岁的人挑出来，再把血压分为高低两组，然后做个生存分析”，基于 Tool Calling 的架构会瞬间瘫痪，因为它无法在参数里表达这种动态的数据操作。
2. **认同“100 个 R 脚本的真实定位”**：
将这 100 个脚本视为\*\*“可学习的范例库（Knowledge Base / Code Templates）”\*\*，而不是死板的 API 工具，这是一个认知上的巨大飞跃。这让系统的天花板从“自动化”提升到了“智能化”。
3. **认同“三阶段演进策略”**：
你们提出的 Phase 1 (工具调用兜底) \-\> Phase 2 (宏脚本执行) \-\> Phase 3 (代码智能) 是极其成熟的务实主义。我们不仅没有分歧，反而达成了高度的战略共识。
## **二、 架构师的“红线”警告 (Where I Strongly Push Back / Warn)**
作为对系统稳定性负责的架构师，针对你们心心念念的 **“Phase 3: Code Intelligence (执行 LLM 动态生成的代码)”**，我必须亮出工程红线。
这是整个业界（包括 OpenAI）都在面临的最难的骨头，切不可低估其危险性。
### **🚨 风险 1：动态代码执行的“核弹级”安全漏洞 (RCE Vulnerability)**
* **团队设想**：LLM 生成 R 代码 \-\> 在沙箱中执行。
* **残酷现实**：如果在常规的 Docker 容器中直接使用 R 的 eval(parse(text=llm\_code)) 或者将生成的代码写入文件运行，哪怕你做了所谓的文件权限限制，**这本质上依然是一个合法的 RCE (远程代码执行) 后门**。
* **后果**：大模型极易被“提示词注入（Prompt Injection）”攻击，生成类似于窃取环境变量、发起内网 DDoS 或占用全部 CPU 资源的恶意代码。
* **架构底线**：在没有引入 **Firecracker 级别的微虚拟机（MicroVM）** 或严格的 **eBPF 系统调用拦截**之前，**绝对禁止**在生产环境中执行 LLM 自由发挥生成的 R 代码。
### **🚨 风险 2：统计学的“幻觉谬误”与合规灾难**
* **团队设想**：LLM 可以根据数据特征动态修改/组合统计代码。
* **残酷现实**：LLM 在写 Python 的 pandas 时很强，但在写深度的医学统计 R 代码时，非常容易产生“看似合理实则谬误”的幻觉（比如错误地设置了随机效应项，或者用错了极大似然估计方法）。
* **后果**：系统生成了 P 值，用户信了，发了论文，最后发现统计算法是错的。在医疗领域，这是致命的声誉打击。
* **架构底线**：涉及 P 值计算的核心统计引擎（如 wilcox.test 的参数配置），必须保留经过人类专家验证的“硬护栏”，绝不能任由大模型自由发挥。
## **三、 破局方案：“受限代码生成”范式 (The Architect's Bridge)**
为了兼顾你们想要的“灵活性（处理复杂数据操作）”和我要的“安全性（护栏与可审计）”，我提出 **“受限代码生成 (Constrained Code Generation)”** 架构。这是连接 Phase 1 和 Phase 3 的完美桥梁。
### **核心思想：把代码切分为“安全区”和“高危区”**
我们将用户的分析诉求分为两截：**【数据加工 (Data Wrangling)】** 和 **【核心检验 (Core Stats)】**。
#### **1\. 安全区：数据加工 (允许大模型自由发挥)**
* **场景**：过滤、重命名、衍生变量（如算 BMI）。
* **机制**：允许 LLM 基于 dplyr 生成 R 代码（这部分代码就算有幻觉，最多就是报错，不会产生错误的 P 值）。
* **安全措施**：使用 R 的 AST (抽象语法树) 解析器，在执行前扫描这段生成的代码，**白名单制**仅允许 mutate, filter, select, group\_by 等数据操作函数，发现任何可疑函数直接阻断。
#### **2\. 高危区：核心检验 (大模型仅能“填空”)**
* **场景**：跑 T 检验、画 KM 曲线。
* **机制**：LLM **不被允许**生成核心检验代码。它必须从你们那 100 个脚本库中，把“专家写好的模板”检索出来，然后把第一步处理好的数据输入进去。
### **💡 “受限代码智能”工作流示例**
1. **用户输入**：“把年龄大于 60 岁的人挑出来，算一下男女的血压差异。”
2. **LLM 理解与检索**：
* 检索到专家模板：ST\_T\_TEST\_IND.R。
3. **LLM 生成混合计划 (Hybrid Plan)**：
{
"data\_wrangling\_code": "df\_filtered \<- df %\>% filter(Age \> 60)",
"core\_tool": "ST\_T\_TEST\_IND",
"core\_params": { "group\_col": "Gender", "val\_col": "BloodPressure" }
}
4. **Executor 执行**：
* 在沙箱内，先行安全校验并执行 data\_wrangling\_code。
* 将清洗后的 df\_filtered 送入经过专家配置、带有强护栏的 ST\_T\_TEST\_IND 工具中执行。
**为什么这个方案好？**
它给了大模型处理复杂现实数据的\*\*“手脚”（数据清洗代码生成）**，但牢牢锁住了大模型的**“嘴巴”（核心统计检验的绝对严谨性）\*\*。
## **四、 针对 MVP 阶段的具体行动建议 (Action Items for NOW)**
既然我们对“三阶段演进”达成了共识，那么在眼下的 MVP 阶段，请务必执行以下微调：
### **1\. 改变 Prompt 的“世界观”**
在构建 Planner 的 Prompt 时，不要对 LLM 说“你是一个从列表里挑工具的接线员”，而是对它说：
"你是一个顶尖的数据科学家。你现在有一个包含 100 个高级统计算法的**专家代码库**。请理解用户意图，从代码库中找出最合适的代码模板，并制定数据传入策略。"
*(即便它现在只能输出 JSON 参数，这种世界观设定也会极大地提高它的推理质量。)*
### **2\. 构建向量库时，保留“代码片段”**
在专家填写 Excel 配置表时，不仅仅存入“工具名”和“适用场景”，把那 100 个 R 脚本的\*\*核心源代码片段（Core Snippet）\*\*也存入向量库。
在 RAG 检索时，把这些代码片段丢给 LLM。这为未来平滑过渡到 Phase 3 埋下伏笔。
### **3\. 先不碰动态代码执行**
MVP 阶段（乃至整个 Phase 2），请严格克制住“让 LLM 动态写代码并执行”的冲动。用我们确定的“混合模式（智能分析 \+ 宏脚本）”打透核心业务流，验证 PMF（产品市场契合度）。
## **五、 最终建议**
作为系统架构师，我必须为您详细拆解为什么在现阶段（MVP及打透核心业务流阶段）必须**严格克制**这种冲动：
### **1\. 安全层面的“达摩克利斯之剑”（RCE 风险）**
让 LLM 动态写代码并执行，本质上是在您的服务器上开了一个 **RCE（远程代码执行）** 的后门。
* 即使我们有那 100 个安全的脚本作为“参考库”，LLM 在修改时，极易受到恶意用户的“提示词注入（Prompt Injection）”攻击。
* 比如用户在上传的 CSV 数据里或者需求里藏入恶意指令，诱导 LLM 生成 `system("rm -rf /")` 或者窃取服务器环境变量的代码。如果没有极其昂贵和复杂的微虚拟机（MicroVM，如 Firecracker）做硬件级隔离，普通的 Docker 容器一旦被攻破，后果不堪设想。
### **2\. 医学统计的“静默谬误”（幻觉与合规灾难）**
在医疗和临床科研领域，**“跑通了”不等于“算对了”**。
* LLM 生成的代码哪怕语法完全正确，没有报错（Bug-free），它在统计学逻辑上也可能产生“幻觉”。
* 例如，它在拼接两段代码时，可能忘记了检查数据是否符合正态分布，或者搞错了混合效应模型的随机截距项。
* 这种错误极其隐蔽（静默谬误），系统会依然输出一个漂亮的 P 值。如果医生拿着这个错误的 P 值去发论文、做临床决策，一旦被查出，将会对您的平台声誉造成毁灭性打击。
### **3\. 运维与排错的“无底洞”（不可复现性）**
* 如果系统是由预设的“宏脚本”和“固定工具”组成的，当用户报 Bug 时，您可以立刻定位：“哦，是 T 检验的脚本第 45 行出错了”，您可以轻松修复。
* 如果代码是 LLM 每次**动态生成**的，那么每次执行的代码都是“阅后即焚”的孤品。一旦报错，您根本无法复现当时的场景，调试和维护成本将呈现指数级爆炸。
---
### **为什么我坚持用“混合模式（智能分析 \+ 宏脚本）”？**
因为这是一种 **“用大模型的智商，用人类专家的底线”** 的降维打击策略：
1. **大模型只做决策（不动手）**：让 LLM 做它最擅长的事——理解医生意图，阅读列名，从这 100 个工具里**选出最合适的一个或几个**，并把参数（JSON）填好。
2. **人类专家代码执行（守底线）**：真正跑计算的，是您的 R 工程师和统计专家精心打磨过、经过千百次测试的固定脚本（包括把多个固定脚本串联起来的“宏脚本套餐”）。
3. **用户体验完美**：在用户看来，他依然是“说了一句话，AI 帮他搞定了一切（哪怕是极度复杂的全流程）”，用户体验并没有打折，但背后的工程安全性提升了一万倍。
**总结来说：** 将那 100 个代码文件作为“可供 LLM 学习和动态修改的范例库”，这是极其超前的愿景，我们可以把它放在 **Phase 3（未来的终极形态）** 去探索。
但在眼下，我们要**打透核心业务流、让产品安全上线并赢得医生信任**，就必须将这 100 个文件视为“不可篡改的执行组件”。大模型可以作为调度员指挥它们，但绝不能赋予大模型在手术台上“随意切改代码”的权力。