# SSA-Pro 四层七工具实现机制详解

> **文档版本：** v1.1  
> **创建日期：** 2026-02-21  
> **最后更新：** 2026-02-21（v1.1 — 新增对话层 LLM 架构说明）  
> **文档类型：** 架构说明 (Architecture Reference)  
> **目标读者：** 开发团队  
> **前置文档：** `SSA-Pro 工具体系规划方案（团队讨论稿）.md`（定义了"做什么"），本文档说明"怎么做"  
> **核心问题：** 每个工具的内部实现机制是什么？哪些依赖 LLM？哪些依赖规则引擎？哪些是纯计算？**对话层 LLM 如何保证多轮对话的连贯性？**

---

## 1. 三层架构全貌：对话层 LLM 是核心大脑

### 1.1 架构中的三个层次

系统不是简单的"Node.js 调工具"，而是三层协同：

```
┌─────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  第一层：Node.js 编排层（交通指挥）                                    │
│  ────────────────────────────────                                    │
│  职责：意图路由 → 工具调度 → 流程控制 → Session 黑板读写              │
│  特点：确定性、无 LLM、零 Token 成本                                  │
│  类比：交通警察，决定车（工具）往哪走，但不理解乘客（用户）在说什么     │
│                                                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  第二层：对话层 LLM（全局大脑）         ← 这是架构的核心               │
│  ────────────────────────────                                        │
│  职责：理解用户意图 → 组织工具输出 → 生成连贯自然语言回复              │
│  特点：全局状态感知、多轮对话记忆、知识推理                            │
│  类比：统计顾问本人，读过你的数据，记得之前聊了什么，知道什么时候该问    │
│                                                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  第三层：工具层（专业手脚）                                           │
│  ────────────────────────                                            │
│  职责：执行具体任务（统计计算、规则匹配、R 脚本执行）                  │
│  特点：无状态函数，输入→输出，不关心对话上下文                         │
│  类比：实验室设备，按按钮出结果，但不知道实验的完整背景                 │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

### 1.2 一次完整交互的真实流程

以用户说 **"帮我看看各组的样本分布"** 为例：

```
用户消息: "帮我看看各组的样本分布"
       │
       ▼
  ┌─ 第一层：Node.js 编排 ──────────────────────────────────────────┐
  │  IntentRouter 分类 → explore                                    │
  │  决定调用 get_data_overview（若缓存未命中）                       │
  └──────────────┬──────────────────────────────────────────────────┘
                 │ 工具调用
                 ▼
  ┌─ 第三层：工具层 ────────────────────────────────────────────────┐
  │  get_data_overview → DataProfileService(Python) 返回结构化 JSON  │
  │  { total_rows: 200, categorical_vars: [...], ... }              │
  └──────────────┬──────────────────────────────────────────────────┘
                 │ 结构化输出
                 ▼
  ┌─ 第二层：对话层 LLM ────────────────────────────────────────────┐
  │                                                                  │
  │  System Prompt:                                                  │
  │    "你是 SSA-Pro 智能统计分析助手...                               │
  │     用户数据全貌: {DataContext}                                   │
  │     请基于数据摘要为用户解读数据特征。"                             │
  │                                                                  │
  │  对话历史:                                                       │
  │    [user] 上传了数据 xxx.csv                                     │
  │    [assistant] 您的数据已上传成功...                               │
  │    [user] 帮我看看各组的样本分布          ← 当前消息               │
  │                                                                  │
  │  工具输出（注入为上下文）:                                         │
  │    get_data_overview 返回: { ... }                                │
  │                                                                  │
  │  → LLM 生成连贯的自然语言回复:                                    │
  │    "您的数据共 200 例，分为 treatment 组（103 例）和               │
  │     control 组（97 例）。各组分布如下：                            │
  │     - treatment 组平均年龄 54.3 岁（SD=11.2）...                  │
  │     需要我进一步看某个具体变量吗？"                                │
  │                                                                  │
  └──────────────────────────────────────────────────────────────────┘
