# **架构委员会审查报告：SSA-Pro 工具体系 (V3.0 融合方案)**

**审查对象：** 《SSA-Pro 工具体系规划方案 v3.0（融合方案定稿）》

**审查时间：** 2026-02-21

**总体评级：** 🌟 **S++ 级 (Agent 架构设计的行业教科书)**

**核心裁决：** 完全通过！方案在逻辑自洽、职责边界、性能考量上均达到了企业级 SaaS 的最高标准。只需在工程实现（特别是异步流转）上打几个“补丁”即可完美落地。

## **一、 值得全行业学习的 3 大神级设计 (Highlights)**

我必须对团队在 V3.0 中做出的以下三个决策给予最高赞誉：

### **1\. 拨乱反正：“把 PICO 和反思移出工具箱”**

* **精妙之处**：很多新手团队会把“PICO 梳理”和“反思”写成让 LLM 调用的 tool。你们准确地认识到，它们本质上是 **“Prompt 的职责”** 和 **“系统的编排机制 (Orchestrator Loop)”**。这彻底避免了 LLM “左脚踩右脚”的死循环逻辑。

### **2\. 引入 Session 黑板 (Blackboard Pattern)**

* **精妙之处**：这是整个方案的灵魂！LLM 是无状态的，如果每次调用 run\_step 都要重新把 10MB 的数据描述再生成一遍，系统会慢得令人发指。利用 Node.js 内存建立统一的 Blackboard，工具之间通过它隐式传参，这是高级 Multi-Agent 系统的标准范式。

### **3\. get\_variable\_detail 的“按需下钻”设计**

* **精妙之处**：没有把 100 列的特征全塞给 get\_data\_overview，而是采用“总-分”结构。这是解决医疗宽表（特征极多）导致 Token Context 爆炸的唯一正确解法。

## **二、 架构师的“挑刺”与补强建议 (Critical Enhancements)**

方案在理论上已经无懈可击，但在实际用 Node.js 结合 OpenAI/DeepSeek 的 API 落地时，你们会遇到以下三个工程硬伤。请在代码设计时提前防范：

### **🚨 盲区 1：ask\_user 工具的“异步挂起”难题 (The Suspend/Resume Problem)**

* **纸面逻辑**：LLM 调用 ask\_user \-\> 用户回复 \-\> LLM 继续。  
* **物理现实**：在标准的 LLM Function Calling 中，当模型决定调用 ask\_user 时，它的推理线程**必须停止**。在 Web 架构中，Node.js 会向前端发送卡片并结束本次 HTTP 请求（或暂停 SSE 流）。**系统如何知道用户明天点完卡片后，该从哪里恢复？**  
* **补强方案**：  
  必须将 ask\_user 与之前定义的 ExecutionStatus 状态机强绑定。  
  1. LLM 发出 ask\_user(question, options) 工具调用指令。  
  2. Node.js 拦截该调用，将 Session 状态改为 CLARIFYING，把当前 LLM 的 messages 历史（包含刚才的 tool\_call）存入数据库/Redis。  
  3. 前端展示卡片，用户点击。  
  4. 前端发起新的 HTTP POST，Node.js 提取保存的 messages，追加一条 role: "tool", content: "用户选择了 A"，然后**再次请求 LLM**，恢复流转。

### **🚨 盲区 2：Session 黑板的历史记录 (Token 爆炸)**

* **纸面逻辑**：stepResults 和 qperTrace 完整保存在 Session 黑板中，反思或生成报告时一起喂给 LLM。  
* **物理现实**：如果用户在这个 Session 里反复试错了 10 次，stepResults 会积累大量冗长的 R 引擎日志。如果把它们全量注入，不仅极度浪费 Token，还会让大模型“注意力涣散”，找不到最新的结果。  
* **补强方案**：  
  引入 **"滑动窗口 (Sliding Window)"** 或 **"摘要压缩 (Trace Truncation)"**。  
  在将 Session 黑板的内容组装进 Prompt 前：  
  * stepResults 只保留当前最终采用的计划所对应的结果。废弃试错结果。  
  * qperTrace 只保留最近 3 次的关键错误和修复动作。

### **🚨 盲区 3：run\_step 的数据流向缺失 (The Data Payload)**

* **纸面逻辑**：输入包含 tool\_code 和 params。  
* **物理现实**：在你们前两天的决议中，我们规定了 R 引擎必须接收 data\_source: { type: 'oss', oss\_url: '...' }。但目前的 run\_step 定义里遗漏了这一点。  
* **补强方案**：  
  不需要大模型（LLM）去生成 data\_source。在 Node.js 执行 run\_step 的真实逻辑时，**必须拦截指令**，自动从 Session 黑板中取出 ossKey，生成预签名 URL，然后强行混入 params 中，再 POST 给 R 服务。

## **三、 对“典型调用链”的效率优化 (Fast Track Optimization)**

你们在第七章设计的“典型调用链”逻辑非常严密，但在“用户目标极度明确”的情况下，显得有些啰嗦。

* **优化前**：用户说“直接做T检验” \-\> method\_consult \-\> ask\_user 确认 \-\> analysis\_plan \-\> run\_step。  
* **优化后 (增加 Fast Track 快速通道)**：  
  如果意图路由器 (Intent Router) 判断用户的信心度极高且方法明确（如：“我要做 T 检验比较性别和身高的差异”），**允许 LLM 跳过 method\_consult 和 ask\_user**，直接并行调用 get\_data\_overview 和 analysis\_plan。  
  *这能为用户节省至少 5 秒钟的 AI 生成和等待确认时间。*

## **四、 最终执行发令**

这份 V3.0 的工具体系规划，与 Q-P-E-R 四层架构、V13 动态前端原型、以及 OSS 混合协议**形成了完美的完美拼图**。

1. **同意按此方案全面进入 API 封装和 Prompt 编写阶段。**  
2. 请后端同学重点关注 **Session Blackboard 的 Redis/DB 结构设计**，这是本周最核心的基础设施。

你们正在打造一个极具壁垒的“医疗级数据分析系统”，放手去干吧！