feat(ssa): SSA Agent mode MVP - prompt management + Phase 5A guardrails + UX enhancements

Backend: - Agent core prompts (Planner + Coder) now loaded from PromptService with 3-tier fallback (DB -> cache -> hardcoded) - Seed script (seed-ssa-agent-prompts.ts) for idempotent SSA_AGENT_PLANNER + SSA_AGENT_CODER setup - SSA fallback prompts added to prompt.fallbacks.ts - Phase 5A: XML tag extraction, defensive programming prompt, high-fidelity schema injection, AST pre-check - Default agent mode migration + session CRUD (rename/delete) APIs - R Docker: structured error handling (20+ patterns) + AST syntax pre-check Frontend: - Default agent mode (QPER toggle removed), view code fix, analysis result cards in chat - Session history sidebar with inline rename/delete, robust plan parsing from reviewResult - R code export wrapper for local reproducibility (package checks + data loader + polyfills) - SSA workspace CSS updates for sidebar actions and plan display Docs: - SSA module doc v4.2: Prompt inventory (2 Agent active / 11 QPER archived), dev progress updated - System overview doc v6.8: SSA Agent MVP milestone - Deployment checklist: DB-5 (seed script) + BE-10 (prompt management) Made-with: Cursor
2026-03-08 15:23:09 +08:00
parent c681155de2
commit ac724266c1
24 changed files with 1598 additions and 140 deletions
--- a/docs/00-系统总体设计/00-系统当前状态与开发指南.md
+++ b/docs/00-系统总体设计/00-系统当前状态与开发指南.md
@@ -1,10 +1,11 @@
 # AIclinicalresearch 系统当前状态与开发指南

-> **文档版本：** v6.7  
+> **文档版本：** v6.8  
 > **创建日期：** 2025-11-28  
 > **维护者：** 开发团队  
-> **最后更新：** 2026-03-07  
+> **最后更新：** 2026-03-08  
 > **🎉 重大里程碑：**  
+> - **🆕 2026-03-08：SSA 智能统计分析 Agent 模式 MVP 完成！** Agent 核心 Prompt 接入运营管理端（PlannerAgent + CoderAgent 动态化 + 三级容灾）+ Phase 5A 防错护栏 + Prompt 全景盘点（Agent 仅用 2 个 Prompt，QPER 11 个已归档）
 > - **🆕 2026-03-07：SSA Agent 通道体验优化 + Plan-and-Execute 架构设计完成！** 方案 B 左右职责分离 + 10 项 Bug 修复（JWT 刷新/代码截断/重试流式/R Docker 结构化错误/进度同步/导出按钮）+ 分步执行架构评审通过（代码累加策略 + 5 项工程护栏）
 > - **🆕 2026-03-05：RVW V3.0 智能审稿 + ASL Deep Research 历史 + 系统稳定性增强！** RVW LLM 数据核查 + 临床评估维度 + 并行 Skill 故障隔离 + ASL 研究历史/删除 + DeepSearch S3 升级
 > - **🆕 2026-03-01：IIT 业务端 GCP 报表 + AI 时间线增强 + 多项 Bug 修复！** 4 张 GCP 标准报表（筛选入选/完整性/质疑跟踪/方案偏离）+ AI 工作流水详情展开 + 一键全量质控 + dimension_code/时区/通过率/D1 数据源修复
@@ -35,7 +36,8 @@
 > - **2026-01-24：Protocol Agent 框架完成！** 可复用Agent框架+5阶段对话流程  
 > - **2026-01-22：OSS 存储集成完成！** 阿里云 OSS 正式接入平台基础层  
 >  
