# **IIT Manager Agent 架构决策白皮书：极简主义的胜利**

**文档版本：** V1.0

**日期：** 2026-02-03

**面向对象：** 开发团队、架构师、项目相关人员

**核心议题：** 为什么我们放弃了 MCP 和 Skills，选择了 Postgres \+ Service Class？

## **1\. 我们的现状与挑战 (Context)**

在做出任何架构决策之前，必须诚实地面对我们当前的约束条件。

* **团队规模**：2 人（精英小队，但人力极其有限）。  
* **技术栈**：Node.js (Fastify) \+ PostgreSQL (Prisma) \+ Postgres-Only (pg-boss)。  
* **业务场景**：  
  * **医疗垂直领域**：对数据的准确性、安全性、合规性要求极高（GCP/FDA）。  
  * **高并发写入**：未来 100+ 项目，47 家中心同时录入 REDCap。  
  * **实时响应**：PI 在企业微信提问，期望秒级回复。  
* **核心痛点**：既要应对复杂的业务逻辑（不同项目的入排标准千差万别），又要保证系统的绝对稳定（医疗数据不能错），还要在有限的人力下快速交付。

## **2\. 为什么我们放弃了 "Skills" 和 "MCP Server"？**

这两个概念在 AI Agent 领域非常火，但经过深度评估，对于现阶段的我们来说，它们是\*\*“屠龙之术”\*\*。

### **2.1 放弃 "Skills" (作为独立框架)**

通常所说的 Skills 往往指代复杂的 Agent 编排框架（如 LangChain 中的 Tools/Skills 概念），或者需要专门的解析器来处理的复杂 DSL（领域特定语言）。

* **问题所在**：  
  * **学习成本高**：团队需要学习一套新的框架或语法。  
  * **调试困难**：一旦 Agent 不按套路出牌，很难追踪是 Prompt 写错了，还是框架解析错了。  
  * **过度设计**：对于绝大多数医疗质控逻辑（如 age \> 18），用自然语言让 LLM 去猜，不如直接写代码判断来得准确、高效、省钱。  
* **我们的替代方案**：**Postgres JSON 配置**。  
  * 我们将“技能”降维为**数据**。  
  * hard\_rules：用 JSON Logic 描述死规则，由 CPU 执行，100% 准确。  
  * soft\_instructions：用一段 Prompt 描述软逻辑，由 LLM 执行。  
  * **本质**：我们没有抛弃 Skills 的**理念**（将逻辑配置化），我们抛弃的是 Skills 的**复杂实现**。

### **2.2 放弃 "MCP Server" (Model Context Protocol)**

MCP 是 Anthropic 推出的一种标准协议，用于连接 AI 和数据源。

* **问题所在**：  
  * **架构复杂度爆炸**：引入 MCP 意味着我们需要维护独立的 Server 进程、处理进程间通信 (IPC/RPC)、处理网络延迟和断连。  
  * **运维负担**：对于 2 人团队，多维护一个服务就是多一份心智负担。  
  * **牛刀杀鸡**：我们的 Agent 和 REDCap Adapter 都在同一个 Node.js 进程里，直接调用函数只要几纳秒；如果走 MCP 协议，需要序列化-\>发送-\>接收-\>反序列化，性能损耗巨大且毫无必要。  
* **我们的替代方案**：**Service Class (伪 MCP)**。  
  * 我们在代码层面定义一个统一的 ToolsService 类。  
  * 它向外暴露标准的接口（就像 MCP 一样），但内部直接调用函数。  
  * **本质**：我们保留了 MCP 的**接口思想**（解耦、标准化），抛弃了 MCP 的**通信协议**。

## **3\. 我们的架构：极简主义的工程实践**

我们将这套架构命名为 **"Postgres-Only \+ Service-First \+ SOP State Machine"**。

### **3.1 架构全景图**

