Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
85fda830c262a48a44ed8c3bf324a2064ed566b0
AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
HaHafeng 85fda830c2 feat(ssa): Complete Phase V-A editable analysis plan variables 
Features:
- Add editable variable selection in workflow plan (SingleVarSelect + MultiVarTags)
- Implement 3-layer flexible interception (warning bar + icon + blocking dialog)
- Add tool_param_constraints.json for 12 statistical tools parameter validation
- Add PATCH /workflow/:id/params API with Zod structural validation
- Implement synchronous parameter sync before execution (Promise chaining)
- Fix LLM hallucination by strict system prompt constraints
- Fix DynamicReport object-based rows compatibility (R baseline_table)
- Fix Word export row.map error with same normalization logic
- Restore inferGroupingVar for smart default variable selection
- Add ReactMarkdown rendering in SSAChatPane
- Update SSA module status document to v3.5

Modified files:
- backend: workflow.routes, ChatHandlerService, SystemPromptService, FlowTemplateService
- frontend: WorkflowTimeline, SSAWorkspacePane, DynamicReport, SSAChatPane, ssaStore, ssa.css
- config: tool_param_constraints.json (new)
- docs: SSA status doc, team review reports

Tested: Cohort study end-to-end execution + report export verified
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-24 13:08:29 +08:00

