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