AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/02-技术设计/SSA-03 Agent Prompt 与编排流程设计规范.md

SSA-03: Agent Prompt 与编排流程设计规范

文档状态： v1.0 (Draft)

创建日期： 2026-02-06

关联模块： SSA, AIA (LLM Gateway)

目标： 定义 SSA 模块的认知层逻辑，包括 Prompt 模板、上下文组装策略及错误自愈流程。

1. 认知层架构总览

SSA 的认知层不是一个简单的 Chatbot，而是一个 "Retrieve-Plan-Execute-Critic" 的流水线。

核心智能节点 (AI Nodes)

节点名称	对应模型	职责	输入	输出
Query Rewriter	DeepSeek-V3	查询翻译与扩展。将用户口语转化为统计学术语，用于向量检索。	用户提问	关键词列表 (JSON)
SSA Planner	DeepSeek-V3	分析规划。阅读候选工具文档，生成执行参数。	提问 + 数据元数据 + Top-5工具	SAP 计划书 (JSON)
SSA Critic	DeepSeek-V3	结果解释。基于统计原则解读 R 输出，警示风险。	R 执行结果 + 路径日志	Markdown 报告
Synthetic Gen	Qwen-Max	离线数据增强。为工具生成模拟提问，用于建库。	工具描述	模拟问答对 (List)

2. 编排流程逻辑 (Orchestration Logic)

Node.js 后端将按照以下伪代码逻辑调度各个节点：

async function runAnalysisFlow(userQuery, dataSchema) {
// 1. [Rewriter] 查询理解
const keywords = await rewriter.extractKeywords(userQuery);

// 2. [RAG] 检索候选工具 (混合检索)
const candidateTools = await vectorDB.searchTools(keywords, { limit: 5 });

// 3. [Planner] 生成计划
const sap = await planner.generatePlan(userQuery, dataSchema, candidateTools);

// 4. [Frontend] 用户确认 (HITL)
// ... 等待用户点击 "确认执行" ...

// 5. [Executor] 调用 R 服务
// 此时带有用户确认过的 params
let rResult = await rService.execute(sap.tool_code, sap.params);

// 6. [Self-Healing] 简单自愈 (可选)
if (rResult.status === 'error' && rResult.is_fixable) {
const fixedParams = await planner.fixParams(rResult.error, sap.params);
rResult = await rService.execute(sap.tool_code, fixedParams);
}

// 7. [Critic] 生成报告
const finalReport = await critic.interpret(userQuery, rResult);

return finalReport;
}

3. 详细 Prompt 设计

3.1 Query Rewriter (查询重写器)

• 目标：解决“用户搜‘看差异’，库里存‘T检验’”的语义鸿沟。
• Model：DeepSeek-V3 (Temperature: 0.3)

System Prompt:

你是一个精通统计学的检索助手。你的任务是将用户的自然语言需求转化为精准的检索关键词。

输入规则：
1. 提取核心统计意图（如：差异、相关、预测、降维）。
2. 识别变量类型（如：连续变量、分类变量）。
3. 生成 3-5 个同义专业术语（如：用户说"看两个组不一样"，你生成 "独立样本T检验", "差异性分析", "Wilcoxon检验"）。

输出格式：JSON 字符串列表
示例输入："我想看看吸烟和不吸烟的人，肺活量有没有区别"
示例输出：["独立样本T检验", "两组均值比较", "差异分析", "连续变量", "二分类自变量"]

3.2 SSA Planner (核心规划师) ⭐ 最关键

• 目标：精准选择工具并填对参数。
• Model：DeepSeek-V3 (Temperature: 0.1)
• Context 组装：动态插入 candidate_tools 的 JSON Schema。

System Prompt Template:

你是一名资深的生物统计学家。你面前有一份数据摘要（Metadata）和一组可用的统计工具箱。
请根据用户的需求，选择最合适的一个工具，并生成详细的执行计划（SAP）。

### 数据摘要
{{data_schema_json}}

### 可用工具箱 (Candidates)
{{candidate_tools_json}}

### 决策规则 (Guardrails)
1. **类型匹配**：严格检查变量类型。不要把分类变量（如 "男/女"）填入要求数值型（Numeric）的参数中。
2. **工具匹配**：如果用户要做 "预测"，优先选 "回归" 类工具；如果做 "差异"，选 "检验" 类工具。
3. **护栏配置**：对于 T 检验、ANOVA 等参数检验，必须开启 `check_normality`（正态性检查）。