```

**关键点：工具返回的是结构化 JSON，但用户看到的是自然语言。中间的翻译者就是对话层 LLM。**

### 1.3 对话层 LLM 的六大职责

| # | 职责 | 靠 Node.js 能做到吗？ | 说明 |
|---|------|:---:|------|
| 1 | **自然语言生成** | ❌ | 把结构化 JSON 变成"像人说的话" |
| 2 | **多轮对话记忆** | ❌ | "刚才那个变量"→ 理解指的是上一轮讨论的 BMI |
| 3 | **上下文推理** | ❌ | 用户说"有没有效"→ 结合 DataContext 推理出想比较什么 |
| 4 | **主动引导** | ❌ | 分析完主动问"需要做敏感性分析吗？" |
| 5 | **知识融合** | ❌ | 结合统计学知识解释"为什么选 T 检验而不是 ANOVA" |
| 6 | **语气和策略** | ❌ | 对医生用临床语言，对统计师用技术语言 |

> **结论：Node.js 编排层绝对不够。对话层 LLM 是不可或缺的核心大脑。Node.js 管"做什么"，LLM 管"怎么说"和"怎么想"。**

---

## 2. 对话层 LLM 的技术实现

### 2.1 System Prompt 架构

对话层 LLM 有一个持久的 System Prompt，在整个会话生命周期内持续生效，并根据意图和状态动态组装：

```
┌─ System Prompt（始终存在）────────────────────────────────────────┐
│                                                                    │
│  [基础角色]（固定）                                                │
│  你是 SSA-Pro 智能统计分析助手，专注于临床研究统计分析。             │
│  你了解用户上传的数据，可以回答关于数据的问题，推荐分析方法，        │
│  解读分析结果。你的风格是专业但易懂的统计顾问。                     │
│                                                                    │
│  [数据全貌]（上传数据后始终注入，~200 Token）                       │
│  用户上传了一份数据集：                                             │
│  {DataContext.summary — 行数/列数/缺失率/类型/结构}                 │
│                                                                    │
│  [PICO 分类]（推断后注入，~150 Token）                              │
│  根据数据特征，推断/确认的 PICO 分类如下：                          │
│  {DataContext.pico — population/intervention/outcome}               │
│                                                                    │
│  [变量字典]（逐步丰富，~50 Token/变量，裁剪后注入）                 │
│  各变量的定义和角色：                                               │
│  {DataContext.variableDictionary — 裁剪策略控制}                    │
│                                                                    │
│  [意图特定指令]（每次请求动态切换）                                  │
│  ┌──────────────────────────────────────────────────┐              │
│  │ chat:     请基于统计知识和用户数据回答。不要主动建议分析。│              │
│  │ explore:  请基于数据摘要解读数据特征。可以推断 PICO。  │              │
│  │ consult:  请推荐分析方法，给出理由和前提。不要执行。   │              │
│  │ analyze:  以下是工具执行结果，请向用户说明进展。      │              │
│  │ discuss:  以下是分析结果: {结果}。请帮助用户解读。    │              │
│  │ feedback: 以下是完整 QPER 记录: {trace}。请分析问题。 │              │
│  └──────────────────────────────────────────────────┘              │
│                                                                    │
│  [工具输出]（本轮工具调用的结果，动态注入）                          │
│  {get_data_overview / method_consult / run_step 等的结构化输出}      │
│                                                                    │
│  [分析结果]（discuss/feedback 时注入，~500 Token/步骤）              │
│  {最近的 AnalysisRecord 摘要}                                       │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

┌─ 对话历史（最近 N 轮，滑动窗口）─────────────────────────────────────┐
│  [user] 上传了 clinical_trial.csv                                    │
│  [assistant] 您的数据已上传，共 200 行 15 列...                       │
│  [user] 帮我看看各组的样本分布                                        │
│  [assistant] treatment 组 103 例，control 组 97 例...                 │
│  [user] BMI 的分布怎样？                                              │
│  [assistant] BMI 均值 25.3，标准差 4.1...                             │
│  [user] 这两组 BMI 有差异吗？应该怎么分析？         ← 当前消息        │
└──────────────────────────────────────────────────────────────────────┘
```

### 2.2 对话层 LLM 在每种意图中的角色

| 意图 | Node.js 编排做了什么 | 对话层 LLM 做了什么 |
|------|---------------------|-------------------|
| **chat** | 几乎不介入（不调工具） | **完全主导**：纯 LLM 对话，基于 DataContext + 统计知识回答 |
| **explore** | 调用 get_data_overview 或 get_variable_detail | **翻译 + 解读**：把结构化 JSON 变成易懂的数据解读 |
| **consult** | 调用 method_consult（决策表匹配） | **融合 + 解释**：把匹配结果变成完整的方法推荐（带理由、前提、替代） |
| **analyze** | 调用 analysis_plan → run_step ×N → write_report | **进度播报 + 过渡衔接**：每步执行后生成进展说明，衔接步骤间的上下文 |
| **discuss** | 提取最近的 AnalysisRecord | **深度解读**：回答"p 值说明什么""置信区间为什么宽"等统计学问题 |
| **feedback** | 注入 qperTrace 到 LLM | **问题诊断**：分析完整记录，找出问题根因，建议新方案 |

### 2.3 对话连贯性保障机制

```
┌─ 保障机制 1：对话历史注入 ────────────────────────────────────────┐
│                                                                    │
│  每次 LLM 调用都携带最近 N 轮对话历史（滑动窗口）                   │
│  → 用户说"刚才那个变量" → LLM 从历史中知道指的是 BMI               │
│  → 用户说"按你说的方案执行" → LLM 从历史中知道之前推荐了 T 检验    │
│                                                                    │
│  窗口大小：根据 Token 预算动态调整                                  │
│  - 简单对话：保留最近 10 轮                                        │
│  - 长对话（含分析结果）：保留最近 5 轮 + 关键事件摘要              │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

┌─ 保障机制 2：Session 黑板持久化 ──────────────────────────────────┐
│                                                                    │
│  对话历史有滑动窗口（会丢失早期内容），但关键决策结果不会丢失：      │
│  - PICO 确认结果 → 写入 blackboard.confirmedPico → 始终可用        │
│  - 变量角色确认 → 写入 blackboard.variableDictionary → 始终可用    │
│  - 分析方案 → 写入 blackboard.currentPlan → 始终可用               │
│  - 执行结果 → 写入 blackboard.stepResults → 始终可用               │
│                                                                    │
│  → 即使对话历史中早期的讨论被裁剪，结论仍在 Session 黑板中          │
│  → LLM 通过 DataContext 注入随时可以引用这些结论                    │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