graph TD  
    subgraph "核心优势：全在内存里，全在库里"  
        DB\[(Postgres DB)\]  
        NodeJS\[Node.js 后端服务\]  
          
        DB \--\>|1. 加载配置 (Skills)| NodeJS  
          
        subgraph "Node.js 内部逻辑"  
            Engine\[QcEngineService\]  
            Engine \--\>|2. 执行| HardRule\[Engine A (CPU)\]  
            Engine \--\>|3. 思考| LLM\[Engine B (AI)\]  
              
            LLM \--\>|4. 调用| Tools\[ToolsService\]  
            HardRule \--\>|4. 调用| Tools  
              
            Tools \--\>|5. 执行| Adapter\[RedcapAdapter\]  
        end  
          
        Adapter \--\>|6. 请求| External((REDCap))  
    end

### **3.2 核心组件解析**

1. **Skills as Data (数据化技能)**  
   * **实现**：iit\_skills 表中的 JSON 字段。  
   * **优势**：热更新。医生在后台改了配置，下一秒 Agent 就生效，无需重启服务。  
2. **Service as Tool (服务即工具)**  
   * **实现**：ToolsService 类。  
   * **优势**：  
     * **极速**：函数调用，零延迟。  
     * **稳定**：利用 TypeScript 的类型检查，编译期就能发现错误。  
     * **可控**：我们可以轻松地在代码里加入重试、熔断、日志逻辑。  
3. **SOP State Machine (SOP 状态机)**  
   * **实现**：通过 JSON 定义的流程图（Check A \-\> Check B）。  
   * **优势**：**确定性**。医疗流程不能随机应变，必须严格合规。状态机保证了 Agent 永远在轨道上运行。  
4. **Self-Correction Loop (自我修正回路)**  
   * **实现**：在 SoftRuleEngine 中捕获工具调用错误，反馈给 LLM 重试。  
   * **优势**：大大提升了系统的鲁棒性，减少了因为 LLM "手滑" 导致的报错。

## **4\. 为什么这套架构更适合我们？(SWOT 分析)**

| 维度 | Strengths (优势) | Weaknesses (劣势) | Opportunities (机会) | Threats (威胁) |
| :---- | :---- | :---- | :---- | :---- |
| **效率** | 开发极快，复用现有 Node.js 代码。 | 不支持跨语言调用（目前也不需要）。 | 快速迭代，最快速度上线 MVP。 | 随着业务极其复杂，单一 Service 类可能变大。 |
| **稳定性** | 链路极短，没有网络开销，没有新进程。 | 强耦合在 Node.js 生态内。 | 极低的出错率，适合医疗场景。 | 无。 |
| **成本** | **零新增成本**。不费服务器资源，不费 Token (Engine A)。 | 需自行维护 Service 代码。 | 将节省的 Token 成本转化为利润。 | 无。 |
| **扩展性** | 通过 JSON 配置即可支持新项目。 | 无法直接对接外部标准 MCP 工具。 | 形成行业壁垒：我们的 JSON 配置库就是核心资产。 | 如果未来 MCP 成为绝对主流，可能需要一层适配器。 |

## **5\. 写给开发团队的话**

兄弟们，我知道大家对新技术充满了热情，看到 "MCP"、"LangChain" 这样的词汇会觉得很兴奋。但在 IIT Manager 这个项目上，我们要**克制**。

1. **我们要的是“结果”，不是“概念”**。用户不在乎你用的是不是 MCP，他们只在乎\*\*“我问的问题能不能秒回”**，**“我的数据质控准不准”\*\*。  
2. **我们的护城河是“业务逻辑”，不是“胶水代码”**。把精力花在编写更精准的 iit\_skills 配置（JSON Logic \+ Prompt）上，这才是别人抄不走的壁垒。而 MCP 只是连接代码，谁都能写。  
3. **简单就是力量**。2 个人维护一套 Node.js \+ Postgres 系统，我们可以睡个安稳觉。如果引入了复杂的微服务和协议，我们的大部分时间都会花在修修补补上。

**现在的架构，是我们在有限资源下，能做出的最优雅、最务实、最强大的选择。**

让我们基于这套 **V2.2 极简架构**，全速推进 Phase 2 的开发！