feat(ssa): finalize strict stepwise agent execution flow
Align Agent mode to strict stepwise generation and execution, add deterministic and safety hardening, and sync deployment/module documentation for Phase 5A.5/5B/5C rollout. - implement strict stepwise execution path and dependency short-circuiting - persist step-level errors/results and stream step_* progress events - add agent plan params patch route and schema/migration support - improve R sanitizer/security checks and step result rendering in workspace - update SSA module guide and deployment change checklist Made-with: Cursor
This commit is contained in:
@@ -1,13 +1,20 @@
|
||||
# SSA智能统计分析模块 - 当前状态与开发指南
|
||||
|
||||
> **文档版本：** v4.2
|
||||
> **文档版本：** v4.3
|
||||
> **创建日期：** 2026-02-18
|
||||
> **最后更新：** 2026-03-08
|
||||
> **最后更新：** 2026-03-11
|
||||
> **维护者：** 开发团队
|
||||
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 通道体验优化 + Agent Prompt 运营管理化完成**
|
||||
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 + Agent Prompt 运营管理化 + Phase 5A/5A.5/5B/5C 联调完成（严格分步写+分步执行）**
|
||||
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
|
||||
>
|
||||
> **最新进展（2026-03-08 Agent 核心 Prompt 接入运营管理端）：**
|
||||
> **最新进展（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`），任何一层失败自动降级
|
||||
@@ -88,12 +95,12 @@
|
||||
| 项目 | 信息 |
|
||||
|------|------|
|
||||
| **模块名称** | SSA - 智能统计分析 (Smart Statistical Analysis) |
|
||||
| **模块定位** | AI驱动的"白盒"统计分析系统 → 升级为"数据感知的统计顾问" |
|
||||
| **模块定位** | AI驱动的"白盒"统计分析系统 → 升级为"数据感知的统计顾问"（Agent 严格分步执行） |
|
||||
| **架构模式** | **双通道：QPER 管线（预制工具）+ LLM Agent 通道（代码生成）** + **四层七工具 + 对话层 LLM** |
|
||||
| **前端状态模型** | **Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps** |
|
||||
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
|
||||
| **目标用户** | 临床研究人员、生物统计师 |
|
||||
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 体验优化完成** |
|
||||
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 + Agent 体验优化 + Phase 5A/5A.5/5B/5C 联调完成** |
|
||||
|
||||
### 核心目标
|
||||
|
||||
@@ -203,8 +210,8 @@ AnalysisRecord {
|
||||
| **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** | **后端分步执行引擎（DB schema + 代码累加循环 + 错误分类短路 + 新 SSE 事件）** | **~10h** | 📋 待开始 | - |
|
||||
| **Phase 5C** | **前端分步展示（类型扩展 + AgentCodePanel 多步骤 UI + SSE 处理器）** | **~6h** | 📋 待开始 | - |
|
||||
| **Phase 5B** | **后端分步执行引擎（确定性种子 + 分步生成执行 + 错误分类短路 + step_* 事件）** | **~10h** | ✅ **已完成（严格分步主链）** | 2026-03-11 |
|
||||
| **Phase 5C** | **前端分步展示（类型扩展 + AgentCodePanel 多步骤 UI + SSE 处理器）** | **~6h** | ✅ **已完成（步骤状态与结果可视化）** | 2026-03-11 |
|
||||
| **Phase V-B** | **反思编排 + 高级特性** | **18h** | 📋 待开始 | - |
|
||||
| **Phase VI** | **集成测试 + 可观测性** | **10h** | 📋 待开始 | - |
|
||||
|
||||
@@ -229,7 +236,7 @@ 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 导出修复 | ✅ |
|
||||
| **双通道 Agent 通道** | PlannerAgent（意图→分析计划）+ CoderAgent（计划→R 代码，含流式生成）+ CodeRunnerService（沙箱执行）+ AgentCodePanel（三步确认 UI）+ ModeToggle（通道切换）+ R Docker /execute-code 端点 | ✅ |
|
||||
| **双通道 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 体验测试通过（统计分析结果+图表正常） | ✅ |
|
||||
@@ -401,9 +408,11 @@ npx tsx prisma/seed-ssa-agent-prompts.ts # Agent: SSA_AGENT_PLANNER + SSA
|
||||
```
|
||||
用户消息
|
||||
→ ChatHandlerService.handleAgentMode()
|
||||
→ AgentPlannerService.generatePlan() ← SSA_AGENT_PLANNER
|
||||
→ AgentCoderService.generateCodeStream() ← SSA_AGENT_CODER
|
||||
→ CodeRunnerService.executeCode() ← 纯 R 执行，无 Prompt
|
||||
→ 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
|
||||
```
|
||||
|
||||
---
|
||||
@@ -429,22 +438,18 @@ npx tsx prisma/seed-ssa-agent-prompts.ts # Agent: SSA_AGENT_PLANNER + SSA
|
||||
|
||||
### 近期（优先级高）
|
||||
|
||||
1. **Phase 5A — CoderAgent 防错护栏**
|
||||
- XML 标签提取：强制 `<r_code>...</r_code>` 标签 + `parseCode()` 严格正则
|
||||
- 防御性 Prompt：NA 处理 / 类型转换 / 因子水平检查 / tryCatch 规则注入
|
||||
- 高保真 Schema 注入：`buildDataContext()` 增加列类型 + 前 3 条样本值
|
||||
- R Docker AST 预检：`parse()` 语法检查在 `eval()` 之前
|
||||
1. **稳定性回归与压测**
|
||||
- 严格分步主链：计划确认不生成代码、执行阶段逐步生成与执行
|
||||
- 依赖短路：上游失败时后续步骤必须 `skipped`
|
||||
- DB 回显：`stepResults/errorMessage/seedAudit` 全链路可追溯
|
||||
|
||||
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`
|
||||
2. **Phase V-B — 反思编排 + 高级特性**
|
||||
- 完成分步结果汇总与反思层输出增强
|
||||
- 细化失败后的人类可读修复建议
|
||||
|
||||
3. **Phase 5C — 前端分步展示**
|
||||
- 类型扩展：`AgentExecutionRecord` 增加 `stepResults[]` + `currentStep`
|
||||
- AgentCodePanel 多步骤 UI（可折叠步骤卡片 + 状态/代码/结果/错误）
|
||||
- SSE 处理器适配新步骤级事件
|
||||
3. **Phase VI — 集成测试 + 可观测性**
|
||||
- 完善 step 级日志、指标和告警
|
||||
- 联调验证清单标准化
|
||||
|
||||
### 中期
|
||||
|
||||
@@ -497,7 +502,7 @@ npx tsx prisma/seed-ssa-agent-prompts.ts # Agent: SSA_AGENT_PLANNER + SSA
|
||||
|
||||
---
|
||||
|
||||
**文档版本：** v4.2
|
||||
**最后更新：** 2026-03-08
|
||||
**当前状态：** 🎉 SSA Agent 模式 MVP 完成（QPER 闭环 + Phase I-IV + Phase V-A + 双通道架构 + Agent 体验优化 + Prompt 运营管理化 + Phase 5A 护栏）
|
||||
**下一步：** Phase 5B（分步执行引擎）→ Phase 5C（前端分步展示）→ Phase V-B（反思编排）
|
||||
**文档版本：** 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（可观测性）
|
||||
|
||||
Reference in New Issue
Block a user