# **架构委员会独立审查报告：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 的文件持久化沙箱！**