HaHafeng
8137e3cde2
Summary: - Add PRD and architecture design V4 (Brain-Hand model) - Complete 5 development guide documents - Pass 3 rounds of team review (v1.0 -> v1.3) - Add module status guide document - Update system status document Key Features: - Brain-Hand architecture: Node.js + R Docker - Statistical guardrails with auto degradation - HITL workflow: PlanCard -> ExecutionTrace -> ResultCard - Mixed data protocol: inline vs OSS - Reproducible R code delivery MVP Scope: 10 statistical tools Status: Design 100%, ready for development Co-authored-by: Cursor <cursoragent@cursor.com>
200 lines
8.6 KiB
Markdown
200 lines
8.6 KiB
Markdown
# **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 流式输出，减少用户等待的焦虑感。 |