AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/07-统计专家配置/架构委员会审查报告：分步执行架构.md

架构委员会独立审查报告：Plan-and-Execute 分步执行架构

审查对象： plan-and-execute_architecture_0895bce2.plan.md

审查时间： 2026-03-07

总体评级： 🌟 A 级 (方向极度正确，但底层状态管理存在重大设计缺陷)

核心裁决： 强烈支持分步执行理念！但在 R 容器的“状态持久化 (Phase 5A)”和“步骤跳过逻辑”上，必须进行架构级修正，否则系统在并发环境下必然崩溃。

一、 极度赞赏的架构闪光点 (Highlights)

1. 降维打击大模型幻觉：让大模型一次写 50 行代码的成功率是 95%，一次写 300 行的成功率只有 30%。按步骤生成代码，彻底规避了 LLM 容易遗忘上下文和乱编变量名的通病。
2. 极佳的渐进式 UX：不再让用户盯着一个大大的“转圈”看一分钟。每个步骤独立出结果，进度条有了真实的物理意义。
3. 精准的局部重试 (Micro-Healing)：Step 3 报错了，只需把 Step 3 的代码重写，不需要把 Step 1（耗时的清洗）和 Step 2 再跑一遍，极大地节省了算力和时间。

二、 致命工程盲区与强制修正指令 (Critical Blind Spots & Fixes)

🚨 盲区 1：Phase 5A 的“内存环境池”是分布式系统的灾难

• 原计划设计：在 R 进程内维护一个全局 SESSION_POOL <- new.env() 来保存上下文。

• 致命隐患 (The Trap)：

  1. OOM 内存溢出：如果 20 个用户同时在做分析，每个人的 df 有 50MB。这些环境全部堆积在 R 的内存中，Docker 容器会迅速耗尽内存并被宿主机 Kill 掉。
  2. 多进程/多实例负载均衡失效：生产环境中的 R Plumber 通常会启动多个 Worker 进程，或者我们在 SAE 上部署了多个 Docker 实例。用户的 Step 1 请求打到了容器 A（变量存在 A 的内存里），Step 2 请求如果被负载均衡打到了容器 B，容器 B 里根本没有这个 session！ 流程直接断裂。

• 架构强制修正 (File-based Session State)：
  坚决放弃内存池！改用硬盘（或共享存储）序列化工作空间。
  在 CodeRunnerService.ts 每次调用 R 时，告诉 R 去哪里加载/保存状态：
  # R Docker 端的标准做法：基于磁盘序列化的 Jupyter 模式
  session_file <- paste0("/tmp/ssa_session_", input$session_id, ".RData")

  # 1. 恢复上一步的现场
  if (file.exists(session_file) && input$step_index > 1) {
  load(session_file, envir = .GlobalEnv)
  } else {
  # 首次加载数据
  df <- load_data(input$data_source)
  }

  # 2. 执行当前步骤代码...
  eval(parse(text = input$code), envir = .GlobalEnv)

  # 3. 保存现场给下一步用
  save.image(file = session_file)

  (注：如果采用多 Docker 实例部署，/tmp 需要挂载为阿里云 NAS 共享网盘，或将 .RData 文件上传/下载至 OSS。在 MVP 单实例阶段，本地 /tmp 配合定期清理脚本即可。)

🚨 盲区 2：LLM 上下文失明 (Variable Namespace Blindness)

• 如果是核心数据处理、模型拟合步骤失败 -> 必须强行阻断整个 Pipeline (Hard Abort)，通知用户分析终止。
• 如果是边缘步骤（如：Step 4 敏感性分析，或者最后画一张漂亮的散点图）失败 -> 允许跳过 (Soft Skip)，并在最终总结中提示“图表生成失败”。

三、 融合《10 大高级策略》的防错与自愈增强 (Advanced Integration)

结合之前制定的《提升 LLM 代码生成与修复成功率的 10 大高级策略》，分步执行（Plan-and-Execute）不仅需要宏观的状态调度，更需要微观的防错。建议将以下三条策略直接“镶嵌”到分步执行架构中：

🛡️ 借鉴 1：AST 语法树预检 (保护 Session 现场)

• 结合点：在 Phase 5B (CodeRunner 执行单步代码) 时。
• 落地价值：在调用 eval() 运行代码并将 R 环境保存为 .RData 现场之前，必须先执行 parse(text = input$code)。如果大模型犯了低级语法错误（如未闭合括号、非法中文字符），预检会直接报错阻断。绝对不能让脏代码污染当前的 Session 内存现场。

🛡️ 借鉴 2：XML 标签提取 (保障代码纯净度)

• 结合点：在 Phase 5B (CoderAgent 按步骤生成代码) 时。
• 落地价值：不要信任 LLM 会乖乖只输出代码。由于分步生成的聊天属性，大模型极易在代码前后加上“Step 1 的分析代码如下：”等解释性文字。强制 CoderAgent 使用 <r_code>...</r_code> 标签包裹单步代码，并在 Node.js 端用正则严格提取，从根源消灭 unexpected input 错误。

🛡️ 借鉴 3：结合错误分类的“智能短路” (增强软/硬阻断)

• 结合点：与本报告“盲区 3”的跳过逻辑结合。
• 落地价值：某一步骤失败后是“重试、跳过还是终止”，不仅取决于 isCritical，还要看错误分类：
  • Fatal Error (硬阻断)：如果 R 抛出 computationally singular（共线性），说明数据数学性质存在冲突，即使重试 LLM 也修不好，直接中断。
  • Fixable Error (可修复重试)：如果是 object 'age_years' not found，则启动独立的 Fixer Agent。利用上下文重置 (Context Reset)，只给它看当前步骤的代码、报错信息和 Data Schema，让其专注修复后再重试。

四、 对 Phase 5B 状态机 (DB Schema) 的优化建议

您在 SsaAgentExecution 中新增了 stepResults: Json[]。为了配合前端渲染“等待中、生成中、执行中、已完成、错误”的复杂状态，建议定义如下精确的状态流转模型：

// 建议的 AgentStepResult 状态流转字典：
type StepStatus =
| 'pending' // 还没轮到它
| 'coding' // LLM 正在吐代码 (前端渲染骨架屏 + 打字机)
| 'executing' // R 引擎正在跑 (前端渲染转圈)
| 'completed' // 成功拿到 ReportBlocks (前端渲染图表)
| 'error' // R 报错 (前端展示红色错误框，准备重试)
| 'skipped'; // 非致命错误被跳过

这种精确的状态切分，能让前端 AgentCodePanel 的进度条和状态图标完美契合用户的心理预期。

五、 最终审核结论

这是一次将系统体验从“玩具”跃升为“生产力工具”的重构。

只要把 R 环境变量的磁盘序列化（解决内存爆炸和状态丢失）、严格的错误阻断机制 以及 XML/AST 防错策略 落实到位，这个 Plan-and-Execute 架构将使你们的 SSA-Pro 在交互体验和容错率上直接对标顶级的 Agent 平台。

准予通过，请优先攻坚 Phase 5A 的文件持久化沙箱！