AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro 工具体系规划方案（团队讨论稿）.md

SSA-Pro 工具体系规划方案

日期： 2026-02-21
版本： v3.1（融合方案 + 工程补强）
议题： SSA 智能统计分析助手的工具定义与规划
背景： 当前 100 个 R 执行工具是基础能力，但工具体系过于单一。需要规划更完整的工具层，让 LLM Agent 能够在分析的全生命周期中为用户服务。
结论： 经过多轮讨论和团队评审，确定融合方案（四层 7 工具 + 反思编排 + Session 黑板 + Token 控制 + data_source 自动注入）

---

一、当前问题

现状：系统只有 R 执行工具（约 100 个），用户发消息 → 系统直接匹配统计方法 → 执行 R 脚本。

问题：

• 用户无法与系统自由对话（每条消息都被当作分析请求）
• LLM 面对 100 个 R 工具会决策瘫痪（工具过载）
• 缺少"看数据""选方法""解读结果"等非执行类工具
• 分析全过程对用户不透明

---

二、工具设计原则

原则	含义
正交性	每个工具有唯一职责，不重叠
清晰触发	LLM 看到工具名就知道何时该用
组合性	工具可按不同顺序组合，下游只依赖上游输出而非特定调用链
粒度适中	太粗=黑箱，太细=决策负担；5-8 个工具是 LLM 的甜区
安全分级	只读工具随时调用，执行工具需确认
最小暴露	每个阶段只暴露完成当前任务所必需的工具子集
工具 vs 智能体	需要外部信息或改变外部世界 → 工具；纯 LLM 推理 → Prompt 职责，不封装为工具

---

三、融合方案总览

3.1 四层架构

┌─────────────────────────────────────────────────────────────┐
│                      LLM Agent 决策层                        │
│          根据对话上下文 + 当前阶段，选择调用哪个工具           │
└──┬─────────────┬──────────────┬──────────────┬──────────────┘
   │             │              │              │
   ▼             ▼              ▼              ▼
 READ 层       INTERACT 层    THINK 层       ACT 层
 只读，零风险   人机交互       生成方案       执行，有成本
 随时可调用     零风险         需用户审查     需用户确认

3.2 工具清单（7 个）

层	#	工具名	类型	一句话职责
READ	1	get_data_overview	只读	数据全貌：统计摘要 + 缺失 + 变量分类 + PICO 自动推断
READ	2	get_variable_detail	只读	单变量深入：分布 + 异常值 + 唯一值（按需查看，控制 Token）
READ	3	method_consult	只读	方法咨询：推荐统计方法 + 理由 + 前提 + 替代方案
INTERACT	4	ask_user	交互	向用户提问/确认：渲染为选择卡片，用于 PICO 确认、方案审查
THINK	5	analysis_plan	生成	分析规划：有序步骤 + 参数 + 依赖（输出确定的 tool_code + params）
ACT	6	run_step	执行	傻瓜式 R 执行：接收 tool_code + params，转发 R 引擎，返回结果
ACT	7	write_report	生成	论文级报告 / 结果解读（双模式：generate + interpret）

3.3 反思机制（不是工具，是编排层逻辑）

反思不定义为独立工具，而是系统编排机制，采用双轨触发：

自动触发（静默重试）：当 run_step 返回硬性错误（Column not found、NaN produced 等参数级错误），系统自动将错误日志注入 LLM 上下文，LLM 修正参数后静默重试，最多 2 次。用户无感知。

手动触发（用户驱动）：当执行成功但用户不满意（"能不能换个方法""把极值删了再跑一次"），意图路由器识别为 feedback 意图，将完整 QPER 记录注入 LLM，LLM 分析问题后生成新的 analysis_plan。

run_step 返回 error
  → 错误分类器
    → 可自愈（参数拼写、列名错误） → 自动修正 → 重试（最多 2 次）
    → 不可自愈（方法不适用、数据不足） → 报告用户 + 建议替代方案

用户表达不满
  → 意图路由器 → feedback 意图
  → 注入完整 QPER 记录 → LLM 分析原因 → 新的 analysis_plan → 重新执行

3.4 PICO 需求梳理（不是工具，是 Prompt 职责）

PICO 梳理在对话过程中自然完成，不需要专门的工具：

