AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/06-开发记录/J技术报告审核评估与建议/SSA-Pro 智能体边界与工具生态规划报告.md

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