Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
HaHafeng
2026-03-08 15:23:09 +08:00
parent c681155de2
commit ac724266c1
24 changed files with 1598 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
View File

@@ -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（反思编排）