1. LLM 调用 get_data_overview → 返回中包含 AI 自动推断的 PICO 分类（置信度标记）
2. LLM 基于推断结果 + 临床知识 + System Prompt 组织 PICO 描述
3. LLM 调用 ask_user → 让用户确认/修正 PICO 分类
4. 确认后的 PICO 写入 Session 黑板，后续所有工具调用都携带

---

四、各工具详细定义

工具 1: get_data_overview

名称: get_data_overview
层级: READ（只读，零风险）
触发时机: 数据上传后自动调用 / 用户询问数据概况时
底层实现: DataProfileService（Python）

输入: {
  session_id: string
}

输出: {
  total_rows: number,
  total_columns: number,
  missing_overview: {
    overall_rate: number,
    columns_with_missing: [{ name, rate }]
  },
  categorical_vars: [{ name, levels_count, top_levels }],
  continuous_vars: [{ name, mean, sd, min, max }],
  id_like_vars: [string],
  data_structure: "cross-sectional" | "longitudinal" | "repeated-measures" | "unknown",
  sample_size_warning: string | null,

  // PICO 自动推断（AI 猜测，需用户通过 ask_user 确认后才生效）
  pico_inference: {
    population: string | null,
    intervention_var: string | null,
    intervention_levels: [string],
    outcome_candidates: [{ var, type, confidence }],
    design_guess: string | null,
    confidence: number       // 整体推断置信度
  }
}

设计要点：

• 输出一次性包含"下游需要的一切只读信息"，满足组合性原则
• PICO 推断标记为 inference（推断），不是 confirmed（确认），后续必须经过 ask_user 确认
• 输出写入 Session 黑板缓存，后续工具直接读缓存，不重复调用

工具 2: get_variable_detail

名称: get_variable_detail
层级: READ（只读，零风险）
触发时机: LLM 需要深入了解某个变量时（按需 drill-down）
底层实现: DataProfileService（Python），按需查询单列

输入: {
  session_id: string,
  variable_name: string
}

输出: {
  name: string,
  type: "continuous" | "categorical" | "ordinal" | "datetime" | "id",
  missing_rate: number,
  unique_values: number,
  distribution: {
    // 连续型: { mean, median, sd, q1, q3, min, max, histogram_bins }
    // 分类型: { levels: [{ value, count, percentage }] }
  },
  outliers: { count, threshold },
  sample_values: [...]
}

设计要点：

• 解决大数据集 Token 爆炸 — LLM 先看 overview 概览，再按需 drill-down 单列
• 多次调用查看不同变量，每次只增加一列的 Token 消耗

工具 3: method_consult

名称: method_consult
层级: READ（只读，零风险）
触发时机: 用户询问"应该用什么方法" / LLM 需要方法推荐时
底层实现: DecisionTableService 四维匹配 + LLM 推理补充

输入: {
  research_question: string,
  outcome_var: string,
  predictor_vars: [string],
  data_context: DataContext       // 从 Session 黑板读取
}

输出: {
  recommended_method: {
    name: string,                 // "Independent Samples T-Test"
    tool_code: string,            // "ST_T_TEST_IND"
    rationale: string,
    prerequisites: [string],      // ["正态性", "方差齐性"]
    limitations: [string]
  },
  alternatives: [{
    name, tool_code, when_to_use  // 何时该用替代方案
  }],
  warnings: [string]
}

设计要点：

• 当前 R 工具数量 7 个，决策表四维匹配（Goal × OutcomeType × PredictorType × Design）已足够精准
• 未来工具扩展到 30+ 时，可在此处引入 RAG Top-K 检索替代/增强决策表
• 只返回推荐，不执行。用户通过 ask_user 确认后才进入 THINK 层

工具 4: ask_user

名称: ask_user
层级: INTERACT（人机交互，零风险）
触发时机: LLM 需要用户确认或澄清时
前端渲染: 选择卡片（单选/多选）或输入框，嵌入对话流

输入: {
  question: string,
  context: string,
  options: [{
    id: string,
    label: string,
    description?: string
  }],
  allow_multiple: boolean,
  allow_free_text: boolean
}

输出: {
  selected_options: [string],
  free_text: string | null
}

设计要点：

