Files

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

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

2026-03-07 22:32:32 +08:00

6.7 KiB

Raw Permalink Blame History

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

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

审查时间： 2026-03-07

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

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

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

降维打击大模型幻觉：让大模型一次写 50 行代码的成功率是 95%，一次写 300 行的成功率只有 30%。按步骤生成代码，彻底规避了 LLM 容易遗忘上下文和乱编变量名的通病。
极佳的渐进式 UX：不再让用户盯着一个大大的“转圈”看一分钟。每个步骤独立出结果，进度条有了真实的物理意义。
精准的局部重试 (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[]。为了配合前端渲染“等待中、生成中、执行中、已完成、错误”的复杂状态，建议定义如下精确的状态流转模型：

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

五、最终审核结论

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

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

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

6.7 KiB Raw Permalink Blame History Unescape Escape