┌─ 保障机制 3：意图切换时的上下文衔接 ──────────────────────────────┐
│                                                                    │
│  用户从 consult 转到 analyze 时：                                  │
│                                                                    │
│  [consult 阶段对话]                                                │
│  user: "我想比较两组血压差异，用什么方法？"                          │
│  assistant: "建议独立样本 T 检验，理由是..."                        │
│  user: "好的，按这个方案执行"                                       │
│                                                                    │
│  → IntentRouter 识别为 analyze                                     │
│  → Node.js 编排层从 Session 黑板读取 consult 阶段的结论             │
│  → 对话层 LLM 收到完整上下文:                                      │
│    System Prompt（含 DataContext + "用户已确认 T 检验方案"）         │
│    + 对话历史（包含 consult 阶段的讨论）                            │
│    + 意图特定指令（"正在执行分析，请向用户说明进展"）                │
│  → LLM 生成衔接回复:                                               │
│    "好的，我来按之前讨论的方案执行。分析计划如下：                   │
│     步骤 1: 描述统计（两组基线特征）                                │
│     步骤 2: 独立样本 T 检验（比较血压差异）                         │
│     确认开始执行吗？"                                               │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘
```

### 2.4 对话层 LLM 的技术参数

| 参数 | 值 | 说明 |
|------|---|------|
| 模型 | deepseek-v3 | 全系统统一模型 |
| Temperature | 0.7（对话）/ 0.3（报告生成） | 对话允许自然变化，报告追求稳定 |
| System Prompt | 持久注入 | 整个会话生命周期内持续生效 |
| 对话历史 | 滑动窗口（5-10 轮） | Token 预算内尽量多保留 |
| DataContext | 始终注入 | 通过 Session 黑板注入，保证数据感知 |
| Prompt 管理 | DB 存储 + Seed 脚本 | 方法学团队可编辑，不写死在代码中 |

---

## 3. 编排层 vs 对话层的职责划分

### 3.1 什么事 Node.js 编排层做

| 职责 | 说明 | 举例 |
|------|------|------|
| **意图路由** | 决定这条消息走哪个处理路径 | "比较两组" → analyze |
| **工具调度** | 决定调用哪些工具、什么顺序 | analyze → plan → run_step ×N → report |
| **Session 黑板读写** | 工具输出写入黑板，工具输入从黑板读 | PICO 写入 → plan 读取 |
| **Token 控制** | 注入 LLM 前裁剪上下文 | 变量字典 >20 → 只注入已确认的 |
| **data_source 注入** | R 引擎调用前自动注入数据源 | OSS 预签名 URL |
| **错误分类** | run_step 出错后决定重试还是报告 | "Column not found" → 可自愈 |
| **流程控制** | ask_user 中断/恢复、重试计数 | MAX 2 次 → 停止重试 |

### 3.2 什么事对话层 LLM 做

| 职责 | 说明 | 举例 |
|------|------|------|
| **自然语言生成** | 把结构化输出变成人话 | JSON → "您的数据共 200 例..." |
| **多轮对话连贯** | 理解指代、省略、上下文引用 | "刚才那个" → BMI |
| **知识推理** | 基于统计学知识回答专业问题 | "为什么选 T 检验？" |
| **PICO 推断** | 基于临床知识推断数据角色 | 推断 outcome 可能是 bp_change |
| **方法解释** | 解释决策表的匹配结果 | "选 T 检验是因为..." |
| **结果解读** | 深度解释统计结果的含义 | "p=0.03 说明..." |
| **主动引导** | 在合适时机引导用户下一步 | "需要做敏感性分析吗？" |
| **反思分析** | 分析 QPER 全记录找问题根因 | "样本量不足导致检验效能低" |

### 3.3 协作模型

```
Node.js 编排层                     对话层 LLM
─────────────                     ──────────

"这条消息是 explore 意图"    →
                                   
"调用 get_data_overview"     →
                                   
"工具返回了 JSON 结果"       →     "把 JSON + DataContext + 对话历史
                                    组装成 Prompt，生成自然语言解读"
                                   
                              ←    "您的数据共 200 例，分为..."
                                   
"把回复返回给前端"           →

─── 下一轮 ───

"这条消息是 consult 意图"    →
                                   
"调用 method_consult          →
 (DecisionTable 匹配)"
                                   
"匹配结果: T 检验"           →     "把匹配结果 + DataContext + 对话历史
                                    组装成 Prompt，生成方法推荐 + 理由"
                                   
                              ←    "建议独立样本 T 检验，因为..."
