docs(ssa): Complete intelligent dialogue and tool system architecture design
Architecture Design: - Add intent recognition and dialogue architecture design (Intent Router + DataContext) - Add tool system planning (4-layer 7-tool fusion solution: READ/INTERACT/THINK/ACT) - Add 4-layer 7-tool implementation mechanism details (Conversation Layer LLM + Node.js orchestration) Development Plan (v1.2): - Create 6-phase development plan (134h/22 days) for intelligent dialogue system - Add 8 architectural constraints (C1-C8): no Function Calling, Postgres-Only cache, streaming output, context guard, Zod dynamic validation - Correct Session Blackboard to use CacheFactory (Postgres-Only, no Redis) Status Updates: - Update SSA module status: QPER complete + dialogue architecture design complete - Update system-level status: add SSA architecture design milestone Other: - R tools minor fixes (chi_square, correlation, logistic_binary, mann_whitney, t_test_paired) - Frontend AIA chat workspace style adjustment Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,75 @@
|
||||
# **架构委员会审查报告：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 结构设计**，这是本周最核心的基础设施。
|
||||
|
||||
你们正在打造一个极具壁垒的“医疗级数据分析系统”，放手去干吧！
|
||||
@@ -0,0 +1,88 @@
|
||||
# **架构委员会独立审查报告：SSA-Pro 智能体边界与工具生态规划**
|
||||
|
||||
**审查对象：** SSA-Pro 核心工具的定义与扩展规划
|
||||
|
||||
**审查时间：** 2026-02-21
|
||||
|
||||
**核心洞察：** 区分“认知节点 (Cognitive Nodes)”与“物理工具 (Physical Tools)”，避免让大模型陷入“左脚踩右脚”的逻辑死锁。
|
||||
|
||||
## **一、 核心诊断：你给出的 7 个定义，到底是“工具”还是“智能体”？**
|
||||
|
||||
你提出的 7 个维度非常完整地覆盖了统计分析的全生命周期。但我对这 7 个定义的架构定性如下：
|
||||
|
||||
| 用户提出的名称 | 架构师的定性 | 为什么？(底层逻辑) |
|
||||
| :---- | :---- | :---- |
|
||||
| (1) PICO 需求梳理 | 🧠 **智能体 (Agent/Prompt)** | 这不需要调用外部系统，纯靠 LLM 内置知识和特定的 Prompt 引导用户对话即可完成。 |
|
||||
| (2) 数据总览与变量 | 🛠️ **物理工具 (Tool)** | LLM 算不出缺失率，它必须通过调用 get\_data\_profile() API（即 Python Tool C）来获取真实数据特征。 |
|
||||
| (3) 高水平分析计划 | 🧠 **智能体 (Agent/Prompt)** | 这是纯逻辑推理，是 Planner Agent 的核心输出物。 |
|
||||
| (4) 统计方法匹配规划 | 🧠 **智能体 \+ 规则引擎** | 这是大模型基于数据特征去匹配配置表（决策树）的过程。 |
|
||||
| (5) 分析执行 (调用R) | 🛠️ **物理工具 (Tool)** | 这是最经典的动作，LLM 调用 run\_r\_script(params) 来改变外部世界。 |
|
||||
| (6) 报告生成与解读 | 🧠 **智能体 (Agent/Prompt)** | 这是 Critic Agent 拿到数字后进行的文本翻译工作。 |
|
||||
| (7) 反思与重执行 | 🔄 **系统编排机制 (Workflow)** | 这是一个系统级的 while 循环，将 Error Log 喂给 LLM 重新生成参数，而不是一个具体的“工具”。 |
|
||||
|
||||
**💡 架构师的黄金法则：**
|
||||
|
||||
* **工具 (Tools)** 是 LLM 的\*\*“手和眼睛”\*\*。只有当 LLM 需要获取外部信息（看数据）、或改变外部世界（跑代码）时，才定义为 Tool。
|
||||
* **智能体 (Agents)** 是 LLM 的\*\*“大脑”\*\*。思考、规划、写文章、做匹配，这些都是靠切换 System Prompt 就能完成的，绝对不要把它们封装成所谓的“推理工具”让 LLM 自己调自己，这会浪费极大的上下文并导致不可控。
|
||||
|
||||
## **二、 重新梳理：3 种工具规划与定义范式 (供团队讨论)**
|
||||
|
||||
基于上述理念，如果你想“精心规划工具的选择和使用”，我们在架构上有以下 3 种范式可供讨论。我强烈建议采用 **范式 C**。
|
||||
|
||||
### **❌ 范式 A：“上帝工具”模式 (The Monolithic Tool)**
|
||||
|
||||
* **设计思路**：给 LLM 提供一个巨大的工具 run\_full\_statistics(goal, data\_id, x\_vars, y\_vars, need\_baseline, need\_plot...)。
|
||||
* **优点**：LLM 只需要调用一次工具。
|
||||
* **致命缺点**：大模型的“注意力分散”。让 LLM 一次性填对包含几十个参数的巨型 JSON 几乎是不可能的。中间一旦报错，完全无法定位是哪一步错了，直接黑盒。
|
||||
|
||||
### **🟡 范式 B：“原子工具箱”模式 (The Micro-Tools Box)**
|
||||
|
||||
* **设计思路**：我们手里有 100 个 R 脚本，就直接注册 100 个工具（如 t\_test, anova, km\_curve, cox\_regression）。
|
||||
* **优点**：颗粒度极细，非常灵活。
|
||||
* **致命缺点**：大模型选错工具的概率激增。你很难通过 System Prompt 讲清楚这 100 个工具的区别。同时，大模型不擅长做复杂的代码控制流（比如：如果正态，调用工具 A；如果不正态，调用工具 B），这会导致极高的 Token 消耗和幻觉。
|
||||
|
||||
### **🌟 范式 C：“宏观指令与物理探针”模式 (The Macro & Probe Paradigm) \-\> 推荐！**
|
||||
|
||||
**这是最符合你“精心规划”理念的架构，也是我们 SSA-Pro QPER 的最佳实践。** 我们把交给 LLM 的工具极度压缩为**三类**（甚至少于 5 个具体的 Function）：
|
||||
|
||||
#### **1\. 探针类工具 (Probe Tools) \- 充当 LLM 的眼睛**
|
||||
|
||||
当 LLM 处于 Q 层（需求梳理期）时，它只有这两个工具可用：
|
||||
|
||||
* get\_data\_schema(file\_id): 获取表头和列类型。
|
||||
* get\_column\_details(file\_id, column\_name): 深入查看某一列的具体分布（解决大文件 Token 爆炸的问题，按需查看）。
|
||||
|
||||
#### **2\. 交互类工具 (Human-in-the-loop Tools) \- 充当 LLM 的嘴巴**
|
||||
|
||||
当 LLM 觉得需求模糊时，**不要让它自己瞎猜**，强迫它调用交互工具：
|
||||
|
||||
* ask\_user\_clarification(question, options\_array): LLM 调用此工具后，前端会渲染出一个漂亮的“单选卡片”让用户点击，而不是一串干巴巴的文字。
|
||||
|
||||
#### **3\. 宏观调度工具 (Macro-Execution Tools) \- 充当 LLM 的手**
|
||||
|
||||
当进入 E 层（执行期）时，LLM **不直接调用具体的 100 个原子工具**。它只调用一个统一的超级路由器：
|
||||
|
||||
* execute\_statistical\_pipeline(pipeline\_id, parameter\_map)
|
||||
* **说明**：pipeline\_id 就是我们配置中心的“套餐 ID”（如：经典队列研究套餐）。LLM 的工作是“根据用户的需求，把正确的变量名（X, Y, Confounders）塞进这个套餐的插槽里”。具体的“T检验还是秩和检验”，是由后台 R 脚本内部的护栏去动态决定的。
|
||||
|
||||
## **三、 对你的三个问题的直接回答与行动建议**
|
||||
|
||||
**(1) 如何规划好工具，你有什么想法？**
|
||||
|
||||
* **减法思维**：限制 LLM 能看到的工具数量。不要把 100 个 R 脚本同时暴露给 LLM，这会引发选择困难症。
|
||||
* **使用 RAG 进行工具检索**：如果非要暴露 100 个工具，请在 LLM 规划前，先用 pgvector（向量库）根据用户的对话，**检索出最相关的 Top-5 工具**。然后只把这 5 个工具的 JSON Schema 塞进 LLM 的上下文。这是目前解决“工具过载”唯一成熟的工业方案。
|
||||
|
||||
**(2) 对于你给出的工具规划和定义有什么建议？**
|
||||
|
||||
* 你的分类是对\*\*“产品功能矩阵”\*\*的完美分类，可以直接拿来画产品架构图和商业 BP。
|
||||
* 但在写代码时，请一定要把它们转化为 **Agent (专门的 Prompt) \+ Workflow (Node.js 编排) \+ API (真实的 Tool)** 三者的结合体。
|
||||
|
||||
**(3) 梳理后的下一步行动建议**
|
||||
|
||||
按照 **范式 C**，我们在代码层面需要做的其实是“分身术（Multi-Agent）”：
|
||||
|
||||
1. **建立 咨询 Agent**：它只有看数据的工具，没有执行计算的工具。它专心做 PICO 梳理和 SAP 计划生成。
|
||||
2. **建立 执行 Agent**：它只能看到 Top-5 的候选工具，职责极其单一，就是把变量名填到这些工具的参数里。
|
||||
3. **建立 反思 Agent**：它不调用任何工具，它只接收 R 报错的字符串，输出修正后的参数 JSON。
|
||||
|
||||
**总结：** 精心规划工具的最高境界，不是造很多工具，而是**在不同的阶段，向不同的 Agent，只暴露其完成当前任务所必需的最小工具集。**
|
||||
Reference in New Issue
Block a user