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

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 即可无缝调用，系统扩展性无限。