```

**核心原则：Node.js 决定"做什么"，LLM 决定"怎么说"和"怎么想"。两者缺一不可。**

---

## 4. 意图 → 编排流程 → LLM 角色映射

| 意图 | Node.js 编排流程 | 对话层 LLM 角色 |
|------|-----------------|----------------|
| **chat** | 几乎不介入 | **完全主导**：直接回答，DataContext 保证数据感知 |
| **explore** | 调用 READ 层工具 | **翻译+解读**：JSON → 自然语言数据解读 |
| **consult** | 调用 method_consult | **融合+解释**：决策表结果 → 完整方法推荐 |
| **analyze** | 调用 THINK+ACT 全链路 | **播报+衔接**：步骤进展说明，上下文衔接 |
| **discuss** | 提取分析结果 | **深度解读**：统计学问题的专业解答 |
| **feedback** | 注入 QPER 记录 | **诊断+建议**：问题根因分析，新方案建议 |

---

## 5. 四层七工具实现机制总览

### 5.1 四层七工具实现机制一览

| 层 | 工具 | 实现机制 | LLM 参与 | 核心引擎 | 风险/成本 |
|----|------|---------|:---:|---------|----------|
| **READ** | `get_data_overview` | Python 计算 + LLM 推断 | ✅ 部分 | DataProfileService (Python) | 零风险 |
| **READ** | `get_variable_detail` | 纯 Python 计算 | ❌ | DataProfileService (Python) | 零风险 |
| **READ** | `method_consult` | 匹配引擎 + LLM 补充 | ✅ 部分 | DecisionTableService (规则) | 零风险 |
| **INTERACT** | `ask_user` | 纯系统机制 | ❌ | Node.js → 前端 → 用户 | 零风险 |
| **THINK** | `analysis_plan` | 匹配引擎 + 模板填充 | ❌ | DecisionTable + FlowTemplate | 低风险 |
| **ACT** | `run_step` | 纯 R 引擎执行 | ❌ | WorkflowExecutor → R Plumber | 有计算成本 |
| **ACT** | `write_report` | LLM 生成 + 槽位注入 | ✅ 核心 | ReflectionService (LLM) | 有 Token 成本 |

### 5.2 辅助机制

| 机制 | 实现方式 | LLM 参与 |
|------|---------|:---:|
| **意图路由器** | 规则引擎优先 + LLM 兜底（混合路由） | ✅ 部分 |
| **反思 — 自动重试** | 错误分类器（规则） + LLM 修正参数 | ✅ 部分 |
| **反思 — 手动触发** | LLM 分析完整 QPER 记录 → 新方案 | ✅ 核心 |
| **Session 黑板** | Node.js 内存缓存 | ❌ |
| **Token 控制** | 代码裁剪函数 | ❌ |
| **data_source 注入** | Node.js 编排层自动注入 | ❌ |

---

## 6. READ 层 — 只读，零风险

### 6.1 get_data_overview

> **实现机制：Python 统计计算 + LLM PICO 推断（两步串联）**

```
                    ┌──────────────────────────────────┐
  session_id ──→   │  Step 1: DataProfileService       │  ← 纯 Python 计算
                    │  （Python pandas 统计分析）         │     无 LLM
                    │  输出：行数/列数/缺失率/类型/分布    │
                    └──────────────┬───────────────────┘
                                   │ 结构化 JSON
                                   ▼
                    ┌──────────────────────────────────┐
                    │  Step 2: LLM PICO 推断            │  ← LLM Prompt
                    │  输入：统计摘要 + 临床知识          │     纯推理，无工具调用
                    │  输出：population / intervention /  │
                    │        outcome 候选 + 置信度        │
                    └──────────────┬───────────────────┘
                                   │ 合并
                                   ▼
                         写入 Session 黑板
```

**实现细节：**

| 环节 | 引擎 | 说明 |
|------|------|------|
| 统计摘要生成 | **Python（pandas）** | 调用已有 `DataProfileService`，返回结构化 JSON |
| PICO 推断 | **LLM Prompt** | 将统计摘要注入 Prompt，LLM 基于临床知识推断 PICO 分类 |
| 结果缓存 | **Node.js 内存** | 写入 Session 黑板，后续工具直接读缓存 |

**关键约束：**
- Step 1（统计计算）和 LLM 完全无关，是确定性结果
- Step 2（PICO 推断）标记为 `inference`，必须经 `ask_user` 确认后才变为 `confirmed`
- 已有实现基础：`DataProfileService` 已能生成统计摘要并缓存

---

### 6.2 get_variable_detail

> **实现机制：纯 Python 计算（零 LLM）**

```
  session_id + variable_name
       │
       ▼
  ┌────────────────────────────────┐
  │  DataProfileService            │  ← 纯 Python 计算
  │  按需查询单列                    │     无 LLM
  │  输出：分布/直方图/异常值/样本值  │     确定性结果
  └────────────────────────────────┘
```

**实现细节：**

| 环节 | 引擎 | 说明 |
|------|------|------|
| 单列统计分析 | **Python（pandas）** | 计算分布、异常值、直方图分箱等 |

**关键约束：**
- 整个工具内部没有 LLM 参与，完全是 Python 数值计算
- 是 `get_data_overview` 的按需 drill-down，解决大数据集 Token 爆炸问题
- 需要在 Python 侧新增"单列查询" API（当前 `DataProfileService` 只有全量 profile）

---

### 6.3 method_consult

> **实现机制：决策表四维匹配 + LLM 推理补充（双引擎）**

```
  research_question + outcome_var + predictors + DataContext
       │
       ├──→ ┌─────────────────────────────────────────┐
       │    │  引擎 A: DecisionTableService             │  ← 规则匹配引擎
       │    │  四维匹配 Goal × OutcomeType ×             │     无 LLM
       │    │  PredictorType × Design                   │     确定性结果
       │    │  输出：primaryTool + fallbackTool           │
       │    └──────────────┬──────────────────────────┘
       │                   │ 匹配结果
       │                   ▼
       └──→ ┌─────────────────────────────────────────┐
            │  引擎 B: LLM 推理补充                     │  ← LLM Prompt
            │  输入：匹配结果 + DataContext + 统计知识    │     纯推理
            │  输出：                                    │
            │    rationale（选择理由）                    │
            │    prerequisites（前提条件）                │
            │    limitations（局限性）                    │
            │    alternatives（替代方案 + 适用场景）       │
            └─────────────────────────────────────────┘
