# **SSA-Executor 专家配置要素清单 (Configuration Specs)**

**文档版本：** v1.0

**创建日期：** 2026-02-18

**核心目标：** 定义统计专家需要在“配置中心”为每个 R 工具录入的详细信息。

**隐喻：** 如果 R 代码是“药方”，这个配置单就是“药品说明书”。

## **1\. 基础元数据 (Identity)**

*给这个 R 脚本一个系统内唯一的身份。*

| 配置项 | 说明 | 示例 |
| :---- | :---- | :---- |
| **Tool Code** | 唯一标识符 (Primary Key) | ST\_T\_TEST\_IND |
| **Tool Name** | 显示名称 | 独立样本 T 检验 |
| **Version** | 版本号 | v1.0.2 (用于回滚) |
| **R Script File** | **上传文件** | t\_test\_ind.R (专家直接上传脚本) |
| **Entry Function** | 入口函数名 | run\_analysis |

## **2\. 输入参数映射 (Input Contract)**

*告诉 Executor：这个 R 脚本需要什么原料？*

| 参数名 (JSON Key) | R 函数参数名 | 数据类型 | 校验规则 (Validator) | 默认值 |
| :---- | :---- | :---- | :---- | :---- |
| group\_col | group\_var | String | Must be column name | \- |
| val\_col | value\_var | String | Must be numeric column | \- |
| conf\_level | conf\_level | Float | 0.90 \- 0.99 | 0.95 |
| alternative | alt | String | "two.sided", "less", "greater" | "two.sided" |

## **3\. 统计护栏配置 (Guardrails Config) ⭐ 核心**

*告诉 Executor：在跑核心代码前，先做什么体检？*

**配置模式：** 规则链 (Rule Chain)

1. **检查项 (Check)**: Shapiro-Wilk Normality Test  
   * **目标变量**: val\_col (按 group\_col 分组)  
   * **阈值 (Threshold)**: P \< 0.05  
   * **失败动作 (Action)**:  
     * \[ \] **Block**: 报错并终止 ("数据不正态，无法计算")  
     * \[ \] **Warn**: 继续执行，但在结果中标记警告  
     * \[x\] **Switch**: 自动切换到工具 ST\_WILCOXON (非参数检验)  
2. **检查项 (Check)**: Sample Size  
   * **规则**: Min(N) \< 3  
   * **失败动作**: **Block** ("样本量太少，无法计算")

## **4\. 输出结果定义 (Output Definition)**

*告诉 Executor：跑完代码后，要给用户看什么？*

### **4.1 结构化数据 (Table)**

定义返回的三线表里包含哪些指标。

* **指标 1**: Statistic (t值 / F值)  
* **指标 2**: P-Value (保留 3 位小数，\<0.001 显示为 "\<0.001")  
* **指标 3**: Mean ± SD (描述性统计)  
* **指标 4**: CI (95%) (置信区间)

### **4.2 图表配置 (Visualization)**

定义 R 脚本生成的图表规范（ggplot2 模板）。

* **图表类型**: Boxplot with Jitter (箱线图+散点)  
* **X 轴映射**: group\_col  
* **Y 轴映射**: val\_col  
* **配色方案**: Nature / Lancet (期刊风格)  
* **其它元素**: 是否标注 P 值？(Yes/No)

### **4.3 智能解读模板 (Narrative Template)**

这是给 AI (Critic) 参考的“填空题”，或者是 R 直接生成的结论。

* **模板**:"本研究纳入 {{N}} 例样本。{{group\_col}} 各组间 {{val\_col}} 的差异 **{{significance\_text}}** (t={{statistic}}, P={{p\_value}})。具体而言，{{high\_group}} 的均值 ({{mean\_1}}) 显著高于 {{low\_group}} ({{mean\_2}})。"

## **5\. 代码交付配置 (Code Handover)**

*告诉 Executor：用户点击“下载代码”时，给他什么？*

这是一个 **glue 字符串模板**，用于生成可复现的 R 代码。

\# 模板示例  
library(ggplot2)  
library(stats)

\# 1\. 读取数据  
data \<- read.csv("your\_data.csv")

\# 2\. 统计检验  
res \<- t.test({{val\_col}} \~ {{group\_col}}, data=data, var.equal={{var\_equal}})  
print(res)

\# 3\. 绘图  
ggplot(data, aes(x={{group\_col}}, y={{val\_col}})) \+  
  geom\_boxplot(fill="\#3C5488") \+  
  theme\_bw() \+  
  labs(title="Difference Analysis")

## **6\. 环境依赖 (Dependencies)**

*告诉 Executor：运行这个脚本需要装什么包？*

* **Packages**: ggplot2, dplyr, car, ggpubr  
* **System Libs**: libcairo2 (如果涉及特殊绘图)

## **7\. 总结：专家的工作流**

统计学专家在“配置中心”要做的事情就是：

1. **上传** 写好的 t\_test.R。  
2. **勾选** 这个脚本需要的输入参数（列名）。  
3. **设置** 护栏（P \< 0.05 切换 Wilcoxon）。  
4. **粘贴** 代码模板（供用户下载）。  
5. **预览** 这一套配置是否能跑通测试数据。

**这才是真正的“专家协同”。**