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

feat(ssa): Complete Phase I-IV intelligent dialogue and tool system development

Browse Source 
Phase I - Session Blackboard + READ Layer:
- SessionBlackboardService with Postgres-Only cache
- DataProfileService for data overview generation
- PicoInferenceService for LLM-driven PICO extraction
- Frontend DataContextCard and VariableDictionaryPanel
- E2E tests: 31/31 passed

Phase II - Conversation Layer LLM + Intent Router:
- ConversationService with SSE streaming
- IntentRouterService (rule-first + LLM fallback, 6 intents)
- SystemPromptService with 6-segment dynamic assembly
- TokenTruncationService for context management
- ChatHandlerService as unified chat entry
- Frontend SSAChatPane and useSSAChat hook
- E2E tests: 38/38 passed

Phase III - Method Consultation + AskUser Standardization:
- ToolRegistryService with Repository Pattern
- MethodConsultService with DecisionTable + LLM enhancement
- AskUserService with global interrupt handling
- Frontend AskUserCard component
- E2E tests: 13/13 passed

Phase IV - Dialogue-Driven Analysis + QPER Integration:
- ToolOrchestratorService (plan/execute/report)
- analysis_plan SSE event for WorkflowPlan transmission
- Dual-channel confirmation (ask_user card + workspace button)
- PICO as optional hint for LLM parsing
- E2E tests: 25/25 passed

R Statistics Service:
- 5 new R tools: anova_one, baseline_table, fisher, linear_reg, wilcoxon
- Enhanced guardrails and block helpers
- Comprehensive test suite (run_all_tools_test.js)

Documentation:
- Updated system status document (v5.9)
- Updated SSA module status and development plan (v1.8)

