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

feat(ssa): Complete SSA-Pro MVP development plan v1.3

Browse Source 
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>
This commit is contained in:
HaHafeng
2026-02-18 21:58:37 +08:00
parent f9ed0c2528
commit 8137e3cde2
19 changed files with 5756 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

162
docs/03-业务模块/SSA-智能统计分析/00-系统设计/PRD SSA-Pro 严谨型智能统计分析模块.md Normal file
View File

@@ -0,0 +1,162 @@
# **PRD: SSA-Pro 严谨型智能统计分析模块 (V1.0)**
**文档状态：** v1.0 (Final)
**创建日期：** 2026-02-18
**关联架构：** [SSA-Pro\_智能统计分析架构设计方案\_V4.md](https://www.google.com/search?q=../09-SSA-Pro_%E6%99%BA%E8%83%BD%E7%BB%9F%E8%AE%A1%E5%88%86%E6%9E%90%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1%E6%96%B9%E6%A1%88_V4.md)
**关联规范：** [SSA-Pro\_Skills架构规范\_V4.1.md](https://www.google.com/search?q=../16-SSA-Pro_Skills%E6%9E%B6%E6%9E%84%E8%A7%84%E8%8C%83_V4.1.md)
## **1\. 研发背景与业务价值**
### **1.1 背景 (Why Now?)**
目前平台的 **AIA (问答)** 和 **DC (清洗)** 模块已趋于成熟，但在**核心统计分析**环节仍存在断层：
1. **用户痛点**：临床医生普遍缺乏统计学能力，SPSS/SAS 操作复杂，且容易误用统计方法（如数据不符合正态分布却强行用 T 检验）。
2. **竞品缺陷**：通用的 AI（如 ChatGPT）虽然能写代码，但经常产生“幻觉”，生成的代码在本地无法运行，且存在严重的数据隐私泄露风险。
3. **资产闲置**：公司内部积累了 100+ 高质量的 R 语言统计脚本，目前处于“沉睡”状态，未能转化为 SaaS 服务能力。
### **1.2 产品目标 (Product Goal)**
构建一个 **“白盒化、严谨型、可交付”** 的智能统计分析 Agent (SSA-Pro)。
* **白盒化**：分析过程透明，用户可见（执行路径、护栏检查）。
* **严谨型**：强制执行统计假设检验（Guardrails），防止学术谬误。
* **可交付**：不仅提供结果，还提供**可复现的 R 源代码**，支持本地二次运行。
## **2\. 核心能力与功能列表**
### **2.1 核心流程 (The Core Loop)**
交互模式采用 **"Retrieve-Plan-Confirm-Execute"** 闭环：
| 步骤 | 功能模块 | 关键动作 | 交付物 |
| :---- | :---- | :---- | :---- |
| **1** | **智能规划 (Planner)** | 意图识别 \+ RAG 检索 \+ 参数映射 | **分析预习卡片 (Plan Card)** |
| **2** | **人机确认 (HITL)** | 用户检查参数，点击确认 | 用户授权指令 |
| **3** | **透明执行 (Execution)** | 混合数据传输 \+ 统计护栏 \+ 核心计算 | **执行路径树 (Execution Trace)** |
| **4** | **资产交付 (Delivery)** | 结果解释 \+ 代码生成 \+ 报告导出 | **分析结果包 (Result \+ Code)** |
### **2.2 功能详细说明**
#### **F1. 智能工具检索 (Tool RAG)**
* **需求**：系统需从 100+ 工具中，根据用户自然语言（如“看两组差异”）精准推荐最合适的工具。
* **技术支撑**：基于 pgvector 的语义检索 \+ pg\_bigm 关键词匹配。
* **输入**：用户 Query \+ 数据 Schema（列名/类型）。
* **输出**：Top-5 候选工具的 JSON Schema。
#### **F2. 统计分析计划生成 (SAP Generation)**
* **需求**：AI 不直接跑代码，而是先像人类统计师一样，写一份 SAP（统计分析计划）。
* **内容包含**：分析目标、变量映射（X/Y）、前置假设条件（如正态性）、降级策略。
* **表现形式**：前端渲染为 **"待确认卡片"**，用户可修改参数。
#### **F3. 统计护栏与自动降级 (Guardrails)**
* **需求**：在执行核心检验前，必须强制检查数据质量与统计假设。
* **逻辑示例**（以 T 检验为例）：
1. 检查样本量是否 \> 3。
2. 执行 Shapiro-Wilk 正态性检验。
3. **决策点**：若 P \< 0.05（非正态），自动切换为 **Wilcoxon 秩和检验**，并在前端亮黄灯提示。
* **价值**：这是本产品区别于 ChatGPT 的核心护城河。
#### **F4. 混合数据传输 (Hybrid Data Protocol)**
* **需求**：支持不同大小的数据集高效传输，规避 HTTP JSON 瓶颈。
* **策略**：
* **\< 1MB**：直接嵌入 API 请求体（Inline JSON）。
* **1MB \- 20MB**：前端先传 OSS，仅向 R 服务传递 OSS File Key，R 服务内网下载。
#### **F5. 代码资产交付 (Reproducible Code)**
* **需求**：用户下载的 R 代码必须能在其本地 RStudio 中直接运行。
* **实现**：R Wrapper 动态拼接代码字符串，数据读取路径替换为占位符 read.csv("your\_data.csv")。
## **3\. 技术路线与架构 (Technical Specifications)**
### **3.1 总体架构：Brain-Hand 模型**
本模块严格遵循公司 **V4.1 架构标准**：
* **Brain (Node.js)**：负责认知、规划、检索、Prompt 组装。**绝不处理真实数据内容**，只看 Schema。
* **Hand (R Docker)**：负责执行、计算、绘图。**运行在隔离容器中**，处理真实数据。
### **3.2 关键技术栈**
* **后端**：Node.js (Fastify) \+ Prisma
* **统计引擎**：Docker \+ R 4.3 \+ Plumber (API 服务)
* **向量库**：RDS PostgreSQL \+ pgvector
* **大模型**：DeepSeek-V3 (Planner/Critic)
* **前端**：React 19 \+ Ant Design X
### **3.3 数据库设计摘要 (Schema)**
需在 capability\_schema 中建立全局统一的技能注册表：
\-- 核心表：统计技能注册表
CREATE TABLE capability\_schema.global\_skills (
skill\_code VARCHAR(50) PRIMARY KEY, \-- e.g. ST\_T\_TEST
provider VARCHAR(50), \-- 'SSA-R-SERVICE'
input\_schema JSONB, \-- OpenAI Function Schema
embedding vector(1024) \-- 用于 RAG 检索
);
## **4\. 数据隐私与安全 (Safety & Privacy)**
### **4.1 数据隔离原则**
* **原则**：**LLM 永远不可见真实患者数据。**
* **实现**：前端提取 Header 发送给 LLM 做规划；前端将 CSV 发送给 R 服务做计算。两者物理隔离。
### **4.2 R 容器安全**
* **网络阻断**：生产环境 SAE 容器配置 Egress Deny，禁止 R 脚本主动发起外网请求。
* **只读文件系统**：R 脚本目录设为 Read-Only，防止代码篡改。
## **5\. 开发里程碑 (Roadmap)**
### **Phase 1: 骨架搭建 (Week 1-2)**
* **目标**：跑通 T 检验的 "Hello World"。
* **产出**：
* R Docker 基础镜像 (含 Plumber)。
* 第 1 个标准化 Wrapper (T-Test)。
* Node.js \-\> R 的同步 API 调通。
### **Phase 2: 交互 MVP (Week 3-5)**
* **目标**：用户可用，体验完整。
* **产出**：
* 集成 RAG 检索，AI 能听懂“做个差异分析”。
* 前端“确认卡片”与“执行树”组件上线。
* 上线 Top 10 高频统计工具。
### **Phase 3: 量产与 Skills 化 (Week 6-8)**
* **目标**：工具丰富，能力开放。
* **产出**：
* 覆盖 50+ 常用工具。
* 完成 **Global Skill Registry** 注册，允许 IIT Manager 模块调用 SSA 能力。
## **6\. 验收标准 (Acceptance Criteria)**
1. **准确性**：对于非正态数据，系统**必须**自动降级为非参数检验，并给出提示。
2. **性能**：20MB 数据文件的 T 检验，端到端耗时（含网络传输）不超过 **5秒**。
3. **复现性**：下载的 R 代码包，在干净的本地 R 环境中安装依赖后，**必须**能跑通并产出相同结果。
4. **隐私**：审计日志中**严禁**出现具体的患者隐私数据（Row Data）。
## **7\. 附录：工具列表 (MVP Top 10\)**
1. 独立样本 T 检验 (Independent T-Test)
2. 配对样本 T 检验 (Paired T-Test)
3. 单因素方差分析 (One-way ANOVA)
4. 卡方检验 (Chi-square Test)
5. Fisher 精确检验
6. Mann-Whitney U 检验 (Wilcoxon Rank Sum)
7. Pearson/Spearman 相关性分析
8. 单因素线性回归 (Simple Linear Regression)
9. 生存分析 (Kaplan-Meier Curve)
10. Cox 比例风险回归 (Cox Regression)

217
docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro (V4.1) 统计技能中心架构规范.md Normal file
View File

@@ -0,0 +1,217 @@
# **SSA-Pro (V4.1): 统计技能中心架构规范 (Statistical Skills Architecture)**
**文档版本：** v4.1 (Skills Edition)
**创建日期：** 2026-02-18
**核心理念：** **能力即技能 (Capabilities as Skills)**。将 100+ R 统计工具标准化为平台级 Skills，实现“认知依赖注入”与跨模块复用。
**适用范围：** SSA 模块、IIT Manager、Protocol Agent、DC 模块
## **1\. 架构愿景：从“专用工具”到“通用技能”**
在 SSA-Pro V4.1 原有架构（同步 API \+ 护栏 \+ 白盒）的基础上，我们引入 **Skills 范式**，旨在解决以下问题：
1. **消除孤岛**：统计能力不应局限于 SSA 聊天窗口。IIT Manager 需要做质控监控，Protocol Agent 需要计算样本量，它们都应该能直接调用 SSA 的 R 代码。
2. **统一治理**：将 R 脚本的元数据、参数定义、权限控制统一在 **Global Skill Registry** 中管理。
3. **认知解耦**：LLM（大脑）不需要知道 R 代码（手）怎么写，只需要知道“技能手册（Schema）”。
## **2\. 核心定义：什么是 "Statistical Skill"？**
在我们的系统中，一个 **统计技能 (Statistical Skill)** 由三部分组成：
### **2.1 语义接口 (Semantic Interface)**
* **定义**：自然语言描述，用于 RAG 检索和 LLM 理解。
* **内容**：
* **Name**: st\_t\_test\_ind (独立样本 T 检验)
* **Description**: "比较两组独立连续变量的均值差异。"
* **Usage Context**: "当因变量为数值型，自变量为二分类，且数据独立时使用。"
### **2.2 数据契约 (JSON Schema)**
* **定义**：严格的输入输出规范，兼容 OpenAI Function Calling 标准。
* **内容**：
{
"type": "object",
"properties": {
"data\_source": { "type": "object", "description": "OSS路径或内联数据" },
"params": {
"group\_col": { "type": "string", "description": "分组列名" },
"val\_col": { "type": "string", "description": "数值列名" }
}
},
"required": \["data\_source", "params"\]
}
### **2.3 原生函数 (Native Function)**
* **定义**：执行逻辑的实体。
* **实现**：运行在 R Docker 容器中的 Plumber API 端点。它包含**统计护栏 (Guardrails)** 和 **代码生成 (Code Gen)** 逻辑。
## **3\. 系统架构蓝图 (Skills Perspective)**
我们将架构划分为 **技能注册层**、**技能路由层** 和 **技能执行层**。
graph TD
subgraph "Clients (技能消费者)"
User\[用户 (SSA Chat)\]
IIT\[IIT Manager Agent\]
Proto\[Protocol Agent\]
end
subgraph "Platform Capability Layer (通用能力层)"
Registry\[(Global Skill Registry\<br\>pgvector)\]
Orchestrator\[Skill Orchestrator\<br\>Node.js\]
Planner\[Planner / Router\<br\>DeepSeek-V3\]
end
subgraph "Skill Provider: Statistics (技能提供者)"
R\_Gateway\[R Service API Gateway\]
subgraph "R Docker Container"
Skill\_A\[Skill: T-Test\]
Skill\_B\[Skill: ANOVA\]
Skill\_C\[Skill: Regression\]
Guard\[Guardrails Engine\]
end
end
%% 注册流程
Skill\_A \-.-\>|注册元数据| Registry
%% 调用流程
User \--\>|1. 自然语言需求| Orchestrator
IIT \--\>|1. 监控触发| Orchestrator
Orchestrator \--\>|2. 语义检索| Registry
Registry \--\>|3. 返回 Top-K Skills| Planner
Planner \--\>|4. 生成调用参数 (JSON)| Orchestrator
Orchestrator \--\>|5. 路由执行 (Sync HTTP)| R\_Gateway
R\_Gateway \--\>|6. 执行与护栏| Skill\_A
Skill\_A \--\>|7. 结果 \+ 代码| Orchestrator
## **4\. 数据库设计：Global Skill Registry**
我们将元数据存储从 ssa\_schema 提升至全局通用的 capability\_schema (或 common\_schema)。
### **表结构：capability\_schema.global\_skills**
CREATE TABLE capability\_schema.global\_skills (
id UUID PRIMARY KEY DEFAULT gen\_random\_uuid(),
\-- 标识信息
skill\_code VARCHAR(50) NOT NULL UNIQUE, \-- e.g., 'ST\_T\_TEST\_IND'
name VARCHAR(100) NOT NULL,
provider VARCHAR(50) NOT NULL, \-- e.g., 'SSA-R-SERVICE'
category VARCHAR(50), \-- e.g., 'STATISTICS', 'DATA\_CLEANING'
\-- 语义信息 (用于 RAG)
description TEXT NOT NULL,
usage\_context TEXT,
search\_text TEXT, \-- 合成检索字段
embedding vector(1024), \-- 向量索引
\-- 契约定义
input\_schema JSONB NOT NULL, \-- JSON Schema for LLM
output\_schema JSONB, \-- 预期输出格式
\-- 执行配置
endpoint VARCHAR(200), \-- R 服务的内部路由路径
is\_active BOOLEAN DEFAULT TRUE,
created\_at TIMESTAMP DEFAULT NOW()
);
\-- 索引
CREATE INDEX idx\_skills\_embedding ON capability\_schema.global\_skills USING hnsw (embedding vector\_cosine\_ops);
CREATE INDEX idx\_skills\_provider ON capability\_schema.global\_skills(provider);
## **5\. 接口协议：标准技能调用**
为了支持跨模块调用，我们需要定义统一的 **Skill Invocation Protocol**。
### **5.1 通用调用入口 (Node.js)**
任何 Agent (SSA/IIT/ASL) 都可以通过此方法调用统计能力。
// common/skills/skillExecutor.ts
interface SkillExecutionRequest {
skillCode: string; // 目标技能
payload: Record\<string, any\>; // 符合 input\_schema 的参数
context?: { // 上下文信息
userId: string;
traceId: string;
};
}
async function executeSkill(req: SkillExecutionRequest) {
// 1\. 从 Registry 获取技能配置
const skillDef \= await skillRegistry.get(req.skillCode);
// 2\. 路由分发 (如果是 SSA-R-SERVICE，转发给 R Docker)
if (skillDef.provider \=== 'SSA-R-SERVICE') {
return await rClient.post(skillDef.endpoint, req.payload);
}
// ... 处理其他 Provider
}
### **5.2 R 服务端点 (Wrapper 实现)**
R Docker 中的 Plumber API 保持不变，但其角色明确为 **"Native Function Host"**。
* **Endpoint**: `/api/v1/skills/{skill_code}`
* **Behavior**:
1. 接收 JSON Payload。
2. 执行 **Guardrails** (正态性检查等)。
3. 执行核心统计逻辑。
4. 返回标准结果包 (Result \+ Trace \+ Code)。
---
## **6\. 场景演练：跨模块能力复用**
### **场景 A：SSA 模块 (标准流程)**
1. **用户**：在 SSA 界面输入“比较两组血压差异”。
2. **Planner**：检索 Registry，命中 `ST_T_TEST_IND`，生成 JSON 参数。
3. **Executor**：调用 R 接口，返回图表和报告。
### **场景 B：IIT Manager (主动监控)**
1. **背景**：IIT Agent 每天扫描 EDC 数据，监控不良事件 (AE)。
2. **触发**：Agent 发现实验组 AE 发生率似乎高于对照组。
3. **决策**：Agent 决定调用“统计技能”来验证差异是否显著。
4. **调用**：
* IIT Agent 构造数据：`{ "group": [...], "ae_flag": [...] }`
* IIT Agent 调用 `executeSkill('ST_CHI_SQUARE', payload)`。
5. **结果**：R 服务返回 `p_value = 0.03`。
6. **行动**：IIT Agent 基于 P \< 0.05，向研究者发送企业微信预警：“检测到实验组不良事件显著升高 (P=0.03)，请关注。”
---
## **7\. 实施路线调整**
在原有的 SSA-Pro 开发计划上，增加 **"Skills 标准化"** 的工作项：
1. **数据库迁移**：
* 原计划：`ssa_schema.tools_library`
* 新计划：`capability_schema.global_skills` (包含 `provider` 字段)
2. **元数据提取脚本 (R)**：
* 生成的 JSON 需要包含符合 OpenAI 标准的 `input_schema`。
3. **通用调用层 (Node.js)**：
* 开发 `SkillService`，作为所有 Agent 调用工具的统一网关。
---
## **8\. 总结**
采用 **SSA-Pro (V4.1) Skills 架构**，我们不仅仅是在开发一个统计工具箱，而是在构建平台的 **"左脑逻辑中心"**。
* **技术上**：保留了 R Docker 的同步高性能和严谨性。
* **架构上**：打通了业务壁垒，实现了统计能力的资产化和服务化。
* **未来**：当我们需要引入 Python 机器学习技能时，只需注册新的 `provider: 'PYTHON-ML-SERVICE'`，Planner 即可无缝调用，系统扩展性无限。

224
docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md Normal file
View File

@@ -0,0 +1,224 @@
# **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 资产，工程边界清晰。
* **对于平台**：它建立了极高的数据隐私壁垒和学术严谨性壁垒。
**这是目前行业内最务实、最可落地的智能统计解决方案。**