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

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
2026-03-02 22:23:54 +08:00
parent 71d32d11ee
commit aadceb5cde
24 changed files with 2694 additions and 56 deletions
--- a/docs/02-通用能力层/06-R统计引擎/01-R统计引擎架构与部署指南.md
+++ b/docs/02-通用能力层/06-R统计引擎/01-R统计引擎架构与部署指南.md
@@ -1,9 +1,9 @@
 # R 统计引擎架构与部署指南

-> **版本：** v1.4  
-> **更新日期：** 2026-02-26  
+> **版本：** v1.5  
+> **更新日期：** 2026-03-02  
 > **维护者：** SSA-Pro 开发团队 / ASL 循证工具箱团队  
-> **状态：** ✅ 生产就绪（13 工具 + Block-based 标准化输出 — 新增 Meta 分析引擎）
+> **状态：** ✅ 生产就绪（13 工具 + Block-based 标准化输出 + Agent 代码执行端点）

 ---

@@ -49,9 +49,10 @@ R 统计引擎是平台的**专用统计计算服务**，基于 Docker 容器化
 │       ▼          ▼       通用能力层                          │
 │  ┌─────────────────────────────────────────────────────┐   │
 │  │              R 统计引擎 (Docker)                     │   │
-│  │  • /health         健康检查                          │   │
-│  │  • /api/v1/tools   工具列表                          │   │
-│  │  • /api/v1/skills  技能执行                          │   │
+│  │  • /health              健康检查                     │   │
+│  │  • /api/v1/tools        工具列表                     │   │
+│  │  • /api/v1/skills       技能执行（QPER 管线）        │   │
+│  │  • /api/v1/execute-code 代码执行（Agent 通道）       │   │
 │  └─────────────────────────────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -552,7 +553,65 @@ Content-Type: application/json
 - 根据 `suggested_tool` 自动切换到更合适的方法
 - 将 `checks` 结果展示给用户

-### 5.5 复合工具示例：基线特征表（Phase Deploy 新增）
+### 5.5 Agent 通道：执行任意 R 代码（v1.5 双通道架构新增）
+
+```http
+POST /api/v1/execute-code
+Content-Type: application/json
+```
+
+**请求体：**
+```json
+{
+  "code": "blocks <- list()\nblocks[[1]] <- make_markdown_block('Hello', title='Test')\nlist(status='success', report_blocks=blocks)",
+  "session_id": "xxx-xxx",
+  "timeout": 120
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `code` | string | ✅ | 要执行的 R 代码（可使用 block_helpers.R 的所有辅助函数） |
+| `session_id` | string | 否 | 会话 ID（用于日志追踪） |
+| `timeout` | number | 否 | 超时秒数，默认 120，最大 120 |
+
+**成功响应：**
+```json
+{
+  "status": "success",
+  "result": {
+    "status": "success",
+    "report_blocks": [
+      {"type": "markdown", "content": "Hello", "title": "Test"}
+    ]
+  },
+  "console_output": [],
+  "duration_ms": 42
+}
+```
+
+**错误响应：**
+```json
+{
+  "status": "error",
+  "error_code": "E_EXEC",
+  "message": "object 'xxx' not found",
+  "user_hint": "R 代码执行出错 (123ms): object 'xxx' not found",
+  "duration_ms": 123
+}
+```
+
+**沙箱安全机制：**
+- 代码在 `new.env(parent = globalenv())` 隔离环境中执行
+- `setTimeLimit` 强制超时（CPU + 挂钟时间 ≤ 120 秒）
+- 可访问 `block_helpers.R` 和 `data_loader.R` 中的所有辅助函数
+- 由 Node.js `CodeRunnerService` 自动注入 `input` 和 `df` 数据变量
+
+**调用方：** SSA 模块 Agent 通道（`CodeRunnerService.ts`），用于执行 LLM 生成的 R 代码。
+
+> **与 `/api/v1/skills/{tool_code}` 的区别：** `/skills` 端点执行**预制的统计工具**（白名单限制），`/execute-code` 端点执行**任意 R 代码**（由 LLM Agent 生成，经 ReviewerAgent 审核后执行）。
+
+### 5.6 复合工具示例：基线特征表（Phase Deploy）

 ```http
 POST /api/v1/skills/ST_BASELINE_TABLE
@@ -604,7 +663,7 @@ Content-Type: application/json

 > **特点：** `ST_BASELINE_TABLE` 是复合工具，基于 `gtsummary::tbl_summary()` 自动判断变量类型（连续/分类）、选择统计方法（T 检验/Mann-Whitney/卡方/Fisher），输出标准三线表。`report_blocks[0].metadata.is_baseline_table = true` 触发前端特殊渲染（P 值标星、rowspan 合并行）。

