# **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 流式输出，减少用户等待的焦虑感。