Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ssa): Implement dual-channel architecture Phase 1-3 (QPER + LLM Agent pipeline)

Browse Source 
Completed:
- Phase 1: DB schema (execution_mode + ssa_agent_executions), ModeToggle component, Session PATCH API
- Phase 2: AgentPlannerService + AgentCoderService (streaming) + CodeRunnerService + R Docker /execute-code endpoint
- Phase 3: AgentCodePanel (3-step confirmation UI), SSE event handling (7 agent events), streaming code display
- Three-step confirmation pipeline: plan -> user confirm -> stream code -> user confirm -> execute R code -> results
- R Docker sandbox /execute-code endpoint with 120s timeout + block_helpers preloaded
- E2E dual-channel test script (8 tests)
- Updated R engine architecture doc (v1.5) and SSA module status doc (v4.0)

Technical details:
- AgentCoderService uses LLM streaming (chatStream) for real-time code generation feedback
- ReviewerAgent temporarily disabled, prioritizing Plan -> Code -> Execute flow
- CodeRunnerService wraps user code with auto data loading (df variable injection)
- Frontend handles agent_planning, agent_plan_ready, code_generating, code_generated, code_executing, code_result events
- ask_user mechanism used for plan and code confirmation steps

Files: 24 files (4 new services, 2 new components, 1 migration, 1 E2E test, 16 modified)
Made-with: Cursor
This commit is contained in:
HaHafeng
2026-03-02 22:23:54 +08:00
parent 71d32d11ee
commit aadceb5cde
24 changed files with 2694 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,22 +1,26 @@
# SSA智能统计分析模块 - 当前状态与开发指南
> **文档版本：** v3.5
> **文档版本：** v4.0
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-23
> **最后更新：** 2026-03-02
> **维护者：** 开发团队
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A（分析方案变量可编辑化）开发完成**
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构（Agent 通道 Phase 1-3）开发完成**
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
>
> **最新进展（2026-02-23 Phase V-A 变量可编辑化完成）：**
> **最新进展（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）
> - ✅ **变量选择器 UI** — 单选下拉（按类型分组）+ 多选标签（分类=紫色 / 连续=蓝色）+ 全选分类/连续快捷按钮 + 不适配变量 ⚠️ 标记
> - ✅ **tool_param_constraints 配置** — 12 个统计工具参数约束表，前后端共用单一事实来源
> - ✅ **后端 PATCH API + Zod 防火墙** — PATCH /workflow/:id/params + 结构校验（400 Bad Request）/ 统计学校验交给 R 引擎
> - ✅ **同步阻塞执行** — 执行按钮 Promise Chaining：await PATCH -> 再触发执行 + loading 防连点
> - ✅ **inferGroupingVar 恢复** — LLM 未识别分组变量时，自动推断二分类变量填入默认值
> - ✅ **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）
@@ -64,11 +68,11 @@
|------|------|
| **模块名称** | SSA - 智能统计分析 (Smart Statistical Analysis) |
| **模块定位** | AI驱动的"白盒"统计分析系统 → 升级为"数据感知的统计顾问" |
| **架构模式** | **QPER（执行层）** + **四层七工具 + 对话层 LLM（智能对话层）** |
| **架构模式** | **双通道：QPER 管线（预制工具）+ LLM Agent 通道（代码生成）** + **四层七工具 + 对话层 LLM** |
| **前端状态模型** | **Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps** |
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
| **目标用户** | 临床研究人员、生物统计师 |
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A（变量可编辑化）完成** |
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 完成** |
### 核心目标
@@ -171,6 +175,10 @@ AnalysisRecord {
| **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 |
| **双通道 Phase 4** | **Prompt 工程 + 全面测试** | **~8h** | ⏳ 待用户体验测试确认后推进 | - |
| **Phase V-B** | **反思编排 + 高级特性** | **18h** | 📋 待开始 | - |
| **Phase VI** | **集成测试 + 可观测性** | **10h** | 📋 待开始 | - |
@@ -195,7 +203,8 @@ AnalysisRecord {
| **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 导出修复 | ✅ |
| **测试** | 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 前后端集成测试通过 | ✅ |
| **双通道 Agent 通道** | PlannerAgent（意图→分析计划）+ CoderAgent（计划→R 代码，含流式生成）+ CodeRunnerService（沙箱执行）+ AgentCodePanel（三步确认 UI）+ ModeToggle（通道切换）+ R Docker /execute-code 端点 | ✅ |
| **测试** | 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 通过 | ✅ |
---
@@ -217,6 +226,10 @@ backend/src/modules/ssa/
│ ├── 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：单变量详情
@@ -250,7 +263,9 @@ frontend-v2/src/modules/ssa/
│ ├── DynamicReport.tsx # Block-based 结果渲染
│ ├── DataContextCard.tsx # Phase I：五段式数据概览卡片
│ ├── VariableDictionaryPanel.tsx # Phase I：变量字典表格（可编辑）
│ └── VariableDetailPanel.tsx # Phase I：单变量详情面板
│ ├── VariableDetailPanel.tsx # Phase I：单变量详情面板
│ ├── AgentCodePanel.tsx # 双通道：Agent 管线三步确认 UI
│ └── ModeToggle.tsx # 双通道：QPER/Agent 通道切换
└── types/
└── index.ts # 前端类型定义
@@ -339,18 +354,24 @@ npx tsx scripts/seed-ssa-phase4-prompts.ts # Phase IV: SSA_ANALYZE_PLAN
### 近期（优先级高）
1. **Phase V-B — 反思编排 + 高级特性（18h / 3 天）**
1. **双通道 Phase 4 — Prompt 工程 + 全面测试**
- 用户体验测试确认双通道 Agent 管线
- Prompt 优化（PlannerAgent / CoderAgent 系统提示词精调）
- 错误处理增强（R 执行失败→LLM 自动修复重试，MAX 2 次）
- ReviewerAgent 按需启用（代码质量/安全审核）
2. **Phase V-B — 反思编排 + 高级特性（18h / 3 天）**
- 错误分类器实现（可自愈 vs 不可自愈）
- 自动反思（静默重试，MAX 2 次）+ 手动反思（用户驱动，feedback 意图）
- write_report interpret 模式 + discuss 意图处理（深度解读已有结果）
2. **Phase Deploy 收尾** — 前端三线表增强、决策表/流程模板补齐、ACR/SAE 部署
3. **Phase Deploy 收尾** — 前端三线表增强、决策表/流程模板补齐、ACR/SAE 部署
### 中期
3. **Phase VI（10h）** — 集成测试 + 可观测性（含 QPER 透明化）
4. **Phase VI（10h）** — 集成测试 + 可观测性（含 QPER 透明化）
**详细计划：** `04-开发计划/11-智能对话与工具体系开发计划.md`（v1.8，Phase I-IV + Phase V-A 完成，含架构约束 C1-C8 + 全部团队审查落地记录）
**详细计划：** `04-开发计划/11-智能对话与工具体系开发计划.md`（v1.8，Phase I-IV + Phase V-A 完成）+ 双通道架构计划详见 `06-开发记录/` 相关文档
---
@@ -395,7 +416,7 @@ npx tsx scripts/seed-ssa-phase4-prompts.ts # Phase IV: SSA_ANALYZE_PLAN
---
**文档版本：** v3.5
**最后更新：** 2026-02-23
**当前状态：** 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A（变量可编辑化）已完成
**下一步：** Phase V-B（反思编排 + 高级特性，18h/3 天）
**文档版本：** v4.0
**最后更新：** 2026-03-02
**当前状态：** 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 已完成
**下一步：** 双通道 Phase 4（Prompt 工程 + 全面测试）→ Phase V-B（反思编排）