• 强制 LLM 在不确定时向用户提问，而非自行猜测
• 贯穿全流程：PICO 确认、变量角色确认、方法选择确认、方案审查
• 前端已有 ClarificationCard 组件基础，需要标准化接口

实现方式（请求-响应模式，非 Function Calling 挂起）：

• 当前架构是 Node.js 编排层控制流程，不是 LLM 自主调用链
• ask_user 不需要"挂起 LLM 推理线程"：Node.js 生成卡片 → 返回前端 → 用户点击 → 前端 POST 新请求 → Node.js 从 Session 黑板恢复上下文 → 继续流程
• 已有实现基础：QueryService.generateClarificationCards() + /workflow/clarify 路由
• 未来若演进为 LLM Function Calling 模式（LLM 自主编排），需引入 Session 状态机 + 消息历史持久化（Phase 4 预研）

工具 5: analysis_plan

名称: analysis_plan
层级: THINK（生成方案，需用户审查）
触发时机: 用户确认需求和方法后
底层实现: FlowTemplateService 模板填充 + DecisionTableService 匹配

输入: {
  confirmed_question: string,
  confirmed_methods: [string],         // 用户确认的 tool_code 列表
  variable_mapping: {
    outcome: string,
    predictors: [string],
    confounders?: [string],
    group_var?: string
  },
  data_context: DataContext             // 从 Session 黑板读取
}

输出: {
  plan_id: string,
  title: string,
  steps: [{
    step_id: string,
    order: number,
    tool_code: string,                  // 确定的 R 工具代码，如 "ST_T_TEST_IND"
    tool_name: string,
    description: string,
    params: { ... },                    // 已填好的参数，run_step 直接透传
    depends_on: [step_id],
    expected_output: string
  }],
  estimated_duration: string,
  notes: [string]
}

设计要点：

• 输出包含确定的 tool_code 和完整 params，run_step 只需要傻瓜式执行
• 方法选择由 method_consult（决策表）+ 用户确认完成，analysis_plan 只负责编排顺序和填充参数
• 生成后展示给用户审查，用户确认后才进入 ACT 层

工具 6: run_step

名称: run_step
层级: ACT（执行，有计算成本）
触发时机: 用户确认分析计划后，逐步执行
底层实现: WorkflowExecutorService → RClientService → R Plumber API

输入: {
  step_definition: {                    // 直接来自 analysis_plan 输出的某一步
    step_id: string,
    tool_code: string,                  // 如 "ST_T_TEST_IND"
    params: { ... }
  },
  session_id: string
}

输出: {
  status: "success" | "warning" | "error",
  result: {
    blocks: ReportBlock[],
    figures: [{ type, data, title }],
    raw_output: { ... }
  },
  r_code: string,
  warnings: [string],
  error_message: string | null
}

设计要点：

• 傻瓜式 API 转发器 — 不做任何方法选择决策，只接收 tool_code + params → 调用 R → 返回结果
• data_source 自动注入 — LLM 和 analysis_plan 都不需要关心数据文件位置。Node.js 编排层自动从 Session 黑板取出 dataOssKey，生成预签名 URL，注入 { type: 'oss', oss_url: signedUrl } 后再 POST 给 R 服务（代码已实现：WorkflowExecutorService.resolveDataSource()）
• 错误处理由编排层接管（双轨反思机制）
• warning 状态的结果正常展示（R 引擎的 ggplot2 废弃警告等不影响结果）

工具 7: write_report

名称: write_report
层级: ACT（生成，有 LLM Token 成本）
触发时机: 步骤全部执行完成后 / 用户要求解读结果时
底层实现: ReflectionService（LLM 结论生成）+ 槽位注入 + Zod 校验

输入: {
  mode: "generate" | "interpret",
  step_results: [StepResult],           // generate 模式：全部步骤结果
  data_context: DataContext,
  user_question?: string                // interpret 模式：用户的具体问题
}

输出: {
  conclusion: {
    summary: string,
    detailed: string,
    clinical_significance: string,
    limitations: [string],
    recommendations: [string]
  },
  export_formats: ["word", "markdown"]
}

设计要点：

• 双模式：generate 生成完整论文级报告（QPER R 层），interpret 解读已有结果（新增能力，支持 discuss 意图）
• generate 模式在全部 run_step 完成后自动触发
• interpret 模式在用户追问结果时触发（"p 值说明什么""为什么置信区间这么宽"）

