HaHafeng
8137e3cde2
Summary: - Add PRD and architecture design V4 (Brain-Hand model) - Complete 5 development guide documents - Pass 3 rounds of team review (v1.0 -> v1.3) - Add module status guide document - Update system status document Key Features: - Brain-Hand architecture: Node.js + R Docker - Statistical guardrails with auto degradation - HITL workflow: PlanCard -> ExecutionTrace -> ResultCard - Mixed data protocol: inline vs OSS - Reproducible R code delivery MVP Scope: 10 statistical tools Status: Design 100%, ready for development Co-authored-by: Cursor <cursoragent@cursor.com>
225 lines
10 KiB
Markdown
225 lines
10 KiB
Markdown
# **SSA-Pro: 严谨型智能统计分析架构设计方案 (V4.0)**
|
||
|
||
**文档版本：** v4.0 (Final Comprehensive Edition)
|
||
|
||
**创建日期：** 2026-02-06
|
||
|
||
**最后更新：** 2026-02-06
|
||
|
||
**核心理念：** **白盒化 (White-box)**、**严谨性 (Rigor)**、**透明交付 (Transparency)**
|
||
|
||
**架构特征：** 同步 HTTP 微服务 \+ RAG 工具检索 \+ 统计护栏 \+ 人机回环 (HITL) \+ 代码交付
|
||
|
||
## **1\. 执行摘要 (Executive Summary)**
|
||
|
||
### **1.1 项目背景**
|
||
|
||
壹证循科技拥有近百种经久考验的 R 语言统计工具（ST模块），这是我们的核心资产。随着 AI Agent 技术的发展，我们致力于将这些“静态工具”升级为“智能统计伙伴 (SSA)”，以降低临床医生的科研门槛。
|
||
|
||
### **1.2 核心决策演进**
|
||
|
||
经过多轮技术选型与研报论证，我们的架构经历了三次关键迭代：
|
||
|
||
1. **SSA-Lite (V1)**: 追求极致速度，采用同步 HTTP API，摒弃了重型的异步队列架构（针对 \<2MB 小数据场景）。
|
||
2. **SSA-Pro (V2)**: 引入行业研报建议，增加 **RAG 工具检索**（解决百种工具调度难）和 **统计护栏**（防止滥用统计方法）。
|
||
3. **SSA-WhiteBox (V3/V4)**: 引入 **人机回环 (HITL)** 和 **代码交付**，将“黑盒 AI”转变为“透明导师”，解决医疗场景下的信任与合规问题。
|
||
|
||
### **1.3 最终方案价值主张**
|
||
|
||
SSA-Pro V4 不是一个简单的“代码生成器”，而是一个\*\*“懂统计、守规矩、乐于分享”的智能分析师\*\*：
|
||
|
||
* **懂统计**：先写计划 (SAP)，再做分析，就像真正的统计师一样。
|
||
* **守规矩**：强制执行正态性、方差齐性等前置检查，不满足条件自动警告。
|
||
* **乐于分享**：不仅给结果，还给**可复现的 R 代码**，支持医生本地二次运行。
|
||
|
||
## **2\. 为什么选择这套架构？(Architecture Rationale)**
|
||
|
||
在确定技术路线前，我们对三种主流方案进行了深度对比：
|
||
|
||
| 维度 | 方案 A: 异步队列 (pg-boss) | 方案 B: 纯 LLM 代码生成 (Open Interpreter) | 方案 C: SSA-Pro V4 (本方案) |
|
||
| :---- | :---- | :---- | :---- |
|
||
| **核心机制** | 提交任务 \-\> 排队 \-\> 轮询结果 | LLM 现场写 Python/R 代码 \-\> 沙箱执行 | **LLM 调参 \-\> R 标准库执行** |
|
||
| **交互体验** | 🐢 慢 (异步断裂感) | 🚀 快 (但不可控) | **⚡ 极速 (同步对话感)** |
|
||
| **准确性** | ✅ 高 (使用固定脚本) | ❌ 低 (容易幻觉、语法错误) | **✅ 极高 (护栏 \+ 预验证)** |
|
||
| **数据隐私** | 🟡 数据需落地 OSS | 🔴 数据需传给 LLM (高风险) | **🟢 数据/认知分离 (最高级)** |
|
||
| **落地难度** | 🔴 重 (需维护队列/状态) | 🟡 中 (需维护复杂沙箱) | **🟢 中 (需封装 R 接口)** |
|
||
|
||
**决策结论：**
|
||
|
||
针对医疗科研中 90% 的 **探索性数据分析 (EDA)** 场景（数据量 \< 2MB），**SSA-Pro V4 (同步微服务 \+ 工具调用模式)** 是平衡体验、安全与成本的最优解。
|
||
|
||
## **3\. 系统架构蓝图 (System Blueprint)**
|
||
|
||
本架构严格遵循 **"Brain-Hand"** 分离原则，并增加了 **"User Check"** 环节。
|
||
|
||
graph TD
|
||
User\[用户 (React Chat)\] \--\>|1. 上传 Data Schema (无敏感数据)| Node\[Node.js 后端 (Brain)\]
|
||
User \--\>|1b. 上传真实 CSV (仅用于执行)| R\_Service\[R Plumber 服务 (Hand)\]
|
||
|
||
subgraph "Phase 1: 认知与规划 (Cognitive Layer)"
|
||
Node \--\>|2. 意图识别| LLM\_Plan\[DeepSeek-V3 (Planner)\]
|
||
Node \--\>|3. 语义检索 (pgvector)| VectorDB\[(Tools Knowledge Base)\]
|
||
VectorDB \--\>|4. 返回 Top-5 工具定义| Node
|
||
Node \--\>|5. 生成 SAP & 推荐参数| LLM\_Plan
|
||
Node \--\>|6. 返回 \[分析预习卡片\]| User
|
||
end
|
||
|
||
subgraph "Phase 2: 确认与执行 (Execution Layer)"
|
||
User \--\>|7. 点击 \[确认执行\]| Node
|
||
Node \--\>|8. HTTP POST /run (Params Only)| R\_Service
|
||
|
||
R\_Service \--\>|9. 路由分发| Wrapper\[工具适配层\]
|
||
|
||
subgraph "R Runtime (Network Isolated)"
|
||
Wrapper \--\>|10. 记录执行路径 (Trace)| TraceLog
|
||
Wrapper \--\>|11. 统计护栏 (Guardrails)| CoreTools
|
||
CoreTools \--\>|12. 核心计算| CoreTools
|
||
CoreTools \--\>|13. 生成复现代码| CodeGen
|
||
end
|
||
|
||
Wrapper \--\>|14. 结果包 (Result+Trace+Code)| R\_Service
|
||
end
|
||
|
||
subgraph "Phase 3: 反思与交付 (Reflection Layer)"
|
||
R\_Service \--\>|15. 原始结果| Node
|
||
Node \--\>|16. 结果解释 (Conservative)| LLM\_Critic\[DeepSeek-V3\]
|
||
LLM\_Critic \--\>|17. 最终报告 \+ R代码下载| User
|
||
end
|
||
|
||
## **4\. 核心业务流程详解**
|
||
|
||
### **4.1 步骤一：智能规划 (The Planner)**
|
||
|
||
**解决痛点：** 100 个工具怎么选？
|
||
|
||
* **动作**：
|
||
1. 用户输入自然语言需求。
|
||
2. 系统提取关键词，在 tools\_library 向量库中检索 Top-5 相关工具。
|
||
3. LLM 基于检索结果，生成 **统计分析计划 (SAP)**。
|
||
* **产出**：不仅是选工具，而是生成一份严谨的计划书（含分析目标、方法选择理由、假设验证条件）。
|
||
|
||
### **4.2 步骤二：人机回环确认 (HITL Confirmation)**
|
||
|
||
**解决痛点：** AI 瞎跑，用户不敢信。
|
||
|
||
* **动作**：在执行代码前，系统弹出一个 **“分析预习卡片”**。
|
||
* **卡片内容**：**📊 分析方案预览：独立样本 T 检验**
|
||
* **目标**：比较吸烟组与非吸烟组的 BMI 差异
|
||
* **参数**：Group=Smoke, Value=BMI
|
||
* **前置检查**：将自动执行 Shapiro-Wilk 正态性检验。
|
||
* **降级策略**：若正态性不满足，自动切换为 Wilcoxon 检验。
|
||
|
||
\[ 🛠️ 修改参数 \] **\[ ✅ 确认并执行 \]**
|
||
|
||
### **4.3 步骤三：透明化执行与护栏 (Transparent Execution)**
|
||
|
||
**解决痛点：** 统计滥用 (P-hacking)。
|
||
|
||
* **动作**：
|
||
1. **统计护栏 (Guardrails)**：R 代码强制执行前置检查（如正态性、方差齐性）。如果检查失败，代码会自动记录日志并可能切换方法（降级）。
|
||
2. **路径可视化 (Trace)**：前端展示执行树。
|
||
├─ 🔍 正态性检验: P=0.23 (通过)
|
||
├─ 🔍 方差齐性检验: P=0.45 (通过)
|
||
└─ 🚀 执行 T 检验: t=2.5, P=0.012
|
||
|
||
### **4.4 步骤四：代码交付与解释 (Handover & Critic)**
|
||
|
||
**解决痛点：** 结果不可复现，P 值过度解读。
|
||
|
||
* **动作**：
|
||
1. **代码生成**：R Wrapper 根据本次执行的参数，拼接出一份**可独立运行**的 .R 脚本，供用户下载。
|
||
2. **保守解释**：Critic Agent (DeepSeek) 将结果翻译成人话，严禁使用“证明了”等绝对词汇，强调置信区间。
|
||
|
||
## **5\. 关键技术实现细节**
|
||
|
||
### **5.1 元数据工程 (Metadata Engineering)**
|
||
|
||
这是连接 R 和 AI 的桥梁。我们不手动写 JSON，而是从 R 代码注释中自动提取。
|
||
|
||
**R 代码规范 (roxygen2 风格):**
|
||
|
||
\#' @title 执行独立样本T检验
|
||
\#' @description 比较两组独立正态分布数据的均值差异。
|
||
\#' @usage\_context 当因变量为连续变量，且在两组间独立时使用。
|
||
\#' @param data 数据框
|
||
\#' @param group\_col 分组列名 (Character)
|
||
\#' @param val\_col 数值列名 (Numeric)
|
||
\#' @guardrails check\_normality=TRUE, check\_variance=TRUE
|
||
st\_t\_test\_ind \<- function(data, group\_col, val\_col) { ... }
|
||
|
||
* **Pipeline**：编写脚本扫描 R 目录 \-\> 提取注释 \-\> 生成 tools\_library.json \-\> 存入 pgvector。
|
||
|
||
### **5.2 R 服务接口设计**
|
||
|
||
所有工具通过**统一入口**调用，简化后端逻辑。
|
||
|
||
* **API**: POST /api/v1/ssa/execute
|
||
* **Request Payload**:
|
||
{
|
||
"tool\_code": "ST\_T\_TEST\_IND",
|
||
"data": \[ ...rows... \],
|
||
"params": { "group\_col": "group", "val\_col": "bmi" },
|
||
"options": { "return\_code": true }
|
||
}
|
||
|
||
* **Response Payload**:
|
||
{
|
||
"status": "success",
|
||
"results": { "p\_value": 0.012, "conf\_int": \[0.5, 2.1\] },
|
||
"plots": \["base64\_string..."\],
|
||
"trace\_log": \["Checking normality... Passed."\],
|
||
"reproducible\_code": "data \<- read.csv('data.csv'); t.test(data$bmi \~ data$group)..."
|
||
}
|
||
|
||
### **5.3 安全与隐私设计**
|
||
|
||
1. **数据本地化 (Data Residency)**：
|
||
* **原则**：LLM (Brain) 永远只看 **Schema (列名)**，不看 **Data (行内容)**。
|
||
* **流程**：前端提取 Schema \-\> 发给 LLM 规划 \-\> LLM 返回参数 \-\> 前端将 参数+Data 发给 R 服务。
|
||
* **结果**：敏感的患者数据只在内网 R 服务中流转，从未触达公网 LLM。
|
||
2. **网络隔离**：
|
||
* SAE 部署 R 容器时，配置 **Egress Policy (出站策略)** 为 Deny All。防止 R 脚本恶意上传数据。
|
||
|
||
---
|
||
|
||
## **6\. 实施路线图 (Roadmap)**
|
||
|
||
### **Phase 1: 地基建设 (2周)**
|
||
|
||
* **目标**：跑通链路，实现 T 检验的自动化。
|
||
* **任务**：
|
||
1. **Metadata Pipeline**：编写 R 注释提取脚本。
|
||
2. **R Wrapper v1**：实现支持 Trace 和 CodeGen 的通用 Wrapper。
|
||
3. **R Docker**：集成 Plumber 和 10 个核心工具。
|
||
|
||
### **Phase 2: 智能体与交互 (3周)**
|
||
|
||
* **目标**：实现“对话 \-\> 确认 \-\> 执行”闭环。
|
||
* **任务**：
|
||
1. **Planner Agent**：接入 RAG 检索，优化 SAP Prompt。
|
||
2. **前端组件**：开发 `ConfirmationCard` (确认卡片) 和 `ExecutionTrace` (执行路径图)。
|
||
3. **统计护栏**：在 T 检验中实装正态性检查。
|
||
|
||
### **Phase 3: 全量迁移与打磨 (持续)**
|
||
|
||
* **目标**：覆盖 100+ 工具。
|
||
* **任务**：
|
||
1. 批量为旧 R 脚本添加 roxygen2 注释。
|
||
2. 全量更新向量库。
|
||
3. 收集用户反馈，微调护栏阈值。
|
||
|
||
---
|
||
|
||
## **7\. 总结**
|
||
|
||
**SSA-Pro V4.0** 是一套\*\*“为了医疗科研而生”\*\*的架构。
|
||
|
||
它没有盲目追求“全自动写代码”的噱头，而是选择了\*\*“同步微服务 \+ 统计护栏 \+ 白盒交付”\*\*这条最难走但最稳健的路。
|
||
|
||
* **对于用户**：它像一位耐心的导师，教你方法，帮你检查，最后把代码送给你。
|
||
* **对于开发团队**：它复用了现有的 R 资产，工程边界清晰。
|
||
* **对于平台**：它建立了极高的数据隐私壁垒和学术严谨性壁垒。
|
||
|
||
**这是目前行业内最务实、最可落地的智能统计解决方案。**
|
||
|