```

**实现细节：**

| 环节 | 引擎 | 说明 |
|------|------|------|
| 方法选择（选什么） | **DecisionTableService** | 四维规则匹配，JSON 驱动，确定性、可审计 |
| 解释说明（为什么选） | **LLM Prompt** | 利用 LLM 统计学知识生成自然语言解释 |

**关键约束：**
- 核心决策（选什么方法）由规则引擎决定，不由 LLM 决定 — 确保可审计、可配置
- LLM 只负责"润色"和"补充" — 生成人类可读的理由和替代方案说明
- 决策表当前 ~10 条规则，覆盖 7 个 R 工具，JSON 驱动，方法学团队可编辑
- 未来工具扩展到 30+ 时，可在决策表前加一层 RAG Top-K 检索
- 已有实现基础：`DecisionTableService.match()` 已实现四维匹配

---

## 7. INTERACT 层 — 人机交互，零风险

### 7.1 ask_user

> **实现机制：纯系统机制（Node.js 请求-响应模式，零 LLM）**

```
  Node.js 编排层决定需要提问
       │
       ▼
  ┌──────────────────────────────────────────────────┐
  │  Step 1: Node.js 生成 ClarificationCard JSON      │  ← 无 LLM
  │  （question + options + context）                  │     Node.js 代码构造
  └──────────────┬───────────────────────────────────┘
                 │ SSE 推送 / HTTP Response
                 ▼
  ┌──────────────────────────────────────────────────┐
  │  Step 2: 前端 ClarificationCard 组件渲染           │  ← 前端 React
  │  用户看到选择卡片 → 点击选择 → 提交                 │
  └──────────────┬───────────────────────────────────┘
                 │ HTTP POST（用户选择结果）
                 ▼
  ┌──────────────────────────────────────────────────┐
  │  Step 3: Node.js 从 Session 黑板恢复上下文          │  ← 无 LLM
  │  将用户选择写入黑板 → 继续后续流程                    │
  └──────────────────────────────────────────────────┘
```

**实现细节：**

| 环节 | 引擎 | 说明 |
|------|------|------|
| 卡片生成 | **Node.js 代码** | 根据当前流程上下文构造问题和选项 |
| 卡片渲染 | **前端 React** | `ClarificationCard` 组件，支持单选/多选/自由文本 |
| 上下文恢复 | **Session 黑板** | 用户响应后，从黑板恢复上下文继续流程 |

**关键约束：**
- 工具本身完全不涉及 LLM — 它是一个"人机交互通道"
- 但"什么时候问、问什么"是由 Node.js 编排层决定的
- 当前实现为"请求-响应模式"：Node.js 发送卡片 → 中断等待 → 下一次 HTTP 请求恢复
- 不是 LLM Function Calling 挂起模式（那是 Phase 4+ 的预研方向）
- 已有实现基础：`QueryService.generateClarificationCards()` + `ClarificationCard` 前端组件

---

## 8. THINK 层 — 生成方案，低风险

### 8.1 analysis_plan

> **实现机制：决策表匹配 + 流程模板填充（确定性引擎，零 LLM）**

```
  confirmed_question + confirmed_methods + variable_mapping + DataContext
       │
       ▼
  ┌──────────────────────────────────────────────────┐
  │  Step 1: DecisionTableService.match()              │  ← 规则匹配引擎
  │  四维匹配 → 命中规则 → 得到 templateId              │     无 LLM
  └──────────────┬───────────────────────────────────┘
                 │ matchResult { templateId, primaryTool, fallbackTool }
                 ▼
  ┌──────────────────────────────────────────────────┐
  │  Step 2: FlowTemplateService.fill()                │  ← 模板引擎
  │  选择模板 → 填充参数 → EPV 防护 → 有序步骤列表      │     无 LLM
  │  输出：[{order, tool_code, params, depends_on}]    │     确定性结果
  └──────────────────────────────────────────────────┘
