HaHafeng
8137e3cde2
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>
218 lines
8.5 KiB
Markdown
218 lines
8.5 KiB
Markdown
# **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 即可无缝调用，系统扩展性无限。
|
||
|