AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md

SSA智能统计分析模块 - 当前状态与开发指南

文档版本： v4.3
创建日期： 2026-02-18
最后更新： 2026-03-11
维护者： 开发团队
当前状态： 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 + Agent Prompt 运营管理化 + Phase 5A/5A.5/5B/5C 联调完成（严格分步写+分步执行）
文档目的： 快速了解SSA模块状态，为新AI助手提供上下文

最新进展（2026-03-11 Agent 分步执行主链落地）：

• ✅ 严格分步模式切换 — confirm_plan 不再生成整段 R 代码，仅进入执行确认；confirm_code 后按步骤逐步生成与执行
• ✅ 依赖失败短路 — 当前步骤重试失败后，后续步骤直接标记 skipped，不再继续写代码与执行
• ✅ 步骤结果可视化增强 — 右侧工作区在分步状态可展开查看每步 reportBlocks，便于排障与审计
• ✅ 失败原因可追溯 — stepResults.errorMessage 落库并可回显，定位链路稳定
• ✅ R 语法修复器纠偏 — 修正 } else 处理策略，降低 unexpected 'else' 误报

此前进展（2026-03-08 Agent 核心 Prompt 接入运营管理端）：

• ✅ PlannerAgent Prompt 动态化 — AgentPlannerService.buildSystemPrompt() 改为 PromptService.get('SSA_AGENT_PLANNER', { dataContext })，支持运营管理端在线编辑、灰度预览、版本管理
• ✅ CoderAgent Prompt 动态化 — AgentCoderService.buildSystemPrompt() 改为 PromptService.get('SSA_AGENT_CODER', { dataContext })，同上
• ✅ 三级容灾 — 数据库 ACTIVE 版本 → 内存缓存（5 分钟） → 代码 fallback（prompt.fallbacks.ts），任何一层失败自动降级
• ✅ 种子数据脚本 — prisma/seed-ssa-agent-prompts.ts 幂等写入初始 Prompt（upsert template + ACTIVE v1）
• ✅ Handlebars 模板变量 — 两个 Prompt 均使用 {{{dataContext}}} 三括号无转义渲染，运营可编辑模板内容但保留变量占位符

此前进展（2026-03-07 Agent 通道体验优化 — 方案 B 左右职责分离 + 10 项 Bug 修复）：

• ✅ 方案 B — 左右职责分离 — 左侧对话区仅输出简洁视线牵引提示，右侧工作区承载计划/代码/结果全部交互；双屏状态互斥同步（右侧操作→左侧追加审计消息）；历史穿梭（点击左侧卡片→右侧切换对应任务）
• ✅ JWT Token 刷新机制 — 前端 ensureFreshToken() 在 API 调用前检查并刷新过期 Token，解决 HTTP 401 问题
• ✅ 代码截断修复 — LLM maxTokens 4000→8000 + CSS max-height 60vh + word-break 优化
• ✅ 重试流式代码生成 — 后端重试改用 generateCodeStream() 流式生成，前端实时展示重试代码
• ✅ 错误信息增强 — R Docker 结构化错误（20+ 模式匹配 + 行号提取 + 错误分类 + 修复建议）；前端展示上次失败原因
• ✅ Prompt 铁律强化 — CoderAgent System Prompt 增加严格输出格式规则，禁止代码块内混入自然语言
• ✅ 代码解析器健壮化 — parseCode() 支持 XML/Markdown/推断三级匹配，过短代码抛错
• ✅ consoleOutput 类型防御 — 兼容 R Docker unboxedJSON 标量/数组两种返回格式
• ✅ Agent 进度条同步 — SSAWorkspacePane 从 agentExecution.status 派生 phase，步骤高亮正确
• ✅ 导出报告/查看代码按钮恢复 — Agent 模式下 hasResults 基于 reportBlocks 长度判断；SSACodeModal 支持 Agent 代码展示
• ✅ 执行中动态 UI — ExecutingProgress 组件（实时计时器 + 动态提示 + 步骤脉冲动画）
• ✅ Plan-and-Execute 分步执行架构设计完成 — 代码累加策略 + 工程护栏（XML 标签/AST 预检/防御性 Prompt/高保真 Schema/错误分类短路）

此前进展（2026-03-02 双通道架构 Phase 1-3 完成）：