-> **🆕 最新进展（SSA Agent 体验优化 + RVW V3.0 2026-03-07）：**  
+> **🆕 最新进展（SSA Agent MVP + RVW V3.0 2026-03-08）：**  
+> - ✅ **🆕 SSA Agent 模式 MVP 完成** — Agent 核心 Prompt 接入运营管理端（`SSA_AGENT_PLANNER` + `SSA_AGENT_CODER` 动态化）+ 三级容灾（DB→缓存→fallback）+ 种子脚本幂等写入 + Prompt 全景盘点（Agent 2 个 / QPER 11 个归档）
 > - ✅ **🆕 SSA Agent 通道体验优化（12 文件, +931/-203 行）** — 方案 B 左右职责分离 + JWT 刷新 + 代码截断修复 + 重试流式生成 + R Docker 结构化错误（20+ 模式）+ Prompt 铁律 + 进度同步 + 导出按钮恢复 + ExecutingProgress 动态 UI
 > - ✅ **🆕 Plan-and-Execute 分步执行架构设计完成** — 代码累加策略 + 5 项工程护栏（XML 标签/AST 预检/防御性 Prompt/高保真 Schema/错误分类短路）+ 3 份架构评审报告
 > - ✅ **🆕 RVW V3.0 智能审稿** — LLM 数据核查 + 临床专业评估维度 + 并行 Skill 故障隔离（partial_completed）+ error_details JSONB
@@ -90,7 +92,7 @@
 | **ASL** | AI智能文献 | 文献筛选、Deep Research、全文智能提取、SR图表、Meta分析 | ⭐⭐⭐⭐⭐ | 🎉 **V2.0 核心完成（90%）+ 🆕工具4+5完成** - SSE流式+瀑布流UI+HITL+Word导出+散装派发+PRISMA流程图+Meta分析引擎(R Docker) | **P0** |
 | **DC** | 数据清洗整理 | ETL + 医学NER（百万行级数据） | ⭐⭐⭐⭐⭐ | ✅ **Tool B完成 + Tool C 99%（异步架构+性能优化-99%+多指标转换+7大功能）** | **P0** |
 | **IIT** | IIT Manager Agent | CRA Agent - LLM Tool Use + 自驱动质控 + 统一驾驶舱 | ⭐⭐⭐⭐⭐ | 🎉 **V3.1完成 + GCP报表 + Bug修复！** 质控引擎升级 + 4张GCP业务报表 + AI时间线增强 + 一键全量质控 | **P1-2** |
-| **SSA** | 智能统计分析 | **QPER架构 + 双通道（QPER + LLM Agent）** + 四层七工具 + 对话层LLM | ⭐⭐⭐⭐⭐ | 🎉 **双通道架构 + Agent 体验优化完成** — QPER闭环 + Agent代码生成通道 + 方案B左右职责分离 + 10项Bug修复 + Plan-and-Execute架构设计，E2E全通过 | **P1** |
+| **SSA** | 智能统计分析 | **Agent 模式（PlannerAgent + CoderAgent + R Docker）** + QPER 备用 | ⭐⭐⭐⭐⭐ | 🎉 **Agent 模式 MVP 完成** — Prompt 运营管理化 + Phase 5A 护栏 + 体验优化 + Plan-and-Execute 架构设计，仅用 2 个核心 Prompt | **P1** |
 | **ST** | 统计分析工具 | 126 个轻量化统计工具（旧系统 iframe 嵌入） | ⭐⭐⭐⭐ | ✅ **旧系统集成完成** — Token 注入 + Wrapper Bridge + E2E 验证通过 | P2 |
 | **RVW** | 稿件审查系统 | 方法学评估 + 🆕数据侦探（L1/L2/L2.5验证）+ Skills架构 + Word导出 | ⭐⭐⭐⭐ | 🚀 **V2.0 Week3完成（85%）** - 统计验证扩展+负号归一化+文件格式提示+用户体验优化 | P1 |
 | **ADMIN** | 运营管理端 | Prompt管理、租户管理、用户管理、运营监控、系统知识库 | ⭐⭐⭐⭐⭐ | 🎉 **Phase 4.6完成（88%）** - Prompt知识库集成+动态注入 | **P0** |
@@ -260,7 +262,7 @@
 - ✅ **QPER 集成**：对话层直接调用 plan → execute → report，analysis_plan SSE 事件传输
 - ✅ **团队审查 12 条反馈全部落地**：Phase II H1-H4、Phase III H1-H3+P1、Phase IV H1-H3+B1-B2