---

五、Session 黑板（状态管理）

5.1 为什么需要 Session 黑板

7 个工具本身是无状态函数。要让它们协同工作，需要一个后端"会话黑板"（Session Context Blackboard）在工具之间传递上下文。

核心规则：切勿让 LLM 反复重新生成上下文。 get_data_overview 的输出缓存到 Session，后续 analysis_plan / run_step / write_report 直接从 Session 读取，不重新调用。

5.2 Session 黑板结构

interface SessionBlackboard {
  sessionId: string;
  uploadedAt: string;

  // get_data_overview 的缓存输出
  dataOverview: DataOverviewResult | null;

  // 用户确认的 PICO（经过 ask_user 确认后写入）
  confirmedPico: {
    population: string;
    intervention: { var: string; levels: string[] };
    outcomes: [{ var: string; type: string; role: string }];
    confirmed: boolean;
  } | null;

  // 变量字典（对话中逐步丰富）
  variableDictionary: Array<{
    name: string;
    label: string;
    type: string;
    role: string;
    confirmed: boolean;
  }>;

  // 当前分析计划（analysis_plan 输出后写入）
  currentPlan: AnalysisPlanResult | null;

  // 数据文件信息（上传时写入，run_step 自动注入 data_source 用）
  dataOssKey: string | null;

  // 执行结果（run_step 每完成一步追加）
  // ⚠️ Token 控制：只保留当前生效计划的结果，废弃试错结果
  stepResults: StepResult[];

  // 结论报告（write_report 输出后写入）
  report: ReportResult | null;

  // QPER 执行记录（反思机制需要）
  // ⚠️ Token 控制：注入 LLM 前只保留最近 3 次关键事件，做摘要压缩
  qperTrace: Array<{
    timestamp: string;
    tool: string;
    input: any;
    output: any;
  }>;
}

5.3 Token 控制策略

Session 黑板会随着对话和试错不断膨胀。如果全量注入 LLM，会导致 Token 爆炸和注意力涣散。

规则 1：stepResults 只保留当前生效计划的结果

• 用户确认新的 analysis_plan 后，清空旧的 stepResults
• 反思迭代产生新方案时，旧方案的结果标记为 deprecated，不注入 LLM

规则 2：qperTrace 滑动窗口

• 注入 LLM 前，只保留最近 3 次关键事件（tool 调用 + 错误 + 修复动作）
• 早期的 trace 条目压缩为一行摘要（如"第 1 轮：T 检验成功"）

规则 3：R 引擎原始输出不入 LLM

• stepResults 中的 raw_output 只存储在黑板中供前端展示
• 注入 LLM 时只提取结构化摘要（关键数值、p 值、置信区间），不灌入完整日志

5.4 数据流

get_data_overview
  → 输出写入 blackboard.dataOverview
  → LLM 基于输出推断 PICO

ask_user（确认 PICO）
  → 用户选择写入 blackboard.confirmedPico

method_consult
  → 读取 blackboard.dataOverview + confirmedPico
  → 返回推荐方法（不写入 blackboard，只是对话中的回复）

analysis_plan
  → 读取 blackboard 全部上下文
  → 输出写入 blackboard.currentPlan

run_step ×N
  → 读取 blackboard.currentPlan 中的 step 定义
  → 每步输出追加到 blackboard.stepResults

write_report
  → 读取 blackboard.stepResults + dataOverview
  → 输出写入 blackboard.report

反思（自动/手动）
  → 读取 blackboard.qperTrace（完整记录）
  → 生成新的 analysis_plan → 覆盖 blackboard.currentPlan

5.5 持久化策略

层级	策略	理由
内存缓存	当前会话有效，进程重启丢失	快速读写，满足当前需求
数据库持久化	跨会话保留，支持历史回溯	后续扩展，用于分析记录和审计
当前实现	先用内存缓存（已有 DataProfileService 缓存机制）	快速落地

---

六、安全梯度与阶段性工具可见性

6.1 安全梯度

READ 层: get_data_overview / get_variable_detail / method_consult
  → 零风险，调用 100 次也无副作用
  → 对话阶段主要使用，支持自由探索
  → LLM 不确定时的安全默认选择