Total E2E: 107/107 passed (Phase I: 31, Phase II: 38, Phase III: 13, Phase IV: 25)

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
HaHafeng
2026-02-22 18:53:39 +08:00
parent bf10dec4c8
commit 3446909ff7
68 changed files with 11583 additions and 412 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,17 +1,41 @@
# SSA智能统计分析模块 - 当前状态与开发指南
> **文档版本：** v3.0
> **文档版本：** v3.4
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-22
> **维护者：** 开发团队
> **当前状态：** 🎉 **QPER 主线闭环 + 智能对话与工具体系架构设计完成**
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I + Phase II + Phase III + Phase IV（对话驱动分析 + QPER 集成）开发完成**
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
>
> **最新进展（2026-02-22）：**
> - ✅ **智能对话与工具体系架构设计完成** — 四层七工具 + 对话层 LLM + 意图路由器
> - ✅ **开发计划 v1.2 定稿** — 6 Phase / 134h / 22 天（含 8 条架构约束 + Postgres-Only 缓存规范）
> - ✅ **3 份系统设计文档** — 意图识别架构、工具体系规划方案、四层七工具实现机制详解
> - ✅ **6 条架构审查建议已裁定** — 3 预警（Function Calling 冲突、System Prompt 膨胀、流式输出）+ 3 盲区（Postgres-Only 缓存、上下文守卫、Zod 动态校验）
> **最新进展（2026-02-22 Phase IV 完成）：**
> - ✅ **Phase IV 全 5 批次完成** — ToolOrchestratorService（PICO hint 三层降级）+ handleAnalyze 重写（plan→analysis_plan SSE→LLM 方案说明→ask_user 确认）+ AVAILABLE_TOOLS 配置化（11 处改 toolRegistryService）+ 前端 SSE 对接（analysis_plan + plan_confirmed）
> - ✅ **团队审查 H1-H3+B1-B2 全部落地** — H1 PICO hint 注入 / H2 幽灵卡片清除 / H3 SSE 严格串行 / B1 修改建议循环 / B2 旧 API 兼容
> - ✅ **SSA_ANALYZE_PLAN Prompt 入库** — 指导 LLM 用自然语言解释分析方案（步骤/理由/注意事项）
> - ✅ **E2E 测试 25/25 通过** — analyze 意图→analysis_plan 3 步骤→ask_user 确认卡片→旧 /workflow/plan 兼容→AVAILABLE_TOOLS 配置化→对话历史
>
> **此前进展（2026-02-22 Phase III 完成）：**
> - ✅ **Phase III 全 5 批次完成** — ToolRegistryService（H2 仓储模式）+ MethodConsultService（PICO→DecisionTable→推荐）+ AskUserService（H3 概念统一 + H1 状态死锁防护）+ ChatHandlerService（handleConsult + handleAskUserResponse）
> - ✅ **H1 全局打断** — chat.routes 入口增加 pendingAskUser 检测，用户无视卡片直接打字时自动解除死锁
> - ✅ **AskUserCard 前端组件** — 4 种 inputType（single_select/multi_select/free_text/confirm）+ 跳过按钮
> - ✅ **SSA_METHOD_CONSULT Prompt 入库** — P1 格式约束（结论先行 + 结构化列表）
> - ✅ **E2E 测试 13/13 通过 + 4 跳过** — consult 意图 + 方法推荐 + 对话历史验证（4 跳过: PICO 未完整触发 ask_user 卡片，预期行为）
>
> **此前进展（2026-02-22 Phase II 完成）：**
> - ✅ **Phase II 全 4 批次完成** — SystemPromptService（六段式 + H2 修正）+ ConversationService（持久化 + SSE 心跳 H1 + Placeholder H3）+ IntentRouterService（规则+LLM 混合+守卫 C5）+ ChatHandlerService（chat/explore/analyze/discuss 分发）
> - ✅ **统一 /chat API** — POST /sessions/:id/chat（SSE 流式）+ GET history + GET conversation
> - ✅ **8 个 Prompt 种子入库** — SSA_BASE_SYSTEM + 6 意图指令 + SSA_INTENT_ROUTER
> - ✅ **前端改造** — useSSAChat hook + SSAChatPane（SSE 流式 + ThinkingBlock + 意图标签 + H3 输入锁）
> - ✅ **E2E 测试 38/38 通过** — 6 意图分类 + SSE 流式 + 对话历史 + 上下文守卫
>
> **此前进展（2026-02-22 Phase I 完成）：**
> - ✅ **Phase I 全 5 批次完成** — SessionBlackboard + GetDataOverview + GetVariableDetail + PICO 推断 + 前端三组件 + SSE 自动触发
> - ✅ **Python 扩展** — 正态性检验（Shapiro-Wilk/K-S）+ 完整病例数 + variable-detail 端点（H2: bins<=30）
> - ✅ **PICO Prompt 种子** — SSA_PICO_INFERENCE 已入库（含 H3 观察性研究 null 处理）
> - ✅ **E2E 测试 31/31 通过** — Python 端点 + 数据结构 + H2/H3 防护验证
>
> **此前进展（2026-02-22 Phase Deploy）：**
> - ✅ **Phase Deploy R 工具层完成** — R 工具 7→12（+Fisher/ANOVA/Wilcoxon/线性回归/基线表），全部 Block-based 标准化，16/16 测试通过
> - ⏳ **Phase Deploy 剩余** — 前端三线表增强(#7)、决策表/流程模板补齐(#8-9)、ACR/SAE 部署(#10-11) 暂缓，不阻塞 Phase II
>
> **此前进展（2026-02-21）：**
> - ✅ **前后端集成测试** — 7 个 Bug 全部修复（R 引擎防御、意图识别、前端状态）
@@ -130,11 +154,11 @@ AnalysisRecord {
| **Phase R** | **LLM 论文级结论** | **22h** | ✅ **已完成** | 2026-02-21 |
| **集成测试** | **Bug 修复 + 统一状态管理重构** | **~4h** | ✅ **已完成** | 2026-02-21 |
| **架构设计** | **智能对话与工具体系架构设计** | **~8h** | ✅ **已完成** | 2026-02-22 |
| Phase Deploy | 工具补齐 + 部署上线 | 37h | 📋 待开始 | - |
| **Phase I** | **Session 黑板 + READ 层** | **30h** | 📋 待开始（吸收 Phase Q+） | - |
| **Phase II** | **对话层 LLM + 意图路由器 + 统一对话入口** | **35h** | 📋 待开始 | - |
| **Phase III** | **method_consult + ask_user 标准化** | **20h** | 📋 待开始 | - |
| **Phase IV** | **THINK + ACT 工具封装** | **21h** | 📋 待开始 | - |
| Phase Deploy | 工具补齐 + 部署上线 | 37h | 🔶 R 层完成（12 工具），前端/部署待收尾 | 2026-02-22 |
| **Phase I** | **Session 黑板 + READ 层** | **30h** | ✅ **已完成（5 批次, 18 文件, E2E 31/31）** | 2026-02-22 |
| **Phase II** | **对话层 LLM + 意图路由器 + 统一对话入口** | **35h** | ✅ **已完成（4 批次, 12 文件, E2E 38/38, H1-H4 落地）** | 2026-02-22 |
| **Phase III** | **method_consult + ask_user 标准化** | **20h** | ✅ **已完成（5 批次, 12 文件, E2E 13/13+4skip, H1-H3+P1 落地）** | 2026-02-22 |
| **Phase IV** | **对话驱动分析 + QPER 集成** | **14h** | ✅ **已完成（5 批次, 11 文件, E2E 25/25, H1-H3+B1-B2 落地）** | 2026-02-22 |
| **Phase V** | **反思编排 + 高级特性** | **18h** | 📋 待开始 | - |
| **Phase VI** | **集成测试 + 可观测性** | **10h** | 📋 待开始 | - |
@@ -142,14 +166,22 @@ AnalysisRecord {
| 组件 | 完成项 | 状态 |
|------|--------|------|
| **R 服务** | 7 个 R 工具 + Block-based 输出 + 防御性编程（NA 安全） | ✅ |
| **R 服务** | 12 个 R 工具 + Block-based 输出 + JIT 护栏 + 防御性编程（NA 安全） | ✅ |
| **Q 层** | QueryService + LLM Intent + Zod 防幻觉 + 追问卡片 + 统计学意义关键词增强 | ✅ |
| **P 层** | ConfigLoader + DecisionTable + FlowTemplate + PlannedTrace + 热更新 API | ✅ |
| **E 层** | WorkflowExecutor + RClient + SSE 实时进度 + 错误分类映射 + 参数日志 | ✅ |
| **R 层** | ReflectionService + 槽位注入 + Zod 校验 + 敏感性冲突准则 + 结论缓存 + Word 增强 | ✅ |
| **前端** | 统一 Record 架构 + 多任务切换 + 已完成标记 + DynamicReport + Word/R 导出 | ✅ |
| **Python** | DataProfileService（is_id_like 标记）+ CSV 解析 | ✅ |
| **测试** | QPER 端到端 40/40 + 集成测试 7 Bug 修复 | ✅ |
| **Python** | DataProfileService（is_id_like 标记）+ CSV 解析 + 正态性检验 + 单变量详情 | ✅ |
| **Phase I 黑板** | SessionBlackboardService（互斥锁 patch）+ GetDataOverview + GetVariableDetail + PICO 推断 + TokenTruncation | ✅ |
| **Phase I 前端** | DataContextCard + VariableDictionaryPanel + VariableDetailPanel + ssaStore dataContext 扩展 | ✅ |
| **Phase II 后端** | SystemPromptService（六段式+H2）+ ConversationService（持久化+SSE H1+Placeholder H3）+ IntentRouterService（规则+LLM+守卫 C5）+ ChatHandlerService + chat.routes + intent_rules.json + 8 Prompt 种子 | ✅ |
| **Phase II 前端** | useSSAChat hook（SSE 流式）+ SSAChatPane 改造（ThinkingBlock + 意图标签 + H3 输入锁 + 中断按钮） | ✅ |
| **Phase III 后端** | ToolRegistryService（H2 仓储模式 IToolRepository）+ MethodConsultService（PICO→DecisionTable→推荐）+ AskUserService（H3 概念统一 + H1 clearPending）+ ChatHandlerService 扩展（handleConsult + handleAskUserResponse）+ chat.routes H1 全局打断 + SSA_METHOD_CONSULT Prompt P1 | ✅ |
| **Phase III 前端** | AskUserCard（4 inputType + H1 跳过按钮）+ useSSAChat 扩展（pendingQuestion + respondToQuestion + skipQuestion） | ✅ |
| **Phase IV 后端** | ToolOrchestratorService（plan+PICO hint 三层降级+formatPlanForLLM）+ ChatHandlerService 重写（handleAnalyze: plan→analysis_plan SSE→LLM 说明→ask_user 确认; handleAskUserResponse: confirm_plan/change_method）+ AVAILABLE_TOOLS 配置化（11 处→toolRegistryService）+ ToolRegistryService（+getVisibleTools）+ AskUserService（+metadata）+ SSA_ANALYZE_PLAN Prompt 入库 | ✅ |
| **Phase IV 前端** | useSSAChat（analysis_plan+plan_confirmed SSE 处理+pendingPlanConfirm→executeWorkflow）+ SSAChatPane（AskUserCard 渲染+幽灵卡片清除 H2） | ✅ |
| **测试** | 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 | ✅ |
---
@@ -166,8 +198,14 @@ backend/src/modules/ssa/
│ ├── RClientService.ts # E 层：R 引擎调用
│ ├── ReflectionService.ts # R 层：LLM 结论生成
│ ├── ConclusionGeneratorService.ts # R 层 fallback
│ ├── DataProfileService.ts # 共享：Python 数据质量
│ └── DataParserService.ts # 共享：文件解析
│ ├── DataProfileService.ts # 共享：Python 数据质量 + variable-detail
│ ├── DataParserService.ts # 共享：文件解析
│ ├── SessionBlackboardService.ts # Phase I：Session 黑板（互斥锁 patch）
│ ├── PicoInferenceService.ts # Phase I：LLM PICO 推断
│ ├── TokenTruncationService.ts # Phase I：Token 截断框架
│ └── tools/
│ ├── GetDataOverviewTool.ts # Phase I：数据概览 + 五段式报告
│ └── GetVariableDetailTool.ts # Phase I：单变量详情
├── config/
│ ├── ConfigLoader.ts # 通用 JSON 加载 + Zod 校验
│ ├── tools_registry.json # R 工具注册表
@@ -175,9 +213,11 @@ backend/src/modules/ssa/
│ └── flow_templates.json # 流程模板
├── types/
│ ├── query.types.ts # Q 层接口
│ └── reflection.types.ts # R 层接口
│ ├── reflection.types.ts # R 层接口
│ └── session-blackboard.types.ts # Phase I：黑板类型 + Zod Schema
├── routes/
│ ├── workflow.routes.ts # 工作流 API（含结论缓存）
│ ├── blackboard.routes.ts # Phase I：黑板 CRUD + 变量 PATCH
│ └── config.routes.ts # 热更新 API
└── ...
@@ -192,7 +232,10 @@ frontend-v2/src/modules/ssa/
│ ├── SSAWorkspacePane.tsx # 工作区（基于 currentRecord 渲染）
│ ├── SSACodeModal.tsx # R 代码模态框（从 record.steps 聚合）
│ ├── WorkflowTimeline.tsx # 执行计划时间线
│ └── DynamicReport.tsx # Block-based 结果渲染
│ ├── DynamicReport.tsx # Block-based 结果渲染
│ ├── DataContextCard.tsx # Phase I：五段式数据概览卡片
│ ├── VariableDictionaryPanel.tsx # Phase I：变量字典表格（可编辑）
│ └── VariableDetailPanel.tsx # Phase I：单变量详情面板
└── types/
└── index.ts # 前端类型定义
@@ -229,7 +272,21 @@ cd frontend-v2 && npm run dev
```bash
cd backend
# QPER 端到端测试
npx tsx scripts/test-ssa-qper-e2e.ts
# Phase I 端到端测试（需 Python + Node.js 在线）
node scripts/test-phase-i-e2e.cjs
# Phase II 端到端测试（需后端在线）
npx tsx scripts/test-ssa-phase2-e2e.ts
# Phase III 端到端测试（需后端在线）
npx tsx scripts/test-ssa-phase3-e2e.ts
# Phase IV 端到端测试（需后端 + 数据库在线）
npx tsx scripts/test-ssa-phase4-e2e.ts
```
### Prompt 种子（需数据库运行）
@@ -238,6 +295,10 @@ npx tsx scripts/test-ssa-qper-e2e.ts
cd backend
npx tsx scripts/seed-ssa-intent-prompt.ts
npx tsx scripts/seed-ssa-reflection-prompt.ts
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
```
---
@@ -263,31 +324,18 @@ npx tsx scripts/seed-ssa-reflection-prompt.ts
### 近期（优先级高）
1. **Phase Deploy（37h / 5.5 天）** — 补齐 R 工具 7→11 + 生产环境部署上线
1. **Phase V — 反思编排 + 高级特性（18h / 3 天）**
- 错误分类器实现（可自愈 vs 不可自愈）
- 自动反思（静默重试，MAX 2 次）+ 手动反思（用户驱动，feedback 意图）
- write_report interpret 模式 + discuss 意图处理（深度解读已有结果）
2. **Phase I — Session 黑板 + READ 层（30h / 5 天）** — 已吸收 Phase Q+
- SessionBlackboardService（CacheFactory / Postgres-Only 架构）
- `get_data_overview` + `get_variable_detail` 工具
- DataContext 前端展示 + 变量字典面板
- PICO 推断 + 用户确认流程
3. **Phase II — 对话层 LLM + 意图路由器 + 统一对话入口（35h / 5.5 天）**
- ConversationService 核心（六段式 System Prompt 动态组装）
- IntentRouterService（规则 + LLM 混合路由 + 上下文守卫）
- 统一对话 API `/api/ssa/chat`
- chat/explore 意图处理
2. **Phase Deploy 收尾** — 前端三线表增强、决策表/流程模板补齐、ACR/SAE 部署
### 中期
4. **Phase III（20h）** — method_consult + ask_user 标准化
5. **Phase IV（21h）** — THINK + ACT 工具封装 + analyze 完整链路
6. **Phase V（18h）** — 反思编排 + discuss + feedback
3. **Phase VI（10h）** — 集成测试 + 可观测性（含 QPER 透明化）
### 后期
7. **Phase VI（10h）** — 集成测试 + 可观测性（含 QPER 透明化）
**详细计划：** `04-开发计划/11-智能对话与工具体系开发计划.md`（v1.2，含 8 条架构约束 C1-C8）
**详细计划：** `04-开发计划/11-智能对话与工具体系开发计划.md`（v1.8，Phase I-IV 完成，含架构约束 C1-C8 + 全部团队审查落地记录）
---
@@ -332,7 +380,7 @@ npx tsx scripts/seed-ssa-reflection-prompt.ts
---
**文档版本：** v3.0
**文档版本：** v3.4
**最后更新：** 2026-02-22
**当前状态：** 🎉 QPER 主线闭环 + 智能对话与工具体系架构设计完成
**下一步：** Phase Deploy（工具补齐）→ Phase I（Session 黑板 + READ 层）
**当前状态：** 🎉 QPER 主线闭环 + Phase I + Phase II + Phase III + Phase IV 已完成
**下一步：** Phase V（反思编排 + 高级特性，18h/3 天）