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

feat(ssa): Agent channel UX optimization (Solution B) + Plan-and-Execute architecture design

Browse Source 
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
This commit is contained in:
HaHafeng
2026-03-07 22:32:32 +08:00
parent 87655ea7e6
commit 52989cd03f
18 changed files with 1334 additions and 230 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,13 +1,27 @@
# SSA智能统计分析模块 - 当前状态与开发指南
> **文档版本：** v4.0
> **文档版本：** v4.1
> **创建日期：** 2026-02-18
> **最后更新：** 2026-03-02
> **最后更新：** 2026-03-07
> **维护者：** 开发团队
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构（Agent 通道 Phase 1-3）开发完成**
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 通道体验优化完成**
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
>
> **最新进展（2026-03-02 双通道架构 Phase 1-3 完成）：**
> **最新进展（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 暂缓
@@ -72,7 +86,7 @@
| **前端状态模型** | **Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps** |
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
| **目标用户** | 临床研究人员、生物统计师 |
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 完成** |
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 体验优化完成** |
### 核心目标
@@ -178,7 +192,11 @@ AnalysisRecord {
| **双通道 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** | ⏳ 待用户体验测试确认后推进 | - |
| **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** | 📋 待开始 | - |
@@ -204,7 +222,8 @@ AnalysisRecord {
| **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 端点 | ✅ |
| **测试** | 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 体验优化** | 方案 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 体验测试通过（统计分析结果+图表正常） | ✅ |
---
@@ -270,7 +289,9 @@ frontend-v2/src/modules/ssa/
└── index.ts # 前端类型定义
r-statistics-service/
├── plumber.R # API 入口（含参数日志）
├── plumber.R # API 入口（含参数日志 + Agent 结构化错误处理）
├── utils/
│ └── error_codes.R # Agent 通道：20+ 错误模式匹配 + format_agent_error
└── tools/
└── descriptive.R # 描述性统计（NA 安全防御）
```
@@ -354,24 +375,30 @@ npx tsx scripts/seed-ssa-phase4-prompts.ts # Phase IV: SSA_ANALYZE_PLAN
### 近期（优先级高）
1. **双通道 Phase 4 — Prompt 工程 + 全面测试**
- 用户体验测试确认双通道 Agent 管线
- Prompt 优化（PlannerAgent / CoderAgent 系统提示词精调）
- 错误处理增强（R 执行失败→LLM 自动修复重试，MAX 2 次）
- ReviewerAgent 按需启用（代码质量/安全审核）
1. **Phase 5A — CoderAgent 防错护栏**
- XML 标签提取：强制 `<r_code>...</r_code>` 标签 + `parseCode()` 严格正则
- 防御性 Prompt：NA 处理 / 类型转换 / 因子水平检查 / tryCatch 规则注入
- 高保真 Schema 注入：`buildDataContext()` 增加列类型 + 前 3 条样本值
- R Docker AST 预检：`parse()` 语法检查在 `eval()` 之前
2. **Phase V-B — 反思编排 + 高级特性（18h / 3 天）**
- 错误分类器实现（可自愈 vs 不可自愈）
- 自动反思（静默重试，MAX 2 次）+ 手动反思（用户驱动，feedback 意图）
- write_report interpret 模式 + discuss 意图处理（深度解读已有结果）
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 Deploy 收尾** — 前端三线表增强、决策表/流程模板补齐、ACR/SAE 部署
3. **Phase 5C — 前端分步展示**
- 类型扩展：`AgentExecutionRecord` 增加 `stepResults[]` + `currentStep`
- AgentCodePanel 多步骤 UI（可折叠步骤卡片 + 状态/代码/结果/错误）
- SSE 处理器适配新步骤级事件
### 中期
4. **Phase VI（10h）** — 集成测试 + 可观测性（含 QPER 透明化）
4. **Phase V-B — 反思编排 + 高级特性（18h）**
5. **Phase VI（10h）** — 集成测试 + 可观测性（含 QPER 透明化）
6. **Phase Deploy 收尾** — 前端三线表增强、决策表/流程模板补齐、ACR/SAE 部署
**详细计划：** `04-开发计划/11-智能对话与工具体系开发计划.md`（v1.8，Phase I-IV + Phase V-A 完成）+ 双通道架构计划详见 `06-开发记录/` 相关文档
**详细计划：** `04-开发计划/11-智能对话与工具体系开发计划.md` + 架构评审报告详见 `07-统计专家配置/` 目录
---
@@ -416,7 +443,7 @@ npx tsx scripts/seed-ssa-phase4-prompts.ts # Phase IV: SSA_ANALYZE_PLAN
---
**文档版本：** v4.0
**最后更新：** 2026-03-02
**当前状态：** 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 已完成
**下一步：** 双通道 Phase 4（Prompt 工程 + 全面测试）→ Phase V-B（反思编排）
**文档版本：** v4.1
**最后更新：** 2026-03-07
**当前状态：** 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 体验优化已完成
**下一步：** Phase 5A（CoderAgent 防错护栏）→ Phase 5B（分步执行引擎）→ Phase 5C（前端分步展示）