-### 5.6 Meta 分析示例（ASL 工具 5 — v1.4 新增）
+### 5.7 Meta 分析示例（ASL 工具 5 — v1.4 新增）

 ```http
 POST /api/v1/skills/ST_META_ANALYSIS
@@ -1364,7 +1423,8 @@ r-statistics-service/

 | 版本 | 日期 | 更新内容 |
 |------|------|----------|
-| v1.4 | 2026-02-26 | ASL Meta 分析引擎：工具 12→13（+ST_META_ANALYSIS），Dockerfile 新增 `meta` 包，新增 §5.6 Meta 分析 API 示例、陷阱 8（对数尺度反变换）、§9.5 Meta E2E 测试（36 断言全通过），架构图更新 ASL 调用方 |
+| v1.5 | 2026-03-02 | SSA 双通道架构：新增 `POST /api/v1/execute-code` 沙箱端点（§5.5）供 Agent 通道执行 LLM 生成的 R 代码，含超时 + 隔离环境；架构图新增 Agent 通道入口 |
+| v1.4 | 2026-02-26 | ASL Meta 分析引擎：工具 12→13（+ST_META_ANALYSIS），Dockerfile 新增 `meta` 包，新增 §5.7 Meta 分析 API 示例、陷阱 8（对数尺度反变换）、§9.5 Meta E2E 测试（36 断言全通过），架构图更新 ASL 调用方 |
 | v1.3 | 2026-02-22 | 开发者体验增强：新工具模板补全 report_blocks（§6.1）、各工具 params 速查表（§6.5）、R 语言 7 大陷阱实录（§6.6）、新增 R 包操作指南（§6.7）、新增 Q11-Q13 常见问题 |
 | v1.2 | 2026-02-22 | Phase Deploy 完成：工具 7→12（+Fisher/ANOVA/Wilcoxon/线性回归/基线表）、Dockerfile 新增 gtsummary 等 5 包、Block-based 输出协议文档化（§6.4）、全工具测试脚本 |
 | v1.1 | 2026-02-20 | Phase 2A 完成：7 个统计工具、JIT 护栏、热重载说明、常见问题补充 |
--- a/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
+++ b/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
@@ -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（反思编排）
--- a/docs/05-部署文档/03-待部署变更清单.md
+++ b/docs/05-部署文档/03-待部署变更清单.md
@@ -17,6 +17,7 @@
 |---|---------|---------|--------|------|
 | DB-1 | modules 表新增 `AIA_PROTOCOL`、`RM` 模块注册，IIT 名称改为「CRA质控」 | 无（运行 seed 脚本） | 高 | 运行 `node scripts/seed-modules.js`（upsert，可重复执行） |
 | DB-2 | RVW Prompt 更新：期刊名称修正为「中华脑血管病杂志」 | 无（重新运行迁移脚本或后台编辑） | 高 | 运行 `npx tsx scripts/migrate-rvw-prompts.ts` 或在 `/admin/prompts/RVW_EDITORIAL` 手动编辑 |
+| DB-3 | SSA 双通道：ssa_sessions 新增 execution_mode 列 + 新建 ssa_agent_executions 表 | `manual_migrations/20260223_add_execution_mode_and_agent_tables.sql` | 中 | 手动执行 SQL 或通过 Prisma 迁移 |

 ### 后端变更 (Node.js)

@@ -29,6 +30,7 @@
 | BE-5 | seed 数据：内部租户补充 RM、AIA_PROTOCOL 模块 | `prisma/seed.ts` | 仅影响新环境初始化 | — |
 | BE-6 | 用户模块配置校验放宽：不再限制必须在租户订阅范围内 | `userService.ts` | 重新构建镜像 | 校验改为「模块代码必须在 modules 表中存在」，支持给用户单独开通功能模块 |
 | BE-7 | 用户独立模块生效：user_modules 中的模块即使租户未订阅也纳入权限 | `module.service.ts` | 重新构建镜像 | 如 AIA_PROTOCOL 可单独配给用户 |
+| BE-8 | SSA 双通道架构：Agent 模式 4 服务 + ChatHandler 分流 + Session PATCH API | `Agent*.ts`, `CodeRunnerService.ts`, `ChatHandlerService.ts`, `chat.routes.ts`, `session.routes.ts` | 重新构建镜像 | 含 PlannerAgent / CoderAgent / ReviewerAgent / CodeRunner |

 ### 前端变更

@@ -55,7 +57,7 @@

 | # | 变更内容 | 涉及文件 | 需要操作 | 备注 |
 |---|---------|---------|---------|------|
-| — | *暂无* | | | |
+| R-1 | 新增 POST /api/v1/execute-code 端点（Agent 通道任意 R 代码执行） | `plumber.R` | 重新构建镜像 | 含超时 + 沙箱限制 |

 ### 环境变量 / 配置变更