• ✅ SSA 双通道架构 — QPER 管线 + LLM Agent 代码生成两条通道并行，前端一键切换
• ✅ Phase 1 基础设施 — DB schema（execution_mode + ssa_agent_executions）、前端 ModeToggle 组件、Session PATCH API
• ✅ Phase 2 Agent 服务 — PlannerAgent + CoderAgent（含流式生成）+ CodeRunnerService，ReviewerAgent 暂缓
• ✅ Phase 3 前端集成 — AgentCodePanel（分步展示：计划→流式代码→执行结果）、SSE 事件处理（7 种 Agent 事件）
• ✅ 三步确认式管线 — 生成计划→用户确认→流式生成代码→用户确认→执行 R 代码→展示结果+原始代码
• ✅ R Docker /execute-code 端点 — 沙箱执行 LLM 生成的 R 代码，120s 超时 + block_helpers 预加载
• ✅ E2E 测试 8/8 通过 — DB 迁移 + mode 切换 + R execute-code + Planner + Coder + Reviewer + CRUD
• ✅ 5 个代码审查问题修复 — R Docker 重启 / 数据双重加载 / Prompt 包列表修正 / URL 注入防护 / 架构文档更新

此前进展（2026-02-23 Phase V-A 变量可编辑化完成）：

• ✅ 分析方案变量可编辑化 — 系统默认帮选变量，医生可在方案审查阶段修改/调整变量选择
• ✅ 三层柔性拦截 — Layer 1 即时黄条警告 + Layer 2 步骤警告图标 + Layer 3 执行前阻断确认弹窗（Informed Consent）
• ✅ DynamicReport 增强 — 兼容 R 基线表对象格式 rows，Word 导出同步修复

此前进展（2026-02-22 Phase IV 完成）：

• ✅ Phase IV 全 5 批次完成 — ToolOrchestratorService（PICO hint 三层降级）+ handleAnalyze 重写（plan→analysis_plan SSE→LLM 方案说明→ask_user 确认）+ AVAILABLE_TOOLS 配置化（11 处改 toolRegistryService）+ 前端 SSE 对接（analysis_plan + plan_confirmed）
• ✅ 团队审查 H1-H3+B1-B2 全部落地 — H1 PICO hint 注入 / H2 幽灵卡片清除 / H3 SSE 严格串行 / B1 修改建议循环 / B2 旧 API 兼容
• ✅ SSA_ANALYZE_PLAN Prompt 入库 — 指导 LLM 用自然语言解释分析方案（步骤/理由/注意事项）
• ✅ E2E 测试 25/25 通过 — analyze 意图→analysis_plan 3 步骤→ask_user 确认卡片→旧 /workflow/plan 兼容→AVAILABLE_TOOLS 配置化→对话历史

此前进展（2026-02-22 Phase III 完成）：

• ✅ Phase III 全 5 批次完成 — ToolRegistryService（H2 仓储模式）+ MethodConsultService（PICO→DecisionTable→推荐）+ AskUserService（H3 概念统一 + H1 状态死锁防护）+ ChatHandlerService（handleConsult + handleAskUserResponse）
• ✅ H1 全局打断 — chat.routes 入口增加 pendingAskUser 检测，用户无视卡片直接打字时自动解除死锁
• ✅ AskUserCard 前端组件 — 4 种 inputType（single_select/multi_select/free_text/confirm）+ 跳过按钮
• ✅ SSA_METHOD_CONSULT Prompt 入库 — P1 格式约束（结论先行 + 结构化列表）
• ✅ E2E 测试 13/13 通过 + 4 跳过 — consult 意图 + 方法推荐 + 对话历史验证（4 跳过: PICO 未完整触发 ask_user 卡片，预期行为）

此前进展（2026-02-22 Phase II 完成）：

• ✅ Phase II 全 4 批次完成 — SystemPromptService（六段式 + H2 修正）+ ConversationService（持久化 + SSE 心跳 H1 + Placeholder H3）+ IntentRouterService（规则+LLM 混合+守卫 C5）+ ChatHandlerService（chat/explore/analyze/discuss 分发）
• ✅ 统一 /chat API — POST /sessions/:id/chat（SSE 流式）+ GET history + GET conversation
• ✅ 8 个 Prompt 种子入库 — SSA_BASE_SYSTEM + 6 意图指令 + SSA_INTENT_ROUTER
• ✅ 前端改造 — useSSAChat hook + SSAChatPane（SSE 流式 + ThinkingBlock + 意图标签 + H3 输入锁）
• ✅ E2E 测试 38/38 通过 — 6 意图分类 + SSE 流式 + 对话历史 + 上下文守卫