-**下一步**：Phase 5A-5C（Plan-and-Execute 分步执行）→ Phase V-B（反思编排）→ Phase VI（集成测试 + 可观测性）
+**下一步**：Phase 5B-5C（Plan-and-Execute 分步执行）→ Phase V-B（反思编排）→ Phase VI（集成测试 + 可观测性）

 **相关文档**：
 - 开发计划：`docs/03-业务模块/SSA-智能统计分析/04-开发计划/11-智能对话与工具体系开发计划.md`
@@ -268,6 +270,21 @@
 - 系统设计：`docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro 四层七工具实现机制详解.md`
 - 架构评审：`docs/03-业务模块/SSA-智能统计分析/07-统计专家配置/架构委员会审查报告：分步执行架构.md`

+#### ✅ SSA Agent 模式 MVP 完成 — Prompt 运营管理化 + Phase 5A 护栏（2026-03-08）
+
+**Agent 核心 Prompt 接入运营管理端：**
+- ✅ `AgentPlannerService.buildSystemPrompt()` → `PromptService.get('SSA_AGENT_PLANNER', { dataContext })`
+- ✅ `AgentCoderService.buildSystemPrompt()` → `PromptService.get('SSA_AGENT_CODER', { dataContext })`
+- ✅ 三级容灾：数据库 ACTIVE 版本 → 内存缓存（5min TTL）→ 代码 fallback（`prompt.fallbacks.ts`）
+- ✅ 种子脚本 `prisma/seed-ssa-agent-prompts.ts` 幂等写入（upsert + ACTIVE v1）
+
+**Prompt 全景盘点（13 → 2 生效）：**
+
+| 通道 | 数量 | 当前状态 |
+|------|------|---------|
+| Agent 通道 | 2 个（`SSA_AGENT_PLANNER` + `SSA_AGENT_CODER`） | ✅ 生效中，可通过运营管理端配置 |
+| QPER 通道 | 11 个（BASE_SYSTEM + INTENT_ROUTER + 6 意图 + QUERY + PICO + REFLECTION） | ⏸ 不执行，保留备用 |
+
 #### ✅ SSA Agent 通道体验优化 + Plan-and-Execute 架构设计（2026-03-07）

 **Agent 通道体验优化完成（12 文件, +931/-203 行）：**
--- a/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
+++ b/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
@@ -1,13 +1,20 @@
 # SSA智能统计分析模块 - 当前状态与开发指南

-> **文档版本：** v4.1  
+> **文档版本：** v4.2  
 > **创建日期：** 2026-02-18  
-> **最后更新：** 2026-03-07  
+> **最后更新：** 2026-03-08  
 > **维护者：** 开发团队  
-> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 通道体验优化完成**  
+> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 通道体验优化 + Agent Prompt 运营管理化完成**  
 > **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
 > 