INTERACT 层: ask_user
  → 零风险，让用户参与决策
  → 贯穿全流程：PICO 确认、方案审查、结果追问

THINK 层: analysis_plan
  → 低风险，只生成方案不执行
  → 用户审查确认后才进入 ACT 层

ACT 层: run_step / write_report
  → 有成本（R 计算资源、LLM Token）
  → 产生真实结果，但可重新执行

6.2 阶段性工具可见性

不同阶段向 LLM 暴露不同的工具子集：

阶段	可见工具	隐藏工具
数据探索	get_data_overview, get_variable_detail, ask_user	method_consult, analysis_plan, run_step, write_report
需求梳理	全部 READ + ask_user	analysis_plan, run_step, write_report
方案规划	method_consult, ask_user, analysis_plan	run_step, write_report
分析执行	run_step, ask_user	其他
报告生成	write_report, ask_user	其他
自由对话	全部 READ + INTERACT	THINK + ACT

---

七、典型调用链

场景 1：完整分析旅程

用户上传数据
  → get_data_overview                          [自动] → 写入 Session 黑板
  → "您的数据有 200 行 15 列，推断为横截面..."    [LLM 回复]
  → 用户: "帮我看看 BMI 这个变量"
  → get_variable_detail("bmi")                 [LLM 调用]
  → ask_user("推断结局变量为 bp_change，         [LLM 调用]
      分组变量为 group，是否正确？")
  → 用户确认                                    → 写入 Session 黑板 confirmedPico
  → 用户: "帮我比较两组血压差异"
  → method_consult(...)                        [LLM 调用，从 Session 读上下文]
  → "建议独立样本 T 检验，理由..."               [LLM 回复]
  → ask_user("确认使用 T 检验分析？")            [LLM 调用]
  → 用户确认
  → analysis_plan(...)                         [LLM 调用] → 写入 Session 黑板
  → "分析计划：步骤1 描述统计 → 步骤2 T 检验"    [展示给用户]
  → 用户: "确认，开始执行"
  → run_step(step_1)                           [逐步执行] → 追加到 Session
  → run_step(step_2)                           [逐步执行] → 追加到 Session
  → write_report(mode: "generate")             [生成报告] → 写入 Session

场景 2：用户只是了解数据

用户: "这个数据有什么特点？"
  → get_data_overview                          [LLM 调用]
  → "您的数据包含 200 例患者，15 个变量..."      [LLM 基于缓存回复]

用户: "age 的分布怎样？"
  → get_variable_detail("age")                 [LLM 调用]

用户: "哪些变量缺失比较严重？"
  → [LLM 从 Session 黑板缓存直接回答，无需再调工具]

场景 3：方法咨询

用户: "BMI 和血压有关系吗？应该怎么分析？"
  → method_consult(...)                        [LLM 调用]
  → "建议 Pearson 相关分析，因为两个变量均为连续型..."
  → ask_user("是否需要控制混杂因素？",
      options: ["不需要", "控制年龄", "控制年龄和性别"])
  → 用户选择后 LLM 更新建议

场景 4：结果不满意，反思迭代

用户: "结果不对，p 值不应该这么大"
  → [编排层] 注入完整 qperTrace 到 LLM 上下文
  → LLM: "可能原因：样本量不足导致检验效能低..."
  → ask_user("建议：1)换用非参数检验 2)排除极值后重新分析 3)合并亚组")
  → 用户选择 "换用非参数检验"
  → analysis_plan(...)                         [生成新方案]
  → run_step(...)                              [重新执行]
  → write_report(mode: "generate")             [新报告]

场景 5：执行出错，自动修正

  → run_step(step_2)                           [执行]
  → R 返回 error: "Column 'Blood_Pressure' not found"
  → [编排层] 错误分类 → 可自愈（列名拼写）
  → [编排层] 自动注入错误 + 数据概览 → LLM 修正参数（bp_change）
  → run_step(step_2, 修正后参数)               [静默重试]
  → 成功 → 用户无感知

---

八、R 工具路由策略

当前方案：决策表四维匹配

100 个 R 脚本通过 run_step 调用时，方法选择在 method_consult / analysis_plan 阶段已确定：

用户需求 → method_consult 调用 DecisionTableService
         → 四维匹配（Goal × OutcomeType × PredictorType × Design）
         → 命中规则：primaryTool = ST_T_TEST_IND, fallbackTool = ST_MANN_WHITNEY
         → 用户确认 → analysis_plan 填充参数 → run_step 傻瓜式执行

决策表（decision_tables.json）当前有 ~10 条规则，覆盖 7 个 R 工具。规则驱动的确定性匹配比语义检索更精准、更可控。

未来扩展：RAG 增强

当 R 工具扩展到 30+ 且四维规则无法穷举时，可在 method_consult 内部增加 RAG 层：

method_consult 内部路由：
  1. 先走决策表匹配 → 命中则直接返回
  2. 未命中 → pgvector 语义检索 Top-5 工具 → LLM 从中选择 → 返回推荐

当前阶段不需要实现 RAG，决策表已足够。

---

九、与意图识别架构的关系

工具体系与意图路由器（详见《SSA-Pro 意图识别与对话架构设计》）配套工作：

意图路由器输出           可见工具                    典型调用
─────────────          ──────────                  ────────
chat（自由对话）    →    READ + INTERACT            data_overview / variable_detail
explore（数据探索） →    READ + INTERACT            data_overview / variable_detail / ask_user
consult（方法咨询） →    READ + INTERACT            method_consult / ask_user
analyze（分析执行） →    THINK + ACT + INTERACT     analysis_plan → run_step → write_report
discuss（结果讨论） →    ACT(write_report) + READ   write_report(interpret)
feedback（不满意）  →    反思编排 → THINK + ACT      analysis_plan → run_step → write_report

两个设计合在一起：

• 意图路由器决定"用户想干什么"→ 控制工具可见性
• 工具体系决定"系统能干什么"→ 提供能力边界
• Session 黑板贯穿全流程 → 所有工具共享上下文，避免重复生成

---

十、与现有 QPER 代码的映射

工具	现有组件	改造程度
get_data_overview	DataProfileService（已有）	低 — 封装为 Tool 接口 + 新增 PICO 推断字段
get_variable_detail	DataProfileService（需扩展）	中 — 新增单列查询 API
method_consult	DecisionTableService（已有）	中 — 封装为 Tool 接口 + LLM 推理补充
ask_user	ClarificationCard 前端组件（已有）	低 — 标准化后端接口
analysis_plan	Q 层 + P 层（FlowTemplateService 已有）	低 — 封装为 Tool 接口
run_step	E 层 WorkflowExecutorService（已有）	已有 — 当前就是傻瓜式执行
write_report	R 层 ReflectionService（已有）	中 — 新增 interpret 模式
Session 黑板	DataProfileService 缓存（部分已有）	中 — 扩展为完整 Blackboard
反思编排	无	新增 — 错误分类器 + 自动重试 + 手动触发

核心结论：QPER 四层的底层实现基本可复用，主要工作是封装 Tool 接口 + 新增 READ/INTERACT 层 + Session 黑板 + 意图路由。

---

十一、落地路线

Phase	工作内容	依赖现有组件	核心产出
Phase 1	READ + INTERACT 层	DataProfileService	get_data_overview + get_variable_detail + ask_user + Session 黑板
	目标：让系统能陪用户聊天，能看懂数据		即使不能跑分析，用户也能感受到 AI 的价值
Phase 2	意图路由器 + method_consult	DecisionTableService	意图分类 + 方法咨询 + 阶段性工具可见性
	目标：系统能区分对话/探索/咨询/分析意图
Phase 3	THINK + ACT 对接	QPER 全链路	analysis_plan + run_step + write_report 封装为 Tool 接口
	目标：把已有 QPER 挂载到新工具体系上
Phase 4	反思编排 + 高级特性	全部	双轨反思 + write_report interpret 模式 + 持久化

---

附：参考文档

• 00-系统设计/SSA-Pro 意图识别与对话架构设计.md — 意图路由器设计
• 00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md — QPER 架构
• 00-系统设计/SSA-Pro 理想状态与智能化愿景设计.md — 智能化愿景
• 06-开发记录/J技术报告审核评估与建议/SSA-Pro 智能体边界与工具生态规划报告.md — 团队架构评审