```

**实现细节：**

| 环节 | 引擎 | 说明 |
|------|------|------|
| 规则匹配 | **DecisionTableService** | 四维匹配（Goal × OutcomeType × PredictorType × Design） |
| 模板填充 | **FlowTemplateService** | 从 `flow_templates.json` 加载模板，填入变量名和参数 |
| EPV 防护 | **FlowTemplateService** | 检查事件数/自变量比，超限自动截断并生成免责声明 |

**关键约束：**
- 整个工具内部没有 LLM 参与 — 完全是规则匹配 + 模板填充的确定性计算
- 方法选择在 `method_consult` 阶段已完成并经用户确认，`analysis_plan` 只负责"编排顺序 + 填充参数"
- 输出包含确定的 `tool_code` + 完整 `params`，`run_step` 只需傻瓜式执行
- 生成后展示给用户审查，用户确认后才进入 ACT 层
- 已有实现基础：`FlowTemplateService.fill()` + `decision_tables.json` + `flow_templates.json`

---

## 9. ACT 层 — 执行，有成本

### 9.1 run_step

> **实现机制：纯 R 引擎执行（傻瓜式 API 转发，零 LLM）**

```
  step_definition { tool_code, params } + session_id
       │
       ▼
  ┌──────────────────────────────────────────────────┐
  │  Node.js 编排层：自动注入 data_source              │  ← 无 LLM
  │  从 Session 黑板取 dataOssKey → 生成预签名 URL      │     系统机制
  │  注入 params.data_source = { type:'oss', oss_url } │
  └──────────────┬───────────────────────────────────┘
                 │
                 ▼
  ┌──────────────────────────────────────────────────┐
  │  WorkflowExecutorService → RClientService          │
  │  HTTP POST 给 R Plumber API                        │  ← 无 LLM
  │  R 脚本执行统计分析                                  │     纯 R 引擎计算
  │  返回 ReportBlock[] + figures + r_code              │
  └──────────────────────────────────────────────────┘
```

**实现细节：**

| 环节 | 引擎 | 说明 |
|------|------|------|
| data_source 注入 | **Node.js 编排层** | 从 Session 黑板取 `dataOssKey`，生成预签名 URL 自动注入 |
| R 脚本执行 | **R Plumber API** | 接收 tool_code + params → 执行统计计算 → 返回结构化结果 |
| 结果标准化 | **R Block Helpers** | R 端输出标准化为 `ReportBlock[]` 格式 |

**关键约束：**
- 整个工具内部没有 LLM 参与 — 纯粹的 HTTP 转发 + R 引擎执行
- 是"傻瓜式 API 转发器"，不做任何方法选择决策
- `data_source` 由 Node.js 编排层自动注入，LLM 和 `analysis_plan` 全程不感知数据文件位置
- 错误处理由编排层接管（双轨反思机制）
- 已有实现基础：`WorkflowExecutorService` + `RClientService` + `resolveDataSource()` 全部已实现

---

### 9.2 write_report

> **实现机制：LLM 生成叙述 + 统计量槽位注入 + Zod 校验（LLM 为核心引擎）**

#### generate 模式（论文级报告）

```
  step_results + DataContext
       │
       ▼
  ┌──────────────────────────────────────────────────┐
  │  Step 1: 提取 Key Findings                        │  ← 无 LLM
  │  从 stepResults 中提取 p 值、置信区间、效应量等      │     纯代码提取
  │  生成 {{ slot }} 映射表                             │
  └──────────────┬───────────────────────────────────┘
                 │
                 ▼
  ┌──────────────────────────────────────────────────┐
  │  Step 2: LLM 生成叙述框架                         │  ← LLM 核心
  │  Prompt: "根据以下统计结果，生成论文级结论"          │     生成自然语言叙述
  │  LLM 输出包含 {{ slot }} 占位符                    │
  │  LLM 被禁止生成任何数值（反幻觉机制）               │
  └──────────────┬───────────────────────────────────┘
                 │
                 ▼
  ┌──────────────────────────────────────────────────┐
  │  Step 3: jsonrepair + Zod 校验 + 槽位渲染         │  ← 无 LLM
  │  校验 LLM 输出结构完整性                            │     确定性后处理
  │  用真实统计数值替换 {{ slot }} 占位符                │
  │  校验失败 → 降级到 ConclusionGeneratorService      │
  └──────────────────────────────────────────────────┘
```

#### interpret 模式（结果解读）

```
  user_question + step_results + DataContext
       │
       ▼
  ┌──────────────────────────────────────────────────┐
  │  LLM 深度解读                                     │  ← LLM 核心
  │  Prompt: DataContext + 分析结果 + 用户具体问题      │     纯推理
  │  输出：针对用户问题的统计学解读                      │
  └──────────────────────────────────────────────────┘
```

**实现细节：**

| 环节 | 引擎 | 说明 |
|------|------|------|
| Key Findings 提取 | **Node.js 代码** | 从 R 输出中提取关键统计量，构建槽位映射表 |
| 叙述框架生成 | **LLM (deepseek-v3)** | 生成论文级叙述，用 `{{ slot }}` 占位符替代数值 |
| 输出校验 | **jsonrepair + Zod** | 修复 JSON 格式 → Schema 强校验 → 确保结构完整 |
| 槽位渲染 | **Node.js 代码** | 用真实统计数值替换占位符 |
| 降级兜底 | **ConclusionGeneratorService** | Zod 校验失败时，规则拼接生成基础结论 |

**关键约束：**
- 这是 7 个工具中 LLM 参与度最高的，LLM 是核心引擎
- 但 LLM 不是"裸奔"的：统计量通过槽位注入从 R 输出渲染，LLM 被禁止生成数值（反幻觉）
- 三层防御：`jsonrepair` → `Zod Schema` → `ConclusionGeneratorService`（规则拼接兜底）
- 已有实现基础：`ReflectionService` + `ConclusionGeneratorService` 全部已实现

---

## 10. 辅助机制详解

### 10.1 意图路由器（IntentRouterService）

> **实现机制：规则引擎优先 + LLM 兜底（混合路由）**

```
  用户消息 + Session 上下文
       │
       ▼
  ┌──────────────────────────────────────┐
  │  Step 1: 规则匹配器                   │  ← 无 LLM
  │  关键词匹配 + 上下文状态推断           │     确定性、零延迟
  │  "执行""分析一下" → analyze            │
  │  "应该用什么方法" → consult             │
  │  "帮我看看" → explore                  │
  │  "p 值说明什么"(有结果) → discuss       │
  └──────────────┬───────────────────────┘
                 │
                 ├── 命中 → 直接返回意图（不调 LLM）
                 │
                 └── 未命中 ──→ ┌──────────────────────────┐
                                │  Step 2: LLM 轻量分类     │  ← LLM Prompt
                                │  仅做分类，不生成长文       │     低 Token 成本
                                │  输出：intent + confidence  │
                                └──────────────┬───────────┘
                                               │
                                               ├── confidence 足够 → 返回
                                               └── confidence 不足 → 默认 chat
