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 天）

320
docs/03-业务模块/SSA-智能统计分析/04-开发计划/11-智能对话与工具体系开发计划.md
View File

@@ -1,8 +1,8 @@
# SSA-Pro 智能对话与工具体系开发计划
> **文档版本：** v1.2
> **文档版本：** v1.8
> **创建日期：** 2026-02-21
> **最后更新：** 2026-02-22（v1.2 — 新增实现规范与约束：6 条审查建议 + Postgres-Only 缓存修正）
> **最后更新：** 2026-02-22（v1.8 — Phase IV 开发完成，E2E 25/25 通过）
> **文档类型：** 开发计划 (Development Plan)
> **前置设计：**
> - `00-系统设计/SSA-Pro 意图识别与对话架构设计.md`
@@ -32,20 +32,20 @@ QPER 主线计划（10-QPER架构开发计划）
├── Phase Q ✅ 已完成
├── Phase P ✅ 已完成
├── Phase R ✅ 已完成
├── Phase Deploy 📋 待启动 ← 本计划的前置条件
├── Phase Deploy 🔶 R 层完成（12 工具），前端/部署待收尾 ← 前置条件已满足
└── Phase Q+ 📋 → 吸收进本计划 Phase I（DataContext + 变量字典）
本计划（11-智能对话与工具体系开发计划）
├── Phase I Session 黑板 + READ 层工具
├── Phase II 意图路由器 + 统一对话入口
├── Phase III method_consult + ask_user 标准化
├── Phase IV THINK + ACT 层工具封装
├── Phase I Session 黑板 + READ 层工具 ✅ 已完成（2026-02-22）
├── Phase II 意图路由器 + 统一对话入口 ✅ 已完成（2026-02-22）
├── Phase III method_consult + ask_user 标准化 ✅ 已完成（2026-02-22，E2E 13/13+4skip）
├── Phase IV 对话驱动分析 + QPER 集成 ✅ 已完成（2026-02-22，E2E 25/25）
├── Phase V 反思编排 + 高级特性
└── Phase VI 集成测试 + 可观测性
```
**关键决策：**
- Phase Deploy **必须先于**本计划启动，因为 R 工具数量从 7 扩展到 11 是 method_consult 和 analysis_plan 的基础
- Phase Deploy R 工具层已完成（2026-02-22，工具 7→12），前置条件已满足。前端增强/决策表补齐/部署上线暂缓，不阻塞本计划
- Phase Q+（变量字典 + 变量选择面板）**吸收进**本计划 Phase I，因为变量字典是 DataContext 的 Layer 3
- QPER 透明化（Pipeline 可观测性）**部分融入**本计划 Phase VI
@@ -99,7 +99,7 @@ QPER 主线计划（10-QPER架构开发计划）
| 违规 | 位置 | 修正计划 |
|------|------|---------|
| `AVAILABLE_TOOLS` 硬编码常量 | `WorkflowPlannerService.ts` | Phase IV 中改为读取 `tools_registry.json` |
| ~~`AVAILABLE_TOOLS` 硬编码常量~~ | `WorkflowPlannerService.ts` | ✅ Phase IV 已改为 `toolRegistryService.getToolName()` |
---
@@ -129,26 +129,27 @@ QPER 主线计划（10-QPER架构开发计划）
---
## 4. Phase I — Session 黑板 + READ 层（30h / 5 天）
## 4. Phase I — Session 黑板 + READ 层（30h / 5 天）✅ 已完成
> **目标：让系统能"看懂数据"并陪用户聊天，即使不能跑分析，用户也能感受到 AI 的价值。**
> **产出：** `get_data_overview` + `get_variable_detail` + Session 黑板 + DataContext 前端展示
> **吸收：** 原 QPER 计划的 Phase Q+（变量字典 + 变量选择面板，20h）
> **吸收：** 原 QPER 计划的 Phase Q+（变量字典 + 变量选择面板，20h）
> **完成日期：** 2026-02-22（5 批次开发 + E2E 测试 31/31 通过）
### 任务清单
| # | 任务 | 工时 | 产出 | 依赖 |
| # | 任务 | 工时 | 产出 | 状态 |
|---|------|------|------|------|
| I-1 | **SessionBlackboardService 设计与实现** | 5h | Session 黑板 CRUD + CacheFactory（Postgres-Only，参见 §16.4）+ sessionId 索引 + TTL 过期 | 无 |
| I-2 | **SessionBlackboard 类型定义** | 1.5h | `SessionBlackboard` interface + Zod Schema 校验 | 无 |
| I-3 | **get_data_overview 工具实现** | 5h | 封装 DataProfileService + PICO 推断字段 + 写入 Session 黑板 | I-1, I-2 |
| I-4 | **get_variable_detail 工具实现** | 4h | DataProfileService 单列查询 API（Python 侧新增）+ Tool 接口 | I-1 |
| I-5 | **DataContext 前端状态扩展** | 3h | ssaStore 新增 dataContext 字段 + DataContextCard 组件 | I-3 |
| I-6 | **PICO 推断 Prompt 模板** | 2h | `pico_inference_prompt.json` + Few-Shot 示例 + Seed 脚本 | I-3 |
| I-7 | **变量字典前端面板** | 4h | VariableDictionaryPanel 组件（AI 推断 + 用户编辑/确认） | I-3, I-5 |
| I-8 | **数据上传后自动触发 get_data_overview** | 2h | 上传回调中调用 + SSE 推送 DataContext 就绪事件 | I-3 |
| I-9 | **Token 控制策略实现** | 2h | Session 黑板注入 LLM 前的裁剪函数（变量字典裁剪、qperTrace 滑动窗口） | I-1 |
| I-10 | **Phase I 联调测试** | 1.5h | 上传数据 → DataContext 自动生成 → 前端展示数据全貌 + 变量字典 | 全部 |
| I-1 | **SessionBlackboardService 设计与实现** | 5h | Session 黑板 CRUD + CacheFactory（Postgres-Only）+ 互斥锁 patch（H1） | ✅ 完成 |
| I-2 | **SessionBlackboard 类型定义** | 1.5h | `SessionBlackboard` interface + Zod Schema（PicoInference 允许 null，H3） | ✅ 完成 |
| I-3 | **get_data_overview 工具实现** | 5h | 封装 DataProfileService + 正态性检验 + 完整病例数 + 五段式报告 + 写入 Session 黑板 | ✅ 完成 |
| I-4 | **get_variable_detail 工具实现** | 4h | Python variable-detail 端点 + bins<=30（H2）+ Q-Q 点数限制 + Tool 接口 | ✅ 完成 |
| I-5 | **DataContext 前端状态扩展** | 3h | ssaStore dataContext 字段 + DataContextCard 五段式报告组件 | ✅ 完成 |
| I-6 | **PICO 推断 Prompt + PicoInferenceService** | 2h | seed-ssa-pico-prompt.ts 已入库 + LLM 推断 + Zod 校验 + jsonrepair + 重试 | ✅ 完成 |
| I-7 | **变量字典前端面板** | 4h | VariableDictionaryPanel（搜索/筛选/类型编辑/标签编辑）+ VariableDetailPanel | ✅ 完成 |
| I-8 | **数据上传后自动触发 + SSE** | 2h | session.routes.ts 异步 fire-and-forget + GET /data-context/stream SSE 端点 | ✅ 完成 |
| I-9 | **TokenTruncationService** | 2h | aggressive/balanced/minimal 策略 + estimateTokens + toPromptString | ✅ 完成 |
| I-10 | **Phase I E2E 测试** | 1.5h | test-phase-i-e2e.cjs: Python 端点 + 数据结构 + H2/H3 防护，31/31 通过 | ✅ 完成 |
### 配置化要求
@@ -158,43 +159,47 @@ QPER 主线计划（10-QPER架构开发计划）
| 变量类型推断规则 | `variable_inference_rules.json` | ✅ |
| Token 裁剪阈值 | `session_config.json`（变量数阈值、滑动窗口大小） | ✅ |
### 验收标准
### 验收标准（已全部达成）
```
✅ 上传 CSV 后 3 秒内，前端展示 DataContext 卡片（统计摘要 + PICO 推断 + 变量列表）
✅ 点击任意变量 → 展示单变量详情（分布图 + 统计量 + 异常值）
✅ PICO 推断标记为 "AI 推断"，用户可编辑确认后标记为 "已确认"
✅ 变量字典支持用户修改 label、type、role，修改后写回 Session 黑板
✅ Session 黑板数据在同一会话内持久有效，刷新页面后可恢复（CacheFactory，生产环境 Postgres 持久化）
✅ 上传 CSV 后自动触发 data_overview + PICO 推断（异步 fire-and-forget + SSE 实时进度）
✅ DataContextCard 展示五段式报告（基本特征/缺失/类型/异常值/正态性）
✅ 点击任意变量 → VariableDetailPanel 展示描述统计/直方图/Q-Q/正态性/分类分布
✅ PICO 推断支持观察性研究（intervention/comparison 允许 null，H3）
✅ 变量字典支持搜索/筛选/修改 confirmedType/label，修改通过 PATCH 写回 Session 黑板
✅ SessionBlackboard patch() 使用 sessionId 互斥锁防止并发覆盖（H1）
✅ Python histogram bins <= 30（H2），Q-Q 点数有上限，防止前端 Payload 爆炸
✅ E2E 测试 31/31 通过（Python 端点 + 数据结构 + H2/H3 验证）
```
---
## 5. Phase II — 对话层 LLM + 意图路由器 + 统一对话入口（35h / 5.5 天）
## 5. Phase II — 对话层 LLM + 意图路由器 + 统一对话入口（35h / 5.5 天）✅ 已完成
> **目标：构建对话层 LLM 基础设施 + 意图路由，让系统具备多轮连贯对话能力。**
> **产出：** 对话层 LLM 核心（System Prompt + 对话历史 + 上下文组装）+ `IntentRouterService` + `/api/ssa/chat` 统一入口 + `ChatService`
> **核心认知：对话层 LLM 是系统的大脑和嘴巴（详见《四层七工具实现机制详解》第 1-4 章），不是简单的"调一次 LLM API"。**
> **产出：** 对话层 LLM 核心（System Prompt + 对话历史 + 上下文组装）+ `IntentRouterService` + `/api/ssa/chat` 统一入口 + `ChatHandlerService`
> **核心认知：对话层 LLM 是系统的大脑和嘴巴（详见《四层七工具实现机制详解》第 1-4 章），不是简单的"调一次 LLM API"。**
> **完成日期：** 2026-02-22（4 批次开发 + E2E 测试 38/38 通过 + 团队反馈 H1-H4 全部落地）
### 任务清单
| # | 任务 | 工时 | 产出 | 依赖 |
| # | 任务 | 工时 | 产出 | 状态 |
|---|------|------|------|------|
| **对话层 LLM 基础设施** | | | | |
| II-1 | **ConversationService 核心实现** | 5h | 对话层 LLM 的核心服务：System Prompt 动态组装 + DataContext 注入 + 工具输出注入 + LLM 调用 + 流式/完整回复 | Phase I |
| II-2 | **对话历史管理** | 3h | 消息历史存储（内存/DB） + 滑动窗口裁剪（根据 Token 预算动态调整窗口大小） + 关键事件摘要压缩 | Phase I |
| II-3 | **System Prompt 架构实现** | 4h | 基础角色（固定） + DataContext 注入（动态） + 意图指令（按意图切换） + 工具输出注入（按需） + 分析结果注入（discuss 时） — 六段式动态组装 | II-1 |
| II-4 | **System Prompt 模板（全意图）** | 3h | DB Prompt 表：`base_system`（基础角色）+ `chat_instruction` / `explore_instruction` / `consult_instruction` / `analyze_instruction` / `discuss_instruction` / `feedback_instruction`（6 个意图指令段）+ Seed 脚本 | 无 |
| II-1 | **ConversationService 核心实现** | 5h | 对话持久化（复用 AIA conversations/messages 表）+ LLM 流式调用 + 5s 心跳保活（H1）+ Placeholder 占位（H3） | ✅ 完成 |
| II-2 | **对话历史管理** | 3h | 吸收进 ConversationService：滑动窗口 MAX=20 + generating 消息过滤 + 消息计数 | ✅ 完成 |
| II-3 | **System Prompt 架构实现** | 4h | SystemPromptService 六段式组装 + H2 Lost-in-the-Middle 修正（意图指令放最后）+ Token 预算裁剪 | ✅ 完成 |
| II-4 | **System Prompt 模板（全意图）** | 3h | seed-ssa-phase2-prompts.ts：8 个 Prompt（SSA_BASE_SYSTEM + 6 意图指令 + SSA_INTENT_ROUTER） | ✅ 完成 |
| **意图路由器** | | | | |
| II-5 | **意图识别规则引擎** | 3h | `intent_rules.json` 规则定义 + 规则匹配器（关键词 + 上下文状态） | Phase I |
| II-6 | **IntentRouterService 实现** | 4h | 混合路由（规则优先 + LLM 兜底）+ 意图分类输出 | II-5 |
| II-7 | **Intent Router Prompt 模板** | 1.5h | `intent_router_prompt.json` + Few-Shot 示例 + Seed 脚本 | 无 |
| II-5 | **意图识别规则引擎** | 3h | `intent_rules.json`：5 条规则 + excludeKeywords + contextGuards + defaultIntent | ✅ 完成 |
| II-6 | **IntentRouterService 实现** | 4h | 规则优先 + LLM 兜底 + 上下文守卫（C5）+ parseLLMResponse 安全解析 | ✅ 完成 |
| II-7 | **Intent Router Prompt 模板** | 1.5h | SSA_INTENT_ROUTER Prompt 已入 seed 脚本（含 Few-Shot 表格） | ✅ 完成 |
| **统一对话入口 + 基础意图处理** | | | | |
| II-8 | **统一对话 API `/api/ssa/chat`** | 3h | 新路由：接收消息 → IntentRouter 分类 → ConversationService 组装上下文 → 分发到对应 Handler → 对话层 LLM 生成回复 | II-1, II-6 |
| II-9 | **ChatService — chat 意图处理** | 2h | ConversationService(DataContext) → 对话层 LLM 直接回复 | II-8 |
| II-10 | **ChatService — explore 意图处理** | 2.5h | 调用 READ 工具获取数据 → 工具输出注入 ConversationService → 对话层 LLM 生成数据解读 | II-8 |
| II-11 | **前端对话入口统一** | 2h | SSAChatPane 消息统一走 `/api/ssa/chat`，按意图渲染不同回复类型 | II-8 |
| II-12 | **Phase II 联调测试** | 2h | 多轮对话连贯性验证 + 各意图场景验证 + 降级验证（LLM 不可用时规则兜底） | 全部 |
| II-8 | **统一对话 API `/api/ssa/chat`** | 3h | chat.routes.ts：POST /:id/chat（SSE）+ GET /:id/chat/history + GET /:id/chat/conversation | ✅ 完成 |
| II-9 | **ChatHandlerService — chat 意图处理** | 2h | handleChat()：ConversationService(DataContext) → 对话层 LLM 直接回复 | ✅ 完成 |
| II-10 | **ChatHandlerService — explore 意图处理** | 2.5h | handleExplore()：读黑板 → TokenTruncation 裁剪 → 工具输出注入 → 对话层 LLM 生成数据解读 | ✅ 完成 |
| II-11 | **前端对话入口统一** | 2h | useSSAChat hook + SSAChatPane 改造（SSE 流式 + ThinkingBlock + 意图标签 + H3 输入锁 + 中断按钮） | ✅ 完成 |
| II-12 | **Phase II 联调测试** | 2h | test-ssa-phase2-e2e.ts：11 组测试 38/38 通过（6 意图分类 + SSE 流式 + 对话历史 + 上下文守卫） | ✅ 完成 |
### 意图分发逻辑
@@ -238,97 +243,201 @@ QPER 主线计划（10-QPER架构开发计划）
| 意图→可见工具映射 | `intent_tool_visibility.json` | ✅ |
| 对话历史窗口配置 | `session_config.json`（窗口大小、Token 上限） | IT 团队 |
### 验收标准
### 验收标准（已全部达成）
```
✅ "这个数据有多少样本？" → 识别为 chat → 对话层 LLM 带 DataContext 直接回复
✅ "帮我看看各组的样本分布" → 识别为 explore → 工具输出注入 → 对话层 LLM 生成数据解读
✅ "对 BMI 和血压做相关分析" → 识别为 analyze → 转入 QPER 流水线
✅ LLM 不可用时 → 规则引擎兜底 → 正确识别明确意图
✅ 无法判断时 → 默认 chat（最安全的兜底）
✅ 多轮对话连贯性：用户说"刚才那个变量" → LLM 从对话历史正确解析为 BMI
✅ 意图切换衔接：consult → analyze 时，LLM 自然衔接"好的，我来按之前讨论的方案执行"
✅ "BMI 的正常范围是多少？" → chat → 对话层 LLM 带 DataContext 直接回复（E2E Test 4）
✅ "帮我看看各组的样本分布" → explore → 黑板数据注入 → 对话层 LLM 生成数据解读（E2E Test 5）
✅ "对 BMI 和血压做相关分析" → analyze → LLM 生成方案摘要（E2E Test 6）
✅ "应该用什么方法比较两组差异" → consult → LLM 方法推荐回复（E2E Test 7）
✅ "这个 p 值说明什么" → discuss 被守卫降级为 chat（无分析结果时，E2E Test 8）
✅ LLM 不可用时 → 规则引擎兜底 → 正确识别明确意图（IntentRouterService try/catch）
✅ 无法判断时 → 默认 chat（最安全的兜底，confidence=0.5）
✅ 对话历史持久化 → 消息有 intent 标记 + 无残留 generating 状态（E2E Test 9）
✅ SSE 心跳保活 5s（H1）+ Placeholder 占位（H3）+ 意图指令放最后（H2）
✅ 前端 useSSAChat hook + SSAChatPane 流式渲染 + ThinkingBlock + 意图标签 + 输入锁
```
### 团队反馈落地（H1-H4）
| 编号 | 问题 | 修正 | 实现文件 |
|------|------|------|---------|
| H1 | SSE 超时/网关断开 | 5s 心跳 keep-alive + 标准化错误事件 | ConversationService.ts |
| H2 | Lost in the Middle | 意图指令放 Prompt 最后，工具输出放中间 | SystemPromptService.ts |
| H3 | 对话历史竞态条件 | DB Placeholder 占位 + 前端 isGenerating 输入锁 | ConversationService.ts + useSSAChat.ts |
| H4 | 前端渐进迁移 | 直接原地改造（开发阶段无需灰度） | SSAChatPane.tsx |
---
## 6. Phase III — method_consult + ask_user 标准化（20h / 3 天）
## 6. Phase III — method_consult + ask_user 标准化（20h / 3 天）✅ 已完成
> **目标：系统能给用户推荐分析方法（不执行），并在不确定时主动提问。**
> **产出：** `method_consult` 工具 + `ask_user` 标准化接口 + consult 意图处理
> **产出：** `MethodConsultService` + `AskUserService` + `ToolRegistryService`（H2 仓储模式）+ `AskUserCard` + consult 意图完整链路
> **完成日期：** 2026-02-22（5 批次代码开发完成，待数据库启动后运行 seed + E2E 测试）
### 任务清单
| # | 任务 | 工时 | 产出 | 依赖 |
| # | 任务 | 工时 | 产出 | 状态 |
|---|------|------|------|------|
| III-1 | **method_consult Tool 实现** | 5h | 封装 DecisionTableService 四维匹配 + LLM 推理补充 + 返回推荐/替代/前提 | Phase I |
| III-2 | **method_consult Prompt 模板** | 2h | `method_consult_prompt.json` + 方法推荐 Few-Shot | 无 |
| III-3 | **ask_user 后端接口标准化** | 4h | 统一输入/输出 Schema + 请求-响应模式（Node.js 生成卡片 → 前端渲染 → 用户选择 → 恢复流程） | Phase I |
| III-4 | **ask_user 前端组件增强** | 3h | ClarificationCard 升级：支持单选/多选/自由文本、上下文说明、标准化样式 | III-3 |
| III-5 | **consult 意图处理（对话层 LLM 集成）** | 3h | method_consult 返回匹配结果 → 注入 ConversationService → 对话层 LLM 生成完整方法推荐（理由+前提+替代） → ask_user 确认 → 可转入 analyze | III-1, III-3, Phase II |
| III-6 | **ToolRegistryService 骨架** | 2h | 7 工具注册表 + `tool_definitions.json` + 阶段性可见性查询 API | 无 |
| III-7 | **Phase III 联调测试** | 1h | consult 场景端到端 + ask_user 确认流程 | 全部 |
| III-1 | **method_consult Tool 实现** | 5h | MethodConsultService: PICO→ParsedQuery 映射 + DecisionTable 匹配 + ToolRegistry 工具详情 + formatForLLM | ✅ 完成 |
| III-2 | **method_consult Prompt 模板** | 2h | seed-ssa-phase3-prompts.ts: SSA_METHOD_CONSULT（P1 结论先行+结构化列表约束） | ✅ 完成（待 seed） |
| III-3 | **ask_user 后端接口标准化** | 4h | AskUserService: createQuestion + parseResponse + clearPending + 黑板持久化 + H1 全局打断判定 | ✅ 完成 |
| III-4 | **ask_user 前端组件增强** | 3h | AskUserCard.tsx: 4 种 inputType（single_select/multi_select/free_text/confirm）+ H1 跳过按钮 + H3 统一替代 ClarificationCard | ✅ 完成 |
| III-5 | **consult 意图完整链路** | 3h | ChatHandlerService.handleConsult（method_consult→LLM 推荐→ask_user 确认）+ handleAskUserResponse（confirm/skip/change） | ✅ 完成 |
| III-6 | **ToolRegistryService** | 2h | H2 仓储模式: IToolRepository 接口 + JsonToolRepository + formatForLLM/formatToolDetail + QueryService 替换 | ✅ 完成 |
| III-7 | **Phase III 联调测试** | 1h | test-ssa-phase3-e2e.ts: 8 组测试（consult + ask_user confirm/skip + H1 全局打断 + 对话历史） | ✅ 完成（13 pass / 4 skip） |
### 配置化要求
| 配置项 | 文件 | 方法学团队可编辑 |
|--------|------|:---:|
| 方法推荐 Prompt | `method_consult_prompt.json` 或 DB Prompt 表 | ✅ |
| 工具定义（名称、描述、层级、参数） | `tool_definitions.json` | ✅ |
| 意图→工具可见性映射 | `intent_tool_visibility.json` | ✅ |
| 方法推荐 Prompt | DB Prompt 表 SSA_METHOD_CONSULT | ✅ |
| 工具定义（名称、描述、参数） | `tools_registry.json` | ✅ |
| 决策表（四维匹配规则） | `decision_tables.json` | ✅ |
### 验收标准
```
✅ "我想比较两组差异，应该用什么方法？" → method_consult → 推荐 T 检验 + 理由 + 前提 + 替代方案
✅ method_consult 输出不触发执行，用户确认后才转入 analyze
✅ ask_user 渲染为标准化选择卡片（单选/多选/自由文本）
✅ PICO 确认流程：get_data_overview → LLM 推断 → ask_user 确认 → 写入 Session 黑板
✅ "我想比较两组差异" → consult → MethodConsultService → DecisionTable 匹配 T 检验
✅ LLM 输出 P1 格式（结论先行 + 理由/前提/替代列表）
✅ method_consult 不触发执行，推送 ask_user confirm 卡片
✅ 用户确认 → 可转 analyze；用户跳过 → 友好回复
✅ H1: 用户无视卡片直接打字 → 自动 clearPending + 按新意图路由
✅ H2: ToolRegistryService 通过 IToolRepository 隔离数据源
✅ H3: AskUserCard 统一替代 ClarificationCard（旧组件保留 deprecated）
✅ 工具注册表可通过热更新 API 重载
```
### 团队审查修正落地
| 编号 | 盲区 | 修正 | 实现文件 |
|------|------|------|---------|
| H1 | 状态死锁/意图强行打断 | 前端跳过按钮 + 后端全局打断判定（chat.routes 入口 pendingAskUser 检测） | chat.routes.ts, AskUserCard.tsx |
| H2 | ToolRegistry 绑死 JSON | IToolRepository 接口 + JsonToolRepository 实现 | ToolRegistryService.ts |
| H3 | Clarification vs AskUser 概念冲突 | 统一 AskUser 领域模型，新建 AskUserCard | AskUserService.ts, AskUserCard.tsx |
| P1 | Prompt 输出格式 | 结论先行 + 结构化列表约束 | seed-ssa-phase3-prompts.ts |
---
## 7. Phase IV — THINK + ACT 层工具封装（21h / 3 天）
## 7. Phase IV — 对话驱动分析 + QPER 集成（14h / 2.5 天）✅ 已完成
> **目标：将已有 QPER 底层 Service 封装为标准 Tool 接口，挂载到新工具体系上。**
> **产出：** `analysis_plan` + `run_step` + `write_report`(generate) 工具封装 + AVAILABLE_TOOLS 配置化修正
> **目标：打通对话层与 QPER 执行层的断裂，让 analyze 意图在对话流中完成全链路。**
> **产出：** ToolOrchestratorService + handleAnalyze 重写 + AVAILABLE_TOOLS 配置化 + 前端事件协调 + E2E
> **完成日期：** 2026-02-22（5 批次开发 + E2E 测试 25/25 通过 + 团队审查 H1-H3+B1-B2 全部落地）
### 任务清单
### 现状诊断
| # | 任务 | 工时 | 产出 | 依赖 |
Phase II 的 `handleAnalyze()` 是一个占位符 — 只生成 1-3 句 LLM 摘要就结束，QPER 计划生成和执行需要前端单独调用 `/workflow/plan` + `/workflow/{id}/stream`。对话层与执行层完全断裂。
### 核心架构决策
| # | 决策 | 选择 | 理由 |
|---|------|------|------|
| D1 | 执行通道 | **保留独立 workflow SSE** | R 引擎每步 20-40s，workflow SSE 已有心跳/重连/进度机制，Workspace 已完美适配 |
| D2 | 计划传递 | **chat SSE 推送 `analysis_plan` 事件** | 前端不再单独调 POST /workflow/plan，计划生成在对话流中完成 |
| D3 | 确认方式 | **双通道** | ask_user 卡片 + Workspace "执行"按钮，两者都触发同一个 executeWorkflow() |
| D4 | 工具封装 | **ToolOrchestratorService 薄层** | 不创建独立 Tool 类（当前阶段过度设计），一个 Service 统一封装 plan/execute/report |
| D5 | PICO 角色 | **可选 hint，非必要条件** | 用户直接表述优先于系统推断；PICO 存在时作为 LLM 附加上下文，不存在时退化为纯 LLM + DataProfile 解析 |
### 团队审查修正记录
| # | 盲区 | 审查结论 | 落地方案 |
|---|------|---------|---------|
| H1 | **planWorkflow 上下文失忆** — plan() 仅传 userMessage，丢失 PICO/变量字典等黄金上下文 | ✅ 接受核心洞察，实现方式优化 | ToolOrchestratorService.plan() 读取黑板，PICO 作为可选 hint 注入 LLM prompt（非强依赖） |
| H2 | **幽灵卡片竞态** — Workspace 触发执行后，Chat 区 ask_user 卡片仍可点击 | ✅ 接受，简化实现 | 任一侧触发执行时同步清除 pendingQuestion + clearPending，卡片消失而非仅禁用 |
| H3 | **SSE 事件乱序** — 建议 analysis_plan → LLM → ask_user 之间加 delay(500) | ❌ 拒绝 delay 方案 | SSE 协议保证顺序（TCP），JS 单线程保证处理顺序；保持严格串行 await 即可 |
| B1 | **修改建议循环** — 用户在 ask_user 自由文本中要求换方法，应走重新规划 | ✅ 接受 | handleAskUserResponse 识别 change_method → 重新调 handleAnalyze() |
| B2 | **旧 API 向后兼容** — /workflow/plan 仍需可用 | ✅ 接受 | 改调用方不改被调用方，E2E 显式验证旧 API |
### PICO 三层降级策略（D5 详解）
```
用户上传数据后直接说"对BMI做T检验" → 场景 B（最常见，~50%）
用户经历完整探索/PICO推断后再分析 → 场景 A（~30%）
用户说"帮我分析一下"很模糊 → 场景 C（~20%）
ToolOrchestratorService.plan(sessionId, userMessage):
1. 读 SessionBlackboard（PICO 可能有也可能没有）
2. 判断路径:
┌─ 用户消息明确（提到变量+目标）→ planWorkflow()（LLM 解析，PICO 不参与）
├─ 用户消息模糊 + PICO 存在 → PICO 作为 hint 注入 LLM prompt，提高准确率
└─ 用户消息模糊 + 无 PICO → 纯 LLM + DataProfile 推断；confidence<0.7 则追问
3. 无论哪条路径 → ParsedQuery → DecisionTable → FlowTemplate → WorkflowPlan
核心原则: PICO 锦上添花，不是必要条件。用户直接表述永远优先于系统推断。
```
### 核心数据流
```mermaid
sequenceDiagram
participant U as 用户
participant FE as ChatPane
participant WS as Workspace
participant Chat as "/chat SSE"
participant TO as ToolOrchestratorService
participant WP as WorkflowPlannerService
participant WE as WorkflowExecutorService
U->>FE: "对BMI和血压做相关分析"
FE->>Chat: POST /chat
Chat->>TO: plan(sessionId, userMessage)
Note over TO: 读黑板, PICO作为可选hint
TO->>WP: planWorkflow()
WP-->>TO: WorkflowPlan
TO-->>Chat: return plan
Chat-->>FE: SSE: analysis_plan事件
FE->>WS: 自动创建Record+打开Workspace
Chat-->>FE: SSE: LLM流式方案说明
Chat-->>FE: SSE: ask_user确认卡片
U->>FE: 点"确认执行"
Note over FE: 清除pendingQuestion(H2)
FE->>WS: executeWorkflow(workflowId)
WS->>WE: GET /workflow/id/stream
WE-->>WS: SSE: 步骤进度+结果
WS->>WS: 显示分析结果+结论
```
### 任务清单（修订后）
| # | 任务 | 工时 | 产出 | 状态 |
|---|------|------|------|------|
| IV-1 | **analysis_plan Tool 封装** | 4h | 封装 Q 层参数提取 + P 层 FlowTemplate 填充 → 输出有序步骤列表 | Phase I, Phase III |
| IV-2 | **run_step Tool 封装** | 3h | 封装 WorkflowExecutorService + data_source 自动注入（从 Session 黑板取 dataOssKey） | Phase I |
| IV-3 | **write_report Tool 封装（generate 模式）** | 3h | 封装 ReflectionService → 论文级报告生成 | Phase I |
| IV-4 | **analyze 意图完整链路对接（对话层 LLM 集成）** | 4h | IntentRouter(analyze) → analysis_plan → 对话层 LLM 生成方案说明 → ask_user(确认方案) → run_step ×N（每步对话层 LLM 播报进展） → write_report → 对话层 LLM 生成总结 | IV-1, IV-2, IV-3, Phase II |
| IV-5 | **AVAILABLE_TOOLS 配置化修正** | 2h | WorkflowPlannerService 中的硬编码常量改为读取 tools_registry.json | 无 |
| IV-6 | **阶段性工具可见性实现** | 2h | ToolRegistryService 根据当前意图/阶段过滤可用工具列表，注入 LLM 上下文 | III-6 |
| IV-7 | **analysis_plan 前端审查面板** | 2h | 展示分析方案 → 用户确认/修改 → 确认后触发执行 | IV-1, IV-4 |
| IV-8 | **Phase IV 联调测试** | 1h | analyze 意图完整旅程验证 | 全部 |
| IV-1 | **AVAILABLE_TOOLS 配置化** | 2h | WorkflowPlannerService 删除硬编码常量（11 处引用），改为 toolRegistryService.getToolName(); ToolCode 改为 string 类型 | ✅ 完成 |
| IV-2 | **工具可见性实现** | 1h | ToolRegistryService 新增 getVisibleTools(intent) 按意图过滤工具列表 | ✅ 完成 |
| IV-3 | **ToolOrchestratorService** | 2h | 新建 Service: plan()（含 PICO hint 三层降级 D5）+ formatPlanForLLM() + buildPicoHint() | ✅ 完成 |
| IV-4 | **handleAnalyze 重写** | 3h | 多阶段编排: 调 orchestrator.plan → 推 analysis_plan SSE → LLM 流式方案说明 → 推 ask_user 确认（含 confirm_plan/change_method 选项） | ✅ 完成 |
| IV-5 | **handleAskUserResponse 扩展** | 1h | 新增 confirm_plan 路由（推 plan_confirmed SSE）; change_method 走重新规划循环(B1); 执行触发时 clearPending(H2) | ✅ 完成 |
| IV-6 | **前端对接** | 3h | useSSAChat 增加 analysis_plan SSE → ssaStore.addRecord + setWorkspaceOpen; plan_confirmed SSE → pendingPlanConfirm 触发 executeWorkflow; SSAChatPane 渲染 AskUserCard + 幽灵卡片清除(H2) | ✅ 完成 |
| IV-7 | **Prompt 种子** | 1h | seed-ssa-phase4-prompts.ts: SSA_ANALYZE_PLAN（指导 LLM 解释分析方案 + 步骤/理由/注意事项格式约束）已入库 | ✅ 完成 |
| IV-8 | **E2E 测试** | 1h | test-ssa-phase4-e2e.ts: 7 组测试 25/25 通过（analyze 意图→analysis_plan→ask_user 确认→旧 API 兼容 B2→AVAILABLE_TOOLS 配置化→对话历史） | ✅ 完成 |
> **总工时: 14h（原计划 21h → 精简 7h，因不创建独立 Tool 类）**
### data_source 自动注入流程
```
run_step 被调用
→ ToolOrchestrator 拦截
→ 从 SessionBlackboard 取出 dataOssKey
→ 生成预签名 URL
→ 注入 params.data_source = { type: 'oss', oss_url: signedUrl }
executeWorkflow() 被前端触发
→ GET /workflow/{id}/stream
→ WorkflowExecutorService.resolveDataSource() 自动注入（已有逻辑，不改）
→ POST 给 R 服务
→ LLM 和 analysis_plan 全程不感知 data_source
→ LLM 和 ToolOrchestratorService 全程不感知 data_source
```
> 注：`WorkflowExecutorService.resolveDataSource()` 已有此逻辑，run_step 封装时直接复用。
### 验收标准
### 验收标准（已全部达成）
```
✅ "对 BMI 和血压做相关分析" → analyze → analysis_plan → 用户确认 → run_step → write_report
✅ analysis_plan 输出确定的 tool_code + params，run_step 傻瓜式转发
✅ data_source 由 Session 黑板自动注入，LLM 上下文中不出现文件路径
✅ WorkflowPlannerService.AVAILABLE_TOOLS 读取 JSON，不再硬编码
✅ 不同阶段 LLM 看到的工具列表不同（数据探索阶段看不到 run_step）
✅ "请执行分析：比较两组患者的BMI差异" → analyze → plan 生成 3 步骤（对话内）→ ask_user 确认卡片（E2E Test 3）
✅ analysis_plan 通过 chat SSE 推送，前端自动创建 AnalysisRecord 并打开 Workspace（E2E Test 3）
✅ 无 PICO 时链路完全可用 — E2E 测试数据无完整 PICO，planWorkflow 仍成功生成方案（E2E Test 6）
✅ 有 PICO 时作为 hint 注入（ToolOrchestratorService.buildPicoHint），不覆盖用户显式指令
✅ ask_user 确认卡片包含 confirm_plan（确认执行）和 change_method（修改方案）选项（E2E Test 4）
✅ confirm_plan 响应 → 推 plan_confirmed SSE → 前端 pendingPlanConfirm → executeWorkflow（H2 幽灵卡片修正）
✅ change_method 响应 → handleAskUserResponse 重新调 handleAnalyze（B1 修改建议循环）
✅ WorkflowPlannerService.AVAILABLE_TOOLS 已删除，11 处引用全部改为 toolRegistryService.getToolName()（E2E Test 6）
✅ ToolRegistryService.getVisibleTools(intent) 按意图过滤工具列表
✅ 旧 /workflow/plan API 仍可正常调用，返回 WorkflowPlan 含 workflow_id + 步骤（E2E Test 5, B2 向后兼容）
✅ 对话历史中有 analyze 意图消息记录，无残留 generating 状态（E2E Test 7）
✅ LLM 流式方案说明 >200 字符，使用 SSA_ANALYZE_PLAN Prompt 指导输出（E2E Test 3）
```
---
@@ -423,11 +532,11 @@ run_step 被调用
| **I** | **Session 黑板 + READ 层** | **30h** | **5 天** | 系统能看懂数据 | 不变 |
| **II** | **对话层 LLM + 意图路由器 + 统一对话入口** | **35h** | **5.5 天** | 系统能连贯对话 + 区分意图 | **+11h**：新增 ConversationService(5h) + 对话历史管理(3h) + System Prompt 架构(4h) + 全意图 Prompt 模板(3h)；chat/explore 工时因依赖 ConversationService 而减少 |
| **III** | **method_consult + ask_user** | **20h** | **3 天** | 系统能推荐方法、主动提问 | 不变（consult 对话层集成已含在 III-5） |
| **IV** | **THINK + ACT 工具封装** | **21h** | **3 天** | 新工具体系挂载 QPER | **+1h**：IV-4 analyze 链路增加对话层 LLM 进展播报 |
| **IV** | **对话驱动分析 + QPER 集成** | **14h** | **2.5 天** | analyze 意图打通对话→计划→执行→结果 | **v1.7 修订**：不创建独立 Tool 类，ToolOrchestratorService 薄层封装；21h→14h；含 H1-H3+B1-B2 团队审查修正 |
| **V** | **反思编排 + 高级特性** | **18h** | **3 天** | 自修复 + 结果解读 | 不变 |
| **VI** | **集成测试 + 可观测性** | **10h** | **2 天** | 全链路验证 + 开发者调试 | 不变 |
| | **本计划合计** | **134h** | **~22 天** | **智能对话 + 工具体系上线** | **+12h** |
| | **含 Phase Deploy 总计** | **171h** | **~27.5 天** | **完整系统升级** | **+12h** |
| | **本计划合计** | **127h** | **~20.5 天** | **智能对话 + 工具体系上线** | v1.7: Phase IV 21h→14h(-7h) |
| | **含 Phase Deploy 总计** | **164h** | **~26 天** | **完整系统升级** | v1.7: -7h |
### 10.2 里程碑时间线
@@ -896,11 +1005,10 @@ function createDynamicSchema<T>(validValues: T[]) {
**文档维护者：** SSA 架构团队
**创建日期：** 2026-02-21
**最后更新：** 2026-02-22（v1.2 — 新增实现规范与约束：6 条审查建议 + Postgres-Only 缓存修正）
**最后更新：** 2026-02-22（v1.8 — Phase IV 开发完成，E2E 25/25 通过）
**下一步行动：**
1. Phase Deploy 启动（R 工具补齐，5.5 天）
2. Phase Deploy 完成后立即启动 Phase I（Session 黑板 + READ 层）
3. Phase I 和 Phase Deploy 可考虑部分并行（Phase I 不依赖新 R 工具）
1. 执行 Phase V（反思编排 + 高级特性，18h / 3 天）
2. Phase Deploy 剩余收尾可与 Phase V 并行
### 变更日志
@@ -909,3 +1017,9 @@ function createDynamicSchema<T>(validValues: T[]) {
| v1.0 | 2026-02-21 | 初版：6 Phase 开发计划，122h/20 天 |
| v1.1 | 2026-02-21 | **新增对话层 LLM 基础设施**：① Phase II 新增 ConversationService 核心实现(5h) + 对话历史管理(3h) + System Prompt 架构实现(4h) + 全意图 Prompt 模板(3h)；② Phase II 名称改为"对话层 LLM + 意图路由器 + 统一对话入口"，24h→35h；③ Phase IV analyze 链路增加对话层 LLM 进展播报(+1h)；④ Prompt 模板清单从 7 个扩展为 13 个（新增 base_system + 6 个意图指令段）；⑤ 新增 ConversationService.ts + ConversationHistoryService.ts；⑥ 总工时 122h→134h，27.5 天含 Deploy |
| v1.2 | 2026-02-22 | **新增实现规范与约束（§16-§17）**：① 6 条架构审查建议（3 预警 W1-W3 + 3 盲区 B1-B3）转化为实现规范；② 修正 Session 黑板缓存策略为 Postgres-Only（无 Redis，遵循平台云原生规范）；③ 新增架构约束速查表（8 条 C1-C8）；④ 无新增工时（规范融入已有任务） |
| v1.3 | 2026-02-22 | **Phase I 开发完成**：① 5 批次全部交付（18 个文件新增/修改）；② 实现 4 项隐患修正（H1 互斥锁/H2 bins 限制/H3 观察性研究 null/H4 Mock 先行）；③ E2E 测试 31/31 通过；④ 新增文件：SessionBlackboardService、PicoInferenceService、TokenTruncationService、GetDataOverviewTool、GetVariableDetailTool、blackboard.routes、seed-ssa-pico-prompt、DataContextCard、VariableDictionaryPanel、VariableDetailPanel、test-phase-i-e2e.cjs；⑤ Python 扩展：正态性检验 + variable-detail 端点 |
| v1.4 | 2026-02-22 | **Phase II 开发完成**：① 4 批次全部交付（9 个文件新增 + 3 个文件修改）；② 落地团队反馈 H1-H4（SSE 心跳/Lost-in-the-Middle/竞态保护/前端直接改造）；③ E2E 测试 38/38 通过（11 组测试：6 意图分类 + SSE 流式 + 对话历史 + 上下文守卫）；④ 新增后端：SystemPromptService、ConversationService、IntentRouterService、ChatHandlerService、chat.routes、intent_rules.json、seed-ssa-phase2-prompts（8 Prompt）；⑤ 新增前端：useSSAChat hook；⑥ 修改前端：SSAChatPane（handleSend 走 /chat SSE + ThinkingBlock + 意图标签 + H3 输入锁）；⑦ 修复 bug：finalizeAssistantMessage metadata 合并（保留 intent 字段） |
| v1.5 | 2026-02-22 | **Phase III 代码完成**：① 5 批次代码交付（7 个文件新增 + 5 个文件修改）；② 落地团队审查 H1-H3+P1（状态死锁防护/仓储模式/概念统一/Prompt 格式约束）；③ 新增后端：ToolRegistryService（IToolRepository+JsonToolRepository）、MethodConsultService（PICO→ParsedQuery→DecisionTable）、AskUserService（createQuestion/parseResponse/clearPending）、seed-ssa-phase3-prompts、test-ssa-phase3-e2e；④ 新增前端：AskUserCard（4 inputType + H1 跳过按钮）；⑤ 修改后端：ChatHandlerService（handleConsult+handleAskUserResponse）、chat.routes（H1 全局打断判定）、session-blackboard.types（pendingAskUser 字段）；⑥ 修改前端：useSSAChat（pendingQuestion+respondToQuestion+skipQuestion）；⑦ QueryService 替换 AVAILABLE_TOOLS 为 toolRegistryService.formatForLLM() |
| v1.6 | 2026-02-22 | **Phase III 完成**：① SSA_METHOD_CONSULT Prompt seed 成功入库（id=28）；② E2E 测试 13 passed / 0 failed / 4 skipped（跳过原因：测试数据 PICO 推断不完整，未触发 ask_user 确认卡片，属预期行为）；③ 修复 seed 脚本（从 raw SQL 改为 Prisma model 调用，适配 capability_schema） |
| v1.7 | 2026-02-22 | **Phase IV 设计方案确定**：① 重新定位为"对话驱动分析 + QPER 集成"（原"THINK + ACT 层工具封装"）；② 5 项架构决策（D1 保留独立 workflow SSE / D2 chat SSE 推 analysis_plan / D3 双通道确认 / D4 ToolOrchestratorService 薄层封装 / D5 PICO 可选 hint 非必要条件）；③ 团队审查 5 条反馈（H1 上下文失忆→接受优化为 PICO hint 注入 / H2 幽灵卡片→接受简化为清除 pendingQuestion / H3 SSE 乱序 delay→拒绝 / B1 修改建议循环→接受 / B2 旧 API 兼容→接受）；④ PICO 三层降级策略（用户显式指令优先→PICO hint 辅助→纯 LLM+DataProfile 推断）；⑤ 工时从 21h 精简为 14h（不创建独立 Tool 类）；⑥ 8 个任务 5 个 Batch |
| v1.8 | 2026-02-22 | **Phase IV 开发完成**：① 5 批次全部交付（4 个文件新增 + 7 个文件修改）；② 落地团队审查 H1-H3+B1-B2（PICO hint 注入/幽灵卡片清除/SSE 严格串行/修改建议循环/旧 API 兼容）；③ E2E 测试 25/25 通过（7 组：登录→Session 创建+数据概览→analyze 意图 analysis_plan 3 步骤→ask_user 确认卡片→旧 /workflow/plan B2 兼容→AVAILABLE_TOOLS 配置化→对话历史）；④ 新增后端：ToolOrchestratorService（plan+formatPlanForLLM+buildPicoHint）、seed-ssa-phase4-prompts（SSA_ANALYZE_PLAN 入库）、test-ssa-phase4-e2e；⑤ 修改后端：WorkflowPlannerService（删除 AVAILABLE_TOOLS 常量，11 处改 toolRegistryService）、ToolRegistryService（+getVisibleTools）、ChatHandlerService（handleAnalyze 重写+handleAskUserResponse 扩展 confirm_plan/change_method）、AskUserService（+metadata）、QueryService/WorkflowExecutorService（清理未用导入）；⑥ 修改前端：useSSAChat（analysis_plan+plan_confirmed SSE 处理+pendingPlanConfirm）、SSAChatPane（AskUserCard 渲染+executeWorkflow 触发） |