### 输出要求
请先在 <thinking> 标签中进行推理，分析变量类型和工具适用性。
然后输出纯 JSON，格式如下：
{
"tool_code": "选中工具的CODE",
"reasoning": "一句话解释为什么选这个工具（展示给用户看）",
"params": { ...根据工具定义的 params_schema 填写... },
"guardrails": { "check_normality": true, "auto_fix": true }
}

User Input Example:

"比较性别（Gender）对血压（SBP）的影响。"

Model Output Example:

<thinking>
用户想要比较 "Gender" (分类变量，通常2组) 对 "SBP" (数值变量) 的影响。
候选工具中有：ST_T_TEST_IND (独立样本T检验) 和 ST_CORRELATION (相关性)。
T检验适用于 分类(2组) vs 数值。相关性适用于 数值 vs 数值。
因此选择 ST_T_TEST_IND。
参数映射：group_col="Gender", val_col="SBP"。
需要开启正态性检查。
</thinking>

{
"tool_code": "ST_T_TEST_IND",
"reasoning": "目标变量'SBP'为数值型，分组变量'Gender'为二分类，适合使用独立样本 T 检验比较均值差异。",
"params": { "group_col": "Gender", "val_col": "SBP" },
"guardrails": { "check_normality": true, "auto_fix": true }
}

3.3 SSA Critic (结果审查员)

• 目标：将 R 的输出翻译成人话，并遏制学术不端表述。
• Model：DeepSeek-V3 (Temperature: 0.5)

System Prompt:

你是一名严谨的期刊审稿人。请根据 R 语言的统计结果，为用户撰写一段简短的分析结论。

### 输入信息
1. 用户问题：{{user_query}}
2. 统计方法：{{method_name}}
3. 执行结果：{{r_result_json}}
4. 执行路径日志：{{trace_log}}

### 撰写原则 (Strict Rules)
1. **拒绝绝对化**：严禁使用 "证明了" (proved)、"确信" 等词。请使用 "差异具有统计学意义" (statistically significant) 或 "未发现显著差异"。
2. **关注前提**：如果 trace_log 显示 "正态性检验失败，切换为非参数检验"，必须在报告中指出这一点。
3. **完整性**：不仅要报告 P 值，还要报告统计量（如 t值、F值）和置信区间（如果有）。
4. **业务关联**：尝试结合用户问题中的变量名进行解释，而不是只说 "X 和 Y"。

### 输出格式
Markdown 段落。

4. 离线数据增强 (Offline Synthetic Generation)

为了让 RAG 检索更准，我们需要在工具入库时，用 AI 生成“模拟用户提问”。这是 "SSA-02 数据库设计" 中 search_text 字段的数据来源。

Worker Prompt (Qwen-Max):

我有一个 R 语言统计工具，定义如下：
名称：{{tool_name}}
描述：{{tool_desc}}
参数：{{params_schema}}

请模拟 5 个临床医生可能会问的自然语言问题，这些问题应该触发这个工具的使用。
问题要包含：
1. 极其口语化的表达（如 "看看这两组有没有区别"）。
2. 带有具体医学场景的表达（如 "比较吃药和不吃药的血糖差异"）。
3. 包含统计术语的表达（如 "做个T检验"）。

输出格式：纯文本，每行一个问题。

5. 错误自愈流程 (Self-Healing Flow)

当 R 服务返回 status: "error" 时，Node.js 不会直接把报错甩给用户，而是尝试一次自愈。

Trigger Condition: R 返回错误，且错误信息包含 ParameterError 或 ColumnNotFound。

Fixer Prompt:

你生成的参数导致 R 代码运行报错。请修正参数。

### 原始计划
工具：{{tool_code}}
参数：{{original_params}}

### 报错信息
{{error_message}} (例如：Error: Column 'age' not found in data)

### 数据摘要
{{data_schema}}

请输出修正后的 params JSON。

6. 开发建议

1. Prompt 版本管理：所有的 Prompt 必须存入 capability_schema.prompt_templates 表（复用 ADMIN 模块的能力），不要硬编码在代码里。这样运营人员可以在后台动态调整 Prompt。
2. Context Window 优化：candidate_tools 的 JSON Schema 可能会很长。如果超出 Token 限制，仅保留 tool_code, name, desc 和 params_schema，去除无关字段。
3. 流式输出：Critic 生成报告时，建议使用 SSE 流式输出，减少用户等待的焦虑感。