docs(ssa): Complete intelligent dialogue and tool system architecture design

Architecture Design: - Add intent recognition and dialogue architecture design (Intent Router + DataContext) - Add tool system planning (4-layer 7-tool fusion solution: READ/INTERACT/THINK/ACT) - Add 4-layer 7-tool implementation mechanism details (Conversation Layer LLM + Node.js orchestration) Development Plan (v1.2): - Create 6-phase development plan (134h/22 days) for intelligent dialogue system - Add 8 architectural constraints (C1-C8): no Function Calling, Postgres-Only cache, streaming output, context guard, Zod dynamic validation - Correct Session Blackboard to use CacheFactory (Postgres-Only, no Redis) Status Updates: - Update SSA module status: QPER complete + dialogue architecture design complete - Update system-level status: add SSA architecture design milestone Other: - R tools minor fixes (chi_square, correlation, logistic_binary, mann_whitney, t_test_paired) - Frontend AIA chat workspace style adjustment Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-22 10:05:14 +08:00
parent 11676f2840
commit bf10dec4c8
9 changed files with 3380 additions and 40 deletions
--- a/docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro
+++ b/docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro
@@ -0,0 +1,675 @@
+# 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 黑板结构
+
+```typescript
+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` — 团队架构评审