HaHafeng
bf10dec4c8
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>
88 lines
6.8 KiB
Markdown
88 lines
6.8 KiB
Markdown
# **架构委员会独立审查报告：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，只暴露其完成当前任务所必需的最小工具集。** |