HaHafeng
52989cd03f
SSA Agent channel improvements (12 code files, +931/-203 lines): - Solution B: left/right separation of concerns (gaze guiding + state mutex + time-travel) - JWT token refresh mechanism (ensureFreshToken) to fix HTTP 401 during pipeline - Code truncation fix: LLM maxTokens 4000->8000 + CSS max-height 60vh - Retry streaming code generation with generateCodeStream() - R Docker structured errors: 20+ pattern matching + format_agent_error + line extraction - Prompt iron rules: strict output format in CoderAgent System Prompt - parseCode robustness: XML/Markdown/inference 3-tier matching + length validation - consoleOutput type defense: handle both array and scalar from R Docker unboxedJSON - Agent progress bar sync: derive phase from agentExecution.status - Export report / view code buttons restored for Agent mode - ExecutingProgress component: real-time timer + dynamic tips + step pulse animation Architecture design (3 review reports): - Plan-and-Execute step-by-step execution architecture approved - Code accumulation strategy (R Docker stays stateless) - 5 engineering guardrails: XML tags, AST pre-check, defensive prompts, high-fidelity schema, error classification circuit breaker Docs: update SSA module status v4.1, system status v6.7, deployment changelist Made-with: Cursor
450 lines
29 KiB
Markdown
450 lines
29 KiB
Markdown
# SSA智能统计分析模块 - 当前状态与开发指南
|
||
|
||
> **文档版本：** v4.1
|
||
> **创建日期：** 2026-02-18
|
||
> **最后更新：** 2026-03-07
|
||
> **维护者：** 开发团队
|
||
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 通道体验优化完成**
|
||
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
|
||
>
|
||
> **最新进展（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驱动的"白盒"统计分析系统 → 升级为"数据感知的统计顾问" |
|
||
| **架构模式** | **双通道：QPER 管线（预制工具）+ LLM Agent 通道（代码生成）** + **四层七工具 + 对话层 LLM** |
|
||
| **前端状态模型** | **Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps** |
|
||
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
|
||
| **目标用户** | 临床研究人员、生物统计师 |
|
||
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 体验优化完成** |
|
||
|
||
### 核心目标
|
||
|
||
> 让**不懂统计的医生**完成**专业级的统计分析**。
|
||
>
|
||
> **三大特征**：
|
||
> 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 双轨逻辑
|
||
|
||
### 数据模型
|
||
|
||
```typescript
|
||
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** | 📋 待开始 | - |
|
||
| **Phase 5B** | **后端分步执行引擎（DB schema + 代码累加循环 + 错误分类短路 + 新 SSE 事件）** | **~10h** | 📋 待开始 | - |
|
||
| **Phase 5C** | **前端分步展示（类型扩展 + AgentCodePanel 多步骤 UI + SSE 处理器）** | **~6h** | 📋 待开始 | - |
|
||
| **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 | ✅ |
|
||
| **测试** | 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 安全防御）
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 开发环境
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
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 种子（需数据库运行）
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
| 文档 | 路径 |
|
||
|------|------|
|
||
| **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. **Phase 5A — CoderAgent 防错护栏**
|
||
- XML 标签提取：强制 `<r_code>...</r_code>` 标签 + `parseCode()` 严格正则
|
||
- 防御性 Prompt：NA 处理 / 类型转换 / 因子水平检查 / tryCatch 规则注入
|
||
- 高保真 Schema 注入：`buildDataContext()` 增加列类型 + 前 3 条样本值
|
||
- R Docker AST 预检：`parse()` 语法检查在 `eval()` 之前
|
||
|
||
2. **Phase 5B — 后端分步执行引擎**
|
||
- DB: `SsaAgentExecution` 新增 `stepResults: Json[]` + `currentStep: Int?`
|
||
- 代码累加执行循环（R Docker 保持无状态，每步累加前序成功代码）
|
||
- 错误分类短路（Fatal→硬停 / Retriable→重试 MAX 2 / Soft→跳过）
|
||
- 新 SSE 事件：`step_coding / step_code_ready / step_executing / step_result / step_error / step_skipped / pipeline_aborted`
|
||
|
||
3. **Phase 5C — 前端分步展示**
|
||
- 类型扩展：`AgentExecutionRecord` 增加 `stepResults[]` + `currentStep`
|
||
- AgentCodePanel 多步骤 UI（可折叠步骤卡片 + 状态/代码/结果/错误）
|
||
- SSE 处理器适配新步骤级事件
|
||
|
||
### 中期
|
||
|
||
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.1
|
||
**最后更新：** 2026-03-07
|
||
**当前状态：** 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 体验优化已完成
|
||
**下一步：** Phase 5A（CoderAgent 防错护栏）→ Phase 5B（分步执行引擎）→ Phase 5C（前端分步展示）
|