402 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SSA智能统计分析模块 - 当前状态与开发指南
> **文档版本：** v3.5
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-23
> **维护者：** 开发团队
> **当前状态：** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A（分析方案变量可编辑化）开发完成**
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
>
> **最新进展（2026-02-23 Phase V-A 变量可编辑化完成）：**
> - ✅ **分析方案变量可编辑化** — 系统默认帮选变量，医生可在方案审查阶段修改/调整变量选择
> - ✅ **三层柔性拦截** — Layer 1 即时黄条警告 + Layer 2 步骤警告图标 + Layer 3 执行前阻断确认弹窗（Informed Consent）
> - ✅ **变量选择器 UI** — 单选下拉（按类型分组）+ 多选标签（分类=紫色 / 连续=蓝色）+ 全选分类/连续快捷按钮 + 不适配变量 ⚠️ 标记
> - ✅ **tool_param_constraints 配置** — 12 个统计工具参数约束表，前后端共用单一事实来源
> - ✅ **后端 PATCH API + Zod 防火墙** — PATCH /workflow/:id/params + 结构校验（400 Bad Request）/ 统计学校验交给 R 引擎
> - ✅ **同步阻塞执行** — 执行按钮 Promise Chaining：await PATCH -> 再触发执行 + loading 防连点
> - ✅ **inferGroupingVar 恢复** — LLM 未识别分组变量时，自动推断二分类变量填入默认值
> - ✅ **DynamicReport 增强** — 兼容 R 基线表对象格式 rows，Word 导出同步修复
> - ✅ **前后端集成测试通过** — 队列研究完整执行 + 报告导出验证
>
> **此前进展（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 引擎防御、意图识别、前端状态）
> - ✅ **统一状态管理重构** — 消除 isWorkflowMode 双轨逻辑，AnalysisRecord 成为唯一数据源
> - ✅ **多任务切换** — 点击不同卡片正确显示各自的分析计划和结果
> - ✅ **R 代码完整性** — 多步骤分析的所有步骤代码均可下载/复制
---
## 📊 模块概览
### 基本信息
| 项目 | 信息 |
|------|------|
| **模块名称** | SSA - 智能统计分析 (Smart Statistical Analysis) |
| **模块定位** | AI驱动的"白盒"统计分析系统 → 升级为"数据感知的统计顾问" |
| **架构模式** | **QPER（执行层）** + **四层七工具 + 对话层 LLM（智能对话层）** |
| **前端状态模型** | **Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps** |
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
| **目标用户** | 临床研究人员、生物统计师 |
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A（变量可编辑化）完成** |
### 核心目标
> 让**不懂统计的医生**完成**专业级的统计分析**。
>
> **三大特征**：
> 1. **白盒**：用户完全理解 AI 做了什么，为什么这样做
> 2. **严谨**：统计护栏自动检测前提条件，违规时自动降级
> 3. **可交付**：生成论文级结论 + 可在本地运行的 R 代码，支持审计复现
---
## 🏗️ QPER 四层架构
```
用户："比较两组血压有没有差别"
│
▼
┌─ Q · Query ─────────────────────────────────────┐
│ LLM 意图解析 + Zod 动态防幻觉 + 追问卡片 │
│ 输出：ParsedQuery { goal, y, x, design } │
└──────────────────────┬──────────────────────────┘
▼
┌─ P · Planner ────────────────────────────────────┐
│ 决策表四维匹配 + 流程模板填充 + EPV 防护 │
│ 输出：WorkflowPlan + PlannedTrace │
└──────────────────────┬──────────────────────────┘
▼
┌─ E · Execute ────────────────────────────────────┐
│ R 引擎执行 + SSE 实时进度 + Block-based 输出 │
│ 输出：StepResult[] + ReportBlock[] │
└──────────────────────┬──────────────────────────┘
▼
┌─ R · Reflection ─────────────────────────────────┐
│ LLM 论文级结论 + 槽位注入 + Zod 校验 │
│ 输出：ConclusionReport（6 要素） │
└──────────────────────────────────────────────────┘
```
### 降级体系
| 层 | 正常路径 | 降级路径 | 触发条件 |
|----|---------|---------|---------|
| Q | QueryService（LLM） | 正则匹配 fallback | LLM 超时/不可用 |
| P | DecisionTable + FlowTemplate | 硬编码 if/else | 决策表无匹配 |
| E | R 引擎 | 错误分类→友好提示 | R 运行时崩溃 |
| R | ReflectionService（LLM） | ConclusionGeneratorService（规则拼接） | LLM 失败/Zod 校验失败 |
---
## 🎨 前端架构：统一状态管理
> **2026-02-21 重构完成** — 消除 isWorkflowMode 双轨逻辑
### 数据模型
```typescript
AnalysisRecord {
id: string; // = workflowId or generated
query: string; // 用户原始问题
createdAt: string;
status: 'planning' | 'executing' | 'completed' | 'error';
plan: WorkflowPlan | null; // 统一用 WorkflowPlan（单步也是 1 步的 Plan）
steps: WorkflowStepResult[]; // 统一用步骤数组
progress: number; // 0-100
conclusionReport: ConclusionReport | null;
}
```
### Store 结构
- `analysisHistory: AnalysisRecord[]` — 所有分析记录
- `currentRecordId: string | null` — 当前激活的记录
- 派生：`currentRecord = analysisHistory.find(r => r.id === currentRecordId)`
- 操作：`addRecord(query, plan)` / `updateRecord(id, patch)` / `selectRecord(id)`
### 已删除的全局字段
`currentPlan`、`executionResult`、`traceSteps`、`workflowPlan`、`workflowSteps`、`workflowProgress`、`conclusionReport`、`isWorkflowMode` 及所有对应 setter。
---
## 📋 开发进度
| Phase | 任务 | 工时 | 状态 | 完成日期 |
|-------|------|------|------|---------|
| Phase 0 | 需求分析与架构设计 | - | ✅ 已完成 | 2026-02-18 |
| Phase 1 | 骨架搭建（T 检验端到端） | - | ✅ 已完成 | 2026-02-19 |
| Phase 1.5 | V11 UI 前后端联调 | - | ✅ 已完成 | 2026-02-20 |
| Phase 2A | 多步骤工作流 + 前端集成 | - | ✅ 已完成 | 2026-02-20 |
| **Phase E+** | **Block-based 标准化** | **15.5h** | ✅ **已完成** | 2026-02-20 |
| **Phase Q** | **LLM 意图理解** | **33h** | ✅ **已完成** | 2026-02-21 |
| **Phase P** | **决策表 + 流程模板** | **23h** | ✅ **已完成** | 2026-02-21 |
| **Phase R** | **LLM 论文级结论** | **22h** | ✅ **已完成** | 2026-02-21 |
| **集成测试** | **Bug 修复 + 统一状态管理重构** | **~4h** | ✅ **已完成** | 2026-02-21 |
| **架构设计** | **智能对话与工具体系架构设计** | **~8h** | ✅ **已完成** | 2026-02-22 |
| 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-A** | **分析方案变量可编辑化** | **~6h** | ✅ **已完成（9 文件, 团队双视角审查 V2, 三层柔性拦截）** | 2026-02-23 |
| **Phase V-B** | **反思编排 + 高级特性** | **18h** | 📋 待开始 | - |
| **Phase VI** | **集成测试 + 可观测性** | **10h** | 📋 待开始 | - |
### 已完成核心功能
| 组件 | 完成项 | 状态 |
|------|--------|------|
| **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 解析 + 正态性检验 + 单变量详情 | ✅ |
| **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） | ✅ |
| **Phase V-A 后端** | PATCH /workflow/:id/params（Zod 结构校验防火墙）+ tool_param_constraints.json（12 工具参数约束）+ inferGroupingVar 恢复（默认填充分组变量） | ✅ |
| **Phase V-A 前端** | WorkflowTimeline 可编辑化（SingleVarSelect + MultiVarTags + 三层柔性拦截）+ ssaStore updateStepParams + SSAWorkspacePane 同步阻塞执行 + DynamicReport 对象 rows 兼容 + Word 导出修复 | ✅ |
| **测试** | 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 前后端集成测试通过 | ✅ |
---
## 📂 代码目录结构
```
backend/src/modules/ssa/
├── services/
│ ├── QueryService.ts # Q 层：LLM 意图解析
│ ├── DecisionTableService.ts # P 层：四维匹配
│ ├── FlowTemplateService.ts # P 层：流程模板
│ ├── WorkflowPlannerService.ts # P 层：核心规划入口
│ ├── WorkflowExecutorService.ts # E 层：步骤编排 + SSE
│ ├── RClientService.ts # E 层：R 引擎调用
│ ├── ReflectionService.ts # R 层：LLM 结论生成
│ ├── ConclusionGeneratorService.ts # R 层 fallback
│ ├── 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 工具注册表
│ ├── decision_tables.json # 四维匹配规则
│ ├── flow_templates.json # 流程模板
│ └── tool_param_constraints.json # Phase V-A：12 工具参数类型约束
├── types/
│ ├── query.types.ts # Q 层接口
│ ├── 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
└── ...
frontend-v2/src/modules/ssa/
├── stores/
│ └── ssaStore.ts # Zustand — Unified Record Architecture
├── hooks/
│ ├── useWorkflow.ts # 工作流 Hook（addRecord/updateRecord）
│ └── useAnalysis.ts # 上传/Legacy 兼容
├── components/
│ ├── SSAChatPane.tsx # 对话区（卡片 → selectRecord）
│ ├── SSAWorkspacePane.tsx # 工作区（基于 currentRecord 渲染）
│ ├── SSACodeModal.tsx # R 代码模态框（从 record.steps 聚合）
│ ├── WorkflowTimeline.tsx # 执行计划时间线
│ ├── DynamicReport.tsx # Block-based 结果渲染
│ ├── DataContextCard.tsx # Phase I：五段式数据概览卡片
│ ├── VariableDictionaryPanel.tsx # Phase I：变量字典表格（可编辑）
│ └── VariableDetailPanel.tsx # Phase I：单变量详情面板
└── types/
└── index.ts # 前端类型定义
r-statistics-service/
├── plumber.R # API 入口（含参数日志）
└── tools/
└── descriptive.R # 描述性统计（NA 安全防御）
```
---
## 🔧 开发环境
### 启动服务
```bash
# 1. 数据库（Docker）
docker start ai-clinical-postgres
# 2. Python 服务
cd extraction_service && python main.py
# 3. R 服务
cd r-statistics-service && Rscript plumber_api.R
# 4. Node.js 后端
cd backend && npm run dev
# 5. 前端
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 种子（需数据库运行）
```bash
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
```
---
## 📚 相关文档
| 文档 | 路径 |
|------|------|
| **QPER 开发计划（主线）** | `04-开发计划/10-QPER架构开发计划-智能化主线.md` |
| **🆕 智能对话与工具体系开发计划** | `04-开发计划/11-智能对话与工具体系开发计划.md` |
| **🆕 意图识别与对话架构设计** | `00-系统设计/SSA-Pro 意图识别与对话架构设计.md` |
| **🆕 工具体系规划方案（融合方案）** | `00-系统设计/SSA-Pro 工具体系规划方案（团队讨论稿）.md` |
| **🆕 四层七工具实现机制详解** | `00-系统设计/SSA-Pro 四层七工具实现机制详解.md` |
| **QPER 开发总结** | `06-开发记录/SSA-QPER架构开发总结-2026-02-21.md` |
| **集成测试 Bug 修复** | `06-开发记录/2026-02-21-集成测试Bug修复与统一状态管理重构.md` |
| **智能化愿景设计** | `00-系统设计/SSA-Pro 理想状态与智能化愿景设计.md` |
| **PRD** | `00-系统设计/PRA SSA-Pro 严谨型智能统计分析模块.md` |
| **架构设计 V4** | `00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md` |
---
## 🎯 下一步
### 近期（优先级高）
1. **Phase V-B — 反思编排 + 高级特性（18h / 3 天）**
- 错误分类器实现（可自愈 vs 不可自愈）
- 自动反思（静默重试，MAX 2 次）+ 手动反思（用户驱动，feedback 意图）
- write_report interpret 模式 + discuss 意图处理（深度解读已有结果）
2. **Phase Deploy 收尾** — 前端三线表增强、决策表/流程模板补齐、ACR/SAE 部署
### 中期
3. **Phase VI（10h）** — 集成测试 + 可观测性（含 QPER 透明化）
**详细计划：** `04-开发计划/11-智能对话与工具体系开发计划.md`（v1.8，Phase I-IV + Phase V-A 完成，含架构约束 C1-C8 + 全部团队审查落地记录）
---
## 🏗️ 智能对话架构概览（四层七工具 + 对话层 LLM）
> **设计目标：** 从"统计分析执行器"升级为"数据感知的统计顾问"
```
用户消息
│
▼
┌─ Intent Router ──────────────────────────────────────┐
│ 规则引擎优先 + LLM 兜底 + 上下文守卫（§16.5） │
│ → chat / explore / consult / analyze / discuss / feedback │
└─────────────────────┬────────────────────────────────┘
▼
┌─ Conversation Layer LLM ─────────────────────────────┐
│ 六段式 System Prompt + DataContext 注入 + 流式输出 │
│ Token 预算 ≤4000（§16.2）+ 禁止 Function Calling（§16.1）│
└─────────────────────┬────────────────────────────────┘
▼
┌─ 四层七工具 ─────────────────────────────────────────┐
│ READ: get_data_overview | get_variable_detail | method_consult │
│ INTERACT: ask_user │
│ THINK: analysis_plan │
│ ACT: run_step | write_report │
└─────────────────────┬────────────────────────────────┘
▼
┌─ QPER 执行层（已有） ────────────────────────────────┐
│ Q → P → E → R（四层降级体系，不动） │
└──────────────────────────────────────────────────────┘
```
**关键架构约束（详见开发计划 §16-§17）：**
| # | 约束 |
|---|------|
| C1 | 对话层 LLM 禁止 Function Calling tools 参数 |
| C4 | Session 黑板使用 CacheFactory（Postgres-Only，无 Redis） |
| C5 | 数据依赖意图必须有上下文守卫 |
| C6 | LLM 枚举输出必须 Zod 动态校验 |
---
**文档版本：** v3.5
**最后更新：** 2026-02-23
**当前状态：** 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A（变量可编辑化）已完成
**下一步：** Phase V-B（反思编排 + 高级特性，18h/3 天）
Reference in New Issue View Git Blame Copy Permalink