4.3 KiB
4.3 KiB
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)
- 检查项 (Check): Shapiro-Wilk Normality Test
- 目标变量: val_col (按 group_col 分组)
- 阈值 (Threshold): P < 0.05
- 失败动作 (Action):
- [ ] Block: 报错并终止 ("数据不正态，无法计算")
- [ ] Warn: 继续执行，但在结果中标记警告
- [x] Switch: 自动切换到工具 ST_WILCOXON (非参数检验)
- 检查项 (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. 总结：专家的工作流
统计学专家在“配置中心”要做的事情就是：
- 上传 写好的 t_test.R。
- 勾选 这个脚本需要的输入参数（列名）。
- 设置 护栏（P < 0.05 切换 Wilcoxon）。
- 粘贴 代码模板（供用户下载）。
- 预览 这一套配置是否能跑通测试数据。
这才是真正的“专家协同”。