HaHafeng
52989cd03f
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
94 lines
6.7 KiB
Markdown
94 lines
6.7 KiB
Markdown
# **架构委员会独立审查报告：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 的文件持久化沙箱！** |