```

**关键约束：**
- 规则优先：明确场景走规则，零延迟、零 Token 成本
- LLM 兜底：模糊场景走轻量级 LLM 分类（仅输出 intent + confidence，不生成长文）
- 默认安全：无法判断时 → chat（最安全的兜底，不触发任何流水线）

### 10.2 反思机制（编排层逻辑，非工具）

#### 自动反思（静默重试）

```
  run_step 返回 error
       │
       ▼
  ┌──────────────────────────────────────┐
  │  错误分类器                            │  ← 无 LLM
  │  读取 error_classification.json        │     规则匹配
  │  R 报错关键词 → 分类                    │
  └──────────┬──────────┬────────────────┘
             │          │
     可自愈（参数级）  不可自愈（方法级）
             │          │
             ▼          ▼
  ┌──────────────┐  ┌──────────────────────────┐
  │  LLM 修正参数 │  │  报告用户 + 建议替代方案   │
  │  注入错误日志  │  │  不重试                    │
  │  + DataContext │  └──────────────────────────┘
  │  → 重试(MAX 2) │
  └──────────────┘
       ← LLM Prompt
```

#### 手动反思（用户驱动）

```
  用户: "结果不对" / "换个方法试试"
       │
       ▼
  IntentRouter → feedback 意图
       │
       ▼
  ┌──────────────────────────────────────┐
  │  LLM 分析完整 QPER 记录              │  ← LLM 核心
  │  注入 qperTrace（滑动窗口摘要）       │     深度推理
  │  分析问题根因 → 生成新方案建议         │
  └──────────────┬───────────────────────┘
                 │
                 ▼
            ask_user → 新 analysis_plan → run_step → write_report
```

### 10.3 Session 黑板（纯系统基础设施）

```
┌─ Session Blackboard ─────────────────────────────────────┐
│  sessionId                                                │
│  dataOverview ← get_data_overview 写入                    │
│  confirmedPico ← ask_user 确认后写入                       │
│  variableDictionary ← 对话中逐步丰富                       │
│  dataOssKey ← 上传时写入（run_step 自动注入用）             │
│  currentPlan ← analysis_plan 写入                         │
│  stepResults ← run_step 每步追加                          │
│  report ← write_report 写入                               │
│  qperTrace ← 所有工具调用记录（反思用）                     │
└──────────────────────────────────────────────────────────┘