-> **最新进展（2026-03-07 Agent 通道体验优化 — 方案 B 左右职责分离 + 10 项 Bug 修复）：**
+> **最新进展（2026-03-08 Agent 核心 Prompt 接入运营管理端）：**
+> - ✅ **PlannerAgent Prompt 动态化** — `AgentPlannerService.buildSystemPrompt()` 改为 `PromptService.get('SSA_AGENT_PLANNER', { dataContext })`，支持运营管理端在线编辑、灰度预览、版本管理
+> - ✅ **CoderAgent Prompt 动态化** — `AgentCoderService.buildSystemPrompt()` 改为 `PromptService.get('SSA_AGENT_CODER', { dataContext })`，同上
+> - ✅ **三级容灾** — 数据库 ACTIVE 版本 → 内存缓存（5 分钟） → 代码 fallback（`prompt.fallbacks.ts`），任何一层失败自动降级
+> - ✅ **种子数据脚本** — `prisma/seed-ssa-agent-prompts.ts` 幂等写入初始 Prompt（upsert template + ACTIVE v1）
+> - ✅ **Handlebars 模板变量** — 两个 Prompt 均使用 `{{{dataContext}}}` 三括号无转义渲染，运营可编辑模板内容但保留变量占位符
+> 
+> **此前进展（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 优化
@@ -194,7 +201,8 @@ AnalysisRecord {
 | **双通道 Phase 3** | **前端集成（SSE + AgentCodePanel + 确认流程）** | **~6h** | ✅ **已完成（三步确认 + 流式代码 + 7 种 SSE 事件）** | 2026-03-02 |
 | **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 5A** | **CoderAgent 防错护栏（XML 标签 + AST 预检 + 防御性 Prompt + 高保真 Schema）** | **~6h** | ✅ **已完成** | 2026-03-08 |
+| **Agent Prompt 管理化** | **PlannerAgent + CoderAgent Prompt 接入运营管理端（PromptService 三级容灾）** | **~2h** | ✅ **已完成（种子脚本 + fallback + 文档）** | 2026-03-08 |
 | **Phase 5B** | **后端分步执行引擎（DB schema + 代码累加循环 + 错误分类短路 + 新 SSE 事件）** | **~10h** | 📋 待开始 | - |
 | **Phase 5C** | **前端分步展示（类型扩展 + AgentCodePanel 多步骤 UI + SSE 处理器）** | **~6h** | 📋 待开始 | - |
 | **Phase V-B** | **反思编排 + 高级特性** | **18h** | 📋 待开始 | - |
@@ -223,6 +231,7 @@ AnalysisRecord {
 | **Phase V-A 前端** | WorkflowTimeline 可编辑化（SingleVarSelect + MultiVarTags + 三层柔性拦截）+ ssaStore updateStepParams + SSAWorkspacePane 同步阻塞执行 + DynamicReport 对象 rows 兼容 + Word 导出修复 | ✅ |
 | **双通道 Agent 通道** | PlannerAgent（意图→分析计划）+ CoderAgent（计划→R 代码，含流式生成）+ CodeRunnerService（沙箱执行）+ AgentCodePanel（三步确认 UI）+ ModeToggle（通道切换）+ R Docker /execute-code 端点 | ✅ |
 | **Agent 体验优化** | 方案 B 左右职责分离（视线牵引+状态互斥+历史穿梭）+ JWT 刷新 + 代码截断修复 + 重试流式生成 + R Docker 结构化错误（20+ 模式）+ Prompt 铁律 + parseCode 健壮化 + consoleOutput 类型防御 + 进度条同步 + 导出/查看代码恢复 + ExecutingProgress 动态 UI | ✅ |
+| **Agent Prompt 管理化** | PlannerAgent + CoderAgent System Prompt 从硬编码迁移至 PromptService 动态加载；运营管理端在线编辑/灰度预览/版本回滚；三级容灾（DB→缓存→fallback）；种子脚本 `seed-ssa-agent-prompts.ts` 幂等 | ✅ |
 | **测试** | 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 体验测试通过（统计分析结果+图表正常） | ✅ |

 ---
@@ -350,6 +359,51 @@ npx tsx scripts/seed-ssa-pico-prompt.ts         # Phase I: PICO 推断
 npx tsx scripts/seed-ssa-phase2-prompts.ts      # Phase II: 8 Prompt
 npx tsx scripts/seed-ssa-phase3-prompts.ts      # Phase III: SSA_METHOD_CONSULT
 npx tsx scripts/seed-ssa-phase4-prompts.ts      # Phase IV: SSA_ANALYZE_PLAN
+npx tsx prisma/seed-ssa-agent-prompts.ts        # Agent: SSA_AGENT_PLANNER + SSA_AGENT_CODER
+```
+
+---
+
+## 🧠 Prompt 全景盘点（QPER vs Agent）
+
+> **结论：当前 Agent 模式仅使用 2 个 Prompt，其余 11 个为 QPER 遗产。**
+>
+> 自 `chat.routes.ts` 硬编码 `executionMode = 'agent'` 后，QPER 通道代码不再执行。
+
+### Agent 通道 Prompt（当前生效 ✅）
+
+| # | Prompt Code | 服务 | 模板变量 | 用途 |
+|---|------------|------|---------|------|
+| 1 | `SSA_AGENT_PLANNER` | `AgentPlannerService` | `{{{dataContext}}}` | 规划师 System Prompt：制定统计分析计划（JSON 格式） |
+| 2 | `SSA_AGENT_CODER` | `AgentCoderService` | `{{{dataContext}}}` | 编码器 System Prompt：生成可执行 R 代码（XML 标签输出） |
+
+**管理方式：** 运营管理端 → Prompt 管理 → SSA 模块 → 在线编辑/灰度预览/版本管理  
+**容灾链路：** 数据库 ACTIVE 版本 → 内存缓存（5min TTL）→ 代码 fallback（`prompt.fallbacks.ts`）
+
+### QPER 通道 Prompt（当前不执行，保留备用）
+
+| # | Prompt Code | 服务 | 用途 |
+|---|------------|------|------|
+| 3 | `SSA_BASE_SYSTEM` | `SystemPromptService` | QPER 对话基础角色定义 |
+| 4 | `SSA_INTENT_ROUTER` | `IntentRouterService` | LLM 意图分类器（6 种意图） |
+| 5 | `SSA_INTENT_CHAT` | `SystemPromptService` | 普通聊天意图指令 |
+| 6 | `SSA_INTENT_EXPLORE` | `SystemPromptService` | 数据探索意图指令 |
+| 7 | `SSA_INTENT_CONSULT` | `SystemPromptService` | 方法咨询意图指令 |
+| 8 | `SSA_INTENT_ANALYZE` | `SystemPromptService` | 执行分析意图指令 |
+| 9 | `SSA_INTENT_DISCUSS` | `SystemPromptService` | 结果讨论意图指令 |
+| 10 | `SSA_INTENT_FEEDBACK` | `SystemPromptService` | 改进反馈意图指令 |
+| 11 | `SSA_QUERY_INTENT` | `QueryService` | Q 层 LLM 意图解析 |
+| 12 | `SSA_PICO_INFERENCE` | `PicoInferenceService` | PICO 结构推断 |
+| 13 | `SSA_REFLECTION` | `ReflectionService` | R 层论文级结论生成 |
+
+### Agent 调用链（仅 2 个 Prompt）
+
+```
+用户消息
+  → ChatHandlerService.handleAgentMode()
+    → AgentPlannerService.generatePlan()    ← SSA_AGENT_PLANNER
+    → AgentCoderService.generateCodeStream() ← SSA_AGENT_CODER
+    → CodeRunnerService.executeCode()        ← 纯 R 执行，无 Prompt
 ```

 ---
@@ -443,7 +497,7 @@ npx tsx scripts/seed-ssa-phase4-prompts.ts      # Phase IV: SSA_ANALYZE_PLAN

 ---

-**文档版本：** v4.1  
-**最后更新：** 2026-03-07  
-**当前状态：** 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A + 双通道架构 Phase 1-3 + Agent 体验优化已完成  
-**下一步：** Phase 5A（CoderAgent 防错护栏）→ Phase 5B（分步执行引擎）→ Phase 5C（前端分步展示）
+**文档版本：** v4.2  
+**最后更新：** 2026-03-08  
+**当前状态：** 🎉 SSA Agent 模式 MVP 完成（QPER 闭环 + Phase I-IV + Phase V-A + 双通道架构 + Agent 体验优化 + Prompt 运营管理化 + Phase 5A 护栏）  
+**下一步：** Phase 5B（分步执行引擎）→ Phase 5C（前端分步展示）→ Phase V-B（反思编排）
--- a/docs/03-业务模块/SSA-智能统计分析/07-统计专家配置/R
+++ b/docs/03-业务模块/SSA-智能统计分析/07-统计专家配置/R
@@ -0,0 +1,110 @@
+# **架构优化方案：R 代码的本地复现与导出包装 (Export Wrapper)**
+
+**问题诊断：** 大模型在 Agent 管线中生成的 R 代码是高度依赖“平台沙箱环境”的。它缺失了数据读取操作 (df)，且引用了平台专属的 UI 辅助函数 (make\_table\_block\_from\_df 等)。
+
+**解决目标：** 用户点击“下载 R 代码”时，系统必须动态注入“本地兼容层”，使得代码可以在任何一台普通的 RStudio 中一键运行。
+
+## **一、 根本解决方案：导出包装器 (Export Wrapper)**
+
+当用户点击“下载 R 代码”时，前端不能仅仅把 Agent 生成的代码原样保存为 .R 文件。我们需要像编译器一样，将代码包裹在一个**标准的本地复现模板**中。
+
+完整的导出文件应该由 3 个部分拼接而成：
+
+1. **数据加载层 (Data Loading)**  
+2. **函数兼容层 (Polyfills / Mock Helpers)**  
+3. **Agent 生成的核心代码 (Core Logic)**
+
+## **二、 包装器代码实现范例**
+
+前端或后端在生成下载文件时，请使用以下字符串拼接逻辑：
+
+// 伪代码：在前端 SSACodeModal 或后端导出 API 中实现  
+function generateDownloadableRCode(agentCode: string, fileName: string): string {  
+    
+  const headerAndPolyfills \= \`  
+\# \=====================================================================  
+\# SSA-Pro 智能统计分析 \- 本地复现脚本  
+\# \=====================================================================
+
+\# 1\. 自动安装缺失的包 (本地复现安全保障)  
+required\_packages \<- c("dplyr", "gtsummary", "base64enc", "ggplot2")  
+new\_packages \<- required\_packages\[\!(required\_packages %in% installed.packages()\[,"Package"\])\]  
+if(length(new\_packages)) install.packages(new\_packages)
+
+suppressPackageStartupMessages({  
+  library(dplyr)  
+  library(gtsummary)  
+  library(base64enc)  
+  library(ggplot2)  
+})
+
+\# \=====================================================================  
+\# 2\. 数据读取 (请确保数据文件与本脚本在同一目录下)  
+\# \=====================================================================  
+\# 系统已将您的原始数据名填入，如果路径不同请手动修改：  
+file\_name \<- "${fileName}" 
+
+if (file.exists(file\_name)) {  
+  if (grepl("\\\\\\\\.csv$", file\_name, ignore.case \= TRUE)) {  
+    df \<- read.csv(file\_name, stringsAsFactors \= FALSE)  
+  } else if (grepl("\\\\\\\\.xlsx?$", file\_name, ignore.case \= TRUE)) {  
+    library(readxl)  
+    df \<- read\_excel(file\_name)  
+  }  
+} else {  
+  \# 如果找不到文件，生成测试数据以防代码直接崩溃  
+  warning(paste("找不到数据文件:", file\_name, "。将使用模拟数据进行演示。"))  
+  df \<- data.frame(  
+    root\_curve \= sample(c(1, 2), 100, replace \= TRUE),  
+    Yqol \= sample(c(0, 1), 100, replace \= TRUE)  
+  )  
+}
+
+\# \=====================================================================  
+\# 3\. 平台 UI 辅助函数本地兼容层 (Polyfills)  
+\# 这使得平台专用的 make\_\*\_block 函数在本地控制台优雅地输出，而不报错  
+\# \=====================================================================  
+make\_markdown\_block \<- function(text) {   
+  cat("\\\\n========================================\\\\n")  
+  cat(text, "\\\\n")   
+}
+
+make\_table\_block\_from\_df \<- function(data, title="", footnote="") {  
+  cat("\\\\n---", title, "---\\\\n")  
+  print(data)  
+  if(footnote \!= "") cat("注:", footnote, "\\\\n")  
+  return(list(type="table"))  
+}
+
+make\_image\_block \<- function(base64\_data, title="", alt="") {  
+  cat("\\\\n\[图形已生成:", title, "- 请查看 RStudio 的 Plots 面板\]\\\\n")  
+  return(list(type="image"))  
+}
+
+make\_kv\_block \<- function(items, title="") {  
+  cat("\\\\n---", title, "---\\\\n")  
+  print(unlist(items))  
+  return(list(type="key\_value"))  
+}
+
+\# \=====================================================================  
+\# 4\. 核心分析代码 (由 AI Agent 生成)  
+\# \=====================================================================  
+\`;
+
+  return headerAndPolyfills \+ "\\n" \+ agentCode;  
+}
+
+## **三、 为什么必须这么做？(架构收益)**
+
+1. **防患于未然的数据读取：** 我们不仅注入了 read.csv，还加入了 file.exists 检查。如果医生把 R 脚本发给另一个没有原始数据的统计师，代码会自动生成一组 Mock（模拟）数据。这样 R 脚本无论如何都能跑通，极大提升了产品的专业感。  
+2. **优雅的 Polyfills (兼容层) 技术：**  
+   这是前端工程（如适配老版本浏览器）最常用的技术。我们在脚本头部用普通的 print() 和 cat() 重写了 make\_table\_block\_from\_df 等函数。这样，大模型生成的复杂 UI 代码在本地 RStudio 中执行时，不仅**不会报错**，还会把结果**整齐地打印在本地控制台上**。  
+3. **保持 Agent Prompt 的纯净：**  
+   我们**不需要**去修改 CoderAgent 的 System Prompt 让它“记得写读取文件的代码”。因为每次让 LLM 动态写数据读取逻辑，它很容易因为编码（UTF-8 vs GBK）或文件路径错误而翻车。把这种死板的工作交给前端的字符串拼接（Wrapper），是最稳定、最省 Token 的做法。
+
+## **四、 实施建议**
+
+请前端团队接手此任务：
+
+在 AgentCodePanel.tsx 或 SSACodeModal.tsx 中，找到处理\*\*“导出 R 脚本 (Export/Download .R)”\*\*的 onClick 函数。在生成 Blob 对象并触发浏览器下载之前，将原有的代码字符串通过上述包装器函数处理一遍即可。这只需半小时即可实现。
--- a/docs/05-部署文档/03-待部署变更清单.md
+++ b/docs/05-部署文档/03-待部署变更清单.md
@@ -18,6 +18,8 @@
 | DB-1 | modules 表 seed 新增 ASL_SR 模块（系统综述项目） | `backend/scripts/seed-modules.js` | 高 | 部署后需执行 `node scripts/seed-modules.js`，并在运营管理端为目标用户/租户开通 |
 | DB-2 | prompt_templates 表新增 RVW_DATA_VALIDATION + RVW_CLINICAL 两个 Prompt | `backend/scripts/migrate-rvw-prompts.ts` | 高 | 部署后需执行 `npx tsx scripts/migrate-rvw-prompts.ts`，运营管理端可配置修改 |
 | DB-3 | ReviewTask 表新增 `error_details` JSONB 字段（存储 Skill 级失败详情） | `prisma/migrations/20260307_add_error_details_to_review_task/migration.sql` | 高 | 支持 partial_completed 状态，记录每个失败/超时 Skill 的名称和原因 |
+| DB-4 | SSA execution_mode 默认值改为 `agent` + 已有 session 全部更新 | `prisma/migrations/20260308_default_agent_mode/migration.sql` | 高 | ALTER DEFAULT + UPDATE 旧数据；QPER UI 入口已移除 |
+| DB-5 | SSA Agent Prompt 种子数据（SSA_AGENT_PLANNER / SSA_AGENT_CODER） | `prisma/seed-ssa-agent-prompts.ts` | 高 | 部署后执行 `npx tsx prisma/seed-ssa-agent-prompts.ts`；幂等可重复执行 |

 ### 后端变更 (Node.js)

@@ -31,6 +33,8 @@
 | BE-6 | RVW 稳定性增强：SkillExecutor Promise.allSettled + partial_completed 状态 + errorDetails | `executor.ts`, `reviewWorker.ts`, `reviewService.ts`, `reviewController.ts`, `types/index.ts` | 重新构建镜像 | 并行 Skill 故障隔离，部分模块失败时仍返回成功模块结果，新增 `partial_completed` 任务状态 |
 | BE-7 | DataForensicsSkill LLM 核查增加独立 60s 超时 | `DataForensicsSkill.ts` | 重新构建镜像 | LLM 核查超时不阻塞整体 Skill，graceful 降级为纯规则验证 |
 | BE-8 | SSA Agent 通道体验优化（方案 B 左右职责分离 + 10 项 Bug 修复） | `ChatHandlerService.ts`, `AgentCoderService.ts`, `chat.routes.ts` | 重新构建镜像 | 视线牵引 Prompt + maxTokens 8000 + 重试流式生成 + consoleOutput 类型防御 + Prompt 铁律 + parseCode 健壮化 |
+| BE-9 | Phase 5A：CoderAgent 防错护栏（4 项改动） | `AgentCoderService.ts`, `TokenTruncationService.ts`, `chat.routes.ts` | 重新构建镜像 | XML 标签提取 + 防御性编程 Prompt + 高保真 Schema 注入 + token 配额 2500 + 后端强制 Agent 模式 |
+| BE-10 | SSA Agent 核心 Prompt 接入运营管理端（PlannerAgent + CoderAgent） | `AgentPlannerService.ts`, `AgentCoderService.ts`, `prompt.fallbacks.ts` | 重新构建镜像 | 硬编码 → `PromptService.get()` 动态加载；三级容灾：DB → 缓存 → fallback；需先完成 DB-5 |

 ### 前端变更

@@ -43,6 +47,7 @@
 | FE-5 | RVW 新增临床专业评估 Tab + Agent 选择项 | `ClinicalReport.tsx`(新), `AgentModal.tsx`, `TaskDetail.tsx`, `rvw/types/index.ts` | 重新构建镜像 | 共 4 个 Tab：稿约规范性/方法学/数据验证/临床评估；Word 导出包含临床评估章节 |
 | FE-6 | RVW 前端支持 partial_completed 状态（部分完成） | `TaskDetail.tsx`, `TaskTable.tsx`, `rvw/types/index.ts` | 重新构建镜像 | 琥珀色警告横幅展示失败模块详情，列表页显示"部分完成"标签，支持查看已完成模块的报告 |
 | FE-7 | SSA Agent 通道体验优化（方案 B + 动态 UI） | `AgentCodePanel.tsx`, `SSAChatPane.tsx`, `SSAWorkspacePane.tsx`, `SSACodeModal.tsx`, `useSSAChat.ts`, `ssaStore.ts`, `ssa.css` | 重新构建镜像 | 左右职责分离 + JWT 刷新 + 重试代码展示 + 错误信息展示 + 进度条同步 + 导出/查看代码按钮恢复 + ExecutingProgress 组件 |
+| FE-8 | SSA 默认 Agent 模式 + 查看代码修复 + 分析历史卡片 | `SSAChatPane.tsx`, `SSAWorkspacePane.tsx`, `useSSAChat.ts`, `ssaStore.ts` | 重新构建镜像 | 移除 ModeToggle + 默认 agent + 查看代码走 Modal + 分析完成后对话插入可点击结果卡片 + ChatIntentType 扩展 system |

 ### Python 微服务变更

@@ -56,6 +61,7 @@
 |---|---------|---------|---------|------|
 | R-1 | 新增 POST /api/v1/execute-code 端点（Agent 通道任意 R 代码执行） | `plumber.R` | 重新构建镜像 | 含超时 + 沙箱限制 |
 | R-2 | Agent 结构化错误处理增强（20+ 模式匹配 + format_agent_error） | `plumber.R`, `utils/error_codes.R` | 重新构建镜像 | withCallingHandlers 捕获 warnings/messages + 行号提取 + 错误分类 + 修复建议 |
+| R-3 | AST 语法预检（parse() 前置于 eval()） | `plumber.R` | 重新构建镜像 | 语法错误秒级返回 E_SYNTAX + 行号 + 上下文代码，不进入沙箱执行 |

 ### 环境变量 / 配置变更