此前进展（2026-02-22 Phase I 完成）：

• ✅ Phase I 全 5 批次完成 — SessionBlackboard + GetDataOverview + GetVariableDetail + PICO 推断 + 前端三组件 + SSE 自动触发
• ✅ Python 扩展 — 正态性检验（Shapiro-Wilk/K-S）+ 完整病例数 + variable-detail 端点（H2: bins<=30）
• ✅ PICO Prompt 种子 — SSA_PICO_INFERENCE 已入库（含 H3 观察性研究 null 处理）
• ✅ E2E 测试 31/31 通过 — Python 端点 + 数据结构 + H2/H3 防护验证

此前进展（2026-02-22 Phase Deploy）：

• ✅ Phase Deploy R 工具层完成 — R 工具 7→12（+Fisher/ANOVA/Wilcoxon/线性回归/基线表），全部 Block-based 标准化，16/16 测试通过
• ⏳ Phase Deploy 剩余 — 前端三线表增强(#7)、决策表/流程模板补齐(#8-9)、ACR/SAE 部署(#10-11) 暂缓，不阻塞 Phase II

此前进展（2026-02-21）：

• ✅ 前后端集成测试 — 7 个 Bug 全部修复（R 引擎防御、意图识别、前端状态）
• ✅ 统一状态管理重构 — 消除 isWorkflowMode 双轨逻辑，AnalysisRecord 成为唯一数据源
• ✅ 多任务切换 — 点击不同卡片正确显示各自的分析计划和结果
• ✅ R 代码完整性 — 多步骤分析的所有步骤代码均可下载/复制

---

📊 模块概览

基本信息

项目	信息
模块名称	SSA - 智能统计分析 (Smart Statistical Analysis)
模块定位	AI驱动的"白盒"统计分析系统 → 升级为"数据感知的统计顾问"（Agent 严格分步执行）
架构模式	双通道：QPER 管线（预制工具）+ LLM Agent 通道（代码生成） + 四层七工具 + 对话层 LLM
前端状态模型	Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps
商业价值	⭐⭐⭐⭐⭐ 极高
目标用户	临床研究人员、生物统计师
开发状态	🎉 QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 + Agent 体验优化 + Phase 5A/5A.5/5B/5C 联调完成

核心目标

让不懂统计的医生完成专业级的统计分析。

三大特征：

1. 白盒：用户完全理解 AI 做了什么，为什么这样做
2. 严谨：统计护栏自动检测前提条件，违规时自动降级
3. 可交付：生成论文级结论 + 可在本地运行的 R 代码，支持审计复现

---

🏗️ QPER 四层架构

用户："比较两组血压有没有差别"
    │
    ▼
┌─ Q · Query ─────────────────────────────────────┐
│  LLM 意图解析 + Zod 动态防幻觉 + 追问卡片       │
│  输出：ParsedQuery { goal, y, x, design }        │
└──────────────────────┬──────────────────────────┘
                       ▼
┌─ P · Planner ────────────────────────────────────┐
│  决策表四维匹配 + 流程模板填充 + EPV 防护         │
│  输出：WorkflowPlan + PlannedTrace               │
└──────────────────────┬──────────────────────────┘
                       ▼
┌─ E · Execute ────────────────────────────────────┐
│  R 引擎执行 + SSE 实时进度 + Block-based 输出     │
│  输出：StepResult[] + ReportBlock[]               │
└──────────────────────┬──────────────────────────┘
                       ▼
┌─ R · Reflection ─────────────────────────────────┐
│  LLM 论文级结论 + 槽位注入 + Zod 校验            │
│  输出：ConclusionReport（6 要素）                 │
└──────────────────────────────────────────────────┘

降级体系

层	正常路径	降级路径	触发条件
Q	QueryService（LLM）	正则匹配 fallback	LLM 超时/不可用
P	DecisionTable + FlowTemplate	硬编码 if/else	决策表无匹配
E	R 引擎	错误分类→友好提示	R 运行时崩溃
R	ReflectionService（LLM）	ConclusionGeneratorService（规则拼接）	LLM 失败/Zod 校验失败

---

🎨 前端架构：统一状态管理

2026-02-21 重构完成 — 消除 isWorkflowMode 双轨逻辑

数据模型

AnalysisRecord {
  id: string;                    // = workflowId or generated
  query: string;                 // 用户原始问题
  createdAt: string;
  status: 'planning' | 'executing' | 'completed' | 'error';
  plan: WorkflowPlan | null;     // 统一用 WorkflowPlan（单步也是 1 步的 Plan）
  steps: WorkflowStepResult[];   // 统一用步骤数组
  progress: number;              // 0-100
  conclusionReport: ConclusionReport | null;
}

Store 结构

• analysisHistory: AnalysisRecord[] — 所有分析记录
• currentRecordId: string | null — 当前激活的记录
• 派生：currentRecord = analysisHistory.find(r => r.id === currentRecordId)
• 操作：addRecord(query, plan) / updateRecord(id, patch) / selectRecord(id)

已删除的全局字段

currentPlan、executionResult、traceSteps、workflowPlan、workflowSteps、workflowProgress、conclusionReport、isWorkflowMode 及所有对应 setter。

---

📋 开发进度

Phase	任务	工时	状态	完成日期
Phase 0	需求分析与架构设计	-	✅ 已完成	2026-02-18
Phase 1	骨架搭建（T 检验端到端）	-	✅ 已完成	2026-02-19
Phase 1.5	V11 UI 前后端联调	-	✅ 已完成	2026-02-20
Phase 2A	多步骤工作流 + 前端集成	-	✅ 已完成	2026-02-20
Phase E+	Block-based 标准化	15.5h	✅ 已完成	2026-02-20
Phase Q	LLM 意图理解	33h	✅ 已完成	2026-02-21
Phase P	决策表 + 流程模板	23h	✅ 已完成	2026-02-21
Phase R	LLM 论文级结论	22h	✅ 已完成	2026-02-21
集成测试	Bug 修复 + 统一状态管理重构	~4h	✅ 已完成	2026-02-21
架构设计	智能对话与工具体系架构设计	~8h	✅ 已完成	2026-02-22
Phase Deploy	工具补齐 + 部署上线	37h	🔶 R 层完成（12 工具），前端/部署待收尾	2026-02-22
Phase I	Session 黑板 + READ 层	30h	✅ 已完成（5 批次, 18 文件, E2E 31/31）	2026-02-22
Phase II	对话层 LLM + 意图路由器 + 统一对话入口	35h	✅ 已完成（4 批次, 12 文件, E2E 38/38, H1-H4 落地）	2026-02-22
Phase III	method_consult + ask_user 标准化	20h	✅ 已完成（5 批次, 12 文件, E2E 13/13+4skip, H1-H3+P1 落地）	2026-02-22
Phase IV	对话驱动分析 + QPER 集成	14h	✅ 已完成（5 批次, 11 文件, E2E 25/25, H1-H3+B1-B2 落地）	2026-02-22
Phase V-A	分析方案变量可编辑化	~6h	✅ 已完成（9 文件, 团队双视角审查 V2, 三层柔性拦截）	2026-02-23
双通道 Phase 1	基础设施（DB + 前端切换 + API）	~4h	✅ 已完成（DB schema + ModeToggle + PATCH API）	2026-03-02
双通道 Phase 2	Agent 服务层（Planner + Coder + Runner）	~6h	✅ 已完成（3 Agent 服务 + R execute-code 端点）	2026-03-02
双通道 Phase 3	前端集成（SSE + AgentCodePanel + 确认流程）	~6h	✅ 已完成（三步确认 + 流式代码 + 7 种 SSE 事件）	2026-03-02
Agent 体验优化	方案 B 左右职责分离 + 10 项 Bug 修复	~8h	✅ 已完成（12 文件, +931/-203 行）	2026-03-07
Plan-and-Execute 设计	分步执行架构设计（代码累加 + 工程护栏）	~4h	✅ 已完成（架构评审 + 三份评估报告）	2026-03-07
Phase 5A	CoderAgent 防错护栏（XML 标签 + AST 预检 + 防御性 Prompt + 高保真 Schema）	~6h	✅ 已完成	2026-03-08
Agent Prompt 管理化	PlannerAgent + CoderAgent Prompt 接入运营管理端（PromptService 三级容灾）	~2h	✅ 已完成（种子脚本 + fallback + 文档）	2026-03-08
Phase 5B	后端分步执行引擎（确定性种子 + 分步生成执行 + 错误分类短路 + step_ 事件）*	~10h	✅ 已完成（严格分步主链）	2026-03-11
Phase 5C	前端分步展示（类型扩展 + AgentCodePanel 多步骤 UI + SSE 处理器）	~6h	✅ 已完成（步骤状态与结果可视化）	2026-03-11
Phase V-B	反思编排 + 高级特性	18h	📋 待开始	-
Phase VI	集成测试 + 可观测性	10h	📋 待开始	-

已完成核心功能

组件	完成项	状态
R 服务	12 个 R 工具 + Block-based 输出 + JIT 护栏 + 防御性编程（NA 安全）	✅
Q 层	QueryService + LLM Intent + Zod 防幻觉 + 追问卡片 + 统计学意义关键词增强	✅
P 层	ConfigLoader + DecisionTable + FlowTemplate + PlannedTrace + 热更新 API	✅
E 层	WorkflowExecutor + RClient + SSE 实时进度 + 错误分类映射 + 参数日志	✅
R 层	ReflectionService + 槽位注入 + Zod 校验 + 敏感性冲突准则 + 结论缓存 + Word 增强	✅
前端	统一 Record 架构 + 多任务切换 + 已完成标记 + DynamicReport + Word/R 导出	✅
Python	DataProfileService（is_id_like 标记）+ CSV 解析 + 正态性检验 + 单变量详情	✅
Phase I 黑板	SessionBlackboardService（互斥锁 patch）+ GetDataOverview + GetVariableDetail + PICO 推断 + TokenTruncation	✅
Phase I 前端	DataContextCard + VariableDictionaryPanel + VariableDetailPanel + ssaStore dataContext 扩展	✅
Phase II 后端	SystemPromptService（六段式+H2）+ ConversationService（持久化+SSE H1+Placeholder H3）+ IntentRouterService（规则+LLM+守卫 C5）+ ChatHandlerService + chat.routes + intent_rules.json + 8 Prompt 种子	✅
Phase II 前端	useSSAChat hook（SSE 流式）+ SSAChatPane 改造（ThinkingBlock + 意图标签 + H3 输入锁 + 中断按钮）	✅
Phase III 后端	ToolRegistryService（H2 仓储模式 IToolRepository）+ MethodConsultService（PICO→DecisionTable→推荐）+ AskUserService（H3 概念统一 + H1 clearPending）+ ChatHandlerService 扩展（handleConsult + handleAskUserResponse）+ chat.routes H1 全局打断 + SSA_METHOD_CONSULT Prompt P1	✅
Phase III 前端	AskUserCard（4 inputType + H1 跳过按钮）+ useSSAChat 扩展（pendingQuestion + respondToQuestion + skipQuestion）	✅
Phase IV 后端	ToolOrchestratorService（plan+PICO hint 三层降级+formatPlanForLLM）+ ChatHandlerService 重写（handleAnalyze: plan→analysis_plan SSE→LLM 说明→ask_user 确认; handleAskUserResponse: confirm_plan/change_method）+ AVAILABLE_TOOLS 配置化（11 处→toolRegistryService）+ ToolRegistryService（+getVisibleTools）+ AskUserService（+metadata）+ SSA_ANALYZE_PLAN Prompt 入库	✅
Phase IV 前端	useSSAChat（analysis_plan+plan_confirmed SSE 处理+pendingPlanConfirm→executeWorkflow）+ SSAChatPane（AskUserCard 渲染+幽灵卡片清除 H2）	✅
Phase V-A 后端	PATCH /workflow/:id/params（Zod 结构校验防火墙）+ tool_param_constraints.json（12 工具参数约束）+ inferGroupingVar 恢复（默认填充分组变量）	✅
Phase V-A 前端	WorkflowTimeline 可编辑化（SingleVarSelect + MultiVarTags + 三层柔性拦截）+ ssaStore updateStepParams + SSAWorkspacePane 同步阻塞执行 + DynamicReport 对象 rows 兼容 + Word 导出修复	✅
双通道 Agent 通道	PlannerAgent（意图→分析计划）+ CoderAgent（按步骤生成 R 代码，执行阶段逐步生成）+ CodeRunnerService（沙箱执行）+ AgentCodePanel（三步确认 UI）+ ModeToggle（通道切换）+ R Docker /execute-code 端点	✅
Agent 体验优化	方案 B 左右职责分离（视线牵引+状态互斥+历史穿梭）+ JWT 刷新 + 代码截断修复 + 重试流式生成 + R Docker 结构化错误（20+ 模式）+ Prompt 铁律 + parseCode 健壮化 + consoleOutput 类型防御 + 进度条同步 + 导出/查看代码恢复 + ExecutingProgress 动态 UI	✅
Agent Prompt 管理化	PlannerAgent + CoderAgent System Prompt 从硬编码迁移至 PromptService 动态加载；运营管理端在线编辑/灰度预览/版本回滚；三级容灾（DB→缓存→fallback）；种子脚本 seed-ssa-agent-prompts.ts 幂等	✅
测试	QPER 端到端 40/40 + 集成测试 7 Bug 修复 + Phase I E2E 31/31 + Phase II E2E 38/38 + Phase III E2E 13/13+4skip + Phase IV E2E 25/25 + Phase V-A 前后端集成测试通过 + 双通道 E2E 8/8 通过 + Agent 体验测试通过（统计分析结果+图表正常）	✅

---

📂 代码目录结构

backend/src/modules/ssa/
├── services/
│   ├── QueryService.ts             # Q 层：LLM 意图解析
│   ├── DecisionTableService.ts     # P 层：四维匹配
│   ├── FlowTemplateService.ts      # P 层：流程模板
│   ├── WorkflowPlannerService.ts   # P 层：核心规划入口
│   ├── WorkflowExecutorService.ts  # E 层：步骤编排 + SSE
│   ├── RClientService.ts           # E 层：R 引擎调用
│   ├── ReflectionService.ts        # R 层：LLM 结论生成
│   ├── ConclusionGeneratorService.ts # R 层 fallback
│   ├── DataProfileService.ts       # 共享：Python 数据质量 + variable-detail
│   ├── DataParserService.ts        # 共享：文件解析
│   ├── SessionBlackboardService.ts # Phase I：Session 黑板（互斥锁 patch）
│   ├── PicoInferenceService.ts     # Phase I：LLM PICO 推断
│   ├── TokenTruncationService.ts   # Phase I：Token 截断框架
│   ├── AgentPlannerService.ts     # 双通道：LLM 生成分析计划
│   ├── AgentCoderService.ts       # 双通道：LLM 生成 R 代码（含流式）
│   ├── AgentReviewerService.ts    # 双通道：代码审核（暂缓启用）
│   ├── CodeRunnerService.ts       # 双通道：R 沙箱代码执行
│   └── tools/
│       ├── GetDataOverviewTool.ts  # Phase I：数据概览 + 五段式报告
│       └── GetVariableDetailTool.ts # Phase I：单变量详情
├── config/
│   ├── ConfigLoader.ts             # 通用 JSON 加载 + Zod 校验
│   ├── tools_registry.json         # R 工具注册表
│   ├── decision_tables.json        # 四维匹配规则
│   ├── flow_templates.json         # 流程模板
│   └── tool_param_constraints.json # Phase V-A：12 工具参数类型约束
├── types/
│   ├── query.types.ts              # Q 层接口
│   ├── reflection.types.ts         # R 层接口
│   └── session-blackboard.types.ts # Phase I：黑板类型 + Zod Schema
├── routes/
│   ├── workflow.routes.ts          # 工作流 API（含结论缓存）
│   ├── blackboard.routes.ts        # Phase I：黑板 CRUD + 变量 PATCH
│   └── config.routes.ts            # 热更新 API
└── ...

frontend-v2/src/modules/ssa/
├── stores/
│   └── ssaStore.ts                 # Zustand — Unified Record Architecture
├── hooks/
│   ├── useWorkflow.ts              # 工作流 Hook（addRecord/updateRecord）
│   └── useAnalysis.ts              # 上传/Legacy 兼容
├── components/
│   ├── SSAChatPane.tsx             # 对话区（卡片 → selectRecord）
│   ├── SSAWorkspacePane.tsx        # 工作区（基于 currentRecord 渲染）
│   ├── SSACodeModal.tsx            # R 代码模态框（从 record.steps 聚合）
│   ├── WorkflowTimeline.tsx        # 执行计划时间线
│   ├── DynamicReport.tsx           # Block-based 结果渲染
│   ├── DataContextCard.tsx         # Phase I：五段式数据概览卡片
│   ├── VariableDictionaryPanel.tsx # Phase I：变量字典表格（可编辑）
│   ├── VariableDetailPanel.tsx     # Phase I：单变量详情面板
│   ├── AgentCodePanel.tsx         # 双通道：Agent 管线三步确认 UI
│   └── ModeToggle.tsx             # 双通道：QPER/Agent 通道切换
└── types/
    └── index.ts                    # 前端类型定义

r-statistics-service/
├── plumber.R                       # API 入口（含参数日志 + Agent 结构化错误处理）
├── utils/
│   └── error_codes.R              # Agent 通道：20+ 错误模式匹配 + format_agent_error
└── tools/
    └── descriptive.R               # 描述性统计（NA 安全防御）

---

🔧 开发环境

启动服务

# 1. 数据库（Docker）
docker start ai-clinical-postgres

# 2. Python 服务
cd extraction_service && python main.py

# 3. R 服务
cd r-statistics-service && Rscript plumber_api.R

# 4. Node.js 后端
cd backend && npm run dev

# 5. 前端
cd frontend-v2 && npm run dev

运行测试

cd backend

# QPER 端到端测试
npx tsx scripts/test-ssa-qper-e2e.ts

# Phase I 端到端测试（需 Python + Node.js 在线）
node scripts/test-phase-i-e2e.cjs

# Phase II 端到端测试（需后端在线）
npx tsx scripts/test-ssa-phase2-e2e.ts

# Phase III 端到端测试（需后端在线）
npx tsx scripts/test-ssa-phase3-e2e.ts

# Phase IV 端到端测试（需后端 + 数据库在线）
npx tsx scripts/test-ssa-phase4-e2e.ts

Prompt 种子（需数据库运行）

cd backend
npx tsx scripts/seed-ssa-intent-prompt.ts
npx tsx scripts/seed-ssa-reflection-prompt.ts
npx tsx scripts/seed-ssa-pico-prompt.ts         # Phase I: PICO 推断
npx tsx scripts/seed-ssa-phase2-prompts.ts      # Phase II: 8 Prompt
npx tsx scripts/seed-ssa-phase3-prompts.ts      # Phase III: SSA_METHOD_CONSULT
npx tsx scripts/seed-ssa-phase4-prompts.ts      # Phase IV: SSA_ANALYZE_PLAN
npx tsx prisma/seed-ssa-agent-prompts.ts        # Agent: SSA_AGENT_PLANNER + SSA_AGENT_CODER

---

🧠 Prompt 全景盘点（QPER vs Agent）

结论：当前 Agent 模式仅使用 2 个 Prompt，其余 11 个为 QPER 遗产。

自 chat.routes.ts 硬编码 executionMode = 'agent' 后，QPER 通道代码不再执行。

Agent 通道 Prompt（当前生效 ✅）

#	Prompt Code	服务	模板变量	用途
1	SSA_AGENT_PLANNER	AgentPlannerService	{{{dataContext}}}	规划师 System Prompt：制定统计分析计划（JSON 格式）
2	SSA_AGENT_CODER	AgentCoderService	{{{dataContext}}}	编码器 System Prompt：生成可执行 R 代码（XML 标签输出）

管理方式： 运营管理端 → Prompt 管理 → SSA 模块 → 在线编辑/灰度预览/版本管理
容灾链路： 数据库 ACTIVE 版本 → 内存缓存（5min TTL）→ 代码 fallback（prompt.fallbacks.ts）

QPER 通道 Prompt（当前不执行，保留备用）

#	Prompt Code	服务	用途
3	SSA_BASE_SYSTEM	SystemPromptService	QPER 对话基础角色定义
4	SSA_INTENT_ROUTER	IntentRouterService	LLM 意图分类器（6 种意图）
5	SSA_INTENT_CHAT	SystemPromptService	普通聊天意图指令
6	SSA_INTENT_EXPLORE	SystemPromptService	数据探索意图指令
7	SSA_INTENT_CONSULT	SystemPromptService	方法咨询意图指令
8	SSA_INTENT_ANALYZE	SystemPromptService	执行分析意图指令
9	SSA_INTENT_DISCUSS	SystemPromptService	结果讨论意图指令
10	SSA_INTENT_FEEDBACK	SystemPromptService	改进反馈意图指令
11	SSA_QUERY_INTENT	QueryService	Q 层 LLM 意图解析
12	SSA_PICO_INFERENCE	PicoInferenceService	PICO 结构推断
13	SSA_REFLECTION	ReflectionService	R 层论文级结论生成

Agent 调用链（仅 2 个 Prompt）

用户消息
  → ChatHandlerService.handleAgentMode()
    → AgentPlannerService.generatePlan()         ← SSA_AGENT_PLANNER
    → confirm_plan: enter code_pending only      ← 不提前生成整段代码
    → confirm_code: for each step
         → AgentCoderService.generateStepCodeStream() ← SSA_AGENT_CODER
         → CodeRunnerService.executeCode()            ← 纯 R 执行，无 Prompt

---

📚 相关文档

文档	路径
QPER 开发计划（主线）	04-开发计划/10-QPER架构开发计划-智能化主线.md
🆕 智能对话与工具体系开发计划	04-开发计划/11-智能对话与工具体系开发计划.md
🆕 意图识别与对话架构设计	00-系统设计/SSA-Pro 意图识别与对话架构设计.md
🆕 工具体系规划方案（融合方案）	00-系统设计/SSA-Pro 工具体系规划方案（团队讨论稿）.md
🆕 四层七工具实现机制详解	00-系统设计/SSA-Pro 四层七工具实现机制详解.md
QPER 开发总结	06-开发记录/SSA-QPER架构开发总结-2026-02-21.md
集成测试 Bug 修复	06-开发记录/2026-02-21-集成测试Bug修复与统一状态管理重构.md
智能化愿景设计	00-系统设计/SSA-Pro 理想状态与智能化愿景设计.md
PRD	00-系统设计/PRA SSA-Pro 严谨型智能统计分析模块.md
架构设计 V4	00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md

---

🎯 下一步

近期（优先级高）

1. 稳定性回归与压测

   • 严格分步主链：计划确认不生成代码、执行阶段逐步生成与执行
   • 依赖短路：上游失败时后续步骤必须 skipped
   • DB 回显：stepResults/errorMessage/seedAudit 全链路可追溯

2. Phase V-B — 反思编排 + 高级特性

   • 完成分步结果汇总与反思层输出增强
   • 细化失败后的人类可读修复建议

3. Phase VI — 集成测试 + 可观测性

   • 完善 step 级日志、指标和告警
   • 联调验证清单标准化

中期

4. Phase V-B — 反思编排 + 高级特性（18h）
5. Phase VI（10h） — 集成测试 + 可观测性（含 QPER 透明化）
6. Phase Deploy 收尾 — 前端三线表增强、决策表/流程模板补齐、ACR/SAE 部署

详细计划： 04-开发计划/11-智能对话与工具体系开发计划.md + 架构评审报告详见 07-统计专家配置/ 目录

---

🏗️ 智能对话架构概览（四层七工具 + 对话层 LLM）

设计目标： 从"统计分析执行器"升级为"数据感知的统计顾问"

用户消息
  │
  ▼
┌─ Intent Router ──────────────────────────────────────┐
│ 规则引擎优先 + LLM 兜底 + 上下文守卫（§16.5）       │
│ → chat / explore / consult / analyze / discuss / feedback │
└─────────────────────┬────────────────────────────────┘
                      ▼
┌─ Conversation Layer LLM ─────────────────────────────┐
│ 六段式 System Prompt + DataContext 注入 + 流式输出    │
│ Token 预算 ≤4000（§16.2）+ 禁止 Function Calling（§16.1）│
└─────────────────────┬────────────────────────────────┘
                      ▼
┌─ 四层七工具 ─────────────────────────────────────────┐
│ READ:  get_data_overview | get_variable_detail | method_consult │
│ INTERACT: ask_user                                    │
│ THINK: analysis_plan                                  │
│ ACT:   run_step | write_report                        │
└─────────────────────┬────────────────────────────────┘
                      ▼
┌─ QPER 执行层（已有） ────────────────────────────────┐
│ Q → P → E → R（四层降级体系，不动）                    │
└──────────────────────────────────────────────────────┘

关键架构约束（详见开发计划 §16-§17）：

#	约束
C1	对话层 LLM 禁止 Function Calling tools 参数
C4	Session 黑板使用 CacheFactory（Postgres-Only，无 Redis）
C5	数据依赖意图必须有上下文守卫
C6	LLM 枚举输出必须 Zod 动态校验

---

文档版本： v4.3
最后更新： 2026-03-11
当前状态： 🎉 SSA Agent 模式已进入严格分步执行（QPER 闭环 + Phase I-IV + Phase V-A + Prompt 运营管理化 + Phase 5A/5A.5/5B/5C）
下一步： 稳定性回归与压测 → Phase V-B（反思编排）→ Phase VI（可观测性）