实现：纯 Node.js 内存缓存，无 LLM 参与
Token 控制：注入 LLM 前的裁剪函数（纯代码逻辑）
```

---

## 11. LLM 在架构中的准确定位

### 11.1 三层分类

```
┌─────────────────────────────────────────────────────────────┐
│                     完全不用 LLM 的                           │
│                                                              │
│  get_variable_detail — 纯 Python 计算                        │
│  ask_user — 纯系统机制（Node.js → 前端 → 用户）              │
│  analysis_plan — 纯规则匹配 + 模板填充                       │
│  run_step — 纯 R 引擎执行                                    │
│  Session 黑板 / Token 控制 / data_source 注入                │
│                                                              │
│  → 这些是"管道和基础设施"，确定性、可审计、零 Token 成本       │
├─────────────────────────────────────────────────────────────┤
│                     部分使用 LLM 的                           │
│                                                              │
│  get_data_overview — Python 计算（主） + LLM PICO 推断（辅）  │
│  method_consult — 决策表匹配（选什么） + LLM（解释为什么选）   │
│  意图路由器 — 规则优先（确定性） + LLM 兜底（模糊场景）       │
│  反思-自动重试 — 规则分类错误 + LLM 修正参数                  │
│                                                              │
│  → 这些是"引擎 + LLM 增强"，核心决策不依赖 LLM              │
├─────────────────────────────────────────────────────────────┤
│                     LLM 为核心的                              │
│                                                              │
│  write_report(generate) — LLM 生成叙述（但槽位注入防幻觉）   │
│  write_report(interpret) — LLM 深度解读用户问题               │
│  反思-手动触发 — LLM 分析完整 QPER 记录                      │
│  chat / explore 对话 — LLM(DataContext) 直接回复              │
│                                                              │
│  → 这些是"LLM 的主场"，充分发挥 LLM 知识和推理能力           │
└─────────────────────────────────────────────────────────────┘
```

### 11.2 LLM 调用点清单

| 调用点 | LLM 角色 | 模型 | 防护机制 |
|--------|---------|------|---------|
| PICO 推断 | 临床知识推理 | deepseek-v3 | ask_user 人工确认 |
| method_consult 补充 | 统计学知识解释 | deepseek-v3 | 决策表为主，LLM 只补充说明 |
| 意图路由 LLM 兜底 | 意图分类 | deepseek-v3 | 规则优先，LLM 只处理模糊场景 |
| write_report(generate) | 论文级叙述生成 | deepseek-v3 | 槽位注入 + Zod 校验 + 规则拼接兜底 |
| write_report(interpret) | 结果深度解读 | deepseek-v3 | DataContext 约束回答范围 |
| 反思-自动修正 | 参数级错误修复 | deepseek-v3 | MAX 2 次重试限制 |
| 反思-手动分析 | QPER 全记录分析 | deepseek-v3 | ask_user 确认新方案 |
| chat/explore 对话 | 自由知识对话 | deepseek-v3 | DataContext 注入提供约束 |

---

## 12. 架构哲学总结

### 12.1 核心协作模型

```
┌─────────────────────────────────────────────────────────────────┐
│                                                                  │
│                    Node.js 编排层（交通指挥）                      │
│                    ┌────────────────────────┐                    │
│                    │  意图路由 → 工具调度      │                    │
│                    │  Session 黑板读写         │                    │
│                    │  Token 控制 + 流程控制    │                    │
│                    └──┬──────────────┬──────┘                    │
│                       │              │                           │
│            ┌──────────┘              └──────────┐                │
│            ▼                                    ▼                │
│   ┌────────────────┐                  ┌────────────────┐        │
│   │  工具层（手脚）  │                  │  用户           │        │
│   │                │    结构化输出      │                │        │
│   │ Python 计算    │ ──────────────→   │  ask_user      │        │
│   │ DecisionTable  │                  │  PICO 确认     │        │
│   │ FlowTemplate   │                  │  方案审查      │        │
│   │ R 引擎         │                  │  反思决策      │        │
│   │ ErrorClassify  │                  └────────────────┘        │
│   └────────┬───────┘                                            │
│            │ 结构化输出                                          │
│            ▼                                                     │
│   ┌────────────────────────────────────────────────────┐        │
│   │           对话层 LLM（全局大脑）                      │        │
│   │                                                     │        │
│   │  System Prompt（角色 + DataContext + 意图指令）       │        │
│   │  + 对话历史（滑动窗口）                               │        │
│   │  + 工具输出（结构化 JSON）                            │        │
│   │                                                     │        │
│   │  → 自然语言生成    → 多轮对话连贯                     │        │
│   │  → 知识推理        → 主动引导                        │        │
│   │  → PICO 推断       → 结果解读                        │        │
│   │  → 方法解释        → 反思分析                        │        │
│   └────────────────────────────────────────────────────┘        │
│                       │                                          │
│                       ▼                                          │
│              自然语言回复 → 前端展示                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### 12.2 一句话总结

> **确定性的事交给规则引擎**（决策表、模板、R 脚本、Python 计算）  
> **需要知识和推理的事交给对话层 LLM**（理解意图、组织回复、知识推理、结果解读）  
> **需要判断和确认的事交给用户**（PICO 确认、方法选择、方案审查）  
> **三者通过 Node.js 编排层和 Session 黑板协同工作**

### 12.3 角色定位

| 层 | 角色类比 | 核心职责 | Token 成本 |
|----|---------|---------|-----------|
| **Node.js 编排层** | 交通指挥 | 决定做什么、走哪条路 | 零 |
| **对话层 LLM** | 统计顾问本人 | 理解、推理、表达、引导 | 有（核心开销） |
| **工具层** | 实验室设备 | 计算、匹配、执行 | 零（除 write_report） |
| **用户** | 最终决策者 | 确认、修正、决定方向 | 零 |

**对话层 LLM 是系统的大脑和嘴巴** — 它理解用户在说什么，知道该怎么回答，把工具的结构化输出变成人类能理解的对话。没有它，系统只是一堆互不关联的 API 调用。

---

---

**文档维护者：** SSA 架构团队  
**创建日期：** 2026-02-21  
**最后更新：** 2026-02-21（v1.1 — 新增对话层 LLM 架构说明，明确三层架构模型）  
**关联文档：**
- `SSA-Pro 工具体系规划方案（团队讨论稿）.md` — 工具定义（做什么）
- `SSA-Pro 意图识别与对话架构设计.md` — 意图路由 + System Prompt 策略
- `04-开发计划/11-智能对话与工具体系开发计划.md` — 开发落地计划

### 变更日志

| 版本 | 日期 | 变更内容 |
|------|------|---------|
| v1.0 | 2026-02-21 | 初版：四层七工具的内部实现机制 |
| v1.1 | 2026-02-21 | **新增对话层 LLM 架构**：① 明确三层架构（编排层 + 对话层 LLM + 工具层）；② 新增 System Prompt 架构（基础角色 + DataContext 注入 + 意图指令 + 对话历史）；③ 新增对话连贯性三大保障机制（对话历史注入 + Session 黑板持久化 + 意图切换上下文衔接）；④ 新增编排层 vs 对话层职责划分表 |